@rig-c/create 0.0.0-stage → 1.0.0

package/src/parts-review.ts

@@ -0,0 +1,196 @@
+import { assertPartsCliArgs, assertPartsReadDraft, decodePartsRead, partsReadFindings, partsVerdictNames, PARTS_CLI_RECEIPT } from './parts-verdict-record.ts';
+/** A parts verdict is recorded independently of signoff and stage progression. */
+import { randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readProject } from './feedback.ts';
+import { readPartsReview, ReviewReadError, storeReviewRead, type ReviewReadRunner } from './review-read.ts';
+import { acquireBoundJobWrite, jobRuntimeExecArgv } from './job-writer.ts';
+import { acquireJobLock, jobHash, readAcknowledgedPublication, readWriterBinding } from './job-outbox.ts';
+import { decodeReviewAct, reviewActFindings, reviewActTransport, reviewActVerbatim } from './review-act.ts';
+import { assertPartsActSource, partsActDraftHash, partsActFindings, partsActReceipt } from './parts-act.ts';
+import { newRefusals } from './refusal-baseline.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+export const PARTS_REVIEW_HELP = 'parts-review [<project>] --from-review <actId> [--json] | parts-review [<project>] --draft <id> --from-review-cli --by <name> [--json] -- <rig-review parts arguments>';
+export interface PartsReviewHooks {
+  afterEvidence?: (path: string) => void;
+  /** Replaces Review's resolution and spawn; the exit code and tool identity are still checked. */
+  runCli?: ReviewReadRunner;
+}
+
+function syncDirectory(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+export function partsReviewCommand(args: string[], now: number, hooks: PartsReviewHooks = {}): { stdout: string; exit: number } {
+  let actId: string | undefined;
+  const options: Record<string, string> = {};
+  let json = false;
+  let fromCli = false;
+  let cliArgs: string[] = [];
+  const positional: string[] = [];
+  const usage = (): never => refuse('PARTS_REVIEW_OPTION_INVALID', `project.json.review_acts: ${PARTS_REVIEW_HELP}; submit human values through Review`, USAGE_EXIT);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { cliArgs = args.slice(i + 1); break; }
+    if (arg === '--from-review-cli') { if (fromCli) usage(); fromCli = true; }
+    else if (arg === '--json') { if (json) usage(); json = true; }
+    else if (arg === '--from-review') { if (actId) usage(); actId = args[++i]; if (!actId || actId.startsWith('-')) usage(); }
+    else if (['--draft', '--by'].includes(arg)) {
+      const value = args[++i];
+      if (options[arg] !== undefined || !value || value.startsWith('-')) usage();
+      options[arg] = value;
+    }
+    else if (arg.startsWith('-')) usage();
+    else positional.push(arg);
+  }
+  if (positional.length > 1 || (actId ? fromCli || Object.keys(options).length > 0 || cliArgs.length > 0 : !fromCli || Object.keys(options).length !== 2 || cliArgs.length === 0)) usage();
+  if (fromCli && cliArgs.some(arg => arg === '--format' || arg.startsWith('--format='))) usage();
+  const root = resolve(positional[0] ?? process.cwd());
+  if (fromCli) assertPartsCliArgs(cliArgs);
+  if (!actId) return recordCliVerdict(root, options, cliArgs, json, now, hooks);
+  const release = acquireBoundJobWrite(root);
+  let created: string | undefined;
+  let committed = false;
+  const temporary = join(root, `.parts-review-${randomUUID()}.tmp`);
+  try {
+    const transport = { ...reviewActTransport(root, actId!), kind: 'parts-verdict' };
+    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);
+    const act = decodeReviewAct(response.bytes, 'parts-verdict');
+    if (Date.parse(act.at) > now) refuse('REVIEW_ACT_INVALID', 'project.json.review_acts: act is dated in the future; restore the clock before recording');
+    const { file } = readProject(root);
+    const original = readFileSync(file);
+    const project = JSON.parse(original.toString('utf8')) as JsonObject;
+    const invalid = [...reviewActFindings(project), ...partsActFindings(root, project), ...partsReadFindings(root, project)][0];
+    if (invalid) refuse(invalid.code, invalid.message);
+    assertPartsActSource(root, project, act);
+    const hash = partsActDraftHash(project, act);
+    const existing = partsActReceipt(project, act);
+    const evidence = { path: `evidence/review-acts/${jobHash(JSON.stringify([act.jobId, act.actId]))}.json`, sha256: jobHash(response.bytes) };
+    const warnings: string[] = [];
+    if (existing) {
+      if (existing.bytes !== response.bytes) refuse('REVIEW_ACT_REPLAY_CONFLICT', 'project.json.review_acts: immutable parts act changed; restore the original receipt');
+      if (existing.version_hash !== hash) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json.review_acts: reviewed draft entry changed; review a new draft id');
+    } else {
+      const publication = readAcknowledgedPublication(root, act.jobId, act.publicationId);
+      if (publication && (publication.versionHash !== hash || publication.result.selector?.kind !== 'draft' || publication.result.selector.id !== act.source.selector.id)) {
+        refuse('REVIEW_ACT_SOURCE_STALE', 'project.json.review_acts: draft differs from its acknowledged publication; record and review a new id');
+      }
+      if (!publication) warnings.push('REVIEW_ACT_VERSION_UNVERIFIED: project.json.review_acts: publication receipt is absent, so the first-ingest draft-entry check was skipped; retain acknowledged receipts');
+      const directory = dirname(join(root, evidence.path));
+      for (const segment of ['evidence', 'evidence/review-acts']) {
+        const path = join(root, segment);
+        let info;
+        try { info = lstatSync(path); }
+        catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+          mkdirSync(path);
+          syncDirectory(dirname(path));
+          info = lstatSync(path);
+        }
+        if (!info.isDirectory() || info.isSymbolicLink()) refuse('PARTS_REVIEW_EVIDENCE_CONFLICT', 'project.json.review_acts: evidence directory is unsafe; restore its original real directory');
+      }
+      const path = join(root, evidence.path);
+      let present = false;
+      try { lstatSync(path); present = true; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      if (present) {
+        if (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink() || !readFileSync(path).equals(Buffer.from(response.bytes))) {
+          refuse('PARTS_REVIEW_EVIDENCE_CONFLICT', `project.json.review_acts: ${evidence.path} contains another act; preserve it and restore the original evidence before retrying`);
+        }
+        const fd = openSync(path, 'r');
+        try { fsyncSync(fd); } finally { closeSync(fd); }
+      } else {
+        const fd = openSync(path, 'wx', 0o600);
+        created = path;
+        try { writeFileSync(fd, response.bytes); fsyncSync(fd); } finally { closeSync(fd); }
+        syncDirectory(directory);
+      }
+      hooks.afterEvidence?.(path);
+      const next = structuredClone(project);
+      next.review_acts = [...(project.review_acts as JsonObject[] ?? []), { schema: 'rig-create/review-act@1', kind: 'parts-verdict',
+        jobId: act.jobId, actId: act.actId, draft_id: act.source.selector.id, version_hash: hash,
+        bytes: response.bytes, sha256: evidence.sha256, evidence }];
+      const failure = [...reviewActFindings(next), ...partsActFindings(root, next), ...newRefusals(root, project, next, { now })][0];
+      if (failure) refuse(failure.code, failure.message);
+      assertPartsActSource(root, project, act);
+      if (!readFileSync(file).equals(original)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: record changed during parts verdict validation; retry against the current job');
+      const fd = openSync(temporary, 'wx', 0o600);
+      try { writeFileSync(fd, `${JSON.stringify(next, null, 2)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(temporary, file);
+      committed = true;
+      syncDirectory(root);
+    }
+    const result = { draft_id: act.source.selector.id, evidence, verdict: act.value.verdict,
+      by: act.authority.reviewer.role === 'owner' ? 'user' : 'delegate', at: act.at, verbatim: reviewActVerbatim(act),
+      ...(warnings.length ? { warnings } : {}) };
+    return { stdout: json ? JSON.stringify(result, null, 2) : [...warnings, `parts-review: ${result.draft_id} ${result.verdict}, evidence ${evidence.path}`].join('\n'), exit: 0 };
+  } finally {
+    if (created && !committed) rmSync(created, { force: true });
+    rmSync(temporary, { force: true });
+    release();
+  }
+}
+
+function recordCliVerdict(root: string, options: Record<string, string>, cliArgs: string[], json: boolean, now: number, hooks: PartsReviewHooks): { stdout: string; exit: number } {
+  if (!options['--by'].trim() || options['--by'].toLowerCase() === 'agent') refuse('SIGNOFF_NOT_HUMAN', 'project.json.review_acts.by: supply the human reviewer with --by');
+  const release = readWriterBinding(root) ? acquireBoundJobWrite(root) : acquireJobLock(root)!;
+  const temporary = join(root, `.parts-review-${randomUUID()}.tmp`);
+  let created: string | undefined;
+  let committed = false;
+  try {
+    const { file } = readProject(root);
+    const original = readFileSync(file);
+    const project = JSON.parse(original.toString('utf8')) as JsonObject;
+    const invalid = [...reviewActFindings(project), ...partsActFindings(root, project), ...partsReadFindings(root, project)][0];
+    if (invalid) refuse(invalid.code, invalid.message);
+    const draftId = options['--draft'];
+    let bytes: Buffer;
+    try { bytes = readPartsReview(root, cliArgs, hooks.runCli).stdout; }
+    catch (error) {
+      if (!(error instanceof ReviewReadError)) throw error;
+      return refuse('PARTS_REVIEW_CLI_FAILED', `project.json.review_acts: rig-review ${error.why}; restore the pinned rig-review installation and the saved verdict, then retry its original display arguments`);
+    }
+    const verdict = decodePartsRead(bytes);
+    assertPartsReadDraft(root, project, verdict, draftId);
+    const hash = jobHash(bytes);
+    const receipts = project.review_acts as JsonObject[] | undefined;
+    const existing = receipts?.find(entry => entry.schema === PARTS_CLI_RECEIPT && entry.draft_id === draftId && (entry.evidence as JsonObject).sha256 === hash);
+    if (existing) return { stdout: json ? JSON.stringify(existing, null, 2) : `parts-review: ${draftId} ${existing.status}, already recorded`, exit: 0 };
+    const evidence = { kind: 'parts-verdict', path: `evidence/review-reads/${hash}.json`, sha256: hash };
+    const receipt: JsonObject = { schema: PARTS_CLI_RECEIPT, kind: 'parts-verdict', draft_id: draftId, evidence,
+      route: 'cli', argv: cliArgs, tool: verdict.tool, status: verdict.status, ...partsVerdictNames(verdict), by: options['--by'], at: new Date(now).toISOString() };
+    const path = join(root, evidence.path);
+    try { if (storeReviewRead(root, bytes).created) created = path; }
+    catch (error) {
+      if (!(error instanceof ReviewReadError)) throw error;
+      refuse('PARTS_REVIEW_EVIDENCE_CONFLICT', `project.json.review_acts.evidence: ${error.why}; preserve and restore the original content-addressed verdict in a real evidence directory`);
+    }
+    hooks.afterEvidence?.(path);
+    const next = structuredClone(project);
+    next.review_acts = [...(receipts ?? []), receipt];
+    const failure = [...partsReadFindings(root, next), ...newRefusals(root, project, next, { now })][0];
+    if (failure) refuse(failure.code, failure.message);
+    if (!readFileSync(file).equals(original)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: record changed during validation; retry against the current record');
+    const fd = openSync(temporary, 'wx', 0o600);
+    try { writeFileSync(fd, `${JSON.stringify(next, null, 2)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+    renameSync(temporary, file);
+    committed = true;
+    syncDirectory(root);
+    return { stdout: json ? JSON.stringify(receipt, null, 2) : `parts-review: ${draftId} ${receipt.status}, evidence ${evidence.path}`, exit: 0 };
+  } finally {
+    if (created && !committed) rmSync(created, { force: true });
+    rmSync(temporary, { force: true });
+    release();
+  }
+}

package/src/parts-sections.ts

@@ -0,0 +1,98 @@
+/**
+ * The top-level sections of a `@rig-c/parts` config, taken from the installed
+ * package's own export — the pipeline's list, not a hand copy.
+ *
+ * parts exports the list as `CONFIG_SECTIONS` from `src/config.ts` (from
+ * 2.3.0; its package.json has no `exports` map, so the subpath is importable).
+ * It is loaded at run time from the parts found for the project being checked
+ * (`locateParts`), not imported from this repository's own dependency, because
+ * `interview --check` reports the sections of the version installed there.
+ * There is no static import either, not even a type-only one: it would make
+ * this repository's typecheck compile the parts and core sources, which do not
+ * typecheck outside their own repositories. A test loads the export from this
+ * repository's pinned install instead.
+ *
+ * Bun's `require` loads that ES module synchronously, so the check stays
+ * synchronous. A parts with no such export (older than 2.3.0, or a release that
+ * moves it) is `PARTS_SECTIONS_UNREADABLE`, so it fails loudly instead of
+ * silently deriving no waypoints.
+ */
+import { existsSync, readFileSync } from './check-reads.ts';
+import { createRequire } from 'node:module';
+import { basename, dirname, join } from 'node:path';
+
+export const PARTS_PACKAGE = '@rig-c/parts';
+const CONFIG_SOURCE = join('src', 'config.ts');
+const SECTIONS_EXPORT = 'CONFIG_SECTIONS';
+
+/** The export's shape: section names, in parts' order. */
+type Sections = readonly string[];
+
+export interface PartsSections {
+  readonly version: string;
+  /** The package folder the sections were read from. */
+  readonly dir: string;
+  /** The export the list was taken from. */
+  readonly read_from: typeof SECTIONS_EXPORT;
+  readonly sections: readonly string[];
+}
+
+export class PartsUnreadable extends Error {
+  readonly code: 'PARTS_NOT_INSTALLED' | 'PARTS_SECTIONS_UNREADABLE';
+  constructor(code: 'PARTS_NOT_INSTALLED' | 'PARTS_SECTIONS_UNREADABLE', message: string) {
+    super(message);
+    this.name = 'PartsUnreadable';
+    this.code = code;
+  }
+}
+
+/** The create repository's own install, used when a project has none (running the check in this repo, or before `bun install` in a project). */
+export const OWN_NODE_MODULES = join(import.meta.dir, '..', 'node_modules');
+
+/**
+ * Where the installed package is looked for, in order: the project's own
+ * install, the collection's for a member (`<collection>/members/<name>/`, which
+ * installs nothing itself: docs/COLLECTIONS.md), then create's.
+ */
+export function partsCandidates(projectDir: string): string[] {
+  const pkg = PARTS_PACKAGE.split('/');
+  const collection = basename(dirname(projectDir)) === 'members' ? [join(dirname(dirname(projectDir)), 'node_modules', ...pkg)] : [];
+  return [join(projectDir, 'node_modules', ...pkg), ...collection, join(OWN_NODE_MODULES, ...pkg)];
+}
+
+export function locateParts(projectDir: string): string | null {
+  for (const dir of partsCandidates(projectDir)) {
+    if (existsSync(join(dir, 'package.json')) && existsSync(join(dir, CONFIG_SOURCE))) return dir;
+  }
+  return null;
+}
+
+const load = createRequire(import.meta.url);
+
+function isSections(v: unknown): v is Sections {
+  return Array.isArray(v) && v.length > 0 && v.every((s) => typeof s === 'string');
+}
+
+export function readPartsSections(projectDir: string): PartsSections {
+  const dir = locateParts(projectDir);
+  if (dir === null) {
+    throw new PartsUnreadable(
+      'PARTS_NOT_INSTALLED',
+      `${PARTS_PACKAGE} is not installed (looked in ${partsCandidates(projectDir).join(', ')}); run bun install in the project`,
+    );
+  }
+  const pkg: unknown = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+  const version =
+    pkg !== null && typeof pkg === 'object' && 'version' in pkg && typeof pkg.version === 'string' ? pkg.version : 'unknown';
+  const unreadable = (why: string): PartsUnreadable =>
+    new PartsUnreadable('PARTS_SECTIONS_UNREADABLE', `${PARTS_PACKAGE} ${version} at ${dir}: ${why}; the section list cannot be derived (it is exported from 2.3.0)`);
+  let mod: unknown;
+  try {
+    mod = load(join(dir, CONFIG_SOURCE));
+  } catch (e) {
+    throw unreadable(`${CONFIG_SOURCE} does not load (${e instanceof Error ? e.message : String(e)})`);
+  }
+  const sections = mod !== null && typeof mod === 'object' && SECTIONS_EXPORT in mod ? (mod as Record<string, unknown>)[SECTIONS_EXPORT] : undefined;
+  if (!isSections(sections)) throw unreadable(`${CONFIG_SOURCE} has no ${SECTIONS_EXPORT} export holding section names`);
+  return { version, dir, read_from: SECTIONS_EXPORT, sections: [...sections] };
+}

package/src/parts-verdict-record.ts

@@ -0,0 +1,265 @@
+import { draftFileUnavailable, draftInputUnavailable } from './drafts.ts';
+import { checkPartsActEvidence, partsActDraftHash, partsActFindings } from './parts-act.ts';
+import { realpathSync } from './check-reads.ts';
+import { isAbsolute, posix, resolve } from 'node:path';
+import { comparePartsVerdictBindings, type FileBinding } from './parts-verdict.ts';
+/** Review CLI stdout is retained separately from Review's private saved verdict. */
+import { isDeepStrictEqual } from 'node:util';
+import { publicationFile } from './job-publication.ts';
+import { jobHash } from './job-outbox.ts';
+import { decodeReviewAct, reviewActFindings } from './review-act.ts';
+import { Refusal, refuse } from './refusal.ts';
+import { ReviewReadError, storedReviewRead } from './review-read.ts';
+import type { Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+import { PARTS_COMMENTS_VERDICT_SCHEMA, parseCommentsPartsVerdict } from '@rig-c/review/job-host';
+
+export const PARTS_CLI_RECEIPT = 'rig-create/parts-verdict-cli@1';
+export const PARTS_VERDICT_LATEST_SINCE = '2026-11-08T00:00:00Z';
+const object = (value: unknown): value is JsonObject => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sha = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const fail = (code: string, detail: string): never => refuse(code, `project.json.review_acts: ${detail}; query the labelled draft with rig-review parts --format json and record its response again`);
+
+export function decodePartsRead(bytes: Buffer): JsonObject {
+  let value: unknown;
+  try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { return fail('PARTS_REVIEW_CLI_INVALID', 'CLI stdout must be a UTF-8 JSON object'); }
+  if (object(value) && value.schema === PARTS_COMMENTS_VERDICT_SCHEMA) {
+    try { return parseCommentsPartsVerdict(value) as unknown as JsonObject; }
+    catch { return fail('PARTS_REVIEW_CLI_INVALID', 'comments verdict or its declared parts binding is malformed'); }
+  }
+  if (!object(value) || !['rig-review-parts-verdict/1', 'rig-review-parts-verdict/2', 'rig-review-parts-verdict/4'].includes(String(value.schema))
+    || !['approved', 'changes-requested', 'pending'].includes(String(value.status))
+    || !object(value.tool) || typeof value.tool.name !== 'string' || !value.tool.name || typeof value.tool.version !== 'string' || !value.tool.version
+    || !object(value.source) || !sha(value.source.sha256) || !Array.isArray(value.source.files) || !value.source.files.length
+    || !value.source.files.every(file => object(file) && sha(file.sha256))) {
+    return fail('PARTS_REVIEW_CLI_INVALID', 'CLI response needs a supported schema, status, tool, source hashes and per-part outcomes');
+  }
+  if (value.schema === 'rig-review-parts-verdict/4') {
+    if (typeof value.mode !== 'string' || !value.mode || typeof value.updatedAt !== 'string' || !value.updatedAt
+      || !['approved', 'changes-requested'].includes(String(value.status)) || !Array.isArray(value.issues)
+      || (value.status === 'approved') !== (value.issues.length === 0)) {
+      return fail('PARTS_REVIEW_CLI_INVALID', 'CLI response needs a supported schema, status, tool, source hashes and issues');
+    }
+    for (const issue of value.issues) {
+      if (!object(issue) || typeof issue.id !== 'string' || !issue.id || typeof issue.summary !== 'string' || !issue.summary.trim()
+        || !Array.isArray(issue.parts) || !issue.parts.length
+        || !issue.parts.every(part => object(part) && typeof part.name === 'string' && part.name.length > 0 && sha(part.imageHash))
+        || new Set(issue.parts.map(part => (part as JsonObject).name)).size !== issue.parts.length) {
+        return fail('PARTS_REVIEW_CLI_INVALID', 'each CLI issue needs id, summary and unique part bindings');
+      }
+    }
+    return value;
+  }
+  if (!object(value.parts)) {
+    return fail('PARTS_REVIEW_CLI_INVALID', 'CLI response needs a supported schema, status, tool, source hashes and per-part outcomes');
+  }
+  for (const part of Object.values(value.parts)) {
+    if (!object(part) || !['clean', 'flagged', 'pending'].includes(String(part.outcome)) || typeof part.note !== 'string') {
+      return fail('PARTS_REVIEW_CLI_INVALID', 'each CLI part needs its outcome and note');
+    }
+  }
+  return value;
+}
+
+/** Bind a parts receipt's stdout through the shared stored-read validator, keeping this route's codes. */
+function partsStdout(root: string, evidence: JsonObject, path: string): Buffer {
+  try { return storedReviewRead(root, evidence); }
+  catch (error) {
+    if (!(error instanceof ReviewReadError)) throw error;
+    if (error.reason === 'unavailable') return refuse('JOB_PUBLICATION_INVALID', `project.json: ${String(evidence.path)} must be a regular source without symlinks; restore its retained bytes`);
+    return fail('PARTS_VERDICT_RECEIPT_INVALID', `${path}.evidence ${error.reason === 'changed' ? 'bytes changed' : error.why}`);
+  }
+}
+
+export function partsVerdictNames(verdict: JsonObject): { flagged: string[]; noted: string[] } {
+  if (verdict.schema === PARTS_COMMENTS_VERDICT_SCHEMA) {
+    const parsed = parseCommentsPartsVerdict(verdict);
+    const names = [...new Set(parsed.comments.flatMap(comment => comment.anchor && 'schema' in comment.anchor
+      ? comment.anchor.parts.map(part => part.name) : []))];
+    return { flagged: names, noted: [...names] };
+  }
+  if (Array.isArray(verdict.issues)) {
+    const names = [...new Set(verdict.issues.flatMap(issue => object(issue) && Array.isArray(issue.parts)
+      ? issue.parts.filter(object).map(part => String(part.name)) : []))];
+    return { flagged: names, noted: [...names] };
+  }
+  const entries = Object.entries(verdict.parts as JsonObject);
+  return {
+    flagged: entries.filter(([, part]) => (part as JsonObject).outcome === 'flagged').map(([name]) => name),
+    noted: entries.filter(([, part]) => (part as JsonObject).note !== '').map(([name]) => name),
+  };
+}
+
+/** Compare only recorded hashes. Output paths remain in Review's own frame. */
+export function assertPartsReadDraft(root: string, project: JsonObject, verdict: JsonObject, draftId: string, options: { requireAvailable?: boolean } = {}): void {
+  const drafts = Array.isArray(project.drafts) ? project.drafts.filter(d => object(d) && d.id === draftId) : [];
+  const draft = drafts[0];
+  if (drafts.length !== 1 || !object(draft) || !object(draft.parts) || !Array.isArray(draft.parts.files)
+    || !draft.parts.files.length || !draft.parts.files.every(file => object(file) && sha(file.sha256))) {
+    return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId} needs unique recorded parts file hashes`);
+  }
+  const parts = draft.parts;
+  const recorded = parts.files as FileBinding[];
+  const manifest = recorded.find(file => file.path === `${parts.path}/parts.json`);
+  if (!manifest) return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId} has no bound parts.json`);
+  if (draftFileUnavailable(root, manifest.path, `derived/drafts/${draftId}`)) {
+    const source = (verdict.source as JsonObject).files as JsonObject[];
+    if (options.requireAvailable === false && source.some(file => file.sha256 === manifest.sha256)) return;
+    return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId}'s parts.json is unavailable; restore its recorded bytes`);
+  }
+  const bytes = publicationFile(realpathSync(root), manifest.path);
+  if (jobHash(bytes) !== manifest.sha256) return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId}'s parts.json differs from its recorded hash`);
+  const declared: unknown = JSON.parse(bytes.toString('utf8'));
+  const painting = object(declared) && object(declared.painting_in_rig) ? declared.painting_in_rig.path : undefined;
+  const paintingFile = typeof painting === 'string' ? recorded.find(file => file.path === posix.join(String(parts.path), painting)) : undefined;
+  if (painting !== undefined && !paintingFile) return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId}'s declared painting has no recorded hash`);
+  const keep = (file: FileBinding): boolean => paintingFile === undefined || file.sha256 !== paintingFile.sha256;
+  const reviewed = ((verdict.source as JsonObject).files as JsonObject[]).map((file, index) => ({ path: `source.files[${index}]`, sha256: String(file.sha256) }));
+  const outputs = Array.isArray(draft.files) ? draft.files as FileBinding[] : [];
+  const reviewedHashes = new Set(reviewed.map(file => file.sha256));
+  for (const file of [...recorded, ...outputs.filter(file => reviewedHashes.has(file.sha256))]) {
+    if (options.requireAvailable === false && draftFileUnavailable(root, file.path, `derived/drafts/${draftId}`)) continue;
+    if (jobHash(publicationFile(realpathSync(root), file.path)) !== file.sha256) {
+      fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId}'s reviewed file ${file.path} differs from its recorded hash`);
+    }
+  }
+  const { verdictOnly, draftOnly } = comparePartsVerdictBindings(reviewed.filter(keep), recorded.filter(keep), outputs);
+  if (verdictOnly.length || draftOnly.length) fail('PARTS_VERDICT_DRAFT_MISMATCH', `CLI source hashes do not match draft ${draftId}: ${verdictOnly.length} unbound source file(s), ${draftOnly.length} missing part file(s)`);
+}
+
+export function partsReadFindings(root: string, project: JsonObject): Finding[] {
+  if (!Array.isArray(project.review_acts)) return [];
+  const seen = new Set<string>();
+  return project.review_acts.flatMap((entry, index) => {
+    if (!object(entry) || entry.schema !== PARTS_CLI_RECEIPT) return [];
+    const path = `review_acts[${index}]`;
+    try {
+      if (entry.kind !== 'parts-verdict' || entry.route !== 'cli' || typeof entry.draft_id !== 'string'
+        || typeof entry.by !== 'string' || !entry.by.trim() || entry.by.toLowerCase() === 'agent'
+        || typeof entry.at !== 'string' || !Number.isFinite(Date.parse(entry.at))
+        || !Array.isArray(entry.argv) || !entry.argv.length || !entry.argv.every(arg => typeof arg === 'string')
+        || !object(entry.evidence) || !sha(entry.evidence.sha256)
+        || entry.evidence.path !== `evidence/review-reads/${entry.evidence.sha256}.json`) {
+        fail('PARTS_VERDICT_RECEIPT_INVALID', `${path} has invalid CLI receipt metadata`);
+      }
+      assertPartsCliArgs(entry.argv as string[]);
+      const evidence = entry.evidence as JsonObject;
+      const verdict = decodePartsRead(partsStdout(root, evidence, path));
+      const names = partsVerdictNames(verdict);
+      if (entry.status !== verdict.status || !isDeepStrictEqual(entry.tool, verdict.tool)
+        || !isDeepStrictEqual(entry.flagged, names.flagged) || !isDeepStrictEqual(entry.noted, names.noted)) {
+        fail('PARTS_VERDICT_RECEIPT_INVALID', `${path} differs from its retained CLI response`);
+      }
+      assertPartsReadDraft(root, project, verdict, String(entry.draft_id), { requireAvailable: false });
+      const key = JSON.stringify([entry.draft_id, evidence.sha256]);
+      if (seen.has(key)) fail('PARTS_VERDICT_RECEIPT_INVALID', `${path} repeats an earlier CLI receipt`);
+      seen.add(key);
+      return [];
+    } catch (error) {
+      return [{ code: error instanceof Refusal ? error.code : 'PARTS_VERDICT_RECEIPT_INVALID', path,
+        message: error instanceof Refusal ? error.message : `${path}: retained CLI response is unavailable; restore its exact bytes` }];
+    }
+  });
+}
+
+/** Both routes append to one ledger, so its order also determines the current verdict. */
+export function latestPartsVerdictFinding(project: JsonObject, draftId: string, path: string): Finding | undefined {
+  const entry = latestPartsReceipt(project, draftId);
+  if (!object(entry)) return;
+  let status = entry.status;
+  if (entry.schema !== PARTS_CLI_RECEIPT) {
+    try { status = decodeReviewAct(String(entry.bytes), 'parts-verdict').value.verdict; }
+    catch { return; } // The act reader reports malformed receipts.
+  }
+  if (status === 'changes-requested') return { code: 'PARTS_VERDICT_LATEST_NOT_APPROVED', path,
+    message: `${path}: draft ${draftId}'s latest parts verdict requests changes; record a newer approved verdict with parts-review before signing` };
+}
+
+export function assertPartsCliArgs(args: string[]): void {
+  for (const arg of args) {
+    const value = arg.startsWith('--') && arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
+    const normalized = posix.normalize(value.replaceAll('\\', '/'));
+    if (arg === '--' || arg === '--format' || arg.startsWith('--format=') || isAbsolute(value) || /^[A-Za-z]:/.test(value)
+      || normalized === '..' || normalized.startsWith('../') || normalized.startsWith('/')) {
+      refuse('PARTS_REVIEW_CLI_ARGUMENT_INVALID', 'project.json.review_acts.argv: pass project-relative CLI arguments without escapes and let create supply --format json');
+    }
+  }
+}
+
+/** Legacy file bindings remain historical records without opening Review's saved files. */
+export const PARTS_VERDICT_RECEIPT_SINCE = '2026-11-08T00:00:00Z';
+
+export function latestPartsReceipt(project: JsonObject, draftId: string): JsonObject | undefined {
+  return Array.isArray(project.review_acts) ? [...project.review_acts].reverse().find(
+    entry => object(entry) && entry.kind === 'parts-verdict' && entry.draft_id === draftId,
+  ) as JsonObject | undefined : undefined;
+}
+
+/** Shared by both writers and check. Reads only the response retained by parts-review. */
+export function recordedPartsVerdict(root: string, project: JsonObject, draftId: unknown, evidence?: unknown, options: { requireAvailable?: boolean } = {}): { evidence: JsonObject; partsFile: string } {
+  if (typeof draftId !== 'string' || !draftId) return fail('PARTS_VERDICT_RECEIPT_REQUIRED', 'signoffs.parts-review.draft_id needs a recorded draft id');
+  const entries = Array.isArray(project.review_acts) ? project.review_acts : [];
+  const receipt = evidence === undefined ? latestPartsReceipt(project, draftId) : entries.find(entry => object(entry)
+    && entry.kind === 'parts-verdict' && entry.draft_id === draftId && object(entry.evidence) && object(evidence)
+    && entry.evidence.path === evidence.path && entry.evidence.sha256 === evidence.sha256);
+  if (!object(receipt) || !object(receipt.evidence)) {
+    const boundPath = object(evidence) && entries.some(entry => object(entry) && entry.kind === 'parts-verdict'
+      && entry.draft_id === draftId && object(entry.evidence) && entry.evidence.path === evidence.path);
+    if (object(evidence) && (evidence.spec !== undefined || boundPath)) {
+      return fail('PARTS_VERDICT_RECEIPT_INVALID', `signoffs.parts-review.evidence differs from its recorded receipt for draft ${draftId}`);
+    }
+    return fail('PARTS_VERDICT_RECEIPT_REQUIRED', `signoffs.parts-review.evidence needs a parts-review receipt for draft ${draftId}`);
+  }
+  const invalid = [...reviewActFindings(project), ...partsReadFindings(root, project), ...partsActFindings(root, project)][0];
+  if (invalid) refuse(invalid.code, invalid.message);
+  const binding = receipt.evidence;
+  const bytes = receipt.schema === PARTS_CLI_RECEIPT ? partsStdout(root, binding, 'signoffs.parts-review')
+    : publicationFile(realpathSync(root), String(binding.path));
+  let partsFile: string;
+  let spec: string;
+  if (receipt.schema === PARTS_CLI_RECEIPT) {
+    spec = PARTS_CLI_RECEIPT;
+    if (evidence !== undefined && (!object(evidence) || evidence.kind !== 'parts-verdict'
+      || (evidence.spec !== undefined && evidence.spec !== spec))) return fail('PARTS_VERDICT_RECEIPT_INVALID', 'signoffs.parts-review.evidence has an invalid receipt spec');
+    const verdict = decodePartsRead(bytes);
+    assertPartsReadDraft(root, project, verdict, draftId, options);
+    if (verdict.status !== 'approved') return fail('PARTS_VERDICT_NOT_APPROVED', `signoffs.parts-review.evidence for draft ${draftId} is not approved`);
+    const draft = (project.drafts as JsonObject[]).find(draft => draft.id === draftId)!;
+    partsFile = resolve(root, String((draft.parts as JsonObject).path), 'parts.json');
+  } else {
+    if (receipt.schema !== 'rig-create/review-act@1') return fail('PARTS_VERDICT_RECEIPT_INVALID', 'signoffs.parts-review.evidence names an unsupported receipt spec');
+    const act = decodeReviewAct(bytes.toString('utf8'), 'parts-verdict');
+    spec = act.schema;
+    if (evidence !== undefined && (!object(evidence) || evidence.kind !== 'parts-verdict'
+      || (evidence.spec !== undefined && evidence.spec !== spec))) return fail('PARTS_VERDICT_RECEIPT_INVALID', 'signoffs.parts-review.evidence has an invalid receipt spec');
+    if (act.source.selector.id !== draftId) return fail('PARTS_VERDICT_DRAFT_MISMATCH', `signoffs.parts-review.draft_id differs from the retained act for ${draftId}`);
+    const draft = (project.drafts as JsonObject[]).find(draft => draft.id === draftId);
+    const draftRoot = `derived/drafts/${draftId}`;
+    const bound = object(draft) && object(draft.parts) ? [draft.config, ...(draft.parts.files as JsonObject[]), ...(draft.files as JsonObject[])] : [];
+    const inputs = object(draft) && Array.isArray(draft.config_inputs) ? draft.config_inputs as JsonObject[] : [];
+    const unavailable = options.requireAvailable === false && (bound.some(file => object(file)
+      && typeof file.path === 'string' && draftFileUnavailable(root, file.path, draftRoot))
+      || inputs.some(file => object(file) && typeof file.path === 'string' && draftInputUnavailable(root, file.path, draftRoot)));
+    if (unavailable) {
+      if (partsActDraftHash(project, act) !== receipt.version_hash) return fail('PARTS_VERDICT_RECEIPT_INVALID', `draft ${draftId}'s recorded identity changed`);
+      if (act.value.verdict !== 'approved') return fail('PARTS_VERDICT_NOT_APPROVED', `signoffs.parts-review.evidence for draft ${draftId} is not approved`);
+      partsFile = resolve(root, act.source.parts.manifest.path);
+    } else partsFile = checkPartsActEvidence(root, bytes, String(binding.sha256), project);
+  }
+  return { evidence: { kind: 'parts-verdict', path: binding.path, sha256: binding.sha256, spec }, partsFile };
+}
+
+export function recordedPartsFinding(root: string, project: JsonObject, signoff: JsonObject, path: string): Finding | undefined {
+  try {
+    if (!object(signoff.evidence)) fail('PARTS_VERDICT_RECEIPT_REQUIRED', 'signoffs.parts-review.evidence needs a recorded API receipt');
+    recordedPartsVerdict(root, project, signoff.draft_id, signoff.evidence, { requireAvailable: false });
+  }
+  catch (error) {
+    const legacy = error instanceof Refusal && error.code === 'PARTS_VERDICT_RECEIPT_REQUIRED'
+      && typeof signoff.at === 'string' && Date.parse(signoff.at) < Date.parse(PARTS_VERDICT_RECEIPT_SINCE);
+    return { code: legacy ? 'PARTS_VERDICT_FILE_LEGACY' : error instanceof Refusal ? error.code : 'PARTS_VERDICT_RECEIPT_INVALID', path: `${path}.evidence`,
+      message: legacy ? `${path}.evidence: legacy review-saved file binding is preserved; query the reviewed draft through parts-review and record a new signature`
+        : error instanceof Refusal ? error.message : `${path}.evidence: retained API response is unavailable; restore the parts-review receipt and its response` };
+  }
+}

