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

package/scripts/kb-query.mjs

@@ -1,554 +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();
+#!/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();