scip-query 0.10.12 → 0.12.0

package/skills/scip-debug/SKILL.md

@@ -1,49 +1,73 @@
 ---
 name: scip-debug
-description: Root-cause bugs and regressions with scip-query evidence. Use when the user reports a bug, failing behavior, regression, confusing runtime path, broken data flow, or asks to debug, diagnose, reproduce, trace, or explain why code behaves incorrectly before fixing it.
+description: Debug bugs and regressions with scip-query evidence. Use for failing behavior, wrong data flow, confusing runtime paths, broken tests, root-cause analysis, reproduction, tracing, or minimal fixes.
+commands:
+  - template: "scip-query files <feature-or-error-term>"
+    when: "Find the entry point from a feature name or error term."
+  - template: "scip-query trace <candidate-symbol>"
+    when: "Find the entry point: definition plus every reference."
+  - template: "scip-query call-graph <entry-symbol>"
+    when: "Follow execution: callers and callees along the failing path."
+  - template: "scip-query dataflow <symbol-or-variable>"
+    when: "Follow data: producers, consumers, and usage sites."
+  - template: "scip-query similar <suspect-symbol> --json --full"
+    when: "Compare nearby implementations for missing guards or handling."
+  - template: "scip-query change-surface <suspect-file> --json --full"
+    when: "Bound the fix: exports, consumers, and blast-radius risk."
 ---
 
-# SCIP Debug
+# scip-debug
 
-Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch and makes the later symptoms possible.
+Use this skill to move from a reported failure to a minimal verified fix. A bug is a mismatch between expected behavior and observed behavior in a concrete execution path. A root cause is the earliest code fact in that path that explains the mismatch.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query files <feature-or-error-term>` | Find files matching a pattern | Find the entry point from a feature name or error term. |
+| `scip-query trace <candidate-symbol>` | Trace a symbol: definition + all references | Find the entry point: definition plus every reference. |
+| `scip-query call-graph <entry-symbol>` | Show incoming callers and outgoing callees for a symbol | Follow execution: callers and callees along the failing path. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Follow data: producers, consumers, and usage sites. |
+| `scip-query similar <suspect-symbol> --json --full` | Find heuristic function similarity candidates from callee fingerprints | Compare nearby implementations for missing guards or handling. |
+| `scip-query change-surface <suspect-file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Bound the fix: exports, consumers, and blast-radius risk. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
 ## Rules
 
-1. Reproduce or restate the failure before changing code.
-2. Use scip-query to identify entry points, call paths, data flow, and blast radius. Do not debug from filename guesses alone.
-3. Prefer one narrow fix over broad cleanup. If cleanup is also needed, record it after the bug fix unless it is required for correctness.
-4. Verify the fix with the repo's test or smoke command, then run `scip-verify`.
+1. Reproduce or restate the failure before editing.
+2. Use scip-query to find entry points, call paths, data flow, and blast radius.
+3. Prefer one narrow fix over broad cleanup.
+4. Verify with the narrowest repo test or smoke command, then invoke `scip-verify`.
 
 ## Workflow
 
 ### 1. Pin the failure
 
-Record:
+Record observed behavior, expected behavior, reproducing command/route/UI action/test/job/file, error text or wrong output, and regression window if known.
 
-- observed behavior;
-- expected behavior;
-- command, route, UI action, test, job, or file that exposes it;
-- error text or wrong output;
-- suspected time window if it is a regression.
+If no reproduction is provided, build the smallest runnable reproduction from existing tests, scripts, CLI, or app entry points.
 
-If the user provides no reproduction, make the smallest runnable reproduction you can from the repo's existing tests, scripts, CLI, or app entry points.
+This step is complete only when the mismatch is concrete enough to test or the missing external fact is named.
 
 ### 2. Find the entry point
 
 ```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
 scip-query files <feature-or-error-term>
 scip-query outline <candidate-file>
 scip-query trace <candidate-symbol>
 scip-query code <candidate-symbol>
 ```
 
-Use `scip-query by-kind function --scope <scope>` or `scip-query kind-counts --scope <scope>` when the codebase is unfamiliar and you need an inventory before selecting an entry point.
+Use `kind-counts` or `by-kind` when the codebase is unfamiliar.
+
+This step is complete only when the failing path has a plausible entry point with source evidence.
 
