rig-create 1.0.1 → 1.0.4

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,10 @@ import {
   STAGE_VALUES,
   stageIndex,
   stageOfStep,
-  stepCoveredByApproval,
 } from './stages.ts';
 import type { Json, JsonObject } from './templates.ts';
+import { sceneCurrentAt, sceneRig, SceneError } from './scene.ts';
+import { resolveAgentCitationSpec } from './scene-authority.ts';
 
 export const NEXT_SCHEMA = 'rig-create/next@1';
 
@@ -109,6 +111,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 +195,81 @@ 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>'`;
+}
+
+/** The person acts in Review; the agent only hosts and ingests its exported act. */
+function reviewCommands(dir: string, project: JsonObject, move: NextMove): NextMove[] {
+  const act = move.review_act;
+  if (move.role !== 'human' || move.unanswered_by_record || move.field === 'pauses' || !act) return [move];
+  let selector: string;
+  let writer: string;
+  if (act.kind === 'interview-picks' && act.question_id) {
+    selector = `--question ${shellWord(act.question_id)}`;
+    writer = `interview-answer ${shellWord(act.question_id)}`;
+  } else if (act.kind === 'signoff' && ['interview', 'plan-approved', 'rigging-interview', 'post-interview', 'direction-review'].includes(act.stage)) {
+    selector = '--plan';
+    writer = `signoff ${act.stage}`;
+  } else if (act.kind === 'parts-verdict' && act.draft_id) {
+    selector = `--draft ${shellWord(act.draft_id)}`;
+    writer = 'parts-review';
+  } else if (act.kind === 'signoff' && act.stage === 'parts-review' && act.draft_id) {
+    selector = `--draft ${shellWord(act.draft_id)}`;
+    const structure = partsStructureSnapshot(dir, project, act.draft_id);
+    writer = `signoff parts-review --draft ${shellWord(act.draft_id)} --structure-file ${shellWord(structure.path)}`;
+  } else if (act.kind === 'signoff' && act.stage === 'rig-review' && act.version_id) {
+    selector = `--rig ${shellWord(act.version_id.slice(1))}`;
+    writer = 'signoff rig-review';
+  } else if (['rig-review', 'direction-review'].includes(act.stage) && act.kind === 'review-verdict' && act.version_id) {
+    const n = act.version_id.slice(1);
+    selector = `--rig ${shellWord(n)}`;
+    writer = `review ${shellWord(n)}`;
+  } else return [move];
+  const agent = (command: string, description: string): NextMove => ({
+    role: 'agent', field: move.field, awaits: move.awaits, command, act: description,
+  });
+  const root = shellWord(dir);
+  return [
+    agent(`rig-create job open ${root} ${selector} --reviewer '<reviewer>' --role owner`, 'host this Review page; keep the host running in a separate terminal until job close'),
+    move,
+    agent(`rig-create job acts ${root} --json`, `after the person submits in Review, list exported acts and use the matching actId below${act.stage === 'parts-review' ? '; run its reported preconditions before ingestion (parts-review signoff includes structure-snapshot)' : ''}`),
+    agent(`rig-create ${writer} ${root} --from-review '<actId>'`, 'ingest the matching exported Review act; never supply the human answer or words'),
+    agent(`rig-create job close ${root}`, 'after successful ingestion, close this job before opening the next Review page'),
+  ];
+}
+
+function sceneWriteCommand(dir: string, project: JsonObject, rigN: string): string {
+  let flags = ` --background '<background.png>'`;
+  const item = collectItems(project, { collection: loadCollection(dir) }).find(item => item.id === 'post_composition');
+  if (item && (item.state.state === 'user' || item.state.state === 'delegated')) {
+    const answer = item.state.answer;
+    const citation = { guide: 'post_composition', asks: ['post_composition'],
+      ...(item.state.state === 'delegated' ? { delegated: true } : { quote: answer.verbatim! }) };
+    try {
+      const spec = resolveAgentCitationSpec(dir, project, citation);
+      const stage = sceneRig(dir, project, Number(rigN)).stage;
+      for (const role of ['background', 'foreground'] as const) {
+        const plate = spec[role];
+        if (!plate) continue;
+        if (role === 'foreground') flags += ` --foreground '<foreground.png>'`;
+        const { x, y, width, height } = plate.rect;
+        if (x !== stage.x || y !== stage.y || width !== stage.width || height !== stage.height) {
+          flags += ` --${role}-rect ${shellWord([x, y, width, height].join(','))}`;
+        }
+      }
+    } catch (error) {
+      if (!(error instanceof SceneError)) throw error;
+      // The scene writer reports the existing named refusal for an unresolved choice.
+    }
+  }
+  return `rig-create scene write ${shellWord(dir)} --rig ${shellWord(rigN)}${flags} --citations-file '<scene-citations.json>'`;
+}
+
 function candidateAdvance(
   dir: string,
   project: JsonObject,
@@ -264,8 +343,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 +406,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 +441,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 +553,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 +563,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 +604,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 +623,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 +650,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 +688,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 +925,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,28 +947,33 @@ 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', 'composition'] : ['seethrough', 'assemble'];
+    const missingPlanIds = planIds.filter(id => {
+      const guide = id === 'camera' ? 'camera_depth' : id === 'timing' ? 'post_timing' : id === 'composition' ? 'post_composition' : 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 === 'composition' ? 'post_composition' : 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' });
       }
     }
 
+    const missingStepNames = missingPlanIds.length === planIds.length ? '' : `${missingPlanIds.join(', ')} `;
+    const missingStepKind = effectiveStage === 'post-interview' ? 'post' : 'rig';
+    const missingPlanReason = `plan.steps has no ${missingStepNames}${missingStepKind} step${missingPlanIds.length === 1 ? '' : 's'}`;
+
     const signoffAwait = `signoffs[stage=${effectiveStage}]`;
     if (!hasLiveStageSignoff(effectiveStage) && !recordedLapseTargets.has(signoffAwait)) {
       addAwait(signoffAwait);
@@ -876,10 +984,10 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
         command: null,
         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 rigging-interview (unanswered by record: ${missingPlanReason} approved at rigging-interview)`
+            : `review-tool act signoff for stage ${effectiveStage} (unanswered by record: ${effectiveStage === 'post-interview' ? missingPlanReason : 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 interview on the record page with job open --plan; ingest signoff interview --from-review <actId>, then advance plan-approved'
             : `review-tool act signoff for stage ${effectiveStage}`,
         review_act: {
           kind: 'signoff',
@@ -992,6 +1100,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 +1142,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 +1199,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 +1209,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 +1437,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 +1450,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: sceneWriteCommand(dir, project, rigN),
+            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]`;
@@ -1372,7 +1504,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
             field: `versions[v${postN}].verdicts`,
             awaits: verdictAwait,
             command: null,
-            act: `review-tool act review-verdict for versions[v${postN}] (direction-review) on the post page: job open --rig ${postN}; ingest with review ${postN} --from-review <actId>; then request record-page sign-off with job open --plan (source-linked Review)`,
+            act: `review-tool act review-verdict for versions[v${postN}] (direction-review) on the post page: job open --rig ${postN}; ingest with review ${postN} --from-review <actId>; then request record-page sign-off with job open --plan`,
             review_act: {
               kind: 'review-verdict',
               stage: 'direction-review',
@@ -1394,8 +1526,8 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
           command: null,
           act:
             postN === null
-              ? `after recording the current post and accepted direction verdict, request review-tool act signoff for direction-review on the record page with job open --plan (source-linked Review; unanswered by record: ${scenes.length === 0 ? 'scenes[n=1] and ' : ''}versions[n=${nextPostN}] are not recorded in project.json)`
-              : `after ingesting the accepted direction-review verdict for v${postN}, request review-tool act signoff on the record page with job open --plan (source-linked Review), ingest signoff direction-review --from-review <actId>, then advance accepted`,
+              ? `after recording the current post and accepted direction verdict, request review-tool act signoff for direction-review on the record page with job open --plan (unanswered by record: ${scenes.length === 0 ? 'scenes[n=1] and ' : ''}versions[n=${nextPostN}] are not recorded in project.json)`
+              : `after ingesting the accepted direction-review verdict for v${postN}, request review-tool act signoff on the record page with job open --plan, ingest signoff direction-review --from-review <actId>, then advance accepted`,
           review_act: {
             kind: 'signoff',
             stage: 'direction-review',
@@ -1443,6 +1575,12 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
     });
   }
 
+  const runnableMoves = moves.flatMap(move => {
+    if (move.review_act?.stage === 'direction-review' && move.review_act.kind === 'signoff'
+      && moves.some(other => other.review_act?.stage === 'direction-review' && other.review_act.kind === 'review-verdict')) return [move];
+    return reviewCommands(dir, project, move);
+  });
+
   return {
     schema: NEXT_SCHEMA,
     project_id: String(project.name ?? ''),
@@ -1452,7 +1590,7 @@ export function nextProject(projectDirArg: string, now: number = Date.now()): Ne
     refusals,
     ...warningFields,
     awaits: awaitsList,
-    moves,
+    moves: runnableMoves,
   };
 }
 

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.

package/src/scene.ts

@@ -9,6 +9,7 @@ import { collectReopens, liveSignoff } from './reopen.ts';
 import { humanReviewVerdicts, latestAccepted, readVersions } from './review.ts';
 import { SCENE_CHOICE_MISMATCH, SCENE_CHOICE_MISSING, sceneAuthor, validateAgentSceneAuthority } from './scene-authority.ts';
 import { reviewPackageHash } from './signoff-target.ts';
+import { samePublicationReviewPair } from './signoff-pair.ts';
 import type { Json, JsonObject } from './templates.ts';
 
 export { SCENE_CHOICE_MISMATCH, SCENE_CHOICE_MISSING, sceneAuthor };
@@ -197,7 +198,8 @@ function validateSceneAcceptance(project: JsonObject, rig: JsonObject): JsonObje
   const signature = collectSignoffs(project, []).find(value => value.stage === identity.stage && value.checkpoint === identity.checkpoint && value.record.at === identity.at)?.record;
   const match = /^versions\[(\d+)\]\.verdicts\[(\d+)\]$/.exec(String(acceptance.verdict));
   const verdict = match && Number(match[1]) === index ? humanReviewVerdicts(version.verdicts, 'rig-review').find(value => value.index === Number(match[2]) && value.record.verdict === 'accepted') : undefined;
-  if (!verdict || !Number.isFinite(Date.parse(String(verdict.record.at))) || Date.parse(String(verdict.record.at)) > Date.parse(String(identity.at))) sceneFail('SCENE_RIG_STALE', 'scene.rig.acceptance.verdict', 'the cited rig must have been human-accepted before this signoff');
+  if (!verdict || !Number.isFinite(Date.parse(String(verdict.record.at))) || Date.parse(String(verdict.record.at)) > Date.parse(String(identity.at))
+    && (!signature || !samePublicationReviewPair(project, signature, version, verdict.index))) sceneFail('SCENE_RIG_STALE', 'scene.rig.acceptance.verdict', 'the cited rig needs human acceptance before signing or a same-publication, same-version human accepted pair');
   const pkg = version.review_package;
   const target = { version: version.n!, verdict: acceptance.verdict!, review_package: { path: `versions[${index}].review_package`, sha256: isObject(pkg) ? reviewPackageHash(pkg) : '' } };
   if (!signature || !equal(signature.target, target) || !equal(acceptance.review_package, target.review_package)) sceneFail('SCENE_ACCEPTANCE_STALE', 'scene.rig.acceptance.review_package', 'restore the recorded acceptance target and its matching package sha256');

package/src/signoff-pair.ts

@@ -0,0 +1,60 @@
+/** Review act order is immaterial only within one human-reviewed publication. */
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, isObject, type Finding } from './check.ts';
+import { decodeReviewAct, isRecordDirectionSignoff, reviewActFindings, reviewActSignoff, SIGNOFF_TARGET_KINDS, signoffActVersion } from './review-act.ts';
+import type { JsonObject } from './templates.ts';
+
+export const SIGNOFF_PAIR_SINCE = '2026-11-13T00:00:00Z';
+
+/** Trust decoded immutable acts and their unique ledger mappings, never copied identity fields. */
+export function samePublicationReviewPair(project: JsonObject, signoff: JsonObject, version: JsonObject, verdictIndex: number): boolean {
+  if (reviewActFindings(project).length) return false;
+  try {
+    const receipts = asArray(project.review_acts).filter(isObject);
+    const signatures = receipts.filter(entry => entry.kind === 'signoff' && typeof entry.bytes === 'string'
+      && reviewActSignoff(decodeReviewAct(entry.bytes, 'signoff')).source === signoff.source);
+    const verdicts = receipts.filter(entry => entry.version === version.n && entry.verdict === verdictIndex);
+    if (signatures.length !== 1 || verdicts.length !== 1) return false;
+    const signed = decodeReviewAct(String(signatures[0]!.bytes), 'signoff');
+    // The validated compact record receipt binds the post, record hash and exact verdict;
+    // record-source acts deliberately have no model selector.
+    const signedVersion = isRecordDirectionSignoff(signed) ? Number(signatures[0]!.target_version) : signoffActVersion(signed);
+    const accepted = decodeReviewAct(String(verdicts[0]!.bytes));
+    const selector = accepted.source.selector;
+    const verdict = asArray(version.verdicts)[verdictIndex];
+    return isObject(verdict) && verdict.verdict === 'accepted'
+      && Object.entries(reviewActSignoff(signed)).every(([key, value]) => isDeepStrictEqual(signoff[key], value))
+      && signed.value.stage === signoff.stage && accepted.value.stage === signoff.stage
+      && signedVersion === version.n && selector !== null && 'version' in selector && selector.version === version.n
+      && selector.kind === SIGNOFF_TARGET_KINDS[String(signoff.stage)]
+      && signed.jobId === accepted.jobId && signed.publicationId === accepted.publicationId;
+  } catch { return false; }
+}
+
+/** A newly ingested verdict must not complete an invalid pair, including a historical signature. */
+export function ingestedVerdictPairFinding(project: JsonObject, version: number, verdict: number): Finding | undefined {
+  const index = asArray(project.versions).findIndex(raw => isObject(raw) && raw.n === version);
+  for (const [i, signoff] of asArray(project.signoffs).entries()) {
+    if (!isObject(signoff) || !isObject(signoff.target) || signoff.target.version !== version
+      || signoff.target.verdict !== `versions[${index}].verdicts[${verdict}]`) continue;
+    const finding = signoffPairFinding(project, signoff, `signoffs[${i}]`, true);
+    if (finding) return finding;
+  }
+}
+
+/** Check gates history by the signature's date; ingest always enforces the current contract. */
+export function signoffPairFinding(project: JsonObject, signoff: JsonObject, path: string, ingest = false): Finding | undefined {
+  if (!(String(signoff.stage) in SIGNOFF_TARGET_KINDS) || !isObject(signoff.target)) return;
+  const target = signoff.target;
+  const match = /^versions\[(\d+)\]\.verdicts\[(\d+)\]$/.exec(String(target.verdict));
+  const version = match ? asArray(project.versions)[Number(match[1])] : undefined;
+  if (!match || !isObject(version) || version.n !== target.version) return;
+  const verdictIndex = Number(match[2]);
+  const verdict = asArray(version.verdicts)[verdictIndex];
+  if (!isObject(verdict) || !(Date.parse(String(verdict.at)) > Date.parse(String(signoff.at)))
+    || samePublicationReviewPair(project, signoff, version, verdictIndex)) return;
+  const legacy = !ingest && Date.parse(String(signoff.at)) < Date.parse(SIGNOFF_PAIR_SINCE);
+  const at = `${path}.target.verdict`;
+  return { code: `SIGNOFF_PAIR_MISMATCH${legacy ? '_LEGACY' : ''}`, path: at,
+    message: `${at}: the verdict follows this signoff without a same-publication, same-version human accepted pair; accept the intended version and sign it again in Review, then ingest both acts` };
+}

package/src/signoff-target.ts

@@ -10,6 +10,7 @@ import { checkReviewPackages } from './review-package.ts';
 import { refuse } from './refusal.ts';
 import { SIGNOFF_TARGET_KINDS } from './review-act.ts';
 import { sorted } from './step-hash.ts';
+import { signoffPairFinding } from './signoff-pair.ts';
 import type { Json, JsonObject } from './templates.ts';
 
 export const SIGNOFF_TARGET_SINCE = '2026-11-06T00:00:00Z';
@@ -75,7 +76,11 @@ export function checkSignoffTarget(dir: string, project: JsonObject, signoff: Js
       if (!isDeepStrictEqual(target, expected)) throw Error(expected.outputs ? 'outputs changed since signing' : stage === 'rig-review' ? 'review_package changed since signing' : expected.direction ? 'direction changed since signing' : 'post config changed since signing');
     } catch (error) { reason = error instanceof Error ? error.message : String(error); }
   }
-  if (!reason) return;
+  if (!reason) {
+    const pair = signoffPairFinding(project, signoff, path);
+    if (pair) (pair.code.endsWith('_LEGACY') ? warnings : refusals).push(pair);
+    return;
+  }
   const legacy = Date.parse(String(signoff.at)) < Date.parse(SIGNOFF_TARGET_SINCE);
   const code = `SIGNOFF_TARGET_${missing ? 'MISSING' : 'STALE'}${legacy ? '_LEGACY' : ''}`;
   const at = `${path}.target`;
@@ -120,8 +125,6 @@ export function selectSignoffTarget(dir: string, project: JsonObject, stage: str
     if (mask) refuse(mask.code, mask.message);
     if (ctx.refusals.length || ctx.warnings.some(w => w.code === 'REVIEW_PACKAGE_MISSING')) fail('review package is missing or differs from its recorded binding');
   }
-  const errors: Finding[] = [];
-  checkSignoffTarget(dir, project, { stage, target, at: SIGNOFF_TARGET_SINCE }, `signoffs[${asArray(project.signoffs).length}]`, errors, []);
-  if (errors[0]) refuse(errors[0].code, errors[0].message);
+  // The writer validates the actual dated signature after attaching its immutable receipt.
   return target;
 }