@rig-c/create 0.0.0-stage → 1.0.1

package/src/pre-interview.ts

@@ -0,0 +1,302 @@
+/** Checked migration history for versions built before the interview (#39). */
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from './check-reads.ts';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import { asArray, asString, isObject, type Finding } from './check.ts';
+import { REVIEW_ACCEPTS } from './stages.ts';
+import type { JsonObject } from './templates.ts';
+
+/** Exact legacy spellings only. An unlisted value requires a documented mapping. */
+export const PRE_INTERVIEW_VERDICTS: Readonly<Record<string, string>> = Object.freeze({
+  accepted: 'accepted',
+  Accepted: 'accepted',
+  'accepted (sent to owner)': 'accepted',
+  'Accepted (sent to owner)': 'accepted',
+  'accepted (HQ-provisional, sent to owner)': 'provisional',
+  'accepted-provisional': 'provisional',
+  'ok for now, polish wanted': 'accepted',
+  'close, polish wanted': 'provisional',
+  bounced: 'bounced',
+  Bounced: 'bounced',
+  provisional: 'provisional',
+  Provisional: 'provisional',
+});
+
+/** Extra record requirements apply only to pre-interview versions. */
+function preInterviewVerdictProblems(d: JsonObject): string[] {
+  const problems: string[] = [];
+  for (const k of ['by', 'at', 'source']) if (typeof d[k] !== 'string' || d[k].trim() === '') problems.push(`no ${k}`);
+  if (typeof d.at === 'string' && !Number.isFinite(Date.parse(d.at))) problems.push('at is not a valid timestamp');
+  if (d.verbatim === null) {
+    if (typeof d.note !== 'string' || d.note.trim() === '') problems.push('a record of the user needs its note beside verbatim: null');
+  } else if (typeof d.verbatim !== 'string' || d.verbatim.trim() === '') problems.push('verbatim is the user words, or null with the record in note');
+  return problems;
+}
+
+interface HistoryCtx {
+  readonly project: JsonObject;
+  readonly dir: string;
+  readonly refusals: Finding[];
+  readonly warnings: Finding[];
+}
+
+function inside(root: string, file: string): boolean {
+  const rel = relative(root, file);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+export interface OutputBinding {
+  readonly path: string;
+  readonly sha256: string;
+}
+
+export interface PreInterviewOutputsInspection {
+  readonly refusals: Finding[];
+  readonly malformed: Finding[];
+  readonly otherRefusals: Finding[];
+  readonly bindings: OutputBinding[];
+  readonly missing: OutputBinding[];
+  readonly readable: string[];
+  readonly allMissing: boolean;
+}
+
+/** A loss declaration is usable on a pre-interview version with recorded missing bindings disjoint from surviving outputs, or legacy { note, source } beside outputs: []. */
+export function validOutputsLoss(version: JsonObject, dir: string): boolean {
+  const loss = version.outputs_lost;
+  if (version.pre_interview !== true || !isObject(loss)
+    || !Object.keys(loss).every((k) => k === 'note' || k === 'source' || k === 'recorded')
+    || typeof loss.note !== 'string' || loss.note.trim() === ''
+    || typeof loss.source !== 'string' || loss.source.trim() === ''
+    || !Array.isArray(version.outputs)) {
+    return false;
+  }
+  if (loss.recorded === undefined) return version.outputs.length === 0;
+  if (!Array.isArray(loss.recorded) || loss.recorded.length === 0) return false;
+  const outputFiles = new Set<string>();
+  for (const out of version.outputs) {
+    if (isObject(out) && typeof out.path === 'string' && out.path.trim() !== '') {
+      outputFiles.add(resolve(dir, out.path));
+    }
+  }
+  const paths = new Set<string>();
+  for (const raw of loss.recorded) {
+    if (!isObject(raw) || !Object.keys(raw).every((k) => k === 'path' || k === 'sha256')
+      || typeof raw.path !== 'string' || raw.path.trim() === ''
+      || typeof raw.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(raw.sha256)) {
+      return false;
+    }
+    const file = resolve(dir, raw.path);
+    if (isAbsolute(raw.path) || !inside(dir, file) || paths.has(file) || outputFiles.has(file)) return false;
+    paths.add(file);
+    try {
+      if (!inside(realpathSync(dir), realpathSync(file))) return false;
+      readFileSync(file);
+      return false;
+    } catch {
+      // Missing on disk.
+    }
+  }
+  return true;
+}
+
+export const OUTPUTS_LOST_MALFORMED_MESSAGE =
+  'record { note, source, recorded } with nonempty strings and missing { path, sha256 } bindings disjoint from surviving outputs (or { note, source } beside outputs: []) on a pre-interview version; restore surviving output records otherwise';
+
+/** Shared output validator for check and `version outputs-lost`. */
+export function inspectPreInterviewOutputs(dir: string, version: JsonObject, label: string): PreInterviewOutputsInspection {
+  const refusals: Finding[] = [];
+  const malformed: Finding[] = [];
+  const otherRefusals: Finding[] = [];
+  const bindings: OutputBinding[] = [];
+  const missing: OutputBinding[] = [];
+  const readable: string[] = [];
+  const push = (target: Finding[], code: string, path: string, message: string): void => {
+    const finding = { code, path, message: `${path}: ${message}` };
+    refusals.push(finding);
+    target.push(finding);
+  };
+  const hasOutputsLost = Object.hasOwn(version, 'outputs_lost');
+  if (hasOutputsLost) {
+    if (!validOutputsLoss(version, dir)) {
+      push(malformed, 'PRE_INTERVIEW_OUTPUTS_LOST_MALFORMED', `${label}.outputs_lost`, OUTPUTS_LOST_MALFORMED_MESSAGE);
+    }
+    if (!Array.isArray(version.outputs) || version.outputs.length === 0) {
+      return { refusals, malformed, otherRefusals, bindings, missing, readable, allMissing: false };
+    }
+  } else if (!Array.isArray(version.outputs) || version.outputs.length === 0) {
+    push(malformed, 'PRE_INTERVIEW_OUTPUT_MALFORMED', `${label}.outputs`, 'a pre-interview version lists its frozen output files with path, sha256 and bytes');
+    return { refusals, malformed, otherRefusals, bindings, missing, readable, allMissing: false };
+  }
+  const paths = new Set<string>();
+  const outcomes: (
+    | { kind: 'malformed'; path: string; message: string }
+    | { kind: 'outside'; path: string }
+    | { kind: 'missing'; path: string; rawPath: string }
+    | { kind: 'changed'; path: string; rawPath: string; actual: string; length: number }
+    | { kind: 'ok' }
+  )[] = [];
+  version.outputs.forEach((raw, index) => {
+    const path = `${label}.outputs[${index}]`;
+    if (!isObject(raw) || typeof raw.path !== 'string' || raw.path.trim() === '' || typeof raw.sha256 !== 'string'
+      || !/^[0-9a-f]{64}$/.test(raw.sha256) || typeof raw.bytes !== 'number' || !Number.isSafeInteger(raw.bytes) || raw.bytes < 0) {
+      outcomes.push({ kind: 'malformed', path, message: 'an output is { path, sha256 (64 lowercase hex digits), bytes (a nonnegative integer) }' });
+      return;
+    }
+    const file = resolve(dir, raw.path);
+    if (isAbsolute(raw.path) || !inside(dir, file) || paths.has(file)) {
+      outcomes.push({ kind: 'malformed', path, message: 'each output names a distinct file relative to the project' });
+      return;
+    }
+    paths.add(file);
+    bindings.push({ path: raw.path, sha256: raw.sha256 });
+    let bytes: Buffer;
+    try {
+      if (!inside(realpathSync(dir), realpathSync(file))) {
+        outcomes.push({ kind: 'outside', path });
+        return;
+      }
+      bytes = readFileSync(file);
+    } catch {
+      missing.push({ path: raw.path, sha256: raw.sha256 });
+      outcomes.push({ kind: 'missing', path, rawPath: raw.path });
+      return;
+    }
+    const actual = createHash('sha256').update(bytes).digest('hex');
+    if (actual !== raw.sha256 || bytes.length !== raw.bytes) {
+      outcomes.push({ kind: 'changed', path, rawPath: raw.path, actual, length: bytes.length });
+      return;
+    }
+    readable.push(raw.path);
+    outcomes.push({ kind: 'ok' });
+  });
+  const allMissing = version.pre_interview === true && !hasOutputsLost && missing.length === version.outputs.length && readable.length === 0;
+  const canRecordLoss = version.pre_interview === true
+    && !hasOutputsLost
+    && missing.length > 0
+    && outcomes.every((o) => o.kind === 'missing' || o.kind === 'ok');
+  const lostRemedy = canRecordLoss && typeof version.n === 'number'
+    ? `; if this pre-interview version's frozen outputs did not survive, record the loss with rig-create version outputs-lost ${String(version.n)} --note <text> --source <text>`
+    : '';
+  for (const outcome of outcomes) {
+    if (outcome.kind === 'malformed') {
+      push(malformed, 'PRE_INTERVIEW_OUTPUT_MALFORMED', outcome.path, outcome.message);
+    } else if (outcome.kind === 'outside') {
+      push(otherRefusals, 'PRE_INTERVIEW_OUTPUT_UNREAD', outcome.path, 'the output resolves outside the project');
+    } else if (outcome.kind === 'missing') {
+      refusals.push({
+        code: 'PRE_INTERVIEW_OUTPUT_UNREAD',
+        path: outcome.path,
+        message: `${outcome.path}: ${outcome.rawPath} cannot be read; restore the frozen file before checking the migration${lostRemedy}`,
+      });
+    } else if (outcome.kind === 'changed') {
+      push(otherRefusals, 'PRE_INTERVIEW_OUTPUT_CHANGED', outcome.path, `${outcome.rawPath} has sha256 ${outcome.actual} and ${outcome.length} bytes, different from its frozen record`);
+    }
+  }
+  return { refusals, malformed, otherRefusals, bindings, missing, readable, allMissing };
+}
+
+function checkOutputs(ctx: HistoryCtx, version: JsonObject, label: string): void {
+  ctx.refusals.push(...inspectPreInterviewOutputs(ctx.dir, version, label).refusals);
+}
+
+function checkOriginals(ctx: HistoryCtx, version: JsonObject, label: string): void {
+  const push = (code: string, path: string, message: string): void => {
+    ctx.refusals.push({ code, path, message: `${path}: ${message}` });
+  };
+  if (!Array.isArray(version.original_verdicts)) {
+    push('PRE_INTERVIEW_HISTORY_MISSING', `${label}.original_verdicts`, 'keep the complete original verdicts array, unchanged and in order');
+    return;
+  }
+  if (!Array.isArray(version.verdicts)) {
+    push('VERDICT_MALFORMED', `${label}.verdicts`, 'verdicts is a list of verdicts in create shape');
+  }
+  const originals = version.original_verdicts;
+  const verdicts = asArray(version.verdicts);
+  verdicts.forEach((d, index) => {
+    const path = `${label}.verdicts[${index}]`;
+    const problems = isObject(d) ? preInterviewVerdictProblems(d) : ['a verdict is an object'];
+    if (isObject(d)) {
+      if (!['accepted', 'bounced', 'provisional'].includes(d.verdict as string)) problems.push('verdict is accepted, bounced or provisional');
+      if (typeof d.review !== 'string' || !Object.hasOwn(REVIEW_ACCEPTS, d.review)) problems.push('review is rig-review or direction-review');
+      if (!Array.isArray(d.on_items)) problems.push('on_items is a list');
+    }
+    if (problems.length > 0) push('VERDICT_MALFORMED', path, problems.join(', '));
+  });
+  originals.forEach((original, index) => {
+    const path = `${label}.verdicts[${index}]`;
+    const converted = verdicts[index];
+    if (!isObject(converted) || !isDeepStrictEqual(converted.as_recorded, original)) {
+      push('PRE_INTERVIEW_VERDICT_LOST', path, `as_recorded must preserve original_verdicts[${index}] unchanged, at the same index`);
+    }
+    const value = isObject(original) ? asString(original.verdict) : null;
+    if (value === null || !Object.hasOwn(PRE_INTERVIEW_VERDICTS, value)) {
+      push('PRE_INTERVIEW_VERDICT_UNKNOWN', `${label}.original_verdicts[${index}]`, `original verdict ${JSON.stringify(value)} has no mapping in PRE_INTERVIEW_VERDICTS; do not infer an acceptance`);
+    } else if (isObject(converted) && converted.verdict !== PRE_INTERVIEW_VERDICTS[value]) {
+      push('PRE_INTERVIEW_VERDICT_MISMATCH', `${path}.verdict`, `${JSON.stringify(value)} maps to ${PRE_INTERVIEW_VERDICTS[value]}, got ${JSON.stringify(converted.verdict ?? null)}`);
+    }
+  });
+  verdicts.slice(originals.length).forEach((verdict, index) => {
+    if (isObject(verdict) && Object.hasOwn(verdict, 'as_recorded')) {
+      push('PRE_INTERVIEW_VERDICT_LOST', `${label}.verdicts[${originals.length + index}]`, 'as_recorded has no corresponding original verdict; new reviews are appended without as_recorded');
+    }
+  });
+}
+
+/** A loss declaration is usable only when the historical config is absent. */
+export function validConfigLoss(version: JsonObject): boolean {
+  const loss = version.config_lost;
+  const provenance = isObject(version.provenance) ? version.provenance : {};
+  return version.pre_interview === true && isObject(loss)
+    && typeof loss.note === 'string' && loss.note.trim() !== ''
+    && typeof loss.source === 'string' && loss.source.trim() !== ''
+    && provenance.config == null;
+}
+
+/** Also used by handoff so unchecked imported history cannot authorize post work. */
+export function checkPreInterview(ctx: HistoryCtx): void {
+  const legacy = ctx.project['x-pre_create'];
+  if (isObject(legacy) && Object.hasOwn(legacy, 'versions') && (!Array.isArray(legacy.versions) || legacy.versions.length > 0)) {
+    ctx.warnings.push({ code: 'PRE_INTERVIEW_UNMIGRATED', path: 'x-pre_create.versions', message: 'x-pre_create.versions awaits migration. Follow docs/PROJECT.md, Migrating work done before the interview, steps 1–6: preserve original verdicts and frozen outputs, move historical versions first into versions[] with pre_interview: true, normalize verdicts with sources, verify outputs, connect answers_feedback, then run interview --check and handoff' });
+  }
+  const versions = asArray(ctx.project.versions);
+  const originalIds = new Set<string | number>();
+  let createSeen = false;
+  let previous = 0;
+  const hasPreInterview = versions.some((v) => isObject(v) && v.pre_interview === true);
+  versions.forEach((v, index) => {
+    if (!isObject(v)) return;
+    const label = typeof v.n === 'number' ? `versions[v${v.n}]` : `versions[${index}]`;
+    if (Object.hasOwn(v, 'config_lost') && !validConfigLoss(v)) {
+      ctx.refusals.push({ code: 'PRE_INTERVIEW_CONFIG_LOST_MALFORMED', path: `${label}.config_lost`, message: `${label}.config_lost: record { note, source } with nonempty strings only on a pre-interview version without provenance.config; restore a surviving config instead` });
+    }
+    if (v.pre_interview !== undefined && typeof v.pre_interview !== 'boolean') {
+      ctx.refusals.push({ code: 'VERSION_MALFORMED', path: `${label}.pre_interview`, message: `${label}.pre_interview is a boolean flag` });
+    }
+    if (hasPreInterview && (typeof v.n !== 'number' || !Number.isSafeInteger(v.n) || v.n <= previous)) {
+      ctx.refusals.push({ code: 'PRE_INTERVIEW_ORDER', path: label, message: `${label}: migrated versions have positive, strictly increasing n in record order` });
+    }
+    if (typeof v.n === 'number') previous = v.n;
+    if (v.pre_interview !== true) {
+      if (Object.hasOwn(v, 'outputs_lost')) {
+        ctx.refusals.push({ code: 'PRE_INTERVIEW_OUTPUTS_LOST_MALFORMED', path: `${label}.outputs_lost`, message: `${label}.outputs_lost: ${OUTPUTS_LOST_MALFORMED_MESSAGE}` });
+      }
+      createSeen = true;
+      return;
+    }
+    if (createSeen) {
+      ctx.refusals.push({ code: 'PRE_INTERVIEW_ORDER', path: label, message: `${label}: every pre-interview version comes before the first create-built version` });
+    }
+    if (!Object.hasOwn(v, 'original_n') || (v.original_n !== null && typeof v.original_n !== 'number' && typeof v.original_n !== 'string')) {
+      ctx.refusals.push({ code: 'PRE_INTERVIEW_ORIGINAL_N_MISSING', path: `${label}.original_n`, message: `${label}.original_n: copy the source version id unchanged as a number, string or null` });
+    } else if (v.original_n !== null) {
+      if (originalIds.has(v.original_n)) {
+        ctx.refusals.push({ code: 'PRE_INTERVIEW_ORIGINAL_N_DUPLICATE', path: `${label}.original_n`, message: `${label}.original_n: two migrated versions share the same non-null source id; restore their distinct original ids` });
+      }
+      originalIds.add(v.original_n);
+    }
+    checkOriginals(ctx, v, label);
+    checkOutputs(ctx, v, label);
+  });
+}

package/src/prepared-inputs.ts

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { readFileSync } from './check-reads.ts';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { asArray, isObject, readJsonObject, type Ctx } from './check.ts';
+import { checkPlateReceipt, checkPlateRegistrations, readPlateReceipt } from './plate-receipt.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+const nonempty = (v: Json | undefined): v is string => typeof v === 'string' && v.trim() !== '';
+const hash = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+
+function inside(dir: string, path: string): boolean {
+  const rel = relative(dir, resolve(dir, path));
+  return !isAbsolute(path) && rel !== '' && rel !== 'project.json' && rel !== '..' && !rel.startsWith(`..${sep}`);
+}
+
+function readHash(dir: string, path: string): string {
+  return hash(readFileSync(resolve(dir, path)));
+}
+
+/** Only the tagged prepared-input records carry this file/hash contract; legacy intermediates are unchanged. */
+export function checkPreparedInputs(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'>): void {
+  asArray(ctx.project.derived).forEach((entry, i) => {
+    if (!isObject(entry)) return;
+    checkPlateReceipt(ctx, entry, `derived[${i}]`);
+    if (entry.kind !== 'prepared-input') return;
+    const path = `derived[${i}]`;
+    const sources = entry.sources === undefined ? [entry.source] : asArray(entry.sources);
+    const files = [
+      ...sources.map((source, index) => ({
+        record: isObject(source) ? source : {},
+        at: entry.sources === undefined ? `${path}.source` : `${path}.sources[${index}]`,
+        optional: false,
+      })),
+      { record: entry, at: path, optional: true },
+    ];
+    if (sources.length === 0 || !nonempty(entry.operation) || files.some(({ record }) => !nonempty(record.path) || !inside(ctx.dir, record.path) || typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(record.sha256)) || sources.some((source) => isObject(source) && typeof source.path === 'string' && typeof entry.path === 'string' && resolve(ctx.dir, source.path) === resolve(ctx.dir, entry.path))) {
+      ctx.refusals.push({ code: 'DERIVED_MALFORMED', path, message: `${path}: prepared-input needs operation, source or sources { path, sha256 }, and derived path and sha256; paths are distinct project-relative files other than project.json` });
+      return;
+    }
+    for (const { record, at, optional } of files) {
+      const name = record.path as string;
+      let actual: string;
+      try { actual = readHash(ctx.dir, name); } catch (error) {
+        if (optional && error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+          ctx.warnings.push({ code: 'DERIVED_RESULT_MISSING', path: `${at}.path`, message: `${at}: '${name}' is absent; regenerate with the recorded operation: ${entry.operation as string}` });
+          continue;
+        }
+        ctx.refusals.push({ code: 'DERIVED_FILE_UNREADABLE', path: `${at}.path`, message: `${at}: cannot read '${name}'; restore the recorded file` });
+        continue;
+      }
+      if (actual !== (record.sha256 as string).toLowerCase()) ctx.refusals.push({ code: 'DERIVED_FILE_CHANGED', path: `${at}.sha256`, message: `${at}: '${name}' no longer matches its recorded sha256` });
+    }
+  });
+  checkPlateRegistrations(ctx);
+}
+
+export const DERIVED_HELP = `derived add [<project dir>] --source <file> [--source <file> …] --file <file> --operation <text> [--receipt <path>] [--json]
+  Records an operation already run by another tool, with the files' sha256s.
+  Paths are relative to the project. No files are transformed; no stage moves.`;
+
+export function derivedCommand(args: string[]): { stdout: string; exit: number } {
+  if (args[0] !== 'add') refuse('DERIVED_USAGE', DERIVED_HELP, USAGE_EXIT);
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  const sources: string[] = [];
+  let json = false;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === '--json') json = true;
+    else if (['--source', '--file', '--operation', '--receipt'].includes(arg)) {
+      const value = args[++i];
+      if ((arg !== '--source' && opts[arg] !== undefined) || value === undefined || value.startsWith('--') || value.trim() === '') refuse('DERIVED_USAGE', `${arg} needs one non-empty value`, USAGE_EXIT);
+      opts[arg] = value;
+      if (arg === '--source') sources.push(value);
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `derived add does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (positional.length > 1 || ['--source', '--file', '--operation'].some((k) => opts[k] === undefined)) refuse('DERIVED_USAGE', DERIVED_HELP, USAGE_EXIT);
+  const dir = resolve(positional[0] ?? process.cwd());
+  const file = resolve(dir, 'project.json');
+  const read = readJsonObject(file);
+  if (!read.ok) refuse('PROJECT_JSON_INVALID', `${file}: ${read.error}`);
+  const project = read.value;
+  if (project.schema !== 'rig-create/project@0') refuse('SCHEMA_UNKNOWN', 'derived add reads rig-create/project@0');
+  if (project.derived !== undefined && !Array.isArray(project.derived)) refuse('DERIVED_MALFORMED', 'derived must be an array');
+  const output = opts['--file'] as string;
+  if (![...sources, output].every((p) => inside(dir, p)) || sources.some((p) => resolve(dir, p) === resolve(dir, output))) refuse('DERIVED_PATH_INVALID', 'source and derived file must be distinct project-relative files other than project.json');
+  const hashes = [...sources, output].map((p) => {
+    try { return readHash(dir, p); } catch { refuse('DERIVED_FILE_UNREADABLE', `cannot read '${p}'; no record written`); }
+  });
+  const inputs = sources.map((path, i) => ({ path, sha256: hashes[i] as string }));
+  const entry: JsonObject = {
+    kind: 'prepared-input',
+    ...(sources.length === 1 ? { source: inputs[0] as JsonObject } : { sources: inputs }),
+    path: output,
+    sha256: hashes[sources.length] as string,
+    operation: opts['--operation'] as string,
+  };
+  if (opts['--receipt'] !== undefined) {
+    try { entry.receipt = readPlateReceipt(dir, opts['--receipt']).binding; }
+    catch (error) { refuse('PLATE_RECEIPT_INVALID', `derived.receipt: ${(error as Error).message}; supply an intact project-relative producer receipt; no record written`); }
+  }
+  project.derived = [...asArray(project.derived), entry];
+  const ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'> = { dir, project: { ...project, derived: [entry], scenes: [] }, refusals: [], warnings: [] };
+  checkPreparedInputs(ctx);
+  const finding = ctx.refusals[0];
+  if (finding) refuse(finding.code, finding.message);
+  writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
+  return { stdout: json ? JSON.stringify(entry, null, 2) : `derived: recorded '${sources.join("', '")}' → '${output}' (${entry.operation as string}); stage unchanged`, exit: 0 };
+}

package/src/progress-writers.ts

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+import { checkpointRequired } from './plan-history.ts';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { asArray, checkProject, collectItems, collectSignoffs, isObject, loadCollection, postNotPassed, type Finding } from './check.ts';
+import { readProject } from './feedback.ts';
+import { acquireAdvanceJobWrite, commitAdvance } from './job-advance.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { findingKey, newFindings, carriedRefusals } from './refusal-baseline.ts';
+import { collectAmendments } from './amend.ts';
+import { LEGACY_STAGE_VALUES, PARTS_REVIEW_SINCE, PAUSED_STAGE, STAGE_VALUES, hasStageOrder, interviewStageOfGuide, stageIndex, stageOfStep } from './stages.ts';
+import { advanceOrder, furthestStageSignoff, isSignoffIdentity, moveOwner, signoffIdentity, statusTransitionFinding, STEP_STATUSES } from './stage-progress.ts';
+import { isPartsCheckMove, partsCheckLines, partsCheckRecord } from './parts-check.ts';
+import type { JsonObject } from './templates.ts';
+
+export const PROGRESS_HELP = `advance:
+  <stage> [<project dir>] [--source <text>] [--parts-check <report> --parts <assembled dir>]
+  Move one authorized stage forward and append advances[] with its stable signoff identity.
+  The person's signoff is the move's authority; advance takes no --by or words of its own.
+  parts -> parts-review requires both: a passing rig-parts check-parts report retained
+  under the project and the project-relative assembled root it was run on.
+step-status:
+  <step> <status> [<project dir>] --by <who> [--note-file <path>]
+  Record pending -> in-progress -> at-checkpoint -> done and status_history[].
+  The optional note is verbatim UTF-8, 1–1,000 bytes, with no controls except newline.
+  A checkpointed done needs a live human checkpoint signature.
+  An amended project also runs steps in the check's effective stage, keeping its stored stage.
+Both accept --json and validate the complete candidate before writing.`;
+
+function options(args: string[], command: string): { positional: string[]; opts: Record<string, string>; json: boolean } {
+  const positional: string[] = [];
+  const opts: Record<string, string> = {};
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--json') json = true;
+    else if (command === 'advance' && (arg === '--by' || arg === '--verbatim-file')) {
+      refuse('ADVANCE_WORDS_REMOVED', `advances: advance no longer takes ${arg}; the move records the live stage signoff it rests on, so record the person's approval with signoff (from the review tool: signoff <stage> --from-review <actId>) and advance without words`, USAGE_EXIT);
+    } else if ((command === 'advance' ? ['--source', '--parts-check', '--parts'] : ['--by', '--note-file']).includes(arg)) {
+      const value = args[++i];
+      if (arg in opts || value === undefined || value.trim() === '') refuse('PROGRESS_OPTION_INVALID', `${command}: ${arg} needs one value; see help`, USAGE_EXIT);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `${command}: unsupported ${arg}; see help`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (command !== 'advance' && opts['--by'] === undefined) refuse('PROGRESS_OPTION_INVALID', `${command}: supply --by; see help`, USAGE_EXIT);
+  return { positional, opts, json };
+}
+
+/**
+ * Validate the complete candidate, then write. `advance` passes no baseline: a stage boundary needs 0 refusals
+ * (only the arrival's own INTERVIEW_INCOMPLETE is allowed). `step-status` passes the record as read, and only a
+ * refusal that record did not already carry blocks its write.
+ */
+function save(dir: string, file: string, project: JsonObject, now: number, forwardWrite = false, before?: JsonObject): void {
+  project.stage_values = [...(hasStageOrder(project) ? STAGE_VALUES : LEGACY_STAGE_VALUES)];
+  const allowed = before === undefined ? new Map<string, number>() : carriedRefusals(dir, before, { now, forwardWrite });
+  if (forwardWrite && ['rigging-interview', 'post-interview'].includes(String(project.stage))) {
+    for (const item of collectItems(project, { collection: loadCollection(dir) })) {
+      if (item.state.state !== 'silent' || interviewStageOfGuide(item.id, item.kind === 'post', hasStageOrder(project)) !== project.stage) continue;
+      const key = findingKey({ code: 'INTERVIEW_INCOMPLETE', path: item.path });
+      allowed.set(key, (allowed.get(key) ?? 0) + 1);
+    }
+  }
+  const first = newFindings(allowed, checkProject(dir, project, { now, forwardWrite }).refusals)[0];
+  if (first !== undefined) refuse(first.code, first.message);
+  if (forwardWrite) commitAdvance(dir, file, project);
+  else writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
+}
+
+export function advanceCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const { positional, opts, json } = options(args, 'advance');
+  if (positional.length < 1 || positional.length > 2) refuse('PROGRESS_OPTION_INVALID', 'stage: advance needs a target and optional project directory; see help', USAGE_EXIT);
+  const dir = resolve(positional[1] ?? process.cwd());
+  const releaseJob = acquireAdvanceJobWrite(dir, positional[0]!);
+  try {
+    const { file, project } = readProject(dir);
+    const history: Finding[] = [];
+    const reopens = collectReopens(project, history);
+    const latest = furthestStageSignoff(collectSignoffs(project, history).filter(s => liveSignoff(reopens, s.stage, s.at)));
+    if (latest !== undefined && !Number.isFinite(latest.at)) refuse('STAGE_SIGNOFF_DATE_INVALID', `signoffs[${latest.index}].at: frontier approval needs a readable date; restore its original date before advancing`);
+    if (latest === undefined) refuse('ADVANCE_UNAUTHORIZED', 'stage: no live stage-level human signoff authorizes a move; sign the current stage first');
+    const preParts = !hasStageOrder(project) && stageIndex(String(project.stage)) > stageIndex('parts-review')
+      && collectSignoffs(project, []).some(s => s.stage === 'plan-approved' && s.checkpoint === null && s.at < Date.parse(PARTS_REVIEW_SINCE));
+    const steps = asArray(isObject(project.plan) ? project.plan.steps : undefined).filter(isObject);
+    // The entry records the signoff it rests on and no person's words: the authority is that signature.
+    const entry: JsonObject = { stage: positional[0]!, from_stage: project.stage ?? null, at: new Date(now).toISOString(),
+      post_not_passed: postNotPassed({ items: collectItems(project, { collection: loadCollection(dir) }) }),
+      order: preParts ? 'pre-parts' : hasStageOrder(project) ? 'split' : 'legacy', signoffs_before: asArray(project.signoffs).filter(isObject).map(signoffIdentity).filter(isSignoffIdentity), signoff: signoffIdentity(latest.record),
+      steps_before: steps.map(s => ({ id: s.id ?? null, phase: s.phase ?? null, ...(s.status === undefined ? {} : { status: s.status }) })) };
+    if (opts['--source'] !== undefined) entry.source = opts['--source'];
+    // A live signature at an earlier stage is not this move's authority; name the stage to sign, not the candidate.
+    // A malformed signoff or reopen may be that signature, so the candidate check names it instead.
+    const order = advanceOrder(entry.order);
+    const owner = moveOwner(order, entry.from_stage);
+    if (history.length === 0 && owner !== undefined && order.findIndex(s => s.id === latest.stage) < order.findIndex(s => s.id === owner)) {
+      refuse('ADVANCE_UNAUTHORIZED', `stage: no live ${owner} signoff authorizes the move from ${String(entry.from_stage)}; the latest live stage signoff is ${latest.stage} (signoffs[${latest.index}]); record rig-create signoff ${owner} first, then advance`);
+    }
+    if (project.advances !== undefined && !Array.isArray(project.advances)) refuse('ADVANCE_MALFORMED', 'advances: must be a list; preserve existing history');
+    const checkPath = `advances[${asArray(project.advances).length}].parts_check`;
+    const report = opts['--parts-check'];
+    const root = opts['--parts']?.replace(/\/+$/, '');
+    if (!isPartsCheckMove(entry) && (report !== undefined || root !== undefined)) {
+      refuse('PROGRESS_OPTION_INVALID', `${checkPath}: --parts-check and --parts are accepted only on the move from parts to parts-review; see help`, USAGE_EXIT);
+    }
+    if ((report === undefined) !== (root === undefined)) {
+      refuse('PROGRESS_OPTION_INVALID', `${checkPath}: supply --parts-check and --parts together; see help`, USAGE_EXIT);
+    }
+    // Without both flags the check refuses the move as PARTS_CHECK_MISSING, in check order.
+    if (report !== undefined && root !== undefined) {
+      const read = partsCheckRecord(dir, report, root, checkPath);
+      if ('refusal' in read) refuse(read.refusal.code, read.refusal.message);
+      entry.parts_check = read.record;
+    }
+    project.advances = [...asArray(project.advances), entry];
+    project.stage = entry.stage!;
+    save(dir, file, project, now, true);
+    const lines = isObject(entry.parts_check) ? partsCheckLines(entry.parts_check, checkPath) : [];
+    return { stdout: json ? JSON.stringify(entry, null, 2) : [`advance: ${String(entry.from_stage)} -> ${String(entry.stage)}`, ...lines].join('\n'), exit: 0 };
+  } finally {
+    releaseJob();
+  }
+}
+
+export function stepStatusCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const { positional, opts, json } = options(args, 'step-status');
+  if (positional.length < 2 || positional.length > 3) refuse('PROGRESS_OPTION_INVALID', 'plan.steps: step-status needs step, status and optional project directory; see help', USAGE_EXIT);
+  const dir = resolve(positional[2] ?? process.cwd());
+  const { file, project } = readProject(dir);
+  const before = structuredClone(project);
+  const matches = asArray(isObject(project.plan) ? project.plan.steps : undefined).filter((s): s is JsonObject => isObject(s) && s.id === positional[0]);
+  const step = matches[0];
+  if (matches.length !== 1 || step === undefined || (step.phase !== 'rig' && step.phase !== 'post')) refuse('STEP_STATUS_TRANSITION', `plan.steps[${positional[0]}]: no unique executable step; restore the plan before step-status`);
+  const stage = stageOfStep(step.phase, String(step.id));
+  // Amend retains project.stage while its approvals lapse; the work resumes at the check's effective stage (PROJECT.md).
+  const resumes = project.stage !== PAUSED_STAGE && collectAmendments(project, []).length > 0
+    ? checkProject(dir, structuredClone(project), { now }).effective_stage : null;
+  const running = resumes !== null && resumes !== project.stage ? [String(project.stage), resumes] : [String(project.stage)];
+  const oldOrder = !hasStageOrder(project) && running.includes('rigging') && collectSignoffs(project, []).some(s => s.stage === 'plan-approved' && s.at < Date.parse(PARTS_REVIEW_SINCE));
+  if (!running.includes(stage) && !(oldOrder && step.phase === 'rig')) {
+    refuse('STEP_STATUS_TRANSITION', running.length > 1
+      ? `plan.steps[${positional[0]}]: runs in ${stage}; the amended project resumes at ${String(resumes)} (stage ${String(project.stage)} retained); sign the lapsed approvals and finish the earlier bars first`
+      : `plan.steps[${positional[0]}]: runs in ${stage}, current stage is ${String(project.stage)}; advance to its execution stage first`);
+  }
+  const enabled = checkpointRequired(project, step, now);
+  const entry: JsonObject = { from_status: step.status ?? 'pending', status: positional[1]!, by: opts['--by']!, at: new Date(now).toISOString(), checkpoint_required: enabled, signoff: null };
+  if (opts['--note-file'] !== undefined) {
+    const notePath = opts['--note-file'];
+    try {
+      const bytes = readFileSync(notePath);
+      if (bytes.length === 0 || bytes.length > 1000) throw new Error('invalid size');
+      // Keep a leading BOM too: the stored text and digest bind the original UTF-8 bytes.
+      entry.note = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+      entry.note_sha256 = createHash('sha256').update(bytes).digest('hex');
+    } catch {
+      refuse('PROGRESS_OPTION_INVALID', `plan.steps[${positional[0]}].status_history: ${notePath}: supply a readable non-empty UTF-8 --note-file of at most 1,000 bytes`, USAGE_EXIT);
+    }
+  }
+  const from = STEP_STATUSES.indexOf(entry.from_status as typeof STEP_STATUSES[number]);
+  if (from >= 0 && STEP_STATUSES.indexOf(entry.status as typeof STEP_STATUSES[number]) !== from + 1) {
+    const next = STEP_STATUSES[from + 1];
+    refuse('STEP_STATUS_TRANSITION', next === undefined
+      ? `plan.steps[${positional[0]}].status: ${String(entry.from_status)} is the last status, so ${String(entry.status)} cannot follow it; to run the step again record rig-create reopen ${stage}`
+      : `plan.steps[${positional[0]}].status: ${String(entry.status)} cannot follow ${String(entry.from_status)}; statuses move one at a time through ${STEP_STATUSES.join(' → ')}, so record rig-create step-status ${String(step.id)} ${next} next`);
+  }
+  const invalid = statusTransitionFinding(entry, `plan.steps[${positional[0]}].status_history`);
+  if (invalid !== null) refuse(invalid.code, invalid.message);
+  if (entry.status === 'done' && enabled) {
+    const reopens = collectReopens(project, []);
+    const signature = collectSignoffs(project, []).filter(s => s.checkpoint === step.id && (s.stage === stage || (oldOrder && s.stage === 'rigging'))
+      && liveSignoff(reopens, s.stage, s.at) && s.at <= Date.parse(String(entry.at))).sort((a, b) => b.at - a.at || b.index - a.index)[0];
+    if (signature === undefined) refuse('CHECKPOINT_UNSIGNED', `plan.steps[${positional[0]}]: done requires its live human checkpoint signoff; record signoff ${stage} --checkpoint ${String(step.id)} first`);
+    entry.signoff = signoffIdentity(signature.record);
+  }
+  if (step.status_history !== undefined && !Array.isArray(step.status_history)) refuse('STEP_STATUS_TRANSITION', `plan.steps[${positional[0]}].status_history: must be a list; preserve existing history`);
+  step.status_history = [...asArray(step.status_history), entry];
+  step.status = entry.status!;
+  save(dir, file, project, now, false, before);
+  return { stdout: json ? JSON.stringify(entry, null, 2) : `step-status: ${positional[0]} ${String(entry.status)}`, exit: 0 };
+}