@gcunharodrigues/wrxn 0.4.0 → 0.6.0

package/manifest.json

@@ -23,6 +23,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/hooks/drift-detect.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/hooks/enforce-managed-guard.cjs",
       "class": "managed",
@@ -98,6 +103,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/dream/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/grill-me/SKILL.md",
       "class": "managed",
@@ -288,6 +298,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/sync/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/tdd/SKILL.md",
       "class": "managed",
@@ -408,6 +423,21 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/dream.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".wrxn/dream/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
+    {
+      "path": ".wrxn/sync.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",
@@ -438,6 +468,16 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/wiki/_rules/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
+    {
+      "path": ".wrxn/wiki/_slots/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": "docs/agents/domain.md",
       "class": "seeded",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"
@@ -13,7 +13,7 @@
     "manifest.json"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test --require ./test/setup.cjs"
   },
   "dependencies": {
     "recon-wrxn": "6.0.0-wrxn.3"

package/payload/.claude/hooks/drift-detect.cjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN drift-detect hook — reactive provenance-drift nudge (sync-07).
+// PostToolUse (Edit|Write). When an edit touches a SOURCE file that downstream wiki docs declare
+// `derived_from:`, it injects a <drift> nudge naming the affected doc(s) — so drift surfaces the moment
+// the source moves, not only at the next batch `wrxn sync`.
+//
+// Self-contained: ships into installs, MUST NOT import the kernel lib OR recon (node stdlib only).
+// Mechanical: a pure fs + string frontmatter scan, NO LLM call. Independent of sync-01 — it never reads
+// a `synced_to:` watermark and never writes; detection NUDGE only.
+//
+// Fail-open: any fault (no install root, unreadable wiki, a corrupt page, a missing dir) emits {} and
+// NEVER blocks the edit.
+//
+// Contract: PostToolUse event JSON on stdin → envelope JSON on stdout (exit 0).
+
+const fs = require('fs');
+const path = require('path');
+
+function emit(envelope) {
+  process.stdout.write(JSON.stringify(envelope));
+  process.exit(0);
+}
+
+function findInstallRoot(startDir) {
+  let dir = startDir || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, 'wrxn.install.json'))) return dir;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// Normalize a path-ish value to an install-root-relative POSIX path. Drops a `#symbol` anchor
+// (sync's `derived_from: path#symbol` form), then resolves relative/absolute/`./`-prefixed forms to
+// the same canonical key so same-path and relative-path declarations both match. Returns '' on empty.
+function relTo(root, p) {
+  const s = String(p == null ? '' : p).split('#')[0].trim();
+  if (!s) return '';
+  const abs = path.isAbsolute(s) ? s : path.resolve(root, s);
+  return path.relative(root, abs).split(path.sep).join('/');
+}
+
+function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, '').trim();
+}
+
+// Extract the frontmatter block (between the leading `---` fence and the next `---`). A page without a
+// closed fence yields '' — its provenance is unreadable, so it simply contributes no declaration.
+function frontmatter(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  return m ? m[1] : '';
+}
+
+// Parse the `derived_from:` declaration(s) from a page's frontmatter. Handles a scalar, an inline list
+// (`[a, b]`), and a block list (`- item` lines). Returns the raw value strings (anchors intact).
+function parseDerivedFrom(content) {
+  const fm = frontmatter(content);
+  if (!fm) return [];
+  const lines = fm.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^derived_from:\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const val = m[1].trim();
+    if (val.startsWith('[')) {
+      // inline list: [a, b, c]
+      for (const part of val.replace(/^\[|\]$/g, '').split(',')) {
+        const v = unquote(part);
+        if (v) out.push(v);
+      }
+    } else if (val) {
+      out.push(unquote(val));
+    } else {
+      // block list: subsequent `  - item` lines until the first non-item line
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        const v = unquote(li[1]);
+        if (v) out.push(v);
+      }
+    }
+  }
+  return out;
+}
+
+// Collect every .md page under <root>/.wrxn/wiki/ (recursively). A missing/unreadable dir yields [].
+function collectDocs(wikiDir, acc) {
+  let entries;
+  try {
+    entries = fs.readdirSync(wikiDir, { withFileTypes: true });
+  } catch {
+    return acc; // missing/unreadable tree → no docs
+  }
+  for (const e of entries) {
+    const full = path.join(wikiDir, e.name);
+    if (e.isDirectory()) collectDocs(full, acc);
+    else if (e.isFile() && e.name.endsWith('.md')) acc.push(full);
+  }
+  return acc;
+}
+
+// The set of doc relpaths whose frontmatter declares `derived_from:` the edited path.
+function affectedDocs(root, editedRel) {
+  const wikiDir = path.join(root, '.wrxn', 'wiki');
+  const hits = new Set();
+  for (const file of collectDocs(wikiDir, [])) {
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue; // skip an unreadable page (fail-open per-file)
+    }
+    const docRel = path.relative(root, file).split(path.sep).join('/');
+    if (docRel === editedRel) continue; // never flag the edited file against itself
+    for (const raw of parseDerivedFrom(content)) {
+      if (relTo(root, raw) === editedRel) {
+        hits.add(docRel);
+        break;
+      }
+    }
+  }
+  return [...hits].sort();
+}
+
+function main() {
+  let event = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin.trim()) event = JSON.parse(stdin);
+  } catch {
+    emit({});
+  }
+
+  const root = findInstallRoot();
+  if (!root) emit({});
+
+  const filePath = event.tool_input && event.tool_input.file_path;
+  if (!filePath || typeof filePath !== 'string') emit({}); // not a file-touching tool
+
+  const editedRel = relTo(root, filePath);
+  if (!editedRel) emit({});
+
+  const docs = affectedDocs(root, editedRel);
+  if (docs.length === 0) emit({}); // no downstream provenance → silent
+
+  const ctx = [
+    '<drift>',
+    `Edited ${editedRel} — ${docs.length} downstream doc(s) declare derived_from it and may now be stale:`,
+    ...docs.map((d) => `  - ${d}`),
+    'Re-derive the affected doc(s), or run `wrxn sync` to confirm the drift set.',
+    '</drift>',
+  ].join('\n');
+
+  emit({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: ctx } });
+}
+
+try {
+  main();
+} catch {
+  emit({});
+}

