scip-query 0.18.0 → 0.19.0

package/docs/DETECTOR_GUIDE.md

@@ -73,15 +73,16 @@ gaps:
 
 | Command | Watches the gap between | Evidence |
 |---|---|---|
-| `drift` | a file and its **siblings/architecture** | reference graph: unused imports, layer violations, "no sibling imports this" deviations |
+| `drift` | a file and its **siblings/declared architecture** | reference graph: unused imports, project-owned forbidden boundary edges, "no sibling imports this" deviations |
 | `doc-drift` | **docs** and the code they describe | doc file-citations + doc↔code co-change history; flags broken references and staleness scores |
 | `co-change` | two **files** with an invisible contract | git history: pairs that change together with no dependency edge |
 
 How to keep them straight: `drift` is structural and intra-code, `doc-drift`
 is prose-vs-code, `co-change` is code-vs-code where the connection exists only
 in commit history. The diff gate includes doc/code and hidden-coupling coverage
-through the `doc-reference` and `co-change-partner` checks; run `drift`
-directly when you need directory-pattern or layer-policy analysis.
+through the `doc-reference` and `co-change-partner` checks; run `drift
+--architecture` when you need direct dependency-rule findings beside boundary
+coverage, reciprocity, and connected-group signals.
 
 <!-- BEGIN GENERATED DIFF-GATE CHECKS -->
 | Check | What it catches | When it runs |
@@ -91,6 +92,7 @@ directly when you need directory-pattern or layer-policy analysis.
 | `co-change-partner` | Historically coupled files that usually change together but are missing from this diff. | Default diff gate. |
 | `twin-partner` | A changed symbol has a same-(near-)name twin (identical or already-divergent) elsewhere that this diff left untouched. | Default diff gate. Advisory: findings print but never cause a nonzero exit by themselves. |
 | `coverage-contract` | A configured `coverageContracts` entry (.scipquery.json) drifted: its declared key set no longer matches its ground-truth source. | Default diff gate, only when either side of a configured contract changed. |
+| `architecture` | A declared architecture boundary rule has a violation absent from the committed health baseline. | Default diff gate when closed dependency rows, requireCompletePolicy, or requireAcyclic are configured and a baseline exists. |
 | `doc-reference` | Docs that cite changed files and may need a matching update. Dated snapshot docs (docs.snapshotPaths) are excluded by policy. | Default diff gate. Advisory (21.2) for bare file-mention citations; blocking when the citation has a line anchor or the cited file was deleted/renamed. |
 | `unused-params` | Fresh trailing parameters or options that no changed body uses. | Default diff gate. |
 | `new-dead` | Changed production symbols with zero indexed consumers. | Default diff gate. |

package/docs/analyzer-inventory.md

@@ -20,7 +20,7 @@ The action tiers are:
 
 ## Current Surfaces
 
