@fusengine/harness 0.1.91 → 0.1.93

package/src/policy/prd/index.ts

@@ -0,0 +1,36 @@
+/** Barrel for `src/policy/prd/**` — the public surface Lot B and Lot C import from. */
+export type {
+  PrdAgentEntryCompacted, PrdAgentEntryExpanded, PrdAgentReportFile, PrdAgentSubEntry,
+  PrdCrossCheckViolation, PrdIdentity, PrdOwnershipVerdict, PrdPathKind, PrdRouter,
+  PrdRouterEntry, PrdRouterStatus, PrdSubagentSlice, PrdSubStatus, PrdSubTask, PrdTaskAgentEntry,
+  PrdTaskFile,
+} from "./interfaces/types";
+
+export {
+  classifyPrdPath, isPrdScopedPath, prdAgentReportPath, prdDir, prdDocsPath, prdRouterPath,
+  prdTaskPath,
+} from "./prd-paths";
+
+export {
+  filesOf, isCompacted, parseAgentReportFile, parseRouter, parseTaskFile, subTasksOf,
+  validateTaskFileInvariant, withRouterStatus, withSubTaskValidated,
+} from "./prd-schema";
+
+export {
+  candidateAgentNames, evaluateWriteOwnership, matchesAgentName, resolveOwnerBinding,
+} from "./prd-ownership";
+
+export {
+  crossCheckRouter, crossCheckTask, hasAnyViolations, incompleteSubTasks,
+} from "./prd-crosscheck";
+
+export { canPromoteRouterEntry, compactAgentEntry, compactTaskFile } from "./prd-compact";
+
+export { agentSlice, agentSlices, joinContextResponses, renderAgentSliceMarkdown } from "./prd-context";
+
+export {
+  readAgentReport, readAgentReportSync, readAllTaskFiles, readRouter, readRouterSync,
+  readTaskFile, readTaskFileSync, writeAgentReport, writeRouter, writeTaskFile,
+} from "./prd-io";
+
+export { isPrdEnabled, isPrdFlagSet, prdProjectRoot, routerExistsSync } from "./prd-enabled";

