@gcunharodrigues/wrxn 0.5.0 → 0.7.0

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

@@ -0,0 +1,210 @@
+---
+name: harvest
+description: Curate the knowledge tiers — run a health-check, then through operator-confirmed proposals MERGE near-duplicate pages into one evidence-grounded survivor and FORWARD-LINK or FLAG superseded/orphaned pages. The destructive sibling to dream (additive) and sync (drift). Use when someone says "harvest", "curate the wiki", "merge duplicate pages", "clean up stale knowledge", or at handoff when there is curation debt.
+user-invocable: true
+---
+
+# harvest — knowledge curation
+
+harvest is the third maintenance loop, sibling to **dream** (consolidation, additive-only) and **sync**
+(drift). It does what dream deliberately doesn't: **merge, forward-link, and flag** the four knowledge
+tiers (`concepts` / `decisions` / `gotchas` / `_rules`), which silt up over time — near-duplicates pile
+beside each other, superseded pages linger next to their replacements, and pages whose source code was
+deleted go orphaned. Left alone, Recall surfaces a thicket where one clean page belongs.
+
+You **propose**; the deterministic adapter **gates and writes**. Every destructive act is shown to the
+operator and **nothing is merged, annotated, or deleted without confirmation** — and a rejected proposal
+is re-checked at the write boundary, so it can never mutate a page. The only sanctioned hard-delete is a
+**merge**: an absorbed page is deleted *only* once its content provably lives in the survivor.
+
+## Indirection contract (MUST)
+
+> Drive the adapter. NEVER edit, annotate, or delete a wiki page directly, and NEVER re-implement the gate.
+
+- Health-check, merge (`stage` / `commit`), and decay (`decay propose` / `decay confirm`) all go through
+  **`.wrxn/harvest.cjs`** — the report, the safety gate (secret-scan, integrity hash, path-confinement),
+  the audit trail, and the writer.
+- To DRAFT a survivor you may **read** the absorbed pages — they are plain `.md` at the paths the report
+  gives — and confirm recall via **`.wrxn/wiki.cjs query`**. Reading never mutates; the indirection
+  contract forbids only direct writes/deletes and re-implementing the gate.
+- The skill is the **semantic** filter (you don't draft a junk merge); the adapter is the **mechanical**
+  backstop (it rejects what slips through). A proposal the gate rejects is never written.
+
+## The loop
+
+1. **Health-check** — `node .wrxn/harvest.cjs check` writes a durable report; nothing is touched.
+2. **Read the report** — one record per finding: `near_dup` clusters, `decay_candidate`s
+   (orphaned / superseded), and `malformed` pages.
+3. **Per finding, draft a proposal** — a merge survivor for a near-dup cluster; a `stale:` /
+   `superseded_by:` annotation for a decay candidate.
+4. **Stage** — `stage` (merge) or `decay propose` (annotate): record by-reference, the live page untouched.
+5. **Present + confirm** — show the operator the survivor (and the pages it deletes) or the annotation, and
+   wait. Nothing is written on staging alone.
+6. **Commit** — `commit` (merge) or `decay confirm` (annotate) the operator-approved subset only.
+
+If the report is clean, **say so and stop** — a tree with no debt is a successful no-op. Do not manufacture
+findings.
+
+## 1 — Health-check (`check`)
+
+Run from inside the install (the adapter walks up to `wrxn.install.json` — no `--root` needed):
+
+```bash
+node .wrxn/harvest.cjs check
+```
+
+It scans the 4 tiers and writes a fresh, never-mutated `.wrxn/harvest/<ts>.jsonl`, then prints
+`{ report, summary: { nearDupStatus, findings: { near_dup, decay_candidate, malformed } } }`. Read the
+report file it names. Each record carries enough to seed a proposal:
+
+- **`near_dup`** — a cluster of pages over the measured semantic-similarity threshold (`members[]` with
+  `slug` / `path` / `tier`, the strongest-edge `score`). The merge candidates.
+- **`decay_candidate`** — `subtype: "orphaned"` (its `derived_from:` source file is gone, carries
+  `missing_source`). The decay candidates. Pages already annotated `stale:`/`superseded_by:` are treated
+  as resolved and excluded. A supersession is raised via `decay propose` with a replacement target
+  (operator/skill judgment), not auto-detected by `check`.
+- **`malformed`** — bad frontmatter (the wiki-lint signal). Report-only here (see §4).
+
+If `nearDupStatus` is `"unavailable"`, the recon serve door was cold — near-dup detection was **skipped**
+(the local decay + malformed scans still ran). Tell the operator "near-dup unavailable — start
+`recon-wrxn serve` and re-run `check`"; never read silence as "no duplicates".
+
+## 2 — Merge (a `near_dup` cluster → one survivor)
+
+A merge folds N near-duplicate pages into **one net-new survivor** and deletes the absorbed originals.
+The survivor is a **fresh** page (a new kebab slug, a path that does not yet exist) — list **every**
+near-dup member in `absorbed`, including any whose name you'd like to reuse (the adapter writes the
+survivor *before* it deletes, so the survivor path can't already exist). The survivor's provenance lands
+as `merged_from: [<absorbed slugs>]` on the surviving page.
+
+### The merge reflection rubric (MUST — run it before you stage)
+
+You are **merging, not authoring**. Read every absorbed page, then self-check the drafted survivor against
+each one. Stage only if all four hold:
+
+1. **No dropped facts.** Every distinct fact in *each* absorbed page appears in the survivor. A merge that
+   loses knowledge is worse than no merge.
+2. **No invented facts.** Every survivor line **traces to a source page** — do not add knowledge, dates,
+   versions, paths, or claims that were not in an absorbed page. If it isn't in a source, it doesn't belong
+   in the survivor.
+3. **Union of evidence preserved.** Every evidence quote, citation, and provenance marker from each
+   absorbed page is carried into the survivor — the merge is loss-free on evidence, not just on prose.
+4. **No secrets.** Redact any credential that surfaced (the gate also rejects `contains_secret`, but you
+   are the first filter).
+
+If any check fails, fix the survivor and re-run the rubric. If the cluster members are **not** actually
+duplicates (your judgment overrides the threshold), **abstain** — stage nothing for that cluster.
+
+### Stage the merge (PROPOSE)
+
+Write the proposal to a throwaway temp file and stage it by-reference (the live pages are untouched):
+
+```bash
+node .wrxn/harvest.cjs stage /tmp/harvest-merge.json
+```
+
+```jsonc
+{
+  "survivor":    ".wrxn/wiki/concepts/auth-flow.md",   // NEW path under a knowledge tier, .md, kebab slug
+  "description": "one-line page description",            // becomes the survivor's frontmatter description
+  "body":        "# Auth flow\n\n…the synthesised union…", // the rubric-checked survivor markdown
+  "absorbed":    [".wrxn/wiki/concepts/login-flow.md", ".wrxn/wiki/concepts/auth-overview.md"]
+}
+```
+
+`stage` path-confines the survivor + every absorbed target to a knowledge tier, rejects a body over the
+cap, secret-scans, then records the proposal + an integrity hash under `.wrxn/harvest/staged.jsonl`. It
+prints `{ staged, survivor, absorbed, stagedFile }` and **writes/deletes nothing**.
+
+### Present, then confirm
+
+Show the operator the **diff**: the absorbed pages (read them at the report's paths) and the one survivor
+that replaces them, naming exactly which pages will be **deleted**. Wait for confirmation. If the operator
+approves none, you are done — commit nothing.
+
+### Commit the merge (CONFIRM, by reference)
+
+Build a JSON array of the approved **survivor paths** (not a rebuilt proposal) and commit:
+
+```bash
+node .wrxn/harvest.cjs commit /tmp/harvest-approved.json   # [".wrxn/wiki/concepts/auth-flow.md"]  (or {"approved":[…]})
+```
+
+`commit` looks up each approved survivor's staged merge, **re-runs the gate** (secret-scan → integrity →
+path-confine survivor + every absorbed → survivor is new), then **writes the survivor first** (knowledge
+preserved) and **only then deletes each absorbed** (survivor-before-delete). It prints `{ merged, skipped }`.
+An **empty** approval is the decline — nothing changes.
+
+## 3 — Decay / supersession (a `decay_candidate` → annotate, never delete)
+
+Decay is **non-destructive**: it stamps a single forward-link key into a page's frontmatter (the body is
+byte-for-byte preserved) so Recall and the operator know its status. Provenance survives — decay never
+deletes (deletion is merge's job alone). Two kinds:
+
+- **`stale: <missing-source-path>`** — an orphaned page whose `derived_from:` source file is gone.
+  Mechanical: `decay propose` **auto-derives** these from the same scan `check` ran — no draft needed.
+- **`superseded_by: <path>`** — a page replaced by another. A **judgment** (auto-scan can't invent the
+  replacement) — you draft it into a proposal file.
+
+### Propose the decay (STAGE)
+
+Auto-scan only (stages a `stale:` annotation for every orphaned page):
+
+```bash
+node .wrxn/harvest.cjs decay propose
+```
+
+Or pass a draft file to add `superseded_by:` judgments (it overrides the auto stale for the same page):
+
+```bash
+node .wrxn/harvest.cjs decay propose /tmp/harvest-decay.json
+```
+
+```jsonc
+// one object, an array, or { "proposals": [ … ] }; key ∈ {stale, superseded_by}; value is a path
+{ "page": ".wrxn/wiki/gotchas/old-auth-bug.md", "key": "superseded_by",
+  "value": ".wrxn/wiki/gotchas/new-auth-bug.md", "reason": "replaced by the post-refactor write-up" }
+```
+
+`decay propose` gates each candidate — page confined + present, key allowlisted, value sanitised +
+secret-scanned, the page **not reinforced** (a page surfaced in Recall within the last 30 days is live
+knowledge and is skipped), and **not already annotated** (idempotent) — and records survivors to
+`.wrxn/harvest/decay-staged.jsonl`. It prints `{ staged, skipped, stagedFile }`. A `skipped` entry names
+its reason (`reinforced`, `already_annotated`, `unsafe_page`, …).
+
+### Present, then confirm
+
+Show the operator each staged annotation — the page, the key, the value, and the reason. Wait.
+
+### Confirm the decay (COMMIT, by reference)
+
+```bash
+node .wrxn/harvest.cjs decay confirm /tmp/harvest-decay-approved.json   # ["…/old-auth-bug.md"] (or {"approved":[…]})
+```
+
+`decay confirm` re-gates each approved page and stamps the one frontmatter key in place (body preserved,
+never deleted). It prints `{ annotated, skipped }`. An empty approval is the decline.
+
+## 4 — Malformed pages (report-only)
+
+`check` also reports pages with bad frontmatter. harvest does **not** auto-fix them — surface the list to
+the operator to repair by hand (the wiki-lint Stop hook flags the same signal). Fixing frontmatter is
+authoring, outside harvest's gated destructive scope.
+
+## Boundaries
+
+- **Curation only, on the 4 knowledge tiers.** Never the retired `sessions` tier, never `_slots`
+  (the focus slot is dream's), never code.
+- **Confirm-gated + re-checked.** Every merge and decay is staged, presented, and confirmed by reference;
+  the gate re-validates at the write boundary, so a rejected/tampered proposal can never mutate a page.
+- **Merge is the only hard-delete.** Decay forward-links / flags; it never deletes. No free-form delete
+  path exists — only a staged cluster's absorbed members are ever removed.
+- **Restraint.** A clean health-check is a success: say so, stage nothing, commit nothing.
+- **Never autonomous.** harvest is deliberate and operator-confirmed — never a background sweep.
+
+## Source
+
+WRXN Kernel issue harvest-06, integrating harvest-02 (`check`), harvest-03 (merge `stage` / `commit`),
+and harvest-04 (`decay propose` / `confirm`). Adapter: `.wrxn/harvest.cjs`. Skill + adapter shape and the
+propose→confirm-by-reference spine adapted from `dream` (`SKILL.md`, `.wrxn/dream.cjs`) and the `sync`
+report→propose→confirm walkthrough. ADR 0005; PRD `harvest-prd`.

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.

package/payload/.wrxn/dream.cjs

@@ -146,6 +146,43 @@ function normalizeTitle(t) {
   return String(t == null ? '' : t).toLowerCase().replace(/\s+/g, ' ').trim();
 }
 
+// ── importance stamp — the decay-weight PRODUCER (harvest-10) ──────────────────
+// dream already scores each page (`confidence`, gate floor 0.75) but never PERSISTED it, so recon
+// D1/D3's `recency × importance` recall weight collapsed to `recency × tier-prior`. On commit we persist
+// that EXISTING score as a single `importance:` frontmatter scalar — we do NOT recompute or invent a new
+// model. Clamped to [0,1] and rendered through Number() so it is one bare scalar that cannot inject a
+// newline/colon (AC4, same discipline as sync.cjs's `synced_to:` watermark).
+function clamp01(score) {
+  const n = Number(score);
+  if (Number.isNaN(n)) return 0; // a non-numeric/garbage score floors to 0 — never a raw string in the page
+  return Math.max(0, Math.min(1, n));
+}
+
+// PURE in-place stamp (mirrors sync.cjs restampDoc): update `importance:` when present (no duplicate key),
+// else append one frontmatter line; the body after the closing fence is preserved byte-for-byte (no churn).
+// A page with no frontmatter fence is returned unchanged (defensive — wiki pages always carry one).
+function stampImportance(content, score) {
+  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/);
+  const value = clamp01(score);
+  let found = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^importance:\s*/.test(lines[i])) { lines[i] = `importance: ${value}`; found = true; break; }
+  }
+  if (!found) lines.push(`importance: ${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);
+}
+
+// Stamp the just-written wiki page in place (read → stampImportance → write). The page is reached by its
+// tier+slug under .wrxn/wiki/ — the same page wiki.cjs just wrote — so the stamp never re-routes the write.
+function stampPageImportance(root, tier, slug, score) {
+  const file = path.join(root, '.wrxn', 'wiki', tier, `${slug}.md`);
+  fs.writeFileSync(file, stampImportance(fs.readFileSync(file, 'utf8'), score));
+}
+
 // ── 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
@@ -407,6 +444,7 @@ 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 });
     } catch (err) {
       // wiki.cjs write-page does process.exit(2) on an existing page — catch the non-zero exit so a
@@ -465,4 +503,8 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { stampImportance };