@tea-agent/loop-agent 0.20.0 → 0.20.1-beta.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### 新增
+
+- 前端规范读取将知识库与 `openspec/` 作为并列来源：无论知识库是否可用或命中，均继续递归枚举 `<repoRoot>/openspec/**` 并读取索引与任务相关规范正文。`discoverFrontendProjectCapability` 在没有 `package.json` 或 `package.json` 不可读时仍能发现 `openspec/**` 规范候选。
+- 前端预写门禁会校验 plan/design-review 的真实读取事件；生成期存在 `openspec` 规范候选但没有成功读取匹配文件时，在 writer 执行前阻断 DAG 并列出候选路径、检查节点和原因。
+- Dashboard 规范证据 API/UI 分别展示知识库查询、`openspec` 检索和 `openspec` 成功读取证据，三种类别独立展示。
+- 前端规范证据 API 新增 `openspecReads` 与 `openspecSearches` 字段，与通用 `specReads`/`specSearches` 并行。
+
 ## [0.20.0] - 2026-07-23
 
 ### 新增

package/dist/executors/shell-executor.js

@@ -769,6 +769,7 @@ export async function executeDagShellNode(input, meta) {
                 runDir: meta.runDir,
                 config: shell.frontendPrewriteGate,
                 sourceBinding: meta.spec.sourceBinding,
+                repoRoot: input.cwd,
             });
             return { ok: true, stdout: formatFrontendPrewriteGateStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
         }

package/dist/worker/observe/spec-evidence.js

