@tea-agent/loop-agent 0.39.0-next.7 → 0.39.0-next.9

package/CHANGELOG.md

@@ -11,14 +11,23 @@
 - `design-review` / `final-design-review` 提示改为消费契约 JSON（注入契约字段摘要），不再要求读取 plan prose
 - Console「模型与认证」页新增模型矩阵编辑器：展示并允许编辑 `harness.json executors.pi` 的 LOW/MED/HIGH 三档模型；输入框从 readiness 结构化投影 `piModelMatrix` 预填（provider/model 或裸 model id），本地内联校验（空串 / `default` 哨兵 / 畸形 `provider/`、`/model`、`a//b`）非法时禁用保存；保存经既有 `POST /api/operator/v1/operations` 派发 `savePiModelMatrix`，复用 HTTP 层 `evaluateMutationGate`（boot capability cookie + `x-loop-console-confirmation` 头 + Origin/Host/Sec-Fetch-Site），读全文档后原子写 tmp+fsync+rename（保留 `$schema` 与其余字段），成功后自动重测 readiness 并对活动 Chat session 触发 `/sessions/:id/reload`（409 `PI_SESSION_BUSY` 给出可恢复提示）
 - `GET /api/operator/v1/readiness` 的 probe 新增 `piModelMatrix` 结构化投影（向后兼容，不改动既有 `modelsMessage`）
+- 组件选型规范合规（ADR 0016）：契约 schema 新增可选 `uiComponentChoices[]`（`{ purpose, component, decision(specified|reuse-existing|new), specReference{path,section,line}|null, rationale }`），`specified` 必须给非空 `specReference`、`new` 不得携带、空串拒绝；`schemaVersion` 保持 1；`docs/templates/frontend-implementation-contract.schema.json` 同步
+- `frontend-prewrite-gate` 新增三个 `retryable-invalid` failureCode：`component-spec-reference-invalid`（specReference.path 非受支持规范路径）、`component-spec-not-cited`（未在 openspec-citations 引用块引用或未真实读取）、`component-choices-missing`（组件/主题候选桶非空且契约有 UI 可见工作而 `uiComponentChoices` 缺失/空）
+- gate 配置新增可选 `componentSpecCandidatePaths`（旧 DAG 缺字段兼容）；`init-hybrid` 从 `designEvidence.classified.component ∪ theme ∪ rule.components` 冻结注入，capability context 强调组件/主题桶语义，plan/revision/design-review/final-design-review 提示加入硬规则与 BAD/GOOD 示例
+- `frontend-plan.md` 新增 `Component Selection (spec conformance)` 章节（纯函数确定性渲染，缺省 `_(not specified)_`）
 
 - `frontend-prewrite-gate` 的 OpenSpec 读取校验支持 `task.json.frontendOpenspec` 配置：`policy` 缺省 `cited`（候选 = `requiredReadPaths` ∪ 任务源显式引用的 openspec 路径），`scan-strict` 保留止血任务后的全量必读语义；`requiredReadPaths` 中非 openspec 支持路径在生成期确定性失败
 - 确定性引用块协议：生效 plan 输出在 fenced `json` 契约块后追加 `openspec-citations` fenced 块（每行一个 JSON `{"path","section","line"}`）；gate 解析并与生效 plan/review 节点的成功 read 事件核验，新增 `openspec-citation-block-unparseable` / `openspec-not-cited` / `openspec-citation-not-read` 三个 retryable-invalid failureCode（防捏造、防遗漏）
 - `src/shared/openspec-spec.ts` 新增 `extractTaskSourceOpenspecPaths` 纯函数（反引号内联、markdown 链接目标、裸路径 token → 归一化 → spec 过滤 → 治理子树排除 → 去重排序）
 - 生成期把 `openspecPolicy` 与候选来源元数据（`openspecCandidateSources.declared` / `taskSourceCited` / `scanStrict`）冻结进 prewrite gate 配置；`task advance` 的 advisories 说明当前模式与候选来源
 
+### 修复
+
+- `frontend-implementation-contract.schema.json` 的 `uiComponentChoices` items 补 `if/then` 决策语义（`specified` ⇒ `specReference` 必填非 null；`new` ⇒ `specReference` 为 null/缺失）；`frontend-plan-render.ts` 空 `section` 不再渲染尾随 `#`；ADR 0016 增补「门禁边界」小节
+
 ### 文档
 
