rig-create 0.0.0-stage → 1.0.0

package/src/stages.ts

@@ -0,0 +1,148 @@
+import type { JsonObject } from './templates.ts';
+
+/**
+ * The project's stages, in order, and how each one is left — the one place the
+ * order is written (docs/PROJECT.md § Stages). `interview --check` reads it;
+ * the review order and the post hand-off (src/review.ts) read `REVIEW_ACCEPTS`
+ * below rather than naming stages themselves.
+ *
+ * `closed_by`:
+ * - `signoff`: the stage ends only on a human `signoffs[]` entry naming it
+ *   with `checkpoint: null`. A project whose `stage` is past such a stage
+ *   without that entry is refused (`STAGE_UNSIGNED`).
+ * - `bar`: the stage ends when the last plan step it runs meets its bar; no
+ *   stage-level sign-off, but a step whose checkpoint is on needs a
+ *   `{ stage, checkpoint: <step id> }` entry before the next step runs
+ *   (`CHECKPOINT_UNSIGNED`).
+ * - `none`: terminal.
+ *
+ * The rig phase runs in two `bar` stages: `parts` runs the steps that make the
+ * parts (`steps`), `rigging` runs the rest. A phase's stage without `steps`
+ * runs every step of the phase the other stages do not name.
+ */
+export interface StageSpec {
+  readonly id: string;
+  readonly closed_by: 'signoff' | 'bar' | 'none';
+  /** For a `bar` stage: the plan phase whose steps run in it. */
+  readonly phase?: 'rig' | 'post';
+  /** For a `bar` stage that runs only some of its phase's steps: their ids. */
+  readonly steps?: readonly string[];
+}
+
+export const STAGES: readonly StageSpec[] = [
+  { id: 'interview', closed_by: 'signoff' },
+  { id: 'plan-approved', closed_by: 'signoff' },
+  { id: 'parts', closed_by: 'bar', phase: 'rig', steps: ['seethrough', 'assemble'] },
+  { id: 'parts-review', closed_by: 'signoff' },
+  { id: 'rigging-interview', closed_by: 'signoff' },
+  { id: 'rigging', closed_by: 'bar', phase: 'rig' },
+  { id: 'rig-review', closed_by: 'signoff' },
+  { id: 'post-interview', closed_by: 'signoff' },
+  { id: 'post', closed_by: 'bar', phase: 'post' },
+  { id: 'direction-review', closed_by: 'signoff' },
+  { id: 'accepted', closed_by: 'none' },
+] as const;
+
+/** Stopped by a human sign-off; outside the order. Resuming starts at the first stage whose sign-off is missing. */
+export const PAUSED_STAGE = 'paused';
+
+/** What a record's `stage_values` is expected to hold: the order, then `paused`. */
+export const STAGE_VALUES: readonly string[] = [...STAGES.map((s) => s.id), PAUSED_STAGE];
+
+/**
+ * The stages skipped when every post item is answered not applicable
+ * (PROJECT.md § When post is not passed): the project moves from
+ * `post-interview` straight to `accepted`.
+ */
+export const SKIPPED_WHEN_NO_POST: readonly string[] = ['post', 'direction-review'];
+
+/** Default new-order phase approvals; parts steps and legacy records use approvalStageOfStep. */
+export const PHASE_APPROVED_BY: Readonly<Record<'rig' | 'post', string>> = {
+  rig: 'rigging-interview',
+  post: 'post-interview',
+};
+
+/** The stage a step runs in (a `bar` stage of its phase), i.e. the `stage` its checkpoint sign-off names. */
+export function stageOfStep(phase: 'rig' | 'post', id: string): string {
+  const ofPhase = STAGES.filter((s) => s.phase === phase);
+  const found = ofPhase.find((s) => s.steps?.includes(id) === true) ?? ofPhase.find((s) => s.steps === undefined);
+  if (found === undefined) throw new Error(`no stage runs ${phase} step ${id}`);
+  return found.id;
+}
+
+/** The sign-off a person gives on the assembled parts before any rig is built (rig-c/create#48). */
+export const PARTS_REVIEW = 'parts-review';
+
+/**
+ * When `parts` and `parts-review` entered the order. A project whose first
+ * `plan-approved` sign-off is dated before this passed that point when the two
+ * stages did not exist: it is reported (`PARTS_REVIEW_PREDATES_STAGE`, a
+ * warning), not refused, and no sign-off is assumed for it.
+ */
+export const PARTS_REVIEW_SINCE = '2026-11-04T00:00:00Z';
+
+/** History entries before this date (or without a readable date) retain free-form bounces with a warning. */
+export const AGENT_BOUNCE_SINCE = '2026-11-05T00:00:00Z';
+
+export function stageIndex(id: string): number {
+  return STAGES.findIndex((s) => s.id === id);
+}
+
+/**
+ * The two reviews and the version kind each one accepts (PROJECT.md § Stages):
+ * `rig-review` accepts one `kind: "rig"` version on its still frame, and post
+ * work runs only on it; `direction-review` accepts one `kind: "post"` version.
+ * A verdict's `review` names one of these keys.
+ */
+export const REVIEW_ACCEPTS: Readonly<Record<'rig-review' | 'direction-review', 'rig' | 'post'>> = {
+  'rig-review': 'rig',
+  'direction-review': 'post',
+};
+
+/** The review that accepts the rig version post work runs on. */
+export const RIG_REVIEW = 'rig-review' satisfies keyof typeof REVIEW_ACCEPTS;
+
+
+export const STAGE_ORDER_SPEC = 'rig-create/stage-order@1';
+export const CHOICE_ORDER_SPEC = 'rig-create/stage-order@2';
+export const PARTS_STEPS: readonly string[] = ['seethrough', 'assemble'];
+export const GUIDE_INTERVIEW: Readonly<Record<string, string>> = {
+  rig_type: 'interview', reference: 'interview', seethrough: 'interview', assemble: 'interview',
+  bones: 'rigging-interview', meshes: 'rigging-interview', constraints: 'rigging-interview', motion: 'rigging-interview',
+};
+
+/** Adoption is explicit, independent of dates and answer representation. */
+export function hasStageOrder(project: JsonObject): boolean {
+  const interview = project.interview;
+  if (interview === null || typeof interview !== 'object' || Array.isArray(interview)) return false;
+  const order = interview.order;
+  return order !== null && typeof order === 'object' && !Array.isArray(order) && (order.spec === STAGE_ORDER_SPEC || order.spec === CHOICE_ORDER_SPEC);
+}
+
+/** Legacy phase=rig approvals retain their original all-step meaning. */
+export function approvalStageOfStep(phase: 'rig' | 'post', id: string, newOrder = false): string {
+  if (phase === 'post') return PHASE_APPROVED_BY.post;
+  if (!newOrder || PARTS_STEPS.includes(id)) return 'plan-approved';
+  return PHASE_APPROVED_BY.rig;
+}
+
+/** Whether a step belongs to the plan published for this approval stage. */
+export function stepCoveredByApproval(project: JsonObject, step: JsonObject, stage: string | null): boolean {
+  const phase = stage === 'post-interview' ? 'post' : 'rig';
+  return step.phase === phase && approvalStageOfStep(phase, String(step.id), hasStageOrder(project) || stage === 'rigging-interview') === stage;
+}
+
+export function interviewStageOfGuide(id: string, post = false, newOrder = false): string {
+  if (post) return 'post-interview';
+  return newOrder ? GUIDE_INTERVIEW[id] ?? 'rigging-interview' : 'interview';
+}
+
+/** Answers use interview membership, including framing ids that are not executable steps. */
+export function approvalStageOfGuide(id: string, post = false, newOrder = false): string {
+  const interview = interviewStageOfGuide(id, post, newOrder);
+  return interview === 'interview' ? 'plan-approved' : interview;
+}
+
+/** Frozen order used by projects that have not adopted the split interview. */
+export const LEGACY_STAGES = STAGES.filter(s => s.id !== 'rigging-interview');
+export const LEGACY_STAGE_VALUES: readonly string[] = [...LEGACY_STAGES.map(s => s.id), PAUSED_STAGE];

