@gcunharodrigues/wrxn 0.7.1 → 0.8.0

package/manifest.json

@@ -343,6 +343,16 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/write-an-agent/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/skills/write-an-agent/EXAMPLES.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/audit/SKILL.md",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.7.1",
+  "version": "0.8.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"
@@ -16,11 +16,19 @@
     "test": "node --test --require ./test/setup.cjs"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.5"
+    "recon-wrxn": "6.0.0-wrxn.6"
   },
   "engines": {
     "node": ">=20"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gcunharodrigues/wrxn-kernel.git"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
   "license": "MIT",
   "private": false
 }

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

@@ -35,14 +35,17 @@ This skill **queries that set and reports it**. It is the third maintenance loop
    node .wrxn/sync.cjs report
    ```
 
-2. **Read the JSON** it prints — `{ status, stale[], unwatermarked[] }`:
+2. **Read the JSON** it prints — `{ status, stale[], unwatermarked[], orphaned[] }`:
 
-   - **`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: "synced"`** — both the stale AND orphaned sets are 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).
+     `orphaned[]` is non-empty, flag those DISTINCTLY — each is a **dangling** doc (`doc` + `synced_to`) whose
+     `derived_from:` source symbol was **renamed or deleted**, so its provenance is gone and drift can no
+     longer be computed. The reconcile loop below cannot fix an orphan (there is no live source to re-stamp
+     against); surface it so the operator can re-anchor or retire the page. If `unwatermarked[]` is non-empty,
+     note those separately — docs that declare `derived_from` but were never watermarked.
    - **`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.

package/payload/.claude/skills/write-an-agent/EXAMPLES.md

@@ -0,0 +1,38 @@
+# write-an-agent — Examples
+
+## A compressed read-only locator
+
+A canonical interactive subagent: a single job, a least-privilege grant (read-only — no `Bash`, so no
+push path), `haiku` (the work is mechanical), and a tight output contract with a concrete example.
+
+```
+---
+name: route-finder
+description: >
+  Read-only locator for HTTP routes. Returns a path:line table of where each route
+  is defined and its handler. Use PROACTIVELY when someone asks "where is the X
+  route", "what handles the Y endpoint", or "list all routes".
+tools: Read, Grep, Glob
+model: haiku
+---
+You locate HTTP routes and report them. Nothing else.
+
+## Process
+1. Grep for route definitions (router calls, decorators, path strings).
+2. Resolve each route's handler symbol.
+3. Emit the table. Stop.
+
+## Constraints
+- Read-only — never edit, run git, or propose changes.
+- No preamble, no prose padding.
+
+## Output
+Your final message IS the result. One row per route, nothing else:
+`METHOD /path — handler@file:line`
+Example:
+`GET /users — listUsers@api/users.ts:42`
+```
+
+**Why it's SOTA:** read-only grant (no push path), `haiku` (mechanical), the `description` leads
+delegation with "use PROACTIVELY" + exact trigger phrases, and the output contract is a fixed
+one-row-per-route shape — the caller gets a compact table, not prose.