-### 3. Follow execution
+### 3. Follow execution and data
 
 ```bash
 scip-query call-graph <entry-symbol>
@@ -51,73 +75,51 @@ scip-query code <callee-symbol>
 scip-query refs <state-or-api-symbol>
 scip-query fan-in <suspect-symbol>
 scip-query fan-out <suspect-file>
-```
-
-Build the smallest path that explains the observed behavior. Stop expanding once the path reaches the first code fact that can cause the symptom.
-
-### 4. Follow data and state
-
-```bash
 scip-query dataflow <symbol-or-variable>
 scip-query slice <symbol-or-variable>
 scip-query slice <symbol-or-variable> --forward
 ```
 
-Use dataflow when the bug looks like wrong state, wrong input normalization, missing validation, stale cache, dropped field, wrong async order, or an unexpected output value.
+Stop expanding when the first code fact that can cause the symptom is found.
 
-### 5. Compare nearby implementations
+This step is complete only when the path explains the symptom or the missing evidence is explicit.
+
+### 4. Compare nearby implementations
 
 ```bash
 scip-query similar <suspect-symbol> --json --full
-scip-query convergence <suspect-symbol> <similar-symbol>
+scip-query similar <suspect-symbol> <similar-symbol> --plan
 scip-query similar-files <suspect-file> --json --full
 ```
 
-A similar implementation can reveal the missing branch, guard, conversion, lifecycle step, or error handling path. Preserve essential differences; do not copy behavior blindly.
+Use comparisons to find missing guards, conversions, lifecycle steps, or error handling. Preserve essential differences.
+
+This step is complete only when comparisons either support the fix or are rejected with a reason.
 
-### 6. Bound the fix
+### 5. Bound and fix
 
 ```bash
 scip-query change-surface <suspect-file> --json --full
 scip-query affected <suspect-symbol> --json
-scip-query diff-impact --json
 ```
 
-Name the smallest symbol or file that should change. If the blast radius is larger than the bug's scope, explain why before editing.
-
-### 7. Fix and verify
+Make the smallest code change that fixes the root cause.
 
-Apply the minimal code change, then run:
+This step is complete only when the changed symbol/file is justified by blast-radius evidence.
 
-```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query diff-gate --json
-```
+### 6. Verify
 
-Also run the narrowest repo test, app smoke test, or command that reproduces the failure. Invoke `scip-verify` before calling the bug fixed.
+Run the reproduction, narrow test or smoke command, and invoke `scip-verify`.
 
-## Report Format
+## Report
 
 ```markdown
-Bug: <observed mismatch>
-
+Bug:
 Entry point:
-- <file/symbol> from <command>
-
 Root cause:
-- <code fact> from <command>
-
 Fix:
-- <minimal change>
-
 Verification:
-- <repo test or smoke command>
-- `scip-query diff-gate --json`
-
 Remaining risk:
-- <blast radius, unavailable capability, or follow-up cleanup>
 ```
 
-If no root cause is proven, say what evidence is missing and what command or reproduction would unblock it. Do not present a guess as a fix.
+Do not present a guess as a root cause. If no root cause is proven, report the missing evidence.

package/skills/scip-diagram/SKILL.md

@@ -1,43 +1,68 @@
 ---
 name: scip-diagram
-description: Create evidence-backed HTML diagrams of how code works using scip-query. Use when the user asks for a code flow diagram, architecture diagram, data-flow diagram, dependency map, blast-radius visualization, module map, or an HTML artifact that explains a system.
+description: Diagram code with scip-query evidence. Use for code flow diagrams, architecture diagrams, data-flow maps, dependency maps, blast-radius visuals, module maps, or HTML artifacts explaining a system.
+commands:
+  - template: "scip-query system <module>"
+    when: "Collect evidence: module map for a dependency or architecture diagram."
+  - template: "scip-query trace <symbol>"
+    when: "Collect evidence: definition plus references for a call-flow diagram."
+  - template: "scip-query call-graph <symbol>"
+    when: "Collect evidence: callers/callees for a call-flow diagram."
+  - template: "scip-query dataflow <symbol>"
+    when: "Collect evidence: producers/consumers for a data-flow diagram."
+  - template: "scip-query affected <symbol> --json"
+    when: "Collect evidence: blast-radius nodes and edges."
+  - template: "scip-query change-surface <file> --json --full"
+    when: "Collect evidence: exports and consumers for a change-surface map."
 ---
 