package/src/parts-verdict.ts

@@ -0,0 +1,33 @@
+/** Hash-list comparison for retained parts-review API responses. */
+import { createHash } from 'node:crypto';
+
+export const PARTS_VERDICT_SCHEMA = 'rig-review-parts-verdict/1';
+export const PARTS_VERDICT_SCHEMA_V2 = 'rig-review-parts-verdict/2';
+export const PARTS_VERDICT_KIND = 'parts-verdict';
+export const PARTS_VERDICT_DRAFT_SINCE = '2026-11-08T00:00:00Z';
+
+export type FileBinding = { path: string; sha256: string };
+
+/** Synthetic producer fixtures use Review's canonical source-list hash. */
+export function sourceSha256(files: readonly { path: string; sha256: string }[]): string {
+  const sorted = [...files].sort((a, b) => Buffer.compare(Buffer.from(a.path, 'utf8'), Buffer.from(b.path, 'utf8')));
+  const hash = createHash('sha256');
+  for (const f of sorted) hash.update(`${f.path}\t${f.sha256}\n`, 'utf8');
+  return hash.digest('hex');
+}
+
+function unmatched(side: FileBinding[], other: FileBinding[]): string[] {
+  const counts = new Map<string, number>();
+  for (const f of other) counts.set(f.sha256, (counts.get(f.sha256) ?? 0) + 1);
+  const out: string[] = [];
+  for (const f of side) {
+    const n = counts.get(f.sha256) ?? 0;
+    if (n > 0) counts.set(f.sha256, n - 1);
+    else out.push(f.path);
+  }
+  return out;
+}
+
+export function comparePartsVerdictBindings(reviewed: FileBinding[], parts: FileBinding[], outputs: FileBinding[]): { verdictOnly: string[]; draftOnly: string[] } {
+  return { verdictOnly: unmatched(reviewed, [...parts, ...outputs]), draftOnly: unmatched(parts, reviewed) };
+}