rig-create 0.0.0-stage → 1.0.0

package/src/plan-bar-amendments.ts

@@ -0,0 +1,54 @@
+import { asArray, isObject, type Finding } from './check.ts';
+import { checkpointGeneration } from './plan-history.ts';
+import { stepHash } from './step-hash.ts';
+import type { JsonObject } from './templates.ts';
+
+/** Policy amendments never change the authored step or its approval hash. */
+export function collectBarAmendments(project: JsonObject, refusals: Finding[], now = Date.now()): JsonObject[] {
+  const plan = isObject(project.plan) ? project.plan : {};
+  if (plan.bar_amendments === undefined) return [];
+  const start = refusals.length;
+  const entries: JsonObject[] = [];
+  const identities = new Set<string>();
+  let previousAt = -Infinity;
+  const fail = (path: string): void => {
+    refusals.push({ code: 'BAR_AMENDMENT_INVALID', path,
+      message: `${path}: restore the original step, hash, generation, amended bar, operator, date, reason and exact words; use plan bar-amend` });
+  };
+  if (!Array.isArray(plan.bar_amendments)) { fail('plan.bar_amendments'); return []; }
+  for (const [index, raw] of plan.bar_amendments.entries()) {
+    const path = `plan.bar_amendments[${index}]`;
+    if (!isObject(raw) || Object.keys(raw).sort().join(',') !== 'amended_bar,at,by,generation,reason,schema,sha256,step,verbatim'
+      || raw.schema !== 'rig-create/bar-amendment@1' || !isObject(raw.step)
+      || typeof raw.step.id !== 'string' || !raw.step.id.trim() || !['rig', 'post'].includes(String(raw.step.phase))
+      || typeof raw.step.bar !== 'string' || !raw.step.bar.trim() || raw.sha256 !== stepHash(raw.step)
+      || !Number.isSafeInteger(raw.generation) || Number(raw.generation) < 0
+      || Number(raw.generation) > checkpointGeneration(project, raw.step.id)
+      || ['amended_bar', 'by', 'reason', 'verbatim'].some(key => typeof raw[key] !== 'string' || !String(raw[key]).trim())
+      || typeof raw.at !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(raw.at)
+      || !Number.isFinite(Date.parse(raw.at)) || Date.parse(raw.at) > now) {
+      fail(path); continue;
+    }
+    const id = raw.step.id;
+    const versions = asArray(plan.replaced).filter(entry => isObject(entry) && isObject(entry.step) && entry.step.id === id);
+    const historical = versions[Number(raw.generation)];
+    const bound = isObject(historical) ? historical.step : asArray(plan.steps).find(step => isObject(step) && step.id === id);
+    const identity = JSON.stringify([id, raw.sha256, raw.generation]);
+    const at = Date.parse(raw.at);
+    if (!isObject(bound) || stepHash(bound) !== raw.sha256 || at < previousAt || identities.has(identity)) {
+      fail(path); continue;
+    }
+    previousAt = at;
+    identities.add(identity);
+    entries.push(raw);
+  }
+  return refusals.length === start ? entries : [];
+}
+
+/** A later revision, even one restoring identical text, does not inherit policy. */
+export function effectiveBar(project: JsonObject, step: JsonObject, now = Date.now()): string {
+  const entry = collectBarAmendments(project, [], now).find(entry => isObject(entry.step)
+    && entry.step.id === step.id && entry.sha256 === stepHash(step)
+    && entry.generation === checkpointGeneration(project, String(step.id)));
+  return entry ? String(entry.amended_bar) : String(step.bar ?? '');
+}

package/src/plan-history.ts

