@gcunharodrigues/wrxn 0.1.0

package/lib/executor.cjs

@@ -0,0 +1,238 @@
+'use strict';
+
+// WRXN executor dispatch harness (wrxn-kernel-18 builder + wrxn-kernel-19 the remaining five).
+// The kernel ships the executor CONTRACT, not a live LLM: buildDispatchSpec turns a ready-for-agent
+// issue into the structured order a thin subagent of a given TYPE follows (which skill/instructions,
+// which artifact, isolation, the boundary gates), and validateReport enforces the structured return +
+// the boundary gates on whatever the subagent reports back. The push gate is type-aware: of the six
+// 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.
+
+const BUILD_SKILL = '.claude/skills/tdd/SKILL.md';
+
+// The builder keeps the rich tdd report contract (wrxn-kernel-18); the other five report a generic
+// type-specific `artifact` + the common boundary fields.
+const BUILDER_REQUIRED = ['issueId', 'status', 'redTest', 'greenCommit', 'typesClean', 'pushed', 'summary'];
+const GENERIC_REQUIRED = ['issueId', 'status', 'artifact', 'pushed', 'summary'];
+const STATUSES = ['completed', 'blocked'];
+
+// 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
+// push: only devops may report pushed=true.
+const EXECUTORS = {
+  builder: {
+    skill: BUILD_SKILL,
+    artifact: 'green-commit',
+    canPush: false,
+    isolation: 'fresh-context',
+    required: BUILDER_REQUIRED,
+    procedure: [
+      `Read ${BUILD_SKILL} FIRST, then follow it — it IS your build loop (never paraphrase it).`,
+      'Build the slice test-first: write a failing (red) test, make it pass (green) with the minimal change, keep types clean.',
+      'Commit locally with a conventional message referencing the issue id.',
+      'Return the structured report described by reportSchema.',
+    ],
+  },
+  reviewer: {
+    skill: null, // /code-review is a global slash-skill — no local file to read
+    instructions: [
+      'You are a fresh-eyes code reviewer. /code-review is a global slash-skill with no local file, and',
+      'subagents have no Skill tool — follow these instructions directly: review the diff against the',
+      'PRD / issue contracts, verify every claim against ALL sources before flagging, and separate',
+      'blocking from non-blocking findings. Write the review marker review-<id>.md.',
+    ],
+    artifact: 'review-marker',
+    canPush: false,
+    isolation: 'fresh-context',
+    required: GENERIC_REQUIRED,
+  },
+  security: {
+    skill: null, // /security-review is a global slash-skill — no local file
+    instructions: [
+      'You are a defensive security reviewer. /security-review is a global slash-skill with no local',
+      'file — follow these instructions directly: scan the diff for injection, path traversal, authz /',
+      'secret handling, and fail-open/closed posture; report PASS / PASS-WITH-FINDINGS / FAIL with evidence.',
+    ],
+    artifact: 'security-report',
+    canPush: false,
+    isolation: 'fresh-context',
+    required: GENERIC_REQUIRED,
+  },
+  'qa-walker': {
+    skill: '.claude/skills/qa-walk/SKILL.md',
+    artifact: 'walk-findings',
+    canPush: false,
+    isolation: 'fresh-context',
+    required: GENERIC_REQUIRED,
+  },
+  researcher: {
+    skill: '.claude/skills/tech-search/SKILL.md',
+    artifact: 'research-summary',
+    canPush: false,
+    isolation: 'fresh-context',
+    required: GENERIC_REQUIRED,
+  },
+  devops: {
+    skill: null, // the integration / push executor — instructions; the ONLY type that may push
+    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.',
+    ],
+    artifact: 'authorized-push',
+    canPush: true,
+    isolation: 'attended',
+    required: GENERIC_REQUIRED,
+  },
+};
+
+const EXECUTOR_TYPES = Object.keys(EXECUTORS);
+
+/**
+ * Parse a ready-for-agent issue markdown into { id, title, labels, whatToBuild, acceptanceCriteria }.
+ * Tolerant: missing sections yield empty values rather than throwing.
+ */
+function parseIssue(issueText) {
+  const text = String(issueText || '');
+  const fm = text.startsWith('---') ? text.slice(3, text.indexOf('\n---', 3)) : '';
+
+  const scalar = (key) => {
+    const m = fm.match(new RegExp(`^${key}\\s*:\\s*(.+)$`, 'm'));
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : '';
+  };
+
+  const labelsRaw = scalar('labels');
+  const labels = labelsRaw
+    ? labelsRaw.replace(/^\[|\]$/g, '').split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  // Only the bullets under "## Acceptance criteria", stopping at the next heading so "## Blocked by"
+  // bullets never leak in.
+  const acceptanceCriteria = [];
+  let inAC = false;
+  for (const line of text.split('\n')) {
+    if (/^##\s+/.test(line)) {
+      inAC = /^##\s+acceptance criteria/i.test(line);
+      continue;
+    }
+    if (inAC) {
+      const m = line.match(/^\s*-\s*\[[ xX]\]\s*(.+)$/);
+      if (m) acceptanceCriteria.push(m[1].trim());
+    }
+  }
+
+  const whatMatch = text.match(/##\s+What to build\s*\n+([\s\S]*?)(?:\n##\s|\n*$)/i);
+  const whatToBuild = whatMatch ? whatMatch[1].trim() : '';
+
+  return { id: scalar('id'), title: scalar('title'), labels, whatToBuild, acceptanceCriteria };
+}
+
+/** The procedure for a non-builder executor: read the skill (or follow instructions), then produce the artifact. */
+function deriveProcedure(def) {
+  const head = def.skill
+    ? [`Read ${def.skill} FIRST, then follow it — it IS your loop (never paraphrase it).`]
+    : def.instructions.slice();
+  return [...head, `Produce your artifact: ${def.artifact}.`, 'Return the structured report described by reportSchema.'];
+}
+
+/** Boundary constraints for an executor — type-aware on the push gate. */
+function constraintsFor(def) {
+  if (def.canPush) {
+    return [
+      'You are the ONLY executor authorized to push (the push gate passes for devops alone).',
+      'Push only AFTER verifying the review marker (review-<id>.md) + a green suite.',
+      'Do NOT edit managed files without the managed-confirm token.',
+    ];
+  }
+  return [
+    'Do NOT run git push — only the devops executor may (boundary gate; integration is devops-only).',
+    'Do NOT edit managed files without the managed-confirm token.',
+    'A review marker (review-<id>.md) is required downstream before this work is pushed.',
+  ];
+}
+
+/**
+ * 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.
+ */
+function buildDispatchSpec(issueText, executorType = 'builder') {
+  const def = EXECUTORS[executorType];
+  if (!def) throw new Error(`unknown executor type: ${executorType} (one of ${EXECUTOR_TYPES.join(', ')})`);
+  const issue = parseIssue(issueText);
+  return {
+    executor: executorType,
+    issue: { id: issue.id, title: issue.title },
+    skill: def.skill,
+    ...(def.skill ? {} : { instructions: def.instructions.slice() }),
+    procedure: def.procedure ? def.procedure.slice() : deriveProcedure(def),
+    artifact: def.artifact,
+    acceptanceCriteria: issue.acceptanceCriteria,
+    isolation: def.isolation,
+    constraints: constraintsFor(def),
+    reportSchema: { required: [...def.required], statuses: [...STATUSES] },
+  };
+}
+
+/**
+ * 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
+ * violation for every type EXCEPT devops. A `completed` builder report must carry full tdd evidence;
+ * a `completed` generic report must carry a non-empty artifact; a `completed` devops report must
+ * record the authorized push (pushed=true). A `blocked` report is valid without evidence.
+ */
+function validateReport(report, executorType = 'builder') {
+  const def = EXECUTORS[executorType];
+  if (!def) return { ok: false, errors: [`unknown executor type: ${executorType}`] };
+
+  const errors = [];
+  if (!report || typeof report !== 'object' || Array.isArray(report)) {
+    return { ok: false, errors: ['report is not an object'] };
+  }
+
+  for (const key of def.required) {
+    if (!(key in report)) errors.push(`missing field: ${key}`);
+  }
+  if ('status' in report && !STATUSES.includes(report.status)) {
+    errors.push(`invalid status: ${report.status} (one of ${STATUSES.join(', ')})`);
+  }
+
+  // Boundary push gate — only devops may report a push.
+  if (report.pushed === true && !def.canPush) {
+    errors.push(`boundary violation: the ${executorType} executor must not push (pushed=true)`);
+  }
+
+  // Completion contract (per type) — checked only when the executor claims it finished.
+  if (report.status === 'completed') {
+    if (executorType === 'builder') {
+      if (report.redTest !== true) errors.push('completed builder report must record a red test (redTest=true)');
+      if (typeof report.greenCommit !== 'string' || !report.greenCommit.trim()) {
+        errors.push('completed builder report must record a green commit (greenCommit sha/ref)');
+      }
+      if (report.typesClean !== true) errors.push('completed builder report must record types clean (typesClean=true)');
+    } else {
+      if (typeof report.artifact !== 'string' || !report.artifact.trim()) {
+        errors.push(`completed ${executorType} report must record a non-empty artifact (${def.artifact})`);
+      }
+      if (def.canPush && report.pushed !== true) {
+        errors.push('completed devops report must record the authorized push (pushed=true) — it is the push path');
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  parseIssue,
+  buildDispatchSpec,
+  validateReport,
+  BUILD_SKILL,
+  EXECUTORS,
+  EXECUTOR_TYPES,
+  STATUSES,
+};

package/lib/install.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadManifest, inProfile } = require('./manifest.cjs');
+
+const RECEIPT = 'wrxn.install.json';
+
+/**
+ * Lay the kernel payload into a target root, governed by the file-class manifest.
+ *
+ * Walking-skeleton install semantics (init only; update is a later issue):
+ *   - every class is laid create-if-absent — a file already present is left untouched.
+ *   - that makes init idempotent across all three classes: a second run lays nothing.
+ *   - the class is recorded per file in the receipt + returned report, so the
+ *     class-aware engine is observable now even though the divergent UPDATE rules
+ *     (managed overwrite / seeded preserve / state never-touch) land with `wrxn update`.
+ *
+ * @param {object} opts
+ * @param {string} opts.pkgRoot   absolute path to the installed kernel package (holds manifest.json + payload/)
+ * @param {string} opts.target    absolute path to the install target (a project root)
+ * @param {string} [opts.profile] "project" (default) | "workspace"
+ * @returns {{ profile: string, laid: Array, skipped: Array, receipt: string }}
+ */
+function init(opts) {
+  const pkgRoot = opts.pkgRoot;
+  const target = opts.target;
+  const profile = opts.profile || 'project';
+
+  const manifest = loadManifest(path.join(pkgRoot, 'manifest.json'));
+  const payloadDir = path.join(pkgRoot, 'payload');
+
+  const laid = [];
+  const skipped = [];
+
+  const version = packageVersion(pkgRoot);
+  // What a PRIOR wrxn install laid here — used to tell a re-init skip (wrxn's own file) apart from a
+  // BROWNFIELD collision (a pre-existing PROJECT file that happens to clash with a payload path).
+  const priorPaths = priorReceiptPaths(target);
+
+  // Lay only the files that belong to the chosen profile: the project subset is the shared floor
+  // (laid for both), workspace files lay only for a workspace install. Brownfield-safe by construction:
+  // a clashing dest is NEVER overwritten — the existing file is preserved and (if new) reported.
+  for (const entry of manifest.files) {
+    if (!inProfile(entry.profile, profile)) continue;
+    const src = path.join(payloadDir, entry.path);
+    const dest = path.join(target, entry.path);
+
+    if (!fs.existsSync(src)) {
+      throw new Error(`manifest lists "${entry.path}" but payload/${entry.path} does not exist in the package`);
+    }
+
+    if (fs.existsSync(dest)) {
+      // A collision = the file existed but was NOT laid by a prior wrxn install (it is the operator's
+      // own pre-existing project file). A re-init skip of wrxn's own file is `exists`, not a collision.
+      const collision = !priorPaths.has(entry.path);
+      skipped.push({ path: entry.path, class: entry.class, reason: collision ? 'collision' : 'exists', collision });
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    laid.push({ path: entry.path, class: entry.class });
+  }
+
+  const collisions = skipped.filter((s) => s.collision);
+  const brownfield = collisions.length > 0;
+
+  writeReceipt(target, { version, profile, laid, skipped, brownfield });
+
+  return { profile, laid, skipped, collisions, brownfield, receipt: path.join(target, RECEIPT) };
+}
+
+/** Paths a prior wrxn install recorded in the receipt (empty when there is no prior install). */
+function priorReceiptPaths(target) {
+  try {
+    const r = JSON.parse(fs.readFileSync(path.join(target, RECEIPT), 'utf8'));
+    return new Set((r.files || []).map((f) => f.path));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Read the kernel package's release version (the semver `wrxn update` compares). */
+function packageVersion(pkgRoot) {
+  return JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
+function writeReceipt(target, data) {
+  const receiptPath = path.join(target, RECEIPT);
+  // The receipt is generated state, not a payload file — it records what THIS install
+  // laid, so a re-run (and a future `wrxn update`) can reason about install history.
+  const existing = fs.existsSync(receiptPath)
+    ? JSON.parse(fs.readFileSync(receiptPath, 'utf8'))
+    : { installs: [] };
+  existing.kernelVersion = data.version;
+  existing.profile = data.profile;
+  existing.brownfield = !!data.brownfield;
+  existing.files = [...data.laid, ...data.skipped].map((f) => ({ path: f.path, class: f.class }));
+  existing.installs.push({ laidCount: data.laid.length, skippedCount: data.skipped.length });
+  fs.writeFileSync(receiptPath, JSON.stringify(existing, null, 2) + '\n');
+}
+
+module.exports = { init, RECEIPT, packageVersion };

package/lib/manifest.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const VALID_CLASSES = ['managed', 'seeded', 'state'];
+const VALID_PROFILES = ['project', 'workspace'];
+
+/**
+ * Load and validate the file-class manifest.
+ *
+ * Validation is the load-bearing contract: a manifest that lists a file with no
+ * class, an unknown class, or a duplicate path is rejected here — so the installer
+ * never lays an unclassifiable file (PRD: "update refuses files it cannot classify").
+ *
+ * @param {string} manifestPath absolute path to manifest.json
+ * @returns {{ version: string, files: Array<{path: string, class: string}> }}
+ */
+function loadManifest(manifestPath) {
+  const raw = fs.readFileSync(manifestPath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`manifest is not valid JSON (${manifestPath}): ${err.message}`);
+  }
+
+  if (!Array.isArray(parsed.files)) {
+    throw new Error('manifest.files must be an array');
+  }
+
+  const seen = new Set();
+  for (const entry of parsed.files) {
+    if (!entry || typeof entry.path !== 'string' || entry.path.length === 0) {
+      throw new Error(`manifest entry missing a path: ${JSON.stringify(entry)}`);
+    }
+    if (!VALID_CLASSES.includes(entry.class)) {
+      throw new Error(
+        `manifest entry "${entry.path}" has unclassifiable class "${entry.class}" — must be one of ${VALID_CLASSES.join(', ')}`
+      );
+    }
+    if (!VALID_PROFILES.includes(entry.profile)) {
+      throw new Error(
+        `manifest entry "${entry.path}" has unclassifiable profile "${entry.profile}" — must be one of ${VALID_PROFILES.join(', ')}`
+      );
+    }
+    if (path.isAbsolute(entry.path) || entry.path.split(path.sep).includes('..')) {
+      throw new Error(`manifest path must be repo-relative, never absolute or escaping: "${entry.path}"`);
+    }
+    if (seen.has(entry.path)) {
+      throw new Error(`manifest lists "${entry.path}" more than once`);
+    }
+    seen.add(entry.path);
+  }
+
+  return { version: String(parsed.version), profiles: parsed.profiles || VALID_PROFILES, files: parsed.files };
+}
+
+/**
+ * Should a file of `entry.profile` be laid for an install of `installProfile`?
+ * The project profile is the shared floor (laid for BOTH); workspace files lay ONLY for workspace.
+ */
+function inProfile(entryProfile, installProfile) {
+  return entryProfile === 'project' || entryProfile === installProfile;
+}
+
+module.exports = { loadManifest, inProfile, VALID_CLASSES, VALID_PROFILES };

package/lib/migrate.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { RECEIPT } = require('./install.cjs');
+const { compareVersions } = require('./semver.cjs');
+
+/**
+ * Migration runner — breaking kernel changes ship as ordered scripts that run once per install
+ * (PRD US8). A migration file lives in the package `migrations/` dir and exports:
+ *   module.exports = { id: '001', version: '0.2.0', up(ctx) { ... } }
+ *   - id      : orderable string (files run in id order; default = filename without .cjs).
+ *   - version : the release the migration ships with — it runs only once the install reaches it.
+ *   - up(ctx) : the migration; ctx = { target, fromVersion, toVersion }. Throw to fail (resumable).
+ *
+ * Semantics: pending = not-yet-applied AND toVersion >= migration.version, run in id order, each
+ * recorded in the receipt's migrationsApplied the instant it succeeds (so a later failure keeps the
+ * earlier successes). A throwing migration halts the run and is NOT recorded → the next `wrxn update`
+ * resumes from it. Re-running with no pending migrations is a no-op.
+ */
+
+/** Load + order the package's migrations. Absent dir → []. */
+function loadMigrations(pkgRoot) {
+  const dir = path.join(pkgRoot, 'migrations');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.cjs'))
+    .map((f) => {
+      // eslint-disable-next-line global-require
+      const mod = require(path.join(dir, f));
+      return {
+        id: String(mod.id || f.replace(/\.cjs$/, '')),
+        version: String(mod.version || '0.0.0'),
+        up: mod.up,
+        file: f,
+      };
+    })
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/**
+ * Run the pending migrations against an install. Returns the ids that ran this call.
+ * Throws (propagating to the caller) on the first failing migration — the install's receipt then
+ * records every migration that succeeded before it, and the failed one stays pending for a resume.
+ *
+ * @param {string} pkgRoot package root holding migrations/
+ * @param {string} target  install root holding the receipt
+ * @param {{fromVersion?:string, toVersion?:string}} ctx
+ * @returns {string[]} ids run this call (in order)
+ */
+function runMigrations(pkgRoot, target, ctx = {}) {
+  const receiptPath = path.join(target, RECEIPT);
+  const applied = new Set(readReceipt(receiptPath).migrationsApplied || []);
+  const toVersion = ctx.toVersion || '0.0.0';
+
+  const pending = loadMigrations(pkgRoot).filter(
+    (m) => !applied.has(m.id) && compareVersions(toVersion, m.version) >= 0,
+  );
+
+  const ran = [];
+  for (const m of pending) {
+    if (typeof m.up !== 'function') {
+      throw new Error(`migration "${m.id}" (${m.file}) has no up() function`);
+    }
+    try {
+      m.up({ target, fromVersion: ctx.fromVersion, toVersion: ctx.toVersion });
+    } catch (err) {
+      throw new Error(
+        `migration "${m.id}" (${m.file}) failed: ${err.message} — resumable: fix it and re-run \`wrxn update\``,
+      );
+    }
+    markApplied(receiptPath, m.id); // persist immediately so a later failure keeps this success
+    ran.push(m.id);
+  }
+  return ran;
+}
+
+function readReceipt(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function markApplied(p, id) {
+  const r = readReceipt(p);
+  r.migrationsApplied = [...new Set([...(r.migrationsApplied || []), id])];
+  fs.writeFileSync(p, JSON.stringify(r, null, 2) + '\n');
+}
+
+module.exports = { loadMigrations, runMigrations };

package/lib/onboard.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+// WRXN onboard scaffold (wrxn-kernel-20) — the DETERMINISTIC half of the onboard skill's Step 3.
+// Reads a filled aios-intake.md and scaffolds the Day-1 operator file set under context/. CLI-First:
+// `wrxn onboard --root <ws>` runs this. Idempotent: re-running regenerates the context/ files from the
+// current intake. It NEVER touches the seeded operator files (decisions/log.md, connections.md) — those
+// are the operator's own, hand-edited.
+
+const fs = require('fs');
+const path = require('path');
+
+const PLACEHOLDER = '[Your answer here]';
+
+// Parse aios-intake.md into { Q1..Q7: <answer text> }.
+function parseIntake(text) {
+  const answers = {};
+  let curQ = null;
+  let buf = [];
+  const flush = () => {
+    if (curQ) answers[curQ] = buf.join('\n').trim();
+    buf = [];
+  };
+  for (const line of String(text || '').split('\n')) {
+    const m = line.match(/^##\s*Q(\d)\b/);
+    if (m) {
+      flush();
+      curQ = `Q${m[1]}`;
+      continue;
+    }
+    if (curQ) buf.push(line);
+  }
+  flush();
+  return answers;
+}
+
+function filled(answer) {
+  const a = (answer || '').trim();
+  return a !== '' && a !== PLACEHOLDER;
+}
+
+// The Day-1 context files and which intake answers feed each.
+const CONTEXT_FILES = [
+  { name: 'about-me.md', title: 'About me', from: ['Q1'] },
+  { name: 'about-business.md', title: 'About the business', from: ['Q4', 'Q5'] },
+  { name: 'priorities.md', title: 'Priorities (90 days)', from: ['Q3'] },
+];
+
+/**
+ * Scaffold the Day-1 operator file set under <root>/context/ from <root>/aios-intake.md.
+ * Returns { scaffolded: string[], skipped: string[] } (paths relative to root). Throws if the
+ * intake is absent (run inside a workspace install, or pass an explicit --root).
+ */
+function scaffold(root) {
+  const intakePath = path.join(root, 'aios-intake.md');
+  let intakeText;
+  try {
+    intakeText = fs.readFileSync(intakePath, 'utf8');
+  } catch {
+    throw new Error('aios-intake.md not found — run inside a wrxn workspace install (wrxn init --workspace)');
+  }
+
+  const answers = parseIntake(intakeText);
+  const ctxDir = path.join(root, 'context');
+  fs.mkdirSync(ctxDir, { recursive: true });
+
+  const scaffolded = [];
+  const skipped = [];
+  for (const file of CONTEXT_FILES) {
+    const sections = file.from
+      .filter((q) => filled(answers[q]))
+      .map((q) => `## ${q}\n\n${answers[q].trim()}`);
+    if (sections.length === 0) {
+      skipped.push(path.join('context', file.name)); // no filled answer for this file yet
+      continue;
+    }
+    const body = [`# ${file.title}`, '', '<!-- generated by `wrxn onboard` from aios-intake.md -->', '', ...sections, ''].join('\n');
+    fs.writeFileSync(path.join(ctxDir, file.name), body);
+    scaffolded.push(path.join('context', file.name));
+  }
+
+  return { scaffolded, skipped };
+}
+
+module.exports = { scaffold, parseIntake, filled, CONTEXT_FILES, PLACEHOLDER };

package/lib/semver.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+/** Compare dotted numeric versions: <0 if a<b, 0 if equal, >0 if a>b. */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+module.exports = { compareVersions };