scip-query 0.17.2 → 0.19.0

package/skills/scip-concrete-plan/SKILL.md

@@ -1,22 +1,24 @@
 ---
 name: scip-concrete-plan
-description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require source citations, reuse audit, test seams, side-effect boundaries, contracts, and verification.
+description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require contextual definitions, cited premises, reuse audit, test seams, counterexample attacks, and a derived verdict.
 commands:
   - template: "scip-query status --capabilities"
     when: "Discover: confirm the index is fresh before citing graph facts."
   - template: "scip-query plan-context <target>"
     when: "Discover: anchor the plan with pre-edit context for the target."
   - template: "scip-query refs <symbol>"
-    when: "Reuse audit: find existing consumers before proposing a new unit."
+    when: "Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers."
+  - template: "scip-query dataflow <symbol-or-variable>"
+    when: "Premises: producers and consumers backing a state-authority premise."
   - template: "scip-query code <symbol>"
-    when: "Reuse audit: read source before citing a behavior claim."
+    when: "Premises: read source before citing a behavior claim."
   - template: "scip-query trace <symbol>"
     when: "Verify the plan: rerun source-producing context for cited targets."
 ---
 
 # Concrete Plan
 
-Use this skill to write an implementation plan that another agent can execute without guessing. A concrete plan is a dated Markdown checklist whose code claims come from scip-query evidence and whose design makes the intended behavior easy to test before it is easy to ship.
+Use this skill to write an implementation plan that another agent can execute without guessing and a reviewer can check without re-deriving. A concrete plan is a certificate: a dated Markdown document whose conclusion — ready to implement — is derived from numbered, source-cited premises, defended against constructed counterexamples, and shaped so the intended behavior is easy to test before it is easy to ship.
 
 Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
 
@@ -27,8 +29,9 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you
 | --- | --- | --- |
 | `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
 | `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
-| `scip-query refs <symbol>` | Find all files referencing a symbol | Reuse audit: find existing consumers before proposing a new unit. |
-| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reuse audit: read source before citing a behavior claim. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Premises: enumerate every writer and reader of a touched state surface; reuse audit: find existing consumers. |
+| `scip-query dataflow <symbol-or-variable>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | Premises: producers and consumers backing a state-authority premise. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Premises: read source before citing a behavior claim. |
 | `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
@@ -39,9 +42,14 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
 2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
 3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
-4. Every code step includes a `Source` field naming the scip-query command that produced the path, line range, and behavior claim.
-5. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
-6. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+4. Define every load-bearing concept contextually and state every invariant in `iff` or `must always` form. A definition without referents (a `Source:` line) is a guess.
+5. Evidence lives in numbered premises (`P1`, `P2`, ...), each with a `Source` naming the scip-query command that produced it. Every shared-state surface the plan touches gets a state-authority premise enumerating its complete writer and reader sets.
+6. Steps and defenses cite the premises they depend on. A claim no premise supports is either new evidence to gather or an explicit `ASSUMPTION` — never silent.
+7. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+8. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
+9. Attack entries must be constructed scenarios — actor, starting state, sequence — and each ends in a recorded outcome: `HELD` citing the defending step and premises, or `HOLE` with its repair step or accepted reason. An assertion of absence ("no new shared mutable state") is not a defense; it cannot fail, so it cannot catch anything.
+10. Installing an enforcer — trigger, constraint, guard, gate — opens an enforcement window: every existing writer in the relevant state-authority premise must be brought into compliance in the same or an earlier step, or the window recorded as an accepted hole. Every step declares `Deployable`.
+11. The verdict is derived, not asserted: `PLANNED-COMPLETE` only when the coverage matrix has no blank rows and every attack ends in `HELD` with citations or an accepted hole. An attack record where nothing ever broke is a red flag — attacks run against a draft should find holes; if none did, rerun the pass as falsification, preferably in a fresh subagent context.
 
 ## Planning Terms
 
@@ -53,6 +61,16 @@ A side-effect boundary is the edge where deterministic program decisions meet fi
 
 A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
 
