@pareto4/pp-core 1.12.1 → 1.17.1

package/scripts/vault-calibrate.cjs

@@ -0,0 +1,996 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * @file vault-calibrate.cjs — LANE 2 of Phase 6's validation split
+ * (Vault Assurance #71924, phase 06 plan 08; D-06-05 … D-06-08, D-06-12,
+ * VERIFY-03).
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * Calibration answers a question no deterministic test can: does the agent that
+ * judges prose practices actually catch a seeded violation, and does it stay
+ * quiet on a compliant near-miss? An agent run is non-deterministic and needs a
+ * live session, so this harness NEVER makes a model call. It owns only the
+ * halves that are code:
+ *
+ *   `--prepare`  materialises the four graded fixture projects from the SHARED
+ *                fixture module and prints the operator instruction — the
+ *                `/pp-vault-review` run happens in a live session, through the
+ *                normal command and agent machinery.
+ *   `--ingest`   reads the four produced `*-VAULT-REVIEW.md` artifacts,
+ *                validates each one's SHAPE with the shipped validator, derives
+ *                the two directions, and writes the dated record.
+ *
+ * ## When to run it (D-06-07)
+ *
+ * When the reviewer prompt changes (`agents/pp-vault-reviewer.md` or
+ * `pp-core/references/verifier-practice-verdicts.md`) or when the practice set
+ * changes. NOT on every commit, NOT in CI, and NOT in `npm test`: suite `all`
+ * collects every `tests/*.test.cjs` marker, and this repository's whole
+ * verification method is a failing-NAME diff over that suite. A live model run
+ * inside it would corrupt the one instrument this project trusts. This file is
+ * therefore in `scripts/`, reachable only through `npm run vault:calibrate`,
+ * and it is absent from `lint:ci` and from the test chain.
+ *
+ * ## It records; it never gates (D-06-08, VERIFY-03)
+ *
+ * EVERY path exits 0. A failed direction is written into the record behind a
+ * leading marker line and changes nothing else: no config is written anywhere
+ * in this file, no gate consults the record, and nothing is auto-disabled. A
+ * human reads it and decides. A non-zero exit appears only for an OPERATIONAL
+ * failure the operator must fix before a run means anything — an unwritable
+ * record home — never because a fixture drew a FAIL.
+ *
+ * ## Lane 3 limit
+ *
+ * Four known cases bound the judge on four known inputs. They say nothing about
+ * the fifty-fourth practice on a real phase. Calibration is not coverage, and
+ * the record says so in its own text.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.join(__dirname, '..');
+
+/** The compiled leaf. Shape validation and both arithmetic lines come from here. */
+const reviewModule = require(path.join(REPO_ROOT, 'pp-core', 'bin', 'lib', 'vault-review.cjs'));
+
+/** Where the shared graded fixture module (06-03) lives, relative to the repo root. */
+const FIXTURE_MODULE_REL = path.join('tests', 'helpers', 'vault-review-fixtures.cjs');
+
+let _fixtures = null;
+
+/**
+ * The shared graded fixture module (06-03), required LAZILY and cached.
+ *
+ * Lane 1 measures the same four projects this lane runs the agent against, so
+ * the two cannot disagree about what was measured — but the module lives under
+ * `tests/`, and `tests/` is not in this package's published `files` list while
+ * `scripts/` is. An eager require at the top of this file would therefore throw
+ * on load inside an installed copy of the package, turning a repo-only
+ * maintenance harness into a crash on a path a consumer might stumble onto. The
+ * lazy require fails only when a mode that actually needs the fixtures is asked
+ * for, and says exactly why.
+ */
+function loadFixtures() {
+  if (_fixtures !== null) return _fixtures;
+  const abs = path.join(REPO_ROOT, FIXTURE_MODULE_REL);
+  try {
+    _fixtures = require(abs);
+  } catch (err) {
+    throw new Error(
+      `the shared graded fixture module ${FIXTURE_MODULE_REL} could not be loaded, so no calibration ` +
+        'fixture could be built or read. This harness runs from a checkout of the pp-core repository; ' +
+        `it is not part of the published package's test surface. (${err && err.message})`,
+    );
+  }
+  return _fixtures;
+}
+
+// ─── Names the two halves and the Lane 1 shape tests share ───────────────────
+
+/** The phase directory `--prepare` scaffolds inside each fixture project. */
+const CALIBRATION_PHASE_DIRNAME = '06-calibration';
+
+/** The trace-carrying artifact that puts the fixture practice into the ledger. */
+const CALIBRATION_TRACE_ARTIFACT = '06-01-SUMMARY.md';
+
+/** The artifact `/pp-vault-review` writes, and `--ingest` reads back. */
+const CALIBRATION_REVIEW_ARTIFACT = '06-VAULT-REVIEW.md';
+
+/** The record home — COMMITTED, and deliberately outside the gitignored `.planning/`. */
+const RECORD_HOME_REL = path.join('docs', 'vault-calibration');
+
+/** The default working directory, stable so `--prepare` and `--ingest` agree with no flag. */
+const DEFAULT_WORK_DIR = path.join(os.tmpdir(), 'pp-vault-calibrate');
+
+/** Whether one fixture was read at all, and if not, on what ground. */
+const OBSERVATION_STATUS = Object.freeze({
+  MEASURED: 'measured',
+  NOT_MEASURED: 'not-measured',
+});
+
+const NOT_MEASURED_GROUND = Object.freeze({
+  ARTIFACT_ABSENT: 'artifact-absent',
+  ARTIFACT_UNREADABLE: 'artifact-unreadable',
+  SHAPE_INVALID: 'shape-invalid',
+});
+
+/**
+ * A direction's outcome. `INCOMPLETE` and `NOT_MEASURED` exist so a direction
+ * derived over fewer fixtures than it names can never render as one that held
+ * (T-6-34): an absence is reported as an absence.
+ */
+const DIRECTION_OUTCOME = Object.freeze({
+  HELD: 'held',
+  FAILED: 'failed',
+  INCOMPLETE: 'incomplete',
+  NOT_MEASURED: 'not-measured',
+});
+
+/** The leading marker. A failed calibration is not allowed to read like a quiet one. */
+const FAILURE_MARKER = 'FAILED CALIBRATION';
+
+/** D-06-08, stated in the record's own body so a reader meets it where the failure is. */
+const NEVER_AUTO_DISABLES =
+  'Nothing reads this record to change behaviour: no gate consults it, no configuration is written ' +
+  'from it, and a failed calibration disables nothing at all. A human reads this file and decides ' +
+  'whether to repair the reviewer prompt or to stop trusting this tier.';
+
+/** The Lane 3 bound, carried by the record rather than left in a plan nobody reopens. */
+const LANE3_LIMIT =
+  'These four known cases bound the judge on four known inputs and bound nothing else. They say ' +
+  'nothing about the fifty-fourth practice on a real phase, and nothing about whether any single ' +
+  'verdict here would reproduce on a second run. Calibration is not coverage.';
+
+/** The record's sections, in order. The Lane 1 shape test walks exactly this list. */
+const RECORD_SECTIONS = Object.freeze([
+  '## What this record is',
+  '## Engine and prompt fingerprint',
+  '## Per-fixture observations',
+  '## The two directions (D-06-06)',
+  '## Observed non-verdict rate (D-06-12)',
+  '## What this record does NOT bound (Lane 3)',
+]);
+
+/** The two files whose bytes decide whether a past record still describes today's judge. */
+const PROMPT_SOURCES = Object.freeze([
+  path.join('agents', 'pp-vault-reviewer.md'),
+  path.join('pp-core', 'references', 'verifier-practice-verdicts.md'),
+]);
+
+// ─── The trace `--prepare` seeds ─────────────────────────────────────────────
+
+/**
+ * The execute-stage practice trace the scaffolded phase carries.
+ *
+ * WHY A TRACE AT ALL, stated so a later reader does not remove it as clutter:
+ * without one the review takes the RECONSTRUCT arm, and on that arm the input
+ * set is derived from the ledger — which is empty — so the remainder is empty
+ * and NO practice reaches the agent. A calibration session against an empty
+ * remainder would judge nothing while producing a well-formed artifact, which
+ * is exactly the hollow-artifact failure mode this workstream exists to end.
+ * Seeding the ledger with the fixture's one practice is what makes the live run
+ * a measurement instead of a formality.
+ *
+ * @param {string} resolvedSha the fixture vault pin, so the review's pin advisory stays quiet
+ * @param {string} practiceId the one practice all four grades are judged against
+ * @param {string[]} changedFiles the graded files, as the trace subject
+ * @returns {string} the artifact body, frontmatter included
+ */
+function renderCalibrationTrace(resolvedSha, practiceId, changedFiles) {
+  const subject = changedFiles.map((name) => [`    - name: ${name}`, '      uri: ' + name]).flat();
+  return [
+    '---',
+    'phase: 06-calibration',
+    'plan: 1',
+    'status: complete',
+    'vault:',
+    '  _type: https://in-toto.io/Statement/v1',
+    '  predicateType: https://github.com/pareto000/pp-core/attestation/vault-practice-trace/v1',
+    '  schemaVersion: 1',
+    '  subject:',
+    ...subject,
+    '  predicate:',
+    '    stage: execute',
+    '    plan: "06-01"',
+    '    generatedAt: "2026-01-01T00:00:00.000Z"',
+    '    vault:',
+    '      state: loaded',
+    '      reason: null',
+    '      ref: calibration-fixture',
+    `      resolvedSha: ${resolvedSha}`,
+    '      tier: client',
+    '      source: cache',
+    '      repo: calibration-fixture',
+    '      practiceUniverse:',
+    `        - ${practiceId}`,
+    '    practices:',
+    `      - id: "${practiceId}"`,
+    '        scope: scoped',
+    '        severity: warning',
+    '        status: applied',
+    '        reason: "seeded by the calibration harness so the practice reaches the judge"',
+    '        tasks: []',
+    '    override: null',
+    '---',
+    '',
+    '# Calibration fixture phase',
+    '',
+    'A one-plan phase whose single commit carries the graded file. It exists so that',
+    '`/pp-vault-review` has a completed phase to review and a ledger to review it against.',
+    '',
+  ].join('\n');
+}
+
+/** A minimal planning workspace, so the phase resolver can find the scaffolded phase. */
+function renderCalibrationState() {
+  return [
+    '---',
+    'current_phase: 6',
+    'status: complete',
+    '---',
+    '',
+    '# Project State',
+    '',
+    '- Current phase: 6 — calibration fixture',
+    '',
+  ].join('\n');
+}
+
+function renderCalibrationRoadmap() {
+  return [
+    '# Roadmap',
+    '',
+    '## Phase 6: Calibration fixture',
+    '',
+    '**Status:** Complete',
+    '',
+    '- [x] 06-01 — the graded file',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Scaffold the calibration phase inside an already-built fixture project: the
+ * trace-carrying summary, plus the minimal planning workspace the phase
+ * resolver needs to answer `/pp-vault-review 6`.
+ *
+ * Exported as its own seam so a deterministic test can build ONE fixture, run
+ * the shipped CLI arm inside it, and pin that the vault-ENABLED path is live —
+ * without materialising all four or waiting for a live session.
+ *
+ * @param {string} projectDir a directory produced by `mkGradedReviewProject`
+ * @param {{resolvedSha: string, practiceId: string, changedFiles: string[]}} fixture
+ * @returns {{phaseDirRel: string, phaseDirAbs: string}}
+ */
+function scaffoldCalibrationPhase(projectDir, { resolvedSha, practiceId, changedFiles }) {
+  const phaseDirRel = path.join('.planning', 'phases', CALIBRATION_PHASE_DIRNAME);
+  const phaseDirAbs = path.join(projectDir, phaseDirRel);
+  fs.mkdirSync(phaseDirAbs, { recursive: true });
+  fs.writeFileSync(
+    path.join(phaseDirAbs, CALIBRATION_TRACE_ARTIFACT),
+    renderCalibrationTrace(resolvedSha, practiceId, changedFiles),
+    'utf-8',
+  );
+  fs.writeFileSync(path.join(projectDir, '.planning', 'STATE.md'), renderCalibrationState(), 'utf-8');
+  fs.writeFileSync(path.join(projectDir, '.planning', 'ROADMAP.md'), renderCalibrationRoadmap(), 'utf-8');
+  return { phaseDirRel, phaseDirAbs };
+}
+
+// ─── `--prepare` ─────────────────────────────────────────────────────────────
+
+function rmDeep(target) {
+  fs.rmSync(target, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+}
+
+/**
+ * Materialise the four fixture projects under `dir`, one directory per grade,
+ * each carrying the scaffolded phase.
+ *
+ * IDEMPOTENT IN CONTENT, AND SAYS SO. A second run removes and rebuilds every
+ * slot, so the working-tree bytes of every fixture are identical to the first
+ * run's. The git objects are not — a fresh `git init` writes fresh commit
+ * timestamps — and the returned `refreshed` flag records which slots were
+ * replaced rather than created, so the operator is never left guessing whether
+ * a stale artifact from a previous session is still sitting there. It is not:
+ * a rebuilt slot has no review artifact until a new session writes one.
+ *
+ * @param {{dir: string}} opts
+ * @returns {Array<object>} one entry per grade
+ */
+function prepareFixtures({ dir }) {
+  fs.mkdirSync(dir, { recursive: true });
+  const prepared = [];
+
+  const fixtures = loadFixtures();
+
+  for (const fixtureId of fixtures.GRADED_FIXTURES) {
+    const target = path.join(dir, fixtureId);
+    const refreshed = fs.existsSync(target);
+    if (refreshed) rmDeep(target);
+
+    const built = fixtures.mkGradedReviewProject(fixtureId);
+    try {
+      fs.cpSync(built.dir, target, { recursive: true });
+    } finally {
+      built.cleanup();
+    }
+
+    const scaffold = scaffoldCalibrationPhase(target, built);
+
+    prepared.push({
+      fixtureId,
+      dir: target,
+      refreshed,
+      practiceId: built.practiceId,
+      changedFiles: built.changedFiles,
+      expectFail: built.expectFail,
+      gloss: built.gloss,
+      phaseDirRel: scaffold.phaseDirRel,
+    });
+  }
+
+  return prepared;
+}
+
+/**
+ * Ask the SHIPPED CLI arm, inside a prepared fixture, whether the review is
+ * live there — vault ENABLED, trace found, one practice in the remainder.
+ *
+ * This is a deterministic exercise of the vault-enabled derive path and it is
+ * NOT a substitute for the agent run: it proves the fixture is reviewable and
+ * that the practice prose reaches the prompt, and it proves nothing whatsoever
+ * about any judgement. Read-and-swallow: a probe that cannot run reports that
+ * it could not, and `--prepare` still completes.
+ *
+ * ONE RUNNER, ONE CLAIM (06-11). The projections below `entries` — `refuses`,
+ * `counts`, `statements` and `trace` — were added so a test can assert on the
+ * clean-render refusal, the derived counts and the trace provenance WITHOUT a
+ * second `execFileSync` of the same command living in the test file. Two runners
+ * of one command are two places the invocation can drift, which is the 04-18
+ * lesson one level up from the predicate it was first learned on. `--prepare`
+ * reads only the original fields and is unaffected.
+ *
+ * `trace` (06-12 / G1) projects the payload's own provenance answer — the CLI
+ * decides loaded-vs-degraded and this runner only reads it back, so a test can
+ * never accidentally pin a rule the shipped arm does not hold.
+ *
+ * @param {string} projectDir
+ * @param {string} phaseDirRel
+ * @returns {{ok: boolean, status: string|null, arm: string|null, remainder: number|null,
+ *            entries: number|null, refuses: boolean|null, counts: object|null,
+ *            statements: string[]|null,
+ *            trace: {present: boolean|null, state: string|null, reason: string|null,
+ *                    loaded: boolean|null}|null,
+ *            detail: string|null}}
+ */
+function probeReviewArm(projectDir, phaseDirRel) {
+  const tools = path.join(REPO_ROOT, 'pp-core', 'bin', 'pp-tools.cjs');
+  try {
+    const out = execFileSync(process.execPath, [tools, 'check', 'vault-review', phaseDirRel, '--raw'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+      timeout: 60_000,
+    });
+    const payload = JSON.parse(out);
+    return {
+      ok: true,
+      status: typeof payload.status === 'string' ? payload.status : null,
+      arm: typeof payload.arm === 'string' ? payload.arm : null,
+      remainder: Array.isArray(payload?.partition?.remainder) ? payload.partition.remainder.length : null,
+      entries: Array.isArray(payload?.practiceEntries) ? payload.practiceEntries.length : null,
+      refuses: typeof payload?.refusesCleanRender === 'boolean' ? payload.refusesCleanRender : null,
+      counts: payload && typeof payload.derivedCounts === 'object' ? payload.derivedCounts : null,
+      statements: Array.isArray(payload?.statements) ? payload.statements : null,
+      trace:
+        payload && typeof payload.trace === 'object' && payload.trace !== null
+          ? {
+              present: typeof payload.trace.present === 'boolean' ? payload.trace.present : null,
+              state: typeof payload.trace.state === 'string' ? payload.trace.state : null,
+              reason: typeof payload.trace.reason === 'string' ? payload.trace.reason : null,
+              loaded: typeof payload.trace.loaded === 'boolean' ? payload.trace.loaded : null,
+            }
+          : null,
+      detail: null,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      status: null,
+      arm: null,
+      remainder: null,
+      entries: null,
+      refuses: null,
+      counts: null,
+      statements: null,
+      trace: null,
+      detail: err && err.message ? String(err.message).split('\n')[0] : 'the probe did not run',
+    };
+  }
+}
+
+// ─── `--ingest` ──────────────────────────────────────────────────────────────
+
+/**
+ * Read and judge the SHAPE of one fixture's produced artifact.
+ *
+ * MEASURED requires two things: the artifact exists and is readable, and the
+ * shipped validator found no problem in it. Anything else is NOT MEASURED with
+ * a named ground — never a pass, and never a throw. An artifact whose shape the
+ * validator could not vouch for is an artifact whose counts nobody should quote.
+ *
+ * @param {{dir: string, fixtureId: string}} opts
+ * @returns {object} the observation
+ */
+function observeFixture({ dir, fixtureId }) {
+  const fixtures = loadFixtures();
+  const spec = Object.prototype.hasOwnProperty.call(fixtures.GRADED_FIXTURE_SPECS, fixtureId)
+    ? fixtures.GRADED_FIXTURE_SPECS[fixtureId]
+    : null;
+  if (!spec) {
+    throw new Error(
+      `unknown graded fixture "${String(fixtureId)}" — the four grades are: ${fixtures.GRADED_FIXTURES.join(', ')}`,
+    );
+  }
+
+  const artifactPath = path.join(
+    dir,
+    fixtureId,
+    '.planning',
+    'phases',
+    CALIBRATION_PHASE_DIRNAME,
+    CALIBRATION_REVIEW_ARTIFACT,
+  );
+  const base = {
+    fixtureId,
+    expectFail: spec.expectFail,
+    gloss: spec.gloss,
+    artifactPath,
+    counts: null,
+    rateLine: null,
+    countsLine: null,
+    drewFail: null,
+    problemKinds: [],
+  };
+
+  let text;
+  try {
+    text = fs.readFileSync(artifactPath, 'utf-8');
+  } catch (err) {
+    const absent = err && err.code === 'ENOENT';
+    return {
+      ...base,
+      status: OBSERVATION_STATUS.NOT_MEASURED,
+      ground: absent ? NOT_MEASURED_GROUND.ARTIFACT_ABSENT : NOT_MEASURED_GROUND.ARTIFACT_UNREADABLE,
+      statement: absent
+        ? `"${fixtureId}" produced no review artifact at ${CALIBRATION_REVIEW_ARTIFACT}, so this grade was ` +
+          'NOT MEASURED. A fixture nobody reviewed is not a fixture that came out clean.'
+        : `"${fixtureId}" has a review artifact that could not be read, so this grade was NOT MEASURED.`,
+    };
+  }
+
+  const result = reviewModule.validateReviewArtifact(text);
+  const problemKinds = [...new Set(result.problems.map((p) => String(p.kind)))].sort();
+  if (!result.sectionPresent || problemKinds.length > 0) {
+    return {
+      ...base,
+      status: OBSERVATION_STATUS.NOT_MEASURED,
+      ground: NOT_MEASURED_GROUND.SHAPE_INVALID,
+      problemKinds,
+      statement:
+        `"${fixtureId}" produced an artifact the shipped validator could not vouch for, so this grade ` +
+        `was NOT MEASURED. Reported: ${problemKinds.join(', ') || 'no verdict section'}.`,
+    };
+  }
+
+  return {
+    ...base,
+    status: OBSERVATION_STATUS.MEASURED,
+    ground: null,
+    counts: result.counts,
+    rateLine: result.expectedRateLine,
+    countsLine: result.expectedCountsLine,
+    drewFail: result.counts.fail > 0,
+    statement:
+      `"${fixtureId}" was reviewed and its artifact validated. ` +
+      (result.counts.fail > 0 ? 'It drew at least one FAIL.' : 'It drew no FAIL.'),
+  };
+}
+
+/** Observe all four grades, in the order the shared module lists them. */
+function observeAllFixtures({ dir }) {
+  return loadFixtures().GRADED_FIXTURES.map((fixtureId) => observeFixture({ dir, fixtureId }));
+}
+
+/**
+ * Derive one direction over the fixtures whose `expectFail` matches `expectFail`.
+ *
+ * A direction HELD only when every one of its fixtures was measured and every
+ * measured one agrees. One contradiction FAILS it; one unmeasured fixture makes
+ * it INCOMPLETE and names the omission; nothing measured makes it NOT MEASURED.
+ * A direction is never allowed to hold on a subset while the subset goes
+ * unmentioned.
+ */
+function deriveDirection(observations, expectFail, label) {
+  const mine = observations.filter((o) => o.expectFail === expectFail);
+  const measured = mine.filter((o) => o.status === OBSERVATION_STATUS.MEASURED);
+  const notMeasured = mine.filter((o) => o.status !== OBSERVATION_STATUS.MEASURED).map((o) => o.fixtureId);
+  const contradicted = measured.filter((o) => o.drewFail !== expectFail).map((o) => o.fixtureId);
+
+  let outcome;
+  if (contradicted.length > 0) outcome = DIRECTION_OUTCOME.FAILED;
+  else if (measured.length === 0) outcome = DIRECTION_OUTCOME.NOT_MEASURED;
+  else if (notMeasured.length > 0) outcome = DIRECTION_OUTCOME.INCOMPLETE;
+  else outcome = DIRECTION_OUTCOME.HELD;
+
+  const statements = {
+    [DIRECTION_OUTCOME.HELD]: `every fixture in this direction was measured and agreed: ${measured
+      .map((o) => o.fixtureId)
+      .join(', ')}.`,
+    [DIRECTION_OUTCOME.FAILED]: `${contradicted.join(', ')} contradicted this direction.`,
+    [DIRECTION_OUTCOME.INCOMPLETE]:
+      `the measured fixtures agreed, but ${notMeasured.join(', ')} went unmeasured, so this direction ` +
+      'is derived over a subset and does not hold as stated.',
+    [DIRECTION_OUTCOME.NOT_MEASURED]:
+      'no fixture in this direction was measured, so nothing was derived about it at all.',
+  };
+
+  return {
+    expectFail,
+    label,
+    outcome,
+    fixtures: mine.map((o) => o.fixtureId),
+    measured: measured.map((o) => o.fixtureId),
+    notMeasured,
+    contradicted,
+    statement: statements[outcome],
+  };
+}
+
+/**
+ * Both D-06-06 directions. A verifier that fails everything catches every
+ * violation and is worthless, so direction two is not a courtesy check — it is
+ * the one that distinguishes a calibrated judge from an indiscriminate one.
+ */
+function deriveDirections(observations) {
+  const one = deriveDirection(
+    observations,
+    true,
+    'Direction 1 — each seeded violation drew at least one FAIL',
+  );
+  const two = deriveDirection(
+    observations,
+    false,
+    'Direction 2 — each compliant fixture drew no FAIL at all',
+  );
+  return {
+    one,
+    two,
+    failed: one.outcome === DIRECTION_OUTCOME.FAILED || two.outcome === DIRECTION_OUTCOME.FAILED,
+  };
+}
+
+// ─── The record ──────────────────────────────────────────────────────────────
+
+/** `<YYYY-MM-DD>-<vault-sha8>.md` — the date and the pin the fixtures carry. */
+function recordFileName(date, resolvedSha) {
+  const sha8 = String(resolvedSha ?? '').slice(0, 8) || 'unknown8';
+  return `${date}-${sha8}.md`;
+}
+
+/**
+ * The fixture ids a RECORD ALREADY ON DISK reports as measured.
+ *
+ * WHY THIS EXISTS: the record filename varies only by date and fixture sha, so
+ * two ingests on one day address the same file — and `--prepare` deliberately
+ * clears each fixture's prior review artifact, so the documented
+ * prepare → live-run → ingest sequence can arrive at `--ingest` with nothing to
+ * read. Writing then would replace a record that measured four grades with one
+ * that measured none. A record nobody re-measured is not a record that came out
+ * empty, which is the same distinction `observeFixture` already makes one tier
+ * down — enforced here against the file rather than against a fixture.
+ *
+ * Parses the per-fixture observations table rather than any prose: the Observed
+ * cell is written by `renderRecord` as `NOT MEASURED (<ground>)` or as a drew-*
+ * statement, and nothing else lands in that column.
+ *
+ * @param {string} text a rendered record's full bytes
+ * @param {string[]} [knownIds] the graded fixture ids; defaults to the shared module's four
+ * @returns {string[]} fixture ids whose Observed cell is not a NOT MEASURED cell
+ */
+function readRecordMeasuredIds(text, knownIds = loadFixtures().GRADED_FIXTURES) {
+  const out = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const cells = line.split('|').map((c) => c.trim());
+    // `| \`id\` | expected | observed | counts |` splits to 6 with empty ends.
+    if (cells.length !== 6) continue;
+    const id = cells[1].replace(/^`|`$/g, '');
+    if (!knownIds.includes(id)) continue;
+    if (cells[3].startsWith('NOT MEASURED')) continue;
+    out.push(id);
+  }
+  return out;
+}
+
+const OUTCOME_LABEL = Object.freeze({
+  [DIRECTION_OUTCOME.HELD]: 'HELD',
+  [DIRECTION_OUTCOME.FAILED]: 'FAILED',
+  [DIRECTION_OUTCOME.INCOMPLETE]: 'INCOMPLETE',
+  [DIRECTION_OUTCOME.NOT_MEASURED]: 'NOT MEASURED',
+});
+
+/**
+ * Render the dated record. PURE over its input, so two renders of the same
+ * observations are byte-identical — the same serialization discipline
+ * `scripts/update-size-baseline.cjs` states for its baseline, and for the same
+ * reason: a record whose bytes drift for no reason is a record nobody can diff.
+ */
+function renderRecord({ date, engine, promptFingerprint, observations, directions, notes = [] }) {
+  const lines = [];
+  lines.push(`# Vault practice-review calibration — ${date}`);
+  lines.push('');
+  if (directions.failed) {
+    lines.push(
+      `> **${FAILURE_MARKER}.** At least one direction was contradicted by a measured fixture. ` +
+        'Read the directions section below before trusting any review this judge produces.',
+    );
+    lines.push('');
+  }
+
+  lines.push(RECORD_SECTIONS[0]);
+  lines.push('');
+  lines.push(
+    'One on-demand run of the four graded fixtures (D-06-05) through `/pp-vault-review`, with the ' +
+      'shape of every produced artifact validated by the shipped validator before anything below was ' +
+      'derived from it.',
+  );
+  lines.push('');
+  lines.push(NEVER_AUTO_DISABLES);
+  lines.push('');
+
+  lines.push(RECORD_SECTIONS[1]);
+  lines.push('');
+  lines.push(`- Engine commit: \`${engine}\``);
+  lines.push(`- Reviewer prompt fingerprint: \`${promptFingerprint}\``);
+  lines.push('');
+  lines.push(
+    'The fingerprint is a digest over the reviewer agent file and the verdict reference. A record ' +
+      'whose fingerprint differs from today\'s describes a judge that no longer exists, which is the ' +
+      'signal to run calibration again (D-06-07).',
+  );
+  lines.push('');
+
+  lines.push(RECORD_SECTIONS[2]);
+  lines.push('');
+  lines.push('| Fixture | Expected direction | Observed | Counts by verdict |');
+  lines.push('| --- | --- | --- | --- |');
+  for (const o of observations) {
+    const expected = o.expectFail ? 'must draw FAIL' : 'must draw no FAIL';
+    const observed =
+      o.status === OBSERVATION_STATUS.MEASURED
+        ? o.drewFail
+          ? 'drew FAIL'
+          : 'drew no FAIL'
+        : `NOT MEASURED (${o.ground})`;
+    const counts = o.status === OBSERVATION_STATUS.MEASURED ? o.countsLine : '—';
+    lines.push(`| \`${o.fixtureId}\` | ${expected} | ${observed} | ${counts} |`);
+  }
+  lines.push('');
+  for (const o of observations) {
+    if (o.status !== OBSERVATION_STATUS.MEASURED) lines.push(`- **NOT MEASURED** — ${o.statement}`);
+  }
+  if (observations.every((o) => o.status === OBSERVATION_STATUS.MEASURED)) {
+    lines.push('- Every one of the four grades produced an artifact the validator vouched for.');
+  }
+  lines.push('');
+
+  lines.push(RECORD_SECTIONS[3]);
+  lines.push('');
+  for (const direction of [directions.one, directions.two]) {
+    lines.push(`### ${direction.label}`);
+    lines.push('');
+    lines.push(`**${OUTCOME_LABEL[direction.outcome]}** — ${direction.statement}`);
+    lines.push('');
+    if (direction.notMeasured.length > 0) {
+      lines.push(`Unmeasured in this direction: ${direction.notMeasured.join(', ')}.`);
+      lines.push('');
+    }
+    if (direction.contradicted.length > 0) {
+      lines.push(`Contradicting fixtures: ${direction.contradicted.join(', ')}.`);
+      lines.push('');
+    }
+  }
+
+  lines.push(RECORD_SECTIONS[4]);
+  lines.push('');
+  lines.push('| Fixture | Non-verdict rate line |');
+  lines.push('| --- | --- |');
+  for (const o of observations) {
+    lines.push(`| \`${o.fixtureId}\` | ${o.status === OBSERVATION_STATUS.MEASURED ? o.rateLine : 'NOT MEASURED'} |`);
+  }
+  lines.push('');
+  lines.push(
+    'The rate line is the shipped renderer\'s own output, computed from the rows and never narrated. ' +
+      'D-06-12 surfaces the rate and its deferred sibling deliberately refuses a threshold, so there ' +
+      'is no number here to pass or fail against — only one to read and to compare with the next run.',
+  );
+  lines.push('');
+
+  lines.push(RECORD_SECTIONS[5]);
+  lines.push('');
+  lines.push(LANE3_LIMIT);
+  lines.push('');
+  for (const note of notes) lines.push(`- ${note}`);
+  if (notes.length > 0) lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Fingerprints and the engine describe ────────────────────────────────────
+
+/** A digest over the reviewer prompt surfaces. Missing files are named, not silently skipped. */
+function promptFingerprint() {
+  const hash = crypto.createHash('sha256');
+  const missing = [];
+  for (const rel of PROMPT_SOURCES) {
+    try {
+      hash.update(fs.readFileSync(path.join(REPO_ROOT, rel)));
+    } catch {
+      missing.push(rel);
+      hash.update(`ABSENT:${rel}`);
+    }
+  }
+  return { digest: hash.digest('hex').slice(0, 16), missing };
+}
+
+/** `git rev-parse --short HEAD`, tolerant of every failure. */
+function engineDescribe() {
+  try {
+    return execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: REPO_ROOT,
+      encoding: 'utf-8',
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// ─── The two modes ───────────────────────────────────────────────────────────
+
+function runPrepare({ dir, probe = true, log = console.log }) {
+  const prepared = prepareFixtures({ dir });
+
+  log('');
+  log('pp-core ► VAULT PRACTICE REVIEW CALIBRATION — prepare');
+  log('');
+  log(`Working directory: ${dir}`);
+  log(`Four graded fixtures materialised from ${FIXTURE_MODULE_REL}.`);
+  log('');
+
+  for (const entry of prepared) {
+    if (probe) entry.probe = probeReviewArm(entry.dir, entry.phaseDirRel);
+    log(`── ${entry.fixtureId} ${entry.refreshed ? '(refreshed)' : '(created)'}`);
+    log(`   ${entry.gloss}`);
+    log(`   expected: ${entry.expectFail ? 'the judge must draw FAIL' : 'the judge must draw no FAIL'}`);
+    log(`   project:  ${entry.dir}`);
+    if (entry.probe) {
+      log(
+        entry.probe.ok
+          ? `   arm:      status=${entry.probe.status} arm=${entry.probe.arm} ` +
+              `remainder=${entry.probe.remainder} fenced-practice-entries=${entry.probe.entries}`
+          : `   arm:      the derive probe did not run — ${entry.probe.detail}`,
+      );
+      if (entry.probe.ok && entry.probe.remainder === 0) {
+        log('   WARNING:  the remainder is empty, so no practice would reach the judge in this fixture.');
+      }
+    }
+    log('');
+  }
+
+  log('Now run the live session — this harness makes no model call:');
+  log('');
+  for (const entry of prepared) {
+    log(`  cd ${entry.dir} && /pp-vault-review 6`);
+  }
+  log('');
+  log('Each run writes .planning/phases/' + CALIBRATION_PHASE_DIRNAME + '/' + CALIBRATION_REVIEW_ARTIFACT + '.');
+  log('When all four exist, ingest them:');
+  log('');
+  log(`  npm run vault:calibrate -- --ingest --dir ${dir}`);
+  log('');
+  return prepared;
+}
+
+function runIngest({
+  dir,
+  out = path.join(REPO_ROOT, RECORD_HOME_REL),
+  now = today(),
+  log = console.log,
+  force = false,
+}) {
+  const observations = observeAllFixtures({ dir });
+  const directions = deriveDirections(observations);
+  const fingerprint = promptFingerprint();
+  const notes = fingerprint.missing.map(
+    (rel) => `The reviewer prompt source \`${rel}\` was NOT readable, so the fingerprint above covers less than it names.`,
+  );
+
+  const text = renderRecord({
+    date: now,
+    engine: engineDescribe(),
+    promptFingerprint: fingerprint.digest,
+    observations,
+    directions,
+    notes,
+  });
+
+  const fileName = recordFileName(now, loadFixtures().FIXTURE_RESOLVED_SHA);
+  const target = path.join(out, fileName);
+
+  // The record home is an audit trail, so a write that REMOVES a measurement is
+  // refused rather than performed quietly. Only that direction is refused: a run
+  // that measures at least everything the record on disk already measured
+  // overwrites it, which is what re-running a calibration is for.
+  const regressed = [];
+  let existingText = null;
+  if (fs.existsSync(target)) {
+    try {
+      existingText = fs.readFileSync(target, 'utf-8');
+    } catch {
+      existingText = null;
+    }
+  }
+  if (existingText !== null) {
+    const before = readRecordMeasuredIds(existingText);
+    const after = new Set(
+      observations.filter((o) => o.status === OBSERVATION_STATUS.MEASURED).map((o) => o.fixtureId),
+    );
+    for (const id of before) if (!after.has(id)) regressed.push(id);
+  }
+  if (regressed.length > 0 && !force) {
+    log('');
+    log('pp-core ► VAULT PRACTICE REVIEW CALIBRATION — ingest REFUSED');
+    log('');
+    log(`  ${path.relative(REPO_ROOT, target)} already records these fixtures as MEASURED,`);
+    log('  and this run measured none of them:');
+    log('');
+    for (const id of regressed) log(`    ${id}`);
+    log('');
+    log('  Nothing was written. A record nobody re-measured is not a record that came');
+    log('  out empty, so replacing the one on disk would delete a measurement rather');
+    log('  than update it. `--prepare` clears each fixture\'s prior review artifact, so');
+    log('  a same-day re-ingest reaches this point whenever the live session has not');
+    log('  been re-run.');
+    log('');
+    log('  Re-run the live session (see --prepare), or pass --force to overwrite.');
+    log('');
+    return { target, text, observations, directions, written: false, regressed };
+  }
+
+  fs.mkdirSync(out, { recursive: true });
+  fs.writeFileSync(target, text.endsWith('\n') ? text : `${text}\n`, 'utf-8');
+
+  const leaked = reviewModule.scanForbiddenScoreTokens(text);
+
+  log('');
+  log('pp-core ► VAULT PRACTICE REVIEW CALIBRATION — ingest');
+  log('');
+  for (const o of observations) log(`  ${o.status === OBSERVATION_STATUS.MEASURED ? 'measured    ' : 'NOT MEASURED'} ${o.fixtureId}`);
+  log('');
+  log(`  ${OUTCOME_LABEL[directions.one.outcome]}  ${directions.one.label}`);
+  log(`  ${OUTCOME_LABEL[directions.two.outcome]}  ${directions.two.label}`);
+  log('');
+  if (directions.failed) {
+    log(`  ${FAILURE_MARKER} — recorded, and nothing was disabled. A human decides.`);
+    log('');
+  }
+  if (leaked.length > 0) {
+    log(`  WARNING: the record carries ${leaked.length} forbidden score form(s); D-06-13 forbids them.`);
+    log('');
+  }
+  // Relative when the record landed inside the repo, absolute when `--out` put
+  // it elsewhere: a `../../../..` prefix names the file without locating it.
+  const rel = path.relative(REPO_ROOT, target);
+  log(`  Record: ${rel.startsWith('..') ? target : rel}`);
+  log('');
+
+  return { target, text, observations, directions, written: true, regressed };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+const USAGE = [
+  'Usage: npm run vault:calibrate -- --prepare [--dir <path>]',
+  '       npm run vault:calibrate -- --ingest  [--dir <path>] [--out <path>] [--force]',
+  '',
+  '  --prepare   materialise the four graded fixture projects and print the operator instruction',
+  '  --ingest    read the produced review artifacts, derive both directions, write the dated record',
+  '  --dir       working directory for the fixture projects (default: ' + DEFAULT_WORK_DIR + ')',
+  '  --out       record home (default: ' + RECORD_HOME_REL + ')',
+  '  --no-probe  skip the vault-enabled derive probe during --prepare',
+  '  --force     let --ingest overwrite a dated record that measured MORE than this run did',
+  '',
+  'This harness never makes a model call. The agent runs happen in a live session.',
+].join('\n');
+
+function parseArgs(argv) {
+  const opts = { mode: null, dir: DEFAULT_WORK_DIR, out: null, probe: true, force: false, unknown: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok === '--prepare' || tok === '--ingest') opts.mode = tok.slice(2);
+    else if (tok === '--dir') opts.dir = path.resolve(argv[(i += 1)] ?? '');
+    else if (tok === '--out') opts.out = path.resolve(argv[(i += 1)] ?? '');
+    else if (tok === '--no-probe') opts.probe = false;
+    else if (tok === '--force') opts.force = true;
+    else if (tok === '--help' || tok === '-h') opts.mode = 'help';
+    else opts.unknown.push(tok);
+  }
+  return opts;
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  if (opts.unknown.length > 0) {
+    console.log(`Unrecognised argument(s): ${opts.unknown.join(', ')} — nothing was calibrated.`);
+    console.log(USAGE);
+    return 0;
+  }
+  if (opts.mode === null || opts.mode === 'help') {
+    console.log(USAGE);
+    return 0;
+  }
+  if (opts.mode === 'prepare') {
+    runPrepare({ dir: opts.dir, probe: opts.probe });
+    return 0;
+  }
+  const ingested = runIngest({ dir: opts.dir, force: opts.force, ...(opts.out ? { out: opts.out } : {}) });
+  // A refusal is a command that did not do its job — it exits non-zero so an
+  // operator's `&&` chain stops. Nothing about the REVIEW tier gates on this;
+  // this is the harness declining to delete a measurement.
+  return ingested.written ? 0 : 1;
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}
+
+module.exports = {
+  CALIBRATION_PHASE_DIRNAME,
+  CALIBRATION_TRACE_ARTIFACT,
+  CALIBRATION_REVIEW_ARTIFACT,
+  RECORD_HOME_REL,
+  DEFAULT_WORK_DIR,
+  RECORD_SECTIONS,
+  PROMPT_SOURCES,
+  NEVER_AUTO_DISABLES,
+  LANE3_LIMIT,
+  FAILURE_MARKER,
+  OBSERVATION_STATUS,
+  NOT_MEASURED_GROUND,
+  DIRECTION_OUTCOME,
+  scaffoldCalibrationPhase,
+  prepareFixtures,
+  probeReviewArm,
+  observeFixture,
+  observeAllFixtures,
+  deriveDirections,
+  renderRecord,
+  recordFileName,
+  readRecordMeasuredIds,
+  runPrepare,
+  runIngest,
+  main,
+  /** The compiled leaf, re-exposed so a consumer harvests the shipped renderers rather than copying them. */
+  __reviewModule: reviewModule,
+};