@gcunharodrigues/wrxn 0.13.2 → 0.14.0

package/bin/wrxn.cjs

@@ -393,7 +393,16 @@ async function main(argv) {
       process.stderr.write(`wrxn: cannot read issue: ${err.message}\n`);
       return 2;
     }
-    process.stdout.write(JSON.stringify(executor.buildDispatchSpec(issueText, type), null, 2) + '\n');
+    // S5 dispatch-RAG (#24): seed a recon_find from the issue's referenced symbols and inject the prose
+    // hits as "Relevant prior knowledge" so the executor starts warm. The door is REUSED from the
+    // package-layer brain client (lib/brain.cjs) — prose-filtered + limit-capped there. Fully fail-open:
+    // an unreachable / cold Brain (brain.query rejects) leaves the spec byte-identical to today.
+    const priorKnowledge = await executor
+      .retrievePriorKnowledge(issueText, {
+        find: (seed) => brain.query(seed, { type: 'prose', limit: executor.PRIOR_KNOWLEDGE_CAP }, {}).then((r) => r.hits),
+      })
+      .catch(() => []);
+    process.stdout.write(JSON.stringify(executor.buildDispatchSpec(issueText, type, priorKnowledge), null, 2) + '\n');
     return 0;
   }
 

package/lib/executor.cjs

@@ -8,7 +8,9 @@
 // executors only `devops` may pass it. The live LLM execution is out of scope — the harness is the
 // proven contract.
 //
-// Pure data transforms (no I/O); the CLI (bin/wrxn.cjs dispatch) reads/writes files around them.
+// Pure data transforms (no I/O of their own); the CLI (bin/wrxn.cjs dispatch) reads/writes files around
+// them. S5 adds retrievePriorKnowledge — an async retrieval orchestrator whose recon_find door is an
+// INJECTED dependency (the CLI wires the real lib/brain.cjs door), so the module itself stays I/O-free.
 
 const BUILD_SKILL = '.claude/skills/tdd/SKILL.md';
 
@@ -18,6 +20,13 @@ const BUILDER_REQUIRED = ['issueId', 'status', 'redTest', 'greenCommit', 'typesC
 const GENERIC_REQUIRED = ['issueId', 'status', 'artifact', 'pushed', 'summary'];
 const STATUSES = ['completed', 'blocked'];
 
+// S5 dispatch-RAG (#24): the dispatch shell may inject prior knowledge recalled from the Brain so an
+// executor starts warm. Capped to a small top-N — a builder wants a few high-signal references, not a
+// digest. The same cap seeds the shell's recon_find limit (single source of truth).
+const PRIOR_KNOWLEDGE_CAP = 5;
+const PRIOR_KNOWLEDGE_NOTE =
+  'Relevant prior knowledge recalled from your Brain for this issue — read it before re-deriving or re-asking the operator.';
+
 // The executor registry — one entry per type. `skill: null` means the loop is a GLOBAL slash-skill
 // with no local file (code-review / security-review / the devops push), so the spec carries explicit
 // `instructions` instead (the subagent has no Skill tool — it cannot /invoke). `canPush` gates the
@@ -157,16 +166,86 @@ function constraintsFor(def) {
   ];
 }
 
