@rig-c/create 1.0.1 → 1.0.2

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 };

package/src/next.ts

@@ -24,6 +24,7 @@ import {
   resolveDiffMapPartsFile,
   validateDiffMapRecord,
 } from './diff-map.ts';
+import { partsStructureSnapshot } from './job-acts.ts';
 import { JOB_BINDING_FILE, type WriterBinding } from './job-outbox.ts';
 import { isPartsCheckMove, partsCheckRecord } from './parts-check.ts';
 import { recordedPartsVerdict } from './parts-verdict-record.ts';
@@ -50,9 +51,9 @@ import {
   STAGE_VALUES,
   stageIndex,
   stageOfStep,
-  stepCoveredByApproval,
 } from './stages.ts';
 import type { Json, JsonObject } from './templates.ts';
+import { sceneCurrentAt } from './scene.ts';
 
 export const NEXT_SCHEMA = 'rig-create/next@1';
 
@@ -109,6 +110,8 @@ export interface NextReport {
   accepted: boolean;
   refusals: NextRefusal[];
   warnings?: Finding[];
+  /** A view of existing answers, never a new project record. */
+  answers?: { question_id: string; field: string; by: Json; at: Json; picks: { ask: Json; option_id: Json; label: Json }[]; command?: string }[];
   awaits: string[];
   moves: NextMove[];
 }
@@ -191,6 +194,14 @@ function isOpenInterviewTodo(finding: Finding, effectiveStage: string): boolean
   return isOpenInterviewStage(effectiveStage) && finding.code === 'INTERVIEW_INCOMPLETE';
 }
 
