scip-query 0.19.5 → 0.19.6

package/skills/_shared/references/detector-precision-and-diffgate.md

@@ -0,0 +1,59 @@
+# Detector precision, diff-gate, and the event ledger
+
+## Weight findings by measured precision, not volume
+
+Detector precision was calibrated against two external production repos on 2026-07-01 (`docs/validation/2026-07-01-external-calibration-*.md`). Use that calibration to decide how much a finding is worth acting on alone versus needing corroboration.
+
+**Strong signal — act on directly:**
+- `complexity-hotspots` (~90% precision)
+- `recent-duplicates` (~75% precision)
+- Graph facts from `refs`, `trace`, `deps`
+- Compiler-verified `cleanup-plan --verify` output
+
+**Good with review — read the cited code before acting:**
+- `duplicate-bodies`, `similar`, `co-change`, `doc-drift`, `twin-drift` (post-retune defaults)
+
+**Exploration only — near-zero precision on codebases with intentional layering or ambient types:**
+- `wrapper-candidates`, `stale-abstractions`, `drift --patterns`
+
+Never file a finding from an exploration-only detector without reading the cited code first. `convergence <s1> <s2>` and `capability-matrix` are deprecated aliases (`similar <s1> <s2> --plan` and `capabilities --matrix` respectively) — prefer the modern form.
+
+## diff-gate
+
+`diff-gate` gates the current diff for architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates, and exits 1 on blocking findings. It recognizes ten checks, any of which can be skipped individually with `--skip <check>`:
+
+| Check | Flags |
+|---|---|
+| `echo` | recent-duplicate-style echoes in the diff |
+| `incomplete-migration` | partially-completed extractions left in the diff |
+| `co-change-partner` | a missing historically-paired file |
+| `twin-partner` | an unedited same-name twin — **advisory**, never blocks |
+| `coverage-contract` | a configured `coverageContracts` enumeration drifted from ground truth (see `scip-setup`) |
+| `architecture` | a declared boundary violation absent from the shared baseline |
+| `doc-reference` | an uncited or stale doc claim |
+| `unused-params` | trailing parameters no body uses |
+| `new-dead` | dead code introduced by this diff |
+| `baseline` | only active with `--baseline`; compares all non-architecture health identities against `.scipquery-baseline.json` — distinct from `health --baseline` |
+
+The `architecture` check runs by default only when enforceable architecture rules and a baseline exist, and it reads that baseline file directly without running the full health suite.
+
+**Reading grouped output:** findings print grouped under a `Root-cause groups (N):` header before the flat list. A root-cause group's remediation usually clears every finding under it. The same remediation may repeat afterward in the flat list below the groups — that repetition is expected, not a separate issue.
+
+**actionTier** on baseline-backed findings tells you how directly to act:
+- `direct` — act on this finding alone.
+- `signal` — corroborating evidence; read before acting.
+- `support` — context only.
+
+Findings marked `(advisory)` never block; treat them as context, not obligations. Fix every finding, or record a specific acceptance reason for each one left unresolved — never report success while a finding is unexplained.
+
+## Event ledger
+
+Every completed diff-gate run — including JSON and hook mode — writes each caught/resolved/suppressed transition to its own committed `.scipquery/events/*.json` file. Independent branches should add independent event files rather than editing a shared log, and commit them with the corresponding change. Legacy `.scipquery/ledger/events.jsonl` records remain readable and migrate automatically on the next gate write.
+
+## Effectiveness
+
+`scip-query effectiveness [--since 30d] [--check <check>] [--json]` reports, per check: findings caught, comparison-verified fixed, suppressed, still open, "moved" (rename noise), legacy/non-comparable "unverified" resolutions, precision (verified-fixed ÷ (verified-fixed + suppressed)), and median days-to-fix.
+
+A pre-commit rerun of diff-gate reuses the same comparison base directly. After HEAD advances, a clean diff-gate run automatically replays the stored comparison commit. A dirty or unavailable replay leaves the effectiveness finding pending instead of manufacturing a fix result. Standalone detector commands (outside diff-gate) are not outcome-tracked in this ledger until they expose complete-scan evidence.
+
+When `diff-gate --hook` reports that a check is rarely acted on in this repo: tune that check's config, suppress the standing findings with reasons, or consciously accept the noise. Do not let unresolved findings accumulate as wallpaper.

