@fusengine/harness 0.1.92 → 0.1.94

package/dist/{store-5-ZPKb0u.mjs → store-BVY6gIYM.mjs}

@@ -1,9 +1,9 @@
-import { l as ttlLabel } from "./dotenv-BLBkBTww.mjs";
+import { i as ttlLabel } from "./ttl-Dgwg_QAv.mjs";
 import { n as fuseHarnessHome } from "./home-state-oUGFB4ds.mjs";
 import { a as writeJsonFile, i as readJsonFile, t as atomicWrite } from "./json-io-DisYd2fb.mjs";
 import { i as resolveSessions } from "./doc-helpers-CWZegVdR.mjs";
 import { t as routeReferences } from "./router-PKVNBHge.mjs";
-import { t as resolveSkillPath } from "./skill-path-DVML3zfp.mjs";
+import { t as resolveSkillPath } from "./skill-path-Cz8WFaGu.mjs";
 import { dirname, join } from "node:path";
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHmac, randomBytes } from "node:crypto";
@@ -142,6 +142,8 @@ const apexAuthorizationGate = (ctx) => {
 };
 //#endregion
 //#region src/tracking/session-state.ts
+/** Cap on {@link SessionTrack.prdViolations} (mirrors the `receipts` style bound — oldest evicted first). */
+const PRD_VIOLATIONS_CAP = 50;
 /** A fresh, empty track. */
 function emptyTrack() {
 	return {
@@ -244,6 +246,45 @@ function recordBrainstormRequired(track, required) {
 		brainstormRequired: required
 	};
 }
+/** Bind `agentId` to its resolved PRD agent-report `name` (merge; idempotent no-op if already bound to the same name). Immutable. */
+function recordPrdOwner(track, agentId, name) {
+	if (track.prdOwners?.[agentId] === name) return track;
+	return {
+		...track,
+		prdOwners: {
+			...track.prdOwners,
+			[agentId]: name
+		}
+	};
+}
+/**
+* Append one PRD cross-check violation. Immutable, uncapped in the mutator
+* itself — same append-only shape as {@link Receipt} — so the journal diff's
+* prefix comparison (`tail`, track-diff.ts) never sees an eviction it would
+* mistake for a bulk rewrite. The {@link PRD_VIOLATIONS_CAP} bound is applied
+* only when the journal is folded/read (track-journal.ts's `foldEvents`),
+* mirroring how `trivialEdits`'s sliding window is re-derived at fold time.
+*/
+function recordPrdViolation(track, v) {
+	return {
+		...track,
+		prdViolations: [...track.prdViolations ?? [], v]
+	};
+}
+/** Record a PRD SubagentStop/Stop one-shot block marker (merge). Immutable. */
+function recordPrdStopBlocked(track, key, ts) {
+	return {
+		...track,
+		prdStopBlocked: {
+			...track.prdStopBlocked,
+			[key]: ts
+		}
+	};
+}
+/** True when the PRD one-shot block for `key` has already fired. */
+function prdAlreadyBlocked(track, key) {
+	return track.prdStopBlocked?.[key] !== void 0;
+}
 //#endregion
 //#region src/tracking/integrity.ts
 /**
@@ -572,6 +613,9 @@ function foldEvents(events, base = emptyTrack()) {
 	const at = { ...base.refsReadAt };
 	const receipts = [...base.receipts ?? []];
 	const trivial = new Set(base.trivialEdits ?? []);
+	const prdOwners = { ...base.prdOwners };
+	const prdViolations = [...base.prdViolations ?? []];
+	const prdStopBlocked = { ...base.prdStopBlocked };
 	let targetTs = base.target ? Date.parse(base.target.set_at) || 0 : 0, brainstormTs = 0;
 	for (const ev of [...events].sort((a, b) => a.ts - b.ts)) if (ev.field === "refsRead") {
 		const p = String(ev.value);
@@ -591,9 +635,19 @@ function foldEvents(events, base = emptyTrack()) {
 	} else if (ev.field === "brainstormRequired" && ev.ts >= brainstormTs) {
 		t.brainstormRequired = Boolean(ev.value);
 		brainstormTs = ev.ts;
+	} else if (ev.field === "prdOwners") {
+		const [aid, name] = ev.value;
+		prdOwners[aid] = name;
+	} else if (ev.field === "prdViolations") prdViolations.push(ev.value);
+	else if (ev.field === "prdStopBlocked") {
+		const [key, ts] = ev.value;
+		prdStopBlocked[key] = ts;
 	}
 	if (Object.keys(at).length) t.refsReadAt = at;
 	if (receipts.length) t.receipts = receipts;
+	if (Object.keys(prdOwners).length) t.prdOwners = prdOwners;
+	if (prdViolations.length) t.prdViolations = prdViolations.slice(-50);
+	if (Object.keys(prdStopBlocked).length) t.prdStopBlocked = prdStopBlocked;
 	const maxT = Math.max(0, ...trivial);
 	t.trivialEdits = [...trivial].filter((x) => x > maxT - TRIVIAL_WINDOW_MS).sort((a, b) => a - b);
 	return t;
@@ -673,6 +727,24 @@ function diffTrackEvents(prev, next, now) {
 		value: next.brainstormRequired,
 		ts: now
 	});
+	for (const [aid, name] of Object.entries(next.prdOwners ?? {})) if (prev.prdOwners?.[aid] !== name) out.push({
+		field: "prdOwners",
+		op: "merge",
+		value: [aid, name],
+		ts: now
+	});
+	for (const v of tail(prev.prdViolations ?? [], next.prdViolations ?? [])) out.push({
+		field: "prdViolations",
+		op: "append",
+		value: v,
+		ts: v.ts ?? now
+	});
+	for (const [key, ts] of Object.entries(next.prdStopBlocked ?? {})) if (prev.prdStopBlocked?.[key] !== ts) out.push({
+		field: "prdStopBlocked",
+		op: "merge",
+		value: [key, ts],
+		ts
+	});
 	return out;
 }
 /** The journal log path twin of a track snapshot path. */
@@ -842,4 +914,4 @@ async function withTrack(file, mutate) {
 	}) !== LOCK_FAILED;
 }
 //#endregion