+// ── S5 dispatch-RAG: render injected prior knowledge into a capped section (PURE) ────────────────────
+//
+// The dispatch shell retrieves prose knowledge from the warm Brain (a recon_find seeded by the issue's
+// referenced symbols) and injects it here. Each item is a recon prose hit ({ name, file }) OR a
+// pre-rendered string; this normalizes every item to one clean line ("<title> — <path>"), dedups, and
+// caps at PRIOR_KNOWLEDGE_CAP. TOTAL + defensive: a non-array / empty / all-junk input → [] (the no-op:
+// buildDispatchSpec then omits the section, keeping the spec byte-identical to pre-S5). PURE — no I/O.
+function priorKnowledgeLine(item) {
+  if (typeof item === 'string') return item.replace(/\s+/g, ' ').trim();
+  if (item && typeof item === 'object') {
+    const name = String(item.name || '').replace(/\s+/g, ' ').trim();
+    const file = String(item.file || '').trim();
+    if (name && file) return `${name} — ${file}`;
+    return name || file || '';
+  }
+  return '';
+}
+
+function renderPriorKnowledge(priorKnowledge) {
+  const list = Array.isArray(priorKnowledge) ? priorKnowledge : [];
+  const seen = new Set();
+  const items = [];
+  for (const it of list) {
+    const line = priorKnowledgeLine(it);
+    if (!line || seen.has(line)) continue;
+    seen.add(line);
+    items.push(line);
+    if (items.length >= PRIOR_KNOWLEDGE_CAP) break;
+  }
+  return items;
+}
+
+// ── S5 dispatch-RAG: seed a recon_find query from the issue's referenced symbols (PURE) ──────────────
+//
+// The dispatch shell needs a structural seed for the Brain. This REUSES slice F's buildStructuralQuery
+// IDEA — basename-if-path, tokenize on non-alphanumerics, dedup case-insensitively, cap — but keyed off
+// the ISSUE's referenced symbols rather than the session .touched paths. The "referenced symbols/paths"
+// are the issue's single-token backtick code spans (function names, identifiers, file paths); multi-word
+// backtick prose phrases are dropped (not symbols → stop-word noise). No backtick symbol → '' (the no-op
+// seed: the shell then injects nothing). This transform is DUPLICATED from the payload hook
+// recall-surface.cjs (buildStructuralQuery) ON PURPOSE — that hook is self-contained node-stdlib-only and
+// cannot be imported by package code (the same cross-install-boundary trade lib/brain.cjs documents for
+// the discovery contract). PURE — no I/O. (basename via lastIndexOf keeps this module dependency-free.)
+const MAX_QUERY_CHARS = 512; // recon_find seed budget (mirrors recall-surface)
+
+function buildIssueQuery(issueText) {
+  const text = String(issueText || '');
+  const spans = text.match(/`([^`\n]+)`/g) || [];
+  const seen = new Set();
+  const tokens = [];
+  for (const span of spans) {
+    const raw = span.slice(1, -1).trim();
+    if (!raw || /\s/.test(raw)) continue; // a referenced symbol/path is a single token, never a prose phrase
+    const base = raw.includes('/') ? raw.slice(raw.lastIndexOf('/') + 1) : raw; // a path reduces to its basename
+    const bare = base.replace(/\.[^.]+$/, ''); // strip a trailing extension (lib/executor.cjs → executor)
+    for (const t of bare.split(/[^A-Za-z0-9]+/)) {
+      const tok = t.trim();
+      if (!tok) continue;
+      const key = tok.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      tokens.push(tok);
+    }
+  }
+  return tokens.join(' ').slice(0, MAX_QUERY_CHARS);
+}
+
 /**
  * Build the dispatch spec for an executor of `executorType` (default 'builder') from an issue. The
  * spec is the complete, self-contained order the subagent follows: which skill to read+follow (or
  * the explicit instructions for a global-only skill), the issue ACs, isolation, the boundary
- * constraints, and the structured reportSchema.
+ * constraints, and the structured reportSchema. `priorKnowledge` (optional, injected by the dispatch
+ * shell) is rendered as a capped "Relevant prior knowledge" section ONLY when non-empty — with nothing
+ * injected the spec is byte-identical to pre-S5 (AC-2). Stays PURE (no I/O).
  */
-function buildDispatchSpec(issueText, executorType = 'builder') {
+function buildDispatchSpec(issueText, executorType = 'builder', priorKnowledge = []) {
   const def = EXECUTORS[executorType];
   if (!def) throw new Error(`unknown executor type: ${executorType} (one of ${EXECUTOR_TYPES.join(', ')})`);
   const issue = parseIssue(issueText);
+  const priorItems = renderPriorKnowledge(priorKnowledge);
   return {
     executor: executorType,
     issue: { id: issue.id, title: issue.title },
@@ -175,12 +254,37 @@ function buildDispatchSpec(issueText, executorType = 'builder') {
     procedure: def.procedure ? def.procedure.slice() : deriveProcedure(def),
     artifact: def.artifact,
     acceptanceCriteria: issue.acceptanceCriteria,
+    // Present ONLY when the shell injected knowledge — with none, the spec is byte-identical to pre-S5.
+    ...(priorItems.length ? { priorKnowledge: { note: PRIOR_KNOWLEDGE_NOTE, items: priorItems } } : {}),
     isolation: def.isolation,
     constraints: constraintsFor(def),
     reportSchema: { required: [...def.required], statuses: [...STATUSES] },
   };
 }
 
+// ── S5 dispatch-RAG: the retrieval orchestrator (IO injected; the impure shell wires the real door) ──
+//
+// Policy layer between the issue and the warm Brain: seed → find → cap, FAIL-OPEN. `find(seed) -> hits`
+// is INJECTED (the IO seam, like brain.query's transport): bin/wrxn.cjs wires it to lib/brain.cjs
+// (recon_find with type:'prose', so the hits are already prose-filtered) — keeping this unit-testable
+// with no live recon. No referenced symbols → empty seed → the door is never queried → []. Any fault
+// (unreachable door, non-200, malformed body) → [] — dispatch then proceeds exactly as today
+// (byte-identical spec). The cap is PRIOR_KNOWLEDGE_CAP (also the shell's recon_find limit);
+// renderPriorKnowledge re-caps defensively. Never throws.
+async function retrievePriorKnowledge(issueText, { find } = {}) {
+  if (typeof find !== 'function') return [];
+  const seed = buildIssueQuery(issueText);
+  if (!seed) return []; // no referenced symbols → nothing to retrieve (fail-open)
+  let hits;
+  try {
+    hits = await find(seed);
+  } catch {
+    return []; // unreachable recon / non-200 / malformed → fail-open
+  }
+  if (!Array.isArray(hits) || !hits.length) return []; // empty Brain → nothing injected
+  return hits.slice(0, PRIOR_KNOWLEDGE_CAP);
+}
+
 /**
  * Validate an executor's structured report against the contract + the boundary gates for its type.
  * Returns { ok, errors }. The push gate is type-aware: a report claiming pushed=true is a boundary
@@ -238,4 +342,7 @@ module.exports = {
   EXECUTORS,
   EXECUTOR_TYPES,
   STATUSES,
+  PRIOR_KNOWLEDGE_CAP,
+  buildIssueQuery,
+  retrievePriorKnowledge,
 };

package/lib/install.cjs

@@ -86,6 +86,19 @@ function init(opts) {
   ensureGitignoreLine(target, '.recon-wrxn/');
   // the recall-surface hook writes per-install access-recency state here (harvest-08) — runtime, not committed.
   ensureGitignoreLine(target, '.wrxn/reinforce.json');
+  // the recall-surface hook also writes the per-session surfaced-log here (#12 S1) — runtime STATE, not committed.
+  ensureGitignoreLine(target, '.wrxn/surfaced.json');
+  // session-start stamps a per-session start-HEAD baseline here and the session-end shell keeps the
+  // coalesced reward sidecar here (#13 S2) — runtime STATE (survives `wrxn update`), never committed.
+  ensureGitignoreLine(target, '.wrxn/baseline/');
+  ensureGitignoreLine(target, '.wrxn/reward.json');
+  // the emit-event hook appends verbatim (secret-redacted) prompt text to .wrxn/events/<sid>.jsonl (#35) —
+  // the only sink persisting raw prompt text. Ignore the whole dir so captured prompts are never committed
+  // (#38 F1); the shipped .gitkeep only makes init create the dir on disk, nothing in it is ever tracked.
+  ensureGitignoreLine(target, '.wrxn/events/');
+  // the memory-synth writes one outcome line per synth run to `.wrxn/continuity/.synth.log` (synth-handoff-fix-01)
+  // — install runtime state (never shipped in the payload), so keep it out of version control.
+  ensureGitignoreLine(target, '.wrxn/continuity/.synth.log');
   // the memory-synth gemini fallback reads GEMINI_API_KEY from `.env` — ignore it so the secret is
   // never committed (the synth's doc-comment calls it the install's gitignored `.env`).
   ensureGitignoreLine(target, '.env');

package/lib/release.cjs

@@ -48,4 +48,16 @@ function parseLog(raw) {
   return String(raw).split('\0').map((s) => s.trim()).filter(Boolean);
 }
 
-module.exports = { shouldRelease, parseLog };
+/**
+ * decidePublish({ typeRelease, versionOnNpm }) → boolean. The publish gate (#43): publish when the
+ * merged commits warrant a type release OR package.json.version is not yet on npm. Lifting the
+ * version-vs-npm guard ABOVE the type gate means a version that landed on `main` via a non-release
+ * commit (e.g. `chore(release):`) still reaches npm. Pure — the `npm view` probe stays in the
+ * workflow; this just combines the two booleans. When the version is already on npm and no type
+ * release applies, it returns false — preserving idempotent re-runs.
+ */
+function decidePublish({ typeRelease, versionOnNpm } = {}) {
+  return Boolean(typeRelease) || !versionOnNpm;
+}
+
+module.exports = { shouldRelease, parseLog, decidePublish };

package/manifest.json

@@ -83,6 +83,31 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/hooks/sidecar.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/hooks/emit-event.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/hooks/prune.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/hooks/reward.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/hooks/session-end-reward.cjs",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/hooks/reference-detect.cjs",
       "class": "managed",
@@ -478,6 +503,11 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/events/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/dream.cjs",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.13.2",
+  "version": "0.14.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,7 +16,7 @@
     "test": "node --test --require ./test/setup.cjs"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.8"
+    "recon-wrxn": "6.0.0-wrxn.9"
   },
   "engines": {
     "node": ">=20"

package/payload/.claude/hooks/emit-event.cjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+'use strict';
+
+// WRXN emit-event hook — the metadata-grade session event source (C2 / kernel #35). Wired on BOTH
+// UserPromptSubmit and PostToolUse, it appends one JSON record per line to .wrxn/events/<sid>.jsonl:
+//   · a `prompt` record (the user prompt, SECRET-REDACTED) per UserPromptSubmit, and
+//   · a SKELETON `tool` record (tool name + a target only) per PostToolUse.
+// This FREEZES the event-JSONL contract the recon-wrxn ② analyzer consumes: { ts, sid, kind, ... } with
+// kind ∈ { prompt, tool }. It is an INDEXED SOURCE (a file recon reads), never a write API.
+//
+// PRIVACY-CRITICAL: a tool record carries ONLY the tool name + a target (e.g. the file path). It NEVER
+// reads the tool input wholesale, the tool response/output, file contents, or a command — by construction
+// the only fields ever copied are tool_name and tool_input.file_path (itself redacted, defence-in-depth).
+//
+// Reuse, do not reinvent: prompt redaction is the sibling sidecar.cjs's redactSecrets (the one source of
+// secret shapes) — the same sibling-require posture as recall-surface.cjs. SPLIT: pure record builders
+// (clock + session id INJECTED) + an IO append shell. APPEND + FAIL-OPEN: any redaction or write fault is
+// swallowed so the emit NEVER throws and never blocks the prompt or the tool call.
+
+const fs = require('fs');
+const path = require('path');
+const { redactSecrets } = require('./sidecar.cjs'); // reuse the existing secret-shape primitive (one source of truth)
+
+// safeSessionId — the session-id → filesystem-safe slug. Replicated to match code-intel-push's safeId /
+// recall-surface's safeSessionId BYTE-FOR-BYTE (same discipline that duplicates the sanitizer across the
+// install-only modules): a crafted sid (slashes, `..`) collapses to `[a-z0-9-]` so the event filename can
+// never escape .wrxn/events/.
+function safeSessionId(sid) {
+  return String(sid || 'session')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+// An ISO-8601 stamp from the INJECTED clock (ms-epoch or Date; default real time). ISO so prune's
+// Date.parse(record.ts) ages event records exactly as it ages the dream/sync/harvest trails.
+function isoStamp(now) {
+  const ms = Number.isFinite(now) ? now : now instanceof Date ? now.getTime() : Date.now();
+  return new Date(ms).toISOString();
+}
+
+// ── pure record builders (clock + sid injected) ──────────────────────────────────────
+
+// A `prompt` record: the user prompt, SECRET-REDACTED. Frozen key set/order: { ts, sid, kind, text }.
+function buildPromptRecord({ ts, sid, prompt }) {
+  return { ts, sid, kind: 'prompt', text: redactSecrets(prompt) };
+}
+
+// A `tool` record: SKELETON ONLY. Frozen key set/order: { ts, sid, kind, tool, target }. `tool` is the
+// tool name; `target` is a short identifier (the file path) — redacted as defence-in-depth so even a
+// crafted secret-shaped path cannot land. NOTHING else is ever carried (see eventToRecord's extraction).
+function buildToolRecord({ ts, sid, tool, target }) {
+  return { ts, sid, kind: 'tool', tool: String(tool || ''), target: redactSecrets(target) };
+}
+
+// Dispatch a raw hook event to the record to write, or null when there is nothing to record. The sid is
+// SANITIZED into the record (so record.sid always agrees with the <sid>.jsonl filename), and the clock is
+// injected. A UserPromptSubmit event (a non-empty string `prompt`) → a prompt record; a PostToolUse event
+// (a `tool_name`) → a SKELETON tool record. PRIVACY-CRITICAL: from a tool event the ONLY fields ever read
+// are tool_name and tool_input.file_path — never tool_input wholesale, a command, file contents, or the
+// tool_response/output. A tool with no string file_path records an empty target (its input stays unseen).
+function eventToRecord(event, { now } = {}) {
+  if (!event || typeof event !== 'object') return null;
+  const ts = isoStamp(now);
+  const sid = safeSessionId(event.session_id);
+  if (typeof event.prompt === 'string' && event.prompt.trim()) {
+    return buildPromptRecord({ ts, sid, prompt: event.prompt });
+  }
+  if (typeof event.tool_name === 'string' && event.tool_name) {
+    const ti = event.tool_input;
+    const target = ti && typeof ti.file_path === 'string' ? ti.file_path : '';
+    return buildToolRecord({ ts, sid, tool: event.tool_name, target });
+  }
+  return null;
+}
+
+// Walk up from event.cwd / CLAUDE_PROJECT_DIR / cwd to the install root carrying wrxn.install.json.
+// Replicated across the install-only hooks (no kernel-lib import). Returns null when not inside an install.
+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;
+}
+
+// ── IO shell: append one JSON line to .wrxn/events/<sid>.jsonl ────────────────────────
+
+// The per-session event log. The filename is built from the SANITIZED sid, so a crafted session id can
+// never escape .wrxn/events/ (defence-in-depth: eventToRecord already sanitizes record.sid, and this
+// re-sanitizes — sanitizing an already-safe slug is idempotent).
+function eventsDir(root) {
+  return path.join(root, '.wrxn', 'events');
+}
+function eventFile(root, sid) {
+  return path.join(eventsDir(root), `${safeSessionId(sid)}.jsonl`);
+}
+
+// Append a record as one compact JSON line. Returns true on write, false on any fail-open path. APPEND
+// (never rewrite) so concurrent same-session hooks only ever add lines. FAIL-OPEN: a write fault is
+// swallowed — the emit must never throw into the prompt/tool path.
+function appendEvent(root, record) {
+  try {
+    if (!root || !record || typeof record !== 'object') return false;
+    fs.mkdirSync(eventsDir(root), { recursive: true });
+    fs.appendFileSync(eventFile(root, record.sid), JSON.stringify(record) + '\n');
+    return true;
+  } catch {
+    return false; // best-effort: a write fault never blocks the prompt or the tool call
+  }
+}
+
+// Dispatch a raw hook event to its record and append it. Returns true on write, false otherwise. Wholly
+// FAIL-OPEN: a redaction or write fault is swallowed and never throws.
+function emitEvent(root, event, { now } = {}) {
+  try {
+    const record = eventToRecord(event, { now });
+    if (!record) return false;
+    return appendEvent(root, record);
+  } catch {
+    return false;
+  }
+}
+
+// ── entrypoint ────────────────────────────────────────────────────────────────────────
+//
+// Contract: a UserPromptSubmit or PostToolUse event JSON on stdin → an empty `{}` envelope on stdout
+// (exit 0). This is a pure SIDE-EFFECT hook: it injects no context, it only appends an event record.
+// Wholly fail-open — any fault (unparseable stdin, no install, write fault) still prints `{}` and exits 0,
+// so it can never block the prompt or the tool call.
+function done() {
+  process.stdout.write('{}');
+  process.exit(0);
+}
+
+function main() {
+  let event = {};
+  try {
+    const stdin = fs.readFileSync(0, 'utf8');
+    if (stdin.trim()) event = JSON.parse(stdin);
+  } catch {
+    return done(); // unparseable stdin → no-op
+  }
+  let root = null;
+  try {
+    root = findInstallRoot(event && event.cwd);
+  } catch {
+    root = null;
+  }
+  try {
+    if (root) emitEvent(root, event, {});
+  } catch {
+    /* fail-open: an emit fault never blocks the prompt or the tool call */
+  }
+  return done();
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch {
+    done();
+  }
+}
+
+module.exports = {
+  eventToRecord,
+  buildPromptRecord,
+  buildToolRecord,
+  safeSessionId,
+  isoStamp,
+  eventsDir,
+  eventFile,
+  appendEvent,
+  emitEvent,
+  findInstallRoot,
+};