+function shellWord(value: string): string {
+  return /^[A-Za-z0-9_./:-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function optionCommand(id: string, dir: string): string {
+  return `rig-create interview-options ${shellWord(id)} ${shellWord(dir)} --file '<option-set.json>'`;
+}
+
 function candidateAdvance(
   dir: string,
   project: JsonObject,
@@ -264,8 +275,8 @@ function candidateAdvance(
   const checked = checkProject(dir, clone, { now, forwardWrite: true, readOnly: true });
   if (newFindings(allowed, checked.refusals).length > 0) return null;
   return partsCheck
-    ? `rig-create advance ${targetStage} --parts-check ${partsCheck.report} --parts ${partsCheck.root}`
-    : `rig-create advance ${targetStage}`;
+    ? `rig-create advance ${targetStage} ${shellWord(dir)} --parts-check ${shellWord(partsCheck.report)} --parts ${shellWord(partsCheck.root)}`
+    : `rig-create advance ${targetStage} ${shellWord(dir)}`;
 }
 
 function candidateStepStatus(
@@ -327,7 +338,7 @@ function candidateStepStatus(
   const allowed = carriedRefusals(dir, before, { now, forwardWrite: false });
   const checked = checkProject(dir, clone, { now, forwardWrite: false, readOnly: true });
   if (newFindings(allowed, checked.refusals).length > 0) return null;
-  return `rig-create step-status ${stepId} ${nextStatus} --by agent`;
+  return `rig-create step-status ${shellWord(stepId)} ${nextStatus} ${shellWord(dir)} --by agent`;
 }
 
 function nextStageInOrder(project: JsonObject, currentStage: string): string | null {
@@ -362,6 +373,7 @@ function resolveLaggingAdvance(
     }
     return null;
   }
+  if (stage === 'post' && (!asArray(project.scenes).length || !asArray(project.versions).some(v => isObject(v) && v.kind === 'post'))) return null;
   const cmd = candidateAdvance(dir, project, nextStage, now);
   return cmd !== null ? { targetStage: nextStage, command: cmd } : null;
 }
@@ -473,7 +485,7 @@ function resolveDiffComponentsMove(
         const recordedPaintingSha = (draftReport.painting as { sha256: string }).sha256;
         if (stackSha === recordedStackSha && paintingSha === recordedPaintingSha) {
           return {
-            command: `cp ${draftReportPath} evidence/diff-components.json`,
+            command: `cp ${shellWord(resolve(dir, draftReportPath))} ${shellWord(resolve(dir, 'evidence/diff-components.json'))}`,
             act: `copy ${draftReportPath} for drafts[${draftId}] to evidence/diff-components.json`,
           };
         }
@@ -483,9 +495,9 @@ function resolveDiffComponentsMove(
     }
   }
 
-  const figureFlag = figureMaskPath !== undefined ? ` --figure ${figureMaskPath}` : '';
+  const figureFlag = figureMaskPath !== undefined ? ` --figure ${shellWord(resolve(dir, figureMaskPath))}` : '';
   return {
-    command: `rig-parts diff-components --stack ${stackPath} --painting ${paintingPath} --parts ${partsRoot}/parts.json${figureFlag} --floor 2 --threshold 40 --out evidence/diff-components.json`,
+    command: `rig-parts diff-components --stack ${shellWord(resolve(dir, stackPath))} --painting ${shellWord(resolve(dir, paintingPath))} --parts ${shellWord(resolve(dir, partsRoot, 'parts.json'))}${figureFlag} --floor 2 --threshold 40 --out ${shellWord(resolve(dir, 'evidence/diff-components.json'))}`,
     act: `run rig-parts diff-components for drafts[${draftId}]`,
   };
 }
@@ -524,13 +536,13 @@ function resolveDiffClassesCommand(dir: string): string {
       const bytes = diffReportBytes(dir, 'evidence/diff-components.json');
       const parsed = JSON.parse(bytes.toString('utf8')) as Json;
       if (isObject(parsed) && reportShape(parsed) && (parsed.components as unknown[]).length === 0) {
-        return 'rig-create diff-classes --diff-report evidence/diff-components.json --by agent';
+        return `rig-create diff-classes ${shellWord(dir)} --diff-report evidence/diff-components.json --by agent`;
       }
     } catch {
       // Fall through to default command with --triage-file.
     }
   }
-  return 'rig-create diff-classes --diff-report evidence/diff-components.json --triage-file evidence/diff-triage.json --by agent';
+  return `rig-create diff-classes ${shellWord(dir)} --diff-report evidence/diff-components.json --triage-file evidence/diff-triage.json --by agent`;
 }
 
 export function nextProject(projectDirArg: string, now: number = Date.now()): NextReport {
@@ -543,7 +555,18 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
   const stage = String(project.stage ?? '');
   const effectiveStage = String(report.effective_stage ?? stage);
   const structureWarnings = report.warnings.filter(w => w.code === 'STRUCTURE_DELTA_REVIEW');
-  const warningFields = structureWarnings.length ? { warnings: structureWarnings } : {};
+  const answers = collectItems(project, { collection: loadCollection(dir) }).flatMap(item => {
+    const answer = item.state.state === 'user' || item.state.state === 'delegated' || item.state.state === 'not_applicable'
+      ? item.state.answer : isObject(item.raw) ? item.raw : null;
+    if (!answer) return [];
+    return [{ question_id: item.id, field: item.path, by: answer.by ?? null, at: answer.at ?? null,
+      picks: asArray(isObject(answer.choice) ? answer.choice.picks : undefined).filter(isObject).map(pick => ({
+        ask: pick.ask ?? null, option_id: pick.option_id ?? null, label: isObject(pick.shown) ? pick.shown.label ?? null : null,
+      })),
+      ...(interviewStageOfGuide(item.id, item.kind === 'post', hasStageOrder(project)) === effectiveStage
+        ? { command: optionCommand(item.id, dir) } : {}) }];
+  });
+  const warningFields = { ...(structureWarnings.length ? { warnings: structureWarnings } : {}), answers };
   const jobId = readOptionalJobId(dir);
   const holes = report.holes ?? [];
 
@@ -559,7 +582,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
     ? resolveLaggingAdvance(dir, project, stage, now)
     : null;
   const isResolvableLagging = (finding: Finding): boolean =>
-    finding.code === 'STAGE_LAGGING' && laggingAdvance !== null;
+    finding.code === 'STAGE_LAGGING' && (laggingAdvance !== null || stage === 'post' && (!asArray(project.scenes).length || !asArray(project.versions).some(v => isObject(v) && v.kind === 'post')));
 
   const hasBlockingRefusal =
     holes.length > 0 ||
@@ -597,14 +620,32 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
       groups.set(kind, [...(groups.get(kind) ?? []), { version: summary.version, verdict: summary.index }]);
     }
     for (const [kind, refs] of groups) {
+      if (kind === 'post') {
+        // Match the direction writer's authoring gate, including earlier
+        // accepted verdicts that a later bounce does not itself reopen.
+        const reopens = collectReopens(project, []);
+        const closed = collectSignoffs(project, []).some(s => s.stage === 'direction-review'
+          && s.checkpoint === null && liveSignoff(reopens, s.stage, s.at))
+          || versions.some(v => v.kind === 'post' && asArray(v.verdicts).filter(isObject).some(d =>
+            d.review === 'direction-review' && d.verdict === 'accepted'
+            && liveSignoff(reopens, 'direction-review', Date.parse(String(d.at)))));
+        if (closed) {
+          const target = 'reopens[stage=direction-review]';
+          addAwait(target);
+          moves.push({ role: 'human', field: 'reopens', awaits: target,
+            command: `rig-create reopen direction-review ${shellWord(dir)} --by '<human>' --verbatim-file '<absolute-human-words-file>' --source '<reopen-act-id>'`,
+            act: 'Until create#493, an agent may type this human reopen only from Review host raw export act@4: save its unchanged nonempty value.words byte-for-byte to an absolute verbatim-file path and name actId with --source. Empty/missing words: STOP; the agent never supplies words. Do not use job fetch-act (it rejects act@4). Create cannot ingest Review reopen acts yet.' });
+          continue;
+        }
+      }
       const field = `versions[n=${n}]`;
       addAwait(field);
       const writer = kind === 'rig' ? `rig-version ${n}` : `direction write ${n}`;
       const inputs = kind === 'rig'
-        ? '--parts <dir> --rig <dir> --build <dir> --idle <dir> --config <file> --path-adapter <file> --compile-report <file> --toolchain-lock <file> --at-source <file> --at-pointer <pointer> --by <agent>'
+        ? '--parts <dir> --rig <dir> --build <dir> --idle <dir> --config <file> --path-adapter <file> --compile-report <file> --toolchain-lock <file> --run-record <run.json> --at-source <file> --at-pointer <pointer> --by <agent>'
         : '--file <direction.json> --rig <rig-version>';
       moves.push({ role: 'agent', field: 'versions', awaits: field,
-        command: `rig-create ${writer} ${inputs} ${refs.map(r => `--answers ${r.version}:${r.verdict}`).join(' ')}`,
+        command: `rig-create ${writer} ${shellWord(dir)} ${inputs.replace(/<[^>]+>/g, shellWord)} ${refs.map(r => `--answers ${r.version}:${r.verdict}`).join(' ')}`,
         act: `build the next ${kind} version with ${writer}, recording answers_feedback ${JSON.stringify(refs)}` });
     }
     if (moves.length > 0) return { schema: NEXT_SCHEMA, project_id: String(project.name ?? ''), stage, effective_stage: effectiveStage, accepted: false, refusals, ...warningFields, awaits: awaitsList, moves };
