@tea-agent/loop-agent 0.42.0-next.15 → 0.42.0-next.17

package/dist/workflows/dag/runner-exit-diagnostics.js

@@ -0,0 +1,125 @@
+import { appendFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+/**
+ * Runner exit-time diagnostics (silent-death forensics).
+ *
+ * A DAG runner can disappear without a crash report and without stderr (five
+ * reproductions during frontend recovery/long-plan runs, 2026-09-06): when a
+ * supervisor hard-kills the process or the event loop is wedged, no JS runs,
+ * so nothing is persisted and the run is only discoverable later as an
+ * orphaned RUNNING state with a frozen heartbeat. That leaves no evidence of
+ * WHERE the runner was when it died or whether the exit was even observable
+ * by Node.
+ *
+ * This module gives every abnormal death a durable trace next to state.json:
+ *   - an `armed` line is written when the checkpoint starts executing;
+ *   - a `process-exit` line is appended from the process `exit` hook with the
+ *     exit code and a live state snapshot (status, terminalReason, RUNNING
+ *     nodes, heartbeat staleness);
+ *   - `uncaught-exception` / `unhandled-rejection` lines record the error
+ *     before the process is allowed to crash exactly as it would have
+ *     via uncaughtExceptionMonitor without changing the host's crash policy.
+ *
+ * On a clean terminal return the runner calls stop(), which removes every
+ * listener and deletes the journal, so completed runs carry no noise. A file
+ * left behind therefore means: diagnostics were armed, then the process went
+ * away through a path Node could not observe (`armed` line only → external
+ * SIGKILL/OOM/event-loop wedge) or through an observed abnormal exit (`armed`
+ * + one or more event lines → the reason is recorded in the file).
+ *
+ * Journal writes are strictly synchronous and best-effort: an append failure
+ * must never alter the runner's own crash/exit behavior.
+ */
+export const RUNNER_EXIT_DIAGNOSTICS_FILE = "runner-exit-diagnostics.jsonl";
+function describeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message };
+    }
+    try {
+        return { message: String(error) };
+    }
+    catch {
+        return { message: "<unstringifiable error>" };
+    }
+}
+function appendJournalLineSync(journalPath, record) {
+    try {
+        mkdirSync(path.dirname(journalPath), { recursive: true });
+        appendFileSync(journalPath, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    catch {
+        // Best-effort: journaling must never crash or alter exit behavior.
+    }
+}
+function removeJournalSync(journalPath) {
+    try {
+        unlinkSync(journalPath);
+    }
+    catch {
+        // Tolerate a missing journal (e.g. nothing was ever written).
+    }
+}
+export function installRunnerExitDiagnostics(options) {
+    const journalPath = path.join(options.runDir, RUNNER_EXIT_DIAGNOSTICS_FILE);
+    const target = options.target ?? process;
+    const armedAt = Date.now();
+    let stopped = false;
+    const base = {
+        runId: options.runId,
+        title: options.title,
+        pid: process.pid,
+        hostname: hostname(),
+    };
+    const safeSnapshot = () => {
+        try {
+            return options.snapshot();
+        }
+        catch {
+            return { status: "<snapshot-error>", running: [] };
+        }
+    };
+    const record = (kind, extra) => ({
+        ts: new Date().toISOString(),
+        kind,
+        ...base,
+        ...(extra ?? {}),
+        state: safeSnapshot(),
+    });
+    appendJournalLineSync(journalPath, {
+        ...record("armed"),
+        armedAt: new Date(armedAt).toISOString(),
+    });
+    const onProcessExit = (code) => {
+        if (stopped)
+            return;
+        appendJournalLineSync(journalPath, record("process-exit", {
+            code: typeof code === "number" ? code : process.exitCode ?? 0,
+            elapsedMs: Date.now() - armedAt,
+        }));
+    };
+    const onUncaughtException = (error, origin) => {
+        if (stopped)
+            return;
+        appendJournalLineSync(journalPath, record(origin === "unhandledRejection" ? "unhandled-rejection" : "uncaught-exception", {
+            error: describeError(error),
+            elapsedMs: Date.now() - armedAt,
+        }));
+        // Monitor listeners neither suppress fatal errors nor force a crash
+        // when the host has its own handlers or a nonfatal rejection policy.
+    };
+    target.on("exit", onProcessExit);
+    target.on("uncaughtExceptionMonitor", onUncaughtException);
+    return {
+        journalPath,
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            target.removeListener("exit", onProcessExit);
+            target.removeListener("uncaughtExceptionMonitor", onUncaughtException);
+            // Clean completion: leave completed runs free of diagnostics noise.
+            removeJournalSync(journalPath);
+        },
+    };
+}

package/dist/workflows/dag/runner.js

@@ -32,11 +32,13 @@ import { assertFrontendTopologyBinding, buildFrontendTopologyBinding, computeFro
 import { ensureFrontendShapeCapsuleRecord } from "./frontend-shape-capsule-store.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
 import { computeActionPayloadHash, } from "../../infrastructure/console/operation-store.js";
+import { classifyFailureOwner, failureOwnerSchema } from "./frontend-recovery-capsule.js";
 import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, claimDagRecoveryLease, } from "./recovery-lease.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
 import { executeDynamicLoopUntil } from "./dynamic-runtime/loop-until.js";
 import { executeDynamicMapExpansion } from "./dynamic-runtime/map.js";
 import { executeDynamicReduction } from "./dynamic-runtime/reduction.js";
+import { installRunnerExitDiagnostics } from "./runner-exit-diagnostics.js";
 export { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions };
 export async function loadDagSpecFromFile(dagPath) {
     const raw = JSON.parse(await readFile(dagPath, "utf-8"));
@@ -602,6 +604,36 @@ async function executeDagCheckpoint(input) {
     const onSigInt = () => shutdownOnSignal("SIGINT");
     process.once("SIGTERM", onSigTerm);
     process.once("SIGINT", onSigInt);
+    // Exit-time diagnostics (silent-death forensics): write an `armed` line at
+    // checkpoint start and append process-exit / uncaught-exception /
+    // unhandled-rejection lines with a live state snapshot so an abnormal death
+    // (supervisor hard kill, wedged event loop, crash with lost stderr) leaves
+    // a durable trace next to state.json. Removed on clean terminal return.
+    const exitDiagnostics = installRunnerExitDiagnostics({
+        runDir,
+        runId: state.runId,
+        title: state.title,
+        snapshot: () => {
+            const heartbeatAt = state.runner?.heartbeatAt;
+            return {
+                status: state.status,
+                terminalReason: state.terminalReason,
+                failureCategory: state.failureCategory,
+                heartbeatAt,
+                heartbeatAgeMs: heartbeatAt === undefined
+                    ? undefined
+                    : Math.max(0, Date.now() - Date.parse(heartbeatAt)),
+                running: Object.values(state.nodes)
+                    .filter((node) => node.status === "RUNNING")
+                    .map((node) => ({
+                    id: node.id,
+                    attempt: node.currentAttempt,
+                    startedAt: node.startedAt,
+                    lastMeaningfulProgressAt: node.lastMeaningfulProgressAt,
+                })),
+            };
+        },
+    });
     try {
         const tasksById = new Map(spec.tasks.map((task) => [task.id, task]));
         const baseExecuteNode = input.executeNode ??
@@ -938,6 +970,7 @@ async function executeDagCheckpoint(input) {
     finally {
         clearInterval(heartbeatTimer);
         interruptWatcher?.stop();
+        exitDiagnostics.stop();
         process.removeListener("SIGTERM", onSigTerm);
         process.removeListener("SIGINT", onSigInt);
     }
@@ -1296,13 +1329,40 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd, f
         if (verifyFailed) {
             const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
             if (continuationCount < frontendRecoveryQuota) {
-                recoveryTrigger = {
-                    requestId: state.runId,
-                    failureSource: "frontend-verify-shell",
-                    failureOwner: "implementation",
-                    protocolFailureReason: "frontend verification failure",
-                    recoveryMode: "continuation",
-                };
+                let recoveryOwner = classifyFailureOwner({
+                    nodeId: "frontend-verify-shell",
+                    rawFailureCategory: state.nodes["frontend-verify-shell"]?.failureCategory,
+                });
+                try {
+                    const verifyFailure = JSON.parse(await readFile(path.join(runDir, "contracts/frontend-verify-failure.json"), "utf8"));
+                    const owner = failureOwnerSchema.safeParse(verifyFailure.failureOwner);
+                    if (verifyFailure.schemaVersion === 1 &&
+                        verifyFailure.schemaId === "frontend-verify-failure-v1" &&
+                        verifyFailure.nodeId === "frontend-verify-shell" &&
+                        verifyFailure.failureCategory === state.nodes["frontend-verify-shell"]?.failureCategory &&
+                        owner.success) {
+                        recoveryOwner = owner.data;
+                    }
+                    else {
+                        recoveryOwner = "unknown";
+                    }
+                }
+                catch {
+                    // The node's classified category remains the fallback; never turn
+                    // unknown/environment/configuration failures into writer work.
+                }
+                if (recoveryOwner === "implementation")
+                    recoveryTrigger = {
+                        requestId: state.runId,
+                        failureSource: "frontend-verify-shell",
+                        failureOwner: recoveryOwner,
+                        protocolFailureReason: "frontend verification failure",
+                        recoveryMode: "continuation",
+                    };
+                else
+                    state.terminalReason = recoveryOwner === "environment"
+                        ? "frontend-verification-wait-external"
+                        : `frontend-verification-${recoveryOwner}-requires-contract-review`;
             }
         }
     }

package/dist/workflows/dag/structured-output-repair.js

@@ -112,7 +112,10 @@ export function isStructuredRepairableFailureCategory(category) {
     return (category === "invalid-output" ||
         category === "structured-output-truncated" ||
         category === "output-too-large" ||
-        category === "empty-output");
+        category === "empty-output" ||
+        // A length-truncated structured turn with a non-empty candidate artifact
+        // still repairs best through the frozen artifact repair prompt.
+        category === "output-limit");
 }
 export function formatStructuredArtifactPointer(input) {
     return [

package/dist/workflows/dag/validate.js

@@ -3,7 +3,7 @@ import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveRepairTaskForGate } from "./repair-artifact.js";
 import { topoSortToRanks } from "./topo.js";
-import { isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, CONTEXT_OVERFLOW_RETRY_CATEGORY, } from "./retry-policy.js";
+import { isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, OUTPUT_LIMIT_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, CONTEXT_OVERFLOW_RETRY_CATEGORY, } from "./retry-policy.js";
 import { isBackendTestCompletenessRetryCandidate } from "./backend-test-writer-completeness.js";
 import { defaultFrontendTestLayout, frontendTestLayoutFromSpec, } from "./frontend-test-layout.js";
 const GOVERNANCE_WARNING_TYPES = new Set([
@@ -630,27 +630,28 @@ function validateRetryPolicyTaskConfig(task, issues) {
         const allowed = new Set([
             WRITER_EMPTY_DIFF_RETRY_CATEGORY,
             INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
+            OUTPUT_LIMIT_RETRY_CATEGORY,
         ]);
         const unsupported = task.retryPolicy.retryCategories.filter((category) => !allowed.has(category));
         if (task.retryPolicy.maxAttempts < 2 ||
-            task.retryPolicy.maxAttempts > 3 ||
+            task.retryPolicy.maxAttempts > 5 ||
             unsupported.length > 0 ||
             !categories.has(WRITER_EMPTY_DIFF_RETRY_CATEGORY)) {
             issues.push({
                 type: "invalid-retry-policy",
-                message: `task ${task.id} backend-test writer retryPolicy must use 2..3 total attempts and only ${WRITER_EMPTY_DIFF_RETRY_CATEGORY} and/or ${INCOMPLETE_WRITE_SET_RETRY_CATEGORY}`,
+                message: `task ${task.id} backend-test writer retryPolicy must use 2..5 total attempts and only ${WRITER_EMPTY_DIFF_RETRY_CATEGORY}, ${INCOMPLETE_WRITE_SET_RETRY_CATEGORY}, and/or ${OUTPUT_LIMIT_RETRY_CATEGORY}`,
             });
         }
         return;
     }
     if (isWriterEmptyDiffCandidate &&
         (task.retryPolicy.maxAttempts !== 2 ||
-            task.retryPolicy.retryCategories.length !== 1 ||
-            task.retryPolicy.retryCategories[0] !==
-                WRITER_EMPTY_DIFF_RETRY_CATEGORY)) {
+            !task.retryPolicy.retryCategories.includes(WRITER_EMPTY_DIFF_RETRY_CATEGORY) ||
+            task.retryPolicy.retryCategories.some((category) => category !== WRITER_EMPTY_DIFF_RETRY_CATEGORY &&
+                category !== OUTPUT_LIMIT_RETRY_CATEGORY))) {
         issues.push({
             type: "invalid-retry-policy",
-            message: `task ${task.id} writer retryPolicy must use exactly two total attempts and only ${WRITER_EMPTY_DIFF_RETRY_CATEGORY}`,
+            message: `task ${task.id} writer retryPolicy must use exactly two total attempts and ${WRITER_EMPTY_DIFF_RETRY_CATEGORY}, with optional ${OUTPUT_LIMIT_RETRY_CATEGORY}`,
         });
         return;
     }
@@ -659,6 +660,7 @@ function validateRetryPolicyTaskConfig(task, issues) {
         const allowedWriterTransportCategories = new Set([
             WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
             CONTEXT_OVERFLOW_RETRY_CATEGORY,
+            OUTPUT_LIMIT_RETRY_CATEGORY,
         ]);
         const allAllowed = [...categories].every((category) => allowedWriterTransportCategories.has(category));
         if (task.retryPolicy.maxAttempts !== 2 ||
@@ -667,7 +669,7 @@ function validateRetryPolicyTaskConfig(task, issues) {
             !categories.has(WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY)) {
             issues.push({
                 type: "invalid-retry-policy",
-                message: `task ${task.id} writer transport retryPolicy must use exactly two total attempts and only writer-clean-timeout (plus optional context-overflow)`,
+                message: `task ${task.id} writer transport retryPolicy must use exactly two total attempts and only writer-clean-timeout (plus optional context-overflow/output-limit)`,
             });
         }
     }

package/dist/workflows/dag/workspace-checkpoint.js

@@ -184,3 +184,69 @@ export function workspaceFingerprintsMatch(left, right) {
         return false;
     return left.fingerprint === right.fingerprint;
 }
+/**
+ * Path-level drift between two checkpoints: paths whose content hash,
+ * porcelain state, or presence differs (changed paths plus stable Task
+ * Contract governance inputs). The whole-tree fingerprint also moves on HEAD
+ * commits or porcelain churn that leaves every path's content untouched;
+ * only content-level path diffs are actionable for scoped rerun eligibility.
+ * Returns undefined when either checkpoint lacks a path inventory so callers
+ * fail closed to the strict whole-fingerprint comparison.
+ */
+export function workspaceDriftedPaths(parent, current) {
+    // changedPaths is only the porcelain inventory; it cannot explain files
+    // already committed between two different HEADs. Never localize that drift.
+    if (!parent.gitHeadSha ||
+        !current.gitHeadSha ||
+        parent.gitHeadSha !== current.gitHeadSha) {
+        return undefined;
+    }
+    if (!Array.isArray(parent.changedPaths) || !Array.isArray(current.changedPaths)) {
+        return undefined;
+    }
+    // Porcelain v1 records only the rename destination in this checkpoint
+    // schema, so the removed source path cannot be proven safe for imported
+    // readers. Keep scoped reuse fail-closed until both sides expose complete
+    // rename lineage.
+    if (parent.changedPaths.some((entry) => entry.state === "renamed") ||
+        current.changedPaths.some((entry) => entry.state === "renamed")) {
+        return undefined;
+    }
+    if ((parent.stableGovernanceInputs === undefined) !==
+        (current.stableGovernanceInputs === undefined)) {
+        return undefined;
+    }
+    const drifted = new Set();
+    const parentByPath = new Map(parent.changedPaths.map((entry) => [entry.path, entry]));
+    const currentByPath = new Map(current.changedPaths.map((entry) => [entry.path, entry]));
+    for (const [pathKey, parentEntry] of parentByPath) {
+        const currentEntry = currentByPath.get(pathKey);
+        if (!currentEntry) {
+            drifted.add(pathKey);
+            continue;
+        }
+        if (parentEntry.contentSha256 !== currentEntry.contentSha256 ||
+            parentEntry.state !== currentEntry.state ||
+            parentEntry.mode !== currentEntry.mode) {
+            drifted.add(pathKey);
+        }
+    }
+    for (const pathKey of currentByPath.keys()) {
+        if (!parentByPath.has(pathKey))
+            drifted.add(pathKey);
+    }
+    if (parent.stableGovernanceInputs && current.stableGovernanceInputs) {
+        const parentGov = new Map(parent.stableGovernanceInputs.map((entry) => [entry.path, entry.contentSha256]));
+        const currentGov = new Map(current.stableGovernanceInputs.map((entry) => [entry.path, entry.contentSha256]));
+        for (const [pathKey, hash] of parentGov) {
+            const other = currentGov.get(pathKey);
+            if (other === undefined || other !== hash)
+                drifted.add(pathKey);
+        }
+        for (const [pathKey, hash] of currentGov) {
+            if (parentGov.get(pathKey) !== hash)
+                drifted.add(pathKey);
+        }
+    }
+    return [...drifted];
+}

package/docs/templates/agent-dag.schema.json

@@ -466,9 +466,9 @@
         "retryCategories": {
           "type": "array",
           "items": {
-            "enum": ["timeout", "network", "rate-limit", "unavailable", "empty-output", "output-too-large", "protocol-invalid", "invalid-output", "writer-empty-diff", "incomplete-write-set", "writer-clean-timeout", "read-burst", "context-overflow"]
+            "enum": ["timeout", "network", "rate-limit", "unavailable", "empty-output", "output-limit", "output-too-large", "protocol-invalid", "invalid-output", "writer-empty-diff", "incomplete-write-set", "writer-clean-timeout", "read-burst", "context-overflow"]
           },
-          "default": ["timeout", "network", "rate-limit", "unavailable", "empty-output"],
+          "default": ["timeout", "network", "rate-limit", "unavailable", "empty-output", "output-limit"],
           "description": "Failure categories eligible for retry. quota/auth/write-guard are never eligible. invalid-output is allowed only on explicit structured/protocol policies; writer-empty-diff and incomplete-write-set are reserved for requireChangedFiles generation/completeness writers; writer-clean-timeout is reserved for standard bounded writers after explicit zero-write-tool-call and empty-diff evidence."
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.42.0-next.15",
+  "version": "0.42.0-next.17",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Use only for the tool-only frontend decision planning node.
 references:
   - path: references/decision-contract.md
     required: true
-    maxChars: 5200
+    maxChars: 5600
   - path: references/design-decisions.md
     required: true
     maxChars: 3400
@@ -29,6 +29,11 @@ cite `evidencePath` of an existing file; greenfield is `decision=new`.
 Bind every file in the Contract-owned `requiredDeliverables` inventory. It records
 explicit source obligations, not every path mentioned by a requirement.
 
+Cross-slice citations must close in the same session: when a requirement cites a
+verification target committed in another slice's session, re-commit that target
+here with the same id and `replace=true` (union backfill) before finalize. A
+`duplicate` receipt is a correction invitation, not a prohibition.
+
 The runtime owns protected skeleton fields, path/command validation, materialization,
 and final schema checks. Finish with exactly one `finalize_plan`; return no Markdown
 narrative. Record a genuine evidence gap when frozen facts are insufficient.

package/skills/frontend-plan/references/decision-contract.md

@@ -16,11 +16,9 @@
 
 ### Behavior target shape (canonical example)
 
-Behavior targets are machine-traced evidence: each one must name the requirements
-it proves and the declared UI states it exercises. Empty `requirementIds` or empty
-`uiStates` (when the contract declares any UI state or interaction) is rejected at
-plan validation — fix the mapping, do not resubmit unchanged. State names must be
-copied verbatim from the declared `uiStates`; never invent synonyms.
+Each behavior target names the requirements it proves and declared UI states it
+exercises. Empty `requirementIds`, or empty `uiStates` when any state/interaction
+is declared, is rejected. Copy state names verbatim; never invent synonyms.
 
 ```json
 {
@@ -36,13 +34,70 @@ the task's declared scope. Capabilities the task source lists as non-goals (e.g.
 responsive/mobile layout, animations) must not be promised here, and themes or
 CSS conventions must not be claimed without a Scout-confirmed repository fact.
 
+### UI state declaration shape (canonical example)
+
+Use the exact state names referenced by behavior targets. Each applicable state
+carries behavior, implementation targets, and verification target ids:
+
+```json
+{
+  "uiStates": [
+    {
+      "name": "disabled-minus",
+      "applicable": true,
+      "expectedBehavior": "minus button disabled at count 0",
+      "implementationTargets": ["src/components/SmokeCounter.tsx"],
+      "verificationTargetIds": ["VT-COUNTER-LOCAL-CONSTRAINTS"]
+    }
+  ],
+  "interactions": [
+    {
+      "name": "refresh",
+      "trigger": "User clicks refresh",
+      "expectedBehavior": "reloads runs",
+      "implementationTargets": ["src/App.tsx"],
+      "verificationTargetIds": ["VT-SMOKE-COUNTER-BEHAVIOR"]
+    }
+  ]
+}
+```
+
+### Implementation target coverage (canonical example)
+
+`targets.files` is the union of every requirement's `implementationTargets`; list
+each required component, integration point, and sibling source. Admission adds
+non-static verification target files to the writer writeSet separately.
+
+```json
+{
+  "id": "AC-FE-001",
+  "implementationTargets": [
+    "src/components/SmokeCounter.tsx",
+    "src/App.tsx"
+  ],
+  "verificationTargetIds": [
+    "VT-SMOKE-COUNTER-BEHAVIOR",
+    "VT-COUNTER-LOCAL-CONSTRAINTS"
+  ]
+}
+```
+
+### Bidirectional VT cross-reference invariant
+
+Every requirement → VT citation must close in both directions: the cited VT's
+`requirementIds` must list the citing requirement back. The checker reports the
+missing direction; fix it in-node by re-submitting the corrected VT entry with
+the same id and `replace=true`. `replace` is a full replacement: the latest
+submission under an id becomes the authoritative entry (a subset re-submission
+is the new rule). A `duplicate` receipt is a correction invitation, not a
+prohibition, and a reverse-reference backfill is not "re-deriving committed
+facts".
+
 ## UX vocabulary (registry first)
 
-- Record `record_state_registry` BEFORE any `record_state_flow`: one compact
-  global vocabulary of UI-state and interaction names. Coverage may slice by
-  requirement; UX must not — never one name per requirement number and never a
-  rename of an already-recorded concept (kebab-case behavior-domain names, e.g.
-  `planner-task-edit`, `focus-queue-move`).
+- Record `record_state_registry` BEFORE `record_state_flow`: one global vocabulary.
+  Coverage may slice by requirement; UX must not. Use stable kebab-case behavior
+  names, never AC-number-derived names or renamed committed concepts.
 - UI states use the contract's declared authoritative ids (`declaredUiStates`
   in the plan input) when the source declares a state table.
 - Retry slices see `committedUx` in the plan input: reuse those exact names.
@@ -50,14 +105,10 @@ CSS conventions must not be claimed without a Scout-confirmed repository fact.
 ## Global decisions
 
 Keep route/component placement, Mock/data strategy, and dependency/deviation policy
-as explicit global decisions rather than duplicating them across each requirement.
-Use only frozen command labels and Scout-confirmed paths.
-
-Component choices: ONE choice may cover many UI states/interactions explicitly via
-`covers` — never one row per interaction. `decision=reuse-existing` REQUIRES
-`evidencePath` naming the existing repo file that proves the reuse (the runtime
-verifies the file exists); a path that does not exist yet is greenfield and must
-use `decision=new`.
+global. Use only frozen command labels and Scout-confirmed paths.
+
+One component choice may cover many states/interactions via `covers`.
+`reuse-existing` requires an existing-file `evidencePath`; greenfield uses `new`.
 
 For Mock/API, keep the real request path enabled by default. Select only a strategy
 allowed by the frozen task capability. Active Mock requires deterministic Mock-backed

package/skills/frontend-plan/references/design-decisions.md

@@ -15,3 +15,35 @@ Contract. Do not search specification roots or nearby code from Plan.
   responsive, and accessibility behavior; use not-applicable only with a reason.
 - Record styling strategy, deviations, conflicts, and unresolved gaps explicitly.
   Never silently replace a spec-defined component or claim unread evidence.
+
+### Component choice shape (canonical example)
+
+`purpose` must exactly match a declared UI state or interaction name — it is the
+coverage key the deterministic policy checks. Do not invent synonyms, and never
+swap a task-mandated component for another name without recording a deviation.
+
+```json
+[
+  {
+    "purpose": "disabled-minus",
+    "component": "SmokeCounter",
+    "decision": "new",
+    "sourceRequirementIds": ["AC-FE-001"],
+    "sourceFragmentId": "REQ-SRC-AC-FE-001",
+    "rationale": "task mandates a new SmokeCounter card on the home surface"
+  },
+  {
+    "purpose": "refresh",
+    "component": "RunFilterBar",
+    "decision": "reuse-existing",
+    "rationale": "reuses the Scout-confirmed filter bar for the refresh interaction"
+  }
+]
+```
+
+For `decision: "new"`, pass `sourceRequirementIds` + `sourceFragmentId` and let
+the runtime derive the exact task-source citation — never hand-write a
+`specReference`. A `reuse-existing` choice covers behavioural interactions
+without one row per interaction; each applicable visual UI state still needs its
+own `purpose` match (or an explicitly scoped stylingStrategy covering the visual
+dimension).

package/dist/worker/console/static/assets/channel-i1DjpDIw.js

@@ -1 +0,0 @@
-import{ag as o,ah as n}from"./mermaid.core-B6Lxil0V.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/worker/console/static/assets/classDiagram-JCYQIIEL-DgDRdE1V.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-AeGX6EAg.js";import{_ as i}from"./mermaid.core-B6Lxil0V.js";import"./chunk-5VM5RSS4-Cc_m4gyV.js";import"./chunk-XXDRQBXY-D-7LGrV2.js";import"./chunk-KBJHAD2P-Bi5UopKd.js";import"./chunk-2GRJ4B5K-BCPb5H0y.js";import"./index-BmMi-Bve.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/worker/console/static/assets/classDiagram-v2-OCEON4UE-DgDRdE1V.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-AeGX6EAg.js";import{_ as i}from"./mermaid.core-B6Lxil0V.js";import"./chunk-5VM5RSS4-Cc_m4gyV.js";import"./chunk-XXDRQBXY-D-7LGrV2.js";import"./chunk-KBJHAD2P-Bi5UopKd.js";import"./chunk-2GRJ4B5K-BCPb5H0y.js";import"./index-BmMi-Bve.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};