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: delete when the gateway/application-resources/IME-activation trio expose only
+//   typed transition methods (no exported mutable field), making an outside write a compile
+//   error instead of an AST finding.
+
 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,15 @@
+// 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: delete when bin.ts's --help fast path is deleted or its alias resolution is
+//   inlined into commands/cli-command-aliases.ts itself, leaving no second call site whose
+//   delegation needs checking.
+//
 // R12 bin-alias-fast-path.
 //
 // `bin.ts`'s `--help` fast path resolves a command alias (`tap`, `launch`, …) to its canonical

scripts/layering/check.ts

@@ -157,6 +157,18 @@ 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: delete when the build graph itself enforces acyclicity (e.g. project
+ *   references per zone reject a cyclic reference edge at tsc time) so a static walk here
+ *   is redundant with a compiler error.
+ */
 function checkCycles(edges: readonly ResolvedImportEdge[]): LayeringViolation[] {
   return findValueImportCycles(edges).map((cycle) => ({
     rule: 'R4 value-import-cycle',
@@ -191,6 +203,18 @@ 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: delete when the spine's zones become physically separate packages (R11's
+ *   package-boundaries model) so an inverted import fails to resolve rather than needing a
+ *   graph walk to catch.
+ */
 function checkBackEdges(edges: readonly ResolvedImportEdge[]): LayeringViolation[] {
   const seen = new Set<string>();
   return edges.flatMap((edge) => {
@@ -209,6 +233,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: delete when the two remaining inversions (commands/mcp -> client,
+//   commands -> daemon-server) are resolved by moving the projection registry or the route
+//   union to a lower zone, leaving the ratchet at zero with nothing left to hold down.
+//
 // 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,14 @@
+// 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: delete when packages/contracts has no runtime dependency on node: built-ins
+//   at all (checked by its own package.json having zero such dependencies), so a mechanic call
+//   fails module resolution instead of needing a source-text scan.
+
 import { parseSync } from 'oxc-parser';
 import type { LayeringViolation } from './model.ts';
 

scripts/layering/daemon-modularity.ts

@@ -45,6 +45,19 @@ 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: delete when architecture-ownership.ts's LOGICAL_MODULE_POLICIES list is empty
+ *   (every planned daemon module has landed) and SESSION_STATE_FIELD_OWNERS needs no baseline
+ *   floor because ownership is enforced structurally instead of by ratchet.
+ */
 export function checkDaemonModularityRatchets(
   edges: readonly ResolvedImportEdge[],
   largestTypeCycleMembers: readonly string[],
@@ -143,6 +156,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: delete when LARGEST_TYPE_CYCLE_ZONE_CEILINGS is empty — the provider-webdriver
+ *   co-defined-contract pair splits its shared type into a third module and no zone carries a
+ *   pinned type cycle any more.
+ */
 function checkTypeCycleBaseline(members: readonly string[]): LayeringViolation[] {
   const violations: LayeringViolation[] = [];
   const baseline = DAEMON_MODULARITY_BASELINE.largestTypeCycle;

scripts/layering/daemon-platform-boundary.ts

@@ -3,6 +3,19 @@ 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: delete when src/daemon has no filesystem adjacency to packages/platform-* at
+ *   all (a separate package boundary, per R11, makes a concrete-platform import a module-
+ *   resolution error instead of a source-text scan finding).
+ */
+
 /**
  * R65 rejects every concrete-platform dependency from tracked production daemon sources.
  *

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

@@ -1,3 +1,14 @@
+// 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: delete when engine.ts is the only exported symbol from
+//   packages/capture-kit/src/ios-snapshot-engine/ (runner-presentation.ts folded into it or made
+//   unexported), so a direct-runner call fails to resolve instead of needing an AST scan.
+
 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,14 @@
+// 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: delete when every workspace package enforces its own boundary at the
+//   TypeScript project-reference level (composite tsconfig references replacing the manual
+//   manifest/exports-map walk), so an undeclared or tunnelled import fails tsc directly.
+//
 // 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: delete when src/platform-runtime.ts's composition becomes generated from the
+//   platform package manifests rather than hand-wired, so eager loading is structurally
+//   impossible instead of merely checked for.
+
 import { parseSync } from 'oxc-parser';
 import { parseImports, type LayeringViolation } from './model.ts';
 

scripts/layering/platform-package-policy.ts

@@ -1,3 +1,16 @@
+// 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: delete when the platform families are separate npm-published packages with
+//   their own dependency graph (rather than workspace packages sharing one repo's build), so
+//   premature loading fails as a missing dependency instead of needing a structural check.
+
 import path from 'node:path';
 import { PLATFORMS } from '@agent-device/kernel/device';
 import { parseImports, type LayeringViolation } from './model.ts';