@tea-agent/loop-agent 0.12.0 → 0.13.0-alpha.0

package/scripts/kb-query.mjs

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+/**
+ * Phase A knowledge-base query (by_id / by_feature / search).
+ * Authority: Git files under knowledge/ and features/. Not RAG.
+ *
+ * Usage:
+ *   node scripts/kb-query.mjs --mode by_feature --feature F-2026-004 --json
+ *   node scripts/kb-query.mjs --mode by_id --id SVC-order --json
+ *   node scripts/kb-query.mjs --mode search --text 预占 --json
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+function usage(exitCode = 2) {
+	const text = `Usage: node scripts/kb-query.mjs --mode <by_id|by_feature|search> [options]
+
+Options:
+  --root <dir>           Repository root (default: cwd)
+  --mode <mode>          by_id | by_feature | search
+  --id <id>              Entity id (by_id)
+  --feature <F-id>       Feature id (by_feature)
+  --text <q>             Search text (search)
+  --glob <pattern>       Optional path substring filter for search (repeatable)
+  --include-staging      Also scan knowledge/bootstrap/staging/**
+  --json                 JSON response (default)
+  --markdown             Human markdown summary
+  -h, --help             Help
+`;
+	if (exitCode === 0) console.log(text);
+	else console.error(text);
+	process.exit(exitCode);
+}
+
+function parseArgs(argv) {
+	const out = {
+		root: process.cwd(),
+		mode: null,
+		id: null,
+		feature: null,
+		text: null,
+		globs: [],
+		includeStaging: false,
+		format: "json",
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const next = () => {
+			const v = argv[++i];
+			if (v === undefined) throw new Error(`missing value for ${a}`);
+			return v;
+		};
+		switch (a) {
+			case "--root":
+				out.root = path.resolve(next());
+				break;
+			case "--mode":
+				out.mode = next();
+				break;
+			case "--id":
+				out.id = next();
+				break;
+			case "--feature":
+				out.feature = next();
+				break;
+			case "--text":
+				out.text = next();
+				break;
+			case "--glob":
+				out.globs.push(next());
+				break;
+			case "--include-staging":
+				out.includeStaging = true;
+				break;
+			case "--json":
+				out.format = "json";
+				break;
+			case "--markdown":
+				out.format = "markdown";
+				break;
+			case "-h":
+			case "--help":
+				usage(0);
+				break;
+			default:
+				throw new Error(`unknown argument: ${a}`);
+		}
+	}
+	return out;
+}
+
+function exists(p) {
+	try {
+		fs.accessSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function readText(p) {
+	return fs.readFileSync(p, "utf8");
+}
+
+function walkFiles(dir, acc = []) {
+	if (!exists(dir)) return acc;
+	for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, ent.name);
+		if (ent.isDirectory()) walkFiles(p, acc);
+		else acc.push(p);
+	}
+	return acc;
+}
+
+function toPosix(root, abs) {
+	return path.relative(root, abs).split(path.sep).join("/");
+}
+
+function excerpt(text, max = 240) {
+	const one = text.replace(/\s+/g, " ").trim();
+	if (one.length <= max) return one;
+	return `${one.slice(0, max)}…`;
+}
+
+function parseYamlishEntitiesIndex(text) {
+	/** Minimal line parser for entities-index.yaml written by materialize / hand. */
+	const entities = [];
+	let cur = null;
+	for (const line of text.split(/\r?\n/)) {
+		const id = line.match(/^\s+id:\s*(.+)\s*$/);
+		const kind = line.match(/^\s+kind:\s*(.+)\s*$/);
+		const p = line.match(/^\s+path:\s*(.+)\s*$/);
+		const item = line.match(/^\s*-\s+kind:\s*(.+)\s*$/);
+		if (item) {
+			if (cur?.id) entities.push(cur);
+			cur = { kind: item[1].trim(), id: null, path: null };
+			continue;
+		}
+		if (!cur) continue;
+		if (kind) cur.kind = kind[1].trim();
+		if (id) cur.id = id[1].trim().replace(/^["']|["']$/g, "");
+		if (p) cur.path = p[1].trim().replace(/^["']|["']$/g, "");
+	}
+	if (cur?.id) entities.push(cur);
+	return entities.filter((e) => e.id && e.path);
+}
+
+function parseKnowledgeLinks(text) {
+	const edges = [];
+	// Very small subset: lines like "- type: feature_touches_service" then "  to: SVC-x" or "target: "
+	let pendingType = null;
+	for (const line of text.split(/\r?\n/)) {
+		const t = line.match(/^\s*-\s*type:\s*(\S+)/);
+		const to =
+			line.match(/^\s+(?:to|target|id):\s*(\S+)/) ||
+			line.match(/^\s+service_id:\s*(\S+)/);
+		if (t) pendingType = t[1];
+		if (to && pendingType) {
+			edges.push({ type: pendingType, to: to[1].replace(/[",']/g, "") });
+			pendingType = null;
+		}
+		// compact: - feature_touches_service: SVC-order
+		const compact = line.match(
+			/^\s*-\s*(feature_touches_\w+|touches_\w+|depends_on):\s*(\S+)/,
+		);
+		if (compact) edges.push({ type: compact[1], to: compact[2] });
+	}
+	return edges;
+}
+
+function loadEntitiesIndex(root) {
+	const p = path.join(root, "knowledge/graph/entities-index.yaml");
+	if (!exists(p)) return [];
+	return parseYamlishEntitiesIndex(readText(p));
+}
+
+function scanMetaEntities(root, includeStaging) {
+	const bases = [
+		"knowledge/domains",
+		"knowledge/services",
+		"knowledge/modules",
+	];
+	if (includeStaging) {
+		bases.push(
+			"knowledge/bootstrap/staging/domains",
+			"knowledge/bootstrap/staging/services",
+			"knowledge/bootstrap/staging/modules",
+		);
+	}
+	const entities = [];
+	for (const base of bases) {
+		for (const file of walkFiles(path.join(root, base))) {
+			if (!file.endsWith("meta.yaml") && !file.endsWith("meta.yml")) continue;
+			const text = readText(file);
+			const id = (text.match(/^id:\s*(\S+)/m) || [])[1];
+			const kind = (text.match(/^kind:\s*(\S+)/m) || [])[1] || "unknown";
+			if (!id) continue;
+			entities.push({
+				kind,
+				id: id.replace(/["']/g, ""),
+				path: toPosix(root, file),
+			});
+		}
+	}
+	return entities;
+}
+
+function mergeEntities(root, includeStaging) {
+	const map = new Map();
+	for (const e of [
+		...loadEntitiesIndex(root),
+		...scanMetaEntities(root, includeStaging),
+	]) {
+		map.set(`${e.kind}:${e.id}`, e);
+	}
+	// Features as entities
+	const featRoot = path.join(root, "features");
+	if (exists(featRoot)) {
+		for (const name of fs.readdirSync(featRoot)) {
+			if (!/^F-/.test(name)) continue;
+			const dir = path.join(featRoot, name);
+			if (!fs.statSync(dir).isDirectory()) continue;
+			map.set(`feature:${name}`, {
+				kind: "feature",
+				id: name,
+				path: `features/${name}/`,
+			});
+		}
+	}
+	return [...map.values()];
+}
+
+function resultFromEntity(root, entity, matchReason, score = 1.0) {
+	const abs = path.join(root, entity.path);
+	let title = entity.id;
+	let bodyExcerpt = "";
+	if (exists(abs) && fs.statSync(abs).isFile()) {
+		const text = readText(abs);
+		const t = text.match(/^title:\s*(.+)$/m) || text.match(/^#\s+(.+)$/m);
+		if (t) title = t[1].trim();
+		bodyExcerpt = excerpt(text);
+	} else if (exists(abs) && fs.statSync(abs).isDirectory()) {
+		const readme = path.join(abs, "requirement.md");
+		const overview = path.join(abs, "overview.md");
+		const pick = exists(readme) ? readme : exists(overview) ? overview : null;
+		if (pick) {
+			const text = readText(pick);
+			const t = text.match(/^#\s+(.+)$/m);
+			if (t) title = t[1].trim();
+			bodyExcerpt = excerpt(text);
+		}
+	}
+	return {
+		entity: { kind: entity.kind, id: entity.id },
+		path: entity.path,
+		title,
+		excerpt: bodyExcerpt,
+		score,
+		match_reason: matchReason,
+	};
+}
+
+function queryById(root, id, includeStaging) {
+	const entities = mergeEntities(root, includeStaging);
+	const hits = entities.filter((e) => e.id === id);
+	const results = hits.map((e) =>
+		resultFromEntity(root, e, hits.length === 1 ? "exact_id" : "id_match"),
+	);
+
+	// Also direct path conventions for testing cases
+	if (results.length === 0) {
+		const candidates = [
+			`features/${id}/`,
+			`knowledge/services/${id}/meta.yaml`,
+			`knowledge/domains/${id}/meta.yaml`,
+			`knowledge/modules/${id}/meta.yaml`,
+		];
+		for (const rel of candidates) {
+			const abs = path.join(root, rel);
+			if (exists(abs)) {
+				results.push(
+					resultFromEntity(
+						root,
+						{
+							kind: rel.startsWith("features/") ? "feature" : "unknown",
+							id,
+							path: rel,
+						},
+						"path_convention",
+					),
+				);
+			}
+		}
+	}
+
+	return {
+		schema_version: 1,
+		ok: results.length > 0,
+		mode: "by_id",
+		results,
+		edges_trace: [],
+		diagnostics: {
+			levels_used: ["Q1"],
+			truncated: false,
+			entity_count_scanned: entities.length,
+		},
+		error:
+			results.length === 0
+				? `no entity with id=${id}; run materialize or check knowledge/graph/entities-index.yaml`
+				: undefined,
+	};
+}
+
+function queryByFeature(root, featureId, includeStaging) {
+	const featureDir = path.join(root, "features", featureId);
+	if (!exists(featureDir)) {
+		return {
+			schema_version: 1,
+			ok: false,
+			mode: "by_feature",
+			results: [],
+			edges_trace: [],
+			diagnostics: { levels_used: ["Q0"], truncated: false },
+			error: `missing features/${featureId}/`,
+		};
+	}
+
+	const results = [];
+	const edgesTrace = [];
+	results.push(
+		resultFromEntity(
+			root,
+			{ kind: "feature", id: featureId, path: `features/${featureId}/` },
+			"feature_root",
+		),
+	);
+
+	const interesting = [
+		"requirement.md",
+		"acceptance.yaml",
+		"knowledge-links.yaml",
+		"testing/acceptance-verdict.yaml",
+		"testing/coverage-matrix.yaml",
+		"testing/automation-map.yaml",
+		"testing/defects/registry.yaml",
+		"testing/cases/index.yaml",
+		"testing/cases/backend/index.yaml",
+		"testing/runs/latest.md",
+	];
+	for (const rel of interesting) {
+		const abs = path.join(featureDir, rel);
+		if (!exists(abs)) continue;
+		const posix = `features/${featureId}/${rel}`;
+		const text = readText(abs);
+		results.push({
+			entity: {
+				kind: rel.includes("testing") ? "testing-asset" : "feature-doc",
+				id: `${featureId}:${rel}`,
+			},
+			path: posix,
+			title: rel,
+			excerpt: excerpt(text),
+			score: 1.0,
+			match_reason: "feature_pack",
+		});
+	}
+
+	const linksPath = path.join(featureDir, "knowledge-links.yaml");
+	const entities = mergeEntities(root, includeStaging);
+	if (exists(linksPath)) {
+		const edges = parseKnowledgeLinks(readText(linksPath));
+		for (const edge of edges) {
+			edgesTrace.push(`${edge.type}->${edge.to}`);
+			const hit = entities.find((e) => e.id === edge.to);
+			if (hit) {
+				results.push(
+					resultFromEntity(root, hit, `edge:${edge.type}`),
+				);
+			} else {
+				results.push({
+					entity: { kind: "unknown", id: edge.to },
+					path: `features/${featureId}/knowledge-links.yaml`,
+					title: edge.to,
+					excerpt: `linked via ${edge.type}; entity body not in index`,
+					score: 1.0,
+					match_reason: `edge:${edge.type}:unresolved`,
+				});
+			}
+		}
+	}
+
+	// edges.yaml mentions
+	const edgesFile = path.join(root, "knowledge/graph/edges.yaml");
+	if (exists(edgesFile)) {
+		const text = readText(edgesFile);
+		if (text.includes(featureId)) {
+			results.push({
+				entity: { kind: "graph-edges", id: "edges.yaml" },
+				path: "knowledge/graph/edges.yaml",
+				title: "graph edges",
+				excerpt: excerpt(
+					text
+						.split(/\r?\n/)
+						.filter((l) => l.includes(featureId))
+						.join("\n") || text,
+				),
+				score: 1.0,
+				match_reason: "graph_edges_mention",
+			});
+		}
+	}
+
+	return {
+		schema_version: 1,
+		ok: true,
+		mode: "by_feature",
+		results,
+		edges_trace: edgesTrace,
+		diagnostics: {
+			levels_used: ["Q0", "Q1", "Q2"],
+			truncated: false,
+		},
+	};
+}
+
+function matchesGlobFilters(rel, globs) {
+	if (!globs.length) return true;
+	return globs.some((g) => {
+		const simple = g.replace(/\*\*/g, "").replace(/\*/g, "");
+		if (simple && rel.includes(simple)) return true;
+		try {
+			return globToLoose(g).test(rel);
+		} catch {
+			return false;
+		}
+	});
+}
+
+function querySearch(root, text, globs, includeStaging) {
+	const q = text.toLowerCase();
+	const roots = ["knowledge", "features"];
+	if (includeStaging) roots.push("knowledge/bootstrap/staging");
+	const results = [];
+	for (const base of roots) {
+		for (const file of walkFiles(path.join(root, base))) {
+			const rel = toPosix(root, file);
+			if (!matchesGlobFilters(rel, globs)) continue;
+			let body;
+			try {
+				body = readText(file);
+			} catch {
+				continue;
+			}
+			if (!body.toLowerCase().includes(q)) continue;
+			const idx = body.toLowerCase().indexOf(q);
+			const slice = body.slice(Math.max(0, idx - 40), idx + q.length + 80);
+			results.push({
+				entity: { kind: "file", id: rel },
+				path: rel,
+				title: path.basename(file),
+				excerpt: excerpt(slice, 200),
+				score: 0.5,
+				match_reason: "search_text",
+			});
+			if (results.length >= 20) break;
+		}
+		if (results.length >= 20) break;
+	}
+	return {
+		schema_version: 1,
+		ok: results.length > 0,
+		mode: "search",
+		results,
+		edges_trace: [],
+		diagnostics: {
+			levels_used: ["Q3"],
+			truncated: results.length >= 20,
+		},
+		error:
+			results.length === 0
+				? `no matches for ${JSON.stringify(text)}`
+				: undefined,
+	};
+}
+
+function globToLoose(g) {
+	// minimal: treat * as .*
+	const esc = g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
+	return new RegExp(esc);
+}
+
+function toMarkdown(resp) {
+	const lines = [
+		`# kb-query ${resp.mode}`,
+		`ok: ${resp.ok}`,
+		resp.error ? `error: ${resp.error}` : null,
+		"",
+		"## results",
+	].filter(Boolean);
+	for (const r of resp.results || []) {
+		lines.push(
+			`- **${r.entity?.id ?? "?"}** (${r.entity?.kind ?? "?"}) \`${r.path}\` — ${r.match_reason}`,
+		);
+		if (r.excerpt) lines.push(`  - ${r.excerpt}`);
+	}
+	if (resp.edges_trace?.length) {
+		lines.push("", "## edges_trace", ...resp.edges_trace.map((e) => `- ${e}`));
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+function main() {
+	let args;
+	try {
+		args = parseArgs(process.argv.slice(2));
+	} catch (e) {
+		console.error(String(e?.message || e));
+		usage(2);
+	}
+	if (!args.mode) {
+		console.error("--mode is required");
+		usage(2);
+	}
+
+	let resp;
+	if (args.mode === "by_id") {
+		if (!args.id) {
+			console.error("by_id requires --id");
+			process.exit(2);
+		}
+		resp = queryById(args.root, args.id, args.includeStaging);
+	} else if (args.mode === "by_feature") {
+		if (!args.feature) {
+			console.error("by_feature requires --feature");
+			process.exit(2);
+		}
+		resp = queryByFeature(args.root, args.feature, args.includeStaging);
+	} else if (args.mode === "search") {
+		if (!args.text) {
+			console.error("search requires --text");
+			process.exit(2);
+		}
+		resp = querySearch(args.root, args.text, args.globs, args.includeStaging);
+	} else {
+		console.error(`unsupported mode: ${args.mode}`);
+		process.exit(2);
+	}
+
+	if (args.format === "markdown") process.stdout.write(toMarkdown(resp));
+	else process.stdout.write(`${JSON.stringify(resp, null, 2)}\n`);
+	process.exit(resp.ok ? 0 : 1);
+}
+
+main();

package/scripts/kb-query.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Phase A knowledge query wrapper (by_id / by_feature / search).
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "${ROOT_DIR}/scripts/kb-query.mjs" "$@"

package/skills/agent-worker/SKILL.md

@@ -26,11 +26,13 @@ references:
 
 ## Operator Flow
 
-1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。
+1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。Task Pool 身份是 `{ featureId, taskId }`，不是裸 taskId。
 2. 在写入前解析并冻结目标 published controller；在 batch、task 与 run evidence 中保留 controller identity。
 3. 将仓库写入委托给受治理的 loop-agent DAG nodes，并审查其 task boundaries 与 write sets。
 4. 自举时保持 published version N 固定，由它维护 candidate N+1，再通过 deterministic isolated canary 证明 candidate takeover。
 5. 失败时先保留原始 run record、evidence 与 failure handoff，再重试或创建后续工作。
+6. Failed task 重试使用 `agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>`；跨 Feature 同名时禁止省略 `--feature-id`。
+7. 升级或发现 legacy state 时先 `pool doctor`，再用 `pool migrate-state`（默认 dry-run；apply 需 `--owner` + `--reason`）。Observe 保持只读。
 
 ## References
 

package/skills/agent-worker/references/agent-worker-operator.md

@@ -19,10 +19,27 @@ Leaf DAG nodes 不得递归启动 `agent-worker`。Worker 负责 DAG 之外的 s
 ## Feature and Task Pool Flow
 
 1. 阅读 Feature Packet，校验其 TaskSpecs 与 dependency graph。
-2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。
+2. 从持久化的 Task Pool state 推导下一步动作；不要从 chat history 重建 lifecycle state。canonical state 键是 `{ featureId, taskId }`（路径 `.harness/task-pool/states/<featureId>/<taskId>.json`）。
 3. 对可写 batch 只冻结一次 controller，并将其 identity 传播到下游 evidence。
 4. 将每个选中的 TaskSpec 委托给 loop-agent，使用其结构化的 allowed / forbidden paths。
 5. 根据 canonical run facts 刷新 Feature review、reports 与 Task Pool state。
+6. 重试 Failed task：
+
+   ```text
+   agent-worker task retry <task-id> --feature-id <feature-id> --repo <repo> --reason <reason>
+   ```
+
+   跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。
+7. 诊断 / 迁移 legacy 扁平 state：
+
+   ```text
+   agent-worker pool doctor --repo <repo> --json
+   agent-worker pool migrate-state --repo <repo>                 # dry-run
+   agent-worker pool migrate-state --repo <repo> --apply --owner <owner> --reason <reason>
+   ```
+
+   doctor 只读；migrate 默认零写入，apply 失败全回滚且不改 JSONL。
+8. Observe（`observe serve|snapshot`）只读；canonical Task 路由为 `/api/features/:featureId/tasks/:taskId` 与 `#/feature/:featureId/task/:taskId`。
 
 ## Versioned Self-Hosting
 

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

@@ -8,39 +8,42 @@ references:
 
 # Frontend Design Review
 
-Use for `frontend-design-gate-pi`. Read the required checklist first. Review the
-contract, scout report, plan, task source/constraints, `task.json` boundaries, and
-traceable component/design evidence. The connector format is TODO; never fabricate
-a result. When knowledge-base access is absent, failed, or unmatched, require evidence
-that `<repoRoot>/openSpec/**` was searched before accepting other repo conventions.
+For first/final design review nodes. Read the checklist, then audit contract, scout,
+plan/revision, task constraints/bounds, and traceable design evidence. The knowledge-
+base connector is TODO: never invent results. If absent/failed/unmatched, require
+`<repoRoot>/openSpec/**` search/read evidence before repo conventions.
 
 ## Verdict Contract
 
-The first non-empty line must be exactly:
+First non-empty line: exactly `VERDICT: pass` or `VERDICT: request-revision`.
+Any blocker requires request-revision; the shell gate reads this line exactly.
 
-- `VERDICT: pass`
-- `VERDICT: request-revision`
-
-Use request-revision for any blocker. The shell gate reads this line exactly.
+For `frontend-final-design-review-pi`: recheck the original plan when output is
+`PASS_NO_REVISION_NEEDED`; otherwise verify every Required Plan Correction. Reject
+remaining, incomplete, or newly introduced gaps.
 
 ## Blocking Conditions
 
-- An acceptance criterion lacks implementation or verification coverage.
-- Applicable UI states are missing without a reason.
-- A dependency is not explicitly permitted.
-- Confirmed project primitives/rules are ignored, or a claim has neither knowledge-base nor required `openSpec/` fallback evidence.
-- Planned paths exceed allowed/write scope or touch forbidden/generated paths.
-- Required static or behavior commands are missing or non-deterministic.
-- Interaction, responsive, accessibility, data, or failure behavior is ambiguous enough to require guessing.
+- Any criterion lacks implementation/verification; UI states lack reasons; a
+  dependency lacks permission; confirmed primitives/rules are ignored; design claims
+  lack knowledge-base or required `openSpec/` evidence; paths cross write bounds;
+  commands are missing/non-deterministic; or interaction, responsive, accessibility,
+  data, or failure behavior requires guessing.
 
-Knowledge-base unavailability alone is advisory when relevant `openSpec/` rules were
-searched and applied. Block when that fallback was skipped, sources conflict without
-resolution, or no source resolves a required user-visible decision.
+Knowledge-base absence is advisory if relevant `openSpec/` rules were searched/read
+and applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
 
 ## Method And Output
 
-Map each criterion to steps, files, states, and checks; audit paths; verify evidence;
-then classify findings as Blocking or Advisory. Do not edit files.
+Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking or
+Advisory, and never edit files.
+
+### Spec Evidence Rules
+
+Run `grep`/`find`, then explicit `read` calls for applicable specs and checklist.
+Only successful paired reads count as “已读取规范文件”; summaries do not. List each
+read path/section in `Checked Items`. If the connector is unavailable, search/read
+`openSpec/` before accepting repository conventions.
 
 ```markdown
 VERDICT: pass
@@ -55,5 +58,4 @@ VERDICT: pass
 - ...
 ```
 
-For revisions, every correction names the criterion/section, missing evidence or
-decision, and exact plan change required.
+Each correction names its criterion/section, gap, and exact plan change.