+An invariant is a property of the changed system that must hold at every observable moment; what makes it load-bearing is that attacks are judged against it and the final verdict is derived from whether it survives them all.
+
+A premise is a numbered, source-cited statement of fact about the current code; what makes it a premise rather than a note is that steps and defenses cite it by ID, so a false premise is traceable to everything built on it.
+
+A state-authority premise is a premise that enumerates the complete writer and reader sets of one shared state surface; what makes it powerful is that "complete" is falsifiable with `refs` and `dataflow`, turning a forgotten write path from an unknowable into a checkable omission.
+
+A counterexample attack is a concrete actor, starting state, and action sequence constructed to violate an invariant; what makes it evidence is that its defense cites premises and steps, so "we considered failure" becomes "this specific failure is blocked here."
+
+An enforcement window is the interval between the step that installs an invariant enforcer and the step that brings the last existing writer into compliance; what makes it dangerous is that during it, every unupdated writer fails the new check in production, so the plan that adds safety is itself the outage.
+
 ## Workflow
 
 ### 1. Discover
@@ -64,22 +82,50 @@ scip-query status --capabilities
 scip-query plan-context <target>
 ```
 
-Use the shared reference for follow-up commands. Fill three gates before designing:
+Use the shared reference for follow-up commands. Fill four gates before designing:
 
 ```markdown
 ## Goal
 What the user is trying to accomplish and what done looks like for them.
 
+## Definitions & Invariants
+For each load-bearing concept: its wider class, then the one trait that causally
+explains its other traits in this codebase — with the referents. Then the
+invariants the change must preserve, in iff / must-always form.
+
 ## Current State
-The affected end-to-end flow, with scip-query citations for entry points, callers, data flow, dependencies, downstream impact, and non-obvious invariants.
+A short narrative of the affected end-to-end flow. Every factual sentence
+cites a premise by ID.
 
 ## Reuse Audit
-For every new symbol or file being considered: reuse target, extension target, or evidence-backed reason new code is justified.
+For every new symbol or file being considered: reuse target, extension target,
+or evidence-backed reason new code is justified.
 ```
 
-This step is complete only when the plan can explain the current flow, its consumers, and every proposed new unit's reuse decision with citations.
+Definition discipline: place the concept in its wider class, then name the essential trait — the one that makes the concept's other traits in this codebase possible and explains them. Do not label genus or differentia; write it as prose. Ban circular and synonym definitions ("the refresh coordinator coordinates refreshes" defines nothing). Any new term the plan introduces gets defined the same way. Good definitions condense: they imply the concept's other traits instead of listing them, and derived requirements fall out of them — if restore is defined as the inverse of cancel, then the privilege to restore must not be weaker than the privilege to cancel, and a plan that gates them asymmetrically must defend that asymmetry.
+
+This step is complete only when the concepts are defined with referents, the invariants are stated formally, and every proposed new unit has a reuse decision with citations.
+
+### 2. Establish Premises
 
-### 2. Shape for Tests
+Number every fact the plan depends on:
+
+```markdown
+## Premises
+
+- P1. <current behavior fact> — Source: `scip-query code <symbol>`
+- P2. Writers of `<state surface>`: <complete list>. Readers: <complete list>.
+  — Source: `scip-query refs <symbol>` + `scip-query dataflow <symbol>`
+- P3. ASSUMPTION: <belief the evidence cannot yet confirm, and what would confirm it>
+```
+
+State-authority rule: for every state surface the plan touches — database column, store field, event topic, endpoint, cache entry — write one premise enumerating its complete writer and reader sets. Completeness comes from `refs` and `dataflow`, not memory.
+
+Why this premise class exists: a sprint-restore plan hardened `restore()` and the cancellation path but never enumerated the writers of sprint status. Review found `PATCH /sprints/:id` could set `status: 'active'` around every restore invariant, and transition automations wrote `sprintId` straight past the new membership guard — two of that review's five ship-blockers, both sitting in the writer list one `refs` call would have produced. With a state-authority premise, each writer in the list must be visited by an attack; without it, the side doors are invisible until review.
+
+This step is complete only when every state surface named in any phase has a state-authority premise and every remaining unknown is an explicit `ASSUMPTION`.
+
+### 3. Shape for Tests
 
 Before writing implementation phases, add:
 
@@ -101,7 +147,7 @@ Plan the code so tests can call the pure core directly and exercise the side-eff
 
 This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
 
-### 3. Design the Checklist
+### 4. Design the Checklist
 
 Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
 
@@ -109,7 +155,8 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
 ### N.M - Imperative title
 
 - [ ] **File**: `path/to/file.ts:LINE-LINE`
-- **Source**: `scip-query <command>`
+- **Premises**: P<n>, P<m>
+- **Deployable**: yes | no — <reason> | part of single-deploy group <name>
 - **What**: Current behavior verified from source.
 - **Change**: Exact edit to make.
 - **Testability**:
@@ -119,41 +166,59 @@ Write phases in execution order. Keep each phase deployable or explicitly mark w
   - Side-effect shell:
   - Contract:
 - **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
-- **Why**: Why this step is needed and why this order is safe.
+- **Why**: Why this step is needed and why this order is safe, citing the premises it rests on.
 ```
 
