@tea-agent/loop-agent 0.39.0-beta.3 → 0.39.0-beta.4

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.39.0-beta.3",
-  "gitSha": "d9fdc0eac8d061d1285094f7d9d1531b669e5266",
-  "builtAt": "2026-08-23T05:55:12.549Z"
+  "version": "0.39.0-beta.4",
+  "gitSha": "c2dcaef179cd0526f8f5779e866d0e1103451baa",
+  "builtAt": "2026-08-23T07:52:07.528Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -1176,6 +1176,48 @@ export async function createFrontendContractTools(input) {
             return receipt(result);
         },
     }));
+    // OpenSpec selection committed as individual typed facts (one path per
+    // call) so a large candidate set never exceeds a single model output
+    // budget: each tool call carries exactly one {path, disposition,
+    // rationale} row and the ledger accumulates them across calls. Only
+    // positive classifications (required | relevant) are legal; unmentioned
+    // candidates default to irrelevant at the prewrite gate.
+    const recordOpenspecSelectionTool = defineTool({
+        name: "record_openspec_selection",
+        label: "record_openspec_selection",
+        description: "Commit one OpenSpec candidate classification (origin=contract openspec-selection fact). Call once per path you actually use or consult: required (must be read and cited) or relevant (informs planning). Never call it for irrelevant candidates — unmentioned candidates default to irrelevant. You may call it many times; one row per call.",
+        promptSnippet: "Commit one OpenSpec candidate classification (required | relevant); one path per call; skip irrelevant candidates.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: "Repo-relative candidate spec path, e.g. openspec/project-specs/ui/ucp-components-md/AdvancedSearch.md",
+            }),
+            disposition: Type.Enum({
+                required: "required",
+                relevant: "relevant",
+            }),
+            rationale: Type.String({}),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const path = typeof params?.path === "string" ? params.path : "";
+            const disposition = params?.disposition;
+            const rationale = typeof params?.rationale === "string" ? params.rationale : "";
+            if (!path || !disposition || !rationale.trim()) {
+                return receipt({
+                    ok: false,
+                    kind: "openspec-selection",
+                    error: "record_openspec_selection requires non-empty path, disposition (required|relevant), and rationale",
+                });
+            }
+            const result = await adoptContractFact("openspec-selection", {
+                kind: "openspec-selection",
+                origin: "contract",
+                path,
+                disposition,
+                rationale,
+            });
+            return receipt(result);
+        },
+    });
     const finalizeContractTool = defineTool({
         name: "finalize_contract",
         label: "finalize_contract",
@@ -1225,7 +1267,11 @@ export async function createFrontendContractTools(input) {
         },
     });
     return {
-        customTools: [...recordTools, finalizeContractTool],
+        customTools: [
+            ...recordTools,
+            recordOpenspecSelectionTool,
+            finalizeContractTool,
+        ],
         flush: async () => {
             const committed = readCommittedEvents(store, attemptId);
             await writeTypedEventStoreJsonl(path.join(input.runDir, input.nodeId, "contract-typed-facts.jsonl"), committed);

package/dist/executors/shell-executor.js

@@ -2429,7 +2429,9 @@ async function executeFrontendDesignPolicy(input, meta) {
             contract,
             allowedMockStrategies: config.allowedMockStrategies,
             sourceFreshness,
-            componentSpecCandidatePaths: config.componentSpecCandidatePaths ?? [],
+            componentSpecCandidatePaths: config.openspecCandidatePaths ??
+                config.componentSpecCandidatePaths ??
+                [],
             allowedDependencies: config.allowedDependencies,
             writeSetPatterns: config.implementationWriteSet ?? [],
         });

package/dist/task/frontend-project-capability.js

@@ -267,6 +267,14 @@ function emptyClassified() {
  * project-specific file names. Basename stems use word-boundary matching so
  * e.g. `*api*` (case-insensitive) maps to `rule.api` without hardcoding names.
  */
+/** True when any path segment (other than the file itself) carries a
+ * component/theme kind marker. Directory-organized libraries such as
+ * `ui/ucp-components-md/AdvancedSearch.md` rely on this; templates/ and
+ * rules/ are handled by their own branches before this fallback runs. */
+function segmentMatchesComponentKind(segments) {
+    const dirSegments = segments.slice(0, -1);
+    return dirSegments.some((segment) => /\bcomponents?\b/.test(segment.toLowerCase()));
+}
 function classifyOpenspecPaths(paths) {
     const classified = emptyClassified();
     const ruleStem = (basename) => {
@@ -305,8 +313,17 @@ function classifyOpenspecPaths(paths) {
                 classified.theme.push(candidate);
             else if (/\bcomponents?\b/.test(lower))
                 classified.component.push(candidate);
-            else
+            else if (segmentMatchesComponentKind(segments)) {
+                // Directory-organized component libraries (e.g.
+                // ui/ucp-components-md/AdvancedSearch.md) carry the kind in the
+                // parent directory name, not the file name. The parent-dir rule
+                // is a fallback so such layouts still land in the component
+                // bucket instead of being dropped into uiOther.
+                classified.component.push(candidate);
+            }
+            else {
                 classified.uiOther.push(candidate);
+            }
         }
         else {
             classified.advisoryOther.push(candidate);

package/dist/workflows/dag/frontend-design-policy.js

@@ -141,10 +141,22 @@ export function checkMockStrategy(contract, allowedMockStrategies) {
 }
 /** 4. Component choice must be precisely spec-referenced: `specified` requires
  * a specReference whose normalized path is a candidate and a non-empty section;
- * `new` must not carry a specReference; `reuse-existing` may omit it. */
+ * `new` must not carry a specReference; `reuse-existing` may omit it. The
+ * candidate set is the full generation-frozen openspec candidate list (the
+ * shell passes openspecCandidatePaths with componentSpecCandidatePaths as the
+ * fallback), so directory-organized component libraries are never rejected.
+ * A component specReference must still not point into clearly non-component
+ * spec areas — templates and the ai_workspace governance subtree cannot be the
+ * authoritative component definition. */
 export function checkComponentChoice(contract, componentSpecCandidatePaths) {
     const findings = [];
     const candidates = new Set(componentSpecCandidatePaths.map(normalizeRelativePath));
+    const isNonComponentSpecArea = (path) => {
+        const normalized = normalizeRelativePath(path);
+        return (normalized.startsWith("openspec/project-specs/templates/") ||
+            normalized.startsWith("ai_workspace/") ||
+            normalized === "openspec/project-specs/templates");
+    };
     (contract.uiComponentChoices ?? []).forEach((choice, index) => {
         if (choice.decision === "specified") {
             if (!choice.specReference) {
@@ -170,6 +182,13 @@ export function checkComponentChoice(contract, componentSpecCandidatePaths) {
                     path: choice.specReference.path,
                 });
             }
+            else if (isNonComponentSpecArea(normalized)) {
+                findings.push({
+                    code: "component-spec-reference-path-outside-candidates",
+                    message: `specified component choice #${index} specReference.path "${choice.specReference.path}" is a candidate but lives in a non-component spec area (templates or ai_workspace governance cannot be the authoritative component definition)`,
+                    path: choice.specReference.path,
+                });
+            }
         }
         else if (choice.decision === "new" && choice.specReference) {
             findings.push({

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

@@ -334,37 +334,124 @@ async function resolveRequiredOpenspecPaths(input) {
     // semantics instead of silently weakening an existing run.
     if (!input.selectionNodeId)
         return { ok: true, paths: input.candidatePaths };
+    // OpenSpec classifications arrive as individual typed `openspec-selection`
+    // facts (one path per record_openspec_selection call) so a large candidate
+    // set never exceeds a single model output budget. Only positive
+    // classifications (required | relevant) are legal facts; candidates that
+    // were never mentioned default to irrelevant. Explicit task declarations /
+    // source citations (`mandatoryPaths`) are never downgraded: they are
+    // always required and always must-read, whether or not the model declared
+    // them. Fall back to the legacy single fenced JSON for older runs (which
+    // may still carry explicit irrelevant rows).
+    let selections;
+    let allowIrrelevant = false;
+    const selectionNodeId = input.selectionNodeId; // guarded above: no selector -> full candidate semantics
+    try {
+        const facts = await readCommittedContractFacts(input.runDir, selectionNodeId);
+        selections = facts
+            .filter((fact) => fact.kind === "openspec-selection")
+            .map((fact) => ({
+            path: String(fact.path ?? ""),
+            disposition: String(fact.disposition ?? ""),
+            rationale: String(fact.rationale ?? ""),
+        }));
+    }
+    catch {
+        selections = [];
+    }
+    if (selections.length === 0) {
+        const legacy = await readLegacyOpenspecSelection({
+            runDir: input.runDir,
+            selectionNodeId,
+            candidatePaths: input.candidatePaths,
+            mandatoryPaths: input.mandatoryPaths,
+        });
+        if (!legacy.ok)
+            return legacy;
+        selections = legacy.selections;
+        allowIrrelevant = true;
+    }
+    try {
+        const byPath = new Map();
+        for (const row of selections) {
+            const legalDispositions = allowIrrelevant
+                ? ["required", "relevant", "irrelevant"]
+                : ["required", "relevant"];
+            if (typeof row.path !== "string" ||
+                !legalDispositions.includes(row.disposition) ||
+                typeof row.rationale !== "string" ||
+                !row.rationale.trim()) {
+                throw new Error(`invalid selection row (path+${legalDispositions.join("|")}+non-empty rationale expected): ${JSON.stringify(row)}`);
+            }
+            if (!input.candidatePaths.includes(row.path)) {
+                throw new Error(`invalid selection ${row.path}: not a candidate path`);
+            }
+            if (byPath.has(row.path))
+                throw new Error(`duplicate selection ${row.path}`);
+            byPath.set(row.path, row.disposition);
+        }
+        // Only explicitly required/relevant candidates must be read; everything
+        // unmentioned defaults to irrelevant. mandatoryPaths are intrinsic:
+        // they must be read even if the model omitted them, and they can never
+        // be downgraded by a declaration.
+        const mustRead = [
+            ...input.mandatoryPaths,
+            ...input.candidatePaths.filter((candidate) => byPath.get(candidate) === "required"),
+        ];
+        return { ok: true, paths: [...new Set(mustRead)].sort() };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function readCommittedContractFacts(runDir, nodeId) {
+    const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");
+    const records = await readTypedEventStoreFromJsonl(path.join(runDir, nodeId, "contract-typed-facts.jsonl"));
+    return records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => Boolean(fact));
+}
+async function readLegacyOpenspecSelection(input) {
     let text;
     try {
         text = await readNodeText(input.runDir, input.selectionNodeId);
     }
     catch (error) {
-        return { ok: false, reason: `openspec selector output unreadable: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            ok: false,
+            reason: `openspec selector output unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
     const fenced = /```json\s*\n([\s\S]*?)\n```/.exec(text);
-    if (!fenced)
-        return { ok: false, reason: "openspec selector must emit exactly one fenced JSON selection object" };
+    if (!fenced) {
+        return {
+            ok: false,
+            reason: "openspec selector emitted neither typed openspec-selection facts nor a legacy fenced JSON selection object",
+        };
+    }
     try {
         const parsed = JSON.parse(fenced[1] ?? "");
-        if (parsed.schemaVersion !== 1 || parsed.schemaId !== "frontend-openspec-selection-v1" || !Array.isArray(parsed.selections))
+        if (parsed.schemaVersion !== 1 ||
+            parsed.schemaId !== "frontend-openspec-selection-v1" ||
+            !Array.isArray(parsed.selections)) {
             throw new Error("schemaVersion/schemaId/selections invalid");
-        const byPath = new Map();
-        for (const row of parsed.selections) {
-            if (typeof row.path !== "string" || typeof row.disposition !== "string" || typeof row.rationale !== "string")
-                throw new Error("selection row invalid");
-            if (!input.candidatePaths.includes(row.path) || !["required", "relevant", "irrelevant"].includes(row.disposition))
-                throw new Error(`invalid selection ${row.path}`);
-            if (byPath.has(row.path))
-                throw new Error(`duplicate selection ${row.path}`);
-            byPath.set(row.path, row.disposition);
         }
-        const missing = input.candidatePaths.filter((candidate) => !byPath.has(candidate));
-        if (missing.length)
-            throw new Error(`missing classifications: ${missing.join(", ")}`);
-        return { ok: true, paths: [...new Set([...input.mandatoryPaths, ...input.candidatePaths.filter((candidate) => byPath.get(candidate) === "required")])].sort() };
+        const rows = parsed.selections.map((row) => ({
+            path: String(row.path ?? ""),
+            disposition: String(row.disposition ?? ""),
+            rationale: String(row.rationale ?? ""),
+        }));
+        return { ok: true, selections: rows };
     }
     catch (error) {
-        return { ok: false, reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}` };
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
 }
 async function finalizePrewrite(input, pending) {

package/dist/workflows/dag/frontend-typed-event-store.js

@@ -94,6 +94,7 @@ export const CONTRACT_FACT_KINDS = [
     "handoff-intent",
     "open-question",
     "split-proposal",
+    "openspec-selection",
     "contract-finalized",
 ];
 export const CONTRACT_TERMINAL_FACT_KINDS = ["contract-finalized"];

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

@@ -2929,7 +2929,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal, then call finalize_contract exactly once. Requirements use stable REQ/BR/AC identifiers with source spans and a disposition (explicit | repository-resolvable | assumption | blocking); each requirement registers evidence expectations across static/behavior/Mock/real-integration (required | optional | not-applicable), and UI-visible or interactive requirements register a non-blocking frontend-test handoff intent. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, also append the openspec classification and one final fenced frontend-openspec-selection-v1 JSON object. No file writes.",
+                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal / record_openspec_selection, then call finalize_contract exactly once. Requirements use stable REQ/BR/AC identifiers with source spans and a disposition (explicit | repository-resolvable | assumption | blocking); each requirement registers evidence expectations across static/behavior/Mock/real-integration (required | optional | not-applicable), and UI-visible or interactive requirements register a non-blocking frontend-test handoff intent. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, classify only the ones you actually use: call record_openspec_selection once per required/relevant path; never enumerate irrelevant candidates (unmentioned defaults to irrelevant) and never emit a fenced selection JSON. No file writes.",
                 subtask_prompt: [
                     "Read task source and produce a concise frontend implementation contract as typed requirement facts plus narrative Markdown.",
                     "Assign each requirement a stable REQ/BR/AC identifier and a source span (task-source section or repository file:line). Label each requirement's disposition as explicit | repository-resolvable | assumption | blocking; a blocking requirement must name its owner (human-decision or external-state) and evidence refs.",
@@ -2938,8 +2938,8 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "If the task is too large for one bounded writer, record a task split proposal instead of silently widening scope.",
                     "End the contract with a single disposition: ready, ready-with-assumptions (bounded assumptions that do not change product behavior), or blocked.",
                     ...(requiresOpenspecClassification ? [
-                        "Classify every generation-frozen OpenSpec candidate while contracting: required must be read and cited by the plan; relevant may inform planning but is not forced; irrelevant is out of scope. mandatoryPaths MUST be required and cannot be downgraded.",
-                        "After the Markdown contract, append exactly one fenced json object with schemaVersion 1, schemaId frontend-openspec-selection-v1, and selections [{path,disposition,rationale}]. No other JSON fences.",
+                        "Classify OpenSpec candidates incrementally while contracting — only the ones you actually use. Call record_openspec_selection once per path with disposition required (must be read and cited by the plan) or relevant (may inform planning). Never call it for irrelevant candidates and never list them: candidates you do not mention are treated as irrelevant by the runtime. Explicit task declarations / source citations are already required and must-read regardless; you never need to re-declare them.",
+                        "Mandatory paths are enforced by the runtime from the frozen task configuration — do not enumerate them, do not downgrade them.",
                         openspecSelectionContext,
                     ] : []),
                     "Read-only: do not modify code, docs, artifacts, or repository files.",

package/package.json

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