scip-query 0.19.4 → 0.19.6

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.

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

@@ -0,0 +1,130 @@
+# React and Vue maintainability
+
+Reviews React and Vue frontends as maintainable systems: React as
+components, hooks, JSX structure, and behavior lifecycles; Vue as single-file
+components, templates, scripts, styles, external scripts, components, and
+composables. Both follow the same four-step workflow below; framework-
+specific commands and definitions are called out per step.
+
+## Definitions
+
+- **Component duplicate candidate** (React or Vue) — a pair or group of
+  rendered structures that repeat the same user-facing arrangement,
+  controls, states, props, or data-presentation shape enough that a shared
+  component may reduce drift.
+- **React hook candidate** — a pair or group of component behaviors that
+  repeat the same state lifecycle, effects, requests, validation,
+  persistence, callback policy, or derived-data rule enough that a shared
+  hook may preserve behavior better.
+- **Vue composable candidate** — a pair or group of script behaviors that
+  repeat the same state lifecycle, effects, requests, validation,
+  persistence, or derived-data policy enough that a shared composable may
+  preserve behavior better.
+- **Large component/view pressure** — one component, SFC, or linked view
+  file contains several kinds of knowledge that change for different
+  reasons. A large file is review pressure, not proof of duplication, by
+  itself.
+
+## Step 1 — Bound and scan
+
+Pick the narrowest source root, feature area, or changed-file scope that
+still includes likely reuse partners.
+
+**Vue only:** if component references, imported composables, script blocks,
+or linked external scripts matter, run `scip-query augment-vue --project
+<path-to-tsconfig>` first — it adds compiler-resolved Vue SFC references to
+the SQLite index using Volar (complete coverage) and must run before
+scanning.
+
+Then run, all uncapped with `--full --json`:
+
+**React:**
+```
+scip-query react-component-duplicates --scope <scope> --full --json
+scip-query react-hook-candidates --scope <scope> --full --json
+scip-query react-large-component-pressure --scope <scope> --full --json
+scip-query recent-duplicates --scope <scope> --full --json
+scip-query health --scope <scope> --json
+```
+
+**Vue:**
+```
+scip-query vue-component-duplicates --scope <scope> --full --json
+scip-query vue-composable-candidates --scope <scope> --full --json
+scip-query vue-large-view-pressure --scope <scope> --full --json
+scip-query recent-duplicates --scope <scope> --full --json
+scip-query health --json
+```
+
+Every `*-duplicates`/`*-candidates`/`*-pressure` command has bounded
+coverage — `--full` is required for the uncapped scan.
+`react-component-duplicates`/`vue-component-duplicates` derive structural
+similarity from tags, props, events, and bindings (React) or tags, bindings,
+slots, and directives (Vue). `recent-duplicates` finds directional pairs:
+recent code that re-implements established callable, React, or Vue code.
+`health` gives a composite codebase health report (score, findings,
+priorities, baselines, coverage notes) scoped to the frontend area.
+
+**Complete when:** command scope, counts, and uncapped/full status are
+recorded.
+
+## Step 2 — Cross-check candidates
+
+- **Component-duplicate-only finding** — inspect for a shared presentational
+  component or existing component reuse.
+- **Hook/composable-candidate-only finding** — inspect for shared behavior,
+  lifecycle, request, validation, persistence, event, or derived-state
+  policy.
+- **Both overlap** — inspect for a feature-level concept that needs both a
+  component and a hook/composable boundary.
+- **Large-component/view-only finding** — split by reason to change, not by
+  line count.
+
+Use `scip-query outline <file>`, `deps <file>`, `rdeps <file>`,
+`similar-files --scope <scope>`, and (React) `similar
+<closest-existing-component-or-hook>` / (Vue) `recent-duplicates --scope
+<scope> --full --json` to validate candidates.
+
+**Complete when:** each top candidate is classified as reuse, extract,
+split, skip, or blocked.
+
+## Step 3 — Act on findings
+
+Prefer reuse over extraction.
+
+- **React:** extract a component for repeated UI structure, states, props,
+  slots/children, or design-system composition; extract a hook for repeated
+  state, effects, requests, subscriptions, memoized derivations, callbacks,
+  or persistence.
+- **Vue:** extract a component for repeated template structure, props,
+  slots, states, or design-system composition; extract a composable for
+  repeated state, lifecycle, requests, validation, persistence, derived
+  data, or event policy.
+
+Keep domain-specific/essential variation at the call site rather than
+abstracting it away.
+
+Anti-patterns to avoid as a side effect of acting on a finding: do not
+create boolean-soup APIs or wrapper components with no policy. Shared
+design-system primitives, icons, labels, route names, test IDs, or CSS
+utilities alone are not sufficient evidence to justify a duplicate/hook/
+composable claim. Similar JSX/templates with different domain lifecycles may
+justify a presentational component but does not justify a shared hook or
+composable.
+
+**Complete when:** the chosen action reduces future drift without creating
+boolean-soup APIs or wrapper components with no policy.
+
+## Step 4 — Verify
+
+Invoke `scip-verify` and use its authoritative postcheck table, including
+the applicable React/Vue, extraction, duplicate, parameter, wrapper,
+passthrough, and stale-abstraction checks.
+
+**Complete when:** acted-on candidate pairs disappear, weaken materially, or
+are explicitly accepted as essential variation.
+
+## Report
+
+Executive read, command evidence, candidate groups, recommended action,
+post-change proof, and remaining accepted variation.

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