-This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, and validation.
+If a step installs an enforcer — trigger, constraint, guard, gate — check its enforcement window here: every existing writer in the relevant state-authority premise is brought into compliance in the same or an earlier step, or the window is carried into the attack record as a hole to accept or repair.
+
+This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, cited premises, a deployability declaration, and validation.
 
-### 4. Stress-Test
+### 5. Attack the Plan
 
-Apply these lenses to every phase. Add or change steps until each answer is concrete:
+Construct counterexamples against every invariant. This pass is falsification, not defense: it succeeds by finding holes, and against a draft it should find some. Prefer delegating it to a fresh subagent when the environment can spawn one — give the adversary only the Definitions & Invariants, Premises, state-authority maps, and the checklist, not your design rationale, and brief it that it wins by producing holes; fold its findings back as HOLE entries and repair steps. Solo fallback: enumerate the full attack list from the coverage-matrix rows below before writing any Outcome line, so attacks cannot be shaped around defenses you already have.
 
-| Lens | Plan must answer |
+Use the lenses as attack prompts — purpose, blast radius, valid intermediate state, reversibility, failure, concurrency, boundaries, data integrity, observability, human experience, efficiency, reuse, testability — and record each attack in this form:
+
+```markdown
+### A<n>. <invariant> via <lens>
+- Attack: <actor> + <starting state> + <action sequence>
+- Outcome: HELD — defended by step <N.M> (P<i>, P<j>)
+  | HOLE — repaired by new step <N.M>
+  | HOLE — accepted: <reason>
+```
+
+A `HELD` that cannot name its defending step and premises is not `HELD`; it is a hole wearing confidence. A repaired hole keeps its `HOLE — repaired by step N.M` label permanently — do not rewrite it to `HELD` after the repair, because the repair history is the evidence that the pass falsified. The verdict's repaired count must equal the number of `HOLE — repaired` entries in the record. Close the record with a coverage matrix — one row per writer in every state-authority premise and per applicable lens (valid intermediate state is always applicable when any step installs an enforcer or migration):
+
+```markdown
+| Surface or lens | Attacks |
 | --- | --- |
-| Purpose | Why does the current code exist, and what invariant must survive? |
-| Blast radius | Which direct and transitive consumers move with this change? |
-| Valid intermediate state | Would the project still work after only this phase? |
-| Reversibility | Is this a one-way or two-way door, and what rollback exists? |
-| Failure | What happens when I/O, external APIs, malformed data, retries, or crashes occur? |
-| Concurrency | What shared state can be touched twice or out of order? |
-| Boundaries | Who can call this entry point, and where is input validated? |
-| Data integrity | What existing data, generated artifacts, or persisted contracts are affected? |
-| Observability | Can a maintainer diagnose failures from logs/errors without rereading the source? |
-| Human experience | What would surprise, confuse, or block a real user? |
-| Reuse | Does existing code already solve this problem or most of it? |
-| Testability | Are dependencies injectable, logic pure where practical, concerns separated, and contracts small? |
-
-This step is complete only when every discovered gap has either a new plan step or a written reason it is accepted.
-
-### 5. Verify the Plan
+| <writer, reader, or lens> | A2, A7 |
+```
+
+A blank row is an unattacked writer. The record is incomplete until every row names an attack or carries an accepted reason. Spread attacks across rows before deepening one: depth on the axis you already anticipated does not protect the axes you did not — the leaks come from blank rows, not from the tenth variation of the race you already modeled.
+
+Invalid entry — this exact shape preceded three post-review remediation rounds on a real plan:
+
+> **Concurrency**: Validation happens before database writes; no new shared mutable state or retry behavior is introduced.
+
+It names no actor, no interleaving, and cites nothing. It is an assertion of absence: it cannot fail, so it caught nothing — review later found exactly the race it waved away. A valid entry for the same phase:
+
+> ### A3. "Every stored value is a member of its field's option set" via concurrency
+> - Attack: admin removes option O in transaction A while a user writes value O in transaction B; interleaving B-validates → A-commits → B-commits persists an orphaned value.
+> - Outcome: HOLE — repaired by new step 2.2: validation reads the option definition outside B's lock (P4), so serialize definition changes with every value writer via FOR UPDATE on the definition row; regression proves both interleavings against PostgreSQL.
+
+This step is complete only when the coverage matrix has no blank rows and every attack entry ends in a cited `HELD` or a recorded `HOLE`.
+
+### 6. Verify the Plan and Derive the Verdict
 
 Run or delegate phase-by-phase reference checks. Each verifier confirms:
 
 - every path exists;
 - every line range is still within about five lines;
