@tea-agent/loop-agent 0.38.0 → 0.38.1

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

@@ -7,9 +7,10 @@ import { assertValidDagSpec } from "./validate.js";
 import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, DEFAULT_DAG_OUTPUT_LANGUAGE, DEFAULT_DAG_EXECUTOR_MODELS, parseDagSpec, } from "./types.js";
 import { planMavenVerification, } from "../../verification/maven/index.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { extractTaskSourceOpenspecPaths } 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, PROTOCOL_AWARE_PI_RETRY_POLICY, STRUCTURED_REQUIRED_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PLANNER_OUTPUT_LIMIT_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, STRUCTURED_REQUIRED_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate, 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";
@@ -19,6 +20,7 @@ import { applySddEmbeddedEnhancements, probeRepoLocalSddSkills, } from "./sdd-em
 import { discoverProjectGovernancePresence } from "./project-governance-context.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
+import { REQUIREMENT_FACT_ROLES } from "../../task/source-prepare/artifact-meta.js";
 import { observeTaskContract } from "../../task/contract/observe.js";
 import { dagHasWriterExecution } from "./task-contract-binding.js";
 import { DEFAULT_VERIFY_TIMEOUT_MS, resolveVerifyPreset, } from "../../executors/shell-verification.js";
@@ -558,6 +560,39 @@ export function hasApiDependency(sources) {
         .some((clause) => !negationPatterns.some((pattern) => pattern.test(clause)) &&
         dependencyPatterns.some((pattern) => pattern.test(clause)));
 }
