docs(layering): kill criteria on every rule module

Adds a four-line Catches/Evidence/Cost/Kill-criterion header to every
layering rule module for R2, R4-R7, R9-R14, R16, R18, R19, R65-R73,
and the rule-id uniqueness gate, so each structural check states what
it catches, why no other gate sees it, its LOC cost, and the concrete
condition under which it gets deleted. No behavior change.

Author: thymikee

scripts/layering/application-lifecycle-policy.ts

@@ -1,3 +1,14 @@
+// Catches: application-lifecycle state (the platform-runtime-gateway/application-resources/
+//   IME-activation trio) mutated from outside its declared owner file — an app-boot or IME
+//   readiness race that only shows up as an intermittent device-facing flake, because the type
+//   system sees a legal write to a legal field regardless of which module made it.
+// Evidence: d8a7d03faf (#1759) routed application lifecycle through runtime facts, the migration
+//   this ownership check protects; 7b48531d3b (#2081) retired the cutover scaffolding around it.
+// Cost: 201 LOC (119 rule + 82 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that the
+//   gateway/application-resources/IME-activation trio having one writer no longer matters.
+//   The trio are plain mutable fields, so an outside write type-checks.
+
 import { parseSync } from 'oxc-parser';
 import { memberName, visitAst } from './layering-ast.ts';
 import type { LayeringViolation } from './model.ts';

scripts/layering/bin-alias-fast-path.ts

@@ -1,3 +1,16 @@
+// Catches: bin.ts's --help fast path re-declaring its own alias table instead of calling the
+//   real registry — the exact silent-drift bug #1618-adjacent produced, where tap/launch/
+//   relaunch fell out of a hand-written table and paid a full CLI bootstrap for static help
+//   text. bin.ts runs unconditionally on import, so no unit test can import and exercise it
+//   directly; only reading its source text structurally can catch a regression.
+// Evidence: d85072d935 (#1641) routed command aliases through the help fast path; 74a70f1764
+//   (#2046) removed next-major compatibility surfaces bin.ts once carried alongside it.
+// Cost: 650 LOC (339 rule + 311 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that bin.ts's --help
+//   fast path no longer needs to delegate to the real alias registry — moot once the fast path
+//   is deleted or its resolution is inlined into commands/cli-command-aliases.ts, leaving no
+//   second call site.
+//
 // R12 bin-alias-fast-path.
 //
 // `bin.ts`'s `--help` fast path resolves a command alias (`tap`, `launch`, …) to its canonical

scripts/layering/check.ts

@@ -156,6 +156,20 @@ function checkLayeringRules(edges: readonly ResolvedImportEdge[]): LayeringViola
   return violations;
 }
 