package/payload/.claude/skills/write-an-agent/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: write-an-agent
+description: Create a state-of-the-art interactive Claude Code subagent (.claude/agents/<name>.md) through a guided interview — pin its single job, routing trigger, least-privilege tools (you approve the grant), model, and a mandatory compressed output contract, then scaffold and validate the subagent file. Use when someone wants to create, add, or scaffold a subagent, build a custom agent, or says "write an agent", "create an agent", or "new subagent".
+---
+
+# Writing an Agent
+
+Scaffold an **interactive subagent** — a `.claude/agents/<name>.md` file spawned via the Agent/Task
+tool — through a short interview that gets the few SOTA levers right. Your job here is not to fill a
+template; it is to **interrogate the job until the subagent is sharp, cheap, and safe**, then write a
+validated file.
+
+**Scope:** interactive helpers (locators, reviewers, runners you call in-session). **Not** AFK
+pipeline executors — those live in the kernel's dispatch-executor registry (`wrxn dispatch`). If the
+user wants a workflow *they* follow inline, write a skill instead (`write-a-skill`).
+
+## Why a subagent (the levers that make it good)
+
+A subagent is a **separate context** with its own tools, model, and system prompt. The caller sees
+**only its final message**. That one fact drives every lever:
+
+| Lever | Why |
+|---|---|
+| **Single responsibility** | One narrow job → sharp prompt → correct routing. An "and" means two subagents. |
+| **`description` = #1 routing lever** | The main thread matches this text to delegate. Vague → mis-routed. Use "use PROACTIVELY" + trigger phrases. |
+| **Least-privilege `tools`** | Omitting `tools` inherits ALL tools. Smaller surface = safer + cheaper. |
+| **Compressed output contract** | The caller eats only the final message. A terse fixed shape is the highest-value, most-skipped lever. |
+| **Stateless** | No memory but the spawn prompt + this file. Put everything it needs on the page. |
+| **Model match** | Mechanical → haiku; reasoning → sonnet; hard → opus. |
+
+## File format (verified — code.claude.com/docs sub-agents)
+
+```
+---
+name: <kebab-case, equals the filename>
+description: >
+  <what it does> + WHEN. Include "use PROACTIVELY" + trigger phrases.
+tools: Read, Grep, Glob          # explicit allowlist ALWAYS — omitting inherits ALL tools
+model: haiku                      # haiku | sonnet | opus | inherit
+skills: tdd                       # OPTIONAL — preloads that skill's content at startup
+---
+<system prompt — SOTA body order below>
+```
+
+Real fields: `name`, `description`, `tools`, `model`, `skills` (advanced: `disallowedTools`,
+`permissionMode`). Don't invent others.
+
+## Interview — run in this order
+
+1. **Job** — the ONE responsibility. If it needs an "and", STOP and propose two subagents.
+2. **Trigger** — when should the main thread delegate? → becomes `description`:
+   `<what it does>. Use PROACTIVELY when <the exact situations/phrases that route to it>.`
+3. **Propose frontmatter → ONE consolidated approval.** Infer from the job, then show `tools` +
+   `model` + `skills` together as a single preview; the operator approves or edits before you continue:
+   - **tools** — the minimal allowlist. Locator/reviewer → `Read, Grep, Glob`; + run things → `+Bash`;
+     mutates files → `+Edit, Write`; research → `WebFetch, WebSearch`; integration →
+     `mcp__<server>__<tool>` (named, never `*`). **Never omit** (= inherit-all). **Never grant a push
+     path** (no devops). Flag `Bash` as broad (reaches `git` + the network).
+   - **model** — mechanical → `haiku`, reasoning → `sonnet`, hard → `opus`, match the caller → `inherit`.
+   - **skills** — propose only if the job maps to a skill **installed here** (`.claude/skills/<name>/`
+     exists; a dangling preload = a broken subagent). Don't auto-add `caveman` — compression ships via
+     the body instruction, which is portable.
+4. **Output contract (mandatory)** — pin exactly what returns + how terse: a fixed return shape (e.g.
+   `path:line — finding`, one per line; or small JSON) **and** a compression instruction (lead with the
+   answer, drop prose, backtick exact paths/symbols). Don't finish the subagent without it.
+5. **Generate → validate → write** (below).
+
+## Body structure (SOTA order — every subagent)
+
+1. **Role** — one line: who it is + the single job.
+2. **Process** — the numbered steps it follows.
+3. **Constraints** — hard NOs: what it refuses (scope creep; edits if read-only; ever pushing).
+4. **Output contract** — the fixed return shape + **one concrete example**. State plainly: *your final
+   message IS the return value — return the result, not a conversational reply.* Compress.
+5. **Stateless reminder** — it gets only its spawn prompt + this file; no main-thread memory, no
+   inherited CLAUDE.md persona. Keep the page self-sufficient.
+
+## Validate (loose by design)
+
+- [ ] `---` fences open/close; `name` present, kebab-case, equals the filename.
+- [ ] `description` says **what** + **when** (the routing trigger; uses "use PROACTIVELY").
+- [ ] `tools` is an explicit allowlist of **real** tools; present, never omitted; no push path.
+- [ ] `model` ∈ `haiku | sonnet | opus | inherit`.
+- [ ] `skills` (if present) names a skill that exists under `.claude/skills/`.
+- [ ] Body has Role + Process + Constraints + Output contract (with an example).
+- Don't hard-gate `tools` against a frozen list — new MCP tools are valid.
+
+## Write + load
+
+- Write `.claude/agents/<name>.md` at the install root. **Brownfield-safe**: if it exists, STOP —
+  offer to edit or rename, never overwrite.
+- **Loading:** a file written to disk is **not live this session**. Tell the operator to **restart
+  Claude Code, or create/refresh it via the `/agents` interface** (which loads immediately). Then it is
+  invokable by the Agent/Task tool, a workflow, or FleetView.
+
+See **[EXAMPLES.md](EXAMPLES.md)** for a complete worked subagent.