-export { apexAuthorizationGate as C, trivialCount as S, recordBrainstormRequired as _, journalLogPath as a, recordTarget as b, appendEvent as c, signTrack as d, verifyTrack as f, recordAgent as g, emptyTrack as h, withTrack as i, withTrackLockSync as l, agentsFresh as m, saveTrack as n, readTrackSync as o, writeLastNonce as p, trackJournalEnabled as r, diffTrackEvents as s, loadTrack as t, LOCK_FAILED as u, recordDoc as v, recordTrivialEdit as x, recordRefRead as y };
+export { recordPrdViolation as C, trivialCount as D, recordTrivialEdit as E, apexAuthorizationGate as O, recordPrdStopBlocked as S, recordTarget as T, prdAlreadyBlocked as _, journalLogPath as a, recordDoc as b, appendEvent as c, signTrack as d, verifyTrack as f, emptyTrack as g, agentsFresh as h, withTrack as i, withTrackLockSync as l, PRD_VIOLATIONS_CAP as m, saveTrack as n, readTrackSync as o, writeLastNonce as p, trackJournalEnabled as r, diffTrackEvents as s, loadTrack as t, LOCK_FAILED as u, recordAgent as v, recordRefRead as w, recordPrdOwner as x, recordBrainstormRequired as y };

package/dist/tracking/index.d.mts

