@fusengine/harness 0.1.91 → 0.1.93

package/src/adapters/cursor/respond.ts

@@ -1,6 +1,9 @@
 import { formatPrompt, type Prompt } from "../../prompt/types";
 import { cursorEventContract } from "./events";
 import { parseNativeCursorStdout } from "./native-response";
+import { capAdditionalContext } from "./context-limit";
+import { capAdditionalContextWithBudget } from "./context-budget";
+import type { CursorBudgetContext } from "./interfaces/context-budget";
 
 const AGENT_MESSAGE_EVENTS = new Set([
   "preToolUse",
@@ -30,39 +33,73 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Render a portable policy prompt using the native Cursor event contract. */
+/**
+ * Render a portable policy prompt using the native Cursor event contract.
+ * Switches exhaustively on {@link CursorResponseKind} — the `never` default
+ * fails to compile if a new kind is ever added without a matching case.
+ * `contract.known === false` is not tested separately: the single
+ * `UNKNOWN_EVENT` fallback in events.ts always pairs `known: false` with
+ * `response: "neutral"`, so both collapse to the same `"{}"` branch.
+ */
 export function toCursorResponse(prompt: Prompt, eventName: string): string {
   const contract = cursorEventContract(eventName);
   const message = formatPrompt(prompt);
-  if (!contract.known || contract.response === "neutral" || contract.response === "plugin-paths") return "{}";
-  if (contract.response === "post-context" || contract.response === "session-context") {
-    return JSON.stringify({ additional_context: message });
+  switch (contract.response) {
+    case "neutral":
+    case "plugin-paths":
+      return "{}";
+    case "post-context":
+    case "session-context":
+      return capAdditionalContext(JSON.stringify({ additional_context: message }));
+    case "followup":
+      return JSON.stringify({ followup_message: message });
+    case "compact-notice":
+      return JSON.stringify({ user_message: prompt.userMessage ?? message });
+    case "submit-control":
+      return JSON.stringify({ continue: prompt.kind !== "block", user_message: prompt.userMessage ?? message });
+    case "permission": {
+      if (prompt.kind === "inform") {
+        return JSON.stringify({
+          permission: "allow",
+          ...permissionMessages(eventName, prompt.userMessage, prompt.reason ? message : undefined),
+        });
+      }
+      const userMessage = prompt.kind === "ask"
+        ? `[downgraded from ask — Cursor does not enforce approval for this event]\n${message}`
+        : message;
+      return JSON.stringify({
+        permission: "deny",
+        ...permissionMessages(eventName, userMessage, userMessage),
+      });
+    }
+    default: {
+      const exhaustive: never = contract.response;
+      return exhaustive;
+    }
   }
-  if (contract.response === "followup") return JSON.stringify({ followup_message: message });
-  if (contract.response === "compact-notice") return JSON.stringify({ user_message: prompt.userMessage ?? message });
-  if (contract.response === "submit-control") {
-    return JSON.stringify({ continue: prompt.kind !== "block", user_message: prompt.userMessage ?? message });
-  }
-  if (prompt.kind === "inform") {
-    return JSON.stringify({
-      permission: "allow",
-      ...permissionMessages(eventName, prompt.userMessage, prompt.reason ? message : undefined),
-    });
-  }
-  const userMessage = prompt.kind === "ask"
-    ? `[downgraded from ask — Cursor does not enforce approval for this event]\n${message}`
-    : message;
-  return JSON.stringify({
-    permission: "deny",
-    ...permissionMessages(eventName, userMessage, userMessage),
-  });
 }
 
-/** Convert a shared lifecycle handler's output to the native Cursor envelope. */
-export function toCursorLifecycleResponse(stdout: string, eventName: string): string {
+/**
+ * Convert a shared lifecycle handler's output to the native Cursor envelope.
+ * The `neutral` and empty-`text` short circuits run before the switch (they
+ * apply identically across several {@link CursorResponseKind} values), so
+ * only the remaining 7 kinds need a case — `never` below still catches a
+ * future kind added without updating this function. This is the single
+ * point every Cursor stdout passes through exactly once (see `handle.ts`'s
+ * `handleHook`), so `budget` — when supplied — is reserved from and
+ * recorded into here, never at the inner `toCursorResponse` pre-cap (that
+ * one's output is re-capped here again on the native-passthrough branch
+ * below, so budgeting it too would double-count the same contribution).
+ * @param stdout - The shared handler's raw stdout for this hook invocation.
+ * @param eventName - Cursor's raw `hook_event_name`.
+ * @param budget - Shared `additional_context` budget context (see
+ * {@link CursorBudgetContext}); `undefined` falls back to the flat
+ * per-response 10,000-char cap, unbudgeted.
+ */
+export function toCursorLifecycleResponse(stdout: string, eventName: string, budget?: CursorBudgetContext): string {
   const contract = cursorEventContract(eventName);
   const native = parseNativeCursorStdout(stdout, eventName);
-  if (native !== null) return native;
+  if (native !== null) return capAdditionalContextWithBudget(native, budget);
   let text = stdout;
   let decision: "allow" | "deny" | "ask" | undefined;
   let userMessage = "";
@@ -97,27 +134,37 @@ export function toCursorLifecycleResponse(stdout: string, eventName: string): st
   }
   if (contract.response === "neutral") return "{}";
   if (!text) return contract.response === "permission" ? '{"permission":"allow"}' : "{}";
-  if (contract.response === "session-context" || contract.response === "post-context") {
-    return JSON.stringify({ additional_context: text });
-  }
-  if (contract.response === "permission") {
-    const permission = decision === "deny" || decision === "ask" ? "deny" : "allow";
-    const denied = permission === "deny";
-    // Cursor subagentStart can gate creation but has no model-context channel.
-    // Drop shared context and its "injected" notice on allow: preserving either
-    // would claim delivery the native event contract cannot perform.
-    if (eventName === "subagentStart" && !denied) return '{"permission":"allow"}';
-    return JSON.stringify({
-      permission,
-      ...permissionMessages(
-        eventName,
-        userMessage || (denied ? decisionMessage || agentMessage : ""),
-        agentMessage || (denied ? decisionMessage || userMessage : structured ? "" : text),
-      ),
-    });
+  switch (contract.response) {
+    case "session-context":
+    case "post-context":
+      return capAdditionalContextWithBudget(JSON.stringify({ additional_context: text }), budget);
+    case "permission": {
+      const permission = decision === "deny" || decision === "ask" ? "deny" : "allow";
+      const denied = permission === "deny";
+      // Cursor subagentStart can gate creation but has no model-context channel.
+      // Drop shared context and its "injected" notice on allow: preserving either
+      // would claim delivery the native event contract cannot perform.
+      if (eventName === "subagentStart" && !denied) return '{"permission":"allow"}';
+      return JSON.stringify({
+        permission,
+        ...permissionMessages(
+          eventName,
+          userMessage || (denied ? decisionMessage || agentMessage : ""),
+          agentMessage || (denied ? decisionMessage || userMessage : structured ? "" : text),
+        ),
+      });
+    }
+    case "followup":
+      return JSON.stringify({ followup_message: text });
+    case "compact-notice":
+      return JSON.stringify({ user_message: text });
+    case "submit-control":
+      return JSON.stringify({ continue: true, user_message: text });
+    case "plugin-paths":
+      return "{}";
+    default: {
+      const exhaustive: never = contract.response;
+      return exhaustive;
+    }
   }
-  if (contract.response === "followup") return JSON.stringify({ followup_message: text });
-  if (contract.response === "compact-notice") return JSON.stringify({ user_message: text });
-  if (contract.response === "submit-control") return JSON.stringify({ continue: true, user_message: text });
-  return "{}";
 }

package/src/cli/bin.ts

@@ -23,6 +23,7 @@ import { runDoctor, runningVersion, versionBanner } from "./doctor";
 import { parseScope } from "./scope";
 import { isMalformedCursorStdin, isOversize, oversizeStdout, readStdin, traceHook } from "./hook-io";
 import { maybePlaySound } from "./hook-sound";
+import { runPrd } from "./prd";
 
 const cmd = process.argv[2];
 
@@ -77,6 +78,8 @@ if (cmd === "--version" || cmd === "-v") {
   const dir = process.argv[3] ?? process.cwd();
   process.stdout.write(JSON.stringify(runSecurityScan(dir), null, 2) + "\n");
   process.exit(0);
+} else if (cmd === "prd") {
+  process.exit(await runPrd(process.argv.slice(3), process.cwd(), process.env));
 } else if (cmd === "codex-rules") {
   const outIdx = process.argv.indexOf("--out");
   const outPath = outIdx !== -1 ? process.argv[outIdx + 1] : undefined;

package/src/cli/index.ts

@@ -1 +1,2 @@
 export * from "./run";
+export * from "./prd";

package/src/cli/prd/compact.ts

@@ -0,0 +1,53 @@
+/**
+ * `harness prd compact <task> [--id] [--root]` — collapses every fully
+ * validated agent entry of a task-PRD to its compacted shape. Requires
+ * `FUSE_PRD=1`; refuses (exit 1) when any sub-task is not yet `validated`.
+ */
+import { writeTaskFile } from "../../policy/prd/prd-io";
+import { compactTaskFile } from "../../policy/prd/prd-compact";
+import { isCompacted, subTasksOf } from "../../policy/prd/prd-schema";
+import { requireFusePrd, resolveTaskFile, withPrdLock } from "./shared";
+
+/**
+ * Run `harness prd compact`. Exit 0 on success (including a no-op compact),
+ * exit 1 when `FUSE_PRD` is unset, a sub-task is unvalidated, or the lock is
+ * held, exit 2 on usage/lookup errors.
+ */
+export async function runPrdCompact(argv: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const resolved = requireFusePrd(argv, cwd, env, "compact");
+  if (!resolved.ok) {
+    process.stderr.write(resolved.message + "\n");
+    return resolved.code;
+  }
+  const { root, homeSeg } = resolved;
+
+  const tf = await resolveTaskFile(argv, root, homeSeg, "usage: harness prd compact <task>");
+  if (!tf.ok) {
+    process.stderr.write(tf.message + "\n");
+    return tf.code;
+  }
+  const { routerEntry, taskFile } = tf;
+
+  for (const [agent, entry] of Object.entries(taskFile)) {
+    if (isCompacted(entry)) continue;
+    for (const [sub, status] of Object.entries(subTasksOf(entry))) {
+      if (status.status !== "validated") {
+        process.stderr.write(`prd compact: sub-task "${sub}" of agent "${agent}" is not validated\n`);
+        return 1;
+      }
+    }
+  }
+
+  const result = await withPrdLock(root, homeSeg, async () => {
+    const now = new Date().toISOString();
+    const { file, compacted } = compactTaskFile(taskFile, now);
+    await writeTaskFile(root, homeSeg, routerEntry.prd, file);
+    return compacted;
+  });
+  if (!result.ok) {
+    process.stderr.write(`prd compact: ${result.message}\n`);
+    return 1;
+  }
+  process.stdout.write(result.value.length > 0 ? `compacted: ${result.value.join(", ")}\n` : "nothing to compact\n");
+  return 0;
+}

package/src/cli/prd/format.ts

@@ -0,0 +1,23 @@
+/**
+ * Rendering helpers for `harness prd` output: an aligned ASCII table for the
+ * human-readable path, and pretty JSON for `--json`.
+ */
+
+/** Pad `s` with trailing spaces to `width`. */
+function pad(s: string, width: number): string {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
+/** Render an aligned ASCII table from a header row + data rows. */
+export function renderTable(header: string[], rows: string[][]): string {
+  const all: string[][] = [header, ...rows];
+  const widths = header.map((_, col) => Math.max(...all.map((r) => (r[col] ?? "").length)));
+  return all
+    .map((r) => r.map((cell, col) => pad(cell ?? "", widths[col] ?? 0)).join("  ").trimEnd())
+    .join("\n");
+}
+
+/** Render `data` as pretty-printed JSON with a trailing newline. */
+export function renderJson(data: unknown): string {
+  return JSON.stringify(data, null, 2) + "\n";
+}

package/src/cli/prd/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `harness prd <status|validate|compact>` — CLI entry point for the PRD
+ * (task/agent ownership coordination) module.
+ */
+export * from "./resolve";
+export * from "./format";
+export { runPrdStatus } from "./status";
+export { runPrdValidate } from "./validate";
+export { runPrdCompact } from "./compact";
+
+import { runPrdStatus } from "./status";
+import { runPrdValidate } from "./validate";
+import { runPrdCompact } from "./compact";
+
+/** Dispatch `harness prd <sub> ...rest` to the matching `run*` function. */
+export async function runPrd(argv: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const [sub, ...rest] = argv;
+  if (sub === "status") return runPrdStatus(rest, cwd, env);
+  if (sub === "validate") return runPrdValidate(rest, cwd, env);
+  if (sub === "compact") return runPrdCompact(rest, cwd, env);
+  process.stderr.write(`harness prd: unknown sub-command "${sub ?? ""}" (expected status|validate|compact)\n`);
+  return 2;
+}

package/src/cli/prd/resolve.ts

@@ -0,0 +1,88 @@
+/**
+ * Argument parsing + harness resolution for `harness prd <cmd>`. Resolves
+ * `--root` (default `cwd`) and `--id`/`homeSeg` (default: the sole
+ * `HOME_DIR` (`config/dotenv.ts`) segment under which
+ * `<root>/<seg>/apex/prd.json` exists — ambiguous or absent is a caller
+ * error, never guessed).
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { HOME_DIR, loadDotenv } from "../../config/dotenv";
+import { harnessHomeSegment } from "../../policy/apex-target";
+import type { HarnessId } from "../../detect/interfaces/types";
+
+const VALUE_FLAGS: ReadonlySet<string> = new Set(["--id", "--root"]);
+const BOOLEAN_FLAGS: ReadonlySet<string> = new Set(["--json"]);
+
+/** Resolved `--root`/`--id` pair for a `prd` sub-command. */
+export interface PrdResolved {
+  root: string;
+  homeSeg: string;
+  id: HarnessId;
+}
+
+/** Result of {@link resolvePrdArgs}: resolved args, or a usage error (exit 2). */
+export type PrdResolveResult = { ok: true; value: PrdResolved } | { ok: false; message: string };
+
+/** Read `--<name> <value>` from argv, or `undefined` when absent. */
+export function readFlag(argv: string[], name: string): string | undefined {
+  const idx = argv.indexOf(name);
+  return idx !== -1 ? argv[idx + 1] : undefined;
+}
+
+/** True when `--json` is present in argv. */
+export function hasJsonFlag(argv: string[]): boolean {
+  return argv.includes("--json");
+}
+
+/** Non-flag tokens in argv, skipping known flags and their values. */
+export function positionalArgs(argv: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === undefined) continue;
+    if (VALUE_FLAGS.has(tok)) { i++; continue; }
+    if (BOOLEAN_FLAGS.has(tok)) continue;
+    out.push(tok);
+  }
+  return out;
+}
+
+/**
+ * Resolve `{root, homeSeg, id}` for a `prd` sub-command. `--id` wins
+ * outright; otherwise auto-detects the sole `HOME_DIR` segment under which
+ * `<root>/<seg>/apex/prd.json` exists.
+ */
+export function resolvePrdArgs(argv: string[], cwd: string): PrdResolveResult {
+  const root = readFlag(argv, "--root") ?? cwd;
+  const idFlag = readFlag(argv, "--id");
+  if (idFlag) {
+    return { ok: true, value: { root, homeSeg: harnessHomeSegment(idFlag), id: idFlag as HarnessId } };
+  }
+
+  const matches: Array<{ id: HarnessId; seg: string }> = [];
+  for (const [id, seg] of Object.entries(HOME_DIR) as Array<[HarnessId, string]>) {
+    if (existsSync(join(root, seg, "apex", "prd.json"))) matches.push({ id, seg });
+  }
+  if (matches.length === 0) {
+    return { ok: false, message: `no PRD router found under ${root}/<home>/apex/prd.json — pass --id <harness>` };
+  }
+  if (matches.length > 1) {
+    return { ok: false, message: `ambiguous harness: PRD routers found for ${matches.map((m) => m.id).join(", ")} — pass --id` };
+  }
+  const only = matches[0] as { id: HarnessId; seg: string };
+  return { ok: true, value: { root, homeSeg: only.seg, id: only.id } };
+}
+
+/**
+ * Shared first step of every `prd` sub-command: {@link resolvePrdArgs}, then
+ * (on success) `loadDotenv` the resolved harness's home `.env` + `<root>/.env`
+ * as a side effect on `env` — same env-loading contract as the `hook` branch
+ * (`bin.ts`'s `loadDotenv(id)` call).
+ */
+export function resolveAndLoadEnv(argv: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): PrdResolveResult {
+  const resolved = resolvePrdArgs(argv, cwd);
+  if (resolved.ok) loadDotenv(resolved.value.id, env, homedir(), resolved.value.root);
+  return resolved;
+}

package/src/cli/prd/shared.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared plumbing for `status`/`validate`/`compact`: root+env resolution,
+ * the `FUSE_PRD` write gate, task-PRD lookup, and the `.lock`-guarded write.
+ * All return a result instead of calling `process.exit` themselves —
+ * callers own the exit code (extracted to kill a jscpd-measured clone
+ * across the three `run*` functions).
+ */
+import { join } from "node:path";
+import { prdDir } from "../../policy/prd/prd-paths";
+import { readRouter, readTaskFile } from "../../policy/prd/prd-io";
+import { isPrdFlagSet } from "../../policy/prd/prd-enabled";
+import type { PrdRouter, PrdRouterEntry, PrdTaskFile } from "../../policy/prd/interfaces/types";
+import { acquireLock } from "../../runtime/lifecycle/aipilot/apex-task-store";
+import { positionalArgs, resolveAndLoadEnv } from "./resolve";
+
+/** `{root, homeSeg}` on success, or an exit code + message on failure. */
+export type PrdStepResult = { ok: true; root: string; homeSeg: string } | { ok: false; code: number; message: string };
+
+/** {@link resolveAndLoadEnv}, narrowed to `{root, homeSeg}` — the common first step of every sub-command. */
+export function resolveRoot(argv: string[], cwd: string, env: NodeJS.ProcessEnv): PrdStepResult {
+  const resolved = resolveAndLoadEnv(argv, cwd, env);
+  if (!resolved.ok) return { ok: false, code: 2, message: resolved.message };
+  return { ok: true, root: resolved.value.root, homeSeg: resolved.value.homeSeg };
+}
+
+/** {@link resolveRoot} + the `FUSE_PRD=1` write gate shared by `validate`/`compact`. */
+export function requireFusePrd(argv: string[], cwd: string, env: NodeJS.ProcessEnv, sub: string): PrdStepResult {
+  const resolved = resolveRoot(argv, cwd, env);
+  if (!resolved.ok) return resolved;
+  if (!isPrdFlagSet(env)) {
+    return { ok: false, code: 1, message: `prd ${sub} requires FUSE_PRD=1 in ${resolved.homeSeg}/.env or the project .env` };
+  }
+  return resolved;
+}
+
+/** Result of {@link loadTaskFileFor}: the resolved router/task-PRD, or a usage error. */
+export type PrdTaskLookup =
+  | { ok: true; router: PrdRouter; routerEntry: PrdRouterEntry; taskFile: PrdTaskFile }
+  | { ok: false; code: 2; message: string };
+
+/** Reads the router + the named task's task-PRD file. Never calls `process.exit`. */
+export async function loadTaskFileFor(root: string, homeSeg: string, task: string): Promise<PrdTaskLookup> {
+  const router = await readRouter(root, homeSeg);
+  const routerEntry = router?.[task];
+  if (!router || !routerEntry) return { ok: false, code: 2, message: `no such task "${task}" in PRD router` };
+
+  const taskFile = await readTaskFile(root, homeSeg, routerEntry.prd);
+  if (!taskFile) return { ok: false, code: 2, message: `task PRD not found or malformed: ${routerEntry.prd}` };
+
+  return { ok: true, router, routerEntry, taskFile };
+}
+
+/** Result of {@link resolveTaskFile}: the `<task>` positional plus its looked-up files, or a usage/lookup error. */
+export type PrdTaskArgLookup =
+  | { ok: true; task: string; agentArg: string | undefined; router: PrdRouter; routerEntry: PrdRouterEntry; taskFile: PrdTaskFile }
+  | { ok: false; code: 2; message: string };
+
+/** Extracts `<task> [agent]` from argv, then {@link loadTaskFileFor} — the shared `validate`/`compact` entry lookup. */
+export async function resolveTaskFile(argv: string[], root: string, homeSeg: string, usage: string): Promise<PrdTaskArgLookup> {
+  const [task, agentArg] = positionalArgs(argv);
+  if (!task) return { ok: false, code: 2, message: usage };
+  const lookup = await loadTaskFileFor(root, homeSeg, task);
+  if (!lookup.ok) return lookup;
+  return { task, agentArg, ...lookup };
+}
+
+/** Result of {@link withPrdLock}. */
+export type PrdLockResult<T> = { ok: true; value: T } | { ok: false; message: string };
+
+/** Runs `fn` under the PRD `.lock` directory-lock. Never calls `process.exit`. */
+export async function withPrdLock<T>(root: string, homeSeg: string, fn: () => Promise<T>): Promise<PrdLockResult<T>> {
+  const lockDir = join(prdDir(root, homeSeg), ".lock");
+  const release = await acquireLock(lockDir);
+  if (!release) return { ok: false, message: `lock held at ${lockDir}` };
+  try {
+    return { ok: true, value: await fn() };
+  } finally {
+    await release();
+  }
+}

package/src/cli/prd/status.ts

@@ -0,0 +1,87 @@
+/**
+ * `harness prd status [--json] [--id <harness>] [--root <dir>]` — read-only
+ * PRD snapshot. Never requires `FUSE_PRD`. Exit 0 on success, exit 1 when no
+ * router is found, exit 2 on an unresolved/ambiguous `--id`.
+ */
+import { prdRouterPath } from "../../policy/prd/prd-paths";
+import { readAgentReport, readAllTaskFiles, readRouter } from "../../policy/prd/prd-io";
+import { crossCheckTask } from "../../policy/prd/prd-crosscheck";
+import { isCompacted, subTasksOf } from "../../policy/prd/prd-schema";
+import type { PrdAgentReportFile, PrdTaskFile } from "../../policy/prd/interfaces/types";
+import { hasJsonFlag } from "./resolve";
+import { renderJson, renderTable } from "./format";
+import { resolveRoot } from "./shared";
+
+const HEADER: string[] = ["Task", "Router status", "Agents", "Sub-tasks done/total", "Violations"];
+
+/**
+ * Sub-task readiness counts for the "done/total" column: a sub-task counts as
+ * done once it is `validated` OR its owning agent's own report already shows
+ * `"done"` for it (readiness view — a report can land well before the
+ * coordinator runs `prd validate`). A compacted (fully-validated) entry
+ * counts as one done/one total unit — its per-sub-task detail is gone.
+ */
+function subTaskCounts(
+  taskFile: PrdTaskFile,
+  reports: Record<string, PrdAgentReportFile | null>,
+  task: string,
+): { done: number; total: number } {
+  let done = 0;
+  let total = 0;
+  for (const [agent, entry] of Object.entries(taskFile)) {
+    if (isCompacted(entry)) {
+      done++;
+      total++;
+      continue;
+    }
+    const report = reports[agent];
+    for (const [sub, subTask] of Object.entries(subTasksOf(entry))) {
+      total++;
+      if (subTask.status === "validated" || report?.[task]?.[sub]?.status === "done") done++;
+    }
+  }
+  return { done, total };
+}
+
+/**
+ * Run `harness prd status`. Prints an aligned table (or `--json` dump of
+ * `{router, taskFiles, reports}`) and returns the process exit code.
+ */
+export async function runPrdStatus(argv: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const resolved = resolveRoot(argv, cwd, env);
+  if (!resolved.ok) {
+    process.stderr.write(resolved.message + "\n");
+    return resolved.code;
+  }
+  const { root, homeSeg } = resolved;
+
+  const router = await readRouter(root, homeSeg);
+  if (!router) {
+    process.stderr.write(`no PRD router at ${prdRouterPath(root, homeSeg)}\n`);
+    return 1;
+  }
+
+  const taskFiles = await readAllTaskFiles(root, homeSeg, router);
+  const agentNames = new Set<string>();
+  for (const tf of Object.values(taskFiles)) {
+    if (tf) for (const agent of Object.keys(tf)) agentNames.add(agent);
+  }
+  const reports: Record<string, PrdAgentReportFile | null> = {};
+  for (const agent of agentNames) reports[agent] = await readAgentReport(root, homeSeg, agent);
+
+  if (hasJsonFlag(argv)) {
+    process.stdout.write(renderJson({ router, taskFiles, reports }));
+    return 0;
+  }
+
+  const rows: string[][] = [];
+  for (const [task, entry] of Object.entries(router)) {
+    const tf = taskFiles[task];
+    const agentCount = tf ? Object.keys(tf).length : 0;
+    const { done, total } = tf ? subTaskCounts(tf, reports, task) : { done: 0, total: 0 };
+    const violations = tf ? crossCheckTask(tf, reports as Record<string, PrdAgentReportFile>, task) : [];
+    rows.push([task, entry.status, String(agentCount), `${done}/${total}`, String(violations.length)]);
+  }
+  process.stdout.write(renderTable(HEADER, rows) + "\n");
+  return 0;
+}

package/src/cli/prd/validate.ts

@@ -0,0 +1,90 @@
+/**
+ * `harness prd validate <task> [agent] [--id] [--root]` — cross-checks a
+ * task-PRD against the named agent(s)' own report(s); on success flips the
+ * matching sub-tasks to `validated` and promotes the router entry when every
+ * agent is fully validated. Requires `FUSE_PRD=1`.
+ */
+import { readAgentReport, writeRouter, writeTaskFile } from "../../policy/prd/prd-io";
+import { incompleteSubTasks } from "../../policy/prd/prd-crosscheck";
+import { isCompacted, subTasksOf, withRouterStatus, withSubTaskValidated } from "../../policy/prd/prd-schema";
+import type { PrdAgentReportFile, PrdCrossCheckViolation, PrdTaskFile } from "../../policy/prd/interfaces/types";
+import { requireFusePrd, resolveTaskFile, withPrdLock } from "./shared";
+
+function allValidated(taskFile: PrdTaskFile): boolean {
+  return Object.values(taskFile).every(
+    (entry) => isCompacted(entry) || Object.values(subTasksOf(entry)).every((s) => s.status === "validated"),
+  );
+}
+
+/**
+ * Sub-tasks of `agents` with no matching `done` entry in their owning
+ * agent's own report — the readiness gate `validate` enforces before
+ * flipping anything. Reuses `incompleteSubTasks` (distinct from
+ * `crossCheckTask`, which only flags an ALREADY-`validated` sub-task lacking
+ * a report; here nothing has been validated yet).
+ */
+function findUnreadySubTasks(
+  taskFile: PrdTaskFile,
+  reports: Record<string, PrdAgentReportFile | null>,
+  task: string,
+  agents: string[],
+): PrdCrossCheckViolation[] {
+  const out: PrdCrossCheckViolation[] = [];
+  for (const agent of agents) {
+    const missing = incompleteSubTasks(taskFile, agent, task, reports[agent] ?? null);
+    for (const sub of missing) out.push({ task, agent, sub, reason: `no "done" report from "${agent}" for sub-task "${sub}"` });
+  }
+  return out;
+}
+
+/**
+ * Run `harness prd validate`. Exit 0 on success, exit 1 on cross-check
+ * violations or a missing `FUSE_PRD=1`/held lock, exit 2 on usage/lookup errors.
+ */
+export async function runPrdValidate(argv: string[], cwd: string, env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const resolved = requireFusePrd(argv, cwd, env, "validate");
+  if (!resolved.ok) {
+    process.stderr.write(resolved.message + "\n");
+    return resolved.code;
+  }
+  const { root, homeSeg } = resolved;
+
+  const tf = await resolveTaskFile(argv, root, homeSeg, "usage: harness prd validate <task> [agent]");
+  if (!tf.ok) {
+    process.stderr.write(tf.message + "\n");
+    return tf.code;
+  }
+  const { task, agentArg, router, routerEntry, taskFile } = tf;
+  if (agentArg && !(agentArg in taskFile)) {
+    process.stderr.write(`no such agent "${agentArg}" in task PRD for "${task}"\n`);
+    return 2;
+  }
+
+  const agents = agentArg ? [agentArg] : Object.keys(taskFile);
+  const reports: Record<string, PrdAgentReportFile | null> = {};
+  for (const agent of Object.keys(taskFile)) reports[agent] = await readAgentReport(root, homeSeg, agent);
+
+  const violations = findUnreadySubTasks(taskFile, reports, task, agents);
+  if (violations.length > 0) {
+    process.stderr.write(`prd validate: ${violations.length} violation(s)\n`);
+    for (const v of violations) process.stderr.write(`  - ${v.task}/${v.agent}/${v.sub}: ${v.reason}\n`);
+    return 1;
+  }
+
+  const result = await withPrdLock(root, homeSeg, async () => {
+    const now = new Date().toISOString();
+    let updated = taskFile;
+    for (const agent of agents) {
+      const entry = updated[agent];
+      if (!entry || isCompacted(entry)) continue;
+      for (const sub of Object.keys(subTasksOf(entry))) updated = withSubTaskValidated(updated, agent, sub, now);
+    }
+    await writeTaskFile(root, homeSeg, routerEntry.prd, updated);
+    if (allValidated(updated)) await writeRouter(root, homeSeg, withRouterStatus(router, task, "validated", now));
+  });
+  if (!result.ok) {
+    process.stderr.write(`prd validate: ${result.message}\n`);
+    return 1;
+  }
+  return 0;
+}