@tea-agent/loop-agent 0.39.0-next.6 → 0.39.0-next.8

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 } } } },
     "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.6",
+  "version": "0.39.0-next.8",
   "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.
 

package/dist/worker/console/static/assets/channel-CgVmTdib.js

@@ -1 +0,0 @@
-import{ag as o,ah as n}from"./mermaid.core-Dudn9krq.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/worker/console/static/assets/classDiagram-JCYQIIEL-CfJu47mG.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-ClNxnCSZ.js";import{_ as i}from"./mermaid.core-Dudn9krq.js";import"./chunk-5VM5RSS4-BoUlzoKw.js";import"./chunk-XXDRQBXY-CAPr_ybW.js";import"./chunk-KBJHAD2P-BwFyCP8o.js";import"./chunk-2GRJ4B5K-Db2uLs2I.js";import"./index-F4oI1Kcc.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/worker/console/static/assets/classDiagram-v2-OCEON4UE-CfJu47mG.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-GF5L2VYU-ClNxnCSZ.js";import{_ as i}from"./mermaid.core-Dudn9krq.js";import"./chunk-5VM5RSS4-BoUlzoKw.js";import"./chunk-XXDRQBXY-CAPr_ybW.js";import"./chunk-KBJHAD2P-BwFyCP8o.js";import"./chunk-2GRJ4B5K-Db2uLs2I.js";import"./index-F4oI1Kcc.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};