+- every premise reproduces when its `Source` command is rerun — a premise that no longer reproduces is false, and everything citing it is suspect until fixed;
 - every behavior claim matches source;
 - every new unit has reuse evidence;
-- every behavior-changing step has a validation command and testability design.
+- every behavior-changing step has cited premises, a validation command, and a testability design.
 
 Then rerun the source-producing context for the cited targets:
 
@@ -161,9 +226,22 @@ Then rerun the source-producing context for the cited targets:
 scip-query plan-context <target>
 ```
 
-Use the shared reference for subagent briefing text when delegating.
+Use the shared reference for subagent briefing text when delegating. Close the plan by applying the definitions to the record — do not summarize feelings:
+
+```markdown
+## Verdict
+
+A plan is PLANNED-COMPLETE iff the coverage matrix has no blank rows, every
+attack ends in HELD with cited steps and premises or an accepted hole with a
+written reason, and no premise failed reverification.
+
+Result: PLANNED-COMPLETE | INCOMPLETE — <n> attacks, <x> holes repaired,
+<y> holes accepted; <unresolved items>
+```
+
+The counts are part of the verdict. "16 attacks, 0 holes repaired" against a fresh draft is not a strong plan; it is an attack pass that defended instead of falsified — rerun it before shipping the plan.
 
-This step is complete only when stale references are fixed and every phase has a validation path.
+This step is complete only when stale references are fixed, every premise reverified, and the verdict line is derived from the attack record.
 
 ## Output Shape
 
@@ -171,11 +249,14 @@ The plan file contains:
 
 1. Title and date.
 2. Goal.
-3. Current State.
-4. Reuse Audit.
-5. Testability Design.
-6. Design Phases.
-7. Stress-Test Findings.
-8. Execution Order and deployable phase notes.
-9. Ship Order with one-way doors flagged.
-10. Summary of files to create, edit, delete, and verify.
+3. Definitions & Invariants.
+4. Premises (including state-authority premises and explicit assumptions).
+5. Current State (narrative citing premise IDs).
+6. Reuse Audit.
+7. Testability Design.
+8. Design Phases (steps citing premises, each with a deployability declaration).
+9. Attack Record (attacks with outcomes, holes repaired or accepted, coverage matrix).
+10. Execution Order and deployable phase notes.
+11. Ship Order with one-way doors flagged.
+12. Verdict with attack and hole counts.
+13. Summary of files to create, edit, delete, and verify.

package/skills/scip-conductor/SKILL.md

@@ -24,7 +24,7 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 | Command | Purpose | When |
 | --- | --- | --- |
 | `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Anchor each phase's step before delegating it. |
-| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Verify a handoff before accepting it and before closing the program. |
+| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Verify a handoff before accepting it and before closing the program. |
 | `scip-query health --json` | Composite codebase health report with prioritized action list | Pre-register or check a program-level health benchmark. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.

package/skills/scip-debug/SKILL.md