package/src/policy/prd/interfaces/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared shapes for the PRD (task/agent ownership coordination) module. Pure
+ * types only — no runtime code, no fs. Mirrors the JSON contract at
+ * `<root>/<homeSeg>/apex/prd.json` and `<root>/<homeSeg>/apex/prd/**`.
+ *
+ * FROZEN CONTRACT: this file is imported by both Lot B (runtime wiring) and
+ * Lot C (CLI). Do not rename or remove an export without flagging it to the
+ * other lots first.
+ */
+
+/** Lifecycle status of a task in the router (`prd.json`). */
+export type PrdRouterStatus = "assigned" | "in-progress" | "validated";
+
+/** One router entry: which task-PRD file backs a task, and its status. */
+export interface PrdRouterEntry {
+  prd: string;
+  status: PrdRouterStatus;
+  "validated-at"?: string;
+}
+
+/** The router file itself (`prd.json`), keyed by task name. */
+export type PrdRouter = Record<string, PrdRouterEntry>;
+
+/** Lifecycle status of one sub-task inside a task-PRD's agent entry. */
+export type PrdSubStatus = "assigned" | "validated";
+
+/** One sub-task's status inside a task-PRD's (expanded) agent entry. */
+export interface PrdSubTask {
+  status: PrdSubStatus;
+  "validated-at"?: string;
+}
+
+/** Pre-compaction shape of one agent's slice of a task-PRD. */
+export interface PrdAgentEntryExpanded {
+  files: string[];
+  "sub-tasks": Record<string, PrdSubTask>;
+}
+
+/** Post-compaction shape of one agent's slice of a task-PRD (all sub-tasks validated). */
+export interface PrdAgentEntryCompacted {
+  status: "validated";
+  files: string[];
+  "validated-at": string;
+}
+
+/** One agent's slice of a task-PRD, expanded or compacted. */
+export type PrdTaskAgentEntry = PrdAgentEntryExpanded | PrdAgentEntryCompacted;
+
+/** A task-PRD file (`prd/<task>-prd.json`), keyed by agent name. */
+export type PrdTaskFile = Record<string, PrdTaskAgentEntry>;
+
+/** One sub-task's completion report inside an agent's own report file. */
+export interface PrdAgentSubEntry {
+  status: "done";
+  modified: string[];
+  unchanged: string[];
+  "done-at"?: string;
+}
+
+/** An agent's own report file (`prd/agents/<agent>-prd.json`), keyed by task then sub-task. */
+export type PrdAgentReportFile = Record<string, Record<string, PrdAgentSubEntry>>;
+
+/** Resolved identity of the current tool-use, for the ownership check. */
+export interface PrdIdentity {
+  agentId?: string;
+  agentType?: string;
+  /**
+   * true = structurally proven lead (Claude/Codex: no agent_id/agent_type on
+   * the event); false = structurally proven sub-agent; "unknown" = harness
+   * can't tell (Cursor/Kimi — see design doc Risks §1/§2).
+   */
+  lead: boolean | "unknown";
+}
+
+/** PreToolUse ownership verdict for one in-scope PRD write. */
+export type PrdOwnershipVerdict =
+  | { allow: true; bind?: { agentId: string; name: string } }
+  | { allow: false; reason: string }
+  | { allow: "advisory" };
+
+/** One cross-check mismatch between a task-PRD's assignment and an agent's own report. */
+export interface PrdCrossCheckViolation {
+  task: string;
+  agent: string;
+  sub: string;
+  reason: string;
+}
+
+/** One sub-agent's rendered slice of a task-PRD, for the SubagentStart injection. */
+export interface PrdSubagentSlice {
+  task: string;
+  agent: string;
+  subTasks: string[];
+  files: string[];
+}
+
+/** Classification of an in-scope PRD path (`isPrdScopedPath`/`classifyPrdPath`). */
+export type PrdPathKind =
+  | { kind: "router" }
+  | { kind: "task"; task: string }
+  | { kind: "agentReport"; agent: string }
+  | { kind: "docs"; task: string }
+  | { kind: "other" };

package/src/policy/prd/prd-compact.ts

@@ -0,0 +1,28 @@
+/** Collapses fully-validated task-PRD agent entries to their compact shape. Pure — no fs. */
+import { isCompacted, subTasksOf } from "./prd-schema";
+import type { PrdTaskAgentEntry, PrdTaskFile } from "./interfaces/types";
+
+/** Collapses one agent entry to the compacted shape ONLY when every sub-task is `validated`; else returns it unchanged. */
+export function compactAgentEntry(e: PrdTaskAgentEntry, at: string): PrdTaskAgentEntry {
+  if (isCompacted(e)) return e;
+  const subTasks = Object.values(subTasksOf(e));
+  if (subTasks.length === 0 || !subTasks.every((s) => s.status === "validated")) return e;
+  return { status: "validated", files: e.files, "validated-at": at };
+}
+
+/** Compacts every eligible agent entry in a task-PRD; reports which agent names got collapsed. */
+export function compactTaskFile(taskFile: PrdTaskFile, at: string): { file: PrdTaskFile; compacted: string[] } {
+  const compacted: string[] = [];
+  const file: PrdTaskFile = {};
+  for (const [agent, entry] of Object.entries(taskFile)) {
+    const next = compactAgentEntry(entry, at);
+    if (next !== entry) compacted.push(agent);
+    file[agent] = next;
+  }
+  return { file, compacted };
+}
+
+/** True when every agent in the task-PRD is already compacted+validated. */
+export function canPromoteRouterEntry(taskFile: PrdTaskFile): boolean {
+  return Object.values(taskFile).every((entry) => isCompacted(entry));
+}

package/src/policy/prd/prd-context.ts

