fix: align layering claims, remove app-log ineffective dynamic import, refresh architecture records (#1222) (#1227)

* fix: align layering claims, remove app-log ineffective dynamic import, refresh architecture records (#1222)

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: fix layering spine ordering (cli top), ADR 0009 deferred-scope wording, terse app-log-request-scope comment (#1222)

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: show full rank groups in layering spine diagrams; clarify back-edge order vs literal imports (#1222)

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: mark replay ADR context historical

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* docs: refresh replay repair and app-log boundary status

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: devin-ai-integration[bot]

CONTEXT.md

@@ -93,10 +93,19 @@ The perfect-shape refactor is complete and merged. Its end-state:
   `src/platforms/apple/os/<os>/`. The public wire stays non-breaking: `PUBLIC_PLATFORMS`
   (`src/kernel/device.ts`) still emits `ios`/`macos` leaf output. See
   [ADR 0009](docs/adr/0009-apple-platform-consolidation.md).
-- Folder DAG + layering lint. `kernel`/`remote`/`metro`/`client`/`snapshot`/`screenshot-diff`/
-  `replay`/`cli-parser`/`daemon-client`+`server`/`sdk` are arranged as an import-direction DAG
-  (imports point down toward the kernel sink), enforced in CI by `scripts/layering/check.ts`.
-  The gate rejects production value-import cycles and every ranked target-spine back-edge.
+- Folder DAG + layering lint. `scripts/layering/check.ts` enforces two different scopes in CI.
+  GLOBALLY, across every production source file, it enforces the R1-R3 move rules
+  (kernel-sink, commands-floor, platforms-seam) and rejects all production static value-import
+  cycles. Separately, it ranks an explicit target spine — as rank groups, lowest (kernel sink) to
+  highest, where `A ◄ B` means B may not be outranked by A (the back-edge order the gate rejects), NOT
+  that every displayed import exists:
+  `kernel ◄ { contracts, request, selectors, platforms } ◄ core ◄ { commands, cli-schema } ◄ { client, daemon-server } ◄ daemon-client ◄ cli` —
+  and rejects every back-edge within it. Root entrypoints and peripheral zones (`mcp`, `compat`,
+  `remote`, `metro`, `replay`, `recording`, `snapshot`, `screenshot-diff`, `cloud-webdriver`,
+  `sdk`, `utils`) are deliberately unranked (`UNRANKED_ZONES` in `scripts/layering/model.ts`):
+  they still obey R1-R4, but the gate asserts no total back-edge order over them. It is not a
+  claim that every folder is arranged in one DAG. `model.test.ts` guards that no new zone escapes
+  this classification silently.
 - Agent-cost. Responses carry a cost block and MCP `outputSchema`, rendered through a leveled
   `ResponseView`.
 

docs/adr/0009-apple-platform-consolidation.md

@@ -52,14 +52,18 @@ and snapshot fidelity is uneven (the deep-RN AX-server fallback is iOS-simulator
 
 This composes with ADR 0008 (the descriptor's capability facet) and ADR 0003.
 
-Implementation status as of 2026-06:
+Implementation status as of 2026-07:
 
-- Shipped: additive `appleOs` groundwork, the shared Apple engine under `src/platforms/apple/core`, macOS leaf
-  files under `src/platforms/apple/os/macos`, direct internal imports to the Apple modules, and visionOS
-  profile/build/discovery groundwork.
-- Deferred: the public `Platform` collapse from `ios`/`macos` to `apple`, a dedicated tvOS leaf, per-`AppleOS`
-  capability tables, and any watchOS unsupported sentinel. watchOS remains out of scope for the current
-  consolidation.
+- Shipped: additive `appleOs` groundwork; the shared Apple engine under `src/platforms/apple/core`; macOS
+  leaf files under `src/platforms/apple/os/macos`; a dedicated tvOS leaf under `src/platforms/apple/os/tvos`;
+  direct internal imports to the Apple modules; the per-`AppleOS` capability table
+  (`APPLE_OS_CAPABILITIES`, `src/platforms/apple/capabilities.ts`, parity-pinned against the pre-table
+  predicates); the watchOS **unsupported sentinel** (reserved in the `AppleOS` type and interactor-rejected —
+  XCUITest cannot drive watchOS UI — never produced by discovery); and visionOS profile/build/discovery
+  groundwork.
+- Deferred: the public `Platform` collapse from `ios`/`macos` to `apple` (the last, highest-diff step; the
+  public wire still emits `ios`/`macos` leaves via `PUBLIC_PLATFORMS`) and net-new visionOS spatial-input QA.
 
-This ADR owns the architectural decision; implementation progress for the remaining platform-plugin work is
-tracked in GitHub issues under the Phase 3 umbrella (#972).
+This ADR owns the architectural decision. The Phase 3 platform-plugin umbrella (#972) is closed; within
+this consolidation the public `Platform` collapse above is the last deferred step (net-new visionOS
+spatial-input QA is separate follow-up, outside the consolidation).

docs/adr/0012-interactive-replay.md

@@ -2,14 +2,20 @@
 
 ## Status
 
-Proposed (2026-07-10). Nothing in this ADR is implemented yet.
+Accepted (2026-07-10). Migration steps 1-6 and 8 have shipped; step 7 (benchmark extension) remains
+deferred. See [Migration progress](#migration-progress) for the per-step landing record.
 
-## Context
+## Context (historical baseline)
 
-Replay today is deterministic. `.ad` scripts are plain text — one action per line, `#` comments, a
-`context platform=... device=... theme=...` header (`src/replay/script.ts`) — recorded via
-`open --save-script` (`src/daemon/session-action-recorder.ts`, `src/daemon/session-script-writer.ts`)
-or hand-written, and executed step-by-step by `runReplayScriptFile`
+This section records the repository state audited on 2026-07-10, before the migration steps recorded
+below shipped. Its present-tense observations are historical evidence;
+[Migration progress](#migration-progress) is the authoritative record of current behavior.
+
+At acceptance, replay was deterministic. `.ad` scripts were plain text — one action per line, `#`
+comments, and a `context platform=... device=... theme=...` header (`src/replay/script.ts`) — recorded
+via `open --save-script` (`src/daemon/session-action-recorder.ts`,
+`src/daemon/session-script-writer.ts`) or hand-written, and executed step-by-step by
+`runReplayScriptFile`
 (`src/daemon/handlers/session-replay-runtime.ts`) under the daemon's `replay`/`test` commands
 (`src/daemon/handlers/session-replay.ts`). Recorded touch/fill/get targets are selector chains with
 `||` alternates (`buildSelectorChainForNode(...).join(' || ')`,
@@ -18,7 +24,7 @@ or hand-written, and executed step-by-step by `runReplayScriptFile`
 (`src/compat/maestro/`); progress is step-indexed (`stepIndex`/`stepTotal` in
 `emitReplayTestActionProgress`, `session-replay-runtime.ts:243-260`).
 
-Recovery is opt-in `--update`/`-u` healing (`replayUpdate` flag,
+Recovery was opt-in `--update`/`-u` healing (`replayUpdate` flag,
 `src/commands/cli-grammar/flag-definitions-workflow.ts`). It only fires after a step has already
 returned a hard failure (`session-replay-runtime.ts:118-149`: `if (!shouldUpdate) return failure; ...
 healReplayAction(...)`), and it only retries the SAME recorded selector material —
@@ -67,14 +73,14 @@ zero on the happy path and paying only where reality diverged from the recording
   ... then smallest on-screen area") but never disclosed per response — an agent that hasn't read the
   help topic, or whose target moved between recording and replay, gets no signal a heuristic rather than
   an exact match chose its target.
-- **(c) No target-binding verification exists anywhere in this path.** `--verify`
+- **(c) No target-binding verification existed in this path at acceptance.** `--verify`
   (`captureEvidenceBaseline`, `resolution.ts:45-58,104-134`; the `verifyEvidence` guarantee cell in ADR
   0011's registry) attaches a pre/post-action node diff so the caller can see SOMETHING changed — it
   says nothing about whether the CORRECT node was the one tapped. A wrong-but-plausible pick (the
   sibling "Prevent Remove" button) produces a real, visible diff and is still the wrong action.
-- **(d) Heal auditability is a bare count.** A successful `--update` run returns
+- **(d) Heal auditability was a bare count.** A successful `--update` run returned
   `{ replayed, healed, ... }` (`session-replay-runtime.ts:186-195`) — `healed` is a number, nothing
-  else — and rewrites the `.ad` file in place via `writeReplayScript`
+  else — and rewrote the `.ad` file in place via `writeReplayScript`
   (`session-replay-runtime.ts:182-184`, `src/replay/script.ts:459-484`) with no diff shown anywhere in
   the response.
 - **(e) This silent-pick default is in real tension with this repo's general posture toward ambiguity.**
@@ -774,3 +780,25 @@ each states its dependencies explicitly.
    boundary watermark on `replay` (R1/R6), the writer's post-watermark slice and bare-`@ref` fail-loud
    guard (R4/R6) — the healed-script emission otherwise reuses `close --save-script`'s existing
    `session.actions` serializer.
+
+## Migration progress
+
+Landing record for the plan above (main as of 2026-07-13). This section tracks progress only; it does
+not restate or amend the decisions.
+
+| Step | Decision | Status | Landed in |
+| --- | --- | --- | --- |
+| 1. Resolution disclosure | 2 | Shipped | #1193 |
+| 2. Structured divergence transport | 4 (report) | Shipped | #1197 |
+| 3. `.ad` target annotations, inert | 3 (parser/writer) | Shipped | #1196 |
+| 4. Target-binding verification | 3 (enforcement) | Shipped | #1209 |
+| 5. `replay --from` + `--plan-digest` resume | 4 (resume) | Shipped | #1211 |
+| 6. `--update` retirement | 1 | Shipped | #1211 |
+| 7. Benchmark extension | 5 | Deferred | — |
+| 8. Agent-supervised re-record repair | 6 | Shipped | #1228 |
+
+Step 4 (#1209) added the `selector-miss`/`identity-mismatch`/`identity-unverifiable` divergence kinds
+and a post-resolution target guard that cross-checks the dispatched winner against the verified member.
+Issue #1221 ("Complete ADR 0012 replay target-binding verification") was closed as already implemented:
+its verification scope is covered by step 4. Step 7 remains deferred. Step 8 implements the repair
+design accepted in #1226 and shipped in #1228.

docs/agents/contract-projection-output-economy-spike.md

@@ -20,7 +20,7 @@ Selected commands:
 
 These commands already have closed neutral results in `src/contracts/navigation.ts`, typed
 `CommandResultMap` entries, executable definitions, Node client methods, and MCP output schemas.
-They do not overlap the broad-return client methods being changed under #1183.
+They do not overlap the broad-return client methods narrowed under #1183 (since closed).
 
 The baseline has three independent command-to-surface declarations per selected command:
 

scripts/layering/check.ts

@@ -1,14 +1,21 @@
 // Import-direction lint — enforces the folder DAG established by the Phase-5
 // folder moves (see CONTEXT.md, "Architecture: folder DAG + layering lint").
 //
-// Target DAG (imports point DOWN, toward the kernel sink):
-//   kernel ◄ platforms ◄ core ◄ commands ◄ { cli, client, daemon/server }
-//   client ◄ daemon/client     remote, metro ◄ daemon/client
-//   sdk = re-export barrels only
+// Ranked target spine, as rank groups lowest (kernel sink) to highest. `A ◄ B` means B may not
+// be outranked by A (the back-edge order the gate rejects), NOT that every displayed import exists:
+//   kernel ◄ { contracts, request, selectors, platforms } ◄ core ◄ { commands, cli-schema }
+//         ◄ { client, daemon-server } ◄ daemon-client ◄ cli
+// (authoritative ranks: `TARGET_DAG_RANK` in model.ts)
 //
-// The target DAG is complete. This gate enforces the three move rules, rejects
-// all production value-import cycles, and rejects every ranked target-spine
-// back-edge.
+// This gate enforces three things, with two different scopes:
+//   - GLOBALLY, across every production source file: the R1-R3 move rules and
+//     rejection of all production static value-import cycles (R4).
+//   - Over the RANKED SPINE only: rejection of every spine back-edge (R5), i.e.
+//     an import whose source zone outranks its target zone.
+// Root and peripheral zones (see `UNRANKED_ZONES` in model.ts) are deliberately
+// NOT ranked: they still participate in R1-R4, but the gate makes no back-edge
+// claim about them. It is not a claim that every folder is arranged in one total
+// order — only the ranked spine is.
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -160,8 +167,9 @@ function checkBackEdges(edges: readonly ResolvedImportEdge[]): Violation[] {
 function report(files: readonly string[], violations: readonly Violation[]): number {
   if (violations.length === 0) {
     process.stdout.write(
-      `Layering guard: OK — ${files.length} source files satisfy R1-R3, contain no ` +
-        `value-import cycles, and contain no target-spine back-edges.\n`,
+      `Layering guard: OK — ${files.length} source files satisfy R1-R3 and contain no ` +
+        `value-import cycles (both checked globally); the ranked target spine contains no ` +
+        `back-edges (root/peripheral zones are intentionally unranked).\n`,
     );
     return 0;
   }

scripts/layering/model.test.ts

@@ -2,10 +2,15 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { listSourceFiles } from './check.ts';
 import {
+  RANKED_ZONES,
+  UNRANKED_ZONES,
+  classifyZone,
   collectBackEdges,
+  collectZones,
   findValueImportCycles,
   parseImports,
   resolveImportEdges,
+  unclassifiedZones,
 } from './model.ts';
 
 test('parseImports distinguishes value, type-only, dynamic, and value re-export edges', () => {
@@ -94,6 +99,40 @@ test('neutral ownership zones reject value imports into higher layers', () => {
   });
 });
 
+test('ranked and unranked zones are disjoint and both non-empty', () => {
+  assert.ok(RANKED_ZONES.size > 0);
+  assert.ok(UNRANKED_ZONES.size > 0);
+  const overlap = [...RANKED_ZONES].filter((zone) => UNRANKED_ZONES.has(zone));
+  assert.deepEqual(overlap, [], 'a zone cannot be both ranked and intentionally unranked');
+});
+
+test('classifyZone separates the ranked spine from intentionally-unranked zones', () => {
+  assert.equal(classifyZone('kernel'), 'ranked');
+  assert.equal(classifyZone('daemon-server'), 'ranked');
+  assert.equal(classifyZone('(root)'), 'unranked');
+  assert.equal(classifyZone('utils'), 'unranked');
+  assert.equal(classifyZone('mcp'), 'unranked');
+  // A zone that is neither ranked nor listed peripheral must be flagged, never
+  // silently treated as back-edge-free.
+  assert.equal(classifyZone('not-a-real-zone'), 'unclassified');
+});
+
+test('every production zone is deliberately classified as ranked or unranked', () => {
+  // Drift guard: a new src/<folder>/ (or a daemon-client/server split) forces a
+  // deliberate ranked-vs-peripheral decision here instead of silently escaping
+  // spine back-edge detection. If this fails, add the new zone to TARGET_DAG_RANK
+  // (ranked spine) or UNRANKED_ZONES (root/peripheral) in model.ts.
+  assert.deepEqual(unclassifiedZones(listSourceFiles()), []);
+
+  // The classification must also stay honest to the tree: every zone the model
+  // names is a real production zone, so the docs cannot list a spine or peripheral
+  // zone that no longer exists.
+  const presentZones = collectZones(listSourceFiles());
+  const namedZones = new Set([...RANKED_ZONES, ...UNRANKED_ZONES]);
+  const staleNamedZones = [...namedZones].filter((zone) => !presentZones.has(zone)).sort();
+  assert.deepEqual(staleNamedZones, []);
+});
+
 test('listSourceFiles includes root-level src/*.ts production files', () => {
   const files = new Set(listSourceFiles());
   for (const rootFile of ['src/cli.ts', 'src/command-catalog.ts', 'src/backend.ts']) {

scripts/layering/model.ts

@@ -16,6 +16,13 @@ export type ResolvedImportEdge = ImportEdge & {
 
 export type BackEdgeMap = Record<string, string[]>;
 
+// The ranked target spine. Back-edge detection is defined ONLY between two ranked
+// zones: an edge whose source outranks its target (lower number imports higher) is a
+// spine back-edge. Zones NOT in this map are intentionally unranked (see
+// `UNRANKED_ZONES`); the gate does not rank them, so ranking their edges would claim a
+// back-edge guarantee the code does not make. Every production zone must be either
+// ranked here or listed as unranked — `unclassifiedZones` and `model.test.ts` guard
+// that no zone is silently unclassified.
 const TARGET_DAG_RANK = new Map([
   ['kernel', 0],
   ['contracts', 1],
@@ -31,6 +38,40 @@ const TARGET_DAG_RANK = new Map([
   ['cli', 6],
 ]);
 
+export const RANKED_ZONES: ReadonlySet<string> = new Set(TARGET_DAG_RANK.keys());
+
+// Zones deliberately left OUT of the ranked spine. They are NOT unenforced: every file
+// in them is still subject to the global production value-import cycle rejection (R4)
+// and the R1-R3 move rules. They only opt out of spine back-edge ranking, for one of
+// two deliberate reasons:
+//   - root: `(root)` entrypoints (src/cli.ts, src/backend.ts, …) compose the spine from
+//     above rather than sitting inside it.
+//   - peripheral: satellite feature/adapter zones the spine does not depend on in a
+//     fixed rank order. Assigning them a rank would invent a back-edge direction the
+//     architecture does not commit to.
+export const UNRANKED_ZONES: ReadonlySet<string> = new Set([
+  '(root)',
+  'cloud-webdriver',
+  'compat',
+  'mcp',
+  'metro',
+  'recording',
+  'remote',
+  'replay',
+  'screenshot-diff',
+  'sdk',
+  'snapshot',
+  'utils',
+]);
+
+export type ZoneClassification = 'ranked' | 'unranked' | 'unclassified';
+
+export function classifyZone(zone: string): ZoneClassification {
+  if (RANKED_ZONES.has(zone)) return 'ranked';
+  if (UNRANKED_ZONES.has(zone)) return 'unranked';
+  return 'unclassified';
+}
+
 function scanDynamicImports(line: string, lineNo: number): ImportEdge[] {
   const edges: ImportEdge[] = [];
   const re = /import\s*\(\s*['"]([^'"]+)['"]/g;
@@ -102,12 +143,25 @@ export function topFolder(file: string): string {
   return match ? match[1]! : '(root)';
 }
 
-function targetDagZone(file: string): string {
+export function targetDagZone(file: string): string {
   if (file.startsWith('src/daemon/client/')) return 'daemon-client';
   if (file.startsWith('src/daemon/')) return 'daemon-server';
   return topFolder(file);
 }
 
+// The set of zones every production file resolves into. A zone that is neither ranked
+// nor listed as intentionally unranked is an unclassified drift signal.
+export function collectZones(files: readonly string[]): Set<string> {
+  return new Set(files.map(targetDagZone));
+}
+
+// Zones present in `files` that are neither ranked nor intentionally unranked. A new
+// `src/<folder>/` must be classified deliberately; leaving it unclassified would let
+// its back-edges silently escape the ranked spine. Empty means the partition holds.
+export function unclassifiedZones(files: readonly string[]): string[] {
+  return [...collectZones(files)].filter((zone) => classifyZone(zone) === 'unclassified').sort();
+}
+
 function resolveTargetFile(
   fromFile: string,
   spec: string,

src/daemon/app-log-request-scope.ts

@@ -0,0 +1,3 @@
+// Isolates request-scope provider composition behind its dynamic import.
+// The shared app-log implementation remains eager for observability and teardown.
+export { withAppLogProvider } from './app-log.ts';

src/daemon/request-platform-providers.ts

@@ -271,7 +271,7 @@ const REQUEST_PLATFORM_PROVIDER_DESCRIPTORS = [
     },
     async appendWrapper(scopedProviders, wrappers) {
       if (!scopedProviders.appLog?.provider) return;
-      const { withAppLogProvider } = await import('./app-log.ts');
+      const { withAppLogProvider } = await import('./app-log-request-scope.ts');
       appendRequestProviderWrapper(wrappers, scopedProviders.appLog, withAppLogProvider);
     },
   },