-The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`; that health path also carries the full-vs-bounded semantic enrichment budget used by semantic-capable detectors. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; the baseline policy helper remains private to the query tree and runs only for the explicit full health-baseline ratchet. The `tla` command is also ordered in that command registry as an on-demand formal-model verifier, not as a health-scored analyzer.
+The published query surface and private query-helper manifest live in `src/queries/public-query-entries.ts`. The CLI command order and families live in `src/runtime/commands/query-command-specs.ts`. The composite health score runs the phases listed in `HEALTH_PHASES` in `src/queries/health/health.ts`; that health path also carries the full-vs-bounded semantic enrichment budget used by semantic-capable detectors. The diff gate runs the default diff-scoped checks listed in `DIFF_GATE_CHECKS` in `src/queries/impact/diff-gate.ts`; its private baseline-policy helper supplies evidence for both the narrow default architecture ratchet and the opt-in full health-baseline ratchet. The `tla` command is also ordered in that command registry as an on-demand formal-model verifier, not as a health-scored analyzer.
 
 An earlier `health --json` run on this repository reported:
 
@@ -52,7 +52,7 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 | `wrapper-candidates`             | Small production callables with one real external caller, caller fan-in, and boundary-token evidence                                                                                                                                |                             Hygiene | Contextual signal, sometimes direct                                                                          | Single-caller wrappers can be needless indirection, but may also be names, domain/lifecycle boundaries, test seams, or API shaping. Boundary evidence discounts those without hiding them.                                                                                                                               |
 | `passthrough-candidates`         | Small production callables with exactly one callee, literal pass-through body, runtime-boundary evidence, public-facade evidence, action tier, recommendation, and score count                                                      | Hygiene, with `scoreCount` discount | Direct when no boundary or public-facade evidence is present; contextual signal when either exists           | Body-shape gate is real. Boundary evidence distinguishes adapter, provider, public, capability, transport, lifecycle, access-policy, and facade-shaped forwarders; public-facade evidence separately identifies package-public or rooted exported passthroughs.                                                          |
 | `stale-abstractions`             | Type-like definitions, real consumers, barrel consumers, transitive reachability, definer usage, confidence, staleness kind, action tier, and recommendation                                                                        |                             Hygiene | Direct for unused abstractions; contextual signal for one-consumer ownership rows                            | `0 consumers` is direct repair. `1 consumer` is contextual, including high-confidence misplaced types, because the repair may be move, inline, keep, or document as public contract.                                                                                                                                     |
-| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, explicit or inferred layer policy, sibling patterns, action tier, policy basis, recommendation                                                                      |                             Hygiene | Split by kind                                                                                                | `unused-import` is direct repair. Explicit `layer-violation` is direct; inferred layer policy and `pattern-deviation` rows are contextual signal. Pattern deviations remain excluded from health scoring.                                                                                                                |
+| `drift`                          | File dep graph, symbol ref graph, semantic/source import usage, project-owned architecture report, sibling patterns, action tier, policy basis, recommendation                                                                      |                             Hygiene | Split by kind                                                                                                | `unused-import` and grouped `architecture-violation` rows are direct repair. `pattern-deviation` rows are contextual signals and remain excluded from health scoring. Undeclared boundary edges, reciprocity, and connected groups appear only in architecture context.                                                   |
 | `complexity-hotspots`            | Production callable LOC, fan-in, fan-out, callee count                                                                                                                                                                              |                                Risk | Direct repair pressure                                                                                       | Complexity pressure usually means refactor, but the current score is structural, not cyclomatic. It should be separate from branch-count complexity.                                                                                                                                                                     |
 | `co-change` / hidden coupling    | Git co-change pairs, dependency edges, declared couplings, file noise filters, partner-class labels, declared-coupling suggestions, commit scope, recency context, commit-subject context, and score-weighted count                 |  Risk, weighted by history strength | Contextual signal                                                                                            | Strong evidence that coordination may be missing, but not proof that extraction or unification is correct. Partner classes, history context, subject context, and score weighting now separate contract-like focused current pairs from broad, stale, or unlabeled history before suggesting declared coupling.          |
 | Suppression inventory            | `scip-query: ignore-*` comments in source, plus structured `.scipquery.json` suppressions                                                                                                                                           |               Evidence quality axis | Meta signal                                                                                                  | Useful precision feedback. High suppressions should reduce trust or weight for that detector family. Structured file-scoped suppressions now validate path freshness.                                                                                                                                                    |
@@ -94,6 +94,7 @@ The declared-coupling config has been refreshed after the inventory surfaced old
 | `hotspots`           | Most referenced symbols                                                                                                            | Support/contextual signal | Identifies choke points. Not a smell alone.                                                                                                                         |
 | `fan-in` / `fan-out` | Reference counts into symbols or out of files                                                                                      | Support analysis          | Raw graph metrics.                                                                                                                                                  |
 | `coupling`           | Shared symbols between two files or top coupled pairs, coupling kind, action tier, evidence reasons, recommendation                | Contextual signal         | May reveal boundary problems, but shared symbols can be intended. Output now makes the coordination-pressure interpretation explicit.                               |
+| `architecture`       | Project-owned boundary paths and dependency rules applied to resolved import and re-export edges, with mapping coverage, policy-row coverage, edge breadth, reciprocity, and SCCs | Split by evidence         | Forbidden edges, required-but-missing policy rows, and cycles under `requireAcyclic` are direct policy findings. Unmapped files, reciprocity, and advisory cycles remain report-only signals.                       |
 | `deep-chains`        | Longest dependency chains after SCC condensation, suffix de-duplication, chain kind, action tier, evidence reasons, recommendation | Contextual signal         | Long chains imply propagation risk, but action depends on layers and ownership. Strict suffix duplicates are now removed from top results.                          |
 | `complexity`         | Branch count, cyclomatic estimate, callee count, fan-in, fan-out for one symbol                                                    | Direct repair pressure    | This is closer to the user-specified "cyclomatic complexity" analyzer than `complexity-hotspots`. Should score strongly when branches/cyclomatic exceed thresholds. |
 | `self-audit`         | Cheap evidence paths checked against TypeScript compiler oracle                                                                    | Meta analysis             | Measures analyzer accuracy. Should guide trust/weight, not code health directly.                                                                                    |
@@ -128,8 +129,8 @@ The remaining conceptual overlap is mostly healthy, but needs product labels:
 | Similarity and reuse       | `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, React/Vue duplicates, `recent-duplicates`, `echo` | Distinct evidence bases. The risk is UX confusion, not implementation duplication.                              | Keep separate, but expose basis, action tier, and root-cause groups where pairwise rows repeat.                                                         |
 | Extraction pressure        | `extract-candidates`, React/Vue behavior candidates, large component/view pressure, `incomplete-migration`                           | Different stages: discover seam, detect duplicated behavior, detect excessive size, catch unfinished migration. | Score unfinished migrations higher than discovery leads.                                                                                                |
 | Indirection                | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`                                                                 | Related but not the same: single caller, literal forwarding, low-consumer types.                                | Passthrough and wrapper rows now split by boundary evidence; stale should split by confidence.                                                          |
-| Architecture/history drift | `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Co-change should remain signal; doc-reference is direct only for behavioral cited claims and support for configuration examples or intentional records. |
-| Graph risk                 | `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`                              | Mostly layered views of graph pressure.                                                                         | Treat as support/context, except `cycles` and high cyclomatic complexity.                                                                               |
+| Architecture/history drift | `architecture`, `drift`, `doc-drift`, `co-change`, `co-change-partner`, `doc-reference`                                              | Same broad problem of things moving out of sync, but sources differ.                                            | Explicit architecture rules are direct; co-change remains signal; doc-reference strength depends on citation kind.                                     |
+| Graph risk                 | `architecture`, `fan-in`, `fan-out`, `hotspots`, `bottlenecks`, `coupling`, `deep-chains`, `change-surface`, `affected`              | Mostly layered views of graph pressure.                                                                         | Treat inferred graph shape as support/context; declared forbidden edges and acyclicity violations are direct policy disagreements.                     |
 
 ## Score Model Implications
 