@@ -0,0 +1,131 @@
+/**
+ * The SubagentStart "slice" text builder: renders only the sub-agent's own
+ * PRD assignment, never the whole task. Pure — no fs.
+ */
+import { candidateAgentNames } from "./prd-ownership";
+import { filesOf, subTasksOf } from "./prd-schema";
+import type { PrdSubagentSlice, PrdTaskFile } from "./interfaces/types";
+
+/**
+ * Builds the slice of `taskFile` owned by each candidate name matching
+ * `agentType` — one entry per candidate. Empty when no candidate matches;
+ * 2+ entries when the match is ambiguous (shared base type, e.g.
+ * `backend-expert`/`backend-expert-2`) so the caller can surface every
+ * possibility instead of silently dropping the assignment.
+ */
+export function agentSlices(taskFile: PrdTaskFile, agentType: string, task: string): PrdSubagentSlice[] {
+  const slices: PrdSubagentSlice[] = [];
+  for (const agent of candidateAgentNames(agentType, taskFile)) {
+    const entry = taskFile[agent];
+    if (entry) slices.push({ task, agent, subTasks: Object.keys(subTasksOf(entry)), files: filesOf(entry) });
+  }
+  return slices;
+}
+
+/**
+ * Builds the one slice of `taskFile` owned by `agentType`, or `null` when no
+ * candidate matches, or the match is ambiguous (2+ candidates — see
+ * {@link agentSlices} to get all of them instead).
+ */
+export function agentSlice(taskFile: PrdTaskFile, agentType: string, task: string): PrdSubagentSlice | null {
+  const slices = agentSlices(taskFile, agentType, task);
+  return slices.length === 1 ? (slices[0] ?? null) : null;
+}
+
+function renderSliceBlock(s: PrdSubagentSlice): string {
+  return [
+    `## PRD assignment — task ${s.task}`,
+    `Your files: ${s.files.join(", ")}`,
+    `Your sub-tasks: ${s.subTasks.join(", ")}`,
+    `Report to prd/agents/${s.agent}-prd.json when done.`,
+  ].join("\n");
+}
+
+/**
+ * Renders one readable markdown block per slice: title, files, sub-tasks,
+ * report path. When 2+ slices share the same `task` (an ambiguous
+ * `agentSlices` result), prefixes that group with an explicit
+ * disambiguation header instead of silently rendering as if unambiguous.
+ */
+export function renderAgentSliceMarkdown(slices: PrdSubagentSlice[]): string {
+  const byTask = new Map<string, PrdSubagentSlice[]>();
+  for (const s of slices) {
+    const group = byTask.get(s.task);
+    if (group) group.push(s); else byTask.set(s.task, [s]);
+  }
+
+  const blocks: string[] = [];
+  for (const group of byTask.values()) {
+    if (group.length > 1) {
+      const names = group.map((s) => s.agent).join(", ");
+      blocks.push(
+        `Several assignments match your agent type. You are ONE of: ${names}. `
+        + "The first report you write binds your name; write only that report.",
+      );
+    }
+    for (const s of group) blocks.push(renderSliceBlock(s));
+  }
+  return blocks.join("\n\n");
+}
+
+/** One rendered context part's extracted text, plus which envelope it came from. Local implementation detail — never exported (not part of the frozen `interfaces/types.ts` contract). */
+interface ExtractedContext {
+  text: string;
+  /** true = cline's native `{contextModification}` shape (see `respond()`'s `"cline"` branch in `runtime/respond.ts`); false = the Claude-family `hookSpecificOutput.additionalContext` envelope every other target (including gemini-cli, which omits `hookEventName` but keeps this same key path) uses. */
+  native: boolean;
+}
+
+/** True for a non-null JSON object `JSON.parse` can produce (excludes arrays/primitives/null). */
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Extracts the text + originating shape from one already-rendered context
+ * response (parse-then-narrow, no unchecked `as` cast on the parsed value —
+ * see {@link isRecord}), or `null` when the input fails to parse, or parses
+ * to neither known shape.
+ */
+function contextTextOf(response: string): ExtractedContext | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(response);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  const hso = parsed.hookSpecificOutput;
+  const claudeText = isRecord(hso) && typeof hso.additionalContext === "string" ? hso.additionalContext : "";
+  if (claudeText) return { text: claudeText, native: false };
+  const clineText = typeof parsed.contextModification === "string" ? parsed.contextModification : "";
+  if (clineText) return { text: clineText, native: true };
+  return null;
+}
+
+/**
+ * Joins two already-rendered `contextResponse(...)`-shaped JSON strings into
+ * one (same fold `dispatch-aipilot.ts`'s `combineContext` already does) —
+ * kept local to avoid a 3rd import edge into that file.
+ *
+ * Recognizes BOTH the Claude-family `hookSpecificOutput.additionalContext`
+ * envelope (claude-code/codex/kimi/cursor/hermes/gemini-cli) and cline's
+ * native `{contextModification}` shape (see `runtime/respond.ts`'s `"cline"`
+ * branch). A cline-shaped part used to parse to `""` here and get silently
+ * dropped by the old `.filter(Boolean)` — exactly how cline's PRD slice never
+ * reached the agent (0-byte `SubagentStart` injection) despite
+ * `prdSubagentContext` building it correctly. When any merged part is
+ * cline-native, the output is re-shaped as `{contextModification}` so
+ * cline's own hook consumer (which never reads `hookSpecificOutput`) can
+ * read it; every other target only ever produces Claude-family parts, so
+ * that branch never triggers for them and their output stays
+ * byte-identical.
+ */
+export function joinContextResponses(...parts: string[]): string {
+  const extracted = parts.map(contextTextOf).filter((e): e is ExtractedContext => e !== null);
+  if (extracted.length === 0) return "";
+  const joined = extracted.map((e) => e.text).join("\n\n");
+  if (extracted.some((e) => e.native)) return JSON.stringify({ contextModification: joined });
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext: joined },
+  });
+}