@@ -0,0 +1,147 @@
+import { asArray, classify, collectSignoffs, isObject, type Finding } from './check.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { approvalStageOfStep, hasStageOrder } from './stages.ts';
+import { stepHash } from './step-hash.ts';
+import type { JsonObject } from './templates.ts';
+
+/** Invalid history is reported and never used to resolve a historical signature. */
+export function collectPlanReplaced(project: JsonObject, refusals: Finding[]): JsonObject[] {
+  const plan = isObject(project.plan) ? project.plan : {};
+  const entries: JsonObject[] = [];
+  const seen = new Set<string>();
+  let previousAt = -Infinity;
+  const push = (code: string, path: string, why: string): void => {
+    refusals.push({ code, path, message: `${path}: ${why}; restore the original plan.replaced entry and use plan revise or remove` });
+  };
+  if (plan.replaced !== undefined && !Array.isArray(plan.replaced)) {
+    push('PLAN_REPLACED_INVALID', 'plan.replaced', 'must be an append-only list');
+    return entries;
+  }
+  for (const [index, raw] of asArray(plan.replaced).entries()) {
+    const path = `plan.replaced[${index}]`;
+    if (!isObject(raw) || !isObject(raw.step) || typeof raw.step.id !== 'string' || !raw.step.id.trim()
+      || (raw.step.phase !== 'rig' && raw.step.phase !== 'post')
+      || typeof raw.by !== 'string' || !raw.by.trim() || typeof raw.at !== 'string'
+      || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(raw.at)
+      || !Number.isFinite(Date.parse(raw.at))) {
+      push('PLAN_REPLACED_INVALID', path, 'needs the full previous step with id and phase, an ISO at and a nonempty by');
+      continue;
+    }
+    const start = refusals.length;
+    if (raw.sha256 !== stepHash(raw.step)) push('PLAN_REPLACED_HASH', `${path}.sha256`, 'does not equal stepHash(step)');
+    if (raw.action !== 'revised' && raw.action !== 'removed') push('PLAN_REPLACED_ACTION', `${path}.action`, 'must be revised or removed');
+    const at = Date.parse(raw.at);
+    if (at < previousAt) push('PLAN_REPLACED_ORDER', `${path}.at`, 'must not precede the previous history entry');
+    previousAt = Math.max(previousAt, at);
+    const identity = JSON.stringify([raw.step.id, raw.at]);
+    if (seen.has(identity)) push('PLAN_REPLACED_DUPLICATE', path, 'step.id and at must identify one history entry');
+    seen.add(identity);
+    if (refusals.length === start) entries.push(raw);
+  }
+  return entries;
+}
+
+/** Only ids with replacement history gain historical hash resolution. Old records are unchanged. */
+export function checkReplacedSignoffs(project: JsonObject, entries: JsonObject[], refusals: Finding[]): void {
+  const reopens = collectReopens(project, []);
+  const signatures = collectSignoffs(project, []).filter(s => s.checkpoint === null);
+  const steps = asArray(isObject(project.plan) ? project.plan.steps : undefined).filter(isObject);
+  const previousSteps = entries.map(entry => entry.step as JsonObject);
+  const ids = new Set(previousSteps.map(step => String(step.id)));
+  for (const signature of signatures) {
+    if (signature.record.step_hashes === undefined) continue;
+    const live = liveSignoff(reopens, signature.stage, signature.at);
+    for (const id of ids) {
+      if (signature.steps !== null && !signature.steps.includes(id)) continue;
+      const hashes = signature.record.step_hashes;
+      // An implicit historical approval cannot bind an id added after that signature.
+      if (!live && signature.steps === null && isObject(hashes) && !Object.hasOwn(hashes, id)) continue;
+      const candidates = [...steps, ...previousSteps].filter(step => step.id === id
+        && (step.phase === 'rig' || step.phase === 'post')
+        && approvalStageOfStep(step.phase, id, hasStageOrder(project)) === signature.stage);
+      if (candidates.length === 0) continue;
+      // Preserve latest-covering approval semantics for live re-signatures.
+      if (live && signatures.some(other => {
+        const at = Number.isNaN(signature.at) ? -Infinity : signature.at;
+        const otherAt = Number.isNaN(other.at) ? -Infinity : other.at;
+        return other.stage === signature.stage && liveSignoff(reopens, other.stage, other.at)
+          && (other.steps === null || other.steps.includes(id))
+          && (otherAt > at || (otherAt === at && other.index > signature.index));
+      })) continue;
+      const allowed = live ? candidates.filter(step => steps.includes(step)) : candidates;
+      if (isObject(hashes) && allowed.some(step => stepHash(step) === hashes[id])) continue;
+      const path = `signoffs[${signature.index}].step_hashes[${id}]`;
+      refusals.push({ code: 'PLAN_REPLACED_SIGNOFF', path,
+        message: `${path}: does not match ${live ? 'the current step' : 'a current or retained previous step'}; restore the signed step and its replacement history, or reopen the live approval before replanning` });
+    }
+  }
+}
+
+
+/** Replacement generations keep a withdrawal from applying to a later revision under the same id. */
+export function checkpointGeneration(project: JsonObject, id: string): number {
+  return asArray(isObject(project.plan) ? project.plan.replaced : undefined)
+    .filter(entry => isObject(entry) && isObject(entry.step) && entry.step.id === id).length;
+}
+
+export function checkpointEnabled(step: JsonObject): boolean {
+  const checkpoint = classify(step.checkpoint, { collection: null });
+  return checkpoint.state === 'user' ? checkpoint.answer.value === true
+    : checkpoint.state === 'delegated' && checkpoint.decided && isObject(checkpoint.answer.agent_decision)
+      && checkpoint.answer.agent_decision.value === true;
+}
+
+/** Withdrawals preserve the signed step. Their authority is limited to its exact hash and replacement generation. */
+export function collectCheckpointWithdrawals(project: JsonObject, refusals: Finding[], now = Infinity): JsonObject[] {
+  const plan = isObject(project.plan) ? project.plan : {};
+  if (plan.checkpoint_withdrawals === undefined) return [];
+  const start = refusals.length;
+  const entries: JsonObject[] = [];
+  const identities = new Set<string>();
+  let previousAt = -Infinity;
+  const fail = (path: string): void => {
+    refusals.push({ code: 'CHECKPOINT_WITHDRAWAL_INVALID', path,
+      message: `${path}: retain a withdrawal with its original enabled step, hash, generation, operator, date, reason and exact words; restore the journal and use plan checkpoint-withdraw` });
+  };
+  if (!Array.isArray(plan.checkpoint_withdrawals)) { fail('plan.checkpoint_withdrawals'); return []; }
+  for (const [index, raw] of plan.checkpoint_withdrawals.entries()) {
+    const path = `plan.checkpoint_withdrawals[${index}]`;
+    if (!isObject(raw) || Object.keys(raw).sort().join(',') !== 'at,by,generation,reason,schema,sha256,step,verbatim'
+      || raw.schema !== 'rig-create/checkpoint-withdrawal@1' || !isObject(raw.step)
+      || typeof raw.step.id !== 'string' || !raw.step.id.trim() || !['rig', 'post'].includes(String(raw.step.phase))
+      || !checkpointEnabled(raw.step) || raw.sha256 !== stepHash(raw.step)
+      || !Number.isSafeInteger(raw.generation) || Number(raw.generation) < 0
+      || Number(raw.generation) > checkpointGeneration(project, raw.step.id)
+      || ['by', 'reason', 'verbatim'].some(key => typeof raw[key] !== 'string' || !String(raw[key]).trim())
+      || typeof raw.at !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(raw.at)
+      || !Number.isFinite(Date.parse(raw.at)) || Date.parse(raw.at) > now) {
+      fail(path); continue;
+    }
+    const original = raw.step;
+    const id = String(original.id);
+    const at = Date.parse(raw.at);
+    const checkpoint = raw.step.checkpoint as JsonObject;
+    const decision = checkpoint.delegated === true && isObject(checkpoint.agent_decision) ? checkpoint.agent_decision : checkpoint;
+    const versions = asArray(plan.replaced).filter(entry => isObject(entry) && isObject(entry.step) && entry.step.id === id);
+    const historical = versions[Number(raw.generation)];
+    const current = asArray(plan.steps).find(step => isObject(step) && step.id === id);
+    const bound = isObject(historical) ? historical.step : current;
+    const identity = JSON.stringify([raw.step.id, raw.sha256, raw.generation]);
+    if (!isObject(bound) || stepHash(bound) !== raw.sha256) { fail(path); continue; }
+    if (at < previousAt || !Number.isFinite(Date.parse(String(decision.at ?? checkpoint.at))) || at < Date.parse(String(decision.at ?? checkpoint.at)) || identities.has(identity)) {
+      fail(path); continue;
+    }
+    previousAt = at;
+    identities.add(identity);
+    entries.push(raw);
+  }
+  // A broken journal grants no partial exemption.
+  return refusals.length === start ? entries : [];
+}
+
+export function checkpointRequired(project: JsonObject, step: JsonObject, now = Infinity): boolean {
+  if (!checkpointEnabled(step)) return false;
+  return !collectCheckpointWithdrawals(project, [], now).some(entry => isObject(entry.step)
+    && entry.step.id === step.id && entry.sha256 === stepHash(step)
+    && entry.generation === checkpointGeneration(project, String(step.id)));
+}

