@gcunharodrigues/wrxn 0.13.2 → 0.14.0

package/payload/.wrxn/dream.cjs

@@ -40,6 +40,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 
 // kind → tier is the contract; the tier must agree with the kind. `rule → _rules` (dream-03) joins the
@@ -128,6 +129,16 @@ function wikiWritePage(root, tier, slug, description, body) {
   return JSON.parse(execFileSync('node', args, { encoding: 'utf8' }));
 }
 
+// Delete a page VIA the wiki adapter's delete-by-reference path (the indirection contract — dream never
+// unlinks a .md directly; --revert reverses this run's pages through it). wiki.cjs confines the delete to
+// the wiki subtree (tier allowlist + kebab slug); the audit-recorded tier/slug are dream-written, but the
+// flag-injection guard is the defense-in-depth backstop at the exec boundary (harvest parity).
+function wikiDeletePage(root, tier, slug) {
+  guardArgv([String(tier), String(slug)]);
+  const args = [wikiAdapter(), 'delete-page', String(tier), String(slug), '--root', root];
+  return JSON.parse(execFileSync('node', args, { encoding: 'utf8' }));
+}
+
 function normalizeTitle(t) {
   return String(t == null ? '' : t).toLowerCase().replace(/\s+/g, ' ').trim();
 }
@@ -169,6 +180,204 @@ function stampPageImportance(root, tier, slug, score) {
   fs.writeFileSync(file, stampImportance(fs.readFileSync(file, 'utf8'), score));
 }
 
