Reorganize hooks, guards, and tests into single-concern domain modules

Decompose multi-concern megafiles into single-concern modules:
- scripts/agent-hooks/detectors.mjs -> command-evidence.mjs, evidence-gate.mjs, response-shape.mjs
- scripts/guards/check-canonical-surfaces.mjs -> code-shape/ aggregator + check-change-discipline, check-pattern-engine, check-package-scripts, ast-scan
- scripts/agent-hooks/skills.mjs -> skill-frontmatter.mjs, skill-paths.mjs, skills.mjs
- extract code-shape/check-child-process-shell (shell:true), ci-release/ci-yaml-primitives, agent-surface/hook-topology

Relocate guards into domain folders (code-shape, toolchain, ci-release,
agent-surface, repo-surface, docs-config, fastmcp, code-atlas, deps);
mirror guard/hook tests under tests/guards/<domain>/ and tests/agent-hooks/;
repoint check-all.mjs manifest, npm guard:* scripts, sync-llm,
check-agent-hooks, check-ci-governance, rules, and AGENTS.md.

Every guard/hook source file is now under Rule 16's 500-line budget, each
enforcing one concern, organized by domain, flowing through the single
check-all.mjs guard source and the single runner.mjs hook source per
execution-source domain.

Verified: npm run guard (ALL_GUARDS_OK), lint, typecheck, sync:llm:check,
664 tests. Also carries the in-flight codex/sync-lanes-0.3.4 branch work
(src/ modules, changeset, rule/script updates) present in the worktree.

Author: jmclaughlin724

.changeset/narrow-public-api.md

@@ -0,0 +1,5 @@
+---
+"supaschema": minor
+---
+
+Narrow the public library API. Internal-grade helpers that were never part of the documented public API are no longer re-exported from `supaschema` and have no published entry point: from `src/db-admin.ts` (disposable-database lifecycle, raw apply, catalog fingerprinting), `src/contract-registry.ts` (`toContract`, `contractDrift`), `src/migration-runners.ts` (`buildSupabaseCliCommand`, `groupMigrationUnits`), `src/migrations-status.ts` (`migrationFileVersion`), and `src/pipeline-services.ts` (`applyDeploySafetyPolicy`, `buildSchemaDiffPlan`, `deployBlockingRlsDiagnosticCodes`, `evaluateTypeContract`, `refreshGeneratedOutputs`, `scanSchemaSafety`). They are compiled into the package for internal CLI use but may change or be removed in any release. Use the documented pipeline exports (`verifyMigration`, `syncMigrations`, `migrationsStatus`) instead.

.claude/rules/01-operating-rules.md

@@ -15,9 +15,9 @@ The non-negotiable working agreement for any agent or contributor in this repo.
 - **Follow the gates; do not skip a STOP condition.** Every concern has a STOP gate with an executable enforcement path. A red gate is a real failure — fix the cause, never weaken, disable, skip, or comment out a guard, test, hook, or assertion to make it pass. The umbrella gate is `npm run guard` (`scripts/guards/check-all.mjs`), which must print `ALL_GUARDS_OK`.
 - **No standard without enforcement.** A rule, contract, or STOP gate that no guard or test reaches is incomplete — wire it into `npm run guard` or a test, do not leave it as prose. A docs-only or skill-only change cannot close hook, context, rule, sync, generated-surface, package-template, or runtime behavior unless the enforcement closure ledger in `AGENTS.md` records the runtime/hook path, guard, focused test, validation script, generated mirrors, consumer/package disposition, and explicit Claude/Codex disposition. STOP IF any ledger row is missing a verified update, already-covered finding, or owner-scoped not-applicable reason.
 - **Anti-patterns stay indexed.** Rule 20 is the single repo-wide anti-pattern inventory. When a rule, hook, guard, skill, or CI lane adds a prohibited pattern, update Rule 20 in the same change and keep the domain rule focused on the positive workflow and recovery path.
