@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.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

@@ -1,37 +1,39 @@
----
-name: agent-worker
-description: Use when work involves agent-worker, Feature Packet, TaskSpec, Task Pool, Feature or batch orchestration, controller pinning, versioned self-hosting (自举) release trains, candidate takeover canaries (候选接棒验证), or worker failure recovery; use loop-agent instead for a single DAG implementation or DAG runtime/kernel repair.
-references:
-  - path: references/agent-worker-operator.md
-    required: true
----
-
-# Agent Worker Operator
-
-当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
-
-## Route the Work
-
-- 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
-- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
-- 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
-
-## Boundaries
-
-- `agent-worker` 读取 Feature Packet 与 Task Pool facts，选择任务，冻结 controller identity，启动 Feature/batch lifecycle 命令，并收集 evidence。
-- `loop-agent` 仍是 DAG executor，负责 Pi-only implementation nodes、write-set governance、skill snapshots 与 run facts。
-- Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
-- 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
-- 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
-
-## Operator Flow
-
-1. 校验 Feature Packet 与 TaskSpecs，再从 Task Pool facts 选择 Ready 工作，而不是从 chat state。
-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，再重试或创建后续工作。
-
-## References
-
-- `references/agent-worker-operator.md`
+---
+name: agent-worker
+description: Use when work involves agent-worker, Feature Packet, TaskSpec, Task Pool, Feature or batch orchestration, controller pinning, versioned self-hosting (自举) release trains, candidate takeover canaries (候选接棒验证), or worker failure recovery; use loop-agent instead for a single DAG implementation or DAG runtime/kernel repair.
+references:
+  - path: references/agent-worker-operator.md
+    required: true
+---
+
+# Agent Worker Operator
+
+当工作起点是 Feature Packet、TaskSpec、Task Pool、Worker batch 或 versioned self-hosting release train 时使用本 skill。它负责在单次 loop-agent DAG run 之外选择并监督工作。
+
+## Route the Work
+
+- 用 `agent-worker` 做 Feature validation 与 lifecycle 决策、Ready-task 选择、batch 推进、controller identity freeze、candidate takeover canary，以及失败 Worker run 的恢复。
+- 对单个有界 DAG task、DAG diagnostics、node implementation，或 DAG runtime/kernel 修复，直接用 `loop-agent`。
+- 不要让 DAG leaf node 递归启动 `agent-worker`；Worker 是 outer loop，不是另一个 node executor。
+
+## Boundaries
+
+- `agent-worker` 读取 Feature Packet 与 Task Pool facts，选择任务，冻结 controller identity，启动 Feature/batch lifecycle 命令，并收集 evidence。
+- `loop-agent` 仍是 DAG executor，负责 Pi-only implementation nodes、write-set governance、skill snapshots 与 run facts。
+- Controller identity 冻结驱动 batch 的 published package；loop-agent skill snapshot 则单独冻结注入单次 DAG run 的 instructions。
+- 本 skill 不复制 command catalog。精确 flags 见 CLI help 与同级 `../loop-agent/references/command-reference.md`。
+- 不要把本 skill 加入默认 DAG role skills；仅对 outer-loop operator 工作显式路由。
+
+## Operator Flow
+
+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
+
+- `references/agent-worker-operator.md`