@staix/agent-hub 0.12.35 → 0.12.37

package/src/hub/envelope.ts

@@ -14,7 +14,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; backlog?: number[]; supervision?: boolean; supervisionKey?: string; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;

package/src/hub/host-executable.ts

@@ -2,7 +2,7 @@ import { isAbsolute, relative } from "node:path";
 import { realPath } from "./project.ts";
 
 /** A repo-writable PATH shim is not a host-owned authenticated capability. No caller-selected binary. */
-export function hostExecutable(name: "gh" | "container" | "git", projectDir: string, path = process.env.PATH ?? ""): string {
+export function hostExecutable(name: "gh" | "container" | "git" | "dot", projectDir: string, path = process.env.PATH ?? ""): string {
   const found = Bun.which(name, { PATH: path });
   if (!found || !isAbsolute(found)) throw new Error(`${name} unavailable`);
   const target = realPath(found), inside = relative(realPath(projectDir), target);

package/src/hub/hub-tools.ts

@@ -17,6 +17,10 @@ const refs = {
   additionalProperties: false,
 } as const;
 const list = (description: string) => ({ type: "array", items: str, description }) as const;
+const costPlanProperties = {
+  review: { type: "object", properties: { scope: { type: "string", enum: ["none", "delta", "full"] }, reviewers: { type: "integer", minimum: 0, maximum: 8 } }, required: ["scope", "reviewers"], additionalProperties: false },
+  ci: { type: "string", enum: ["focused", "full", "reuse"] },
+} as const;
 const plan = {
   type: "object",
   description: "what you will change, before you start. Owners of open tasks on the same files or symbols see it, and get a notice when your task is done.",
@@ -57,6 +61,11 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_backlog_pull", "Reserve a WIP slot and pull ready unpinned backlog work into To Do at its current revision. Preserves person order/reservations and frozen scope; pending unowned work can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "reason"]),
   tool("hub_backlog_split", "Split unstarted backlog work into two to eight staged parts. The original card retains integration/acceptance and depends on the children. Use after for existing prerequisite ids and afterParts for earlier zero-based part indexes. Latest unused unchanged children can be undone with hub_backlog_undo.", { id, revision: { type: "integer", minimum: 0 }, reason: { type: "string", minLength: 1, maxLength: 1000 }, parts: { type: "array", minItems: 2, maxItems: 8, items: { type: "object", properties: { title: { type: "string", minLength: 1, maxLength: 300 }, detail: { type: "string", maxLength: 8000 }, class: str, refs, plan, after: { type: "array", maxItems: 64, uniqueItems: true, items: { type: "integer", minimum: 1 } }, afterParts: { type: "array", maxItems: 8, uniqueItems: true, items: { type: "integer", minimum: 0 } } }, required: ["title"], additionalProperties: false } } }, ["id", "revision", "reason", "parts"]),
   tool("hub_backlog_undo", "Undo your latest planning change at its current revision. Refuses intervening changes and another actor's edit.", { id, revision: { type: "integer", minimum: 1 } }, ["id", "revision"]),
+  tool("hub_release_new", "Create a future release planning row. Planner/person only; no activation, publish or release authorization.", { name: { type: "string", minLength: 1, maxLength: 64 }, goal: { type: "string", minLength: 1, maxLength: 1000 }, order: { type: "integer", minimum: 0 } }, ["name", "goal", "order"]),
+  tool("hub_release_report", "Read a planned release's task readiness and recorded metrics. Planner/person only. A due date never waives unfinished scope.", { id }, ["id"]),
+  tool("hub_release_assign", "Assign or move only a task's release, retaining its execution state and owner. Planner/person only; requires a reason and current planning revision. Frozen scope refuses.", { id, revision: { type: "integer", minimum: 0 }, release: { type: ["integer", "null"], minimum: 1 }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, ["id", "revision", "release", "reason"]),
+  tool("hub_release_configure", "Configure/activate a release train or record a hotfix cause. Planner/person only. At most one train is active/frozen; planning rows are future trains.", { id, revision: { type: "integer", minimum: 0 }, state: { type: "string", enum: ["active"] }, cut: { type: "integer", minimum: 1 }, hotfix: { type: "object", properties: { cause: { type: "string", enum: ["loss", "security_privacy", "upgrade_start_blocked", "core_flow_no_workaround"] }, reason: { type: "string", minLength: 1, maxLength: 1000 } }, required: ["cause", "reason"], additionalProperties: false } }, ["id", "revision"]),
+  tool("hub_release_cut", "Freeze an active release's approved scope after host resource admission and fresh peer quota checks. Unknown evidence defers; no publish, tag, upgrade or authorization.", { id, revision: { type: "integer", minimum: 0 } }, ["id", "revision"]),
   tool("hub_release_list", "Read public release scope and planned/actual dates for phased planning. Configured planners only.", {}),
 
   tool("hub_task_propose", "Put a piece of work on the shared task board. The hub assigns an owner by class (routing.toml) unless you name one. Classes: plan, implement, bulk_edit, test, review, summarize, triage. Name the class when you know it; without one the hub tries to pick it. Name yourself as owner to claim work nobody assigned you: it starts in progress. Put the paths the work touches in refs, and when you claim work, a plan; the hub says when they overlap another open task.", { title: str, class: { type: "string", enum: ["plan", "implement", "bulk_edit", "test", "review", "summarize", "triage"] }, detail: str, role: { type: "string", description: "catalog role id for this task class; guidance only, no routing or authority change" }, refs, plan, owner: { type: "string", description: "peer id; yours to claim the work, omit to let the hub route it. With after, the owner is reserved: offered the task first once it is ready" }, after: { type: "array", items: { type: "integer" }, description: "ids of tasks that must be approved first; until then this one waits, offered to nobody, and cannot be claimed" }, backlog: { type: "boolean", description: "stage unoffered work; owner is only a reservation, even when naming yourself" }, urgent: { type: "boolean", description: "hand it over even when its owner is paused for quota only briefly" }, goal: { type: "string", description: "id of this project's long-term task (ahub goal list) the work is part of" } }, ["title"]),
@@ -66,7 +75,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs; no duplicate hub_send chat is needed. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_sdlc_record", "Record artifact ids or claimed local checks on your task. This grants no authority or external-check evidence. Only its owner/reviewer or the person may record; only its reviewer/person may name a reviewed head or phase checklist. Phase evidence refs are content hashes, not external verification.", { id, receipt: { type: "object", properties: { stage: { type: "string", enum: ["spec", "plan", "implement", "review", "verify", "merge", "release"] }, repo: str, issue: id, pr: id, localHead: str, localResult: { type: "string", enum: ["passed", "failed", "unknown"] }, reviewedHead: str, phase: { type: "object", properties: { id: str, head: str, tasks: { type: "array", maxItems: 64, items: { type: "object", properties: { id, after: { type: "array", maxItems: 16, items: id } }, required: ["id", "after"], additionalProperties: false } }, criteria: { type: "array", maxItems: 32, items: { type: "object", properties: { id: str, required: { type: "boolean" }, result: { type: "string", enum: ["verified", "failed", "unverified"] }, refs: { type: "array", maxItems: 8, items: str } }, required: ["id", "required", "result", "refs"], additionalProperties: false } } }, required: ["id", "tasks", "criteria"], additionalProperties: false } }, additionalProperties: false } }, ["id", "receipt"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
-  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
+  tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. The verdict notifies the task owner; no duplicate hub_send chat is needed. Consecutive changes_requested verdicts (three by default, `tasks.escalate_after`) move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" }, coverage: { type: "object", description: "the review brief's reviewable paths you read (reviewed) and any you did not (skipped, each with a reason); in enforce an approval must account for every one", properties: { reviewed: { type: "array", items: str }, skipped: { type: "array", items: { type: "object", properties: { path: str, reason: str }, required: ["path", "reason"] } } } } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
   tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
@@ -75,6 +84,13 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
 ];
 
+export const PLANNER_REVIEW_TOOLS: HubTool[] = [
+  tool("hub_planner_groom", "Read a bounded planner grooming digest of dependencies, repository-scoped overlaps, WIP and blockers. No board change; unavailable evidence stays unknown.", {}),
+  tool("hub_plan_review", "Record a planner review against the task planning revision and host-read issue edit time. Configured planner or person only; never accepts caller issue timestamps.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 }, ...costPlanProperties }, ["id", "revision", "reason"]),
+  tool("hub_sdlc_costs", "Read bounded review and CI cost metrics for linked merged PRs. Planner/person only; metadata only, no board writes. S7 owns automatic band proposals.", { repo: str }),
+  tool("hub_backlog_return_untouched", "Return accepted but untouched work to the backlog with its history and planning retained. Refuses execution/branch/commit evidence; planner or person only.", { id, revision: { type: "integer", minimum: 0 }, reason: { ...str, maxLength: 1000 } }, ["id", "revision", "reason"]),
+];
+TASK_TOOLS.push(...PLANNER_REVIEW_TOOLS);
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
 
 /** Separately published: serving a schema grants no authority, only the daemon's explicit role does. */
@@ -134,6 +150,14 @@ export function profileTaskTools(profile: ProfileSelection = "dev", stages?: rea
       const selectedPlan = { ...plan, properties: Object.fromEntries(data.plan_keys.map(key => [key, plan.properties[key as keyof typeof plan.properties] ?? list(key === "sections" ? "document heading anchors, such as report.md#methods" : key === "sources" ? "citation ids, DOI or source URL ids" : "short claim ids to verify")])) };
       properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: selectedPlan } } };
     }