-# SCIP Diagram
+# scip-diagram
 
-Use this skill to build a visual explanation from compiler-resolved code facts. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map. Its defining trait is that every node and edge comes from scip-query evidence, not from guessed folder structure.
+Use this skill to build a visual explanation from compiler-resolved facts. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map; every node and edge must trace to scip-query evidence.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query system <module>` | Full module map: files, symbols, deps in/out | Collect evidence: module map for a dependency or architecture diagram. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Collect evidence: definition plus references for a call-flow diagram. |
+| `scip-query call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | Collect evidence: callers/callees for a call-flow diagram. |
+| `scip-query dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Collect evidence: producers/consumers for a data-flow diagram. |
+| `scip-query affected <symbol> --json` | Transitive closure of symbols that could break if this symbol changes | Collect evidence: blast-radius nodes and edges. |
+| `scip-query change-surface <file> --json --full` | Pre-change briefing: exports, consumers, and blast-radius risk | Collect evidence: exports and consumers for a change-surface map. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
 ## Rules
 
-1. Run scip-query evidence first, then draw. Do not invent nodes or arrows.
-2. Make a self-contained HTML file unless the user asks for another format.
-3. Include command provenance in the HTML so readers can see which scip-query commands produced the diagram.
-4. Keep diagrams scoped. If the graph is huge, summarize clusters and link to detailed evidence rather than rendering a hairball.
-5. Verify the HTML opens cleanly and contains the expected diagram content.
+1. Run evidence before drawing.
+2. Default to a self-contained HTML file.
+3. Include command provenance in the artifact.
+4. Scope large graphs into clusters instead of rendering a hairball.
+5. Verify the HTML opens and the diagram is nonblank.
 
-## Pick the Diagram Type
+## Workflow
 
-| User wants | Use |
-|---|---|
-| "How does this feature work?" | Call-flow diagram |
-| "Where does this value come from?" | Data-flow diagram |
-| "What depends on this?" | Blast-radius diagram |
-| "What is this module's architecture?" | Module/dependency diagram |
-| "Why is this hard to change?" | Change-surface or bottleneck diagram |
-| "Show classes or ownership" | Hierarchy and surface diagram |
+### 1. Pick diagram type
 
-## Evidence Commands
+| User wants | Diagram |
+| --- | --- |
+| Feature flow | Call flow |
+| Value origin or mutation | Data flow |
+| Dependents | Blast radius |
+| Module architecture | Dependency map |
+| Hard-to-change explanation | Change surface or bottleneck map |
+| Classes or ownership | Hierarchy and surface map |
 
-Start with current graph facts:
+This step is complete only when the diagram's node and edge types are chosen.
 
-```bash
-scip-query status --capabilities
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-```
+### 2. Collect evidence
 
-Collect only the commands needed for the diagram:
+Use only commands needed for the chosen diagram:
 
 ```bash
 scip-query system <module>
@@ -55,86 +80,31 @@ scip-query affected <symbol> --json
 scip-query change-surface <file> --json --full
 scip-query hierarchy <symbol> --json
 scip-query fan-out <file> --json
