@tea-agent/loop-agent 0.38.0 → 0.38.2

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

@@ -13,6 +13,7 @@ export const frontendNormalizationActionSchema = z.enum([
     "strip-comments",
     "canonicalize-requirement-ids",
     "canonicalize-verification-alias",
+    "drop-unresolved-verification-symbols",
     "inject-source-binding",
 ]);
 export function sha256Hex(input) {
@@ -102,6 +103,21 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     return [...labels];
 }
 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";
+/**
+ * Build the deterministic, run-owned portion of the frontend contract. The
+ * planner is allowed to fill semantic fields with an RFC 7386 merge patch but
+ * cannot redefine task identity, risk, or the implementation write boundary.
+ */
+export function buildFrontendImplementationContractSkeleton(input) {
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalFrontendContractSourceBinding(input.sourceBinding),
+        riskLevel: input.riskLevel,
+        targets: { files: [...input.targetFiles] },
+        mockApi: { productionDefaultOff: true },
+    };
+}
 /**
  * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
  * installed loop-agent package docs/templates/ path. Package-root discovery
@@ -191,6 +207,42 @@ const gap = z
     blocking: z.boolean(),
 })
     .strict();
+/**
+ * Structured component/token selection contract (ADR 0016). Every user-visible
+ * UI purpose the plan touches must be declared here so the prewrite gate can
+ * deterministically cross-check that the selection comes from the frontend
+ * specification (openspec/ai_workspace component + theme specs) instead of
+ * relying on design-review's soft model judgment.
+ *
+ * - `specified`: the frontend spec mandates this component for the purpose →
+ *   `specReference` is required (path/section/line hit).
+ * - `reuse-existing`: reuse an existing repo component/convention not named by
+ *   the spec → `specReference` may be null, rationale explains the basis.
+ * - `new`: neither spec nor existing code fits → `specReference` must be null,
+ *   rationale must declare the deviation (design-review approves it).
+ *
+ * `specReference` is nullable + optional because `stripNullValuesDeep` strips
+ * null object values before validation, so a `new` choice's `specReference:
+ * null` becomes an absent field; the superRefine below treats absent and null
+ * identically.
+ */
+const uiComponentSpecReferenceSchema = z
+    .object({
+    path: safePath,
+    section: z.string(),
+    line: z.number().int().nullable().optional(),
+})
+    .strict();
+const uiComponentChoiceSchema = z
+    .object({
+    purpose: z.string().min(1),
+    component: z.string().min(1),
+    decision: z.enum(["specified", "reuse-existing", "new"]),
+    specReference: uiComponentSpecReferenceSchema.nullable().optional(),
+    rationale: z.string().min(1),
+})
+    .strict();
+const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
 /**
  * Normalize unstable model emissions before the strict schema sees them:
  * recursively drop null values (object entries and array elements). A null for
@@ -316,6 +368,12 @@ export const frontendImplementationContractSchema = z
     })
         .strict()).min(1),
     evidenceGaps: z.array(gap),
+    implementationSteps: z.array(z.string().min(1)).optional(),
+    stylingStrategy: z.string().min(1).optional(),
+    uiComponentChoices: uiComponentChoicesSchema.optional(),
+    dependencyPolicy: z.string().min(1).optional(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+    realIntegrationGap: z.string().min(1).optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -391,6 +449,26 @@ export const frontendImplementationContractSchema = z
                 path: ["uiStates"],
             });
     }
+    for (const [index, choice] of (value.uiComponentChoices ?? []).entries()) {
+        if (choice.decision === "specified") {
+            if (!choice.specReference || !choice.specReference.path) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "specified component choice requires a non-empty specReference.path",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+        else if (choice.decision === "new") {
+            if (choice.specReference) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: "new component choice must not carry a specReference",
+                    path: ["uiComponentChoices", index, "specReference"],
+                });
+            }
+        }
+    }
     if (value.mockApi.strategy !== "not-needed") {
         if (value.mockApi.endpoints.length === 0) {
             ctx.addIssue({
@@ -426,6 +504,47 @@ export const frontendImplementationContractSchema = z
         });
     }
 }));
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Apply an RFC 7386 merge-patch on a target contract without mutating it.
+ * `null` removes the key; plain objects merge recursively when the target value
+ * is also a plain object; arrays and scalars replace the whole value. The
+ * result is re-validated by analyzeFrontendImplementationContract before it is
+ * ever materialized, so a patch that removes a required field still fails
+ * closed at the gate.
+ */
+export function applyFrontendContractMergePatch(target, patch) {
+    if (!isPlainObject(patch)) {
+        throw new Error("frontend contract patch must be a JSON object");
+    }
+    const merge = (base, delta) => {
+        if (delta === null)
+            return undefined;
+        if (!isPlainObject(delta))
+            return delta;
+        const result = isPlainObject(base)
+            ? { ...base }
+            : {};
+        for (const [key, value] of Object.entries(delta)) {
+            if (value === null) {
+                delete result[key];
+            }
+            else if (isPlainObject(value) && isPlainObject(result[key])) {
+                result[key] = merge(result[key], value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
+    return merge(target, patch);
+}
+export function applyFrontendImplementationContractPatch(target, patch) {
+    return applyFrontendContractMergePatch(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -648,6 +767,18 @@ function asStringArray(value) {
         .map((item) => asString(item))
         .filter((item) => item.length > 0);
 }
+/**
+ * Pass structured component choices through the free-form compatibility
+ * branch. The strict-shape branch already spreads unknown fields, so only this
+ * explicit constructor needs to re-emit `uiComponentChoices`; a missing/empty
+ * array normalizes to undefined (absent) so the optional schema field stays
+ * compatible with legacy free-form contracts.
+ */
+function normalizeUiComponentChoices(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    return value;
+}
 function normalizeFrontendRoute(value) {
     const route = asString(value).replaceAll("\\", "/").replace(/^\/+/, "");
     if (!route || route === "." || route.split("/").includes(".."))
@@ -1331,6 +1462,12 @@ 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),
+        realIntegrationGap: asString(record.realIntegrationGap) || undefined,
+        uiComponentChoices: normalizeUiComponentChoices(record.uiComponentChoices),
     };
 }
 /**
@@ -1490,6 +1627,206 @@ export async function writeFrontendImplementationContractArtifact(input) {
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
     };
 }
+const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
+    "/schemaVersion",
+    "/sourceBinding",
+    "/riskLevel",
+    "/targets/files",
+    "/mockApi/productionDefaultOff",
+];
+function frontendPlanPatchProtectedPathViolations(patch) {
+    const record = asRecord(patch);
+    if (!record)
+        return ["/"];
+    const violations = [];
+    for (const key of ["schemaVersion", "sourceBinding", "riskLevel"]) {
+        if (Object.hasOwn(record, key))
+            violations.push(`/${key}`);
+    }
+    const targets = asRecord(record.targets);
+    if (targets && Object.hasOwn(targets, "files"))
+        violations.push("/targets/files");
+    const mockApi = asRecord(record.mockApi);
+    if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
+        violations.push("/mockApi/productionDefaultOff");
+    return violations;
+}
+function workspaceRootFromDagRunDir(runDir) {
+    const absolute = path.resolve(runDir);
+    const segments = absolute.split(path.sep);
+    const harnessIndex = segments.lastIndexOf(".harness");
+    if (harnessIndex < 0 ||
+        segments[harnessIndex + 1] !== "dag-runs" ||
+        harnessIndex + 3 >= segments.length) {
+        return null;
+    }
+    const joined = segments.slice(0, harnessIndex).join(path.sep);
+    return joined || path.parse(absolute).root;
+}
+function verificationSymbolMatchesFile(symbol, content) {
+    if (symbol.trim().toLowerCase() === "all describe blocks")
+        return content.includes("describe(");
+    const symbols = symbol.includes(" / ")
+        ? symbol
+            .split(/[（(]/, 1)[0]
+            .split("/")
+            .map((item) => item.trim())
+            .filter(Boolean)
+        : [symbol];
+    return symbols.every((item) => {
+        const describeTitle = item.match(/^describe\((?:['"])(.+?)(?:['"])/i)?.[1];
+        return [item, describeTitle, describeTitle ? "describe(" : undefined]
+            .filter((candidate) => Boolean(candidate))
+            .some((candidate) => content.includes(candidate));
+    });
+}
+async function dropUnresolvedVerificationSymbols(input) {
+    const workspaceRoot = workspaceRootFromDagRunDir(input.runDir);
+    const targets = asRecord(input.contract)?.verificationTargets;
+    if (!workspaceRoot || !Array.isArray(targets))
+        return false;
+    let changed = false;
+    for (const targetValue of targets) {
+        const target = asRecord(targetValue);
+        const file = asString(target?.file);
+        const symbol = asString(target?.symbol);
+        if (!target || !file || !symbol)
+            continue;
+        const absolute = path.resolve(workspaceRoot, file);
+        const relative = path.relative(workspaceRoot, absolute);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative) ||
+            relative.includes("..")) {
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(absolute, "utf8");
+        }
+        catch {
+            // Missing files remain a trace-time hard failure; do not hide them by
+            // changing the optional symbol during candidate normalization.
+            continue;
+        }
+        if (verificationSymbolMatchesFile(symbol, content))
+            continue;
+        delete target.symbol;
+        changed = true;
+    }
+    return changed;
+}
+function extractSingleOpenspecCitationsBlock(text) {
+    const blocks = text.match(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g) ?? [];
+    if (blocks.length !== 1) {
+        throw new Error(`frontend plan patch output must include exactly one fenced openspec-citations block (found ${blocks.length})`);
+    }
+    return blocks[0];
+}
+async function writeFrontendPlanCandidateRaw(input) {
+    const relativePath = path.posix.join("contracts", "candidates", input.nodeId, `attempt-${input.attempt}.raw.md`);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text.endsWith("\n") ? input.text : `${input.text}\n`);
+    return relativePath;
+}
+/**
+ * Compile the planner's editable RFC 7386 patch against the deterministic
+ * runtime skeleton. Every attempt is preserved under contracts/candidates so
+ * format/schema failures can be inspected and replayed without trusting model
+ * prose. A successful result returns canonical full-contract text for all
+ * downstream review and prewrite nodes.
+ */
+export async function validateFrontendPlanPatchNodeOutput(input) {
+    const nodeId = input.nodeId ?? "frontend-plan-pi";
+    const attempt = input.attempt ?? 1;
+    const candidateDir = path.posix.join("contracts", "candidates", nodeId);
+    const rawPath = await writeFrontendPlanCandidateRaw({
+        runDir: input.runDir,
+        nodeId,
+        attempt,
+        text: input.text,
+    });
+    const reportBase = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
+        nodeId,
+        attempt,
+        rawPath,
+        protectedPaths: [...FRONTEND_PLAN_PATCH_PROTECTED_PATHS],
+        candidateRawSha256: sha256Hex(input.text),
+    };
+    let extractedPatchPath;
+    let extractedPatchSha256;
+    const writeReport = async (value) => {
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
+            ...reportBase,
+            ...(extractedPatchPath
+                ? { extractedPatchPath, extractedPatchSha256 }
+                : {}),
+            ...value,
+        });
+    };
+    try {
+        if (!input.sourceBinding)
+            throw new Error("frontend plan patch validator requires DAG sourceBinding");
+        const skeleton = input.structuredContractOutput?.skeleton;
+        if (!skeleton)
+            throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
+        const patch = extractFrontendImplementationJson(input.text);
+        if (!isPlainObject(patch))
+            throw new Error("frontend plan patch must extract to one JSON object");
+        extractedPatchPath = path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`);
+        const extractedArtifact = await writeDeterministicJsonArtifact(input.runDir, extractedPatchPath, patch);
+        extractedPatchSha256 = extractedArtifact.sha256;
+        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+        const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+        if (protectedViolations.length > 0)
+            throw new Error(`frontend plan patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+        const merged = applyFrontendContractMergePatch(skeleton, patch);
+        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
+            runDir: input.runDir,
+            contract: merged,
+        });
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
+        await writeReport({
+            classification: "accepted-normalized",
+            normalizedContractPath: path.posix.relative(input.runDir.replaceAll(path.sep, "/"), normalizedArtifact.path.replaceAll(path.sep, "/")),
+            normalizedContractSha256: normalizedArtifact.sha256,
+            normalizationActions: [
+                "apply-runtime-skeleton",
+                ...(droppedUnresolvedSymbols
+                    ? ["drop-unresolved-verification-symbols"]
+                    : []),
+                ...analysis.normalizationActions,
+            ],
+            errors: [],
+        });
+        return {
+            ok: true,
+            contract: analysis.canonical,
+            normalizedText: [
+                "Frontend implementation contract compiled from the runtime skeleton.",
+                "",
+                "```json",
+                serializeDeterministicJson(analysis.canonical),
+                "```",
+                citationsBlock,
+            ].join("\n"),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        await writeReport({
+            classification: "retryable-invalid",
+            normalizationActions: [],
+            errors: [{ path: "$", code: "invalid-output", message: reason }],
+        });
+        return { ok: false, reason };
+    }
+}
 /**
  * Node-output self-check for plan nodes that produce the implementation
  * contract. Mirrors the prewrite gate validation so schema/typo/null violations
@@ -1514,6 +1851,55 @@ export async function validateFrontendContractNodeOutput(input) {
         };
     }
 }
+/**
+ * Node-output self-check for the plan revision node, which emits an RFC 7386
+ * merge-patch delta against the original contract instead of a full contract.
+ * Deliberately loose and format-level: the output must contain exactly one
+ * ```openspec-citations fenced block and must extract (after the citations
+ * blocks are stripped) to exactly one JSON object. The delta carries no
+ * schemaVersion/targets, so no full-contract schema/semantic checks run here;
+ * content parsing, patch application, and merged-contract validation stay with
+ * the prewrite gate, which remains the only authority.
+ */
+export async function validateFrontendRevisionPatchNodeOutput(input) {
+    let citationsBlock;
+    try {
+        citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // Strip the citation blocks before extraction: their per-row JSON objects
+    // would otherwise count as competing balanced objects in the extractor.
+    const textWithoutCitations = input.text.replace(citationsBlock, "");
+    let patch;
+    try {
+        patch = extractFrontendImplementationJson(textWithoutCitations);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+        return {
+            ok: false,
+            reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
+        };
+    }
+    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+    if (protectedViolations.length > 0) {
+        return {
+            ok: false,
+            reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
+        };
+    }
+    return { ok: true, contract: patch };
+}
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);
     return writeFrontendImplementationContractArtifact({

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

@@ -0,0 +1,90 @@
+/**
+ * Deterministic Markdown renderer for a canonical frontend implementation
+ * contract. The prewrite gate materializes this as `contracts/frontend-plan.md`
+ * next to the contract JSON, so plan prose is never produced by the model — it
+ * is derived from the single machine contract at materialization time.
+ *
+ * The function is pure: the same contract always renders byte-identical
+ * Markdown, and absent optional fields render as placeholders without throwing.
+ */
+function bulletList(items) {
+    if (!items || items.length === 0)
+        return "";
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function requirementsCoverage(contract) {
+    const lines = contract.requirements.map((requirement) => `- ${requirement.id}: ${requirement.expectedOutcome}`);
+    return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
+}
+function uiStateHandling(contract) {
+    const lines = contract.uiStates.map((state) => {
+        if (state.applicable) {
+            return `- ${state.name}: ${state.expectedBehavior ?? ""}`;
+        }
+        return `- ${state.name}: not applicable — ${state.notApplicableReason ?? ""}`;
+    });
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function interactionNotes(contract) {
+    const lines = contract.interactions.map((interaction) => `- ${interaction.name}: ${interaction.trigger} → ${interaction.expectedBehavior}`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function verificationPlan(contract) {
+    const lines = contract.verificationTargets.map((target) => `- ${target.id}: ${target.commandLabel} (${target.file})`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function componentSelection(contract) {
+    const choices = contract.uiComponentChoices ?? [];
+    if (choices.length === 0)
+        return "_(not specified)_";
+    return choices
+        .map((choice) => {
+        const specReference = choice.specReference;
+        const refText = specReference
+            ? ` ${specReference.path}${specReference.section ? `#${specReference.section}` : ""}${specReference.line != null ? `:${specReference.line}` : ""}`
+            : "";
+        return `- ${choice.purpose} → ${choice.component} (${choice.decision})${refText ? `:${refText}` : ""} — ${choice.rationale}`;
+    })
+        .join("\n");
+}
+export function renderFrontendPlanMarkdown(contract) {
+    return [
+        "# Frontend Implementation Plan",
+        "",
+        "## Requirement Coverage",
+        requirementsCoverage(contract),
+        "",
+        "## Implementation Steps",
+        bulletList(contract.implementationSteps) || "_(not specified)_",
+        "",
+        "## Target Files",
+        bulletList(contract.targets.files) || "_(none)_",
+        "",
+        "## UI State Handling",
+        uiStateHandling(contract),
+        "",
+        "## Styling & Component Strategy",
+        contract.stylingStrategy || "_(not specified)_",
+        "",
+        "## Component Selection (spec conformance)",
+        componentSelection(contract),
+        "",
+        "## Interaction Notes",
+        interactionNotes(contract),
+        "",
+        "## Mock & API Strategy",
+        contract.mockApi.strategy,
+        "",
+        "## Dependency Policy",
+        contract.dependencyPolicy || "_(not specified)_",
+        "",
+        "## Verification Plan",
+        verificationPlan(contract),
+        "",
+        "## Real Integration Gap",
+        contract.realIntegrationGap || "_(not specified)_",
+        "",
+        "## Residual Risks",
+        bulletList(contract.residualRisks) || "_(none)_",
+    ].join("\n") + "\n";
+}