@@ -0,0 +1,154 @@
+# Integrity: is this real?
+
+Structural review (`references/maintainability.md`) asks "is this well
+organized?" This drill set asks **"is this real?"** — it hunts decorative
+checkers, adapters written against imagined data, features that have
+silently never run, and numbers nobody ever recomputed.
+
+Command shortlist: `refs <symbol>`, `code <symbol>`, `trace <symbol>`,
+`call-graph <symbol>`, `twin-drift -s <scope> --json`,
+`twin-ab <symbolA> <symbolB>`, `outline <file> --signatures`,
+`decorative-checkers -s <scope> --json`, `not-implemented -s <scope> --json`,
+`test-quality -s <scope> --json`.
+
+## The stance
+
+A green result you have never seen fail is unverified: every status word,
+banner, and metric is testimony from the code, not evidence about the code,
+so cross-examine the producer before believing it. The most dangerous code
+is not broken code; it is code that reports success without doing the work.
+
+## Run all five drills over the chosen scope
+
+### Drill 1 — Falsify every checker
+
+Inventory everything in scope that accepts/rejects, passes/fails, or
+validates (checkers, gates, verifiers, validators) by finding producers with
+`refs`/`call-graph` on the status words in their output.
+
+For each one found, construct an input that MUST fail — a wrong binding, a
+corrupt file, an impossible value — and run it. A checker that passes its
+should-fail input is decorative and must be filed as a defect, not a note.
+
+Before filing, attempt the defense: an accusation triggers a rewrite, so
+search for the failure exit the drill may have missed — a config-gated
+branch, an async rejection, or one-hop delegation (the calibration's known
+noise archetypes). File the defect with the executed should-fail input
+attached and the defense attempt noted; a defense that succeeds clears the
+checker and stays in the record as its witness.
+
+**Complete when:** every checker in scope has been witnessed rejecting a
+constructed should-fail input, or is listed with a reason it cannot be.
+
+Mechanized by `scip-query decorative-checkers`, which finds
+`validate*`/`verify*`/`check*`/`assert*`/`is*`/`has*` callables with no
+reachable failure exit anywhere in their body. Run it first to shortlist
+candidates before hand-constructing should-fail inputs. It was calibrated
+2026-07-03 against two external repos, is standalone-only, and its noise
+archetypes past one-hop delegation are documented in
+`docs/validation/2026-07-03-integrity-detector-calibration.md`.
+
+### Drill 2 — Diff every adapter against captured reality
+
+For each parser/adapter of an external format (tool output, XML/JSON
+schemas, protocol messages), obtain ONE real sample from the actual source
+and diff it against the code's assumptions and the tests' fixtures. Ask of
+every fixture whether it was generated from reality or imagined. A parser
+and a hand-written fixture can validate each other's shared hallucination
+indefinitely, so fixture-vs-code agreement alone is not proof of
+correctness.
+
+**Complete when:** every adapter has been checked against at least one
+captured-real sample.
+
+### Drill 3 — Autopsy every fallback
+
+For every catch block, `??` fallback, and degraded mode in scope, produce an
+execution witness (a test, a probe, a log) that the PRIMARY path runs —
+because a primary path that has never worked looks identical to a healthy
+fallback. Use the probe-reachability mode in `scip-diagnose` for parser/AST
+branch reachability
+when autopsying fallbacks. A fallback that always fires means the feature
+above it is dead — "date of death: birth."
+
+**Complete when:** every fallback's primary path has a witness or a filed
+defect.
+
+Mechanized by `scip-query not-implemented`, which finds reachable placeholder
+stubs (`throw new Error('not implemented')`, TODO-comment + return-default,
+empty bodies) that a real caller, entry surface, or package-surface export
+can actually reach — distinguishing "primary path never built" from `dead`'s
+"primary path built but unreferenced." Standalone-only (calibrated
+2026-07-03; 0 live findings on two external repos post-fix). A clean run
+means "nothing this shape found," not proof that every fallback's primary
+path is live.
+
+### Drill 4 — Hand-compute every metric twice
+
+For each number the system reports (scores, counts, estimates), pick two
+concrete instances, compute the expected value by hand from first
+principles, and compare — off-by-a-factor errors (double counting, inflated
+estimates) survive for years when nobody recomputes a single sample.
+
+**Complete when:** every reported metric has two hand-verified samples.
+
+### Drill 5 — Cross-examine same-concept twins
+
+Where one concept is computed in more than one place, feed both
+implementations the same input and require the same answer. `twin-drift`
+finds same-name cases mechanically; same-concept-different-name pairs must be
+traced via `refs` and compared via `code` (see `references/twin-drift.md`
+for the full drift-classification workflow once a pair is found).
+
+Once a twin pair is identified, `scip-query twin-ab <symbolA> <symbolB>`
+scaffolds a table-driven vitest file that imports both implementations and
+asserts equal output — fill in the input table and run it. Disagreement
+between twins means at least one is wrong — determine which before
+consolidating them.
+
+**Complete when:** every discovered twin pair has been compared on a shared
+input.
+
+## Severity
+
+Rank findings by what the failure does to a user who trusted the output: a
+decorative checker or false "verified" banner outranks everything; a
+dead-but-fallbacked feature outranks a wrong metric; a wrong metric outranks
+structural mess. Route structural findings to `references/maintainability.md`
+instead of reporting them here — they are real but they are not lies.
+
+## Reporting
+
+File each finding with: the claim as displayed, the producer (file:line),
+the drill that exposed it, the should-fail input or real sample used, and the
+fix. The audit is complete only when every drill's exit criterion is met for
+the scope, and every defect found has a regression artifact (a test,
+fixture, or model) that fails on the pre-fix behavior.
+
+End with a derived verdict, not an impression:
+
+```
+Integrity: <scope> — <c> checkers witnessed failing, <a> adapters diffed
+against reality, <f> fallback primaries witnessed live, <m> metrics
+recomputed, <t> twins compared; <d> defects filed, <u> unverifiable (reasons)
+```
+
+A suspect scope that produces zero defects is itself a claim: state what
+made the suspicion wrong, or rerun the drill that should have caught it.
+
+## Your own regression artifacts are in scope too
+
+A regression artifact that doesn't actually assert anything, or asserts the
+same literal it stubbed into its own mock, is a fake witness — the same
+"reports success without doing the work" failure mode this drill set hunts
+in production code, just relocated to the test suite.
+
+Run `scip-query test-quality -s <scope>` over the audit's own regression
+artifacts (and periodically over the suite at large) to catch fake
+witnesses. It catches assertion-free test bodies, a skipped-test ledger with
+git-blame age (a skip with no fix date attached is a claim nobody is
+checking), and mock-echo (a test that only proves its own stub).
+Standalone-only with mixed precision by sub-check (calibrated 2026-07-03):
+assertion-free and skipped are high-precision; mock-echo is intentionally
+low-precision (syntactic same-literal matching, not dataflow) — treat its
+output as a reviewed candidate list, not a verdict.

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

