mg-integrity-check

name	mg-integrity-check
description	Use before committing significant code changes to verify project integrity. Checks code style, project structure, naming conventions, and change management rules from CONTRIBUTING.md. Trigger phrases include "pre-commit check", "integrity check", "check before commit", "review my changes", "verify changes".

Pre-Commit Integrity Check

Run this checklist against the current staged or changed files before committing. Report each check as PASS, FAIL, or SKIP (not applicable). At the end, summarize all findings.

Step 0: Gather Changed Files

Run git diff --name-only HEAD (unstaged) and git diff --cached --name-only (staged) to get the full list of changed files. Categorize them:

• API files — paths starting with modelguide-api/
• UI files — paths starting with modelguide-ui/
• Docs files — paths starting with docs/
• DB schema files — paths matching modelguide-api/src/db/schema/*.ts
• Migration files — paths matching modelguide-api/drizzle/*.sql
• Connector files — paths matching modelguide-api/src/features/connectors/catalog/*/
• Env files — modelguide-api/src/env.ts
• API route files — paths matching modelguide-api/src/features/*/routes.ts or *.routes.ts
• UI route files — paths matching modelguide-ui/src/routes/**/*.tsx
• Test files — paths matching modelguide-api/tests/** or modelguide-ui/src/**/*.test.*

Check 1: File Naming

For every changed file, verify:

• File name is kebab-case (e.g., agent-form.tsx, auth.routes.ts)
• No PascalCase or camelCase file names (exception: SKILL.md, CLAUDE.md, README.md, CONTRIBUTING.md)
• UI Route files follow TanStack Router convention: name.tsx or name.$param.tsx

Check 2: File Location

For every changed source file, verify it lives in the correct directory:

• API feature code → modelguide-api/src/features/<feature>/
• API shared utilities → modelguide-api/src/lib/
• API DB schema → modelguide-api/src/db/schema/
• UI feature components → modelguide-ui/src/features/<feature>/
• UI shared primitives → modelguide-ui/src/components/ui/
• UI layout components → modelguide-ui/src/components/layout/
• UI routes → modelguide-ui/src/routes/
• UI stores → modelguide-ui/src/stores/
• UI schemas → modelguide-ui/src/schemas/

Flag any source file that lives outside these directories (e.g., code directly in src/ root).

Check 3: Import Aliases

Read changed API files and verify:

• Imports use path aliases: @features/*, @lib/*, @db/*, @/*
• No deep relative imports like ../../lib/ or ../../../db/ (one level ./ within the same feature is fine)

Read changed UI files and verify:

• Imports use ~/ alias (e.g., ~/lib/api, ~/components/ui/button)
• No deep relative imports

Check 4: API Route Conventions

If any new route files are added or modified:

• Routes use @hono/zod-openapi for request/response validation
• Route is registered in modelguide-api/src/app.ts
• Handler has Zod schemas for request params, body, and response

Check 5: UI Patterns

If UI component files are changed:

• Component variants use CVA (cva() from class-variance-authority)
• Data fetching uses TanStack Query (useQuery, useMutation)
• Client state uses Zustand (not React Context for global state)
• Form validation uses Zod schemas

These are guidelines — only flag if a new component introduces a different pattern (e.g., raw fetch() instead of TanStack Query, or inline styles instead of CVA).

Check 6: Database Changes

If any files in modelguide-api/src/db/schema/ are modified:

• Check that a corresponding migration file exists in modelguide-api/drizzle/

• If no new migration is staged, warn: "Schema changed but no migration found. Run bunx drizzle-kit generate --name <descriptive-name>"

• If the change is significant (new table, new pattern, security model change), check for an ADR in docs/decisions/

• Read modelguide-api/drizzle/meta/_journal.json and verify that when timestamps are monotonically increasing. For each entry after the first, confirm its when value is strictly greater than the previous entry's. If any migration has a timestamp less than or equal to the previous entry, FAIL with: "Migration {tag} has out-of-order timestamp (when: {value} ≤ previous: {prevValue}). Re-generate with bunx drizzle-kit generate --name <name> after rebasing."

Check 7: Environment Variables

If modelguide-api/src/env.ts is modified (variables added, renamed, or removed):

• Check that railway/DEPLOY.md is also modified in this changeset
• If not, warn: "Env vars changed but railway/DEPLOY.md not updated (steps 3 and 8 list production vars)"

Check 8: Test Coverage

For new files added in this changeset:

• New API route → should have corresponding test in modelguide-api/tests/unit/ or tests/integration/
• New connector handler → should have test in modelguide-api/tests/unit/connectors/
• New UI feature component → should have test file

Only flag missing tests for new files. Don't flag modifications to existing files that already have tests.

Check 9: Connector Module Integrity

If any connector files are changed (paths matching catalog/*/):