-scip-query bottlenecks
-scip-query cycles
 ```
 
-Use `scip-query kind-counts --scope <scope>` and `scip-query by-kind <kind> --scope <scope>` when the diagram needs an inventory of symbols.
+This step is complete only when every planned node and edge has a source command.
 
-## Build the HTML
+### 3. Build the artifact
 
-Write the artifact under:
+Write to:
 
 ```text
 docs/scip-query/diagrams/YYYY-MM-DD-<scope>.html
 ```
 
-If the repo has a different reports convention, follow it. The file should include:
-
-- title and scope;
-- short textual summary;
-- the visual diagram;
-- legend for node colors, edge styles, and risk labels;
-- evidence table listing every scip-query command used;
-- notes for omitted nodes, collapsed clusters, or unavailable capabilities.
-
-Implementation guidance:
-
-- Use inline CSS and either semantic HTML layout or inline SVG.
-- Use stable dimensions and labels that wrap cleanly.
-- Use one visual encoding per meaning: call edges, data edges, dependency edges, and risk edges should look different.
-- Keep colors accessible and avoid relying on color alone; include labels or edge styles.
-- For large graphs, group by module, ownership, lifecycle phase, or public surface.
-
-## Diagram Recipes
-
-### Call Flow
-
-```bash
-scip-query trace <entry-symbol>
-scip-query call-graph <entry-symbol>
-scip-query code <entry-symbol>
-```
-
-Render entry point -> major callees -> side effects or terminal outputs. Label each edge with the call or branch reason when `code` proves it.
-
-### Data Flow
-
-```bash
-scip-query dataflow <value-symbol>
-scip-query slice <value-symbol>
-scip-query slice <value-symbol> --forward
-```
-
-Render producers, transformations, validators, storage, and consumers. Mark inferred or unavailable parts explicitly.
+Include title, scope, summary, visual diagram, legend, evidence table, omitted/collapsed nodes, and unavailable capabilities.
 
-### Dependency or Module Map
-
-```bash
-scip-query system <module>
-scip-query deps <file>
-scip-query rdeps <file>
-scip-query surface <module>
-```
-
-Render internal files, imported modules, reverse consumers, and public surfaces. Distinguish internal dependencies from external consumers.
-
-### Blast Radius
-
-```bash
-scip-query affected <symbol> --json
-scip-query change-surface <file> --json --full
-```
+Use inline CSS and semantic HTML or inline SVG. Give stable dimensions, wrapping labels, accessible colors, and distinct edge styles for calls, data, dependencies, and risk.
 
-Render the changed symbol, direct consumers, transitive consumers, and high-risk surfaces. Show depth so the user can see how far the change travels.
+This step is complete only when the HTML contains the visual and provenance table.
 
-## Verification
+### 4. Verify
 
-After writing the HTML:
+Open the file locally or use a browser/screenshot tool when available. Confirm:
 
-1. Open it locally or use a browser/screenshot tool when available.
-2. Confirm the diagram is nonblank and labels do not overlap badly.
-3. Confirm every major node and edge is traceable to the evidence table.
-4. Run `scip-query diff-gate --json` if the diagram is part of a code or docs change.
+- diagram is nonblank;
+- labels do not overlap badly;
+- major nodes and edges trace to evidence;
+- `scip-verify` has been invoked when this is part of a docs/code change.
 
-End by giving the file path and a short summary of what the diagram proves.
+End with the file path and what the diagram proves.

package/skills/scip-directory-architecture/SKILL.md

@@ -1,71 +1,73 @@
 ---
 name: scip-directory-architecture
-description: Review and improve repository directory architecture with scip-query evidence. Use when the user asks to design, evaluate, reorganize, or migrate source folder structure; identify feature/module ownership boundaries; turn a messy or AI-generated codebase into clearer folders; decide whether locality boundaries are mature enough for config; or plan safe directory migrations without guessing from filenames alone.
+description: Review directory architecture with scip-query evidence. Use to evaluate, design, reorganize, or migrate folder structure, ownership boundaries, locality config, messy repos, AI-generated layout, or safe file-move slices.
+commands:
+  - template: "scip-query system <scope>"
+    when: "Inventory evidence: files, symbols, deps in/out for the scope."
+  - template: "scip-query locality-candidates --json --full"
+    when: "Inventory evidence: directory-locality candidates from consumer ownership."
+  - template: "scip-query similar-files --full --json"
+    when: "Inventory evidence: files with overlapping dependency profiles."
+  - template: "scip-query cycles"
+    when: "Inventory evidence: circular dependency chains between files."
+  - template: "scip-query co-change --json --full"
+    when: "Inventory evidence: hidden file-level coupling from git history."
+  - template: "scip-query config-validate --json"
+    when: "Implement a slice: validate locality config after a move."
 ---
 
-# SCIP Directory Architecture
+# scip-directory-architecture
 
-## Overview
+Use this skill to answer where code should live. Directory architecture is the filesystem arrangement of source files by their main reason to change; what distinguishes a good structure is that a maintainer can predict where a concept belongs before reading every import.
 
-Use this skill to turn source layout questions into an evidence-backed architecture review. Do not treat the current folder tree as authoritative, and do not invent an "optimal" structure without proving the ownership concepts from code, tests, docs, and dependency evidence.
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-A directory architecture is the filesystem arrangement of source files by their main reason to change. Its defining trait is that a maintainer can predict where a concept belongs before reading every import.
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
-An ownership boundary is a folder, package, module, or convention that groups code around one stable responsibility. Its defining trait is that code inside the boundary should usually change for the same kind of reason.
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query system <scope>` | Full module map: files, symbols, deps in/out | Inventory evidence: files, symbols, deps in/out for the scope. |
+| `scip-query locality-candidates --json --full` | Find directory-locality and ancestry candidates from consumer ownership | Inventory evidence: directory-locality candidates from consumer ownership. |
+| `scip-query similar-files --full --json` | Find heuristic similar-file candidates from dependency profiles | Inventory evidence: files with overlapping dependency profiles. |
+| `scip-query cycles` | Detect circular dependency chains between files | Inventory evidence: circular dependency chains between files. |
+| `scip-query co-change --json --full` | Files that change together in git history without a dependency edge — hidden coupling candidates | Inventory evidence: hidden file-level coupling from git history. |
+| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | Implement a slice: validate locality config after a move. |
 