package/src/plan-writers.ts

@@ -0,0 +1,202 @@
+import { collectBarAmendments } from './plan-bar-amendments.ts';
+import { checkpointEnabled, checkpointGeneration, checkpointRequired, collectCheckpointWithdrawals } from './plan-history.ts';
+import { readVerbatim } from './record-input.ts';
+import { acquireBoundJobWrite } from './job-writer.ts';
+import { closeSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { asArray, checkProject, collectSignoffs, isObject } from './check.ts';
+import { readProject } from './feedback.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { baselineOf, newFindings } from './refusal-baseline.ts';
+import { approvalStageOfStep, hasStageOrder, stageOfStep } from './stages.ts';
+import { stepHash } from './step-hash.ts';
+import type { JsonObject } from './templates.ts';
+
+export const PLAN_HELP = `plan add|revise|remove <id> [<project dir>] --by <drafter> [--json]
+  --phase rig|post --order <number> --does <text> --produces <text>
+  --rests-on <id,id,...> --bar <text> --checkpoint-proposed true|false
+  checkpoint-withdraw <id> [<project dir>] --by <operator> --reason-file <file> --quote-file <file>
+  bar-amend <id> [<project dir>] --by <operator> --reason-file <file> --quote-file <file> --bar-file <file>
+  Amend one execution bar without changing the signed step.
+  Withdraw one enabled execution checkpoint without changing the signed step.
+  Add requires all fields. Revise accepts any of these fields and preserves the id.
+  Revise/remove retain the full previous step in plan.replaced[].
+  Reopen live covering plan signatures first. Completed steps require removal and a new id.
+  Dates follow approval ownership: parts/legacy rig update drafted_at and drafted_by,
+  production rigging updates rigging_drafted_at, and post preserves plan dates.
+  Each candidate passes check's refusal delta before writing.`;
+
+const FIELDS = ['phase', 'order', 'does', 'produces', 'rests_on', 'bar', 'checkpoint_proposed'];
+
+/** Reopen resets status, but cannot make completed work a new draft under the same id. */
+function completed(project: JsonObject, step: JsonObject): boolean {
+  return step.status === 'done' || asArray(step.status_history).some(event => isObject(event) && event.status === 'done')
+    || asArray(project.reopens).some(entry => isObject(entry) && asArray(entry.steps_before).some(before => isObject(before) && before.id === step.id && before.status === 'done'));
+}
+
+export function planCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const action = args[0];
+  if (action === 'help' || args.includes('--help')) return { stdout: PLAN_HELP, exit: 0 };
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  let json = false;
+  const usage = (why: string): never => refuse('PLAN_OPTION_INVALID', `plan.steps: ${why}; see plan help`, USAGE_EXIT);
+  if (!['add', 'revise', 'remove', 'checkpoint-withdraw', 'bar-amend'].includes(action ?? '')) usage('expected add, revise, remove, checkpoint-withdraw or bar-amend');
+  const flags = ['--by', '--reason-file', '--quote-file', '--bar-file', ...FIELDS.map(field => `--${field.replaceAll('_', '-')}`)];
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === '--json') json = true;
+    else if (flags.includes(arg)) {
+      const value = args[++index];
+      if (opts[arg] !== undefined || value === undefined || !value.trim() || value.startsWith('--')) usage(`${arg} needs one nonempty value`);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) usage(`unsupported option ${arg}`);
+    else positional.push(arg);
+  }
+  const id = positional[0];
+  if (!id?.trim() || positional.length > 2 || !opts['--by']) usage('supply an id, --by and one optional project directory');
+  const patch: JsonObject = {};
+  for (const field of FIELDS) {
+    const value = opts[`--${field.replaceAll('_', '-')}`];
+    if (value !== undefined) patch[field] = value;
+  }
+  const withdrawing = action === 'checkpoint-withdraw';
+  const amendingBar = action === 'bar-amend';
+  const journalAction = withdrawing || amendingBar;
+  if (journalAction && (Object.keys(patch).length || !opts['--reason-file'] || !opts['--quote-file'])) usage('journal actions need reason-file and quote-file and take no authored step fields');
+  if (amendingBar !== (opts['--bar-file'] !== undefined)) usage('bar-amend requires bar-file; other actions do not accept it');
+  if (!journalAction && (opts['--reason-file'] || opts['--quote-file'])) usage('reason-file and quote-file belong only to journal actions');
+  const inputFlags = journalAction ? ['--reason-file', '--quote-file', ...(amendingBar ? ['--bar-file'] : [])] : [];
+  if (inputFlags.some(flag => opts[flag] === '-')) usage('journal actions need retained files, not shared stdin');
+  const inputs = inputFlags.map(flag => ({ file: opts[flag]!, text: readVerbatim(opts[flag]!) }));
+  if (inputs.some(input => !input.text.trim())) usage('journal input files must contain nonempty text');
+  const reason = inputs[0]?.text ?? '';
+  const verbatim = inputs[1]?.text ?? '';
+  const amendedBar = inputs[2]?.text ?? '';
+  if (action === 'remove' && Object.keys(patch).length) usage('remove takes no step fields');
+  if (action === 'add' && FIELDS.some(field => patch[field] === undefined)) usage('add needs every step field');
+  if (action === 'revise' && Object.keys(patch).length === 0) usage('revise needs at least one step field');
+  if (patch.phase !== undefined && patch.phase !== 'rig' && patch.phase !== 'post') usage('--phase is rig or post');
+  if (patch.order !== undefined) {
+    const order = Number(patch.order);
+    if (!Number.isFinite(order)) usage('--order needs a finite number');
+    patch.order = order;
+  }
+  if (patch.rests_on !== undefined) {
+    const ids = String(patch.rests_on).split(',');
+    if (ids.some(value => !value.trim()) || new Set(ids).size !== ids.length) usage('--rests-on needs distinct nonempty answer ids');
+    patch.rests_on = ids;
+  }
+  if (patch.checkpoint_proposed !== undefined) {
+    if (!['true', 'false'].includes(String(patch.checkpoint_proposed))) usage('--checkpoint-proposed is true or false');
+    patch.checkpoint_proposed = patch.checkpoint_proposed === 'true';
+  }
+
+  const dir = resolve(positional[1] ?? process.cwd());
+  // Validate the target before creating a lock, then reload under the lock.
+  readProject(dir);
+  const releaseJob = acquireBoundJobWrite(dir);
+  const lock = join(dir, '.plan.lock');
+  let descriptor: number;
+  try { descriptor = openSync(lock, 'wx'); }
+  catch { releaseJob(); refuse('PLAN_WRITE_CONFLICT', 'project.json: cannot acquire its plan writer lock; finish or recover the active plan write before retrying'); }
+  try {
+    const { file, project } = readProject(dir);
+    const original = readFileSync(file);
+    if (amendingBar && inputs.some(input => readVerbatim(input.file) !== input.text)) refuse('PLAN_WRITE_CONFLICT', 'plan.bar_amendments: input files changed while acquiring locks; restore the intended files and retry');
+    if (!isObject(project.plan) || !Array.isArray(project.plan.steps)) refuse('PLAN_STEP_INVALID', 'plan.steps: must be a list in a plan object; restore the plan before drafting');
+    if (project.plan.replaced !== undefined && !Array.isArray(project.plan.replaced)) refuse('PLAN_REPLACED_INVALID', 'plan.replaced: must be an append-only list; restore its original history');
+    const next = structuredClone(project);
+    const plan = next.plan as JsonObject;
+    const steps = plan.steps as JsonObject[];
+    const matches = steps.filter(step => isObject(step) && step.id === id);
+    const previous = matches[0];
+    if (action === 'add' ? matches.length !== 0 : matches.length !== 1) refuse('PLAN_STEP_INVALID', `plan.steps[${id}]: ${action === 'add' ? 'id already exists' : 'no unique current step'}; use a distinct id for add or an existing id for revise/remove`);
+    if (action === 'add' && asArray(plan.replaced).some(entry => isObject(entry) && isObject(entry.step) && entry.step.id === id && completed(project, entry.step))) {
+      refuse('PLAN_STEP_DONE', `plan.steps[${id}]: completed work is retained in history; add the replacement under a new id`);
+    }
+    const at = new Date(now).toISOString();
+    if (amendingBar) {
+      const findings: import('./check.ts').Finding[] = [];
+      const journal = collectBarAmendments(project, findings, now);
+      if (findings[0]) refuse(findings[0].code, findings[0].message);
+      const generation = checkpointGeneration(project, id!);
+      const replay = journal.find(entry => isObject(entry.step) && entry.step.id === id
+        && entry.sha256 === stepHash(previous!) && entry.generation === generation);
+      if (replay) {
+        if (replay.by !== opts['--by'] || replay.reason !== reason || replay.verbatim !== verbatim || replay.amended_bar !== amendedBar) refuse('BAR_AMENDMENT_CONFLICT', `plan.bar_amendments: ${id} already has a different amendment; retain its original policy entry`);
+        return { stdout: json ? JSON.stringify(replay, null, 2) : `plan: bar ${id} already amended`, exit: 0 };
+      }
+      if (!previous || !['rig', 'post'].includes(String(previous.phase))
+        || stageOfStep(previous.phase as 'rig' | 'post', id!) !== project.stage
+        || completed(project, previous) || typeof previous.bar !== 'string' || !previous.bar.trim()) {
+        refuse('BAR_AMENDMENT_SCOPE', `plan.steps[${id}]: amendment needs one unfinished step with a bar in the current execution stage; preserve other stages and use the matching step`);
+      }
+      plan.bar_amendments = [...journal, { schema: 'rig-create/bar-amendment@1', step: structuredClone(previous),
+        sha256: stepHash(previous), generation, amended_bar: amendedBar, by: opts['--by']!, at, reason, verbatim }];
+    } else if (withdrawing) {
+      const findings: import('./check.ts').Finding[] = [];
+      const journal = collectCheckpointWithdrawals(project, findings, now);
+      if (findings[0]) refuse(findings[0].code, findings[0].message);
+      const generation = checkpointGeneration(project, id!);
+      const replay = journal.find(entry => isObject(entry.step) && entry.step.id === id
+        && entry.sha256 === stepHash(previous!) && entry.generation === generation);
+      if (replay) {
+        if (replay.by !== opts['--by'] || replay.reason !== reason || replay.verbatim !== verbatim) refuse('CHECKPOINT_WITHDRAWAL_CONFLICT', `plan.checkpoint_withdrawals: ${id} already has different withdrawal words or actor; retain its original journal entry`);
+        return { stdout: json ? JSON.stringify(replay, null, 2) : `plan: checkpoint ${id} already withdrawn`, exit: 0 };
+      }
+      if (!previous || !['rig', 'post'].includes(String(previous.phase))
+        || stageOfStep(previous.phase as 'rig' | 'post', id!) !== project.stage
+        || completed(project, previous) || !checkpointEnabled(previous) || !checkpointRequired(project, previous, now)) {
+        refuse('CHECKPOINT_WITHDRAWAL_SCOPE', `plan.steps[${id}]: withdrawal needs one enabled unfinished checkpoint in the current execution stage; preserve other stages and use the matching step`);
+      }
+      plan.checkpoint_withdrawals = [...journal, { schema: 'rig-create/checkpoint-withdrawal@1', step: structuredClone(previous),
+        sha256: stepHash(previous), generation, by: opts['--by']!, at: new Date(now).toISOString(), reason, verbatim }];
+    } else {
+      if (previous !== undefined) {
+        if (previous.phase !== 'rig' && previous.phase !== 'post') refuse('PLAN_STEP_INVALID', `plan.steps[${id}].phase: restore rig or post before drafting`);
+        const stage = approvalStageOfStep(previous.phase, id!, hasStageOrder(project));
+        const reopens = collectReopens(project, []);
+        if (collectSignoffs(project, []).some(signature => signature.stage === stage && signature.checkpoint === null
+          && (signature.steps === null || signature.steps.includes(id!)) && liveSignoff(reopens, signature.stage, signature.at))) {
+          refuse('PLAN_STEP_SIGNED', `plan.steps[${id}]: a live ${stage} signature binds this step; reopen ${stage} before revising or removing it`);
+        }
+        if (action === 'revise' && completed(project, previous)) refuse('PLAN_STEP_DONE', `plan.steps[${id}]: completed work cannot be revised; remove it and add the replacement under a new id`);
+      }
+      if (previous !== undefined) {
+        plan.replaced = [...asArray(plan.replaced), { step: structuredClone(previous), sha256: stepHash(previous), action: action === 'revise' ? 'revised' : 'removed', at, by: opts['--by']! }];
+        const index = steps.indexOf(previous);
+        if (action === 'remove') steps.splice(index, 1);
+        else steps[index] = { ...previous, ...patch };
+      } else steps.push({ id: id!, ...patch, checkpoint: null, status: 'pending' });
+      const changedSteps = [previous, ...steps.filter(step => isObject(step) && step.id === id)].filter(isObject);
+      const ownerships = new Set(changedSteps.map(step => approvalStageOfStep(step.phase as 'rig' | 'post', id!, hasStageOrder(project))));
+      if (ownerships.has('plan-approved')) {
+        plan.drafted_by = opts['--by']!;
+        plan.drafted_at = at;
+      }
+      if (ownerships.has('rigging-interview')) plan.rigging_drafted_at = at;
+    }
+
+    const amendmentFindings: import('./check.ts').Finding[] = [];
+    collectBarAmendments(next, amendmentFindings, now);
+    if (amendmentFindings[0]) refuse(amendmentFindings[0].code, amendmentFindings[0].message);
+    // Refusals the record already carries stay; a new code/path pair, or one more copy of a carried one, refuses.
+    const fresh = newFindings(baselineOf(checkProject(dir, project, { now })), checkProject(dir, next, { now }).refusals)[0];
+    if (fresh !== undefined) refuse(fresh.code, fresh.message);
+    const temporary = join(dirname(file), `.plan-${process.pid}-${crypto.randomUUID()}.tmp`);
+    try {
+      writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { flag: 'wx' });
+      if (!readFileSync(file).equals(original)) refuse('PLAN_WRITE_CONFLICT', 'project.json: changed while drafting; reload it and retry the plan command');
+      if (amendingBar && inputs.some(input => readVerbatim(input.file) !== input.text)) refuse('PLAN_WRITE_CONFLICT', 'plan.bar_amendments: input files changed before commit; restore the intended files and retry');
+      renameSync(temporary, file);
+    } finally { rmSync(temporary, { force: true }); }
+    return { stdout: json ? JSON.stringify(plan, null, 2) : `plan: ${action} ${id} by ${opts['--by']} at ${at}`, exit: 0 };
+  } finally {
+    closeSync(descriptor);
+    rmSync(lock);
+    releaseJob();
+  }
+}

