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

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

@@ -599,12 +599,15 @@ export function resolveFrontendMockMode(capability, taskConfig, hasApiDep) {
     if (!hasApiDep) {
         return "not-required";
     }
-    // In auto mode, frontend Mock is optional. Only require Mock-backed strategy
-    // assessment when a native project Mock capability is actually present.
-    // Projects without confirmed Mock support continue through the normal
-    // frontend writer and must preserve the real integration gap instead of
-    // inventing a temporary Mock framework or blocking solely for missing Mock.
-    return capability.status === "present" ? "required" : "not-required";
+    // In auto mode, frontend Mock is optional. Only enter Mock-backed "required"
+    // mode when the project has a confirmed native Mock capability AND
+    // deterministic Mock verification commands. Without executable verification
+    // commands a non-not-needed strategy could never be verified, so auto falls
+    // back to not-required; the prewrite gate then forces not-needed and the
+    // plan records the Real Integration Gap instead of inventing commands.
+    return capability.status === "present" && hasDeterministicMockVerification
+        ? "required"
+        : "not-required";
 }
 function mapTaskComplexity(complexity) {
     if (complexity === "small")
@@ -2008,8 +2011,9 @@ function buildFrontendMockVerifyNode(sources, implementId, readOnlyPaths, forbid
         },
     };
 }
