rig-create 0.0.0-stage → 1.0.1

package/src/provenance.ts

@@ -0,0 +1,301 @@
+import { fixedNotApplicableCamera } from './direction-citation.ts';
+/**
+ * Provenance per config section (docs/INTERVIEW.md § Provenance): every
+ * section of the config a version was built from cites the guide sentence or
+ * the delegation it rests on, in `versions[].provenance`. Run as part of
+ * `interview --check`, over the same `Ctx`; the codes are in docs/CHECKS.md
+ * § Provenance.
+ *
+ * Which sections a config has:
+ * - The config file named in `provenance.config.path` is read when it is under
+ *   the project folder and its sha256 matches `provenance.config.sha256`; its
+ *   top-level keys are the sections, and each must be cited. A rig config's
+ *   records (`x-…`) and annotations (`note`, `…_note`) are not sections.
+ * - Otherwise (`derived/` is not kept, so this is the usual case) the sections
+ *   `provenance.sections` lists are the ones checked, and the report says the
+ *   config's own list could not be verified (`provenance[].config`).
+ *
+ * Which sections need a citation:
+ * - `kind: "rig"`: the config is a `@rig-c/parts` config; a section placed
+ *   `none` in src/waypoints.ts (`key`, `note`, `generation`, …) is not a
+ *   direction call and needs none. Every other section does.
+ * - `kind: "post"`: the config is the post tool's, whose sections are not
+ *   parts sections and are not on the placement table; every one of them is a
+ *   direction call and needs a citation, and it cites a post item (or a
+ *   framing answer), never a rig waypoint.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from './check-reads.ts';
+import { relative, resolve, sep } from 'node:path';
+
+import { answered, asArray, asString, collectionQuestion, isDecision, isObject, itemFor, type Ctx, type Item } from './check.ts';
+import type { PartsSections } from './parts-sections.ts';
+import type { Json, JsonObject } from './templates.ts';
+import { SECTION_PLACEMENT, WAYPOINT_ASKS } from './waypoints.ts';
+
+/** How the version's section list was obtained. */
+export type ConfigRead =
+  | 'verified' // the config file was read and its hash matched; its keys are the sections
+  | 'absent' // no file at provenance.config.path under the project; the listed sections were checked
+  | 'changed' // the file is there but its hash differs; the listed sections were checked
+  | 'unreadable'; // the file is there but is not a JSON object, or the path leaves the project
+
+export interface ProvenanceSummary {
+  readonly version: string;
+  readonly kind: 'rig' | 'post';
+  readonly config_path: string | null;
+  readonly config: ConfigRead;
+  /** The sections checked: the config's keys when verified, else the ones provenance lists. */
+  readonly sections: string[];
+}
+
+function versionLabel(v: JsonObject, index: number): string {
+  return typeof v.n === 'number' ? `versions[v${v.n}]` : `versions[${index}]`;
+}
+
+function sha256(file: string): string | null {
+  try {
+    return createHash('sha256').update(readFileSync(file)).digest('hex');
+  } catch {
+    return null; // a directory or an unreadable file: reported as `unreadable`, never a crash
+  }
+}
+
+/**
+ * A top-level key parts reads nothing from: a record (`x-` and at least one
+ * character more, any JSON) or an annotation (`note` or `<name>_note`, holding
+ * a string). Records are tested first, so `x-seed_note` is a record whatever it
+ * holds. This mirrors `isRecordKey` and `isDoorKey` with the loader's string
+ * test for annotations in @rig-c/parts `src/config.ts` (AUTHORING §3); `xstatus`,
+ * `x_status`, `X-status` and a bare `x-` are not record names.
+ */
+function isAnnotationOrRecord(key: string, value: unknown): boolean {
+  if (key.length > 2 && key.startsWith('x-')) return true;
+  return (key === 'note' || key.endsWith('_note')) && typeof value === 'string';
+}
+
+/**
+ * Reads the config's top-level keys when the file is the one the version was
+ * built from, leaving out the keys `skip` is true for (a rig config's records
+ * and annotations).
+ */
+function readConfigSections(
+  dir: string,
+  config: Json | undefined,
+  skip: (key: string, value: unknown) => boolean = () => false,
+): { read: ConfigRead; path: string | null; sections: string[] | null; document?: JsonObject } {
+  const path = isObject(config) ? asString(config.path) : null;
+  if (path === null) return { read: 'absent', path: null, sections: null };
+  const file = resolve(dir, path);
+  const rel = relative(dir, file);
+  if (rel === '' || rel.startsWith('..') || rel.startsWith(sep)) return { read: 'unreadable', path, sections: null };
+  if (!existsSync(file)) return { read: 'absent', path, sections: null };
+  const expected = isObject(config) ? asString(config.sha256) : null;
+  const actual = sha256(file);
+  if (actual === null) return { read: 'unreadable', path, sections: null };
+  if (expected === null || actual !== expected) return { read: 'changed', path, sections: null };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return { read: 'unreadable', path, sections: null };
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return { read: 'unreadable', path, sections: null };
+  return { read: 'verified', path, document: parsed as JsonObject, sections: Object.entries(parsed).filter(([k, v]) => !skip(k, v)).map(([k]) => k) };
+}
+
+/**
+ * The answers a citation may rest on: the current one, and every earlier one
+ * in the question's `history[]` — a version built before an answer was
+ * replaced was built from the answer as it was then (INTERVIEW.md § Answer
+ * shape: a replaced answer moves whole into `history[]`).
+ */
+export function answersOf(item: Item, ctx: Pick<Ctx, 'collection'>): JsonObject[] {
+  const s = item.state;
+  const current = s.state === 'user' || s.state === 'delegated' || s.state === 'not_applicable' ? [s.answer] : [];
+  const history = asArray(item.record.history).filter(isObject);
+  // An inherited answer's earlier versions live in the collection question's history, not the member's.
+  if (isObject(item.raw) && item.raw.basis === 'inherited' && ctx.collection !== null && isObject(item.raw.from)) {
+    const question = asString(item.raw.from.question);
+    const source = question === null ? undefined : collectionQuestion(ctx.collection, question);
+    if (source !== undefined) history.push(...asArray(source.history).filter(isObject));
+  }
+  return [...current, ...history];
+}
+
+/** The stored sentences a quote may be taken from: each answer's `verbatim` and every `additions[].verbatim`. */
+function sentences(item: Item, ctx: Pick<Ctx, 'collection'>): string[] {
+  const out: string[] = [];
+  for (const answer of answersOf(item, ctx)) {
+    const verbatim = asString(answer.verbatim);
+    if (verbatim !== null) out.push(verbatim);
+    for (const add of asArray(answer.additions)) if (isObject(add) && asString(add.verbatim) !== null) out.push(add.verbatim as string);
+  }
+  return out;
+}
+
+/** A delegation the citation can rest on: an answer that is delegated, or a user answer that left part open, with the agent's decision written. */
+function delegationOf(item: Item, ctx: Pick<Ctx, 'collection'>): 'ok' | 'not-delegated' | 'undecided' {
+  let undecided = false;
+  for (const answer of answersOf(item, ctx)) {
+    if (answer.delegated === true) {
+      if (isDecision(answer.agent_decision)) return 'ok';
+      undecided = true;
+    } else if (answer.delegated === false && isDecision(answer.agent_decision)) {
+      return 'ok';
+    }
+  }
+  return undecided ? 'undecided' : 'not-delegated';
+}
+
+/** Answers that explicitly record this canonical ask. Keep each answer intact for evidence checks. */
+export function askAnswers(item: Item, ctx: Pick<Ctx, 'collection'>, id: string): JsonObject[] {
+  return answersOf(item, ctx).filter((answer) => asArray(answer.asks).some((entry) => isObject(entry) && entry.id === id));
+}
+
+function checkCitationAsks(ctx: Ctx, item: Item, raw: JsonObject, path: string): void {
+  const answers = answersOf(item, ctx);
+  if (!('asks' in raw)) {
+    if (answers.some((answer) => Array.isArray(answer.asks))) {
+      ctx.warnings.push({ code: 'CITATION_ASKS_MISSING', path, message: `${path}: guide '${item.id}' has per-ask coverage; add asks naming the recorded ask ids this citation rests on` });
+    }
+    return;
+  }
+  if (!Array.isArray(raw.asks) || raw.asks.length === 0 || raw.asks.some((id) => typeof id !== 'string' || id === '')
+    || new Set(raw.asks).size !== raw.asks.length) {
+    ctx.refusals.push({ code: 'CITATION_ASKS_MALFORMED', path, message: `${path}: guide '${item.id}' needs asks as a nonempty list of unique ask ids; name each recorded ask once` });
+    return;
+  }
+  for (const id of raw.asks as string[]) {
+    if (!(item.kind !== 'waypoint' && id === item.id) && !WAYPOINT_ASKS[item.id]?.some((ask) => ask.id === id)) {
+      ctx.refusals.push({ code: 'CITATION_ASK_UNKNOWN', path, message: `${path}: guide '${item.id}' has no ask '${id}'; choose an id from its waypoint asks` });
+      continue;
+    }
+    const recorded = askAnswers(item, ctx, id);
+    if (recorded.length === 0) {
+      ctx.refusals.push({ code: 'CITATION_ASK_UNRECORDED', path, message: `${path}: guide '${item.id}' does not record ask '${id}'; record its user answer or delegation before citing it` });
+      continue;
+    }
+    const quote = asString(raw.quote);
+    const valid = recorded.some((answer) => asArray(answer.asks).some((entry) => {
+      if (!isObject(entry) || entry.id !== id) return false;
+      if (entry.state === 'delegated') return raw.delegated === true && isDecision(answer.agent_decision);
+      if (entry.state !== 'user' || raw.delegated === true || quote === null || quote === '') return false;
+      return [answer.verbatim, ...asArray(answer.additions).filter(isObject).map((add) => add.verbatim)]
+        .some((sentence) => typeof sentence === 'string' && sentence.includes(quote));
+    }));
+    if (!valid) ctx.refusals.push({ code: 'CITATION_ASK_STATE', path, message: `${path}: guide '${item.id}' ask '${id}' contradicts this citation; quote the user words for a user ask, or use delegated: true with a decided delegation on the same answer` });
+  }
+}
+
+function needsCitation(kind: 'rig' | 'post', section: string): boolean {
+  if (kind === 'post') return true;
+  return SECTION_PLACEMENT[section]?.kind !== 'none';
+}
+
+export function checkEntry(ctx: Ctx, kind: 'rig' | 'post', path: string, raw: Json): void {
+  if (!isObject(raw)) {
+    ctx.refusals.push({ code: 'ENTRY_UNCITED', path, message: `${path}: an entry is an object { entry, guide, quote | delegated: true }` });
+    return;
+  }
+  const label = asString(raw.entry);
+  const named = label === null ? path : `${path} ('${label}')`;
+  const quote = asString(raw.quote);
+  const delegated = raw.delegated === true;
+  const guide = asString(raw.guide);
+  if ((quote === null || quote === '') && !delegated) {
+    ctx.refusals.push({ code: 'ENTRY_UNCITED', path, message: `${named}: neither a quote nor delegated: true; a decision nobody gave — find the sentence, ask for one, or remove the entry` });
+    return;
+  }
+  if (guide === null) {
+    ctx.refusals.push({ code: 'CITATION_GUIDE_UNKNOWN', path, message: `${named}: no guide id; name the answer it rests on` });
+    return;
+  }
+  const item = itemFor(ctx, guide);
+  if (item === undefined) {
+    ctx.refusals.push({ code: 'CITATION_GUIDE_UNKNOWN', path, message: `${named}: cites '${guide}', which is no framing, waypoint or post item of this interview` });
+    return;
+  }
+  if (!answered(item.state)) {
+    ctx.refusals.push({ code: 'CITATION_GUIDE_SILENT', path, message: `${named}: cites '${guide}', which has no answer (${item.path} is ${item.state.state})` });
+    return;
+  }
+  if (kind === 'post' && item.kind === 'waypoint') {
+    ctx.refusals.push({ code: 'CITATION_WRONG_PHASE', path, message: `${named}: a post version cites rig waypoint '${guide}'; a post config section rests on a post item (or a framing answer) — rig feedback makes a new rig version` });
+    return;
+  }
+  checkCitationAsks(ctx, item, raw, path);
+  if (quote !== null && quote !== '') {
+    if (!sentences(item, ctx).some((s) => s.includes(quote))) {
+      ctx.refusals.push({ code: 'QUOTE_NOT_FOUND', path, message: `${named}: quote ${JSON.stringify(quote)} is in no verbatim or additions[] of ${item.path} (current or history[]); a quote is an exact fragment of a stored sentence` });
+    }
+  } else {
+    const d = delegationOf(item, ctx);
+    if (d === 'not-delegated') {
+      ctx.refusals.push({ code: 'DELEGATION_NOT_GIVEN', path, message: `${named}: cites '${guide}' as delegated, but no answer at ${item.path} (current or history[]) is a delegation or carries an agent_decision — the user did not hand this over` });
+    } else if (d === 'undecided') {
+      ctx.refusals.push({ code: 'DELEGATION_NOT_GIVEN', path, message: `${named}: cites the delegation at '${guide}', but ${item.path} has no agent_decision; the decision the section follows is not written` });
+    }
+  }
+}
+
+/** Checks every `versions[]` entry of kind `rig` or `post`; returns what was read, per version, for the report. */
+export function checkProvenance(ctx: Ctx, parts: PartsSections | null): ProvenanceSummary[] {
+  const summaries: ProvenanceSummary[] = [];
+  const known = new Set([...Object.keys(SECTION_PLACEMENT), ...(parts?.sections ?? [])]);
+  asArray(ctx.project.versions).forEach((v, index) => {
+    if (!isObject(v) || v.pre_interview === true || (v.kind !== 'rig' && v.kind !== 'post')) return;
+    const kind = v.kind;
+    const label = versionLabel(v, index);
+    const prov = v.provenance;
+    if (!isObject(prov) || !isObject(prov.sections)) {
+      ctx.refusals.push({ code: 'PROVENANCE_MISSING', path: `${label}.provenance`, message: `${label}.provenance has no sections{}; a version built from a config cites, per section, the guide it rests on` });
+      return;
+    }
+    const cited = prov.sections;
+    // A rig config's records and annotations are not sections and need no citation; a section parts or the table knows is kept.
+    const read = readConfigSections(ctx.dir, prov.config, kind === 'rig' ? (k, val) => !known.has(k) && isAnnotationOrRecord(k, val) : undefined);
+    const sections = kind === 'post' && isObject(prov.direction) ? ['camera', 'timing'] : read.sections ?? Object.keys(cited);
+    summaries.push({ version: label, kind, config_path: read.path, config: read.read, sections });
+    if (read.read === 'changed') {
+      ctx.warnings.push({ code: 'PROVENANCE_CONFIG_CHANGED', path: `${label}.provenance.config`, message: `${label}.provenance.config: ${read.path} is present but its sha256 is not the recorded one; the sections listed were checked, not the file's` });
+    }
+    for (const section of sections) {
+      const path = `${label}.provenance.sections[${section}]`;
+      if (kind === 'rig' && !known.has(section)) {
+        ctx.refusals.push({ code: 'SECTION_UNKNOWN', path, message: `${path}: '${section}' is no @rig-c/parts${parts === null ? '' : ` ${parts.version}`} section; a misspelt name leaves the real section uncited` });
+        continue;
+      }
+      const entries = asArray(cited[section]);
+      if (entries.length === 0) {
+        if (needsCitation(kind, section)) {
+          ctx.refusals.push({ code: 'SECTION_UNCITED', path, message: `${path}: the config has section '${section}' and nothing cites the guide or delegation it rests on` });
+        }
+        continue;
+      }
+      entries.forEach((e, i) => {
+        const item = isObject(e) && typeof e.guide === 'string' ? itemFor(ctx, e.guide) : undefined;
+        if (kind === 'post' && isObject(prov.direction) && fixedNotApplicableCamera(section, item, e, read.document)) return;
+        checkEntry(ctx, kind, `${path}[${i}]`, e);
+      });
+    }
+    // A citation under a key the config listing skipped (a record or annotation) is still no section.
+    if (kind === 'rig') {
+      for (const section of Object.keys(cited)) {
+        if (known.has(section) || sections.includes(section)) continue;
+        const path = `${label}.provenance.sections[${section}]`;
+        ctx.refusals.push({ code: 'SECTION_UNKNOWN', path, message: `${path}: '${section}' is no @rig-c/parts${parts === null ? '' : ` ${parts.version}`} section; a misspelt name leaves the real section uncited` });
+      }
+    }
+  });
+  return summaries;
+}
+
+/** Lines for the human report: one per version whose config could not be read, so an unverified section list is said, not implied. */
+export function formatProvenance(summaries: readonly ProvenanceSummary[]): string[] {
+  const unverified = summaries.filter((s) => s.config !== 'verified');
+  if (summaries.length === 0) return [];
+  const head = `  provenance: ${summaries.length} version${summaries.length === 1 ? '' : 's'} checked`;
+  if (unverified.length === 0) return [`${head}; every config read`];
+  return [`${head}; config not read for ${unverified.map((s) => `${s.version} (${s.config})`).join(', ')} — the sections provenance lists were checked`];
+}

