@tea-agent/loop-agent 0.39.0-beta.3 → 0.39.0-beta.5

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.39.0-beta.3",
-  "gitSha": "d9fdc0eac8d061d1285094f7d9d1531b669e5266",
-  "builtAt": "2026-08-23T05:55:12.549Z"
+  "version": "0.39.0-beta.5",
+  "gitSha": "0981b80311d973603a870fd80693331cb5e48335",
+  "builtAt": "2026-08-23T11:38:56.113Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -216,6 +216,9 @@ export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
     "record_mock_api",
     "record_design_deviation",
     "record_dependency",
+    "record_plan_requirement",
+    "record_plan_verification_target",
+    "record_plan_evidence_gap",
 ];
 export const FRONTEND_PLAN_TERMINAL_TOOL_NAMES = ["finalize_plan"];
 export const FRONTEND_PLAN_ADOPT_TOOL_NAMES = ["adopt_staged_fact"];
@@ -923,16 +926,83 @@ export async function createFrontendPlanLedgerTools(input) {
             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; each entry carries id, expectedOutcome, implementationTargets, verificationTargetIds, and optional evidenceGap.",
+        promptSnippet: "Commit one plan requirement entry.",
+        parameters: Type.Object({
+            entry: requirementSchema,
+        }, { 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",
+                });
+            }
+            const entry = rawEntry;
+            const result = await adoptPlanFact("plan-requirement", `${attemptId}:record_plan_requirement:${randomUUID()}`, { kind: "plan-requirement", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
+    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). Call once per target; entry carries id, type, commandLabel, file, symbol, requirementIds, uiStates.",
+        promptSnippet: "Commit one plan verification target entry.",
+        parameters: Type.Object({
+            entry: verificationTargetSchema,
+        }, { 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",
+                });
+            }
+            const entry = rawEntry;
+            const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, { kind: "plan-verification-target", origin: "plan", entry });
+            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.",
+        promptSnippet: "Commit one plan evidence gap entry.",
+        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;
+            const result = await adoptPlanFact("plan-evidence-gap", `${attemptId}:record_plan_evidence_gap:${randomUUID()}`, { kind: "plan-evidence-gap", origin: "plan", entry });
+            return planToolReceipt(result);
+        },
+    });
     const finalizePlanTool = defineTool({
         name: "finalize_plan",
         label: "finalize_plan",
-        description: "Assemble the canonical editable plan patch from committed record facts plus these remaining fields, publish it on a target-surface fact, and commit the finalize_plan terminal. Call exactly once.",
-        promptSnippet: "Assemble and commit the finalize_plan terminal (requirements + verificationTargets + evidenceGaps + optional fields).",
+        description: "Commit the finalize_plan terminal. Requirements, verification targets, and evidence gaps (optional) were already committed incrementally through record_plan_requirement / record_plan_verification_target / record_plan_evidence_gap; finalize_plan assembles them from the ledger together with these optional remaining fields, publishes the canonical editable patch on a target-surface fact, and commits the terminal. Call exactly once.",
+        promptSnippet: "Commit the finalize_plan terminal (ledger fields + optional residualRisks / realIntegrationGap).",
         parameters: Type.Object({
-            requirements: Type.Array(requirementSchema),
-            verificationTargets: Type.Array(verificationTargetSchema),
-            evidenceGaps: Type.Array(evidenceGapSchema),
-            implementationSteps: optionalStringArray,
             residualRisks: optionalStringArray,
             realIntegrationGap: optionalString,
         }, { additionalProperties: false }),
@@ -942,12 +1012,6 @@ export async function createFrontendPlanLedgerTools(input) {
                 const fragment = assemblePlanPatchFromCommittedFacts(committed) ?? {};
                 const patch = {
                     ...fragment,
-                    requirements: params?.requirements ?? [],
-                    verificationTargets: params?.verificationTargets ?? [],
-                    evidenceGaps: params?.evidenceGaps ?? [],
-                    ...(params?.implementationSteps
-                        ? { implementationSteps: params.implementationSteps }
-                        : {}),
                     ...(params?.residualRisks
                         ? { residualRisks: params.residualRisks }
                         : {}),
@@ -1024,6 +1088,9 @@ export async function createFrontendPlanLedgerTools(input) {
             recordMockApiTool,
             recordDesignDeviationTool,
             recordDependencyTool,
+            recordPlanRequirementTool,
+            recordPlanVerificationTargetTool,
+            recordPlanEvidenceGapTool,
             adoptStagedFactTool,
             finalizePlanTool,
         ],
@@ -1176,6 +1243,48 @@ export async function createFrontendContractTools(input) {
             return receipt(result);
         },
     }));
+    // OpenSpec selection committed as individual typed facts (one path per
+    // call) so a large candidate set never exceeds a single model output
+    // budget: each tool call carries exactly one {path, disposition,
+    // rationale} row and the ledger accumulates them across calls. Only
+    // positive classifications (required | relevant) are legal; unmentioned
+    // candidates default to irrelevant at the prewrite gate.
+    const recordOpenspecSelectionTool = defineTool({
+        name: "record_openspec_selection",
+        label: "record_openspec_selection",
+        description: "Commit one OpenSpec candidate classification (origin=contract openspec-selection fact). Call once per path you actually use or consult: required (must be read and cited) or relevant (informs planning). Never call it for irrelevant candidates — unmentioned candidates default to irrelevant. You may call it many times; one row per call.",
+        promptSnippet: "Commit one OpenSpec candidate classification (required | relevant); one path per call; skip irrelevant candidates.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: "Repo-relative candidate spec path, e.g. openspec/project-specs/ui/ucp-components-md/AdvancedSearch.md",
+            }),
+            disposition: Type.Enum({
+                required: "required",
+                relevant: "relevant",
+            }),
+            rationale: Type.String({}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const path = typeof params?.path === "string" ? params.path : "";
+            const disposition = params?.disposition;
+            const rationale = typeof params?.rationale === "string" ? params.rationale : "";
+            if (!path || !disposition || !rationale.trim()) {
+                return receipt({
+                    ok: false,
+                    kind: "openspec-selection",
+                    error: "record_openspec_selection requires non-empty path, disposition (required|relevant), and rationale",
+                });
+            }
+            const result = await adoptContractFact("openspec-selection", {
+                kind: "openspec-selection",
+                origin: "contract",
+                path,
+                disposition,
+                rationale,
+            });
+            return receipt(result);
+        },
+    });
     const finalizeContractTool = defineTool({
         name: "finalize_contract",
         label: "finalize_contract",
@@ -1225,7 +1334,11 @@ export async function createFrontendContractTools(input) {
         },
     });
     return {
-        customTools: [...recordTools, finalizeContractTool],
+        customTools: [
+            ...recordTools,
+            recordOpenspecSelectionTool,
+            finalizeContractTool,
+        ],
         flush: async () => {
             const committed = readCommittedEvents(store, attemptId);
             await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), committed);