package/src/policy/prd/prd-crosscheck.ts

@@ -0,0 +1,76 @@
+/**
+ * Cross-checks a task-PRD's declared status against the agents' own reports
+ * (and, for the router, against the task-PRD's own internal consistency).
+ * Pure — no fs.
+ */
+import { isCompacted, subTasksOf } from "./prd-schema";
+import type {
+  PrdAgentReportFile, PrdCrossCheckViolation, PrdRouter, PrdTaskFile,
+} from "./interfaces/types";
+
+/** Mismatches between a task-PRD's `validated` sub-tasks and the agents' own reports. */
+export function crossCheckTask(
+  taskFile: PrdTaskFile,
+  reports: Record<string, PrdAgentReportFile>,
+  task: string,
+): PrdCrossCheckViolation[] {
+  const violations: PrdCrossCheckViolation[] = [];
+  for (const [agent, entry] of Object.entries(taskFile)) {
+    if (isCompacted(entry)) continue;
+    const report = reports[agent];
+    for (const [sub, subTask] of Object.entries(subTasksOf(entry))) {
+      if (subTask.status !== "validated") continue;
+      if (report?.[task]?.[sub]?.status !== "done") {
+        violations.push({ task, agent, sub, reason: "validated without a matching done report" });
+      }
+    }
+  }
+  return violations;
+}
+
+function taskFullyValidated(taskFile: PrdTaskFile): boolean {
+  return Object.values(taskFile).every((entry) => {
+    if (isCompacted(entry)) return true;
+    return Object.values(subTasksOf(entry)).every((sub) => sub.status === "validated");
+  });
+}
+
+/**
+ * Router-level consistency check: a router entry marked `validated` whose
+ * task-PRD is missing/unparseable, or not actually fully validated, is a
+ * violation. Non-`validated` router entries are never checked.
+ */
+export function crossCheckRouter(
+  router: PrdRouter,
+  taskFiles: Record<string, PrdTaskFile | null>,
+): PrdCrossCheckViolation[] {
+  const violations: PrdCrossCheckViolation[] = [];
+  for (const [task, entry] of Object.entries(router)) {
+    if (entry.status !== "validated") continue;
+    const taskFile = taskFiles[task];
+    if (!taskFile) {
+      violations.push({ task, agent: "*", sub: "*", reason: "router marked validated but task-PRD is missing or unparseable" });
+    } else if (!taskFullyValidated(taskFile)) {
+      violations.push({ task, agent: "*", sub: "*", reason: "router marked validated but task-PRD is not fully validated" });
+    }
+  }
+  return violations;
+}
+
+/** Sub-tasks assigned to `agent` in `taskFile` for `task` not `done` in its own report. */
+export function incompleteSubTasks(
+  taskFile: PrdTaskFile,
+  agent: string,
+  task: string,
+  report: PrdAgentReportFile | null,
+): string[] {
+  const entry = taskFile[agent];
+  if (!entry || isCompacted(entry)) return [];
+  const doneSubs = report?.[task] ?? {};
+  return Object.keys(subTasksOf(entry)).filter((sub) => doneSubs[sub]?.status !== "done");
+}
+
+/** True when the router has any `validated`-vs-task-PRD mismatch. */
+export function hasAnyViolations(router: PrdRouter, taskFiles: Record<string, PrdTaskFile | null>): boolean {
+  return crossCheckRouter(router, taskFiles).length > 0;
+}