-- **Use `$elegant` only.** DEFAULT TO `$elegant` for every task and action. MUST NOT create or keep backwards compatibility behavior or paths, export-only compatibility files, shims, aliases, wrappers, DTOs, facades, copied enum tuples, casts that patch missing contracts, local view-models, local compatibility layers, broader helper surfaces, allowlist exceptions, transitional branches, comments in code or scripts, redundant or convenience entry points, placeholders, TODOs, regex, or duplicate owners. Typed UI prop containers are allowed only when DB-backed payloads use direct generated contracts without renaming, projection, mirroring, or local ownership. Use AST only for structural analysis. Treat external-contract conflicts as STOP conditions; solve them in the canonical owner. STOP IF the approach preserves an old path or patches around a missing contract instead of rewriting or deleting its consumers in the same change. VERIFY with Code Atlas impact/consumer queries plus AST/LSP import-export-symbol inspection before deleting or privatizing a public surface, and with `scripts/guards/check-canonical-surfaces.mjs` for code-surface shape. FIX BY moving behavior into the canonical owner, updating consumers, and deleting the legacy surface.
+- **Use `$elegant` only.** DEFAULT TO `$elegant` for every task and action. MUST NOT create or keep backwards compatibility behavior or paths, export-only compatibility files, shims, aliases, wrappers, DTOs, facades, copied enum tuples, casts that patch missing contracts, local view-models, local compatibility layers, broader helper surfaces, allowlist exceptions, transitional branches, comments in code or scripts, redundant or convenience entry points, placeholders, TODOs, regex, or duplicate owners. Typed UI prop containers are allowed only when DB-backed payloads use direct generated contracts without renaming, projection, mirroring, or local ownership. Use AST only for structural analysis. Treat external-contract conflicts as STOP conditions; solve them in the canonical owner. STOP IF the approach preserves an old path or patches around a missing contract instead of rewriting or deleting its consumers in the same change. VERIFY with Code Atlas impact/consumer queries plus AST/LSP import-export-symbol inspection before deleting or privatizing a public surface, and with `scripts/guards/code-shape/check-canonical-surfaces.mjs` for code-surface shape. FIX BY moving behavior into the canonical owner, updating consumers, and deleting the legacy surface.
 - **Enforce the AGENTS-owned change discipline.** MUST follow the `AGENTS.md` Repo-Wide Change Discipline before adding or preserving any surface. `AGENTS.md` owns the sequence; this rule owns the STOP gate and guard wiring. STOP IF the accepted scope keeps backwards compatibility behavior or paths, backwards-compatibility shims, export-only compatibility files, avoidable duplicate owners, wrappers, aliases, DTOs, facades, copied enum tuples, cast-based contract patches, local view-models, local compatibility layers, broader helper surfaces, allowlist exceptions, redundant docs, placeholders, TODOs, or multiple entry points without a named distinct runtime, storage, compliance, lifecycle, or external-contract boundary. VERIFY by naming the canonical owner, the single entry point, and the direct source or Code Atlas evidence. FIX BY merging, moving, deleting, or documenting the distinct boundary that justifies a separate surface.
-- **Separate mechanism, end state, and verification for correctness work.** Diagnostic, review, verification, source, why, correctness, best-practice, redundancy, and architecture-shaped tasks MUST name the runtime mechanism, the `$elegant` architecture/end-state disposition, and the verification disposition before claiming correctness. STOP IF the answer treats upstream-valid runtime behavior as proof of local correctness, omits the canonical owner or end-state disposition, or omits commands, sources, failures, skipped checks, or blockers. VERIFY with Rule 12 response-shape enforcement, `scripts/agent-hooks/detectors.mjs`, `tests/agent-hook-core.test.ts`, and `npm run guard:agent`. FIX BY revising the answer or running the missing verification before making the correctness claim.
+- **Separate mechanism, end state, and verification for correctness work.** Diagnostic, review, verification, source, why, correctness, best-practice, redundancy, and architecture-shaped tasks MUST name the runtime mechanism, the `$elegant` architecture/end-state disposition, and the verification disposition before claiming correctness. STOP IF the answer treats upstream-valid runtime behavior as proof of local correctness, omits the canonical owner or end-state disposition, or omits commands, sources, failures, skipped checks, or blockers. VERIFY with Rule 12 response-shape enforcement, `scripts/agent-hooks/response-shape.mjs`, `tests/agent-hook-core.test.ts`, and `npm run guard:agent`. FIX BY revising the answer or running the missing verification before making the correctness claim.
 - **Reason from source, not pattern.** Derive changes from the requested end state and protected invariant; treat existing patterns as evidence, not authority. When mechanisms overlap, verify the canonical upstream source before keeping, consolidating, or replacing enforcement. Add only surfaces that directly protect the verified invariant. VERIFY by naming the source and invariant before editing; guards must check behavior, not incidental shape.
 - **Resolve technical choices by research, not by polling the user** (Rule 05): default to the upstream-canonical pattern and cite the source. Escalate only product scope, irreversible/outward-facing actions, secrets/spend, or a genuine conflict between the user's own prior instructions.
 - **Generated types come from the declarative tree, never hand-rolled.** supaschema generates `database.types.ts` and `database.zod.ts` from the declarative SQL tree and source model (`supaschema types`), not from live database introspection (`.claude/rules/supaschema.md`).
@@ -30,7 +30,7 @@ The non-negotiable working agreement for any agent or contributor in this repo.
 
 ## Enforced by
 