package/src/step-hash.ts

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+
+import type { Json, JsonObject } from './templates.ts';
+
+const FIELDS = ['id', 'phase', 'order', 'does', 'produces', 'rests_on', 'bar', 'checkpoint_proposed', 'checkpoint'] as const;
+
+export function sorted(value: Json): Json {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+  }
+  return value;
+}
+
+/** SHA-256 of the present approval fields, recursively key-sorted JSON, encoded as UTF-8. */
+export function stepHash(step: JsonObject): string {
+  const fields = Object.fromEntries(FIELDS.filter((key) => key in step).map((key) => [key, step[key]]));
+  return createHash('sha256').update(JSON.stringify(sorted(fields))).digest('hex');
+}

package/src/structure-snapshot.ts

@@ -0,0 +1,109 @@
+/**
+ * The parts-review structure-decisions snapshot, written from the bound draft
+ * (rig-c/create#229). The parts verdict names no per-declaration approval: an
+ * approved verdict approves the reviewed draft, so the snapshot carries every
+ * `meshes.<part>` declaration of that draft's config, copied exactly. The
+ * writer measures and derives no mesh.
+ */
+import { lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { asArray, isObject, type Finding } from './check.ts';
+import { readProject } from './feedback.ts';
+import { IGNORED_DIRS } from './init.ts';
+import { recordedPartsVerdict } from './parts-verdict-record.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { retainedJson, STRUCTURE_SCHEMA, structurePathIsIgnored, validateStructureSnapshot } from './structure.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const STRUCTURE_SNAPSHOT_HELP = `structure-snapshot:
+  [<project dir>] --draft <id> --out <path>
+  Write ${STRUCTURE_SCHEMA} from the recorded draft <id>: one entry per
+  meshes.<part> of its config, copied exactly, or entries:[] without meshes.
+  The latest recorded parts-review API receipt for --draft must approve it.
+  --out is project-relative and outside ignored roots, for example evidence/.
+  Writes only --out; an existing --out with the same bytes is left as it is.
+  Pass the same --draft and --out to signoff parts-review --structure-file.`;
+
+const pointer = (part: string): string => `/meshes/${part.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+
+/** Where --out may be written, refusing before any byte is: a literal path under the project, outside ignored roots. */
+function outTarget(dir: string, out: string): string {
+  const at = `structure-snapshot --out ${out}`;
+  const segments = out.split('/');
+  if (isAbsolute(out) || out.includes('\\') || segments.some(s => s === '' || s === '.' || s === '..')) {
+    refuse('STRUCTURE_SNAPSHOT_OUT_INVALID', `${at}: expected a literal project-relative POSIX path; name a file under the project, for example evidence/structure-decisions.json`);
+  }
+  const root = realpathSync(dir);
+  // The longest existing prefix: it carries the links the write would follow.
+  let existing = '';
+  for (const segment of segments) {
+    const next = existing === '' ? segment : `${existing}/${segment}`;
+    try { lstatSync(join(dir, next)); } catch { break; }
+    existing = next;
+  }
+  if (existing !== '') {
+    let real: string;
+    try { real = realpathSync(join(dir, existing)); } catch { refuse('STRUCTURE_SNAPSHOT_OUT_INVALID', `${at}: ${existing} is a link that leads nowhere; name a file under the project`); }
+    const rel = relative(root, real);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) refuse('STRUCTURE_SNAPSHOT_OUT_INVALID', `${at}: ${existing} leads out of the project; name a file under the project`);
+    if (existing !== out && !lstatSync(real).isDirectory()) refuse('STRUCTURE_SNAPSHOT_OUT_INVALID', `${at}: ${existing} is not a folder; name a file under a folder of the project`);
+  }
+  const ignored: readonly string[] = [...IGNORED_DIRS, 'node_modules', '.git'];
+  if (ignored.includes(segments[0] as string) || (existing !== '' && structurePathIsIgnored(dir, existing))) {
+    refuse('STRUCTURE_SNAPSHOT_OUT_IGNORED', `${at}: the snapshot must survive a clone, and ${out} is under an ignored root; write it outside ignored roots, for example evidence/`);
+  }
+  const file = resolve(dir, out);
+  if (existing === out && !lstatSync(file).isFile()) refuse('STRUCTURE_SNAPSHOT_OUT_INVALID', `${at}: ${out} exists and is not a regular file; name a new file or remove that entry`);
+  return file;
+}
+
+export function structureSnapshotCommand(args: string[]): { stdout: string; exit: number } {
+  if (args.some(arg => arg === '--verdict' || arg.startsWith('--verdict='))) refuse('PARTS_VERDICT_FILE_ROUTE_REMOVED', 'project.json.drafts: --verdict was removed; record the API response with parts-review and select it with --draft', USAGE_EXIT);
+  const opts: Record<string, string> = {};
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (['--draft', '--out'].includes(arg)) {
+      const value = args[++i];
+      if (arg in opts || value === undefined || value === '' || value.startsWith('--')) refuse('STRUCTURE_SNAPSHOT_USAGE', `structure-snapshot: ${arg} needs one non-empty value; ${STRUCTURE_SNAPSHOT_HELP}`, USAGE_EXIT);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) refuse('STRUCTURE_SNAPSHOT_USAGE', `structure-snapshot: unsupported ${arg}; ${STRUCTURE_SNAPSHOT_HELP}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  const draftId = opts['--draft'];
+  const out = opts['--out'];
+  if (positional.length > 1 || draftId === undefined || out === undefined) refuse('STRUCTURE_SNAPSHOT_USAGE', `structure-snapshot: needs --draft and --out and at most one project folder; ${STRUCTURE_SNAPSHOT_HELP}`, USAGE_EXIT);
+  const dir = resolve(positional[0] ?? process.cwd());
+  const { project } = readProject(dir);
+  const file = outTarget(dir, out);
+
+  const index = asArray(project.drafts).findIndex(d => isObject(d) && d.id === draftId);
+  const draft = asArray(project.drafts)[index];
+  if (!isObject(draft)) refuse('STRUCTURE_SNAPSHOT_DRAFT_UNKNOWN', `drafts[${draftId}]: no recorded draft has this id; record the reviewed draft with draft-rig, then name its id with --draft`);
+  let config: JsonObject;
+  try { config = retainedJson(dir, draft.config); } catch (error) {
+    refuse('STRUCTURE_SNAPSHOT_CONFIG_CHANGED', `drafts[${index}].config: ${error instanceof Error ? error.message : String(error)}; the snapshot copies the config the draft recorded, so restore those bytes, or record the changed config as a new draft with draft-rig and review it`);
+  }
+
+  recordedPartsVerdict(dir, project, draftId);
+
+  const meshes = config.meshes;
+  if (meshes !== undefined && !isObject(meshes)) refuse('STRUCTURE_DECISIONS_INVALID', `drafts[${index}].config meshes: expected an object of part declarations; review the labelled draft, retain its exact structure decisions, and sign again`);
+  const entries: Json[] = Object.entries(meshes ?? {}).map(([part, value]) => ({ path: pointer(part), value: structuredClone(value) }));
+  const snapshot: JsonObject = { schema: STRUCTURE_SCHEMA, draft_id: draftId, config: structuredClone(draft.config) as Json, entries };
+  const errors: Finding[] = [];
+  validateStructureSnapshot(dir, project, draftId, snapshot, out, errors);
+  if (errors[0] !== undefined) refuse(errors[0].code, errors[0].message);
+
+  const bytes = `${JSON.stringify(snapshot, null, 2)}\n`;
+  let present: Buffer | undefined;
+  try { present = readFileSync(file); } catch { present = undefined; }
+  if (present !== undefined) {
+    if (present.equals(Buffer.from(bytes))) return { stdout: `structure-snapshot: ${out} already holds this snapshot of draft ${draftId}; unchanged`, exit: 0 };
+    refuse('STRUCTURE_SNAPSHOT_OUT_EXISTS', `structure-snapshot --out ${out}: the file holds different bytes; a retained snapshot is never overwritten, so name a new file`);
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, bytes);
+  return { stdout: `structure-snapshot: wrote ${out} for draft ${draftId} with ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`, exit: 0 };
+}