+    if (criteria && properties.plan) {
+      const current = properties.plan as { properties: Record<string, unknown> };
+      properties.plan = { ...current, properties: { ...current.properties, ...costPlanProperties } };
+    }
+    if (criteria && tool.name === "hub_backlog_split") {
+      const parts = properties.parts as { items: { properties: { plan: { properties: Record<string, unknown> } } } };
+      properties.parts = { ...parts, items: { ...parts.items, properties: { ...parts.items.properties, plan: { ...parts.items.properties.plan, properties: { ...parts.items.properties.plan.properties, ...costPlanProperties } } } } };
+    }
     return { ...tool, ...(customProfile && tool.name === "hub_task_propose" ? { description: tool.description + ` Selected profile ${data.name}: ${Object.keys(data.classes).join(", ")}. Routing uses their existing base classes.` } : {}), inputSchema: { ...tool.inputSchema, properties } };
   });
 }

package/src/hub/instances.ts

@@ -7,6 +7,7 @@ export interface InstanceConfig {
   roles?: string[];
   start_mode?: StartForm;
   permission_mode?: PermissionMode;
+  review_mode?: "fresh";
   worktree?: string;
 }
 export type InstancesConfig = Readonly<Record<string, InstanceConfig>>;
@@ -48,14 +49,36 @@ export function validateInstances(raw: unknown): InstancesConfig {
   for (const [id, descriptor] of Object.entries(declarations)) {
     if (!PEER_ID.test(id) || RESERVED.has(id) || definitionOf(id)) return fail("instances", "ids must be nonreserved extra instance ids, not builtin ids");
     const path = `instances.${id}`, entry = fields(descriptor.value, path);
-    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree"].includes(key))) return fail(path, "unsupported field");
+    if (Object.keys(entry).some(key => !["kind", "roles", "start_mode", "permission_mode", "worktree", "review_mode"].includes(key))) return fail(path, "unsupported field");
     const kind: unknown = entry.kind?.value;
     if (typeof kind !== "string") return fail(`${path}.kind`, "must name a native kind");
     const definition = definitionOf(kind), prefix = `${kind}-`;
     if (!definition) return fail(`${path}.kind`, "unknown native kind");
     if (!id.startsWith(prefix) || !/^[a-z0-9][a-z0-9-]*$/.test(id.slice(prefix.length))) return fail(path, "id must be <kind>-<name>");
-    if (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp)) return fail(`${path}.kind`, "unsupported in I2; a headless factory with env or ACP-session identity is required, not channel-only or project-file identity");
-    const value: InstanceConfig = { kind };
+    const declaredRoles = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
+    const reviewer = (definition.reviewerVariant ?? definition).reviewer;
+    const reviewerOnly = entry.start_mode?.value === "headless" && declaredRoles.length === 1 && declaredRoles[0] === "reviewer";
+    if (entry.review_mode && (entry.review_mode.value !== "fresh" || !reviewerOnly || !reviewer)) return fail(`${path}.review_mode`, "fresh requires reviewer-only roles, headless mode and a declared fresh-review capability");
+    const freshReviewer = reviewerOnly && !!reviewer && (reviewer.declaration === "automatic" || entry.review_mode?.value === "fresh");
+    if (definition.routing?.reviewOnly && !freshReviewer) return fail(path, "a review-only kind requires headless roles exactly [\"reviewer\"]");
+    if (freshReviewer && entry.worktree) return fail(`${path}.worktree`, "a fresh reviewer reads the project checkout: worktree is not supported");
+    if (freshReviewer && entry.permission_mode) return fail(`${path}.permission_mode`, "a fresh reviewer has a fixed read-only policy");
+    // #450 I3: a channel-plugin kind (Claude) runs only in the person's terminal, so it reviews or plans and never owns writes.
+    const channel = definition.identity.mcp === "channel-plugin";
+    const unavailableReviewer = freshReviewer && !!(definition.reviewerVariant ?? definition).reviewer?.unavailable;
+    if (!channel && !unavailableReviewer && (!definition.start.create || !definition.start.forms.includes("headless") || !["env", "acp-session"].includes(definition.identity.mcp))) return fail(`${path}.kind`, "unsupported; a headless factory with env or ACP-session identity, or a channel-plugin kind, is required, not project-file identity");
+    if (channel) {
+      const declared = entry.roles ? roles(entry.roles.value, `${path}.roles`) : [];
+      // #223: a headless one is the kind's reviewer variant, one fresh hub-run session per review request.
+      if (entry.start_mode && definition.reviewerVariant) {
+        if (entry.worktree) return fail(path, "a headless reviewer reads the project checkout: worktree is not supported");
+        if (declared.length !== 1 || declared[0] !== "reviewer") return fail(`${path}.roles`, "a headless channel-kind instance is a reviewer: roles must be exactly [\"reviewer\"]");
+      } else {
+        if (entry.start_mode || entry.worktree) return fail(path, "a channel instance starts only from the person's terminal (ahub <kind> --as <id>): start_mode and worktree are not supported; a headless reviewer declares roles [\"reviewer\"] and start_mode \"headless\"");
+        if (!declared.length || declared.some(role => role !== "reviewer" && role !== "planner")) return fail(`${path}.roles`, "a channel instance must declare its roles: reviewer and/or planner");
+      }
+    }
+    const value: InstanceConfig = { kind, ...(entry.review_mode ? { review_mode: "fresh" as const } : {}) };
     if (entry.roles) { value.roles = roles(entry.roles.value, `${path}.roles`); Object.freeze(value.roles); }
     if (entry.start_mode) {
       if (entry.start_mode.value !== "headless") return fail(`${path}.start_mode`, "I2 extra instances require headless mode");
@@ -80,13 +103,14 @@ export function instanceCatalog(declarations?: InstancesConfig): readonly Instan
   const instances = validateInstances(declarations);
   return Object.freeze([
     ...ADAPTERS.map(definition => Object.freeze({ id: definition.kind, kind: definition.kind, definition })),
-    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(config.kind)!, config })),
+    ...Object.entries(instances).map(([id, config]) => Object.freeze({ id, kind: config.kind, definition: definitionOf(id, instances)!, config })),
   ]);
 }
 export function instancePeerIds(declarations?: InstancesConfig): string[] { return instanceCatalog(declarations).map(entry => entry.id); }
 export function instanceDefaultRoles(declarations?: InstancesConfig, includeOptional = true): Record<string, string[]> {
   const result = defaultPeerRoles(includeOptional);
-  for (const [id, config] of Object.entries(validateInstances(declarations))) result[id] = [...(config.roles ?? definitionOf(config.kind)!.roles)];
+  const instances = validateInstances(declarations);
+  for (const [id, config] of Object.entries(instances)) result[id] = [...(config.roles ?? definitionOf(id, instances)!.roles)];
   return result;
 }
 

