@staix/agent-hub 0.12.43 → 0.12.45

package/src/hub/no-writes.ts

@@ -0,0 +1,50 @@
+import type { Task } from "./board.ts";
+
+export interface NoWriteObservation {
+  task: number;
+  /** Opaque binding to the current owner and its latest acceptance. */
+  generation: string;
+  limit: number;
+  changed: boolean | undefined;
+  effect: boolean;
+}
+
+/** Pure per-task streaks; callers own evidence, privacy and warning delivery. */
+export class NoWriteTurns {
+  private readonly streaks = new Map<number, { generation: string; count: number; emitted: boolean }>();
+
+  observe({ task, generation, limit, changed, effect }: NoWriteObservation): number | undefined {
+    if (!Number.isSafeInteger(limit) || limit <= 0 || changed !== false || effect !== false) {
+      this.reset(task);
+      return undefined;
+    }
+    const previous = this.streaks.get(task);
+    const streak = previous?.generation === generation ? previous : { generation, count: 0, emitted: false };
+    if (streak !== previous) this.streaks.set(task, streak);
+    if (streak.emitted) return undefined;
+    if (streak.count < Number.MAX_SAFE_INTEGER) streak.count++;
+    if (streak.count < limit) return undefined;
+    streak.emitted = true;
+    return streak.count;
+  }
+
+  reset(task: number): void { this.streaks.delete(task); }
+
+  retain(activeTaskIds: readonly number[]): void {
+    const active = new Set(activeTaskIds);
+    for (const task of this.streaks.keys()) if (!active.has(task)) this.reset(task);
+  }
+}
+
+
+const OWNER_TOOL_EFFECTS = new Set(["hub_task_propose", "hub_task_decline", "hub_task_done", "hub_task_cancel", "hub_task_assign", "hub_task_escalate", "hub_review", "hub_checkpoint", "hub_remember", "hub_memory_correct", "hub_check_start", "hub_check_cancel", "hub_sdlc_record", "hub_plan_review", "hub_backlog_plan", "hub_backlog_pull", "hub_backlog_undo", "hub_backlog_split", "hub_backlog_return_untouched", "hub_release_new", "hub_release_configure", "hub_release_assign", "hub_release_cut"]);
+/** A read does not prove progress; failed/pending mutations are handled conservatively by the host. */
+export function ownerToolEffect(op: string, input: Record<string, unknown> | undefined): boolean {
+  return OWNER_TOOL_EFFECTS.has(op) || op === "hub_task_accept" && !!input?.plan && typeof input.plan === "object" && Object.keys(input.plan).length > 0;
+}
+
+/** Canonical snapshots cannot disprove work in the owner's separately recorded checkout/PR. */
+export function canonicalWriteUnknown(task: Pick<Task, "refs" | "plan" | "sdlc">): boolean {
+  return !!(task.refs.branch || task.refs.commit || task.sdlc?.head || task.sdlc?.localHead || task.sdlc?.pr)
+    || [...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])].some(path => /(?:^|[\\/])\.worktrees(?:[\\/]|$)/i.test(path));
+}

package/src/hub/peers.ts

@@ -1,4 +1,5 @@
 import type { Envelope, EnvelopeOpts, PeerId, PeerState } from "./envelope.ts";