@@ -1,4 +1,4 @@
-import { a as recordAgent, c as recordRefRead, d as trivialCount, i as emptyTrack, l as recordTarget, n as SessionTrack, o as recordBrainstormRequired, r as agentsFresh, s as recordDoc, t as AgentQuality, u as recordTrivialEdit } from "../session-state-D5gLr66m.mjs";
+import { _ as trivialCount, a as agentsFresh, c as recordAgent, d as recordPrdOwner, f as recordPrdStopBlocked, g as recordTrivialEdit, h as recordTarget, i as SessionTrack, l as recordBrainstormRequired, m as recordRefRead, n as PRD_VIOLATIONS_CAP, o as emptyTrack, p as recordPrdViolation, r as PrdViolationRecord, s as prdAlreadyBlocked, t as AgentQuality, u as recordDoc } from "../session-state-COg7Ej_2.mjs";
 //#region src/tracking/store.d.ts
 /** Journal mode is the default; `FUSE_TRACK_JOURNAL=0` reverts to the legacy locked RMW (see the module NOTE: =0 ignores the uncompacted journal — recoverable, keep the `.log`). */
 declare function trackJournalEnabled(): boolean;
@@ -26,4 +26,4 @@ declare function saveTrack(file: string, track: SessionTrack): Promise<void>;
  */
 declare function withTrack(file: string, mutate: (track: SessionTrack) => SessionTrack | Promise<SessionTrack>): Promise<boolean>;
 //#endregion
-export { AgentQuality, SessionTrack, agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };
+export { AgentQuality, PRD_VIOLATIONS_CAP, PrdViolationRecord, SessionTrack, agentsFresh, emptyTrack, loadTrack, prdAlreadyBlocked, recordAgent, recordBrainstormRequired, recordDoc, recordPrdOwner, recordPrdStopBlocked, recordPrdViolation, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };

package/dist/tracking/index.mjs

@@ -1,2 +1,2 @@
-import { S as trivialCount, _ as recordBrainstormRequired, b as recordTarget, g as recordAgent, h as emptyTrack, i as withTrack, m as agentsFresh, n as saveTrack, r as trackJournalEnabled, t as loadTrack, v as recordDoc, x as recordTrivialEdit, y as recordRefRead } from "../store-5-ZPKb0u.mjs";
-export { agentsFresh, emptyTrack, loadTrack, recordAgent, recordBrainstormRequired, recordDoc, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };
+import { C as recordPrdViolation, D as trivialCount, E as recordTrivialEdit, S as recordPrdStopBlocked, T as recordTarget, _ as prdAlreadyBlocked, b as recordDoc, g as emptyTrack, h as agentsFresh, i as withTrack, m as PRD_VIOLATIONS_CAP, n as saveTrack, r as trackJournalEnabled, t as loadTrack, v as recordAgent, w as recordRefRead, x as recordPrdOwner, y as recordBrainstormRequired } from "../store-BVY6gIYM.mjs";
+export { PRD_VIOLATIONS_CAP, agentsFresh, emptyTrack, loadTrack, prdAlreadyBlocked, recordAgent, recordBrainstormRequired, recordDoc, recordPrdOwner, recordPrdStopBlocked, recordPrdViolation, recordRefRead, recordTarget, recordTrivialEdit, saveTrack, trackJournalEnabled, trivialCount, withTrack };

package/dist/ttl-Dgwg_QAv.mjs

@@ -0,0 +1,26 @@
+import { l as parseEnvInt } from "./limits-DG5pl-5s.mjs";
+//#region src/config/ttl.ts
+/**
+* Default enforcement-freshness window, in seconds (2 minutes). Matches the
+* plugin's original `FUSE_ENFORCE_TTL_SEC` default. This is the constant that
+* actually reaches production (via `resolveTtlSec` -> `bin.ts`); `gate.ts`'s
+* `DEFAULT_WINDOW_MS` is only a fallback for direct programmatic callers that
+* omit `windowMs` (e.g. tests) and never applies on the real CLI path.
+*/
+const DEFAULT_TTL_SEC = 120;
+/** Default env var name carrying the TTL override. */
+const TTL_ENV_KEY = "FUSE_ENFORCE_TTL_SEC";
+/**
+* Resolve the enforcement TTL (seconds) from an env map.
+* @param env - environment map (defaults to `process.env`)
+* @param key - env var name (defaults to `FUSE_ENFORCE_TTL_SEC`)
+*/
+function resolveTtlSec(env = process.env, key = TTL_ENV_KEY) {
+	return parseEnvInt(env[key], 120);
+}
+/** Human label for a TTL: 120 -> "2min", 240 -> "4min", 90 -> "90s". */
+function ttlLabel(sec) {
+	return sec % 60 === 0 ? `${sec / 60}min` : `${sec}s`;
+}
+//#endregion
+export { ttlLabel as i, TTL_ENV_KEY as n, resolveTtlSec as r, DEFAULT_TTL_SEC as t };

