rig-create 0.0.0-stage → 1.0.1

package/src/signoff-checkpoint-act.ts

@@ -0,0 +1,95 @@
+/** `signoff --checkpoint <id> --from-review <actId>`: a passed Review checkpoint act becomes the checkpoint sign-off. */
+import { randomUUID } from 'node:crypto';
+import { readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, isObject } from './check.ts';
+import { jobHash } from './job-outbox.ts';
+import { jobRuntimeExecArgv } from './job-writer.ts';
+import { refuse } from './refusal.ts';
+import { assertActSubjectDeclared, checkpointActSignoff, decodeReviewAct, reviewActFindings, reviewActTransport, type CheckpointAct, type ReviewActTransport } from './review-act.ts';
+import { stepHash } from './step-hash.ts';
+import { readCheckpointEvidence } from './checkpoint-evidence.ts';
+import type { JsonObject } from './templates.ts';
+
+export interface SignoffHooks {
+  /** Tests inject the job API response; the command otherwise fetches through the private runtime. */
+  fetch?: (transport: ReviewActTransport) => { bytes: string };
+}
+
+export interface CheckpointIngest {
+  act: CheckpointAct;
+  bytes: string;
+  by: string;
+  at: string;
+  verbatim: string;
+  source: string;
+  /** The sign-off this act already recorded: the command replays it and writes nothing. */
+  replay?: JsonObject;
+}
+
+function fetchBytes(transport: ReviewActTransport, hooks: SignoffHooks): string {
+  if (hooks.fetch) return hooks.fetch(transport).bytes;
+  const child = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), fileURLToPath(new URL('./review-act-runtime.ts', import.meta.url))], {
+    stdin: Buffer.from(JSON.stringify(transport)), stdout: 'pipe', stderr: 'pipe',
+  });
+  let response: { ok: boolean; bytes: string; code: string; message: string };
+  try { response = JSON.parse(child.stdout.toString()); }
+  catch { return refuse('REVIEW_ACT_FETCH_REFUSED', 'project.json.review_acts: fetch adapter failed; restore the live Review job'); }
+  if (!response.ok || child.exitCode) refuse(response.code, response.message);
+  return response.bytes;
+}
+
+/** Fetches, decodes and binds the act to the `--checkpoint` step the command already accepted. */
+export function ingestCheckpointAct(dir: string, project: JsonObject, actId: string, checkpointId: string, now: number, hooks: SignoffHooks): CheckpointIngest {
+  const invalid = reviewActFindings(project)[0];
+  if (invalid) refuse(invalid.code, invalid.message);
+  const transport: ReviewActTransport = { ...reviewActTransport(dir, actId), kind: 'checkpoint' };
+  const bytes = fetchBytes(transport, hooks);
+  const act = decodeReviewAct(bytes, 'checkpoint');
+  if (act.jobId !== transport.jobId || act.actId !== transport.actId || Date.parse(act.at) > now) {
+    refuse('REVIEW_ACT_INVALID', `signoffs.checkpoint ${checkpointId}: fetched act identity or date differs from the request; fetch the checkpoint act again`);
+  }
+  if (act.value.planStepId !== checkpointId || act.value.checkpointId !== act.value.planStepId) {
+    refuse('REVIEW_ACT_CHECKPOINT_MISMATCH', `signoffs.checkpoint ${checkpointId}: act ${act.jobId}/${act.actId} names checkpoint ${act.value.checkpointId} on plan step ${act.value.planStepId}; sign the checkpoint the act names, or ask Review for checkpoint ${checkpointId}`);
+  }
+  assertActSubjectDeclared(dir, act, `signoffs.checkpoint ${checkpointId}`);
+  const fields = { act, bytes, ...checkpointActSignoff(act) };
+  const existing = asArray(project.review_acts).filter(isObject).find(entry => entry.jobId === act.jobId && entry.actId === act.actId);
+  if (existing) {
+    if (existing.bytes !== bytes) refuse('REVIEW_ACT_REPLAY_CONFLICT', 'project.json.review_acts: immutable checkpoint act changed; restore the original receipt');
+    const signoff = asArray(project.signoffs)[Number(existing.signoff)];
+    if (existing.kind !== 'checkpoint' || !isObject(signoff)) refuse('REVIEW_ACT_LEDGER_INVALID', 'project.json.review_acts: checkpoint receipt has no recorded sign-off; restore the original receipt and sign-off together');
+    return { ...fields, replay: signoff };
+  }
+  if (act.value.outcome !== 'pass') {
+    refuse('REVIEW_ACT_CHECKPOINT_FAILED', `signoffs.checkpoint ${checkpointId}: the person failed this checkpoint in Review (act ${act.jobId}/${act.actId}); a failed checkpoint is feedback, not a sign-off, so fix the step from its words and ask for the checkpoint again`);
+  }
+  const plan = isObject(project.plan) ? project.plan : null;
+  const current = asArray(plan?.steps).map(raw => ({ id: isObject(raw) ? raw.id : null, hash: isObject(raw) ? stepHash(raw) : null }));
+  if (!isDeepStrictEqual(act.source.plan.steps, current)) {
+    refuse('REVIEW_ACT_SOURCE_STALE', `signoffs.checkpoint ${checkpointId}: displayed plan step identities changed since act ${act.jobId}/${act.actId}; ask for the checkpoint again on the current plan`);
+  }
+  const displayedEvidence = (act.source as { checkpointEvidence?: readonly { checkpointId: string }[] }).checkpointEvidence
+    ?.find(packet => packet.checkpointId === checkpointId);
+  const currentEvidence = readCheckpointEvidence(dir, project)?.find(packet => packet.checkpointId === checkpointId);
+  if (!isDeepStrictEqual(displayedEvidence, currentEvidence)) {
+    refuse('REVIEW_ACT_SOURCE_STALE', `signoffs.checkpoint ${checkpointId}: sealed checkpoint presentation changed since act ${act.jobId}/${act.actId}; ask for the checkpoint again on the current evidence`);
+  }
+  return fields;
+}
+
+export function checkpointReceipt(ingest: CheckpointIngest, signoff: number): JsonObject {
+  const displayed = ingest.act.source.plan.steps.find(step => step.id === ingest.act.value.planStepId)!;
+  return { schema: 'rig-create/review-act@1', kind: 'checkpoint', jobId: ingest.act.jobId, actId: ingest.act.actId,
+    checkpoint: ingest.act.value.planStepId, signoff, bytes: ingest.bytes, sha256: jobHash(ingest.bytes), version_hash: displayed.hash };
+}
+
+/** Writes only if the record is the one the fetch was validated against, through an exclusive temporary file. */
+export function commitIngestedSignoff(file: string, original: Buffer, project: JsonObject): void {
+  if (!readFileSync(file).equals(original)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: record changed during checkpoint fetch; retry against the current live job');
+  const temporary = join(dirname(file), `.rig-create-review-act-${randomUUID()}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(project, null, 2)}\n`, { flag: 'wx' });
+  renameSync(temporary, file);
+}

package/src/signoff-target.ts

@@ -0,0 +1,127 @@
+import { acceptedReviewVerdict, readVersions } from './review.ts';
+import { checkFigureMask } from './figure-mask.ts';
+/** Review signatures bind accepted verdicts and the reviewed version's retained inputs. */
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, collectSignoffs, isObject, type Finding } from './check.ts';
+import { directionBinding } from './direction.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { checkReviewPackages } from './review-package.ts';
+import { refuse } from './refusal.ts';
+import { SIGNOFF_TARGET_KINDS } from './review-act.ts';
+import { sorted } from './step-hash.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const SIGNOFF_TARGET_SINCE = '2026-11-06T00:00:00Z';
+
+export function outputsHash(outputs: Json[]): string {
+  return createHash('sha256').update(JSON.stringify(sorted(outputs))).digest('hex');
+}
+
+export function reviewPackageHash(record: JsonObject): string {
+  return createHash('sha256').update(JSON.stringify(sorted({ config: record.config, files: record.files }))).digest('hex');
+}
+
+function validBinding(value: Json | undefined): value is JsonObject {
+  return isObject(value) && typeof value.path === 'string' && value.path.length > 0
+    && typeof value.sha256 === 'string' && /^[a-f0-9]{64}$/.test(value.sha256);
+}
+
+function targetFor(dir: string, project: JsonObject, stage: string, version: JsonObject, index: number, verdict: number): JsonObject {
+  const target: JsonObject = { version: version.n, verdict: `versions[${index}].verdicts[${verdict}]` };
+  if (stage === 'rig-review' && version.pre_interview === true) {
+    if (version.outputs_lost !== undefined) throw Error('outputs lost: nothing to bind');
+    if (!Array.isArray(version.outputs) || version.outputs.length === 0) throw Error('outputs missing: nothing to bind');
+    target.outputs = { path: `versions[${index}].outputs`, sha256: outputsHash(version.outputs) };
+  } else if (stage === 'rig-review') {
+    if (!isObject(version.review_package) || !isObject(version.review_package.config) || !Array.isArray(version.review_package.files)) throw Error('review_package missing or malformed');
+    target.review_package = { path: `versions[${index}].review_package`, sha256: reviewPackageHash(version.review_package) };
+  } else {
+    const provenance = isObject(version.provenance) ? version.provenance : {};
+    if (project.direction_contract !== undefined && provenance.direction !== undefined) {
+      if (!validBinding(provenance.direction)) throw Error('direction binding missing or malformed');
+      const actual = directionBinding(dir, provenance.direction.path as string);
+      if (!isDeepStrictEqual(actual, provenance.direction)) throw Error('direction file hash differs from recorded binding');
+      target.direction = actual;
+    } else {
+      if (!validBinding(provenance.config)) throw Error('post config binding missing or malformed');
+      target.post_config = provenance.config;
+    }
+  }
+  return target;
+}
+
+/** Same resolution is used by the reader and by the writer before its commit point. */
+export function checkSignoffTarget(dir: string, project: JsonObject, signoff: JsonObject, path: string, refusals: Finding[], warnings: Finding[]): void {
+  const stage = String(signoff.stage);
+  if (!(stage in SIGNOFF_TARGET_KINDS)) return;
+  const missing = signoff.target === undefined || signoff.target === null;
+  let reason = missing ? 'target missing' : '';
+  if (!missing) {
+    try {
+      const target = signoff.target;
+      if (!isObject(target) || !Number.isSafeInteger(target.version) || Number(target.version) < 1) throw Error('target version missing or malformed');
+      const versions = asArray(project.versions);
+      const matches = versions.map((v, i) => ({ v, i })).filter(({ v }) => isObject(v) && v.n === target.version);
+      if (matches.length !== 1) throw Error('target version does not exist uniquely');
+      const { v, i } = matches[0] as { v: JsonObject; i: number };
+      if (v.kind !== SIGNOFF_TARGET_KINDS[stage]) throw Error('target version belongs to another stage kind');
+      const match = typeof target.verdict === 'string' ? /^versions\[(\d+)\]\.verdicts\[(\d+)\]$/.exec(target.verdict) : null;
+      if (!match || Number(match[1]) !== i) throw Error('verdict path does not resolve to the target version');
+      const verdictIndex = Number(match[2]);
+      const verdict = asArray(v.verdicts)[verdictIndex];
+      if (!isObject(verdict) || verdictIndex !== acceptedReviewVerdict(v, stage)) throw Error('named verdict is missing, not accepted or belongs to another review stage');
+      const expected = targetFor(dir, project, stage, v, i, verdictIndex);
+      if (!isDeepStrictEqual(target, expected)) throw Error(expected.outputs ? 'outputs changed since signing' : stage === 'rig-review' ? 'review_package changed since signing' : expected.direction ? 'direction changed since signing' : 'post config changed since signing');
+    } catch (error) { reason = error instanceof Error ? error.message : String(error); }
+  }
+  if (!reason) return;
+  const legacy = Date.parse(String(signoff.at)) < Date.parse(SIGNOFF_TARGET_SINCE);
+  const code = `SIGNOFF_TARGET_${missing ? 'MISSING' : 'STALE'}${legacy ? '_LEGACY' : ''}`;
+  const at = `${path}.target`;
+  (legacy ? warnings : refusals).push({ code, path: at, message: `${at}: ${reason}; preserve the reviewed inputs and sign ${stage} again with --version` });
+}
+
+export function selectSignoffTarget(dir: string, project: JsonObject, stage: string, requested?: string): JsonObject | undefined {
+  if (!(stage in SIGNOFF_TARGET_KINDS)) {
+    if (requested !== undefined) refuse('SIGNOFF_OPTION_INVALID', 'signoffs.target: --version requires rig-review or direction-review; remove --version');
+    return undefined;
+  }
+  const reopens = collectReopens(project, []);
+  const signed = collectSignoffs(project, []).filter(s => s.stage === stage && liveSignoff(reopens, stage, s.at));
+  const versions = asArray(project.versions);
+  // A rig a reopen or amendment made history is no candidate (rig-c/create#243).
+  const history = stage === 'rig-review' ? new Set(readVersions(project).rigs.filter(r => !r.live).map(r => r.n)) : new Set<number>();
+  const candidates = versions.filter((v): v is JsonObject => isObject(v) && v.kind === SIGNOFF_TARGET_KINDS[stage]
+    && acceptedReviewVerdict(v, stage) >= 0 && !history.has(v.n as number)
+    && !signed.some(s => isObject(s.record.target) && s.record.target.version === v.n));
+  const fail = (reason: string): never => refuse('SIGNOFF_TARGET_STALE', `signoffs[${asArray(project.signoffs).length}].target: ${reason}; candidates [${candidates.map(v => String(v.n)).join(', ')}]; select an accepted version with --version and restore its reviewed inputs`);
+  let version: JsonObject;
+  if (requested === undefined) {
+    if (candidates.length !== 1) fail('exactly one unsigned accepted candidate is required');
+    version = candidates[0]!;
+  } else {
+    const matches = versions.filter((v): v is JsonObject => isObject(v) && v.n === Number(requested));
+    if (!/^[1-9][0-9]*$/.test(requested) || matches.length !== 1 || matches[0]?.kind !== SIGNOFF_TARGET_KINDS[stage]) fail('requested version does not exist uniquely with this stage kind');
+    version = matches[0]!;
+  }
+  if (history.has(version.n as number)) fail('rig version is history since a reopen or amendment of rig-review or an earlier stage');
+  const verdictIndex = acceptedReviewVerdict(version, stage);
+  if (verdictIndex < 0) fail('version has no accepted verdict');
+  let target: JsonObject;
+  try { target = targetFor(dir, project, stage, version, versions.indexOf(version), verdictIndex); }
+  catch (error) { return fail(error instanceof Error ? error.message : String(error)); }
+  if (stage === 'rig-review' && version.pre_interview !== true) {
+    const ctx = { dir, project: { ...project, versions: [{ ...version, pre_interview: false }] }, refusals: [] as Finding[], warnings: [] as Finding[] };
+    checkReviewPackages(ctx);
+    checkFigureMask(ctx);
+    const mask = ctx.refusals.find(f => f.code.startsWith('FIGURE_MASK_')
+      || ['REVIEW_PACKAGE_PART_FILE_MISMATCH', 'RIG_VERSION_AT_INVALID'].includes(f.code));
+    if (mask) refuse(mask.code, mask.message);
+    if (ctx.refusals.length || ctx.warnings.some(w => w.code === 'REVIEW_PACKAGE_MISSING')) fail('review package is missing or differs from its recorded binding');
+  }
+  const errors: Finding[] = [];
+  checkSignoffTarget(dir, project, { stage, target, at: SIGNOFF_TARGET_SINCE }, `signoffs[${asArray(project.signoffs).length}]`, errors, []);
+  if (errors[0]) refuse(errors[0].code, errors[0].message);
+  return target;
+}