@@ -816,17 +857,11 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
           });
         } else {
           moves.push({
-            role: 'human',
+            role: 'agent',
             field: answerField,
             awaits: answerField,
-            command: null,
-            act: `review-tool act interview-picks for ${questionPath} (unanswered by record: ${questionPath}.pending_options is not recorded in project.json)`,
-            review_act: {
-              kind: 'interview-picks',
-              stage: effectiveStage,
-              question_id: item.id,
-              ...(jobId ? { job_id: jobId } : {}),
-            },
+            command: optionCommand(item.id, dir),
+            act: `draft an option-set file for ${item.id}, then register it for a Review pick`,
             unanswered_by_record: `${questionPath}.pending_options`,
           });
         }
@@ -844,25 +879,26 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
       }
     }
 
-    const needsPlanSteps =
-      (effectiveStage === 'interview' && steps.length === 0) ||
-      (effectiveStage === 'post-interview' && !steps.some(s => s.phase === 'post')) ||
-      (effectiveStage === 'rigging-interview' && !steps.some(step => stepCoveredByApproval(project, step, effectiveStage)));
+    const planIds = effectiveStage === 'rigging-interview' ? ['bones', 'meshes', 'constraints', 'motion']
+      : effectiveStage === 'post-interview' ? ['camera', 'timing'] : ['seethrough', 'assemble'];
+    const missingPlanIds = planIds.filter(id => {
+      const guide = id === 'camera' ? 'camera_depth' : id === 'timing' ? 'post_timing' : id;
+      const phase = effectiveStage === 'post-interview' ? 'post' : 'rig';
+      return !steps.some(step => step.phase === phase && (step.id === id
+        || phase === 'post' && asArray(step.rests_on).includes(guide)));
+    });
+    const needsPlanSteps = missingPlanIds.length > 0;
     if (needsPlanSteps) {
       addAwait('plan.steps');
-      if (effectiveStage === 'rigging-interview') {
-        for (const id of ['bones', 'meshes', 'constraints', 'motion']) {
-          const item = stageItems.find(item => item.id === id);
-          if (!item || item.state.state === 'silent' || (item.state.state === 'delegated' && !item.state.decided) || steps.some(step => step.id === id)) continue;
-          moves.push({
-            role: 'agent',
-            field: 'plan.steps',
-            awaits: 'plan.steps',
-            command: `rig-create plan add ${id} '${dir.replaceAll("'", "'\\''")}' --by agent --phase rig …`,
-            act: `author the ${id} plan step for approval at rigging-interview; supply order, does, produces, rests-on, bar and checkpoint-proposed`,
-            unanswered_by_record: 'plan.steps',
-          });
-        }
+      for (const [index, id] of missingPlanIds.entries()) {
+        const guideId = id === 'camera' ? 'camera_depth' : id === 'timing' ? 'post_timing' : id;
+        const item = stageItems.find(item => item.id === guideId);
+        if (!item || item.state.state === 'silent' || (item.state.state === 'delegated' && !item.state.decided)) continue;
+        const order = Math.max(0, ...steps.map(step => Number(step.order) || 0)) + index + 1;
+        moves.push({ role: 'agent', field: 'plan.steps', awaits: 'plan.steps',
+          command: `rig-create plan add ${id} ${shellWord(dir)} --by agent --phase ${effectiveStage === 'post-interview' ? 'post' : 'rig'} --order ${order} --does '<work>' --produces '<result>' --rests-on ${guideId} --bar '<acceptance bar>' --checkpoint-proposed false`,
+          act: `author the ${id} plan step for approval at ${effectiveStage}; replace the work, result and acceptance bar placeholders`,
+          unanswered_by_record: 'plan.steps' });
       }
     }
 
@@ -877,7 +913,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
         act: needsPlanSteps
           ? effectiveStage === 'rigging-interview'
             ? 'review-tool act signoff for stage rigging-interview (unanswered by record: plan.steps has no rig steps approved at rigging-interview)'
-            : `review-tool act signoff for stage ${effectiveStage} (unanswered by record: plan.steps is empty in project.json)`
+            : `review-tool act signoff for stage ${effectiveStage} (unanswered by record: ${effectiveStage === 'post-interview' ? 'plan.steps has no post steps' : steps.length === 0 ? 'plan.steps is empty' : 'plan.steps has uncovered parts guides'} in project.json)`
           : effectiveStage === 'interview'
             ? 'review-tool act signoff for stage interview on the record page with job open --plan (source-linked Review); ingest signoff interview --from-review <actId>, then advance plan-approved'
             : `review-tool act signoff for stage ${effectiveStage}`,
@@ -992,6 +1028,14 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
           : undefined;
       const hasApprovedPartsVerdict = hasApprovedPartsVerdictReceipt(dir, project, draftId);
 
+      if (effectiveStage === 'parts' && partsRoot !== undefined
+        && candidateAdvance(dir, project, 'parts-review', now, { report: 'evidence/parts-check.json', root: partsRoot }) === null) {
+        addAwait('evidence/parts-check.json');
+        moves.push({ role: 'producer', field: 'drafts', awaits: 'evidence/parts-check.json',
+          command: `rig-parts check-parts --parts ${shellWord(resolve(dir, partsRoot))} --out ${shellWord(resolve(dir, 'evidence'))}`,
+          act: 'produce and retain evidence/parts-check.json before advance parts-review' });
+      }
+
       if (effectiveStage === 'parts' && partsRoot !== undefined && existsSync(join(dir, 'evidence/parts-check.json'))) {
         const advCmd = candidateAdvance(dir, project, 'parts-review', now, {
           report: 'evidence/parts-check.json',
@@ -1026,17 +1070,15 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
         });
       }
 
-      const hasStructureFile =
-        existsSync(join(dir, 'evidence/structure.json')) ||
-        existsSync(join(dir, 'evidence/structure-decisions.json'));
-      if (draftId !== undefined && hasApprovedPartsVerdict && !hasStructureFile) {
-        addAwait('evidence/structure.json');
+      const structure = draftId === undefined ? undefined : partsStructureSnapshot(dir, project, draftId);
+      if (draftId !== undefined && hasApprovedPartsVerdict && structure !== undefined && !structure.valid) {
+        addAwait(structure.path);
         moves.push({
           role: 'agent',
           field: `drafts[${draftId}]`,
-          awaits: 'evidence/structure.json',
-          command: `rig-create structure-snapshot --draft ${draftId} --out evidence/structure.json`,
-          act: `write structure-snapshot for drafts[${draftId}] to evidence/structure.json`,
+          awaits: structure.path,
+          command: `rig-create structure-snapshot ${shellWord(dir)} --draft ${shellWord(draftId)} --out ${shellWord(structure.path)}`,
+          act: `write structure-snapshot for drafts[${draftId}] to ${structure.path}`,
         });
       }
 
@@ -1085,7 +1127,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
           awaits: signoffAwait,
           command: null,
           act: hasApprovedPartsVerdict
-            ? 'review-tool act signoff for stage parts-review'
+            ? `review-tool act signoff for stage parts-review; after structure-snapshot, ingest rig-create signoff parts-review ${shellWord(dir)} --draft ${shellWord(draftId!)} --structure-file ${shellWord(structure!.path)} --from-review '<actId>'`
             : `review-tool act signoff for stage parts-review (unanswered by record: review_acts[kind=parts-verdict,draft_id=${draftId ?? 'unknown'}] is absent)`,
           review_act: {
             kind: 'signoff',
@@ -1095,7 +1137,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
           },
           ...(!hasApprovedPartsVerdict
             ? {
-                unanswered_by_record: `review_acts[kind=parts-verdict,draft_id=${draftId ?? 'unknown'}], evidence/structure.json`,
+                unanswered_by_record: `review_acts[kind=parts-verdict,draft_id=${draftId ?? 'unknown'}], ${structure?.path ?? 'structure snapshot'}`,
               }
             : {}),
         });