package/dist/{validate-KjZ1X9tH.mjs → validate-Dcjl0LUS.mjs}

@@ -1,10 +1,11 @@
 import { a as resolveMaxLines, c as storeBudget, i as hookBudget } from "./limits-DG5pl-5s.mjs";
-import { l as ttlLabel, t as HOME_DIR } from "./dotenv-BLBkBTww.mjs";
+import { i as ttlLabel } from "./ttl-Dgwg_QAv.mjs";
 import { A as moduleAwarePath, S as isHooksPath, T as isStoresPath, _ as rolloutVerdict, at as maskCommentsOnly, it as maskCommentsAndStrings, nt as nearestManifestDir, ot as DEV_KEYWORDS, rt as projectCaps, x as isComponentsPath, y as declaresInterface } from "./evaluate-CMiIqHeH.mjs";
 import { d as countFrameworkCodeLines, l as PLUGINS_DIR, u as SOLID_REF } from "./home-state-oUGFB4ds.mjs";
 import { r as isDocConsulted, t as formatDocDeny } from "./doc-helpers-CWZegVdR.mjs";
 import { t as routeReferences } from "./router-PKVNBHge.mjs";
-import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-DVML3zfp.mjs";
+import { n as findMarketplacePlugins, r as readPluginMeta, t as resolveSkillPath } from "./skill-path-Cz8WFaGu.mjs";
+import { n as apexPlanTool, r as harnessHomeSegment, t as apexDocName } from "./apex-target-Xc2M32Pl.mjs";
 import { dirname, extname, join, resolve } from "node:path";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
@@ -1446,52 +1447,6 @@ function getExpertAgent(type, pluginsDirOverride) {
 	return "general-purpose";
 }
 //#endregion