+import type { PermissionMode } from "./permission-mode.ts";
 
 export interface DeliveryReceipt {
   id: string;
@@ -11,6 +12,14 @@ export interface DeliveryReceipt {
 export interface PeerAdapter {
   readonly id: PeerId;
   readonly state: PeerState;
+  /** Host-observed native session identity. An absent port permits owner-token fallback; undefined means unknown. */
+  readonly sessionGeneration?: string | number;
+  /** Defaults to fencing checkpoints when the generation port exists; native legacy exceptions opt out explicitly. */
+  readonly checkpointUsesSessionGeneration?: boolean;
+  /** Effective native approval state; absent peers retain the hub-managed choice. */
+  readonly permissionModeState?: PermissionMode | "unknown" | "unmanaged";
+  /** Resolve only after native acknowledgement. This changes approval frequency, never the sandbox. */
+  setPermissionMode?(mode: PermissionMode): Promise<void>;
   /** A peer the hub drives itself (Pi, the local worker). It cannot be trusted to rate its own urgency: the bus caps it. */
   readonly hubNative?: boolean;
   /** Never handed a delivery: its queue waits for `Bus.pull` (a Claude session that cannot show channel pushes, issue #205). */

package/src/hub/permission-mode.ts

@@ -1,4 +1,4 @@
-import { definitionOf, type KindMap } from "../adapters/registry.ts";
+import { definitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
 import { lstatSync } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
@@ -8,13 +8,15 @@ export type PermissionMode = typeof PERMISSION_MODES[number];
 export { KIMI_MODE_IDS } from "../adapters/definitions/kimi-native.ts";
 export { QWEN_MODE_IDS } from "../adapters/definitions/qwen-native.ts";
 export const isPermissionMode = (value: unknown): value is PermissionMode => typeof value === "string" && (PERMISSION_MODES as readonly string[]).includes(value);
-export function permissionDefaults(value: unknown, instances?: KindMap): Record<string, PermissionMode> {
+export function permissionDefaults(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog): Record<string, PermissionMode> {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("permission_modes must be an object with ask, ask-when-needed or never-ask values");
   const result: Record<string, PermissionMode> = {};
   for (const [peer, mode] of Object.entries(value)) {
-    const definition = typeof peer === "string" ? definitionOf(peer, instances) : undefined;
+    const definition = typeof peer === "string" ? (catalog?.definitionOf ?? definitionOf)(peer, instances) : undefined;
     if (!definition) throw new Error(`permission_modes.${peer}: unsupported peer`);
+    if (instances && Object.hasOwn(instances, peer) && (instances[peer] as { readOnly?: boolean })?.readOnly) throw new Error(`permission_modes.${peer}: read-only ceiling is locked`);
+    if (definition.permission.genericAcp && (!definition.permission.genericAcp.modes || typeof mode !== "string" || !Object.hasOwn(definition.permission.genericAcp.modes, mode))) throw new Error(`permission_modes.${peer}: native mode mapping is unavailable`);
     if (definition.permission.unmanaged) throw new Error(`${definition.displayName} native policy is unmanaged; no hub permission_modes.${peer} mapping exists`);
     if (!isPermissionMode(mode)) throw new Error(`permission_modes.${peer} must be ask, ask-when-needed or never-ask`);
     result[peer] = mode;
@@ -22,16 +24,16 @@ export function permissionDefaults(value: unknown, instances?: KindMap): Record<
   return result;
 }
 /** Approval frequency does not create a common sandbox across native peers. */
-export function permissionBoundary(peer: string, instances?: KindMap): string {
-  const definition = definitionOf(peer, instances);
+export function permissionBoundary(peer: string, instances: KindMap | undefined, catalog: ProjectAdapterCatalog): string {
+  const definition = catalog.definitionOf(peer, instances);
   if (definition?.permission.unmanaged) return `${peer}: native policy unmanaged; NO hub sandbox; approvals belong to its native tools`;
   if (definition?.trust.hubSandboxed) return `${peer}: inside hub sandbox, path guard and denylist`;
   if (definition?.transport === "claude-channel" || definition?.transport === "codex-appserver") return `${peer}: native vendor bounds; no hub sandbox`;
   return `${peer}: runs its own tools; NO hub sandbox`;
 }
 /** What a mode lets a peer do without asking, in one line a person reads before choosing it (#269). */
-export function permissionGrant(peer: string, mode: PermissionMode, instances?: KindMap): string {
-  const grant = definitionOf(peer, instances)?.permission.grants?.[mode];
+export function permissionGrant(peer: string, mode: PermissionMode, instances?: KindMap, catalog?: ProjectAdapterCatalog): string {
+  const grant = (catalog?.definitionOf ?? definitionOf)(peer, instances)?.permission.grants?.[mode];
   if (grant !== undefined) return grant;
   if (mode === "ask") return "every write, edit and shell command asks";
   return mode === "never-ask" ? "every tool runs without asking, inside the hub sandbox and path guard" : "write and edit inside the project run without asking; shell and git writes still ask";

package/src/hub/plan-conformance.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+
+export interface PlanConformance {
+  state: "covered" | "departure" | "unknown";
+  head?: string;
+  outside: string[];
+  untouched: string[];
+}
+/** Repository-relative literal names only. A star is a filename character, never a glob operator. */
+function pathIdentity(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || !raw || raw.length > 1000 || /[\p{Cc}\p{Cf}]/u.test(raw)
+    || raw.startsWith("/") || raw.startsWith("\\") || /^[A-Za-z]:/.test(raw)) return undefined;
+  const path = raw.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
+  if (path === "." || path.split("/").some(part => part === "." || part === "..")) return undefined;
+  return path;
+}
+const covers = (planned: string, changed: string) => changed === planned || changed.startsWith(`${planned}/`);
+
+/** A complete file inventory is independent of any plan or coverage claim. */
+export function completePlanInventory(evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): string[] | undefined {
+  if (!evidence || typeof evidence.head !== "string" || !/^[a-f0-9]{40}$/.test(evidence.head) || evidence.pathsComplete !== true || evidence.typesComplete !== true || !Array.isArray(evidence.paths) || evidence.paths.length > 1000) return undefined;
+  const paths: string[] = [], seen = new Set<string>();
+  for (const raw of evidence.paths) {
+    const path = pathIdentity(raw); if (path === undefined || seen.has(path)) return undefined;
+    seen.add(path); paths.push(path);
+  }
+  return paths;
+}
+
+/** Compare current complete PR file metadata with the current plan; never inspect patches or the filesystem. */
+export function planConformance(planPaths: readonly string[] | undefined, evidence: { head: string; paths: readonly string[]; pathsComplete?: boolean; typesComplete?: boolean } | undefined): PlanConformance {
+  const head = typeof evidence?.head === "string" && /^[a-f0-9]{40}$/.test(evidence.head) ? evidence.head : undefined;
+  const unknown: PlanConformance = { state: "unknown", ...(head ? { head } : {}), outside: [], untouched: [] };
+  const changed = completePlanInventory(evidence);
+  if (!head || changed === undefined
+    || !Array.isArray(planPaths) || !planPaths.length || planPaths.length > 1000) return unknown;
+  const planned: string[] = [], seenPlan = new Set<string>();
+  for (const raw of planPaths) {
+    const path = pathIdentity(raw); if (path === undefined) return unknown;
+    if (!seenPlan.has(path)) { seenPlan.add(path); planned.push(path); }
+  }
+  const outside = changed.filter(path => !planned.some(plan => covers(plan, path)));
+  const untouched = planned.filter(plan => !changed.some(path => covers(plan, path)));
+  return { state: outside.length ? "departure" : "covered", head, outside, untouched };
+}
+
+/** Hash plain plan data without invoking accessors/toJSON; object key order is immaterial, list order is not. */
+export function planFingerprint(plan: unknown): string {
+  const seen = new Set<object>();
+  const fail = (): never => { throw new Error("invalid plan fingerprint data"); };
+  const encode = (value: unknown, depth: number): string => {
+    if (depth > 64) return fail();
+    if (value === undefined) return "undefined";
+    if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+    if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : fail();
+    if (typeof value !== "object" || types.isProxy(value) || seen.has(value)) return fail();
+    seen.add(value);
+    try {
+      if (Array.isArray(value)) {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Reflect.ownKeys(descriptors).length !== value.length + 1) return fail();
+        return "[" + Array.from({ length: value.length }, (_, index) => {
+          const descriptor = descriptors[String(index)];
+          return descriptor && Object.hasOwn(descriptor, "value") ? encode(descriptor.value, depth + 1) : fail();
+        }).join(",") + "]";
+      }
+      if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) return fail();
+      const keys = Reflect.ownKeys(value); if (keys.some(key => typeof key !== "string")) return fail();
+      return "{" + (keys as string[]).sort().map(key => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+        if (!Object.hasOwn(descriptor, "value") || !descriptor.enumerable) return fail();
+        return JSON.stringify(key) + ":" + encode(descriptor.value, depth + 1);
+      }).join(",") + "}";
+    } finally { seen.delete(value); }
+  };
+  return createHash("sha256").update(encode(plan, 0)).digest("hex");
+}
+
+/** Approval blockers only; untouched planned files are advisory. */
+export function planConformanceBlockers(plan: (PlanConformance & { accepted?: boolean }) | undefined): string[] {
+  return !plan ? [] : plan.state === "unknown" ? ["plan conformance unknown"] : plan.state === "departure" && !plan.accepted ? ["plan conformance: changed files outside the plan"] : [];
+}

package/src/hub/review-findings.ts

@@ -0,0 +1,104 @@
+import { types } from "node:util";
+import { sanitize } from "./envelope.ts";
+
+export interface ReviewFinding {
+  id: string;
+  pass: "bugs" | "security" | "compliance";
+  severity: "important" | "nit";
+  path?: string;
+  disposition: "open" | "fixed" | "false_positive" | "accepted";
+  rationale?: string;
+}
+export interface ReviewFindingSet { head?: string; items: ReviewFinding[] }
+export interface ReviewFindingTally { important: number; nit: number; openImportant: number; openNit: number; fixed: number; falsePositive: number; accepted: number }
+export const DEFAULT_MAX_NITS = 5;
+const MAX_ITEMS = 64, MAX_BYTES = 64 * 1024;
+const fail = (reason: string): never => { throw new Error("review findings: " + reason); };
+function fields(raw: unknown): Record<string, PropertyDescriptor> {
+  if (!raw || typeof raw !== "object" || types.isProxy(raw) || Array.isArray(raw)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(raw)) || Object.getOwnPropertySymbols(raw).length) return fail("plain own-data finding required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.values(descriptors).some(field => !Object.hasOwn(field, "value") || !field.enumerable)) return fail("accessors and hidden fields refused");
+  if (Object.keys(descriptors).some(key => !["id", "pass", "severity", "path", "disposition", "rationale"].includes(key))) return fail("unknown finding field");
+  return descriptors;
+}
+function text(raw: unknown, max: number, path: boolean): string {
+  if (typeof raw !== "string" || !raw.trim() || Buffer.byteLength(raw) > max
+    || path && /[\p{Cc}\p{Cf}]/u.test(raw)) return fail("invalid bounded finding text");
+  const clean = sanitize(raw.trim());
+  if (Buffer.byteLength(clean) > max) return fail("sanitized finding text exceeds its bound");
+  return clean;
+}
+/** Supplied findings are validated independently of lifecycle mode, before any board effect. */
+export function parseReviewFindings(raw: unknown, options: { person: boolean; maxNits: number }): ReviewFinding[] {
+  if (typeof options.person !== "boolean" || !Number.isSafeInteger(options.maxNits) || options.maxNits < 0 || options.maxNits > MAX_ITEMS) return fail("invalid finding authority or nit limit");
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw) || types.isProxy(raw) || Object.getPrototypeOf(raw) !== Array.prototype
+    || Object.getOwnPropertySymbols(raw).length || raw.length > MAX_ITEMS) return fail("at most 64 own-data findings required");
+  const descriptors: Record<string, PropertyDescriptor> = Object.assign(Object.create(null), Object.getOwnPropertyDescriptors(raw));
+  if (Object.keys(descriptors).length !== raw.length + 1) return fail("dense finding array required");
+  const ids = new Set<string>();
+  const result = Array.from({ length: raw.length }, (_, index): ReviewFinding => {
+    const entry = descriptors[String(index)];
+    if (!entry || !Object.hasOwn(entry, "value") || !entry.enumerable) return fail("finding array accessors refused");
+    const item = fields(entry.value), id: unknown = item.id?.value, pass: unknown = item.pass?.value;
+    const severity: unknown = item.severity?.value, disposition: unknown = item.disposition?.value;
+    if (typeof id !== "string" || !/^[A-Za-z0-9._:-]+$/.test(id) || Buffer.byteLength(id) > 96 || ids.has(id)) return fail("invalid or duplicate finding id");
+    ids.add(id);
+    if (pass !== "bugs" && pass !== "security" && pass !== "compliance") return fail("invalid finding pass");
+    if (severity !== "important" && severity !== "nit") return fail("invalid finding severity");
+    if (disposition !== "open" && disposition !== "fixed" && disposition !== "false_positive" && disposition !== "accepted") return fail("invalid finding disposition");
+    const path = item.path ? text(item.path.value, 512, true) : undefined;
+    const rationale = item.rationale ? text(item.rationale.value, 2048, false) : undefined;
+    if (disposition === "accepted" && (!options.person || !rationale)) return fail("accepted findings require a person and rationale");
+    return { id, pass, severity, disposition, ...(path !== undefined ? { path } : {}), ...(rationale !== undefined ? { rationale } : {}) };
+  });
+  if (result.filter(item => item.severity === "nit").length > options.maxNits) return fail("nit limit exceeded");
+  if (Buffer.byteLength(JSON.stringify(result)) > MAX_BYTES) return fail("finding report exceeds 64 KiB");
+  return result;
+}
+
+/** Prefer live artifact identity, skipping malformed historical candidates rather than hiding a valid fallback. */
+export function findingHead(receipt?: { head?: string; reviewedHead?: string; localHead?: string }, evidence?: { head: string }, commit?: string): string | undefined {
+  return [evidence?.head, receipt?.head, receipt?.reviewedHead, receipt?.localHead, commit]
+    .find((head): head is string => typeof head === "string" && /^[a-f0-9]{40}$/.test(head));
+}
+
+/**
+ * Nits belong only to their head bucket, including the explicit undefined bucket.
+ * Open Important is an obligation across heads until an explicit disposition resolves its ID globally.
+ */
+export function findingsForHead(sets: readonly ReviewFindingSet[], head?: string): ReviewFinding[] {
+  interface Entry { item: ReviewFinding; order: number }
+  const current = new Map<string, Entry>(), important = new Map<string, Entry>();
+  let order = 0;
+  for (const set of sets) for (const item of set.items) {
+    const key = item.id, position = order++;
+    if (set.head === head) current.set(key, { item: { ...current.get(key)?.item, ...item }, order: position });
+    const prior = important.get(key);
+    if (item.severity === "important") {
+      important.set(key, { item: { ...prior?.item, ...item }, order: position });
+    } else if (prior && (prior.item.disposition === "open" || item.disposition !== "open")) {
+      // A nit/open reclassification cannot discharge Important. An explicit disposition can.
+      important.set(key, { item: { ...prior.item, ...item, severity: "important" }, order: position });
+    }
+  }
+  for (const [key, entry] of important) {
+    if (entry.item.disposition === "open") current.set(key, entry);
+    else {
+      const seen = current.get(key);
+      // Settling on B also settles older A when A is queried again. A later new nit/open remains a head-local nit.
+      if (seen?.item.disposition === "open" && seen.order <= entry.order) current.delete(key);
+    }
+  }
+  return [...current.values()].map(entry => ({ ...entry.item }));
+}
+export function findingTally(items: readonly ReviewFinding[]): ReviewFindingTally {
+  const tally: ReviewFindingTally = { important: 0, nit: 0, openImportant: 0, openNit: 0, fixed: 0, falsePositive: 0, accepted: 0 };
+  for (const item of items) {
+    tally[item.severity]++;
+    if (item.disposition === "open") tally[item.severity === "important" ? "openImportant" : "openNit"]++;
+    else tally[item.disposition === "false_positive" ? "falsePositive" : item.disposition]++;
+  }
+  return tally;
+}

package/src/hub/roster.ts

@@ -1,14 +1,41 @@
-import { definitionOf, type KindMap } from "../adapters/registry.ts";
-import { defaultRosterEnabled } from "../adapters/registry.ts";
+import { definitionOf as builtinDefinitionOf, type ProjectAdapterCatalog, type KindMap } from "../adapters/registry.ts";
+import { validateInstances } from "./instances.ts";
+import { defaultRosterEnabled as builtinDefaultRosterEnabled, createProjectAdapterCatalog as builtinCatalog } from "../adapters/registry.ts";
 
 export type PeerRoster = Partial<Record<string, boolean>>;
 
-export function peerRosterConfig(value: unknown, instances?: KindMap): PeerRoster {
+/**
+ * A roster key of an instance that was declared, put on the roster and later undeclared (#225). It has the shape a declaration
+ * could have had (`<builtin kind>-<name>`, the rule validateInstances applies to an id) and no definition now, so it grants and
+ * refuses nothing: the config still loads and `ahub roster remove` can delete it. Anything else stays an unsupported peer.
+ */
+export function staleInstanceKey(peer: string, catalog: ProjectAdapterCatalog | undefined): boolean {
+  const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(peer) || definitionOf(peer)) return false; // a reserved id (user, hub, digest) never starts with a kind and a dash
+  if (!catalog) return false;
+  return catalog.definitions.some(kind => peer.startsWith(`${kind.kind}-`) && /^[a-z0-9][a-z0-9-]*$/.test(peer.slice(kind.kind.length + 1)) && canDeclareInstance(peer, kind.kind, catalog) && !catalog.externalDefinitions.some(item => item.kind === kind.kind));
+}
+
+/** The declarations a person can write for an extra instance of a kind: validateInstances decides which of them its definition takes. */
+const DECLARATION_SHAPES: readonly Record<string, unknown>[] = [
+  { roles: ["implementer"], start_mode: "headless" }, { roles: ["reviewer"], start_mode: "headless" }, { roles: ["reviewer"] }, { roles: ["planner"] },
+];
+
+/** Whether validateInstances would take `<kind>-<name>` for this kind under any declaration, so the answer cannot drift from its policy. */
+function canDeclareInstance(id: string, kind: string, catalog: ProjectAdapterCatalog): boolean {
+  return DECLARATION_SHAPES.some(shape => { try { validateInstances({ [id]: { kind, ...shape } }, catalog); return true; } catch { return false; } });
+}
+
+export function peerRosterConfig(value: unknown, instances?: KindMap, catalog?: ProjectAdapterCatalog, inertUnknown = false): PeerRoster {
+  const definitionOf = catalog?.definitionOf ?? builtinDefinitionOf;
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("roster must be an object of boolean peer values");
   const roster: PeerRoster = {};
+  const requireKnownPeer = (peer: string) => {
+    if (!definitionOf(peer, instances) && !staleInstanceKey(peer, catalog ?? builtinCatalog())) throw new Error("roster contains an unsupported peer");
+  };
   for (const [peer, on] of Object.entries(value)) {
-    if (!definitionOf(peer, instances)) throw new Error("roster contains an unsupported peer");
+    if (!inertUnknown || !/^[a-z][a-z0-9-]{0,31}$/.test(peer)) requireKnownPeer(peer);
     if (typeof on !== "boolean") throw new Error(`roster.${peer} must be a boolean`);
     roster[peer] = on;
   }
@@ -16,8 +43,10 @@ export function peerRosterConfig(value: unknown, instances?: KindMap): PeerRoste
 }
 
 /** External ids keep their existing admission rules; Pi's legacy switch is only its default. */
-export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances?: KindMap): boolean {
+export function rosterAllows(roster: PeerRoster, peer: string, piEnabled: boolean, instances: KindMap | undefined, catalog: ProjectAdapterCatalog, inertUnknown = false): boolean {
+  const definitionOf = catalog.definitionOf;
+  const defaultRosterEnabled = (id: string, enabled: boolean) => !builtinDefinitionOf(id) ? catalog.definitionOf(id)?.defaultOnRoster ?? false : builtinDefaultRosterEnabled(id, enabled);
   const definition = definitionOf(peer, instances);
-  if (!definition) return true; // External clients do not acquire a native kind from a project declaration.
+  if (!definition) return !inertUnknown || !Object.hasOwn(roster, peer); // Only a captured module scope makes unresolved rows inert; legacy external clients keep their admission rules.
   return roster[peer] ?? (definition.kind === peer ? defaultRosterEnabled(peer, piEnabled) : true);
 }

package/src/hub/routing.ts

@@ -1,5 +1,5 @@
 import { selectReviewerPool, type ReviewerPoolSelection } from "./reviewer-pool.ts";
-import { ADAPTERS, definitionOf, kindOf, familyOf } from "../adapters/registry.ts";
+import { ADAPTERS, definitionOf, kindOf, familyOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CLASSES, type Task, type TaskClass } from "./board.ts";
@@ -115,6 +115,7 @@ export const PI: PeerId = "pi";
 
 /** Startup-bound project data, never inferred from a suffix or read from configuration here. */
 export interface InstanceRoutingOptions {
+  adapterCatalog?: ProjectAdapterCatalog;
   instances?: Readonly<Record<string, { kind: string }>>;
   wip?: Record<string, number>;
   load?: Record<string, number>;
@@ -133,8 +134,8 @@ function siblingOrder(states: Readonly<Record<string, PeerState>>, opts: Instanc
 function expandClassPeers(peers: readonly PeerId[], states: Readonly<Record<string, PeerState>>, opts: InstanceRoutingOptions): PeerId[] {
   if (!hasInstances(opts)) return [...peers];
   return [...new Set(peers.flatMap(peer => {
-    const kind = kindOf(peer, opts.instances);
-    return kind && kind === peer ? [peer, ...Object.keys(opts.instances!).filter(id => kindOf(id, opts.instances) === kind)].sort(siblingOrder(states, opts)) : [peer];
+    const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(peer, opts.instances);
+    return kind && kind === peer ? [peer, ...Object.keys(opts.instances!).filter(id => (opts.adapterCatalog?.kindOf ?? kindOf)(id, opts.instances) === kind)].sort(siblingOrder(states, opts)) : [peer];
   }))];
 }
 /** Quota/adaptive policy retains kind slots; sibling workload chooses only within that kind's slots. */
@@ -142,7 +143,7 @@ function orderSiblingSlots(peers: PeerId[], states: Readonly<Record<string, Peer
   if (!hasInstances(opts)) return peers;
   const groups = new Map<string, number[]>(), out = [...peers];
   for (const [index, peer] of peers.entries()) {
-    const kind = kindOf(peer, opts.instances);
+    const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(peer, opts.instances);
     if (kind) { const slots = groups.get(kind) ?? []; slots.push(index); groups.set(kind, slots); }
   }
   for (const slots of groups.values()) {
@@ -154,11 +155,11 @@ function orderSiblingSlots(peers: PeerId[], states: Readonly<Record<string, Peer
 
 /** The quota/roster relay keeps its native preference order, then the class's original tail. */
 export function relayCandidates(classPeers: readonly PeerId[], pii: boolean, opts: InstanceRoutingOptions & { states?: Readonly<Record<string, PeerState>> } = {}): PeerId[] {
-  const preferred = ADAPTERS.filter(adapter => adapter.routing?.handoffPriority !== undefined)
+  const preferred = (opts.adapterCatalog?.definitions ?? ADAPTERS).filter(adapter => adapter.routing?.handoffPriority !== undefined)
     .sort((a, b) => a.routing!.handoffPriority! - b.routing!.handoffPriority!);
   const candidates = [
     ...preferred.filter(adapter => !pii || adapter.trust.onPrem).map(adapter => adapter.kind),
-    ...classPeers.filter(peer => definitionOf(peer, opts.instances)?.routing?.handoffPriority === undefined),
+    ...classPeers.filter(peer => (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.handoffPriority === undefined),
   ].filter((peer): peer is PeerId => !!peer);
   return expandClassPeers(candidates, opts.states ?? {}, opts);
 }
@@ -378,10 +379,10 @@ export function assign(
   const refusals = new Map<string, RoutingRefusal>();
   const blocked = (peer: PeerId, role: "owner" | "reviewer"): string | undefined => {
     const deny = (code: RoutingRefusalCode, reason: string): string => { refusals.set(`${role}:${peer}`, { peer, role, code, reason }); return reason; };
-    const ceiling = definitionOf(peer, opts.instances)?.routing?.allowedRoles;
+    const ceiling = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.allowedRoles;
     const requiredRole = role === "reviewer" || task.class === "review" ? "reviewer" : task.class === "plan" ? "planner" : "implementer";
     if (ceiling && !ceiling.includes(requiredRole)) return deny("policy", "adapter role ceiling excludes this assignment");
-    const unavailable = role === "reviewer" ? definitionOf(peer, opts.instances)?.reviewer?.unavailable : undefined;
+    const unavailable = role === "reviewer" ? (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.reviewer?.unavailable : undefined;
     if (unavailable) return deny("policy", unavailable);
     if (role === "owner" && opts.capabilities && !pii) {
       const caps = peerEntry(opts.capabilities, peer);
@@ -394,7 +395,7 @@ export function assign(
     if (!Object.hasOwn(states, peer)) return deny("not-attached", "not attached");
     if (opts.exclude?.includes(peer)) return deny("excluded", "excluded (declined or replaced)");
     if (role === "owner" && opts.excludeOwners?.includes(peer)) return deny("owner-admission", "owner admission: WIP or delivery hold");
-    const adapter = definitionOf(peer, opts.instances);
+    const adapter = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances);
     if (role === "owner" && adapter?.routing?.reviewOnly) return deny("owner-admission", "owner admission: a review-only instance owns no task");
     if (role === "owner" && needsTests && adapter && adapter.kind !== peer) {
       if (!peerEntry(opts.roles, peer)?.includes("implementer")) return deny("owner-admission", "owner admission: declared write owner requires the current implementer role");
@@ -404,8 +405,8 @@ export function assign(
     if (states[peer] === "paused" && routing.constraints.budget_paused === "skip_peer") return deny("paused", "paused");
     const failing = peerEntry(opts.failing, peer);
     if (failing) return deny("failing", `failing: ${failing}`);
-    if (pii && definitionOf(peer, opts.instances)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
-    const nativeRouting = definitionOf(peer, opts.instances)?.routing;
+    if (pii && (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.trust.onPrem !== true) return deny("pii", "pii: on-prem peers only");
+    const nativeRouting = (opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing;
     if (nativeRouting?.localAllowedRefusal && policy?.local_allowed === false) return deny("policy", nativeRouting.localAllowedRefusal);
     if (nativeRouting?.longContext === "backend-limit" && task.signals.includes("long_context")) {
       const backend = policy?.pi_backend ?? "dgx";
@@ -462,7 +463,7 @@ export function assign(
     }
     const ranked = sortSiblings ? orderSiblingSlots(rank(ok, role, not), states, opts) : rank(ok, role, not);
     // Demotion applies to local and Pi too: a demoted one loses its place ahead of the cloud peers.
-    const localTier = ranked.filter((p) => definitionOf(p, opts.instances)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
+    const localTier = ranked.filter((p) => (opts.adapterCatalog?.definitionOf ?? definitionOf)(p, opts.instances)?.routing?.preferredTier === true && !(role === "owner" && peerEntry(opts.demoted, p)));
     if (localTier.length) return localTier.find((p) => states[p] === "idle") ?? localTier[0]; // local/Pi stays ahead of an idle cloud peer
     return ranked.find((p) => states[p] === "idle") ?? ranked[0];
   };
@@ -492,13 +493,13 @@ export function assign(
       trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
       const reviewOwner = owner ?? opts.notReviewer;
       const automatic = [...new Set([...expandClassPeers(classPeers, states, opts), ...rolePeers])];
-      const ownerFamily = instanceMode && reviewOwner ? familyOf(reviewOwner, opts.instances) : undefined;
-      const sameFamily = (peer: PeerId) => ownerFamily !== undefined && familyOf(peer, opts.instances) === ownerFamily;
+      const ownerFamily = instanceMode && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
+      const sameFamily = (peer: PeerId) => ownerFamily !== undefined && (opts.adapterCatalog?.familyOf ?? familyOf)(peer, opts.instances) === ownerFamily;
       const independent = ownerFamily === undefined ? [] : automatic.filter(peer => peer !== reviewOwner && !blocked(peer, "reviewer") && !sameFamily(peer));
       const named = opts.namedReviewer;
       const declaredPool = opts.reviewPool && named === undefined ? Object.keys(opts.instances ?? {}).flatMap(id => {
-        const roles = peerEntry(opts.roles, id), definition = definitionOf(id, opts.instances);
-        const kind = kindOf(id, opts.instances), family = familyOf(id, opts.instances);
+        const roles = peerEntry(opts.roles, id), definition = (opts.adapterCatalog?.definitionOf ?? definitionOf)(id, opts.instances);
+        const kind = (opts.adapterCatalog?.kindOf ?? kindOf)(id, opts.instances), family = (opts.adapterCatalog?.familyOf ?? familyOf)(id, opts.instances);
         if (roles?.length !== 1 || roles[0] !== "reviewer" || !definition?.routing?.reviewOnly || !kind || !family) return [];
         const reason = id === reviewOwner ? "is the owner" : definition.reviewer?.unavailable ?? blocked(id, "reviewer")
           ?? (states[id] === "paused" ? "paused" : undefined)
@@ -509,7 +510,7 @@ export function assign(
       if (declaredPool.length || opts.reviewPool?.required && named === undefined) {
         for (const candidate of declaredPool) if (!opts.reviewPool!.pool.includes(candidate.kind)) trace.push(`  reviewer pool candidate ${candidate.id} (${candidate.family}): unavailable skip: ${candidate.blocked ?? "kind outside configured pool"}`);
         const last = task.history?.findLast(entry => entry.event === "changes_requested");
-        const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? familyOf(last.by, opts.instances) : undefined;
+        const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? (opts.adapterCatalog?.familyOf ?? familyOf)(last.by, opts.instances) : undefined;
         const pr = task.sdlc?.pr;
         const seed = typeof pr === "number" && Number.isSafeInteger(pr) && pr > 0 ? pr : task.id ?? 0;
         reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed });
@@ -518,7 +519,7 @@ export function assign(
         if (reviewSelection.blocked) {
           trace.push("blocked: no reviewer can run");
           // Optional defaults retain the legacy planner escape when no fresh reviewer can run.
-          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !definitionOf(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
+          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
           const otherFamily = planners.filter(peer => !sameFamily(peer));
           const planner = pick(otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
           if (planner) {
@@ -555,8 +556,8 @@ export function assign(
   const route = effectiveLocalRoute(routing.local.route, policy?.route, policy?.fixed_model);
   const fixedModel = policy?.fixed_model ?? routing.local.fixed_model;
   const piBackend = policy?.pi_backend;
-  if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
-  if (owner && definitionOf(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${definitionOf(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
+  if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "route") trace.push(`route: ${route ?? "(none)"}, fixed_model ${fixedModel}`);
+  if (owner && (opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)?.routing?.trace === "backend") trace.push(`${(opts.adapterCatalog?.definitionOf ?? definitionOf)(owner, opts.instances)!.routing!.backendLabel} decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
   return { ...(reviewSelection ? { reviewSelection } : {}), ...(reviewBlocked ? { reviewBlocked: true as const } : {}), ...(sameFamilyFallback ? { sameFamilyFallback: true as const } : {}), ...(plannerFallback ? { plannerFallback: true as const } : {}), ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), ...(unreserved ? { unreserved } : {}), ...(refusals.size ? { refusals: [...refusals.values()] } : {}), trace };
 }
 

package/src/hub/sdlc-queue.ts

@@ -1,7 +1,9 @@
+import { planConformance, planConformanceBlockers } from "./plan-conformance.ts";
+import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } from "./workflow.ts";
 import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
-export interface DeliveryTask { id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
-export interface MergeQueueRow { pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
+export interface MergeQueueRow { planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
 export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
 export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
 const validRepo = (value: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -49,15 +51,28 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
   for (const pr of ids) {
     const holders = tasks.filter(t => sameRepo(t.receipt?.repo) && t.receipt?.pr === pr); links.set(pr, holders);
     const row: MergeQueueRow = { pr, tasks: holders.some(t => t.private) ? [] : holders.map(t => t.id), ready: false, blockers: [], after: [] }; result.rows.push(row);
-    if (holders.some(t => t.private)) { row.private = true; row.blockers.push("private lifecycle evidence unavailable"); continue; }
+    if (holders.some(t => t.private)) { row.private = true; if (config.mode !== "off") row.planConformance = [{ state: "unknown", outside: 0, untouched: 0, accepted: false }]; row.blockers.push("private lifecycle evidence unavailable"); continue; }
     const read = await readSdlcPr(holders[0]?.receipt ?? { stage: config.stages[0] ?? "spec", repo, pr }, bounded);
     if (!read || read.state !== "OPEN") { row.blockers.push("current PR evidence unknown or no longer open"); continue; }
     evidence.set(pr, read); row.head = read.head;
+    for (const holder of holders) {
+      const items = findingsForHead(holder.findings ?? [], findingHead(holder.receipt, read));
+      if (!items.length) continue;
+      const tally = findingTally(items);
+      row.findings ??= findingTally([]);
+      for (const key of Object.keys(tally) as (keyof ReviewFindingTally)[]) row.findings[key] += tally[key];
+    }
     if (!read.pathsComplete) row.blockers.push("PR file coverage is incomplete or unknown");
     if (read.draft !== false) row.blockers.push("PR is draft or draft status is unknown");
     if (!read.base) row.blockers.push("PR target branch is unknown");
     const linked = holders.length ? holders : [undefined];
-    for (const holder of linked) row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+    if (config.mode === "enforce" && row.findings?.openImportant) row.blockers.push("open important review findings: " + row.findings.openImportant);
+    for (const holder of linked) {
+      const conformance = holder?.plan ? { ...planConformance(holder.plan.paths, read), accepted: holder.plan.accepted.some(item => item.repo === holder.receipt?.repo && item.pr === holder.receipt?.pr && item.head === read.head && item.revision === holder.plan!.revision && item.fingerprint === holder.plan!.fingerprint && JSON.stringify([...item.paths].sort()) === JSON.stringify([...read.paths].sort())) } : undefined;
+      if (holder && conformance && config.mode !== "off") (row.planConformance ??= []).push({ task: holder.id, state: conformance.state, outside: conformance.outside.length, untouched: conformance.untouched.length, accepted: conformance.accepted });
+      row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance));
+    }
   }
   const dependencyEvidence = new Map<number, PrEvidence | undefined>(); let dependencyReads = 0;
   for (const row of result.rows) {

package/src/hub/sdlc-release.ts

@@ -4,7 +4,22 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { childEnv, stopOwnedProcess } from "./child-process.ts";
 import { hubGitSync } from "./git.ts";
-import { sdlcGh, type SdlcGh } from "./sdlc.ts";
+import type { SdlcGh } from "./sdlc.ts";
+// Standalone document evidence does not need lifecycle/review code; load the default remote reader only when used.
+let importDiagnosticShown = false;
+const sdlcGh: SdlcGh = async (...args) => {
+  let reader: typeof import("./sdlc.ts");
+  try { reader = await import("./sdlc.ts"); }
+  catch {
+    if (!importDiagnosticShown) {
+      importDiagnosticShown = true;
+      try { console.warn("sdlc: release evidence reader unavailable (lifecycle import failed)"); } catch { /* a diagnostic cannot turn unknown evidence into an exception */ }
+    }
+    return { code: 1, stdout: "" };
+  }
+  try { return await reader.sdlcGh(...args); }
+  catch { return { code: 1, stdout: "" }; }
+};
 export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
 export interface ReleaseReadiness { repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
 export type ReleaseGit = (args: string[]) => { code: number; stdout: string };