+/**
+ * Generation-time heuristic: does the task source mention interface/API/Mock
+ * needs anywhere (requirement or constraints)?
+ *
+ * Mirrors hasApiDependency's clause-level negation filtering so explicit
+ * "not involved / not implementing" clauses and out-of-scope sections do not
+ * become positive evidence. Used to emit a machine-visible advisory when auto
+ * mode narrows Mock to not-needed despite the source mentioning such needs.
+ */
+export function frontendSourceMentionsMock(sources) {
+    const text = [sources.requirementMarkdown, sources.constraintMarkdown]
+        .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        .map((entry) => normalizeTaskRequirementText(entry).replace(/`[^`\n]*`/g, " "))
+        .join("\n");
+    const signalPatterns = [
+        /mock/i,
+        /模拟服务/,
+        /接口桩/,
+        /\bmsw\b/i,
+        /(?<![A-Za-z0-9_])API(?![A-Za-z0-9_])/i,
+        /接口/,
+    ];
+    const negationPatterns = [
+        /(?:不涉及|无需|不需要|不依赖|不调用|不请求|不实现|没有|禁止|不得).{0,16}(?:接口|后端|服务端|远程数据|异步数据|API|mock|模拟|桩)/i,
+        /\b(?:no|without|does\s+not|do\s+not|must\s+not)\b.{0,24}\b(?:api|endpoint|request|backend|server|mock)\b/i,
+    ];
+    return text
+        .split(/[。！？!?；;，,\r\n]+/)
+        .map((clause) => clause.trim())
+        .filter(Boolean)
+        .some((clause) => !negationPatterns.some((pattern) => pattern.test(clause)) &&
+        signalPatterns.some((pattern) => pattern.test(clause)));
+}
 /**
  * Resolve frontend Mock mode from capability seed, task config, and interface dependency analysis.
  *
@@ -1465,11 +1500,27 @@ function buildSourceContextBlock(sources) {
             .relative(path.join(sources.taskDir, "source"), reference.path)
             .replaceAll(path.sep, "/");
         const referenceRef = toDagSourcePath(sources, reference.path);
-        const referenceExcerpt = excerptMarkdown(reference.markdown, {
-            sourceRef: referenceRef,
-        });
-        boundReadPaths.push(`- reference ${relativePath}: ${referenceRef}`);
-        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, referenceExcerpt.text);
+        // Fact-source roles (requirement/acceptance) carry the fields contracts
+        // depend on (AC/scope/columns). Inject them in full so a fixed excerpt
+        // cannot silently drop definitions; archival roles stay excerpted.
+        const isFactRole = reference.role !== undefined &&
+            REQUIREMENT_FACT_ROLES.has(reference.role);
+        const referenceExcerpt = isFactRole
+            ? {
+                text: reference.markdown.trim(),
+                truncated: false,
+                originalChars: reference.markdown.trim().length,
+                maxChars: Number.POSITIVE_INFINITY,
+            }
+            : excerptMarkdown(reference.markdown, {
+                sourceRef: referenceRef,
+            });
+        boundReadPaths.push(`- reference ${relativePath}${isFactRole ? " (full source)" : ""}: ${referenceRef}`);
+        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, ...(isFactRole
+            ? [
+                `Full source injected (role: ${reference.role}) — complete and authoritative; no excerpt truncation applied.`,
+            ]
+            : []), referenceExcerpt.text);
     }
     parts.push("## Bound source read paths", ...boundReadPaths, "Use these repository-readable paths for any Pi read-tool calls. Bound files under `.harness/tasks/<taskId>/source/**` are read-only inputs: reading them is allowed even though writing `.harness/**` is forbidden.", "Never resolve task-relative citations such as `source/需求.md` or `source/references/*` against the repository root, invent `source/<taskId>/...`, search for substitutes, or fall back to `docs/**` when a bound read fails.", "## Task config summary", `- taskId: ${sources.taskConfig.taskId}`, `- flow: ${sources.taskConfig.flow}`, `- complexity: ${sources.taskConfig.complexity}`, `- contextProfile: ${sources.taskConfig.contextProfile}`, `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none — review before execute)"}`, `- forbiddenPaths: ${sources.taskConfig.forbiddenPaths.join(", ") || "(none)"}`, '- Pi DAG nodes are read-only unless toolProfile="write" is explicitly selected for a bounded writer node.', "- Agent DAG read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.", `- Derived execution contract and immutable references live under the Bound source read paths above (not as repo-root \`source/...\`).`);
     if (sources.taskConfig.hardConstraints.length > 0) {
@@ -1507,10 +1558,49 @@ async function loadMaterializedSourceReferences(sourceDir) {
     }
     await collect(referenceDir);
     referencePaths.sort((left, right) => left.localeCompare(right));
-    return Promise.all(referencePaths.map(async (filePath) => ({
-        path: filePath,
-        markdown: await readFile(filePath, "utf-8"),
-    })));
+    const roleByPath = await loadReferenceRoles(sourceDir);
+    return Promise.all(referencePaths.map(async (filePath) => {
+        const relative = path
+            .relative(sourceDir, filePath)
+            .replaceAll(path.sep, "/");
+        const role = roleByPath.get(relative);
+        return {
+            path: filePath,
+            markdown: await readFile(filePath, "utf-8"),
+            ...(role !== undefined ? { role } : {}),
+        };
+    }));
+}
+/**
+ * Reads `source-manifest.json` into a materializedPath → role map so the DAG
+ * generator can tell fact-source references (requirement/acceptance) apart
+ * from archival ones (analysis/clarification/design). A missing or malformed
+ * manifest yields an empty map; such references keep the bounded-excerpt
+ * treatment instead of being injected in full.
+ */
+async function loadReferenceRoles(sourceDir) {
+    const roleByPath = new Map();
+    const manifestPath = path.join(sourceDir, "source-manifest.json");
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf-8");
+    }
+    catch {
+        return roleByPath;
+    }
+    try {
+        const manifest = JSON.parse(raw);
+        for (const document of manifest.documents ?? []) {
+            if (typeof document.materializedPath === "string" &&
+                typeof document.role === "string") {
+                roleByPath.set(document.materializedPath.replaceAll(path.sep, "/"), document.role);
+            }
+        }
+    }
+    catch {
+        // A malformed manifest must never break reference injection.
+    }
+    return roleByPath;
 }
 export async function loadTaskHybridSources(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
@@ -2111,6 +2201,7 @@ function resolveFrontendMockContextBlock(sources) {
         parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
         if (frontendMockStrategyMustBeNotNeeded(sources)) {
             parts.push('Auto mode has no confirmed project Mock capability or no deterministic Mock verification command. The structured contract must set mockApi.strategy to "not-needed". Do not add Mock files or dependencies; keep the real request path as default and record any unproved backend behavior as Real Integration Gap.');
+            parts.push('HARD CONSTRAINT (frozen at generation time): this DAG allows only mockApi.strategy "not-needed"; the prewrite gate rejects any other strategy. If project governance (openspec / ai_workspace / decision records, e.g. a DEC rule requiring native) demands Mock-backed verification, that is a generation-time contract gap, not a plan-revision defect: declare frontendMock.verifyCommands (or policy: "required") in task.json and regenerate the DAG. Do not emit any mockApi.strategy outside the allowlist and do not add Mock files or dependencies within this run.');
         }
     }
     if (mode === "blocked") {
@@ -2129,6 +2220,41 @@ function frontendMockStrategyMustBeNotNeeded(sources) {
             capabilityStatus === "ambiguous" ||
             !hasDeterministicMockVerification));
 }
+function resolveFrontendOpenspecGateConfig(sources) {
+    const taskConfig = sources.taskConfig;
+    const policy = taskConfig.frontendOpenspec?.policy ?? "cited";
+    const declared = taskConfig.frontendOpenspec?.requiredReadPaths ?? [];
+    const taskSourceCited = extractTaskSourceOpenspecPaths([sources.requirementMarkdown, sources.constraintMarkdown ?? ""].join("\n"));
+    const scanStrict = sources.frontendProjectCapability?.designEvidence.normativePaths ?? [];
+    const dedupeSorted = (paths) => [...new Set(paths)].sort();
+    const openspecCandidateSources = {
+        declared: dedupeSorted(declared),
+        taskSourceCited: dedupeSorted(taskSourceCited),
+        scanStrict: dedupeSorted(scanStrict),
+    };
+    const openspecCandidatePaths = policy === "cited"
+        ? dedupeSorted([...declared, ...taskSourceCited])
+        : openspecCandidateSources.scanStrict;
+    return {
+        openspecPolicy: policy,
+        openspecCandidatePaths,
+        openspecCandidateSources,
+    };
+}
+const openspecCitationInstruction = [
+    "OpenSpec 引用块（citation block）：在 fenced json 契约块之后，追加**恰好一个** ```openspec-citations 围栏代码块（三反引号 + openspec-citations）。",
+    '该块内每行一个 JSON 对象 {"path":"<repo 相对 openspec 路径>","section":"<命中章节或空串>","line":<int 或 null>}，必须逐条列出你在本计划中实际读取并应用的每个 openspec 规范文件。',
+    "prewrite gate 会用真实 read 事件核验每条引用：引用存在但无成功 read 事件 → openspec-citation-not-read；契约冻结的必读候选未被引用 → openspec-not-cited；两者都 fail-closed。不要引用未读取的路径。",
+].join("\n");
+const frontendComponentConformanceInstruction = [
+    "## Component Selection conformance (uiComponentChoices; hard rule)",
+    "每个 UI 用途必须在契约的 uiComponentChoices[] 中声明组件选型：{ purpose, component, decision, specReference, rationale }。",
+    "- decision=specified：前端规范（候选组件/主题桶 + 任务源显式引用）已定义该用途组件 → 必须使用该组件，并给精确 specReference { path, section, line }（path 必须是 openspec/ai_workspace 受支持规范路径）。",
+    "- decision=reuse-existing：复用仓库既有组件/惯例（规范未点名）→ specReference 可为 null，rationale 说明复用的现有组件与依据。",
+    "- decision=new：规范与既有代码均无合适组件 → specReference 必须为 null，rationale 必须说明偏差理由（design-review 审，最终 review 复核）。",
+    "不得静默替换规范组件或自创组件而无偏差声明；spec 已定义该用途组件时不得改选其它组件。",
+    "prewrite gate 确定性交叉校验：specReference.path 非法 → component-spec-reference-invalid；未在 openspec-citations 引用块中引用或未真实读取 → component-spec-not-cited；候选桶非空且契约有 UI 可见工作而 uiComponentChoices 缺失/空 → component-choices-missing。",
+].join("\n");
 function resolveFrontendCapabilityContextBlock(sources) {
     const risk = sources.frontendRisk;
     const capability = sources.frontendProjectCapability;
@@ -2141,9 +2267,34 @@ function resolveFrontendCapabilityContextBlock(sources) {
     }
     if (capability) {
         parts.push("", capability.adapterGuidance);
-        if (capability.designEvidence.normativePaths.length > 0) {
-            parts.push(`openspec normative candidates: ${capability.designEvidence.normativePaths.slice(0, 12).join(", ")}`);
+        const classified = capability.designEvidence.classified;
+        const bucketLines = [];
+        const pushBucket = (label, paths) => {
+            if (paths.length > 0)
+                bucketLines.push(`${label}: ${paths.join(", ")}`);
+        };
+        pushBucket("schemas", classified.schemas);
+        pushBucket("code-template", classified.codeTemplate);
+        pushBucket("rule.api", classified.rule.api);
+        pushBucket("rule.mock", classified.rule.mock);
+        pushBucket("rule.router", classified.rule.router);
+        pushBucket("rule.hooks", classified.rule.hooks);
+        pushBucket("rule.utils", classified.rule.utils);
+        pushBucket("rule.components", classified.rule.components);
+        pushBucket("rule.other", classified.rule.other);
+        pushBucket("theme", classified.theme);
+        pushBucket("component", classified.component);
+        pushBucket("ui-other", classified.uiOther);
+        pushBucket("advisory-other", classified.advisoryOther);
+        parts.push("## Classified openspec specification paths (role semantics)");
+        if (bucketLines.length > 0) {
+            parts.push(...bucketLines);
+        }
+        else {
+            parts.push("(no openspec specification paths discovered — greenfield)");
         }
+        parts.push("component / theme / rule.components 是「组件/主题规范」必读语义桶：规范已定义某用途组件时必须使用它（uiComponentChoices 用 decision=specified + 精确 path/section/line），不得静默替换为自认更合适的组件；无规范定义时才允许 reuse-existing 或 new（new 必须声明偏差 rationale）。这些路径在生成期冻结为 prewrite gate 的 componentSpecCandidatePaths。");
+        parts.push("Each consuming node MUST report in its output: applicable rules, the hit path/section/line number for every applied specification, and any conflicts or missing specifications. Missing or conflicting required specifications must fail closed rather than silently substituting nearby repository conventions.");
         parts.push(`A11y capability: ${capability.a11y.status}` +
             (capability.a11y.tools.length
                 ? ` (${capability.a11y.tools.join(", ")})`
@@ -2198,6 +2349,7 @@ function pruneFrontendTasksForRisk(tasks, risk) {
                             planFallbackFromNodeIds: [],
                             reviewFromNodeId: "frontend-design-review-pi",
                             reviewFallbackFromNodeIds: [],
+                            revisionPatch: false,
                         },
                     }
                     : task.shell,
@@ -2344,8 +2496,38 @@ async function buildFrontendHybridDagFromTask(sources) {
             "",
             "### mockApi.endpoints - GOOD (strategy=native with complete endpoint):",
             '{"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"}',
+            "",
+            "### 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',
+            "",
+            "### uiComponentChoices - GOOD (specified with precise spec hit):",
+            '{"purpose":"primary action button","component":"Button","decision":"specified","specReference":{"path":"openspec/schemas/button.md","section":"Variants","line":12},"rationale":"spec mandates Button for primary actions"}',
+            "",
+            "### uiComponentChoices - GOOD (new with deviation rationale; specReference null):",
+            '{"purpose":"loading skeleton","component":"SkeletonCard","decision":"new","specReference":null,"rationale":"no spec or existing component covers skeleton; deviation pending design-review approval"}',
+            "",
+            "### uiComponentChoices - BAD (specified without specReference, or new with specReference):",
+            '{"purpose":"primary action","component":"MyButton","decision":"specified","specReference":null,"rationale":"..."}  <-- REJECTED: specified requires specReference',
+            '{"purpose":"primary action","component":"MyButton","decision":"new","specReference":{"path":"openspec/schemas/button.md","section":"","line":null},"rationale":"..."}  <-- REJECTED: new must not carry specReference',
         ].join("\n");
     })();
+    const frontendContractFieldSummary = [
+        "## Contract field summary (authoritative JSON; no plan prose)",
+        "The plan/revision node emits only a fenced json contract — there is no Markdown plan explanation to read. Review these fields:",
+        "- requirements[]: id, expectedOutcome, implementationTargets, verificationTargetIds, evidenceGap",
+        "- uiStates[]: name, applicable, expectedBehavior, implementationTargets, verificationTargetIds, notApplicableReason",
+        "- interactions[]: name, trigger, expectedBehavior, implementationTargets, verificationTargetIds",
+        "- 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",
+        "- 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");
     const sourceContext = [
         buildSourceContextBlock(sources),
         capabilityContextBlock,
@@ -2378,6 +2560,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         `Non-static targets (type unit/component/integration/mock) MUST set file to a concrete code file inside the implementation writeSet (task allowedPaths); the prewrite gate rejects any non-static target whose file falls outside the writeSet.`,
         `Command-level checks that run project-wide (all tests, typecheck, build, governance) MUST use type "static" and must NOT be bound as non-static targets with file=package.json/tsconfig.json/vite.config.ts/scripts/*. Static targets are exempt from the writeSet containment check.`,
     ].join("\n");
+    const mandatorySourceReadInstruction = [
+        "## Mandatory full source read before contracting",
+        "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 strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -2509,6 +2696,40 @@ async function buildFrontendHybridDagFromTask(sources) {
         `- Behavior command source: ${behaviorVerifyEvidence.commandSource}`,
         ...behaviorVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
     ].join("\n");
+    const advisories = [];
+    if (frontendSourceMentionsMock(frontendSources) &&
+        frontendMockStrategyMustBeNotNeeded(frontendSources)) {
+        advisories.push("auto 模式已将 Mock 策略收窄为 not-needed：任务源提到接口/API/Mock 需求，但仓库无确认 Mock 能力或无确定性 Mock 验证命令。若项目规范要求 Mock，请声明 frontendMock.verifyCommands 或 policy:required 后重新生成 DAG。");
+    }
+    const openspecGate = resolveFrontendOpenspecGateConfig(sources);
+    // Generation-frozen component/theme specification bucket (ADR 0016). Derived
+    // from the classified component/theme/rule.components buckets; the prewrite
+    // gate consumes it to enforce uiComponentChoices presence and specReference
+    // cross-checking. `src/task/**` classification logic is intentionally
+    // unchanged — these buckets already partition normativePaths.
+    const classified = sources.frontendProjectCapability?.designEvidence.classified;
+    const componentSpecCandidatePaths = [
+        ...(classified?.component ?? []),
+        ...(classified?.theme ?? []),
+        ...(classified?.rule.components ?? []),
+    ].filter((value, index, array) => array.indexOf(value) === index).sort();
+    if (openspecGate.openspecPolicy === "cited") {
+        if (openspecGate.openspecCandidatePaths.length === 0) {
+            advisories.push("openspec 策略 cited：契约声明的 requiredReadPaths 与任务源引用均为空，prewrite gate 不强制读取 openspec；如需增强规范门禁，请在 task.json.frontendOpenspec.requiredReadPaths 声明必读路径或在任务源中显式引用 openspec 文件。");
+        }
+        else {
+            advisories.push(`openspec 策略 cited：候选 ${openspecGate.openspecCandidatePaths.length} 个（declared ${openspecGate.openspecCandidateSources.declared.length} / task-source-cited ${openspecGate.openspecCandidateSources.taskSourceCited.length}），plan/review 必须在 openspec-citations 引用块中逐条引用并真实读取。`);
+        }
+    }
+    else {
+        const openspecDiscovery = sources.frontendProjectCapability?.openspecDiscovery;
+        if (openspecDiscovery) {
+            advisories.push(`openspec 策略 scan-strict：候选来源 auto-discovered，共 ${openspecDiscovery.candidateCount} 个，排除治理目录 ${openspecDiscovery.governanceRoot} 下 ${openspecDiscovery.excludedGovernanceCount} 个文件`);
+            if (openspecDiscovery.truncated) {
+                advisories.push(`openspec 候选命中安全上限 ${openspecDiscovery.maxCandidates}，已截断（非静默）；请缩小 spec 范围或提高上限`);
+            }
+        }
+    }
     const spec = {
         version: 3,
         title: `Frontend implementation DAG: ${taskConfig.title}`,
@@ -2523,6 +2744,7 @@ async function buildFrontendHybridDagFromTask(sources) {
         skillsByRole: FRONTEND_SKILLS_BY_ROLE,
         executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
         verifyStrategy: resolveDagVerifyStrategy(taskConfig),
+        advisories: advisories.length > 0 ? advisories : undefined,
         tasks: [
             {
                 id: "frontend-contract-pi",
@@ -2539,6 +2761,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read task source and produce a concise frontend implementation contract.",
                     "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations.",
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    mandatorySourceReadInstruction,
                     sourceContext,
                 ].join("\n\n"),
             },
@@ -2578,23 +2801,26 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Markdown implementation plan with Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks, ending with exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once and must not contain or be followed by any raw JSON or extra fenced block. No file writes.",
+                outputContract: "One-line lead-in, then exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. Do NOT emit a Markdown plan explanation or any prose after the contract JSON — the output is JSON-only (the gate renders plan.md deterministically). Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
                 subtask_prompt: [
                     "Based on frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence, return a minimal frontend implementation plan.",
                     "Select the Mock / API strategy inside the plan and structured contract. Carry endpoint/fixture mapping, explicit activation, production-default-off rule, verification commands, and Real Integration Gap into both outputs.",
-                    "Include ordered steps, target files, UI state handling, styling/component strategy, interaction notes, Mock/API strategy, dependency policy, deterministic verification entrypoints, and residual risks. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
+                    "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.",
-                    "End with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response; the plan text must not contain other balanced JSON objects.",
+                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit a Markdown plan explanation or any prose after the contract JSON — the output is JSON-only. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit 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,
                     fixedVerificationContext,
                     sourceContext,
                     mockContextBlock,
                     frontendContractSchemaBlock,
+                    frontendComponentConformanceInstruction,
+                    openspecCitationInstruction,
                 ].join("\n\n"),
             },
             {
@@ -2610,13 +2836,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputProtocol: REVIEW_VERDICT_OUTPUT_PROTOCOL,
                 outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision, followed by Findings, Required Plan Corrections, and Checked Items. No file writes.",
                 subtask_prompt: [
-                    "Audit the frontend plan before implementation.",
+                    "Audit the frontend plan before implementation. Consume the contract JSON (the single fenced json block from frontend-plan-pi); there is no separate plan prose.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence. A static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint. not-needed otherwise requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
+                    "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,
+                    frontendContractFieldSummary,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -2630,27 +2859,30 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputMode: "structured-required",
                 retryPolicy: STRUCTURED_REQUIRED_PI_RETRY_POLICY,
                 structuredContractOutput: {
-                    schemaId: "frontend-implementation-contract-v1",
+                    schemaId: "frontend-implementation-contract-revision-patch-v1",
                     retryOnInvalid: true,
                 },
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "When the initial design review requests revision, return a complete Markdown revision plan followed by exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once and must not contain or be followed by any raw JSON or extra fenced block. Do NOT include multiple fenced JSON blocks; only the single authoritative contract JSON block is accepted. No file writes.",
+                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.",
                 subtask_prompt: [
-                    "Consume frontend-plan-pi (original plan) and frontend-design-review-pi (first design review findings).",
-                    "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce a complete revised implementation plan that addresses every Required Plan Correction from the design findings.",
-                    "The revised plan must include Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks.",
+                    "Consume frontend-plan-pi (original contract JSON) and frontend-design-review-pi (first design review findings).",
+                    "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 any of these contract fields: requirements, implementationSteps, targets, uiStates, interactions, mockApi, dependencyPolicy, stylingStrategy, uiComponentChoices, verificationTargets, evidenceGaps, residualRisks, realIntegrationGap. 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,
                     "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.",
-                    "End the response with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer when the design review requests revision: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response. Bind it to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not include secrets or unsafe paths.",
-                    "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the revised contract; do not reduce behavior semantics to IDs and paths.",
+                    "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.",
+                    "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,
                     frontendContractSchemaBlock,
+                    mockContextBlock,
+                    frontendComponentConformanceInstruction,
+                    openspecCitationInstruction,
                 ].join("\n\n"),
             },
             {
@@ -2672,15 +2904,18 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputProtocol: REVIEW_VERDICT_OUTPUT_PROTOCOL,
                 outputContract: "For the effective frontend plan, return plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision, followed by Findings and Checked Items. No file writes.",
                 subtask_prompt: [
-                    "Audit the revised frontend plan before implementation. This node runs only after request-revision and consumes frontend-plan-revision-pi.",
+                    "Audit the revised frontend plan before implementation. This node runs only after request-revision and consumes the merge-patch delta from frontend-plan-revision-pi applied on the original frontend-plan-pi contract JSON — there is no separate plan prose.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Verify that every Required Plan Correction from the initial design review has been fully addressed.",
                     "Recheck the selected Mock / API strategy, contract-to-fixture mapping, authorized paths/dependencies, explicit activation, production-default-off behavior, behavior verification, and Real Integration Gap. MOCK_STRATEGY: blocked cannot receive VERDICT: pass.",
                     "Review every explicit REQ-/BR-/AC- mapping; the downstream prewrite gate also checks identifier retention deterministically.",
                     "Request revision if any design gap remains, if corrections are incomplete, or if the revised plan introduces new unaddressed issues.",
+                    "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,
+                    frontendContractFieldSummary,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -2723,10 +2958,18 @@ async function buildFrontendHybridDagFromTask(sources) {
                                 ],
                         artifactName: "frontend-implementation-contract.json",
                         outputDir: "contracts",
+                        revisionPatch: true,
+                        planMdArtifactName: "frontend-plan.md",
                         requireSourceFreshness: true,
                         implementationWriteSet: implementPaths.writeSet,
-                        openspecCandidatePaths: sources.frontendProjectCapability?.designEvidence
-                            .normativePaths ?? [],
+                        openspecPolicy: openspecGate.openspecPolicy,
+                        openspecCandidateSources: {
+                            declared: openspecGate.openspecCandidateSources.declared,
+                            taskSourceCited: openspecGate.openspecCandidateSources.taskSourceCited,
+                            scanStrict: openspecGate.openspecCandidateSources.scanStrict,
+                        },
+                        openspecCandidatePaths: openspecGate.openspecCandidatePaths,
+                        componentSpecCandidatePaths,
                     },
                     cwd: ".",
                     timeoutMs: 60000,
@@ -5783,7 +6026,9 @@ function applyDefaultReadOnlyRetryPolicy(spec) {
         if (isSafeReadOnlyPiRetryCandidate(task)) {
             task.retryPolicy = task.outputProtocol
                 ? PROTOCOL_AWARE_PI_RETRY_POLICY
-                : DEFAULT_READ_ONLY_PI_RETRY_POLICY;
+                : task.role === "planner"
+                    ? PLANNER_OUTPUT_LIMIT_RETRY_POLICY
+                    : DEFAULT_READ_ONLY_PI_RETRY_POLICY;
             continue;
         }
         if (isWriterTransportRetryCandidate(task)) {

package/dist/workflows/dag/lifecycle.js

@@ -743,6 +743,7 @@ function findDoctorFailureNode(state) {
             nodeId: state.pausedByNodeId,
             status: node?.status,
             rawFailureCategory: node?.failureCategory,
+            skippedReason: node?.skippedReason,
         };
     }
     const errorEntry = Object.entries(state.nodes).find(([, node]) => node.status === "ERROR");
@@ -758,6 +759,7 @@ function findDoctorFailureNode(state) {
         nodeId: selected[0],
         status: selected[1].status,
         rawFailureCategory: selected[1].failureCategory,
+        skippedReason: selected[1].skippedReason,
     };
 }
 async function readRunOwnedBackendTestClassification(runDir) {
@@ -786,6 +788,7 @@ async function resolveDoctorFailureRouting(input) {
             normalizedFailureCategory: "unknown",
             nodeId: input.nodeId,
             productLineFailureCategory: classifiedCategory,
+            skippedReason: input.skippedReason,
         });
     }
     return routeDagFailure(input);
@@ -807,6 +810,7 @@ async function formatDagDoctorMarkdown(repoRoot, runId) {
         rawFailureCategory,
         normalizedFailureCategory: normalizedCategory,
         nodeId: failure.nodeId,
+        skippedReason: failure.skippedReason,
     });
     const evidence = failure.nodeId
         ? path.join(located.runDir, failure.nodeId, "result.summary.md")