package/src/structure.ts

@@ -0,0 +1,166 @@
+/** Human-approved structure declarations, without applying producer patches or measuring meshes. */
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from './check-reads.ts';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { asArray, collectItems, collectSignoffs, isObject, loadCollection, type Finding } from './check.ts';
+import { draftFileUnavailable } from './drafts.ts';
+import { IGNORED_DIRS } from './init.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { hasStageOrder, interviewStageOfGuide, stageIndex } from './stages.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const STRUCTURE_SCHEMA = 'rig-create/structure-decisions@0';
+const hash = (b: Buffer): string => createHash('sha256').update(b).digest('hex');
+const add = (out: Finding[], code: string, path: string, why: string): void => { out.push({ code, path, message: `${path}: ${why}; review the labelled draft, retain its exact structure decisions, and sign again` }); };
+
+export function retainedJson(dir: string, binding: Json | undefined): JsonObject {
+  if (!isObject(binding) || typeof binding.path !== 'string' || typeof binding.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(binding.sha256) || isAbsolute(binding.path)) throw new Error('expected project-relative path and sha256');
+  const file = realpathSync(resolve(dir, binding.path));
+  const rel = relative(realpathSync(dir), file);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error('file escapes project');
+  const bytes = readFileSync(file);
+  if (hash(bytes) !== binding.sha256) throw new Error(`${binding.path}: bytes changed`);
+  const json: Json = JSON.parse(bytes.toString('utf8'));
+  if (!isObject(json)) throw new Error('expected an object');
+  return json;
+}
+
+export function structurePathIsIgnored(dir: string, path: string): boolean {
+  const ignored: readonly string[] = [...IGNORED_DIRS, 'node_modules', '.git'];
+  return [relative(resolve(dir), resolve(dir, path)), relative(realpathSync(dir), realpathSync(resolve(dir, path)))]
+    .some(rel => ignored.includes(rel.split(sep)[0] as string));
+}
+
+export function latestPartsApproval(project: JsonObject, at = Infinity): JsonObject | undefined {
+  const reopens = collectReopens(project, []).filter(r => r.at <= at);
+  return collectSignoffs(project, []).filter(s => s.stage === 'parts-review' && s.checkpoint === null && s.at <= at && liveSignoff(reopens, s.stage, s.at))
+    .sort((a, b) => b.at - a.at || b.index - a.index)[0]?.record;
+}
+
+export function checkStructure(dir: string, project: JsonObject, signoff: JsonObject, path: string, errors: Finding[]): JsonObject | null {
+  if (signoff.structure === undefined || signoff.draft_id === undefined) {
+    add(errors, 'STRUCTURE_DECISIONS_MISSING', path, 'parts approval needs --draft and --structure-file, with explicit entries:[] when unchanged'); return null;
+  }
+  let snapshot: JsonObject;
+  try { snapshot = retainedJson(dir, signoff.structure); } catch (error) { add(errors, 'STRUCTURE_DECISIONS_INVALID', `${path}.structure`, error instanceof Error ? error.message : String(error)); return null; }
+  return validateStructureSnapshot(dir, project, signoff.draft_id, snapshot, `${path}.structure`, errors);
+}
+
+/**
+ * The rules a structure snapshot meets, shared by the check and the
+ * structure-snapshot writer: it binds the named draft and its config, and
+ * every entry is a distinct exact `meshes.<part>` declaration of that config
+ * when the config is available. `at` is the path findings name.
+ */
+export function validateStructureSnapshot(dir: string, project: JsonObject, draftId: Json | undefined, snapshot: JsonObject, at: string, errors: Finding[]): JsonObject | null {
+  try {
+    const draft = asArray(project.drafts).find(d => isObject(d) && d.id === draftId);
+    if (!isObject(draft) || snapshot.schema !== STRUCTURE_SCHEMA || snapshot.draft_id !== draft.id || !isDeepStrictEqual(snapshot.config, draft.config) || !Array.isArray(snapshot.entries)) throw new Error('snapshot must bind the named draft and its config');
+    if (!isObject(draft.config) || typeof draft.config.path !== 'string') throw new Error('draft config binding is malformed');
+    const config = draftFileUnavailable(dir, draft.config.path, `derived/drafts/${String(draft.id)}`)
+      ? undefined : retainedJson(dir, snapshot.config);
+    const seen = new Set<string>();
+    for (const raw of snapshot.entries) {
+      if (!isObject(raw) || typeof raw.path !== 'string' || !/^\/meshes\/(?:[^~/]|~[01])+$/.test(raw.path) || seen.has(raw.path) || !('value' in raw)) throw new Error('entries require distinct complete /meshes/<part> declarations');
+      seen.add(raw.path);
+      const part = raw.path.slice('/meshes/'.length).replaceAll('~1', '/').replaceAll('~0', '~');
+      if (config !== undefined && (!isObject(config.meshes) || !isDeepStrictEqual(config.meshes[part], raw.value))) {
+        add(errors, 'STRUCTURE_DECISIONS_CONFLICT', at, `${raw.path} differs from the reviewed config`); return null;
+      }
+    }
+    return snapshot;
+  } catch (error) { add(errors, 'STRUCTURE_DECISIONS_INVALID', at, error instanceof Error ? error.message : String(error)); return null; }
+}
+
+/** Resolve shared context outside the answer union, ready for later choice-answer schemas. */
+export function riggingContext(dir: string, project: JsonObject, at: string, errors: Finding[]): JsonObject | null {
+  const review = latestPartsApproval(project);
+  if (review === undefined || typeof review.at !== 'string' || !Number.isFinite(Date.parse(review.at)) || !isObject(review.evidence) || !(Date.parse(at) >= Date.parse(review.at))) {
+    add(errors, 'RIGGING_INTERVIEW_CONTEXT', 'interview.rigging_context', 'a live dated parts review must precede the rigging interview'); return null;
+  }
+  if (checkStructure(dir, project, review, 'signoffs[parts-review]', errors) === null) return null;
+  for (const item of collectItems(project, { collection: loadCollection(dir) })) {
+    if (interviewStageOfGuide(item.id, item.kind === 'post', true) !== 'rigging-interview' || item.state.state === 'silent') continue;
+    const state = item.state;
+    if (state.state !== 'user' && state.state !== 'delegated') continue;
+    const when = typeof state.answer.at === 'string' ? Date.parse(state.answer.at) : NaN;
+    if (!Number.isFinite(when) || when < Date.parse(review.at) || when > Date.parse(at)) add(errors, 'RIG_GUIDE_BEFORE_PARTS', item.path, 'fresh rig guides must follow the accepted parts and precede their approval; preserve earlier answers as history');
+  }
+  return { accepted_parts: { signoff_at: review.at, evidence: review.evidence }, structure: review.structure as Json };
+}
+
+/** The meshes answer must be covered by a live later interview approval at build time. */
+export function acceptsStructureDelta(project: JsonObject, review: JsonObject, at = Infinity): boolean {
+  const partsAt = Date.parse(String(review.at));
+  const interview = isObject(project.interview) ? project.interview : {};
+  const meshes = asArray(interview.waypoints).find(w => isObject(w) && w.id === 'meshes');
+  const guide = isObject(meshes) && isObject(meshes.guide) ? meshes.guide : {};
+  const guideAt = Date.parse(String(guide.at));
+  const reopens = collectReopens(project, []).filter(r => r.at <= at);
+  return guideAt > partsAt && collectSignoffs(project, []).some(s =>
+    s.stage === 'rigging-interview' && s.record.checkpoint === null && s.at > partsAt
+    && s.at <= at && guideAt <= s.at && liveSignoff(reopens, s.stage, s.at));
+}
+
+/** Snapshot order is retained; null denotes a declaration absent from the version. */
+export function structureDelta(snapshot: JsonObject, config: JsonObject): JsonObject[] {
+  return asArray(snapshot.entries).flatMap(entry => {
+    if (!isObject(entry) || typeof entry.path !== 'string') return [];
+    const part = entry.path.slice('/meshes/'.length).replaceAll('~1', '/').replaceAll('~0', '~');
+    const value = isObject(config.meshes) ? config.meshes[part] : undefined;
+    return isDeepStrictEqual(value, entry.value) ? [] : [{ entry: entry.path, snapshot: entry.value!, version: value ?? null }];
+  });
+}
+
+/** Writer and checker share the approval gate and exact file-derived delta. */
+export function approvedStructureDelta(dir: string, project: JsonObject, at: number, config: JsonObject): JsonObject[] {
+  const interview = isObject(project.interview) ? project.interview : {};
+  const adoptedAt = isObject(interview.order) ? Date.parse(String(interview.order.adopted_at)) : NaN;
+  if (!(at >= adoptedAt)) return [];
+  const review = latestPartsApproval(project, at);
+  if (!hasStageOrder(project) || review === undefined || !acceptsStructureDelta(project, review, at)) return [];
+  const errors: Finding[] = [];
+  const snapshot = checkStructure(dir, project, review, 'signoffs[parts-review]', errors);
+  return snapshot === null ? [] : structureDelta(snapshot, config);
+}
+
+export function checkRiggingContext(dir: string, project: JsonObject, effectiveStage: string, errors: Finding[], warnings: Finding[] = []): void {
+  const review = latestPartsApproval(project);
+  if (review !== undefined && (hasStageOrder(project) || review.structure !== undefined)) checkStructure(dir, project, review, 'signoffs[parts-review]', errors);
+  if (!hasStageOrder(project)) return;
+  const interview = isObject(project.interview) ? project.interview : {};
+  if (!isObject(interview.order) || typeof interview.order.adopted_at !== 'string' || !Number.isFinite(Date.parse(interview.order.adopted_at))) add(errors, 'RIGGING_INTERVIEW_CONTEXT', 'interview.order', 'order adoption needs a clock date');
+  const reopens = collectReopens(project, []);
+  const approvals = collectSignoffs(project, []).filter(s => s.stage === 'rigging-interview' && s.checkpoint === null && liveSignoff(reopens, s.stage, s.at));
+  for (const approval of approvals.sort((a, b) => b.at - a.at || b.index - a.index).slice(0, 1)) {
+    const context = riggingContext(dir, project, String(approval.record.at), errors);
+    if (context !== null && (!isDeepStrictEqual(approval.record.accepted_parts, context.accepted_parts) || !isDeepStrictEqual(approval.record.structure, context.structure))) add(errors, 'RIGGING_INTERVIEW_CONTEXT', `signoffs[${approval.index}]`, 'approval does not bind the current parts review and structure');
+  }
+  if (stageIndex(effectiveStage) < stageIndex('rigging-interview')) return;
+  if (review === undefined) add(errors, 'RIGGING_INTERVIEW_CONTEXT', 'interview.rigging_context', 'review parts before asking rigging questions');
+  // Bind production config declarations, not geometry. Historical pre-adoption builds remain history.
+  const adoptedAt = isObject(interview.order) ? Date.parse(String(interview.order.adopted_at)) : NaN;
+  for (const version of asArray(project.versions)) {
+    if (!isObject(version) || version.kind !== 'rig' || !(Date.parse(String(version.at)) >= adoptedAt)) continue;
+    const historicalReview = latestPartsApproval(project, Date.parse(String(version.at)));
+    if (historicalReview === undefined) { add(errors, 'RIGGING_INTERVIEW_CONTEXT', `versions[v${String(version.n)}]`, 'no parts structure approval was live when this rig was built'); continue; }
+    const snapshot = checkStructure(dir, project, historicalReview, `versions[v${String(version.n)}].structure`, errors);
+    if (snapshot === null) continue;
+    const provenance = isObject(version.provenance) ? version.provenance : {};
+    if (!isObject(provenance.config)) continue; // Existing provenance reader owns absent configs.
+    let config: JsonObject;
+    try { config = retainedJson(dir, provenance.config); } catch { continue; }
+    const delta = structureDelta(snapshot, config);
+    const path = `versions[v${String(version.n)}].provenance`;
+    if (delta.length > 0 && !acceptsStructureDelta(project, historicalReview, Date.parse(String(version.at)))) {
+      errors.push({ code: 'STRUCTURE_DECISIONS_CONFLICT', path: `${path}.config`, message: `${path}.config: mesh/chest declaration overrides the person-approved structure; answer the rigging meshes guide, or renew parts-review` });
+      continue;
+    }
+    if ((delta.length > 0 || provenance.structure_delta !== undefined) && !isDeepStrictEqual(provenance.structure_delta, delta)) {
+      add(errors, 'STRUCTURE_DELTA_MISMATCH', `${path}.structure_delta`, 'recorded delta differs from the snapshot and retained version config; register the rig again');
+      continue;
+    }
+    if (delta.length > 0) warnings.push({ code: 'STRUCTURE_DELTA_REVIEW', path: `${path}.structure_delta`, message: `${path}.structure_delta: ${delta.length} changed structure entries; the rig-review verdict and sign-off must cover changed structure` });
+  }
+}