package/payload/.claude/hooks/synapse-engine.cjs

@@ -257,6 +257,7 @@ function handoffDirective(consumed, pct) {
     '  1. Finish the current request.',
     '  2. Run the handoff skill to write the baton (a compact handoff document).',
     '  3. Tell the operator to /clear and open a fresh session, where the baton injects on resume.',
+    '  Suggestion (optional, before step 2): run the dream skill to consolidate this session\'s durable learnings into wiki memory — a suggestion only; dream never auto-runs, it acts only when you invoke it.',
   ].join('\n');
 }
 

package/payload/.claude/hooks/wiki-lint.cjs

@@ -15,6 +15,9 @@
 const fs = require('fs');
 const path = require('path');
 
+// The human-prose tiers only. The `_`-prefixed tiers (`_rules` and `_slots`) are machine-written by the
+// dream adapter through wiki.cjs — they are deliberately OUTSIDE this human-prose frontmatter lint, not
+// an omission (dream-03: no silent divergence).
 const TIERS = ['concepts', 'decisions', 'gotchas', 'sessions'];
 const REQUIRED_KEYS = ['name', 'description', 'tier'];
 const MAX_FLAGGED = 20;

package/payload/.claude/settings.json

@@ -45,7 +45,8 @@
       {
         "matcher": "Edit|Write",
         "hooks": [
-          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/code-intel-push.cjs\"" }
+          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/code-intel-push.cjs\"" },
+          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/drift-detect.cjs\"" }
         ]
       }
     ],