-A target structure is a proposed future folder layout for the repo or scope. Its defining trait is that it expresses the desired ownership model, not merely a prettier tree.
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
 
-A migration slice is the smallest set of file moves and import updates that can be verified independently. Its defining trait is that it reduces one structural ambiguity without requiring the whole architecture to move at once.
+## Terms
 
-## Non-Negotiables
+An ownership boundary is a folder, package, module, or convention that groups code around one stable responsibility.
 
-1. Start with evidence, not taste. Refresh the index when stale, then ground claims in `scip-query` outputs plus project docs and tests.
-2. Separate review from migration. A directory architecture review may propose moves; it does not move files unless the user asked for implementation or approved a specific migration slice.
-3. Preserve working conventions. Existing boundaries are not wrong just because they are broad; central folders such as `errors`, `routes`, `workflows`, `schemas`, `contracts`, or `features` may be doing real work.
-4. Do not reward generic `shared`. A shared folder is justified only when the shared concept has a name, owner, and consumers across real boundaries.
-5. Treat messy repos honestly. If ownership concepts are not stable, produce a discovery map and decision list instead of pretending the repo has a clean target structure.
-6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, a fresh scip-query index, and `scip-query diff-gate --json`.
+A target structure is a proposed future layout that expresses an ownership model, not merely a prettier tree.
 
-## Workflow
-
-### 1. Bound the Question
-
-Identify whether the user wants:
-
-- a review of the existing structure;
-- a proposed target structure;
-- a locality config decision;
-- a migration plan;
-- or an actual file-moving implementation.
+A migration slice is the smallest set of file moves and import updates that can be verified independently.
 
-If the user asks for "the best folder structure," translate that into: "What ownership model is supported by this repo's code, tests, product domains, and change history?"
+A slop codebase is a codebase whose files are arranged by accident, convenience, or recent edits rather than stable ownership rules.
 
-### 2. Refresh and Inventory
+## Rules
 
-Run:
+1. Start with evidence, not taste.
+2. Separate review from migration; do not move files unless asked.
+3. Preserve broad boundaries when evidence shows they are intentional.
+4. Do not reward generic `shared` unless the shared concept has a name, owner, and cross-boundary consumers.
+5. For messy repos, produce a discovery map and decisions instead of pretending the target is obvious.
+6. Prefer small verified moves.
 
-```bash
-scip-query status
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query stats
-find . -maxdepth 3 -type d | sort
-```
-
-Read durable project guidance before judging structure:
+## Workflow
 
-```bash
-rg -n "architecture|structure|feature|module|boundary|shared|workflow|route|contract|domain|ownership" AGENTS.md README.md docs agent-os .codex -g '!node_modules'
-```
+### 1. Bound the question
 
-Use `rg --files` to sample real files in each important folder. Ignore generated, build, coverage, vendored, and dependency directories unless they are part of the architecture question.
+Classify the request: review, target structure, locality config, migration plan, or implementation.
 
-### 3. Build the Evidence Map
+This step is complete only when the scope and deliverable are explicit.
 
-Use these probes as evidence, not as verdicts:
+### 2. Inventory evidence
 
 ```bash
+scip-query stats
 scip-query system <scope>
 scip-query files <pattern>
 scip-query surface <scope>
@@ -82,101 +84,57 @@ scip-query recent-duplicates
 scip-query drift
 ```
 
-For each folder under review, record:
+Also read durable project guidance that names architecture, modules, ownership, routes, workflows, contracts, or domains.
 