package/src/record-direction-target.ts

@@ -0,0 +1,26 @@
+/** Resolve only the post approved in a sealed decision record, never a UI selector. */
+import { asArray, isObject } from './check.ts';
+import { collectReopens, liveSignoff } from './reopen.ts';
+import { acceptedReviewVerdict } from './review.ts';
+import { refuse } from './refusal.ts';
+import type { JsonObject } from './templates.ts';
+
+export function recordDirectionTarget(project: JsonObject, at = Infinity): number | null {
+  const reopens = collectReopens(project, []);
+  const posts = asArray(project.versions).filter(isObject).filter(version => version.kind === 'post'
+    && Number.isSafeInteger(version.n) && Number(version.n) > 0
+    && Number.isFinite(Date.parse(String(version.at))) && Date.parse(String(version.at)) <= at
+    && liveSignoff(reopens, 'post', Date.parse(String(version.at))));
+  const current = posts.at(-1);
+  if (!current || asArray(project.versions).filter(isObject).filter(version => version.n === current.n).length !== 1) return null;
+  const index = acceptedReviewVerdict(current, 'direction-review');
+  const verdict = index >= 0 ? asArray(current.verdicts)[index] : undefined;
+  return isObject(verdict) && Number.isFinite(Date.parse(String(verdict.at))) && Date.parse(String(verdict.at)) <= at
+    && liveSignoff(reopens, 'direction-review', Date.parse(String(verdict.at))) ? Number(current.n) : null;
+}
+
+export function requireRecordDirectionTarget(project: JsonObject, at = Infinity): number {
+  const version = recordDirectionTarget(project, at);
+  if (version === null) refuse('REVIEW_ACT_RECORD_TARGET_INVALID', 'project.json.versions: the frozen record does not bind one current live post with an accepted direction-review verdict; resolve ambiguous or stale verdicts through the writers and publish the record again');
+  return version;
+}

