rig-create 0.0.0-stage → 1.0.1

package/src/collection.ts

@@ -0,0 +1,348 @@
+/**
+ * `rig-create init --collection <dir>` and `rig-create init --member <collection dir> <name>`
+ * (docs/COLLECTIONS.md § Layout).
+ *
+ * A collection is one git repository. Its members are ordinary project folders
+ * under `members/<name>/` inside that repository, not repositories of their
+ * own: the folder path is the membership record (COLLECTIONS.md § Members live
+ * inside the collection), and a collection version pins member builds, so the
+ * collection's history has to hold the member records it pins. A nested
+ * repository would make the collection's git see a member as an opaque gitlink.
+ *
+ * For the same reason a member has no `package.json` of its own: the
+ * collection pins the rig-c packages once, so every member is built with the
+ * same versions and a cross bar measures one toolchain. `interview --check` in
+ * a member reads the collection's install (src/parts-sections.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+
+import { CREATE_DOCS, DERIVED_LINK, PACKAGE_DOCS, READ_FIRST, createDocUrl, packageDocPath, writeAgentGuide } from './agent-guide.ts';
+import { COLLECTION_SCHEMA, collectionAnswer, readJsonObject } from './check.ts';
+import {
+  checkTarget,
+  FALLBACK_IDENTITY,
+  GITIGNORE,
+  hasGitIdentity,
+  IGNORED_DIRS,
+  INTERVIEW_DOC_URL,
+  run,
+  TRACKED_EMPTY_DIRS,
+  writePackageJson,
+} from './init.ts';
+import { PINNED_PACKAGES } from './pins.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { CHOICE_ORDER_SPEC } from './choices.ts';
+import { readTemplate, TEMPLATES_DIR, type Json, type JsonObject } from './templates.ts';
+
+/** The collection's stages, in order (COLLECTIONS.md § Collection stages); `closed_by` as in src/stages.ts. */
+export const COLLECTION_STAGES = [
+  { id: 'interview', closed_by: 'signoff' },
+  { id: 'plan-approved', closed_by: 'signoff' },
+  { id: 'reference', closed_by: 'signoff' },
+  { id: 'members', closed_by: 'bar' },
+  { id: 'post-interview', closed_by: 'signoff' },
+  { id: 'post', closed_by: 'bar' },
+  { id: 'direction-review', closed_by: 'signoff' },
+  { id: 'accepted', closed_by: 'none' },
+] as const satisfies readonly { id: string; closed_by: 'signoff' | 'bar' | 'none' }[];
+
+export const COLLECTION_STAGE_VALUES: readonly string[] = [...COLLECTION_STAGES.map((s) => s.id), 'paused'];
+
+/** A collection folder holds members/ besides a project's tracked folders. */
+export const COLLECTION_TRACKED_EMPTY_DIRS = ['members', ...TRACKED_EMPTY_DIRS] as const;
+
+export const COLLECTION_GUIDE_TEMPLATE = 'collection-agent-guide.md';
+
+/** A member name is one folder name: it becomes `members/<name>/` and the `from.collection` key nobody retypes. */
+const MEMBER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export interface CollectionInitResult {
+  dir: string;
+  name: string;
+  installed: boolean;
+  installError: string | null;
+  committed: string[];
+  commit: string;
+  fallbackIdentity: boolean;
+}
+
+export interface MemberInitResult {
+  collectionDir: string;
+  collection: string;
+  dir: string;
+  name: string;
+  inherited: string[];
+  own: string[];
+  committed: string[];
+  /** `null` when the collection folder is not a git work tree: files are written, nothing is committed. */
+  commit: string | null;
+  fallbackIdentity: boolean;
+}
+
+function writeJson(file: string, value: JsonObject): void {
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function isObject(v: Json | undefined): v is JsonObject {
+  return v !== null && v !== undefined && typeof v === 'object' && !Array.isArray(v);
+}
+
+function identityArgs(dir: string): { args: string[]; fallback: boolean } {
+  const fallback = !hasGitIdentity(dir);
+  return {
+    fallback,
+    args: fallback ? ['-c', `user.name=${FALLBACK_IDENTITY.name}`, '-c', `user.email=${FALLBACK_IDENTITY.email}`] : [],
+  };
+}
+
+function commitPaths(dir: string, paths: string[], message: string): { commit: string; fallback: boolean } {
+  const add = run(['git', 'add', '--', ...paths], dir);
+  if (!add.ok) refuse('INIT_GIT_FAILED', `git add failed in ${dir}\n${add.out}`);
+  const identity = identityArgs(dir);
+  const commit = run(['git', ...identity.args, 'commit', '-q', '-m', message, '--', ...paths], dir);
+  if (!commit.ok) refuse('INIT_GIT_FAILED', `git commit failed in ${dir}\n${commit.out}`);
+  return { commit: run(['git', 'rev-parse', '--short', 'HEAD'], dir).out, fallback: identity.fallback };
+}
+
+/** The collection's AGENTS.md, from templates/collection-agent-guide.md. */
+export function renderCollectionGuide(): string {
+  const fills: Record<string, string> = {
+    COLLECTIONS_LINK: `[COLLECTIONS.md](${createDocUrl('docs/COLLECTIONS.md')})`,
+    DERIVED_LINK: `[INTERVIEW.md § Derived answers](${createDocUrl(DERIVED_LINK.path, DERIVED_LINK.anchor)})`,
+    READ_FIRST,
+    PACKAGE_DOCS: PACKAGE_DOCS.map((doc) => `- [${doc.package} ${doc.path}](${packageDocPath(doc)}): ${doc.why}.`).join('\n'),
+    CREATE_DOCS: CREATE_DOCS.map((doc) => `- [${doc.path}](${createDocUrl(doc.path)}): ${doc.why}.`).join('\n'),
+  };
+  const template = readFileSync(join(TEMPLATES_DIR, COLLECTION_GUIDE_TEMPLATE), 'utf8');
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (marker, key: string) => {
+    const fill = fills[key];
+    if (fill === undefined) throw new Error(`${COLLECTION_GUIDE_TEMPLATE}: unknown marker ${marker}`);
+    return fill;
+  });
+}
+
+/**
+ * Creates a collection in `target`: collection.json and shared/conventions.json
+ * from the templates (both named after the folder), members/, the project
+ * folders a collection shares (inputs/references, evidence, and the ignored
+ * derived, outputs, scratch), .gitignore, package.json pinning the rig-c
+ * packages once for every member, the install (unless skipped), the agent
+ * guide, and a first commit of exactly those files.
+ */
+export function initCollection(target: string, options: { install: boolean }): CollectionInitResult {
+  const dir = resolve(target);
+  checkTarget(dir);
+  const name = basename(dir);
+  mkdirSync(join(dir, 'shared'), { recursive: true });
+  const written: string[] = [];
+
+  const collection = readTemplate('collection.json');
+  collection.name = name;
+  writeJson(join(dir, 'collection.json'), collection);
+  written.push('collection.json');
+  const conventions = readTemplate('shared/conventions.json');
+  conventions.collection = name;
+  writeJson(join(dir, 'shared', 'conventions.json'), conventions);
+  written.push('shared/conventions.json');
+  writePackageJson(dir, name);
+  written.push('package.json');
+  writeFileSync(join(dir, '.gitignore'), GITIGNORE);
+  written.push('.gitignore');
+  for (const sub of COLLECTION_TRACKED_EMPTY_DIRS) {
+    mkdirSync(join(dir, sub), { recursive: true });
+    writeFileSync(join(dir, sub, '.gitkeep'), '');
+    written.push(`${sub}/.gitkeep`);
+  }
+  for (const sub of IGNORED_DIRS) mkdirSync(join(dir, sub), { recursive: true });
+  writeFileSync(join(dir, 'AGENTS.md'), renderCollectionGuide());
+  writeFileSync(join(dir, 'CLAUDE.md'), ['@AGENTS.md', '', 'The agent guide for this collection is AGENTS.md, imported above. It is the only copy: change it there, not here.', ''].join('\n'));
+  written.push('AGENTS.md', 'CLAUDE.md');
+
+  let installError: string | null = null;
+  if (options.install) {
+    const install = run([process.execPath, 'install'], dir);
+    if (install.ok) written.push('bun.lock');
+    else installError = install.out;
+  }
+  const gitInit = run(['git', 'init', '-q'], dir);
+  if (!gitInit.ok) refuse('INIT_GIT_FAILED', `git init failed in ${dir}\n${gitInit.out}`);
+  const { commit, fallback } = commitPaths(dir, written, `Create collection ${name}`);
+  return { dir, name, installed: options.install && installError === null, installError, committed: written, commit, fallbackIdentity: fallback };
+}
+
+/** Reads `<dir>/collection.json`, refusing by name when the folder is not a collection. */
+export function readCollection(dir: string): JsonObject {
+  const file = join(dir, 'collection.json');
+  if (!existsSync(file)) refuse('INIT_NOT_A_COLLECTION', `${dir} is not a collection: it has no collection.json (make one with rig-create init --collection <dir>)`);
+  const read = readJsonObject(file);
+  if (!read.ok) refuse('INIT_NOT_A_COLLECTION', `${file}: ${read.error}`);
+  if (read.value.schema !== COLLECTION_SCHEMA) {
+    refuse('INIT_NOT_A_COLLECTION', `${file}: schema is ${JSON.stringify(read.value.schema ?? null)}, not ${COLLECTION_SCHEMA}`);
+  }
+  return read.value;
+}
+
+/**
+ * Where the member's answer starts: a reference to the collection's answer
+ * when the collection gave one (anything but `null` or `"per-member"`), and
+ * `null` — the member's own question — otherwise. The value is never copied.
+ */
+function startingAnswer(collection: JsonObject, collectionName: string, id: string, at: string): { answer: Json; inherited: boolean } {
+  const answer = collectionAnswer(collection, id);
+  if (answer === undefined || answer === null) return { answer: null, inherited: false };
+  if (isObject(answer) && ('deferred' in answer || answer.value === 'per-member')) return { answer: null, inherited: false };
+  return { answer: { basis: 'inherited', from: { collection: collectionName, question: id }, by: 'rig-create', at }, inherited: true };
+}
+
+/**
+ * Creates `<collection>/members/<name>/` as an ordinary project (PROJECT.md §
+ * Layout, without package.json and without a repository of its own), its
+ * answers inherited from the collection where the collection answered, and
+ * registers it in collection.json `members[]`. Commits exactly the files
+ * written and collection.json in the collection's repository; refuses when
+ * collection.json has uncommitted changes, so that commit never carries
+ * someone else's edit.
+ */
+export function initMember(collectionArg: string, name: string, now: Date): MemberInitResult {
+  const collectionDir = resolve(collectionArg);
+  if (!MEMBER_NAME_RE.test(name)) {
+    refuse('INIT_MEMBER_NAME_INVALID', `member name ${JSON.stringify(name)} is not one folder name (letters, digits, '.', '_', '-'; not starting with '.', '_' or '-')`);
+  }
+  const collection = readCollection(collectionDir);
+  const collectionName = typeof collection.name === 'string' && collection.name !== '' ? collection.name : null;
+  if (collectionName === null) refuse('INIT_COLLECTION_UNNAMED', `${join(collectionDir, 'collection.json')} has no name; an inherited answer names its collection`);
+  const members = Array.isArray(collection.members) ? collection.members : [];
+  const dir = join(collectionDir, 'members', name);
+  if (members.some((m) => isObject(m) && m.name === name)) {
+    refuse('INIT_MEMBER_EXISTS', `collection '${collectionName}' already has a member '${name}' in members[]`);
+  }
+  if (existsSync(dir)) refuse('INIT_MEMBER_EXISTS', `${dir} already exists; collection '${collectionName}' has a folder for '${name}'`);
+
+  const inGit = run(['git', 'rev-parse', '--is-inside-work-tree'], collectionDir).ok;
+  if (inGit) {
+    const dirty = run(['git', 'status', '--porcelain', '--', 'collection.json'], collectionDir).out;
+    if (dirty !== '') {
+      refuse('INIT_COLLECTION_DIRTY', `${join(collectionDir, 'collection.json')} has uncommitted changes; commit them first, so registering '${name}' commits only that`);
+    }
+  }
+
+  const at = now.toISOString();
+  const project = readTemplate('project.json');
+  project.name = name;
+  project.corrections_contract = { schema: 'rig-create/corrections@1', adopted_at: at };
+  project.corrections = [];
+  const inherited: string[] = [];
+  const own: string[] = [];
+  const interview = isObject(project.interview) ? project.interview : {};
+  interview.order = { spec: CHOICE_ORDER_SPEC, adopted_at: at, choices_adopted_at: at };
+  const post = isObject(interview.post) ? interview.post : {};
+  const lists: [Json | undefined, 'answer' | 'guide'][] = [
+    [interview.framing, 'answer'],
+    [interview.waypoints, 'guide'],
+    [post.items, 'guide'],
+  ];
+  for (const [list, field] of lists) {
+    for (const item of Array.isArray(list) ? list : []) {
+      if (!isObject(item) || typeof item.id !== 'string') continue;
+      const start = startingAnswer(collection, collectionName, item.id, at);
+      item[field] = start.answer;
+      (start.inherited ? inherited : own).push(item.id);
+    }
+  }
+
+  mkdirSync(dir, { recursive: true });
+  const rel = (p: string): string => `members/${name}/${p}`;
+  const written: string[] = [];
+  writeJson(join(dir, 'project.json'), project);
+  written.push(rel('project.json'));
+  writeFileSync(join(dir, '.gitignore'), GITIGNORE);
+  written.push(rel('.gitignore'));
+  for (const sub of TRACKED_EMPTY_DIRS) {
+    mkdirSync(join(dir, sub), { recursive: true });
+    writeFileSync(join(dir, sub, '.gitkeep'), '');
+    written.push(rel(`${sub}/.gitkeep`));
+  }
+  for (const sub of IGNORED_DIRS) mkdirSync(join(dir, sub), { recursive: true });
+  // The member's guide links the installed docs in the collection's node_modules, two folders up.
+  written.push(...writeAgentGuide(dir).map(rel));
+  const guide = join(dir, 'AGENTS.md');
+  writeFileSync(guide, readFileSync(guide, 'utf8').replaceAll('](node_modules/', '](../../node_modules/'));
+
+  collection.members = [...members, { name, project: rel('project.json'), input: null, note: null }];
+  writeJson(join(collectionDir, 'collection.json'), collection);
+  written.push('collection.json');
+
+  let commit: string | null = null;
+  let fallbackIdentity = false;
+  if (inGit) {
+    const made = commitPaths(collectionDir, written, `Add member ${name} to collection ${collectionName}`);
+    commit = made.commit;
+    fallbackIdentity = made.fallback;
+  }
+  return { collectionDir, collection: collectionName, dir, name, inherited, own, committed: written, commit, fallbackIdentity };
+}
+
+export function describeCollectionInit(result: CollectionInitResult): string {
+  const pins = Object.entries(PINNED_PACKAGES).map(([pkg, version]) => `${pkg} ${version}`).join(', ');
+  const lines = [
+    `Created collection ${result.name} at ${result.dir}`,
+    result.installed
+      ? `  installed ${pins} for every member (bun.lock written)`
+      : result.installError === null
+        ? `  pinned ${pins} for every member; install skipped (--no-install)`
+        : `  pinned ${pins}; bun install FAILED, so bun.lock is not in the first commit`,
+    `  first commit ${result.commit}: ${result.committed.join(', ')}`,
+  ];
+  if (result.fallbackIdentity) lines.push(`  no git identity is configured; the first commit is authored as "${FALLBACK_IDENTITY.name} <${FALLBACK_IDENTITY.email}>"`);
+  lines.push('', 'Next:');
+  let step = 1;
+  if (!result.installed) lines.push(`  ${step++}. cd ${result.dir} && bun install, then commit bun.lock`);
+  lines.push(`  ${step++}. put the group painting in inputs/, then hold the collection interview: ${INTERVIEW_DOC_URL}`);
+  lines.push(`  ${step++}. add members once the shared answers are given: rig-create init --member ${result.dir} <name>`);
+  return lines.join('\n');
+}
+
+export function describeMemberInit(result: MemberInitResult): string {
+  const lines = [
+    `Created member ${result.name} of collection ${result.collection} at ${result.dir}`,
+    `  inherited from the collection (${result.inherited.length}): ${result.inherited.join(', ') || 'none'}`,
+    `  the member's own to answer (${result.own.length}): ${result.own.join(', ') || 'none'}`,
+    result.commit === null
+      ? `  ${result.collectionDir} is not a git work tree; nothing committed (written: ${result.committed.join(', ')})`
+      : `  commit ${result.commit}: ${result.committed.join(', ')}`,
+  ];
+  if (result.fallbackIdentity) lines.push(`  no git identity is configured; the commit is authored as "${FALLBACK_IDENTITY.name} <${FALLBACK_IDENTITY.email}>"`);
+  lines.push('', 'Next:', `  1. interview the member on what it does not inherit: rig-create interview --check ${result.dir}`);
+  return lines.join('\n');
+}
+
+/**
+ * `init --collection <dir> [--no-install]` and `init --member <collection dir> <name>`.
+ * The member is named, not pathed: the command derives `members/<name>/`, so a
+ * member cannot be made outside `members/`, and "not a collection" is refused
+ * on the folder the user named, before anything is written.
+ */
+export function collectionInitCommand(args: string[], now: number): { stdout: string; installError: string | null; dir: string } {
+  let collection = false;
+  let member = false;
+  let install = true;
+  const positional: string[] = [];
+  for (const arg of args) {
+    if (arg === '--collection') collection = true;
+    else if (arg === '--member') member = true;
+    else if (arg === '--no-install') install = false;
+    else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `init does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (collection && member) refuse('INIT_TOO_MANY_ARGUMENTS', 'init takes --collection or --member, not both', USAGE_EXIT);
+  if (collection) {
+    if (positional.length !== 1) refuse('INIT_DIR_MISSING', 'init --collection takes one folder: rig-create init --collection <dir>', USAGE_EXIT);
+    const result = initCollection(positional[0] as string, { install });
+    return { stdout: describeCollectionInit(result), installError: result.installError, dir: result.dir };
+  }
+  if (!install) refuse('UNKNOWN_OPTION', 'init --member does not take --no-install: a member installs nothing (the collection pins the packages)', USAGE_EXIT);
+  if (positional.length !== 2) refuse('INIT_DIR_MISSING', 'init --member takes the collection folder and a member name: rig-create init --member <collection dir> <name>', USAGE_EXIT);
+  const result = initMember(positional[0] as string, positional[1] as string, new Date(now));
+  return { stdout: describeMemberInit(result), installError: null, dir: result.dir };
+}

package/src/config-inputs.ts

@@ -0,0 +1,155 @@
+/** Config input identities come from the installed loader's file declarations. */
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from './check-reads.ts';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { locateParts, OWN_NODE_MODULES } from './parts-sections.ts';
+import type { JsonObject } from './templates.ts';
+
+export const CONFIG_INPUTS_SINCE = '2026-11-06T00:00:00Z';
+const load = createRequire(import.meta.url);
+export class ConfigInputsUnavailable extends Error {
+  constructor(version: string) {
+    super(`@rig-c/parts ${version} has no configFileReferences export; install a version providing the config file declarations before recording new named inputs`);
+  }
+}
+export type ConfigInputsWarning = (error: ConfigInputsUnavailable) => void;
+export function configInputReferences(dir: string, config: unknown, unavailable?: ConfigInputsWarning): { at: string; value: string }[] {
+  const parts = locateParts(dir);
+  if (parts === null) throw new Error('install @rig-c/parts to read config-named inputs');
+  const mod = load(join(parts, 'src/config.ts')) as { configFileReferences?: (config: unknown) => { at: string; value: string }[] };
+  if (typeof mod.configFileReferences !== 'function') {
+    // The pinned declaration only detects whether the unavailable capability matters.
+    // It supplies no binding on behalf of the project's older loader.
+    const own = load(join(OWN_NODE_MODULES, '@rig-c/parts/src/config.ts')) as typeof mod;
+    if (typeof own.configFileReferences !== 'function' || !own.configFileReferences(config).length) return [];
+    const pkg = JSON.parse(readFileSync(join(parts, 'package.json'), 'utf8')) as { version: string };
+    const error = new ConfigInputsUnavailable(pkg.version);
+    if (!unavailable) throw error;
+    unavailable(error);
+    return [];
+  }
+  return mod.configFileReferences(config);
+}
+/**
+ * The config-named inputs the pinned parts declares for `config` that the
+ * project's install does not, with the install's version. The pinned
+ * declaration stands in for a newer producer's, which create cannot load; it
+ * is used only to refuse a writer, never to bind on the install's behalf.
+ */
+export function inputsUndeclaredByInstall(dir: string, config: unknown): { version: string; refs: { at: string; value: string }[] } {
+  const parts = locateParts(dir);
+  if (parts === null) throw new Error('install @rig-c/parts to read config-named inputs');
+  type Loader = { configFileReferences?: (config: unknown) => { at: string; value: string }[] };
+  const mod = load(join(parts, 'src/config.ts')) as Loader;
+  const own = load(join(OWN_NODE_MODULES, '@rig-c/parts/src/config.ts')) as Loader;
+  const version = (JSON.parse(readFileSync(join(parts, 'package.json'), 'utf8')) as { version: string }).version;
+  if (typeof own.configFileReferences !== 'function') return { version, refs: [] };
+  const declared = typeof mod.configFileReferences === 'function' ? new Set(mod.configFileReferences(config).map(ref => ref.at)) : new Set<string>();
+  return { version, refs: own.configFileReferences(config).filter(ref => !declared.has(ref.at)) };
+}
+/** Whether release `a` is later than release `b`; a version that is not plain major.minor.patch is never later. */
+export function releaseAfter(a: string, b: string): boolean {
+  const x = /^(\d+)\.(\d+)\.(\d+)$/.exec(a);
+  const y = /^(\d+)\.(\d+)\.(\d+)$/.exec(b);
+  if (x === null || y === null) return false;
+  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) > Number(y[i]);
+  return false;
+}
+/**
+ * The file a directory reference binds: a See-through occluder plate directory
+ * (`comfy plate --mode occluder`) is bound by its producer's receipt, which
+ * itself binds the plate's sibling files; create never hashes those siblings.
+ */
+export const DIRECTORY_INPUT_RECEIPT = 'receipt.json';
+/**
+ * The plate-receipt spec the project's installed parts declares
+ * (`PLATE_RECEIPT_SPEC` in `src/plate.ts`), read from the producer and never
+ * copied into create.
+ */
+export function plateReceiptSpec(dir: string): string {
+  const parts = locateParts(dir);
+  if (parts === null) throw new Error('install @rig-c/parts to read config-named inputs');
+  let spec: unknown;
+  try { spec = (load(join(parts, 'src/plate.ts')) as { PLATE_RECEIPT_SPEC?: unknown }).PLATE_RECEIPT_SPEC; } catch { spec = undefined; }
+  if (typeof spec !== 'string' || !spec) {
+    const pkg = JSON.parse(readFileSync(join(parts, 'package.json'), 'utf8')) as { version: string };
+    throw new Error(`@rig-c/parts ${pkg.version} has no PLATE_RECEIPT_SPEC export in src/plate.ts; install a version declaring the plate receipt spec before binding a directory input`);
+  }
+  return spec;
+}
+/** The `spec` a receipt's bytes declare, or null when they are not a JSON object with a string spec. */
+export function receiptSpec(bytes: Uint8Array): string | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.from(bytes).toString('utf8')); } catch { return null; }
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) && typeof (parsed as { spec?: unknown }).spec === 'string' ? (parsed as { spec: string }).spec : null;
+}
+/**
+ * One binding per config-named input. A file binds `{path, sha256}`; a
+ * directory binds `{path: <dir>/receipt.json, sha256, directory: <dir>, spec}`,
+ * so every reader that hashes `path` reads a regular file either way. The
+ * receipt must declare the installed parts' plate-receipt spec; its siblings
+ * and measurements are parts' to verify, not create's.
+ */
+export function configInputBindings(dir: string, configPath: string, allowMissing = false, unavailable?: ConfigInputsWarning): JsonObject[] {
+  const config = JSON.parse(readFileSync(resolve(dir, configPath), 'utf8'));
+  const root = realpathSync(dir);
+  const contained = (at: string, path: string): string => {
+    if (!path || isAbsolute(path) || path === '..' || path.startsWith(`..${sep}`)) throw new Error(`${at}: named input leaves the project`);
+    return path.split(sep).join('/');
+  };
+  const canonical = (target: string): string => {
+    let cur = target;
+    while (!existsSync(cur)) {
+      try { if (lstatSync(cur).isSymbolicLink()) break; } catch { /* Missing segment; try parent. */ }
+      const parent = dirname(cur);
+      if (parent === cur) return target;
+      cur = parent;
+    }
+    return resolve(realpathSync(cur), relative(cur, target));
+  };
+  return configInputReferences(dir, config, unavailable).map((ref): JsonObject => {
+    const file = resolve(dir, dirname(configPath), ref.value);
+    const present = existsSync(file);
+    const real = present ? realpathSync(file) : canonical(file);
+    const path = contained(ref.at, relative(root, real));
+    if (!present) {
+      if (allowMissing) return { path, sha256: null };
+      realpathSync(file);
+    }
+    if (lstatSync(real).isDirectory()) {
+      const receipt = join(real, DIRECTORY_INPUT_RECEIPT);
+      const bound = `${path}/${DIRECTORY_INPUT_RECEIPT}`;
+      if (allowMissing && !existsSync(receipt)) return { path: bound, sha256: null, directory: path };
+      if (!existsSync(receipt) || !lstatSync(receipt).isFile()) throw new Error(`${ref.at}: named input directory ${path} holds no regular-file ${DIRECTORY_INPUT_RECEIPT}; a directory input binds its producer's receipt, such as a comfy plate --mode occluder output`);
+      const bytes = readFileSync(receipt);
+      const spec = plateReceiptSpec(dir);
+      const declared = receiptSpec(bytes);
+      if (declared !== spec) throw new Error(`${ref.at}: ${bound} declares spec ${JSON.stringify(declared)}; a directory input binds a ${spec} receipt, such as a comfy plate --mode occluder output`);
+      return { path: bound, sha256: createHash('sha256').update(bytes).digest('hex'), directory: path, spec };
+    }
+    if (!lstatSync(real).isFile()) throw new Error(`${ref.at}: named input ${path} is not a regular file`);
+    return { path, sha256: createHash('sha256').update(readFileSync(file)).digest('hex') };
+  });
+}
+export function configInputsLegacy(at: unknown): boolean {
+  return typeof at !== 'string' || !Number.isFinite(Date.parse(at)) || Date.parse(at) < Date.parse(CONFIG_INPUTS_SINCE);
+}
+/**
+ * Drafts recorded before this date with no `config_inputs` key, on a config
+ * that names inputs, WARN DRAFT_CONFIG_INPUTS_UNRECORDED: the config is bound
+ * by sha256, so the absent key came from an install that could not declare the
+ * inputs, which draft-rig refuses from this date (DRAFT_PARTS_INSTALL_BEHIND).
+ */
+export const DRAFT_CONFIG_INPUTS_SINCE = '2026-11-09T00:00:00Z';
+/**
+ * How a draft's unbound config-named input is reported, the one rule for check
+ * and every reader that runs it (the job record's inventory phase included):
+ * `legacy` WARNs DRAFT_RIG_FILE before CONFIG_INPUTS_SINCE, `unrecorded` WARNs
+ * DRAFT_CONFIG_INPUTS_UNRECORDED for an absent key before
+ * DRAFT_CONFIG_INPUTS_SINCE, and `refused` is a DRAFT_RIG_FILE refusal.
+ */
+export function draftUnboundInputs(draft: { at?: unknown; config_inputs?: unknown }): 'legacy' | 'unrecorded' | 'refused' {
+  if (configInputsLegacy(draft.at)) return 'legacy';
+  return draft.config_inputs === undefined && Date.parse(String(draft.at)) < Date.parse(DRAFT_CONFIG_INPUTS_SINCE) ? 'unrecorded' : 'refused';
+}