package/src/signoff.ts

@@ -0,0 +1,331 @@
+import { latestPartsVerdictFinding, recordedPartsVerdict } from './parts-verdict-record.ts';
+import { selectAnswerHashes } from './signoff-answers.ts';
+import { selectSignoffTarget } from './signoff-target.ts';
+import { assertDirectionApproval } from './direction.ts';
+import { assertCorrectionApproval } from './correction-writers.ts';
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { acquireBoundJobWrite, jobRuntimeExecArgv } from './job-writer.ts';
+import { assertInterviewRecordSignable, checkpointProblem } from './signable.ts';
+import { checkpointReceipt, commitIngestedSignoff, ingestCheckpointAct, type CheckpointIngest, type SignoffHooks } from './signoff-checkpoint-act.ts';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { jobHash } from './job-outbox.ts';
+import { assertActSubjectDeclared, decodeReviewAct, isRecordDirectionSignoff, isRecordInterviewSignoff, recordSignoffActVersion, PLAN_BOUND_SIGNOFF_STAGES, reviewActFindings, reviewActSignoff, reviewActTransport, SIGNOFF_TARGET_KINDS, signoffActIdentity, signoffActVersion, type ReviewActTransport, type SignoffAct } from './review-act.ts';
+
+import { asArray, checkProject, classify, collectItems, collectSignoffs, isObject, loadCollection, postNotPassed, type Finding } from './check.ts';
+import { checkDiffMap } from './diff-map.ts';
+import { readProject } from './feedback.ts';
+import { checkStructure, riggingContext, structurePathIsIgnored } from './structure.ts';
+import { readVerbatim } from './record-input.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { baselineOf, newFindings } from './refusal-baseline.ts';
+import { approvalStageOfStep, hasStageOrder, PARTS_REVIEW, RIG_REVIEW, STAGE_ORDER_SPEC, STAGE_VALUES } from './stages.ts';
+import { assertRigReviewSignable } from './review.ts';
+import { furthestStageSignoff } from './stage-progress.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { stepHash } from './step-hash.ts';
+import type { JsonObject } from './templates.ts';
+
+export const SIGNOFF_HELP = `signoff:
+  <stage> [<project dir>]  record a human signature without moving project.stage
+  --version <n>           reviewed rig or post version (single candidate defaults)
+  --from-review <actId>   without --checkpoint: record the person's Review signoff act for <stage>
+                          (excludes --by, --verbatim-file and --steps on both routes)
+  --by <who>              the person signing (agent is refused)
+  --verbatim-file <file>  UTF-8 words unchanged, or - for stdin (default: stdin)
+  --steps <id,id,...>      narrow parts plan, rigging-interview rig steps, or post steps
+  --checkpoint <id>       sign an enabled checkpoint in this execution stage
+  --from-review <actId>   with --checkpoint: record the passed Review checkpoint act (no --by or --verbatim-file)
+  --draft <id>            labelled draft with a recorded parts-review API receipt
+  --structure-file <path> retained structure decisions snapshot
+  --json                  print the signature as JSON
+  The clock supplies at. With no --steps, signs all steps of the stage's phase.
+  Fills null checkpoints from checkpoint_proposed and hashes covered steps after filling.
+  Existing checkpoints are preserved. Parts-review validates evidence before recording.`;
+
+interface FetchedSignoff { act: SignoffAct; bytes: string; human: JsonObject }
+
+/** Fetch and decode a finalized signoff act; its stage, words, identity and date are the person's, never flags. */
+function fetchSignoffAct(dir: string, stage: string, actId: string, now: number, hooks: SignoffHooks): FetchedSignoff {
+  const invalid = reviewActFindings(readProject(dir).project)[0];
+  if (invalid) refuse(invalid.code, invalid.message);
+  const transport: ReviewActTransport = { ...reviewActTransport(dir, actId), kind: 'signoff' };
+  let bytes: string;
+  if (hooks.fetch) bytes = hooks.fetch(transport).bytes;
+  else {
+    const child = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), fileURLToPath(new URL('./review-act-runtime.ts', import.meta.url))], {
+      stdin: Buffer.from(JSON.stringify(transport)), stdout: 'pipe', stderr: 'pipe',
+    });
+    let response: { ok: boolean; bytes: string; code: string; message: string };
+    try { response = JSON.parse(child.stdout.toString()); }
+    catch { return refuse('REVIEW_ACT_FETCH_REFUSED', 'project.json.review_acts: fetch adapter failed; restore the live Review job'); }
+    if (!response.ok || child.exitCode) refuse(response.code, response.message);
+    bytes = response.bytes;
+  }
+  const act = decodeReviewAct(bytes, 'signoff');
+  if (act.jobId !== transport.jobId || act.actId !== transport.actId || Date.parse(act.at) > now) {
+    refuse('REVIEW_ACT_INVALID', 'project.json.review_acts: fetched signoff identity or date differs from the request; fetch the correct signoff act');
+  }
+  if (act.value.stage !== stage) refuse('REVIEW_ACT_KIND_MISMATCH', `project.json.review_acts: act signs ${act.value.stage}, not ${stage}; invoke signoff for the stage the person approved`);
+  assertActSubjectDeclared(dir, act, 'project.json.review_acts');
+  return { act, bytes, human: reviewActSignoff(act) };
+}
+
+export function signoffCommand(args: string[], now: number, hooks: SignoffHooks = {}): { stdout: string; exit: number } {
+  if (args.some(arg => arg === '--evidence' || arg.startsWith('--evidence='))) refuse('PARTS_VERDICT_FILE_ROUTE_REMOVED', 'project.json.signoffs.evidence: --evidence was removed; record the API response with parts-review and select it with --draft', USAGE_EXIT);
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  let json = false;
+  let hasDiffFlag = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--component' || arg === '--diff-report' || arg === '--triage-file') {
+      hasDiffFlag = true;
+      i++;
+    } else if (arg.startsWith('--component=') || arg.startsWith('--diff-report=') || arg.startsWith('--triage-file=')) {
+      hasDiffFlag = true;
+    } else if (['--version', '--draft', '--structure-file', '--by', '--verbatim-file', '--steps', '--checkpoint', '--from-review'].includes(arg)) {
+      const value = args[++i];
+      if (arg in opts || value === undefined || value === '') refuse('SIGNOFF_OPTION_INVALID', `${arg} needs one non-empty value`, USAGE_EXIT);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `signoff does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  const stage = positional[0];
+  if (positional.length > 2 || stage === undefined || !STAGE_VALUES.includes(stage)) refuse('SIGNOFF_OPTION_INVALID', 'signoff takes a known stage and one optional project folder', USAGE_EXIT);
+  if (hasDiffFlag) {
+    if (stage !== PARTS_REVIEW) refuse('SIGNOFF_OPTION_INVALID', '--diff-report, --triage-file and --component are not accepted on signoff', USAGE_EXIT);
+    refuse(
+      'SIGNOFF_DIFF_MAP_REMOVED',
+      "project.json.signoffs.diff_map: --diff-report, --triage-file and --component were removed from signoff; component classification is agent-authored — record it with 'rig-create diff-classes --diff-report <path> --triage-file <file> --by agent' (or '--component <id>=<status>:<why> --by agent')",
+      USAGE_EXIT,
+    );
+  }
+  const actId = opts['--from-review'];
+  if (actId !== undefined) {
+    const mixed = ['--by', '--verbatim-file', '--steps'].filter(flag => opts[flag] !== undefined);
+    if (mixed.length > 0) refuse('SIGNOFF_OPTION_INVALID', `project.json.review_acts: --from-review excludes ${mixed.join(', ')}; the person's identity, words and covered steps come from the review act`, USAGE_EXIT);
+  }
+  if (actId === undefined) return recordSignoff(stage, positional, opts, json, now, hooks);
+  // One bound write lock per route covers the fetch, validation and the write.
+  const root = resolve(positional[1] ?? process.cwd());
+  const release = acquireBoundJobWrite(root);
+  try {
+    // With --checkpoint the passed checkpoint act is fetched inside the writer; without it, the stage signoff act.
+    const review = opts['--checkpoint'] === undefined ? fetchSignoffAct(root, stage, actId, now, hooks) : undefined;
+    return recordSignoff(stage, positional, opts, json, now, hooks, review);
+  } finally { release(); }
+}
+
+function recordSignoff(stage: string, positional: string[], opts: Record<string, string>, json: boolean, now: number, hooks: SignoffHooks, review?: FetchedSignoff): { stdout: string; exit: number } {
+  const actId = opts['--from-review'];
+  let by = review === undefined ? opts['--by'] ?? '' : String(review.human.by);
+  if (opts['--by'] === undefined && actId === undefined) refuse('SIGNOFF_OPTION_INVALID', 'signoff needs --by', USAGE_EXIT);
+  if (by.toLowerCase() === 'agent') refuse('SIGNOFF_NOT_HUMAN', `stage ${stage}: signed by agent`);
+  const dir = resolve(positional[1] ?? process.cwd());
+  const { file, project } = readProject(dir);
+  const original = actId === undefined ? undefined : readFileSync(file);
+  let ingest: CheckpointIngest | undefined;
+  // Recorded checkpoint receipts replay before current eligibility, through the same immutable-byte validator.
+  if (actId !== undefined && opts['--checkpoint'] !== undefined && asArray(project.review_acts).some(entry =>
+    isObject(entry) && entry.kind === 'checkpoint' && entry.actId === actId)) {
+    ingest = ingestCheckpointAct(dir, project, actId, opts['--checkpoint'], now, hooks);
+    if (ingest.replay) {
+      if (ingest.replay.stage !== stage) refuse('SIGNOFF_CHECKPOINT_INVALID', `signoffs.checkpoint ${opts['--checkpoint']}: recorded act belongs to ${String(ingest.replay.stage)}; replay it for its original stage`);
+      return { stdout: json ? JSON.stringify(ingest.replay, null, 2) : `signoff: ${stage} checkpoint ${opts['--checkpoint']} already recorded from ${ingest.source}; nothing written`, exit: 0 };
+    }
+  }
+  // A target stage signs Review's selector or the exact displayed record, never a flag-selected replacement.
+  let targetVersion = opts['--version'];
+  if (review !== undefined && stage in SIGNOFF_TARGET_KINDS && !isRecordDirectionSignoff(review.act)) {
+    const shown = signoffActVersion(review.act);
+    const at = `signoffs[${asArray(project.signoffs).length}].target.version`;
+    if (shown === null) refuse('REVIEW_ACT_TARGET_MISMATCH', `${at}: the review act names no ${SIGNOFF_TARGET_KINDS[stage]} version it displayed; ask for ${stage} again in Review on the reviewed version`);
+    if (targetVersion !== undefined && targetVersion !== String(shown)) refuse('REVIEW_ACT_TARGET_MISMATCH', `${at}: --version ${targetVersion} differs from version ${shown} the person approved in Review; drop --version or ask for ${stage} on version ${targetVersion} in Review`);
+    targetVersion = String(shown);
+  }
+  if (review !== undefined) {
+    // Replays dedupe before current-source checks: the recorded signoff is returned unchanged.
+    const existing = asArray(project.review_acts).filter(isObject).find(entry => entry.jobId === review.act.jobId && entry.actId === review.act.actId);
+    if (existing !== undefined) {
+      if (existing.bytes !== review.bytes) refuse('REVIEW_ACT_REPLAY_CONFLICT', 'project.json.review_acts: immutable signoff act changed; restore the original receipt');
+      if (isRecordDirectionSignoff(review.act)) {
+        const invalid = reviewActFindings(project)[0];
+        if (invalid !== undefined) refuse(invalid.code, invalid.message);
+      }
+      const recorded = asArray(project.signoffs).filter(isObject).find(entry => entry.source === review.human.source);
+      if (recorded === undefined) refuse('REVIEW_ACT_LEDGER_INVALID', 'project.json.review_acts: the signoff this act recorded is absent; restore its signoffs[] entry');
+      return { stdout: json ? JSON.stringify(recorded, null, 2) : `signoff: replayed ${stage} by ${by} at ${String(recorded.at)}; stage unchanged`, exit: 0 };
+    }
+    if (review.act.schema === 'rig-review/act@4' && review.act.source.projectHash !== jobHash(original!)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: displayed signoff record differs; publish the current plan and ask again');
+    if (isRecordDirectionSignoff(review.act)) {
+      const shown = recordSignoffActVersion(review.act, original!.toString('utf8'));
+      if (shown === null) refuse('REVIEW_ACT_RECORD_TARGET_INVALID', 'project.json.versions: the frozen sign-off record has no single current live post with an accepted direction-review verdict; publish the corrected record after reviewing that post');
+      if (targetVersion !== undefined && targetVersion !== String(shown)) refuse('REVIEW_ACT_TARGET_MISMATCH', `signoffs.target.version: --version ${targetVersion} differs from post ${shown} bound by the frozen record; drop --version and sign the displayed record`);
+      targetVersion = String(shown);
+    }
+    if (PLAN_BOUND_SIGNOFF_STAGES.includes(stage) || isRecordInterviewSignoff(review.act)) {
+      const displayed = review.act.source.plan?.steps ?? [];
+      const current = asArray(isObject(project.plan) ? project.plan.steps : undefined).map(raw => ({ id: isObject(raw) ? raw.id ?? null : null, hash: isObject(raw) ? stepHash(raw) : null }));
+      if (displayed.length !== current.length || displayed.some((step, index) => step.id !== current[index]!.id || step.hash !== current[index]!.hash)) {
+        refuse('REVIEW_ACT_SOURCE_STALE', `signoffs[${asArray(project.signoffs).length}].step_hashes: the plan steps the person approved differ from the current plan; publish the current plan and ask for ${stage} again`);
+      }
+    }
+  }
+  if (review !== undefined && stage === PARTS_REVIEW) {
+    const selector = review.act.source.selector;
+    const shown = isObject(selector) && selector.kind === 'draft' && typeof selector.id === 'string' && selector.id !== '' ? selector.id : null;
+    const at = `signoffs[${asArray(project.signoffs).length}].draft_id`;
+    if (selector !== null && (shown === null || (opts['--draft'] !== undefined && opts['--draft'] !== shown))) {
+      refuse('REVIEW_ACT_DRAFT_MISMATCH', `${at}: --draft ${opts['--draft'] ?? '<absent>'} differs from draft ${shown ?? '<non-draft>'} the person approved in Review; drop --draft or ask for parts-review on the reviewed draft in Review`);
+    }
+    if (shown !== null) opts['--draft'] = shown;
+  }
+  if (stage === PARTS_REVIEW && opts['--draft'] !== undefined) {
+    const finding = latestPartsVerdictFinding(project, opts['--draft'], `signoffs[${asArray(project.signoffs).length}].draft_id`);
+    if (finding) refuse(finding.code, finding.message);
+  }
+  // The record as read: its refusals are the baseline the candidate is judged against below.
+  const asRead = checkProject(dir, project, { now });
+  if (review !== undefined && isRecordInterviewSignoff(review.act)) assertInterviewRecordSignable(project, asRead);
+  const existingLag = asRead.refusals.find(f => f.code === 'STAGE_LAGGING');
+  if (existingLag !== undefined) refuse(existingLag.code, existingLag.message);
+  if (!Array.isArray(project.signoffs)) refuse('SIGNOFF_MALFORMED', 'signoffs must be a list');
+  const checkpointId = opts['--checkpoint'];
+  if (checkpointId !== undefined) {
+    if (opts['--steps'] !== undefined) refuse('SIGNOFF_OPTION_INVALID', '--checkpoint and --steps cannot be combined', USAGE_EXIT);
+    // The publications declare checkpoint subjects with this same rule (src/signable.ts).
+    const problem = checkpointProblem(project, stage, checkpointId);
+    if (problem !== null) refuse('SIGNOFF_CHECKPOINT_INVALID', problem);
+    if (actId !== undefined) {
+      ingest = ingestCheckpointAct(dir, project, actId, checkpointId, now, hooks);
+      if (ingest.replay) return { stdout: json ? JSON.stringify(ingest.replay, null, 2) : `signoff: ${stage} checkpoint ${checkpointId} already recorded from ${ingest.source}; nothing written`, exit: 0 };
+      by = ingest.by;
+    }
+  }
+  if (stage === PARTS_REVIEW && !opts['--draft']) refuse('PARTS_VERDICT_RECEIPT_REQUIRED', 'project.json.signoffs.draft_id: parts-review needs --draft with a recorded API receipt');
+  let evidence: JsonObject | undefined;
+  const recorded = stage === PARTS_REVIEW ? recordedPartsVerdict(dir, project, opts['--draft']) : undefined;
+  evidence = recorded?.evidence;
+  if ((opts['--draft'] !== undefined || opts['--structure-file'] !== undefined) && stage !== PARTS_REVIEW) refuse('SIGNOFF_OPTION_INVALID', '--draft and --structure-file require parts-review', USAGE_EXIT);
+  const phase = stage === 'post-interview' ? 'post' : ['plan-approved', 'rigging-interview'].includes(stage) ? 'rig' : undefined;
+  if (phase === undefined && opts['--steps'] !== undefined) refuse('SIGNOFF_OPTION_INVALID', '--steps requires plan-approved, rigging-interview or post-interview', USAGE_EXIT);
+  const requested = opts['--steps']?.split(',');
+  if (requested !== undefined && (requested.some((id) => id === '') || new Set(requested).size !== requested.length)) refuse('SIGNOFF_STEP_INVALID', '--steps needs distinct non-empty step ids', USAGE_EXIT);
+  const steps = phase === undefined ? [] : asArray(isObject(project.plan) ? project.plan.steps : undefined)
+    .filter((step): step is JsonObject => isObject(step) && step.phase === phase && approvalStageOfStep(phase as 'rig' | 'post', String(step.id), hasStageOrder(project) || stage === 'rigging-interview') === stage);
+  for (const id of requested ?? []) {
+    if (!steps.some((step) => step.id === id)) refuse('SIGNOFF_STEP_INVALID', `${id}: no step in phase ${phase}`);
+  }
+  const covered = steps.filter((step) => requested === undefined || requested.includes(step.id as string));
+  const emptyPost = stage === 'post-interview' && requested === undefined && steps.length === 0
+    && postNotPassed({ items: collectItems(project, { collection: loadCollection(dir) }) });
+  if (phase !== undefined && covered.length === 0 && !emptyPost) refuse('SIGNOFF_STEP_INVALID', `no ${phase} steps to sign`);
+  const ids = covered.map((step) => step.id);
+  if (ids.some((id) => typeof id !== 'string' || id === '') || new Set(ids).size !== ids.length) refuse('SIGNOFF_STEP_INVALID', 'covered steps need distinct non-empty string ids');
+  for (const step of covered) {
+    if (typeof step.checkpoint_proposed !== 'boolean') refuse('SIGNOFF_CHECKPOINT_INVALID', `${String(step.id)}: checkpoint_proposed must be boolean`);
+    const checkpoint = classify(step.checkpoint, { collection: null });
+    if (checkpoint.state === 'silent') continue;
+    const value = checkpoint.state === 'user' ? checkpoint.answer.value
+      : checkpoint.state === 'delegated' && checkpoint.decided && isObject(checkpoint.answer.agent_decision) ? checkpoint.answer.agent_decision.value : undefined;
+    if (typeof value !== 'boolean') refuse('SIGNOFF_CHECKPOINT_INVALID', `${String(step.id)}: checkpoint needs a boolean user answer or a decided boolean delegation`);
+  }
+  const verbatim = review !== undefined ? String(review.human.verbatim) : ingest ? ingest.verbatim : readVerbatim(opts['--verbatim-file'] ?? '-');
+  const at = review !== undefined ? String(review.human.at) : ingest ? ingest.at : new Date(now).toISOString();
+  const hashes: JsonObject = Object.create(null) as JsonObject;
+  for (const step of covered) {
+    if (step.checkpoint === null || step.checkpoint === undefined) {
+      step.checkpoint = { delegated: false, by, at, verbatim, value: step.checkpoint_proposed };
+    }
+    hashes[step.id as string] = stepHash(step);
+  }
+  const signoff: JsonObject = { stage, checkpoint: checkpointId ?? null, by, at, verbatim };
+  if (review !== undefined) signoff.source = review.human.source!;
+  if (evidence !== undefined) signoff.evidence = evidence;
+  if (phase !== undefined) {
+    signoff.steps = ids;
+    signoff.step_hashes = hashes;
+  }
+  const answerHashes = selectAnswerHashes(dir, project, signoff);
+  if (answerHashes !== undefined) signoff.answer_hashes = answerHashes;
+  if (stage === PARTS_REVIEW && opts['--draft'] !== undefined) signoff.draft_id = opts['--draft'];
+  if (stage === PARTS_REVIEW && checkpointId === undefined) {
+    const errors: Finding[] = [];
+    checkDiffMap(dir, signoff, `signoffs[${project.signoffs.length}]`, recorded?.partsFile, errors, [], project);
+    if (errors[0] !== undefined) refuse(errors[0].code, errors[0].message);
+  }
+  if (stage === PARTS_REVIEW && (hasStageOrder(project) || opts['--structure-file'] !== undefined)) {
+    const path = opts['--structure-file'];
+    if (path !== undefined) {
+      try {
+        if (structurePathIsIgnored(dir, path)) throw new Error('structure snapshots must survive a clone; retain the file outside ignored roots, for example evidence/');
+        const canonical = realpathSync(resolve(dir, path));
+        const rel = relative(realpathSync(dir), canonical).split(sep).join('/');
+        if (isAbsolute(path) || rel === '' || rel === '..' || rel.startsWith('../')) throw new Error('structure file must stay under the project');
+        signoff.structure = { path: rel, sha256: createHash('sha256').update(readFileSync(canonical)).digest('hex') };
+      } catch (error) { refuse('STRUCTURE_DECISIONS_INVALID', `signoffs.structure: ${error instanceof Error ? error.message : String(error)}; retain the structure snapshot under the project`); }
+    }
+    const errors: Finding[] = [];
+    checkStructure(dir, project, signoff, `signoffs[${project.signoffs.length}]`, errors);
+    if (errors[0] !== undefined) refuse(errors[0].code, errors[0].message);
+  }
+  if (stage === 'rigging-interview') {
+    const errors: Finding[] = [];
+    const context = riggingContext(dir, project, at, errors);
+    if (errors[0] !== undefined) refuse(errors[0].code, errors[0].message);
+    if (context !== null) { signoff.accepted_parts = context.accepted_parts as JsonObject; signoff.structure = context.structure as JsonObject; }
+    if (!isObject(project.interview)) refuse('RIGGING_INTERVIEW_CONTEXT', 'interview: restore the interview record before adoption');
+    project.interview.rigging_context = context;
+    if (!hasStageOrder(project)) project.interview.order = { spec: STAGE_ORDER_SPEC, adopted_at: at };
+    project.stage_values = [...STAGE_VALUES];
+  }
+  assertDirectionApproval(dir, project, stage, now);
+  assertCorrectionApproval(dir, project, stage, now, signoff);
+  if (stage === RIG_REVIEW) assertRigReviewSignable(project, `signoffs[${project.signoffs.length}]`);
+  const target = selectSignoffTarget(dir, project, stage, targetVersion);
+  if (target !== undefined) signoff.target = target;
+  if (ingest) signoff.source = ingest.source;
+  project.signoffs.push(signoff);
+  if (review !== undefined) {
+    project.review_acts = [...asArray(project.review_acts), { schema: 'rig-create/review-act@1', kind: 'signoff', jobId: review.act.jobId, actId: review.act.actId,
+      stage, bytes: review.bytes, sha256: jobHash(review.bytes), version_hash: jobHash(JSON.stringify(signoffActIdentity(review.act))),
+      ...(isRecordDirectionSignoff(review.act) ? { record_sha256: review.act.source.projectHash,
+        target_version: target!.version!, verdict: target!.verdict! } : {}) }];
+    const invalid = reviewActFindings(project)[0];
+    if (invalid !== undefined) refuse(invalid.code, invalid.message);
+  }
+  if (ingest) {
+    project.review_acts = [...asArray(project.review_acts), checkpointReceipt(ingest, project.signoffs.length - 1)];
+    const invalid = reviewActFindings(project)[0];
+    if (invalid) refuse(invalid.code, invalid.message);
+  }
+  const reopens = collectReopens(project, []);
+  const frontier = furthestStageSignoff(collectSignoffs(project, []).filter(s => liveSignoff(reopens, s.stage, s.at)));
+  const ownLag = signoff.checkpoint === null && frontier?.index === project.signoffs.length - 1;
+  const candidateRefusals = checkProject(dir, project, { now }).refusals;
+  // Refusals the record already carried do not block the signature (docs/PROJECT.md); a new one does.
+  const fresh = new Set(newFindings(baselineOf(asRead), candidateRefusals));
+  const pendingOwnAdvance = (finding: Finding): boolean => ownLag && finding.code === 'STAGE_LAGGING';
+  const progress = candidateRefusals.find(f => ['STAGE_LAGGING', 'STAGE_SKIPPED', 'STAGE_SIGNOFF_DATE_INVALID', 'ADVANCE_MALFORMED', 'STEP_STATUS_TRANSITION', 'STEP_STATUS_SIGNOFF'].includes(f.code) && !pendingOwnAdvance(f) && fresh.has(f));
+  if (progress !== undefined) refuse(progress.code, progress.message);
+  if (hasStageOrder(project) || signoff.structure !== undefined || project.amendments !== undefined) {
+    const path = `signoffs[${project.signoffs.length - 1}]`;
+    const first = candidateRefusals.find(f => {
+      if (pendingOwnAdvance(f)) return false;
+      if (f.code.startsWith('SIGNOFF_ANSWERS_')) return f.path.startsWith(`${path}.`);
+      // A covered step this signature leaves unapproved is its own failure, even when the record carried it.
+      if (f.code === 'GUIDE_CHANGED_UNSIGNED') return covered.some(step => f.path === `plan.steps[${String(step.id)}]`);
+      return fresh.has(f);
+    });
+    if (first !== undefined) refuse(first.code, first.message);
+  }
+  if (ingest) commitIngestedSignoff(file, original!, project);
+  else {
+    if (review !== undefined && !readFileSync(file).equals(original!)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: record changed during signoff validation; retry against the current live job');
+    writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
+  }
+  return { stdout: json ? JSON.stringify(signoff, null, 2) : `signoff: recorded ${stage} by ${by} at ${at}; stage unchanged`, exit: 0 };
+}