package/skills/_shared/references/evidence-and-dead-code.md

@@ -0,0 +1,25 @@
+# Subagent evidence boundary and dead-code resolution status
+
+## Subagent evidence boundary
+
+When a subagent is used to gather scip-query evidence, its prompt must include these rules verbatim:
+- Use scip-query for compiler-resolved identity and completeness claims.
+- Native search/file reads are valid for literal source content and local logic, including an unambiguous helper visible in the same file.
+- Cite the evidence source appropriate to each claim.
+- State explicitly when neither source establishes a claim completely.
+
+The trigger for requiring scip-query evidence is **resolution or completeness, not whether execution crosses a call boundary.** Asserting what `handler(x)` does without resolving what `handler` is constitutes a resolution claim and requires scip-query evidence. Reading a helper defined two lines down in the same file is not a resolution claim and does not require it.
+
+Reject a subagent's finding if it sources a resolution or completeness claim from text search alone. Do not reject a literal-content claim merely for citing a file read as its evidence.
+
+## Dead-code reference-counting status (as of the 2026-07-02 remediation, `docs/plans/2026-07-02-followups.md` items 1-3)
+
+The shared reference-counting layer used by `dead`, `isolated`, `new-dead`, and `stale-abstractions` correctly resolves as consumers:
+- import type-only consumers, including tsconfig paths-aliased specifiers;
+- pnpm/npm/yarn workspace cross-package consumers, including unbuilt `dist/` exports-map consumers.
+
+Vue `<script setup>` composable consumers were already correctly resolved before this remediation — verified live, no code change needed.
+
+**One residual gap remains:** a symbol with an ambiguous leaf name (a same-named definition exists elsewhere in the project) reached only through a re-exporting barrel file in a workspace package can still be misattributed as dead. For that case, `new-dead` labels the finding `unconfirmed (cross-package ambiguous-name resolution gap)` with evidence `heuristic` and lowered confidence, instead of asserting dead — treat it as "verify manually," not fact.
+
+Outside that one residual gap, dead-code findings in this class are normal graph-fact dead claims: confirm with `refs` when in doubt, same as any other finding.

