rig-create 1.0.1 → 1.0.4

package/scripts/verify-example-seals.ts

@@ -0,0 +1,148 @@
+/** Verify installed example seals, or pack a temporary copy without nested ignore losses. */
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readNpmJson } from './npm-json.ts';
+
+const packageRoot = resolve(import.meta.dir, '..');
+const hash = (path: string): string => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+function within(root: string, path: string): string {
+  const target = resolve(root, path);
+  const rel = relative(root, target);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw Error(`invalid example path: ${path}`);
+  return target;
+}
+
+function files(root: string): string[] {
+  return readdirSync(root, { withFileTypes: true }).flatMap(entry => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return files(path);
+    if (!entry.isFile()) throw Error(`expected a regular example file: ${path}`);
+    return [path];
+  }).sort();
+}
+
+export function verifyExampleSeals(root: string): { ok: number; failures: string[]; sealedFiles: string[] } {
+  const chainRoot = join(root, 'templates/example-chain');
+  const index = JSON.parse(readFileSync(join(chainRoot, 'chain.json'), 'utf8')) as { checkpoints: { name: string }[] };
+  if (!Array.isArray(index.checkpoints) || index.checkpoints.length === 0) throw Error('example-chain/chain.json: no checkpoints to verify');
+  let ok = 0;
+  const failures: string[] = [];
+  const sealedFiles: string[] = [];
+  for (const { name } of index.checkpoints) {
+    const declaration = within(join(chainRoot, 'checkpoints'), `${name}.json`);
+    if (!existsSync(declaration)) { failures.push(`missing checkpoint declaration: ${relative(root, declaration)}`); continue; }
+    const seal = JSON.parse(readFileSync(declaration, 'utf8')) as {
+      schema: string; name: string; files: { path: string; sha256: string }[]; project_sha256: string;
+    };
+    if (seal.schema !== 'rig-create/example-checkpoint@1' || seal.name !== name || !Array.isArray(seal.files) || seal.files.length === 0) {
+      throw Error(`${relative(root, declaration)}: invalid checkpoint seal`);
+    }
+    const checkpoint = within(join(chainRoot, 'checkpoints'), name);
+    for (const entry of [...seal.files, { path: 'project.json', sha256: seal.project_sha256 }]) {
+      const path = within(checkpoint, entry.path);
+      const label = relative(root, path);
+      sealedFiles.push(path);
+      if (!existsSync(path)) failures.push(`missing sealed file: ${label}`);
+      else if (!/^[a-f0-9]{64}$/.test(entry.sha256) || hash(path) !== entry.sha256) failures.push(`sha256 mismatch: ${label}`);
+      else ok++;
+    }
+  }
+  return { ok, failures, sealedFiles };
+}
+
+function report(root: string, log: (line: string) => void): ReturnType<typeof verifyExampleSeals> {
+  const result = verifyExampleSeals(root);
+  for (const failure of result.failures) log(failure);
+  log(`checkpoint seals: ${result.ok} ok / ${result.failures.length} fail (files[] plus project_sha256)`);
+  if (result.failures.length) throw Error('example seals failed; repack the unmodified source with scripts/verify-example-seals.ts --pack <output-dir>');
+  return result;
+}
+
+function run(command: string, args: string[], cwd?: string): string {
+  const result = spawnSync(command, args, { cwd, encoding: 'utf8', timeout: 60_000, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 });
+  if (result.error || result.status !== 0) throw Error(`${command} ${args.join(' ')} failed: ${result.error?.message ?? result.status}\n${result.stderr}`);
+  return result.stdout;
+}
+
+/** Only the disposable copy gets .npmignore; every original example byte is retained. */
+function stage(root: string, destination: string): void {
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { files: string[] };
+  mkdirSync(destination);
+  cpSync(join(root, 'package.json'), join(destination, 'package.json'));
+  for (const path of manifest.files) {
+    const target = within(destination, path);
+    mkdirSync(dirname(target), { recursive: true });
+    cpSync(within(root, path), target, { recursive: true });
+  }
+  for (const path of files(join(destination, 'templates')).filter(path => path.endsWith(`${sep}.gitignore`))) {
+    const npmignore = join(dirname(path), '.npmignore');
+    if (existsSync(npmignore)) throw Error(`pack staging would overwrite ${npmignore}`);
+    writeFileSync(npmignore, '!**\n');
+  }
+}
+
+export function verifyTarball(tarball: string, sourceRoot?: string): void {
+  const scratch = mkdtempSync(join(tmpdir(), 'create-example-seals-'));
+  try {
+    run('tar', ['-xzf', resolve(tarball), '-C', scratch]);
+    const root = join(scratch, 'package');
+    const verified = report(root, console.error);
+    if (sourceRoot) {
+      const source = join(sourceRoot, 'templates');
+      const originals = files(source);
+      for (const path of originals) {
+        const target = join(root, 'templates', relative(source, path));
+        if (!existsSync(target) || hash(target) !== hash(path)) throw Error(`packed template missing or changed: templates/${relative(source, path)}`);
+      }
+      console.error(`template byte parity: ${originals.length} files match source`);
+    }
+    // Negative control operates only on the extracted tree, after the positive gate.
+    const deleted = verified.sealedFiles.find(path => path.endsWith(`${sep}.gitignore`))!;
+    unlinkSync(deleted);
+    const planted = verifyExampleSeals(root);
+    const expected = `missing sealed file: ${relative(root, deleted)}`;
+    if (planted.failures.length !== 1 || planted.failures[0] !== expected || planted.ok !== verified.ok - 1) {
+      throw Error(`planted deletion was not detected: ${expected}`);
+    }
+    console.error(`planted deletion detected: ${expected} (${planted.ok} ok / 1 fail)`);
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+
+export function packExamples(output: string, stageOutput?: string): string {
+  const scratch = mkdtempSync(join(tmpdir(), 'create-example-pack-'));
+  try {
+    const destination = resolve(output);
+    mkdirSync(destination, { recursive: true });
+    const staged = stageOutput === undefined ? join(scratch, 'source') : resolve(stageOutput);
+    stage(packageRoot, staged);
+    const name = (JSON.parse(readFileSync(join(staged, 'package.json'), 'utf8')) as { name: string }).name;
+    const args = ['pack', '.', '--json', '--pack-destination', destination];
+    const packed = readNpmJson(run('npm', args, staged), `npm ${args.join(' ')}`, 'pack', name);
+    const tarball = join(destination, packed.filename);
+    console.error(`npm pack: ${packed.entryCount} files / ${packed.size} bytes compressed / ${packed.unpackedSize} bytes unpacked`);
+    verifyTarball(tarball, packageRoot);
+    return tarball;
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+
+if (import.meta.main) {
+  try {
+    const [mode, path, ...extra] = process.argv.slice(2);
+    if (mode === undefined) report(packageRoot, console.log);
+    else if (path && extra.length === 0 && mode === '--pack') console.log(packExamples(path));
+    else if (path && extra.length === 0 && mode === '--tarball') verifyTarball(path);
+    else if (path && extra.length === 0 && mode === '--stage') {
+      const scratch = mkdtempSync(join(tmpdir(), 'create-example-stage-gate-'));
+      try { packExamples(scratch, path); console.log(resolve(path)); }
+      finally { rmSync(scratch, { recursive: true, force: true }); }
+    }
+    else throw Error('usage: bun scripts/verify-example-seals.ts [--pack <output-dir> | --tarball <file.tgz> | --stage <fresh-dir>]');
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/src/agent-guide.ts

@@ -53,7 +53,7 @@ export const PACKAGE_DOCS: readonly PackageDoc[] = [
   {
     package: '@rig-c/parts',
     path: 'docs/DEPTH.md',
-    why: 'when the plan has a head turn driven by depth',
+    why: 'depth reference; unavailable in current direction',
   },
   {
     package: '@rig-c/parts',
@@ -88,7 +88,7 @@ export const PACKAGE_DOCS: readonly PackageDoc[] = [
   {
     package: '@rig-c/core',
     path: 'docs/FACE.md',
-    why: 'blink, gaze and head-turn plans',
+    why: 'blink and gaze in the accepted rig',
   },
   {
     package: '@rig-c/core',
@@ -155,13 +155,13 @@ function createLink(label: string, path: string, anchor?: string): string {
  * linked, because the package links below are exactly PACKAGE_DOCS.
  */
 export const READ_FIRST = [
-  '1. **Before the interview**: INTERVIEW.md, and CRAFT.md for the default at each',
-  '   waypoint (both linked below); parts AUTHORING §3, *`config.json`, field by',
-  `   field*; ${createLink('CHECKS.md', 'docs/CHECKS.md')} before a sign-off.`,
-  '2. **Before `seethrough` and `assemble`**: SOURCE.md, the order of the split and',
-  `   the cut: ${createLink('re-running a bad split', 'docs/SOURCE.md', 're-run-first')},`,
-  `   ${createLink('where a cut is allowed', 'docs/SOURCE.md', 'where-a-cut-is-allowed')};`,
-  '   then parts AUTHORING *See-through head-run source reading*, *Source before',
+  '1. **Before the interview**: INTERVIEW.md; CRAFT.md (waypoint defaults);',
+  '   parts AUTHORING §3, *`config.json`, field by field*;',
+  `   ${createLink('CHECKS.md', 'docs/CHECKS.md')} before a sign-off.`,
+  '2. **Before `seethrough` and `assemble`**: SOURCE.md, split/cut order:',
+  `   ${createLink('bad-split reruns', 'docs/SOURCE.md', 're-run-first')},`,
+  `   ${createLink('allowed cuts', 'docs/SOURCE.md', 'where-a-cut-is-allowed')};`,
+  '   parts AUTHORING *See-through head-run source reading*, *Source before',
   '   scissors* and *Limbs: cut at their joints*.',
   `3. **Before rigging**: ${createLink('CRAFT.md § For the gates', 'docs/CRAFT.md', 'for-the-gates-not-the-interview')}`,
   '   (G1–G9); core RIGGING and MOTION; parts AUTHORING §7, the bars `check` enforces.',
@@ -175,7 +175,9 @@ export const READ_FIRST = [
  * rig-c/create#3 it is `rig-create interview --check`, which refuses every
  * `null` answer by name, so the line names the command, not the doc reference.
  */
-export const INTERVIEW_CHECK_LINE = 'Before asking the user to sign the interview, run `rig-create interview --check`: it names every `null` answer.';
+export const INTERVIEW_CHECK_LINE = 'Run `rig-create interview --check` before interview sign-off: it names every `null` answer.';
+
+export const REOPEN_EXCEPTION = 'Until create#493, agents may type `reopen` only from Review host raw export `act@4`: save nonempty `value.words` byte-for-byte to a verbatim file; `--source` names `actId`. Empty/missing words: STOP. Never supply words. `job fetch-act` rejects act@4.';
 
 export const GUIDE_TEMPLATE = 'agent-guide.md';
 
@@ -198,12 +200,13 @@ function linkLine(label: string, href: string, why: string): string {
 /** The text of AGENTS.md, from the template and the tables above. */
 export function renderAgentGuide(): string {
   const fills: Record<string, string> = {
-    RESUME_LINK: `[PROJECT.md § How an agent resumes a project](${createDocUrl(RESUME_LINK.path, RESUME_LINK.anchor)})`,
+    RESUME_LINK: `[Resume](${createDocUrl(RESUME_LINK.path, RESUME_LINK.anchor)})`,
     INTERVIEW_CHECK: INTERVIEW_CHECK_LINE,
+    REOPEN_EXCEPTION,
     DERIVED_LINK: `[INTERVIEW.md § Derived answers](${createDocUrl(DERIVED_LINK.path, DERIVED_LINK.anchor)})`,
     GATES_LINK: `[CRAFT.md G8](${createDocUrl(GATES_LINK.path, GATES_LINK.anchor)})`,
-    DRAFTS_LINK: `[PROJECT.md § Labelled draft rigs](${createDocUrl(DRAFTS_LINK.path, DRAFTS_LINK.anchor)})`,
-    STAGES_LINK: `[PROJECT.md § Stages](${createDocUrl(STAGES_LINK.path, STAGES_LINK.anchor)})`,
+    DRAFTS_LINK: `[Draft rigs](${createDocUrl(DRAFTS_LINK.path, DRAFTS_LINK.anchor)})`,
+    STAGES_LINK: `[Stages](${createDocUrl(STAGES_LINK.path, STAGES_LINK.anchor)})`,
     LIFETIME_LINK: `[PROJECT.md § Data is split by lifetime](${createDocUrl(LIFETIME_LINK.path, LIFETIME_LINK.anchor)})`,
     INTAKE_LINK: `[PROJECT.md § Advisory intake reports](${createDocUrl(INTAKE_LINK.path, INTAKE_LINK.anchor)})`,
     CG_GATES_LINK: `[CHECKS.md § CG gates](${createDocUrl(CG_GATES_LINK.path, CG_GATES_LINK.anchor)})`,

package/src/choice-writers.ts

@@ -24,7 +24,13 @@ interview-answer <question> [<dir>] --set <path> --sha256 <shown sha> --by <huma
   [--note-file <file>] [--source <location>] [--why-file <file> for a member override]
 interview-decision <question> [<dir>] --by <agent> --reasoning-file <file>
   --fragment <ask>=<JSON file>...
-Retain the shown set first. Each ask is picked explicitly; no recommended option is preselected.`;
+Retain the shown set first. Each ask is picked explicitly; no recommended option is preselected.
+To ask an answered question again, retain and register a new set id/path with
+interview-options <question> --file <path>, then job open --question <question>
+and ingest interview-answer <question> --from-review <actId>; history is kept.
+--adopt: split-order projects adopt all choices; legacy-order projects may adopt
+post choices at post-interview only. For full adoption, first adopt the split
+stage order with a fresh parts/rigging interview (docs/INTERVIEW.md).`;
 function usage(why: string): never { refuse('INTERVIEW_OPTIONS_USAGE', `interview: ${why}; ${CHOICE_HELP}`, USAGE_EXIT); }
 interface Args { positional: string[]; one: Record<string,string>; many: Record<string,Map<string,string>>; adopt: boolean; }
 function parse(args: string[], allowed: string[], repeat: string[] = []): Args {
@@ -97,7 +103,7 @@ export function interviewOptionsCommand(args: string[], now: number): string { r
     const dir = resolve(opts.positional[0] ?? process.cwd()); const {file,project} = readProject(dir); const next = structuredClone(project);
     const interview = isObject(next.interview) ? next.interview : null;
     if (interview && interview.order === undefined && isObject(interview.post)) {
-      if (project.stage !== 'post-interview') refuse('INTERVIEW_CHOICE_INVALID', 'interview.post: advance to post-interview before adopting post choices');
+      if (project.stage !== 'post-interview') refuse('INTERVIEW_CHOICE_INVALID', 'interview.post: for post-only choices, advance to post-interview before interview-options --adopt; for full adoption, first adopt the split stage order with a fresh parts/rigging interview (docs/INTERVIEW.md)');
       if (interview.post.choices_adopted_at !== undefined) {
         if (!Number.isFinite(Date.parse(String(interview.post.choices_adopted_at)))) refuse('INTERVIEW_CHOICE_INVALID', 'interview.post: restore the original valid choices_adopted_at');
         return 'interview: post choices already adopted; original date preserved';

package/src/choices.ts

@@ -177,7 +177,7 @@ export function optionContext(project: JsonObject, stage: string, at: number, di
   if (!signoff || !rig || !isObject(provenance.config)) fail('INTERVIEW_OPTIONS_STALE', 'accept a rig with retained config before drafting post options');
   const approval = latestPartsApproval(project, date(rig.at));
   const draft = objects(project.drafts).find(d => d.id === approval?.draft_id);
-  if (!draft || !isObject(draft.parts)) fail('INTERVIEW_OPTIONS_STALE', 'retain the accepted rig parts identity before drafting post options');
+  if (!draft || !isObject(draft.parts)) fail('INTERVIEW_OPTIONS_STALE', `versions[v${String(rig.n)}]: no retained approved draft parts are available at rig.at ${String(rig.at)}; restore the parts-review approval and draft live at that build date, or register a new rig version after parts-review before drafting post options`);
   return { kind: 'rig', rig_version: rig.n as Json, signoff_at: signoff.record.at as Json, config: provenance.config, parts: draft.parts };
 }
 

package/src/cli.ts

@@ -113,12 +113,20 @@ ${INPUT_CLI}  rig-create init <dir> [--no-install]              create a project
   rig-create --help                                 show this help
   rig-create --version                              show the version
 
+job open / job reconcile / bound writers:
+  --rig <n>      selects a registered rig OR post version; the flag name is shared
+  Keep the Review host up across bound writes (including advance and republish).
+  If it stopped, job open again with --reviewer <id> --role owner|delegate,
+  then job reconcile; a pending publication blocks later bound writes.
+
 init:
   <dir>          an empty or missing folder; a non-empty one is refused
   --no-install   do not run bun install (offline, tests); run it yourself afterwards
   --painting <file> --origin <words>
                  copy the painting into inputs/, register it and declare project.painting; refused (INIT_ARTWORK_EXISTS) when a
-                 project directly under --projects-root (default: the parent folder) binds the same sha256
+                 project directly under --projects-root (default: the parent folder) binds the same sha256.
+                 Continue there as a new version; restart keeps its correction ledger.
+                 A new project is for different artwork or a different rig kind only.
   --same-artwork-reason <file>
                  record why this artwork needs a second project (a different rig kind)
 

package/src/direction-writers.ts

@@ -18,6 +18,8 @@ direction write <N> [<dir>] --file <retained JSON> --rig <R> [--answers <version
 direction patch <N> [<dir>] --patch-file <retained direction-patch/1> [--answers <version>:<verdict>]
 direction check <N> [<dir>] [--json]
   Documents are immutable evidence/direction/v<N>.json. No rendering or producer builds.
+  --file and --patch-file are retained, non-ignored project-relative paths.
+  A bounced predecessor needs --answers <version>:<verdict> on write/patch.
   Capture a made correction with correction record --direction-patch-file before patch ingestion;
   resolve it against the result post. Review exports patches, never invokes this writer.`;
 function usage(why:string):never {refuse('DIRECTION_USAGE',`direction: ${why}; ${DIRECTION_HELP}`,USAGE_EXIT);}
@@ -32,7 +34,7 @@ function prospective(dir:string,before:JsonObject,next:JsonObject,now:number):vo
 /** A narrow seam for fault-injected transaction tests; CLI never supplies a hook. */
 export interface DirectionWriteHooks { beforeCommit?:()=>void; }
 export function directionCommand(args:string[],now:number,hooks:DirectionWriteHooks={}):{stdout:string;exit:number} {
-  try{return command(args,now,hooks);}catch(e){if(e instanceof DirectionError)refuse(e.code,e.message,e.code==='DIRECTION_USAGE'?USAGE_EXIT:1);throw e;}
+  try{return command(args,now,hooks);}catch(e){if(e instanceof DirectionError)refuse(e.code,e.code==='FEEDBACK_UNANSWERED'?`${e.message}; retry direction write/patch with --answers <version>:<verdict> naming the bounced verdict`:e.message,e.code==='DIRECTION_USAGE'?USAGE_EXIT:1);throw e;}
 }
 function command(args:string[],now:number,hooks:DirectionWriteHooks):{stdout:string;exit:number} {
   const action=args[0];const positional:string[]=[];const opts:Record<string,string>={};const answerValues:string[]=[];let json=false;

package/src/direction.ts

@@ -35,7 +35,8 @@ export function directionFinding(e: DirectionError): Finding { return { code: e.
 export function directionBytes(dir: string, path: string): Buffer { return retainedBytes(dir, path, false); }
 function retainedBytes(dir: string, path: string, boundOutput: boolean): Buffer {
   try {
-    if (isAbsolute(path) || path.includes('\\') || path.split('/').some(p => !p || p === '.' || p === '..') || !boundOutput && structurePathIsIgnored(dir, path) && !/^derived\/review\/v[1-9][0-9]*\/out\/check\/build\/skeleton\.model\.json$/.test(path)) throw Error('literal retained POSIX path required');
+    if (isAbsolute(path) || path.includes('\\') || path.split('/').some(p => !p || p === '.' || p === '..')) throw Error('literal project-relative POSIX path required');
+    if (!boundOutput && structurePathIsIgnored(dir, path) && !/^derived\/review\/v[1-9][0-9]*\/out\/check\/build\/skeleton\.model\.json$/.test(path)) throw Error('path is ignored; retain the source in a non-ignored project folder such as evidence/direction-src/ and pass that project-relative path');
     let current = realpathSync(dir);
     for (const [i, segment] of path.split('/').entries()) {
       current = join(current, segment); const stat = lstatSync(current);

package/src/feedback.ts

@@ -27,6 +27,7 @@ import { acquireBoundJobWrite, jobRuntimeExecArgv } from './job-writer.ts';
 import { jobHash } from './job-outbox.ts';
 import { assertReviewActSource, decodeReviewAct, reviewActFindings, reviewActPublicationWarning, reviewActStill, reviewActTransport, reviewActVerbatim, reviewActVersionHash, type FetchedReviewAct } from './review-act.ts';
 import { newRefusals } from './refusal-baseline.ts';
+import { ingestedVerdictPairFinding } from './signoff-pair.ts';
 import { dirname, join, resolve } from 'node:path';
 
 import { asArray, asString, collectItems, isObject, itemFor, loadCollection, type Ctx, type Item } from './check.ts';
@@ -541,7 +542,7 @@ function writeVerdict(projectDirArg: string, input: ReviewInput, now: number, fe
         bytes: fetched.bytes, sha256: jobHash(fetched.bytes), version: input.version, verdict: verdicts.length - 1,
         version_hash: reviewActVersionHash(original, fetched.act), added_evidence: addedEvidence };
       project.review_acts = [...asArray(project.review_acts), receipt];
-      const invalid = reviewActFindings(project)[0] ?? newRefusals(dir, original, project, { now })[0];
+      const invalid = reviewActFindings(project)[0] ?? ingestedVerdictPairFinding(project, input.version, verdicts.length - 1) ?? newRefusals(dir, original, project, { now })[0];
       if (invalid) refuse(invalid.code, invalid.message);
       assertReviewActSource(dir, original, fetched.act);
       if (!readFileSync(file).equals(originalBytes)) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json: record changed during verdict validation; retry against the current live job');
@@ -556,7 +557,7 @@ function writeVerdict(projectDirArg: string, input: ReviewInput, now: number, fe
       } finally { closeSync(fd); rmSync(temporary, { force: true }); }
       return result;
     }
-    const invalid = newRefusals(dir, original, project, { now })[0];
+    const invalid = ingestedVerdictPairFinding(project, input.version, verdicts.length - 1) ?? newRefusals(dir, original, project, { now })[0];
     if (invalid) refuse(invalid.code, invalid.message);
     writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
     return { project_dir: dir, verdict_path: verdictPath, verdict, items: out, stage: asString(project.stage) };
@@ -589,6 +590,8 @@ export function recordReviewAct(root: string, requestedVersion: number, actId: s
         ? existing.bytes === response.bytes
         : isDeepStrictEqual(JSON.parse(String(existing.bytes)), act);
       if (!sameAct) refuse('REVIEW_ACT_REPLAY_CONFLICT', 'project.json.review_acts: immutable act changed; restore the original receipt');
+      const pair = ingestedVerdictPairFinding(project, requestedVersion, Number(existing.verdict));
+      if (pair) refuse(pair.code, pair.message);
       if (existing.version_hash !== reviewActVersionHash(project, act, Number(existing.verdict))) refuse('REVIEW_ACT_SOURCE_STALE', 'project.json.review_acts: reviewed version changed; request a new review act');
       const version = asArray(project.versions).find(v => isObject(v) && v.n === requestedVersion) as JsonObject;
       return { project_dir: root, verdict_path: `versions[v${requestedVersion}].verdicts[${existing.verdict}]`,

package/src/init.ts

@@ -65,7 +65,7 @@ export function sameArtworkFor(dir: string, name: string, sha256: string, now: n
     return inputs.some(input => input !== null && typeof input === 'object' && (input as JsonObject).sha256 === sha256);
   });
   if (matches.length > 0 && options.sameArtworkReason === undefined) {
-    refuse('INIT_ARTWORK_EXISTS', `inputs[${options.index ?? 0}]: ${name} (sha256 ${sha256}) is already an input of ${matches.join(', ')} under ${root}; one artwork is one project, so record a redo, a new source or a new tool as a version there, or give --same-artwork-reason <file> for a different rig kind`);
+    refuse('INIT_ARTWORK_EXISTS', `inputs[${options.index ?? 0}]: ${name} (sha256 ${sha256}) is already an input of ${matches.join(', ')} under ${root}; continue in that existing project as a new version; restart there inherits its correction ledger. A new project is only for different artwork or a different rig kind (--same-artwork-reason <file> for the latter); do not copy the artwork to bypass this refusal`);
   }
   if (options.sameArtworkReason !== undefined) {
     if (matches.length === 0) refuse('INIT_ARTWORK_USAGE', `--same-artwork-reason: no project under ${root} binds ${name}; drop the reason`, USAGE_EXIT);

package/src/job-acts.ts

@@ -1,7 +1,12 @@
 /** Writer routing for finalized acts. No event transport or automatic ingestion. */
 import type { ActV3 } from '@rig-c/review/job-host';
-import { asArray, isObject } from './check.ts';
+import { asArray, isObject, type Finding } from './check.ts';
+import { existsSync, readFileSync } from './check-reads.ts';
+import { join } from 'node:path';
+import { recordedPartsVerdict } from './parts-verdict-record.ts';
 import { stageOfStep } from './stages.ts';
+import { checkStructure } from './structure.ts';
+import { createHash } from 'node:crypto';
 import type { JsonObject } from './templates.ts';
 
 export interface PendingJobAct {
@@ -11,6 +16,7 @@ export interface PendingJobAct {
   at: string;
   args: string[] | null;
   command: string | null;
+  preconditions?: { command: string | null; act: string }[];
   unavailable?: { code: 'JOB_ACTS_WRITER_UNAVAILABLE'; message: string };
 }
 
@@ -18,6 +24,23 @@ function shellWord(value: string): string {
   return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
 }
 
+/** A retained snapshot is reusable only for this exact draft and config.
+ * Never overwrite unrelated or invalid bytes: choose the next retained name.
+ */
+export function partsStructureSnapshot(root: string, project: JsonObject, draft: string): { path: string; valid: boolean } {
+  const stem = `evidence/structure-${encodeURIComponent(draft)}`;
+  for (let suffix = 0; ; suffix++) {
+    const path = `${stem}${suffix === 0 ? '' : `-${suffix}`}.json`;
+    if (!existsSync(join(root, path))) return { path, valid: false };
+    try {
+      const bytes = readFileSync(join(root, path));
+      const errors: Finding[] = [];
+      const signoff = { draft_id: draft, structure: { path, sha256: createHash('sha256').update(bytes).digest('hex') } };
+      if (checkStructure(root, project, signoff, path, errors) !== null && errors.length === 0) return { path, valid: true };
+    } catch { /* Preserve the existing bytes and select another output path. */ }
+  }
+}
+
 export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root: string): PendingJobAct[] {
   const ingested = new Set(asArray(project.review_acts).filter(isObject).map(row => JSON.stringify([row.jobId, row.actId])));
   const signoffs = asArray(project.signoffs).filter(isObject);
@@ -28,6 +51,7 @@ export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root
     seen.add(key);
     let subject: string = act.kind;
     let args: string[] | null = null;
+    const preconditions: { command: string | null; act: string }[] = [];
     switch (act.kind) {
       case 'review-verdict': {
         const selector = act.source.selector;
@@ -51,10 +75,26 @@ export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root
         subject = `question ${act.value.questionId}`;
         args = ['interview-answer', act.value.questionId, root];
         break;
-      case 'signoff':
+      case 'signoff': {
         subject = `stage ${act.value.stage}`;
         args = ['signoff', act.value.stage, root];
+        if (act.value.stage === 'parts-review') {
+          const selector = act.source.selector;
+          // Select only the draft shown by Review, never the latest draft by guess.
+          if (selector?.kind !== 'draft') { args = null; break; }
+          const draft = selector.id;
+          const structure = partsStructureSnapshot(root, project, draft);
+          let approved = false;
+          try { recordedPartsVerdict(root, project, draft); approved = true; } catch { /* Ordered prerequisite below. */ }
+          if (!approved) preconditions.push({ command: null, act: `ingest the approved parts-verdict for draft ${draft} before structure-snapshot; use its job acts writer command` });
+          if (!structure.valid) preconditions.push({
+            command: ['rig-create', 'structure-snapshot', root, '--draft', draft, '--out', structure.path].map(shellWord).join(' '),
+            act: 'after ingesting the approved parts-verdict, retain the structure snapshot before signoff',
+          });
+          args.push('--draft', draft, '--structure-file', structure.path);
+        }
         break;
+      }
       case 'checkpoint': {
         const step = asArray(isObject(project.plan) ? project.plan.steps : undefined).filter(isObject).find(step => step.id === act.value.planStepId);
         subject = `checkpoint ${act.value.planStepId}`;
@@ -68,6 +108,7 @@ export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root
     }
     if (args) args.push('--from-review', act.actId);
     return [{ actId: act.actId, kind: act.kind, subject, at: act.at, args,
+      ...(preconditions.length ? { preconditions } : {}),
       command: args ? ['rig-create', ...args].map(shellWord).join(' ') : null,
       ...(args ? {} : { unavailable: { code: 'JOB_ACTS_WRITER_UNAVAILABLE' as const,
         message: `project.json: act ${act.actId} (${subject}) has no current writer target; restore its plan step or use a supported Review subject before ingestion` } }) }];
@@ -76,5 +117,5 @@ export function pendingJobActs(project: JsonObject, acts: readonly ActV3[], root
 
 export function jobActsText(result: { acts: readonly PendingJobAct[] }): string {
   if (!result.acts.length) return 'job: no finalized acts awaiting ingestion';
-  return result.acts.map(act => `${act.actId} ${act.kind} ${act.subject} at ${act.at}\n  ${act.command ?? `${act.unavailable!.code}: ${act.unavailable!.message}`}`).join('\n');
+  return result.acts.map(act => `${act.actId} ${act.kind} ${act.subject} at ${act.at}\n${(act.preconditions ?? []).map(step => `  first: ${step.command ?? step.act}\n`).join('')}  ${act.command ?? `${act.unavailable!.code}: ${act.unavailable!.message}`}`).join('\n');
 }

package/src/job-host.ts

@@ -424,7 +424,7 @@ export function requestedRecordResult(root: string, question?: string, plan = fa
   if (question !== undefined) {
     const items = collectItems(project, { collection: loadCollection(root, project) }).filter(item => item.id === question);
     const binding = items.length === 1 ? items[0]!.record.pending_options : undefined;
-    if (!isObject(binding) || typeof binding.path !== 'string') refuse('JOB_RECORD_SUBJECT_INVALID', 'project.json: requested question has no unique pending option set; register it with interview-options first');
+    if (!isObject(binding) || typeof binding.path !== 'string') refuse('JOB_RECORD_SUBJECT_INVALID', `project.json: requested question has no unique pending option set; register it with rig-create interview-options ${question} '${root.replaceAll("'", "'\\''")}' --file '<option-set.json>' first (draft a new option set to re-ask an answered question)`);
     const set = JSON.parse(publicationFile(root, binding.path).toString('utf8')) as JsonObject;
     if (typeof set.id !== 'string') refuse('JOB_RECORD_SUBJECT_INVALID', 'project.json: pending option set has no id; restore its original identity');
     result = { kind: 'option-set', questionId: question, setId: set.id };