package/src/policy/prd/prd-enabled.ts

@@ -0,0 +1,39 @@
+/**
+ * The single activation check for the whole PRD module. Everything
+ * downstream short-circuits on `false` here — this is the only place the
+ * module's "totally inert when off" contract lives. The other file in this
+ * module that touches disk (besides `prd-io.ts`).
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { harnessHomeSegment } from "../apex-target";
+import { prdRouterPath } from "./prd-paths";
+
+/** True only when `FUSE_PRD` is the exact string `"1"` — no truthy-string leniency. */
+export function isPrdFlagSet(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.FUSE_PRD === "1";
+}
+
+/** `CLAUDE_PROJECT_DIR` then `CURSOR_PROJECT_DIR` (first absolute value wins), else `cwd`. */
+export function prdProjectRoot(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
+  for (const candidate of [env.CLAUDE_PROJECT_DIR, env.CURSOR_PROJECT_DIR]) {
+    if (candidate !== undefined && isAbsolute(candidate)) return candidate;
+  }
+  return cwd;
+}
+
+/** True when the router file exists on disk. */
+export function routerExistsSync(root: string, homeSeg: string): boolean {
+  return existsSync(prdRouterPath(root, homeSeg));
+}
+
+/**
+ * Activation = `FUSE_PRD=1` AND the router is present. Short-circuits on the
+ * env check first, so a disabled module never touches disk.
+ */
+export function isPrdEnabled(cwd: string, id: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  if (!isPrdFlagSet(env)) return false;
+  const root = prdProjectRoot(cwd, env);
+  const homeSeg = harnessHomeSegment(id);
+  return routerExistsSync(root, homeSeg);
+}

package/src/policy/prd/prd-io.ts