package/skills/scip-audit/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: scip-audit
+description: Use to find and confirm problems WITHOUT editing: is this implementation real (decorative checkers, not-implemented, lying metrics), is a status word derived or merely asserted, are cleanup findings worth acting on, has a same-name twin silently drifted, have the living docs (AGENTS.md, standards, command docs) drifted from the code, and are there hidden policies, scattered concepts, accidental variation or weak boundaries — including React/Vue component and directory-locality pressure. Proactive: needs no reported symptom. Hand confirmed findings to scip-improve. Distinct from `complexity-cleanup` and `principal-maintainability-review`: those reason about a specific symbol's complexity or a reviewer's judgement; this one runs detectors across the repo and ranks confirmed findings by evidence.
+commands:
+  - template: "scip-query health --json"
+    when: "Orient to the repository-wide finding inventory before confirming candidates."
+  - template: "scip-query decorative-checkers --json --full"
+    when: "Audit whether validation-shaped code has a reachable failure exit."
+  - template: "scip-query doc-drift --json --full"
+    when: "Find current-guidance documents whose cited or coupled code moved."
+---
+
+# scip-audit
+
+Read-only evidence audits. Every audit here classifies something —
+real-vs-decorative, derived-vs-asserted, confirmed-vs-noise, drifted-vs-stable
+— and ends in a ranked, evidenced verdict. None of them edit code or docs.
+When a finding needs a fix, hand it to `scip-improve`; do not apply it here.
+
+Load shared mechanics (evidence freshness, lookup, the full command
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | Returns | Coverage | When |
+| --- | --- | --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | health score, findings, priorities, baselines, and coverage notes | `bounded` | Orient to the repository-wide finding inventory before confirming candidates. |
+| `scip-query decorative-checkers --json --full` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | checker identities, call sites, and decorative behavior evidence | `bounded` | Audit whether validation-shaped code has a reachable failure exit. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | document paths, coupled code subjects, and history evidence | `bounded` | Find current-guidance documents whose cited or coupled code moved. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+catalogue) from `../_shared/SKILL.md` — each reference file below carries its
+own shortlist first and only defers to `_shared` when that shortlist runs
+out. Before trusting any graph fact, confirm the index is fresh with
+`scip-query status --capabilities` (reindex if `stale`/`missing`/`unknown`).
+
+## Triage
+
+| Situation | Open | Core commands |
+|---|---|---|
+| A checker/verifier/metric/feature might be decorative, half-built, or a fallback might be masking a dead primary path | [`references/integrity.md`](references/integrity.md) | `decorative-checkers`, `not-implemented`, `twin-ab`, `test-quality`, `refs`, `code`, `call-graph` |
+| A status word ("available", "verified", "safe", "PASS", "complete") needs classifying as derived, hedged, or asserted | [`references/claims.md`](references/claims.md) | `files`, `refs`, `code`, `trace`, `capabilities` |
+| Turning a health report, de-bloat report, AI-residue sweep, or raw detector output into a confirmed cleanup queue | [`references/cleanup.md`](references/cleanup.md) | `health`, `cleanup-plan`, `duplicate-bodies`, `recent-duplicates`, `incomplete-migration`, `doc-drift`, `unused-params`, `passthrough-candidates`, `dead`, `isolated`, `cycles`, `co-change` |
+| Same-name or near-name functions across files whose bodies have silently diverged | [`references/twin-drift.md`](references/twin-drift.md) | `twin-drift`, `duplicate-bodies`, `code`, `refs`, `diff-gate` |
+| Hidden policy, scattered concepts, accidental variation, weak boundaries — general structural/maintainability pressure | [`references/maintainability.md`](references/maintainability.md) | `stats`, `system`, `surface`, `change-surface`, `affected`, `drift`, `health`, `similar*`, `extract-candidates`, `wrapper-candidates`, `stale-abstractions`, `cycles` |
+| React or Vue component/hook/composable duplication, or large-component/view pressure | [`references/frontend.md`](references/frontend.md) | `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`, `augment-vue`, `recent-duplicates`, `similar`, `health` |
+| Folder structure, ownership boundaries, locality config, a messy or AI-generated layout, safe move slices | [`references/directory.md`](references/directory.md) | `system`, `locality-candidates`, `similar-files`, `cycles`, `architecture`, `drift`, `co-change`, `config-validate`, `diff-gate`, `health` |
+
+Rows are not exclusive. A "does this actually work" investigation that turns
+up structural mess routes that mess to `references/maintainability.md`
+instead of forcing it into the integrity verdict — real-but-messy is a
+different failure mode than fake-but-green. A twin-drift finding that
+surfaces on your own diff (via `diff-gate`) is a live instance of that defect
+class, not just a gate finding — open `references/twin-drift.md`.
+
+## Cross-cutting rules
+
+- **Classify, don't just list.** Every audit in this skill assigns each item
+  in scope to exactly one label from its taxonomy (real/decorative,
+  derived/hedged/asserted, confirmed/intentional/false-positive/blocked,
+  intentional-variation/drifted-policy/one-sided-fix, mature/emerging/
+  accidental). A count that doesn't sum to the scope size is an unfinished
+  audit.
+- **Ground every claim in evidence**, not opinion or a variable's name — a
+  variable called `verified` that nothing ever checked is still asserted.
+  Name concrete files/symbols before naming a smell.
+- **Preserve essential variation.** Difference that reflects real behavior,
+  domain facts, runtime constraints, or external contracts is not a defect;
+  consolidating it away is a false abstraction. Any merge/consolidate
+  recommendation must carry the single trait that makes the cited sites one
+  concept — if that trait can't be stated, they aren't one concept.
+- **A clean run is itself a claim.** A suspect scope that produces zero
+  findings needs a stated reason the suspicion was wrong, not silence.
+- **This skill never edits.** Findings, evidence, and a fix direction are the
+  deliverable; route action to `scip-improve`.

package/skills/scip-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Audit"
+  short_description: "Find and confirm real problems without editing"
+  default_prompt: "Use $scip-audit to proactively find and confirm real problems in this codebase without changing any code."

package/skills/scip-audit/references/claims.md

