@rig-c/create 0.0.0-stage → 1.0.0

package/src/overrides.ts

@@ -0,0 +1,42 @@
+/** Member-local departures bind the collection answer they departed from. */
+import { asArray, answered, classify, collectItems, collectionAnswer, collectionQuestion, isObject, type Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+
+export const OVERRIDDEN_ANSWERS_SINCE = '2026-11-06T00:00:00Z';
+
+/** Shared by the record check and the writer, before any write. */
+export function overrideFindings(answer: JsonObject, collection: JsonObject | null, path: string): Finding[] {
+  const findings: Finding[] = [];
+  const add = (code: string, why: string, remedy: string): void => {
+    findings.push({ code, path, message: `${path}: ${why}; ${remedy}` });
+  };
+  const ref = isObject(answer.overrides) ? answer.overrides : {};
+  if (collection === null || typeof collection.name !== 'string' || ref.collection !== collection.name) {
+    add('OVERRIDE_COLLECTION_INVALID', 'overrides.collection does not name this member\'s collection', 'restore the parent collection and record its name in overrides.collection');
+  } else {
+    const question = typeof ref.question === 'string' ? collectionQuestion(collection, ref.question) : undefined;
+    const current = typeof ref.question === 'string' ? collectionAnswer(collection, ref.question) : undefined;
+    const answers = [current, ...asArray(question?.history)].filter(isObject).filter(a => answered(classify(a, { collection: null })));
+    if (question === undefined || answers.length === 0) {
+      add('OVERRIDE_QUESTION_INVALID', 'overrides.question names no answered collection question', 'reference an answered collection question, retaining its original answer in history');
+    } else if (typeof ref.collection_answer_at !== 'string' || !Number.isFinite(Date.parse(ref.collection_answer_at)) || !answers.some(a => a.at === ref.collection_answer_at)) {
+      add('OVERRIDE_ANSWER_STALE', 'overrides.collection_answer_at matches no current or historical collection answer', 'restore the referenced collection answer and its exact at timestamp, or ask and record a fresh override');
+    }
+  }
+  if (typeof answer.why_verbatim !== 'string' || !answer.why_verbatim.trim()) {
+    add('OVERRIDE_REASON_MISSING', 'why_verbatim is not a nonempty string', 'ask the user why this member differs and record their exact words with interview-answer --why-file');
+  }
+  return findings;
+}
+
+export function checkOverrides(project: JsonObject, collection: JsonObject | null, refusals: Finding[], warnings: Finding[]): void {
+  for (const item of collectItems(project, { collection })) {
+    const records = [{ answer: item.raw, path: item.path }, ...asArray(item.record.history).map((answer, i) => ({ answer, path: `${item.path.replace(/\.(answer|guide)$/, '')}.history[${i}]` }))];
+    for (const { answer, path } of records) {
+      if (!isObject(answer) || answer.basis !== 'overridden') continue;
+      const at = typeof answer.at === 'string' ? Date.parse(answer.at) : NaN;
+      const target = at < Date.parse(OVERRIDDEN_ANSWERS_SINCE) ? warnings : refusals;
+      target.push(...overrideFindings(answer, collection, path));
+    }
+  }
+}

package/src/package-upgrades.ts

@@ -0,0 +1,32 @@
+/** Optional package migration history: old records need no adoption date. */
+import { isObject, type Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+
+export const PACKAGE_NAMES = ['@rig-c/core', '@rig-c/parts', '@rig-c/review'] as const;
+export const exactVersion = (value: unknown): value is string => typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
+export function compareVersions(a: string, b: string): number {
+  const right = b.split('.').map(Number);
+  for (const [index, value] of a.split('.').map(Number).entries()) {
+    if (value !== right[index]) return value - right[index]!;
+  }
+  return 0;
+}
+
+export function packageUpgradeFindings(project: JsonObject): Finding[] {
+  const history = project.package_upgrades;
+  if (history === undefined) return [];
+  const bad = (path: string): Finding => ({ code: 'PACKAGE_UPGRADE_MALFORMED', path, message: `${path}: invalid package upgrade history; restore the writer's from/to versions, operator, timestamp and lock integrity (rig-create packages upgrade)` });
+  if (!Array.isArray(history)) return [bad('package_upgrades')];
+  const out: Finding[] = [];
+  for (const [index, row] of history.entries()) {
+    const path = `package_upgrades[${index}]`;
+    if (!isObject(row) || typeof row.by !== 'string' || !row.by.trim() || typeof row.at !== 'string' || !Number.isFinite(Date.parse(row.at)) || typeof row.lock_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(row.lock_sha256) || !Array.isArray(row.packages) || row.packages.length !== PACKAGE_NAMES.length) {
+      out.push(bad(path)); continue;
+    }
+    for (const [i, name] of PACKAGE_NAMES.entries()) {
+      const pin = row.packages[i];
+      if (!isObject(pin) || pin.name !== name || (pin.from !== null && !exactVersion(pin.from)) || !exactVersion(pin.to) || (typeof pin.from === 'string' && compareVersions(pin.from, pin.to) > 0)) out.push(bad(`${path}.packages[${i}]`));
+    }
+  }
+  return out;
+}

package/src/packages-upgrade-check.ts

@@ -0,0 +1,6 @@
+/** A fresh process avoids parts module-cache reuse across an install swap. */
+import { checkProject } from './check.ts';
+if (import.meta.main) {
+  const input = await Bun.stdin.json();
+  process.stdout.write(JSON.stringify(checkProject(input.dir, input.project, { now: input.now, readOnly: true })));
+}

package/src/packages-upgrade.ts

@@ -0,0 +1,168 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, lstatSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isObject, type CheckReport } from './check.ts';
+import { acquireBoundJobWrite, jobRuntimeExecArgv } from './job-writer.ts';
+import { PACKAGE_NAMES, compareVersions, exactVersion, packageUpgradeFindings } from './package-upgrades.ts';
+import { PINNED_PACKAGES } from './pins.ts';
+import { Refusal, refuse, USAGE_EXIT } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+/** Value spans permit literal edits without reserializing unrelated JSON. */
+export function jsonSpans(text: string): Map<string, [number, number]> {
+  JSON.parse(text);
+  let at = 0;
+  const spans = new Map<string, [number, number]>();
+  const ws = () => { while (/\s/.test(text[at] ?? '') && at < text.length) at++; };
+  const string = () => { const start = at++; while (at < text.length) { if (text[at++] === '"') break; if (text[at - 1] === '\\') at++; } return JSON.parse(text.slice(start, at)) as string; };
+  const value = (path: string[]) => {
+    ws(); const start = at;
+    if (text[at] === '{') {
+      at++; ws(); const keys = new Set<string>();
+      while (text[at] !== '}') {
+        const key = string();
+        if (keys.has(key)) refuse('PACKAGE_UPGRADE_INPUT', 'package.json/project.json: duplicate JSON keys; remove the ambiguity before packages upgrade');
+        keys.add(key); ws(); at++; value([...path, key]); ws();
+        if (text[at] !== ',') break;
+        at++; ws();
+      }
+      at++;
+    } else if (text[at] === '[') {
+      at++; ws(); let index = 0;
+      while (text[at] !== ']') { value([...path, String(index++)]); ws(); if (text[at] !== ',') break; at++; ws(); }
+      at++;
+    } else if (text[at] === '"') string();
+    else { while (at < text.length && !/[\s,\]}]/.test(text[at]!)) at++; }
+    spans.set(JSON.stringify(path), [start, at]);
+  };
+  value([]); return spans;
+}
+function edit(text: string, path: string[], replacement: string): string {
+  const spans = jsonSpans(text);
+  const span = spans.get(JSON.stringify(path));
+  if (span) return text.slice(0, span[0]) + replacement + text.slice(span[1]);
+  const parent = path.slice(0, -1);
+  const container = spans.get(JSON.stringify(parent));
+  if (!container) refuse('PACKAGE_UPGRADE_INPUT', 'package.json/project.json: missing object; restore the project manifest before packages upgrade');
+  const object = JSON.parse(text.slice(...container));
+  const pos = container[1] - 1;
+  return text.slice(0, pos) + `${Object.keys(object).length ? ',' : ''}\n  ${JSON.stringify(path.at(-1))}: ${replacement}\n` + text.slice(pos);
+}
+function appendUpgrade(text: string, row: object): string {
+  const span = jsonSpans(text).get(JSON.stringify(['package_upgrades']));
+  if (!span) return edit(text, ['package_upgrades'], JSON.stringify([row]));
+  const prior = JSON.parse(text.slice(...span));
+  const at = span[1] - 1;
+  return text.slice(0, at) + `${prior.length ? ',' : ''}${JSON.stringify(row)}` + text.slice(at);
+}
+function checked(dir: string, project: JsonObject, now: number): CheckReport {
+  const child = Bun.spawnSync([process.execPath, ...jobRuntimeExecArgv(), join(import.meta.dir, 'packages-upgrade-check.ts')], { stdin: Buffer.from(JSON.stringify({ dir, project, now })), stdout: 'pipe', stderr: 'pipe' });
+  if (child.exitCode !== 0) refuse('PACKAGE_UPGRADE_CHECK_FAILED', 'project.json: check process failed; restore the installed packages and retry packages upgrade');
+  return JSON.parse(child.stdout.toString()) as CheckReport;
+}
+
+export function packagesCommand(args: string[], now: number): string {
+  if (args[0] !== 'upgrade') refuse('PACKAGE_UPGRADE_USAGE', 'project.json: use packages upgrade [dir] --by <operator>', USAGE_EXIT);
+  let by = ''; let dirArg: string | undefined;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--by' && !by && args[i + 1] && !args[i + 1]!.startsWith('-')) by = args[++i]!;
+    else if (!arg.startsWith('-') && dirArg === undefined) dirArg = arg;
+    else refuse('PACKAGE_UPGRADE_USAGE', 'project.json: use packages upgrade [dir] --by <operator>', USAGE_EXIT);
+  }
+  if (!by.trim()) refuse('PACKAGE_UPGRADE_USAGE', 'project.json: packages upgrade requires --by <operator>', USAGE_EXIT);
+  const dir = resolve(dirArg ?? process.cwd());
+  const release = acquireBoundJobWrite(dir);
+  const lock = join(dir, '.rig-create-packages.lock');
+  let fd: number;
+  try { fd = openSync(lock, 'wx'); } catch { release(); return refuse('PACKAGE_UPGRADE_CONFLICT', 'project.json: another package writer holds the lock; finish it before packages upgrade'); }
+  let scratch: string | undefined;
+  let swapped = false; let committed = false;
+  const backup = join(dir, `.node_modules-${randomUUID()}`);
+  const paths = ['package.json', 'bun.lock', 'project.json'];
+  const originals = new Map<string, Buffer | null>();
+  try {
+    for (const path of paths) originals.set(path, existsSync(join(dir, path)) ? readFileSync(join(dir, path)) : null);
+    const pkgBytes = originals.get('package.json'); const recordBytes = originals.get('project.json');
+    if (!pkgBytes || !recordBytes) refuse('PACKAGE_UPGRADE_INPUT', 'project.json/package.json: missing record or manifest; restore them before packages upgrade');
+    let pkg: JsonObject; let project: JsonObject;
+    try { pkg = JSON.parse(pkgBytes.toString()); project = JSON.parse(recordBytes.toString()); jsonSpans(pkgBytes.toString()); jsonSpans(recordBytes.toString()); }
+    catch { return refuse('PACKAGE_UPGRADE_INPUT', 'project.json/package.json: invalid JSON; restore valid objects before packages upgrade'); }
+    if (!isObject(project) || !isObject(pkg)) refuse('PACKAGE_UPGRADE_INPUT', 'project.json/package.json: expected JSON objects; restore valid objects before packages upgrade');
+    if (project.schema !== 'rig-create/project@0' || !pkg.dependencies || typeof pkg.dependencies !== 'object' || Array.isArray(pkg.dependencies)) refuse('PACKAGE_UPGRADE_INPUT', 'project.json/package.json: expected a project and dependencies object; restore them before packages upgrade');
+    const malformed = packageUpgradeFindings(project)[0];
+    if (malformed) refuse(malformed.code, malformed.message);
+    const dependencies = pkg.dependencies as JsonObject;
+    const pins = { ...PINNED_PACKAGES, '@rig-c/review': JSON.parse(readFileSync(join(import.meta.dir, '../package.json'), 'utf8')).dependencies['@rig-c/review'] as string };
+    const packages = PACKAGE_NAMES.map(name => {
+      const from = dependencies[name] ?? null; const to = pins[name];
+      if (!exactVersion(to) || from !== null && !exactVersion(from)) refuse('PACKAGE_UPGRADE_INPUT', `package.json.dependencies[${name}]: expected an exact release version; resolve ranges before packages upgrade`);
+      if (from !== null && compareVersions(from as string, to) > 0) refuse('PACKAGE_UPGRADE_DOWNGRADE', `package.json.dependencies[${name}]: ${from} is newer than ${to}; use a newer Create release`);
+      for (const section of ['devDependencies', 'optionalDependencies', 'peerDependencies']) {
+        if (pkg[section] && typeof pkg[section] === 'object' && name in pkg[section]) refuse('PACKAGE_UPGRADE_INPUT', `package.json.${section}[${name}]: duplicate pin location; keep the release pin in dependencies before packages upgrade`);
+      }
+      return { name, from, to };
+    });
+    if (packages.every(pin => pin.from === pin.to)) refuse('PACKAGE_UPGRADE_CURRENT', 'package.json.dependencies: all packages already match Create release pins; no upgrade to record');
+    // A staging install must not resolve local dependencies against a different directory.
+    for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+      const entries = pkg[section];
+      if (entries && typeof entries === 'object') for (const value of Object.values(entries)) if (typeof value === 'string' && /^(?:file:|link:|workspace:|\.\.?\/|\/)/.test(value)) refuse('PACKAGE_UPGRADE_INPUT', `package.json.${section}: local dependencies cannot be staged safely; publish or resolve them before packages upgrade`);
+    }
+    if (pkg.workspaces) refuse('PACKAGE_UPGRADE_INPUT', 'package.json.workspaces: upgrade a standalone project install; resolve workspace ownership before packages upgrade');
+    const before = checked(dir, project, now);
+    if (before.stage === null) refuse('PACKAGE_UPGRADE_CHECK_FAILED', 'project.json: check stopped before validating the project; repair its schema and stage before packages upgrade');
+    let manifest = pkgBytes.toString();
+    for (const pin of packages) manifest = edit(manifest, ['dependencies', pin.name], JSON.stringify(pin.to));
+    scratch = mkdtempSync(join(tmpdir(), 'rig-create-packages-'));
+    writeFileSync(join(scratch, 'package.json'), manifest);
+    const oldLock = originals.get('bun.lock');
+    if (oldLock) writeFileSync(join(scratch, 'bun.lock'), oldLock);
+    const install = Bun.spawnSync([process.execPath, 'install', '--ignore-scripts'], { cwd: scratch, stdout: 'pipe', stderr: 'pipe' });
+    if (install.exitCode !== 0 || !existsSync(join(scratch, 'bun.lock'))) refuse('PACKAGE_UPGRADE_INSTALL', 'package.json/bun.lock: staged bun install failed; check registry access and package versions before retrying packages upgrade');
+    const nextLock = readFileSync(join(scratch, 'bun.lock'));
+    const row = { by, at: new Date(now).toISOString(), packages, lock_sha256: createHash('sha256').update(nextLock).digest('hex') };
+    const history = [...(project.package_upgrades as JsonObject[] | undefined ?? []), row];
+    const candidate = { ...project, package_upgrades: history };
+    const invalid = packageUpgradeFindings(candidate)[0];
+    if (invalid) refuse(invalid.code, invalid.message);
+    for (const [path, bytes] of originals) {
+      const current = existsSync(join(dir, path)) ? readFileSync(join(dir, path)) : null;
+      if (bytes === null ? current !== null : !current?.equals(bytes)) refuse('PACKAGE_UPGRADE_CONFLICT', `project.json: ${path} changed during installation; retry packages upgrade against the current files`);
+    }
+    if (existsSync(join(dir, 'node_modules'))) {
+      if (!lstatSync(join(dir, 'node_modules')).isDirectory()) refuse('PACKAGE_UPGRADE_INPUT', 'package.json: node_modules must be a project-owned directory; restore a standalone install before packages upgrade');
+      renameSync(join(dir, 'node_modules'), backup);
+    }
+    swapped = true;
+    renameSync(join(scratch, 'node_modules'), join(dir, 'node_modules'));
+    // The check sees the candidate install and package pins, but never a committed history row.
+    writeFileSync(join(dir, 'package.json'), manifest);
+    writeFileSync(join(dir, 'bun.lock'), nextLock);
+    const after = checked(dir, candidate, now);
+    const counts = new Map<string, number>();
+    const key = (finding: CheckReport['refusals'][number]) => JSON.stringify(finding);
+    for (const finding of before.refusals) counts.set(key(finding), (counts.get(key(finding)) ?? 0) + 1);
+    for (const finding of after.refusals) {
+      const count = counts.get(key(finding)) ?? 0;
+      if (!count) refuse('PACKAGE_UPGRADE_REFUSAL', `project.json: ${finding.code} at ${finding.path} changed after upgrading ${packages.filter(pin => pin.from !== pin.to).map(pin => pin.name).join(', ')}; keep the original pins and resolve this finding before retrying (${finding.message})`);
+      counts.set(key(finding), count - 1);
+    }
+    writeFileSync(join(dir, 'project.json'), appendUpgrade(recordBytes.toString(), row));
+    committed = true;
+    return `packages: upgraded ${packages.map(pin => `${pin.name} ${pin.from ?? '(absent)'} → ${pin.to}`).join(', ')}; recorded package_upgrades[${history.length - 1}]`;
+  } catch (error) {
+    if (error instanceof Refusal) throw error;
+    return refuse('PACKAGE_UPGRADE_INSTALL', 'project.json/package.json: package migration could not complete; restore filesystem access and retry packages upgrade');
+  } finally {
+    if (swapped && !committed) {
+      rmSync(join(dir, 'node_modules'), { recursive: true, force: true });
+      if (existsSync(backup)) renameSync(backup, join(dir, 'node_modules'));
+      for (const [path, bytes] of originals) if (bytes === null) rmSync(join(dir, path), { force: true }); else writeFileSync(join(dir, path), bytes);
+    }
+    if (committed) rmSync(backup, { recursive: true, force: true });
+    if (scratch) rmSync(scratch, { recursive: true, force: true });
+    closeSync(fd); rmSync(lock); release();
+  }
+}