• The connector directory has all 3 files: client.ts, handlers.ts, index.ts
• Handlers use the with{Name}() HOF wrapper (grep for the pattern)
• No raw throw in handler functions (errors should be returned via the wrapper)
• Mutation tools have defaultRequiresConfirmation: true in the manifest
• The connector is imported in modelguide-api/src/features/connectors/catalog/registry.ts

Check 10: Security

Across all changed files:

• No hardcoded secrets, API keys, or credentials (grep for patterns like sk_, mgk_, Bearer , passwords)
• No .env files being committed (should be gitignored)
• Connector config fields storing secrets use type: "secret" in configSchema

Check 11: Package Manager

Verify the correct package manager is used per sub-project:

• modelguide-api/ — uses Bun. If modelguide-api/package-lock.json appears in the changeset, FAIL: "API uses Bun — package-lock.json should not exist. Use bun install (produces bun.lock)."
• modelguide-ui/ — uses npm. package-lock.json is expected. If modelguide-ui/bun.lock appears in the changeset, WARN: "UI uses npm — unexpected bun.lock."
• Root — if a root lockfile is added, it must be bun.lock. If package-lock.json appears at the repo root, FAIL: "Root uses Bun — package-lock.json should not exist at repo root."

Check 12: Commit Message Format

Skip this check if on the default branch.

Get the default branch name and check every commit since diverging:

DEFAULT=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
git log "origin/$DEFAULT..HEAD" --pretty=format:"%h %s"

Each commit subject must match:

<type>(<scope>): <summary>

Field	Valid values
type	feat, fix, chore, refactor, docs, test, perf, ci
scope	agents, connectors, sessions, auth, mcp, ui, db, analytics, secrets, feedback, sops, simulations

Additional rules:

• First line must be ≤ 72 characters
• Summary must be imperative mood, lowercase start

Fail on commits that do not match the format. List each offending commit hash and subject line.

Check 13: Branch Naming

Skip this check if on the default branch.

Current branch must match:

<type>/<short-kebab-description>

Where <type> is one of: feat, fix, chore, refactor, docs, test, perf, ci.

Examples: feat/add-agent-search, fix/session-timeout, chore/update-deps.

Fail if the branch name does not match the pattern.

Check 14: Staging Hygiene

Skip this check if nothing is staged (git diff --cached --name-only is empty).

If files are staged, check for potentially unrelated or dangerous files:

1. Sensitive files — .env, .env.*, credentials.json, *.pem, *.key
2. Scratch / generated — node_modules/, .DS_Store, *.log, *.tmp
3. Large binaries — images, videos, archives (> 500 KB)
4. Cross-concern files — e.g., API schema changes staged alongside a UI-only branch (infer branch intent from branch name and majority of changed files)

Warn on any suspicious staged files. This is advisory — the user may have a good reason.

Report Format

After running all checks, output a summary:

## Integrity Check Results

Files checked: N

| # | Check | Result | Details |
|---|-------|--------|---------|
| 1 | File naming | PASS | |
| 2 | File location | PASS | |
| 3 | Import aliases | FAIL | `modelguide-api/src/features/agents/foo.ts` uses relative import `../../lib/crypto` |
| ... | ... | ... | ... |
| 11 | Package manager | PASS | |
| 12 | Commit message format | PASS | |
| 13 | Branch naming | PASS | |
| 14 | Staging hygiene | PASS | |

### Issues to Fix (N)
- [FAIL] Check 3: ...

### Warnings (N)
- [WARN] Check 6: Schema changed but no migration found

### All Clear
✓ No blocking issues found. Ready to commit.

Report FAIL for violations that should be fixed before committing. Report WARN for advisory items the developer should consider. SKIP checks that don't apply to the current changeset.