package/dist/executors/shell-executor.js

@@ -2429,7 +2429,9 @@ async function executeFrontendDesignPolicy(input, meta) {
             contract,
             allowedMockStrategies: config.allowedMockStrategies,
             sourceFreshness,
-            componentSpecCandidatePaths: config.componentSpecCandidatePaths ?? [],
+            componentSpecCandidatePaths: config.openspecCandidatePaths ??
+                config.componentSpecCandidatePaths ??
+                [],
             allowedDependencies: config.allowedDependencies,
             writeSetPatterns: config.implementationWriteSet ?? [],
         });

package/dist/task/frontend-project-capability.js

@@ -267,6 +267,14 @@ function emptyClassified() {
  * project-specific file names. Basename stems use word-boundary matching so
  * e.g. `*api*` (case-insensitive) maps to `rule.api` without hardcoding names.
  */
+/** True when any path segment (other than the file itself) carries a
+ * component/theme kind marker. Directory-organized libraries such as
+ * `ui/ucp-components-md/AdvancedSearch.md` rely on this; templates/ and
+ * rules/ are handled by their own branches before this fallback runs. */
+function segmentMatchesComponentKind(segments) {
+    const dirSegments = segments.slice(0, -1);
+    return dirSegments.some((segment) => /\bcomponents?\b/.test(segment.toLowerCase()));
+}
 function classifyOpenspecPaths(paths) {
     const classified = emptyClassified();
     const ruleStem = (basename) => {
@@ -305,8 +313,17 @@ function classifyOpenspecPaths(paths) {
                 classified.theme.push(candidate);
             else if (/\bcomponents?\b/.test(lower))
                 classified.component.push(candidate);
-            else
+            else if (segmentMatchesComponentKind(segments)) {
+                // Directory-organized component libraries (e.g.
+                // ui/ucp-components-md/AdvancedSearch.md) carry the kind in the
+                // parent directory name, not the file name. The parent-dir rule
+                // is a fallback so such layouts still land in the component
+                // bucket instead of being dropped into uiOther.
+                classified.component.push(candidate);
+            }
+            else {
                 classified.uiOther.push(candidate);
+            }
         }
         else {
             classified.advisoryOther.push(candidate);

package/dist/workflows/dag/frontend-design-policy.js

@@ -141,10 +141,22 @@ export function checkMockStrategy(contract, allowedMockStrategies) {
 }
 /** 4. Component choice must be precisely spec-referenced: `specified` requires
  * a specReference whose normalized path is a candidate and a non-empty section;
- * `new` must not carry a specReference; `reuse-existing` may omit it. */
+ * `new` must not carry a specReference; `reuse-existing` may omit it. The
+ * candidate set is the full generation-frozen openspec candidate list (the
+ * shell passes openspecCandidatePaths with componentSpecCandidatePaths as the
+ * fallback), so directory-organized component libraries are never rejected.
+ * A component specReference must still not point into clearly non-component
+ * spec areas — templates and the ai_workspace governance subtree cannot be the
+ * authoritative component definition. */
 export function checkComponentChoice(contract, componentSpecCandidatePaths) {
     const findings = [];
     const candidates = new Set(componentSpecCandidatePaths.map(normalizeRelativePath));
+    const isNonComponentSpecArea = (path) => {
+        const normalized = normalizeRelativePath(path);
+        return (normalized.startsWith("openspec/project-specs/templates/") ||
+            normalized.startsWith("ai_workspace/") ||
+            normalized === "openspec/project-specs/templates");
+    };
     (contract.uiComponentChoices ?? []).forEach((choice, index) => {
         if (choice.decision === "specified") {
             if (!choice.specReference) {
@@ -170,6 +182,13 @@ export function checkComponentChoice(contract, componentSpecCandidatePaths) {
                     path: choice.specReference.path,
                 });
             }
+            else if (isNonComponentSpecArea(normalized)) {
+                findings.push({
+                    code: "component-spec-reference-path-outside-candidates",
+                    message: `specified component choice #${index} specReference.path "${choice.specReference.path}" is a candidate but lives in a non-component spec area (templates or ai_workspace governance cannot be the authoritative component definition)`,
+                    path: choice.specReference.path,
+                });
+            }
         }
         else if (choice.decision === "new" && choice.specReference) {
             findings.push({

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -209,7 +209,6 @@ export function loadFrontendImplementationContractJsonSchema(startDir = path.dir
         "mockApi",
         "designEvidence",
         "verificationTargets",
-        "evidenceGaps",
     ];
     const actualRequired = Array.isArray(schema.required) ? schema.required : [];
     const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
@@ -407,7 +406,7 @@ export const frontendImplementationContractSchema = z
         uiStates: z.array(z.string().min(1)),
     })
         .strict()).min(1),
-    evidenceGaps: z.array(gap),
+    evidenceGaps: z.array(gap).optional(),
     implementationSteps: z.array(z.string().min(1)).optional(),
     stylingStrategy: z.string().min(1).optional(),
     uiComponentChoices: uiComponentChoicesSchema.optional(),
@@ -1687,7 +1686,7 @@ export async function analyzeFrontendImplementationContract(input) {
     if (!result.success)
         fail("retryable-invalid", `invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`, candidateJsonSha256);
     const blockingGaps = [
-        ...result.data.evidenceGaps,
+        ...(result.data.evidenceGaps ?? []),
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
     ].filter((item) => item.blocking);
     if (blockingGaps.length > 0)
@@ -1696,7 +1695,7 @@ export async function analyzeFrontendImplementationContract(input) {
             .join(", ")}`, candidateJsonSha256);
     for (const requirementId of canonicalBinding.requirementIds)
         if (!result.data.requirements.some((item) => item.id === requirementId) &&
-            !result.data.evidenceGaps.some((item) => item.requirementId === requirementId))
+            !(result.data.evidenceGaps ?? []).some((item) => item.requirementId === requirementId))
             fail("blocked", `frontend contract does not cover ${requirementId}`, candidateJsonSha256);
     return {
         canonical: result.data,
@@ -1728,6 +1727,9 @@ const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
     "mock-api",
     "design-deviation",
     "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
 ];
 /**
  * Restore the editable RFC 7386 plan patch from a committed plan ledger.

package/dist/workflows/dag/frontend-plan-render.js

@@ -54,9 +54,6 @@ export function renderFrontendPlanMarkdown(contract) {
         "## Requirement Coverage",
         requirementsCoverage(contract),
         "",
-        "## Implementation Steps",
-        bulletList(contract.implementationSteps) || "_(not specified)_",
-        "",
         "## Target Files",
         bulletList(contract.targets.files) || "_(none)_",
         "",

package/dist/workflows/dag/frontend-prewrite-gate.js

@@ -334,37 +334,124 @@ async function resolveRequiredOpenspecPaths(input) {
     // semantics instead of silently weakening an existing run.
     if (!input.selectionNodeId)
         return { ok: true, paths: input.candidatePaths };
+    // OpenSpec classifications arrive as individual typed `openspec-selection`
+    // facts (one path per record_openspec_selection call) so a large candidate
+    // set never exceeds a single model output budget. Only positive
+    // classifications (required | relevant) are legal facts; candidates that
+    // were never mentioned default to irrelevant. Explicit task declarations /
+    // source citations (`mandatoryPaths`) are never downgraded: they are
+    // always required and always must-read, whether or not the model declared
+    // them. Fall back to the legacy single fenced JSON for older runs (which
+    // may still carry explicit irrelevant rows).
+    let selections;
+    let allowIrrelevant = false;
+    const selectionNodeId = input.selectionNodeId; // guarded above: no selector -> full candidate semantics
+    try {
+        const facts = await readCommittedContractFacts(input.runDir, selectionNodeId);
+        selections = facts
+            .filter((fact) => fact.kind === "openspec-selection")
+            .map((fact) => ({
+            path: String(fact.path ?? ""),
+            disposition: String(fact.disposition ?? ""),
+            rationale: String(fact.rationale ?? ""),
+        }));
+    }
+    catch {
+        selections = [];
+    }
+    if (selections.length === 0) {
+        const legacy = await readLegacyOpenspecSelection({
+            runDir: input.runDir,
+            selectionNodeId,
+            candidatePaths: input.candidatePaths,
+            mandatoryPaths: input.mandatoryPaths,
+        });
+        if (!legacy.ok)
+            return legacy;
+        selections = legacy.selections;
+        allowIrrelevant = true;
+    }
+    try {
+        const byPath = new Map();
+        for (const row of selections) {
+            const legalDispositions = allowIrrelevant
+                ? ["required", "relevant", "irrelevant"]
+                : ["required", "relevant"];
+            if (typeof row.path !== "string" ||
+                !legalDispositions.includes(row.disposition) ||
+                typeof row.rationale !== "string" ||
+                !row.rationale.trim()) {
+                throw new Error(`invalid selection row (path+${legalDispositions.join("|")}+non-empty rationale expected): ${JSON.stringify(row)}`);
+            }
+            if (!input.candidatePaths.includes(row.path)) {
+                throw new Error(`invalid selection ${row.path}: not a candidate path`);
+            }
+            if (byPath.has(row.path))
+                throw new Error(`duplicate selection ${row.path}`);
+            byPath.set(row.path, row.disposition);
+        }
+        // Only explicitly required/relevant candidates must be read; everything
+        // unmentioned defaults to irrelevant. mandatoryPaths are intrinsic:
+        // they must be read even if the model omitted them, and they can never
+        // be downgraded by a declaration.
+        const mustRead = [
+            ...input.mandatoryPaths,
+            ...input.candidatePaths.filter((candidate) => byPath.get(candidate) === "required"),
+        ];
+        return { ok: true, paths: [...new Set(mustRead)].sort() };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function readCommittedContractFacts(runDir, nodeId) {
+    const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");
+    const records = await readTypedEventStoreFromJsonl(path.join(runDir, nodeId, "contract-typed-facts.jsonl"));
+    return records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => Boolean(fact));
+}
+async function readLegacyOpenspecSelection(input) {
     let text;
     try {
         text = await readNodeText(input.runDir, input.selectionNodeId);
     }
     catch (error) {
-        return { ok: false, reason: `openspec selector output unreadable: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            ok: false,
+            reason: `openspec selector output unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
     const fenced = /```json\s*\n([\s\S]*?)\n```/.exec(text);
-    if (!fenced)
-        return { ok: false, reason: "openspec selector must emit exactly one fenced JSON selection object" };
+    if (!fenced) {
+        return {
+            ok: false,
+            reason: "openspec selector emitted neither typed openspec-selection facts nor a legacy fenced JSON selection object",
+        };
+    }
     try {
         const parsed = JSON.parse(fenced[1] ?? "");
-        if (parsed.schemaVersion !== 1 || parsed.schemaId !== "frontend-openspec-selection-v1" || !Array.isArray(parsed.selections))
+        if (parsed.schemaVersion !== 1 ||
+            parsed.schemaId !== "frontend-openspec-selection-v1" ||
+            !Array.isArray(parsed.selections)) {
             throw new Error("schemaVersion/schemaId/selections invalid");
-        const byPath = new Map();
-        for (const row of parsed.selections) {
-            if (typeof row.path !== "string" || typeof row.disposition !== "string" || typeof row.rationale !== "string")
-                throw new Error("selection row invalid");
-            if (!input.candidatePaths.includes(row.path) || !["required", "relevant", "irrelevant"].includes(row.disposition))
-                throw new Error(`invalid selection ${row.path}`);
-            if (byPath.has(row.path))
-                throw new Error(`duplicate selection ${row.path}`);
-            byPath.set(row.path, row.disposition);
         }
-        const missing = input.candidatePaths.filter((candidate) => !byPath.has(candidate));
-        if (missing.length)
-            throw new Error(`missing classifications: ${missing.join(", ")}`);
-        return { ok: true, paths: [...new Set([...input.mandatoryPaths, ...input.candidatePaths.filter((candidate) => byPath.get(candidate) === "required")])].sort() };
+        const rows = parsed.selections.map((row) => ({
+            path: String(row.path ?? ""),
+            disposition: String(row.disposition ?? ""),
+            rationale: String(row.rationale ?? ""),
+        }));
+        return { ok: true, selections: rows };
     }
     catch (error) {
-        return { ok: false, reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
 }
 async function finalizePrewrite(input, pending) {

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -232,6 +232,9 @@ export const PLAN_LEDGER_FACT_KINDS = [
     "mock-api",
     "design-deviation",
     "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
 ];
 function skeletonTargetFiles(skeleton) {
     if (!isRecord(skeleton))
@@ -320,6 +323,29 @@ export function assemblePlanPatchFromCommittedFacts(records) {
     const dependencyPolicy = asString(dependency?.policy);
     if (dependencyPolicy)
         patch.dependencyPolicy = dependencyPolicy;
+    // Requirements / verification targets / evidence gaps / implementation
+    // steps arrive as individual facts (one per record_plan_* call) so a large
+    // plan never exceeds a single model output budget. Aggregate them in
+    // ledger order.
+    const requirements = facts
+        .filter((fact) => fact.kind === "plan-requirement")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (requirements.length > 0)
+        patch.requirements = requirements;
+    const verificationTargets = facts
+        .filter((fact) => fact.kind === "plan-verification-target")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (verificationTargets.length > 0) {
+        patch.verificationTargets = verificationTargets;
+    }
+    const evidenceGaps = facts
+        .filter((fact) => fact.kind === "plan-evidence-gap")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (evidenceGaps.length > 0)
+        patch.evidenceGaps = evidenceGaps;
     return Object.keys(patch).length > 0 ? patch : undefined;
 }
 /** Derive the 7 origin=plan ledger facts from an editable patch. Skeleton
@@ -460,7 +486,8 @@ function planLedgerFactsFromCommittedRecords(records) {
         .filter((fact) => isRecord(fact) &&
         fact.origin === "plan" &&
         typeof fact.kind === "string" &&
-        PLAN_LEDGER_FACT_KINDS.includes(fact.kind));
+        PLAN_LEDGER_FACT_KINDS.includes(fact.kind))
+        .map((fact) => fact);
 }
 export async function loadCommittedPlanLedgerFacts(runDir, nodeId = "frontend-plan-pi") {
     const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");

package/dist/workflows/dag/frontend-typed-event-store.js

@@ -94,6 +94,7 @@ export const CONTRACT_FACT_KINDS = [
     "handoff-intent",
     "open-question",
     "split-proposal",
+    "openspec-selection",
     "contract-finalized",
 ];
 export const CONTRACT_TERMINAL_FACT_KINDS = ["contract-finalized"];
@@ -112,6 +113,18 @@ export const contractBlockingOwnerSchema = z.enum([
  * `finalize_plan` terminal fact.
  */
 export const PLAN_TERMINAL_FACT_KINDS = ["finalize_plan"];
+/**
+ * A+B: incremental payload records for `frontend-plan-pi` (requirements,
+ * verification targets, evidence gaps). Each is committed by one
+ * `record_plan_*` call so a large plan never exceeds a single model output
+ * budget; `assemblePlanPatchFromCommittedFacts` aggregates them from the
+ * ledger in commit order.
+ */
+export const PLAN_RECORD_FACT_KINDS = [
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
+];
 /**
  * A+B (AC-009): typed issue category shared by review and design change
  * requests. The five-value enum replaces free-form issueCategory strings.
@@ -142,6 +155,7 @@ const ALL_TYPED_EVENT_FACT_KIND_VALUES = [
         ...FRONTEND_SHAPE_FACT_KINDS,
         ...CONTRACT_FACT_KINDS,
         ...PLAN_TERMINAL_FACT_KINDS,
+        ...PLAN_RECORD_FACT_KINDS,
     ]),
 ];
 export const typedEventFactKindSchema = z.enum(ALL_TYPED_EVENT_FACT_KIND_VALUES);

package/dist/workflows/dag/init-hybrid.js

@@ -11,7 +11,7 @@ import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { DEFAULT_OPENSPEC_GOVERNANCE_ROOT, DEFAULT_FRONTEND_SPEC_ROOTS, extractTaskSourceFrontendSpecPaths, } from "../../shared/openspec-spec.js";
 import { BASELINE_FORBIDDEN_PATHS } from "./governance-constants.js";
 import { buildDecisionEnvelopePromptContract } from "./decision-envelope.js";
-import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PLANNER_OUTPUT_LIMIT_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, FRONTEND_PLAN_LADDER_RETRY_POLICY, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY, isCanonicalFinalVerifyShellRetryCandidate, isSafeReadOnlyPiRetryCandidate, isTargetTemplateImplementPi, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PLANNER_OUTPUT_LIMIT_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, FRONTEND_PLAN_LADDER_RETRY_POLICY, FRONTEND_REVIEW_TERMINAL_RETRY_POLICY, TARGET_TEMPLATE_TRANSIENT_RETRY_PROFILE, TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY, isCanonicalFinalVerifyShellRetryCandidate, isSafeReadOnlyPiRetryCandidate, isTargetTemplateImplementPi, isWriterTransportRetryCandidate, } from "./retry-policy.js";
 import { REVIEW_JSON_VERDICT_OUTPUT_PROTOCOL, REVIEW_VERDICT_OUTPUT_PROTOCOL, } from "./output-protocol.js";
 import { resolveAdapter } from "../../adapters/index.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
@@ -2651,7 +2651,7 @@ async function buildFrontendHybridDagFromTask(sources) {
             '{"strategy":"native","productionDefaultOff":true,"activation":"VITE_ENABLE_MOCK=true","endpoints":[{"method":"GET","path":"/api/users","fixture":"mocks/fixtures/users.json","consumer":"src/api/users.ts"}]}',
             "",
             "### optional plan fields - GOOD (all optional; omit when absent):",
-            '{"implementationSteps":["confirm contract","sync tests"],"stylingStrategy":"reuse existing design tokens","dependencyPolicy":"no new runtime deps","residualRisks":["browser a11y not-run"],"realIntegrationGap":"FE-TEST owns live HTTP"}',
+            '{"stylingStrategy":"reuse existing design tokens","dependencyPolicy":"no new runtime deps","residualRisks":["browser a11y not-run"],"realIntegrationGap":"FE-TEST owns live HTTP"}',
             "",
             "### optional plan fields - BAD (present-but-empty strings are rejected):",
             '{"stylingStrategy":"","dependencyPolicy":""}  <-- REJECTED: optional string fields must be non-empty when present; omit them instead',
@@ -2676,8 +2676,8 @@ async function buildFrontendHybridDagFromTask(sources) {
         "- targets: files, routes, publicApiChanges",
         "- mockApi: strategy, productionDefaultOff, activation, endpoints[]",
         "- verificationTargets[]: id, type, commandLabel, file, symbol, requirementIds, uiStates",
-        "- designEvidence: source, paths, conflicts; evidenceGaps[]",
-        "- optional: implementationSteps[], stylingStrategy, uiComponentChoices[], dependencyPolicy, residualRisks[], realIntegrationGap",
+        "- designEvidence: source, paths, conflicts; evidenceGaps[] (optional)",
+        "- optional: stylingStrategy, uiComponentChoices[], dependencyPolicy, residualRisks[], realIntegrationGap",
         "- uiComponentChoices[]: purpose, component, decision (specified|reuse-existing|new), specReference { path, section, line } | null, rationale",
         "Do not require or read a separate plan prose section; the contract JSON is the only plan surface.",
     ].join("\n");
@@ -2929,7 +2929,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal, then call finalize_contract exactly once. Requirements use stable REQ/BR/AC identifiers with source spans and a disposition (explicit | repository-resolvable | assumption | blocking); each requirement registers evidence expectations across static/behavior/Mock/real-integration (required | optional | not-applicable), and UI-visible or interactive requirements register a non-blocking frontend-test handoff intent. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, also append the openspec classification and one final fenced frontend-openspec-selection-v1 JSON object. No file writes.",
+                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal / record_openspec_selection, then call finalize_contract exactly once. Requirements use stable REQ/BR/AC identifiers with source spans and a disposition (explicit | repository-resolvable | assumption | blocking); each requirement registers evidence expectations across static/behavior/Mock/real-integration (required | optional | not-applicable), and UI-visible or interactive requirements register a non-blocking frontend-test handoff intent. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, classify only the ones you actually use: call record_openspec_selection once per required/relevant path; never enumerate irrelevant candidates (unmentioned defaults to irrelevant) and never emit a fenced selection JSON. No file writes.",
                 subtask_prompt: [
                     "Read task source and produce a concise frontend implementation contract as typed requirement facts plus narrative Markdown.",
                     "Assign each requirement a stable REQ/BR/AC identifier and a source span (task-source section or repository file:line). Label each requirement's disposition as explicit | repository-resolvable | assumption | blocking; a blocking requirement must name its owner (human-decision or external-state) and evidence refs.",
@@ -2938,8 +2938,8 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "If the task is too large for one bounded writer, record a task split proposal instead of silently widening scope.",
                     "End the contract with a single disposition: ready, ready-with-assumptions (bounded assumptions that do not change product behavior), or blocked.",
                     ...(requiresOpenspecClassification ? [
-                        "Classify every generation-frozen OpenSpec candidate while contracting: required must be read and cited by the plan; relevant may inform planning but is not forced; irrelevant is out of scope. mandatoryPaths MUST be required and cannot be downgraded.",
-                        "After the Markdown contract, append exactly one fenced json object with schemaVersion 1, schemaId frontend-openspec-selection-v1, and selections [{path,disposition,rationale}]. No other JSON fences.",
+                        "Classify OpenSpec candidates incrementally while contracting — only the ones you actually use. Call record_openspec_selection once per path with disposition required (must be read and cited by the plan) or relevant (may inform planning). Never call it for irrelevant candidates and never list them: candidates you do not mention are treated as irrelevant by the runtime. Explicit task declarations / source citations are already required and must-read regardless; you never need to re-declare them.",
+                        "Mandatory paths are enforced by the runtime from the frozen task configuration — do not enumerate them, do not downgrade them.",
                         openspecSelectionContext,
                     ] : []),
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
@@ -2982,13 +2982,14 @@ async function buildFrontendHybridDagFromTask(sources) {
                     retryOnInvalid: true,
                     skeleton: frontendContractSkeleton,
                 },
-                outputContract: "Short Markdown narrative plus incremental typed plan record tools (record_target_surface / record_component_choice / record_state_flow / record_data_flow / record_mock_api / record_design_deviation / record_dependency) and exactly one finalize_plan terminal call. finalize_plan assembles the canonical editable patch from committed facts (requirements / verificationTargets / evidenceGaps / implementationSteps / residualRisks / realIntegrationGap). Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. The runtime compiles facts ⊕ skeleton into canonical full-contract JSON for downstream review. No file writes.",
+                outputContract: "Short Markdown narrative plus incremental typed plan record tools (record_target_surface / record_component_choice / record_state_flow / record_data_flow / record_mock_api / record_design_deviation / record_dependency / record_plan_requirement / record_plan_verification_target / record_plan_evidence_gap) and exactly one finalize_plan terminal call. finalize_plan assembles the canonical editable patch from the committed ledger facts (requirements / verificationTargets / evidenceGaps / residualRisks / realIntegrationGap). Commit requirements and verification targets incrementally — one entry per record call — so the plan never needs a single large output; evidence gaps are optional and only needed for genuine gaps. Implementation steps are NOT part of the plan — the implementer designs its own ordering. Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. The runtime compiles facts ⊕ skeleton into canonical full-contract JSON for downstream review. No file writes.",
                 subtask_prompt: [
                     "Use frontend-contract-pi typed requirement facts (stable REQ/BR/AC identifiers, dispositions, evidence expectations, and frontend-test handoff intents), frontend-scout-pi, task sources, and the generation-time Mock capability evidence to fill the runtime-owned frontend contract skeleton. Record the plan decision ledger through the incremental record_* tools, then call finalize_plan exactly once. The runtime already owns schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff; omit those protected paths even when their values look obvious.",
+                    "Commit requirements with record_plan_requirement (one entry per call) and verification targets with record_plan_verification_target (one entry per call). Evidence gaps are optional — call record_plan_evidence_gap only for genuine gaps. Never bundle these into finalize_plan arguments — finalize_plan only closes the plan. Splitting one entry per call keeps every single output small. Do NOT plan implementation steps: the implementer decides ordering itself.",
                     ...(requiresOpenspecClassification ? ["Additionally consume the frontend-contract-pi openspec classification. Successfully read every required selection (including mandatory paths) and declare any used component specReference in the typed decision ledger; relevant/irrelevant selections are not forced into the ledger unless the plan actually uses them."] : []),
                     "The incremental record_* facts become the complete implementation plan after deterministic merge with the protected skeleton. Do not treat leftover JSON in the narrative as the compile authority.",
                     "Select the Mock / API strategy only through record_mock_api. Encode endpoint/fixture mapping, explicit activation, verification commands, and Real Integration Gap in schema-defined fields; productionDefaultOff comes from the protected skeleton and there is no second plan output.",
-                    "Encode ordered steps (implementationSteps), target files, UI state handling, styling/component strategy (stylingStrategy), interaction notes, Mock/API strategy, dependency policy (dependencyPolicy), deterministic verification entrypoints, Real Integration Gap (realIntegrationGap), and residual risks (residualRisks) into the ledger payload. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
+                    "Encode target files, UI state handling, styling/component strategy (stylingStrategy), interaction notes, Mock/API strategy, dependency policy (dependencyPolicy), deterministic verification entrypoints, Real Integration Gap (realIntegrationGap), and residual risks (residualRisks) into the ledger payload. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
                     "Every target file and verification target must be selected from the current target workspace and task scope. Do not reuse paths or symbols from examples, prior tasks, or loop-agent itself; if the project uses app/, packages/, spec/, __tests__, or another layout, preserve that layout.",
                     "Consume the Scout target surface and design evidence before selecting files. Preserve the discovered existing entrypoint and data source. If implementationPaths or testPaths are outside task allowedPaths, record a blocking scope conflict; do not substitute a new page or silently broaden the writeSet.",
                     "Output a short Markdown narrative, record the incremental facts, then call finalize_plan exactly once. Do NOT emit protected skeleton fields or a full contract as the authority.",
@@ -3234,6 +3235,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 executor: "pi",
                 complexity: "HIGH",
                 writePolicy: "read-only",
+                retryPolicy: FRONTEND_REVIEW_TERMINAL_RETRY_POLICY,
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_REVIEW_SKILLS,

package/dist/workflows/dag/node-execution.js

@@ -228,6 +228,16 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
         ].join("\n");
     }
+    if (previousFailureCategory === "review-terminal-missing") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The review emitted a verdict in response text but never committed the authoritative typed terminal tool call (approve_review / request_review_changes). The response text is NOT the authority: no branch or gate reads it.",
+            "Call exactly one typed terminal tool to finish: approve_review (implementation passes, no Critical/Important findings) or request_review_changes (with typed issueCategory, at least one evidenceRef, and non-empty findings). Do not repeat the review analysis; commit the terminal tool once and stop.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {

package/dist/workflows/dag/retry-policy.js

@@ -25,6 +25,13 @@ export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
 /** Provider stopReason=length truncated the response before the JSON contract completed. */
 export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
+/**
+ * The review node emitted a verdict in response text (e.g. "VERDICT: pass")
+ * but never committed the authoritative typed terminal tool call
+ * (approve_review / request_review_changes). Read-only and safe to retry with
+ * a corrected instruction; the typed terminal is the only authority.
+ */
+export const REVIEW_TERMINAL_MISSING_RETRY_CATEGORY = "review-terminal-missing";
 /** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
 export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
 /** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
@@ -57,6 +64,7 @@ export const ALL_DAG_RETRY_CATEGORIES = [
     WRITER_EMPTY_DIFF_RETRY_CATEGORY,
     INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
     WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,
+    REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
 ];
 const RETRY_SAFE_PI_ROLES = new Set([
     "planner",
@@ -143,6 +151,20 @@ export const PROTOCOL_AWARE_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [...PROTOCOL_AWARE_DAG_RETRY_CATEGORIES],
 };
+/**
+ * frontend-review-pi retry policy. The review verdict must be committed
+ * through the typed terminal tools (approve_review / request_review_changes);
+ * a model that only echoes "VERDICT: pass" text fails as
+ * review-terminal-missing. That is read-only and safe to retry with a
+ * corrected instruction so a single model slip does not burn the whole run.
+ */
+export const FRONTEND_REVIEW_TERMINAL_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
+    ],
+};
 /**
  * The sole writer retry policy for requireChangedFiles writers. It is
  * intentionally not included in any read-only default: a writer may retry only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-beta.3",
+  "version": "0.39.0-beta.5",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",