package/src/parts-act.ts

@@ -0,0 +1,96 @@
+import { PARTS_CLI_RECEIPT } from './parts-verdict-record.ts';
+/** Typed semantic evidence retained by the parts-review API route. */
+import { dirname, join } from 'node:path';
+import { readFileSync } from './check-reads.ts';
+import { isDeepStrictEqual } from 'node:util';
+import { publicationFile, publishedDraft } from './job-publication.ts';
+import { jobHash, publicationVersionHash } from './job-outbox.ts';
+import { decodeReviewAct, partsActIssues, type PartsVerdictAct } from './review-act.ts';
+import { stepHash } from './step-hash.ts';
+import { refuse } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+const object = (value: unknown): value is JsonObject => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (why: string): never => refuse('REVIEW_ACT_SOURCE_STALE', `project.json.review_acts: ${why}; restore the reviewed draft or record and review a new draft id`);
+
+export function partsActDraftHash(project: JsonObject, act: PartsVerdictAct): string {
+  const hash = publicationVersionHash(Buffer.from(JSON.stringify(project)), { path: '', selector: act.source.selector });
+  return hash ?? fail('reviewed draft is absent');
+}
+
+export function partsActReceipt(project: JsonObject, act: PartsVerdictAct): JsonObject | undefined {
+  return Array.isArray(project.review_acts) ? project.review_acts.find(entry => object(entry) && entry.jobId === act.jobId && entry.actId === act.actId) as JsonObject | undefined : undefined;
+}
+
+/** File hashes are checked as declared. No enumeration or producer measurement. */
+export function assertPartsActSource(root: string, project: JsonObject, act: PartsVerdictAct, options: { comparePlan?: boolean } = {}): void {
+  let draft: JsonObject;
+  try { draft = publishedDraft(project, act.source.selector.id); }
+  catch { return fail('reviewed draft is absent or ambiguous'); }
+  const parts = draft.parts as JsonObject;
+  const bound = [draft.config, ...(draft.config_inputs as JsonObject[] ?? []), ...(parts.files as JsonObject[]), ...(draft.files as JsonObject[])];
+  const check = (identity: { path: string; sha256: string }): void => {
+    try { if (jobHash(publicationFile(root, identity.path)) !== identity.sha256) fail(`${identity.path} changed`); }
+    catch { fail(`${identity.path} is absent or changed`); }
+  };
+  for (const raw of bound) {
+    if (!object(raw) || typeof raw.path !== 'string' || typeof raw.sha256 !== 'string') return fail('draft file identity is malformed');
+    check({ path: String(raw.path), sha256: String(raw.sha256) });
+  }
+  if (act.source.parts.manifest.path !== `${parts.path}/parts.json`) fail('parts manifest differs from the selected draft');
+  const manifestIdentity = (parts.files as JsonObject[]).find(file => file.path === act.source.parts.manifest.path);
+  if (manifestIdentity?.sha256 !== act.source.parts.manifest.sha256) fail('manifest hash differs from the draft');
+  check(act.source.parts.manifest);
+  for (const image of act.source.parts.images) check({ path: join(dirname(act.source.parts.manifest.path), image.path), sha256: image.sha256 });
+  const manifest = JSON.parse(publicationFile(root, act.source.parts.manifest.path).toString('utf8')) as { parts: { name: string }[] };
+  const names = manifest.parts.map(part => part.name).sort();
+  const issues = partsActIssues(act);
+  if (issues !== null) {
+    const manifestNames = new Set(names);
+    if (issues.some(issue => issue.parts.some(part => !manifestNames.has(part.name)))) fail('verdict part membership differs from the bound manifest');
+  } else if (act.schema === 'rig-review/act@2' && !isDeepStrictEqual(names, act.value.parts.map(part => part.partId).sort())) fail('verdict part membership differs from the bound manifest');
+  if (act.source.model) {
+    if (!(draft.files as JsonObject[]).some(file => file.path === act.source.model!.path && file.sha256 === act.source.model!.sha256)) fail('displayed model is outside the selected draft');
+    check(act.source.model);
+  }
+  if (act.source.direction) check(act.source.direction);
+  if (act.source.plan && options.comparePlan !== false) {
+    const steps = object(project.plan) && Array.isArray(project.plan.steps) ? project.plan.steps : [];
+    if (!isDeepStrictEqual(act.source.plan.steps, steps.map(step => ({ id: object(step) ? step.id : null, hash: object(step) ? stepHash(step) : null })))) fail('displayed plan changed');
+  }
+  const publication = JSON.parse(publicationFile(root, `review-draft-${draft.id}.json`).toString('utf8')) as JsonObject;
+  if (publication.id !== act.source.package.id || publication.revision !== act.source.package.revision
+    || act.source.package.revision !== partsActDraftHash(project, act)
+    || (publication.model ?? null) !== (act.source.model?.path ?? null)) fail('published package identity changed');
+}
+
+export function partsActFindings(root: string, project: JsonObject): { code: string; path: string; message: string }[] {
+  if (!Array.isArray(project.review_acts)) return [];
+  return project.review_acts.flatMap((entry, index) => {
+    if (!object(entry) || entry.kind !== 'parts-verdict' || entry.schema === PARTS_CLI_RECEIPT) return [];
+    const path = `review_acts[${index}].evidence`;
+    try {
+      if (entry.schema !== 'rig-create/review-act@1' || typeof entry.jobId !== 'string' || typeof entry.actId !== 'string'
+        || !object(entry.evidence) || entry.evidence.path !== `evidence/review-acts/${jobHash(JSON.stringify([entry.jobId, entry.actId]))}.json`
+        || entry.evidence.sha256 !== entry.sha256) throw Error();
+      const bytes = publicationFile(root, entry.evidence.path);
+      if (jobHash(bytes) !== entry.sha256 || bytes.toString('utf8') !== entry.bytes) throw Error();
+      decodeReviewAct(bytes.toString('utf8'), 'parts-verdict');
+      return [];
+    } catch { return [{ code: 'REVIEW_ACT_LEDGER_INVALID', path, message: `${path}: retained evidence differs from its act receipt; restore the original evidence and ledger together` }]; }
+  });
+}
+
+export function checkPartsActEvidence(root: string, bytes: Buffer, evidenceHash: string, candidate?: JsonObject): string {
+  const act = decodeReviewAct(bytes.toString('utf8'), 'parts-verdict');
+  const project = candidate ?? JSON.parse(readFileSync(join(root, 'project.json'), 'utf8')) as JsonObject;
+  const receipt = partsActReceipt(project, act);
+  if (!receipt || receipt.kind !== 'parts-verdict' || receipt.sha256 !== evidenceHash || receipt.bytes !== bytes.toString('utf8')) {
+    refuse('REVIEW_ACT_LEDGER_INVALID', 'project.json.review_acts: parts evidence has no matching recorded receipt; ingest it with parts-review --from-review');
+  }
+  // Later plan approvals can fill checkpoints without changing the reviewed draft.
+  assertPartsActSource(root, project, act, { comparePlan: false });
+  if (partsActDraftHash(project, act) !== receipt.version_hash) fail('recorded draft entry changed');
+  if (act.value.verdict !== 'approved') refuse('PARTS_VERDICT_NOT_APPROVED', 'signoffs.parts-review.evidence: semantic verdict is not approved; review the corrected draft and record a separate approval');
+  return join(root, act.source.parts.manifest.path);
+}