@@ -47,6 +47,23 @@ function isSpecFilePath(filePath) {
 function isKnowledgeBaseTool(toolName) {
     return KB_CONNECTOR_TOOLS.has(toolName);
 }
+/** A repo-relative path references <repoRoot>/openspec/**. */
+function isOpenspecPath(filePath) {
+    const normalized = filePath.replaceAll(path.sep, "/");
+    return normalized === "openspec" || normalized.startsWith("openspec/");
+}
+/** A search query targets the openspec/ directory. */
+function isOpenspecSearch(query, searchPath) {
+    const lower = query.toLowerCase();
+    const normalizedPath = searchPath?.replaceAll(path.sep, "/").toLowerCase();
+    return (normalizedPath === "openspec" ||
+        normalizedPath?.startsWith("openspec/") === true ||
+        lower === "openspec" ||
+        lower === "openspec/" ||
+        lower.startsWith("openspec/") ||
+        lower.includes("openspec/**") ||
+        lower.includes("openspec/*"));
+}
 function resolveSessionEventsPath(repoRoot, dagRunId, nodeId) {
     if (!isSafeObservabilityIdentifier(dagRunId) || !isSafeObservabilityIdentifier(nodeId)) {
         return null;
@@ -278,6 +295,9 @@ export async function extractSpecEvidence(repoRoot, dagRunId, nodeId) {
             }
             // Search/scan tool calls (grep, find, ls, glob)
             if (["grep", "find", "ls", "glob"].includes(toolName)) {
+                const searchPath = typeof pairedInput.path === "string"
+                    ? pairedInput.path
+                    : undefined;
                 const query = typeof pairedInput.pattern === "string"
                     ? pairedInput.pattern
                     : typeof pairedInput.query === "string"
@@ -288,6 +308,7 @@ export async function extractSpecEvidence(repoRoot, dagRunId, nodeId) {
                 searches.push({
                     tool: toolName,
                     query,
+                    path: searchPath,
                     timestamp: ts,
                 });
                 if (toolCallId)
@@ -341,6 +362,16 @@ export async function extractSpecEvidence(repoRoot, dagRunId, nodeId) {
     if (status === "no-evidence") {
         summaryLines.push("未观察到任何规范证据：无 skill 注入、无文件读取、无检索操作。");
     }
+    // Separate openspec/** reads and searches for Dashboard display.
+    // Knowledge base and openspec are parallel sources.
+    const openspecReads = specReads.filter((r) => isOpenspecPath(r.path));
+    const openspecSearches = searches.filter((s) => isOpenspecSearch(s.query, s.path));
+    if (openspecReads.length > 0) {
+        summaryLines.push(`openspec 已读取 ${openspecReads.length} 个文件：${openspecReads.map((r) => r.path).join("、")}`);
+    }
+    if (openspecSearches.length > 0) {
+        summaryLines.push(`openspec 检索 ${openspecSearches.length} 次。`);
+    }
     return {
         dagRunId,
         nodeId,
@@ -352,6 +383,8 @@ export async function extractSpecEvidence(repoRoot, dagRunId, nodeId) {
         specReads,
         specSearches: searches,
         knowledgeBaseQueries: kbQueries,
+        openspecReads,
+        openspecSearches,
         summary: summaryLines.join(" "),
     };
 }

package/dist/worker/observe/static/views/dag-inspector.js

@@ -233,10 +233,15 @@ async function renderSpecEvidence(content, dagRunId, nodeId, cachedEvidence) {
 	}
 	content.appendChild(statusSection);
 
-	const appendListSection = (title, entries, renderEntry) => {
-		if (!entries?.length) return;
+	const appendListSection = (title, entries, renderEntry, emptyMessage = "") => {
+		if (!entries?.length && !emptyMessage) return;
 		const section = el("div", "spec-evidence-section");
 		section.appendChild(el("h4", null, title));
+		if (!entries?.length) {
+			section.appendChild(el("p", "spec-evidence-summary", emptyMessage));
+			content.appendChild(section);
+			return;
+		}
 		const list = el("ul", "spec-evidence-list");
 		for (const entry of entries) list.appendChild(renderEntry(entry));
 		section.appendChild(list);
@@ -273,9 +278,15 @@ async function renderSpecEvidence(content, dagRunId, nodeId, cachedEvidence) {
 		return item;
 	});
 	appendListSection("显式需求编号", evidence.sourceBinding?.requirementIds, (id) => el("li", null, id));
+	const openspecReadPaths = new Set(
+		(evidence.openspecReads ?? []).map((entry) => entry.path),
+	);
+	const otherSpecReads = (evidence.specReads ?? []).filter(
+		(entry) => !openspecReadPaths.has(entry.path),
+	);
 	appendListSection(
-		`已读取规范文件（${evidence.specReads?.length ?? 0}）`,
-		evidence.specReads,
+		`其他已读取规范文件（${otherSpecReads.length}）`,
+		otherSpecReads,
 		(read) => {
 			const item = el("li", null);
 			const button = document.createElement("button");
@@ -327,6 +338,58 @@ async function renderSpecEvidence(content, dagRunId, nodeId, cachedEvidence) {
 			item.append(icon, document.createTextNode(` ${query.connector}`));
 			return item;
 		},
+		"unavailable：未观察到知识库查询；connector 可能未配置或未调用。",
+	);
+
+	// openspec reads are displayed independently from skill/docs reads.
+	appendListSection(
+		`openspec 已读取（${evidence.openspecReads?.length ?? 0}）`,
+		evidence.openspecReads,
+		(read) => {
+			const item = el("li", null);
+			const button = document.createElement("button");
+			button.type = "button";
+			button.className = "spec-evidence-file-btn";
+			button.setAttribute("data-source", "read");
+			button.setAttribute("data-path", read.path);
+			if (read.timestamp) {
+				button.setAttribute("data-read-at", read.timestamp);
+			}
+			button.id = `spec-evidence-btn-read-${read.path}`;
+			const icon = el("i", "ri-book-open-line");
+			icon.setAttribute("aria-hidden", "true");
+			button.append(icon, el("code", null, read.path));
+			if (read.timestamp) {
+				button.appendChild(
+					el(
+						"span",
+						"spec-evidence-time",
+						formatSessionEventTime({ timestamp: read.timestamp }),
+					),
+				);
+			}
+			button.addEventListener("click", () =>
+				onSpecEvidenceFileClick(content, dagRunId, nodeId, "read", read.path, button),
+			);
+			item.appendChild(button);
+			return item;
+		},
+		evidence.openspecSearches?.length
+			? "已检索但未观察到 openspec 成功读取；若生成期存在候选，预写门禁会阻断 writer。"
+			: "unavailable：未观察到 openspec 成功读取。",
+	);
+
+	appendListSection(
+		`openspec 检索（${evidence.openspecSearches?.length ?? 0}）`,
+		evidence.openspecSearches,
+		(search) => {
+			const item = el("li", null);
+			const icon = el("i", "ri-search-line");
+			icon.setAttribute("aria-hidden", "true");
+			item.append(icon, document.createTextNode(` ${search.tool}: ${search.query}`));
+			return item;
+		},
+		"unavailable：未观察到 openspec 检索。",
 	);
 
 	if (evidence.status === "source-bound" || evidence.status === "spec-injected" || evidence.status === "no-evidence") {

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

@@ -30,6 +30,80 @@ function firstVerdictLine(text) {
     }
     return "";
 }
+function eventArgs(event) {
+    return event.args ?? event.toolInput ?? event.input ?? {};
+}
+function toRepoRelativePath(filePath, repoRoot) {
+    const resolved = path.resolve(repoRoot, filePath);
+    const relative = path.relative(repoRoot, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replaceAll(path.sep, "/");
+}
+function isFailedToolResult(event) {
+    return (event.isError === true ||
+        event.toolResult?.error != null ||
+        event.toolResult?.ok === false ||
+        event.result?.error != null ||
+        event.result?.ok === false);
+}
+async function checkOpenspecReadEvidence(input) {
+    const { runDir, candidatePaths, planNodeId, reviewNodeId, repoRoot } = input;
+    if (candidatePaths.length === 0)
+        return [];
+    const matched = new Set();
+    const normalizedCandidates = new Set(candidatePaths
+        .map((candidate) => toRepoRelativePath(candidate, repoRoot))
+        .filter((candidate) => Boolean(candidate?.startsWith("openspec/"))));
+    for (const nodeId of [planNodeId, reviewNodeId]) {
+        const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
+        try {
+            const raw = await readFile(eventsPath, "utf8");
+            const startedReads = new Map();
+            for (const line of raw.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(trimmed);
+                }
+                catch {
+                    continue;
+                }
+                if (event.type === "tool_execution_start" &&
+                    event.toolName === "read" &&
+                    event.toolCallId) {
+                    const readPath = eventArgs(event).path;
+                    if (typeof readPath === "string") {
+                        startedReads.set(event.toolCallId, readPath);
+                    }
+                }
+                else if (event.type === "tool_execution_end" &&
+                    event.toolName === "read" &&
+                    event.toolCallId !== undefined) {
+                    const readPath = startedReads.get(event.toolCallId);
+                    const relativePath = readPath
+                        ? toRepoRelativePath(readPath, repoRoot)
+                        : null;
+                    if (relativePath &&
+                        !isFailedToolResult(event) &&
+                        normalizedCandidates.has(relativePath)) {
+                        matched.add(relativePath);
+                    }
+                    startedReads.delete(event.toolCallId);
+                }
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+    }
+    return [...matched];
+}
 export async function runFrontendPrewriteGate(input) {
     const planNodeId = await selectNode(input.runDir, input.config.planFromNodeId, input.config.planFallbackFromNodeIds);
     const reviewNodeId = await selectNode(input.runDir, input.config.reviewFromNodeId, input.config.reviewFallbackFromNodeIds);
@@ -55,6 +129,18 @@ export async function runFrontendPrewriteGate(input) {
     if (!input.config.allowedMockStrategies.includes(contract.mockApi.strategy)) {
         throw new Error(`frontend prewrite gate blocked mock strategy ${contract.mockApi.strategy}; allowed=${input.config.allowedMockStrategies.join(",")}`);
     }
+    const candidatePaths = input.config.openspecCandidatePaths ?? [];
+    const openspecReadPaths = await checkOpenspecReadEvidence({
+        runDir: input.runDir,
+        candidatePaths,
+        planNodeId,
+        reviewNodeId,
+        repoRoot: input.repoRoot ?? process.cwd(),
+    });
+    if (candidatePaths.length > 0 && openspecReadPaths.length === 0) {
+        const checkedNodes = [planNodeId, reviewNodeId].join(", ");
+        throw new Error(`openspec gate blocked: ${candidatePaths.length} candidate(s) [${candidatePaths.join(", ")}] not read by ${checkedNodes}; writer not authorized.`);
+    }
     return {
         ok: true,
         planNodeId,
@@ -62,10 +148,12 @@ export async function runFrontendPrewriteGate(input) {
         verdict,
         mockStrategy: contract.mockApi.strategy,
         artifact,
+        openspecReadPaths,
+        openspecCandidatePaths: candidatePaths,
     };
 }
 export function formatFrontendPrewriteGateStdout(result) {
-    return [
+    const lines = [
         "Frontend prewrite gate: pass",
         `Plan: ${result.planNodeId}`,
         `Review: ${result.reviewNodeId}`,
@@ -73,5 +161,12 @@ export function formatFrontendPrewriteGateStdout(result) {
         `Structured artifact: ${result.artifact.path}`,
         `Schema: ${result.artifact.schemaId}`,
         `SHA-256: ${result.artifact.sha256}`,
-    ].join("\n");
+    ];
+    if (result.openspecReadPaths.length > 0) {
+        lines.push(`openspec read: ${result.openspecReadPaths.join(", ")}`);
+    }
+    else if (result.openspecCandidatePaths.length === 0) {
+        lines.push("openspec: unavailable");
+    }
+    return lines.join("\n");
 }

package/dist/workflows/dag/frontend-project-capability.js

@@ -105,6 +105,7 @@ export async function discoverFrontendProjectCapability(repoRoot) {
     const pkgPath = path.join(repoRoot, "package.json");
     const pkgRaw = await readJson(pkgPath);
     if (!pkgRaw || typeof pkgRaw !== "object") {
+        const openspec = await listOpenspec(repoRoot);
         const base = {
             schemaVersion: 1,
             framework: "unknown",
@@ -115,14 +116,17 @@ export async function discoverFrontendProjectCapability(repoRoot) {
             testRunner: [],
             mock: [],
             a11y: { status: "unknown", tools: [], evidencePaths: [] },
-            evidencePaths: [],
+            evidencePaths: openspec.slice(0, 5),
             reasons: ["package.json missing or unreadable"],
             designEvidence: {
-                normativePaths: [],
+                normativePaths: openspec,
                 advisoryPaths: [],
                 conflicts: [],
             },
         };
+        if (openspec.length) {
+            base.reasons.push(`openspec/ files discovered: ${openspec.slice(0, 5).join(", ")}`);
+        }
         return { ...base, adapterGuidance: buildAdapterGuidance(base) };
     }
     evidencePaths.push("package.json");

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

@@ -2041,6 +2041,7 @@ function buildFrontendHybridDagFromTask(sources) {
                                 : ["native", "browser-intercept", "request-adapter", "not-needed"],
                         artifactName: "frontend-implementation-contract.json",
                         outputDir: "contracts",
+                        openspecCandidatePaths: sources.frontendProjectCapability?.designEvidence.normativePaths ?? [],
                     },
                     cwd: ".",
                     timeoutMs: 60000,

package/dist/workflows/dag/types.js

@@ -126,6 +126,9 @@ export const dagFrontendPrewriteGateSchema = z.object({
     allowedMockStrategies: z.array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"])).min(1),
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
+    openspecCandidatePaths: z
+        .array(z.string().regex(/^openspec\/.+/, "openspec candidate must be repo-relative"))
+        .default([]),
 });
 export const dagFrontendVerificationBundleSchema = z.object({
     schemaVersion: z.literal(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.20.0",
+  "version": "0.20.1-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-design-review/SKILL.md

@@ -10,9 +10,11 @@ references:
 # Frontend Design Review
 
 For frontend design review nodes. Read the checklist; audit contract, scout, Mock
-strategy, effective plan, task bounds, and traceable design evidence. The knowledge-
-base connector is TODO: never invent results. If unavailable or unmatched, require
-`<repoRoot>/openspec/**` search/read evidence before repository conventions.
+strategy, effective plan, task bounds, and traceable design evidence.
+Knowledge base and `openspec/` are parallel specification sources. Query the
+knowledge-base connector when available; regardless of result, also search and
+read `<repoRoot>/openspec/**` before accepting repository conventions. The
+connector format is TODO: never invent results.
 
 ## Verdict Contract
 

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

@@ -9,8 +9,9 @@
 ## Project Fit
 
 - Reuse components, hooks, API helpers, mocks, schemas, router patterns, tokens, and theme rules.
-- Cite knowledge-base or `openspec/`; failed/empty knowledge queries must search `<repoRoot>/openspec/**`.
-- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths.
+- Cite knowledge base and `openspec/` as parallel sources; failed or empty
+  knowledge queries must still search `<repoRoot>/openspec/**`.
+- Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths for both.
 
 ## Interaction / Quality
 

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

@@ -2,14 +2,22 @@
 
 ## Required Source Sequence
 
-1. Attempt the configured component/design knowledge-base query first.
-2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openspec/` directory.
-3. Treat relevant matches 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 `openspec/` directly to neighboring-code conventions. Report source
-conflicts instead of combining them. Explicit task requirements remain the contract;
-flag conflicts with knowledge-base or `openspec/` rules.
+Knowledge base and `openspec/` 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 the project root's exact `openspec/`
+   directory for index files and task-relevant specification 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 `openspec/` directly to 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/` rules.
 
 ## Knowledge Base Connection — TODO
 

package/skills/frontend-review/SKILL.md

@@ -34,7 +34,13 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
   and no false real-integration claim. `not-needed` needs applicable real/no-remote
   evidence, or an explicit default-auto skipped-Mock rationale with the Real
   Integration Gap preserved when no project Mock capability is confirmed.
-- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openspec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
+- Component/design claims require traceable evidence from two parallel sources:
+  knowledge base and `<repoRoot>/openspec/**`. Query the knowledge-base connector
+  when available; regardless of result, also read `<repoRoot>/openspec/**`.
+  The connector format is TODO; never claim a query or fallback search without
+  evidence. Execute explicit `grep`/`find` to locate spec files and `read` to
+  load them before referencing their rules. Only successful `read` tool calls are
+  observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

package/skills/frontend-review/references/review-findings.md

@@ -11,7 +11,11 @@
 - Cite tight file locations, exact commands/results, or named DAG artifacts.
 - Never invent evidence; name the missing check. An implementation summary is not the actual diff.
 - Failed required static/behavior verification is at least Important unless proven unrelated.
-- A knowledge-base claim records connector/query, source ID/version, and retrieval time. If absent, failed, or unmatched, review evidence must show `<repoRoot>/openspec/**` search terms and matched paths/headings; label `openspec fallback`, `repository fallback`, or `unavailable` accurately.
+- Treat the knowledge base and `openspec/` as parallel sources. Record
+  connector/query, source ID/version, and retrieval time for knowledge-base
+  claims. Regardless of that result, evidence must show
+  `<repoRoot>/openspec/**` search terms and matched paths/headings; label
+  `openspec`, `repository fallback`, or `unavailable` accurately.
 
 ## Review Sequence
 

package/skills/frontend-verification/SKILL.md

@@ -24,9 +24,11 @@ verdict/findings, and required browser, visual, manual, or knowledge evidence.
 - Mock-backed behavior proves frontend rendering and state transitions only. It never
   proves backend readiness, transport compatibility, or real API integration.
 - Unavailable commands remain gaps.
-- Resolve design evidence via knowledge base, then `<repoRoot>/openspec/**` after
-  failure/no match. Its connector format remains TODO; never invent it. An applied
-  `openspec fallback` is available project evidence.
+- Resolve design evidence from two parallel sources: query the execution environment's
+  knowledge base connector when available; regardless of result, also read
+  `<repoRoot>/openspec/**` for index and task-relevant specification content.
+  The connector format remains TODO; never invent it. Applied `openspec` rules
+  from successful reads are available project evidence.
 - Separate Mock service/handler checks from page consumption and record the
   dev/test-only boundary; handler tests alone do not prove page use.
 

package/skills/frontend-verification/references/verification-checklist.md

@@ -12,8 +12,9 @@
 
 ## Design And Component Evidence
 
-- Claims cite knowledge-base retrieval or `<repoRoot>/openspec/**` fallback.
-- Evidence records query/source/time or fallback search terms, paths, headings, and applied rules.
+- Claims cite two parallel sources: knowledge-base retrieval and
+  `<repoRoot>/openspec/**`.
+- Evidence records query/source/time for knowledge base plus openspec search terms, paths, headings, and applied rules for both.
 - Relevant `openspec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
 
 ## Status