package/payload/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "recon-wrxn": {
       "command": "npx",
-      "args": ["-y", "recon-wrxn@6.0.0-wrxn.5", "serve"]
+      "args": ["-y", "recon-wrxn@6.0.0-wrxn.6", "serve"]
     }
   }
 }

package/payload/.wrxn/harvest.cjs

@@ -50,6 +50,14 @@ const HARVEST_DIR = ['.wrxn', 'harvest'];
 const STAGED_FILE = 'staged.jsonl'; // the proposed-but-unconfirmed merges (survivor body + absorbed, by-reference).
 const AUDIT_FILE = 'audit.jsonl'; // append-only outcome log (stage + commit + decay events).
 const DECAY_STAGED_FILE = 'decay-staged.jsonl'; // harvest-04: proposed-but-unconfirmed decay annotations (by-reference). Distinct fixed name from merge's staged.jsonl; both non-.md so recon never recalls a staged-but-unconfirmed op.
+// Bounded retention for the timestamped <ts>.jsonl check reports (phase-4.5-04). `check` writes a fresh
+// report every run; without a cap the dir grows without bound on a long-lived install. Keep the N most-recent
+// (ISO timestamps sort lexically = chronologically — no clock read). 20 is a generous trailing window of
+// recent checks for trend/diff while strictly bounding growth; env override (clamped >= 1 so the just-written
+// report is never pruned) mirrors synapse's WRXN_HANDOFF_PCT precedent. REPORT_RE matches ONLY a timestamped
+// report — the fixed-name state files (staged/audit/decay-staged.jsonl) + .gitkeep never match, never prune.
+const REPORT_RETAIN_DEFAULT = 20;
+const REPORT_RE = /^\d{4}-\d{2}-\d{2}T.*\.jsonl$/;
 const BODY_MAX = 32000; // survivor body cap (chars) — a durable merged page, not a dump (dream/sync parity).
 const WIKI_REL = ['.wrxn', 'wiki']; // all merge targets confine under <root>/.wrxn/wiki/<knowledge-tier>/.
 const WIKI_PREFIX = '.wrxn/wiki/'; // stripped to form the reinforce.json wiki-rel join key (recall-surface parity).
@@ -296,6 +304,22 @@ function nearDupQualifies(hit) {
   return Number.isFinite(sem) && hasSemantic && sem >= NEAR_DUP_THRESHOLD;
 }
 