@@ -43,6 +43,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 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`.
+5. A root-cause claim whose fix crosses a file boundary requires a rival: state the next-most-plausible explanation for the same symptom and run the observation that separates them. A root cause with no rival considered is a guess with confidence.
 
 ## Workflow
 
@@ -82,6 +83,8 @@ scip-query slice <symbol-or-variable> --forward
 
 Stop expanding when the first code fact that can cause the symptom is found.
 
+When a candidate cause emerges, state it as a hypothesis alongside one rival — the next-most-plausible explanation for the same symptom. Name the observation that distinguishes them (a log line, a probe, a narrower test) and execute it. Choose the discriminator that is cheapest to run, not the one most likely to confirm.
+
 This step is complete only when the path explains the symptom or the missing evidence is explicit.
 
 ### 4. Compare nearby implementations
@@ -117,9 +120,11 @@ Run the reproduction, narrow test or smoke command, and invoke `scip-verify`.
 Bug:
 Entry point:
 Root cause:
+Rival considered:
+Discriminator: <the executed observation that separated them>
 Fix:
 Verification:
 Remaining risk:
 ```
 
-Do not present a guess as a root cause. If no root cause is proven, report the missing evidence.
+Do not present a guess as a root cause. A root cause with no rival considered and no executed discriminator is a guess. If no root cause is proven, report the missing evidence.

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

@@ -10,8 +10,16 @@ commands:
     when: "Inventory evidence: files with overlapping dependency profiles."
   - template: "scip-query cycles"
     when: "Inventory evidence: circular dependency chains between files."
+  - template: "scip-query architecture --json"
+    when: "Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles."
+  - template: "scip-query drift --architecture"
+    when: "Review direct drift findings together with boundary coverage and architecture signals."
   - template: "scip-query co-change --json --full"
     when: "Inventory evidence: hidden file-level coupling from git history."
+  - template: "scip-query health --write-baseline"
+    when: "Record reviewed existing debt before enabling architecture regression enforcement."
+  - template: "scip-query diff-gate"
+    when: "Verify that the current diff introduces no new declared architecture violation."
   - template: "scip-query config-validate --json"
     when: "Implement a slice: validate locality config after a move."
 ---
@@ -31,7 +39,11 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 | `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 architecture --json` | Evaluate project-owned architectural boundaries and dependency rules | Measure configured boundaries, actual dependency traffic, forbidden edges, reciprocal pairs, and boundary cycles. |
+| `scip-query drift --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | Review direct drift findings together with boundary coverage and architecture signals. |
 | `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 health --write-baseline` | Composite codebase health report with prioritized action list | Record reviewed existing debt before enabling architecture regression enforcement. |
+| `scip-query diff-gate` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Verify that the current diff introduces no new declared architecture violation. |
 | `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | Implement a slice: validate locality config after a move. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
@@ -41,6 +53,16 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 
 An ownership boundary is a folder, package, module, or convention that groups code around one stable responsibility.
 
+A dependency edge points from code that relies on something to the code it relies on. For imports, `A -> B` means A imports B.
+
+A forbidden edge is an actual cross-boundary dependency rejected by an explicit project rule. Directory distance or an unusual import does not make an edge forbidden by itself.
+
+A layer is a responsibility ordered by dependency direction, such as presentation depending on application. A subsystem is a responsibility that owns an end-to-end capability, such as authentication or rendering. A package is a publication or build unit. A service is an independently running unit. Do not force all four into one layer hierarchy.
+
+A reciprocal dependency is 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.
+
+An architecture ratchet is an enforcement rule that records existing violations while preventing new ones, allowing a large codebase to improve without a speculative rewrite.
+
 A target structure is a proposed future layout that expresses an ownership model, not merely a prettier tree.
 
 A migration slice is the smallest set of file moves and import updates that can be verified independently.
@@ -55,6 +77,8 @@ A slop codebase is a codebase whose files are arranged by accident, convenience,
 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.
+7. Configure descriptive boundaries before closing dependency rules.
+8. Treat graph shape as evidence about responsibilities, never as a substitute for identifying them.
 
 ## Workflow
 
@@ -77,6 +101,8 @@ scip-query change-surface <file>
 scip-query plan-context <file-or-symbol>
 scip-query locality-candidates --json --full
 scip-query cycles
