@staix/agent-hub 0.12.35 → 0.12.36

package/src/hub/tasks.ts

@@ -1,3 +1,5 @@
+import { cleanCostPlan, costMetrics, type CostPlan, type ReviewCost } from "./cost-governance.ts";
+import { specRefs } from "./spec-read.ts";
 import type { InstancesConfig } from "./instances.ts";
 import { composeRememberText } from "./memory-fail.ts";
 import { VERSION } from "../version.ts";
@@ -16,7 +18,7 @@ import { isAbsolute, relative } from "node:path";
 import type { Briefs, NativeItem } from "../memory/brief.ts";
 import type { MemoryClient } from "../memory/client.ts";
 import { candidateTargetRevision, type CandidateInput, type CandidateStore, extractNodes, looksSecret, PROMOTED_KINDS, taskKey, type GoalView, type Kind, type MemoryStore, type Scope, type Tier } from "@staix/agent-mem";
-import { CLASSES, OUTCOMES_KEPT_MS, ALL_PLAN_KEYS, TASK_MOVE_REASONS, taskHasStarted, planningUndoEntry, isClosedTaskState, type TaskStall, type HistoryEntry, type Board, type Task, type TaskClass, type TaskMoveReason, type TaskPlan, type TaskRefs } from "./board.ts";
+import { CLASSES, OUTCOMES_KEPT_MS, ALL_PLAN_KEYS, TASK_MOVE_REASONS, taskCanPlan, taskHasWorkEvidence, taskHasStarted, planningUndoEntry, isClosedTaskState, type TaskStall, type HistoryEntry, type Board, type Task, type TaskClass, type TaskMoveReason, type TaskPlan, type TaskRefs } from "./board.ts";
 import type { Bus } from "./bus.ts";
 import { HUB, newEnvelope, NOTE_KINDS, noteLine, sanitize, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
 import type { PiiVerdict, ScreenItem, ScreenRecord } from "./inference.ts";
@@ -25,9 +27,10 @@ import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecisi
 import { Cohorts, MAX_REQUESTS, type Cohort, type Completion } from "./cohorts.ts";
 import { realPath } from "./project.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { coverageGap, renderReviewBrief, type ReviewBrief } from "./review-brief.ts";
 import { ADAPTERS, definitionOf } from "../adapters/registry.ts";
-import { nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
-import { checklistOf, readSdlcPr, sdlcConfig, sdlcReceipt, sdlcStatus, stageDefinition, lifecycleStage, type SdlcConfig, sdlcGh, type SdlcGh, type SdlcStatus } from "./sdlc.ts";
+import { plannerGrooming, nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
+import { readPrCostHistory, readReviewReadiness, reviewReadinessFromEvidence, type PrEvidence, type ReviewReadiness, readPlanIssueMetadata, canonicalStage, checklistOf, readSdlcPr, readSpecEdit, sdlcConfig, sdlcReceipt, sdlcStatus, specState, SPEC_STATE_TEXT, stageDefinition, lifecycleStage, type SdlcConfig, type PlanIssueMetadata, sdlcGh, type SdlcGh, type SdlcStatus, type SpecEdit, type SpecState } from "./sdlc.ts";
 
 export type TaskAssignmentRole = "owner" | "reviewer";
 
@@ -52,6 +55,8 @@ export interface TasksDeps {
   sessionRoles?: (peer: PeerId) => string[];
   /** Optional bounded snapshot presentation; never stored in task history or memory. */
   projectedReview?: (task: Task) => string | undefined;
+  /** #520: the review brief for a task's commit (git only, bounded); undefined when the task names no commit. */
+  reviewBrief?: (task: Task) => ReviewBrief | { unavailable: string } | undefined;
   sdlc?: { config: () => SdlcConfig; gh?: SdlcGh };
   briefs?: Briefs;
   /** Screened live fail notes directly intersecting the task plan or refs; read-only advice. */
@@ -60,6 +65,12 @@ export interface TasksDeps {
   candidateScreen?: MemoryScreen;
   /** Authenticated live turn context, not a model-supplied flag. */
   privateTurn?: (peer: PeerId) => boolean;
+  /** #223 R4: the hub's reading of a verdict's context (`fresh` only for a reviewer session started for this review). */
+  reviewContext?: (by: PeerId, task: number) => "fresh" | "continuing" | undefined;
+  /** #223 R2: a reviewer-only instance gets review facts, not the builder's done summary. */
+  reviewOnly?: (peer: PeerId) => boolean;
+  /** #223: captured when a verdict call starts; a non-undefined result refuses the verdict at every later check. */
+  reviewAuthority?: (by: PeerId, task: number) => (() => string | undefined) | undefined;
   memory?: MemoryClient;
   /** Captured native profile fence at our memory operation boundaries; no board mutation. */
   memoryCheck?: () => void;
@@ -93,6 +104,8 @@ export interface TasksDeps {
   failing?: () => Record<PeerId, string>;
   /** Peers whose queue a needs_review delivery holds, with the hold detail (issue #90); routing explains the hold, never rejects. */
   held?: () => Record<PeerId, string>;
+  /** Closed host facts only; approval text and quota reasons never enter the grooming projection. */
+  plannerBlocks?: () => Record<PeerId, ("approvals" | "quota")[]>;
   /** Roles from `.agenthub/config.json` (issue #92): peers with the reviewer role join the reviewer candidates. */
   roles?: Record<string, string[]>;
   /** Optional: name a class for a task proposed without one. `onCampus` says whether the model call stays on campus. */
@@ -213,7 +226,9 @@ function cleanRefs(input: unknown): TaskRefs {
 /** The same for a plan (issue #31): only its four lists, each of short strings. */
 function cleanPlan(input: unknown, profile: ProfileSelection = "dev"): TaskPlan {
   const r = fields(input);
-  return Object.fromEntries((profileData(profile).plan_keys as (keyof TaskPlan)[]).map((k) => [k, k === "paths" ? [...new Set(textList(r[k]).map(normPath))] : textList(r[k])] as const).filter(([, v]) => v.length));
+  let scope: CostPlan;
+  try { scope = cleanCostPlan(r); } catch { throw new PreEffectToolRefusal("invalid review or CI cost scope"); }
+  return { ...Object.fromEntries((profileData(profile).plan_keys as (keyof TaskPlan)[]).map((k) => [k, k === "paths" ? [...new Set(textList(r[k]).map(normPath))] : textList(r[k])] as const).filter(([, v]) => v.length)), ...scope };
 }
 
 /** A plan as one line for other owners; the whole plan is on the board. */
@@ -644,6 +659,11 @@ export class Tasks {
     if (by !== USER && !this.d.roles?.[by]?.includes("planner")) throw new PreEffectToolRefusal("planning requires a person or configured planner role");
   }
 
+  private plannerWriteAuthority(by: PeerId): void {
+    if (by !== USER && this.d.privateTurn?.(by)) throw new PreEffectToolRefusal("planner writes are unavailable during a private turn");
+    this.planningAuthority(by);
+  }
+
   wipLimit(peer: PeerId): number {
     const limit = this.d.wipLimit?.(peer) ?? 1;
     if (!Number.isSafeInteger(limit) || limit < 0 || limit > 32) throw new PreEffectToolRefusal("invalid planner WIP capacity");
@@ -681,7 +701,7 @@ export class Tasks {
     if (!Number.isSafeInteger(input.id) || input.id <= 0 || !Number.isSafeInteger(input.revision) || input.revision < 0 || typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 1000) throw new PreEffectToolRefusal("planner pull needs an id, revision and bounded reason");
     const validate = () => {
       const task = this.d.board.get(input.id);
-      if (!task || (task.planningRevision ?? 0) !== input.revision || task.state !== "backlog" || task.owner || taskHasStarted(task) || task.pinned) throw new PreEffectToolRefusal("planner pull changed, pinned or already started");
+      if (!task || (task.planningRevision ?? 0) !== input.revision || task.state !== "backlog" || task.owner || !taskCanPlan(task) || task.pinned) throw new PreEffectToolRefusal("planner pull changed, pinned or already started");
       const release = task.release == null ? undefined : this.d.board.release(task.release);
       if (task.release != null && (!release || ["frozen", "shipped", "dropped"].includes(release.state))) throw new PreEffectToolRefusal("planner pull requires unfrozen release scope");
       if (this.waitsFor(task).length) throw new PreEffectToolRefusal("planner pull waits for dependency approval");
@@ -719,6 +739,7 @@ export class Tasks {
     for (const id of ids) if (this.d.board.get(id)?.state === "backlog") pending.add(id);
     if (pending.size) this.plannerBacklog.set(peer, pending);
   }
+  private readonly groomingNotified = new Map<string, number>();
   /** One bounded ids-only batch per attached planner; failed or evicted copies stay pending. */
   flushPlannerNotices(): number {
     const configured = Object.entries(this.d.roles ?? {}).filter(([, roles]) => roles.includes("planner")).map(([peer]) => peer);
@@ -732,6 +753,18 @@ export class Tasks {
     }
     const planners = configured.filter(peer => this.d.bus.isRostered(peer) && this.d.bus.peers.has(peer) && this.d.bus.stateOf(peer) !== "offline");
     if (!planners.length) return 0;
+    if ((this.d.sdlc?.config().mode ?? "off") !== "off") {
+      const revision = this.d.board.statusRevision();
+      const body = "The board changed. Before offering or accepting build work, read hub_planner_groom, consolidate dependencies and priorities, and record hub_plan_review against the current planning revision.";
+      for (const peer of planners) if (this.groomingNotified.get(peer) !== revision) {
+        const queued = this.d.bus.pendingEnvelopes(peer).some(env => env.from === HUB && env.kind === "task" && env.body === body);
+        if (queued) continue;
+        this.releaseNotice(`could not notify planner ${peer} about grooming`, () => {
+          const recipients = this.d.bus.publish(newEnvelope(HUB, body, { to: [peer], kind: "task" }));
+          if (recipients.includes(peer)) this.groomingNotified.set(peer, revision);
+        });
+      }
+    }
     for (const id of this.incomingBacklog) if (this.d.board.get(id)?.state !== "backlog") this.incomingBacklog.delete(id);
     const incoming = [...this.incomingBacklog].sort((a, b) => a - b).slice(0, 64);
     if (incoming.length) {
@@ -815,11 +848,14 @@ export class Tasks {
       const task = this.d.board.get(input.id);
       if (!task || (task.planningRevision ?? 0) !== input.revision) throw new PreEffectToolRefusal("planning revision changed");
       if (isClosedTaskState(task.state)) throw new PreEffectToolRefusal("closed work is final");
-      if (by !== USER && (task.state !== "backlog" || taskHasStarted(task) || task.pinned || Object.hasOwn(patch, "pinned"))) throw new PreEffectToolRefusal("planner changes only unpinned backlog work");
+      if (by !== USER && (task.state !== "backlog" || !taskCanPlan(task) || task.pinned || Object.hasOwn(patch, "pinned"))) throw new PreEffectToolRefusal("planner changes only unpinned backlog work");
       if (by !== USER && patch.rank !== undefined && task.history.some(entry => entry.by === USER && entry.planning?.fields.includes("rank"))) throw new PreEffectToolRefusal("a person's backlog order is retained");
       if (by !== USER && Object.hasOwn(patch, "reserved") && this.hasPersonReservation(task)) throw new PreEffectToolRefusal("a person's reservation is retained");
       if (Object.hasOwn(patch, "deps") || Object.hasOwn(patch, "reserved")) {
-        if (task.state !== "backlog" || taskHasStarted(task) || task.owner) throw new PreEffectToolRefusal("dependency and reservation changes require unstarted backlog work");
+        const returnedUntouched = task.state === "backlog" && !task.owner && taskHasStarted(task) && taskCanPlan(task);
+        if (!returnedUntouched) {
+          if (task.state !== "backlog" || taskHasStarted(task) || task.owner) throw new PreEffectToolRefusal("dependency and reservation changes require unstarted backlog work");
+        }
         if (patch.reserved && !definitionOf(patch.reserved, this.d.instances?.()) && !this.d.bus.knownPeers().includes(patch.reserved) && !this.d.routing().classes[task.class]?.peers.includes(patch.reserved)) throw new PreEffectToolRefusal("reserved owner is not a supported or configured peer");
         if (patch.reserved && !this.d.bus.isRostered(patch.reserved)) throw new PreEffectToolRefusal("reserved owner is off roster");
         if (patch.reserved) this.requireCapabilities(task, patch.reserved);
@@ -1011,6 +1047,12 @@ export class Tasks {
     if (external && (by !== USER || input.backlog !== true)) throw new PreEffectToolRefusal("external intake requires person-owned backlog staging");
     if (input.backlog !== undefined && typeof input.backlog !== "boolean") throw new PreEffectToolRefusal("backlog must be a boolean");
     const backlog = input.backlog === true;
+    const claiming = !backlog && input.owner === by;
+    if (claiming) {
+      this.acceptanceCapacity({ id: -1, owner: by, state: "proposed" });
+      this.pendingClaims.set(by, (this.pendingClaims.get(by) ?? 0) + 1);
+    }
+    try {
     if (backlog && input.owner && !this.d.bus.isRostered(input.owner)) throw new PreEffectToolRefusal(`${input.owner} is off roster; add it before reserving work`);
     // Callers are models: a title is one line (it is part of console and hub.log lines), not a document.
     const title = String(input.title ?? "").replace(/\s+/g, " ").trim().slice(0, 300);
@@ -1060,6 +1102,7 @@ export class Tasks {
     const defaulted = !backlog && !cls && input.owner === by;
     if (defaulted) cls = "implement";
     if (!cls) throw new PreEffectToolRefusal(`class is required (one of ${CLASSES.join(", ")}); ${fenced ? "the task is handled as PII and the hub's model is not reached on campus, so it was not asked to name one" : "the hub could not name one for you"}`);
+    if (claiming) this.acceptanceCapacity({ id: -1, owner: by, state: "proposed" }, 1);
     let selected;
     try { selected = taskRole(input.role, cls, this.d.catalog ?? loadRoleCatalog(this.d.cwd)); }
     catch (error) { throw new PreEffectToolRefusal((error as Error).message); }
@@ -1086,7 +1129,40 @@ export class Tasks {
       return this.d.board.update(task.id, HUB, "blocked", {}, `waits for ${still.map((id) => `#${id}`).join(", ")}`);
     }
     // Naming yourself is a claim: the work is already yours, so no offer comes back to you (paper: Agensh CLAIM, #68).
-    return this.assignOwner(task, by, input.owner ? { candidates: [input.owner], namedOwner: input.owner, claim: input.owner === by } : {});
+    return await this.assignOwner(task, by, input.owner ? { candidates: [input.owner], namedOwner: input.owner, claim: input.owner === by } : {});
+    } finally {
+      if (claiming) {
+        const remaining = (this.pendingClaims.get(by) ?? 1) - 1;
+        if (remaining) this.pendingClaims.set(by, remaining); else this.pendingClaims.delete(by);
+      }
+    }
+  }
+
+  async returnUntouchedToBacklog(by: PeerId, input: { id: number; revision: number; reason: string }): Promise<Task> {
+    this.plannerWriteAuthority(by);
+    if (!Number.isSafeInteger(input.id) || input.id < 1 || !Number.isSafeInteger(input.revision) || input.revision < 0
+      || typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 1000) throw new PreEffectToolRefusal("untouched return needs an id, revision and bounded reason");
+    const validate = () => {
+      const task = this.need(input.id, false, true);
+      if (!["proposed", "in_progress"].includes(task.state) || (task.planningRevision ?? 0) !== input.revision || taskHasWorkEvidence(task)) throw new PreEffectToolRefusal("work has execution evidence or its planning revision changed");
+      if (by !== USER && task.pinned) throw new PreEffectToolRefusal("pinned work requires the person");
+      const release = task.release == null ? undefined : this.d.board.release(task.release);
+      if (release && (["shipped", "dropped"].includes(release.state) || by !== USER && release.state === "frozen")) throw new PreEffectToolRefusal("settled or frozen release scope cannot return");
+      return task;
+    };
+    const task = validate(), flow = task.history.length;
+    const withheld = await this.withholds("note", input.reason, task);
+    this.plannerWriteAuthority(by);
+    const confirmed = validate();
+    if (confirmed.history.length !== flow) throw new PreEffectToolRefusal("task changed during untouched return");
+    const returned = this.d.board.update(confirmed.id, by, "backlog returned untouched", { state: "backlog", owner: null, reviewer: null }, input.reason.trim(), { ...(withheld ? { withheld: true } : {}) }, flow);
+    this.offered.delete(confirmed.id);
+    this.cohorts.leave(confirmed.id);
+    this.withdrawRoleRequest(confirmed, returned, "owner");
+    this.withdrawRoleRequest(confirmed, returned, "reviewer");
+    this.incomingBacklog.add(confirmed.id);
+    this.planningRecorded({ by, task: confirmed.id, fields: ["return"], revision: confirmed.planningRevision ?? 0 });
+    return returned;
   }
 
   /** Person-owned staging only. Flow transitions remain with their existing owners and reviewers. */
@@ -1480,7 +1556,8 @@ export class Tasks {
   }
 
   private assignmentNote(note: string, assignment: Assignment): string {
-    return assignment.sameFamilyFallback ? `${note}; sameFamilyFallback=true` : note;
+    const tagged = assignment.sameFamilyFallback ? `${note}; sameFamilyFallback=true` : note;
+    return assignment.plannerFallback ? `${tagged}; reviewer=planner (fallback)` : tagged;
   }
 
   /** A later move to another owner means the caller's assignment was superseded, so its success tail is not authoritative. */
@@ -1495,6 +1572,24 @@ export class Tasks {
   /** `override`: a person's explicit assign, which past refusals do not block and which drops an agent's reservation (#207). */
   private async assignOwner(task: Task, by: PeerId, opts: { candidates?: PeerId[]; namedOwner?: PeerId; event?: string; note?: string; reason?: TaskMoveReason; clearOnFail?: boolean; exclude?: PeerId[]; context?: string; contextWithheld?: boolean; claim?: boolean; override?: boolean; roster?: boolean; planner?: boolean; expectedFlowRevision?: number } = {}): Promise<Task> {
     if (task.state === "backlog") throw new PreEffectToolRefusal(`task #${task.id}: pull backlog work before assigning it`);
+    const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
+    let stagedClaimGap: string | undefined;
+    if (mode !== "off" && this.isBuildTask(task)) {
+      const gap = task.sdlc?.planReview ? await this.planReviewGap(task) : "plan not reviewed since proposal";
+      const current = this.d.board.get(task.id);
+      if (!current || !this.ownerAssignmentCurrent(task, current)) return current ?? task;
+      task = current; // Reviewer-only and quiet bookkeeping updates do not supersede ownership authority.
+      if (gap) {
+        this.releaseNotice(`task ${this.publicTitle(current)}: ${gap}; planner: call hub_planner_groom then hub_plan_review`);
+        if (mode === "enforce") {
+          if (opts.claim && opts.namedOwner === by) stagedClaimGap = gap;
+          else {
+            this.reportStall(current, { kind: "no-eligible-peer", code: "policy" });
+            return current;
+          }
+        }
+      }
+    }
     const waits = this.waitsFor(task);
     const plannedMove = opts.planner || this.plannerPullRecord(task)?.pull === true && (by === HUB || opts.roster) && (opts.reason !== "manual" || opts.roster);
     const plannerFull = plannedMove ? this.plannerFull(task) : [];
@@ -1566,6 +1661,13 @@ export class Tasks {
     }
     // A claim is its own hand-over, with no delivery: its accepted write and its line stay as they were (#297).
     if (opts.claim && a.owner === by) {
+      // #481 S1: a claim of build work starts it only from an accepted spec. In enforce the claim stays an assignment
+      // (owner set, still proposed); hub_task_accept starts it once the person accepted the spec.
+      if (this.specGated(next) && specState(next.sdlc, undefined) === "missing") {
+        if (this.d.sdlc?.config().mode === "enforce") { this.releaseNotice(`${this.specText(next, "missing", "blocked")}; the claim stays assigned to ${by}`); return next; }
+        this.releaseNotice(this.specText(next, "missing", "advice"));
+      }
+      if (stagedClaimGap) return next; // An explicit claim may reserve its owner, but no offer or acceptance bypasses review.
       const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
       this.releaseNotice(`task ${this.publicTitle(claimed)} claimed by ${by}`);
       return claimed;
@@ -1835,6 +1937,154 @@ export class Tasks {
     if (by !== USER && task[role] !== by) throw new (preEffect ? PreEffectToolRefusal : Error)(`task #${task.id}: only its ${role} (${task[role] ?? "none"}) or the console user can do that`);
   }
 
+  private planIssueIdentity(task: Task): { repo: string; issue: number } | undefined {
+    const source = task.external ?? task.sdlc;
+    if (source?.repo && source.issue) return { repo: source.repo, issue: source.issue };
+    const repository = task.refs.repo ?? this.d.repository ?? "";
+    let issues: number[];
+    try { issues = specRefs(task, repository); }
+    catch { throw new PreEffectToolRefusal("plan review issue identity unavailable"); }
+    if (issues.length > 1) throw new PreEffectToolRefusal("plan review needs one explicit issue identity");
+    return issues[0] ? { repo: repository, issue: issues[0] } : undefined;
+  }
+
+  async groomingDigest(by: PeerId): Promise<Record<string, unknown>> {
+    this.planningAuthority(by);
+    const included = (task: Task) => !isClosedTaskState(task.state) || task.state === "cancelled" && task.history.some(entry => !!entry.supersededBy);
+    const snapshot = this.d.board.list().filter(included), issues = new Map<string, PlanIssueMetadata>(), attempted = new Set<string>();
+    const deadline = performance.now() + 4_000;
+    let reads = 0, incomplete = false;
+    // ponytail: at most eight metadata reads within four seconds; add paginated revision-bound readback for larger boards.
+    for (const listed of snapshot) {
+      this.planningAuthority(by);
+      const task = this.d.board.get(listed.id);
+      if (!task || this.isPii(task) || isClosedTaskState(task.state)) continue;
+      let source: { repo: string; issue: number } | undefined;
+      try { source = this.planIssueIdentity(task); } catch { continue; }
+      if (!source) continue;
+      const key = `${source.repo.toLowerCase()}#${source.issue}`;
+      if (attempted.has(key)) continue;
+      attempted.add(key);
+      if (reads >= 8 || performance.now() >= deadline) { incomplete = true; break; }
+      reads++;
+      const run = this.d.sdlc?.gh ?? sdlcGh;
+      const issue = await readPlanIssueMetadata(source.repo, source.issue, (args, timeout, cwd, cap) => run(args, Math.max(1, Math.min(timeout ?? 10_000, deadline - performance.now())), cwd, cap));
+      if (issue) issues.set(key, issue);
+    }
+    this.planningAuthority(by);
+    const current = this.d.board.list().filter(included), visible = current.filter(task => !this.isPii(task));
+    const peers = [...new Set([...Object.keys(this.states()), ...current.flatMap(task => task.owner ? [task.owner] : [])])];
+    const reviewedIssues = new Map(visible.flatMap(task => task.sdlc?.planReview?.issue ? [[task.id, task.sdlc.planReview.issue] as const] : []));
+    const acceptedIssues = new Map(visible.flatMap(task => task.sdlc?.acceptance ? [[task.id, task.sdlc.acceptance] as const] : []));
+    const blockers: { task: number; code: string }[] = this.d.board.stalls().map(stall => ({ task: stall.task, code: stall.cause.code }));
+    const health = this.health(), states = this.states(), routing = this.d.routing(), hostBlocks = this.d.plannerBlocks?.() ?? {};
+    for (const task of visible.filter(task => !isClosedTaskState(task.state)).slice(0, 500)) {
+      const owner = task.owner ?? task.reserved;
+      if (owner) for (const code of peerEntry(hostBlocks, owner) ?? []) blockers.push({ task: task.id, code });
+      const result = assign(task.state === "backlog" ? { ...task, state: "proposed" } : task, states, routing, { ...health, waitsFor: this.waitsFor(task), ...(owner ? { candidates: [owner], namedOwner: owner } : {}) });
+      if (!result.owner) for (const refusal of result.refusals ?? []) if (refusal.role === "owner") blockers.push({ task: task.id, code: refusal.code === "instance" || refusal.code === "family" ? "policy" : refusal.code });
+      if (this.waitsFor(task).length) blockers.push({ task: task.id, code: "dependency" });
+    }
+    const digest = plannerGrooming(visible, { repository: this.d.repository ?? `path:${realPath(this.d.cwd)}`,
+      limits: Object.fromEntries(peers.map(peer => [peer, this.wipLimit(peer)])), wip: Object.fromEntries(peers.map(peer => [peer, this.wip(peer)])),
+      states, issues, reviewedIssues, acceptedIssues, blockers });
+    return { ...digest, truncated: digest.truncated || incomplete, ...(current.some(task => this.isPii(task)) ? { privateTasks: "withheld" } : {}) };
+  }
+
+  /** S10 read-only planner report; S7 owns rolling bands and automatic board proposals. */
+  async costReport(by: PeerId, repository?: unknown): Promise<Record<string, unknown>> {
+    const authority = () => {
+      this.planningAuthority(by);
+      if (by !== USER && this.d.privateTurn?.(by)) throw new PreEffectToolRefusal("cost report unavailable during private work");
+    };
+    authority();
+    const repo = repository ?? this.d.repository;
+    if (typeof repo !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || repo.startsWith("-") || !this.nameable(repo)) throw new PreEffectToolRefusal("cost report requires a public owner/repository identity");
+    const deadline = performance.now() + 20_000;
+    const bounded = (args: string[], timeout?: number, cwd?: string, cap?: number) => performance.now() < deadline
+      ? (this.d.sdlc?.gh ?? sdlcGh)(args, Math.max(1, Math.min(timeout ?? 10_000, deadline - performance.now())), cwd, cap)
+      : Promise.resolve({ code: 1, stdout: "" });
+    const linked = () => this.d.board.list().filter(task => task.sdlc?.repo?.toLowerCase() === repo.toLowerCase() && Number.isSafeInteger(task.sdlc.pr) && task.sdlc.pr! > 0);
+    const ids = [...new Set(linked().filter(task => !this.isPii(task)).map(task => task.sdlc!.pr!))].sort((a, b) => a - b);
+    const observations: import("./cost-governance.ts").CostPr[] = [];
+    let incomplete = ids.length > 16;
+    for (const pr of ids.slice(0, 16)) {
+      authority();
+      if (linked().some(task => task.sdlc?.pr === pr && this.isPii(task))) continue;
+      if (performance.now() >= deadline) { incomplete = true; break; }
+      const evidence = await readPrCostHistory(repo, pr, (args, timeout, cwd, cap) => {
+        authority();
+        const fresh = linked().filter(task => task.sdlc?.pr === pr);
+        if (!fresh.length || fresh.some(task => this.isPii(task))) return Promise.resolve({ code: 1, stdout: "" });
+        return bounded(args, timeout, cwd, cap);
+      });
+      if (evidence) observations.push(evidence); else incomplete = true;
+    }
+    authority();
+    const current = linked();
+    const visiblePrs = new Set(current.filter(task => !this.isPii(task)).map(task => task.sdlc!.pr!));
+    for (const task of current) if (this.isPii(task)) visiblePrs.delete(task.sdlc!.pr!);
+    if (JSON.stringify([...visiblePrs].sort((a, b) => a - b)) !== JSON.stringify(ids)) incomplete = true;
+    const report = costMetrics(current.map(task => ({ repo, pr: task.sdlc!.pr!, private: this.isPii(task), history: task.history })), observations.filter(pr => visiblePrs.has(pr.pr)));
+    return { ...report, truncated: report.truncated || incomplete, ...(current.some(task => this.isPii(task)) ? { privateTasks: "withheld" } : {}), bands: "S7 pending" };
+  }
+
+  async planReviewGap(task: Task): Promise<string | undefined> {
+    const receipt = task.sdlc?.planReview;
+    if (!receipt) return "plan not reviewed since proposal";
+    if (!receipt.planner || !Number.isFinite(receipt.recordedAt) || receipt.planningRevision !== (task.planningRevision ?? 0)) return "plan not reviewed since planning revision change";
+    if (receipt.scope && JSON.stringify(receipt.scope) !== JSON.stringify(cleanCostPlan(task.plan ?? {}))) return "plan not reviewed since cost scope change";
+    const identity = this.planIssueIdentity(task);
+    if (identity?.issue && this.isPii(task)) return "private issue plan review evidence unavailable";
+    if (!identity?.issue) return receipt.issue ? "plan not reviewed since issue identity change" : undefined;
+    if (!identity.repo || typeof receipt.issue?.repo !== "string" || receipt.issue.repo.toLowerCase() !== identity.repo.toLowerCase() || receipt.issue.issue !== identity.issue) return "plan not reviewed since issue identity change";
+    const current = await readPlanIssueMetadata(identity.repo, identity.issue, this.d.sdlc?.gh ?? sdlcGh);
+    if (!current) return "plan review issue metadata unavailable";
+    if (current.state !== "OPEN") return "plan review issue is closed";
+    return current.editedAt !== receipt.issue.editedAt ? "plan not reviewed since issue edit" : undefined;
+  }
+
+  /** Planner authority and issue edit evidence are rechecked across every external await. */
+  async recordPlanReview(by: PeerId, id: unknown, input: unknown): Promise<Task> {
+    this.plannerWriteAuthority(by);
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new PreEffectToolRefusal("plan review needs a revision and reason");
+    const raw = input as Record<string, unknown>;
+    if (Object.keys(raw).some(key => !["revision", "reason", "review", "ci"].includes(key)) || !Number.isSafeInteger(raw.revision) || (raw.revision as number) < 0
+      || typeof raw.reason !== "string" || !raw.reason.trim() || raw.reason.length > 1000) throw new PreEffectToolRefusal("plan review needs a current revision and bounded reason");
+    const task = this.need(id, false, true, true), revision = raw.revision as number;
+    if (isClosedTaskState(task.state)) throw new PreEffectToolRefusal("closed work is final");
+    if ((task.planningRevision ?? 0) !== revision) throw new PreEffectToolRefusal("planning revision changed");
+    let scope: CostPlan;
+    try { scope = cleanCostPlan({ ...task.plan, ...("review" in raw ? { review: raw.review } : {}), ...("ci" in raw ? { ci: raw.ci } : {}) }); }
+    catch { throw new PreEffectToolRefusal("invalid review or CI cost scope"); }
+    const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
+    if (!scope.review || !scope.ci) {
+      if (mode === "enforce") throw new PreEffectToolRefusal("review and CI cost scope required for a new plan receipt");
+      if (mode === "advise") this.releaseNotice(`task ${this.publicTitle(task)}: cost scope unspecified`);
+    }
+    const flow = task.history.length, withheld = await this.withholds("note", raw.reason, task);
+    this.plannerWriteAuthority(by);
+    const observed = this.need(task.id, false, true, true);
+    if (observed.history.length !== flow || (observed.planningRevision ?? 0) !== revision) throw new PreEffectToolRefusal("plan review changed during readback");
+    const identity = this.planIssueIdentity(observed);
+    if (identity?.issue && this.isPii(observed)) throw new PreEffectToolRefusal("private issue plan review readback unavailable");
+    const issue = identity?.repo && identity.issue ? await readPlanIssueMetadata(identity.repo, identity.issue, this.d.sdlc?.gh ?? sdlcGh) : undefined;
+    if (identity?.issue && !issue) throw new PreEffectToolRefusal("plan review issue metadata unavailable");
+    if (issue && !this.isPii(task) && !this.nameable(JSON.stringify(issue))) throw new PreEffectToolRefusal("plan review metadata matches a PII pattern");
+    this.plannerWriteAuthority(by);
+    const current = this.need(task.id, false, true, true);
+    if (current.history.length !== flow || (current.planningRevision ?? 0) !== revision) throw new PreEffectToolRefusal("plan review changed during readback");
+    const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
+    const updated = this.d.board.update(current.id, by, "plan reviewed", { ...(Object.keys(scope).length ? { plan: { ...current.plan, ...scope } } : {}), sdlc: { ...current.sdlc, stage: current.sdlc?.stage ?? lifecycleStage(config, "plan"),
+      planReview: { planner: by, planningRevision: revision, recordedAt: Date.now(), ...(Object.keys(scope).length ? { scope } : {}), ...(issue ? { issue } : {}) } } }, raw.reason.trim(), { ...(withheld ? { withheld: true } : {}) }, flow);
+    if (updated.state === "proposed" && !updated.owner) {
+      this.offered.delete(updated.id);
+      try { await this.offerReady(updated, "planner review recorded"); }
+      catch { this.releaseNotice(`task #${updated.id}: plan review saved; inspect its owner delivery before retrying`); }
+    }
+    return this.d.board.get(updated.id) ?? updated;
+  }
+
   /** Artifact links and claimed local gates stay on the board; no outside text is accepted. */
   recordLifecycle(by: PeerId, id: unknown, input: unknown): Task {
     const task = this.need(id, false, true);
@@ -1842,6 +2092,8 @@ export class Tasks {
     const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
     const next = sdlcReceipt(input, task.sdlc, config, VERSION);
     const definition = stageDefinition(config, next.stage);
+    // #481 S1: entering a build stage in enforce needs the person's spec acceptance; the person may move any stage.
+    if (config.mode === "enforce" && by !== USER && next.stage !== task.sdlc?.stage && definition && canonicalStage(definition.base) === "build" && specState(next, undefined) === "missing") throw new PreEffectToolRefusal(this.specText(task, "missing", "blocked"));
     if (config.mode === "enforce" && config.definitions && input && typeof input === "object" && "stage" in input && next.stage !== task.sdlc?.stage && by !== USER) {
       const actor = definition?.actor;
       const acts = actor === "owner" ? by === task.owner : actor === "reviewer" ? by === task.reviewer : actor === "planner" ? this.d.roles?.[by]?.includes("planner") : actor === "owner/planner" && (by === task.owner || this.d.roles?.[by]?.includes("planner"));
@@ -1900,20 +2152,93 @@ export class Tasks {
   async lifecycleStatus(id: unknown, refresh = true): Promise<SdlcStatus> {
     const task = this.need(id), config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
     const evidence = task.sdlc && !this.isPii(task) && refresh && config.mode !== "off" ? await readSdlcPr(task.sdlc, this.d.sdlc?.gh) : undefined;
-    return sdlcStatus(config, task.sdlc, evidence, this.workflowView(task));
+    const accepted = task.sdlc?.acceptance;
+    const edit = accepted && !this.isPii(task) && refresh && config.mode !== "off" ? await readSpecEdit(accepted.repo, accepted.issue, this.d.sdlc?.gh) : undefined;
+    return sdlcStatus(config, task.sdlc, evidence, this.workflowView(task), edit);
+  }
+
+  /** #481 S1: only build work starts from an accepted spec. */
+  private specGated(task: Task): boolean {
+    return (this.d.sdlc?.config().mode ?? "off") !== "off" && (task.class === "implement" || task.class === "bulk_edit");
+  }
+  private specText(task: Task, state: Exclude<SpecState, "current">, verb: "blocked" | "advice"): string {
+    const issue = task.sdlc?.issue;
+    const why = issue ? SPEC_STATE_TEXT[state].replace("<task>", String(task.id)).replace("<n>", String(issue)) : "spec issue unknown: record repo and issue with hub_sdlc_record, then the person accepts it with ahub sdlc accept";
+    return `task #${task.id}: SDLC build entry ${verb}: ${why}`;
   }
 
-  private async lifecycleGate(task: Task, transition: "review" | "approval", reviewedHead?: string): Promise<void> {
+  /** The person's acceptance of the task's spec issue at its current body (#481 S1); identity and edit times only. */
+  acceptSpec(by: PeerId, id: unknown, spec: { repo?: unknown; issue: unknown; edit: SpecEdit }): Task {
+    if (by !== USER) throw new PreEffectToolRefusal("spec acceptance is the person's: run ahub sdlc accept in a terminal");
+    const task = this.need(id, false, true, true), config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
+    const repo = spec.repo ?? task.sdlc?.repo;
+    if (task.sdlc?.issue !== undefined && task.sdlc.issue !== spec.issue) throw new PreEffectToolRefusal(`task #${task.id} links issue #${task.sdlc.issue}; relink it with hub_sdlc_record before accepting another`);
+    const next = sdlcReceipt({ repo, issue: spec.issue }, task.sdlc, config);
+    if (!next.repo || !next.issue) throw new PreEffectToolRefusal("spec acceptance needs the repository (owner/repository) and the issue number");
+    next.acceptance = { repo: next.repo, issue: next.issue, lastEditedAt: spec.edit.lastEditedAt, updatedAt: spec.edit.updatedAt, acceptedAt: Date.now() };
+    return this.d.board.update(task.id, USER, "spec accepted", { sdlc: next }, `issue #${next.issue}, body last edited ${spec.edit.lastEditedAt ?? "never"}`);
+  }
+
+  /** Build entry with a live readback of the spec's body edit time (#481 S1): enforce refuses, advise notifies, off does nothing. */
+  async specGate(by: PeerId, id: unknown): Promise<void> {
+    const task = this.need(id, false, true);
+    if (!this.specGated(task) || task.owner !== by && by !== USER) return; // accept reports its own refusals
+    const accepted = task.sdlc?.acceptance;
+    const edit = accepted && !this.isPii(task) ? await readSpecEdit(accepted.repo, accepted.issue, this.d.sdlc?.gh) : undefined;
+    if (this.specMoved(task)) return;
+    this.specVerdict(task, task.sdlc?.issue ? specState(task.sdlc, edit) : "missing");
+  }
+
+  /** #481 S1: a build stage change by an agent re-reads the body edit time first, as accept does. */
+  async specStageGate(by: PeerId, id: unknown, input: unknown): Promise<void> {
+    const task = this.need(id, false, true), config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
+    if (config.mode === "off" || by === USER || !input || typeof input !== "object" || !("stage" in input)) return;
+    let next: ReturnType<typeof sdlcReceipt>;
+    try { next = sdlcReceipt(input, task.sdlc, config, VERSION); } catch { return; } // recordLifecycle reports an invalid receipt
+    const definition = stageDefinition(config, next.stage);
+    if (next.stage === task.sdlc?.stage || !definition || canonicalStage(definition.base) !== "build") return;
+    const accepted = next.acceptance;
+    const edit = accepted && !this.isPii(task) ? await readSpecEdit(accepted.repo, accepted.issue, this.d.sdlc?.gh) : undefined;
+    if (this.specMoved(task)) return;
+    this.specVerdict(task, next.issue ? specState(next, edit) : "missing");
+  }
+
+  /**
+   * The task a spec readback started from changed while it was awaited (flow, link, acceptance, owner or privacy): the
+   * reading belongs to other work. Enforce refuses before any write; advise drops the stale advice.
+   */
+  private specMoved(before: Task): boolean {
+    const now = this.need(before.id, false, true);
+    if (now.history.length === before.history.length && now.owner === before.owner && this.isPii(now) === this.isPii(before)
+      && JSON.stringify(now.sdlc ?? null) === JSON.stringify(before.sdlc ?? null)) return false;
+    if (this.d.sdlc?.config().mode === "enforce") throw new PreEffectToolRefusal(`task #${before.id}: changed during the spec readback; nothing was recorded, retry on current work`);
+    return true;
+  }
+  private specVerdict(task: Task, state: SpecState): void {
+    if (state === "current") return;
+    if (this.d.sdlc?.config().mode === "enforce") throw new PreEffectToolRefusal(this.specText(task, state, "blocked"));
+    this.d.notify(this.specText(task, state, "advice"));
+  }
+
+  private async lifecycleGate(task: Task, transition: "review" | "approval", reviewedHead?: string): Promise<PrEvidence | undefined> {
     const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
     if (config.mode === "off") return;
     const receipt = task.sdlc && { ...task.sdlc, ...(reviewedHead ? { reviewedHead } : {}) };
-    const evidence = receipt && !this.isPii(task) ? await readSdlcPr(receipt, this.d.sdlc?.gh) : undefined;
+    const read: SdlcGh = (args, timeout, cwd, cap) => {
+      const current = this.need(task.id, false, true);
+      if (current.history.length !== task.history.length || current.owner !== task.owner || current.reviewer !== task.reviewer || this.isPii(current) !== this.isPii(task)) return Promise.resolve({ code: 1, stdout: "" });
+      return (this.d.sdlc?.gh ?? sdlcGh)(args, timeout, cwd, cap);
+    };
+    const evidence = receipt && !this.isPii(task) ? await readSdlcPr(receipt, read) : undefined;
     const current = this.need(task.id, false, true);
     if (config.mode === "enforce" && (current.history.length !== task.history.length || current.owner !== task.owner || current.reviewer !== task.reviewer || current.state !== task.state)) throw new PreEffectToolRefusal(`task #${task.id}: changed during lifecycle readback; retry on current work`);
+    // Advise may continue on the current task, but evidence from its previous link cannot admit that task's review.
+    if (current.history.length !== task.history.length || current.owner !== task.owner || current.reviewer !== task.reviewer || current.state !== task.state || this.isPii(current) !== this.isPii(task)) return;
     const status = sdlcStatus(config, receipt, evidence, this.workflowView(current));
     const blockers = transition === "review" ? [...new Set([...status.blockers.filter(blocker => ["lifecycle stage definition unknown", "issue identity missing", "PR identity missing", "current PR evidence unknown", "PR is not open", "local gate on current head missing or failed"].includes(blocker)), ...(status.entry ?? []), ...(status.exit ?? [])])] : status.blockers;
     if (config.mode === "enforce" && blockers.length) throw new PreEffectToolRefusal(`task #${task.id}: SDLC ${transition} blocked: ${blockers.join("; ")}`);
     if (config.mode === "advise" && blockers.length) this.d.notify(`task ${this.publicTitle(task)}: SDLC ${transition} advice: ${this.isPii(task) ? "private lifecycle evidence unknown" : blockers.join("; ")}`);
+    return evidence;
   }
 
   private need(id: unknown, open = false, preEffect = false, allowBacklog = false): Task {
@@ -1928,6 +2253,62 @@ export class Tasks {
     return task;
   }
 
+  private readonly pendingClaims = new Map<PeerId, number>();
+  private readonly reviewedAdmissions = new Map<number, { flow: number; owner: string | null }>();
+  private isBuildTask(task: Task): boolean {
+    const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
+    if (["implement", "bulk_edit"].includes(task.class)) return true;
+    const base = task.sdlc ? stageDefinition(config, task.sdlc.stage)?.base : undefined;
+    return base === "build" || base === "implement";
+  }
+  async acceptReviewed(by: PeerId, id: unknown, plan?: unknown): Promise<Task> {
+    const task = this.need(id, false, true);
+    this.mine(task, by, "owner", true);
+    this.acceptanceCapacity(task);
+    if ((this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode === "off" || !this.isBuildTask(task)) return this.accept(by, id, plan);
+    await this.specGate(by, id);
+    await this.planEntryGate(by, task);
+    const current = this.need(id, false, true);
+    this.mine(current, by, "owner", true);
+    if (current.history.length !== task.history.length || current.owner !== task.owner) throw new PreEffectToolRefusal("task changed during build admission");
+    this.reviewedAdmissions.set(current.id, { flow: current.history.length, owner: current.owner });
+    try { return this.accept(by, id, plan); }
+    finally { this.reviewedAdmissions.delete(current.id); }
+  }
+
+  /** Spec and plan readbacks share the caller's original task snapshot until the final acceptance write. */
+  private async planEntryGate(by: PeerId, task: Task): Promise<void> {
+    const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
+    if (mode === "off" || !this.isBuildTask(task)) return;
+    const gap = await this.planReviewGap(task);
+    if (mode === "advise" && !task.sdlc?.planReview?.scope) this.releaseNotice(`task ${this.publicTitle(task)}: cost scope unspecified`);
+    const current = this.need(task.id, false, true);
+    this.mine(current, by, "owner", true);
+    if (current.history.length !== task.history.length || current.owner !== task.owner) throw new PreEffectToolRefusal("task changed during plan readback");
+    if (gap && mode === "enforce") throw new PreEffectToolRefusal(gap);
+    if (gap) this.releaseNotice(`task ${this.publicTitle(current)}: ${gap}`);
+  }
+
+  private acceptanceCapacity(task: Pick<Task, "id" | "owner" | "reserved" | "state"> & Partial<Pick<Task, "history">>, excludePending = 0): void {
+    const owner = task.owner ?? task.reserved;
+    if (!owner) return;
+    if ((task.state === "in_progress" || task.state === "changes_requested") && task.history) {
+      let boundary = 0, previous: PeerId | null | undefined;
+      task.history.forEach((entry, index) => {
+        if (entry.owner !== undefined) {
+          if (entry.owner !== previous) boundary = index;
+          previous = entry.owner;
+        } else if (OWNERSHIP_EVENTS.has(entry.event)) { boundary = index; previous = undefined; }
+      });
+      if (task.history.slice(boundary).some(entry => entry.event === "accepted" && (entry.by === owner || entry.by === USER))) return;
+    }
+    const limit = this.wipLimit(owner), pending = Math.max(0, (this.pendingClaims.get(owner) ?? 0) - excludePending);
+    if (this.wip(owner, task.id) + pending < limit) return;
+    const open = this.d.board.list().filter(other => other.id !== task.id && !["backlog", "approved", "cancelled"].includes(other.state)
+      && (other.owner === owner || !other.owner && other.reserved === owner && this.plannerPullRecord(other)?.pull)).map(other => `#${other.id}`);
+    throw new PreEffectToolRefusal(`planner WIP capacity for ${owner}: limit ${limit}; open tasks ${open.join(", ") || "none"}${pending ? `; pending claims ${pending}` : ""}`);
+  }
+
   /**
    * With a plan, the owners of overlapping tasks get it as a ride-along line, and an overlap only the plan reveals is
    * announced like one found at assignment (issue #31).
@@ -1937,9 +2318,24 @@ export class Tasks {
     this.mine(task, by, "owner", true);
     this.ready(task, true);
     if (task.state !== "proposed" && task.state !== "changes_requested" && task.state !== "in_progress") throw new PreEffectToolRefusal(`task #${task.id} is ${task.state}: cannot move to in_progress`);
+    this.acceptanceCapacity(task);
+    // S1 spec acceptance and S9 plan review are independent prerequisites; retain S1's missing-spec refusal first.
+    if (this.specGated(task) && this.d.sdlc?.config().mode === "enforce" && specState(task.sdlc, undefined) === "missing") throw new PreEffectToolRefusal(this.specText(task, "missing", "blocked"));
+    if ((this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode === "enforce" && this.isBuildTask(task)) {
+      const readback = this.reviewedAdmissions.get(task.id);
+      this.reviewedAdmissions.delete(task.id);
+      if (!readback || readback.flow !== task.history.length || readback.owner !== task.owner) throw new PreEffectToolRefusal("current plan-review readback required before acceptance");
+    }
     // Models send null or {} for an optional field they leave empty: neither replaces a plan.
     const given = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
-    const cleaned = given && Object.keys(given).length ? given : undefined;
+    // File-list intent still replaces the old lists; omitted budget keys retain the planner-reviewed scope.
+    const cleaned = given && Object.keys(given).length ? { ...cleanCostPlan(task.plan ?? {}), ...given } : undefined;
+    if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview && !task.sdlc.planReview.scope
+      && given && Object.keys(cleanCostPlan(given)).length) throw new PreEffectToolRefusal("legacy plan cost scope is unspecified; record a scoped planner review before acceptance");
+    if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview?.scope
+      && JSON.stringify(cleanCostPlan(cleaned ?? task.plan ?? {})) !== JSON.stringify(task.sdlc.planReview.scope)) {
+      throw new PreEffectToolRefusal("plan cost scope changed; record a new planner review before acceptance");
+    }
     // A task's signals are fixed when it is proposed: text that matches a PII pattern cannot be let in afterwards.
     if (cleaned && !this.isPii(task) && this.isPii({ signals: this.signalsFor({ title: "", detail: planText(cleaned), refs: {}, plan: cleaned }) })) {
       throw new PreEffectToolRefusal("this plan matches a PII pattern and is not kept: other owners would see it");
@@ -2029,6 +2425,7 @@ export class Tasks {
       this.mine(t, by, "owner", true);
       if (t.state === "in_review" || isClosedTaskState(t.state)) throw new PreEffectToolRefusal(`task #${t.id} is already ${t.state}`);
       this.ready(t, true);
+      if (t.state === "proposed" || t.state === "changes_requested") this.acceptanceCapacity(t);
       if (this.checking.has(t.id)) {
         // The result goes only to the owner the check was started for: anyone who took the task since hears nothing.
         throw new PreEffectToolRefusal(this.checking.get(t.id) === t.owner ? `task #${t.id}: its check is still running; its result comes as a task message` : `task #${t.id}: a check from before it changed hands is still running; call hub_task_done again in a few minutes`);
@@ -2038,7 +2435,17 @@ export class Tasks {
     // The PII screen reads the summary of a done that passes these checks (issue #198); they run again after it.
     const withheld = await this.withholds("summary", summary, valid());
     let task = valid();
-    if (this.d.sdlc && this.d.sdlc.config().mode !== "off") { await this.lifecycleGate(task, "review"); task = valid(); }
+    // #481 S1: done without a separate accept starts build work too: the same live spec check as accept, before any write.
+    if (task.state === "proposed" || task.state === "changes_requested") {
+      const admission = task;
+      await this.specGate(by, task.id);
+      await this.planEntryGate(by, admission);
+      task = valid();
+    }
+    let reviewEvidence: PrEvidence | undefined;
+    if (this.d.sdlc && this.d.sdlc.config().mode !== "off") { reviewEvidence = await this.lifecycleGate(task, "review"); task = valid(); }
+    const reviewAdmission = task.reviewer ? await this.reviewRequestAdmission(task, refs, true, by, reviewEvidence) : undefined;
+    task = valid();
     // A member of a silent cohort (issue #107): its done is an intent, and the last of them integrates first.
     const cohort = this.cohorts.of(task.id);
     const silentMember = !!cohort?.silent && this.turnFree() && !!task.owner && !this.isPii(task);
@@ -2069,7 +2476,7 @@ export class Tasks {
     }
     if (task.state === "proposed" || task.state === "changes_requested") task = this.d.board.update(task.id, by, "accepted", { state: "in_progress" }, WITH_DONE); // done without a separate accept
     const command = this.d.runCheck ? this.d.check?.(task.class, task) : undefined;
-    if (!command) return this.complete(task, by, summary, refs, "", withheld, "review");
+    if (!command) return this.complete(task, by, summary, refs, "", withheld, "review", reviewAdmission);
     // The tool call returns now; a check can outlast an agent's tool timeout. The result decides what comes next.
     this.checking.set(task.id, task.owner);
     const pending = this.d.board.update(task.id, by, "done (checking)", { refs: cleanRefs(refs) }, summary, { withheld: withheld || undefined });
@@ -2196,17 +2603,27 @@ export class Tasks {
   }
 
   /** `gated`: the transition `done()` already gated with no await since, so it is not read back twice (#382). */
-  private async complete(task: Task, by: PeerId, summary?: string, refs?: TaskRefs, checkOutput = "", withheld = false, gated?: "review"): Promise<Task> {
-    let reviewer = task.reviewer;
+  private async complete(task: Task, by: PeerId, summary?: string, refs?: TaskRefs, checkOutput = "", withheld = false, gated?: "review", admission?: ReviewReadiness): Promise<Task> {
+    let reviewer = task.reviewer, reviewEvidence: PrEvidence | undefined;
     if (this.d.sdlc && this.d.sdlc.config().mode !== "off" && gated !== (reviewer ? "review" : "approval")) {
-      await this.lifecycleGate(task, reviewer ? "review" : "approval");
+      reviewEvidence = await this.lifecycleGate(task, reviewer ? "review" : "approval");
       task = this.need(task.id, false, true);
       this.mine(task, by, "owner", true);
       // In every mode: another done may have landed during the readback.
       if (task.state === "in_review" || isClosedTaskState(task.state)) throw new Error(`task #${task.id} is already ${task.state}`);
       reviewer = task.reviewer;
     }
-    const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", ...(task.sdlc ? { sdlc: { ...task.sdlc, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), reviewer ? "review" : "merge") } } : {}), refs: cleanRefs(refs) }, checkOutput ? `${summary ?? ""}\n${checkOutput}`.trim() : summary, { withheld: withheld || undefined });
+    // A delayed local check needs a new readback; the immediate done path already admitted before effects.
+    if (reviewer && !admission && (this.d.sdlc?.config().mode ?? "off") !== "off") {
+      const observed = task;
+      admission = await this.reviewRequestAdmission(task, refs, false, by, reviewEvidence);
+      task = this.need(task.id);
+      this.mine(task, by, "owner");
+      if (task.history.length !== observed.history.length || task.state === "in_review" || isClosedTaskState(task.state)) throw new Error("task changed during review admission");
+    }
+    const reviewCost: ReviewCost | undefined = reviewer && task.plan && (task.plan.review || task.plan.ci)
+      ? { ...cleanCostPlan(task.plan), ...(admission?.ready && admission.head ? { head: admission.head } : {}) } : undefined;
+    const next = this.d.board.update(task.id, by, "done", { state: reviewer ? "in_review" : "approved", ...(task.sdlc ? { sdlc: { ...task.sdlc, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), reviewer ? "review" : "merge") } } : {}), refs: cleanRefs(refs) }, checkOutput ? `${summary ?? ""}\n${checkOutput}`.trim() : summary, { withheld: withheld || undefined, ...(reviewCost ? { reviewCost } : {}) });
     this.cohorts.closed(next.id); // its owner's next native turn end settles it in its cohort (issue #107)
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`, withheld);
     this.tellCompleted(next, summary, withheld);
@@ -2217,7 +2634,7 @@ export class Tasks {
       await this.releaseDependents(next);
     }
     else if (reviewer === USER) this.releaseNotice(`task ${this.publicTitle(next)} done by ${by}: review it with ahub task show ${next.id}, then ahub review ${next.id} approved|changes_requested [note]`);
-    else this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${reviewer}`, () => this.sendReview(next, reviewer));
+    else this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${reviewer}`, () => this.sendReview(next, reviewer, "", admission));
     return next;
   }
 
@@ -2291,7 +2708,44 @@ export class Tasks {
   }
 
   /** The one place a review request is written: the first reviewer and a replacement get the same text, refs and privacy. */
-  private sendReview(task: Task, reviewer: PeerId, why = ""): void {
+  /** Review admission is separate from brief construction (#228). All refusals precede the requesting done's writes. */
+  private async reviewRequestAdmission(task: Task, refs?: TaskRefs, preEffect = true, actor: PeerId = task.owner ?? USER, previous?: PrEvidence): Promise<ReviewReadiness | undefined> {
+    const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
+    if (mode === "off") return undefined;
+    const guard = () => {
+      if (actor !== USER && actor !== task.owner) {
+        const holders = Object.entries(this.d.roles ?? {}).filter(([, roles]) => Array.isArray(roles) && roles.includes("conductor")).map(([peer]) => peer);
+        if (holders.length !== 1 || holders[0] !== actor) throw new (preEffect ? PreEffectToolRefusal : Error)("review admission authority changed");
+      }
+      const current = this.need(task.id, false, preEffect);
+      if ((this.d.sdlc?.config().mode ?? "off") !== mode || current.history.length !== task.history.length || current.owner !== task.owner || current.reviewer !== task.reviewer
+        || this.isPii(current) !== this.isPii(task) || JSON.stringify(current.sdlc ?? null) !== JSON.stringify(task.sdlc ?? null)
+        || actor !== USER && this.d.privateTurn?.(actor) && !this.isPii(current)) throw new (preEffect ? PreEffectToolRefusal : Error)("task or authority changed during review admission");
+      return current;
+    };
+    guard();
+    const expected = cleanRefs(refs).commit ?? task.refs.commit ?? task.sdlc?.head ?? task.sdlc?.localHead;
+    const read: SdlcGh = (args, timeout, cwd, cap) => { guard(); return (this.d.sdlc?.gh ?? sdlcGh)(args, timeout, cwd, cap); };
+    const evidence: ReviewReadiness = this.isPii(task)
+      ? { ready: false, blockers: ["private review readiness unavailable"] }
+      : task.sdlc ? reviewReadinessFromEvidence(previous, expected, this.d.sdlc?.config().requiredChecks ?? []) ?? await readReviewReadiness(task.sdlc, expected, read, this.d.sdlc?.config().requiredChecks ?? []) : { ready: false, blockers: ["review PR identity missing"] };
+    const current = guard();
+    if (!evidence.ready) {
+      const message = `task ${this.publicTitle(current)}: premature review: ${evidence.blockers.join("; ")}`;
+      if (mode === "enforce") throw new (preEffect ? PreEffectToolRefusal : Error)(message);
+      this.releaseNotice(message);
+    }
+    return evidence;
+  }
+
+  private sendReview(task: Task, reviewer: PeerId, why = "", admission?: ReviewReadiness): void {
+    const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
+    if (mode === "enforce" && !admission?.ready) {
+      // Background roster/quota role changes are retained, but never invent a remotely admitted review request.
+      this.releaseNotice(`task ${this.publicTitle(task)}: premature review held; retry the reviewer assignment after current CI and bot replies are verified`);
+      return;
+    }
+
     const r = task.refs;
     const last = [...task.history].reverse().find((h) => h.event === "done");
     const where = [r.branch ? `branch ${r.branch}` : "", r.commit ? `commit ${r.commit}` : "", r.paths?.length ? `paths ${r.paths.join(", ")}` : ""].filter(Boolean).join("; ");
@@ -2305,18 +2759,41 @@ export class Tasks {
       `- ${check ? `Check result: ${(check.note ?? "").split("\n")[0]}` : "No check ran for this class: run the affected tests yourself."}`,
       `- List what is unmet in hub_review's unmet, one item each.`,
     ].join("\n");
-    const summary = last?.note ? this.screen(task, last.note, "summary", reviewer, last.withheld) : "(no summary)";
+    // #223 R2: a reviewer-only instance judges from facts; the builder's narrative stays out, earlier findings go in.
+    const reviewOnly = this.d.reviewOnly?.(reviewer) === true;
+    const summary = reviewOnly ? "(summary withheld from a review-only reviewer; judge the change itself)" : last?.note ? this.screen(task, last.note, "summary", reviewer, last.withheld) : "(no summary)";
+    const specRepo = task.sdlc?.repo ?? task.external?.repo, specIssue = task.sdlc?.issue ?? task.external?.issue;
+    const spec = reviewOnly && specRepo && specIssue ? `Spec issue: ${specRepo}#${specIssue}\n` : "";
+    const findings = reviewOnly ? task.history.filter(h => h.event === "changes_requested" && h.note).map(h => `- ${h.by}: ${this.screen(task, h.note!, "review note", reviewer, h.withheld)}`) : [];
     const guidance = this.roleGuidance(task, reviewer, true);
     let projection = "";
     try { const text = this.d.projectedReview?.(task); if (text) projection = this.screen(task, sanitize(text), "document projection", reviewer); }
     catch { projection = "(document projection unavailable)"; }
-    const body = `Review task #${task.id} [${profileTaskLabel(task)}] ${task.title}\nDone by ${last?.by ?? task.owner}: ${summary}\n${where ? `Where: ${where}\n` : ""}${why ? `${why}\n` : ""}${!plan && task.detail ? `Task detail:\n${task.detail}\n` : ""}${guidance ? guidance + "\n" : ""}${projection ? projection + "\n" : ""}${checklist}\nGive your verdict with hub_review {id: ${task.id}, verdict: "approved" | "changes_requested", note, unmet}.`;
+    const brief = this.briefText(task);
+    const body = `Review task #${task.id} [${profileTaskLabel(task)}] ${task.title}\nDone by ${last?.by ?? task.owner}: ${summary}\n${where ? `Where: ${where}\n` : ""}${spec}${why ? `${why}\n` : ""}${!plan && task.detail ? `Task detail:\n${task.detail}\n` : ""}${guidance ? guidance + "\n" : ""}${projection ? projection + "\n" : ""}${brief ? brief + "\n" : ""}${findings.length ? `Earlier findings (set a disposition for each):\n${findings.join("\n")}\n` : ""}${checklist}\nGive your verdict with hub_review {id: ${task.id}, verdict: "approved" | "changes_requested", note, unmet}.`;
     this.d.bus.publish(newEnvelope(HUB, body, { to: [reviewer], kind: "review", priority: "important", refs: { ...r, task: String(task.id) }, ...(this.isPii(task) ? { private: true } : {}) }));
   }
 
-  async review(by: PeerId, id: unknown, verdict: unknown, note?: string, unmet?: unknown, head?: unknown): Promise<Task> {
+  /** #520: the rendered review brief of a non-PII task's commit, or why there is none; empty without a commit. */
+  briefText(task: Task): string {
+    if (this.isPii(task) || !task.refs.commit) return "";
+    try {
+      const brief = this.d.reviewBrief?.(task);
+      if (!brief) return "";
+      return "unavailable" in brief ? `Review brief unavailable: ${brief.unavailable}.` : sanitize(renderReviewBrief(brief));
+    } catch { return "Review brief unavailable: it could not be built."; }
+  }
+
+  async review(by: PeerId, id: unknown, verdict: unknown, note?: string, unmet?: unknown, head?: unknown, coverage?: unknown): Promise<Task> {
+    const authority = by === USER ? undefined : this.d.reviewAuthority?.(by, Number(id));
+    // #520: what the coverage was checked against, pinned through every await: the commit and the lifecycle receipt (the
+    // inherited reviewedHead lives there).
+    let covered: { commit: string | undefined; receipt: string } | undefined;
     const valid = (): Task => {
+      const refused = authority?.();
+      if (refused) throw new PreEffectToolRefusal(refused); // rechecked after every await, right before each write
       const t = this.need(id, false, true);
+      if (covered && (t.refs.commit !== covered.commit || JSON.stringify(t.sdlc ?? null) !== covered.receipt)) throw new PreEffectToolRefusal(`task #${t.id}'s commit or lifecycle receipt changed during the verdict: review the new head`);
       this.mine(t, by, "reviewer", true);
       if (verdict !== "approved" && verdict !== "changes_requested") throw new PreEffectToolRefusal('verdict must be "approved" or "changes_requested"');
       if (t.state !== "in_review") throw new PreEffectToolRefusal(`task #${t.id} is ${t.state}: cannot move to ${verdict} before its owner calls hub_task_done`);
@@ -2324,6 +2801,34 @@ export class Tasks {
     };
     const items = textList(unmet);
     if (items.length) note = `${note ?? ""}\nUnmet: ${items.join("; ")}`.trim();
+    // #520: an approval accounts for every reviewable path of the brief. enforce refuses before any effect, advise records
+    // the gap in the verdict note, off and a person's own verdict skip it.
+    const mode = this.d.sdlc?.config().mode ?? "off";
+    // A Tasks without a brief provider (library use; the daemon always has one) has no coverage gate.
+    if (verdict === "approved" && by !== USER && mode !== "off" && this.d.reviewBrief) {
+      const t = valid(), enforce = mode === "enforce", list = (paths: string[]) => `${paths.slice(0, 20).join(", ")}${paths.length > 20 ? ", ..." : ""}`;
+      // Code work (a commit, branch or PR) needs a brief; work with none of them is exempt and has nothing to account for.
+      const code = !this.isPii(t) && !!(t.refs.commit || t.refs.branch || t.sdlc?.pr);
+      // The commit under review: the task's, else the head the verdict names, else the lifecycle receipt's.
+      const commit = t.refs.commit ?? (typeof head === "string" ? head : undefined) ?? t.sdlc?.reviewedHead ?? t.sdlc?.localHead;
+      const brief: ReviewBrief | { unavailable: string } | undefined = !code ? undefined
+        : !commit ? { unavailable: "the task links a branch or PR but names no commit" }
+        : this.d.reviewBrief({ ...t, refs: { ...t.refs, commit } }) ?? { unavailable: "the review brief could not be built" };
+      if (brief && "unavailable" in brief) {
+        // An unknown inventory is never an empty one.
+        if (enforce) throw new PreEffectToolRefusal(`coverage: the review brief is unavailable (${brief.unavailable}); an approval needs a complete brief of the task's commit`);
+        note = `${note ?? ""}\nCoverage unknown: the review brief is unavailable (${brief.unavailable})`.trim();
+      } else if (brief) {
+        // One head: the brief's, the task's commit, and the head the verdict names or inherits from an earlier review (with a
+        // PR, the lifecycle gate binds that head to the PR's).
+        const effective = typeof head === "string" ? head : t.sdlc?.reviewedHead;
+        if (effective !== undefined && effective !== brief.head && enforce) throw new PreEffectToolRefusal(`coverage: the verdict ${typeof head === "string" ? "names" : "inherits"} head ${effective}, but the review brief is for ${brief.head} (the commit under review)`);
+        covered = { commit: t.refs.commit, receipt: JSON.stringify(t.sdlc ?? null) };
+        const gap = coverageGap(brief, coverage);
+        if (gap.length && enforce) throw new PreEffectToolRefusal(`coverage: ${gap.length} reviewable path(s) of the review brief are not accounted for: ${list(gap)}. Pass coverage {reviewed, skipped: [{path, reason}]}.`);
+        if (gap.length) note = `${note ?? ""}\nCoverage gap (${gap.length}): ${list(gap)}`.trim();
+      }
+    }
     // The PII screen reads the note of a review that passes these checks (issue #198); they run again after it.
     const withheld = await this.withholds("review note", note, valid());
     let task = valid();
@@ -2345,7 +2850,8 @@ export class Tasks {
       if (cleared && context === JSON.stringify({ title: task.title, detail: task.detail, refs: task.refs, plan: task.plan, signals: task.signals })) candidate = input; // Async screening cannot authorize a verdict under an obsolete role/state.
     }
     const pii = this.isPii(task);
-    const flag = { withheld: withheld || undefined };
+    const reviewContext = by === USER ? undefined : this.d.reviewContext?.(by, task.id);
+    const flag = { withheld: withheld || undefined, ...(reviewContext ? { reviewContext } : {}) };
     if (verdict === "approved") {
       const next = this.d.board.update(task.id, by, "approved", { state: "approved", rejections: 0, ...(reviewedHead && task.sdlc ? { sdlc: { ...task.sdlc, reviewedHead, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), "merge") } } : {}) }, note, flag);
       if (next.owner) {
@@ -2475,11 +2981,23 @@ export class Tasks {
       this.ready(task, preEffect);
       const a = assign(task, this.states(), this.d.routing(), { candidates: [], namedReviewer: peer, ...(task.owner ? { notReviewer: task.owner } : {}), ...this.weights(task.class) });
       if (a.reviewer !== peer) throw new (preEffect ? PreEffectToolRefusal : Error)(`cannot name ${peer} as reviewer: ${a.trace.filter(line => line.includes("reviewer") || line.includes("pii")).join("; ")}`);
+      const admission = task.state === "in_review" ? await this.reviewRequestAdmission(task, undefined, preEffect, by) : undefined;
+      // Every runtime authority check precedes the final write, including revocations during the metadata await.
+      const current = this.need(task.id, false, preEffect);
+      if (current.history.length !== task.history.length) throw new (preEffect ? PreEffectToolRefusal : Error)("task changed during reviewer admission");
+      if (by !== USER) {
+        const holders = Object.entries(this.d.roles ?? {}).filter(([, roles]) => Array.isArray(roles) && roles.includes("conductor")).map(([actor]) => actor);
+        if (holders.length !== 1 || holders[0] !== by) throw new (preEffect ? PreEffectToolRefusal : Error)("only the console user or the configured conductor may name a reviewer");
+      }
+      if (!this.d.bus.isRostered(peer)) throw new (preEffect ? PreEffectToolRefusal : Error)(`${peer} is off roster`);
+      this.requireCapabilities(current, peer, role, preEffect);
+      const eligible = assign(current, this.states(), this.d.routing(), { candidates: [], namedReviewer: peer, ...(current.owner ? { notReviewer: current.owner } : {}), ...this.weights(current.class) });
+      if (eligible.reviewer !== peer) throw new (preEffect ? PreEffectToolRefusal : Error)("reviewer is no longer eligible");
       const next = this.d.board.update(task.id, by, "reviewer changed", { reviewer: peer }, this.assignmentNote(`named reviewer ${peer}`, a), { reason: "manual" }, expectedFlowRevision);
       if (next.state === "in_review" && task.reviewer && task.reviewer !== peer) {
         this.withdrawRoleRequest(task, next, "reviewer");
       }
-      if (next.state === "in_review" && peer !== USER) this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${peer}`, () => this.sendReview(next, peer));
+      if (next.state === "in_review" && peer !== USER) this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${peer}`, () => this.sendReview(next, peer, "", admission));
       return next;
     }
     // Work that waits is handed to nobody yet (issue #207): the peer becomes its reserved owner instead.