package/src/templates.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from './check-reads.ts';
+import { join } from 'node:path';
+
+/** The repository's templates/ folder, read from the source tree. */
+export const TEMPLATES_DIR = join(import.meta.dir, '..', 'templates');
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type JsonObject = { [key: string]: Json };
+
+export function readTemplate(relPath: string): JsonObject {
+  const parsed: unknown = JSON.parse(readFileSync(join(TEMPLATES_DIR, relPath), 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`template ${relPath} is not a JSON object`);
+  }
+  return parsed as JsonObject;
+}

package/src/waypoints.ts

@@ -0,0 +1,163 @@
+/**
+ * Where each top-level section of a `@rig-c/parts` config goes: a rig waypoint,
+ * a post item, or nowhere (not a direction call). This is the table in
+ * docs/INTERVIEW.md § Waypoints, as data, and the ONLY place the mapping is
+ * written. The section list itself is not here: it is read from the installed
+ * parts package (src/parts-sections.ts), so a section parts adds that is not
+ * on this table is refused by name (`SECTION_UNPLACED`) — a new section is a
+ * new question before it is a new line here.
+ *
+ * `alternates` is not listed: @rig-c/parts 2.4.0 accepts it only inside
+ * `assemble` (`assemble.alternates`), so it is part of the `assemble`
+ * waypoint's decision, not a section of its own.
+ */
+export type Placement =
+  | { readonly kind: 'waypoint'; readonly waypoint: string }
+  | { readonly kind: 'post'; readonly item: string }
+  | { readonly kind: 'none'; readonly why: string };
+
+const wp = (waypoint: string): Placement => ({ kind: 'waypoint', waypoint });
+const post = (item: string): Placement => ({ kind: 'post', item });
+const none = (why: string): Placement => ({ kind: 'none', why });
+
+export const SECTION_PLACEMENT: Readonly<Record<string, Placement>> = {
+  seethrough: wp('seethrough'),
+  assemble: wp('assemble'),
+  limbs: wp('assemble'),
+  scene: wp('assemble'),
+  waist: wp('assemble'),
+  bones: wp('bones'),
+  meshes: wp('meshes'),
+  regions: wp('meshes'),
+  constraints: wp('constraints'),
+  stops: wp('constraints'),
+  cloth: wp('constraints'),
+  motion: wp('motion'),
+  turn: post('camera_depth'),
+  depth: post('camera_depth'),
+  key: none('a name'),
+  generation: none('a record of a run'),
+  proposed_rig_scale: none('a value the tool proposes'),
+  requirements: none(
+    "a path to a checks file. Declare setup_painting.required: true, with limits from parts' own pixel_count per region "
+    + 'on the build accepted at the split checkpoint, recorded as a "no worse than the accepted split" bar with its source. '
+    + 'A busy project declares setup_painting.figure_mask from a named matte of the original painting at alpha ≥ 128 (parts coverage convention) minus any foreground plane, recorded with derived add. '
+    + 'Translated guide sentences land here, after they are asked',
+  ),
+  motion_seams: none('an observation'),
+  note: none('an annotation; parts accepts it beside any object and reads nothing from it'),
+};
+
+/** Pipeline order of the rig waypoints; a waypoint not listed here sorts last, by name. */
+export const WAYPOINT_ORDER: readonly string[] = ['seethrough', 'assemble', 'bones', 'meshes', 'constraints', 'motion'];
+
+/** The framing questions asked before the waypoints (INTERVIEW.md F1, F2). */
+export const FRAMING_IDS: readonly string[] = ['rig_type', 'reference'];
+
+/**
+ * Post items with no config section of their own (INTERVIEW.md § Post-production).
+ * `camera_depth` is not listed: it is derived from the `turn` and `depth`
+ * sections through the table above.
+ */
+export const SECTIONLESS_POST_ITEMS: readonly string[] = ['post_timing', 'post_composition'];
+
+export interface DerivedWaypoint {
+  readonly id: string;
+  /** The parts sections placed on it, in parts' order. */
+  readonly config: readonly string[];
+}
+
+export interface DerivedSet {
+  readonly waypoints: readonly DerivedWaypoint[];
+  readonly post_items: readonly DerivedWaypoint[];
+  /** Sections present in parts and absent from the table. */
+  readonly unplaced: readonly string[];
+  /** Sections the table places on a waypoint or post item that parts no longer has (a retired `none` entry is not reported: nothing was asked there). */
+  readonly retired: readonly string[];
+}
+
+function byOrder(a: string, b: string): number {
+  const ia = WAYPOINT_ORDER.indexOf(a);
+  const ib = WAYPOINT_ORDER.indexOf(b);
+  if (ia === -1 && ib === -1) return a.localeCompare(b);
+  if (ia === -1) return 1;
+  if (ib === -1) return -1;
+  return ia - ib;
+}
+
+/** Places every section parts has; the result is what a project's interview is checked against. */
+export function deriveWaypoints(sections: readonly string[]): DerivedSet {
+  const waypoints = new Map<string, string[]>();
+  const items = new Map<string, string[]>();
+  const unplaced: string[] = [];
+  for (const section of sections) {
+    const placement = SECTION_PLACEMENT[section];
+    if (placement === undefined) {
+      unplaced.push(section);
+    } else if (placement.kind === 'waypoint') {
+      waypoints.set(placement.waypoint, [...(waypoints.get(placement.waypoint) ?? []), section]);
+    } else if (placement.kind === 'post') {
+      items.set(placement.item, [...(items.get(placement.item) ?? []), section]);
+    }
+  }
+  for (const item of SECTIONLESS_POST_ITEMS) if (!items.has(item)) items.set(item, []);
+  const present = new Set(sections);
+  return {
+    waypoints: [...waypoints.entries()].sort(([a], [b]) => byOrder(a, b)).map(([id, config]) => ({ id, config })),
+    post_items: [...items.entries()].map(([id, config]) => ({ id, config })),
+    unplaced,
+    retired: Object.keys(SECTION_PLACEMENT).filter((s) => !present.has(s) && SECTION_PLACEMENT[s]?.kind !== 'none'),
+  };
+}
+
+/** A direction ask, from INTERVIEW.md's waypoint descriptions, not a config field. */
+export interface WaypointAsk {
+  readonly id: string;
+  readonly text: string;
+  readonly required_for?: 'fullscreen.game_logic' | 'other';
+}
+
+export const WAYPOINT_ASKS: Readonly<Record<string, readonly WaypointAsk[]>> = {
+  seethrough: [
+    { id: 'layers', text: 'What must the layer split keep together or apart?' },
+    { id: 'resolution', text: 'What resolution should the layer passes use?' },
+    { id: 'head_crop', text: 'What head crop should be used?' },
+    { id: 'seed', text: 'What seed should be used?' },
+  ],
+  assemble: [
+    { id: 'projection', text: 'Core keeps the part mask as the boundary. Visible follows the painting rim and can take backdrop pixels. Which projection should assemble use?' },
+    { id: 'ground', text: 'Plain preserves the existing rim projection. Busy limits backdrop pickup around thin parts. Is the ground plain or busy? A busy project declares setup_painting.figure_mask from a named matte of the original painting at alpha ≥ 128 (parts coverage convention) minus any foreground plane, recorded with derived add.' },
+    { id: 'cut', text: 'Which parts are cut, and how finely?' },
+    { id: 'emphasis', text: 'Which parts need detail or must stay exactly as painted?' },
+    { id: 'draw_order', text: 'What is the parts draw order?' },
+    { id: 'authored', text: 'What is authored new?' },
+    { id: 'occluders', text: 'What is kept under occluders?' },
+    { id: 'outfits', text: 'Which outfit sets exist?' },
+  ],
+  bones: [
+    { id: 'chains', text: 'Which parts get chains or stay rigid?' },
+    { id: 'placement', text: 'Where do bones sit?' },
+    { id: 'length', text: 'How long are the chains?' },
+  ],
+  meshes: [
+    { id: 'bend', text: 'Which parts bend smoothly?' },
+    { id: 'rigid', text: 'Which parts stay rigid?' },
+    { id: 'density', text: 'What mesh density should be used?' },
+  ],
+  constraints: [
+    { id: 'effects', text: 'Which parts move on physics, wind or other effects?' },
+    { id: 'strength', text: 'How strongly do those effects act?' },
+    { id: 'extent', text: 'How far may the affected parts move?' },
+    { id: 'gravity', text: 'What gravity applies?' },
+    { id: 'stops', text: 'Where must chains stop?' },
+  ],
+  motion: [
+    { id: 'tracks', text: 'Which moves? Name each one.', required_for: 'other' },
+    { id: 'states', text: 'Which game states drive the motion?', required_for: 'fullscreen.game_logic' },
+    { id: 'transitions', text: 'What moves it from one state to the next?', required_for: 'fullscreen.game_logic' },
+    { id: 'extent', text: 'How far does each motion move?' },
+    { id: 'speed', text: 'How fast does each motion move?' },
+    { id: 'loop', text: 'How long is the motion loop?' },
+    { id: 'blink', text: 'Should it blink?', required_for: 'other' },
+  ],
+};