+scip-query architecture --json
+scip-query drift --architecture
 scip-query co-change
 scip-query similar-files --min-similarity 0.6 --min-deps 3
 scip-query similar-chains --min-similarity 0.5
@@ -98,7 +124,66 @@ Classify each candidate:
 
 This step is complete only when mature, emerging, and accidental boundaries are separated.
 
-### 4. Propose structure or decisions
+### 4. Build a descriptive architecture model
+
+For a large existing codebase, identify real system units before calling them layers. Inventory:
+
+- workspace packages and public exports;
+- applications, services, and deployable entry points;
+- domain capabilities and end-to-end subsystems;
+- persistence, network, rendering, compiler, and other technical responsibilities;
+- tests, routes, contracts, and ownership or architecture documentation;
+- dependency and co-change evidence that shows which files already move as a unit.
+
+Add mature boundary path patterns to `.scipquery.json` without `allowedDependencies` rows first:
+
+```json
+{
+  "architecture": {
+    "boundaries": [
+      { "name": "domain", "paths": ["src/domain/**"] },
+      { "name": "runtime", "paths": ["src/runtime/**"] }
+    ]
+  }
+}
+```
+
+Then run:
+
+```bash
+scip-query config-validate --json
+scip-query architecture --json
+```
+
+Use unmapped and ambiguous files to repair boundary membership. Use actual boundary edges, reciprocal pairs, and strongly connected groups to test whether the names describe real separation.
+
+This step is complete only when every configured boundary has a stated responsibility and the mapping gaps are understood.
+
+### 5. Declare only supported dependency rules
+
+An `allowedDependencies` row is closed: an outgoing target omitted from a present row is forbidden. A missing row makes no dependency claim.
+
+```json
+{
+  "architecture": {
+    "boundaries": [
+      { "name": "domain", "paths": ["src/domain/**"] },
+      { "name": "runtime", "paths": ["src/runtime/**"] }
+    ],
+    "allowedDependencies": {
+      "domain": [],
+      "runtime": ["domain"]
+    },
+    "requireAcyclic": true
+  }
+}
+```
+
+For each closed 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 rows undeclared.
+
+This step is complete only when every forbidden edge is understood as either implementation debt, a false boundary, or a policy mistake.
+
+### 6. Propose structure or decisions
 
 Use this shape:
 
@@ -108,6 +193,10 @@ Use this shape:
 ## Scope
 ## Current Structure Map
 ## Boundary Maturity
+## Descriptive Architecture Model
+## Dependency Rules
+## Forbidden-Edge Ledger
+## Reciprocal and Cycle Review
 ## Target Structure
 ## Move Ledger
 ## Locality Config
@@ -120,7 +209,29 @@ List no-move decisions when broad consumers, route/package/contract surfaces, in
 
 This step is complete only when every proposed move has a reason and verification path.
 
-### 5. Implement one slice when asked
+### 7. Ratchet, then implement one slice when asked
+
+For a large repository with existing violations, review the direct findings and
+write the shared health baseline:
+
+```bash
+scip-query drift --architecture
+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 then compares only architecture identities; it
+does not run every health detector. `diff-gate --baseline` remains the opt-in
+full health ratchet and does not duplicate architecture findings.
+
+Commit `.scipquery-baseline.json` with `.scipquery.json`. A missing baseline
+causes the architecture gate to report that enforcement is not enabled; it
+does not silently treat the current graph as accepted.
+
+Prefer inspecting the least-broad edge inside a boundary cycle first, but
+determine whether the repair is a move, dependency inversion, named shared
+contract, boundary merge, or policy correction.
 
 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:
 
@@ -135,6 +246,9 @@ Also run project tests or typecheck for the affected workspace. If `.scipquery.j
 ```bash
 scip-query config-validate
 scip-query locality-candidates --json --full
+scip-query architecture --json
+scip-query drift --architecture
+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-explore/SKILL.md

@@ -44,6 +44,7 @@ Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only
 3. Read source with `scip-query code`; do not describe what a function probably does.
 4. Follow the graph before trusting folder structure.
 5. Start wide, then narrow.
+6. Descriptions need citations; conclusions need discriminators. A conclusion — why something happens, what a unit is for, which intent explains a shape — states one rival explanation and the trace evidence that rules it out.
 
 ## Workflow
 
@@ -117,4 +118,4 @@ This step is complete only when the explanation includes the risky symbols or st
 
 ## Report
 
-Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. Exploration is complete only when the user can see what was proven and what remains unverified.
+Report overview, entry points, call flow, data flow, dependencies, consumers, risk areas, and the command citations that prove each claim. For each conclusion-bearing claim, name the rival explanation considered and the evidence that ruled it out. Exploration is complete only when the user can see what was proven, what remains unverified, and which conclusions rest on a discriminator rather than a single story.

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

@@ -43,6 +43,12 @@ validates (checkers, gates, verifiers, validators — find producers with
 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: file it 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, 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 only when every checker in scope has been witnessed rejecting a
 constructed should-fail input, or is listed with a reason it cannot be.
 
@@ -121,6 +127,17 @@ 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:
+
+```markdown
+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.
+
 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 skill hunts in