@@ -0,0 +1,89 @@
+/**
+ * Thin fail-closed wrappers over `util/json-io.ts` + the `prd-schema.ts`
+ * parsers. Both async (CLI, PostToolUse) and sync (SubagentStart/Stop, which
+ * must not float async work) variants. The only two files in this module
+ * that touch disk (besides `prd-enabled.ts`).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { readJsonFile, writeJsonFile } from "../../util/json-io";
+import { prdAgentReportPath, prdRouterPath, prdTaskPath } from "./prd-paths";
+import { parseAgentReportFile, parseRouter, parseTaskFile } from "./prd-schema";
+import type { PrdAgentReportFile, PrdRouter, PrdTaskFile } from "./interfaces/types";
+
+function readJsonSync(path: string): unknown {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the router file; `null` when missing or malformed. */
+export async function readRouter(root: string, homeSeg: string): Promise<PrdRouter | null> {
+  const raw = await readJsonFile<unknown>(prdRouterPath(root, homeSeg));
+  return raw === null ? null : parseRouter(raw);
+}
+
+/** Sync twin of {@link readRouter}, for SubagentStart/Stop call sites. */
+export function readRouterSync(root: string, homeSeg: string): PrdRouter | null {
+  const raw = readJsonSync(prdRouterPath(root, homeSeg));
+  return raw === null ? null : parseRouter(raw);
+}
+
+/** Reads a task-PRD file; `null` when missing or malformed. */
+export async function readTaskFile(root: string, homeSeg: string, relPrd: string): Promise<PrdTaskFile | null> {
+  const raw = await readJsonFile<unknown>(prdTaskPath(root, homeSeg, relPrd));
+  return raw === null ? null : parseTaskFile(raw);
+}
+
+/** Sync twin of {@link readTaskFile}. */
+export function readTaskFileSync(root: string, homeSeg: string, relPrd: string): PrdTaskFile | null {
+  const raw = readJsonSync(prdTaskPath(root, homeSeg, relPrd));
+  return raw === null ? null : parseTaskFile(raw);
+}
+
+/** Reads every task-PRD file named in `router`, keyed by task name (`null` per unreadable/malformed entry). */
+export async function readAllTaskFiles(
+  root: string,
+  homeSeg: string,
+  router: PrdRouter,
+): Promise<Record<string, PrdTaskFile | null>> {
+  const out: Record<string, PrdTaskFile | null> = {};
+  for (const [task, entry] of Object.entries(router)) {
+    out[task] = await readTaskFile(root, homeSeg, entry.prd);
+  }
+  return out;
+}
+
+/** Reads an agent's own report file; `null` when missing or malformed. */
+export async function readAgentReport(root: string, homeSeg: string, agent: string): Promise<PrdAgentReportFile | null> {
+  const raw = await readJsonFile<unknown>(prdAgentReportPath(root, homeSeg, agent));
+  return raw === null ? null : parseAgentReportFile(raw);
+}
+
+/** Sync twin of {@link readAgentReport}. */
+export function readAgentReportSync(root: string, homeSeg: string, agent: string): PrdAgentReportFile | null {
+  const raw = readJsonSync(prdAgentReportPath(root, homeSeg, agent));
+  return raw === null ? null : parseAgentReportFile(raw);
+}
+
+/** Atomically writes the router file. */
+export async function writeRouter(root: string, homeSeg: string, router: PrdRouter): Promise<void> {
+  await writeJsonFile(prdRouterPath(root, homeSeg), router);
+}
+
+/** Atomically writes a task-PRD file. */
+export async function writeTaskFile(root: string, homeSeg: string, relPrd: string, file: PrdTaskFile): Promise<void> {
+  await writeJsonFile(prdTaskPath(root, homeSeg, relPrd), file);
+}
+
+/** Atomically writes an agent's own report file. */
+export async function writeAgentReport(
+  root: string,
+  homeSeg: string,
+  agent: string,
+  file: PrdAgentReportFile,
+): Promise<void> {
+  await writeJsonFile(prdAgentReportPath(root, homeSeg, agent), file);
+}

package/src/policy/prd/prd-ownership.ts