@@ -146,8 +147,8 @@ Recommended model:
 
 Suggested initial tier map:
 
-- Direct: `cleanup-plan`, `dead-code`, `isolated`, `real cycles`, `unused-params`, `new-dead`, `incomplete-migration`, behavioral/current `doc-reference` claims, broken `doc-drift` references, `redundant-reexports` with zero consumers, direct passthrough rows with no boundary or public-facade role, `unused-import` drift, high branch/cyclomatic `complexity`, large React/Vue pressure.
-- Signal: `co-change`, `co-change-partner`, ordinary `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `passthrough-candidates` with boundary or public-facade roles, single-consumer `stale-abstractions`, React/Vue duplicate or behavior candidates, bottlenecks, hotspots, coupling, deep chains, inferred layer or pattern drift, doc staleness from churn.
+- Direct: `cleanup-plan`, `dead-code`, `isolated`, `real cycles`, `unused-params`, `new-dead`, `incomplete-migration`, behavioral/current `doc-reference` claims, broken `doc-drift` references, `redundant-reexports` with zero consumers, direct passthrough rows with no boundary or public-facade role, `unused-import` drift, declared `architecture-violation` drift, high branch/cyclomatic `complexity`, large React/Vue pressure.
+- Signal: `co-change`, `co-change-partner`, ordinary `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `convergence`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `passthrough-candidates` with boundary or public-facade roles, single-consumer `stale-abstractions`, React/Vue duplicate or behavior candidates, bottlenecks, hotspots, coupling, deep chains, undeclared/reciprocal/connected architecture context, pattern drift, doc staleness from churn.
 - Support: navigation commands, `affected`, `change-surface`, `plan-context`, `stats`, `self-audit`, suppression inventory, baseline comparison mechanics, configuration-example and intentional-record `doc-reference` rows.
 
 ## Directory Locality Analyzer