-- real-world concept or product area represented by the folder;
-- public exports, entry points, routes, commands, or package surfaces;
-- main consumers and cross-boundary consumers;
-- tests that define the folder's behavior;
-- co-change partners and repeated edit patterns;
-- duplicated or parallel folder patterns;
-- docs or standards that claim ownership rules.
+This step is complete only when each folder under review has evidence for exports, entry points, consumers, tests, co-change partners, and claimed ownership rules.
 
-### 4. Classify Boundary Maturity
+### 3. Classify boundary maturity
 
-Classify each candidate folder:
+Classify each candidate:
 
 - Mature: repeated, documented, and enforced by imports, tests, routes, packages, standards, or review history.
-- Emerging: meaningful and partly repeated, but not yet consistent enough to configure or enforce.
-- Accidental: a convenience bucket, legacy pile, generated artifact, recent edit cluster, or mixed folder with unrelated reasons to change.
+- Emerging: meaningful and partly repeated, but not consistent enough to configure.
+- Accidental: convenience bucket, legacy pile, generated artifact, recent edit cluster, or mixed reasons to change.
 
-A slop codebase is a codebase whose files are arranged by accident, convenience, or recent edits rather than stable ownership rules. Its defining trait is that directory names do not reliably predict where code should live. For this case, stop at discovery and decision prompts unless the user explicitly asks for a first migration slice.
+This step is complete only when mature, emerging, and accidental boundaries are separated.
 
-### 5. Propose the Target Structure
+### 4. Propose structure or decisions
 
-Produce an architecture proposal with this shape:
+Use this shape:
 
-````markdown
+```markdown
 # Directory Architecture Review
 
 ## Scope
 ## Current Structure Map
 ## Boundary Maturity
-
-| Boundary | Evidence | Maturity | Judgment |
-| --- | --- | --- | --- |
-
 ## Target Structure
-
-```text
-src/
-  ...
-```
-
 ## Move Ledger
-
-| Slice | Current files | Proposed home | Why | Verification |
-| --- | --- | --- | --- | --- |
-
 ## Locality Config
+## No-Move Decisions
 ## Deferred Decisions
 ## Migration Order
-````
-
-The target structure should name ownership concepts, not just folder labels. Prefer existing names when they already carry meaning. Introduce a new folder only when it removes ambiguity for multiple files or consumers.
-
-### 6. Decide What Not to Move
-
-Explicitly list no-move decisions when:
-
-- a broad consumer set proves a central boundary is useful;
-- a folder is route-facing, package-facing, or contract-facing;
-- consumers cross boundaries because the concept is infrastructure;
-- moving would hide a domain-specific concept under generic `shared`;
-- the evidence is too weak and needs a human ownership decision.
+```
 
-### 7. Implement Only a Migration Slice
+List no-move decisions when broad consumers, route/package/contract surfaces, infrastructure roles, generic shared risk, or weak evidence make a move harmful.
 
-When the user asks to proceed, pick the smallest high-confidence slice. Before editing, state:
+This step is complete only when every proposed move has a reason and verification path.
 
-- files to move;
-- imports/exports/tests/docs to update;
-- expected verification commands;
-- rollback risk.
+### 5. Implement one slice when asked
 
-Then move files with normal filesystem tools, update imports with project tooling where available, and run:
+Before editing, state files to move, imports/exports/tests/docs to update, expected verification, and rollback risk. Then move the smallest high-confidence slice and run:
 
 ```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
 scip-query incomplete-migration
 scip-query recent-duplicates
 scip-query co-change <moved-file-or-config>
-scip-query diff-gate --json
 ```
 
-Also run the repo's normal tests or typecheck for the affected workspace. If the migration adds or changes `.scipquery.json` locality settings, run:
+Also run project tests or typecheck for the affected workspace. If `.scipquery.json` locality changed, run:
 
 ```bash
 scip-query config-validate
 scip-query locality-candidates --json --full
 ```
 
-## Output Rules
-
-- Lead with findings and judgments, not command transcripts.
-- Every proposed boundary needs evidence from at least two independent signals or a clear note that it is only a candidate.
-- Every proposed move needs a verification path.
-- For messy repos, output "discovery mode" and decision questions instead of a fake complete architecture.
-- For implementation, never batch unrelated folder moves just because they fit the same target structure.
+Then invoke `scip-verify`. The implementation is complete only when imports, tests, locality signals, and verification are checked.