@gcunharodrigues/wrxn 0.2.0 → 0.3.0

package/bin/wrxn.cjs

@@ -12,6 +12,8 @@ const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
 const statusline = require('../lib/statusline.cjs');
+const { convert } = require('../lib/convert.cjs');
+const { ingest } = require('../lib/ingest.cjs');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -54,6 +56,8 @@ function parseArgs(argv) {
       args.flags.owner = argv[++i];
     } else if (a === '--probe') {
       args.flags.probe = argv[++i];
+    } else if (a === '--distillation') {
+      args.flags.distillation = argv[++i];
     } else if (a === '--check-report') {
       args.flags['check-report'] = true;
     } else if (a.startsWith('--')) {
@@ -112,6 +116,20 @@ Usage:
                                  resolved (or --path) statusline script, idempotently (append-only,
                                  never overwrites). init NEVER touches your statusline.
 
+  wrxn convert <file> [--cpu]    convert a source file to Markdown and print it. Per-format routing:
+                                 markitdown (html/docx/txt/pptx/xlsx) · docling (pdf, with automatic
+                                 CPU fallback on a GPU arch-crash) · pure-JS floor when Python is
+                                 absent. --cpu forces docling onto CPU from the first attempt.
+
+  wrxn ingest <file> [--distillation <result.json>] [--root <dir>]
+                                 distill a source into the memory wiki: convert (slice 05) → an LLM
+                                 (the ingest skill) produces a summary + N note pages → write them
+                                 to .wrxn/wiki/, each stamped derived_from the raw source, which is
+                                 kept under .wrxn/raw/. ADDITIVE-ONLY: an existing page is never
+                                 overwritten (re-runs are safe). --distillation feeds the skill's
+                                 result JSON (summary,notes); without it, the harness points you at
+                                 the ingest skill.
+
   wrxn onboard [--root <dir>]    scaffold the Day-1 operator file set under context/ from a filled
                                  aios-intake.md (the deterministic half of the onboard skill;
                                  workspace installs only). Idempotent.
@@ -120,7 +138,7 @@ Profiles: --project (default, the dev pipeline + intelligence + enforcement) |
           --workspace (adds the operator layer: onboard/audit/level-up + intake + decisions log +
           connections registry).`;
 
-function main(argv) {
+async function main(argv) {
   const args = parseArgs(argv);
 
   if (args.flags.version) {
@@ -294,6 +312,43 @@ function main(argv) {
     return 0;
   }
 
+  if (cmd === 'convert') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: convert requires <file>\n'); return 2; }
+    try {
+      const md = await convert(path.resolve(file), { gpu: args.flags.cpu ? false : undefined });
+      process.stdout.write(md.endsWith('\n') ? md : md + '\n');
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  if (cmd === 'ingest') {
+    const file = args._[1];
+    if (!file) { process.stderr.write('wrxn: ingest requires <file>\n'); return 2; }
+    const root = path.resolve(args.flags.root || process.cwd());
+    // The distillation is the LLM step (the `ingest` skill). The CLI feeds its structured result via
+    // --distillation <result.json>; without one, the harness's defaultDistill points back to the skill.
+    let distill;
+    if (args.flags.distillation) {
+      const dpath = path.resolve(args.flags.distillation);
+      distill = () => JSON.parse(fs.readFileSync(dpath, 'utf8'));
+    }
+    try {
+      const report = await ingest(path.resolve(file), { root, ...(distill ? { distill } : {}) });
+      process.stdout.write(`wrxn ingest ${report.source} → raw ${report.raw}\n`);
+      for (const p of report.written) process.stdout.write(`  wrote   ${p}\n`);
+      for (const p of report.skipped) process.stdout.write(`  skipped ${p} (exists — additive-only, never clobbered)\n`);
+      process.stdout.write(`${report.written.length} written, ${report.skipped.length} skipped.\n`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+  }
+
   if (cmd === 'onboard') {
     const root = path.resolve(args.flags.root || process.cwd());
     let report;
@@ -397,4 +452,7 @@ function main(argv) {
   return 2;
 }
 
-process.exit(main(process.argv.slice(2)));
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (err) => { process.stderr.write(`wrxn: ${err && err.message ? err.message : err}\n`); process.exit(1); }
+);

package/lib/convert.cjs

@@ -0,0 +1,215 @@
+'use strict';
+
+// Converter primitive (multiformat-distill-05) — convert(srcPath) → Markdown, per-format routing.
+//
+// Decision (ADR 0001 / PRD §5, empirically baked off): markitdown is the primary subprocess for the
+// office/web matrix (html/docx/pptx/xlsx); txt is a zero-dep pass-through; PDF escalates to docling
+// (SOTA tables + OCR), which auto-grabs the GPU and CRASHES on arch-incompat (the GTX-1070/Pascal
+// sm_61 trap — torch cu13x ships no sm_61 kernel) → we force CPU on that crash. When Python /
+// markitdown is absent (ENOENT) we degrade to the pure-JS floor (turndown / mammoth / unpdf / SheetJS).
+//
+// The spawn boundary is INJECTED, mirroring lib/connect.cjs's injectable `invoke`: convert(src,{run})
+// takes a converter runner so routing, ENOENT-degrade, and the CPU fallback are unit-testable WITHOUT
+// any real binary. defaultRun does the real spawnSync — that is what makes the integration check
+// "validated by invocation". convert is async only so the pure-JS floor (mammoth/unpdf are async)
+// can be wired in completely; the primary subprocess path is plain blocking spawnSync.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Extension → logical format. (.htm folds into html.)
+const FORMATS = {
+  '.html': 'html',
+  '.htm': 'html',
+  '.docx': 'docx',
+  '.txt': 'txt',
+  '.pptx': 'pptx',
+  '.xlsx': 'xlsx',
+  '.pdf': 'pdf',
+};
+
+// CUDA / arch-incompat crash signatures — the Pascal sm_61 trap and friends. docling auto-grabs the
+// GPU; a torch build with no matching SM kernel dies with "no kernel image is available...".
+const ARCH_CRASH_RE = /no kernel image|kernel image is available|sm_\d+|CUDA error|CUDA_ERROR|device-side assert|out of memory/i;
+
+const SPAWN_OPTS = { encoding: 'utf8', timeout: 600000, maxBuffer: 256 * 1024 * 1024 };
+
+// ── the injected boundary's real implementation ────────────────────────────────
+
+/**
+ * Run a converter subprocess and normalize its result to { ok, markdown } | { ok:false, error }.
+ * error.code is 'ENOENT' (not installed → degrade), 'CRASH' (arch-incompat → CPU retry), or 'EXIT'.
+ */
+function defaultRun(tool, srcPath, { device } = {}) {
+  if (tool === 'markitdown') {
+    const r = spawnSync('markitdown', [srcPath], SPAWN_OPTS);
+    return normalize(r);
+  }
+  if (tool === 'docling') {
+    // docling writes <basename>.md into an --output dir (no markdown on stdout); read it back.
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wrxn-docling-'));
+    try {
+      const args = [srcPath, '--to', 'md', '--output', outDir];
+      const opts = { ...SPAWN_OPTS };
+      if (device === 'cpu') {
+        args.push('--device', 'cpu');
+        opts.env = { ...process.env, CUDA_VISIBLE_DEVICES: '' };
+      }
+      const r = spawnSync('docling', args, opts);
+      if (r.error) return { ok: false, error: classifyError(r.error) };
+      if (r.status !== 0 || r.signal) {
+        const stderr = r.stderr || '';
+        const code = ARCH_CRASH_RE.test(stderr) || r.signal ? 'CRASH' : 'EXIT';
+        return { ok: false, error: { code, status: r.status, signal: r.signal, message: stderr.trim() } };
+      }
+      return { ok: true, markdown: readDoclingOutput(outDir, srcPath) };
+    } finally {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  }
+  throw new Error(`unknown converter tool: ${tool}`);
+}
+
+function normalize(r) {
+  if (r.error) return { ok: false, error: classifyError(r.error) };
+  if (r.status !== 0 || r.signal) {
+    return { ok: false, error: { code: 'EXIT', status: r.status, signal: r.signal, message: (r.stderr || '').trim() } };
+  }
+  return { ok: true, markdown: r.stdout };
+}
+
+function classifyError(err) {
+  return { code: err.code || 'ERR', message: err.message || String(err) };
+}
+
+function readDoclingOutput(outDir, srcPath) {
+  const base = path.basename(srcPath, path.extname(srcPath));
+  const preferred = path.join(outDir, `${base}.md`);
+  if (fs.existsSync(preferred)) return fs.readFileSync(preferred, 'utf8');
+  // Fall back to the first .md docling produced (naming can vary by version).
+  const md = fs.readdirSync(outDir).find((f) => f.toLowerCase().endsWith('.md'));
+  if (!md) throw new Error(`docling produced no markdown in ${outDir}`);
+  return fs.readFileSync(path.join(outDir, md), 'utf8');
+}
+
+// ── the pure-JS floor (no-Python degrade) ───────────────────────────────────────
+
+function lazy(mod) {
+  try {
+    return require(mod);
+  } catch {
+    throw new Error(
+      `pure-JS floor needs "${mod}" but it is not installed, and the primary converter is absent. ` +
+      `Install the primary path (pip install 'markitdown[all]' / docling) or the floor (npm i ${mod}).`
+    );
+  }
+}
+
+/** The no-Python in-process floor (research §2: turndown / mammoth / unpdf / SheetJS). Async. */
+async function defaultFloor(fmt, srcPath) {
+  if (fmt === 'txt') return fs.readFileSync(srcPath, 'utf8');
+  if (fmt === 'html') {
+    const Turndown = lazy('turndown');
+    const td = new Turndown();
+    try {
+      const { gfm } = require('turndown-plugin-gfm');
+      td.use(gfm);
+    } catch { /* gfm tables are a nice-to-have, not required */ }
+    return td.turndown(fs.readFileSync(srcPath, 'utf8'));
+  }
+  if (fmt === 'docx') {
+    const mammoth = lazy('mammoth');
+    const Turndown = lazy('turndown');
+    const { value: html } = await mammoth.convertToHtml({ path: srcPath });
+    return new Turndown().turndown(html);
+  }
+  if (fmt === 'pdf') {
+    const { extractText, getDocumentProxy } = lazy('unpdf');
+    const buf = new Uint8Array(fs.readFileSync(srcPath));
+    const pdf = await getDocumentProxy(buf);
+    const { text } = await extractText(pdf, { mergePages: true });
+    return text;
+  }
+  if (fmt === 'xlsx') {
+    const XLSX = lazy('xlsx');
+    const wb = XLSX.readFile(srcPath);
+    return wb.SheetNames.map((n) => `## ${n}\n\n${XLSX.utils.sheet_to_csv(wb.Sheets[n])}`).join('\n\n');
+  }
+  if (fmt === 'pptx') {
+    const officeParser = lazy('officeparser');
+    return await officeParser.parseOfficeAsync(srcPath);
+  }
+  throw new Error(`no pure-JS floor for format "${fmt}"`);
+}
+
+// ── the primitive ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a source file to Markdown via per-format routing.
+ * @param {string} srcPath
+ * @param {{ run?: Function, floor?: Function, gpu?: boolean }} [opts]
+ *   run   — injectable converter boundary (default: defaultRun, the real spawnSync).
+ *   floor — injectable pure-JS floor (default: defaultFloor).
+ *   gpu   — false forces docling onto CPU from the first attempt (skips the GPU probe/crash).
+ * @returns {Promise<string>} the markdown.
+ */
+async function convert(srcPath, { run = defaultRun, floor = defaultFloor, gpu } = {}) {
+  // Resolve to an absolute path up front so a leading-dash filename can never be read as a CLI flag
+  // by the converter subprocess — the dash-neutralization must not depend on the caller (slice-06
+  // ingest calls convert() directly, not via the CLI).
+  srcPath = path.resolve(srcPath);
+  // Pre-check existence up front (mirrors lib/ingest.cjs's source-not-found guard) so a missing file
+  // is rejected with a clean message and NEVER reaches the converter subprocess — whose Python
+  // traceback (markitdown/docling) would otherwise leak to the user verbatim (multiformat-distill-08).
+  if (!fs.existsSync(srcPath)) throw new Error(`wrxn convert: source not found: ${srcPath}`);
+  const ext = path.extname(srcPath).toLowerCase();
+  const fmt = FORMATS[ext];
+  if (!fmt) {
+    throw new Error(`wrxn convert: unsupported format "${ext || '(none)'}" — supported: ${Object.keys(FORMATS).join(', ')}`);
+  }
+
+  // txt is already plain text — pass it through (zero-dep, always works).
+  if (fmt === 'txt') {
+    return fs.readFileSync(srcPath, 'utf8');
+  }
+
+  if (fmt === 'pdf') {
+    return convertPdf(srcPath, { run, floor, gpu });
+  }
+
+  // markitdown-primary formats (html/docx/pptx/xlsx).
+  const r = run('markitdown', srcPath);
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor(fmt, srcPath); // markitdown absent → degrade to the pure-JS floor
+  }
+  throw new Error(`wrxn convert: markitdown failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+/** PDF tier: docling (GPU/auto) → CPU on an arch-crash → pure-JS floor if docling is absent. */
+async function convertPdf(srcPath, { run, floor, gpu }) {
+  const firstDevice = gpu === false ? 'cpu' : undefined; // undefined = let docling pick (GPU/auto)
+  const r = run('docling', srcPath, { device: firstDevice });
+  if (r.ok) return r.markdown;
+  if (r.error && r.error.code === 'ENOENT') {
+    return floor('pdf', srcPath); // no docling → unpdf floor
+  }
+  if (r.error && r.error.code === 'CRASH' && firstDevice !== 'cpu') {
+    // arch-incompat / GPU crash → force CPU (CUDA_VISIBLE_DEVICES='' + --device cpu).
+    const cpu = run('docling', srcPath, { device: 'cpu' });
+    if (cpu.ok) return cpu.markdown;
+    if (cpu.error && cpu.error.code === 'ENOENT') return floor('pdf', srcPath);
+    throw new Error(`wrxn convert: docling failed on the CPU fallback for ${path.basename(srcPath)} — ${cpu.error.message || cpu.error.code}`);
+  }
+  throw new Error(`wrxn convert: docling failed on ${path.basename(srcPath)} — ${r.error.message || r.error.code}`);
+}
+
+module.exports = {
+  convert,
+  defaultRun,
+  defaultFloor,
+  FORMATS,
+  ARCH_CRASH_RE,
+};

package/lib/executor.cjs

@@ -80,7 +80,7 @@ const EXECUTORS = {
     instructions: [
       'You are the devops integration executor — the ONLY executor authorized to push. Integrate the',
       'reviewed + security-passed + qa-walked track to the trunk: verify the review marker (review-<id>.md)',
-      '+ a green suite exist, THEN push (AIOX_ACTIVE_AGENT=devops). This is the single path through the push gate.',
+      '+ a green suite exist, then authorize the push by setting WRXN_ACTIVE_AGENT to devops under the `env` key of .claude/settings.local.json (an inline command-scoped assignment never reaches the gate hook), push, then REMOVE WRXN_ACTIVE_AGENT from .claude/settings.local.json — a persistent flag defeats the anti-accidental-push gate. This is the single path through the push gate.',
     ],
     artifact: 'authorized-push',
     canPush: true,

package/lib/ingest.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+// Distillation ingest harness (multiformat-distill-06) — the deterministic half of `wrxn ingest`.
+//
+// PRD decisions D/E (grill 2026-06-16) + [[karpathy-llm-wiki-pattern]] (raw → distill → wiki, Adler):
+// a dropped source becomes a SUMMARY page + N NOTE pages in the memory wiki, each carrying a
+// `derived_from:` link back to the raw source. Additive-only: ingest CREATES new pages and refuses
+// to overwrite an existing one — editing existing knowledge + cross-source synthesis is the `dream`
+// loop (out of scope here).
+//
+// TWO boundaries are INJECTED, mirroring lib/convert.cjs's injectable spawn, so the harness is
+// deterministically testable WITHOUT a real binary OR a live LLM:
+//   - convert(src) → markdown          slice-05 converter primitive (default: the real convert).
+//   - distill(markdown, ctx) → pages   the LLM step. The `ingest` SKILL is the prompt that produces
+//                                       this; the harness only consumes its structured output, so the
+//                                       distillation QUALITY is validated by the feature QA-walk, not
+//                                       here. defaultDistill refuses to fabricate — it points the
+//                                       caller at the skill (or the CLI's --distillation feed).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { convert: defaultConvert } = require('./convert.cjs');
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const TIERS = ['concepts', 'decisions', 'gotchas', 'sessions'];
+const DEFAULT_TIER = 'concepts'; // distilled source knowledge lands in the concepts tier by default.
+const MAX_NOTES = 100;           // cap so a garbage distillation can't flood the wiki.
+// eslint-disable-next-line no-control-regex
+const CTRL_RE = /[\x00-\x1f]/;   // control chars (NL/CR/NUL/...) — illegal in a source filename.
+
+// Collapse a value to a single safe frontmatter scalar: strip control chars, fold whitespace.
+function safeScalar(v) {
+  // eslint-disable-next-line no-control-regex
+  return String(v || '').replace(/[\x00-\x1f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// The no-op default for the distill boundary: there is no deterministic LLM, so refuse rather than
+// fabricate. The real distillation is the `ingest` skill; the CLI feeds its result via --distillation.
+function defaultDistill() {
+  throw new Error(
+    'no distillation provided. The distillation step is the `ingest` skill (an LLM reads the ' +
+    'converted markdown and produces a summary + notes). Run via the ingest skill, feed a result ' +
+    'with --distillation <result.json>, or inject a distill boundary. See .claude/skills/ingest/SKILL.md.'
+  );
+}
+
+/** Flatten the distillation result into an ordered page list, validating the contract. */
+function normalizePages(result) {
+  if (!result || typeof result !== 'object') throw new Error('wrxn ingest: distillation returned no result object');
+  const summary = result.summary;
+  if (!summary || !summary.slug || !summary.body) {
+    throw new Error('wrxn ingest: distillation must include a summary page with { slug, body }');
+  }
+  const notes = Array.isArray(result.notes) ? result.notes : [];
+  if (notes.length > MAX_NOTES) {
+    throw new Error(`wrxn ingest: distillation produced ${notes.length} notes — cap is ${MAX_NOTES}. Refusing to flood the wiki.`);
+  }
+  const pages = [{ ...summary, role: 'summary' }, ...notes.map((n) => ({ ...n, role: 'note' }))];
+  for (const pg of pages) {
+    if (!pg.slug || !SLUG_RE.test(pg.slug)) {
+      throw new Error(`wrxn ingest: page slug must be kebab-case ([a-z0-9-]): "${pg.slug}"`);
+    }
+    pg.tier = pg.tier || DEFAULT_TIER;
+    if (!TIERS.includes(pg.tier)) {
+      throw new Error(`wrxn ingest: unknown tier "${pg.tier}" — one of ${TIERS.join(', ')}`);
+    }
+  }
+  // Intra-run dup: the DISTILLATION itself yielded two pages targeting one path. Distinct from the
+  // legit pre-existing-page skip (handled at write time via the wx/O_EXCL EEXIST path).
+  const seen = new Set();
+  for (const pg of pages) {
+    const key = `${pg.tier}/${pg.slug}`;
+    if (seen.has(key)) throw new Error(`wrxn ingest: duplicate slug in distillation: "${pg.slug}" (tier ${pg.tier})`);
+    seen.add(key);
+  }
+  return pages;
+}
+
+/** Render one wiki page: frontmatter (with the sanitized derived_from provenance stamp) + body. */
+function renderPage(pg, derivedFrom) {
+  return [
+    '---',
+    `name: ${pg.slug}`,
+    `description: ${safeScalar(pg.description)}`,
+    `tier: ${pg.tier}`,
+    `derived_from: ${safeScalar(derivedFrom)}`,
+    `role: ${pg.role}`,
+    'source: wrxn-ingest',
+    '---',
+    '',
+    `# ${pg.title || pg.slug}`,
+    '',
+    (pg.body || '').trim(),
+    '',
+  ].join('\n');
+}
+
+/**
+ * Ingest a source file into the memory wiki as a summary + N note pages.
+ * @param {string} srcPath
+ * @param {{ root?: string, convert?: Function, distill?: Function }} [opts]
+ *   root    — install root the wiki + raw zone live under (default: cwd).
+ *   convert — injectable converter boundary (default: slice-05 convert, the real spawnSync path).
+ *   distill — injectable distillation boundary (default: defaultDistill, which refuses to fabricate).
+ * @returns {Promise<{source:string, raw:string, written:string[], skipped:string[]}>}
+ */
+async function ingest(srcPath, { root, convert = defaultConvert, distill = defaultDistill } = {}) {
+  srcPath = path.resolve(srcPath);
+  if (!fs.existsSync(srcPath)) throw new Error(`wrxn ingest: source not found: ${srcPath}`);
+  root = path.resolve(root || process.cwd());
+
+  // ── fail-fast guards: everything cheap that can reject runs BEFORE convert + raw copy, so a pure
+  //    error path leaves NO stray work (no spawned converter, no dropped raw file). ──
+  const base = path.basename(srcPath);
+  if (CTRL_RE.test(base)) {
+    // a newline/control char in the filename would break out of the YAML frontmatter block.
+    throw new Error(`wrxn ingest: source filename contains control characters (invalid): ${JSON.stringify(base)}`);
+  }
+  // refuse a symlinked source: copyFileSync would follow it and copy an arbitrary readable file.
+  if (fs.lstatSync(srcPath).isSymbolicLink()) {
+    throw new Error(`wrxn ingest: source is a symlink (refused): ${srcPath}`);
+  }
+  // validate the distill boundary up front — `wrxn ingest <file>` with no distillation must NOT
+  // convert + drop a raw file before defaultDistill throws.
+  if (distill === defaultDistill) defaultDistill();
+
+  // 1. convert source → markdown (slice 05).
+  const markdown = await convert(srcPath);
+
+  // 2. place/keep the raw source under .wrxn/raw/. The filename is content-hash-namespaced so two
+  //    DIFFERENT sources sharing a basename never collide (provenance stays correct), while the SAME
+  //    bytes always map to the SAME name → idempotent re-run skips the copy.
+  const rawDir = path.join(root, '.wrxn', 'raw');
+  fs.mkdirSync(rawDir, { recursive: true });
+  const bytes = fs.readFileSync(srcPath);
+  const hash = crypto.createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+  const ext = path.extname(base);
+  const stem = base.slice(0, base.length - ext.length);
+  const rawName = `${stem}.${hash}${ext}`;
+  const rawDest = path.join(rawDir, rawName);
+  if (!fs.existsSync(rawDest)) fs.writeFileSync(rawDest, bytes);
+  const derivedFrom = path.relative(root, rawDest).split(path.sep).join('/');
+
+  // 3. distill the markdown → { summary, notes } (validated: contract, note cap, intra-run dup slug).
+  const pages = normalizePages(await distill(markdown, { srcPath, derivedFrom }));
+
+  // 4. write pages ADDITIVELY. The wx flag (O_EXCL) makes the check-and-create atomic AND refuses to
+  //    follow a (dangling) symlink at the destination — EEXIST is the legit pre-existing-page skip.
+  const written = [];
+  const skipped = [];
+  for (const pg of pages) {
+    const dir = path.join(root, '.wrxn', 'wiki', pg.tier);
+    fs.mkdirSync(dir, { recursive: true });
+    const dest = path.join(dir, `${pg.slug}.md`);
+    const rel = path.relative(root, dest).split(path.sep).join('/');
+    try {
+      fs.writeFileSync(dest, renderPage(pg, derivedFrom), { flag: 'wx' });
+      written.push(rel);
+    } catch (err) {
+      if (err.code === 'EEXIST') { skipped.push(rel); continue; }
+      throw err;
+    }
+  }
+
+  return {
+    source: path.relative(root, srcPath).split(path.sep).join('/'),
+    raw: derivedFrom,
+    written,
+    skipped,
+  };
+}
+
+module.exports = { ingest, defaultDistill, normalizePages, DEFAULT_TIER, TIERS, MAX_NOTES };