@@ -262,3 +263,12 @@ semantic parity slice. Health still owns the composite phase inventory and
 score model, and it now threads semantic enrichment through the health budget:
 full/default health enables semantic facts, while bounded large-index health
 can explicitly disable them.
+
+## 2026-07-23 Architecture Coherence Follow-Up
+
+The public query manifest and command-order references remain canonical after
+the graph family gained `architecture`. The command applies project-owned
+boundary paths and dependency rows to import-only file edges, retaining edge
+breadth and representative files. It is report-only in this slice: inferred
+reciprocity and strongly connected groups do not affect health or diff-gate,
+and an unconfigured repository receives no implicit source-layer policy.

package/docs/analyzer-validation-ledger.md

@@ -72,7 +72,7 @@ The canonical source is `src/runtime/commands/query-command-specs.ts:11-78`, whe
 - Direct cleanup and deletion analyzers: `dead`, `isolated`, `unused-imports`, `cleanup-plan`, `unused-params`, `passthrough-candidates`, `redundant-reexports`
 - Similarity, reuse, extraction, and locality analyzers: `similar`, `similar-files`, `similar-chains`, `similar-signatures`, `recent-duplicates`, `duplicate-bodies`, `twin-drift`, `twin-ab`, `extract-candidates`, `locality-candidates`, `wrapper-candidates`, `stale-abstractions`, `doc-drift`, `drift`, `convergence`
 - Frontend analyzers: `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure`, `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure`
-- Graph, risk, and complexity analyzers: `hotspots`, `fan-in`, `fan-out`, `coupling`, `cycles`, `bottlenecks`, `deep-chains`, `complexity-hotspots`, `complexity`
+- Graph, risk, and complexity analyzers: `architecture`, `hotspots`, `fan-in`, `fan-out`, `coupling`, `cycles`, `bottlenecks`, `deep-chains`, `complexity-hotspots`, `complexity`
 - Diff, impact, and planning analyzers: `affected`, `change-surface`, `co-change`, `diff-gate`, `incomplete-migration`, `plan-context`
 - Formal model verification: `tla`
 - Meta and action commands: `self-audit`, `cleanup-apply`
@@ -364,3 +364,14 @@ repository-dead candidates, while `file-internal`, other detector families,
 Rust, Python, and the aggregate health score retain independent status. The
 full evidence is in
 `docs/validation/2026-07-10-typescript-dead-certification.md`.
+
+## 2026-07-23 Architecture Coherence Follow-Up
+
+`src/runtime/commands/query-command-specs.ts` remains the canonical public
+query order after adding `architecture` to the graph family. The enforcement
+follow-up replaced drift's repository-specific policy with project-owned
+configuration and added stable boundary-pair identities to the shared health
+baseline. The default diff gate now blocks only new configured forbidden edges
+or explicitly forbidden cycles; accepted existing identities remain ratcheted.
+Reciprocal pairs, unmapped files, undeclared edges, and undeclared cycles remain
+contextual signals until external calibration.

package/docs/architecture-coherence-vision.md