+- 新增 `docs/decisions/0016-frontend-component-conformance.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-implementation-contract.schema.json`、`skills/frontend-implementation/references/design-spec.md`、`skills/frontend-implementation/references/node-contracts.md`、`skills/frontend-design-review/references/review-checklist.md`、`CONTEXT.md`
 - 新增 `docs/decisions/0015-frontend-plan-json-only-contract.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-implementation-contract.schema.json`、`skills/frontend-implementation/references/node-contracts.md`
 - 新增 `docs/decisions/0014-openspec-gate-claim-verification.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-task-constraints.md`、`docs/templates/frontend-design-contract.md`、`skills/frontend-implementation/references/node-contracts.md`
 

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "version": "0.37.0",
-  "gitSha": "21814008c0dd62e8ff8de012c1e66143600e093e",
-  "builtAt": "2026-08-17T17:17:00.338Z"
+  "gitSha": "aaa51e1fe0a1b8731731152ae34de25ed4c8ff0d",
+  "builtAt": "2026-08-18T06:52:28.616Z"
 }

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

@@ -191,6 +191,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
@@ -318,6 +354,7 @@ export const frontendImplementationContractSchema = z
     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(),
@@ -396,6 +433,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({
@@ -691,6 +748,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(".."))
@@ -1379,6 +1448,7 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         dependencyPolicy: asString(record.dependencyPolicy) || undefined,
         residualRisks: asStringArray(record.residualRisks),
         realIntegrationGap: asString(record.realIntegrationGap) || undefined,
+        uiComponentChoices: normalizeUiComponentChoices(record.uiComponentChoices),
     };
 }
 /**

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

@@ -33,6 +33,20 @@ 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",
@@ -52,6 +66,9 @@ export function renderFrontendPlanMarkdown(contract) {
         "## Styling & Component Strategy",
         contract.stylingStrategy || "_(not specified)_",
         "",
+        "## Component Selection (spec conformance)",
+        componentSelection(contract),
+        "",
         "## Interaction Notes",
         interactionNotes(contract),
         "",

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

@@ -35,6 +35,9 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "openspec-citation-block-unparseable",
     "openspec-not-cited",
     "openspec-citation-not-read",
+    "component-spec-reference-invalid",
+    "component-spec-not-cited",
+    "component-choices-missing",
     "contract-too-large",
 ]);
 export const frontendPrewriteResultV1Schema = z
@@ -785,6 +788,87 @@ export async function runFrontendPrewriteGate(input) {
             }
         }
     }
+    // Component selection spec conformance (ADR 0016). Deterministic cross-check
+    // that declared component/token selections trace to the frontend spec
+    // (openspec/ai_workspace component + theme) instead of a model's ad-hoc
+    // "better" choice. Runs after the openspec read gate so citation + read
+    // evidence are already resolved.
+    const componentChoices = analysis.canonical.uiComponentChoices ?? [];
+    const componentSpecCandidates = input.config.componentSpecCandidatePaths ?? [];
+    const hasUiVisibleWork = analysis.canonical.uiStates.some((state) => state.applicable) ||
+        analysis.canonical.interactions.length > 0;
+    if (componentSpecCandidates.length > 0 &&
+        hasUiVisibleWork &&
+        componentChoices.length === 0) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy,
+            classification: "retryable-invalid",
+            failureReason: "frontend prewrite gate: the canonical contract has UI-visible work but uiComponentChoices is missing or empty while the generation-frozen component/theme specification bucket is non-empty. 为每个 UI 用途声明组件选型（decision: specified | reuse-existing | new），specified 必须给 specReference.path/section/line，new 必须给 rationale 声明偏差。",
+            failureCode: "component-choices-missing",
+            openspecReadPaths,
+            openspecCandidatePaths: candidatePaths,
+        });
+    }
+    const componentSpecReferences = componentChoices
+        .map((choice) => ({
+        raw: choice.specReference?.path ?? "",
+        normalized: choice.specReference?.path
+            ? normalizeCitationPath(choice.specReference.path, candidateRoot)
+            : null,
+    }))
+        .filter((ref) => ref.raw.length > 0);
+    if (componentSpecReferences.length > 0) {
+        const invalidRefs = [
+            ...new Set(componentSpecReferences
+                .filter((ref) => !ref.normalized ||
+                !isOpenspecSpecFilePath(ref.normalized))
+                .map((ref) => ref.raw)),
+        ];
+        if (invalidRefs.length > 0) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths are not supported openspec/ai_workspace spec files: ${invalidRefs.join(", ")}`,
+                failureCode: "component-spec-reference-invalid",
+                openspecReadPaths,
+                openspecCandidatePaths: candidatePaths,
+            });
+        }
+        if (openspecPolicy === "cited") {
+            const parsedCitations = parseOpenspecCitations(planText, candidateRoot);
+            const citedPaths = new Set(parsedCitations.citations.map((citation) => citation.path));
+            const readSet = new Set(openspecReadPaths);
+            const uncorroborated = [
+                ...new Set(componentSpecReferences
+                    .filter((ref) => !ref.normalized ||
+                    !citedPaths.has(ref.normalized) ||
+                    !readSet.has(ref.normalized))
+                    .map((ref) => ref.raw)),
+            ];
+            if (uncorroborated.length > 0) {
+                return finalizePrewrite(input, {
+                    ...basePending,
+                    verdict,
+                    candidateJsonSha256: analysis.candidateJsonSha256,
+                    normalizationActions: [],
+                    mockStrategy,
+                    classification: "retryable-invalid",
+                    failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths were not cited in the plan openspec-citations block or lack a successful read event: ${uncorroborated.join(", ")}`,
+                    failureCode: "component-spec-not-cited",
+                    openspecReadPaths,
+                    openspecCandidatePaths: candidatePaths,
+                });
+            }
+        }
+    }
     // Render the deterministic plan.md from the canonical contract (fail-closed
     // before any artifact is written: no contract, no writer authorization).
     let planMarkdown;

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

@@ -2246,6 +2246,15 @@ const openspecCitationInstruction = [
     '该块内每行一个 JSON 对象 {"path":"<repo 相对 openspec 路径>","section":"<命中章节或空串>","line":<int 或 null>}，必须逐条列出你在本计划中实际读取并应用的每个 openspec 规范文件。',
     "prewrite gate 会用真实 read 事件核验每条引用：引用存在但无成功 read 事件 → openspec-citation-not-read；契约冻结的必读候选未被引用 → openspec-not-cited；两者都 fail-closed。不要引用未读取的路径。",
 ].join("\n");
+const frontendComponentConformanceInstruction = [
+    "## Component Selection conformance (uiComponentChoices; hard rule)",
+    "每个 UI 用途必须在契约的 uiComponentChoices[] 中声明组件选型：{ purpose, component, decision, specReference, rationale }。",
+    "- decision=specified：前端规范（候选组件/主题桶 + 任务源显式引用）已定义该用途组件 → 必须使用该组件，并给精确 specReference { path, section, line }（path 必须是 openspec/ai_workspace 受支持规范路径）。",
+    "- decision=reuse-existing：复用仓库既有组件/惯例（规范未点名）→ specReference 可为 null，rationale 说明复用的现有组件与依据。",
+    "- decision=new：规范与既有代码均无合适组件 → specReference 必须为 null，rationale 必须说明偏差理由（design-review 审，最终 review 复核）。",
+    "不得静默替换规范组件或自创组件而无偏差声明；spec 已定义该用途组件时不得改选其它组件。",
+    "prewrite gate 确定性交叉校验：specReference.path 非法 → component-spec-reference-invalid；未在 openspec-citations 引用块中引用或未真实读取 → component-spec-not-cited；候选桶非空且契约有 UI 可见工作而 uiComponentChoices 缺失/空 → component-choices-missing。",
+].join("\n");
 function resolveFrontendCapabilityContextBlock(sources) {
     const risk = sources.frontendRisk;
     const capability = sources.frontendProjectCapability;
@@ -2284,6 +2293,7 @@ function resolveFrontendCapabilityContextBlock(sources) {
         else {
             parts.push("(no openspec specification paths discovered — greenfield)");
         }
+        parts.push("component / theme / rule.components 是「组件/主题规范」必读语义桶：规范已定义某用途组件时必须使用它（uiComponentChoices 用 decision=specified + 精确 path/section/line），不得静默替换为自认更合适的组件；无规范定义时才允许 reuse-existing 或 new（new 必须声明偏差 rationale）。这些路径在生成期冻结为 prewrite gate 的 componentSpecCandidatePaths。");
         parts.push("Each consuming node MUST report in its output: applicable rules, the hit path/section/line number for every applied specification, and any conflicts or missing specifications. Missing or conflicting required specifications must fail closed rather than silently substituting nearby repository conventions.");
         parts.push(`A11y capability: ${capability.a11y.status}` +
             (capability.a11y.tools.length
@@ -2492,6 +2502,16 @@ async function buildFrontendHybridDagFromTask(sources) {
             "",
             "### optional plan fields - BAD (present-but-empty strings are rejected):",
             '{"stylingStrategy":"","dependencyPolicy":""}  <-- REJECTED: optional string fields must be non-empty when present; omit them instead',
+            "",
+            "### uiComponentChoices - GOOD (specified with precise spec hit):",
+            '{"purpose":"primary action button","component":"Button","decision":"specified","specReference":{"path":"openspec/schemas/button.md","section":"Variants","line":12},"rationale":"spec mandates Button for primary actions"}',
+            "",
+            "### uiComponentChoices - GOOD (new with deviation rationale; specReference null):",
+            '{"purpose":"loading skeleton","component":"SkeletonCard","decision":"new","specReference":null,"rationale":"no spec or existing component covers skeleton; deviation pending design-review approval"}',
+            "",
+            "### uiComponentChoices - BAD (specified without specReference, or new with specReference):",
+            '{"purpose":"primary action","component":"MyButton","decision":"specified","specReference":null,"rationale":"..."}  <-- REJECTED: specified requires specReference',
+            '{"purpose":"primary action","component":"MyButton","decision":"new","specReference":{"path":"openspec/schemas/button.md","section":"","line":null},"rationale":"..."}  <-- REJECTED: new must not carry specReference',
         ].join("\n");
     })();
     const frontendContractFieldSummary = [
@@ -2504,7 +2524,8 @@ async function buildFrontendHybridDagFromTask(sources) {
         "- mockApi: strategy, productionDefaultOff, activation, endpoints[]",
         "- verificationTargets[]: id, type, commandLabel, file, symbol, requirementIds, uiStates",
         "- designEvidence: source, paths, conflicts; evidenceGaps[]",
-        "- optional: implementationSteps[], stylingStrategy, dependencyPolicy, residualRisks[], realIntegrationGap",
+        "- optional: implementationSteps[], stylingStrategy, uiComponentChoices[], dependencyPolicy, residualRisks[], realIntegrationGap",
+        "- uiComponentChoices[]: purpose, component, decision (specified|reuse-existing|new), specReference { path, section, line } | null, rationale",
         "Do not require or read a separate plan prose section; the contract JSON is the only plan surface.",
     ].join("\n");
     const sourceContext = [
@@ -2681,6 +2702,17 @@ async function buildFrontendHybridDagFromTask(sources) {
         advisories.push("auto 模式已将 Mock 策略收窄为 not-needed：任务源提到接口/API/Mock 需求，但仓库无确认 Mock 能力或无确定性 Mock 验证命令。若项目规范要求 Mock，请声明 frontendMock.verifyCommands 或 policy:required 后重新生成 DAG。");
     }
     const openspecGate = resolveFrontendOpenspecGateConfig(sources);
+    // Generation-frozen component/theme specification bucket (ADR 0016). Derived
+    // from the classified component/theme/rule.components buckets; the prewrite
+    // gate consumes it to enforce uiComponentChoices presence and specReference
+    // cross-checking. `src/task/**` classification logic is intentionally
+    // unchanged — these buckets already partition normativePaths.
+    const classified = sources.frontendProjectCapability?.designEvidence.classified;
+    const componentSpecCandidatePaths = [
+        ...(classified?.component ?? []),
+        ...(classified?.theme ?? []),
+        ...(classified?.rule.components ?? []),
+    ].filter((value, index, array) => array.indexOf(value) === index).sort();
     if (openspecGate.openspecPolicy === "cited") {
         if (openspecGate.openspecCandidatePaths.length === 0) {
             advisories.push("openspec 策略 cited：契约声明的 requiredReadPaths 与任务源引用均为空，prewrite gate 不强制读取 openspec；如需增强规范门禁，请在 task.json.frontendOpenspec.requiredReadPaths 声明必读路径或在任务源中显式引用 openspec 文件。");
@@ -2787,6 +2819,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     sourceContext,
                     mockContextBlock,
                     frontendContractSchemaBlock,
+                    frontendComponentConformanceInstruction,
                     openspecCitationInstruction,
                 ].join("\n\n"),
             },
@@ -2807,6 +2840,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence. A static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint. not-needed otherwise requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
+                    "Component selection conformance is a hard blocking condition: VERDICT: request-revision when the frontend spec (component/theme/rule.components bucket) already defines a component for a purpose but the plan selects another or self-invents one without a declared deviation; when uiComponentChoices is missing/empty for UI-visible work while the frozen component/theme bucket is non-empty; or when any uiComponentChoices specReference.path is not cited in the openspec-citations block or has no successful read event.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
@@ -2835,7 +2869,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Consume frontend-plan-pi (original contract JSON) and frontend-design-review-pi (first design review findings).",
                     "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce an RFC 7386 merge-patch delta against the original contract JSON that addresses every Required Plan Correction from the design findings.",
-                    "The patch delta may update any of these contract fields: requirements, implementationSteps, targets, uiStates, interactions, mockApi, dependencyPolicy, stylingStrategy, verificationTargets, evidenceGaps, residualRisks, realIntegrationGap. Only include fields you change; omit unchanged fields (the gate applies the patch on the original contract). null deletes a key; arrays and scalars replace; plain objects merge recursively.",
+                    "The patch delta may update any of these contract fields: requirements, implementationSteps, targets, uiStates, interactions, mockApi, dependencyPolicy, stylingStrategy, uiComponentChoices, verificationTargets, evidenceGaps, residualRisks, realIntegrationGap. Only include fields you change; omit unchanged fields (the gate applies the patch on the original contract). null deletes a key; arrays and scalars replace; plain objects merge recursively.",
                     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.",
@@ -2847,6 +2881,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     sourceContext,
                     frontendContractSchemaBlock,
                     mockContextBlock,
+                    frontendComponentConformanceInstruction,
                     openspecCitationInstruction,
                 ].join("\n\n"),
             },
@@ -2875,6 +2910,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Recheck the selected Mock / API strategy, contract-to-fixture mapping, authorized paths/dependencies, explicit activation, production-default-off behavior, behavior verification, and Real Integration Gap. MOCK_STRATEGY: blocked cannot receive VERDICT: pass.",
                     "Review every explicit REQ-/BR-/AC- mapping; the downstream prewrite gate also checks identifier retention deterministically.",
                     "Request revision if any design gap remains, if corrections are incomplete, or if the revised plan introduces new unaddressed issues.",
+                    "Also request revision for component selection non-conformance: spec-defined components silently replaced or self-invented without a declared deviation, uiComponentChoices missing for UI-visible work, or a uiComponentChoices specReference.path not cited in the openspec-citations block / not actually read.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
@@ -2933,6 +2969,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                             scanStrict: openspecGate.openspecCandidateSources.scanStrict,
                         },
                         openspecCandidatePaths: openspecGate.openspecCandidatePaths,
+                        componentSpecCandidatePaths,
                     },
                     cwd: ".",
                     timeoutMs: 60000,

package/dist/workflows/dag/types.js

@@ -193,6 +193,16 @@ export const dagFrontendPrewriteGateSchema = z.object({
     requireSourceFreshness: z.literal(true),
     implementationWriteSet: z.array(z.string().min(1)).min(1).optional(),
     openspecCandidatePaths: z.array(openspecCandidatePathSchema).default([]),
+    /**
+     * Generation-frozen component/theme specification bucket. Derived from
+     * `designEvidence.classified.component ∪ theme ∪ rule.components` at DAG
+     * generation. When non-empty and the canonical contract has UI-visible
+     * work, the prewrite gate requires a non-empty `uiComponentChoices` and
+     * cross-checks each `specReference.path` against this set + the effective
+     * plan openspec-citations block. Legacy DAGs without this field keep the
+     * field-absent semantics (component-choices-missing is not enforced).
+     */
+    componentSpecCandidatePaths: z.array(openspecCandidatePathSchema).optional(),
     /**
      * OpenSpec gate policy. Omitted on legacy DAGs: the runtime treats
      * undefined as scan-strict so pre-existing full-read semantics are

package/docs/templates/frontend-implementation-contract.schema.json

@@ -19,6 +19,7 @@
     "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } },
     "implementationSteps": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "stylingStrategy": { "type": "string", "minLength": 1 },
+    "uiComponentChoices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["purpose", "component", "decision", "rationale"], "properties": { "purpose": { "type": "string", "minLength": 1 }, "component": { "type": "string", "minLength": 1 }, "decision": { "enum": ["specified", "reuse-existing", "new"] }, "specReference": { "anyOf": [{ "$ref": "#/$defs/uiComponentSpecReference" }, { "type": "null" }] }, "rationale": { "type": "string", "minLength": 1 } }, "allOf": [ { "if": { "properties": { "decision": { "const": "specified" } }, "required": ["decision"] }, "then": { "required": ["specReference"], "properties": { "specReference": { "$ref": "#/$defs/uiComponentSpecReference" } } } }, { "if": { "properties": { "decision": { "const": "new" } }, "required": ["decision"] }, "then": { "properties": { "specReference": { "type": "null" } } } } ] } },
     "dependencyPolicy": { "type": "string", "minLength": 1 },
     "residualRisks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "realIntegrationGap": { "type": "string", "minLength": 1 }
@@ -28,6 +29,7 @@
     "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
     "requirementId": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" },
     "gap": { "type": "object", "additionalProperties": false, "required": ["description", "blocking"], "properties": { "requirementId": { "$ref": "#/$defs/requirementId" }, "description": { "type": "string", "minLength": 1 }, "blocking": { "type": "boolean" } } },
-    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } }
+    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } },
+    "uiComponentSpecReference": { "type": "object", "additionalProperties": false, "required": ["path", "section"], "properties": { "path": { "$ref": "#/$defs/path" }, "section": { "type": "string" }, "line": { "anyOf": [{ "type": "integer" }, { "type": "null" }] } } }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.7",
+  "version": "0.39.0-next.9",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-design-review/references/review-checklist.md

@@ -12,6 +12,7 @@
 - Cite knowledge base, `openspec/schemas/`, `openspec/project-specs/`, and `ai_workspace/` as parallel sources; failed or empty
   knowledge queries must still search `<repoRoot>/openspec/schemas/`, `<repoRoot>/openspec/project-specs/`, and `<repoRoot>/ai_workspace/`.
 - Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths for both.
+- Component selection conformance: every UI purpose must be declared in the contract `uiComponentChoices[]`. `specified` must carry a non-empty `specReference { path, section, line }` hitting a supported openspec/ai_workspace spec; `new` must declare a deviation rationale with `specReference` null; a spec-defined component must not be silently replaced or self-invented without a declared deviation.
 
 ## Interaction / Quality
 
@@ -37,5 +38,6 @@
 ## Verdict Matrix
 
 - Request revision for coverage gaps, unsafe scope, unauthorized deps, unresolved required interaction, missing required verification, skipped local specification fallback (`openspec/schemas/`, `openspec/project-specs/`, or `ai_workspace/`), unsafe/missing Mock strategy, or Mock evidence presented as real integration.
+- Request revision for component selection non-conformance: spec-defined components silently replaced or self-invented without a declared deviation, `uiComponentChoices` missing for UI-visible work, or a `uiComponentChoices` `specReference.path` not cited in the `openspec-citations` block / not actually read.
 - Knowledge-base unavailable but relevant OpenSpec or `ai_workspace/` rules applied is advisory only.
 - Optional cleanup that cannot affect acceptance is advisory.

package/skills/frontend-implementation/references/design-spec.md

@@ -5,27 +5,21 @@
 Knowledge base, OpenSpec, and `ai_workspace/` are parallel specification sources:
 
 1. Attempt the configured component/design knowledge-base query first when a
-   connector is available in the execution environment.
-2. Regardless of knowledge-base success, failure, timeout, no match, or no
-   configuration, also recursively search `openspec/schemas/`,
-   `openspec/project-specs/`, and `ai_workspace/` for index files and relevant content.
+   connector is available.
+2. Regardless of knowledge-base success/failure/timeout/no-match, also
+   recursively search `openspec/schemas/`, `openspec/project-specs/`, and
+   `ai_workspace/` for index files and relevant content.
 3. Treat relevant matches from both sources as the current project's
    specification for this run.
 4. Only then use component source, tokens, stories, tests, and pages as
    non-normative repository fallback.
 
-Never skip local OpenSpec or `ai_workspace/` sources for neighboring-code
-conventions, even when a knowledge-base query returned results. Report source
-conflicts instead of combining them. Explicit task requirements remain the
-contract; flag conflicts with knowledge-base or openspec specification rules.
+Never skip local OpenSpec or `ai_workspace/` for neighboring-code conventions,
+even when a knowledge-base query returned results. Report source conflicts instead
+of combining them. Explicit task requirements remain the contract.
 
-## Knowledge Base Connection — TODO
-
-Request format is undecided. TODO: define connector/owner, namespaces, secret-free
-auth, query fields, result identity/version/time, and failure behavior.
-
-Attempt only a connector actually available in the execution environment. Otherwise
-record `not-configured` and run the openspec fallback; never invent a connection.
+Connector format is TODO; attempt only an available connector, otherwise record
+`not-configured` and run the openspec fallback (never invent a connection).
 
 ## openspec Fallback Procedure
 
@@ -33,10 +27,10 @@ record `not-configured` and run the openspec fallback; never invent a connection
   and `<repoRoot>/ai_workspace/` when present; enumerate supported files recursively.
 - Read indexes first, then search names/content using task, route, component,
   interaction, theme, token, and state terms.
-- Read relevant matches in context; do not treat a filename-only hit as a rule.
+- Read matches in context; a filename-only hit is not a rule.
 - Record search terms, inspected/matched paths, headings or tight line ranges,
   applied rules, and conflicts.
-- If both directories or relevant rules are absent, record that fact before using
+- If both directories or relevant rules are absent, record that before using
   repository fallback.
 
 ## Retrieval Evidence
@@ -54,6 +48,9 @@ and conflicts. `openspec fallback` includes terms, paths/headings/lines, rules,
 
 - Reuse confirmed primitives unless a new pattern is authorized.
 - Define applicable states and responsive behavior before implementation.
-- Cite knowledge-base or openspec specification evidence for component/token
-  choices; label weaker repository fallback.
+- Cite knowledge-base or openspec spec evidence for component/token choices;
+  label weaker repo fallback.
 - Make deviations and unresolved gaps explicit.
+- Contract `uiComponentChoices[]` per UI purpose: `specified` needs
+  `specReference {path,section,line}`; `new` needs null ref + rationale; never
+  silently replace a spec-defined component.

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

@@ -5,18 +5,20 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 ## Core nodes
 
 - **`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. Search+read `openspec/schemas/`, `openspec/project-specs/`, `ai_workspace/` first. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap. **JSON-only**: one-line lead-in + **exactly one** fenced `json` block (`frontend-implementation-contract-v1`) + one `openspec-citations` block. No plan prose; plan.md is rendered by the prewrite gate. `frontend-contract-json-pi`/`frontend-contract-json-validate-shell` don't exist. IDs+paths aren't sufficient behavior semantics. Use `uiStates: []` for logic-only changes; don't invent UI states. Applicable states need behavior/implementation/verification; non-applicable need a reason. Non-`not-needed` needs frozen Mock verify commands (`frontendMock.verifyCommands`/`package.json` mock script/capability seed); `auto` with absent/ambiguous capability or no command → `not-needed`; `required` without a command → generation-time blocked. Initial pass uses original plan; only exact `request-revision` runs revision + final review. Small-risk: one design review.
-- **`frontend-prewrite-gate-shell`**: sole write authorization. Resolve effective plan (revised if revision ran, else original) + review; require exact pass; retain every REQ/BR/AC id; enforce Mock policy; validate schema/source binding+writeSet containment; materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block (multiple candidates fail closed `invalid-output`). Fallback only when conditional primary absent; existing malformed primary fails closed. Generation-time blocked Mock yields one deterministic blocking shell node, no writer.
+- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets; fact vs inference vs gap. Search+read `openspec/schemas/`, `openspec/project-specs/`, `ai_workspace/` first. Output stack, styling, conventions, state/data, test entry points, reuse, risks.
+- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; steps, in-bound files, UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap. **JSON-only**: one-line lead-in + **exactly one** fenced `json` block (`frontend-implementation-contract-v1`) + one `openspec-citations` block. No plan prose; plan.md is rendered by the gate. `frontend-contract-json-pi`/`frontend-contract-json-validate-shell` don't exist; IDs+paths ≠ behavior semantics. Use `uiStates: []` for logic-only changes; don't invent UI states. Applicable states need behavior/implementation/verification; non-applicable need reasons. Non-`not-needed` needs frozen Mock verify commands (`frontendMock.verifyCommands`/`package.json` mock script/capability seed); `auto` with absent/ambiguous capability or no command → `not-needed`; `required` without a command → generation-time blocked. Initial pass = original plan; only `request-revision` runs revision+final review; small-risk = one review.
+  - `uiComponentChoices[]` (optional): `{purpose, component, decision, specReference, rationale}`; `specified` needs `specReference{path,section,line}`; `new` needs null ref+rationale.
+- **`frontend-prewrite-gate-shell`**: sole write authorization. Resolve effective plan (revised if revision ran, else original) + review; require exact pass; retain every REQ/BR/AC id; enforce Mock policy; validate schema/source binding+writeSet containment; materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block (multiple candidates fail closed `invalid-output`). Fallback only when conditional primary absent; malformed primary fails closed. Generation-time blocked Mock yields one blocking shell node, no writer.
   - `verificationTarget.commandLabel` must be a **frozen command label** from `verifyEvidence.commandLabels`; others fail closed (`invalid-output`). Empty frozen set (no `run.json`) skips check.
   - `mockApi.strategy !== "not-needed"` fails closed when `mockCommandLabels` empty (`no authorized Mock verification commands`).
-  - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); candidates = `requiredReadPaths` ∪ task-source citations; effective plan must append one fenced `openspec-citations` block (one JSON `{"path","section","line"}` per line). Candidates non-empty but block missing/unparseable → `openspec-citation-block-unparseable`; candidate not cited → `openspec-not-cited`; cited path without successful read event in plan/review → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement (generation-time advisory). `scan-strict` keeps auto-discovered full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
+  - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); candidates = `requiredReadPaths` ∪ task-source citations; effective plan must append one fenced `openspec-citations` block (one JSON `{"path","section","line"}` per line). Candidates non-empty but block missing/unparseable → `openspec-citation-block-unparseable`; candidate not cited → `openspec-not-cited`; cited path without read event → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement. `scan-strict` keeps full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
+  - Component conformance: missing `uiComponentChoices` (frozen bucket non-empty + UI-visible work) → `component-choices-missing`; bad/uncited `specReference.path` → `component-spec-reference-invalid` / `component-spec-not-cited`.
   - revisionPatch mode: revision output is an RFC 7386 merge-patch delta applied on the original contract node (`planFallbackFromNodeIds[0]`); legacy DAGs keep full-contract semantics. Size guard: canonical serialization >64KB → `retryable-invalid` + `contract-too-large`.
-- **`frontend-implement-pi`**: sole regular exclusive writer; uses `frontend-bounded-implement` (not this skill). Stay in `writeSet`; real requests default-on. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths/guesses. First line `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks against attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. `not-needed` keeps real integration pending unless real backend has fresh evidence.
+- **`frontend-implement-pi`**: sole regular exclusive writer; uses `frontend-bounded-implement` (not this skill). Stay in `writeSet`; real requests default-on. Atomic handler/intercept/adapter with tests. Stop on forbidden paths/guesses. First line `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks against attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. `not-needed` keeps real integration pending unless real backend has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)
 
-- `frontend-verify-assess-shell` runs Mock/static/behavior groups, binds `verificationTargets` to command labels + file/symbol evidence, writes `frontend-verification-trace.json` + `frontend-repair-assessment.json`; browser/visual stay `not-run`.
+- `frontend-verify-assess-shell` runs Mock/static/behavior groups, binds `verificationTargets` to command labels+evidence, writes `frontend-verification-trace.json`+`frontend-repair-assessment.json`; browser/visual stay `not-run`.
 - `frontend-review-context-shell` captures real diff; combines contract, effective trace, repair assessment, diff into `contracts/frontend-review-context.json`.
 - Implement stages: (1) contract confirm (2) tests sync (3) component/UI (4) API/Mock (5) frozen checks (6) diff cleanup. Summary: Contract Ref, Changed Files, Requirements, UI States, Tests, Verification Attempts, Deviations, Residual Risks.