package/manifest.json

@@ -148,6 +148,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/ingest/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/memory/SKILL.md",
       "class": "managed",
@@ -398,6 +403,11 @@
       "class": "state",
       "profile": "project"
     },
+    {
+      "path": ".wrxn/raw/.gitkeep",
+      "class": "state",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/wiki.cjs",
       "class": "managed",

package/migrations/002-seeded-honesty.cjs

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 002 — seeded-file honesty migration (foundation-honesty-06).
+ *
+ * Managed payload reaches existing installs on `wrxn update`, but SEEDED files are never overwritten
+ * (operator-owned) — so two artifacts seeded before 0.2.1 keep their stale wording forever unless a
+ * migration corrects them:
+ *   - .synapse/routing's ROUTING_RULE_0 still asserts a fictional "devops role" authority.
+ *   - docs/agents/domain.md still points at the deleted CONTEXT-MAP.md context.
+ * Each file is rewritten in place ONLY while it still carries its known-stale marker, so an operator
+ * who already customized it (or whose install is already honest) is never clobbered. The two branches
+ * are independent and neither ever crashes on a missing file.
+ *
+ * The honest content is EMBEDDED below as frozen 0.2.1 constants: a migration is a historical
+ * transform of the 0.2.1 release, not a re-read of the evolving template (ctx carries no pkgRoot, by
+ * design). Idempotency falls out of the gate — after the rewrite the stale markers ("devops role",
+ * "CONTEXT-MAP.md") are gone, so a second run is a no-op. Runs via `wrxn update` once the install
+ * reaches 0.2.1.
+ */
+
+// The honest ROUTING_RULE_0 — mirrors the seeded `.synapse/routing` template (issue 04 confirmation-
+// gate wording, minus the constitution citation the managed `global` GLOBAL_RULE_0 carries).
+const HONEST_ROUTING_RULE_0 =
+  'ROUTING_RULE_0=git push, PR creation, and release tags are deliberate acts held behind a confirmation flag (anti-accidental-push) — they run only once the session sets WRXN_ACTIVE_AGENT=devops in .claude/settings.local.json; `devops` is a dispatch-phase label, not an authority.';
+
+// The honest domain glossary — frozen verbatim from the post-issue-05 payload docs/agents/domain.md.
+const HONEST_DOMAIN_MD = `# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **\`CONTEXT.md\`** at the repo root — the domain glossary, the canonical vocabulary for this project.
+- **\`docs/adr/\`** — Architecture Decision Records. Read the ADRs that touch the area you're about to work in.
+
+If either doesn't exist yet, **proceed silently**. Don't flag its absence; don't suggest creating it upfront. The producer skill (\`grill-with-docs\`) creates them lazily — \`CONTEXT.md\` when the first term is resolved, an ADR when a hard-to-reverse decision is actually made.
+
+## File structure
+
+A fresh install ships neither file. They appear at the repo root as the project's language and decisions accumulate:
+
+\`\`\`
+/
+├── CONTEXT.md        ← domain glossary (created lazily by grill-with-docs)
+└── docs/
+    └── adr/          ← one file per decision, named NNNN-<slug>.md
+\`\`\`
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in \`CONTEXT.md\`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for \`grill-with-docs\`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 — but worth reopening because…_
+`;
+
+module.exports = {
+  id: '002',
+  version: '0.2.1',
+  up(ctx) {
+    const target = ctx.target;
+
+    // 1. routing: replace ONLY a ROUTING_RULE_0 line still carrying the stale "devops role" authority
+    //    wording. Comments and any operator-added ROUTING_RULE_N lines are preserved verbatim; the
+    //    split/join round-trip keeps the trailing newline. No stale line → routing left untouched.
+    const routingPath = path.join(target, '.synapse', 'routing');
+    if (fs.existsSync(routingPath)) {
+      const lines = fs.readFileSync(routingPath, 'utf8').split('\n');
+      let changed = false;
+      const out = lines.map((line) => {
+        if (line.startsWith('ROUTING_RULE_0=') && line.includes('devops role')) {
+          changed = true;
+          return HONEST_ROUTING_RULE_0;
+        }
+        return line;
+      });
+      if (changed) fs.writeFileSync(routingPath, out.join('\n'));
+    }
+
+    // 2. domain.md: overwrite the whole glossary with the honest content ONLY while it still names the
+    //    deleted CONTEXT-MAP.md context. An honest or operator-customized file (marker absent) is left
+    //    untouched. Missing file → nothing to do.
+    const domainPath = path.join(target, 'docs', 'agents', 'domain.md');
+    if (fs.existsSync(domainPath)) {
+      const body = fs.readFileSync(domainPath, 'utf8');
+      if (body.includes('CONTEXT-MAP.md')) {
+        fs.writeFileSync(domainPath, HONEST_DOMAIN_MD);
+      }
+    }
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.2.0",
+  "version": "0.3.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"
   },
   "dependencies": {
-    "recon-wrxn": "6.0.0-wrxn.1"
+    "recon-wrxn": "6.0.0-wrxn.2"
   },
   "engines": {
     "node": ">=20"

package/payload/.claude/constitution.md

@@ -5,7 +5,10 @@ Project-local preferences live in the seeded `constitution.local.md` addendum, n
 
 ## Article I — Agent Authority (NON-NEGOTIABLE)
 
-- `git push`, PR creation, and release tags are EXCLUSIVE to the devops role.
+- `git push`, PR creation, and release tags are deliberate acts, held behind a
+  confirmation flag to prevent an accidental push: the op proceeds only once the session
+  confirms intent by setting `WRXN_ACTIVE_AGENT=devops` in the machine-local
+  `.claude/settings.local.json`. `devops` here is a dispatch-phase label, not an authority grant.
 - An agent acts only within its scope; it delegates when out of scope and never assumes
   another agent's authority.