-- `npm run guard` (`scripts/guards/check-all.mjs`) is the umbrella gate — tooling stack, canonical surface shape (`scripts/guards/check-canonical-surfaces.mjs`), agent hooks, agent-surface parity, policy standardization (`scripts/guards/check-agent-policy-standardization.mjs`), rule-citation integrity, dependency catalog, Code Atlas, LSP coverage, and FastMCP surface. lefthook (`pre-commit` runs Biome on staged files; `pre-push` runs `npm run typecheck` + `npm run guard`) and the PreToolUse/PostToolUse hooks enforce in-loop.
+- `npm run guard` (`scripts/guards/check-all.mjs`) is the umbrella gate — tooling stack, canonical surface shape (`scripts/guards/code-shape/check-canonical-surfaces.mjs`), agent hooks, agent-surface parity, policy standardization (`scripts/guards/check-agent-policy-standardization.mjs`), rule-citation integrity, dependency catalog, Code Atlas, LSP coverage, and FastMCP surface. lefthook (`pre-commit` formats staged files across every language owner — Biome, Prettier, taplo, sh-syntax, with fixes re-staged; `pre-push` runs `npm run typecheck` + `npm run guard`) and the PreToolUse/PostToolUse hooks enforce in-loop.
 
 STOP if any STOP condition in `.claude/rules/*` is skipped, a guard or test is weakened instead of its cause being fixed, a standard ships without an executable enforcement path, hook/context/rule/sync/package-template behavior changes without the `AGENTS.md` enforcement closure ledger, the package manager is switched away from npm, a technical decision ships on a guess when an authoritative upstream source was available, an approach preserves avoidable duplication because removing it would be a larger patch, a backwards compatibility path, export-only compatibility file, shim, placeholder, or TODO remains in the accepted scope, or avoidable duplicate or redundant surfaces or multiple entry points remain in the accepted scope.
 

.claude/rules/04-python-toolchain.md

@@ -53,8 +53,8 @@ Apply Python fixes locally with `npm run py:fix` (`ruff check --fix` for lint +
 ## Gates
 
 - `.github/workflows/python.yml`, when present locally, is private with `services/agent-mcp` and must stay untracked. Public CI must not require private FastMCP files that are absent from a clean checkout. The focused local lane remains the `py:*` command set above. The `--package supaschema-agent-mcp` selector is mandatory: the workspace root has no runtime deps (`dependencies = []`, `package = false`) and does not depend on the member, so a bare `uv run mypy`/`pytest` resolves in the root env that lacks `fastmcp`/`mcp`/`pydantic` and fails with `import-not-found`.
-- `npm run guard:lsp-coverage` (`scripts/guards/check-lsp-coverage.mjs`, part of `npm run guard`) hard-blocks if any tracked code extension — including `.py`/`.pyi` — is not mapped in `.claude/cclsp.json` when that local map exists. In a clean public checkout where `.claude/cclsp.json` is absent by design, Rule 06 requires the explicit `LSP_COVERAGE_SKIPPED_LOCAL_ONLY` pass. The cclsp map itself is governed by **Rule 06**.
-- `npm run guard:fastmcp` (`scripts/guards/check-fastmcp-agent.mjs`) keeps the FastMCP server surface aligned (owned by **Rule 11**), not the Python toolchain.
+- `npm run guard:lsp-coverage` (`scripts/guards/toolchain/check-lsp-coverage.mjs`, part of `npm run guard`) hard-blocks if any tracked code extension — including `.py`/`.pyi` — is not mapped in `.claude/cclsp.json` when that local map exists. In a clean public checkout where `.claude/cclsp.json` is absent by design, Rule 06 requires the explicit `LSP_COVERAGE_SKIPPED_LOCAL_ONLY` pass. The cclsp map itself is governed by **Rule 06**.
+- `npm run guard:fastmcp` (`scripts/guards/fastmcp/check-fastmcp-agent.mjs`) keeps the FastMCP server surface aligned (owned by **Rule 11**), not the Python toolchain.
 - After changing any dev tool or runtime dependency, run `uv lock` and commit `uv.lock`; the `uv sync --locked` step fails the PR on drift.
 
 STOP if a Python file ships unformatted (`ruff format --check` fails) or with ruff lint errors; if it fails `mypy` strict; if `uv.lock` drifts from `pyproject.toml` (`uv sync --locked` would fail); if the ruff/black/isort line lengths diverge from `100`; if the `.py`/`.pyi` cclsp mapping or a pylsp plugin is removed; if a `python.yml` step or any script runs a bare `uv run <tool>` that needs the member environment (`mypy`/`pytest`) without `--package supaschema-agent-mcp`, diverging from the canonical `py:*` invocations; if `python.yml` becomes tracked while `services/agent-mcp` is private; if a competing Python formatter, linter, or type checker is added to the CLI/CI gate; or if FastAPI, `services/api`, pnpm, or any HTTP-API-only construct is reintroduced into this FastMCP-only Python surface.