package/src/record-input.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from './check-reads.ts';
+
+import { refuse, USAGE_EXIT } from './refusal.ts';
+
+/** Decode valid UTF-8 without removing a BOM, spaces, CRLFs or the final newline. */
+export function readVerbatim(file: string): string {
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(file === '-' ? 0 : file);
+  } catch (error) {
+    refuse('VERBATIM_UNREADABLE', `${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    refuse('VERBATIM_INVALID_UTF8', 'verbatim input must be valid UTF-8 to round-trip through project.json', USAGE_EXIT);
+  }
+}

package/src/refusal-baseline.ts

@@ -0,0 +1,55 @@
+/**
+ * The refusals a record already carries (docs/PROJECT.md § Refusals a record already carries).
+ *
+ * A writer's baseline is `checkProject` on the record as read, at write time. It is never stored
+ * in the record. A candidate refusal is new when the baseline does not cover it: findings match
+ * by code and path, counting multiplicity, so the same code at a different path is new. Removing
+ * a carried refusal is always allowed. A check that stopped early (an unreadable record, schema or
+ * stage) validated nothing after that point, so it supplies no baseline to any writer: every writer
+ * takes its baseline through `baselineOf` or `carriedRefusals`, and a stored pending-answer baseline
+ * does not stand in for a stopped-early check. `advance` does not use this: it still needs 0 refusals.
+ */
+import { checkProject, type CheckReport, type Finding } from './check.ts';
+import type { JsonObject } from './templates.ts';
+
+type CheckOptions = Parameters<typeof checkProject>[2];
+
+export const findingKey = (finding: Pick<Finding, 'code' | 'path'>): string => JSON.stringify([finding.code, finding.path]);
+
+/** Count findings by code and path. */
+export function countFindings(findings: Iterable<Pick<Finding, 'code' | 'path'>>): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const finding of findings) counts.set(findingKey(finding), (counts.get(findingKey(finding)) ?? 0) + 1);
+  return counts;
+}
+
+/** A check stops early on an unreadable record, an unknown schema or an unknown stage, and reads nothing after it. */
+export function stoppedEarly(report: CheckReport): boolean {
+  return report.stage === null;
+}
+
+/** The baseline a check report supplies: its refusals counted by code and path, or none when the check stopped early. */
+export function baselineOf(report: CheckReport): Map<string, number> {
+  return stoppedEarly(report) ? new Map() : countFindings(report.refusals);
+}
+
+/** The baseline of a record as read, at write time. */
+export function carriedRefusals(dir: string, before: JsonObject, options: CheckOptions): Map<string, number> {
+  return baselineOf(checkProject(dir, structuredClone(before), options));
+}
+
+/** The findings in `after` that `baseline` does not cover, in check order. The baseline is not changed. */
+export function newFindings(baseline: ReadonlyMap<string, number>, after: readonly Finding[]): Finding[] {
+  const left = new Map(baseline);
+  return after.filter(finding => {
+    const count = left.get(findingKey(finding)) ?? 0;
+    left.set(findingKey(finding), count - 1);
+    return count <= 0;
+  });
+}
+
+/** The candidate's check refusals that the record as read did not already carry. */
+export function newRefusals(dir: string, before: JsonObject, candidate: JsonObject, options: CheckOptions): Finding[] {
+  const baseline = carriedRefusals(dir, before, options);
+  return newFindings(baseline, checkProject(dir, candidate, options).refusals);
+}

package/src/refusal.ts

@@ -0,0 +1,30 @@
+/**
+ * A named refusal: a stable code a caller (or a test) can match on, a message
+ * naming the object refused, and the exit code the CLI leaves with.
+ *
+ * Every command refuses through this, so `interview --check` and later
+ * commands print and exit the same way `init` does.
+ */
+export class Refusal extends Error {
+  readonly code: string;
+  readonly exitCode: number;
+
+  constructor(code: string, message: string, exitCode = 1) {
+    super(message);
+    this.name = 'Refusal';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+export function refuse(code: string, message: string, exitCode = 1): never {
+  throw new Refusal(code, message, exitCode);
+}
+
+/** The one-line form printed to stderr: `rig-create: CODE: message`. */
+export function formatRefusal(refusal: Refusal): string {
+  return `rig-create: ${refusal.code}: ${refusal.message}`;
+}
+
+/** Exit code for a usage error (unknown command, unknown option, missing argument). */
+export const USAGE_EXIT = 2;

package/src/reopen-lapses.ts

@@ -0,0 +1,80 @@
+/**
+ * The approvals a reopen voided and nothing has restored yet (rig-c/create#220). A reopen is
+ * legitimate, so each one is a WARN naming the record, the reopen and the act that restores it.
+ * Liveness is the same `liveSignoff` and rig-version `live` the gates read; this module only
+ * names which reopen did it. Amendment lapses are listed by the report's `amendments[].lapsed`.
+ */
+import { asArray, collectSignoffs, isObject, type Finding } from './check.ts';
+import { collectReopens, liveSignoff, reopenIndex, type Reopen } from './reopen.ts';
+import { acceptedReviewVerdict, latestAccepted, readVersions } from './review.ts';
+import { PARTS_REVIEW, RIG_REVIEW, stageIndex } from './stages.ts';
+import type { JsonObject } from './templates.ts';
+
+const DIRECTION_REVIEW = 'direction-review';
+
+/** The earliest reopen (amendments excluded) that voids an approval of `stage` made at `at`. */
+function voidingReopen(project: JsonObject, events: readonly Reopen[], stage: string, at: number): string | null {
+  const cutoff = events.filter(e => !('index' in e) && stageIndex(e.stage) <= stageIndex(stage) && !(at > e.at))
+    .reduce<Reopen | null>((a, e) => (a === null || e.at < a.at ? e : a), null);
+  return cutoff === null ? null
+    : `the reopen to ${cutoff.stage} at ${new Date(cutoff.at).toISOString()} (reopens[${reopenIndex(project, cutoff)}])`;
+}
+
+function signoffRemedy(stage: string, checkpoint: string | null): string {
+  if (checkpoint !== null) return `ask the person to approve checkpoint ${checkpoint} again in the review tool and record it with rig-create signoff ${stage} --checkpoint ${checkpoint}`;
+  if (stage === PARTS_REVIEW) return 'ask the person to review the parts again in the review tool and record the verdict with rig-create parts-review --draft <id> --from-review-cli followed by signoff parts-review --draft <id> --diff-report <report>';
+  if (stage === RIG_REVIEW || stage === DIRECTION_REVIEW) return `ask the person to accept a live version again at ${stage} in the review tool, record it with rig-create review <n> --verdict accepted --review ${stage}, and sign with rig-create signoff ${stage}`;
+  return `ask the person to sign ${stage} again in the review tool and record it with rig-create signoff ${stage}`;
+}
+
+/** One WARN per lapsed approval (the latest record of each), until a live approval of the same kind exists. */
+export function reopenLapseWarnings(project: JsonObject): Finding[] {
+  const events = collectReopens(project, []);
+  if (!events.some(e => !('index' in e))) return [];
+  const out: Finding[] = [];
+  const latest = new Map<string, { index: number; stage: string; checkpoint: string | null; by: string }>();
+  const restored = new Set<string>();
+  for (const s of collectSignoffs(project, [])) {
+    if (stageIndex(s.stage) < 0) continue;
+    const key = `${s.stage}\u0000${s.checkpoint ?? ''}`;
+    if (liveSignoff(events, s.stage, s.at)) {
+      restored.add(key);
+      continue;
+    }
+    const by = voidingReopen(project, events, s.stage, s.at);
+    if (by !== null) latest.set(key, { index: s.index, stage: s.stage, checkpoint: s.checkpoint, by });
+  }
+  for (const [key, s] of latest) {
+    if (restored.has(key)) continue;
+    const path = `signoffs[${s.index}]`;
+    const what = s.checkpoint === null ? `the ${s.stage} sign-off` : `the ${s.stage} checkpoint ${s.checkpoint} sign-off`;
+    out.push({ code: 'REOPEN_SIGNOFF_LAPSED', path, message: `${path}: ${what} was voided by ${s.by}; ${signoffRemedy(s.stage, s.checkpoint)}` });
+  }
+
+  const versions = readVersions(project);
+  if (latestAccepted(versions) === null) {
+    const rig = versions.rigs.filter(r => !r.live && r.accepted !== null).reduce<(typeof versions.rigs)[number] | null>((a, r) => (a === null || r.n > a.n ? r : a), null);
+    const by = rig === null ? null : voidingReopen(project, events, RIG_REVIEW, Date.parse(rig.at ?? ''));
+    if (rig !== null && rig.accepted !== null && by !== null) {
+      const path = `${rig.path}.verdicts[${rig.accepted.verdict}]`;
+      out.push({ code: 'REOPEN_VERDICT_LAPSED', path, message: `${path}: the rig-review acceptance of rig v${rig.n} was voided by ${by}; register a new rig version with rig-create rig-version <n>, ask the person to review it in the review tool, and record the acceptance with rig-create review <n> --verdict accepted --review rig-review` });
+    }
+  }
+
+  let direction: { path: string; n: number; at: number } | null = null;
+  let directionLive = false;
+  for (const v of asArray(project.versions)) {
+    if (!isObject(v) || v.kind !== 'post' || typeof v.n !== 'number') continue;
+    const index = acceptedReviewVerdict(v, DIRECTION_REVIEW);
+    const verdict = asArray(v.verdicts)[index];
+    if (index < 0 || !isObject(verdict)) continue;
+    const at = Date.parse(String(verdict.at));
+    if (liveSignoff(events, DIRECTION_REVIEW, at)) directionLive = true;
+    else if (direction === null || at > direction.at) direction = { path: `versions[v${v.n}].verdicts[${index}]`, n: v.n, at };
+  }
+  const by = direction === null || directionLive ? null : voidingReopen(project, events, DIRECTION_REVIEW, direction.at);
+  if (direction !== null && by !== null) {
+    out.push({ code: 'REOPEN_VERDICT_LAPSED', path: direction.path, message: `${direction.path}: the direction-review acceptance of post v${direction.n} was voided by ${by}; ask the person to review a live post version in the review tool and record the acceptance with rig-create review <n> --verdict accepted --review direction-review` });
+  }
+  return out;
+}