@@ -1323,7 +1365,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
       );
       const nextPostN = postN ?? maxVersionN + 1;
 
-      if (effectiveStage === 'post') {
+      if (effectiveStage === 'post' && postN !== null && scenes.length > 0) {
         const advCmd = candidateAdvance(dir, project, 'direction-review', now);
         if (advCmd !== null) {
           moves.push({
@@ -1336,9 +1378,27 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
         }
       }
 
-      if (scenes.length === 0) {
-        addAwait('scenes[n=1]');
+      if (postN === null) {
+        const rig = versions.filter(v => v.kind === 'rig').at(-1);
+        const rigN = typeof rig?.n === 'number' ? String(rig.n) : '<rig-version>';
+        const currentScene = sceneCurrentAt(dir, project, now);
+        if (!isObject(project.direction_contract)) {
+          addAwait('direction_contract');
+          moves.push({ role: 'agent', field: 'direction_contract', awaits: 'direction_contract',
+            command: `rig-create direction --adopt ${shellWord(dir)}`, act: 'adopt direction before authoring the post' });
+        } else if (currentScene === undefined) {
+          addAwait('scenes[n=1]');
+          moves.push({ role: 'agent', field: 'scenes', awaits: 'scenes[n=1]',
+            command: `rig-create scene write ${shellWord(dir)} --rig ${shellWord(rigN)} --background '<background.png>' --citations-file '<scene-citations.json>'`,
+            act: 'author scene inputs matching the current post_composition Review choice, then write the scene' });
+        } else {
+          addAwait(`versions[n=${nextPostN}]`);
+          moves.push({ role: 'agent', field: 'versions', awaits: `versions[n=${nextPostN}]`,
+            command: `rig-create direction write ${nextPostN} ${shellWord(dir)} --file '<direction.json>' --rig ${shellWord(rigN)}`,
+            act: 'author a direction document binding the current scene, then record the post version' });
+        }
       }
+      if (scenes.length === 0) addAwait('scenes[n=1]');
       if (postN === null) {
         addAwait(`versions[n=${nextPostN}]`);
         const verdictAwait = `versions[n=${nextPostN}].verdicts[review=direction-review]`;

package/src/record-input.ts

@@ -8,7 +8,7 @@ export function readVerbatim(file: string): string {
   try {
     bytes = readFileSync(file === '-' ? 0 : file);
   } catch (error) {
-    refuse('VERBATIM_UNREADABLE', `${file}: ${error instanceof Error ? error.message : String(error)}`);
+    refuse('VERBATIM_UNREADABLE', `${file}: ${error instanceof Error ? error.message : String(error)}; --verbatim-file paths resolve against the current working directory, not the project folder; supply an absolute path or run from the folder containing the file`);
   }
   try {
     return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);

package/src/reopen.ts

@@ -95,7 +95,7 @@ export function liveSignoff(reopens: readonly Reopen[], stage: string, at: numbe
 export const REOPEN_HELP = `reopen:
   <stage> [<project dir>]  record a human backward move and set project.stage
   --by <who>              human signer (agent is refused)
-  --verbatim-file <file>  unchanged UTF-8 words, or - for stdin (default)
+  --verbatim-file <file>  unchanged UTF-8 words; relative to the current working directory, not the project; or - for stdin (default)
   --source <text>         optional origin of the words, separate from verbatim
   --json                  print the reopen record
   The clock supplies at; sign-offs and versions remain history.`;

package/src/review-package.ts

@@ -1,4 +1,5 @@
 import { recordedPartsVerdict, recordedPartsFinding } from './parts-verdict-record.ts';
+import reviewPackage from '@rig-c/review/package.json';
 import { configInputReferences, configInputsLegacy, DIRECTORY_INPUT_RECEIPT, plateReceiptSpec, receiptSpec, type ConfigInputsWarning } from './config-inputs.ts';
 import { DirectionError, objects as directionObjects, readDirection } from './direction.ts';
 /** Frozen producer inputs in review's fixed discovery layout (create#38). */
@@ -40,7 +41,7 @@ function checkBuildIdentity(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'war
     if (finding.code === 'PARTS_VERDICT_FILE_LEGACY') {
       if (!ctx.warnings.some(existing => existing.code === finding.code && existing.path === finding.path)) ctx.warnings.push(finding);
     } else findings.push({ code: 'REVIEW_PACKAGE_PARTS_UNREAD', path: `${path}.files[out/parts.json]`,
-      message: `${path}.files[out/parts.json]: accepted parts receipt is unavailable (${finding.code}); restore its recorded API response and selected draft before packaging this version` });
+      message: `${path}.files[out/parts.json]: accepted parts receipt cannot be read (${finding.code}: ${finding.message}); compare the Review version that recorded the act (not carried by API act receipts) with the current @rig-c/review ${reviewPackage.version} reader. For an act parsing failure, register with a Review version that parses that act, or wait until support lands; preserve the retained bytes. For missing or changed evidence, restore its recorded API response and selected draft before packaging this version` });
     return;
   }
   recordedPartsVerdict(ctx.dir, ctx.project, approval.draft_id, approval.evidence, { requireAvailable: false });

package/src/scene-writers.ts

@@ -12,7 +12,8 @@ import type { JsonObject } from './templates.ts';
 
 export const SCENE_HELP = `scene write --rig <R> --background <path> [--foreground <path>]
   [--background-rect x,y,w,h] [--foreground-rect x,y,w,h]
-  --citations-file <file> [<dir>]
+  --citations-file <retained project-relative JSON> [<dir>]
+  Retain citations inside the project, for example evidence/scene-src/citations.json; absolute paths are refused.
   Citations are a role map {background: citation, foreground?: citation}.
   Each citation names post_composition, asks:["post_composition"], and quote or delegated:true.
   Paths and rects must match the current ingested post_composition choice.