@@ -0,0 +1,98 @@
+# Claims: derived, hedged, or asserted?
+
+Classify whether an "available", "verified", "safe", "PASS", or "complete"
+status word is derived from a real check, hedged as a candidate, or merely
+asserted without being probed.
+
+Command shortlist: `files <pattern>` (inventory), `refs <symbol>` /
+`code <symbol>` / `trace <symbol>` (classify), `capabilities --matrix --json`
+(spot-check against a known-good derived surface).
+
+## Taxonomy
+
+- **Derived** — the producer computes the value from a real probe, scan, or
+  computation (a compiler run, a runtime capability probe, a graph
+  traversal).
+- **Hedged** — the code or its label already says it is a candidate,
+  heuristic, or unverified. Hedged is not a finding — the label already
+  discloses the uncertainty.
+- **Asserted** — the value is a constant, a hardcoded table entry, or a
+  string literal presented with the same confidence as a derived value but
+  backed by nothing the code actually checked at that call site.
+
+Asserted status words that are agent-facing and trust-bearing — an agent
+would route a decision ("use this evidence", "skip this check", "delete
+this") based on the word — are the highest-severity class this audit exists
+to find.
+
+Ground every claim in the producing function's source, not its label or
+variable name alone: a variable named `verified` that is never checked
+against a real result is still asserted. Every status word in scope gets
+exactly one of the three labels.
+
+## Severity rubric
+
+Asserted + agent-facing + trust-bearing = high. Asserted + internal-only or
+low-consequence = low. Hedged is not a finding.
+
+A status that used to be asserted and now calls a real probe is fixed — say
+so and move on, do not re-report it.
+
+## Step 1 — Inventory
+
+Grep the target scope (a file, module, or command family) for user-visible
+or JSON-facing status words (`available`, `unavailable`, `partial`,
+`verified`, `safe`, `PASS`, `FAIL`, `complete`, `derived`, `asserted`),
+noting the file:line and the renderer or JSON field surfacing each hit. Use
+`scip-query files <target-file-or-pattern>` to locate the renderer or
+status-producing module for a claim.
+
+**Complete when:** every status-bearing string or field in scope is listed
+with its surface (human output, `--json` field, or both).
+
+## Step 2 — Classify
+
+For each status word's producing function, run `refs`, `code`, and `trace`,
+read the function body, and classify it as derived (computed from a probe,
+scan, spawn result, file check, or graph query performed at or near that
+call site), hedged, or asserted.
+
+**Complete when:** every producer has one of the three labels with the one
+line of source evidence that justifies it.
+
+Use `scip-query capabilities --matrix --json` as a spot-check: an
+already-known example of a fixed derived-status surface, useful for
+calibrating what "derived" looks like in this codebase before judging
+ambiguous cases.
+
+## Step 3 — File and fix
+
+File findings as a table, not prose. Finding format:
+
+- **Claim** — the status word and where it appears.
+- **Producer** — file:line, function name.
+- **Classification** — asserted.
+- **Severity** — high or low (per the rubric above).
+- **Fix** — probe it (name the real check to add), generate it (derive from
+  a registry/config that is itself kept honest), or soften the language
+  (hedge the label to match what is actually known).
+
+**Complete when:** every asserted status in scope has a filed finding with a
+fix direction, and every derived/hedged status is confirmed correct (not
+silently asserted behind a computed-looking name).
+
+## Report
+
+Write the audit report under `docs/scip-query/` unless the user asked only
+for a conversational answer. Template:
+
+- Scope
+- Status words inventoried: N
+- Classified: `<d>` derived / `<h>` hedged / `<a>` asserted — must sum to N;
+  a gap is an unfinished audit
+- Claim table: Claim, Producer, Classification, Fix
+- "Fixed since last audit" — claims now derived that were previously
+  reported asserted
+
+The audit is complete only when every status word in scope is classified and
+every asserted, trust-bearing claim has a filed finding.

package/skills/scip-audit/references/cleanup.md

@@ -0,0 +1,101 @@
+# Cleanup: raw signal to confirmed queue
+
+Turn raw scip-query cleanup signals into a confirmed cleanup queue. Use for
+health reports, de-bloat reports, recent AI-residue audits, score-framed
+cleanup queues, confirming raw findings, or preparing a cleanup plan.
+
+This audit never edits application code — it only audits and classifies
+signals; applying fixes is `scip-improve`'s job.
+
+Three common modes, same underlying workflow:
+
+- **Whole-repo audit** — rank all cleanup signals across the codebase.
+- **Recent-AI-residue** — focus specifically on echoes, twins, incomplete
+  migrations, speculative params, stale agent-facing docs, and hidden
+  couplings.
+- **Score-framed** — explain the health score's deductions and identify the
+  safest first cleanup batch.
+
+## Step 1 — Establish evidence
+
+Before any sweeping begins, run `scip-query doctor`, `scip-query status
+--capabilities`, `scip-query health --json`, `scip-query capabilities
+--json`, and `scip-query config-validate --json`.
+
+**Complete when:** unavailable capabilities are explicitly recorded as
+unavailable, not silently skipped.
+
+## Step 2 — Sweep signals
+
+Run every relevant detector class or explicitly record why it is
+unavailable — never silently omit a class.
+
+Core sweep set:
+
+```
+scip-query cleanup-plan --verify --json          # compiler-verified batched deletion plan
+scip-query duplicate-bodies --json --full        # exact duplicate small-body candidates
+scip-query recent-duplicates --json --full       # recent code re-implementing established code
+scip-query incomplete-migration --json --full    # partially-completed extractions
+scip-query unused-params --json --full
+scip-query passthrough-candidates --json --full
+scip-query dead --json --full
+scip-query isolated --json --full
+scip-query cycles
+scip-query co-change --json --full               # hidden file-level coupling from git history
+scip-query doc-drift --json --full                # docs whose referenced/co-changed code kept moving
+```
+
+`scip-query health --json` establishes the composite score and prioritized
+action list; `scip-query cleanup-plan --verify --json` combines graph-fact
+dead code with the cascade candidates it unlocks. `scip-query doc-drift
+--json --full` finds stale-doc candidates: code a doc references, or
+co-changed with, that kept changing after the doc stopped — run it whenever
+the audit is about living-doc drift, not just code cleanup.
+
+For frontend repos, add the React/Vue duplicate, hook/composable, and
+large-component/view detector commands (see `references/frontend.md`) to the
+sweep.
+
+**Optional deep dives**, run only after the main sweep is exhausted:
+`scip-query stale-abstractions --json --full` and `scip-query
+wrapper-candidates --json --full` have near-zero precision on codebases with
+intentional layering or ambient types — treat every hit as a lead to
+confirm, never a finding on its own.
+
+## Step 3 — Confirm each candidate
+
+Classify every cleanup candidate as exactly one of: **confirmed fix
+target**, **intentional design**, **false positive**, or **blocked**.
+
+To confirm a high-priority candidate, inspect source and graph evidence with
+`scip-query code`, `scip-query refs`, `scip-query fan-in`, `scip-query
+fan-out`, `scip-query affected --json`, `scip-query change-surface --json
+--full`, `scip-query similar --plan`, and `scip-query co-change --json
+--full`.
+
+Because a deletion is this audit's scrutiny-ending verdict, a candidate
+classified "confirmed fix target" that deletes code must survive refutation
+checks before being finalized:
+
+1. Run `rg` for the symbol name as a plain string to catch dynamic dispatch,
+   config keys, serialized references, and CLI/doc text that graph-based
+   detectors cannot see.
+2. Check for the cross-package barrel re-export gap — the one blind spot
+   `dead` self-labels as "unconfirmed."
+
+Record `refutation: survived — <checks run>` on a confirmed-deletion entry
+once the blind-spot checks pass, or reclassify the entry if they don't;
+either way the note must be recorded.
+
+## Report
+
+Final report must include: health score, classification counts
+(confirmed/intentional/false positive/blocked — must cover every collected
+signal, none left uncounted), confirmed items with evidence and first safe
+action, unconfirmed signals with evidence still needed, unavailable/blocked
+checks with reasons, and a recommended first cleanup batch with why it's
+safe now.
+
+A run is complete only when each collected signal is classified and the
+next action is visible.

package/skills/scip-audit/references/directory.md

@@ -0,0 +1,222 @@
+# Directory architecture: boundaries, locality, and safe moves
+
+Evaluate, design, reorganize, or migrate folder structure, ownership
+boundaries, locality config, messy repos, AI-generated layout, or safe
+file-move slices.
+
+Command shortlist: `system <scope>`, `locality-candidates --json --full`,
+`similar-files --full --json`, `cycles`, `architecture --json`, `drift
+--architecture`, `co-change --json --full`, `health --write-baseline`,
+`diff-gate`, `config-validate --json`.
+
+## Definitions
+
+- **Ownership boundary** — a folder, package, module, or convention that
+  groups code around one stable responsibility.
+- **Dependency edge** — points from code that relies on something to the
+  code it relies on; for imports, A → B means A imports B.
+- **Forbidden edge** — an actual cross-boundary dependency rejected by an
+  explicit project rule. Directory distance or an unusual import alone does
+  not make an edge forbidden.
+- **Layer** — a responsibility ordered by dependency direction, such as
+  presentation depending on application.
+- **Subsystem** — a responsibility that owns an end-to-end capability, such
+  as authentication or rendering.
+- **Package** — a publication or build unit. **Service** — an independently
+  running unit. Do not force the layer, subsystem, package, and service
+  concepts all into one single layer hierarchy.
+- **Reciprocal dependency** — dependency traffic in both directions between
+  two boundaries; it is a review signal because the boundaries exert mutual
+  change pressure, not proof that either import is wrong.
+- **Architecture ratchet** — an enforcement rule that records existing
+  violations while preventing new ones, allowing a large codebase to improve
+  without a speculative rewrite.
+- **Target structure** — a proposed future layout that expresses an
+  ownership model, not merely a prettier tree.
+- **Migration slice** — the smallest set of file moves and import updates
+  that can be verified independently.
+- **Slop codebase** — one whose files are arranged by accident, convenience,
+  or recent edits rather than stable ownership rules.
+
+## Operating principles
+
+Start with evidence, not taste. Separate review from migration — do not move
+files unless asked. Preserve broad boundaries when evidence shows they are
+intentional; do not reward a generic "shared" boundary/directory unless the
+shared concept has a name, owner, and cross-boundary consumers. For messy
+repos, produce a discovery map and decisions instead of pretending the
+target structure is obvious. Prefer small verified moves over large
+speculative reorganizations. Configure descriptive boundaries before closing
+(declaring) dependency rules. Treat graph shape (dependency structure) as
+evidence about responsibilities, never as a substitute for identifying them.
+
+## Step 1 — Bound the question
+
+Classify the request as review, target structure, locality config,
+migration plan, or implementation.
+
+**Complete when:** scope and deliverable are explicit.
+
+## Step 2 — Inventory evidence
+
+Run `stats`, `system <scope>`, `files <pattern>`, `surface <scope>`, `deps
+<file>`, `rdeps <file>`, `change-surface <file>`, `plan-context
+<file-or-symbol>`, `locality-candidates --json --full`, `cycles`,
+`architecture --json`, `drift --architecture`, `co-change`, `similar-files
+--min-similarity 0.6 --min-deps 3`, `similar-chains --min-similarity 0.5`,
+`recent-duplicates`, and `drift`.
+
+- `system <scope>` returns module file paths, exported symbols with line
+  ranges, internal dependencies, and reverse dependencies.
+- `locality-candidates --json --full` returns directory-locality and
+  ancestry candidates from consumer ownership — symbols, current homes,
+  consumer locality, and suggested homes.
+- `similar-files --full --json` returns file pairs with similarity scores
+  and shared symbols (overlapping dependency profiles).
+- `cycles` detects circular dependency chains between files.
+- `architecture --json` measures configured boundaries, actual dependency
+  traffic, forbidden edges, reciprocal pairs, and boundary cycles.
+- `drift --architecture` reviews direct drift findings together with
+  boundary coverage and architecture signals.
+- `co-change --json --full` inventories hidden file-level coupling from git
+  history — files that change together without a dependency edge.
+
+Also read durable project guidance that names architecture, modules,
+ownership, routes, workflows, contracts, or domains.
+
+**Complete when:** each folder under review has evidence for exports, entry
+points, consumers, tests, co-change partners, and claimed ownership rules.
+
+## Step 3 — Classify boundary maturity
+
+Classify each boundary candidate as:
+
+- **Mature** — repeated, documented, and enforced by imports, tests,
+  routes, packages, standards, or review history.
+- **Emerging** — meaningful and partly repeated but not consistent enough
+  to configure.
+- **Accidental** — a convenience bucket, legacy pile, generated artifact,
+  recent edit cluster, or mixed reasons to change.
+
+**Complete when:** mature, emerging, and accidental boundaries are
+separated.
+
+## Step 4 — Build a descriptive architecture model
+
+For a large existing codebase, before calling anything a "layer," inventory:
+workspace packages/public exports; applications/services/deployable entry
+points; domain capabilities/end-to-end subsystems;
+persistence/network/rendering/compiler/other technical responsibilities;
+tests/routes/contracts/ownership or architecture documentation; and
+dependency/co-change evidence showing which files already move as a unit.
+
+Add mature boundary path patterns to `.scipquery.json` under
+`architecture.boundaries` WITHOUT `allowedDependencies` rows first:
+
+```json
+{
+  "architecture": {
+    "boundaries": [
+      { "name": "domain", "paths": ["src/domain/**"] },
+      { "name": "runtime", "paths": ["src/runtime/**"] }
+    ]
+  }
+}
+```
+
+After adding boundaries, run `scip-query config-validate --json` then
+`scip-query architecture --json` to check the new boundary configuration.
+Use unmapped and ambiguous files to repair boundary membership, and use
+actual boundary edges, reciprocal pairs, and strongly connected groups to
+test whether boundary names describe real separation.
+
+**Complete when:** every configured boundary has a stated responsibility and
+the mapping gaps are understood.
+
+## Step 5 — Declare only supported dependency rules
+
+An `allowedDependencies` row is closed: an outgoing target omitted from a
+present row is forbidden, but a missing row makes no dependency claim at
+all. Example closed config:
+
+```json
+{
+  "architecture": {
+    "boundaries": [ ... ],
+    "allowedDependencies": {
+      "domain": [],
+      "runtime": ["domain"]
+    },
+    "requireAcyclic": true
+  }
+}
+```
+
+For each closed `allowedDependencies` row, record the evidence for its
+intended direction. Do not copy the current dependency graph into the
+allow-list merely to obtain zero findings. Leave emerging or disputed
+dependency rules undeclared rather than closing the row prematurely.
+
+**Complete when:** every forbidden edge is understood as either
+implementation debt, a false boundary, or a policy mistake.
+
+## Step 6 — Propose structure or decisions
+
+Structure a directory architecture review/proposal using this exact section
+order:
+
+1. Scope
+2. Current Structure Map
+3. Boundary Maturity
+4. Descriptive Architecture Model
+5. Dependency Rules
+6. Forbidden-Edge Ledger
+7. Reciprocal and Cycle Review
+8. Target Structure
+9. Move Ledger
+10. Locality Config
+11. No-Move Decisions
+12. Deferred Decisions
+13. Migration Order
+
+List a decision as No-Move when broad consumers, route/package/contract
+surfaces, infrastructure roles, generic shared risk, or weak evidence make a
+move harmful.
+
+**Complete when:** every proposed move has a reason and a verification path.
+
+## Step 7 — Ratchet, then implement one slice (when asked)
+
+For a large repository with existing violations, review the direct findings
+with `scip-query drift --architecture` and write the shared health baseline
+with `scip-query health --write-baseline`. The baseline records stable
+architecture identities by boundary pair, not by whichever example file
+happens to sort first.
+
+The default `scip-query diff-gate` architecture check compares only
+architecture identities and does not run every health detector; `diff-gate
+--baseline` is the opt-in full health ratchet and does not duplicate
+architecture findings. Commit `.scipquery-baseline.json` together with
+`.scipquery.json`. A missing baseline causes the architecture gate to report
+that enforcement is not enabled — it does NOT silently treat the current
+dependency graph as accepted.
+
+Prefer inspecting the least-broad edge inside a boundary cycle first, then
+determine whether the repair is a move, dependency inversion, named shared
+contract, boundary merge, or policy correction.
+
+Before editing to implement a migration slice, state the files to move, the
+imports/exports/tests/docs to update, the expected verification, and the
+rollback risk.
+
+After moving the smallest high-confidence slice, run `scip-query
+incomplete-migration`, `scip-query recent-duplicates`, and `scip-query
+co-change <moved-file-or-config>`. Also run the project's tests or typecheck
+for the affected workspace.
+
+If `.scipquery.json` locality changed, run `scip-query config-validate`,
+`scip-query locality-candidates --json --full`, `scip-query architecture
+--json`, `scip-query drift --architecture`, and `scip-query diff-gate`.
+
+Then invoke `scip-verify`; the implementation is complete only when imports,
+tests, locality signals, and verification are checked.