@tea-agent/loop-agent 0.16.1-beta.0 → 0.16.1-beta.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新日志
 
+## [0.16.1-beta.1] - 2026-07-19
+
+### 修复
+
+- 修复前端实现契约 Schema 漂移：DAG 生成时从当前 loop-agent 包内置 `docs/templates/frontend-implementation-contract.schema.json` 加载完整 `frontend-implementation-contract-v1` JSON Schema，并注入到 `frontend-plan-pi` 与 `frontend-plan-revision-pi` 提示中，模型不再需要搜索或猜测契约字段
+- Prompt 中显式禁止 `schemaId`、`targetFiles`、`requirementCoverage` 等不在 Schema 内的字段，防止模型（如 DeepSeek）生成错误结构
+- small 拓扑下 `frontend-plan-pi` 与 reviewed/high-risk 拓扑下 `frontend-plan-revision-pi` 均获得相同的完整 Schema 与确定性上下文
+
 ## [0.15.0] - 2026-07-18
 
 ### 重点更新

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

@@ -1,9 +1,86 @@
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { findPackageRoot } from "../../shared/package-metadata.js";
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
+/**
+ * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
+ * installed loop-agent package docs/templates/ path. Package-root discovery
+ * works from both the source module and the compiled dist module without
+ * relying on CommonJS globals in the ESM runtime.
+ *
+ * Validation is fail-closed: missing file, malformed JSON, mismatched $id,
+ * missing additionalProperties: false, or incomplete top-level required keys
+ * all throw before any DAG prompt is assembled.
+ */
+export function loadFrontendImplementationContractJsonSchema(startDir = path.dirname(fileURLToPath(import.meta.url))) {
+    const packageRoot = findPackageRoot(startDir);
+    if (!packageRoot) {
+        throw new Error(`cannot locate loop-agent package root from ${path.resolve(startDir)}`);
+    }
+    const schemaPath = path.join(packageRoot, "docs", "templates", "frontend-implementation-contract.schema.json");
+    let content;
+    try {
+        content = readFileSync(schemaPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`cannot load frontend-implementation-contract.schema.json from current loop-agent package at ${schemaPath}: ${error.code ?? String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`frontend-implementation-contract.schema.json is not valid JSON: ${error.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new Error("frontend-implementation-contract.schema.json root is not a JSON object");
+    }
+    const schema = parsed;
+    if (schema.$id !== FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID) {
+        throw new Error(`schema $id mismatch: expected ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID}, got ${String(schema.$id)}`);
+    }
+    if (schema.additionalProperties !== false) {
+        throw new Error("schema must have additionalProperties: false at top level");
+    }
+    const expectedRequired = [
+        "schemaVersion",
+        "sourceBinding",
+        "riskLevel",
+        "targets",
+        "requirements",
+        "uiStates",
+        "interactions",
+        "mockApi",
+        "designEvidence",
+        "verificationTargets",
+        "evidenceGaps",
+    ];
+    const actualRequired = Array.isArray(schema.required) ? schema.required : [];
+    const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
+    if (missing.length > 0) {
+        throw new Error(`schema required fields missing: ${missing.join(", ")}`);
+    }
+    const properties = schema.properties && typeof schema.properties === "object"
+        ? schema.properties
+        : {};
+    const missingProperties = expectedRequired.filter((key) => !Object.hasOwn(properties, key));
+    if (missingProperties.length > 0) {
+        throw new Error(`schema properties missing: ${missingProperties.join(", ")}`);
+    }
+    const schemaVersion = properties.schemaVersion;
+    const mockApi = properties.mockApi;
+    const mockApiProperties = mockApi?.properties;
+    const productionDefaultOff = mockApiProperties?.productionDefaultOff;
+    if (schemaVersion?.const !== 1 || productionDefaultOff?.const !== true) {
+        throw new Error("schema fixed values are incomplete: schemaVersion.const must be 1 and mockApi.productionDefaultOff.const must be true");
+    }
+    return JSON.stringify(parsed);
+}
 const id = z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/);
 const safePath = z
     .string()

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

@@ -21,6 +21,7 @@ import { BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT, buildBackendTestExecutionPref
 import { buildBackendTestOutcomeGateShellSnippet } from "./backend-test-result-contract.js";
 import { classifyFrontendRisk, } from "./frontend-risk.js";
 import { discoverFrontendProjectCapability, } from "./frontend-project-capability.js";
+import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, loadFrontendImplementationContractJsonSchema, } from "./frontend-implementation-contract.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
 const REFERENCE_DIRECTORY = "references";
@@ -1733,6 +1734,46 @@ function buildFrontendHybridDagFromTask(sources) {
             allowedPaths: taskConfig.allowedPaths,
             complexity: taskConfig.complexity,
         });
