ruvnet-brain 4.3.20 → 4.3.25

package/plugin/scripts/grounding-turn-mark.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * grounding-turn-mark.mjs — UserPromptSubmit half of the "answered without searching" gate.
+ *
+ * THE GAP THIS CLOSES (measured, not assumed — see grounding-turn-gate.mjs's header for the full
+ * account). ground-ruvnet.sh's Gate 1 tells the model, in prose, "you MUST call search_ruvnet
+ * before asserting" whenever the prompt touches the rUv stack — but a prompt is advisory (rUv's own
+ * ADR-G007: "prompts are advisory. Agents can and do ignore them"), and nothing checked whether the
+ * model actually did it before the turn ended. This file is step one of making that check possible:
+ * it records ONLY the fact that Gate 1 fired for this turn, so the Stop-time gate
+ * (grounding-turn-gate.mjs) has something to check against — Stop's own payload carries no prompt
+ * text (confirmed against every Stop-consuming file in this repo; continuation-gate.mjs's `Stop`
+ * input has session_id/turn_id/stop_hook_active/last_assistant_message and nothing resembling the
+ * user's prompt).
+ *
+ * THE REGEX IS NOT REDEFINED HERE. It is imported from ruvnet-gate1-pattern.mjs, which is the one
+ * JS copy of ground-ruvnet.sh's Gate 1 ERE, proven byte-identical to it by
+ * tests/unit/ruvnet-gate1-pattern.test.mjs. ground-ruvnet.sh itself is UNTOUCHED by this file — it
+ * is a hot, heavily-tuned, every-prompt hook, and this feature does not need to change it.
+ *
+ * WHAT THIS WRITES: a marker file under ~/.cache/ruvnet-brain/grounding-turn/<session_id>, whose
+ * MTIME is the signal (same idiom grounding-stamp.sh and ground-before-write.sh already use for
+ * their own 24h stamps — this reuses that mtime-comparison convention rather than inventing a new
+ * one). Its CONTENT is a JSON blob for a human reading the cache, but the Stop-time gate only ever
+ * trusts the mtime.
+ *
+ * CONTRACT: PostToolUse-shaped hooks in this repo are advisory; this one is too — it can never
+ * block a prompt. It exits 0 unconditionally and writes nothing to stdout Claude/Codex would act
+ * on (UserPromptSubmit's silence contract). A write failure (unwritable cache dir, race, etc.) is
+ * swallowed: a marker that fails to write means the Stop gate later sees nothing and stays silent,
+ * which is fail-open in the correct direction — never a false block from a plumbing failure.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readStdinBounded } from './hook-input.mjs';
+import { ruvnetGate1Matches } from './ruvnet-gate1-pattern.mjs';
+
+const HOME = os.homedir();
+export const MARKER_DIR = process.env.RUVNET_GROUNDING_TURN_DIR
+  || path.join(HOME, '.cache', 'ruvnet-brain', 'grounding-turn');
+
+/** Filesystem-safe key for a session id — mirrors continuation-gate.mjs's own `replace(':', '-')`
+ *  idiom, generalised: a session id is host-supplied and must never be trusted as a bare path
+ *  segment. */
+export function markerPathFor(sessionId, dir = MARKER_DIR) {
+  const safe = String(sessionId ?? '').replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 200);
+  return safe ? path.join(dir, `${safe}.json`) : null;
+}
+
+/** Exported for the unit test: pure decision, no I/O. */
+export function shouldMark(hookInput) {
+  if (!hookInput || hookInput.hook_event_name !== 'UserPromptSubmit') return false;
+  if (!hookInput.session_id) return false;
+  const text = String(hookInput.prompt ?? hookInput.user_prompt ?? hookInput.input ?? '');
+  return ruvnetGate1Matches(text);
+}
+
+async function main() {
+  let hookInput;
+  try {
+    const raw = (await readStdinBounded()).toString('utf8');
+    hookInput = JSON.parse(raw || '{}');
+  } catch { process.exit(0); }
+
+  if (!shouldMark(hookInput)) process.exit(0);
+
+  const file = markerPathFor(hookInput.session_id);
+  if (!file) process.exit(0);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({
+      at: new Date().toISOString(),
+      sessionId: hookInput.session_id,
+      turnId: hookInput.turn_id || hookInput.prompt_id || null,
+    }) + '\n');
+  } catch { /* fail-open: no marker means the Stop gate stays silent, never a false block */ }
+  process.exit(0);
+}
+
+/** Never runs main() merely because a test (or anything else) imported this file for its pure
+ *  helpers — same guard decision-gate.mjs uses, for the same reason (entrypoint-guard-safety). */
+function isMain() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch { return false; }
+}
+
+if (isMain()) main();