@@ -0,0 +1,219 @@
+# Architecture Coherence Vision
+
+## Purpose
+
+scip-query should help a maintainer answer two different questions:
+
+1. What architecture does this codebase actually have?
+2. Where does the implementation contradict the architecture the project intends to preserve?
+
+The dependency graph can answer neither question alone. It records which files rely on which other files. Architectural judgment connects those facts to the real responsibilities, public contracts, runtime boundaries, and maintenance work that gave the code its structure.
+
+The product vision is therefore a combination of:
+
+- an `architecture` query that measures declared boundaries and dependency rules;
+- a directory-architecture skill that helps an agent discover, name, test, and gradually enforce those rules;
+- drift and health integrations that expose architectural changes without pretending every unusual import is a defect.
+
+## Vocabulary
+
+An architectural boundary is a named group of code with one stable reason to change, such as a domain model, rendering subsystem, persistence adapter, compiler frontend, or deployable service. A folder often represents a boundary, but a folder is only evidence of one: the decisive fact is the responsibility its files jointly serve.
+
+A dependency edge is a directed relationship from code that relies on something to the code it relies on. For an import, `A -> B` means file A imports file B. The direction matters because changes to B can force changes in A.
+
+A boundary edge is the same relationship after file edges are grouped by their architectural boundaries. Ten imports from UI files into domain files form one `ui -> domain` boundary edge with ten pieces of file-level evidence.
+
+An allowed edge is a boundary dependency that agrees with a declared rule. A forbidden edge is an actual dependency that contradicts a declared rule about which responsibilities may rely on which others. Files being far apart or living under different directories does not by itself make the edge forbidden.
+
+A reciprocal dependency is a pair of boundary edges in both directions, such as `source -> parser` and `parser -> source`. It is a review signal because neither boundary can change independently, but it can be intentional when the named boundaries are really one subsystem or meet through a deliberately shared contract.
+
+A strongly connected component is a group of boundaries where every member can reach every other member through dependency edges. Its essential consequence is mutual change pressure: no member is directionally independent of the group. A component with many boundaries is evidence that the current names may not describe real separation.
+
+A cycle-break candidate is a boundary edge inside a dependency cycle whose small amount of file-level evidence makes it a plausible place to inspect first. It is not automatically the correct edge to remove; a single import can expose either an accidental shortcut or a legitimate contract that the boundary model failed to name.
+
+An architecture policy is the project-owned configuration that names boundaries and records dependency directions the maintainers are prepared to defend. Its rules are stronger than inferred folder conventions because the project explicitly chose them.
+
+An architecture ratchet is an enforcement rule that permits recorded existing debt while preventing new violations. It lets a large codebase improve incrementally without requiring a speculative rewrite before the policy becomes useful.
+
+Architectural coherence is the degree to which actual dependencies, named responsibilities, and declared dependency rules describe the same system. The tool should report the evidence needed to improve that alignment, not reduce coherence to a single score.
+
+## Why `drift` Is Not Enough
+
+Drift is movement away from a reference state or established pattern. A system can be statically incoherent without having changed recently, and it can change while remaining coherent. Therefore architecture needs a first-class report rather than being hidden inside `drift`.
+
+`scip-query architecture` owns the complete boundary graph and policy
+evaluation. `scip-query drift --architecture` reuses that report to show
+direct declared violations together with mapping coverage and report-only
+signals; it does not maintain a second policy engine.
+
+Before this work, the source-layer table in
+`src/queries/cleanup/drift-policy.ts` embedded repository-specific knowledge in
+a general-purpose command. An unrelated repository using folders such as
+`src/core` and `src/runtime` could therefore inherit scip-query's rules. That
+table has now been removed: drift consumes only explicit project
+configuration, and an unconfigured repository receives no architecture
+violations.
+
+## Configuration Model
+
+The first configuration shape should be small enough to understand without learning a policy language:
+
+```json
+{
+  "architecture": {
+    "boundaries": [
+      { "name": "domain", "paths": ["src/domain/**"] },
+      { "name": "source", "paths": ["src/source/**"] },
+      { "name": "runtime", "paths": ["src/runtime/**"] }
+    ],
+    "allowedDependencies": {
+      "domain": [],
+      "source": ["domain"],
+      "runtime": ["domain", "source"]
+    },
+    "requireCompletePolicy": true,
+    "requireAcyclic": true
+  }
+}
+```
+
+A boundary row names code; it does not yet prohibit anything. An `allowedDependencies` row is closed: when a row exists for `source`, every cross-boundary dependency not listed in that row is forbidden. A missing row means the project has not made a rule for that boundary yet. Same-boundary dependencies remain allowed.
+
+This distinction lets a large repository describe mature boundaries first while leaving emerging or disputed areas in discovery mode.
+
+`requireCompletePolicy` turns that gradual-discovery model into a finished
+contract: every configured boundary must have a closed row, including an empty
+row for a boundary that may depend on nothing. `requireAcyclic` independently
+forbids multi-boundary strongly connected components. A project should enable
+both only after the observed graph has been classified and repaired.
+
+## What the Analyzer Should Report
+
+The report should preserve both policy truth and graph evidence:
+
+- mapped, unmapped, and ambiguously mapped files;
+- boundary edges with importer count, imported-file count, total file-edge count, and representative file edges;
+- forbidden edges, grouped by boundary pair rather than emitted as a flood of individual imports;
+- reciprocal boundary pairs;
+- strongly connected boundary components;
+- the narrowest internal edges to inspect first for each component;
+- policy coverage: which boundaries have closed dependency rows and which remain descriptive only.
+- resolved `export ... from` dependencies as well as ordinary imports, so
+  published barrel and package surfaces are governed;
+
+The output tiers should remain explicit:
+
+- **Direct finding:** an actual edge contradicts a declared rule, or a declared acyclicity rule is violated.
+- **Signal:** reciprocity, a large connected component, low policy coverage, an unmapped file, or a narrow cycle-break candidate.
+
+Inferred signals should not reduce health scores or block diffs until external calibration shows that acting on them reliably improves real codebases.
+
+## Applying This to an Existing Large Codebase
+
+The tool cannot discover the “best architecture” by optimizing graph shape. The best available architecture is the clearest model that preserves the system's real responsibilities and necessary behavior while reducing accidental change pressure. Finding it requires a staged investigation.
+
+### 1. Inventory the system's referents
+
+Read the repository guidance, package manifests, deployable entry points, routes, public exports, databases, message boundaries, tests, and build graph. Use scip-query to map consumers, dependencies, change surfaces, cycles, locality candidates, and historical co-change.
+
+This identifies what the code actually does and which units already behave as maintenance units.
+
+### 2. Name candidate boundaries
+
+Do not assume every top-level directory is a layer. A layer is a responsibility ordered by dependency direction, such as presentation over application over domain. A subsystem is a responsibility that owns an end-to-end capability, such as authentication or a compiler. A package is a publication or build unit. A service is an independently running unit.
+
+The architecture model may contain all four. The useful name is the one that predicts why its code changes and what it may depend on.
+
+### 3. Classify boundary maturity
+
+- A mature boundary is repeatedly expressed by code, documentation, tests, entry points, ownership, or history.
+- An emerging boundary has a coherent responsibility but inconsistent placement or dependencies.
+- An accidental boundary is mainly a convenience bucket, legacy pile, generated directory, or recent edit cluster.
+
+Only mature boundaries should receive closed dependency rules initially.
+
+### 4. Build a descriptive model first
+
+Add boundary path patterns without `allowedDependencies` rows. Run `scip-query architecture --json` to inspect mapping coverage, actual boundary edges, reciprocal pairs, and connected components.
+
+Revise names and path membership when the graph reveals that a supposed boundary has no independent responsibility or that one responsibility is split across several folders.
+
+### 5. Declare the rules supported by evidence
+
+For each mature boundary, state which other boundaries it is allowed to depend on and why. Record uncertain edges as unresolved decisions instead of silently allowing the entire current graph.
+
+Run the report again. A forbidden edge is now a testable disagreement between implementation and policy, not the tool's opinion about directory distance.
+
+### 6. Baseline and ratchet
+
+Record reviewed existing violations with `scip-query health
+--write-baseline`. Architecture identities name a forbidden boundary pair or
+an explicitly forbidden boundary cycle, so moving a representative file does
+not churn the ratchet. The default `scip-query diff-gate` architecture check
+then rejects new identities while preserving visibility into recorded debt.
+This turns architecture from a one-time diagram into a maintained contract.
+
+### 7. Migrate narrow seams
+
+Start with a narrow edge whose few file dependencies cross a mature rule. Determine whether the right repair is to move code, invert a dependency, extract a genuinely shared contract, combine falsely separated boundaries, or revise the policy.
+
+Verify each slice with tests, typechecking, incomplete-migration checks, architecture analysis, and diff-gate before taking the next one.
+
+## Example: Vega 2.0
+
+For a codebase the size of Vega 2.0, the first pass should not invent a universal stack of layers. It should:
+
+1. identify workspace packages, applications, servers, public entry points, data stores, and major feature or compiler/rendering subsystems;
+2. map actual dependency traffic between those units;
+3. read the architecture and ownership claims already present in docs and package surfaces;
+4. classify candidate boundaries as mature, emerging, or accidental;
+5. configure the mature boundaries descriptively;
+6. inspect reciprocal pairs and large connected components with their file-edge breadth;
+7. close dependency rows only where the intended direction is supported;
+8. baseline existing violations and prevent new ones;
+9. migrate one narrow, high-confidence seam at a time.
+
+The initial result may be a mixture of layers and subsystems. That is preferable to forcing a neat diagram that contradicts the software. The model becomes stronger as verified migrations and maintenance history provide new facts.
+
+## Delivery Sequence
+
+### Slice 1: explicit measurement — implemented
+
+- Add architecture configuration types and validation.
+- Extract the reusable strongly-connected-component algorithm already embedded in `deep-chains`.
+- Add a pure architecture graph analyzer and `scip-query architecture`.
+- Extend the directory-architecture skill with the discover, declare, measure, and ratchet workflow.
+- Keep architecture outside health scoring and diff-gate blocking.
+
+### Slice 2: replace implicit drift policy — implemented
+
+- Move scip-query's source-boundary rules into its `.scipquery.json`.
+- Make drift consume architecture findings instead of repository-specific hardcoded folder rules.
+- Add `drift --architecture` as a summary view.
+- Preserve unused-import drift and keep sibling-pattern deviation opt-in.
+
+### Slice 3: baselines and enforcement — implemented locally; external calibration remains
+
+- Give architecture findings stable identities.
+- Add report-only health visibility.
+- Add a narrow default diff-gate ratchet for newly introduced declared violations, backed by the shared health baseline.
+- Calibrate on scip-query, Vega 2.0, Stable Management, and structurally different external repositories before any score deduction.
+
+### Slice 4: discovery assistance
+
+- Add candidate-boundary evidence that combines paths, entry points, public surfaces, dependency neighborhoods, and co-change history.
+- Have the skill produce a reviewable architecture draft, never silently write closed rules.
+- Measure whether suggested boundaries and repairs survive maintainer review and reduce future cross-boundary churn.
+
+## Success Criteria
+
+The architecture feature is effective when:
+
+- an unconfigured repository never inherits scip-query-specific rules;
+- a configured forbidden edge is reported with concrete import evidence;
+- broad and narrow boundary edges are distinguishable;
+- large cycles are summarized without flooding the user;
+- the agent can explain why each proposed boundary exists in the running system;
+- existing debt can be ratcheted without a rewrite;
+- acting on a recommendation improves ownership or dependency direction in externally reviewed codebases;
+- the tool is willing to say “the policy is incomplete” instead of manufacturing certainty.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scip-query",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Evidence and verification for AI coding agents: map code, reuse concepts, finish migrations, and gate diffs.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,6 +33,10 @@
       "import": "./dist/queries/affected.js",
       "types": "./dist/queries/affected.d.ts"
     },