package/src/plate-receipt.ts

@@ -0,0 +1,110 @@
+/** Bind the producer's published receipt bytes, without repeating its measurements. */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from './check-reads.ts';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { asArray, isObject, type Ctx } from './check.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const PLATE_RECEIPT_SINCE = '2026-11-08T00:00:00Z';
+const SPEC = 'rig-parts-plate-receipt/1';
+const KEYS = ['spec', 'mode', 'painting', 'mask', 'model', 'params', 'graph', 'gpu'];
+const hash = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+const hex = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/i.test(value);
+
+/** Reject symlinks at every component, including directory aliases within the project. */
+function receiptBytes(dir: string, path: unknown): Buffer {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\')) throw Error('project-relative receipt path required');
+  const rel = relative(dir, resolve(dir, path));
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || rel === 'project.json') throw Error('receipt must stay inside the project');
+  let current = dir;
+  for (const part of path.split('/').filter(part => part && part !== '.')) {
+    current = resolve(current, part);
+    const component = relative(dir, current);
+    if (component === '..' || component.startsWith(`..${sep}`)) throw Error('receipt must stay inside the project');
+    if (lstatSync(current).isSymbolicLink()) throw Error('receipt must have no symlink components');
+  }
+  return readFileSync(current);
+}
+
+/** Also used before the derived writer commits its new entry. */
+export function readPlateReceipt(dir: string, path: string): { binding: JsonObject; report: JsonObject } {
+  const bytes = receiptBytes(dir, path);
+  const value = JSON.parse(bytes.toString('utf8')) as Json;
+  if (!isObject(value) || value.spec !== SPEC) throw Error('known rig-parts-plate-receipt/1 spec required');
+  const keys = [...KEYS, ...(value.grid_transform === undefined ? [] : ['grid_transform']), 'output'];
+  if (Object.keys(value).join(',') !== keys.join(',')) throw Error('published receipt key order required');
+  const fileFields = [
+    ['painting', ['path', 'sha256']],
+    ['mask', ['source', 'from', 'path', 'sha256']],
+    ['output', ['path', 'sha256']],
+  ] as const;
+  for (const [field, fields] of fileFields) {
+    const record = value[field];
+    if (!isObject(record) || Object.keys(record).join(',') !== fields.join(',')
+      || typeof record.path !== 'string' || !record.path || isAbsolute(record.path)
+      || record.path.includes('\\') || !hex(record.sha256)) {
+      throw Error(`${field} needs the published path and sha256 fields`);
+    }
+  }
+  return { binding: { path, sha256: hash(bytes), spec: SPEC }, report: value };
+}
+
+export function checkPlateReceipt(ctx: Pick<Ctx, 'dir' | 'refusals'>, entry: JsonObject, at: string): void {
+  if (entry.receipt === undefined) return;
+  try {
+    if (!isObject(entry.receipt) || typeof entry.receipt.path !== 'string'
+      || !hex(entry.receipt.sha256) || entry.receipt.spec !== SPEC) {
+      throw Error('receipt needs path, sha256 and a known spec');
+    }
+    const { binding, report } = readPlateReceipt(ctx.dir, entry.receipt.path);
+    if (binding.sha256 !== entry.receipt.sha256.toLowerCase()) throw Error('receipt bytes differ from the recorded sha256');
+    const base = dirname(resolve(ctx.dir, entry.receipt.path));
+    const matches = (declared: JsonObject, recorded: JsonObject): boolean =>
+      typeof recorded.path === 'string' && hex(recorded.sha256)
+      && resolve(base, String(declared.path)) === resolve(ctx.dir, recorded.path)
+      && String(declared.sha256).toLowerCase() === recorded.sha256.toLowerCase();
+    const sources = entry.sources === undefined ? [entry.source] : asArray(entry.sources);
+    const painting = report.painting as JsonObject;
+    const mask = report.mask as JsonObject;
+    if (sources.length !== 2 || !sources.every(isObject)
+      || !(matches(painting, sources[0] as JsonObject) && matches(mask, sources[1] as JsonObject)
+        || matches(painting, sources[1] as JsonObject) && matches(mask, sources[0] as JsonObject))
+      || !matches(report.output as JsonObject, entry)) {
+      throw Error('painting, uploaded mask and output must match the recorded source and result paths and hashes');
+    }
+  } catch (error) {
+    ctx.refusals.push({ code: 'PLATE_RECEIPT_INVALID', path: `${at}.receipt`, message: `${at}.receipt: ${(error as Error).message}; restore the producer receipt and record its painting, mask and output with derived add --receipt` });
+  }
+}
+
+/** Scene plate registrations are the recorded discriminator. Earliest registration dates the rule. */
+export function checkPlateRegistrations(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'>): void {
+  const earliest = new Map<number, number>();
+  for (const scene of asArray(ctx.project.scenes)) {
+    if (!isObject(scene) || typeof scene.path !== 'string' || !hex(scene.sha256) || typeof scene.at !== 'string' || !Number.isFinite(Date.parse(scene.at))) continue;
+    let doc: JsonObject;
+    try {
+      const bytes = receiptBytes(ctx.dir, scene.path);
+      if (hash(bytes) !== scene.sha256.toLowerCase()) continue;
+      const value = JSON.parse(bytes.toString('utf8')) as Json;
+      if (!isObject(value)) continue;
+      doc = value;
+    } catch { continue; } // The scene checker reports missing or changed scene documents.
+    for (const plate of asArray(doc.plates)) {
+      if (!isObject(plate) || !isObject(plate.registered) || plate.registered.kind !== 'derived' || typeof plate.registered.ref !== 'string') continue;
+      const match = /^derived\[(\d+)\]$/.exec(plate.registered.ref);
+      if (!match) continue;
+      const index = Number(match[1]);
+      const entry = asArray(ctx.project.derived)[index];
+      if (!isObject(entry) || plate.path !== entry.path || plate.sha256 !== entry.sha256) continue;
+      earliest.set(index, Math.min(earliest.get(index) ?? Infinity, Date.parse(scene.at)));
+    }
+  }
+  for (const [index, first] of earliest) {
+    const entry = asArray(ctx.project.derived)[index] as JsonObject;
+    if (entry.receipt !== undefined) continue;
+    const path = `derived[${index}].receipt`;
+    const findings = first < Date.parse(PLATE_RECEIPT_SINCE) ? ctx.warnings : ctx.refusals;
+    findings.push({ code: 'PLATE_RECEIPT_MISSING', path, message: `${path}: scene-registered derived plate has no producer receipt; record the plate with derived add --receipt` });
+  }
+}