+    const frontendSourceBinding = buildDagSourceBinding(sources);
+    const frontendContractSchemaBlock = (() => {
+        const schema = loadFrontendImplementationContractJsonSchema();
+        const requirement = frontendSourceBinding.sources.find((source) => source.kind === "requirement");
+        if (!requirement) {
+            throw new Error("frontend implementation contract context requires a bound requirement source");
+        }
+        const referencePaths = frontendSourceBinding.sources
+            .filter((s) => s.kind === "reference")
+            .map((s) => s.path);
+        const fixedFields = {
+            schemaVersion: 1,
+            sourceBinding: {
+                taskId: frontendSourceBinding.taskId,
+                requirementPath: requirement.path,
+                requirementSha256: requirement.sha256,
+                referencePaths,
+                requirementIds: frontendSourceBinding.requirementIds,
+            },
+            riskLevel: frontendRisk.selectedRisk,
+            targets: { files: implementPaths.writeSet },
+        };
+        return [
+            `## ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID} JSON Schema (authoritative; do not guess fields)`,
+            schema,
+            "",
+            "## Fixed contract fields (deterministic; copy exactly and do not modify)",
+            JSON.stringify(fixedFields),
+            "",
+            "## Forbidden fields (these are NOT in the schema; do not emit)",
+            "- schemaId",
+            "- targetFiles",
+            "- requirementCoverage",
+            "",
+            "## Critical rules",
+            "- verificationTargets is a TOP-LEVEL required array",
+            "- uiStates items use name/applicable/expectedBehavior/implementationTargets/verificationTargetIds/notApplicableReason",
+            "- mockApi.productionDefaultOff must always be true (including strategy: not-needed)",
+        ].join("\n");
+    })();
     const sourceContext = [
         buildSourceContextBlock(sources),
         capabilityContextBlock,
@@ -1741,7 +1782,7 @@ function buildFrontendHybridDagFromTask(sources) {
         .join("\n\n");
     const hasMockVerifyCommands = (taskConfig.frontendMock?.verifyCommands.length ?? 0) > 0 ||
         mockCapability.verifyCommands.length > 0;
-    const requirementIds = buildDagSourceBinding(sources).requirementIds;
+    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.`
         : "";
@@ -1900,6 +1941,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     fixedVerificationContext,
                     sourceContext,
                     mockContextBlock,
+                    frontendContractSchemaBlock,
                 ].join("\n\n"),
             },
             {
@@ -1976,6 +2018,7 @@ 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.",
                     sourceContext,
+                    frontendContractSchemaBlock,
                 ].join("\n\n"),
             },
             ...(requirementIds.length > 0

package/package.json

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

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

@@ -9,7 +9,7 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 - **`frontend-mock-assess-pi` + gate**: declares `firstProtocolLine: "MOCK_STRATEGY:"`; canonical output first line
   `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
   Pi output mapping promotes the first matching protocol line ahead of any preamble without inventing or replacing its value; missing, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
-- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix).
+- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix). The plan-pi prompt now includes the complete `frontend-implementation-contract-v1` JSON Schema loaded from the loop-agent package `docs/templates/` path, plus deterministic source binding, risk level, and allowed implementation targets. The model does not need to search or guess contract fields; `schemaId`, `targetFiles`, `requirementCoverage` are explicitly forbidden.
 - **`frontend-implement-pi`**: sole exclusive writer. 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. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. 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)