-//#region src/policy/apex-target.ts
-/**
-* Harness-target helpers for the APEX context builders. Single source of
-* truth for the home-dir segment / root doc name / plan-tool idiom that
-* differ between Claude Code and Codex (and beyond), so the builders in
-* `claude-md-context.ts`, `apex-task-context.ts`, and `inject-apex.ts` never
-* hardcode `.claude`/`CLAUDE.md`/`TaskCreate` again. Runtime `id` values flow
-* through the pipeline as plain `string` (see `handleHook(id: string, ...)`),
-* so these helpers accept `string` and narrow internally — same idiom as the
-* existing `HOME_DIR[id] ?? ".claude"` precedent in `cartographer/detect.ts`.
-*/
-/**
-* Home-dir segment for a harness target (".claude", ".codex", ...). Falls
-* back to ".claude" for any harness without a {@link HOME_DIR} entry.
-* @param id - Harness id (e.g. "claude-code", "codex").
-* @returns The home-dir segment, e.g. ".claude".
-*/
-function harnessHomeSegment(id) {
-	return HOME_DIR[id] ?? ".claude";
-}
-/**
-* Root instructions doc name for a harness target: "AGENTS.md" for Codex and
-* Kimi Code CLI (both documented conventions), "CLAUDE.md" for every other
-* target (including the default/unknown fallback).
-* @param id - Harness id.
-* @returns The doc file name.
-*/
-function apexDocName(id) {
-	return id === "codex" || id === "kimi" ? "AGENTS.md" : "CLAUDE.md";
-}
-/**
-* Native plan/track tool name for a harness target: Codex's `update_plan`,
-* Kimi Code CLI's `TodoList`, or Claude's `TaskCreate` (default). Covers only
-* the PLAN-step line — other target-specific tool references (`TaskList`,
-* `TaskUpdate`) are resolved via `apexTaskSteps`/`apexAgentSteps` in
-* `apex-target-steps.ts` since their surrounding prose differs structurally,
-* not just by token.
-* @param id - Harness id.
-* @returns The plan-tool name.
-*/
-function apexPlanTool(id) {
-	if (id === "codex") return "update_plan";
-	if (id === "kimi") return "TodoList";
-	return "TaskCreate";
-}
-//#endregion
 //#region src/policy/detect-claude-md-project-type.ts
 /**
 * Detect the project type from the cwd, reproducing the legacy Python logic:
@@ -1907,4 +1862,4 @@ function missingSeoElements(html) {
 	return missing;
 }
 //#endregion
-export { importsTanstackQuery as A, APEX_GATES as B, detectRequiredSkills as C, frameworkSolidGate as D, SKILL_TRIGGERS as E, isExcludedSwiftPath as F, evaluateApex as G, PRE_AUTH_GATES as H, MAX_EXA_RESULTS as I, freshnessGate as K, MAX_TOKENS as L, countStores as M, declaresStore as N, declaresCustomHook as O, isExcludedJsPath as P, capVerbosity as R, parseField as S, usesTailwindUtilities as T, brainstormGate as U, POST_AUTH_GATES as V, docConsultedGate as W, detectClaudeMdProjectType as _, firstHeading as a, scanPlugin as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, buildClaudeMdContext as g, buildApexInstruction as h, firstComment as i, queryCapActive as j, declaresQueryHook as k, PROJECT_INDICATORS as l, DEV_VERBS as m, missingSeoElements as n, parseEnrichment as o, apexAgentSteps as p, solidReadGate as q, descFromText as r, parseEntry as s, isHtmlLike as t, buildApexTaskContext as u, apexDocName as v, skillTriggerGate as w, parseBodyDesc as x, harnessHomeSegment as y, detectCreationIntent as z };
+export { countStores as A, PRE_AUTH_GATES as B, usesTailwindUtilities as C, declaresQueryHook as D, declaresCustomHook as E, MAX_TOKENS as F, solidReadGate as G, docConsultedGate as H, capVerbosity as I, detectCreationIntent as L, isExcludedJsPath as M, isExcludedSwiftPath as N, importsTanstackQuery as O, MAX_EXA_RESULTS as P, APEX_GATES as R, skillTriggerGate as S, frameworkSolidGate as T, evaluateApex as U, brainstormGate as V, freshnessGate as W, detectClaudeMdProjectType as _, firstHeading as a, parseField as b, EXCLUDE_DIRS as c, buildApexTaskInjection as d, loadApexTaskState as f, buildClaudeMdContext as g, buildApexInstruction as h, firstComment as i, declaresStore as j, queryCapActive as k, PROJECT_INDICATORS as l, DEV_VERBS as m, missingSeoElements as n, parseEnrichment as o, apexAgentSteps as p, descFromText as r, parseEntry as s, isHtmlLike as t, buildApexTaskContext as u, scanPlugin as v, SKILL_TRIGGERS as w, detectRequiredSkills as x, parseBodyDesc as y, POST_AUTH_GATES as z };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fusengine/harness",
-	"version": "0.1.92",
+	"version": "0.1.94",
 	"description": "Harness-agnostic toolkit for AI coding agents: runtime harness detection (Claude Code, Codex, Cursor, Cline, Gemini, Aider...), pure policy core (env config, project/framework detection, SOLID/file-size limits, APEX freshness, guard patterns, portable prompts), cache, project memory, ref routing, state/locks, statusline, per-harness adapters (Claude/Cursor/Cline/Gemini) and a cli-mode harness-check binary. Bun-native, with a built dist for Node + bundlers.",
 	"type": "module",
 	"module": "src/index.ts",

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;
+}