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

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [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
+
+### 新增
+
+- streamline implementation DAG (#61)
+- improve human-readable artifacts
+
+### 修复
+
+- relax traceability mapping
+
 ## [0.19.0] - 2026-07-23
 
 ### 重点更新
@@ -17,6 +35,7 @@
 
 ### 改进
 
+- `frontend-implementation` 保留独立 contract/scout，并把 Mock 策略与 implementation contract 合入 plan，把写前授权、验证/失败评估、复验和 review context 分别收敛为组合 shell 节点。standard/high-risk 固定 15 个顶层节点、small-risk 13 个；绿色路径执行 11 个节点、7 次 Pi，同时保留唯一 prewrite 写入授权、同 writeSet repair、真实 diff review 与 fail-closed closeout。
 - 优化操作与观测统一界面的导航与布局，合并确认与运行为「开始运行」，DAG 详情跳转路径更加准确
 
 ### 修复

package/dist/application/dag/generate-task-dag.js

@@ -105,6 +105,17 @@ function isVerificationShellTask(task) {
     const commands = resolveShellCommands(task.shell);
     return commands.some((command) => /(vitest|npm run (lint|typecheck|test)|check-repo\.sh|loop-agent-standard-verify)/.test(command));
 }
+function resolveReviewPacketShellCommands(task) {
+    const bundle = task.shell?.frontendVerificationBundle;
+    if (bundle) {
+        return [
+            ...bundle.mockCommands,
+            ...bundle.staticCommands,
+            ...bundle.behaviorCommands,
+        ];
+    }
+    return resolveShellCommands(task.shell);
+}
 async function buildReviewPacket(input) {
     const spec = parseDagSpec(JSON.parse(await readFile(input.dagPath, "utf-8")));
     const writers = collectWriterTasksForPacket(spec).map((task) => {
@@ -123,7 +134,7 @@ async function buildReviewPacket(input) {
         .filter(isVerificationShellTask)
         .map((task) => ({
         nodeId: task.id,
-        commands: resolveShellCommands(task.shell),
+        commands: resolveReviewPacketShellCommands(task),
     }));
     return {
         profileRouting: {

package/dist/executors/shell-executor.js

@@ -12,10 +12,12 @@ import { materializeFrontendTestResult, } from "../workflows/dag/frontend-test-r
 import { formatFrontendVerificationTraceStdout, runFrontendVerificationTraceGate, } from "../workflows/dag/frontend-verification-trace.js";
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
 import { formatFrontendFailureAssessStdout, formatFrontendRepairContractStdout, runFrontendFailureAssessGate, runFrontendRepairContractGate, } from "../workflows/dag/frontend-repair.js";
+import { formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
+import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from "../workflows/dag/frontend-review-context.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { materializeBackendTestResultFromRunDir, parseJunitXml } from "../workflows/dag/backend-test-result-contract.js";
-import { inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
 import { pathsChangedDuringRun, readGitStatusPorcelain, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
@@ -356,14 +358,16 @@ async function executeBackendTestPipeline(input, meta) {
             if (![0, 1].includes(pytestExitCode))
                 throw new Error(`pytest did not complete with a reportable exit code: ${pytestExitCode}`);
             const parsed = parseJunitXml(junitContent);
+            const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
             const htmlContent = renderBackendTestHtml({
                 title: meta.spec.title,
                 parsed,
+                cases,
                 environmentSummary: await readFile(path.join(reportsDir, "backend-test-environment.md"), "utf8"),
                 traceabilitySummary: await readFile(path.join(reportsDir, "backend-test-traceability.md"), "utf8"),
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
-            const facts = renderBackendTestFacts({ parsed, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent });
+            const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent });
             const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
             const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));
             outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `facts=${factsPath}`, facts);
@@ -601,8 +605,191 @@ async function executePipelineCommands(input, meta, overrideCommands) {
     }
     return results;
 }
+async function executeFrontendVerificationBundle(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const bundle = shell.frontendVerificationBundle;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    const results = [];
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const groups = [
+        { name: "mock", commands: bundle.mockCommands },
+        { name: "static", commands: bundle.staticCommands },
+        { name: "behavior", commands: bundle.behaviorCommands },
+    ];
+    for (const group of groups) {
+        for (const command of group.commands) {
+            const commandNumber = results.length + 1;
+            const result = await executeShellCommand({
+                command,
+                cwd,
+                timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+                envAllowlist: shell.envAllowlist,
+                dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+                outputArtifacts: {
+                    stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                    stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+                },
+            });
+            results.push(result);
+            if (!result.ok)
+                break;
+        }
+    }
+    if (beforeStatus !== undefined) {
+        const guard = await runShellWriteGuard({
+            rootCwd: input.cwd,
+            task: input.task,
+            beforeStatus,
+        });
+        if (!guard.ok) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `write guard failed: ${guard.violations.join(", ")}`,
+                failureCategory: "write-guard",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    await writeDagNodeTextArtifact(meta.runDir, input.task.id, "result.summary.md", buildShellResultSummaryMarkdown({
+        nodeId: input.task.id,
+        runId: meta.runId,
+        rootCwd: input.cwd,
+        results,
+    }));
+    const commandResults = results.map((result) => ({
+        ok: result.ok,
+        exitCode: result.exitCode,
+        failureCategory: result.failureCategory,
+        command: result.command,
+    }));
+    const firstFailure = results.find((result) => !result.ok);
+    let traceError;
+    try {
+        await runFrontendVerificationTraceGate({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            evidence: {
+                static: {
+                    nodeId: input.task.id,
+                    commandLabels: bundle.staticEvidence.commandLabels,
+                },
+                behavior: {
+                    nodeId: input.task.id,
+                    commandLabels: bundle.behaviorEvidence.commandLabels,
+                },
+            },
+        });
+    }
+    catch (error) {
+        traceError = error instanceof Error ? error : new Error(String(error));
+    }
+    if (bundle.mode === "repair") {
+        if (firstFailure || traceError) {
+            return {
+                ok: false,
+                stdout: summarizeCommandResults(results).stdout,
+                stderr: firstFailure?.stderr || traceError?.message || "frontend reverify failed",
+                failureCategory: firstFailure?.failureCategory ?? "invalid-output",
+                durationMs: Date.now() - started,
+                ...{ commandResults },
+            };
+        }
+        return {
+            ok: true,
+            stdout: "Frontend reverify bundle: pass",
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    const failureFacts = [];
+    if (firstFailure) {
+        failureFacts.push({
+            nodeId: input.task.id,
+            record: {
+                status: "FINISHED",
+                failureCategory: firstFailure.failureCategory,
+                stdout: summarizeCommandResults(results).stdout,
+                stderr: firstFailure.stderr,
+                commandResults,
+            },
+        });
+    }
+    if (traceError) {
+        failureFacts.push({
+            nodeId: "frontend-verification-trace-shell",
+            record: {
+                status: "FINISHED",
+                failureCategory: "invalid-output",
+                stderr: traceError.message,
+            },
+        });
+    }
+    try {
+        const assessment = await runFrontendFailureAssessGate({
+            runDir: meta.runDir,
+            failureFacts,
+        });
+        await runFrontendRepairContractGate({ runDir: meta.runDir });
+        return {
+            ok: true,
+            stdout: formatFrontendFailureAssessStdout(assessment),
+            stderr: "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+            ...{ commandResults },
+        };
+    }
+}
 export async function executeDagShellNode(input, meta) {
     const shell = input.task.shell;
+    if (shell?.frontendPrewriteGate) {
+        const started = Date.now();
+        try {
+            const result = await runFrontendPrewriteGate({
+                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 };
+        }
+        catch (error) {
+            return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error), failureCategory: "invalid-output", durationMs: Date.now() - started };
+        }
+    }
+    if (shell?.frontendVerificationBundle) {
+        return executeFrontendVerificationBundle(input, meta);
+    }
+    if (shell?.frontendReviewContext) {
+        const started = Date.now();
+        try {
+            const result = await runFrontendReviewContextGate({ runDir: meta.runDir, workspaceRoot: input.cwd });
+            return { ok: true, stdout: formatFrontendReviewContextStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
+        }
+        catch (error) {
+            return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error), failureCategory: "invalid-output", durationMs: Date.now() - started };
+        }
+    }
     if (shell?.backendTestPipeline) {
         return executeBackendTestPipelineWithWriteGuard(input, meta);
     }

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") {