scip-query 0.10.11 → 0.11.0

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.

package/skills/scip-doc-reconcile/SKILL.md

@@ -1,100 +1,89 @@
 ---
 name: scip-doc-reconcile
-description: Reconcile standards docs and living documentation with the current code using scip-query doc-drift evidence. Updates descriptive claims, repairs broken file references, and escalates normative violations instead of silently blessing them. Ends with staleness driven to zero.
+description: Reconcile living docs with current code using scip-query doc-drift. Use for stale standards, broken file references, docs that cite moved code, agent guidance, or normative contradictions between documentation and implementation.
+commands:
+  - template: "scip-query doc-drift --json --full"
+    when: "Build the worklist: every stale-doc candidate, ranked."
+  - template: "scip-query doc-drift <doc>"
+    when: "Reconcile one doc: staleness detail for a single target."
+  - template: "scip-query outline <subject-file>"
+    when: "Reconcile one doc: current shape of the code the doc describes."
+  - template: "scip-query trace <symbol>"
+    when: "Reconcile one doc: verify a symbol the doc mentions still exists as described."
+  - template: "scip-query code <symbol>"
+    when: "Reconcile one doc: re-derive a snippet from current source."
 ---
 
-# Doc Reconciliation with scip-query
+# scip-doc-reconcile
 
-Standards docs exist so agents implement consistently. When the code moves and
-the doc doesn't, every agent that reads it implements against a dead spec.
-This skill reconciles docs with reality — using evidence, not memory.
+Use this skill to make living documentation true again. A living doc is documentation agents or maintainers use to make present-day changes, such as AGENTS.md, CLAUDE.md, standards, command docs, or workflow docs.
 
-## The One Rule That Matters
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 
-A doc contains two kinds of statements, and they drift differently:
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
 
-- **Descriptive** ("the horses workflow lives in `workflows/horses.ts` and
-  exposes `listHorses`") — when code moved on, **update the doc**.
-- **Normative** ("all routes MUST validate stable scope before querying") —
-  when code violates it, **do NOT rewrite the standard to bless the
-  violation**. Either fix the code to comply, or record the contradiction in
-  the report for a human decision. Silently weakening a standard to match
-  drifted code is worse than the drift.
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Build the worklist: every stale-doc candidate, ranked. |
+| `scip-query doc-drift <doc>` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Reconcile one doc: staleness detail for a single target. |
+| `scip-query outline <subject-file>` | Tree view of symbols in a file, with line ranges | Reconcile one doc: current shape of the code the doc describes. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Reconcile one doc: verify a symbol the doc mentions still exists as described. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reconcile one doc: re-derive a snippet from current source. |
 
-When unsure which kind a statement is: MUST/SHOULD/NEVER language is
-normative; file paths, symbol names, and behavior descriptions are
-descriptive.
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rule
+
+Separate statement types:
+
+- Descriptive claims say what the code currently does or where it lives. Update them when code moves.
+- Normative claims say what code must or should do. If code violates them, fix the code or escalate the contradiction; do not weaken the standard silently.
+
+This distinction is the core of doc reconciliation.
 
 ## Workflow
 
-### 1. Build the evidence-backed worklist
+### 1. Build the worklist
 
 ```bash
-scip-query status --capabilities
-# If freshness is stale, missing, or unknown:
-# scip-query reindex
-scip-query doc-drift                      # all living docs, ranked by staleness
-scip-query doc-drift agent-os/standards   # scoped to a standards tree
+scip-query doc-drift --json --full
+scip-query doc-drift <doc-or-tree>
 ```
 
-Triage order:
-1. Docs with `BROKEN REFERENCE` lines (the spec cites deleted code — actively wrong)
-2. Highest staleness score
-3. Docs agents read most (AGENTS.md, CLAUDE.md, standards indexes)
+Prioritize broken references, highest staleness, then docs agents read most. Do not reconcile archival records such as dated plans, ADRs, or reports — list them in `.scipquery.json` `docs.snapshotPaths` so `doc-drift` excludes them with a labeled exclusion instead of resurfacing them every sweep.
 
-Track each doc as a task. Archival docs (dated plans, ADRs, reports) are
-excluded automatically — do not "reconcile" records of past decisions.
+This step is complete only when each target doc is selected for a current-use reason.
 
-### 2. Reconcile one doc at a time
+### 2. Reconcile one doc
 
-For each doc, gather what actually changed:
+For each doc:
 
 ```bash
-scip-query doc-drift <doc>                            # its subjects + changes since
-git log --oneline -15 -- <subject-file>               # WHY the subject changed
-scip-query outline <subject-file>                     # what it looks like NOW
-scip-query system <module>                            # current module shape
-scip-query trace <symbol-the-doc-mentions>            # does it still exist? who uses it?
+scip-query doc-drift <doc>
+scip-query outline <subject-file>
+scip-query system <module>
+scip-query trace <symbol-the-doc-mentions>
+scip-query code <symbol>
 ```
 
-Then edit the doc:
+Use Git history only to understand why a subject changed, not as a substitute for current code evidence.
+
+Fix broken references by finding the current code or deleting the obsolete claim. Rewrite stale descriptive claims from current source evidence. Re-derive snippets from `scip-query code`. Record normative contradictions instead of changing standards to bless drifted code.
 
-- **Broken references**: find where the code went (`scip-query files <stem>`,
-  `git log --follow`) and update the citation — or delete the claim if the
-  capability is gone.
-- **Stale descriptive claims**: re-read the subject files and rewrite the
-  claims to match current behavior. Every concrete claim you write must be
-  something you verified with a scip-query command this session — no claims
-  from memory.
-- **Examples and snippets**: re-derive them from current code
-  (`scip-query code <symbol>`), don't patch them by eye.
-- **Normative violations found while reading**: add them to the report under
-  "Standard vs code contradictions" with file:line evidence. Do not edit the
-  normative text.
+This step is complete only when every edited claim is supported by evidence from this session.
 
-### 3. Verify, per doc and overall
+### 3. Verify
 
 ```bash
-scip-query doc-drift <doc>     # staleness must drop to 0, broken refs to none
-scip-query diff-gate --json    # your own doc edits gate clean before commit
+scip-query doc-drift <doc>
 ```
 
-A doc still showing staleness after your edit means a subject changed in
-ways you haven't reflected — go back.
+Invoke `scip-verify` when the documentation change is part of a codebase diff. The doc is complete only when staleness drops to zero or the remaining contradiction is explicitly reported.
 
 ### 4. Report
 
-- Per doc: staleness before → after, broken references fixed, claims updated.
-- **Standard vs code contradictions** (normative): each with the standard's
-  requirement, the violating file:line, and a recommendation (fix code /
-  amend standard) — explicitly awaiting a human call.
-- Docs recommended for deletion (describe removed capabilities entirely).
-
-## Hard Rules
+Report staleness before and after, broken references fixed, claims updated, normative contradictions, and docs recommended for deletion.
 
-1. Every updated claim cites the scip-query command that verified it (in the
-   commit message or PR description).
-2. Never weaken normative language to match drifted code.
-3. Never reconcile archival docs (plans, ADRs, reports) — they are records.
-4. One commit per doc (or tight group) so review is per-standard.
-5. Re-run `scip-query doc-drift` at the end; the summary line is the result.
+Do not claim reconciliation is done until `doc-drift` has been rerun.