package/src/config-lost.ts

@@ -0,0 +1,135 @@
+/** Record a pre-interview version's lost build config or frozen outputs (#171, #344, docs/PROJECT.md § Migrating work done before the interview). */
+import { resolve } from 'node:path';
+
+import { asArray, isObject, PROJECT_SCHEMA } from './check.ts';
+import { save } from './choice-writers.ts';
+import { readProject } from './feedback.ts';
+import { inspectPreInterviewOutputs, OUTPUTS_LOST_MALFORMED_MESSAGE, validConfigLoss, validOutputsLoss } from './pre-interview.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+export const VERSION_HELP = `version config-lost <n> --note <text> --source <text> [<dir>] [--json]
+  Record config_lost: { note, source } on a pre-interview version whose build config did not survive.
+  Refuses when the version is not pre_interview: true, carries provenance.config, already declares config_lost, or adds a check refusal.
+version outputs-lost <n> --note <text> --source <text> [<dir>] [--json]
+  Record outputs_lost: { note, source, recorded } on a pre-interview version whose frozen outputs did not survive, keeping any readable outputs in outputs[].
+  Refuses when the version is not pre_interview: true, no output is lost, already declares outputs_lost, or adds a check refusal.`;
+
+type VersionSubcommand = 'config-lost' | 'outputs-lost';
+
+function usage(sub: VersionSubcommand, why: string): never {
+  const code = sub === 'outputs-lost' ? 'OUTPUTS_LOST_USAGE' : 'CONFIG_LOST_USAGE';
+  refuse(code, `version ${sub}: ${why}; ${VERSION_HELP}`, USAGE_EXIT);
+}
+
+export function versionCommand(args: string[], now: number): { stdout: string; exit: number } {
+  const rawSub = args[0];
+  if (rawSub !== 'config-lost' && rawSub !== 'outputs-lost') {
+    usage('config-lost', 'expected subcommand config-lost or outputs-lost');
+  }
+  const sub: VersionSubcommand = rawSub;
+  const positional: string[] = [];
+  const opts: Record<string, string> = {};
+  let json = false;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === '--json') {
+      if (json) usage(sub, 'duplicate --json');
+      json = true;
+    } else if (arg === '--note' || arg === '--source') {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--') || arg in opts) usage(sub, `${arg} needs one value`);
+      opts[arg] = value;
+    } else if (arg.startsWith('-')) {
+      usage(sub, `unsupported flag ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  const rawN = positional[0];
+  const n = rawN === undefined || !/^v?[1-9]\d*$/.test(rawN) ? Number.NaN : Number(rawN.replace(/^v/, ''));
+  if (!Number.isSafeInteger(n) || n < 1 || positional.length > 2 || !('--note' in opts) || !('--source' in opts)) {
+    usage(sub, 'supply version <n>, --note <text>, --source <text> and at most one project folder');
+  }
+  const note = opts['--note'] as string;
+  const source = opts['--source'] as string;
+  const dir = resolve(positional[1] ?? process.cwd());
+  const { file, project } = readProject(dir);
+  if (project.schema !== PROJECT_SCHEMA) {
+    refuse('SCHEMA_UNKNOWN', `schema is ${JSON.stringify(project.schema ?? null)}; version ${sub} reads ${PROJECT_SCHEMA}`);
+  }
+  const label = `versions[v${n}]`;
+  if (sub === 'outputs-lost') {
+    if (note.trim() === '' || source.trim() === '') {
+      refuse('OUTPUTS_LOST_EMPTY', `${label}.outputs_lost: --note and --source must be non-empty strings; explain the output loss and name its source record`);
+    }
+    const current = asArray(project.versions).find((v): v is JsonObject => isObject(v) && v.n === n);
+    if (current === undefined) {
+      refuse('OUTPUTS_LOST_VERSION_UNKNOWN', `${label}: versions[] has no version ${n}; name an existing pre-interview version`);
+    }
+    if (current.pre_interview !== true) {
+      refuse('OUTPUTS_LOST_NOT_PRE_INTERVIEW', `${label}.pre_interview: version ${n} is not pre_interview: true; record outputs_lost only on a migrated pre-interview version, or keep outputs[] on a create-built version`);
+    }
+    if (Object.hasOwn(current, 'outputs_lost')) {
+      refuse('OUTPUTS_LOST_ALREADY_SET', `${label}.outputs_lost: outputs_lost is already recorded on version ${n}; preserve the existing loss declaration`);
+    }
+    const inspected = inspectPreInterviewOutputs(dir, current, label);
+    const malformed = inspected.malformed[0];
+    if (malformed !== undefined) {
+      refuse(malformed.code, malformed.message);
+    }
+    const other = inspected.otherRefusals[0];
+    if (other !== undefined) {
+      refuse(other.code, other.message);
+    }
+    if (inspected.missing.length === 0) {
+      refuse('OUTPUTS_LOST_HAS_OUTPUTS', `${label}.outputs: no output is lost on version ${n} (${inspected.readable.join(', ')}); keep surviving outputs instead of declaring outputs_lost`);
+    }
+    const next = structuredClone(project);
+    const target = asArray(next.versions).find((v): v is JsonObject => isObject(v) && v.n === n)!;
+    const missingPaths = new Set(inspected.missing.map((m) => m.path));
+    const loss: JsonObject = {
+      note,
+      source,
+      recorded: inspected.missing.map((b) => ({ path: b.path, sha256: b.sha256 })),
+    };
+    target.outputs = asArray(target.outputs).filter((o) => isObject(o) && typeof o.path === 'string' && !missingPaths.has(o.path));
+    target.outputs_lost = loss;
+    if (!validOutputsLoss(target, dir)) {
+      refuse('PRE_INTERVIEW_OUTPUTS_LOST_MALFORMED', `${label}.outputs_lost: ${OUTPUTS_LOST_MALFORMED_MESSAGE}`);
+    }
+    save(file, dir, project, next, now);
+    return {
+      stdout: json ? JSON.stringify(loss, null, 2) : `version outputs-lost: recorded ${label}.outputs_lost (${source}); stage unchanged`,
+      exit: 0,
+    };
+  }
+  if (note.trim() === '' || source.trim() === '') {
+    refuse('CONFIG_LOST_EMPTY', `${label}.config_lost: --note and --source must be non-empty strings; explain the config loss and name its source record`);
+  }
+  const current = asArray(project.versions).find((v): v is JsonObject => isObject(v) && v.n === n);
+  if (current === undefined) {
+    refuse('CONFIG_LOST_VERSION_UNKNOWN', `${label}: versions[] has no version ${n}; name an existing pre-interview version`);
+  }
+  if (current.pre_interview !== true) {
+    refuse('CONFIG_LOST_NOT_PRE_INTERVIEW', `${label}.pre_interview: version ${n} is not pre_interview: true; record config_lost only on a migrated pre-interview version, or keep provenance.config on a create-built version`);
+  }
+  if (Object.hasOwn(current, 'config_lost')) {
+    refuse('CONFIG_LOST_ALREADY_SET', `${label}.config_lost: config_lost is already recorded on version ${n}; preserve the existing loss declaration`);
+  }
+  if (isObject(current.provenance) && current.provenance.config !== null && current.provenance.config !== undefined) {
+    refuse('CONFIG_LOST_HAS_CONFIG', `${label}.provenance.config: version ${n} has provenance.config; keep the surviving build config instead of declaring config_lost`);
+  }
+  const next = structuredClone(project);
+  const target = asArray(next.versions).find((v): v is JsonObject => isObject(v) && v.n === n)!;
+  const loss: JsonObject = { note, source };
+  target.config_lost = loss;
+  if (!validConfigLoss(target)) {
+    refuse('PRE_INTERVIEW_CONFIG_LOST_MALFORMED', `${label}.config_lost: record { note, source } with nonempty strings only on a pre-interview version without provenance.config; restore a surviving config instead`);
+  }
+  save(file, dir, project, next, now);
+  return {
+    stdout: json ? JSON.stringify(loss, null, 2) : `version config-lost: recorded ${label}.config_lost (${source}); stage unchanged`,
+    exit: 0,
+  };
+}