@rig-c/create 0.0.0-stage → 1.0.1

package/src/init.ts

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from './check-reads.ts';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { writeAgentGuide } from './agent-guide.ts';
+import { PINNED_PACKAGES } from './pins.ts';
+import { readVerbatim } from './record-input.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+import { CHOICE_ORDER_SPEC } from './stages.ts';
+import { readTemplate, type JsonObject } from './templates.ts';
+import { JOB_BINDING_FILE, JOB_OUTBOX_DIRECTORY } from './job-outbox.ts';
+
+export const INTERVIEW_DOC_URL = 'https://github.com/rig-c/create/blob/main/docs/INTERVIEW.md';
+
+/** Folders kept in git while empty (docs/PROJECT.md: tracked). Kept by a .gitkeep. */
+export const TRACKED_EMPTY_DIRS = ['inputs/references', 'evidence'] as const;
+/** Folders git ignores (docs/PROJECT.md: not tracked). Created empty. */
+export const IGNORED_DIRS = ['derived', 'outputs', 'scratch'] as const;
+
+export const GITIGNORE = ['/derived/', '/outputs/', '/scratch/', 'node_modules/', `/${JOB_BINDING_FILE}`, `/${JOB_OUTBOX_DIRECTORY}/`, ''].join('\n');
+
+/** Used for the first commit only, and only when git has no identity configured. */
+export const FALLBACK_IDENTITY = { name: 'rig-create', email: 'rig-create@localhost' } as const;
+
+export interface InitOptions {
+  install: boolean;
+  /** The instant the record's adoption dates carry (ms since the epoch). */
+  now: number;
+  /** The painting the project is for, registered as its first input; with it init refuses a second project for the same artwork. */
+  painting?: PaintingOption;
+}
+
+export interface SameArtworkOptions {
+  /** Where sibling projects live; default the new project's parent folder. */
+  projectsRoot?: string | undefined;
+  /** A file saying why this is a new project for an artwork another project already binds. */
+  sameArtworkReason?: string | undefined;
+  /** The input index being registered; default 0. */
+  index?: number | undefined;
+}
+
+export interface PaintingOption extends SameArtworkOptions {
+  file: string;
+  origin: string;
+}
+
+interface Artwork { readonly path: string; readonly bytes: Buffer; readonly entry: JsonObject; readonly same: JsonObject | null }
+
+/**
+ * One artwork is one project (create#285, create#291): refuse before writing anything when a
+ * project directly under the projects root binds an input with the painting's sha256, unless a reason is given.
+ */
+export function sameArtworkFor(dir: string, name: string, sha256: string, now: number, options: SameArtworkOptions = {}): JsonObject | null {
+  const root = resolve(options.projectsRoot ?? dirname(dir));
+  let siblings: string[] = [];
+  try { siblings = readdirSync(root).sort(); } catch {
+    if (options.projectsRoot !== undefined) refuse('INIT_ARTWORK_USAGE', `--projects-root ${root}: not a readable folder`, USAGE_EXIT);
+  }
+  const matches = siblings.filter(sibling => {
+    if (resolve(root, sibling) === dir) return false;
+    let record: unknown;
+    try { record = JSON.parse(readFileSync(join(root, sibling, 'project.json'), 'utf8')); } catch { return false; }
+    const inputs = record !== null && typeof record === 'object' && 'inputs' in record && Array.isArray(record.inputs) ? record.inputs as unknown[] : [];
+    return inputs.some(input => input !== null && typeof input === 'object' && (input as JsonObject).sha256 === sha256);
+  });
+  if (matches.length > 0 && options.sameArtworkReason === undefined) {
+    refuse('INIT_ARTWORK_EXISTS', `inputs[${options.index ?? 0}]: ${name} (sha256 ${sha256}) is already an input of ${matches.join(', ')} under ${root}; one artwork is one project, so record a redo, a new source or a new tool as a version there, or give --same-artwork-reason <file> for a different rig kind`);
+  }
+  if (options.sameArtworkReason !== undefined) {
+    if (matches.length === 0) refuse('INIT_ARTWORK_USAGE', `--same-artwork-reason: no project under ${root} binds ${name}; drop the reason`, USAGE_EXIT);
+    const reason = readVerbatim(options.sameArtworkReason).trim();
+    if (!reason) refuse('INIT_ARTWORK_USAGE', '--same-artwork-reason: the reason file is empty; say why this artwork needs a second project', USAGE_EXIT);
+    return { reason, at: new Date(now).toISOString(), projects: matches };
+  }
+  return null;
+}
+
+function artworkFor(dir: string, painting: PaintingOption, now: number): Artwork {
+  let bytes: Buffer;
+  try {
+    if (!statSync(painting.file).isFile()) throw new Error('not a file');
+    bytes = readFileSync(painting.file);
+  } catch { refuse('INIT_ARTWORK_USAGE', `--painting ${painting.file}: not a readable file`, USAGE_EXIT); }
+  const name = basename(painting.file);
+  if (name.startsWith('.') || name === 'references') refuse('INIT_ARTWORK_USAGE', `--painting ${painting.file}: name the painting file so it can sit in inputs/`, USAGE_EXIT);
+  const sha256 = createHash('sha256').update(bytes).digest('hex');
+  const same = sameArtworkFor(dir, name, sha256, now, painting);
+  const path = `inputs/${name}`;
+  return { path, bytes, same, entry: { path, sha256, bytes: bytes.length, origin: painting.origin, at: new Date(now).toISOString() } };
+}
+
+export interface InitResult {
+  dir: string;
+  name: string;
+  installed: boolean;
+  /** Why `bun install` failed, when it did; the project is still created and committed without bun.lock. */
+  installError: string | null;
+  committed: string[];
+  commit: string;
+  fallbackIdentity: boolean;
+}
+
+/** A package name npm accepts, from a folder name. */
+export function packageNameFor(folder: string): string {
+  const name = folder
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+/, '')
+    .slice(0, 214);
+  return name === '' ? 'rig-project' : name;
+}
+
+export function run(cmd: string[], cwd: string): { ok: boolean; out: string } {
+  const proc = Bun.spawnSync(cmd, { cwd, stdout: 'pipe', stderr: 'pipe' });
+  const out = `${proc.stdout.toString()}${proc.stderr.toString()}`.trim();
+  return { ok: proc.exitCode === 0, out };
+}
+
+export function checkTarget(dir: string): void {
+  if (!existsSync(dir)) return;
+  if (!statSync(dir).isDirectory()) {
+    refuse('INIT_NOT_A_DIRECTORY', `${dir} exists and is not a directory`);
+  }
+  const entries = readdirSync(dir).sort();
+  if (entries.length > 0) {
+    const shown = entries.slice(0, 5).join(', ') + (entries.length > 5 ? ', …' : '');
+    refuse('INIT_DIR_NOT_EMPTY', `${dir} is not empty (${entries.length} entries: ${shown})`);
+  }
+}
+
+/** The record init writes, and restart starts from: the template with its contracts adopted at `now`. */
+export function freshProjectRecord(name: string, now: number): JsonObject {
+  const record = readTemplate('project.json');
+  record.name = name;
+  const at = new Date(now).toISOString();
+  record.corrections_contract = { schema: 'rig-create/corrections@1', adopted_at: at };
+  record.corrections = [];
+  const interview = record.interview as JsonObject;
+  interview.order = { spec: CHOICE_ORDER_SPEC, adopted_at: at, choices_adopted_at: at };
+  return record;
+}
+
+export function writePackageJson(dir: string, name: string): void {
+  const pkg = {
+    name: packageNameFor(name),
+    private: true,
+    type: 'module',
+    dependencies: { ...PINNED_PACKAGES },
+  };
+  writeFileSync(join(dir, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+export function hasGitIdentity(dir: string): boolean {
+  return run(['git', 'config', 'user.name'], dir).ok && run(['git', 'config', 'user.email'], dir).ok;
+}
+
+/**
+ * Creates a project in `target`: the layout of docs/PROJECT.md, project.json
+ * from the template, .gitignore, a package.json pinning the rig-c packages,
+ * the install (unless skipped), the agent guide, and a first commit holding
+ * exactly the files written here. Refuses before writing anything if the
+ * target exists and is not an empty directory.
+ */
+export function initProject(target: string, options: InitOptions): InitResult {
+  const dir = resolve(target);
+  checkTarget(dir);
+  const name = basename(dir);
+  const artwork = options.painting === undefined ? null : artworkFor(dir, options.painting, options.now);
+
+  mkdirSync(dir, { recursive: true });
+  const written: string[] = [];
+
+  const record = freshProjectRecord(name, options.now);
+  if (artwork !== null) {
+    mkdirSync(join(dir, 'inputs'), { recursive: true });
+    writeFileSync(join(dir, artwork.path), artwork.bytes);
+    written.push(artwork.path);
+    record.inputs = [artwork.entry];
+    record.painting = artwork.path;
+    if (artwork.same !== null) record.same_artwork = artwork.same;
+  }
+  writeFileSync(join(dir, 'project.json'), `${JSON.stringify(record, null, 2)}\n`);
+  written.push('project.json');
+  writePackageJson(dir, name);
+  written.push('package.json');
+  writeFileSync(join(dir, '.gitignore'), GITIGNORE);
+  written.push('.gitignore');
+
+  for (const sub of 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 });
+  }
+
+  written.push(...writeAgentGuide(dir));
+
+  // An install failure does not stop init: the project and its first commit
+  // are still made (without bun.lock), so the recovery is to run `bun install`
+  // in the project and commit bun.lock — never to delete it and start again.
+  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 add = run(['git', 'add', '--', ...written], dir);
+  if (!add.ok) refuse('INIT_GIT_FAILED', `git add failed in ${dir}\n${add.out}`);
+
+  const fallbackIdentity = !hasGitIdentity(dir);
+  const identity = fallbackIdentity
+    ? ['-c', `user.name=${FALLBACK_IDENTITY.name}`, '-c', `user.email=${FALLBACK_IDENTITY.email}`]
+    : [];
+  const commit = run(['git', ...identity, 'commit', '-q', '-m', `Create project ${name}`], dir);
+  if (!commit.ok) refuse('INIT_GIT_FAILED', `git commit failed in ${dir}\n${commit.out}`);
+
+  const head = run(['git', 'rev-parse', '--short', 'HEAD'], dir);
+  return {
+    dir,
+    name,
+    installed: options.install && installError === null,
+    installError,
+    committed: written,
+    commit: head.out,
+    fallbackIdentity,
+  };
+}
+
+/** What init prints on success. */
+export function describeInit(result: InitResult): string {
+  const pins = Object.entries(PINNED_PACKAGES)
+    .map(([pkg, version]) => `${pkg} ${version}`)
+    .join(', ');
+  const lines = [
+    `Created project ${result.name} at ${result.dir}`,
+    result.installed
+      ? `  installed ${pins} (bun.lock written)`
+      : result.installError === null
+        ? `  pinned ${pins}; 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}>" (that commit only, nothing written to git config)`,
+    );
+  }
+  lines.push('', 'Next:');
+  let step = 1;
+  if (!result.installed) {
+    lines.push(`  ${step++}. cd ${result.dir} && bun install, then commit bun.lock`);
+  }
+  const painting = result.committed.find(path => path.startsWith('inputs/') && !path.endsWith('.gitkeep'));
+  lines.push(painting === undefined
+    ? `  ${step++}. put the painting in inputs/, then start the interview: ${INTERVIEW_DOC_URL}`
+    : `  ${step++}. ${painting} is registered; start the interview: ${INTERVIEW_DOC_URL}`);
+  return lines.join('\n');
+}