package/plugin/scripts/hook-shim.mjs

@@ -154,6 +154,20 @@ const TABLE = {
   // 'partial' (work-ledger retained, grounding-debt bytes suppressed). Declaring 'partial' today
   // would declare a split that does not exist, which is the ceremony ADR-055 §4 refuses by name.
   'continuation-gate': { file: 'continuation-gate.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run' },
+  // THE "ANSWERED WITHOUT SEARCHING" PAIR (2026-09-12). ground-ruvnet's Gate 1 is a prompt-level
+  // directive ("call search_ruvnet before asserting"), and a directive is advisory — nothing
+  // checked whether the model actually complied before the turn ended. grounding-turn-mark records
+  // Gate 1 firing at UserPromptSubmit (Stop's own payload carries no prompt text); grounding-turn-
+  // gate reads that marker at Stop and forces continuation if no search_ruvnet call was recorded in
+  // between (reusing grounding-stamp.sh's existing stamp evidence — see that file's own header).
+  // Both are mode:'advisory' for the same reason continuation-gate is: a UserPromptSubmit hook's
+  // silence contract has nothing to block, and Stop's own forcing mechanism is the stdout envelope,
+  // not the exit code. offBehavior:'silence' on both — ADR-054's own discriminator names GROUNDING
+  // as one of the three jobs 'silence' exists for, matching ground-ruvnet's classification exactly;
+  // with the brain off there is no search_ruvnet to call, so forcing this would be hostile, not
+  // enforcement (the same reasoning ground-before-write.sh's own BRAIN_OFF check already applies).
+  'grounding-turn-mark': { file: 'grounding-turn-mark.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
+  'grounding-turn-gate': { file: 'grounding-turn-gate.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
 };
 
 const hookId = process.argv[2];

package/plugin/scripts/host-shell-boundary.mjs

@@ -0,0 +1,43 @@
+// host-shell-boundary.mjs — one definition of the files a running host freezes at boot.
+//
+// Body files are reached through the Stable Spine and can change in place. These paths are the
+// host declarations or boot-loaded surfaces whose change must be reported honestly to a running
+// Claude/Codex session. Both the updater and the installer consume this one list so they cannot
+// disagree about whether a release needs a restart.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SHELL_PATHS = Object.freeze([
+  'hooks/hooks.json',
+  'scripts/hook-shim.mjs',
+  'scripts/hook-shim-bash.mjs',
+  'scripts/development-maintenance.mjs',
+  'mcp/server.mjs',
+  '.mcp.json',
+]);
+
+function treeDigest(root, relative) {
+  const target = path.join(root, relative);
+  let stat;
+  try { stat = fs.lstatSync(target); } catch { return '<missing>'; }
+  if (stat.isSymbolicLink()) return '<symlink>';
+  if (stat.isFile()) return `file:${crypto.createHash('sha256').update(fs.readFileSync(target)).digest('hex')}`;
+  if (!stat.isDirectory()) return `<special:${stat.mode}>`;
+  const entries = fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  return `dir:${entries.map((entry) => `${entry.name}:${treeDigest(target, entry.name)}`).join('|')}`;
+}
+/** Return the boot-loaded paths that differ between two plugin payload roots. */
+export function shellDiff(prevRootAbs, nextRootAbs) {
+  if (!prevRootAbs || !nextRootAbs) throw new Error('both plugin roots are required for shell comparison');
+  const changed = [];
+  for (const rel of SHELL_PATHS) {
+    if (treeDigest(prevRootAbs, rel) !== treeDigest(nextRootAbs, rel)) changed.push(rel);
+  }
+  // skills/ and commands/ are markdown surfaces loaded at host boot. Any file-set or content
+  // difference is a boot-surface change, even though they are not executable hook declarations.
+  for (const dir of ['skills', 'commands']) {
+    if (treeDigest(prevRootAbs, dir) !== treeDigest(nextRootAbs, dir)) changed.push(`${dir}/`);
+  }
+  return changed;
+}

package/plugin/scripts/nightly-scheduler.mjs

@@ -85,6 +85,27 @@ export function validateRefreshReceiptEnvelope(receipt) {
   return { ok: true };
 }
 