@@ -0,0 +1,99 @@
+/**
+ * The PreToolUse ownership decision. Everything it needs is passed in — no
+ * I/O. Pure functions over already-loaded router/task-PRD/bindings data.
+ */
+import type { PrdIdentity, PrdOwnershipVerdict, PrdPathKind, PrdTaskFile } from "./interfaces/types";
+
+/** True when `name === agentType`, or `"<agentType>-<n>"` with `n >= 2`. */
+export function matchesAgentName(name: string, agentType: string): boolean {
+  if (name === agentType) return true;
+  if (!name.startsWith(agentType)) return false;
+  const suffix = name.slice(agentType.length);
+  if (!suffix.startsWith("-")) return false;
+  const numPart = suffix.slice(1);
+  return /^\d+$/.test(numPart) && Number(numPart) >= 2;
+}
+
+/** Agent names in `taskFile` whose name matches `agentType` (base or `-n` suffixed). */
+export function candidateAgentNames(agentType: string, taskFile: PrdTaskFile): string[] {
+  return Object.keys(taskFile).filter((name) => matchesAgentName(name, agentType));
+}
+
+/**
+ * agentId -> bound name resolution. `bindings` is the journal's `prdOwners`
+ * map (agentId -> name), read-only here. Returns the candidate already
+ * bound to this agentId, or the SOLE still-unbound candidate (free to bind
+ * now), or `null` (ambiguous: >1 free candidate, or 0 candidates at all).
+ */
+export function resolveOwnerBinding(
+  candidates: string[],
+  agentId: string,
+  bindings: Record<string, string>,
+): { name: string; alreadyBound: boolean } | null {
+  const boundToMe = bindings[agentId];
+  if (boundToMe !== undefined && candidates.includes(boundToMe)) {
+    return { name: boundToMe, alreadyBound: true };
+  }
+  const takenByOthers = new Set(
+    Object.entries(bindings).filter(([id]) => id !== agentId).map(([, name]) => name),
+  );
+  const free = candidates.filter((c) => !takenByOthers.has(c));
+  if (free.length !== 1) return null;
+  const [name] = free;
+  return name === undefined ? null : { name, alreadyBound: false };
+}
+
+const COORDINATOR_ONLY_LABEL: Record<"router" | "task" | "docs", string> = {
+  router: "router",
+  task: "task PRD",
+  docs: "docs",
+};
+
+function evaluateCoordinatorOnly(kind: "router" | "task" | "docs", identity: PrdIdentity): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: true };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: `${COORDINATOR_ONLY_LABEL[kind]} is coordinator-only` };
+}
+
+function evaluateAgentReport(
+  agent: string,
+  identity: PrdIdentity,
+  taskFile: PrdTaskFile | null,
+  bindings: Record<string, string>,
+): PrdOwnershipVerdict {
+  if (identity.lead === true) return { allow: false, reason: "agent report is not the coordinator's to write" };
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  if (identity.agentType === undefined || identity.agentId === undefined) {
+    return { allow: false, reason: "unidentifiable agent_type — cannot verify ownership" };
+  }
+  const candidates = candidateAgentNames(identity.agentType, taskFile ?? {});
+  const resolved = resolveOwnerBinding(candidates, identity.agentId, bindings);
+  if (!resolved || resolved.name !== agent) {
+    return { allow: false, reason: "name doesn't match your agent_type, or already bound to another agent" };
+  }
+  return resolved.alreadyBound
+    ? { allow: true }
+    : { allow: true, bind: { agentId: identity.agentId, name: resolved.name } };
+}
+
+/**
+ * Top-level PreToolUse verdict for ONE file path already known to be in
+ * scope (`classifyPrdPath` returned non-`"other"`/non-`null` upstream).
+ */
+export function evaluateWriteOwnership(input: {
+  kind: PrdPathKind;
+  identity: PrdIdentity;
+  taskFile: PrdTaskFile | null;
+  bindings: Record<string, string>;
+}): PrdOwnershipVerdict {
+  const { kind, identity, taskFile, bindings } = input;
+
+  if (kind.kind === "router" || kind.kind === "task" || kind.kind === "docs") {
+    return evaluateCoordinatorOnly(kind.kind, identity);
+  }
+  if (kind.kind === "agentReport") {
+    return evaluateAgentReport(kind.agent, identity, taskFile, bindings);
+  }
+  if (identity.lead === "unknown") return { allow: "advisory" };
+  return { allow: false, reason: "not a recognized PRD file" };
+}