package/skills/scip-maintainability/SKILL.md

@@ -12,8 +12,8 @@ commands:
     when: "Map evidence: exports, consumers, and blast-radius risk."
   - template: "scip-query affected <symbol>"
     when: "Map evidence: transitive consumers of a candidate symbol."
-  - template: "scip-query drift --patterns"
-    when: "Map evidence: layer violations and pattern deviations as probes (--patterns is off by default and near-zero precision; treat hits as leads, not findings)."
+  - template: "scip-query drift --patterns --architecture"
+    when: "Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings."
 ---
 
 # scip-maintainability
@@ -32,7 +32,7 @@ Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
 | `scip-query surface <scope>` | What symbols consumers actually use from this module | Map evidence: what consumers actually use from the scope. |
 | `scip-query change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | Map evidence: exports, consumers, and blast-radius risk. |
 | `scip-query affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | Map evidence: transitive consumers of a candidate symbol. |
-| `scip-query drift --patterns` | Detect heuristic drift candidates: unused imports and layer violations by default; pass --patterns for pattern deviations too | Map evidence: layer violations and pattern deviations as probes (--patterns is off by default and near-zero precision; treat hits as leads, not findings). |
+| `scip-query drift --patterns --architecture` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | Map evidence: declared architecture violations plus boundary and pattern signals; treat opt-in pattern hits as leads, not findings. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
@@ -53,6 +53,8 @@ Essential variation is difference that must remain because the real units differ
 
 System compression is replacing several mechanisms that perform the same role, policy, lifecycle, or surface job with fewer named mechanisms that preserve behavior.
 
+A unifying definition is the single essential trait that makes several code sites one concept; what makes it a test is that failing to state it proves the sites are not one concept, and consolidating them anyway would package-deal essential variation into a false abstraction.
+
 ## Rules
 
 1. Ground claims in files, symbols, references, call graphs, dependencies, surfaces, and blast radius.
@@ -61,6 +63,7 @@ System compression is replacing several mechanisms that perform the same role, p
 4. Preserve essential variation.
 5. Add an abstraction only when it removes hidden policy, names a lifecycle, enforces a rule, or reduces concept count.
 6. Prefer deletion, inlining, merging, generation, or enforcement before broad frameworks.
+7. A scattered-concept or consolidation claim ships its unifying definition. If no single essential trait covers every cited site, the variation is essential: record it and do not consolidate.
 
 ## Workflow
 
@@ -100,7 +103,7 @@ This step is complete only when concrete units, consumers, tests, fallbacks, ada
 
 For each cluster, ask:
 
-- What one concept appears in several places?
+- 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.
 - What policy is hidden?
 - What lifecycle is unnamed?
 - Which differences are essential?
@@ -144,6 +147,8 @@ For broad review, write a register under `docs/plans/` unless the user asks not
 
 Use dispositions: `merge`, `delete`, `inline`, `extract`, `generate`, `enforce`, `supersede`, `defer`, `skip`.
 
+Every `merge`, `extract`, or `generate` entry carries its unifying definition and its strongest dissenter — the cited site most likely to differ essentially — with the evidence that it does not. A dissenter that survives moves the entry to `skip` with reason `essential variation`; the dissenter stays in the register either way.
+
 This step is complete only when each opportunity has evidence, disposition, dependency order, touch map, and validation plan.
 
 ### 7. Implement and verify when asked