package/src/hub/memory-profile.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import {
-  CandidateStore, MemoryStore, realPath, memoryHome, resolveProfile,
+  CandidateStore, MemoryStore, realPath, memoryHome, memoryProjectKey, openShardStore, readShardedSelection, resolveAlias, resolveProfile, resolveShardProfile,
   type BoundProfile, type ProfileInput, type StoreOptions,
 } from "@staix/agent-mem";
 import packageJson from "../../package.json";
@@ -39,6 +39,14 @@ function assertLoadedAgentMem(): void {
 }
 export const MEMORY_PROFILE_UNAVAILABLE = "memory profile unavailable; inspect the selector and generation state, run ahub memory profile-check; use amem migrate --deactivate only to stop using the selected generation";
 const UNAVAILABLE = MEMORY_PROFILE_UNAVAILABLE;
+/** agent-mem#15 T2: a split marker that is not active (captured, malformed) is never read as an empty or legacy store. */
+export const MEMORY_SPLIT_INCOMPLETE = "memory home has a curated split that is not active; finish it with amem migrate --shards --resume, then restart the hub";
+/** Hub memory options: the project key selects this project's shard once the home is split. */
+/**
+ * Hub memory options. `project` is the bound (alias-resolved) key; `projectKey`, when given, is the raw key it came
+ * from, and the entry fence latches the binding unavailable once the alias log maps it elsewhere.
+ */
+export type ProfileMemoryOptions = Omit<StoreOptions, "memoryDir"> & { project?: string; projectKey?: string };
 
 /** No handle was opened; distinct from an unavailable, still-bound handle. */
 export interface UnboundMemoryProfileReceipt {
@@ -70,7 +78,25 @@ function canonicalHome(path: string): string {
 }
 function sameProfile(a: BoundProfile, b: BoundProfile): boolean {
   return a.home === b.home && a.dir === b.dir && a.kind === b.kind
-    && a.generation === b.generation && a.selectorRevision === b.selectorRevision;
+    && a.generation === b.generation && a.selectorRevision === b.selectorRevision
+    && !!a.sharded === !!b.sharded && a.shardKey === b.shardKey && !!a.shardUser === !!b.shardUser;
+}
+// lstat, not exists: a dangling or unreadable marker is still a marker and must fail closed.
+const splitMarked = (home: string) => lstatSync(join(home, "shards.json"), { throwIfNoEntry: false }) !== undefined;
+/** Refuse an inactive split before any shard read, so the remedy names resume rather than the generic profile check. */
+function assertActiveSplit(home: string): void {
+  try { readShardedSelection(home); } catch { throw new Error(MEMORY_SPLIT_INCOMPLETE); }
+}
+/**
+ * The one profile a binding may hold: this project's shard on a split home, the selected profile otherwise.
+ * ponytail: the entry fence re-checks the project shard only; the user overlay shares its selection and selector
+ * revision, so its own seal or machine drift goes unchecked. Add resolveShardProfile(home, { user: true }) if needed.
+ */
+function currentProfile(home: string, project: string | undefined): BoundProfile {
+  if (!splitMarked(home)) return resolveProfile(home);
+  assertActiveSplit(home);
+  if (!project) throw new Error(UNAVAILABLE);
+  return resolveShardProfile(home, { project });
 }
 function homeFor(opts: Pick<StoreOptions, "home">): string {
   return canonicalHome(opts.home === undefined ? memoryHome() : join(canonicalHome(opts.home), "memory"));
@@ -83,6 +109,14 @@ function receipt(profile: BoundProfile, state: MemoryProfileReceipt["state"], sk
   };
 }
 
+/**
+ * The project key agent-mem's own CLI binds: memoryProjectKey(cwd) through the person-reviewed alias log of the
+ * canonical memory home. The daemon and `ahub memory`/`ahub goal` use it so both open the same shard and rows.
+ */
+export function memoryProjectFor(cwd: string, opts: Pick<StoreOptions, "home"> = {}): string {
+  return resolveAlias(homeFor(opts), memoryProjectKey(cwd));
+}
+
 /** Inspect selection without constructing a store, index, or candidate sidecar. */
 export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
   assertLoadedAgentMem();
@@ -95,14 +129,20 @@ export class MemoryProfileBinding {
   readonly explicitProfile: ProfileInput;
   private readonly options: Pick<StoreOptions, "home">;
   private readonly directMemoryDir: string | undefined;
+  /** The shard key on a split home; unused on an unsplit one. */
+  private readonly project: string | undefined;
+  /** The raw key `project` was resolved from; an alias added later must not leave writes on the old key. */
+  private readonly projectKey: string | undefined;
   private unavailable = false;
 
-  constructor(opts: StoreOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
+  constructor(opts: ProfileMemoryOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
     assertLoadedAgentMem();
     this.options = { home: opts.home };
     this.directMemoryDir = directMemoryDir;
+    this.project = opts.project;
+    this.projectKey = opts.projectKey;
     this.home = directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(directMemoryDir);
-    this.profile = Object.freeze({ ...resolveProfile(this.home) });
+    this.profile = Object.freeze({ ...currentProfile(this.home, this.project) });
     this.explicitProfile = this.profile.kind === "shared-v1" ? "shared-v1" : Object.freeze({ generation: this.profile.generation! });
   }
 
@@ -110,8 +150,9 @@ export class MemoryProfileBinding {
     if (this.unavailable) throw new Error(UNAVAILABLE);
     try {
       const currentHome = this.directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(this.directMemoryDir);
-      const current = resolveProfile(currentHome);
+      const current = currentProfile(currentHome, this.project);
       if (currentHome !== this.home || !sameProfile(current, this.profile)) throw new Error(UNAVAILABLE);
+      if (this.projectKey !== undefined && resolveAlias(currentHome, this.projectKey) !== this.project) throw new Error(UNAVAILABLE);
     } catch {
       this.invalidate();
       throw new Error(UNAVAILABLE);
@@ -149,12 +190,27 @@ export class MemoryProfileBinding {
   }
 }
 
-export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neutralReason: string) => void): {
+export function openProfileMemory(opts: ProfileMemoryOptions = {}, onUnavailable?: (neutralReason: string) => void): {
   store: MemoryStore; binding: MemoryProfileBinding;
 } {
-  const binding = new MemoryProfileBinding(opts, onUnavailable);
-  binding.assertCurrent();
-  const raw = new MemoryStore({ ...opts, profile: binding.explicitProfile });
+  const { project, ...storeOptions } = opts;
+  const home = homeFor(opts);
+  let raw: MemoryStore, binding: MemoryProfileBinding;
+  if (splitMarked(home)) {
+    // agent-mem#15 T2: a plain MemoryStore refuses a split home. The shard store opens this project's shard (created on
+    // first use) with the user shard as its overlay; the binding is resolved after it, since a new shard has no seal yet.
+    assertActiveSplit(home);
+    if (!project) throw new Error(UNAVAILABLE);
+    // The canonical memory directory the binding resolves: a lexical home (a symlinked AGENTHUB_HOME or memory dir)
+    // would give the shard a different profile.home and dir than the binding compares against.
+    raw = openShardStore({ ...storeOptions, home: undefined, memoryDir: home, project });
+    try { binding = new MemoryProfileBinding(opts, onUnavailable); }
+    catch (error) { raw.close(); throw error; }
+  } else {
+    binding = new MemoryProfileBinding(opts, onUnavailable);
+    binding.assertCurrent();
+    raw = new MemoryStore({ ...storeOptions, profile: binding.explicitProfile });
+  }
   try {
     binding.assertCurrent();
     if (!sameProfile(raw.profile, binding.profile)) throw new Error(UNAVAILABLE);
@@ -172,7 +228,7 @@ export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neut
 export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void): {
   store: MemoryStore; binding: MemoryProfileBinding;
 } {
-  const binding = new MemoryProfileBinding({}, onUnavailable, store.profile.home);
+  const binding = new MemoryProfileBinding({ project: store.profile.shardKey }, onUnavailable, store.profile.home);
   binding.assertCurrent();
   if (!sameProfile(store.profile, binding.profile)) throw new Error(UNAVAILABLE);
   return { store, binding };

package/src/hub/planning.ts

@@ -1,3 +1,4 @@
+import type { ReleaseTrainData } from "./sdlc-release.ts";
 import type { Task } from "./board.ts";
 
 export const BACKLOG_SPLIT_SCREEN_TIMEOUT_MS = 8000;
@@ -28,6 +29,7 @@ export function planningWipLimits(input: unknown): Record<string, number> {
 export const RELEASE_STATES = ["planning", "active", "frozen", "shipped", "dropped"] as const;
 export type ReleaseState = (typeof RELEASE_STATES)[number];
 export interface Release {
+  train?: ReleaseTrainData;
   id: number; name: string; goal: string; order: number; state: ReleaseState;
   plannedStart: number | null; cut: number | null; ship: number | null;
   activatedAt: number | null; frozenAt: number | null; shippedAt: number | null;

package/src/hub/release-admission.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+import { hubGitSync } from "./git.ts";
+import { hostExecutable } from "./host-executable.ts";
+import { childEnv, stopOwnedProcess } from "./child-process.ts";
+import { detectTooling } from "./tooling.ts";
+
+export interface ReleaseHostAdmission { admitted: boolean; reason?: string; current?: () => boolean; close?: () => Promise<void> }
+const READY = "AHUB_RELEASE_SLOT_READY\n";
+const HOLD = 'process.stdout.write("AHUB_RELEASE_SLOT_READY\\n");process.stdin.resume();process.stdin.on("end",()=>process.exit(0));';
+/** Hold the installed controller's repository lease through the synchronous scope freeze. No caller command. */
+export function readReleaseHostAdmission(cwd: string): Promise<ReleaseHostAdmission> {
+  const common = hubGitSync(["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd, encoding: "utf8", timeout: 1000, maxBuffer: 4096 });
+  const directory = common.stdout?.trim();
+  if (common.status !== 0 || !directory) return Promise.resolve({ admitted: false, reason: "repository resource identity unavailable" });
+  const locked = () => existsSync(join(directory, "ahub-heavy.lock"));
+  if (locked()) return Promise.resolve({ admitted: false, reason: "repository heavy-job slot held" });
+  return new Promise(resolve => {
+    let executable: string;
+    try { executable = hostExecutable("dot", cwd); } catch { resolve({ admitted: false, reason: "host resource controller unavailable" }); return; }
+    const env = childEnv();
+    delete env.DOT_ADMISSION_SCOPE; // A long-lived daemon must not inherit an expired launcher lease.
+    const child = spawn(executable, ["admit", "--wait", "0s", "--json", "--", process.execPath, "-e", HOLD], { cwd, env, detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    let output = "", bytes = 0, invalid = false, admitted = false;
+    const stop = () => { invalid = true; void stopOwnedProcess(child, { group: true }).catch(() => {}); };
+    // ponytail: one five-second metadata cut lease, never a build lease. Heavy preparation runs through its own admission.
+    const timer = setTimeout(() => { stop(); resolve({ admitted: false, reason: "host resource admission timed out" }); }, 5000);
+    child.stdin.on("error", () => {});
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", chunk => {
+      if (invalid) return;
+      output += chunk; bytes += Buffer.byteLength(chunk);
+      if (bytes > 16 * 1024 || !READY.startsWith(output) && output !== READY) { stop(); resolve({ admitted: false, reason: "host resource admission unknown" }); return; }
+      if (!admitted && output === READY && !locked()) {
+        admitted = true;
+        resolve({ admitted: true, current: () => !invalid && child.exitCode === null && child.signalCode === null && !locked(), close: async () => {
+          clearTimeout(timer);
+          if (child.exitCode === null && child.signalCode === null) {
+            await new Promise<void>(done => {
+              const grace = setTimeout(done, 500);
+              child.once("close", () => { clearTimeout(grace); done(); });
+              child.stdin.end();
+            });
+          }
+          await stopOwnedProcess(child, { group: true });
+        } });
+      }
+    });
+    child.stderr.on("data", (chunk: Buffer) => { bytes += chunk.length; if (bytes > 16 * 1024) stop(); });
+    child.once("error", () => { invalid = true; clearTimeout(timer); resolve({ admitted: false, reason: "host resource controller unavailable" }); });
+    child.once("close", async code => {
+      clearTimeout(timer); invalid = true;
+      if (admitted) return;
+      if (code === 75) { resolve({ admitted: false, reason: "host resource admission deferred (busy repository or pressure)" }); return; }
+      // Diagnose a failed invocation with the same bounded identity probe used by the tooling inventory (#351).
+      // This readback never grants admission or substitutes for the controller's held-lease handshake.
+      const tooling = await detectTooling("hub", { cwd, path: dirname(executable) }).catch(() => undefined);
+      resolve({ admitted: false, reason: tooling && !tooling.some(addon => addon.name === "dot-admit")
+        ? "host resource controller unavailable (dot is not the resource controller; install dot-admit or fix PATH)"
+        : "host resource admission unknown" });
+    });
+  });
+}

package/src/hub/review-brief.ts

@@ -0,0 +1,175 @@
+import { childEnv } from "./child-process.ts";
+import { hubGitSync } from "./git.ts";
+
+/**
+ * #520: the review brief ahub builds itself, in place of `ocr delegate preview` and `rule`. Every reviewer gets the same
+ * one: the changed files of the head against its merge base with the checkout's HEAD, the files left out and why, the
+ * review rules that apply to each file, and the files the plain name list shows that the brief does not. Only git is
+ * read, bounded; nothing here touches the board.
+ */
+export interface BriefFile { path: string; status: string; oldPath?: string; insertions?: number; deletions?: number }
+export interface BriefExcluded { path: string; status: string; oldPath?: string; reason: string }
+export interface ReviewBrief {
+  head: string;
+  /** The default branch the head is compared with: origin/HEAD, origin/main or origin/master. */
+  base: string;
+  mergeBase: string;
+  reviewable: BriefFile[];
+  excluded: BriefExcluded[];
+  /** Changes left out by the privacy policy, both sides of a move included; counted, never named. */
+  withheld: number;
+  /** Rule files by name (REVIEW.md, then `ahub-review-rules` attribute values) with their text at the merge base. */
+  rules: { source: string; text: string }[];
+  /** Configured rule files the brief could not load, with why: the reviewer reads them in the repository. */
+  rulesMissing: { source: string; reason: string }[];
+  /** Reviewable paths grouped by the rule sources that apply to them. */
+  ruleGroups: { sources: string[]; paths: string[] }[];
+  /** Paths in the plain name list of the range that the brief does not list: read them directly. */
+  unlisted: string[];
+}
+export interface BriefPolicy { privatePath(path: string): boolean; nameable(text: string): boolean }
+
+const MAX_FILES = 500, RULE_BYTES = 32_000, MAX_RULE_FILES = 8;
+const LOCKFILES = new Set(["bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock", "uv.lock", "go.sum", "composer.lock", "Gemfile.lock"]);
+const HEX = /^[0-9a-f]{7,40}$/i;
+
+/** Every diff of the brief reads attributes from the trusted tree, never the checkout (a head's `* -diff` cannot mark its own files binary). */
+const attrFrom = (source?: string) => source ? [`--attr-source=${source}`] : [];
+const git = (cwd: string, args: string[]) => hubGitSync(["-C", cwd, ...args], { encoding: "utf8", env: childEnv(process.env), maxBuffer: 16 * 1024 * 1024, timeout: 15_000 });
+
+/**
+ * The changes of `HEAD...head` as groups: one path, or both sides of a rename or copy. A caller that must not show a
+ * private file withholds a whole group when any side is private, so content never shows up under a public name.
+ * ponytail: git's 50% similarity decides what counts as a move.
+ */
+export function changedPathGroups(cwd: string, head: string, base = "HEAD", attrSource?: string): { status: string; paths: string[] }[] | undefined {
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--name-status", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const fields = r.stdout.split("\0"), groups: { status: string; paths: string[] }[] = [];
+  for (let i = 0; i < fields.length - 1;) {
+    const status = fields[i++]!, sides = /^[RC]/.test(status) ? 2 : 1;
+    groups.push({ status, paths: fields.slice(i, i + sides) }); i += sides;
+  }
+  return groups;
+}
+
+export function buildReviewBrief(cwd: string, head: unknown, policy: BriefPolicy): ReviewBrief | { unavailable: string } {
+  if (typeof head !== "string" || !HEX.test(head)) return { unavailable: "the task names no commit" };
+  const full = git(cwd, ["rev-parse", "--verify", "-q", `${head}^{commit}`]);
+  if (full.status !== 0 || typeof full.stdout !== "string") return { unavailable: `commit ${head} is not in this checkout` };
+  const commit = full.stdout.trim();
+  // A reliable base only: the remote's default branch. The checkout's HEAD may be the head itself (an empty inventory)
+  // or another session's branch.
+  const from = ["origin/HEAD", "origin/main", "origin/master"].find(ref => git(cwd, ["rev-parse", "--verify", "-q", `${ref}^{commit}`]).status === 0);
+  if (!from) return { unavailable: "no default branch (origin/HEAD, origin/main or origin/master) to compare with" };
+  const base = git(cwd, ["merge-base", from, commit]);
+  if (base.status !== 0 || typeof base.stdout !== "string") return { unavailable: `commit ${head} shares no history with ${from}` };
+  const mergeBase = base.stdout.trim();
+  const groups = changedPathGroups(cwd, commit, from, mergeBase);
+  if (!groups) return { unavailable: `the changes of ${head} could not be read` };
+  if (!groups.length) return { unavailable: `commit ${head} has no changes against ${from}` };
+  const shown = groups.filter(g => !g.paths.some(path => policy.privatePath(path) || !policy.nameable(path)));
+  if (shown.length > MAX_FILES) return { unavailable: `${shown.length} changed files, over the brief's ${MAX_FILES}` };
+  const withheld = groups.length - shown.length;
+  const counts = numstat(cwd, commit, from, mergeBase);
+  // Attributes and rules come from the merge base: a change cannot lift its own review obligations (a head that marks
+  // everything generated, or edits REVIEW.md, is still reviewed under the rules it is merging into).
+  // Both sides of a move: renaming a reviewed file to a generated or unscoped name must not shed its obligations.
+  const attrs = attributes(cwd, mergeBase, [...new Set(shown.flatMap(g => g.paths))]);
+  if (!counts || !attrs) return { unavailable: `the file details of ${head} could not be read` };
+  const reviewable: BriefFile[] = [], excluded: BriefExcluded[] = [];
+  for (const g of shown) {
+    const path = g.paths.at(-1)!, count = counts.get(path);
+    const sides = { status: g.status[0]!, ...(g.paths.length === 2 ? { oldPath: g.paths[0]! } : {}) };
+    // Excluded only when every side is: a move keeps the source's obligation.
+    const sideReason = (p: string) => attrs.get(p)?.generated ? "generated (linguist-generated)" : LOCKFILES.has(p.split("/").at(-1)!) ? "lockfile" : undefined;
+    const reasons = g.paths.map(sideReason);
+    const reason = count?.binary ? "binary" : reasons.every(Boolean) ? reasons.at(-1) : undefined;
+    if (reason) { excluded.push({ path, ...sides, reason }); continue; }
+    reviewable.push({ path, ...sides, ...(count && !count.binary ? { insertions: count.insertions, deletions: count.deletions } : {}) });
+  }
+  const ruleText = new Map<string, string>(), rulesMissing = new Map<string, string>();
+  const readRule = (source: string): boolean => {
+    if (ruleText.has(source)) return true;
+    if (rulesMissing.has(source)) return false;
+    // A private or non-nameable rule path is not named either: it is left out silently.
+    if (policy.privatePath(source) || !policy.nameable(source)) return false;
+    if (ruleText.size >= MAX_RULE_FILES) { rulesMissing.set(source, `over the brief's ${MAX_RULE_FILES} rule files`); return false; }
+    const r = git(cwd, ["show", `${mergeBase}:${source}`]);
+    if (r.status !== 0 || typeof r.stdout !== "string") { rulesMissing.set(source, "not found at the merge base"); return false; }
+    // Screened whole, before any cut: a rule file that matches a private-data pattern is named but not shown.
+    if (!policy.nameable(r.stdout)) { ruleText.set(source, "(withheld: it matches a private-data pattern; read it in the repository)"); return true; }
+    const bytes = Buffer.from(r.stdout, "utf8");
+    ruleText.set(source, bytes.length > RULE_BYTES ? `${bytes.subarray(0, RULE_BYTES).toString("utf8")}\n[cut at ${RULE_BYTES} bytes]` : r.stdout);
+    return true;
+  };
+  const root = readRule("REVIEW.md");
+  const byKey = new Map<string, { sources: string[]; paths: string[] }>();
+  for (const file of reviewable) {
+    // The rules of every side apply, so a move out of a scoped directory keeps its rule file.
+    const scoped = [...new Set([file.oldPath, file.path].flatMap(p => { const r = p ? attrs.get(p)?.rules : undefined; return r ? [r] : []; }))];
+    const sources = [...(root ? ["REVIEW.md"] : []), ...scoped.filter(readRule)];
+    const key = sources.join("\0");
+    (byKey.get(key) ?? byKey.set(key, { sources, paths: [] }).get(key)!).paths.push(file.path);
+  }
+  // Cross-check with the plain name list (no rename detection), as OCR's list is checked against the PR's.
+  const plain = git(cwd, [...attrFrom(mergeBase), "diff", "--relative", "--no-renames", "--name-only", "-z", `${from}...${commit}`, "--"]);
+  if (plain.status !== 0 || typeof plain.stdout !== "string") return { unavailable: `the name list of ${head} could not be read` };
+  const listed = new Set(shown.flatMap(g => g.paths)), hidden = new Set(groups.filter(g => !shown.includes(g)).flatMap(g => g.paths));
+  const unlisted = plain.stdout.split("\0").filter(path => path && !listed.has(path) && !hidden.has(path));
+  return { head: commit, base: from, mergeBase, reviewable, excluded, withheld, rules: [...ruleText].map(([source, text]) => ({ source, text })), rulesMissing: [...rulesMissing].map(([source, reason]) => ({ source, reason })), ruleGroups: [...byKey.values()], unlisted };
+}
+
+function numstat(cwd: string, head: string, base: string, attrSource: string): Map<string, { insertions: number; deletions: number; binary: boolean }> | undefined {
+  const out = new Map<string, { insertions: number; deletions: number; binary: boolean }>();
+  const r = git(cwd, [...attrFrom(attrSource), "diff", "--no-ext-diff", "--no-textconv", "--relative", "-M", "-C", "--find-copies-harder", "--numstat", "-z", `${base}...${head}`, "--"]);
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  // -z: "ins\tdel\tpath\0", or for a move "ins\tdel\t\0old\0new\0"; a binary file has "-" counts.
+  const fields = r.stdout.split("\0");
+  for (let i = 0; i < fields.length - 1;) {
+    const [ins = "", del = "", path = ""] = fields[i++]!.split("\t");
+    const target = path || (i++, fields[i++] ?? "");
+    out.set(target, { insertions: Number(ins) || 0, deletions: Number(del) || 0, binary: ins === "-" });
+  }
+  return out;
+}
+
+function attributes(cwd: string, source: string, paths: string[]): Map<string, { generated?: boolean; rules?: string }> | undefined {
+  const out = new Map<string, { generated?: boolean; rules?: string }>();
+  if (!paths.length) return out;
+  const r = hubGitSync(["-C", cwd, "check-attr", "-z", "--stdin", `--source=${source}`, "linguist-generated", "ahub-review-rules"], { input: paths.join("\0") + "\0", encoding: "utf8", env: childEnv(process.env), maxBuffer: 4 * 1024 * 1024, timeout: 15_000 });
+  if (r.status !== 0 || typeof r.stdout !== "string") return undefined;
+  const f = r.stdout.split("\0");
+  for (let i = 0; i + 2 < f.length; i += 3) {
+    const [path, attr, value] = [f[i]!, f[i + 1]!, f[i + 2]!], entry = out.get(path) ?? {};
+    if (attr === "linguist-generated" && (value === "set" || value === "true")) entry.generated = true;
+    if (attr === "ahub-review-rules" && value !== "unspecified" && value !== "unset" && value !== "set" && !value.startsWith("/") && !value.split("/").includes("..")) entry.rules = value;
+    out.set(path, entry);
+  }
+  return out;
+}
+
+/** The brief as review text: what every reviewer reads and how it accounts for its coverage. */
+export function renderReviewBrief(brief: ReviewBrief): string {
+  const file = (f: BriefFile) => `- ${f.oldPath ? `${f.oldPath} -> ` : ""}${f.path} (${f.status}${f.insertions !== undefined ? `, +${f.insertions} -${f.deletions}` : ""})`;
+  return [
+    `Review brief: head ${brief.head} against ${brief.base} (merge base ${brief.mergeBase.slice(0, 12)}); ${brief.reviewable.length} reviewable, ${brief.excluded.length} excluded${brief.withheld ? `, ${brief.withheld} withheld by the privacy policy` : ""}.`,
+    ...(brief.reviewable.length ? ["Reviewable:", ...brief.reviewable.map(file)] : ["Reviewable: none (record why in the note)."]),
+    ...(brief.excluded.length ? ["Excluded (still read their diff when it matters):", ...brief.excluded.map(e => `- ${e.oldPath ? `${e.oldPath} -> ` : ""}${e.path} (${e.status}): ${e.reason}`)] : []),
+    ...(brief.unlisted.length ? ["Not in the brief's list, read directly:", ...brief.unlisted.map(path => `- ${path}`)] : []),
+    ...brief.ruleGroups.filter(g => g.sources.length).map(g => `Rules ${g.sources.join(" + ")} apply to: ${brief.ruleGroups.length === 1 ? "every reviewable file" : g.paths.join(", ")}`),
+    ...(brief.rulesMissing.length ? ["Configured rules not loaded (read them in the repository):", ...brief.rulesMissing.map(m => `- ${m.source}: ${m.reason}`)] : []),
+    ...brief.rules.map(r => `--- ${r.source} ---\n${r.text.trimEnd()}`),
+    `Coverage: pass hub_review coverage {reviewed: [paths], skipped: [{path, reason}]} naming every reviewable path above.`,
+  ].join("\n");
+}
+
+/** The reviewable paths a verdict's coverage does not account for: reviewed, or skipped with a reason. */
+export function coverageGap(brief: ReviewBrief, coverage: unknown): string[] {
+  const c = coverage && typeof coverage === "object" && !Array.isArray(coverage) ? coverage as { reviewed?: unknown; skipped?: unknown } : {};
+  const accounted = new Set<string>([
+    ...(Array.isArray(c.reviewed) ? c.reviewed.filter((p): p is string => typeof p === "string") : []),
+    ...(Array.isArray(c.skipped) ? c.skipped.flatMap(s => s && typeof s === "object" && typeof (s as { path?: unknown }).path === "string" && typeof (s as { reason?: unknown }).reason === "string" && (s as { reason: string }).reason.trim() ? [(s as { path: string }).path] : []) : []),
+  ]);
+  return brief.reviewable.map(f => f.path).filter(path => !accounted.has(path));
+}

package/src/hub/reviewer-pool-config.ts

@@ -0,0 +1,11 @@
+export interface ReviewerPoolConfig { pool: string[]; rerotate: boolean }
+
+/** Kind order is project policy; capability and isolation evidence remain host-owned registry facts. */
+export function reviewerPoolConfig(raw: unknown, defaults: readonly string[], known: readonly string[]): ReviewerPoolConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("review must be an object");
+  const value = raw as Record<string, unknown>;
+  const pool = value.pool === undefined ? defaults : value.pool;
+  if (!Array.isArray(pool) || pool.length < 1 || pool.length > 16 || pool.some(kind => typeof kind !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(kind) || !known.includes(kind)) || new Set(pool).size !== pool.length) throw new Error("review.pool must list 1..16 distinct known kinds");
+  if (value.rerotate !== undefined && typeof value.rerotate !== "boolean") throw new Error("review.rerotate must be a boolean");
+  return { pool: [...pool], rerotate: value.rerotate === true };
+}