@tea-agent/loop-agent 0.34.5 → 0.35.0-beta.1

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

@@ -8,6 +8,40 @@ import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-s
 import { findPackageRoot } from "../../shared/package-metadata.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+/**
+ * Extract frozen command labels from the DAG run spec (run.json).
+ * The run spec is written before any node executes, so it is always available
+ * when the prewrite gate materializes the contract.
+ */
+async function deriveFrozenCommandLabelsFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        // run.json is guaranteed to exist in production (DAG runner writes it
+        // before any node executes). When absent (e.g. test fixtures), there is
+        // no frozen set to validate against and the check is skipped downstream.
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`cannot derive frozen command labels: run.json is not valid JSON at ${specPath}: ${error.message}`);
+    }
+    const labels = new Set();
+    for (const task of spec.tasks ?? []) {
+        const cmdLabels = task.shell?.verifyEvidence?.commandLabels;
+        if (cmdLabels) {
+            for (const label of cmdLabels)
+                labels.add(label);
+        }
+    }
+    return [...labels];
+}
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
 /**
  * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
@@ -1228,6 +1262,21 @@ export async function materializeFrontendImplementationContract(input) {
     parsed = canonicalizeRequirementIdsInPayload(parsed);
     parsed = canonicalizeVerificationTargetAliases(parsed);
     assertFrontendContractPathsSafe(parsed);
+    // Validate verificationTarget commandLabels against frozen command set.
+    // The frozen set is derived from DAG verification shell task verifyEvidence.
+    const frozenLabels = await deriveFrozenCommandLabelsFromRun(input.runDir);
+    if (frozenLabels.length > 0) {
+        const frozen = new Set(frozenLabels);
+        const parsedVt = asRecord(parsed)?.verificationTargets;
+        if (Array.isArray(parsedVt)) {
+            for (const vt of parsedVt) {
+                const label = asString(asRecord(vt)?.commandLabel);
+                if (label && !frozen.has(label)) {
+                    throw new Error(`invalid-output: verificationTarget commandLabel "${label}" is not in the frozen command set [${[...frozen].join(", ")}]`);
+                }
+            }
+        }
+    }
     const parsedTargets = asRecord(parsed)?.targets;
     const parsedTargetFiles = asStringArray(asRecord(parsedTargets)?.files);
     if (parsedTargetFiles.some((file) => file.startsWith("/") || file.includes("\\")))

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

@@ -191,6 +191,11 @@ export async function runFrontendPrewriteGate(input) {
         if (uncoveredTargets.length > 0) {
             throw new Error(`frontend prewrite gate contract target is outside implementation writeSet: ${uncoveredTargets.join(", ")}`);
         }
+        const nonStaticVTs = contract.verificationTargets.filter((vt) => vt.type !== "static");
+        const uncoveredVTs = nonStaticVTs.filter((vt) => ![...writeSet].some((pattern) => pathMatchesPattern(vt.file, pattern) || vt.file === pattern));
+        if (uncoveredVTs.length > 0) {
+            throw new Error(`frontend prewrite gate verification target is outside implementation writeSet: ${uncoveredVTs.map((vt) => vt.file).join(", ")}`);
+        }
     }
     const candidatePaths = input.config.openspecCandidatePaths ?? [];
     const openspecReadPaths = await checkOpenspecReadEvidence({

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

@@ -2264,6 +2264,44 @@ async function buildFrontendHybridDagFromTask(sources) {
             "- mockApi.productionDefaultOff must always be true (including strategy: not-needed)",
             "- All implementation files, verification files, symbols, and commands must be discovered from the current target workspace and current task. Never copy paths, symbols, or commands from the loop-agent repository, an example task, or prior run output.",
             "- Use relative POSIX paths rooted at the target workspace. Do not assume a particular src/test directory layout; preserve the target project's actual app/, packages/, spec/, __tests__, or other layout.",
+            "",
+            "## Bad / Good contract field examples",
+            "",
+            "### verificationTargets - BAD (invented commandLabel, missing file):",
+            '{"id":"vt-1","type":"static","commandLabel":"lint","file":"","requirementIds":["AC-001"],"uiStates":[]}  <-- REJECTED: commandLabel not in frozen command set; empty file path',
+            "",
+            '### verificationTargets - GOOD (real frozen label, real file):',
+            '{"id":"vt-1","type":"static","commandLabel":"npm run typecheck","file":"tsconfig.json","requirementIds":["AC-001"],"uiStates":[]}  <-- Matches frozen command set; real file path',
+            "",
+            "### requirements - BAD (missing expectedOutcome):",
+            '{"id":"AC-001","expectedOutcome":"","implementationTargets":["src/app.tsx"],"verificationTargetIds":["vt-1"]}  <-- REJECTED: empty expectedOutcome',
+            "",
+            "### requirements - GOOD (concrete expectedOutcome):",
+            '{"id":"AC-001","expectedOutcome":"TypeScript compilation exits with code 0 and produces no errors in dist/","implementationTargets":["src/app.tsx"],"verificationTargetIds":["vt-1"]}',
+            "",
+            "### interactions - BAD (empty trigger/expectedBehavior):",
+            '{"name":"save-click","trigger":"","expectedBehavior":"","implementationTargets":["src/button.tsx"],"verificationTargetIds":["vt-3"]}  <-- REJECTED: empty trigger and expectedBehavior',
+            "",
+            "### interactions - GOOD:",
+            '{"name":"save-click","trigger":"User clicks the Save button in the editor toolbar","expectedBehavior":"POST /api/save is called with editor content; success toast appears; button enters disabled+spinner state until response","implementationTargets":["src/editor/save-button.tsx"],"verificationTargetIds":["vt-3"]}',
+            "",
+            "### uiStates - BAD (applicable=true but missing expectedBehavior):",
+            '{"name":"loading","applicable":true,"expectedBehavior":"","implementationTargets":[],"verificationTargetIds":[]}  <-- REJECTED: applicable UI state requires non-empty expectedBehavior, implementationTargets, and verificationTargetIds',
+            "",
+            "### uiStates - GOOD (applicable=true with complete fields):",
+            '{"name":"loading","applicable":true,"expectedBehavior":"Skeleton placeholder visible while data fetches; aria-busy=true on the list container","implementationTargets":["src/dashboard/list-view.tsx"],"verificationTargetIds":["vt-3"]}',
+            "",
+            "### uiStates - BAD (applicable=false without notApplicableReason):",
+            '{"name":"dark-mode","applicable":false}  <-- REJECTED: non-applicable UI state requires notApplicableReason',
+            "",
+            "### uiStates - GOOD (applicable=false with reason):",
+            '{"name":"dark-mode","applicable":false,"notApplicableReason":"Dark mode toggle is out of scope for this task; only light theme is targeted"}',
+            "",
+            "### mockApi.endpoints - BAD (strategy=native but empty endpoints):",
+            '{"strategy":"native","productionDefaultOff":true,"activation":"env flag","endpoints":[]}  <-- REJECTED: native strategy requires at least one endpoint with method, path, fixture, and consumer',
+            "",
+            "### 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"}]}',
         ].join("\n");
     })();
     const sourceContext = [
@@ -2276,7 +2314,21 @@ async function buildFrontendHybridDagFromTask(sources) {
         mockCapability.verifyCommands.length > 0;
     const requirementIds = frontendSourceBinding.requirementIds;
     const requirementCoverageInstruction = requirementIds.length > 0
-        ? `Include a Requirement Coverage section that lists every exact source identifier: ${requirementIds.join(", ")}. Preserve each identifier verbatim and map it to concrete implementation and verification steps.`
+        ? [
+            `## 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.`,
+        ].join("\n")
         : "";
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
@@ -2469,7 +2521,7 @@ 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, followed by exactly one fenced json object conforming to frontend-implementation-contract-v1 when this node is the effective plan source. No file writes.",
+                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, followed by exactly ONE fenced json object (\`\`\`json ... \`\`\`) conforming to frontend-implementation-contract-v1 when this node is the effective plan source. Do NOT include multiple fenced JSON blocks; only the single authoritative contract JSON block is accepted. 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.",
@@ -2520,7 +2572,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 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 conforming to frontend-implementation-contract-v1. The JSON is the authoritative materialization input. No file writes.",
+                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. Do NOT include multiple fenced JSON blocks; only the single authoritative contract JSON block is accepted. The JSON is the authoritative materialization input. 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.",
@@ -2530,6 +2582,8 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "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. 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.",
+                    "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
+                    fixedVerificationContext,
                     sourceContext,
                     frontendContractSchemaBlock,
                 ].join("\n\n"),
@@ -2581,12 +2635,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Return exactly one JSON object conforming to frontend-implementation-contract-v1. No Markdown, prose, comments, or code fences.",
+                outputContract: "Return exactly one raw JSON object conforming to frontend-implementation-contract-v1. OUTPUT ONLY THE JSON OBJECT. NO MARKDOWN, NO PROSE, NO COMMENTS, NO CODE FENCES, NO BACKTICKS. The first character must be '{' and the last character must be '}'. Any text before or after the JSON will cause the output to be REJECTED.",
                 subtask_prompt: [
                     "Convert the effective reviewed frontend plan into the canonical frontend-implementation-contract-v1 JSON.",
                     "Use frontend-plan-revision-pi when it is FINISHED; otherwise use frontend-plan-pi. Confirm the effective design review passed before producing the contract.",
                     "Return only the JSON object. Do not wrap it in Markdown or a code fence. Do not add explanatory text.",
                     "Preserve all requirement expectedOutcome, interaction trigger/expectedBehavior, target files, verification targets, Mock/API decisions, and Real Integration Gap from the effective plan.",
+                    "OUTPUT REQUIREMENT: The response must consist solely of a raw JSON object - no Markdown headers, no code fences (no \`\`\`json), no explanatory prose before or after. The very first character you output must be '{' and the very last character must be '}'. If you add ANY text, the extraction gate will reject the output.",
+                    "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
+                    requirementCoverageInstruction,
+                    fixedVerificationContext,
                     frontendContractSchemaBlock,
                     sourceContext,
                 ].join("\n\n"),

package/package.json

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