package/src/parts-check.ts

@@ -0,0 +1,242 @@
+/**
+ * The parts-stage check report that a `parts` → `parts-review` move binds
+ * (docs/PROJECT.md § Recording forward progress, docs/CHECKS.md § Parts-stage check at the parts → parts-review move).
+ *
+ * The report is `@rig-c/parts`' `rig-parts check-parts` output, spec `rig-parts-parts-check/1`.
+ * create reads it bound by the sha256 of its bytes and by its spec, copies `exit_code`, `holes` and
+ * `reported` from it, and never runs or recomputes it. Matching the report to the parts on disk hashes
+ * the files under the assembled root and compares them with the report's own `inputs` rows; that is a
+ * binding, not a measurement. The writer and the check share `partsCheckFindings`.
+ */
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from './check-reads.ts';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, isObject, type Ctx, type Finding } from './check.ts';
+import { sha256 } from './choices.ts';
+import { IGNORED_DIRS } from './init.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const PARTS_CHECK_SPEC = 'rig-parts-parts-check/1';
+
+/** Dates the parts-check requirement by the advance's own `at`. */
+export const PARTS_CHECK_SINCE = '2026-11-08T00:00:00Z';
+
+const REPORT_KEYS = ['spec', 'stage', 'inputs', 'parts', 'refusals', 'reported', 'holes', 'exit_code'];
+const RECORD_KEYS = ['path', 'sha256', 'spec', 'parts', 'exit_code', 'holes', 'reported'];
+const ROW_KEYS: Record<string, readonly string[]> = {
+  inputs: ['path', 'status', 'sha256'],
+  refusals: ['code', 'object', 'found', 'required', 'detail'],
+  reported: ['code', 'set', 'part', 'source', 'count', 'spans'],
+  holes: ['code', 'object', 'reason', 'line'],
+};
+const STATUSES = ['read', 'missing', 'unreadable', 'absent'];
+/** The roots a clone does not carry, as the path is written; a link inside the project is followed as for the parts verdict. */
+const isIgnoredRoot = (root: string): boolean => [...IGNORED_DIRS, 'node_modules', '.git'].includes(root);
+const RUN = 'run rig-parts check-parts --parts <assembled dir> --out <dir outside it>, retain parts-check.json under the project (for example evidence/) and advance with --parts-check <report> --parts <assembled dir>';
+
+/** The move whose arrival needs a passing parts-stage check. */
+export function isPartsCheckMove(entry: JsonObject): boolean {
+  return entry.from_stage === 'parts' && entry.stage === 'parts-review';
+}
+
+const literal = (value: Json | undefined): value is string => typeof value === 'string' && value !== ''
+  && !isAbsolute(value) && !value.includes('\\') && value.split('/').every(segment => segment !== '' && segment !== '.' && segment !== '..');
+const code = (value: Json | undefined): boolean => typeof value === 'string' && /^[A-Z][A-Z0-9_]*$/.test(value);
+const finding = (code: string, path: string, why: string, remedy: string): Finding => ({ code, path, message: `${path}: ${why}; ${remedy}` });
+
+/** Read the retained report bytes at a project-relative path, the way both the writer and the check do. */
+export function readPartsCheckBytes(dir: string, path: Json | undefined, at: string): Buffer | Finding {
+  const unread = (why: string): Finding => finding('PARTS_CHECK_UNREAD', at, why, RUN);
+  if (!literal(path)) return unread('the report needs a literal project-relative path');
+  // Contained as the parts verdict is: as written, and with every link on its way followed.
+  let file: string;
+  try {
+    const root = realpathSync(dir);
+    file = realpathSync(resolve(dir, path));
+    const rel = relative(root, file);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return unread(`${path} leaves the project through a link`);
+    if (!statSync(file).isFile()) return unread(`${path} is not a regular file`);
+  } catch { return unread(`${path} is not there`); }
+  if (isIgnoredRoot(path.split('/')[0]!)) return unread(`${path} is under an ignored root and would not survive a clone`);
+  try {
+    return readFileSync(file);
+  } catch (error) {
+    return unread(`${path} cannot be read (${error instanceof Error ? error.message : String(error)})`);
+  }
+}
+
+function parseReport(bytes: Buffer): JsonObject | null {
+  try {
+    const value = JSON.parse(bytes.toString('utf8')) as Json;
+    return isObject(value) ? value : null;
+  } catch { return null; }
+}
+
+/** Shape of `rig-parts-parts-check/1` as STABILITY.md states it; no field is recomputed. */
+function reportShape(report: JsonObject): string | null {
+  if (report.spec !== PARTS_CHECK_SPEC) return `spec is ${JSON.stringify(report.spec ?? null)}, not ${PARTS_CHECK_SPEC}`;
+  if (report.stage !== 'parts') return `stage is ${JSON.stringify(report.stage ?? null)}, not parts`;
+  if (Object.keys(report).join(',') !== REPORT_KEYS.join(',')) return `top-level keys must be ${REPORT_KEYS.join(', ')} in that order`;
+  if (!isObject(report.parts)) return 'parts must be an object';
+  if (!Number.isSafeInteger(report.exit_code)) return 'exit_code must be an integer';
+  for (const [key, keys] of Object.entries(ROW_KEYS)) {
+    const rows = report[key];
+    if (!Array.isArray(rows)) return `${key} must be a list`;
+    for (const [index, row] of rows.entries()) {
+      if (!isObject(row) || Object.keys(row).join(',') !== keys.join(',')) return `${key}[${index}] must have ${keys.join(', ')}`;
+      if (key !== 'inputs' && !code(row.code)) return `${key}[${index}].code must be a SCREAMING_SNAKE_CASE code`;
+    }
+  }
+  const paths = new Set<string>();
+  for (const [index, row] of (report.inputs as JsonObject[]).entries()) {
+    if (!literal(row.path) || paths.has(row.path)) return `inputs[${index}].path must be a unique relative POSIX path`;
+    paths.add(row.path);
+    if (!STATUSES.includes(String(row.status))) return `inputs[${index}].status must be ${STATUSES.join(', ')}`;
+    if (row.status === 'read' ? !(typeof row.sha256 === 'string' && /^[a-f0-9]{64}$/.test(row.sha256)) : row.sha256 !== null) {
+      return `inputs[${index}].sha256 must be a sha256 for a read file and null otherwise`;
+    }
+  }
+  for (const [index, row] of (report.holes as JsonObject[]).entries()) {
+    if (['object', 'reason', 'line'].some(key => typeof row[key] !== 'string')) return `holes[${index}] needs text object, reason and line`;
+  }
+  return null;
+}
+
+/** Every regular file under the root, by relative POSIX path, hashed; a symlink or special file is named. */
+function inventory(root: string): { files: Map<string, string>; other: string[] } {
+  const files = new Map<string, string>();
+  const other: string[] = [];
+  const walk = (abs: string, rel: string): void => {
+    for (const entry of readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const path = rel === '' ? entry.name : `${rel}/${entry.name}`;
+      const stat = lstatSync(join(abs, entry.name));
+      if (stat.isDirectory()) walk(join(abs, entry.name), path);
+      else if (stat.isFile()) files.set(path, sha256(readFileSync(join(abs, entry.name))));
+      else other.push(path);
+    }
+  };
+  walk(root, '');
+  return { files, other };
+}
+
+/** Why the report no longer matches the assembled parts on disk, or null when it does. */
+function staleness(dir: string, partsRoot: string, inputs: JsonObject[]): string[] | null {
+  let root: string;
+  try {
+    root = resolve(realpathSync(dir), partsRoot);
+    const stat = lstatSync(root);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) return [`${partsRoot} is not a directory`];
+  } catch { return [`${partsRoot} is not a directory`]; }
+  const { files, other } = inventory(root);
+  const manifest = files.has('parts.json') ? parseReport(readFileSync(join(root, 'parts.json'))) : null;
+  const scenes = [manifest?.scene, ...asArray(manifest?.alternates).filter(isObject).map(set => set.scene)];
+  // The producer excludes this declared root mask from its report inputs (#1177).
+  const excludesFigureMask = scenes.some(scene => isObject(scene) && scene.figure_mask === 'figure_rig.png');
+  const reasons = other.map(path => `${path} is not a regular file`);
+  const named = new Set<string>();
+  for (const row of inputs) {
+    const path = String(row.path);
+    named.add(path);
+    const now = files.get(path);
+    if (row.status === 'read') {
+      if (now === undefined) reasons.push(`${path} is gone`);
+      else if (now !== row.sha256) reasons.push(`${path} changed after the check`);
+    } else if (row.status === 'absent') {
+      if (now !== undefined) reasons.push(`${path} was absent at the check and exists now`);
+    } else reasons.push(`${path} was ${String(row.status)} at the check`);
+  }
+  for (const path of files.keys()) {
+    if (!named.has(path) && !(excludesFigureMask && path === 'figure_rig.png')) reasons.push(`${path} is not in the report's inputs`);
+  }
+  return reasons.length === 0 ? null : reasons;
+}
+
+/**
+ * Validate one recorded `parts_check`. Always: the closed shape, the retained bytes hashing to `sha256`,
+ * the report's spec and shape, the copied fields, and a passing report. At the move only: the report
+ * matches the parts under `parts` on disk now. The first failing rule is the finding.
+ */
+export function partsCheckFindings(dir: string, record: Json | undefined, path: string, atMove: boolean): Finding[] {
+  const invalid = (why: string): Finding[] => [finding('PARTS_CHECK_INVALID', path, why, `record the report through advance; ${RUN}`)];
+  if (!isObject(record) || Object.keys(record).length !== RECORD_KEYS.length || !RECORD_KEYS.every(key => key in record)) {
+    return invalid(`must have exactly ${RECORD_KEYS.join(', ')}`);
+  }
+  if (!literal(record.parts)) return invalid('parts must be the literal project-relative assembled root');
+  if (typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(record.sha256)) return invalid('sha256 must be the report bytes\' sha256');
+  const bytes = readPartsCheckBytes(dir, record.path, `${path}.path`);
+  if (!Buffer.isBuffer(bytes)) return [bytes];
+  if (sha256(bytes) !== record.sha256) {
+    return [finding('PARTS_CHECK_CHANGED', `${path}.sha256`, `${String(record.path)} no longer hashes to the recorded sha256`, 'restore the retained report bytes the move recorded; a new check is recorded by a new parts → parts-review move')];
+  }
+  const report = parseReport(bytes);
+  if (report === null) return [finding('PARTS_CHECK_UNREAD', `${path}.path`, `${String(record.path)} is not a JSON object`, RUN)];
+  const shape = reportShape(report);
+  if (shape !== null) return invalid(`${String(record.path)}: ${shape}`);
+  if (record.spec !== report.spec || record.exit_code !== report.exit_code || !isDeepStrictEqual(record.holes, report.holes) || !isDeepStrictEqual(record.reported, report.reported)) {
+    return invalid('spec, exit_code, holes and reported must be copied verbatim from the retained report');
+  }
+  const refusals = asArray(report.refusals).filter(isObject);
+  if (report.exit_code !== 0 || refusals.length > 0) {
+    const codes = refusals.map(row => String(row.code));
+    return [finding('PARTS_CHECK_FAILED', path, `the report records exit_code ${String(report.exit_code)}${codes.length === 0 ? '' : ` and refusals ${codes.join(', ')}`}`, 'fix the refused parts, rerun rig-parts check-parts and advance with the passing report')];
+  }
+  if (atMove) {
+    const reasons = staleness(dir, record.parts, report.inputs as JsonObject[]);
+    if (reasons !== null) {
+      const shown = reasons.slice(0, 3).join('; ') + (reasons.length > 3 ? `; and ${reasons.length - 3} more` : '');
+      return [finding('PARTS_CHECK_STALE', path, `the report does not match the parts under ${record.parts}: ${shown}`, 'rerun rig-parts check-parts on the assembled parts as they are now and advance with that report')];
+    }
+  }
+  return [];
+}
+
+/** The writer's copy of the report: path and sha256 of its bytes, and spec, exit_code, holes and reported as written. */
+export function partsCheckRecord(dir: string, reportPath: string, partsRoot: string, path: string): { record: JsonObject } | { refusal: Finding } {
+  const bytes = readPartsCheckBytes(dir, reportPath, `${path}.path`);
+  if (!Buffer.isBuffer(bytes)) return { refusal: bytes };
+  const report = parseReport(bytes);
+  if (report === null) return { refusal: finding('PARTS_CHECK_UNREAD', `${path}.path`, `${reportPath} is not a JSON object`, RUN) };
+  const copy = (value: Json | undefined): Json => value === undefined ? null : structuredClone(value);
+  return { record: { path: reportPath, sha256: sha256(bytes), spec: copy(report.spec), parts: partsRoot,
+    exit_code: copy(report.exit_code), holes: copy(report.holes), reported: copy(report.reported) } };
+}
+
+/**
+ * Each `parts` → `parts-review` advance binds a passing report. Missing on a move dated from
+ * `PARTS_CHECK_SINCE`, or on the move being written, is refused; on an earlier move it WARNs.
+ * A `parts_check` on any other move is refused. Staleness is judged only for the move being written.
+ */
+export function checkPartsChecks(ctx: Ctx, forwardWrite = false): void {
+  const advances = asArray(ctx.project.advances);
+  const since = Date.parse(PARTS_CHECK_SINCE);
+  for (const [index, entry] of advances.entries()) {
+    if (!isObject(entry)) continue;
+    const path = `advances[${index}].parts_check`;
+    const atMove = forwardWrite && index === advances.length - 1;
+    if (entry.parts_check === undefined) {
+      if (!isPartsCheckMove(entry)) continue;
+      if (atMove || !(Date.parse(String(entry.at)) < since)) {
+        ctx.refusals.push(finding('PARTS_CHECK_MISSING', path, 'a parts → parts-review move needs a passing parts-stage check report', RUN));
+      } else {
+        ctx.warnings.push(finding('PARTS_CHECK_MISSING', path, `the move predates ${PARTS_CHECK_SINCE} and binds no parts-stage check report`, 'preserve the historical move; the next parts → parts-review move binds a report'));
+      }
+      continue;
+    }
+    if (!isPartsCheckMove(entry)) {
+      ctx.refusals.push(finding('PARTS_CHECK_INVALID', path, 'a parts-stage check report is recorded only on a parts → parts-review move', 'restore the move as advance wrote it'));
+      continue;
+    }
+    ctx.refusals.push(...partsCheckFindings(ctx.dir, entry.parts_check, path, atMove));
+  }
+}
+
+/** One named line per HOLE and per reported row, for the advance output. */
+export function partsCheckLines(record: JsonObject, path: string): string[] {
+  const holes = asArray(record.holes).filter(isObject);
+  const reported = asArray(record.reported).filter(isObject);
+  return [
+    `  parts check ${String(record.path)}: exit_code ${String(record.exit_code)}, ${holes.length} HOLE, ${reported.length} reported; a HOLE is not a pass`,
+    ...holes.map((row, index) => `  ${String(row.line)} (${path}.holes[${index}])`),
+    ...reported.map((row, index) => `  REPORTED ${String(row.code)}: part ${String(row.part)}, source ${String(row.source)}, count ${String(row.count)} (${path}.reported[${index}])`),
+  ];
+}