@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.10

package/dist/executors/dag-pi/plan/record-tools.js

@@ -0,0 +1,861 @@
+import { nonEmptyString, planToolReceipt, stringList } from "./tool-helpers.js";
+import { collectCanonicalStateFlowNames } from "../../../workflows/dag/frontend-contract-facts.js";
+import { pathMatchesPattern } from "../../../shared/git-progress.js";
+import { isRecordObject } from "../guards.js";
+import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+export function buildPlanRecordTools(ctx) {
+    const { Type, defineTool, session, schemas, input, readCommittedEvents, scopedRequirementIds, executionGroups, adoptPlanFact } = ctx;
+    const { stringArray, optionalString, requirementSchema, uiStateSchema, interactionSchema, mockEndpointSchema, mockApiSchema, designEvidenceSchema, verificationTargetSchema, evidenceGapSchema, uiComponentChoiceSchema } = ctx.schemas;
+    const recordRouteSelectionTool = defineTool({
+        name: "record_route_selection",
+        label: "record_route_selection",
+        description: "Record the route selection needed by this plan. Repository target surface and file ownership belong to Scout/runtime. Example: {\"routes\": [\"/<route>\"]}",
+        promptSnippet: "Record the selected routes.",
+        parameters: Type.Object({ routes: stringArray }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const routes = stringList(params?.routes);
+            const result = await adoptPlanFact("target-surface", `${session.attemptId}:record_route_selection:${randomUUID()}`, { kind: "target-surface", origin: "plan", routes });
+            return planToolReceipt(result);
+        },
+    });
+    const recordComponentChoiceTool = defineTool({
+        name: "record_component_choice",
+        label: "record_component_choice",
+        description: "Record ONE component choice (origin=plan component-choice fact). One choice may cover MULTIPLE UI states/interactions via covers: [\"<state-or-interaction name>\", ...]; do not emit one row per interaction. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component and sourceFragmentId selecting one frozen citation listed in the plan checklist; the runtime validates the relation and derives the exact PRD specReference. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo and REQUIRES evidencePath: a repo-relative path to the existing file that proves the reuse — the runtime verifies the file exists (fresh evidence); a path with no existing file is greenfield and must use decision=new instead. Call up to 5 component choices per assistant message; never more than 5 per message. Optionally include stylingStrategy (set it once, on the first call). Example: {\"choice\": {\"purpose\": \"<interaction or UI state name>\", \"component\": \"<component name>\", \"decision\": \"new\", \"covers\": [\"<other interaction names this component also serves>\"]}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"} or {\"choice\": {\"purpose\": \"FocusQueuePanel\", \"component\": \"FocusQueuePanel\", \"decision\": \"reuse-existing\", \"evidencePath\": \"src/journal.ts\"}}",
+        promptSnippet: "Record 1-5 component choices (up to 5 per message).",
+        parameters: Type.Object({
+            choice: uiComponentChoiceSchema,
+            sourceRequirementIds: Type.Optional(stringArray),
+            sourceFragmentId: optionalString,
+            stylingStrategy: optionalString,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawChoice = params?.choice;
+            if (!isRecordObject(rawChoice)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "component-choice",
+                    error: "record_component_choice requires a non-empty choice object",
+                });
+            }
+            const sourceRequirementIds = stringList(params?.sourceRequirementIds);
+            const sourceFragmentId = nonEmptyString(params?.sourceFragmentId);
+            const choice = { ...rawChoice };
+            if (choice.decision === "new") {
+                if (sourceRequirementIds.length === 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=new requires sourceRequirementIds so runtime can materialize the task-source specReference",
+                    });
+                }
+                if (!sourceFragmentId) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=new requires sourceFragmentId selecting a frozen task-source citation",
+                    });
+                }
+                const citation = sourceRequirementIds
+                    .flatMap((id) => input.componentNewSourceReferences?.get(id) ?? [])
+                    .find((candidate) => candidate.fragmentId === sourceFragmentId);
+                if (!citation) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: `decision=new sourceFragmentId ${sourceFragmentId} is not bound to sourceRequirementIds ${sourceRequirementIds.join(", ")}`,
+                    });
+                }
+                choice.specReference = {
+                    path: citation.path,
+                    section: citation.section,
+                    ...(citation.line !== undefined ? { line: citation.line } : {}),
+                };
+            }
+            if (choice.decision === "reuse-existing") {
+                // reuse-existing must cite a file that actually exists NOW (fresh
+                // existence evidence, same semantics as Scout pathEvidence.fresh).
+                // A path with no file on disk is greenfield: decision=new is the
+                // only honest choice (dogfood run dag-1788504923861-0f7b17a9
+                // claimed 18 reuse-existing conventions in a not-yet-written
+                // src/planner.ts and every gate let it through).
+                const evidencePath = typeof choice.evidencePath === "string"
+                    ? choice.evidencePath.trim()
+                    : "";
+                if (!evidencePath) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=reuse-existing requires evidencePath naming the existing repo file that proves the reuse; if the file does not exist yet, use decision=new",
+                    });
+                }
+                if (input.workspaceRoot) {
+                    const absolute = path.resolve(input.workspaceRoot, evidencePath);
+                    const workspaceRoot = path.resolve(input.workspaceRoot);
+                    const contained = absolute === workspaceRoot ||
+                        absolute.startsWith(`${workspaceRoot}${path.sep}`);
+                    let exists = false;
+                    if (contained) {
+                        try {
+                            exists = (await stat(absolute)).isFile();
+                        }
+                        catch {
+                            exists = false;
+                        }
+                    }
+                    if (!exists) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "component-choice",
+                            error: `decision=reuse-existing evidencePath "${evidencePath}" has no fresh existence evidence (file not found in the workspace); reuse requires an existing file — use decision=new for greenfield paths`,
+                        });
+                    }
+                }
+            }
+            const components = typeof choice.component === "string" ? [choice.component] : [];
+            const result = await adoptPlanFact("component-choice", `${session.attemptId}:record_component_choice:${randomUUID()}`, {
+                kind: "component-choice",
+                origin: "plan",
+                scopeRequirementIds: scopedRequirementIds(),
+                components,
+                uiComponentChoices: [choice],
+                ...(params?.stylingStrategy
+                    ? { stylingStrategy: params.stylingStrategy }
+                    : {}),
+            });
+            // Echo the frozen citation the runtime derived: the model sees the
+            // purpose↔citation mapping it just committed and can re-record the
+            // choice (last-wins per purpose at compile) when it mismatches.
+            const echo = {
+                ...result,
+                ...(choice.specReference
+                    ? { derivedSpecReference: choice.specReference }
+                    : {}),
+            };
+            return planToolReceipt(echo);
+        },
+    });
+    // Global UX vocabulary: one compact registry committed BEFORE any state
+    // flow details. Coverage may slice by AC; UX must not — the registry is
+    // the anti-duplication anchor that keeps every later slice on the same
+    // named concepts instead of re-inventing them per AC chunk.
+    const recordStateRegistryTool = defineTool({
+        name: "record_state_registry",
+        label: "record_state_registry",
+        description: "Commit the GLOBAL UX vocabulary (origin=plan state-registry fact) BEFORE any record_state_flow call: uiStateNames (use the contract's declared authoritative state ids when provided) and interactionNames (stable behavior-domain kebab-case names, e.g. planner-task-edit / focus-queue-move — one name per behavior domain, never one per AC). Empty arrays explicitly mean the request has no UI state or interaction vocabulary. Re-record the full vocabulary to correct it; the latest commit wins, but it may not remove names still referenced by committed state-flow facts. Example: {\"uiStateNames\": [\"planner-empty\"], \"interactionNames\": [\"planner-task-create\", \"focus-queue-move\"]}",
+        promptSnippet: "Record the global UI-state/interaction vocabulary once, before any state flow.",
+        parameters: Type.Object({
+            uiStateNames: stringArray,
+            interactionNames: stringArray,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const uiStateNames = [...new Set(stringList(params?.uiStateNames).map((name) => name.trim()))];
+            const interactionNames = [
+                ...new Set(stringList(params?.interactionNames).map((name) => name.trim())),
+            ];
+            if (uiStateNames.some((name) => name.length === 0) || interactionNames.some((name) => name.length === 0)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: "record_state_registry names must be non-empty strings",
+                });
+            }
+            const invalidInteractionNames = interactionNames.filter((name) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name));
+            if (invalidInteractionNames.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: `record_state_registry interactionNames must be stable kebab-case behavior-domain names: ${invalidInteractionNames.join(", ")}`,
+                });
+            }
+            if (input.declaredUiStateIds &&
+                input.declaredUiStateIds.length > 0) {
+                const declared = new Set(input.declaredUiStateIds);
+                const undeclared = uiStateNames.filter((name) => !declared.has(name));
+                if (undeclared.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-registry",
+                        error: `record_state_registry uiStateNames are not declared by the contract's authoritative UI-state table: ${undeclared.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")})`,
+                    });
+                }
+                const missing = input.declaredUiStateIds.filter((name) => !uiStateNames.includes(name));
+                if (missing.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-registry",
+                        error: `record_state_registry must include every state from the contract's authoritative UI-state table; missing: ${missing.join(", ")}`,
+                    });
+                }
+            }
+            // A correction is deterministic only when the new last-wins registry
+            // still contains every live name already committed by state-flow facts.
+            // This permits adding a missed concept, while preventing a registry edit
+            // from retroactively orphaning earlier slices.
+            const liveNames = collectCanonicalStateFlowNames(readCommittedEvents(session.store, session.attemptId));
+            const orphanedUiStates = [...liveNames.uiStateNames].filter((name) => !uiStateNames.includes(name));
+            const orphanedInteractions = [...liveNames.interactionNames].filter((name) => !interactionNames.includes(name));
+            if (orphanedUiStates.length > 0 || orphanedInteractions.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: `record_state_registry cannot remove names still referenced by committed state-flow facts (uiStates: ${orphanedUiStates.join(", ") || "none"}; interactions: ${orphanedInteractions.join(", ") || "none"}); first correct/remove those state-flow entries, then re-record the full registry`,
+                });
+            }
+            const result = await adoptPlanFact("state-registry", `${session.attemptId}:record_state_registry:${randomUUID()}`, {
+                kind: "state-registry",
+                origin: "plan",
+                uiStateNames,
+                interactionNames,
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordStateFlowTool = defineTool({
+        name: "record_state_flow",
+        label: "record_state_flow",
+        description: "Record UI states and interactions as an origin=plan state-flow fact. REQUIRES a committed record_state_registry vocabulary first, and every name here must be in that registry; uiState names must also be contract-declared authoritative ids when the contract declares them. To correct stale named entries from an earlier UX batch, include removeUiStateNames and/or removeInteractionNames. Example: {\"uiStates\": [{\"name\": \"<state>\", \"applicable\": true, \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}], \"interactions\": [{\"name\": \"<interaction>\", \"trigger\": \"<user event>\", \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}]}",
+        promptSnippet: "Record the plan state-flow fact.",
+        parameters: Type.Object({
+            uiStates: Type.Array(uiStateSchema),
+            interactions: Type.Array(interactionSchema),
+            removeUiStateNames: Type.Optional(stringArray),
+            removeInteractionNames: Type.Optional(stringArray),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawUiStates = Array.isArray(params?.uiStates)
+                ? params.uiStates
+                : [];
+            const rawInteractions = Array.isArray(params?.interactions)
+                ? params.interactions
+                : [];
+            const removeUiStateNames = stringList(params?.removeUiStateNames);
+            const removeInteractionNames = stringList(params?.removeInteractionNames);
+            const uiStates = [];
+            for (const rawState of rawUiStates) {
+                if (!isRecordObject(rawState)) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow uiStates entries must be objects",
+                    });
+                }
+                const { reason, notApplicableReason, ...state } = rawState;
+                const canonicalReason = nonEmptyString(notApplicableReason);
+                const aliasReason = nonEmptyString(reason);
+                if (canonicalReason !== undefined &&
+                    aliasReason !== undefined &&
+                    canonicalReason !== aliasReason) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow uiState has conflicting reason and notApplicableReason values",
+                    });
+                }
+                const resolvedReason = canonicalReason ?? aliasReason;
+                if (state.applicable === false && !resolvedReason) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow requires non-empty notApplicableReason when uiState.applicable is false",
+                    });
+                }
+                uiStates.push({
+                    ...state,
+                    ...(resolvedReason
+                        ? { notApplicableReason: resolvedReason }
+                        : {}),
+                });
+            }
+            const interactions = [];
+            for (const rawInteraction of rawInteractions) {
+                if (!isRecordObject(rawInteraction)) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow interactions entries must be objects",
+                    });
+                }
+                const { id, name, ...interaction } = rawInteraction;
+                const canonicalName = nonEmptyString(name);
+                const aliasName = nonEmptyString(id);
+                if (canonicalName !== undefined &&
+                    aliasName !== undefined &&
+                    canonicalName !== aliasName) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow interaction has conflicting id and name values",
+                    });
+                }
+                const resolvedName = canonicalName ?? aliasName;
+                if (!resolvedName) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow requires non-empty interaction.name (id is accepted only as a legacy alias)",
+                    });
+                }
+                // Interaction -> VT forward references are legal only against
+                // already-committed VT facts. In the segmented flow every VT
+                // commits in the coverage segment before state flows run, so a
+                // dangling reference here is a real defect (r20: *-BEHAVIOR
+                // refs reached the final review untraceable).
+                const interactionVtIds = stringList(interaction.verificationTargetIds);
+                const committedVtIds = new Set(readCommittedEvents(session.store, session.attemptId)
+                    .map((event) => event.fact)
+                    .filter((fact) => fact.kind === "plan-verification-target")
+                    .map((fact) => fact.entry
+                    ?.id)
+                    .filter((id) => typeof id === "string"));
+                const unknownVtIds = interactionVtIds.filter((id) => !committedVtIds.has(id));
+                if (unknownVtIds.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: `record_state_flow interaction "${resolvedName}" references verification targets that are not recorded yet: ${unknownVtIds.join(", ")}; record them with record_plan_verification_target first, then re-record this state flow`,
+                    });
+                }
+                interactions.push({ ...interaction, name: resolvedName });
+            }
+            // UX vocabulary gate: every recorded state/interaction name must be
+            // declared in the committed global registry first. This keeps UX out
+            // of AC-number slicing — the model commits one compact vocabulary
+            // (record_state_registry), then fills behavior-domain details, and a
+            // later slice cannot silently rename an earlier concept (dogfood
+            // dag-1788504923861-0f7b17a9: 5 renames of "prioritize" + 7 of
+            // "focus queue" across AC chunks).
+            const states = uiStates
+                .map((state) => (typeof state?.name === "string" ? state.name : ""))
+                .filter(Boolean);
+            const committedRegistry = readCommittedEvents(session.store, session.attemptId)
+                .map((event) => event.fact)
+                .filter((fact) => isRecordObject(fact) && fact.kind === "state-registry")
+                .at(-1);
+            if (!committedRegistry) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: "record_state_flow requires a committed UX registry first: call record_state_registry with the full uiStateNames/interactionNames vocabulary, then record state flows against it",
+                });
+            }
+            const registryUiStateNames = new Set(stringList(committedRegistry.uiStateNames));
+            const registryInteractionNames = new Set(stringList(committedRegistry.interactionNames));
+            const unknownStates = states.filter((name) => !registryUiStateNames.has(name));
+            if (unknownStates.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: `record_state_flow uiState names not in the committed registry: ${unknownStates.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryUiStateNames].join(", ") || "(none)"})`,
+                });
+            }
+            const unknownInteractions = interactions
+                .map((interaction) => typeof interaction?.name === "string" ? interaction.name : "")
+                .filter((name) => name && !registryInteractionNames.has(name));
+            if (unknownInteractions.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: `record_state_flow interaction names not in the committed registry: ${unknownInteractions.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryInteractionNames].join(", ") || "(none)"})`,
+                });
+            }
+            // Authoritative UI states: when the contract node declared the
+            // source's UI-state table, planner states must bind those ids — no
+            // invented variants (planner-empty/create-invalid/no-results/
+            // editing/focus-full/storage-unavailable, not "planner-list").
+            if (input.declaredUiStateIds &&
+                input.declaredUiStateIds.length > 0) {
+                const declared = new Set(input.declaredUiStateIds);
+                const undeclaredStates = states.filter((name) => !declared.has(name));
+                if (undeclaredStates.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: `record_state_flow uiState names are not declared by the contract's authoritative UI-state table: ${undeclaredStates.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")}), or record a design deviation if the source table is genuinely incomplete`,
+                    });
+                }
+            }
+            // Named entries are last-wins at assembly. A scoped correction may
+            // replace its own bindings, but must retain other scopes' coverage.
+            const scope = new Set(scopedRequirementIds());
+            const committed = readCommittedEvents(session.store, session.attemptId).map(event => event.fact);
+            const targetOwners = new Map();
+            for (const fact of committed) {
+                if (fact.kind === "plan-verification-target" && isRecordObject(fact.entry) && typeof fact.entry.id === "string") {
+                    targetOwners.set(fact.entry.id, stringList(fact.entry.requirementIds));
+                }
+            }
+            for (const [field, removals] of [["uiStates", removeUiStateNames], ["interactions", removeInteractionNames]]) {
+                const live = new Map();
+                for (const fact of committed) {
+                    if (fact.kind !== "state-flow")
+                        continue;
+                    for (const name of stringList(fact[field === "uiStates" ? "removeUiStateNames" : "removeInteractionNames"]))
+                        live.delete(name);
+                    for (const entry of Array.isArray(fact[field]) ? fact[field] : []) {
+                        if (isRecordObject(entry) && typeof entry.name === "string")
+                            live.set(entry.name, entry);
+                    }
+                }
+                const foreignBindings = (entry) => scope.size === 0 ? [] : stringList(entry.verificationTargetIds).filter(id => {
+                    const owners = targetOwners.get(id);
+                    return !owners?.length || owners.some(owner => !scope.has(owner));
+                });
+                for (const name of removals) {
+                    const previous = live.get(name);
+                    if (previous && foreignBindings(previous).length)
+                        return planToolReceipt({ ok: false, kind: "state-flow",
+                            error: `Cannot remove shared ${name} from this requirement scope; retain it and update its scoped bindings instead` });
+                }
+                for (const entry of field === "uiStates" ? uiStates : interactions) {
+                    const previous = live.get(String(entry.name));
+                    if (previous)
+                        entry.verificationTargetIds = [...new Set([...foreignBindings(previous), ...stringList(entry.verificationTargetIds)])];
+                }
+            }
+            const result = await adoptPlanFact("state-flow", `${session.attemptId}:record_state_flow:${randomUUID()}`, {
+                kind: "state-flow",
+                origin: "plan",
+                scopeRequirementIds: scopedRequirementIds(),
+                states,
+                uiStates,
+                interactions,
+                removeUiStateNames,
+                removeInteractionNames,
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordDataFlowTool = defineTool({
+        name: "record_data_flow",
+        label: "record_data_flow",
+        description: "Record interaction/endpoint data flow as an origin=plan data-flow fact. Example: {\"interactions\": [\"<interaction name>\"], \"endpoints\": [\"GET <path>\"]}",
+        promptSnippet: "Record the plan data-flow fact.",
+        parameters: Type.Object({ interactions: stringArray, endpoints: stringArray, replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const previous = params.replace ? undefined : readCommittedEvents(session.store, session.attemptId).filter(r => r.fact.kind === "data-flow").at(-1)?.fact;
+            const result = await adoptPlanFact("data-flow", `${session.attemptId}:record_data_flow:${randomUUID()}`, {
+                kind: "data-flow",
+                origin: "plan",
+                interactions: [...new Set([...stringList(previous?.interactions), ...stringList(params?.interactions)])],
+                endpoints: [...new Set([...stringList(previous?.endpoints), ...stringList(params?.endpoints)])],
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordMockApiTool = defineTool({
+        name: "record_mock_api",
+        label: "record_mock_api",
+        description: "Record the Mock/API strategy as an origin=plan mock-api fact. Example: {\"mockApi\": {\"strategy\": \"not-needed\", \"activation\": \"n/a\", \"endpoints\": []}}",
+        promptSnippet: "Record the plan mock-api fact.",
+        parameters: Type.Object({ mockApi: mockApiSchema }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const mockApi = params?.mockApi ?? {
+                strategy: "not-needed",
+                activation: "",
+                endpoints: [],
+            };
+            const endpoints = stringList((Array.isArray(mockApi?.endpoints) ? mockApi.endpoints : []).map((endpoint) => `${typeof endpoint?.method === "string" ? endpoint.method : ""} ${typeof endpoint?.path === "string" ? endpoint.path : ""}`.trim()));
+            const result = await adoptPlanFact("mock-api", `${session.attemptId}:record_mock_api:${randomUUID()}`, {
+                kind: "mock-api",
+                origin: "plan",
+                strategy: typeof mockApi?.strategy === "string" ? mockApi.strategy : "",
+                endpoints,
+                mockApi,
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordMockEndpointTool = defineTool({
+        name: "record_mock_endpoint", label: "record_mock_endpoint",
+        description: "Record one Mock/API endpoint. First record_mock_api with the policy and endpoints: []; then submit each endpoint separately. Never regenerate the whole endpoint collection. Use replace:true to revise an existing method/path, or replace:true plus remove:true to withdraw it.",
+        parameters: Type.Object({ endpoint: mockEndpointSchema, remove: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+        async execute(_callId, params) {
+            if (!readCommittedEvents(session.store, session.attemptId).some(r => r.fact.kind === "mock-api"))
+                return planToolReceipt({ ok: false, kind: "mock-endpoint", code: "MOCK_POLICY_MISSING", error: "Record the mock policy before its endpoints" });
+            return planToolReceipt(await adoptPlanFact("mock-endpoint", `${session.attemptId}:endpoint:${randomUUID()}`, { kind: "mock-endpoint", origin: "plan", endpoint: params.endpoint, ...(params.remove ? { removed: true } : {}) }));
+        },
+    });
+    const recordDesignDeviationTool = defineTool({
+        name: "record_design_deviation",
+        label: "record_design_deviation",
+        description: "Record design evidence conflicts as an origin=plan design-deviation fact. Example: {\"designEvidence\": {\"source\": \"<source>\", \"paths\": [\"<file>\"], \"conflicts\": [\"<conflicting requirement id>\"]}}",
+        promptSnippet: "Record the plan design-deviation fact.",
+        parameters: Type.Object({ designEvidence: designEvidenceSchema }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const conflicts = stringList(params?.designEvidence?.conflicts);
+            const result = await adoptPlanFact("design-deviation", `${session.attemptId}:record_design_deviation:${randomUUID()}`, { kind: "design-deviation", origin: "plan", conflicts });
+            return planToolReceipt(result);
+        },
+    });
+    const recordDependencyTool = defineTool({
+        name: "record_dependency",
+        label: "record_dependency",
+        description: "Record the dependency policy as an origin=plan dependency fact. Example: {\"policy\": \"<dependency policy statement>\"}",
+        promptSnippet: "Record the plan dependency fact.",
+        parameters: Type.Object({ policy: Type.String({}) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const result = await adoptPlanFact("dependency", `${session.attemptId}:record_dependency:${randomUUID()}`, {
+                kind: "dependency",
+                origin: "plan",
+                policy: typeof params?.policy === "string" ? params.policy : "",
+            });
+            return planToolReceipt(result);
+        },
+    });
+    // Incremental plan payload records (one entry per call) so requirements,
+    // verification targets, evidence gaps, and implementation steps never have
+    // to be emitted as one large array inside a single finalize_plan call —
+    // they aggregate from the ledger in commit order. Mirrors the contract
+    // node's record_requirement pattern to stay within any model output budget.
+    const recordPlanRequirementTool = defineTool({
+        name: "record_plan_requirement",
+        label: "record_plan_requirement",
+        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement. Verification targets are authoritative in record_plan_verification_target; omit verificationTargetIds here unless repairing legacy input. For a correction, re-submit the same id with replace=true; the ledger compiles the latest replacement. Entry carries id, implementationTargets, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"<AC-XXX>\", \"implementationTargets\": [\"<deliverable file>\"]}}",
+        promptSnippet: "Commit 1-4 plan requirement entries (up to 4 per message).",
+        parameters: Type.Object({
+            entry: requirementSchema,
+            replace: Type.Optional(Type.Boolean()),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-requirement",
+                    error: "record_plan_requirement requires a non-empty entry object",
+                });
+            }
+            let entry = rawEntry;
+            // An embedded evidenceGap with a blank description means "no gap":
+            // small-output models emit the slot defensively with description ""
+            // on every requirement. The canonical contract schema requires a
+            // non-empty gap description (min 1 char), so passing the empty slot
+            // through would deterministically fail the plan compile with
+            // invalid-output and burn every retry. Drop the empty slot — the
+            // field is optional and the runtime derives real blocking gaps when
+            // a requirement has no proof.
+            const rawGap = isRecordObject(entry.evidenceGap)
+                ? entry.evidenceGap
+                : undefined;
+            if (rawGap &&
+                typeof rawGap.description === "string" &&
+                rawGap.description.trim() === "") {
+                const { evidenceGap: _omittedGap, ...rest } = entry;
+                void _omittedGap;
+                entry = rest;
+            }
+            // Canonical-identity check: a requirement id outside the frozen
+            // canonical list (e.g. a BR-* business rule picked up from the PRD
+            // prose) would commit an immutable fact that finalize's
+            // canonical-coverage gate rejects with no in-node cure. Reject here
+            // and name the allowed ids.
+            const id = typeof entry.id === "string" ? entry.id : "";
+            if (session.activeRequirementScope.length && !session.activeRequirementScope.includes(id))
+                return planToolReceipt({ ok: false, kind: "plan-requirement", code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: `Requirement ${id} is outside this session` });
+            if (id &&
+                input.requirementIds &&
+                input.requirementIds.length > 0 &&
+                !input.requirementIds.includes(id)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-requirement",
+                    error: `record_plan_requirement id "${id}" is not a frozen canonical requirement; canonical ids are: ${input.requirementIds.join(", ")}`,
+                });
+            }
+            // A requirement id is a canonical identity: recording it twice would
+            // compile a duplicate requirements[] entry and fail design review.
+            // Reject duplicates by default; replace=true is the explicit in-node
+            // correction path and the compiler keeps the latest replacement.
+            if (id && params?.replace !== true) {
+                const existing = readCommittedEvents(session.store, session.attemptId).find((event) => {
+                    const fact = event.fact;
+                    if (!fact || fact.kind !== "plan-requirement")
+                        return false;
+                    const entryFact = fact.entry;
+                    return (typeof entryFact?.id === "string" &&
+                        entryFact.id === id);
+                });
+                if (existing) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "plan-requirement",
+                        error: `record_plan_requirement duplicate: requirement ${id} is already recorded; do not record the same requirement id twice`,
+                    });
+                }
+            }
+            if (id &&
+                session.activeRequirementScope.length > 0 &&
+                !session.activeRequirementScope.includes(id)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-requirement",
+                    error: `record_plan_requirement id "${id}" is outside this session's requirement scope [${session.activeRequirementScope.join(", ")}]`,
+                });
+            }
+            const result = await adoptPlanFact("plan-requirement", `${session.attemptId}:record_plan_requirement:${randomUUID()}`, {
+                kind: "plan-requirement",
+                origin: "plan",
+                entry,
+                ...(params?.replace === true ? { replaces: id } : {}),
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordPlanGroupCoverageTool = defineTool({
+        name: "record_plan_group_coverage", label: "record_plan_group_coverage",
+        description: "Submit shared implementation/verification references for one declared execution group. Runtime expands to every canonical member and retains its full outcome and source bindings. A shared VT must actually verify each independent condition. Use per-requirement records for differences; never create UI for constraints or exclusions. replace:true explicitly revises the group.",
+        parameters: Type.Object({ id: Type.String({ minLength: 1 }), implementationTargets: stringArray, verificationTargetIds: Type.Optional(stringArray), replace: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+        async execute(callId, params, signal, onUpdate, ctx) {
+            const group = executionGroups.find(g => g.id === params.id && g.kind !== "unclassified");
+            if (!group || (session.activeRequirementScope.length && group.requirementIds.some(id => !session.activeRequirementScope.includes(id))))
+                return planToolReceipt({ ok: false, kind: "plan-requirement", code: "EXECUTION_GROUP_SCOPE_INVALID", error: "A known complete group must be present in this session; submit individual member records when the group spans scopes" });
+            let last;
+            for (const id of group.requirementIds) {
+                const existing = readCommittedEvents(session.store, session.attemptId).filter(r => r.fact.kind === "plan-requirement" && r.fact.entry?.id === id).at(-1)?.fact.entry;
+                if (existing && !params.replace) {
+                    if (JSON.stringify(existing.implementationTargets) !== JSON.stringify(params.implementationTargets))
+                        return planToolReceipt({ ok: false, kind: "plan-requirement", code: "FACT_IDENTITY_CONFLICT", error: `${id}: existing coverage differs; use replace:true to revise explicitly` });
+                    continue;
+                }
+                last = await recordPlanRequirementTool.execute(`${callId}:${id}`, { entry: { id, implementationTargets: params.implementationTargets, ...(params.verificationTargetIds ? { verificationTargetIds: params.verificationTargetIds } : {}) }, ...(params.replace ? { replace: true } : {}) }, signal, onUpdate, ctx);
+                if (!last.details?.ok)
+                    return last;
+            }
+            return planToolReceipt(await adoptPlanFact("plan-group-coverage", `${session.attemptId}:group:${randomUUID()}`, { kind: "plan-group-coverage", origin: "plan", id: group.id, requirementIds: group.requirementIds }));
+        },
+    });
+    const recordPlanVerificationTargetTool = defineTool({
+        name: "record_plan_verification_target",
+        label: "record_plan_verification_target",
+        description: "Commit one plan verification target entry (origin=plan plan-verification-target fact). Reference a frozen verification command by commandId (see the frozen command directory in your prompt: static commands are project-wide checks traced by file and command only; behavior commands bind an existing affected test file; preserve its test names). For behavior targets, call once per distinct behavior, not mechanically once per requirement: one target may cover multiple related requirementIds. For a correction, re-submit the same id with replace=true; the ledger compiles the latest replacement. A target id identifies a contract entry only; never require it in test names. Results bind by frozen command and test file. Entry carries id, commandId, file, requirementIds, and uiStates; optional scope (unit | component | integration) is display-only. Free-form symbol text is not accepted. IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"id\": \"VT-DASHBOARD-SHELL\", \"commandId\": \"<frozen behavior command id>\", \"file\": \"<test file>\", \"requirementIds\": [\"AC-001\", \"AC-002\"], \"uiStates\": []}}" +
+            (input.canonicalVerificationTargetIds &&
+                input.canonicalVerificationTargetIds.length > 0
+                ? ` Frozen canonical behavior target ids (use exactly for behavior targets): ${input.canonicalVerificationTargetIds.join(", ")}.`
+                : ""),
+        promptSnippet: "Commit 1-4 plan verification target entries (up to 4 per message).",
+        parameters: Type.Object({
+            entry: verificationTargetSchema,
+            replace: Type.Optional(Type.Boolean()),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: "record_plan_verification_target requires a non-empty entry object",
+                });
+            }
+            // Contract v2: the plan references a frozen command by commandId;
+            // mode and label are resolved by the runtime from the frozen
+            // command directory (run.json frontend-verify-shell bundle lanes).
+            // Reject unknown ids and behavior commands bound to non-test
+            // files here so the model fixes them in-node instead of the
+            // attempt dying at materialization or at the writer focused-check.
+            const verificationCommandId = typeof rawEntry.commandId === "string"
+                ? rawEntry.commandId.trim()
+                : "";
+            if (!verificationCommandId) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target entry.commandId is required (received ${JSON.stringify(rawEntry.commandId ?? null)}); pick one id from the frozen command directory in your prompt`,
+                });
+            }
+            const { deriveFrontendVerifyCommandDirectoryFromRun, isFrontendTestFilePath, } = await import("../../../workflows/dag/frontend-implementation-contract.js");
+            const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
+            if (verifyDirectory.length > 0) {
+                const directoryEntry = verifyDirectory.find((entry) => entry.commandId === verificationCommandId);
+                if (!directoryEntry) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "plan-verification-target",
+                        error: `record_plan_verification_target verification-target-unknown-command: unknown commandId "${verificationCommandId}"; available frozen commands: [${verifyDirectory.map((entry) => `${entry.commandId} (${entry.mode}: ${entry.label})`).join(", ")}]`,
+                    });
+                }
+                if (directoryEntry.mode === "behavior" &&
+                    typeof rawEntry.file === "string" &&
+                    !isFrontendTestFilePath(rawEntry.file)) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "plan-verification-target",
+                        error: `record_plan_verification_target verification-target-phase-mismatch: behavior command "${directoryEntry.label}" (${directoryEntry.commandId}) must bind a test file (__tests__/, tests?/, e2e/, cypress/, *.test.*, *.spec.*, *.cy.*); received file "${rawEntry.file}"`,
+                    });
+                }
+                // Canonical-identity check for behavior targets: the PRD freezes
+                // the exact behavior verification-target ids (e.g.
+                // VT-SMOKE-COUNTER-BEHAVIOR). A committed non-canonical id is
+                // immutable and design review rejects it as a
+                // contract-requirement gap, so reject invented ids here.
+                if (directoryEntry.mode === "behavior" &&
+                    input.canonicalVerificationTargetIds &&
+                    input.canonicalVerificationTargetIds.length > 0) {
+                    const canonicalTargetId = typeof rawEntry.id === "string" ? rawEntry.id.trim() : "";
+                    if (canonicalTargetId &&
+                        !input.canonicalVerificationTargetIds.includes(canonicalTargetId)) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "plan-verification-target",
+                            error: `record_plan_verification_target id "${canonicalTargetId}" is not a frozen canonical behavior verification target; canonical ids are: ${input.canonicalVerificationTargetIds.join(", ")}`,
+                        });
+                    }
+                }
+            }
+            // Duplicate-id rejection: committed typed facts are immutable, so
+            // re-recording the same VT id would deadlock the compile by default.
+            // replace=true is the explicit in-node correction path.
+            const vtId = typeof rawEntry.id === "string" ? rawEntry.id : "";
+            if (vtId &&
+                params?.replace !== true &&
+                readCommittedEvents(session.store, session.attemptId).some((event) => {
+                    const fact = event.fact;
+                    if (!fact || fact.kind !== "plan-verification-target")
+                        return false;
+                    const entryFact = fact.entry;
+                    return entryFact?.id === vtId;
+                })) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target duplicate: verification target ${vtId} is already recorded; use replace=true for an in-node correction`,
+                });
+            }
+            // WriteSet containment at the boundary: a committed VT fact whose
+            // file is outside the task writeSet is immutable, and the finalize
+            // pre-validation would then fail the whole attempt with no in-node
+            // cure (r17 post-merge). Reject here with the allowed patterns.
+            if (typeof rawEntry.file === "string" &&
+                input.writeSetPatterns &&
+                input.writeSetPatterns.length > 0 &&
+                !input.writeSetPatterns.some((pattern) => pathMatchesPattern(rawEntry.file, pattern))) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target file is outside the writeSet patterns [${input.writeSetPatterns.join(", ")}]: ${rawEntry.file}; verification targets must point inside the task writeSet`,
+                });
+            }
+            // uiStates: [] means this verification target is intentionally not
+            // bound to a named UI state. Keep that canonical representation even
+            // when a model omits the optional tool-boundary field.
+            const entryWithoutSymbol = { ...rawEntry };
+            delete entryWithoutSymbol.symbol;
+            const entry = {
+                ...entryWithoutSymbol,
+                uiStates: stringList(rawEntry.uiStates),
+            };
+            // Cross-reference integrity at the boundary: the compile gate
+            // rejects verification targets referencing UI states or
+            // requirements that were never declared. Validate against the
+            // facts already committed in this attempt so the model fixes the
+            // reference in-node instead of burning the attempt at compile time
+            // (r7: one full attempt lost to a single unknown UI state name).
+            const committedEvents = readCommittedEvents(session.store, session.attemptId);
+            const declaredUiStateNames = collectCanonicalStateFlowNames(committedEvents).uiStateNames;
+            const unknownUiStates = entry.uiStates.filter((name) => !declaredUiStateNames.has(name));
+            if (unknownUiStates.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target references UI states that were never declared: ${unknownUiStates.join(", ")}; declare every referenced UI state with record_state_flow first, or pass uiStates: [] for intentionally unbound targets`,
+                });
+            }
+            const declaredRequirementIds = new Set(committedEvents.flatMap((event) => {
+                const fact = event.fact;
+                if (!fact || fact.kind !== "plan-requirement")
+                    return [];
+                const requirementEntry = fact.entry;
+                return typeof requirementEntry?.id === "string"
+                    ? [requirementEntry.id]
+                    : [];
+            }));
+            const unknownRequirementIds = stringList(rawEntry.requirementIds).filter((id) => !declaredRequirementIds.has(id));
+            const outOfScopeRequirementIds = stringList(rawEntry.requirementIds).filter((id) => session.activeRequirementScope.length > 0 &&
+                !session.activeRequirementScope.includes(id));
+            if (outOfScopeRequirementIds.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target references requirements outside this session's scope [${session.activeRequirementScope.join(", ")}]: ${outOfScopeRequirementIds.join(", ")}`,
+                });
+            }
+            if (unknownRequirementIds.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-verification-target",
+                    error: `record_plan_verification_target references unknown requirement ids: ${unknownRequirementIds.join(", ")}; record every referenced requirement with record_plan_requirement first`,
+                });
+            }
+            const result = await adoptPlanFact("plan-verification-target", `${session.attemptId}:record_plan_verification_target:${randomUUID()}`, {
+                kind: "plan-verification-target",
+                origin: "plan",
+                entry,
+                ...(params?.replace === true ? { replaces: vtId } : {}),
+            });
+            return planToolReceipt(result);
+        },
+    });
+    const recordPlanEvidenceGapTool = defineTool({
+        name: "record_plan_evidence_gap",
+        label: "record_plan_evidence_gap",
+        description: "Commit one plan evidence gap entry (origin=plan plan-evidence-gap fact). Call once per gap; entry carries requirementId, description, blocking. IMPORTANT: batch up to 4 record_* calls per assistant message; never batch more than 4 — a larger single message risks output truncation under a small output window. Example: {\"entry\": {\"requirementId\": \"<AC-XXX>\", \"description\": \"<what evidence is missing and why>\", \"blocking\": false}}",
+        promptSnippet: "Commit 1-4 plan evidence gap entries (up to 4 per message).",
+        parameters: Type.Object({
+            entry: evidenceGapSchema,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const rawEntry = params?.entry;
+            if (!isRecordObject(rawEntry)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-evidence-gap",
+                    error: "record_plan_evidence_gap requires a non-empty entry object",
+                });
+            }
+            const entry = rawEntry;
+            // A standalone evidence gap IS the gap statement: a blank description
+            // would fail the canonical contract schema (min 1 char) after the
+            // whole attempt finished. Reject at the boundary so the model writes
+            // a real description in-node instead of burning the attempt.
+            if (typeof entry.description === "string" &&
+                entry.description.trim() === "") {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-evidence-gap",
+                    error: "record_plan_evidence_gap requires a non-empty description describing the gap",
+                });
+            }
+            const requirementId = typeof entry.requirementId === "string"
+                ? entry.requirementId
+                : undefined;
+            if (requirementId &&
+                session.activeRequirementScope.length > 0 &&
+                !session.activeRequirementScope.includes(requirementId)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "plan-evidence-gap",
+                    error: `record_plan_evidence_gap requirementId "${requirementId}" is outside this session's requirement scope [${session.activeRequirementScope.join(", ")}]`,
+                });
+            }
+            const result = await adoptPlanFact("plan-evidence-gap", `${session.attemptId}:record_plan_evidence_gap:${randomUUID()}`, { kind: "plan-evidence-gap", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
+    return {
+        recordRouteSelectionTool,
+        recordComponentChoiceTool,
+        recordStateRegistryTool,
+        recordStateFlowTool,
+        recordDataFlowTool,
+        recordMockApiTool,
+        recordMockEndpointTool,
+        recordDesignDeviationTool,
+        recordDependencyTool,
+        recordPlanRequirementTool,
+        recordPlanGroupCoverageTool,
+        recordPlanVerificationTargetTool,
+        recordPlanEvidenceGapTool,
+    };
+}