+/**
+ * Catches: a production import cycle — A imports B imports A at the value level — that a
+ *   file-by-file review cannot see because each edge looks locally fine; only walking the
+ *   whole graph exposes the loop. No other gate looks at cycles at all.
+ * Evidence: 3d70943550 (#984) introduced the import-direction DAG gate this cycle check
+ *   anchors; f19864e486 (#1410) added the dependency-graph report built on the same model.
+ * Cost: not attributed (folded into check.ts's whole-graph pass; no standalone module or
+ *   test file to size separately).
+ * Kill criterion: none enforced today; retire only by maintainer decision that an acyclic
+ *   value-import graph no longer matters. tsc rejects a cyclic `references` edge between
+ *   projects, but no tsconfig declares references today and the A4 spike found they are a
+ *   build-cache mechanism, not a boundary: value imports inside one project are never
+ *   cycle-checked, and a cross-package edge resolves through root node_modules with no error.
+ */
 function checkCycles(edges: readonly ResolvedImportEdge[]): LayeringViolation[] {
   return findValueImportCycles(edges).map((cycle) => ({
     rule: 'R4 value-import-cycle',
@@ -190,6 +204,19 @@ function checkRecordRuntimeOwnership(sources: ReadonlyMap<string, string>): Laye
   });
 }
 
+/**
+ * Catches: a value import that runs against the ranked target spine's declared order (a lower
+ *   zone importing a higher one) — the runtime-consequential half of what R6 also checks for
+ *   type-only edges; neither zone-policy.ts's table nor the cycle check names direction.
+ * Evidence: 3d70943550 (#984) introduced the ranked spine and its back-edge check; docs/
+ *   dependency-graph-findings.md tracks the count this rule ratchets.
+ * Cost: not attributed (folded into check.ts's whole-graph pass; no standalone module or
+ *   test file to size separately).
+ * Kill criterion: none enforced today; retire only by maintainer decision that the ranked spine's
+ *   import direction no longer matters. Splitting zones into packages would not replace it: the
+ *   A4 spike found an undeclared workspace package still resolves through root node_modules and
+ *   a relative tunnel into another package's src still compiles.
+ */
 function checkBackEdges(edges: readonly ResolvedImportEdge[]): LayeringViolation[] {
   const seen = new Set<string>();
   return edges.flatMap((edge) => {
@@ -208,6 +235,18 @@ function checkBackEdges(edges: readonly ResolvedImportEdge[]): LayeringViolation
   });
 }
 
+// Catches: a type-only import against the ranked spine's declared order — a design-level
+//   dependency (zone A is stated in terms of zone B) that R5 is blind to because it costs
+//   nothing at runtime, so nothing else flags "the type shape leaks the wrong direction."
+// Evidence: the R5-adjacent commits in check.ts's history introduced this ratchet; the 61-to-5
+//   reduction and the two remaining deliberate inversions are recorded below and in
+//   docs/dependency-graph-findings.md.
+// Cost: not attributed (folded into check.ts's whole-graph pass; no standalone module or test
+//   file to size separately).
+// Kill criterion: none enforced today; retire only by maintainer decision that type-only spine
+//   inversions no longer matter. Reaching zero remaining inversions does not retire it: at zero
+//   the ratchet is what keeps the count from regrowing, and tsc never rejects a type-only edge.
+//
 // R6 ratchet: type-only spine inversions, per zone pair. R5 cannot see these (a type-only import
 // is free at runtime), but "zone A is declared in terms of zone B" is still a boundary claim, and
 // ranking type edges surfaced 61 of them. Down to 5, and every one of the 5 is now a deliberate

scripts/layering/contracts-implementation-policy.ts

@@ -1,3 +1,17 @@
+// Catches: packages/contracts production source calling host, process, or timer mechanics
+//   directly — contracts owns vocabulary only, and a mechanic call there means an adapter's
+//   concern leaked into the shared-vocabulary package every zone imports, invisible to
+//   consumers because the call itself is fully typed and legal Node code.
+// Evidence: 8f98d23f14 (#1750) gave R18 its own number after an id collision; 057ab1c82d (#1746)
+//   fixed double-reporting in this same authority check.
+// Cost: 337 LOC (206 rule + 131 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that contracts owning
+//   vocabulary only no longer matters. package.json cannot replace it: node: built-ins are not
+//   dependencies and timer globals need no import. The A4 spike found `types: []` would break
+//   contracts' AbortSignal/URL/Buffer/process uses while every lib that supplies them also
+//   supplies setTimeout, and the file-level bans (interaction-outcome, snapshot-quality-warnings,
+//   network-traffic and ios-snapshot type-only statements, kernel-only imports) have no tsc form.
+
 import { parseSync } from 'oxc-parser';
 import type { LayeringViolation } from './model.ts';
 

scripts/layering/daemon-modularity.ts

@@ -45,6 +45,20 @@ const ENGINE_FILE_PREFIXES = [
   'packages/replay-test/src/',
 ] as const;
 
+/**
+ * Catches: the daemon modularity migration regressing quietly — a SessionState field losing
+ *   its owner, a logical module gaining a forbidden or internal import, or an external
+ *   daemon/types.ts importer count creeping up — any of which erodes the wave-by-wave
+ *   extraction #1478/#1478-P5 already paid for, and nothing enforces the wave order itself.
+ * Evidence: 2316fd32c5 (#1487) pinned the migration contracts this ratchet grew from;
+ *   6984a1e095 (#1852) fixed the R10 zone-listing message when the type-cycle ceiling trips.
+ * Cost: 937 LOC total for the file (323 rule + 614 test; shared with R9's checkTypeCycleBaseline
+ *   below, not attributed separately).
+ * Kill criterion: none enforced today; retire only by maintainer decision that the daemon
+ *   modularity baselines (SessionState field-owner counts, logical-module import policies and
+ *   facades, the external daemon/types.ts importer list, per-zone cycle ceilings) no longer
+ *   matter. Every one is a count or an import edge the compiler accepts either way.
+ */
 export function checkDaemonModularityRatchets(
   edges: readonly ResolvedImportEdge[],
   largestTypeCycleMembers: readonly string[],
@@ -143,6 +157,20 @@ function checkSessionStateBaseline(): LayeringViolation[] {
   return violations;
 }
 
+/**
+ * Catches: the largest type-only import cycle growing past its pinned size, or the baseline
+ *   shrinking without the ceiling being lowered to match — R4 keeps the value graph acyclic, so
+ *   these cycles cost nothing at runtime, but an ungoverned type cycle can grow without bound
+ *   while every individual edge still looks locally reasonable.
+ * Evidence: 6984a1e095 (#1852) fixed R10's zone listing when this ceiling trips, evidence the
+ *   check fires in practice; ef6ec2995b (#1825, #1781 A6) made the R9 shrink direction
+ *   mandatory rather than advisory.
+ * Cost: 937 LOC total for the file (323 rule + 614 test; shared with R10's ratchets above, not
+ *   attributed separately).
+ * Kill criterion: none enforced today; retire only by maintainer decision that a bounded
+ *   type-only cycle size no longer matters. tsc never rejects a type-only cycle, and emptying
+ *   LARGEST_TYPE_CYCLE_ZONE_CEILINGS pins the size at zero rather than retiring the check.
+ */
 function checkTypeCycleBaseline(members: readonly string[]): LayeringViolation[] {
   const violations: LayeringViolation[] = [];
   const baseline = DAEMON_MODULARITY_BASELINE.largestTypeCycle;

scripts/layering/daemon-platform-boundary.ts

@@ -3,6 +3,20 @@ import { parseSync } from 'oxc-parser';
 import { isProductionSourceFile } from './tracked-sources.ts';
 import type { LayeringViolation } from './model.ts';
 
+/**
+ * Catches: src/daemon importing a concrete platform package or the retired src/platforms path,
+ *   in any form — static, dynamic, or type-only — the terminal boundary the R11/R13 package
+ *   split exists to make possible; a daemon module that reaches around a platform's package
+ *   facade defeats the composition-root discipline R13 enforces on the other side.
+ * Evidence: c794c11d7e (#2072) closed the daemon platform boundary this rule pins; 1522126f1f
+ *   (#2212) kept close lifecycle behind the session facade rather than reopening the boundary.
+ * Cost: 694 LOC (402 rule + 292 test).
+ * Kill criterion: none enforced today; retire only by maintainer decision that src/daemon staying
+ *   free of concrete-platform imports no longer matters. A package boundary would not replace
+ *   it: @agent-device/platform-* resolves from src/daemon through root node_modules whether
+ *   declared or not (A4 spike), and the retired src/platforms path is a plain relative import.
+ */
+
 /**
  * R65 rejects every concrete-platform dependency from tracked production daemon sources.
  *

scripts/layering/ios-snapshot-engine-policy.ts

@@ -1,3 +1,16 @@
+// Catches: an iOS snapshot caller reaching the XCTest/Limrun/Appium runners directly instead of
+//   through the one converged engine.ts — the fragmentation #2222's "converge Limrun snapshots
+//   through engine" and #758's "bulk-snapshot DEPTH limit" both trace back to, where each
+//   backend's snapshot path could silently diverge from the others' presentation contract.
+// Evidence: a8ee397168 (#2213) added the snapshot engine conformance gates this policy
+//   enforces; 6c8c0508d9 (#2222) converged Limrun snapshots through the engine it protects.
+// Cost: 267 LOC (229 rule + 38 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that the engine.ts →
+//   runner-presentation.ts call topology (presentIosSnapshot and publishIosSnapshot each make
+//   their one delegating call; the runner file never folds, validates, or builds the
+//   presentation itself) no longer matters. An exports map cannot replace it: both files sit
+//   in one package and call each other by relative import, which no manifest restricts.
+
 import { parseSync } from 'oxc-parser';
 import type { LayeringViolation } from './model.ts';
 import { memberPath, visitAst } from './layering-ast.ts';

scripts/layering/package-boundaries.ts

@@ -1,3 +1,17 @@
+// Catches: a package reaching back into root src/, a root file tunnelling into packages/*/src
+//   with a relative path, an undeclared workspace import, or a subpath the exports map does not
+//   name — bypasses Node's own resolution error cannot see, because a relative route resolves
+//   fine even though it duplicates the module under its specifier form.
+// Evidence: 76453add71 (#1494, #1490 W0) established the workspace split this rule protects;
+//   83322a3f2f (#1574) pinned exact facade symbols for every workspace package.
+// Cost: 1239 LOC (363 rule + 876 test).
+// Kill criterion: none enforced today; retire only by maintainer decision that the workspace
+//   boundary no longer matters. `pnpm typecheck` already covers two branches for src/ and
+//   packages/ importers (NodeNext rejects a non-exported subpath with TS2307; composite rootDir
+//   rejects a package→root relative escape with TS6059), but the A4 spike found no compiler
+//   mechanism for an undeclared workspace:* dependency, a root→packages/*/src relative tunnel,
+//   or any scripts/ import: project references are a build-cache mechanism, not a boundary.
+//
 // R11 package-boundaries: the workspace rules of #1490, as data the gate walks.
 //
 // Package resolution already makes a deep `@agent-device/*` specifier a runtime

scripts/layering/platform-composition-policy.ts

@@ -1,3 +1,17 @@
+// Catches: src/platform-runtime.ts, the one canonical composition root, wiring a platform
+//   package's implementation eagerly instead of through the lazy provider-composition seam —
+//   a startup-cost regression (every platform's code loading on every process start) that only
+//   shows up as a perf number, not a type error.
+// Evidence: 03f0f408c2 (#2070) moved platform provider composition out of the daemon into this
+//   root; c7f42ccedc (#2117) moved the Android family behind package exports the composition
+//   file now targets.
+// Cost: 103 LOC (no dedicated test file; exercised through platform-package-policy.test.ts);
+//   shares rule id R13 with platform-package-policy.ts (1030 LOC) and
+//   platform-package-source-policy.ts (230 LOC).
+// Kill criterion: none enforced today; retire only by maintainer decision that lazy platform
+//   composition in src/platform-runtime.ts no longer matters. The build cannot tell an eager
+//   import from the lazy seam; both resolve and type-check identically.
+
 import { parseSync } from 'oxc-parser';
 import { parseImports, type LayeringViolation } from './model.ts';
 

scripts/layering/platform-package-policy.ts

@@ -1,3 +1,19 @@
+// Catches: a platform package's private implementation loaded before the one canonical
+//   composition root assembles it, or a cross-boundary edge into another platform family's
+//   private surface — the six platform packages moved behind package facades (#2116-#2125)
+//   specifically to make eager loading and cross-family reach-ins visible, and only a source
+//   walk over every package's imports can confirm the boundary actually held.
+// Evidence: 838ed223b5 (#2116) moved the six W6 platform families behind package facades;
+//   ed26b31c94 (#2125) contracted the Apple platform surface to match.
+// Cost: 1030 LOC (377 rule + 653 test); shared with platform-composition-policy.ts (103 LOC)
+//   and platform-package-source-policy.ts (230 LOC), which this module orchestrates.
+// Kill criterion: none enforced today; retire only by maintainer decision that platform-family
+//   isolation (private manifests with exact exports, static imports only from the composition
+//   root, no sibling-family reach-ins, no top-level loadInventory/loadRuntime) no longer
+//   matters. Publishing the families separately would not replace it: the A4 spike found an
+//   undeclared workspace package still resolves through root node_modules and a relative tunnel
+//   into a sibling's src still compiles; project references are a build cache, not a boundary.
+
 import path from 'node:path';
 import { PLATFORMS } from '@agent-device/kernel/device';
 import { parseImports, type LayeringViolation } from './model.ts';