ultimate-pi 0.18.0 → 0.19.0

package/.pi/scripts/generate-agents-policy-yaml.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Generate .pi/harness/agents.policy.yaml from harness agent .md frontmatter + submit registry.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { walkAgentsDir } from "../lib/harness-agent-discovery.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const AGENTS_DIR = join(ROOT, ".pi", "agents");
+const OUT = join(ROOT, ".pi", "harness", "agents.policy.yaml");
+
+const SUBMIT_BY_AGENT = {
+	"harness/planning/planning-context": ["submit_planning_context"],
+	"harness/planning/decompose": ["submit_decomposition_brief", "submit_human_required"],
+	"harness/planning/hypothesis": ["submit_hypothesis_brief"],
+	"harness/planning/hypothesis-validator": ["submit_hypothesis_validation"],
+	"harness/planning/plan-evaluator": ["submit_validation_turn"],
+	"harness/planning/plan-adversary": ["submit_adversary_brief"],
+	"harness/planning/sprint-contract-auditor": ["submit_sprint_audit"],
+	"harness/planning/review-integrator": ["submit_review_round_draft"],
+	"harness/planning/implementation-researcher": ["submit_implementation_research"],
+	"harness/planning/stack-researcher": ["submit_stack_brief"],
+	"harness/planning/execution-plan-author": ["submit_execution_plan_brief"],
+	"harness/running/executor": ["submit_executor_handoff"],
+	"harness/reviewing/evaluator": ["submit_eval_verdict"],
+	"harness/reviewing/adversary": ["submit_adversary_report"],
+	"harness/reviewing/tie-breaker": ["submit_human_required"],
+	"harness/trace-librarian": ["submit_human_required"],
+	"harness/incident-recorder": ["submit_human_required"],
+	"harness/sentrux-steward": ["submit_sentrux_manifest_proposal"],
+};
+
+function parseFrontmatter(content) {
+	const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!m) return {};
+	return parseYaml(m[1]) ?? {};
+}
+
+function kindFor(id) {
+	if (id.startsWith("harness/planning/")) return "planner";
+	if (id === "harness/running/executor") return "executor";
+	if (id === "harness/reviewing/evaluator") return "evaluator";
+	if (id === "harness/reviewing/adversary") return "adversary";
+	if (id === "harness/reviewing/tie-breaker") return "tie_breaker";
+	if (id === "harness/trace-librarian") return "trace";
+	if (id === "harness/incident-recorder") return "incident";
+	if (id === "harness/sentrux-steward" || id === "harness/sentrux-bootstrap")
+		return "planner";
+	return "other";
+}
+
+const KIND_BASE = {
+	planner: ["read", "grep", "find", "ls"],
+	executor: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+	evaluator: ["read", "grep", "find", "ls"],
+	adversary: ["read", "grep", "find", "ls"],
+	tie_breaker: ["read", "grep", "find", "ls"],
+	trace: ["read", "grep", "find", "ls"],
+	incident: ["read", "grep", "find", "ls"],
+	other: ["read", "grep", "find", "ls"],
+};
+
+function csvTools(fm) {
+	const raw = fm.tools;
+	if (!raw) return [];
+	return String(raw)
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+}
+
+async function main() {
+	const files = new Map();
+	walkAgentsDir(AGENTS_DIR, "package", files);
+
+	const kinds = {
+		planner: { tools: KIND_BASE.planner, extensions: false, read_only: true },
+		executor: { tools: KIND_BASE.executor, extensions: true, read_only: false },
+		evaluator: { tools: KIND_BASE.evaluator, extensions: false, read_only: true },
+		adversary: { tools: KIND_BASE.adversary, extensions: false, read_only: true },
+		tie_breaker: {
+			tools: KIND_BASE.tie_breaker,
+			extensions: false,
+			read_only: true,
+		},
+		trace: { tools: KIND_BASE.trace, extensions: false, read_only: true },
+		incident: { tools: KIND_BASE.incident, extensions: false, read_only: true },
+		other: { tools: KIND_BASE.other, extensions: false, read_only: true },
+	};
+
+	const agents = {};
+
+	for (const [id, file] of files) {
+		if (!id.startsWith("harness/")) continue;
+		const fm = parseFrontmatter(file.content);
+		const kind = kindFor(id);
+		const base = new Set(KIND_BASE[kind] ?? KIND_BASE.other);
+		const fromFm = csvTools(fm);
+		const submit = SUBMIT_BY_AGENT[id] ?? [];
+		const toolsAdd = [...new Set([...fromFm, ...submit])].filter(
+			(t) => !base.has(t),
+		);
+		const entry = { kind };
+		if (toolsAdd.length > 0) entry.tools_add = toolsAdd;
+		if (fm.extensions === false) entry.extensions = false;
+		if (fm.extensions === true) entry.extensions = true;
+		if (typeof fm.max_turns === "number") entry.max_turns = fm.max_turns;
+		if (typeof fm.thinking === "string") entry.thinking = fm.thinking;
+		if (submit.length === 1) entry.submit_tool = submit[0];
+		agents[id] = entry;
+	}
+
+	// plan-synthesizer: parent-only, minimal policy for spawn if ever used
+	agents["harness/planning/plan-synthesizer"] = {
+		kind: "planner",
+		tools_add: [
+			"submit_decomposition_brief",
+			"submit_hypothesis_brief",
+			"submit_execution_plan_brief",
+		],
+		extensions: false,
+	};
+
+	const doc = {
+		apiVersion: "harness.toolkit/v1",
+		kinds,
+		agents,
+	};
+
+	const yaml = [
+		"# Generated/maintained SSOT for harness agent tools (see ADR 0049).",
+		"# Regenerate hints: node .pi/scripts/generate-agents-policy-yaml.mjs",
+		"",
+	];
+	const { stringify } = await import("yaml");
+	yaml.push(stringify(doc));
+	await writeFile(OUT, yaml.join("\n"), "utf8");
+	console.log(`Wrote ${OUT} (${Object.keys(agents).length} harness agents)`);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/graphify-kb-updater.mjs

@@ -20,6 +20,7 @@ const DEFAULT_RAW_DIR = "raw/graphify-kb-updates";
 const DEFAULT_DATA_DIR = "data";
 const DEFAULT_GRAPH_DIR = "graphify-out";
 const REQUIRED_RIGHTS = ["license", "access", "approved_by", "approved_at"];
+const REQUIRED_PROVENANCE = ["origin", "locator"];
 const RISKY_KINDS = new Set(["book", "transcript", "youtube"]);
 
 function parseArgs(argv) {
@@ -92,6 +93,8 @@ function loadConfig(args) {
 		allowlist: (cfg.allowlist ?? []).map((entry) => typeof entry === "string" ? { domain: entry, approved: true } : entry),
 		reviewQueue: cfg.review_queue ?? [],
 		articleQueries: cfg.article_queries ?? [],
+		repoSources: cfg.repo_sources ?? [],
+		releaseFeeds: cfg.release_feeds ?? [],
 		paperFeeds: cfg.paper_feeds ?? [],
 		localBooks: cfg.local_books ?? [{ path: "data/books" }],
 		localTranscripts: cfg.local_transcripts ?? [{ path: "data/youtube-transcripts" }],
@@ -130,6 +133,11 @@ function hasRightsApproval(candidate) {
 	return Boolean(r && REQUIRED_RIGHTS.every((k) => typeof r[k] === "string" && r[k].trim()));
 }
 
+function hasCompleteProvenance(candidate) {
+	const p = candidate.provenance;
+	return Boolean(p && REQUIRED_PROVENANCE.every((k) => typeof p[k] === "string" && p[k].trim()));
+}
+
 function urlDomain(url) {
 	try { return new URL(url).hostname.replace(/^www\./, ""); } catch { return ""; }
 }
@@ -138,6 +146,14 @@ function allowlistEntry(cfg, domain) {
 	return cfg.allowlist.find((entry) => entry.domain === domain || domain.endsWith(`.${entry.domain}`));
 }
 
+function allowlistEntryAllows(entry, kind) {
+	return Boolean(entry?.approved === true && (!Array.isArray(entry.allowed_source_classes) || entry.allowed_source_classes.includes(kind)));
+}
+
+function allowlistAllows(candidate) {
+	return Boolean(candidate.allowlist_state.allowed && candidate.allowlist_state.approved && (!Array.isArray(candidate.allowlist_state.allowed_source_classes) || candidate.allowlist_state.allowed_source_classes.includes(candidate.kind)));
+}
+
 function competitorLabels(cfg, candidate) {
 	const haystack = `${candidate.title ?? ""} ${candidate.url ?? ""} ${candidate.path ?? ""}`.toLowerCase();
 	const labels = [];
@@ -163,7 +179,7 @@ function normalizeCandidate(cfg, raw) {
 		risk_class: raw.risk_class ?? taxonomy.risk_class ?? (RISKY_KINDS.has(raw.kind) ? "high" : "medium"),
 		provenance: raw.provenance ?? { origin: raw.source_type, discovered_by: "graphify-kb-updater", locator: raw.url ?? raw.path ?? raw.query ?? null },
 		rights_access: raw.rights_access ?? null,
-		allowlist_state: allow ? { allowed: true, domain: allow.domain, approved: allow.approved === true, approved_by: allow.approved_by ?? null, approved_at: allow.approved_at ?? null } : { allowed: false },
+		allowlist_state: allow ? { allowed: true, domain: allow.domain, approved: allow.approved === true, approved_by: allow.approved_by ?? null, approved_at: allow.approved_at ?? null, allowed_source_classes: allow.allowed_source_classes ?? null } : { allowed: false },
 		approval_state: raw.approved === true ? "approved" : "not_approved",
 	};
 	candidate.competitor_labels = raw.competitor_labels ?? competitorLabels(cfg, candidate);
@@ -175,12 +191,27 @@ function normalizeCandidate(cfg, raw) {
 function discoverCandidates(cfg, args) {
 	const candidates = [];
 	for (const query of cfg.articleQueries) candidates.push({ kind: "article", source_type: "web_search_query", title: query, query, review_required: true, promotion_policy: "stage_only" });
+	for (const repo of cfg.repoSources) {
+		const kind = "repo";
+		const domain = urlDomain(repo.url);
+		const allow = allowlistEntry(cfg, domain);
+		const explicit = cfg.autoPromoteAllowlist && allowlistEntryAllows(allow, kind) && repo.approved === true;
+		candidates.push({ ...repo, kind, source_type: "repo_metadata", domain, review_required: !explicit, promotion_policy: explicit ? "allowlist_auto_promote" : "manual_review", rights_access: repo.rights_access ?? null, provenance: repo.provenance });
+	}
+	for (const release of cfg.releaseFeeds) {
+		const kind = "release";
+		const domain = urlDomain(release.url);
+		const allow = allowlistEntry(cfg, domain);
+		const explicit = cfg.autoPromoteAllowlist && allowlistEntryAllows(allow, kind) && release.approved === true;
+		candidates.push({ ...release, kind, source_type: "release_metadata", domain, review_required: !explicit, promotion_policy: explicit ? "allowlist_auto_promote" : "manual_review", rights_access: release.rights_access ?? null, provenance: release.provenance });
+	}
 	for (const feed of cfg.paperFeeds) candidates.push({ kind: "paper", source_type: "feed", title: feed.title ?? feed.url, url: feed.url, rights_access: feed.rights_access ?? null, review_required: true, promotion_policy: "stage_only", provenance: feed.provenance });
 	for (const entry of cfg.reviewQueue) {
+		const kind = entry.kind ?? "article";
 		const domain = urlDomain(entry.url);
 		const allow = allowlistEntry(cfg, domain);
-		const explicit = cfg.autoPromoteAllowlist && allow?.approved === true && entry.approved === true;
-		candidates.push({ ...entry, kind: entry.kind ?? "article", source_type: "review_queue", domain, review_required: !explicit, promotion_policy: explicit ? "allowlist_auto_promote" : "manual_review", rights_access: entry.rights_access ?? null });
+		const explicit = cfg.autoPromoteAllowlist && allowlistEntryAllows(allow, kind) && entry.approved === true;
+		candidates.push({ ...entry, kind, source_type: "review_queue", domain, review_required: !explicit, promotion_policy: explicit ? "allowlist_auto_promote" : "manual_review", rights_access: entry.rights_access ?? null });
 	}
 	for (const spec of cfg.localBooks) for (const file of walkFiles(resolve(ROOT, spec.path), [".md", ".txt", ".pdf"], spec.max_files ?? 50)) candidates.push({ kind: "book", source_type: "local_file", title: basename(file), path: rel(file), rights_access: rightsFromSidecar(file), review_required: true, promotion_policy: "manual_review" });
 	for (const spec of cfg.localTranscripts) for (const file of walkFiles(resolve(ROOT, spec.path), [".md", ".txt", ".vtt"], spec.max_files ?? 80)) candidates.push({ kind: "transcript", source_type: "local_file", title: basename(file), path: rel(file), rights_access: rightsFromSidecar(file), review_required: true, promotion_policy: "manual_review" });
@@ -208,10 +239,11 @@ function sourceBody(candidate) {
 }
 
 function promotionAllowed(candidate) {
+	if (!hasCompleteProvenance(candidate)) return { ok: false, reason: "missing_complete_provenance" };
 	if (!hasRightsApproval(candidate)) return { ok: false, reason: "missing_rights_access_approval" };
 	if (RISKY_KINDS.has(candidate.kind) && candidate.approved !== true) return { ok: false, reason: "manual_approval_required" };
-	if (candidate.source_type === "review_queue" && candidate.promotion_policy === "allowlist_auto_promote" && candidate.allowlist_state.allowed && candidate.allowlist_state.approved) return { ok: true };
-	return candidate.approved === true ? { ok: true } : { ok: false, reason: "manual_approval_required" };
+	if (candidate.promotion_policy === "allowlist_auto_promote" && candidate.approved === true && allowlistAllows(candidate)) return { ok: true, reason: "allowlist_auto_promote" };
+	return candidate.approved === true ? { ok: true, reason: "manual_approved" } : { ok: false, reason: "manual_approval_required" };
 }
 
 function promote(candidate, args) {
@@ -267,15 +299,19 @@ function pilotMetrics(summary) {
 function schedulerSmoke() {
 	const service = readFileSync(resolve(ROOT, ".pi/harness/corpus/systemd/graphify-kb-updater.service"), "utf8");
 	const timer = readFileSync(resolve(ROOT, ".pi/harness/corpus/systemd/graphify-kb-updater.timer"), "utf8");
+	const envTemplate = readFileSync(resolve(ROOT, ".pi/harness/corpus/systemd/graphify-kb-updater.env.template"), "utf8");
 	const cron = readFileSync(resolve(ROOT, ".pi/harness/corpus/cron.example"), "utf8");
+	const graphifyArgs = envTemplate.match(/^GRAPHIFY_KB_ARGS=(.+)$/m)?.[1] ?? "";
 	const checks = {
 		systemd_daily: /OnCalendar=\*-\*-\*\s+08:30:00|OnCalendar=daily/i.test(timer),
 		cron_daily: /^30\s+8\s+\*\s+\*\s+\*/m.test(cron),
 		bounded_timeout: /timeout 45m/.test(service) && /timeout 45m/.test(cron),
 		locked_no_overlap: /flock -n/.test(service) && /flock -n/.test(cron),
 		explicit_env: /EnvironmentFile/.test(service) && /UP_ROOT/.test(cron),
+		working_directory: /WorkingDirectory=\$\{UP_ROOT\}/.test(service),
 		logged: /StandardOutput=append/.test(service) && /HARNESS_GRAPHIFY_KB_LOG/.test(cron),
-		refresh_intent: /--refresh-graph/.test(cron),
+		refresh_intent: /--refresh-graph/.test(cron) && /--refresh-graph/.test(graphifyArgs),
+		graphify_kb_args_template: /--apply/.test(graphifyArgs) && /--pilot-report/.test(graphifyArgs) && !/[;&|`$<>]/.test(graphifyArgs),
 	};
 	const ok = Object.values(checks).every(Boolean);
 	console.log(JSON.stringify({ ok, checks }, null, 2));
@@ -305,8 +341,8 @@ function main() {
 		}
 		if (contentChanged) changedExisting++;
 		const gate = promotionAllowed(c);
-		registry.candidates[c.id] = { ...(prior ?? {}), ...c, first_seen_at: prior?.first_seen_at ?? runAt, last_seen_at: runAt, status: gate.ok ? "promotable" : "review_required", block_reason: gate.reason ?? null, content_state: contentChanged ? "changed" : "new" };
-		if (!gate.ok) { blocked.push({ id: c.id, title: c.title, reason: gate.reason, allowlist_state: c.allowlist_state, category: c.category, competitor_labels: c.competitor_labels }); continue; }
+		registry.candidates[c.id] = { ...(prior ?? {}), ...c, first_seen_at: prior?.first_seen_at ?? runAt, last_seen_at: runAt, status: gate.ok ? "promotable" : "review_required", decision: gate.ok ? gate.reason : "stage_for_review", block_reason: gate.ok ? null : gate.reason, next_action: gate.ok ? "promote_on_apply" : "manual_review_required", content_state: contentChanged ? "changed" : "new" };
+		if (!gate.ok) { blocked.push({ id: c.id, title: c.title, kind: c.kind, source_type: c.source_type, reason: gate.reason, next_action: "manual_review_required", allowlist_state: c.allowlist_state, category: c.category, competitor_labels: c.competitor_labels }); continue; }
 		planned.push(c);
 	}
 
@@ -326,6 +362,7 @@ function main() {
 
 	const graph = refreshGraph(args, promoted);
 	const stale = registry.runs.at?.(-1)?.run_id ? [] : ["no_prior_apply_run_recorded"];
+	const reviewQueue = blocked.map((b) => ({ id: b.id, title: b.title, kind: b.kind, reason: b.reason, next_action: b.next_action })).slice(0, 50);
 	const summary = {
 		run_id: `kb-${Date.now()}`,
 		last_run_at: runAt,
@@ -335,6 +372,7 @@ function main() {
 		promoted_count: promoted,
 		duplicate_skips: duplicates,
 		blocked_count: blocked.length,
+		staged_count: blocked.length,
 		skipped_count: skipped.length,
 		failure_count: failed,
 		changed_existing_count: changedExisting,
@@ -344,6 +382,8 @@ function main() {
 		graph,
 		exit_status: failed || graph.ok === false ? 1 : 0,
 		promoted: promotedRefs,
+		review_queue_count: reviewQueue.length,
+		review_queue: reviewQueue,
 		blocked: blocked.slice(0, 50),
 		skipped: skipped.slice(0, 50),
 		config: rel(cfg.path),

package/.pi/scripts/harness-agents-manifest.mjs

@@ -7,6 +7,7 @@
  *   node .pi/scripts/harness-agents-manifest.mjs --check
  */
 
+import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,6 +16,10 @@ import {
 	sha256Content,
 	walkAgentsDir,
 } from "../lib/harness-agent-discovery.mjs";
+import {
+	loadAgentsPolicyMerged,
+	packageAgentsPolicyPath,
+} from "../lib/agents-policy.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const MANIFEST_PATH = join(ROOT, ".pi", "harness", "agents.manifest.json");
@@ -27,7 +32,7 @@ async function readPackageMeta() {
 	return { name: pkg.name ?? "ultimate-pi", version: pkg.version ?? "0.0.0" };
 }
 
-function buildManifest(packageFiles, packageName, packageVersion) {
+async function buildManifest(packageFiles, packageName, packageVersion) {
 	const agents = {};
 	for (const f of packageFiles.values()) {
 		agents[f.id] = {
@@ -35,11 +40,17 @@ function buildManifest(packageFiles, packageName, packageVersion) {
 			sha256: sha256Content(f.content),
 		};
 	}
+	const policyPath = packageAgentsPolicyPath(ROOT);
+	let policy_sha256;
+	if (existsSync(policyPath)) {
+		policy_sha256 = sha256Content(await readFile(policyPath, "utf-8"));
+	}
 	return {
 		schema_version: "1.0.0",
 		package: packageName,
 		package_version: packageVersion,
 		generated_at: new Date().toISOString(),
+		...(policy_sha256 ? { policy_sha256 } : {}),
 		agents,
 	};
 }
@@ -68,6 +79,37 @@ function getDriftReport(manifest, packageFiles) {
 	return { ok: items.length === 0, items };
 }
 
+function frontmatterHasToolLists(content) {
+	const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!m) return false;
+	return /^tools:/m.test(m[1]) || /^disallowed_tools:/m.test(m[1]);
+}
+
+function verifyAgentsPolicy(packageFiles) {
+	const items = [];
+	const policyPath = packageAgentsPolicyPath(ROOT);
+	if (!existsSync(policyPath)) {
+		return { ok: false, items: [{ id: "*", kind: "missing_agents_policy_yaml" }] };
+	}
+	const merged = loadAgentsPolicyMerged(ROOT, ROOT);
+	for (const [id, file] of packageFiles) {
+		if (!id.startsWith("harness/")) continue;
+		if (frontmatterHasToolLists(file.content)) {
+			items.push({ id, kind: "frontmatter_tools" });
+		}
+		if (!merged.agents.has(id)) {
+			items.push({ id, kind: "missing_policy_entry" });
+		}
+	}
+	for (const id of merged.agents.keys()) {
+		if (!id.startsWith("harness/")) continue;
+		if (!packageFiles.has(id)) {
+			items.push({ id, kind: "orphan_policy_entry" });
+		}
+	}
+	return { ok: items.length === 0, items };
+}
+
 async function loadPackageFiles() {
 	const files = new Map();
 	walkAgentsDir(PACKAGE_AGENTS, "package", files);
@@ -81,10 +123,10 @@ async function main() {
 	const mode = process.argv.includes("--check") ? "check" : "write";
 	const { name, version } = await readPackageMeta();
 	const packageFiles = await loadPackageFiles();
-	const built = buildManifest(packageFiles, name, version);
+	const built = await buildManifest(packageFiles, name, version);
 
 	if (mode === "write") {
-		await writeFile(MANIFEST_PATH, `${JSON.stringify(built, null, 2)}\n`, "utf-8");
+		await writeFile(MANIFEST_PATH, `${JSON.stringify(built, null, "\t")}\n`, "utf-8");
 		console.log(
 			`Wrote ${MANIFEST_PATH} (${Object.keys(built.agents).length} agents)`,
 		);
@@ -107,6 +149,19 @@ async function main() {
 		process.exit(1);
 	}
 
+	const policyCheck = verifyAgentsPolicy(packageFiles);
+	if (!policyCheck.ok) {
+		for (const item of policyCheck.items) {
+			console.error(`policy: ${item.id} (${item.kind})`);
+		}
+		process.exit(1);
+	}
+
+	if (built.policy_sha256 && onDisk.policy_sha256 !== built.policy_sha256) {
+		console.error("policy_sha256 mismatch — regenerate manifest with --write");
+		process.exit(1);
+	}
+
 	if (onDisk.package_version !== version) {
 		console.error(
 			`package_version mismatch: manifest=${onDisk.package_version} package=${version}`,
@@ -114,7 +169,9 @@ async function main() {
 		process.exit(1);
 	}
 
-	console.log(`agents.manifest.json OK (${Object.keys(built.agents).length} agents)`);
+	console.log(
+		`agents.manifest.json OK (${Object.keys(built.agents).length} agents, policy aligned)`,
+	);
 }
 
 main().catch((err) => {

package/.pi/scripts/harness-agt-doctor.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env npx tsx
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { doctorHarnessPolicies } from "../lib/agt/policy-engine.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const doc = doctorHarnessPolicies(ROOT);
+if (!doc.ok) {
+	console.error("AGT policy doctor failed:");
+	for (const e of doc.errors) console.error(`  - ${e}`);
+	process.exit(1);
+}
+const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")) as {
+	files?: string[];
+};
+const files = pkg.files ?? [];
+if (
+	!files.some(
+		(f: string) =>
+			f === ".pi/harness/policies" || f.startsWith(".pi/harness/policies/"),
+	)
+) {
+	console.error("package.json files[] missing .pi/harness/policies");
+	process.exit(1);
+}
+if (
+	!files.includes(".pi/lib") &&
+	!files.some((f) => f.startsWith(".pi/lib/"))
+) {
+	console.error("package.json files[] missing .pi/lib (ships .pi/lib/agt)");
+	process.exit(1);
+}
+console.log(
+	`AGT doctor OK (${doc.loaded.length} policies at ${doc.policyDir})`,
+);

package/.pi/scripts/harness-cli-verify.sh

@@ -262,11 +262,18 @@ verify_cocoindex() {
 
 verify_biome() {
 	log "[biome]"
-	npm_global_install "@biomejs/biome" "biome" || { fail "biome npm install"; return; }
+	if [ ! -f "${ROOT}/package.json" ] && [ ! -f "${ROOT}/biome.json" ]; then
+		warn "biome skipped (non-JS/TS repo detected; optional tool)"
+		return
+	fi
+	npm_global_install "@biomejs/biome" "biome" || {
+		warn "biome npm install failed (optional — use your stack's formatter/linter)"
+		return
+	}
 	if biome --version &>/dev/null; then
 		pass "biome $(biome --version 2>/dev/null | head -1)"
 	else
-		fail "biome --version failed"
+		warn "biome --version failed (optional — use your stack's formatter/linter)"
 	fi
 }
 

package/.pi/scripts/harness-project-toggle.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Toggle per-project harness governance — writes `.pi/harness/project.json`.
+ *
+ * Usage:
+ *   node harness-project-toggle.mjs status [--project-root DIR]
+ *   node harness-project-toggle.mjs enable [--project-root DIR]
+ *   node harness-project-toggle.mjs disable [--project-root DIR]
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CONFIG_BASENAME = "project.json";
+
+function parseArgs(argv) {
+	const args = [...argv];
+	let projectRoot = process.cwd();
+	const positional = [];
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--project-root" && args[i + 1]) {
+			projectRoot = args[++i];
+			continue;
+		}
+		positional.push(arg);
+	}
+	return { projectRoot, action: positional[0] ?? "status" };
+}
+
+function configPath(projectRoot) {
+	return join(projectRoot, ".pi", "harness", CONFIG_BASENAME);
+}
+
+function envOverrideEnabled() {
+	const raw = process.env.HARNESS_ENABLED?.trim().toLowerCase();
+	if (!raw) return null;
+	if (raw === "0" || raw === "false" || raw === "no") return false;
+	if (raw === "1" || raw === "true" || raw === "yes") return true;
+	return null;
+}
+
+function readConfig(projectRoot) {
+	const fromEnv = envOverrideEnabled();
+	if (fromEnv !== null) {
+		return {
+			schema_version: "1.0.0",
+			enabled: fromEnv,
+			source: "env:HARNESS_ENABLED",
+		};
+	}
+
+	const path = configPath(projectRoot);
+	if (!existsSync(path)) {
+		return {
+			schema_version: "1.0.0",
+			enabled: true,
+			source: "default",
+		};
+	}
+
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof raw.enabled === "boolean") {
+			return {
+				schema_version: "1.0.0",
+				enabled: raw.enabled,
+				updated_at: raw.updated_at,
+				source: path,
+			};
+		}
+	} catch {
+		// fall through
+	}
+
+	return {
+		schema_version: "1.0.0",
+		enabled: true,
+		source: "default-corrupt-file",
+	};
+}
+
+function writeConfig(projectRoot, enabled) {
+	const path = configPath(projectRoot);
+	mkdirSync(dirname(path), { recursive: true });
+	const payload = {
+		schema_version: "1.0.0",
+		enabled,
+		updated_at: new Date().toISOString(),
+	};
+	writeFileSync(path, `${JSON.stringify(payload, null, "\t")}\n`, "utf8");
+	return { ...payload, path };
+}
+
+function main() {
+	const { projectRoot, action } = parseArgs(process.argv.slice(2));
+	if (!["status", "enable", "disable"].includes(action)) {
+		console.error(
+			"Usage: harness-project-toggle.mjs <status|enable|disable> [--project-root DIR]",
+		);
+		process.exit(1);
+	}
+
+	if (action === "status") {
+		const config = readConfig(projectRoot);
+		console.log(JSON.stringify({ ok: true, projectRoot, ...config }, null, 2));
+		return;
+	}
+
+	const enabled = action === "enable";
+	const written = writeConfig(projectRoot, enabled);
+	console.log(
+		JSON.stringify(
+			{
+				ok: true,
+				projectRoot,
+				enabled: written.enabled,
+				path: written.path,
+				updated_at: written.updated_at,
+				reload_required: true,
+			},
+			null,
+			2,
+		),
+	);
+}
+
+main();