@tea-agent/loop-agent 0.43.0-next.18 → 0.43.0-next.19

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

@@ -443,6 +443,306 @@ async function deriveWriteSetFromRun(runDir) {
     }
     return [...writeSet];
 }
+/** Read the frozen task source paths from run.json sourceBinding so the plan
+ * precheck can require new/specified component choices to cite a traceable
+ * task source. Smoke r37/r38: specReference.path pointed at a to-be-implemented
+ * file or an AC id — a demand that only lived in review prose could never be
+ * closed by the plan retry ladder. The allowed set is enumerable here. */
+async function deriveFrontendSourceBindingPathsFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const paths = [];
+    for (const source of spec.sourceBinding?.sources ?? []) {
+        if (source &&
+            typeof source === "object" &&
+            typeof source.path === "string" &&
+            (source.path).trim()) {
+            paths.push((source.path).trim());
+        }
+    }
+    return paths;
+}
+function stripSourcePathFragment(value) {
+    const hash = value.indexOf("#");
+    return (hash >= 0 ? value.slice(0, hash) : value).trim().replace(/\/$/, "");
+}
+/** decision=new/specified component choices must cite a frozen task source
+ * path (requirement/constraint), never a to-be-implemented file or a bare
+ * acceptance-criterion id. Absent sourceBinding paths (legacy fixtures) the
+ * check is skipped — generation always freezes them. */
+function checkComponentChoiceSourceReferences(canonical, sourcePaths) {
+    const findings = [];
+    if (sourcePaths.length === 0)
+        return findings;
+    for (const choice of canonical.uiComponentChoices ?? []) {
+        if (choice.decision !== "new" && choice.decision !== "specified") {
+            continue;
+        }
+        const rawPath = choice.specReference?.path ?? "";
+        const normalized = stripSourcePathFragment(rawPath);
+        const traceable = normalized.length > 0 &&
+            sourcePaths.some((source) => stripSourcePathFragment(source) === normalized);
+        if (!traceable) {
+            findings.push({
+                code: "component-choice-source-reference-invalid",
+                message: `component choice "${choice.component}" (decision=${choice.decision}) must cite a frozen task source path as specReference.path; allowed: [${sourcePaths.join(", ")}]${rawPath ? ` — got "${rawPath}"` : " — missing"}`,
+                path: "uiComponentChoices",
+            });
+        }
+    }
+    return findings;
+}
+const CAPABILITY_BOUNDARY_MARKER = "测试能力边界（冻结）";
+export async function deriveFrontendInteractionIdsFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    for (const task of spec.tasks ?? []) {
+        const ids = task.shell?.frontendDesignPolicy?.interactionIds;
+        if (ids && ids.length > 0)
+            return ids.filter((id) => typeof id === "string" && id.trim());
+    }
+    return [];
+}
+function checkInteractionIdVocabulary(canonical, declaredIds) {
+    const findings = [];
+    if (declaredIds.length === 0)
+        return findings;
+    for (const interaction of canonical.interactions ?? []) {
+        if (!declaredIds.includes(interaction.name)) {
+            findings.push({
+                code: "interaction-name-not-declared",
+                message: `interaction "${interaction.name}" is not in the frozen interaction id vocabulary; allowed: [${declaredIds.join(", ")}] — retract the wrong record via record_data_flow {"interaction": "${interaction.name}", "retracted": true} or retract_data_flow, then record the declared id`,
+                path: "interactions",
+            });
+        }
+    }
+    return findings;
+}
+export async function deriveFrontendAllowedMockStrategiesFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    for (const task of spec.tasks ?? []) {
+        const strategies = task.shell?.frontendDesignPolicy?.allowedMockStrategies;
+        if (strategies &&
+            strategies.length > 0 &&
+            strategies.every((s) => typeof s === "string" && s.trim())) {
+            return strategies;
+        }
+    }
+    return [];
+}
+function checkMockApiStrategyAllowed(canonical, allowedStrategies) {
+    const findings = [];
+    if (allowedStrategies.length === 0)
+        return findings;
+    const strategy = canonical.mockApi?.strategy;
+    if (strategy && !allowedStrategies.includes(strategy)) {
+        const onlyNotNeeded = allowedStrategies.length === 1 && allowedStrategies[0] === "not-needed";
+        findings.push({
+            code: "mock-strategy-not-allowed",
+            message: `mockApi.strategy "${strategy}" is not in the frozen allowed strategies; allowed: [${allowedStrategies.join(", ")}] — re-record the api mock decision with an allowed strategy (relationship path: record_mock_api {"mockApi": {...}, "replace": true}; decision path: record_api_mock_boundary with the same boundary and a mode that maps to an allowed strategy)${onlyNotNeeded ? "; the run has no deterministic Mock verification capability, so keep strategy \"not-needed\" and preserve the real integration gap instead of inventing Mock evidence" : ""}`,
+            path: "mockApi",
+        });
+    }
+    return findings;
+}
+async function deriveFrontendCapabilityBoundaryFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    for (const task of spec.tasks ?? []) {
+        const boundary = task.shell?.frontendDesignPolicy?.capabilityBoundary;
+        if (boundary &&
+            ((boundary.allowed?.length ?? 0) > 0 ||
+                (boundary.forbidden?.length ?? 0) > 0)) {
+            return boundary;
+        }
+    }
+    return undefined;
+}
+/** Runtime composes the frozen capability boundary into dependencyPolicy —
+ * the planner never maintains it (smoke r42: the boundary lived in PRD prose,
+ * the plan omitted it twice, and recovery could not close a prose gap). */
+export function composeDependencyPolicyWithBoundary(policy, boundary) {
+    if (!boundary)
+        return policy;
+    const allowed = (boundary.allowed ?? []).filter((item) => item.trim());
+    const forbidden = (boundary.forbidden ?? []).filter((item) => item.trim());
+    if (allowed.length === 0 && forbidden.length === 0)
+        return policy;
+    if (policy?.includes(CAPABILITY_BOUNDARY_MARKER))
+        return policy;
+    const sentence = `${CAPABILITY_BOUNDARY_MARKER}：` +
+        (allowed.length > 0 ? `仅可使用 ${allowed.join("、")}` : "无允许清单") +
+        (forbidden.length > 0 ? `；禁止 ${forbidden.join("、")}` : "") +
+        "。";
+    return policy?.trim() ? `${policy.trim()}；${sentence}` : sentence;
+}
+/** Read the generation-frozen requirement→file ownership from run.json
+ * (frontendDesignPolicy spec). Absent (legacy fixtures) → no ownership gate. */
+export async function deriveRequirementOwnershipFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const merged = new Map();
+    for (const task of spec.tasks ?? []) {
+        for (const entry of task.shell?.frontendDesignPolicy?.requirementOwnership ?? []) {
+            const key = [...(entry.requirementIds ?? [])].sort().join("|");
+            if (!merged.has(key))
+                merged.set(key, entry);
+        }
+    }
+    return [...merged.values()];
+}
+/** Deterministic requirement→file ownership check. A requirement's
+ * implementation targets must live inside its declared implementationFiles,
+ * and every verification target bound to it must file under its declared
+ * verificationFiles. Unknown requirement ids are findings too: a typo in the
+ * declaration must fail the declaration, not deadlock the planner. */
+function checkRequirementOwnership(canonical, ownership) {
+    const findings = [];
+    if (ownership.length === 0)
+        return findings;
+    const requirementById = new Map((canonical.requirements ?? []).map((requirement) => [requirement.id, requirement]));
+    const targetsByRequirement = new Map();
+    for (const target of canonical.verificationTargets ?? []) {
+        for (const id of target.requirementIds ?? []) {
+            if (!targetsByRequirement.has(id))
+                targetsByRequirement.set(id, new Set());
+            targetsByRequirement.get(id).add(target.file);
+        }
+    }
+    const declaredRequirementIds = new Set();
+    for (const entry of ownership) {
+        for (const id of entry.requirementIds)
+            declaredRequirementIds.add(id);
+    }
+    for (const entry of ownership) {
+        for (const id of entry.requirementIds) {
+            if (!requirementById.has(id)) {
+                findings.push({
+                    code: "requirement-ownership-unknown-requirement",
+                    message: `requirementOwnership declares unknown requirement id "${id}"; frozen requirement ids: [${[...requirementById.keys()].join(", ")}]`,
+                    path: "requirements",
+                });
+            }
+        }
+    }
+    for (const entry of ownership) {
+        const implementationFiles = entry.implementationFiles ?? [];
+        const verificationFiles = entry.verificationFiles ?? [];
+        for (const id of entry.requirementIds) {
+            const requirement = requirementById.get(id);
+            if (!requirement)
+                continue;
+            if (implementationFiles.length > 0) {
+                const allTargets = requirement.implementationTargets ?? [];
+                // Test-shaped placements belong to the verification lane (a shared
+                // behavior group's placement carries the test file for the
+                // test-writing requirement); they are governed by allowedPaths and
+                // the entry's verificationFiles, not by implementationFiles.
+                const implementationFilesAreTestShaped = implementationFiles.some((file) => isFrontendTestFilePath(file));
+                const targets = implementationFilesAreTestShaped
+                    ? allTargets
+                    : allTargets.filter((file) => !isFrontendTestFilePath(file));
+                // Contract deliverables are existence obligations, not ownership
+                // claims: a contract may require a mounting file to exist for a
+                // requirement implemented elsewhere (smoke r55 — a deliverable
+                // otherwise made plan finalize permanently unfixable).
+                const deliverables = new Set(requirement.deliverableTargets ?? []);
+                const ownedTargets = targets.filter((file) => !deliverables.has(file));
+                // Only files OUTSIDE the declared set violate. An empty owned set
+                // means every mapped file is a deliverable/test-shaped obligation —
+                // unplaced requirements are rejected upstream, not here (r56:
+                // "maps [X] expects [X]" still violated when deliverables covered
+                // the whole mapping).
+                const outside = ownedTargets.filter((file) => !implementationFiles.includes(file));
+                if (outside.length > 0) {
+                    findings.push({
+                        code: "requirement-ownership-violated",
+                        message: `requirement ${id} expects implementation within [${implementationFiles.join(", ")}] but plan maps [${targets.join(", ") || "none"}] — re-map the owning behavior group's module placement`,
+                        path: "requirements",
+                    });
+                }
+            }
+            if (verificationFiles.length > 0) {
+                const files = [...(targetsByRequirement.get(id) ?? [])];
+                const outside = files.filter((file) => !verificationFiles.includes(file));
+                if (outside.length > 0) {
+                    findings.push({
+                        code: "requirement-ownership-violated",
+                        message: `requirement ${id} expects verification evidence within [${verificationFiles.join(", ")}] but verification targets bind [${files.join(", ") || "none"}]`,
+                        path: "verificationTargets",
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
 export const FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID = "frontend-implementation-contract-plan-patch-v1";
 export const FRONTEND_CONTRACT_REVIEW_INDEX_SCHEMA_ID = "frontend-contract-review-index-v1";
@@ -463,7 +763,7 @@ const FRONTEND_CONTRACT_REVIEW_GROUPS = [
     },
     {
         id: "verification",
-        fields: ["verificationTargets", "evidenceGaps", "implementationSteps", "residualRisks"],
+        fields: ["verificationTargets", "evidenceGaps", "residualRisks"],
     },
 ];
 const FRONTEND_CONTRACT_CAPACITY_WARNING_RATIO = 0.6;
@@ -714,6 +1014,11 @@ export const frontendImplementationContractSchema = z
         expectedOutcome: z.string().min(1),
         execution: frontendExecutionSchema.optional(),
         implementationTargets: z.array(safePath),
+        /** Contract-bound "files that must exist" (from the plan
+         * relationship patch). Ownership-exempt: a deliverable is an
+         * existence obligation, not an implementation-ownership claim
+         * (smoke r55 regression). */
+        deliverableTargets: z.array(safePath).optional(),
         verificationTargetIds: z.array(z.string().min(1)),
         evidenceGap: gap.optional(),
         // Source fidelity ledger binding (AC-005/AC-006): 每个 requirement
@@ -799,7 +1104,6 @@ export const frontendImplementationContractSchema = z
     })
         .strict()).min(1),
     evidenceGaps: z.array(gap).optional(),
-    implementationSteps: z.array(z.string().min(1)).optional(),
     stylingStrategy: z.string().min(1).optional(),
     uiComponentChoices: uiComponentChoicesSchema.optional(),
     dependencyPolicy: z.string().min(1).optional(),
@@ -1681,6 +1985,7 @@ export function compactFrontendImplementationContract(value) {
     }
     compact.requirements = compactRecordArrayField(record.requirements, [
         "implementationTargets",
+        "deliverableTargets",
         "verificationTargetIds",
         "sourceFragmentIds",
         "sourceRefs",
@@ -1716,7 +2021,7 @@ export function compactFrontendImplementationContract(value) {
             conflicts: dedupeJsonArray(designEvidence.conflicts),
         };
     }
-    for (const field of ["evidenceGaps", "implementationSteps", "residualRisks"]) {
+    for (const field of ["evidenceGaps", "residualRisks"]) {
         if (Object.hasOwn(compact, field))
             compact[field] = dedupeJsonArray(compact[field]);
     }
@@ -2071,6 +2376,9 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
                 ? { sourceFragmentIds: req.sourceFragmentIds }
                 : {}),
             ...(Array.isArray(req.sourceRefs) ? { sourceRefs: req.sourceRefs } : {}),
+            ...(Array.isArray(req.deliverableTargets)
+                ? { deliverableTargets: req.deliverableTargets }
+                : {}),
             ...(req.execution !== undefined ? { execution: req.execution } : {}),
         };
         // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
@@ -2250,7 +2558,6 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         },
         verificationTargets,
         evidenceGaps,
-        implementationSteps: asStringArray(record.implementationSteps),
         stylingStrategy: asString(record.stylingStrategy) || undefined,
         dependencyPolicy: asString(record.dependencyPolicy) || undefined,
         residualRisks: asStringArray(record.residualRisks),
@@ -2486,6 +2793,7 @@ export async function analyzeFrontendImplementationContract(input) {
         if (!result.data.requirements.some((item) => item.id === requirementId) &&
             !(result.data.evidenceGaps ?? []).some((item) => item.requirementId === requirementId))
             fail("blocked", `frontend contract does not cover ${requirementId}`, candidateJsonSha256);
+    result.data.dependencyPolicy = composeDependencyPolicyWithBoundary(result.data.dependencyPolicy, await deriveFrontendCapabilityBoundaryFromRun(input.runDir));
     return {
         canonical: result.data,
         candidateRawSha256,
@@ -2506,11 +2814,12 @@ function splitFrontendContractReviewGroup(canonical, fields) {
         slices = [];
     };
     for (const field of fields) {
-        if (!Object.hasOwn(canonical, field))
-            continue;
         const fieldValue = canonical[field];
-        // JSON omits undefined object properties; the index must describe the
-        // persisted contract, not phantom keys retained by normalization.
+        // Normalization keeps optional fields as present keys with an undefined
+        // value; JSON serialization drops them, so a slice emitted here would
+        // bind the section to a field the on-disk canonical never contains and
+        // every reader (which re-parses the canonical from JSON) would fail to
+        // resolve it.
         if (fieldValue === undefined)
             continue;
         if (!Array.isArray(fieldValue)) {
@@ -2881,6 +3190,27 @@ function assertVerificationSymbolShapes(contract) {
  * (finalize_plan receipt) can synthesize fix suggestions instead of making
  * the model re-derive them from prose.
  */
+/** Normalized-content sha256 of a parent run's canonical contract, used by the
+ * recovery identical-plan guard. Both sides hash serializeDeterministicJson of
+ * the parsed canonical, so on-disk formatting never changes the verdict.
+ * Unreadable/missing parent contract → undefined (guard skipped). */
+export async function readParentCanonical(parentRunDir) {
+    try {
+        const raw = await readFile(path.join(parentRunDir, "contracts", "frontend-implementation-contract.json"), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function parentCanonicalContentSha256(parentRunDir) {
+    const canonical = await readParentCanonical(parentRunDir);
+    if (!canonical)
+        return undefined;
+    return createHash("sha256")
+        .update(serializeDeterministicJson(canonical))
+        .digest("hex");
+}
 export class PlanPolicyPrecheckFailure extends Error {
     findings;
     constructor(message, findings) {
@@ -2924,7 +3254,34 @@ export async function analyzeFrontendPlanPatchCandidate(input) {
         ...checkUxNameCollisions(analysis.canonical),
         ...checkDependencies(analysis.canonical, await deriveAllowedDependenciesFromRun(input.runDir)),
         ...checkTargetPaths(analysis.canonical, await deriveWriteSetFromRun(input.runDir)),
+        ...checkComponentChoiceSourceReferences(analysis.canonical, await deriveFrontendSourceBindingPathsFromRun(input.runDir)),
+        ...checkRequirementOwnership(analysis.canonical, await deriveRequirementOwnershipFromRun(input.runDir)),
+        ...checkInteractionIdVocabulary(analysis.canonical, await deriveFrontendInteractionIdsFromRun(input.runDir)),
+        ...checkMockApiStrategyAllowed(analysis.canonical, await deriveFrontendAllowedMockStrategiesFromRun(input.runDir)),
     ];
+    // Front-load the static verification coverage gap (smoke r16-r20): when
+    // the frozen command directory offers static entrypoints and no
+    // verification target binds one, type-level/build constraints cannot be
+    // proven. Surface the offered commands here so the plan retry ladder
+    // records a static focus instead of the review flagging it post-hoc.
+    // Every frozen static entry is a required check (smoke r27-r31): binding
+    // only `verify-build` used to satisfy an "at least one" rule, after which
+    // design review rejected the plan for the uncovered `verify-typecheck`
+    // entry — a demand that reached the plan as prose and could never be
+    // machine-checked. Coverage is enumerable, so it is enforced here.
+    const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
+    const staticCommands = verifyDirectory.filter((entry) => entry.mode === "static");
+    if (staticCommands.length > 0) {
+        const boundCommandIds = new Set(analysis.canonical.verificationTargets.map((target) => target.commandId));
+        const uncovered = staticCommands.filter((entry) => !boundCommandIds.has(entry.commandId));
+        if (uncovered.length > 0) {
+            policyPreFindings.push({
+                code: "static-verification-coverage-missing",
+                message: `verification targets miss frozen static command(s): [${uncovered.map((entry) => `${entry.commandId} (${entry.label})`).join(", ")}]; the frozen directory offers: [${staticCommands.map((entry) => `${entry.commandId} (${entry.label})`).join(", ")}] — record record_verification_focus for every static commandId`,
+                path: "verificationTargets",
+            });
+        }
+    }
     if (policyPreFindings.length > 0) {
         const message = `frontend plan policy pre-check failed (fix these plan facts, then re-commit and finalize): ${policyPreFindings
             .map((finding) => `${finding.code}: ${finding.message}`)

package/dist/workflows/dag/frontend-plan-canary.js

@@ -0,0 +1,53 @@
+import { readFrontendPlanCanaryRunMetrics, } from "./frontend-session-budget.js";
+export const FRONTEND_PLAN_CANARY_SCENARIOS = [
+    "missing-idle-loading-empty",
+    "loading-not-mounted",
+    "test-layer-does-not-prove-wiring",
+    "mock-claimed-as-real-integration",
+];
+const reduction = (before, after) => before !== null && after !== null && before > 0 ? ((before - after) / before) * 100 : null;
+/** Compare two same-input runs. Missing observations fail the canary rather
+ * than being interpreted as a zero-cost candidate. */
+export function evaluateFrontendPlanCanary(input) {
+    const required = { planSessionsPct: 30, planWallClockPct: 30, protocolRetryPct: 50, ...input.requiredReductions };
+    const reductions = {
+        planSessionsPct: reduction(input.baseline.planSessions, input.candidate.planSessions),
+        planWallClockPct: reduction(input.baseline.planWallClockMs, input.candidate.planWallClockMs),
+        protocolRetryPct: reduction(input.baseline.retries, input.candidate.retries),
+    };
+    const failedChecks = [];
+    if (reductions.planSessionsPct === null || reductions.planSessionsPct < required.planSessionsPct)
+        failedChecks.push("plan-session-reduction");
+    if (reductions.planWallClockPct === null || reductions.planWallClockPct < required.planWallClockPct)
+        failedChecks.push("plan-wall-clock-reduction");
+    // A zero retry baseline is already optimal: a zero->zero candidate is not a
+    // regression and must not block, while zero->positive or missing evidence
+    // still fails closed.
+    const retriesAlreadyOptimal = input.baseline.retries === 0 && input.candidate.retries === 0;
+    if (!retriesAlreadyOptimal &&
+        (reductions.protocolRetryPct === null || reductions.protocolRetryPct < required.protocolRetryPct)) {
+        failedChecks.push("protocol-retry-reduction");
+    }
+    for (const scenario of FRONTEND_PLAN_CANARY_SCENARIOS) {
+        const result = input.scenarios[scenario];
+        if (result !== "blocked" && result !== "reported")
+            failedChecks.push(`regression:${scenario}`);
+    }
+    return { pass: failedChecks.length === 0, reductions, failedChecks };
+}
+/** Read two frozen run directories and evaluate the same-input canary. Plan
+ * cost metrics come from persisted session receipts; supplemental DAG/review/
+ * recovery values come from each run's `frontend-plan-canary-metrics.json`.
+ * Missing observations surface as `null` and fail the evaluation, never as a
+ * manufactured zero-cost improvement. */
+export async function compareFrontendPlanCanaryRuns(input) {
+    const baseline = await readFrontendPlanCanaryRunMetrics(input.baselineRunDir);
+    const candidate = await readFrontendPlanCanaryRunMetrics(input.candidateRunDir);
+    const evaluation = evaluateFrontendPlanCanary({
+        baseline,
+        candidate,
+        scenarios: input.scenarios,
+        requiredReductions: input.requiredReductions,
+    });
+    return { ...evaluation, baseline, candidate };
+}