package/src/inputs.ts

@@ -0,0 +1,160 @@
+/** Register immutable source bytes without interpreting producer content. */
+import { createHash } from 'node:crypto';
+import { closeSync, fchmodSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { readFileSync, realpathSync, statSync } from './check-reads.ts';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { asArray, isObject, readJsonObject, type Ctx } from './check.ts';
+import { sameArtworkFor } from './init.ts';
+import { Refusal, refuse, USAGE_EXIT } from './refusal.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const INPUT_WRITER_SINCE = '2026-11-08T00:00:00Z';
+const text = (value: Json | undefined): value is string => typeof value === 'string' && value.trim() !== '';
+const sha256 = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+const escapes = (path: string): boolean => isAbsolute(path) || path === '..' || path.startsWith(`..${sep}`);
+
+function inputPath(dir: string, name: string): string {
+  const path = relative(dir, resolve(dir, name));
+  if (isAbsolute(name) || escapes(path) || path === '' || path === 'project.json' || path === '.input.lock') {
+    refuse('INPUT_PATH_INVALID', `inputs[].path: '${name}' must name a project-relative source file other than project.json; retain the source inside the project`);
+  }
+  return path.split(sep).join('/');
+}
+
+function sourceBytes(dir: string, name: string, path: string): Buffer {
+  const file = resolve(dir, name);
+  try {
+    const target = realpathSync(file);
+    const source = statSync(file);
+    const record = statSync(resolve(dir, 'project.json'));
+    if (escapes(relative(realpathSync(dir), target)) || (source.dev === record.dev && source.ino === record.ino) || target === resolve(realpathSync(dir), '.input.lock')) {
+      refuse('INPUT_PATH_INVALID', `${path}: '${name}' resolves outside the project, to project.json or to the writer lock; retain a contained source file`);
+    }
+    if (!source.isFile()) throw new Error('not a regular file');
+    return readFileSync(file);
+  } catch (error) {
+    if (error instanceof Refusal) throw error;
+    refuse('INPUT_FILE_UNREADABLE', `${path}: cannot read source file '${name}'; restore the retained file before registering or checking it`);
+  }
+}
+
+/** The writer and check use the same shape, containment and raw-byte validator. */
+export function checkInputs(ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'>): void {
+  const painting = ctx.project.painting;
+  if (painting !== undefined && (!text(painting) || !asArray(ctx.project.inputs).some(input => isObject(input) && input.path === painting))) {
+    ctx.refusals.push({ code: 'INPUT_PAINTING_INVALID', path: 'painting', message: 'painting: expected the path of one registered input; restore the declaration written by init --painting or input add --painting' });
+  }
+  if (ctx.project.inputs !== undefined && !Array.isArray(ctx.project.inputs)) {
+    ctx.refusals.push({ code: 'INPUTS_INVALID', path: 'inputs', message: 'inputs: expected an array; restore the input records and register new files with input add' });
+    return;
+  }
+  const paths = new Set<string>();
+  asArray(ctx.project.inputs).forEach((raw, index) => {
+    const path = `inputs[${index}]`;
+    const entry = isObject(raw) ? raw : {};
+    const at = typeof entry.at === 'string' ? Date.parse(entry.at) : NaN;
+    const complete = text(entry.path) && typeof entry.sha256 === 'string' && /^[a-f0-9]{64}$/.test(entry.sha256)
+      && typeof entry.bytes === 'number' && Number.isSafeInteger(entry.bytes) && entry.bytes >= 0 && text(entry.origin) && Number.isFinite(at);
+    if (!complete) {
+      const legacy = !Number.isFinite(at) || at < Date.parse(INPUT_WRITER_SINCE);
+      (legacy ? ctx.warnings : ctx.refusals).push({ code: 'INPUT_WRITER_MISSING', path,
+        message: `${path}: '${String(entry.path ?? '(missing path)')}' lacks writer metadata {path, sha256, bytes, origin, at}${legacy ? '; legacy record retained' : ''}; preserve historical bytes and register a new source name with input add --origin` });
+      return;
+    }
+    try {
+      const name = inputPath(ctx.dir, entry.path as string);
+      if (paths.has(name)) ctx.refusals.push({ code: 'INPUT_PATH_DUPLICATE', path: `${path}.path`, message: `${path}.path: '${name}' is already registered; keep one record per source name and use a new name for changed bytes` });
+      paths.add(name);
+      const bytes = sourceBytes(ctx.dir, name, `${path}.path`);
+      if (sha256(bytes) !== entry.sha256 || bytes.length !== entry.bytes) ctx.refusals.push({ code: 'INPUT_FILE_CHANGED', path, message: `${path}: '${name}' differs from its recorded raw sha256 or bytes; restore the original file and register changed bytes under a new name` });
+    } catch (error) {
+      if (!(error instanceof Refusal)) throw error;
+      ctx.refusals.push({ code: error.code, path: `${path}.path`, message: `${path}.path: ${error.message}` });
+    }
+  });
+}
+
+export const INPUT_HELP = `input add <path> [<project dir>] --origin <words> [--painting [--projects-root <dir>] [--same-artwork-reason <file>]] [--json]
+  Register raw source bytes as {path, sha256, bytes, origin, at}.
+  --painting declares the project's one painting and checks sibling inputs for the same artwork.
+  Paths are project-relative. Changed inputs require a new file name.`;
+
+export function inputCommand(args: string[], now: number): { stdout: string; exit: number } {
+  if (args[0] !== 'add') refuse('INPUT_USAGE', INPUT_HELP, USAGE_EXIT);
+  const positional: string[] = [];
+  let origin: string | undefined;
+  let projectsRoot: string | undefined;
+  let sameArtworkReason: string | undefined;
+  let painting = false;
+  let json = false;
+  for (let index = 1; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === '--json' && !json) json = true;
+    else if (arg === '--painting' && !painting) painting = true;
+    else if (arg === '--origin' && origin === undefined) {
+      origin = args[++index];
+      if (!origin || origin.startsWith('--') || !origin.trim()) refuse('INPUT_USAGE', 'inputs[].origin: supply --origin with non-empty source words', USAGE_EXIT);
+    } else if (arg === '--projects-root' && projectsRoot === undefined) {
+      projectsRoot = args[++index];
+      if (!projectsRoot || projectsRoot.startsWith('--') || !projectsRoot.trim()) refuse('INPUT_USAGE', 'inputs: supply --projects-root with a directory path', USAGE_EXIT);
+    } else if (arg === '--same-artwork-reason' && sameArtworkReason === undefined) {
+      sameArtworkReason = args[++index];
+      if (!sameArtworkReason || sameArtworkReason.startsWith('--') || !sameArtworkReason.trim()) refuse('INPUT_USAGE', 'inputs: supply --same-artwork-reason with a file path', USAGE_EXIT);
+    } else if (arg.startsWith('-')) refuse('INPUT_USAGE', `inputs: unexpected or repeated option '${arg}'; ${INPUT_HELP}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (positional.length < 1 || positional.length > 2 || origin === undefined) refuse('INPUT_USAGE', INPUT_HELP, USAGE_EXIT);
+  if (!painting && (projectsRoot !== undefined || sameArtworkReason !== undefined)) refuse('INPUT_USAGE', 'painting: --projects-root and --same-artwork-reason require input add --painting', USAGE_EXIT);
+  const dir = resolve(positional[1] ?? process.cwd());
+  const name = inputPath(dir, positional[0]!);
+  const file = resolve(dir, 'project.json');
+  const lock = resolve(dir, '.input.lock');
+  let fd: number;
+  try { fd = openSync(lock, 'wx'); } catch { refuse('INPUT_SOURCE_CHANGED', 'inputs: another input writer holds the project lock; wait for it to finish and retry against frozen source bytes'); }
+  let published = false;
+  try {
+    let before: Buffer;
+    try { before = readFileSync(file); } catch { refuse('PROJECT_JSON_INVALID', 'project.json: restore a readable project record before input add'); }
+    const read = readJsonObject(file);
+    if (!read.ok) refuse('PROJECT_JSON_INVALID', `project.json: ${read.error}`);
+    const project = read.value;
+    if (project.schema !== 'rig-create/project@0') refuse('SCHEMA_UNKNOWN', 'project.json.schema: input add reads rig-create/project@0');
+    if (painting && project.painting !== undefined) refuse('INPUT_PAINTING_EXISTS', `painting: '${String(project.painting)}' is already declared; retain the project's painting and register other sources without --painting`);
+    const bytes = sourceBytes(dir, name, 'inputs[].path');
+    const entry: JsonObject = { path: name, sha256: sha256(bytes), bytes: bytes.length, origin, at: new Date(now).toISOString() };
+    const existing = asArray(project.inputs).filter(isObject).find(input => text(input.path) && resolve(dir, input.path) === resolve(dir, name));
+    if (existing) {
+      if (existing.sha256 !== entry.sha256 || existing.bytes !== entry.bytes) refuse('INPUT_FILE_CHANGED', `inputs[].path: '${name}' has changed under its registered name; restore the old bytes and register a new file name`);
+      refuse('INPUT_PATH_DUPLICATE', `inputs[].path: '${name}' is already registered; keep its record and use a new name for changed bytes`);
+    }
+    const ctx: Pick<Ctx, 'dir' | 'project' | 'refusals' | 'warnings'> = { dir, project, refusals: [], warnings: [] };
+    if (project.inputs !== undefined && !Array.isArray(project.inputs)) {
+      checkInputs(ctx);
+      refuse(ctx.refusals[0]!.code, ctx.refusals[0]!.message);
+    }
+    if (painting) {
+      const same = sameArtworkFor(dir, name, String(entry.sha256), now, {
+        projectsRoot,
+        sameArtworkReason,
+        index: asArray(project.inputs).length,
+      });
+      project.painting = name;
+      if (same !== null && project.same_artwork === undefined) project.same_artwork = same;
+    }
+    project.inputs = [...asArray(project.inputs), entry];
+    checkInputs(ctx);
+    const finding = ctx.refusals[0];
+    if (finding) refuse(finding.code, finding.message);
+    try {
+      fchmodSync(fd, statSync(file).mode);
+      writeFileSync(fd, `${JSON.stringify(project, null, 2)}\n`);
+      if (!readFileSync(file).equals(before) || !sourceBytes(dir, name, 'inputs[].path').equals(bytes)) refuse('INPUT_SOURCE_CHANGED', `inputs[].path: '${name}' or project.json changed during registration; freeze both files and retry`);
+      renameSync(lock, file);
+      published = true;
+    } catch (error) {
+      if (error instanceof Refusal) throw error;
+      refuse('INPUT_WRITE_FAILED', 'inputs: could not publish the staged project.json record; restore writable project storage and retry');
+    }
+    return { stdout: json ? JSON.stringify(entry, null, 2) : `input: recorded '${name}' (${bytes.length} bytes)`, exit: 0 };
+  } finally { closeSync(fd); if (!published) unlinkSync(lock); }
+}

package/src/intake.ts

@@ -0,0 +1,158 @@
+/** Advisory intake: consume immutable producer bytes, never pixels or producer verifiers. */
+import { renameSync, writeFileSync } from 'node:fs';
+import { readFileSync } from './check-reads.ts';
+import { dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual as equal } from 'node:util';
+import { asArray, classify, isObject, type Finding, type Item } from './check.ts';
+import { choiceAdoption, literalFile, optionFile, selection, sha256, validateChoice, validateContext, validateSet } from './choices.ts';
+import { structurePathIsIgnored } from './structure.ts';
+import { readProject } from './feedback.ts';
+import { refuse } from './refusal.ts';
+import type { Json, JsonObject } from './templates.ts';
+
+export const INTAKE_SPEC = 'rig-create/intake@1';
+export const PREFLIGHT_SPEC = 'rig-parts/head-crop-preflight/1';
+export const INTAKE_QUESTION = 'intake_suitability';
+export const INTAKE_NOTES = 'Colour-adjacent ground and ground enclosed between strands: known-not-predicted (two rounds of a model sweep on a pilot did not separate them). No threshold. Silhouette stepping, source-vs-final alpha classes, patchwork runs and versioned dark retention need post-assemble outputs and are excluded.';
+const text = (v: Json | undefined): v is string => typeof v === 'string' && v.trim() !== '';
+const clock = (v: Json | undefined): number => typeof v === 'string' ? Date.parse(v) : NaN;
+const count = (v: Json | undefined): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+function invalid(why: string): never { throw Error(why); }
+
+/** Optional item for the explicit choice writers only, never global approval readers. */
+export function intakeItem(project: JsonObject): Item | undefined {
+  const intake = isObject(project.intake) ? project.intake : null;
+  const record = intake && isObject(intake.choice) ? intake.choice : null;
+  if (!record) return undefined;
+  return { id: INTAKE_QUESTION, kind: 'framing', path: 'intake.choice.answer', record, raw: record.answer ?? null, state: classify(record.answer, { collection: null }) };
+}
+
+export function intakeContext(project: JsonObject, at: number): JsonObject {
+  const intake = isObject(project.intake) ? project.intake : {};
+  const reports = asArray(intake.reports).filter(isObject).filter(r => clock(r.at) <= at);
+  const entry = reports.at(-1);
+  if (intake.spec !== INTAKE_SPEC || !entry || !isObject(entry.report)) invalid('intake.reports: record a preflight before showing the parts-stage ask');
+  return { kind: 'intake', report_id: entry.id as Json, report: entry.report };
+}
+
+/** Validate the producer's report shape; do not rederive registration or count measurements. */
+export function readIntakeReport(dir: string, binding: JsonObject): JsonObject {
+  if (!text(binding.path) || typeof binding.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(binding.sha256)) invalid('report needs a retained path and raw sha256');
+  const file = literalFile(dir, binding.path);
+  if (structurePathIsIgnored(dir, binding.path)) invalid('report must survive a clone; retain it outside ignored roots');
+  const bytes = readFileSync(file);
+  if (sha256(bytes) !== binding.sha256) invalid('report sha256 differs from retained bytes');
+  const raw: Json = JSON.parse(bytes.toString('utf8'));
+  if (!isObject(raw) || raw.spec !== PREFLIGHT_SPEC || raw.drawn_alpha_above !== 8 || raw.pixel_grid !== 'full-run') invalid('expected rig-parts/head-crop-preflight/1, native alpha > 8 on the full-run grid');
+  if (!Array.isArray(raw.head_box) || raw.head_box.length !== 4 || !raw.head_box.every(n => typeof n === 'number' && Number.isFinite(n)) || Number(raw.head_box[0]) >= Number(raw.head_box[2]) || Number(raw.head_box[1]) >= Number(raw.head_box[3])) invalid('invalid head_box');
+  for (const key of ['source_canvas', 'run_canvas']) {
+    const canvas = raw[key];
+    if (!isObject(canvas) || !count(canvas.w) || !count(canvas.h) || !canvas.w || !canvas.h) invalid(`invalid ${key}`);
+  }
+  if (!isObject(raw.registration) || typeof raw.registration.scale_source_per_run !== 'number' || !Number.isFinite(raw.registration.scale_source_per_run) || raw.registration.scale_source_per_run <= 0 || !['pad_left','pad_top'].every(k => typeof (raw.registration as JsonObject)[k] === 'number' && Number.isFinite((raw.registration as JsonObject)[k]))) invalid('invalid registration');
+  const tags = new Set<string>();
+  if (!Array.isArray(raw.layers)) invalid('layers must be an array');
+  for (const layer of raw.layers) {
+    if (!isObject(layer) || !text(layer.tag) || tags.has(layer.tag) || !count(layer.drawn_px) || !count(layer.bottom_px) || !isObject(layer.sides) || !['top_px','left_px','right_px'].every(k => count((layer.sides as JsonObject)[k]))) invalid('invalid or duplicate layer counts');
+    tags.add(layer.tag);
+    if ([layer.bottom_px, ...Object.values(layer.sides)].some(n => typeof n !== 'number' || n > Number(layer.drawn_px))) invalid('edge count exceeds drawn samples');
+  }
+  for (const key of ['spec','head_box','source_canvas','run_canvas']) if (key in binding && !equal(binding[key], raw[key])) invalid(`report binding ${key} differs from producer bytes`);
+  return raw;
+}
+export function intakeHit(report: JsonObject): boolean {
+  return asArray(report.layers).filter(isObject).some(l => isObject(l.sides) && ['top_px','left_px','right_px'].some(k => Number((l.sides as JsonObject)[k]) > 0));
+}
+function warning(code: string, path: string, why: string, remedy: string): Finding { return { code, path, message: `${path}: ${why}; ${remedy}` }; }
+
+export function intakeWarnings(dir: string, project: JsonObject): Finding[] {
+  if (project.intake === undefined) return [];
+  const warnings: Finding[] = [];
+  const addInvalid = (path: string, e: unknown) => warnings.push(warning('INTAKE_REPORT_INVALID',path,String(e),'restore the original producer report bytes first, then append a corrected entry with intake-report'));
+  const intake = project.intake;
+  if (!isObject(intake) || intake.spec !== INTAKE_SPEC || !Array.isArray(intake.reports) || !intake.reports.length) {
+    addInvalid('intake','expected rig-create/intake@1 with nonempty reports'); return warnings;
+  }
+  const ids = new Set<string>();
+  let active: JsonObject | undefined;
+  for (const [i, entry] of intake.reports.entries()) {
+    const path = `intake.reports[${i}]`;
+    try {
+      if (!isObject(entry) || !text(entry.id) || ids.has(entry.id) || !text(entry.by) || !Number.isFinite(clock(entry.at)) || !text(entry.parts_version) || !isObject(entry.report)) invalid('invalid report identity, clock, declared parts version or binding');
+      if (entry.supersedes !== undefined && (!text(entry.supersedes) || !ids.has(entry.supersedes))) invalid('supersedes must name an earlier retained entry');
+      ids.add(entry.id);
+      if (!['spec','head_box','source_canvas','run_canvas'].every(k => k in (entry.report as JsonObject))) invalid('report binding must retain spec, head_box and both canvases');
+      const raw = readIntakeReport(dir, entry.report);
+      if (!equal(entry.measurement,raw) || entry.prediction !== (intakeHit(raw) ? 'hit' : 'no-hit')) invalid('copied report fields or prediction differ from retained report');
+      if (i === intake.reports.length-1) active = entry;
+    } catch (e) { addInvalid(path,e); }
+  }
+  if (active?.prediction === 'hit') {
+    const raw = active.measurement as JsonObject;
+    const counts = asArray(raw.layers).filter(isObject).map(l => `${String(l.tag)} ${JSON.stringify(l.sides)} (bottom ${String(l.bottom_px)})`).join('; ');
+    warnings.push(warning('INTAKE_HEAD_CROP_RISK','intake.reports',`advisory native alpha > 8 before ghost cleanup: ${counts}`,'show the report-bound parts-stage intake_suitability choice; no approval is refused'));
+  }
+  const item = intakeItem(project);
+  let pending = true;
+  if (item) {
+    try {
+      if (item.record.pending_options !== undefined) {
+        const {set} = optionFile(dir,item.record.pending_options); validateSet(project,item,set); validateContext(dir,project,set,clock(set.drafted_at));
+      }
+      if (item.raw !== null) {
+        if (!isObject(item.raw) || item.raw.basis === 'inherited') invalid('intake choice must be a local per-ask record');
+        validateChoice(dir,project,item,item.raw);
+        const {set} = optionFile(dir,(item.raw.choice as JsonObject).set);
+        const chosen = selection(set,item.raw.choice as JsonObject);
+        const context = set.context as JsonObject;
+        pending = !active || context.report_id !== active.id || chosen.pending.length > 0 || (chosen.autos.length > 0 && !(isObject(item.raw.agent_decision) && 'value' in item.raw.agent_decision));
+      }
+      if (!Array.isArray(item.record.history)) invalid('intake choice history must be an array');
+      for (const answer of item.record.history) {
+        if (!isObject(answer)) invalid('invalid choice history');
+        validateChoice(dir,project,item,answer);
+      }
+    } catch (e) { pending = true; warnings.push(warning('INTAKE_CHOICE_INVALID','intake.choice',String(e),'retain and re-show report-bound options with the interview choice writers')); }
+  } else if (intake.choice !== undefined) warnings.push(warning('INTAKE_CHOICE_INVALID','intake.choice','invalid optional choice record','record a new report before showing options'));
+  if (project.stage === 'parts' && active?.prediction === 'hit' && pending) warnings.push(warning('INTAKE_CHOICE_PENDING','intake.choice','HIT report has no resolved choice bound to it',`${choiceAdoption(project) === null ? 'adopt choices with interview-options --adopt first, then ' : ''}show intake_suitability in parts and record the person’s explicit pick, Other or delegation; advisory only`));
+  return warnings;
+}
+
+export const INTAKE_HELP = `intake-report [<dir>] --id <id> --report <retained relative path> --sha256 <raw sha> --parts-version <declared version> --by <agent> [--supersedes <id>]
+  Record a parts head-crop preflight without running a producer. Offers optional intake_suitability in parts.
+intake [<dir>]
+  Show advisory counts and choice state; never refuse approval. This cannot save the first full run.`;
+export function intakeReportCommand(args: string[], now: number): string {
+  const opts: Record<string,string> = {}; const positional: string[] = [];
+  for (let i=0;i<args.length;i++) {
+    const arg = args[i] as string;
+    if (!arg.startsWith('-')) { positional.push(arg); continue; }
+    if (!['--id','--report','--sha256','--parts-version','--by','--supersedes'].includes(arg) || opts[arg] !== undefined || !args[i+1] || args[i+1]?.startsWith('--')) refuse('INTAKE_REPORT_INVALID',`intake.reports: invalid writer arguments; ${INTAKE_HELP}`);
+    opts[arg] = args[++i] as string;
+  }
+  if (positional.length > 1 || !['--id','--report','--sha256','--parts-version','--by'].every(k => opts[k]?.trim())) refuse('INTAKE_REPORT_INVALID',`intake.reports: missing writer arguments; ${INTAKE_HELP}`);
+  const dir = resolve(positional[0] ?? process.cwd()); const {file,project} = readProject(dir);
+  const next = structuredClone(project);
+  try {
+    if (project.stage !== 'parts') invalid('offer intake only in the parts stage at report time');
+    if (next.intake !== undefined && intakeWarnings(dir,next).some(w => w.code === 'INTAKE_REPORT_INVALID')) invalid('restore existing retained intake reports before appending');
+    if (next.intake === undefined) next.intake = {spec:INTAKE_SPEC,reports:[],choice:{id:INTAKE_QUESTION,answer:null,history:[]}};
+    const intake = next.intake as JsonObject; const reports = intake.reports as Json[];
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(opts['--id'] as string) || reports.some(r => isObject(r) && r.id === opts['--id'])) invalid('use a new report id');
+    const binding: JsonObject = {path:opts['--report'] as string,sha256:opts['--sha256'] as string};
+    const measurement = readIntakeReport(dir,binding);
+    for (const k of ['spec','head_box','source_canvas','run_canvas']) binding[k] = measurement[k] as Json;
+    reports.push({id:opts['--id'] as string,report:binding,parts_version:opts['--parts-version'] as string,measurement,prediction:intakeHit(measurement)?'hit':'no-hit',by:opts['--by'] as string,at:new Date(now).toISOString(),...(opts['--supersedes']?{supersedes:opts['--supersedes']}:{})});
+    const errors = intakeWarnings(dir,next).filter(w => w.code === 'INTAKE_REPORT_INVALID');
+    if (errors.length) invalid(errors[0]?.message ?? 'invalid report');
+    const tmp = join(dirname(file),`.intake-${crypto.randomUUID()}.tmp`);
+    writeFileSync(tmp,`${JSON.stringify(next,null,2)}\n`,{flag:'wx'}); renameSync(tmp,file);
+    return intakeCommand([dir]);
+  } catch (e) { refuse('INTAKE_REPORT_INVALID',`intake.reports: ${String(e)}; retain correct report bytes and retry intake-report`); }
+}
+export function intakeCommand(args: string[]): string {
+  if (args.length > 1 || args.some(a => a.startsWith('-'))) refuse('INTAKE_REPORT_INVALID',`intake: expected a project folder; ${INTAKE_HELP}`);
+  const dir = resolve(args[0] ?? process.cwd()); const {project} = readProject(dir);
+  const intake = isObject(project.intake) ? project.intake : null;
+  return JSON.stringify({advisory:true,notes:INTAKE_NOTES,intake:intake ?? 'not-measured',warnings:intakeWarnings(dir,project)},null,2);
+}