-function buildBlockedFrontendMockDag(sources, readOnlyPaths, forbiddenPaths, globalConstraints) {
+function buildBlockedFrontendMockDag(sources, readOnlyPaths, forbiddenPaths, globalConstraints, blockedReason) {
     const { taskConfig } = sources;
+    const reason = blockedReason ?? "Mock contract is blocked by deterministic generation-time Mock safety constraints.";
     const spec = {
         version: 3,
         title: `Frontend implementation DAG (BLOCKED Mock): ${taskConfig.title}`,
@@ -2039,10 +2043,10 @@ function buildBlockedFrontendMockDag(sources, readOnlyPaths, forbiddenPaths, glo
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 outputContract: "Deterministic generation-time Mock blocker. Always exits nonzero and never reaches a writer.",
-                subtask_prompt: "Fail closed because required Mock verification entrypoints were not materialized. Resolve the task contract and regenerate the DAG.",
+                subtask_prompt: `Fail closed: ${reason} Resolve the task contract and regenerate the DAG.`,
                 shell: {
                     commands: [
-                        "node -e \"console.error('frontend Mock contract blocked: required verification entrypoints are unavailable'); process.exit(1)\"",
+                        `node -e ${JSON.stringify(`console.error(${JSON.stringify(`frontend Mock contract blocked: ${reason}`)}); process.exit(1)`)}`,
                     ],
                     cwd: ".",
                     timeoutMs: 60000,
@@ -2093,7 +2097,7 @@ function resolveFrontendMockContextBlock(sources) {
     if (mode === "not-required") {
         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. 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('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.');
         }
     }
     if (mode === "blocked") {
@@ -2102,10 +2106,15 @@ function resolveFrontendMockContextBlock(sources) {
     return parts.join("\n");
 }
 function frontendMockStrategyMustBeNotNeeded(sources) {
-    const capabilityStatus = sources.frontendMockCapability?.status;
-    return ((sources.taskConfig.frontendMock?.policy ?? "auto") === "auto" &&
+    const policy = sources.taskConfig.frontendMock?.policy ?? "auto";
+    const capability = sources.frontendMockCapability;
+    const capabilityStatus = capability?.status;
+    const hasDeterministicMockVerification = (capability?.verifyCommands.length ?? 0) > 0;
+    return (policy === "auto" &&
         (sources.frontendMockMode ?? "not-required") === "not-required" &&
-        (capabilityStatus === "absent" || capabilityStatus === "ambiguous"));
+        (capabilityStatus === "absent" ||
+            capabilityStatus === "ambiguous" ||
+            !hasDeterministicMockVerification));
 }
 function resolveFrontendCapabilityContextBlock(sources) {
     const risk = sources.frontendRisk;
@@ -2355,7 +2364,12 @@ async function buildFrontendHybridDagFromTask(sources) {
     ];
     // Guard: blocked mode — generate assessment-only DAG with no writer reachable
     if (mockMode === "blocked") {
-        return buildBlockedFrontendMockDag(frontendSources, readOnlyPaths, forbiddenPaths, globalConstraints);
+        const blockedReason = mockCapability.safetyViolation
+            ? `Mock contract blocked: ${mockCapability.safetyViolation}`
+            : (taskConfig.frontendMock?.policy ?? "auto") === "required"
+                ? "Mock strategy is required, but no authorized Mock verification command was found."
+                : "Mock contract is blocked by deterministic generation-time Mock safety constraints.";
+        return buildBlockedFrontendMockDag(frontendSources, readOnlyPaths, forbiddenPaths, globalConstraints, blockedReason);
     }
     const fallbackVerifyCommands = await discoverFrontendFallbackVerifyCommands(sources.repoRoot);
     const staticFallbackCommands = fallbackVerifyCommands.staticCommands;
@@ -2521,14 +2535,14 @@ 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 (\`\`\`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.",
+                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.",
                 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.",
                     "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 so small topology can materialize the contract without plan-revision.",
+                    "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.",
                     "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,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
@@ -2572,7 +2586,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 (\`\`\`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.",
+                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.",
                 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.",
@@ -2580,7 +2594,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     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. 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.",
+                    "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.",
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     fixedVerificationContext,
@@ -2617,66 +2631,9 @@ async function buildFrontendHybridDagFromTask(sources) {
                     sourceContext,
                 ].join("\n\n"),
             },
-            {
-                id: "frontend-contract-json-pi",
-                depends_on: [
-                    "frontend-plan-revision-pi",
-                    "frontend-plan-pi",
-                    "frontend-final-design-review-pi",
-                    "frontend-design-review-pi",
-                ],
-                dependsPolicy: "all-or-condition-skip",
-                role: "planner",
-                executor: "pi",
-                complexity: "MED",
-                writePolicy: "read-only",
-                outputMode: "structured-required",
-                retryPolicy: STRUCTURED_REQUIRED_PI_RETRY_POLICY,
-                allowedPaths: readOnlyPaths,
-                forbiddenPaths,
-                skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                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"),
-            },
-            {
-                id: "frontend-contract-json-validate-shell",
-                depends_on: ["frontend-contract-json-pi"],
-                role: "verifier",
-                executor: "shell",
-                complexity: "LOW",
-                writePolicy: "read-only",
-                allowedPaths: readOnlyPaths,
-                forbiddenPaths,
-                outputContract: "Validated frontend implementation contract artifact with schema ID and SHA-256.",
-                subtask_prompt: "Materialize and validate the structured frontend contract before prewrite authorization.",
-                shell: {
-                    commands: [],
-                    jsonArtifactGate: {
-                        fromNodeId: "frontend-contract-json-pi",
-                        schemaId: "frontend-implementation-contract-v1",
-                        artifactName: "frontend-implementation-contract.json",
-                        outputDir: "contracts",
-                    },
-                    cwd: ".",
-                    timeoutMs: 60000,
-                },
-            },
             {
                 id: "frontend-prewrite-gate-shell",
                 depends_on: [
-                    "frontend-contract-json-pi",
-                    "frontend-contract-json-validate-shell",
                     "frontend-final-design-review-pi",
                     "frontend-design-review-pi",
                     "frontend-plan-revision-pi",
@@ -2695,14 +2652,12 @@ async function buildFrontendHybridDagFromTask(sources) {
                     commands: [],
                     frontendPrewriteGate: {
                         schemaVersion: 1,
-                        planFromNodeId: "frontend-contract-json-pi",
-                        planFallbackFromNodeIds: [
-                            "frontend-plan-revision-pi",
-                            "frontend-plan-pi",
-                        ],
+                        planFromNodeId: "frontend-plan-revision-pi",
+                        planFallbackFromNodeIds: ["frontend-plan-pi"],
                         reviewFromNodeId: "frontend-final-design-review-pi",
                         reviewFallbackFromNodeIds: ["frontend-design-review-pi"],
                         requiredRequirementIds: requirementIds,
+                        mockCommandLabels: mockVerifyEvidence?.commandLabels ?? [],
                         allowedMockStrategies: taskConfig.frontendMock?.policy === "disabled" ||
                             frontendMockStrategyMustBeNotNeeded(frontendSources)
                             ? ["not-needed"]

package/dist/workflows/dag/types.js

@@ -183,6 +183,8 @@ export const dagFrontendPrewriteGateSchema = z.object({
     allowedMockStrategies: z
         .array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"]))
         .min(1),
+    /** Frozen Mock verification command labels the DAG will actually execute. */
+    mockCommandLabels: z.array(z.string()).default([]),
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     requireSourceFreshness: z.literal(true),

package/package.json

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

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,8 +6,10 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Query the knowledge base when available and always search+read `openspec/schemas/`, `openspec/project-specs/`, and `ai_workspace/` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-plan-pi` + conditional design loop**: AC → explicit observable `expectedOutcome`, interactions → explicit `trigger` + `expectedBehavior`, then steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap, and exactly one `frontend-implementation-contract-v1` JSON object. IDs plus file paths are not sufficient behavior semantics. Use `uiStates: []` for logic-only changes with no user-visible UI state; do not invent UI states. Applicable states require behavior/implementation/verification, while non-applicable states require a reason and omit empty behavior placeholders. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for a reversible seam. `auto` with absent/ambiguous project Mock capability must select `not-needed`, keep real requests default, and record the gap; `required` cannot select `not-needed`. Initial design pass uses the original plan; only exact `request-revision` runs read-only revision plus final review. Small-risk runs one design review only.
-- **`frontend-prewrite-gate-shell`**: the sole write authorization. Resolve effective plan/review, require exact pass, retain every REQ/BR/AC id, enforce Mock policy, validate schema/source binding and writeSet containment, and materialize `contracts/frontend-implementation-contract.json`. A planned fixture or consumer may be a future writer output and need not exist before authorization. Fallback is allowed only when a conditional primary is absent; an existing malformed primary fails closed. Generation-time blocked Mock produces one deterministic blocking shell node and no writer.
+- **`frontend-plan-pi` + conditional design loop**: AC → explicit observable `expectedOutcome`, interactions → explicit `trigger` + `expectedBehavior`, then steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, and real-integration gap. These nodes output Markdown plans only; each plan ends with **exactly one** fenced `json` block carrying the single authoritative `frontend-implementation-contract-v1` object. Do not emit raw JSON, JSON in prose, or a second fenced block. `frontend-contract-json-pi` and `frontend-contract-json-validate-shell` do not exist; the prewrite gate materializes the contract from the effective plan node. IDs plus file paths are not sufficient behavior semantics. Use `uiStates: []` for logic-only changes with no user-visible UI state; do not invent UI states. Applicable states require behavior/implementation/verification, while non-applicable states require a reason and omit empty behavior placeholders. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for a reversible seam. A non-`not-needed` strategy requires frozen Mock verify commands (`frontendMock.verifyCommands` / `package.json` mock script / capability seed); `auto` with absent/ambiguous capability or no command selects `not-needed` (real requests stay default, gap recorded); `required` without a command is generation-time blocked (no writer is generated). Initial design pass uses the original plan; only exact `request-revision` runs read-only revision plus final review. Small-risk runs one design review only.
+- **`frontend-prewrite-gate-shell`**: the sole write authorization. Resolve the effective plan (revised plan when the revision branch ran, otherwise the original plan) and its review, require exact pass, retain every REQ/BR/AC id, enforce Mock policy, validate schema/source binding and writeSet containment, and materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block in the effective plan node (multiple candidates fail closed with `invalid-output`). A planned fixture or consumer may be a future writer output and need not exist before authorization. Fallback is allowed only when a conditional primary is absent; an existing malformed primary fails closed. Generation-time blocked Mock produces one deterministic blocking shell node and no writer.
+  - Every `verificationTarget.commandLabel` must be one of the **frozen command labels** derived from the DAG run spec's `verifyEvidence.commandLabels`; any other value is rejected fail-closed at materialization (`invalid-output`). An empty frozen set (e.g. no `run.json`) skips the check.
+  - `mockApi.strategy !== "not-needed"` fails closed at the gate when `mockCommandLabels` is empty (`no authorized Mock verification commands`).
 - **`frontend-implement-pi`**: sole regular exclusive writer and consumer of `frontend-bounded-implement`, not this discovery skill. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. First line must be `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks it against the attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)