+// Order clusters by a STABLE total order so an unchanged tree yields a byte-identical report every run
+// (phase-4.5-04). Primary key = the lexically-first member. The old `(a,b) => a.members[0] < b.members[0]
+// ? -1 : 1` returned 1 for BOTH compare(a,b) AND compare(b,a) on an equal leading member — non-antisymmetric,
+// so V8's sort could resolve tied clusters by input permutation → non-reproducible reports. Clusters are
+// disjoint connected components, so leading members never collide TODAY; the secondary keys make this a
+// proper total order regardless (defense in depth): larger cluster first, then the stronger edge score, then
+// the full member list — and two truly-identical clusters compare EQUAL (return 0).
+function compareClusters(a, b) {
+  if (a.members[0] !== b.members[0]) return a.members[0] < b.members[0] ? -1 : 1;
+  if (a.members.length !== b.members.length) return b.members.length - a.members.length; // larger cluster first
+  if (a.score !== b.score) return b.score - a.score; // stronger dup signal first
+  const ja = a.members.join('');
+  const jb = b.members.join('');
+  return ja < jb ? -1 : ja > jb ? 1 : 0; // full member list; identical clusters → 0
+}
+
 // Collapse pairwise near-dup edges into connected-component CLUSTERS (union-find), so a symmetric A↔B
 // match is reported once and a transitive A-B-C chain is one cluster of three. Each cluster carries its
 // sorted members + the STRONGEST edge similarity (the clearest dup signal). Singletons are not clusters.
@@ -333,7 +357,7 @@ function clusterNearDups(edges) {
     if (members.size < 2) continue;
     clusters.push({ members: [...members].sort(), score: Math.round((groupScore.get(r) || 0) * 1e4) / 1e4 });
   }
-  return clusters.sort((a, b) => (a.members[0] < b.members[0] ? -1 : 1));
+  return clusters.sort(compareClusters);
 }
 
 // ── the door (IO shell, injectable transport) — the recall-surface.cjs contract ──
@@ -504,6 +528,41 @@ function reportPath(dir, ts) {
   return file;
 }
 
+// The effective report-retention bound: the WRXN_HARVEST_RETAIN env override (clamped to a whole number >= 1
+// so a bogus/zero value can never prune away the just-written report), else the sane default (phase-4.5-04).
+function reportRetention() {
+  const env = Number(process.env.WRXN_HARVEST_RETAIN);
+  return Number.isFinite(env) && env >= 1 ? Math.floor(env) : REPORT_RETAIN_DEFAULT;
+}
+
+// Prune the timestamped check reports under .wrxn/harvest/ to the retention bound, keeping the `keep` most-
+// recent (phase-4.5-04). ISO timestamps sort lexically = chronologically, so the oldest are the lexical
+// prefix — no clock is read. ONLY <ts>.jsonl reports are eligible (REPORT_RE); the fixed-name state files
+// (staged/audit/decay-staged.jsonl) + .gitkeep never match, so curation/merge/decay trails are never touched.
+// Fail-soft: an unreadable dir or a failed unlink is swallowed — retention is hygiene, never the point of check.
+function pruneReports(dir, keep, protect) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return; // no report dir yet → nothing to prune
+  }
+  const reports = names.filter((n) => REPORT_RE.test(n)).sort(); // lexical = chronological (oldest first)
+  // Delete the oldest down to the `keep` bound, but NEVER the just-written report (`protect`): a same-
+  // millisecond collision names it `<base>-N.jsonl`, which collates BEFORE its `<base>.jsonl` sibling, so a
+  // blind oldest-prefix prune could delete the fresh report `check` is about to return (phase-4.5-04 review).
+  let toDelete = reports.length - keep;
+  for (let i = 0; i < reports.length && toDelete > 0; i++) {
+    if (reports[i] === protect) continue; // the fresh report is retained and counts toward `keep`
+    try {
+      fs.unlinkSync(path.join(dir, reports[i]));
+    } catch {
+      /* fail-soft — a vanished/locked report never breaks the check run */
+    }
+    toDelete--;
+  }
+}
+
 // ── check: the IO orchestrator ───────────────────────────────────────────────────
 // scanLocal (always) + nearDupFromDoor (degrades to unavailable when cold) → assemble → write the jsonl.
 // REPORT-ONLY: the ONLY write is the report under .wrxn/harvest/. `transport` is injected in tests.