package/src/interview.ts

@@ -0,0 +1,53 @@
+/**
+ * `rig-create interview --check [<project dir>] [--json]`: the command around
+ * src/check.ts. Prints every finding, exits 0 when clean, 1 when anything is
+ * refused, 2 on a usage error. `--json` prints the report as one JSON object
+ * for agents and later checks (#6, #8, #9) to read.
+ */
+import { checkProject, formatReport } from './check.ts';
+import { checkCollection, collectionDirOf, formatCollectionReport } from './pins-check.ts';
+import { refuse, USAGE_EXIT } from './refusal.ts';
+
+export interface CommandResult {
+  stdout: string;
+  exit: number;
+}
+
+export const INTERVIEW_HELP = `interview:
+  --check          check project.json: each current interview has its guides, later rigging guides wait for approved parts,
+                   every plan step rests on an answer,
+                   every stage moved has its sign-off, every @rig-c/parts section has a place,
+                   every config section of a version cites its guide, every bounce is answered by a later version (docs/CHECKS.md)
+  <project dir>    the project folder (default: the current directory); a collection folder (or its collection.json)
+                   runs the collection check (see collection --check)
+  --json           print the report as JSON (ok, stage, parts, derived, provenance[], feedback[], refusals[], warnings[])`;
+
+export function interviewCommand(args: string[], now: number): CommandResult {
+  let check = false;
+  let json = false;
+  const positional: string[] = [];
+  for (const arg of args) {
+    if (arg === '--check') check = true;
+    else if (arg === '--json') json = true;
+    else if (arg.startsWith('-')) refuse('UNKNOWN_OPTION', `interview does not take ${arg}`, USAGE_EXIT);
+    else positional.push(arg);
+  }
+  if (!check) refuse('INTERVIEW_MODE_MISSING', 'interview needs --check: rig-create interview --check [<project dir>]', USAGE_EXIT);
+  if (positional.length > 1) {
+    refuse('INTERVIEW_TOO_MANY_ARGUMENTS', `interview --check takes one folder, got ${positional.join(' ')}`, USAGE_EXIT);
+  }
+  const target = positional[0] ?? process.cwd();
+  // A collection is checked by the collection check (src/pins-check.ts), not refused as SCHEMA_UNKNOWN.
+  const collectionDir = collectionDirOf(target);
+  if (collectionDir !== null) {
+    const report = checkCollection(collectionDir);
+    return { stdout: json ? JSON.stringify(report, null, 2) : formatCollectionReport(report), exit: report.ok ? 0 : 1 };
+  }
+  const report = checkProject(target, undefined, { now });
+  return {
+    stdout: json ? JSON.stringify(report, null, 2) : [formatReport(report),
+      ...(report.invariants === null ? [] : [`invariants: ${report.invariants.entries.length} entries, ${report.invariants.gaps.length} gaps (translated from the guide; not a rig check)`]),
+    ].join('\n'),
+    exit: report.ok ? 0 : 1,
+  };
+}