+    "./queries/architecture": {
+      "import": "./dist/queries/architecture.js",
+      "types": "./dist/queries/architecture.d.ts"
+    },
     "./queries/bottlenecks": {
       "import": "./dist/queries/bottlenecks.js",
       "types": "./dist/queries/bottlenecks.d.ts"

package/skills/_shared/SKILL.md

@@ -110,7 +110,7 @@ scip-query cleanup-apply # Apply a compiler-verified cleanup-plan batch to the w
 scip-query recent-duplicates # Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code
 scip-query doc-drift [doc] # Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped
 scip-query unused-params # Speculative-generality candidates: trailing parameters no body ever uses (TS/JS)
-scip-query drift [module] # Detect heuristic drift candidates: unused imports and layer violations by default; pass --patterns for pattern deviations too
+scip-query drift [module] # Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context
 scip-query wrapper-candidates # Find heuristic wrapper candidates only called by one consumer (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings)
 scip-query passthrough-candidates # Find heuristic passthrough candidates that forward to one callee
 scip-query stale-abstractions # Find heuristic stale abstraction candidates with 0-1 consumers (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings)
@@ -134,6 +134,7 @@ scip-query fan-in [symbol] # Count files referencing an exact symbol; top JSON r
 scip-query fan-out [file] # How many external symbols a file uses (or top fan-out across codebase)
 scip-query coupling [file1] [file2] # Coupling between two files, or top coupled pairs in codebase
 scip-query cycles # Detect circular dependency chains between files
+scip-query architecture # Evaluate project-owned architectural boundaries and dependency rules
 scip-query bottlenecks # Find coupling hubs: high fan-in AND high fan-out
 scip-query deep-chains # Find the longest condensed dependency-component chains
 scip-query call-graph <symbol> # Show incoming callers and outgoing callees for a symbol
@@ -145,7 +146,7 @@ scip-query call-graph <symbol> # Show incoming callers and outgoing callees for
 scip-query affected <symbol> # Transitive closure of symbols that could break if this symbol changes
 scip-query change-surface <file> # Pre-change briefing: exports, consumers, and blast-radius risk
 scip-query co-change [file] # Files that change together in git history without a dependency edge — hidden coupling candidates
-scip-query diff-gate # 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
+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
 scip-query incomplete-migration # Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain
 scip-query diff-impact # Compute changed symbols and downstream consumers from current git diff
 ```
@@ -211,7 +212,7 @@ measured precision, not by volume:
 
 ## Diff Gate Checks
 
-`diff-gate` runs nine checks (`--skip <check>` accepts any of these): `echo` (recent-duplicate-style echoes in the diff), `incomplete-migration`, `co-change-partner` (missing historically-paired file), `twin-partner` (advisory — unedited same-name twin), `coverage-contract` (a configured `coverageContracts` enumeration drifted from its ground truth — see `scip-setup`), `doc-reference` (uncited or stale doc claim), `unused-params`, `new-dead` (dead code introduced by this diff), and `baseline` (only with `--baseline`: compares against the committed `.scipquery-baseline.json`, distinct from `health --baseline`). Findings print grouped under a `Root-cause groups (N):` header before the flat list — a group's remediation usually clears every finding under it, and the same remediation may then repeat in the flat list below; that repetition is expected, not a separate issue. `--baseline` findings additionally carry an `actionTier`: `direct` (act on this finding alone), `signal` (corroborating evidence — read before acting), `support` (context only).
+`diff-gate` recognizes ten checks (`--skip <check>` accepts any of these): `echo` (recent-duplicate-style echoes in the diff), `incomplete-migration`, `co-change-partner` (missing historically-paired file), `twin-partner` (advisory — unedited same-name twin), `coverage-contract` (a configured `coverageContracts` enumeration drifted from its ground truth — see `scip-setup`), `architecture` (a declared boundary violation absent from the shared baseline), `doc-reference` (uncited or stale doc claim), `unused-params`, `new-dead` (dead code introduced by this diff), and `baseline` (only with `--baseline`: compares all non-architecture health identities against the committed `.scipquery-baseline.json`, distinct from `health --baseline`). The architecture check runs by default only when enforceable architecture rules and a baseline exist; it uses that same file without running the full health suite. Findings print grouped under a `Root-cause groups (N):` header before the flat list — a group's remediation usually clears every finding under it, and the same remediation may then repeat in the flat list below; that repetition is expected, not a separate issue. Baseline-backed findings additionally carry an `actionTier`: `direct` (act on this finding alone), `signal` (corroborating evidence — read before acting), `support` (context only).
 
 ## Postchecks
 

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-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-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 -->