@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.2

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.39.0-beta.0",
-  "gitSha": "cf0cf7e8e996da8d1c727ccc7cb8f4c52f8d5319",
-  "builtAt": "2026-08-21T03:47:18.913Z"
+  "version": "0.39.0-beta.2",
+  "gitSha": "cf766ed6e83a3498e13744ffd944ac10d7b1aeca",
+  "builtAt": "2026-08-21T07:43:32.268Z"
 }

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

@@ -41,9 +41,6 @@ export function serializeDeterministicJson(value) {
 export function deterministicSha256(value) {
     return sha256Hex(serializeDeterministicJson(value));
 }
-/** Provider-safe limits for the two planner outputs. Larger work must split. */
-export const FRONTEND_PLAN_RESPONSE_MAX_BYTES = 14 * 1024;
-export const FRONTEND_CANONICAL_CONTRACT_MAX_BYTES = 16 * 1024;
 /** A contract materialization failure carries its classification plus the
  * audit context collected up to the failure point, so the prewrite gate can
  * persist a complete frontend-prewrite-result-v1 even when the canonical
@@ -1718,8 +1715,13 @@ async function dropUnresolvedVerificationSymbols(input) {
     }
     return changed;
 }
-function extractSingleOpenspecCitationsBlock(text) {
-    const blocks = text.match(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g) ?? [];
+function extractSingleOpenspecCitationsBlock(text, citationsRequired = true) {
+    const blocks = [...text.matchAll(/^```openspec-citations[ \t]*\r?\n([\s\S]*?)^```[ \t]*$/gim)].map((match) => match[0]);
+    if (!citationsRequired) {
+        if (blocks.length === 0)
+            return "";
+        throw new Error("frontend plan output must not include an openspec-citations block when the generation-frozen OpenSpec candidate set is empty");
+    }
     if (blocks.length !== 1) {
         throw new Error(`frontend plan patch output must include exactly one fenced openspec-citations block (found ${blocks.length})`);
     }
@@ -1731,8 +1733,8 @@ function extractSingleOpenspecCitationsBlock(text) {
  * separate so a citation row can never become a competing contract candidate.
  * A bare JSON payload is retained only for historical node-output compatibility.
  */
-export function extractFrontendPlanPayload(text) {
-    const citationsBlock = extractSingleOpenspecCitationsBlock(text);
+export function extractFrontendPlanPayload(text, options) {
+    const citationsBlock = extractSingleOpenspecCitationsBlock(text, options?.citationsRequired !== false);
     return {
         payload: extractFrontendPlanPrimaryPayload(text.replace(citationsBlock, "")),
         citationsBlock,
@@ -1796,21 +1798,20 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
         });
     };
     try {
-        if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
-            throw new Error(`frontend plan response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`);
-        }
         if (!input.sourceBinding)
             throw new Error("frontend plan patch validator requires DAG sourceBinding");
         const skeleton = input.structuredContractOutput?.skeleton;
         if (!skeleton)
             throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
+        // Preserve the raw primary candidate even if the separately parsed
+        // citation fence is malformed; the retry report is an audit artifact.
         const patch = extractFrontendPlanPrimaryPayload(input.text);
         if (!isPlainObject(patch))
             throw new Error("frontend plan patch must extract to one JSON object");
         extractedPatchPath = path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`);
         const extractedArtifact = await writeDeterministicJsonArtifact(input.runDir, extractedPatchPath, patch);
         extractedPatchSha256 = extractedArtifact.sha256;
-        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text, input.structuredContractOutput?.citationsRequired !== false);
         const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
         await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
         const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
@@ -1826,10 +1827,6 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
         });
-        if (Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8") >
-            FRONTEND_CANONICAL_CONTRACT_MAX_BYTES) {
-            throw new Error(`frontend canonical contract exceeds the ${FRONTEND_CANONICAL_CONTRACT_MAX_BYTES}-byte limit; split the task`);
-        }
         const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
         await writeReport({
             classification: "accepted-normalized",
@@ -1907,9 +1904,10 @@ export async function validateFrontendContractNodeOutput(input) {
 /**
  * Node-output self-check for the plan revision node, which emits an RFC 7386
  * merge-patch delta against the original contract instead of a full contract.
- * Deliberately loose and format-level: the output must contain exactly one
- * ```openspec-citations fenced block and must extract (after the citations
- * blocks are stripped) to exactly one JSON object. The delta carries no
+ * Deliberately loose and format-level: when OpenSpec candidates exist, the
+ * output contains exactly one ```openspec-citations fenced block; otherwise it
+ * contains no citation fence. It must extract (after the citations block is
+ * stripped) to exactly one JSON object. The delta carries no
  * schemaVersion/targets, so no full-contract schema/semantic checks run here;
  * content parsing, patch application, and merged-contract validation stay with
  * the prewrite gate, which remains the only authority.
@@ -1924,16 +1922,12 @@ export async function validateFrontendRevisionPatchNodeOutput(input) {
         attempt,
         text: input.text,
     });
-    if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
-        return {
-            ok: false,
-            reason: `frontend revision response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`,
-        };
-    }
     let citationsBlock;
     let patch;
     try {
-        const parsed = extractFrontendPlanPayload(input.text);
+        const parsed = extractFrontendPlanPayload(input.text, {
+            citationsRequired: input.structuredContractOutput?.citationsRequired,
+        });
         citationsBlock = parsed.citationsBlock;
         patch = parsed.payload;
     }

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

@@ -4,15 +4,13 @@ import { z } from "zod";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
 import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { countExcludedGovernanceSpecFiles, resolveOpenspecGovernanceRoot, } from "../../task/frontend-project-capability.js";
-import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, FRONTEND_CANONICAL_CONTRACT_MAX_BYTES, applyFrontendImplementationContractPatch, extractFrontendImplementationJson, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
+import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, applyFrontendImplementationContractPatch, extractFrontendImplementationJson, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
 import { captureFrontendWorktreeBaseline } from "./frontend-worktree-diff.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { normalizeVerdictCandidateLine } from "./dynamic-runtime/shared.js";
 export const FRONTEND_PREWRITE_RESULT_SCHEMA_ID = "frontend-prewrite-result-v1";
 export const FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME = "frontend-prewrite-result.json";
-/** Canonical contract serialization must stay at or below this byte size. */
-export const FRONTEND_CONTRACT_MAX_BYTES = FRONTEND_CANONICAL_CONTRACT_MAX_BYTES;
 /**
  * Machine-readable failure classification for blocked/retryable-invalid
  * prewrite outcomes. Kept alongside the human-readable failureReason so
@@ -39,7 +37,6 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "component-spec-reference-invalid",
     "component-spec-not-cited",
     "component-choices-missing",
-    "contract-too-large",
     "revision-patch-unmergeable",
 ]);
 export const frontendPrewriteResultV1Schema = z
@@ -732,21 +729,6 @@ export async function runFrontendPrewriteGate(input) {
         }
         throw error;
     }
-    // Size guard: a canonical contract above 64KB is a retryable-invalid defect
-    // (compress the contract) rather than a writer authorization failure.
-    const contractSizeBytes = Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8");
-    if (contractSizeBytes > FRONTEND_CONTRACT_MAX_BYTES) {
-        return finalizePrewrite(input, {
-            ...basePending,
-            verdict,
-            candidateJsonSha256: analysis.candidateJsonSha256,
-            normalizationActions: [],
-            mockStrategy: analysis.canonical.mockApi.strategy,
-            classification: "retryable-invalid",
-            failureReason: `frontend prewrite gate: canonical contract serialization is ${contractSizeBytes} bytes, exceeding the ${FRONTEND_CONTRACT_MAX_BYTES}-byte limit. 压缩契约（移除冗余 prose、重复目标或过长描述）后重试。`,
-            failureCode: "contract-too-large",
-        });
-    }
     const mockStrategy = analysis.canonical.mockApi.strategy;
     if (!input.config.allowedMockStrategies.includes(mockStrategy)) {
         const quotedAllowed = input.config.allowedMockStrategies

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

@@ -1530,6 +1530,21 @@ function buildSourceContextBlock(sources) {
     }
     return parts.join("\n\n");
 }
+/**
+ * Planner/reviewer nodes already receive the contract/scout artifacts. They
+ * only need stable task-source pointers for an unresolved or conflicting
+ * field, not a second inline copy of every fact-source document.
+ */
+function buildArtifactFirstSourceAccessBlock(sources) {
+    const binding = buildDagSourceBinding(sources);
+    return [
+        "## Bound task-source access (read only when upstream artifacts are missing or conflict)",
+        ...binding.sources.map((source) => `- ${source.kind}: ${source.path}`),
+        "Use these exact repository-readable paths. Do not search for substitutes or read runtime implementation code to diagnose a format retry.",
+        `- taskId: ${binding.taskId}`,
+        `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none)"}`,
+    ].join("\n");
+}
 async function loadMaterializedSourceReferences(sourceDir) {
     const referenceDir = path.join(sourceDir, REFERENCE_DIRECTORY);
     const referencePaths = [];
@@ -2523,7 +2538,8 @@ async function buildFrontendHybridDagFromTask(sources) {
         "Emit only editable fields: requirements[], implementationSteps[], targets.routes/publicApiChanges, uiStates[], interactions[], mockApi.strategy/activation/endpoints, verificationTargets[], designEvidence, evidenceGaps[], stylingStrategy, uiComponentChoices[], dependencyPolicy, residualRisks[], realIntegrationGap.",
         "Protected and forbidden: schemaVersion, sourceBinding, riskLevel, targets.files, mockApi.productionDefaultOff, schemaId, targetFiles, requirementCoverage.",
         "Invariants: every requirement has expectedOutcome; every interaction has trigger + expectedBehavior; applicable uiStates have expectedBehavior + implementationTargets + verificationTargetIds; non-applicable uiStates have notApplicableReason; commandLabel is frozen; mockApi production default remains off.",
-        "Enums: mock strategy native|browser-intercept|request-adapter|not-needed; uiComponentChoices decision specified|reuse-existing|new. Omit optional empty strings and unchanged revision fields.",
+        "Each behavior belongs to one primary row: requirements cover acceptance, uiStates cover only distinct visible states, and interactions cover only distinct user triggers. Link with IDs; do not restate the same prose in all three. Steps are action plus files, not a prose mirror. Omit optional fields when upstream contract/scout facts already settle them, and omit unchanged revision fields.",
+        "Enums: mock strategy native|browser-intercept|request-adapter|not-needed; uiComponentChoices decision specified|reuse-existing|new. Omit optional empty strings.",
     ].join("\n");
     const sourceContext = [
         buildSourceContextBlock(sources),
@@ -2531,24 +2547,20 @@ async function buildFrontendHybridDagFromTask(sources) {
     ]
         .filter(Boolean)
         .join("\n\n");
+    const artifactFirstSourceContext = [
+        buildArtifactFirstSourceAccessBlock(sources),
+        capabilityContextBlock,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
     const hasMockVerifyCommands = (taskConfig.frontendMock?.verifyCommands.length ?? 0) > 0 ||
         mockCapability.verifyCommands.length > 0;
     const requirementIds = frontendSourceBinding.requirementIds;
     const requirementCoverageInstruction = requirementIds.length > 0
         ? [
-            `## Requirement Coverage (per-AC echo with bad/good examples)`,
-            `For each requirement ID below, echo the ID verbatim and confirm: expectedOutcome (user-observable or logic-observable), implementation targets (files), and verification targets (commandLabel + file).`,
-            `Do not skip any ID. Use the bad/good patterns below as reference for each field.`,
-            ``,
-            `Bad example (empty expectedOutcome, empty targets -- REJECTED at contract materialization):`,
-            `- AC-001: expectedOutcome="" implementationTargets=[] verificationTargets=[]`,
-            ``,
-            `Good example (concrete expectedOutcome, real files, real verification targets):`,
-            `- AC-001: expectedOutcome="TypeScript compilation exits with code 0 and produces no errors in dist/" implementationTargets=["src/app.tsx"] verificationTargets=["vt-typecheck":"npm run typecheck","tsconfig.json"]`,
-            ``,
-            ...requirementIds.map((id) => `- ${id}: [expectedOutcome] [implementation files] [verification targets]`),
-            ``,
-            `Every requirement MUST have a non-empty expectedOutcome. Every interaction MUST have non-empty trigger and expectedBehavior. UI states with applicable=true MUST have non-empty expectedBehavior. Empty strings or omitted fields for these will cause contract rejection.`,
+            "## Requirement Coverage",
+            `Cover each frozen ID exactly once in requirements[]: ${requirementIds.join(", ")}. Each item needs a concrete expectedOutcome, implementationTargets, and verificationTargetIds.`,
+            "Interactions need trigger + expectedBehavior; applicable uiStates need expectedBehavior + implementationTargets + verificationTargetIds. Do not use empty strings.",
         ].join("\n")
         : "";
     const verificationTargetFileInstruction = [
@@ -2562,6 +2574,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         "Before producing this contract/plan, use the Pi read tool to read the FULL bound source files (需求.md, 执行约束.md, and every `references/*` Bound readPath listed above) — the inline copies above may be truncated excerpts, and requirement/acceptance references are authoritative only in their full form.",
         "Do not drop scope fields, acceptance criteria, non-goals, UI states, or column/field definitions that exist in the full sources but are absent from the inline excerpts; if a field appears in the full source, it belongs in the contract.",
     ].join("\n");
+    const plannerSourceReadInstruction = [
+        "## Source-read policy",
+        "Use frontend-contract-pi and frontend-scout-pi artifacts as primary evidence. Do not repeat reads that those facts already settle.",
+        "Read a bound source only to resolve a missing or conflicting field; read every applicable OpenSpec candidate directly before citing it. Never infer omitted task fields from a preview.",
+    ].join("\n");
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -2710,6 +2727,17 @@ async function buildFrontendHybridDagFromTask(sources) {
         ...(classified?.theme ?? []),
         ...(classified?.rule.components ?? []),
     ].filter((value, index, array) => array.indexOf(value) === index).sort();
+    const frontendPlanCitationsRequired = openspecGate.openspecCandidatePaths.length > 0 ||
+        componentSpecCandidatePaths.length > 0;
+    const frontendPlanCitationInstruction = frontendPlanCitationsRequired
+        ? openspecCitationInstruction
+        : "The generation-frozen OpenSpec/component candidate set is empty. Do not read, cite, or emit an openspec-citations fence; output only the primary JSON patch. The runtime records an empty citation artifact deterministically.";
+    const frontendPlanOutputContract = frontendPlanCitationsRequired
+        ? "JSON-only patch output: exactly ONE fenced json object (```json ... ```) containing only the editable RFC 7386 plan patch for the runtime contract skeleton, immediately followed by exactly one ```openspec-citations``` fenced citation block. Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. The runtime applies the patch, validates it, and promotes canonical full-contract JSON for downstream review. Do NOT emit a full contract, Markdown plan explanation, raw JSON, or any other fenced block. No file writes."
+        : "JSON-only patch output: exactly ONE fenced json object (```json ... ```) containing only the editable RFC 7386 plan patch for the runtime contract skeleton. The generation-frozen OpenSpec candidate set is empty, so do NOT emit an openspec-citations fence. Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. The runtime applies the patch, validates it, and promotes canonical full-contract JSON for downstream review. Do NOT emit a full contract, Markdown plan explanation, raw JSON, or any other fenced block. No file writes.";
+    const frontendRevisionOutputContract = frontendPlanCitationsRequired
+        ? "When the initial design review requests revision, return exactly ONE fenced json object (```json ... ```) containing an RFC 7386 merge-patch delta against the original frontend-implementation-contract-v1 (only the fields you change; null deletes a key; arrays and scalars replace; plain objects merge recursively), immediately followed by exactly one ```openspec-citations``` fenced citation block. Do NOT emit a full contract, Markdown explanation, or prose — the output is JSON-only; the gate applies the patch on the original contract and renders plan.md deterministically. Apart from the patch JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes."
+        : "JSON-only output: when the initial design review requests revision, return exactly ONE fenced json object (```json ... ```) containing an RFC 7386 merge-patch delta against the original frontend-implementation-contract-v1 (only the fields you change; null deletes a key; arrays and scalars replace; plain objects merge recursively). The generation-frozen OpenSpec candidate set is empty, so do NOT emit an openspec-citations fence. Do NOT emit a full contract, Markdown explanation, prose, or another fenced block. No file writes.";
     if (openspecGate.openspecPolicy === "cited") {
         if (openspecGate.openspecCandidatePaths.length === 0) {
             advisories.push("openspec 策略 cited：契约声明的 requiredReadPaths 与任务源引用均为空，prewrite gate 不强制读取 openspec；如需增强规范门禁，请在 task.json.frontendOpenspec.requiredReadPaths 声明必读路径或在任务源中显式引用 openspec 文件。");
@@ -2795,11 +2823,12 @@ async function buildFrontendHybridDagFromTask(sources) {
                     schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
                     retryOnInvalid: true,
                     skeleton: frontendContractSkeleton,
+                    citationsRequired: frontendPlanCitationsRequired,
                 },
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: [],
-                outputContract: "JSON-only patch output: one-line lead-in, then exactly ONE fenced json object (```json ... ```) containing only the editable RFC 7386 plan patch for the runtime contract skeleton. Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. The runtime applies the patch, validates it, and promotes canonical full-contract JSON for downstream review. Do NOT emit a full contract, Markdown plan explanation, raw JSON, or any other fenced block. No file writes.",
+                outputContract: frontendPlanOutputContract,
                 subtask_prompt: [
                     "Use frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence to fill the runtime-owned frontend contract skeleton. Return JSON-only output containing only an editable RFC 7386 plan patch. The runtime already owns schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff; omit those protected paths even when their values look obvious.",
                     "The patch fields become the complete implementation plan after deterministic merge. Do not produce a separate plan document, prose mirror, or full contract.",
@@ -2807,19 +2836,22 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "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 contract JSON fields. 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 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 in this exact order: (1) exactly one fenced json object containing the editable plan patch; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit protected skeleton fields, a full contract, Markdown plan explanation, raw JSON, or any other fenced block.",
+                    frontendPlanCitationsRequired
+                        ? "Output exactly two adjacent blocks: (1) one fenced json object containing the editable plan patch; (2) one openspec-citations citation block."
+                        : "Output exactly one fenced json object containing the editable plan patch; do not emit an openspec-citations block.",
+                    "Do NOT emit protected skeleton fields, a full contract, Markdown plan explanation, raw JSON, or any other fenced block.",
                     "Each requirement must state its user-observable or logic-observable expectedOutcome. Each interaction must state its trigger and expectedBehavior. IDs plus file paths are not sufficient behavior semantics.",
                     requirementCoverageInstruction,
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     verificationTargetFileInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
-                    mandatorySourceReadInstruction,
+                    plannerSourceReadInstruction,
                     fixedVerificationContext,
-                    sourceContext,
+                    artifactFirstSourceContext,
                     mockContextBlock,
                     frontendPlanFieldGuide,
                     frontendComponentConformanceInstruction,
-                    openspecCitationInstruction,
+                    frontendPlanCitationInstruction,
                 ].join("\n\n"),
             },
             {
@@ -2843,7 +2875,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Component selection conformance is a hard blocking condition: VERDICT: request-revision when the frontend spec (component/theme/rule.components bucket) already defines a component for a purpose but the plan selects another or self-invents one without a declared deviation; when uiComponentChoices is missing/empty for UI-visible work while the frozen component/theme bucket is non-empty; or when any uiComponentChoices specReference.path is not cited in the openspec-citations block or has no successful read event.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
-                    sourceContext,
+                    artifactFirstSourceContext,
                     frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),
@@ -2862,28 +2894,32 @@ async function buildFrontendHybridDagFromTask(sources) {
                 structuredContractOutput: {
                     schemaId: "frontend-implementation-contract-revision-patch-v1",
                     retryOnInvalid: true,
+                    citationsRequired: frontendPlanCitationsRequired,
                 },
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: [],
-                outputContract: "When the initial design review requests revision, return a one-line lead-in followed by exactly ONE fenced json object (```json ... ```) containing an RFC 7386 merge-patch delta against the original frontend-implementation-contract-v1 (only the fields you change; null deletes a key; arrays and scalars replace; plain objects merge recursively). Immediately after it, append exactly one ```openspec-citations``` fenced citation block. Do NOT emit a full contract, Markdown explanation, or prose — the output is JSON-only; the gate applies the patch on the original contract and renders plan.md deterministically. Apart from the patch JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
+                outputContract: frontendRevisionOutputContract,
                 subtask_prompt: [
-                    "Consume frontend-plan-pi (original contract JSON) and frontend-design-review-pi (first design review findings).",
+                    "Consume the hash-bound frontend-plan-pi contract artifact and frontend-design-review-pi findings. Read the artifact only for fields affected by a Required Plan Correction.",
                     "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce an RFC 7386 merge-patch delta against the original contract JSON that addresses every Required Plan Correction from the design findings.",
                     "The patch delta may update editable contract fields such as requirements, implementationSteps, targets.routes/publicApiChanges, uiStates, interactions, mockApi.strategy/activation/endpoints, dependencyPolicy, stylingStrategy, uiComponentChoices, verificationTargets, evidenceGaps, residualRisks, and realIntegrationGap. It must not modify protected schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff. Only include fields you change; omit unchanged fields (the gate applies the patch on the original contract). null deletes a key; arrays and scalars replace; plain objects merge recursively.",
-                    requirementCoverageInstruction,
+                    "Only include changed fields. For a changed requirement, preserve its expectedOutcome, implementationTargets, and verificationTargetIds; do not resend unchanged requirements.",
                     "Do not turn MOCK_STRATEGY: blocked into an implementable strategy without new repository or contract evidence that resolves every blocker.",
                     "Read-only: do not modify code, docs, artifacts, or repository files. This node revises the plan only.",
-                    "Output in this exact order: (1) exactly one fenced json object containing the merge-patch delta — this is the only plan output the prewrite gate applies on the original contract; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit a full contract, Markdown explanation, or prose — the output is JSON-only. Do not emit any raw JSON or JSON objects in prose. Apart from the patch JSON fenced block and the openspec-citations block, do not emit any other fenced block. Do not include secrets or unsafe paths.",
+                    frontendPlanCitationsRequired
+                        ? "Output exactly two adjacent blocks: (1) one fenced json object containing the merge-patch delta; (2) one openspec-citations citation block."
+                        : "JSON-only: output exactly one fenced json object containing the merge-patch delta; do not emit an openspec-citations block.",
+                    "Do NOT emit a full contract, Markdown explanation, prose, raw JSON or JSON objects outside the fenced payload, secrets, or unsafe paths.",
                     "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the effective (merged) contract; do not reduce behavior semantics to IDs and paths.",
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     verificationTargetFileInstruction,
                     fixedVerificationContext,
-                    sourceContext,
+                    artifactFirstSourceContext,
                     frontendPlanFieldGuide,
                     mockContextBlock,
                     frontendComponentConformanceInstruction,
-                    openspecCitationInstruction,
+                    frontendPlanCitationInstruction,
                 ].join("\n\n"),
             },
             {
@@ -2918,7 +2954,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Also request revision for component selection non-conformance: spec-defined components silently replaced or self-invented without a declared deviation, uiComponentChoices missing for UI-visible work, or a uiComponentChoices specReference.path not cited in the openspec-citations block / not actually read.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
-                    sourceContext,
+                    artifactFirstSourceContext,
                     frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),

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

@@ -129,17 +129,24 @@ export function buildNodePrompt(spec, task, upstream, options) {
         convergenceFeedback: options?.convergenceFeedback,
     });
 }
-function frontendStructuredArtifactRetryGuidance(schemaId) {
+function frontendStructuredArtifactRetryGuidance(schemaId, citationsRequired = true) {
+    const format = citationsRequired
+        ? "one fenced json block immediately followed by one fenced openspec-citations block"
+        : "one fenced json block and no openspec-citations block";
     if (schemaId === "frontend-implementation-contract-plan-patch-v1") {
         return [
-            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by exactly one fenced openspec-citations block.",
+            citationsRequired
+                ? "Return exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by one fenced openspec-citations block, and nothing else."
+                : `Return exactly ${format} and nothing else; the json block contains only the editable RFC 7386 plan patch.`,
             "The runtime applies your patch to its protected contract skeleton. Do not emit schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff; do not emit the full contract.",
             "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
         ];
     }
     if (schemaId === "frontend-implementation-contract-revision-patch-v1") {
         return [
-            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by exactly one fenced openspec-citations block.",
+            citationsRequired
+                ? "Return exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by one fenced openspec-citations block, and nothing else."
+                : `Return exactly ${format} and nothing else; the json block contains the RFC 7386 merge-patch delta.`,
             "The delta contains only the fields you change; null deletes a key, arrays and scalars replace, and plain objects merge recursively. Do not emit a full contract or a schemaVersion/targets section.",
             "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
         ];
@@ -149,6 +156,27 @@ function frontendStructuredArtifactRetryGuidance(schemaId) {
         "The contract JSON fields are the complete implementation plan. Do not emit a separate plan document, Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
     ];
 }
+function isFrontendPlanArtifactSchema(schemaId) {
+    return (schemaId === "frontend-implementation-contract-plan-patch-v1" ||
+        schemaId === "frontend-implementation-contract-revision-patch-v1");
+}
+function buildFrontendPlanArtifactRecoveryPrompt(options) {
+    const cause = options.failure === "truncated"
+        ? "Previous response was truncated by the provider (stopReason=length)."
+        : options.failure === "too-large"
+            ? "Previous response could not be retained by the provider."
+            : "Previous response failed structured validation.";
+    return [
+        "<retry_instruction>",
+        cause,
+        options.reason ? `Validation error: ${options.reason}` : "",
+        ...frontendStructuredArtifactRetryGuidance(options.schemaId, options.citationsRequired),
+        "Use concise values and reference paths/IDs instead of copying source prose. Do not omit required semantics.",
+        "</retry_instruction>",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
 function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
     if (attemptNumber <= 1)
         return basePrompt;
@@ -164,6 +192,14 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {
+        if (isFrontendPlanArtifactSchema(task.structuredContractOutput.schemaId)) {
+            return buildFrontendPlanArtifactRecoveryPrompt({
+                failure: "invalid",
+                reason: previousProtocolReason,
+                schemaId: task.structuredContractOutput.schemaId,
+                citationsRequired: task.structuredContractOutput.citationsRequired,
+            });
+        }
         return [
             basePrompt,
             "",
@@ -178,22 +214,13 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     if (previousFailureCategory === "structured-output-truncated" &&
         task.structuredContractOutput) {
         const schemaId = task.structuredContractOutput.schemaId;
-        if (schemaId === "frontend-implementation-contract-plan-patch-v1" ||
-            schemaId === "frontend-implementation-contract-revision-patch-v1") {
-            const payloadKind = schemaId === "frontend-implementation-contract-plan-patch-v1"
-                ? "editable plan patch"
-                : "RFC 7386 revision patch";
-            return [
-                "<retry_instruction>",
-                "Previous response was truncated (stopReason=length).",
-                previousProtocolReason ? `Validation error: ${previousProtocolReason}` : "",
-                `Return one short lead-in, one complete fenced json ${payloadKind}, then one fenced openspec-citations block.`,
-                "Protected: schemaVersion, sourceBinding, riskLevel, targets.files, mockApi.productionDefaultOff. Required semantics: requirement expectedOutcome; interaction trigger + expectedBehavior; frozen verification command labels.",
-                "No prose, examples, schema copy, Markdown headings, raw JSON, or other fences.",
-                "</retry_instruction>",
-            ]
-                .filter(Boolean)
-                .join("\n");
+        if (isFrontendPlanArtifactSchema(schemaId)) {
+            return buildFrontendPlanArtifactRecoveryPrompt({
+                failure: "truncated",
+                reason: previousProtocolReason,
+                schemaId,
+                citationsRequired: task.structuredContractOutput.citationsRequired,
+            });
         }
         return [
             basePrompt,
@@ -271,6 +298,13 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     }
     if (task.outputMode === "structured-required") {
         if (task.structuredContractOutput) {
+            if (isFrontendPlanArtifactSchema(task.structuredContractOutput.schemaId)) {
+                return buildFrontendPlanArtifactRecoveryPrompt({
+                    failure: "too-large",
+                    schemaId: task.structuredContractOutput.schemaId,
+                    citationsRequired: task.structuredContractOutput.citationsRequired,
+                });
+            }
             return [
                 basePrompt,
                 "",

package/dist/workflows/dag/types.js

@@ -782,6 +782,10 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
          * this run-owned skeleton before strict contract validation.
          */
         skeleton: z.record(z.string(), z.unknown()).optional(),
+        /** Frontend plan/revision citation fence is only needed for a
+         * generation-frozen OpenSpec candidate set. Undefined preserves the
+         * historical required-fence protocol. */
+        citationsRequired: z.boolean().optional(),
     })
         .strict()
         .superRefine((value, ctx) => {

package/package.json

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