@@ -520,6 +579,7 @@ async function check(root, { transport, timeoutMs } = {}) {
   const dir = harvestDir(root);
   const file = reportPath(dir, ts);
   fs.writeFileSync(file, records.length ? records.map((r) => JSON.stringify(r)).join('\n') + '\n' : '');
+  pruneReports(dir, reportRetention(), path.basename(file)); // phase-4.5-04: bound the report dir, never pruning the fresh report
   const nearDupCount = near.status === 'unavailable' ? 0 : near.clusters.length;
   return {
     report: path.relative(root, file),
@@ -1154,7 +1214,10 @@ module.exports = {
   scanLocal,
   isProse,
   nearDupQualifies,
+  compareClusters,
   clusterNearDups,
+  pruneReports,
+  reportRetention,
   assembleRecords,
   tierOfPath,
   isHarvestPath,
@@ -1187,4 +1250,5 @@ module.exports = {
   NEAR_DUP_THRESHOLD,
   FIND_PATH,
   REINFORCE_WINDOW_DAYS,
+  REPORT_RETAIN_DEFAULT,
 };

package/payload/.wrxn/sync.cjs

@@ -15,10 +15,12 @@
 //
 // Subcommand:
 //   report   query recon_drift over the serve door and print the drift summary JSON:
-//            { status, stale[], unwatermarked[] }
-//              · status "drift"        — at least one doc is stale (stale[] names doc/symbol/synced_to/current).
-//              · status "synced"       — the warm door computed an EMPTY stale set ("all synced"; AC3 no-op,
-//                                        never manufactures stale rows).
+//            { status, stale[], unwatermarked[], orphaned[] }
+//              · status "drift"        — at least one doc is stale OR orphaned. stale[] names doc/symbol/
+//                                        synced_to/current; orphaned[] (phase-4.5-02) names a doc whose
+//                                        derived_from source symbol is GONE (doc/synced_to, no symbol/current).
+//              · status "synced"       — the warm door computed an EMPTY stale AND orphaned set ("all synced";
+//                                        AC3 no-op, never manufactures rows).
 //              · status "unavailable"  — recon is unreachable OR answered without the structured drift sidecar
 //                                        (no warm door, a timeout, a non-200, a malformed body, or a 200 whose
 //                                        body lacks an affirmative `drift.stale` array — unknown is not clean,
@@ -117,11 +119,18 @@ function summarizeDrift(parsed) {
   if (!isEntry(d) || !Array.isArray(d.stale)) return unavailable();
   const stale = d.stale.filter(isEntry).map(normEntry);
   const unwatermarked = (Array.isArray(d.unwatermarked) ? d.unwatermarked : []).filter(isEntry).map(normEntry);
-  return { status: stale.length ? 'drift' : 'synced', stale, unwatermarked };
+  // phase-4.5-02: the third drift class — a watermarked page whose derived_from source symbol is GONE from
+  // recon's graph (renamed/deleted). Each entry normalizes to { doc, synced_to } (no symbol/current — the
+  // source is absent). It is DISTINCT from stale (source moved) and unwatermarked (never reconciled), but
+  // like stale it MUST elevate the status off a clean "synced": a dangling page is the exact case sync used
+  // to hide (the operator never learned the page was un-reconcilable). An older recon with no drift.orphaned
+  // degrades to [] (back-compatible, never throws).
+  const orphaned = (Array.isArray(d.orphaned) ? d.orphaned : []).filter(isEntry).map(normEntry);
+  return { status: stale.length || orphaned.length ? 'drift' : 'synced', stale, unwatermarked, orphaned };
 }
 
 function unavailable() {
-  return { status: 'unavailable', stale: [], unwatermarked: [] };
+  return { status: 'unavailable', stale: [], unwatermarked: [], orphaned: [] };
 }
 
 // ── the door (IO shell, injectable transport) — the recall-surface.cjs contract ─