+/**
+ * An ABORTED run is not a malformed receipt. kb/refresh-run.mjs appends a phase as it completes and
+ * stops at the first required failure, so every aborted run's ledger is a strict prefix of its
+ * declared order — by design. `validateRefreshReceiptEnvelope` rightly rejects that shape (the
+ * two-run PROOF needs a full, successful ledger), but the health READER must not report "invalid:
+ * phase ledger differs from its declared contract" for a run that failed early for a stated reason
+ * and then throw the reason away (measured 2026-09-12: two FAILED receipts, cause "unresolved
+ * rollback state exists…", surfaced to nobody). Returns the failure sentence, or null when the
+ * receipt is not a FAILED prefix-shaped run — then the envelope validator speaks.
+ */
+export function describeFailedRefreshRun(receipt, { reasonLimit = 200 } = {}) {
+  if (receipt?.status !== 'FAILED' || !Array.isArray(receipt.requiredPhaseOrder) || !Array.isArray(receipt.phases)) return null;
+  const declared = receipt.requiredPhaseOrder;
+  const ledger = receipt.phases.map((entry) => entry?.phase);
+  if (ledger.length > declared.length || ledger.some((phase, index) => phase !== declared[index])) return null;
+  if (ledger.length === 0) return `failed before its first phase (${receipt.terminalVerdict || 'unknown'})`;
+  const failing = [...receipt.phases].reverse().find((entry) => entry?.status !== 'PASS') || receipt.phases[receipt.phases.length - 1];
+  const reason = String(failing.evidence?.updateResult?.reason ?? failing.evidence?.reason ?? '').split('\n')[0].trim();
+  return reason ? `failed at ${failing.phase}: ${reason.slice(0, reasonLimit)}` : `failed at ${failing.phase}`;
+}
+
 function sameExecutable(left, right) {
   try { return fs.realpathSync(left) === fs.realpathSync(right); }
   catch { return path.resolve(left || '') === path.resolve(right || ''); }
@@ -233,14 +254,22 @@ export function refreshRunHealth({ brainHome, identity = NIGHTLY_LABEL, now = Da
         ? `Nightly refresh ${receipt.runId} has a dead exact owner.`
         : `Nightly refresh ${receipt.runId} owner cannot be established exactly.`, receipt };
   }
+  // A FAILED run whose ledger is a prefix of its contract failed for a reason the receipt carries.
+  // Say where and why; "invalid" is reserved for receipts that are genuinely out of contract.
+  const failure = describeFailedRefreshRun(receipt);
+  if (failure) {
+    return { state: 'failed', ageHours, receipt,
+      evidence: `Nightly refresh ${receipt.runId} ${failure}${/[.!?]$/.test(failure) ? '' : '.'}` };
+  }
   const envelope = validateRefreshReceiptEnvelope(receipt);
   if (!envelope.ok) return { state: 'failed', ageHours,
     evidence: `Nightly refresh ${receipt.runId} is invalid: ${envelope.why}.`, receipt };
   if (ageHours > maxAgeHours) {
     return { state: 'stale', ageHours, evidence: `Last verified nightly refresh is ${ageHours.toFixed(1)}h old.`, receipt };
   }
-  return { state: receipt.status === 'SUCCEEDED' ? 'ok' : 'failed', ageHours,
-    evidence: `Last nightly refresh ${receipt.terminalVerdict} successfully ${ageHours.toFixed(1)}h ago.`, receipt };
+  // envelope.ok already implies status SUCCEEDED and terminalVerdict applied|noop.
+  return { state: 'ok', ageHours,
+    evidence: `Last nightly refresh ${receipt.terminalVerdict} ${ageHours.toFixed(1)}h ago; envelope verified.`, receipt };
 }
 
 export function nightlyCommand(record) {
@@ -477,10 +506,14 @@ export function schedulerStatus({ platform = process.platform, env = process.env
     const loaded = !listed.error && listed.status === 0;
     if (!loaded) return finish({ state: 'degraded', evidence: 'LaunchAgent plist exists but job is not loaded', artifact, registration });
     const exit = String(listed.stdout || '').match(/last exit code\s*=\s*(-?\d+)/i);
+    // `lastExitCode` lets a projector tell "loaded, verified, FIRED and failed" from the degraded
+    // states that genuinely cannot fire (not loaded, command drift) — the watchdog was collapsing
+    // both into MISSING (2026-09-12).
     if (exit && Number(exit[1]) !== 0) {
-      return finish({ state: 'degraded', evidence: `LaunchAgent is loaded and runner digest verified, but last exited ${exit[1]}`, artifact, registration });
+      return finish({ state: 'degraded', lastExitCode: Number(exit[1]),
+        evidence: `LaunchAgent is loaded and runner digest verified, but last exited ${exit[1]}`, artifact, registration });
     }
-    return finish({ state: 'on', evidence: exit
+    return finish({ state: 'on', lastExitCode: exit ? Number(exit[1]) : null, evidence: exit
       ? 'LaunchAgent is loaded, runner digest verified, and last exited cleanly'
       : 'LaunchAgent is loaded and runner digest verified; no completed run is recorded yet', artifact, registration });
   }

package/plugin/scripts/project-progression-checkpoint.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * project-progression-checkpoint.mjs — the EXPLICIT capture boundary behind /ruvnet-brain:checkpoint.
+ *
+ * The automatic boundaries (Stop, PreCompact, SessionEnd) capture what can be READ from the machine:
+ * git, the work ledger, the owner's note, a bounded transcript reference. They cannot read what only
+ * the model knows — the acceptance contract it is working to, the decision it just made and why, the
+ * exact next action. This entry point lets the model hand that over, once, deliberately.
+ *
+ * IT IS NOT A SECOND WRITER. Everything still goes through the producer and
+ * captureProjectTransition, so the snapshot is validated, redacted, fsynced to the outbox, written
+ * by `ruflo memory store`, and read back by its exact key before this prints a receipt. The model's
+ * `--json` contributes FIELDS; it never contributes a write path.
+ *
+ * The supplied fields are merged OVER the produced ones, and each supplied field is recorded in
+ * `provenance` as `model-checkpoint` with `authoritative: false`. A model asserting its own goal is
+ * a useful record and is not the same kind of fact as a line the user wrote in their ledger, and the
+ * snapshot must not lose that distinction on the way in.
+ *
+ * Usage:
+ *   node project-progression-checkpoint.mjs --json '<completeProjectState fragment>' [--session <id>]
+ *   node project-progression-checkpoint.mjs --json-file <path> [--project-dir <dir>]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { captureProjectTransition } from './project-progression-hook.mjs';
+import { buildProjectProgression } from './project-progression-producer.mjs';
+import { ProjectProgressionStore } from './project-progression-store.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { projectDirectory } from './project-identity.mjs';
+
+/** Fields a checkpoint may contribute. Anything else is ignored rather than silently stored. */
+export const CHECKPOINT_FIELDS = Object.freeze([
+  'currentGoal', 'acceptanceContract', 'nextAction', 'activeStep',
+  'decisions', 'blockers', 'failures', 'completed', 'inProgress', 'plan',
+  'changedFiles', 'commands', 'proofArtifacts', 'untested',
+]);
+
+const ARRAY_FIELDS = new Set([
+  'decisions', 'blockers', 'failures', 'completed', 'inProgress', 'plan',
+  'changedFiles', 'commands', 'proofArtifacts', 'untested',
+]);
+
+export function parseArgs(argv) {
+  const out = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (!flag.startsWith('--')) continue;
+    out[flag.slice(2)] = argv[index + 1]?.startsWith('--') ? true : argv[index + 1];
+  }
+  return out;
+}
+
+export function readCheckpointState({ json, 'json-file': jsonFile } = {}) {
+  let text = json;
+  if (typeof jsonFile === 'string' && jsonFile) text = fs.readFileSync(jsonFile, 'utf8');
+  if (typeof text !== 'string' || !text.trim()) throw new Error('a checkpoint needs --json or --json-file');
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { throw new Error('checkpoint state is not JSON'); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('checkpoint state must be an object');
+  const state = {};
+  for (const field of CHECKPOINT_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(parsed, field)) continue;
+    if (ARRAY_FIELDS.has(field) && !Array.isArray(parsed[field])) throw new Error(`checkpoint ${field} must be an array`);
+    state[field] = parsed[field];
+  }
+  if (Object.keys(state).length === 0) {
+    throw new Error(`a checkpoint must set at least one of: ${CHECKPOINT_FIELDS.join(', ')}`);
+  }
+  return state;
+}
+
+export function runCheckpoint({
+  projectDir = projectDirectory(),
+  state,
+  host = process.env.RUVNET_HOOK_HOST || 'claude',
+  sessionId = process.env.CLAUDE_SESSION_ID || `checkpoint-${Date.now()}`,
+  produce = buildProjectProgression,
+  capture = captureProjectTransition,
+  storeFactory,
+} = {}) {
+  const resolution = resolveProjectStore({ projectDir });
+  if (!fs.existsSync(path.dirname(resolution.canonicalAgentDbPath))) {
+    throw new Error(`this project has not adopted the canonical store (${resolution.canonicalAgentDbPath})`);
+  }
+  const payload = { session_id: sessionId, hook_event_name: 'checkpoint' };
+  const produced = produce({ resolution, payload, host, trigger: 'checkpoint' });
+
+  // Commit any durable-but-uncommitted snapshot first, so an explicit checkpoint also settles the
+  // debt SessionStart is forbidden from settling. Same ordering as the automatic boundaries.
+  const store = (storeFactory ?? ((options) => new ProjectProgressionStore(options)))({
+    projectDir, requestedStorePath: resolution.canonicalAgentDbPath,
+  });
+  let replayed = 0;
+  try { replayed = store.replay().length; } catch { /* the checkpoint itself is still worth writing */ }
+
+  const provenance = { ...produced.projectProgression.completeProjectState.provenance };
+  for (const field of Object.keys(state)) provenance[field] = { source: 'model-checkpoint', authoritative: false };
+
+  const result = capture({
+    host,
+    projectDir,
+    storeFactory,
+    payload: {
+      ...payload,
+      projectProgression: {
+        ...produced.projectProgression,
+        completeProjectState: {
+          ...produced.projectProgression.completeProjectState,
+          ...state,
+          provenance,
+        },
+      },
+    },
+  });
+  return { receipt: result.receipt, replayed, provenance, sequence: result.snapshot.sequence };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = parseArgs(process.argv.slice(2));
+  try {
+    const outcome = runCheckpoint({
+      state: readCheckpointState(args),
+      ...(typeof args['project-dir'] === 'string' ? { projectDir: args['project-dir'] } : {}),
+      ...(typeof args.session === 'string' ? { sessionId: args.session } : {}),
+    });
+    // THE RECEIPT IS THE POINT. It names the exact key, and it says the row was read BACK by that
+    // key and matched — which is the only evidence that distinguishes a checkpoint from a claim.
+    console.log(JSON.stringify({
+      checkpoint: 'stored',
+      eventKey: outcome.receipt.eventKey,
+      sequence: outcome.sequence,
+      payloadDigest: outcome.receipt.payloadDigest,
+      readbackDigest: outcome.receipt.readbackDigest,
+      readbackVerified: outcome.receipt.readbackDigest === outcome.receipt.payloadDigest,
+      alreadyStored: outcome.receipt.alreadyStored,
+      replayedPending: outcome.replayed,
+      committedAt: outcome.receipt.committedAt,
+    }, null, 2));
+  } catch (error) {
+    console.error(`[checkpoint] ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/plugin/scripts/project-progression-contract.mjs

@@ -328,6 +328,22 @@ function mergeHeads(heads) {
     }
   }
 
+  // CARRY THE FIELDS THIS MERGE DOES NOT KNOW ABOUT (provenance, evidence, anything a later producer
+  // adds). The merge used to build `state` from its two hard-coded field lists alone, so every extra
+  // key silently VANISHED the moment a project had two heads — and provenance is exactly the kind of
+  // field whose disappearance turns "we guessed this from a transcript" into an unmarked fact.
+  const knownFields = new Set([...STATE_ARRAY_FIELDS, ...STATE_VALUE_FIELDS, 'journalHeads', 'sourceIdentity']);
+  const extraFields = [...new Set(heads.flatMap((head) => Object.keys(head.completeProjectState)))]
+    .filter((field) => !knownFields.has(field)).sort();
+  for (const field of extraFields) {
+    const values = uniqueSorted(heads.map((head) => head.completeProjectState[field] ?? null));
+    if (values.length === 1) state[field] = values[0];
+    else {
+      state[field] = null;
+      conflicts.push(conflict(field, heads, (head) => head.completeProjectState[field] ?? null));
+    }
+  }
+
   const sources = uniqueSorted(heads.map((head) => head.sourceIdentity));
   if (sources.length === 1) state.sourceIdentity = sources[0];
   else {

package/plugin/scripts/project-progression-hook.mjs

@@ -14,6 +14,9 @@ const CAPTURE_TRIGGERS = new Set([
   'SubagentStop',
   'PreCompact',
   'SessionEnd',
+  // The EXPLICIT boundary: /ruvnet-brain:checkpoint. It routes through this same function on
+  // purpose — a second writer for "the model wrote its own state" would be a second writer.
+  'checkpoint',
 ]);
 const PLUGIN_JSON = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '.claude-plugin', 'plugin.json');
 

package/plugin/scripts/project-progression-producer.mjs

@@ -0,0 +1,252 @@
+/**
+ * project-progression-producer.mjs — the thing that was missing.
+ *
+ * `captureProjectTransition` has always been able to store a complete project snapshot. Nothing ever
+ * BUILT one: it was only reachable when a host payload already carried a `projectProgression`
+ * extension, and no host emits one. So the North Star's "append-only full project snapshots" had a
+ * verified writer, a verified reader, and no producer — which is why the canonical store held zero
+ * rows in the project-progression namespace while 378 hand-written `project-state-current` notes
+ * accumulated beside it. This module is the producer.
+ *
+ * EVERY FIELD CARRIES PROVENANCE, and the order of authority is fixed:
+ *
+ *   ledger             the user's own work ledger — they wrote it, so it wins
+ *   owner-note         the newest `project-state-current%` note — the owner's own narrative
+ *   prior-head         the previous snapshot: sequence, parent links, carried acceptance
+ *   git                branch / HEAD / the three tree digests — mechanical, never inferred
+ *   transcript-derived a bounded single-sentence reduction, used ONLY where nothing above spoke
+ *
+ * Anything derived from the transcript or from repository contents is marked
+ * `authoritative: false`. A later session reading this snapshot can then tell the difference between
+ * "the user said this" and "we guessed this from the tail of a conversation" — a distinction that
+ * disappears the moment provenance is dropped, and whose disappearance is how an inferred goal ends
+ * up being obeyed as an instruction.
+ *
+ * THE PRIVACY BOUNDARY. The user's prompt and the assistant's reply are never persisted. The
+ * transcript contributes a REFERENCE (path, byte span, record count, sha256 of the exact bytes read)
+ * and at most two derived sentences of DERIVED_TEXT_LIMIT each. redactProgression then runs over the
+ * whole snapshot inside createProgressionSnapshot, so secret-shaped material cannot survive even
+ * within those bounds.
+ */
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { digestCanonical, redactProgression, restoreProjectProgression } from './project-progression-contract.mjs';
+import { readOwnerNote, readSourceIdentity, readTranscriptReference, readWorkLedger } from './project-progression-sources.mjs';
+import { withProgressionReader } from './project-progression-reader.mjs';
+
+const PROGRESSION_NAMESPACE = 'project-progression';
+const OWNER_NOTE_NAMESPACES = Object.freeze(['default']);
+
+/**
+ * `none` is not a filler value, it is the honest answer to "where did this come from?" when the
+ * answer is "nowhere — no source had one". Labelling an empty goal `git` (as the first version did,
+ * simply because git was the last branch in the chain) claims a provenance the field does not have,
+ * and provenance that can be wrong is worse than no provenance at all.
+ */
+export const PROVENANCE_SOURCES = Object.freeze([
+  'ledger', 'owner-note', 'prior-head', 'git', 'transcript-derived', 'model-checkpoint', 'none',
+]);
+
+const AUTHORITATIVE = Object.freeze({
+  ledger: true,
+  'owner-note': true,
+  'prior-head': true,
+  git: true,
+  'transcript-derived': false,
+  'model-checkpoint': false,
+  none: false,
+});
+
+function marker(source) {
+  if (!PROVENANCE_SOURCES.includes(source)) throw new Error(`unknown provenance source: ${source}`);
+  return { source, authoritative: AUTHORITATIVE[source] };
+}
+
+/**
+ * Read the owner's `project-state-current%` notes from the canonical store WITHOUT a CLI spawn.
+ * The owner's convention writes them into the project's own namespace and into `default`; both are
+ * checked, because which one a given session used depends on whether `-n` was passed.
+ */
+function ownerNoteRows(canonicalAgentDbPath, projectNamespace) {
+  const namespaces = [...new Set([projectNamespace, ...OWNER_NOTE_NAMESPACES].filter(Boolean))];
+  const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
+    const rows = [];
+    for (const namespace of namespaces) {
+      for (const key of reader.listKeys(namespace)) {
+        if (!key.startsWith('project-state-current')) continue;
+        const content = reader.readContent(namespace, key);
+        if (typeof content === 'string') rows.push({ key, namespace, content });
+      }
+    }
+    return rows;
+  });
+  return result.ok ? result.value : [];
+}
+
+/** The committed heads, computed the same way a restore computes them. Empty store → no heads. */
+function committedHeads(canonicalAgentDbPath, projectIdentity) {
+  const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
+    const snapshots = [];
+    for (const key of reader.listKeys(PROGRESSION_NAMESPACE)) {
+      const content = reader.readContent(PROGRESSION_NAMESPACE, key);
+      if (typeof content !== 'string') continue;
+      try { snapshots.push(JSON.parse(content)); } catch { /* a malformed row is the restore's problem */ }
+    }
+    return snapshots;
+  });
+  if (!result.ok) return { heads: [], readPath: `unavailable (${result.reason})` };
+  const restored = restoreProjectProgression(result.value, { expectedProjectIdentity: projectIdentity });
+  const byKey = new Map(result.value.map((snapshot) => [snapshot?.eventKey, snapshot]));
+  return { heads: restored.heads.map((key) => byKey.get(key)).filter(Boolean), readPath: 'node:sqlite' };
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))];
+}
+
+/**
+ * Build the `projectProgression` extension for one host payload.
+ *
+ * @returns {{ projectProgression: object, provenance: object, skipped?: { reason: string } }}
+ *   `skipped` is set when this capture would add nothing: a snapshot whose complete project state
+ *   and source identity are byte-identical to the previous head is a no-op, and writing it would let
+ *   three capture boundaries per session grow memory.db without bound for sessions that changed
+ *   nothing. The caller does not write when `skipped` is present.
+ */
+export function buildProjectProgression({
+  resolution,
+  payload = {},
+  host = 'claude',
+  env = process.env,
+  now = () => new Date().toISOString(),
+  trigger = payload.hook_event_name,
+} = {}) {
+  if (!resolution || typeof resolution !== 'object') throw new TypeError('resolution must be a project store resolution');
+  const source = readSourceIdentity({ checkoutRoot: resolution.checkoutRoot, kind: resolution.kind });
+  const ledger = readWorkLedger({ projectId: resolution.projectIdentity.id, env });
+  const note = readOwnerNote(() => ownerNoteRows(resolution.canonicalAgentDbPath, path.basename(resolution.projectRoot)));
+  const transcript = readTranscriptReference(payload.transcript_path, { host });
+  const { heads } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity);
+
+  const priorSequence = heads.reduce((highest, head) => Math.max(highest, head.sequence ?? 0), 0);
+  const priorState = heads.length === 1 ? heads[0].completeProjectState : null;
+
+  const provenance = {};
+  const record = (field, sourceName) => { provenance[field] = marker(sourceName); };
+
+  // GOAL — the ledger's oldest open item is what the user actually committed to; the owner note and
+  // the prior head come next; the transcript is the last resort and is never authoritative.
+  let currentGoal = ledger.open[0] ?? null;
+  if (currentGoal) record('currentGoal', 'ledger');
+  else if (typeof priorState?.currentGoal === 'string' && priorState.currentGoal) {
+    currentGoal = priorState.currentGoal;
+    record('currentGoal', 'prior-head');
+  } else if (transcript.derivedGoal) {
+    currentGoal = transcript.derivedGoal;
+    record('currentGoal', 'transcript-derived');
+  } else if (note?.excerpt) {
+    currentGoal = note.excerpt.split('\n')[0].slice(0, 240);
+    record('currentGoal', 'owner-note');
+  } else record('currentGoal', 'none');
+
+  // NEXT ACTION — the next open ledger item, else the assistant's own last stated step (derived).
+  let nextAction = ledger.open[1] ?? ledger.open[0] ?? null;
+  if (nextAction) record('nextAction', 'ledger');
+  else if (transcript.derivedNextAction) {
+    nextAction = transcript.derivedNextAction;
+    record('nextAction', 'transcript-derived');
+  } else if (typeof priorState?.nextAction === 'string' && priorState.nextAction) {
+    nextAction = priorState.nextAction;
+    record('nextAction', 'prior-head');
+  } else record('nextAction', 'none');
+
+  const decisions = [];
+  if (ledger.objective && typeof ledger.objective.text === 'string' && ledger.objective.text) {
+    decisions.push({ text: ledger.objective.text, state: ledger.objective.state ?? null, source: 'ledger' });
+    record('decisions', 'ledger');
+  } else if (note?.excerpt) {
+    decisions.push({ text: note.excerpt, note: note.key, truncated: note.truncated, source: 'owner-note' });
+    record('decisions', 'owner-note');
+  } else record('decisions', 'prior-head');
+
+  record('plan', ledger.present ? 'ledger' : 'prior-head');
+  record('completed', ledger.present ? 'ledger' : 'prior-head');
+  record('inProgress', ledger.present ? 'ledger' : 'prior-head');
+  record('changedFiles', 'git');
+  record('sourceIdentity', 'git');
+
+  const completeProjectState = {
+    currentGoal,
+    nextAction,
+    acceptanceContract: priorState?.acceptanceContract ?? null,
+    activeProcess: 'ProjectContinuity',
+    activeStep: trigger ?? 'unknown',
+    plan: ledger.open.map((text) => ({ id: text.slice(0, 64), status: 'open', source: 'ledger' })),
+    completed: uniqueStrings(ledger.done),
+    inProgress: uniqueStrings(ledger.open),
+    blockers: [],
+    failures: [],
+    decisions,
+    // The three digests already identify the tree exactly; enumerating paths here would duplicate
+    // that and, for an untracked file, would put a filename we were never asked to keep into a row.
+    changedFiles: [],
+    commands: [],
+    proofArtifacts: [],
+    untested: [],
+    resumeConflicts: [],
+    provenance,
+    evidence: {
+      workLedger: { file: ledger.file, present: ledger.present, open: ledger.open.length, done: ledger.done.length },
+      ownerNote: note ? { key: note.key, excerptSha256: note.excerptSha256, truncated: note.truncated } : null,
+      transcript: transcript.reference ?? { skipped: transcript.skipped },
+      sourceCapture: { headStable: source.headStable, headAfter: source.headAfter ?? source.identity.head, kind: source.kind },
+    },
+  };
+
+  // REDACT HERE, NOT ONLY AT THE STORE.
+  //
+  // createProgressionSnapshot already redacts, so the STORED row was always safe. What was not safe
+  // was everything between: this function's return value is passed through a hook payload, appears
+  // in a receipt, and is exactly the kind of object a diagnostic line prints. A secret that is
+  // scrubbed on the way into the database but readable on the way there has not been protected, it
+  // has been moved. Redacting at the point of derivation makes the store's own pass a no-op second
+  // check rather than the only one (redactProgression is idempotent, so running it twice is free).
+  const { value: redactedProgression } = redactProgression({
+    canonicalAgentDbPath: resolution.canonicalAgentDbPath,
+    sourceIdentity: source.identity,
+    sequence: priorSequence + 1,
+    occurredAt: now(),
+    parentEventKeys: heads.map((head) => head.eventKey),
+    dedupId: `${host}:${payload.session_id ?? 'unknown-session'}:${trigger ?? 'unknown'}:${priorSequence + 1}`,
+    completeProjectState,
+  });
+  const projectProgression = redactedProgression;
+
+  // RETENTION (ADR-073). Three capture boundaries per session times every session is unbounded
+  // growth unless a capture that changes nothing writes nothing. Compare what a snapshot MEANS —
+  // the project state and the tree it describes — while deliberately ignoring the fields that always
+  // differ (sequence, timestamp, dedup id, the trigger that happens to be firing, and the evidence
+  // block's own timestamps), because comparing those would make every capture look novel.
+  const meaning = digestCanonical({
+    state: { ...projectProgression.completeProjectState, activeStep: null, evidence: null },
+    source: projectProgression.sourceIdentity,
+  });
+  const priorMeaning = heads.length === 1 ? digestCanonical({
+    state: { ...priorState, activeStep: null, evidence: null },
+    source: heads[0].sourceIdentity,
+  }) : null;
+
+  return {
+    projectProgression,
+    provenance,
+    meaningDigest: meaning,
+    ...(priorMeaning === meaning
+      ? { skipped: { reason: 'no-op capture: project state and source identity are identical to the current head' } }
+      : {}),
+  };
+}
+
+/** Stable identifier for one produced snapshot, for logs and receipts. */
+export function producedDigest(produced) {
+  return crypto.createHash('sha256').update(JSON.stringify(produced.projectProgression)).digest('hex');
+}