@@ -0,0 +1,162 @@
+# Maintainability: hidden policy, scattered concepts, weak boundaries
+
+Maintainability is the degree to which real code units let a maintainer
+understand, verify, and change behavior without rediscovering hidden
+knowledge. Use for hidden policies, scattered concepts, accidental
+variation, weak boundaries, system compression, architecture smells, and
+structural refactor opportunities beyond a health score.
+
+Ground all claims in files, symbols, references, call graphs, dependencies,
+surfaces, and blast radius rather than opinion. Do not chase health scores —
+detector counts are clues, not objectives. Name concrete referents (specific
+files/symbols) before naming a code smell. Only add an abstraction when it
+removes hidden policy, names a lifecycle, enforces a rule, or reduces
+concept count — never for its own sake; prefer deletion, inlining, merging,
+generation, or enforcement of an existing mechanism before introducing a
+broad new framework.
+
+## Vocabulary
+
+- **Code smell** — an observable codebase fact that predicts avoidable
+  future mistakes because the same knowledge must be rediscovered,
+  synchronized, or defended in more than one place.
+- **Concept boundary** — the line around code units that exist for one
+  reason to change.
+- **Hidden policy** — a rule for choosing among several plausible behaviors
+  that lives in local branches, comments, conventions, or caller folklore
+  instead of a named mechanism.
+- **Lifecycle** — a repeatable sequence of states or steps that makes a
+  result valid.
+- **Accidental variation** — difference in code shape that does not
+  correspond to behavior, domain facts, runtime constraints, or external
+  contracts.
+- **Essential variation** — difference that must remain because the real
+  units differ: language grammars, user-visible APIs, runtime environments,
+  or compatibility boundaries. Preserve it; do not remove it.
+- **System compression** — replacing several mechanisms that perform the
+  same role, policy, lifecycle, or surface job with fewer named mechanisms
+  that preserve behavior.
+- **Unifying definition** — the single essential trait that makes several
+  code sites one concept. Any scattered-concept or consolidation claim must
+  ship its unifying definition; if no such trait covers every cited site,
+  the variation is essential and the sites must not be consolidated. Failing
+  to state it proves the sites are not one concept — consolidating anyway
+  packages essential variation into a false abstraction.
+
+## Step 1 — Bound the review
+
+Restate the review question as: "What future-maintenance mistakes does this
+structure invite, and what smaller named mechanisms would prevent them
+without hiding real variation?" Name the scope as one of: repo, module,
+command family, query family, runtime surface, fixture set, or feature path.
+
+**Complete when:** the review question and scope are both concrete.
+
+## Step 2 — Map evidence
+
+Run, in sequence: `scip-query stats`, `system <scope>`, `surface <scope>`,
+`files <pattern>`, `outline <file>`, `deps <file>`, `rdeps <file>`, `trace
+<symbol>`, `call-graph <symbol>`, `affected <symbol>`, `change-surface
+<file>`.
+
+- `stats` maps repo-wide index size before bounding the review (complete
+  coverage).
+- `system <scope>` gives the full module map — files, exported symbols with
+  line ranges, internal deps, reverse deps (complete coverage).
+- `surface <scope>` shows which symbols consumers actually use — consumer
+  paths and consumed symbol identities (complete coverage).
+- `change-surface <file>` gives a pre-change briefing of defined symbols,
+  external consumer counts, and risk levels (bounded coverage).
+- `affected <symbol>` computes the transitive closure of symbols that could
+  break if a candidate symbol changes (bounded coverage).
+- `drift --patterns --architecture` finds drift candidates — unused imports
+  plus declared architecture boundary violations (bounded coverage; opt-in
+  pattern hits are leads, not confirmed findings).
+
+Use the cleanup-oriented commands `health`, `similar`, `similar-files`,
+`similar-chains`, `extract-candidates`, `wrapper-candidates`,
+`passthrough-candidates`, `stale-abstractions`, `drift`, and `cycles` as
+evidence-gathering probes during this step, not as final verdicts.
+
+**Complete when:** concrete units, consumers, tests, fallbacks, adapters,
+generated artifacts, and compatibility constraints are all visible.
+
+## Step 3 — Build the role inventory
+
+For each cluster, ask what one concept appears in several places and what
+single essential trait makes them one concept — if the trait cannot be
+stated, they are not one concept. Also ask: what policy is hidden, what
+lifecycle is unnamed, which differences are essential, what must a
+maintainer know that the local interface does not admit, and would a
+smaller mechanism remove a reason to change, versus merely move code?
+
+**Complete when:** every candidate smell names its referents and its
+future-maintenance failure mode.
+
+## Step 4 — Rank pressure
+
+Severity tiers, most to least severe:
+
+1. Hidden correctness or evidence policy spread across modules.
+2. A repeated lifecycle or pipeline with no owner.
+3. Public surface exposing accidental internals.
+4. A large module with unrelated reasons to change.
+5. Tests that encode incident history without contract vocabulary.
+6. Adapter families with repeated capability or fallback shapes.
+7. Suppression comments that document architecture decisions instead of
+   exceptions.
+8. Thin wrappers and passthroughs that do not buy clarity.
+
+Reject and do not act on smells that are aesthetic, unverifiable, or false
+compression.
+
+**Complete when:** each target is ranked, skipped, or deferred with
+evidence.
+
+## Step 5 — Choose a model
+
+For substantial changes, compare at least two of three models:
+
+- **Conservative** — delete or inline local bloat.
+- **Shape-level** — introduce one small mechanism for a repeated role or
+  lifecycle.
+- **Radical** — replace a scattered surface with metadata, generation, or
+  enforced policy.
+
+Evaluate: behavior preserved, concept count removed, blast radius, deletion
+potential, false-abstraction failure mode, migration path, and verification
+cost.
+
+**Complete when:** the chosen model removes a concept or policy duplication
+rather than merely extracting a helper.
+
+## Step 6 — Produce a register or atlas
+
+For a broad review, write a register under `docs/plans/` unless the user
+asks not to edit files; for an implementation, write an atlas before
+editing.
+
+Dispositions: merge, delete, inline, extract, generate, enforce, supersede,
+defer, skip.
+
+Every merge, extract, or generate entry must carry its unifying definition
+and its strongest dissenter (the cited site most likely to differ
+essentially), plus evidence that the dissenter does not actually differ
+essentially. If a dissenter survives review (it really does differ
+essentially), the entry moves to disposition `skip` with reason "essential
+variation" — but the dissenter stays recorded in the register either way.
+
+**Complete when:** each opportunity has evidence, disposition, dependency
+order, touch map, and validation plan recorded.
+
+## Step 7 — Implement and verify (when asked)
+
+Implement the smallest named mechanism that matches the real concept, and
+keep essential variation near the adapter or domain code that knows it.
+After implementing, run focused tests and the routed postchecks from
+`scip-verify`, then complete that verification skill.
+
+## Report
+
+State the smell addressed, the mechanism introduced or removed, what was
+deliberately not compressed, and verification results.