package/payload/.claude/skills/dream/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: dream
+description: Consolidate the live session into durable wiki memory — reflect on this conversation, draft evidence-backed Proposals (concept/decision/gotcha/rule), gate each through the dream adapter, and on your confirmation write net-new pages the Brain will recall next time. Use when someone says "dream", "consolidate this session", "save what we learned", or wants to capture durable memory before a handoff.
+user-invocable: true
+---
+
+# dream — session consolidation
+
+dream turns what you learned in **this session** into durable wiki pages the **Brain** will recall in
+future sessions. You **propose**; the deterministic adapter **judges**. Every page must quote the
+session that justifies it, and **nothing is written without the operator's confirmation** — so a bad
+proposal can never poison recall. "Bad memory is worse than no memory."
+
+## Indirection contract (MUST)
+
+> Drive the adapters. NEVER write wiki files directly and NEVER re-implement the gate.
+
+- Validate / stage / commit go through **`.wrxn/dream.cjs`** (the Validation gate + audit + writer).
+- Wiki reads (to check what already exists, or to confirm recall) go through **`.wrxn/wiki.cjs`**.
+- The skill is the **semantic** filter (you don't even draft junk); the adapter is the **mechanical**
+  backstop (it rejects what slips through). Run a proposal the gate rejected? It is never written.
+
+## The loop
+
+1. **Reflect** on the live conversation already in your context. Do NOT read transcripts or stored
+   session pages — reflect on what is in front of you, this session only.
+2. **Draft** candidate Proposals (see schema + rubric below), each grounded in a **verbatim quote**
+   from THIS session. If the session yields no durable insight, **abstain** — propose nothing.
+3. **check** the batch through the adapter; drop or fix anything it rejects (never carry a reject
+   forward).
+4. **stage** the validated batch — records it to the audit trail, outside the recalled wiki.
+5. **Present** the staged batch to the operator and wait for confirmation.
+6. **commit** only the operator-approved subset — net-new pages, additively, into their tiers.
+
+If reflection surfaces nothing durable, or the gate rejects every proposal, **stop**: say so, stage
+nothing, commit nothing. Restraint is a success, not a failure.
+
+## FAITHFULNESS — the most important rule
+
+The wiki records *what happened in this project, this session* — not what you know about the topic in
+general. You are not writing tutorials, documentation, or reference material. Every claim in every
+page MUST trace to the session in front of you.
+
+Do NOT:
+- Invent dates, version numbers, commit hashes, author names, file paths, function names, line
+  numbers, or error codes that did not appear in the session.
+- Add "When to use" / "Best practices" / "Alternatives" / "See also" sections that weren't grounded in
+  the session — those are reference-material patterns, not memory.
+- Enumerate options that weren't actually considered, or expand a terse operator comment into an essay.
+- Fabricate code or speculate about consequences the session itself didn't raise.
+- **Write a session secret into a page.** Redact any credential (API key, token, private key) that
+  surfaced in the session — a durable page is recalled forever. The gate also rejects `contains_secret`,
+  but you are the first filter.
+
+Do:
+- Compress the session into well-titled pages with the right `kind`.
+- **Preserve the operator's actual phrasing** for decisions and rules — it is load-bearing.
+- Write each page at the length the session actually warrants — dense fact, no padding, no truncation.
+- If the session yields no durable insight, **abstain**. Resist the urge to manufacture content.
+
+## What to propose — the `kind` rubric
+
+Exactly one kind per Proposal; `tier` must agree with `kind`.
+
+| kind       | tier         | propose when the session produced…                                            |
+|------------|--------------|-------------------------------------------------------------------------------|
+| `decision` | `decisions`  | a choice of X over Y, with its rationale and consequences (why the project is the way it is) |
+| `gotcha`   | `gotchas`    | a reproducible pitfall / failure mode, its root cause, and the mitigation     |
+| `concept`  | `concepts`   | stable architecture or domain knowledge (synthesis, not a task chronology)    |
+| `rule`     | `_rules`     | an always/never project convention the session established — a standing rule, recalled like a concept (NOT a SYNAPSE always-on rule; see Boundaries) |
+
+Two unrelated insights stay **two** pages — never merge them into one. Small pages, stable
+kebab-case names (Karpathy LLM-wiki style). Cap a run at **≤ 5** proposals.
+
+## What NOT to propose — anti-superstition
+
+Do not even draft these. A transient or false "memory", once recalled, hardens into a permanent false
+constraint on every future session. (The adapter rejects them too — but you are the first filter.)
+
+| Reject                          | Why                                                                  |
+|---------------------------------|----------------------------------------------------------------------|
+| "tool X is broken"              | A broad negative tool claim hardens into a permanent false refusal after the tool is fixed. |
+| Transient env / setup failures  | ENOENT, connection refused, timeouts, flaky/intermittent, rate-limits, a missing binary — stale false constraints, not durable truth. |
+| Smoke / sanity / happy-path checks | Operational evidence, not reusable knowledge.                     |
+| Release / version markers       | A one-time event (a version bump, a changelog, an npm publish), not a lesson. |
+| One-off task narratives         | "Renamed a file", "fixed a typo", a trivial chore — episodic, already captured. |
+| **wrxn itself**                 | Never memorialize wrxn's own routing / skills / synapse / hooks / constitution / adapters — the memory system must not pollute itself. |
+
+## Proposal schema
+
+A Proposal is one JSON object. A run is a JSON **array** of them (the batch).
+
+```jsonc
+{
+  "kind":  "concept" | "decision" | "gotcha" | "rule",      // pick one
+  "tier":  "concepts" | "decisions" | "gotchas" | "_rules", // = f(kind); MUST agree
+  "slug":  "kebab-case-page-name",                  // stable name
+  "title": "One-line page title",
+  "body":  "# Title\n\n…markdown… ",                // MUST start with '# '
+  "confidence": 0.0,                                 // honest 0–1; the gate floor is 0.75
+  "rationale": "Why this is durable.",
+  "evidence": [                                      // >= 1, each a VERBATIM quote from THIS session
+    { "quote": "exact words from the session", "source": "file:line | commit | turn-N" }  // source optional
+  ]
+}
+```
+
+## Driving the adapter
+
+Run from inside the install (the adapter walks up to `wrxn.install.json` to find the root — no
+`--root` needed). Write each batch to a **throwaway temp file** (it is scratch input, not a wiki page;
+only the adapter's own `.wrxn/dream/*.jsonl` audit files persist).
+
+**1 — check** (the gate; PROPOSE, then let it JUDGE):
+
+```bash
+node .wrxn/dream.cjs check /tmp/dream-batch.json
+```
+
+A batch returns `{ abstained, accepted[], rejected[ {index, slug, reason} ] }`. Each `reason` is a
+machine code — `confidence_below_threshold`, `missing_evidence`, `missing_rationale`,
+`body_missing_h1`, `body_too_large`, `invalid_slug`, `missing_title`, `invalid_title`,
+`unsupported_tier`, `kind_tier_mismatch`, `contains_secret`, `duplicate_existing_path`,
+`duplicate_existing_title`, `max_proposals_exceeded`, or a `negative_filter_*`. Fix or drop every
+rejected proposal; re-check until the batch is clean. If it returns `{ abstained: true }` (or every
+proposal is rejected), **stop** — write nothing.
+
+If the gate rejects a genuinely durable insight on a `negative_filter_*` **false positive** (e.g. a real
+decision that merely mentions "transient", "synapse", or "release"), **rephrase** the page to drop the
+transient/operational wording — state the durable decision, not the episodic event — then re-check.
+Never write around the gate.
+
+**2 — stage** (record the validated batch to the audit trail; nothing reaches the wiki yet):
+
+```bash
+node .wrxn/dream.cjs stage /tmp/dream-batch.json
+```
+
+**3 — present, then confirm.** Show the operator each staged proposal — its **tier/slug**, **title**,
+**confidence**, the **verbatim evidence quote**, and the one-line rationale — and ask which to approve.
+Never skip this step. If the operator approves none, you are done: commit nothing.
+
+**4 — commit** (write ONLY the operator-approved subset, **by reference**). Build a JSON array of the
+approved **slugs** — NOT a rebuilt Proposal array — and commit it:
+
+```bash
+node .wrxn/dream.cjs commit /tmp/dream-approved.json   # ["slug-a","slug-b"]  (or {"approved":["slug-a",…]})
+```
+
+`commit` reads `.wrxn/dream/staged.jsonl`, finds each approved slug's **staged** proposal, **re-runs the
+gate** on it (confidence, evidence, body H1, kind↔tier, secret-scan, negative filters, identity, dedup —
+everything `check` ran), and writes ONLY the ones that still pass — net-new pages, additively, via
+`wiki.cjs`. It **dedup-skips** any whose path already exists (never clobbers a curated page); a slug not
+staged (`not_staged`) or one that fails re-validation is recorded skipped with the reason. Returns
+`{ written[], skipped[] }`. This binds *committed == staged == presented*: a proposal the gate would
+reject can never be written, even if its slug is force-approved.
+
+**5 — confirm recall (optional).** The committed pages are plain `.md` in the wiki, so the Brain
+recalls them automatically next session. Spot-check with a wiki query:
+
+```bash
+node .wrxn/wiki.cjs query "<a phrase from a page you just wrote>"
+```
+
+## Refreshing the focus slot
+
+`_slots/current-focus.md` is the project's **durable standing focus** — a short statement of what the
+project is centered on right now, recall-surfaced like any other page. It is the **lone updatable wiki
+page**: every knowledge page is additive + dedup-skip, but the focus slot may be **overwritten in
+place**.
+
+This is **not** the knowledge-proposal loop — do not run a focus update through `check` / `stage` /
+`commit` (those are for evidence-backed concept/decision/gotcha/rule pages). The slot has its **own op**:
+
+1. Draft a short standing-focus statement (a few lines of markdown, body starting with `# `).
+2. **Present it to the operator and wait for confirmation** — like every dream write.
+3. On approval, write it via the dedicated op — it overwrites the slot in place:
+
+```bash
+node .wrxn/dream.cjs set-focus /tmp/dream-focus.json   # { "title": "Current focus", "body": "# Current focus\n\n…" }
+```
+
+The focus slot is **gated** too: `set-focus` runs the anti-superstition negative filters and the
+credential secret-scan over the focus body and **refuses** (writing nothing) if either fires. Redact
+secrets and pin durable standing context, not a transient note.
+
+**Continuity doctrine — do not cross these wires.** The focus slot is **disjoint** from the handoff
+**baton** (`.wrxn/continuity/latest.md`): different path, different writer. `set-focus` NEVER reads or
+writes the baton, and the **handoff** skill remains its sole writer. The baton is ephemeral cross-session
+resume; the focus slot is durable standing context. Keeping their paths and writers separate is the
+structural fix that stops a deliberate handoff from being clobbered.
+
+## Boundaries
+
+- **Current session only.** No transcript mining, no cross-session backlog.
+- **Additive only, save one slot.** dream creates net-new knowledge pages; merging or refreshing an
+  existing page is out of scope (that is harvest, a later phase). The **lone exception** is the focus
+  slot `_slots/current-focus.md`, which `set-focus` overwrites in place (see *Refreshing the focus slot*).
+- **Never autonomous.** dream is a deliberate, attended, operator-confirmed skill — never a background
+  run, never a write without confirmation.
+- **`_rules` ≠ SYNAPSE.** A `rule` page is *recalled knowledge* — the Brain surfaces it like a concept
+  or gotcha. It is NOT a SYNAPSE always-on rule. Promoting a `_rules` page into SYNAPSE's curated
+  always-injected set (`.synapse/`) is a separate, deliberate act — **dream NEVER edits `.synapse/`**.
+
+## Source
+
+WRXN Kernel issue dream-02. Adapter: `.wrxn/dream.cjs` (dream-01). Prompts adapted from
+`akitaonrails/ai-memory` (`auto_improve` system prompt, the `batch_consolidate` FAITHFULNESS block,
+the `kind` rubric, the `docs/auto-improvement-loop.md` negative-filter list). ADR 0003; PRD
+`dream-prd`.

package/payload/.claude/skills/handoff/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "What will the next session be used for?"
 
 Write a handoff document summarising the current conversation so a fresh agent can continue the work.
 
+Before writing the baton, OFFER to run the `dream` skill to consolidate this session's durable learnings into wiki memory (concept/decision/gotcha/rule pages the Brain recalls next session). This is an offer only — run `dream` solely if the operator agrees; never auto-run it. `dream` writes additive wiki pages (and may refresh its own `_slots/current-focus.md`), while this skill remains the SOLE writer of `.wrxn/continuity/latest.md` — the two are disjoint, so neither clobbers the other.
+
 Save it to the install's continuity slot: `.wrxn/continuity/latest.md` (resolve the install root by walking up to the `wrxn.install.json` receipt; create the `.wrxn/continuity/` directory if absent). This slot is the deliberate, intent-carrying baton — the NEXT session's `session-start` hook injects its contents as the resume surface, taking precedence over the automatic episodic session page.
 
 CONTINUITY DOCTRINE: this skill is the SINGLE writer of `.wrxn/continuity/latest.md`. The automatic `session-end` hook writes ONLY dated session pages under `.wrxn/wiki/sessions/` and NEVER touches the baton — so a deliberate handoff is never clobbered by the automatic episodic record. Overwrite the previous baton (the latest deliberate handoff is the live one).

package/payload/.claude/skills/sync/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: sync
+description: Report which derived docs have drifted from the source code they describe — query recon's computable drift set over the warm serve door and list each stale page, the source symbol that moved, and the watermark it was last reconciled at. Use when someone says "sync", "check for stale docs", "what docs have drifted", or wants to know if the prose is still reconciled with the code before a handoff or release.
+user-invocable: true
+---
+
+# sync — drift report
+
+`sync` tells you which **derived prose** has fallen out of step with the **source code** it documents.
+A page that declares `derived_from: path#symbol` carries a `synced_to:` watermark — the source version
+it was last reconciled against. recon-wrxn computes, purely from its index, the set of docs whose source
+symbol has since changed (an AST fingerprint, so reformatting and comment edits do **not** trip drift).
+This skill **queries that set and reports it**. It is the third maintenance loop alongside `dream`
+(memory) — `sync` keeps derived prose reconciled with source.
+
+> The **report** is read-only — it never edits a doc or advances a watermark. For **prose** drift you can
+> then go one step further: `sync` can DRAFT a reconciling edit and, on your explicit confirm, write it in
+> place and advance the watermark (the `propose → confirm` loop below). Auto-regen of *mechanical* derived
+> files is still a separate, later step.
+
+## Indirection contract (MUST)
+
+> Drive the adapter. NEVER hand-compute drift, re-read a doc's frontmatter, or write any file.
+
+- The drift query goes through **`.wrxn/sync.cjs report`** (the install-local door client + report gate).
+- The adapter consumes the `synced_to` watermark **from the recon_drift door response** — recon parsed
+  it out of the doc's frontmatter. Do not open wiki files to re-derive it; `sync` is strictly read-only.
+
+## The loop
+
+1. **Run the report** from inside the install (the adapter walks up to `wrxn.install.json` — no `--root`
+   needed):
+
+   ```bash
+   node .wrxn/sync.cjs report
+   ```
+
+2. **Read the JSON** it prints — `{ status, stale[], unwatermarked[] }`:
+
+   - **`status: "synced"`** — the stale set is empty. **Say so briefly ("all synced") and stop.** Do not
+     manufacture findings. A clean tree is a successful no-op.
+   - **`status: "drift"`** — present each `stale[]` entry to the operator: the **doc** page, the **symbol**
+     that moved, and **`synced_to` → `current`** (the watermark vs the source's current fingerprint). If
+     `unwatermarked[]` is non-empty, note those separately — docs that declare `derived_from` but were
+     never watermarked (so drift can't yet be computed for them).
+   - **`status: "unavailable"`** — recon's serve door is not warm (no `recon-wrxn serve` running, or it was
+     unreachable). Report "drift unavailable — start `recon-wrxn serve` and retry." Never treat this as
+     "all synced": unknown is not clean.
+
+3. **Decide per stale doc.** Hand the stale list to the operator. For a **prose** page, you may reconcile
+   it with the `propose → confirm` loop below. Regenerating a *mechanical* derived file is still out of
+   scope here.
+
+## Propose → confirm (prose re-stamp, sync-06)
+
+For a stale PROSE doc, reconcile it WITHOUT ever auto-rewriting words: you draft the edit, the operator
+confirms, then the watermark advances. The watermark means **"verified fresh"**, never "stamped without
+checking". Same split as `dream`: **you (the skill) draft the prose; `.wrxn/sync.cjs` gates and writes.**
+
+1. **Draft + propose (stage).** From a `stale[]` entry, write the reconciling markdown body and stage it
+   by-reference — secret-scanned, recorded under `.wrxn/sync/staged.jsonl`, the live doc untouched:
+
+   ```bash
+   node .wrxn/sync.cjs propose proposal.json
+   ```
+
+   `proposal.json` carries the drift record's own fields (do NOT re-derive them) plus your drafted body:
+
+   ```json
+   { "doc": ".wrxn/wiki/concepts/auth-flow.md", "symbol": "src/auth.ts#login",
+     "synced_to": "<old watermark from the report>", "current": "<current fingerprint from the report>",
+     "body": "# Auth flow\n\n…the reconciled prose…" }
+   ```
+
+2. **Present it to the operator and wait.** Show the drafted edit. Nothing is written and the watermark is
+   NOT advanced until the operator confirms — staging alone never re-stamps.
+
+3. **Confirm (commit) or decline.** On approval, confirm BY REFERENCE (the doc path). The adapter re-reads
+   the staged edit, re-runs the secret-scan + an integrity check (a tampered or altered proposal cannot
+   write), edits the doc in place, and advances `synced_to:` to `current`:
+
+   ```bash
+   node .wrxn/sync.cjs confirm approved.json
+   ```
+
+   where `approved.json` is the operator-approved doc list — `[".wrxn/wiki/concepts/auth-flow.md"]` or
+   `{ "approved": [".wrxn/wiki/concepts/auth-flow.md"] }`. **Decline** = confirm an empty approval
+   (`{ "approved": [] }`) — the file AND the watermark stay exactly as they were.
+
+## Boundaries
+
+- **Report is read-only.** Prose `propose → confirm` is the ONLY write path, and only on explicit operator
+  confirm. Regen of mechanical derived files is a later sync slice.
+- **Never auto-rewrite words.** The reconciling edit is staged and presented; the in-place write + watermark
+  advance happen only on confirm, re-validated at the write boundary.
+- **Declared provenance only.** Only docs carrying a `derived_from:` anchor participate; an undocumented
+  file is never "drifted". This is opt-in by provenance, by design.
+- **Fail-soft, never alarmist.** If recon is unreachable the answer is "unavailable", not "stale" and not
+  "synced". The adapter never throws; neither should your report.
+
+## Source
+
+WRXN Kernel issues sync-04 (report) + sync-06 (prose propose → confirm → re-stamp). Adapter: `.wrxn/sync.cjs`.
+Drift signal: recon-wrxn `recon_drift` (sync-03), watermark storage (sync-01) + AST fingerprint (sync-02).
+Door discovery mirrors `recall-surface.cjs`; skill+adapter shape (stage → commit-by-reference, secret-scan)
+mirrors `dream`. PRD `sync-prd`; ADR 0004.