+// ── lineage stamp — the provenance PRODUCER (S3 / #22) ─────────────────────────
+// Every committed page records WHO wrote it: origin_session (the session id), synth_run (the per-run id —
+// the SAME value that keys this run's audit-log commit event, so --revert can resolve "this run's pages"),
+// proposal_id (the staged proposal's stable id = its slug). Machine-written frontmatter only — the prose
+// body is preserved byte-for-byte, like importance: (no churn). This is the seam sub-epic ② reuses for
+// evidence citations (J = who wrote it). Values are sanitised to a single bare frontmatter scalar: a
+// newline would inject an arbitrary key, a colon creates YAML ambiguity — both are collapsed to a space
+// (same write-channel discipline as harvest's annotationValueProblem / importance's shape-safety).
+const LINEAGE_KEYS = ['origin_session', 'synth_run', 'proposal_id'];
+
+// One bare scalar — strip CR/LF/colon to a space so a hostile value can never inject a frontmatter key or
+// YAML mapping (mirrors stampImportance's shape-safety). Empty/undefined → 'unknown' so the key is always
+// present and parseable (a missing value must never silently drop a lineage key).
+function lineageScalar(value) {
+  const s = String(value == null ? '' : value).replace(/[\r\n:]+/g, ' ').trim();
+  return s || 'unknown';
+}
+
+// PURE in-place stamp (mirrors stampImportance): set each lineage key when present (no duplicate key), else
+// append it; the body after the closing fence is preserved byte-for-byte. A page with no frontmatter fence
+// is returned unchanged (defensive — wiki pages always carry one).
+function stampLineage(content, lineage) {
+  const text = String(content);
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return text;
+  const lines = m[1].split(/\r?\n/);
+  for (const key of LINEAGE_KEYS) {
+    const value = lineageScalar(lineage && lineage[key]);
+    let found = false;
+    for (let i = 0; i < lines.length; i++) {
+      if (new RegExp(`^${key}:\\s*`).test(lines[i])) { lines[i] = `${key}: ${value}`; found = true; break; }
+    }
+    if (!found) lines.push(`${key}: ${value}`);
+  }
+  // splice ONLY the frontmatter fence back; the body after the closing --- is byte-for-byte preserved.
+  return text.slice(0, m.index) + ['---', lines.join('\n'), '---'].join('\n') + text.slice(m.index + m[0].length);
+}
+
+// PURE resolver (deterministic given its injected IO): gather the evidence FACTS into { session, commit,
+// symbols }. The git HEAD resolver + the touched set + the session anchor are all injected, so the core is
+// unit-tested with no live repo (mirrors session-end-reward's gitFacts injection). FAIL-OPEN: a resolveHead
+// that throws or returns nothing → commit null (stampEvidence omits it); a missing touched set → []. NEVER
+// throws — a field that cannot be resolved must never break consolidation.
+function resolveEvidence({ session, resolveHead, touched } = {}) {
+  let commit = null;
+  try {
+    const head = typeof resolveHead === 'function' ? resolveHead() : null;
+    commit = head ? String(head) : null;
+  } catch {
+    commit = null; // no git binary / not a repo / detached → no commit (fail-open)
+  }
+  return {
+    session: session == null ? '' : String(session),
+    commit,
+    symbols: Array.isArray(touched) ? touched : [],
+  };
+}
+
+// ── evidence production IO (the real resolvers resolveEvidence injects at the CLI boundary) ─────
+// Resolve the install repo's current git HEAD sha — the citation's `commit`. Rooted at the install so a
+// nested cwd can't resolve a different repo's HEAD. Fail-open: no git binary / not a repo / detached →
+// null (commit omitted). Mirrors session-end-reward.cjs / session-start.cjs resolveGitHead byte-for-byte.
+function resolveGitHead(root) {
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const sha = String(out || '').trim();
+    return sha || null;
+  } catch {
+    return null; // no git binary / not a repo / detached with no commit → no commit (fail-open)
+  }
+}
+
+// The session-id → filename transform — MUST match code-intel-push's safeId byte-for-byte, or the read
+// targets the wrong .touched file (replicated here, no shared import — the self-contained discipline).
+function safeSessionId(sid) {
+  return String(sid || 'session').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'session';
+}
+
+// Read this session's edited paths from <root>/.wrxn/history/<safeId>.touched — the list code-intel-push
+// already maintains (REUSE; no new persistence path). Deduped, order preserved. FAIL-OPEN: an absent/
+// unreadable file → [] (the citation simply carries no symbols). This is the citation's `symbols` set.
+function readTouched(root, sessionId) {
+  if (!root) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, '.wrxn', 'history', `${safeSessionId(sessionId)}.touched`), 'utf8');
+  } catch {
+    return []; // absent / unreadable → no edits this session
+  }
+  const seen = new Set();
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const p = line.trim();
+    if (!p || seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+
+// Stamp the just-written wiki page's evidence in place (read → stampEvidence → write). Same page reach as
+// stampPageImportance/Lineage — the stamp never re-routes the write (AC6: the existing stamp seam, not a new one).
+function stampPageEvidence(root, tier, slug, evidence) {
+  const file = path.join(root, '.wrxn', 'wiki', tier, `${slug}.md`);
+  fs.writeFileSync(file, stampEvidence(fs.readFileSync(file, 'utf8'), evidence));
+}
+
+// Stamp the just-written wiki page's lineage in place (read → stampLineage → write). Same page reach as
+// stampPageImportance — the stamp never re-routes the write.
+function stampPageLineage(root, tier, slug, lineage) {
+  const file = path.join(root, '.wrxn', 'wiki', tier, `${slug}.md`);
+  fs.writeFileSync(file, stampLineage(fs.readFileSync(file, 'utf8'), lineage));
+}
+
+// ── evidence stamp — the forward citation PRODUCER (C3 / #36) ──────────────────
+// Every committed page records the FACTS that make its citation resolvable: `session` (the quote-verified
+// source anchor — the session id), `commit` (the real git HEAD at write time), `symbols` (the session's
+// .touched set). This FREEZES the evidence-frontmatter contract recon-wrxn ②'s edge resolver reads to draw
+// EVIDENCED_BY / DOCUMENTED_BY edges — every field is computed from ground truth, so the citation is
+// inherently resolvable. Written as an `evidence:` MAPPING (nested under one key, distinct from the flat
+// lineage/importance scalars). Machine-written frontmatter only — the prose body is preserved byte-for-byte.
+
+// One bare nested scalar (session/commit) — strip CR/LF/colon to a space so a hostile value can never
+// inject a frontmatter key or a YAML mapping (mirrors lineageScalar's shape-safety). Empty stays empty —
+// the session sentinel + the commit/symbols omission are the caller-visible policy applied in stampEvidence.
+function evidenceScalar(value) {
+  return String(value == null ? '' : value).replace(/[\r\n:]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// One symbol list item — additionally strip the inline-flow-list breakers ([ ] ,) so a path can never break
+// the `symbols: [a, b]` list shape (defense in depth; .touched values are real paths without these chars).
+function symbolScalar(value) {
+  return String(value == null ? '' : value).replace(/[[\],\r\n:]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// Drop any pre-existing `evidence:` mapping (its key line + the indented members beneath it) so a re-stamp
+// updates in place with no duplicate block — the in-place discipline stampLineage gets for free with flat keys.
+function stripEvidence(lines) {
+  const out = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (/^evidence:/.test(line)) { inBlock = true; continue; }   // the mapping key line → drop
+    if (inBlock && /^\s+\S/.test(line)) continue;                // an indented nested member → drop
+    inBlock = false;
+    out.push(line);
+  }
+  return out;
+}
+
+// PURE in-place stamp (mirrors stampLineage): append an `evidence:` mapping to the frontmatter fence; the
+// body after the closing fence is preserved byte-for-byte. A page with no frontmatter fence is returned
+// unchanged (defensive — wiki pages always carry one).
+function stampEvidence(content, evidence) {
+  const text = String(content);
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return text;
+  const ev = evidence || {};
+  const lines = stripEvidence(m[1].split(/\r?\n/)); // in-place: remove any prior evidence block first
+  lines.push('evidence:');
+  // session — always present: an unresolvable anchor falls back to the 'unknown' sentinel (parseable key).
+  lines.push(`  session: ${evidenceScalar(ev.session) || 'unknown'}`);
+  // commit / symbols — FAIL-OPEN: a field that cannot be resolved (no git HEAD → empty; empty .touched → no
+  // items) is OMITTED, never written blank. The block still writes with whatever facts ARE known.
+  const commit = evidenceScalar(ev.commit);
+  if (commit) lines.push(`  commit: ${commit}`);
+  const symbols = (Array.isArray(ev.symbols) ? ev.symbols : []).map(symbolScalar).filter(Boolean);
+  if (symbols.length) lines.push(`  symbols: [${symbols.join(', ')}]`);
+  // splice ONLY the frontmatter fence back; the body after the closing --- is byte-for-byte preserved.
+  return text.slice(0, m.index) + ['---', lines.join('\n'), '---'].join('\n') + text.slice(m.index + m[0].length);
+}
+
+// The current session id for a CLI-invoked adapter (no hook event payload exists here). The whole codebase
+// keys provenance off the session id; hooks read event.session_id, the synth path reads the .pending stash,
+// and Claude Code exports it to the environment — so a hand-run adapter resolves it from CLAUDE_SESSION_ID.
+// Absent ⇒ 'unknown' (fail-open: a missing session id must never break consolidation).
+function currentSession() {
+  return lineageScalar(process.env.CLAUDE_SESSION_ID);
+}
+
+// The per-run id, derived deterministically from the run's ISO timestamp (the SAME ts that keys this run's
+// audit-log commit event). No new clock read and no random/uuid — the run id IS the audit timestamp, which
+// is exactly what binds a stamped page to its audit entry for --revert. Colons stripped so it is a clean
+// frontmatter scalar (an ISO ts carries `:` in the time).
+function runIdFromTs(ts) {
+  return lineageScalar(ts);
+}
+
+// Read a committed page's full on-disk content (frontmatter + body). Reached by tier+slug under .wrxn/wiki/.
+function pageContent(root, tier, slug) {
+  return fs.readFileSync(path.join(root, '.wrxn', 'wiki', tier, `${slug}.md`), 'utf8');
+}
+
+// sha256 of a page's exact bytes — the integrity fingerprint --revert recomputes to detect a hand-edit
+// (mirrors harvest's mergeHash/decayHash sha256 discipline).
+function sha256(text) {
+  return crypto.createHash('sha256').update(String(text)).digest('hex');
+}
+
 // ── anti-superstition negative filters ────────────────────────────────────────
 // A mechanical backstop to the dream skill's prompt (the skill is the primary semantic filter; this is
 // "reinforced where mechanical"). Each pattern catches a class of transient/false "memory" that, if
@@ -504,6 +713,14 @@ function runCommit() {
   const io = makeIo(root);
   const source = readSource(); // null ⇒ legacy re-gate; string ⇒ re-verify every quote at the write boundary
   const staged = readStaged(root);
+  // One ts per run: it keys this run's audit event AND derives synth_run, so a stamped page's synth_run is
+  // byte-identical to the run id recorded in the audit log — the bind that lets --revert resolve this run.
+  const ts = new Date().toISOString();
+  const runId = runIdFromTs(ts);
+  const session = currentSession();
+  // C3 (#36): the forward citation FACTS, resolved ONCE per run from ground truth — the session anchor, the
+  // real git HEAD, the session's .touched symbol set. Fail-open by construction (resolveEvidence never throws).
+  const evidence = resolveEvidence({ session, resolveHead: () => resolveGitHead(root), touched: readTouched(root, session) });
   const written = [];
   const skipped = [];
   for (const slug of approved) {
@@ -521,7 +738,12 @@ function runCommit() {
     try {
       const r = wikiWritePage(root, p.tier, p.slug, p.title, p.body);
       stampPageImportance(root, p.tier, p.slug, p.confidence); // persist dream's score as importance: (harvest-10)
-      written.push({ slug: p.slug, tier: p.tier, file: r.written });
+      stampPageLineage(root, p.tier, p.slug, { origin_session: session, synth_run: runId, proposal_id: p.slug }); // S3 provenance
+      stampPageEvidence(root, p.tier, p.slug, evidence); // C3 (#36): forward citation facts (session/commit/symbols)
+      // capture the content hash of EXACTLY what this run wrote (after all stamps) so --revert can detect a
+      // page hand-edited since (current hash ≠ this) and refuse to clobber it.
+      const hash = sha256(pageContent(root, p.tier, p.slug));
+      written.push({ slug: p.slug, tier: p.tier, file: r.written, hash });
     } catch (err) {
       // wiki.cjs write-page does process.exit(2) on an existing page — catch the non-zero exit so a
       // TOCTOU collision (or any single write failure) is recorded and the rest of the batch STILL writes.
@@ -530,8 +752,108 @@ function runCommit() {
       skipped.push({ slug: key, reason });
     }
   }
-  appendLine(path.join(dreamDir(root), AUDIT_FILE), { ts: new Date().toISOString(), op: 'commit', written: written.map((w) => w.slug), skipped });
-  return print({ written, skipped });
+  // the audit commit event records this run's id + each written page's tier/slug/hash — the cross-check
+  // ledger --revert reads to reverse exactly this run's pages and detect hand-edits (#22).
+  appendLine(path.join(dreamDir(root), AUDIT_FILE), {
+    ts, op: 'commit', synth_run: runId, origin_session: session,
+    written: written.map((w) => w.slug),
+    pages: written.map((w) => ({ slug: w.slug, tier: w.tier, hash: w.hash })),
+    skipped,
+  });
+  return print({ written, skipped, synth_run: runId });
+}
+
+// ── revert (S3 / #22) — pull a bad consolidation batch back out ────────────────
+// Resolve EXACTLY the pages a given synth_run wrote (the audit commit event is the source of truth — we
+// never trust the on-disk synth_run stamp alone) and reverse them. SAFETY: a page hand-edited since the run
+// wrote it (its current sha256 no longer matches the hash the audit recorded at commit) is REFUSED and
+// reported, never clobbered; an unknown run id (no matching audit commit event) is REFUSED and reported.
+
+// Read the append-only audit log into an array of parsed records (malformed lines skipped; absent → []).
+function readAudit(root) {
+  let txt;
+  try {
+    txt = fs.readFileSync(path.join(root, ...DREAM_DIR, AUDIT_FILE), 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of txt.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try { out.push(JSON.parse(s)); } catch { /* skip a malformed audit line */ }
+  }
+  return out;
+}
+
+// The pages this run committed, per the audit log (the cross-check ledger). Gathers every `commit` event
+// whose synth_run matches, de-duplicating by tier/slug (a slug can't be committed twice in additive dream,
+// but be defensive). Returns [] when no commit event matches the run id → the caller reports unknown_run.
+function runPagesFromAudit(audit, runId) {
+  const seen = new Set();
+  const pages = [];
+  for (const rec of audit) {
+    if (!rec || rec.op !== 'commit' || rec.synth_run !== runId) continue;
+    for (const pg of Array.isArray(rec.pages) ? rec.pages : []) {
+      if (!pg || !pg.slug || !pg.tier) continue;
+      const key = `${pg.tier}/${pg.slug}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      pages.push({ slug: String(pg.slug), tier: String(pg.tier), hash: String(pg.hash || '') });
+    }
+  }
+  return pages;
+}
+
+// PURE revert planner (deterministic given the audit + a content reader). Classifies each audit page of the
+// run: missing (already gone — nothing to reverse), edited (current hash ≠ audit hash — REFUSE), or
+// reversible (hash matches → safe to delete). `readContent(tier, slug)` returns the page text or null when
+// absent. Unknown run (no audit pages) → { unknown_run:true }. v1 is delete-only: dream commit is purely
+// additive (it dedup-SKIPS a pre-existing slug, never overwrites — proven by the AC2-backward-safe test), so
+// a reverted page had no prior version to restore; reversing == removing the page the run created.
+function resolveRevert(audit, runId, readContent) {
+  const pages = runPagesFromAudit(audit, runId);
+  if (pages.length === 0) return { unknown_run: true, reversible: [], edited: [], missing: [] };
+  const reversible = [];
+  const edited = [];
+  const missing = [];
+  for (const pg of pages) {
+    const content = readContent(pg.tier, pg.slug);
+    if (content == null) { missing.push({ slug: pg.slug, tier: pg.tier }); continue; }
+    if (sha256(content) !== pg.hash) { edited.push({ slug: pg.slug, tier: pg.tier }); continue; } // hand-edited → refuse
+    reversible.push({ slug: pg.slug, tier: pg.tier });
+  }
+  return { unknown_run: false, reversible, edited, missing };
+}
+
+function runRevert() {
+  const runId = positionalFile(); // the run id is the lone positional after `revert`
+  const root = installRoot();
+  const audit = readAudit(root);
+  const plan = resolveRevert(audit, runId, (tier, slug) => {
+    try { return pageContent(root, tier, slug); } catch { return null; }
+  });
+  if (plan.unknown_run) {
+    print({ run: runId, reverted: [], refused: [], missing: [], reason: 'unknown_run' });
+    process.exit(2); // an unknown run id is refused (and reported) — not a silent no-op success
+  }
+  const reverted = [];
+  const failed = [];
+  for (const pg of plan.reversible) {
+    try {
+      wikiDeletePage(root, pg.tier, pg.slug);
+      reverted.push(pg.slug);
+    } catch (e) {
+      // a delete that fails (vanished page / wiki refusal) is recorded — never aborts the rest of the batch.
+      failed.push({ slug: pg.slug, reason: String((e && e.message) || 'delete_failed').split('\n')[0] });
+    }
+  }
+  const refused = plan.edited.map((p) => ({ slug: p.slug, reason: 'hand_edited' })); // hand-edited pages are NOT clobbered
+  appendLine(path.join(dreamDir(root), AUDIT_FILE), {
+    ts: new Date().toISOString(), op: 'revert', synth_run: runId,
+    reverted, refused, missing: plan.missing.map((p) => p.slug), failed,
+  });
+  return print({ run: runId, reverted, refused, missing: plan.missing.map((p) => p.slug), failed });
 }
 
 function main() {
@@ -543,8 +865,10 @@ function main() {
       return runStage();
     case 'commit':
       return runCommit();
+    case 'revert':
+      return runRevert();
     default:
-      process.stdout.write('Usage: node .wrxn/dream.cjs <check|stage|commit> <file.json> [--root <dir>]\n');
+      process.stdout.write('Usage: node .wrxn/dream.cjs <check|stage|commit> <file.json> | revert <run_id> [--root <dir>]\n');
       process.exit(cmd ? 2 : 0);
   }
 }
@@ -553,4 +877,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { stampImportance };
+module.exports = { stampImportance, stampLineage, stampEvidence, resolveEvidence, lineageScalar, sha256, resolveRevert, runPagesFromAudit };

package/payload/.wrxn/harvest.cjs

@@ -735,6 +735,142 @@ function composeSurvivor({ tier, slug, description, body, mergedFrom }) {
   ].join('\n');
 }
 
+// ── lineage stamp — the provenance PRODUCER (S3 / #22, mirrors dream.cjs) ───────
+// A merged survivor is a net-new durable page, so it records WHO wrote it: origin_session (the session id),
+// synth_run (the per-run id = this run's audit ts), proposal_id (the survivor slug). Machine-written
+// frontmatter only — the survivor body is preserved byte-for-byte (no churn). Replicated here (not imported)
+// because each install-only adapter is self-contained (node stdlib only) — same discipline as secretScan.
+const LINEAGE_KEYS = ['origin_session', 'synth_run', 'proposal_id'];
+
+// One bare frontmatter scalar — strip CR/LF/colon to a space so a value can never inject a key or YAML
+// mapping (composeSurvivor's frontmatter write-channel discipline). Empty → 'unknown' (the key is always present).
+function lineageScalar(value) {
+  const s = String(value == null ? '' : value).replace(/[\r\n:]+/g, ' ').trim();
+  return s || 'unknown';
+}
+
+// PURE in-place stamp: set each lineage key (no duplicate key) in the frontmatter fence; the body after the
+// closing fence is preserved byte-for-byte. No fence → returned unchanged (defensive — wiki pages carry one).
+function stampLineage(content, lineage) {
+  const text = String(content);
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return text;
+  const lines = m[1].split(/\r?\n/);
+  for (const key of LINEAGE_KEYS) {
+    const value = lineageScalar(lineage && lineage[key]);
+    let found = false;
+    for (let i = 0; i < lines.length; i++) {
+      if (new RegExp(`^${key}:\\s*`).test(lines[i])) { lines[i] = `${key}: ${value}`; found = true; break; }
+    }
+    if (!found) lines.push(`${key}: ${value}`);
+  }
+  return text.slice(0, m.index) + ['---', lines.join('\n'), '---'].join('\n') + text.slice(m.index + m[0].length);
+}
+
+// The current session id for this CLI-invoked adapter — Claude Code exports it; absent ⇒ 'unknown' (fail-open).
+function currentSession() {
+  return lineageScalar(process.env.CLAUDE_SESSION_ID);
+}
+
+// ── forward evidence stamp — the citation PRODUCER (C3 / #36, mirrors dream.cjs) ─
+// A merged survivor records the FACTS that make its citation resolvable: session (the consolidating
+// session id), commit (the real git HEAD at write time), symbols (the session's .touched set). The same
+// evidence-frontmatter contract recon-wrxn ②'s edge resolver reads. Replicated here (not imported) — each
+// install-only adapter is self-contained (node stdlib only), the same discipline as secretScan/stampLineage.
+
+// A bare nested scalar (session/commit) — strip CR/LF/colon so a value can never inject a key or YAML mapping.
+function evidenceScalar(value) {
+  return String(value == null ? '' : value).replace(/[\r\n:]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// A symbol list item — also strip the inline-flow-list breakers ([ ] ,) so a path can never break the list shape.
+function symbolScalar(value) {
+  return String(value == null ? '' : value).replace(/[[\],\r\n:]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// Drop any pre-existing `evidence:` mapping (key line + indented members) so a re-stamp has no duplicate block.
+function stripEvidence(lines) {
+  const out = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (/^evidence:/.test(line)) { inBlock = true; continue; }
+    if (inBlock && /^\s+\S/.test(line)) continue;
+    inBlock = false;
+    out.push(line);
+  }
+  return out;
+}
+
+// PURE in-place stamp (mirrors stampLineage): append an `evidence:` mapping to the frontmatter fence; the body
+// after the closing fence is preserved byte-for-byte. No fence → returned unchanged. FAIL-OPEN: an empty
+// commit/symbols field is OMITTED; session falls back to the 'unknown' sentinel so the key is always present.
+function stampEvidence(content, evidence) {
+  const text = String(content);
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return text;
+  const ev = evidence || {};
+  const lines = stripEvidence(m[1].split(/\r?\n/));
+  lines.push('evidence:');
+  lines.push(`  session: ${evidenceScalar(ev.session) || 'unknown'}`);
+  const commit = evidenceScalar(ev.commit);
+  if (commit) lines.push(`  commit: ${commit}`);
+  const symbols = (Array.isArray(ev.symbols) ? ev.symbols : []).map(symbolScalar).filter(Boolean);
+  if (symbols.length) lines.push(`  symbols: [${symbols.join(', ')}]`);
+  return text.slice(0, m.index) + ['---', lines.join('\n'), '---'].join('\n') + text.slice(m.index + m[0].length);
+}
+
+// PURE resolver (deterministic given injected IO): gather the evidence facts. The git HEAD resolver + touched
+// set + session anchor are injected, so the core is unit-tested with no live repo. FAIL-OPEN: a resolveHead
+// that throws/returns nothing → commit null; a missing touched set → []. NEVER throws.
+function resolveEvidence({ session, resolveHead, touched } = {}) {
+  let commit = null;
+  try {
+    const head = typeof resolveHead === 'function' ? resolveHead() : null;
+    commit = head ? String(head) : null;
+  } catch {
+    commit = null; // no git binary / not a repo / detached → no commit (fail-open)
+  }
+  return { session: session == null ? '' : String(session), commit, symbols: Array.isArray(touched) ? touched : [] };
+}
+
+// Resolve the install repo's current git HEAD — the citation's `commit`. Rooted at the install. Fail-open:
+// no git / not a repo → null (mirrors dream.cjs / session-end-reward.cjs resolveGitHead).
+function resolveGitHead(root) {
+  try {
+    const out = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const sha = String(out || '').trim();
+    return sha || null;
+  } catch {
+    return null;
+  }
+}
+
+// The session-id → filename transform — MUST match code-intel-push's safeId byte-for-byte (replicated, no import).
+function safeSessionId(sid) {
+  return String(sid || 'session').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'session';
+}
+
+// Read this session's edited paths from <root>/.wrxn/history/<safeId>.touched — the citation's `symbols` set
+// (REUSE the list code-intel-push maintains). Deduped, order preserved. FAIL-OPEN: absent/unreadable → [].
+function readTouched(root, sessionId) {
+  if (!root) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, '.wrxn', 'history', `${safeSessionId(sessionId)}.touched`), 'utf8');
+  } catch {
+    return [];
+  }
+  const seen = new Set();
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const p = line.trim();
+    if (!p || seen.has(p)) continue;
+    seen.add(p);
+    out.push(p);
+  }
+  return out;
+}
+
 // ── the wiki delete bridge (dream.cjs indirection contract) ──────────────────────
 function wikiAdapter() {
   return path.join(__dirname, 'wiki.cjs'); // sibling in the same install .wrxn/ dir
@@ -837,7 +973,7 @@ function runStage() {
 // proposal cannot write or delete (AC2). Then — and only then — WRITE THE SURVIVOR FIRST (knowledge
 // preserved), THEN delete each absorbed (AC4 survivor-before-delete). Atomic on validation: if ANY target
 // is unsafe the whole merge is refused (no partial delete). Returns { ok, ... } | { ok:false, reason }.
-function commitOne(root, rec) {
+function commitOne(root, rec, lineage, evidence) {
   const description = rec.description ? String(rec.description) : '';
   const sec = secretScan(`${description}\n${rec.body}`); // re-scan at the write boundary
   if (sec) return { ok: false, reason: sec };
@@ -869,8 +1005,18 @@ function commitOne(root, rec) {
   // WRITE THE SURVIVOR FIRST — the merged knowledge exists on disk before any page is deleted (AC4).
   const mergedFrom = targets.map((t) => t.slug).slice().sort();
   const page = composeSurvivor({ tier: rec.tier, slug: rec.slug, description, body: rec.body, mergedFrom });
+  // S3 (#22): stamp the survivor's lineage (origin_session/synth_run/proposal_id) into its frontmatter at
+  // compose time — proposal_id is the survivor slug. The body is preserved byte-for-byte (no churn).
+  const stamped = stampLineage(page, {
+    origin_session: (lineage && lineage.origin_session) || currentSession(),
+    synth_run: (lineage && lineage.synth_run) || 'unknown',
+    proposal_id: rec.slug,
+  });
+  // C3 (#36): stamp the forward citation evidence (session/commit/symbols) at compose time — beside lineage,
+  // before the write. The body is preserved byte-for-byte (no churn); fail-open omits any unresolved field.
+  const withEvidence = stampEvidence(stamped, evidence);
   fs.mkdirSync(path.dirname(survAbs), { recursive: true });
-  fs.writeFileSync(survAbs, page);
+  fs.writeFileSync(survAbs, withEvidence);
 
   // THEN delete each absorbed — ONLY the staged cluster members (no free-form delete path) (AC4).
   const deleted = [];
@@ -897,15 +1043,21 @@ function runCommit() {
   const staged = readStaged(root);
   const merged = [];
   const skipped = [];
+  // One ts per run: it keys this run's audit event AND is the survivors' synth_run, so a survivor's stamped
+  // synth_run is byte-identical to the run id in the audit log (S3 #22 provenance binding, dream parity).
+  const ts = new Date().toISOString();
+  const lineage = { origin_session: currentSession(), synth_run: lineageScalar(ts) };
+  // C3 (#36): the forward citation FACTS, resolved ONCE per run from ground truth (session/git HEAD/.touched).
+  const evidence = resolveEvidence({ session: lineage.origin_session, resolveHead: () => resolveGitHead(root), touched: readTouched(root, lineage.origin_session) });
   for (const ref of approved) {
     const key = String(ref);
     const rec = staged.get(key);
     if (!rec) { skipped.push({ survivor: key, reason: 'not_staged' }); continue; }
-    const res = commitOne(root, rec);
+    const res = commitOne(root, rec, lineage, evidence);
     if (res.ok) merged.push({ survivor: res.survivor, merged_from: res.merged_from, deleted: res.deleted, deleteFailed: res.deleteFailed });
     else skipped.push({ survivor: key, reason: res.reason });
   }
-  appendLine(path.join(harvestDir(root), AUDIT_FILE), { ts: new Date().toISOString(), op: 'commit', merged: merged.map((m) => m.survivor), skipped });
+  appendLine(path.join(harvestDir(root), AUDIT_FILE), { ts, op: 'commit', synth_run: lineageScalar(ts), origin_session: lineage.origin_session, merged: merged.map((m) => m.survivor), skipped });
   return print({ merged, skipped });
 }
 
@@ -1235,6 +1387,9 @@ module.exports = {
   descriptionProblem,
   composeSurvivor,
   isKebab,
+  // evidence stamp (C3 / #36) — pure citation primitives
+  stampEvidence,
+  resolveEvidence,
   // decay (harvest-04) — pure gate + annotation primitives
   reinforcedSet,
   dayStamp,