@gcunharodrigues/wrxn 0.9.0 → 0.10.0

package/bin/wrxn.cjs

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execFileSync } = require('child_process');
 
 const { init } = require('../lib/install.cjs');
 const { update } = require('../lib/update.cjs');
@@ -15,6 +16,7 @@ const brain = require('../lib/brain.cjs');
 const statusline = require('../lib/statusline.cjs');
 const { convert } = require('../lib/convert.cjs');
 const { ingest } = require('../lib/ingest.cjs');
+const { flowStatus } = require('../lib/flow-status.cjs');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -23,6 +25,12 @@ function version() {
   return pkg.version;
 }
 
+// Escape a dynamic fragment before embedding it in a RegExp. Slice ids derive from the prd slug and
+// issue filenames, so an unescaped metachar would otherwise build an invalid pattern (crash / ReDoS).
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
@@ -150,6 +158,14 @@ Usage:
                                  aios-intake.md (the deterministic half of the onboard skill;
                                  workspace installs only). Idempotent.
 
+  wrxn flow status <prd> [--root <dir>]
+                                 print the flow-status board for a PRD's issue set. Reads issues
+                                 from .scratch/<prd>/issues/, detects gate artifacts (green commit
+                                 via git log, review-<id>.md, security-<id>.md, walk-findings-<id>.md),
+                                 and prints per-slice gate progress (build/review/sec/qa) plus state
+                                 (done | in-progress | stalled | queued). No separate state store —
+                                 derives from the durable artifacts only.
+
 Profiles: --project (default, the dev pipeline + intelligence + enforcement) |
           --workspace (adds the operator layer: onboard/audit/level-up + intake + decisions log +
           connections registry).`;
@@ -490,6 +506,135 @@ async function main(argv) {
     return 0;
   }
 
+  if (cmd === 'flow') {
+    const sub = args._[1];
+    if (sub === 'status') {
+      const prd = args._[2];
+      if (!prd) {
+        process.stderr.write('wrxn: flow status requires <prd>\n');
+        return 2;
+      }
+      const root = path.resolve(args.flags.root || process.cwd());
+      // S2: prd flows into a filesystem path — keep it a plain dir name contained within
+      // <root>/.scratch/. Reject "..", absolute paths, and anything that resolves outside .scratch/.
+      const scratchRoot = path.join(root, '.scratch');
+      const issuesDir = path.join(scratchRoot, prd, 'issues');
+      if (prd.includes('..') || path.isAbsolute(prd)
+          || !path.resolve(issuesDir).startsWith(path.resolve(scratchRoot) + path.sep)) {
+        process.stderr.write(`wrxn: invalid prd "${prd}" — must be a directory name under .scratch/\n`);
+        return 2;
+      }
+
+      // Read issue files sorted by filename (numeric ordering preserved by filename prefix)
+      let issueFiles;
+      try {
+        issueFiles = fs.readdirSync(issuesDir).filter((f) => f.endsWith('.md')).sort();
+      } catch (err) {
+        process.stderr.write(`wrxn: cannot read issues from ${issuesDir}: ${err.message}\n`);
+        return 2;
+      }
+
+      // Derive the id prefix from the PRD slug (e.g. "flow-redesign" → "flow", "myprd" → "myprd")
+      const prdPrefix = prd.split('-')[0];
+
+      // Parse each issue file: id from filename, title + blockedBy from content
+      const issues = issueFiles.map((f) => {
+        const stem = f.replace(/\.md$/, '');
+        const numMatch = stem.match(/^(\d+)/);
+        const num = numMatch ? numMatch[1] : stem;
+        const id = `${prdPrefix}-${num}`;
+        let title = stem;
+        const blockedBy = [];
+        try {
+          const text = fs.readFileSync(path.join(issuesDir, f), 'utf8');
+          // First heading: # N — Title (em-dash or hyphen)
+          const titleMatch = text.match(/^#\s+\d+\s*[—\-]\s*(.+)/m);
+          if (titleMatch) title = titleMatch[1].trim();
+          // ## Blocked by section — bullet items
+          let inBlocked = false;
+          for (const line of text.split('\n')) {
+            if (/^##\s+/.test(line)) { inBlocked = /^##\s+blocked by/i.test(line); continue; }
+            if (inBlocked) {
+              const m = line.match(/^\s*-\s+(.+)$/);
+              if (m) {
+                const item = m[1].trim();
+                // B1: the "None — can start immediately." sentinel is not a real dependency.
+                if (/^none\b/i.test(item)) continue;
+                // B2: normalize a "02 (desc)." bullet to the canonical id "<prefix>-02" so it can be
+                // resolved against the done set. A bullet that is already an id is kept as-is.
+                const numM = item.match(/^(\d+)/);
+                blockedBy.push(numM ? `${prdPrefix}-${numM[1]}` : item);
+              }
+            }
+          }
+        } catch { /* id still usable without content */ }
+        return { id, title, blockedBy };
+      });
+
+      // git log for greenCommit detection — fail-open (not a git repo is fine)
+      let gitLog = '';
+      try {
+        gitLog = execFileSync('git', ['-C', root, 'log', '--all', '--oneline'], {
+          encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch { /* not a repo, or git unavailable — all build gates stay pending */ }
+
+      // Look for an artifact file in the common locations an executor would write it
+      function findArtifactFile(name) {
+        const candidates = [
+          path.join(root, name),
+          path.join(root, '.scratch', prd, name),
+          path.join(root, '.claude', 'ai', 'output', name),
+        ];
+        for (const c of candidates) {
+          try { if (fs.existsSync(c)) return c; } catch { /* skip */ }
+        }
+        return null;
+      }
+
+      // Build artifact map for flowStatus
+      const artifacts = {};
+      for (const issue of issues) {
+        const { id } = issue;
+        const entry = {};
+        // greenCommit: commit message containing [id] or the bare id word.
+        // S1: escape the id (+ guard construction) so a metachar id can never build an invalid RegExp.
+        const eid = escapeRegExp(id);
+        let re;
+        try { re = new RegExp(`\\[${eid}\\]|\\b${eid}\\b`); } catch { re = null; }
+        const commitLine = re ? gitLog.split('\n').find((l) => re.test(l)) : null;
+        if (commitLine) entry.greenCommit = commitLine.trim().split(/\s+/)[0];
+        // review marker
+        const reviewFile = findArtifactFile(`review-${id}.md`);
+        if (reviewFile) entry.reviewMarker = reviewFile;
+        // security report
+        const secFile = findArtifactFile(`security-${id}.md`);
+        if (secFile) entry.securityReport = secFile;
+        // walk findings (two common naming conventions)
+        const walkFile = findArtifactFile(`walk-findings-${id}.md`) || findArtifactFile(`walk-${id}.md`);
+        if (walkFile) entry.walkFindings = walkFile;
+        artifacts[id] = entry;
+      }
+
+      const board = flowStatus(issues, artifacts);
+
+      // Print readable board: id  build✓ review· sec· qa·  state
+      for (const slice of board) {
+        const g = slice.gates;
+        const cols = [
+          `build${g.build === 'done' ? '✓' : '·'}`,
+          `review${g.review === 'done' ? '✓' : '·'}`,
+          `sec${g.security === 'done' ? '✓' : '·'}`,
+          `qa${g.qa === 'done' ? '✓' : '·'}`,
+        ];
+        process.stdout.write(`${slice.id.padEnd(16)} ${cols.join(' ')}  ${slice.state}\n`);
+      }
+      return 0;
+    }
+    process.stderr.write(`wrxn: unknown flow subcommand "${sub || ''}"\n\n${USAGE}\n`);
+    return 2;
+  }
+
   process.stderr.write(`wrxn: unknown command "${cmd}"\n\n${USAGE}\n`);
   return 2;
 }

package/lib/agent-conformance.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// Agent-contract conformance (wrxn-kernel flow-redesign flow-02).
+// A pure transform mirroring lib/executor.cjs: it confirms a native executor subagent definition
+// (.claude/agents/<type>.md) is a faithful THIN WRAPPER of the dispatch contract for its type — it
+// declares least-privilege tools, a model, and an output contract that EQUALS that type's
+// reportSchema (EXECUTORS[type].required). The agent file carries no logic the harness doesn't
+// already define, so validateReport's guarantees still hold by construction.
+//
+// An agent .md declares its output contract in a fenced ```output-contract block in the body — one
+// required report field per line. validateAgentFile accepts EITHER the raw markdown (it parses the
+// frontmatter + that block) OR a pre-parsed { tools, model, outputContract } object, so it is
+// unit-testable without a live LLM.
+
+const { EXECUTORS } = require('./executor.cjs');
+
+/**
+ * Parse an agent .md into { name, tools, model, outputContract }.
+ *   - frontmatter `tools:` → comma-separated least-privilege allowlist
+ *   - frontmatter `model:` → scalar
+ *   - the fenced ```output-contract block → one report field per line
+ * Tolerant: a missing piece yields an empty value rather than throwing.
+ */
+function parseAgentFile(markdown) {
+  const text = String(markdown || '');
+  const fmEnd = text.startsWith('---') ? text.indexOf('\n---', 3) : -1;
+  const fm = fmEnd !== -1 ? text.slice(3, fmEnd) : '';
+
+  const scalar = (key) => {
+    const m = fm.match(new RegExp(`^${key}\\s*:\\s*(.+)$`, 'm'));
+    return m ? m[1].trim().replace(/^["']|["']$/g, '') : '';
+  };
+
+  const toolsRaw = scalar('tools');
+  const tools = toolsRaw
+    ? toolsRaw.replace(/^\[|\]$/g, '').split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  // The fenced ```output-contract block (info-string `output-contract`), one field per line; a
+  // leading bullet marker is tolerated so the block can read as a list.
+  const block = text.match(/```output-contract[^\n]*\n([\s\S]*?)```/);
+  const outputContract = block
+    ? block[1].split('\n').map((l) => l.replace(/^\s*[-*]\s*/, '').trim()).filter(Boolean)
+    : [];
+
+  return { name: scalar('name'), tools, model: scalar('model'), outputContract };
+}
+
+/** Order-independent set-equality over two string arrays (duplicate-safe). */
+function sameSet(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const x of sa) if (!sb.has(x)) return false;
+  return true;
+}
+
+/**
+ * Validate that an executor agent definition conforms to EXECUTORS[type]:
+ *   - declares a non-empty `tools` allowlist (least-privilege; presence, not a frozen list —
+ *     new MCP tools are valid, per the write-an-agent doctrine),
+ *   - declares a `model`,
+ *   - its declared output contract EQUALS that type's reportSchema (EXECUTORS[type].required),
+ *   - the type is known.
+ * `agentDef` may be the raw agent markdown (string) or a pre-parsed
+ * { tools, model, outputContract } object. Returns { ok, errors } (mirrors validateReport).
+ */
+function validateAgentFile(agentDef, type) {
+  const def = EXECUTORS[type];
+  if (!def) return { ok: false, errors: [`unknown executor type: ${type}`] };
+
+  const parsed = typeof agentDef === 'string' ? parseAgentFile(agentDef) : (agentDef || {});
+  const errors = [];
+
+  const tools = Array.isArray(parsed.tools) ? parsed.tools : [];
+  if (tools.length === 0) errors.push('agent declares no tools (a least-privilege allowlist is required)');
+
+  if (!parsed.model || typeof parsed.model !== 'string' || !parsed.model.trim()) {
+    errors.push('agent declares no model');
+  }
+
+  const declared = Array.isArray(parsed.outputContract) ? parsed.outputContract : [];
+  if (!sameSet(declared, def.required)) {
+    errors.push(
+      `output contract ${JSON.stringify(declared)} does not equal the ${type} reportSchema ${JSON.stringify(def.required)}`
+    );
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = { validateAgentFile, parseAgentFile };

package/lib/compass-coverage.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+// compass coverage guard (wrxn-kernel flow-04).
+// compass/SKILL.md carries a static ```buckets``` block routing every installed skill to a flow bucket
+// (dev-pipeline / knowledge / setup-health / meta / cross-session). The runtime live-read in the skill
+// body is the resilience layer; THIS is the drift-guard on the static map — an installed skill missing
+// from every bucket is an orphan, i.e. the map fell behind a newly-added skill.
+//
+// Pure data transforms (no I/O), mirroring lib/executor.cjs: parseBuckets is the tolerant parser, the
+// test reads the real SKILL.md + skills dir around them.
+
+/**
+ * Parse the fenced ```buckets``` block out of compass/SKILL.md into { bucket: [skill, …] }.
+ * Each line is `bucket: a, b, c`. Tolerant: a missing block, blank lines, comment (#) lines, or
+ * lines without a colon are skipped rather than thrown on.
+ */
+function parseBuckets(skillMd) {
+  const text = String(skillMd || '');
+  const m = text.match(/```buckets\s*\n([\s\S]*?)```/);
+  if (!m) return {};
+
+  const buckets = {};
+  for (const line of m[1].split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf(':');
+    if (idx === -1) continue;
+    const bucket = trimmed.slice(0, idx).trim();
+    const skills = trimmed
+      .slice(idx + 1)
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (bucket) buckets[bucket] = skills;
+  }
+  return buckets;
+}
+
+/**
+ * The coverage check: every installed skill must appear in some bucket. Returns { ok, orphans },
+ * where orphans is the list of installed skills absent from every bucket (the static map drifted
+ * behind a newly-added skill). Pure: the caller supplies the installed skill list and parsed buckets.
+ */
+function compassCoverage(installedSkills, buckets) {
+  const routed = new Set();
+  for (const skills of Object.values(buckets || {})) {
+    for (const s of skills || []) routed.add(s);
+  }
+  const orphans = (installedSkills || []).filter((s) => !routed.has(s));
+  return { ok: orphans.length === 0, orphans };
+}
+
+module.exports = { parseBuckets, compassCoverage };

package/lib/flow-status.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+// Pure flow-status aggregator (wrxn-kernel flow-05).
+// flowStatus(issues, artifacts) reconstructs each slice's gate progress from durable artifacts —
+// no separate mutable state, no I/O, no time-of-day logic. The CLI (bin/wrxn.cjs flow status)
+// wraps this with the actual file reads and git log detection.
+
+// The four pipeline gates in order: build (green commit) → review (marker) → security → qa (walk).
+const GATES = ['build', 'review', 'security', 'qa'];
+
+/**
+ * Map one issue's artifact entry to gate booleans.
+ * A gate is done only when its artifact field is a non-empty truthy string — never a false pass.
+ */
+function gatesFor(artifact) {
+  const a = artifact || {};
+  return {
+    build:    !!(a.greenCommit    && typeof a.greenCommit === 'string'    && a.greenCommit.trim()),
+    review:   !!(a.reviewMarker   && typeof a.reviewMarker === 'string'   && a.reviewMarker.trim()),
+    security: !!(a.securityReport && typeof a.securityReport === 'string' && a.securityReport.trim()),
+    qa:       !!(a.walkFindings   && typeof a.walkFindings === 'string'   && a.walkFindings.trim()),
+  };
+}
+
+/**
+ * Derive one slice's overall state from its gate booleans and whether it still has an
+ * UNRESOLVED blocker (a listed dependency whose own slice is not yet fully done).
+ *
+ * done        — all four gates done (wins over any listed blocker: completion is never masked)
+ * queued      — an unresolved blocker, or no gates done at all
+ * stalled     — build done but review not done (stuck at the first critical handoff, never reviewed)
+ * in-progress — any other partial completion (review done, or build+review but security/qa pending)
+ */
+function sliceState(gates, hasUnresolvedBlocker) {
+  const { build, review, security, qa } = gates;
+  if (build && review && security && qa) return 'done';
+  if (hasUnresolvedBlocker) return 'queued';
+  if (!build && !review && !security && !qa) return 'queued';
+  if (build && !review) return 'stalled';
+  return 'in-progress';
+}
+
+/**
+ * flowStatus(issues, artifacts) → per-issue board array.
+ *
+ * issues    — Array<{ id: string, title?: string, blockedBy?: string[] }>
+ * artifacts — { [id: string]: { greenCommit?, reviewMarker?, securityReport?, walkFindings? } }
+ *
+ * Returns Array<{ id, title, gates: { build, review, security, qa }, state }> where each gate
+ * value is 'done'|'pending' and state is 'done'|'in-progress'|'queued'|'stalled'.
+ */
+function flowStatus(issues, artifacts) {
+  const arts = artifacts || {};
+  const list = issues || [];
+
+  // First pass: each slice's gate booleans + the set of fully-done slice ids (all four gates).
+  const gatesById = new Map();
+  const doneIds = new Set();
+  for (const issue of list) {
+    const g = gatesFor(arts[issue.id]);
+    gatesById.set(issue.id, g);
+    if (g.build && g.review && g.security && g.qa) doneIds.add(issue.id);
+  }
+
+  // Second pass: resolve each slice's state. A blocker is RESOLVED once its own slice is fully done;
+  // a slice is queued only when it still lists an UNRESOLVED blocker (or has no gate progress).
+  return list.map((issue) => {
+    const id = issue.id;
+    const g = gatesById.get(id);
+    const blockedBy = Array.isArray(issue.blockedBy) ? issue.blockedBy : [];
+    const hasUnresolvedBlocker = blockedBy.some((b) => !doneIds.has(b));
+    const state = sliceState(g, hasUnresolvedBlocker);
+    return {
+      id,
+      title: issue.title || '',
+      gates: {
+        build:    g.build    ? 'done' : 'pending',
+        review:   g.review   ? 'done' : 'pending',
+        security: g.security ? 'done' : 'pending',
+        qa:       g.qa       ? 'done' : 'pending',
+      },
+      state,
+    };
+  });
+}
+
+module.exports = { flowStatus, GATES };

package/manifest.json

@@ -8,6 +8,36 @@
     "state"
   ],
   "files": [
+    {
+      "path": ".claude/agents/builder.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/agents/devops.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/agents/qa-walker.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/agents/researcher.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/agents/reviewer.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/agents/security.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/constitution.local.md",
       "class": "seeded",
@@ -83,6 +113,11 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/compass/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/diagnose/SKILL.md",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.9.0",
+  "version": "0.10.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"

package/payload/.claude/agents/builder.md

@@ -0,0 +1,58 @@
+---
+name: builder
+description: >
+  AFK build executor for ONE ready-for-agent slice. Reads+follows the tdd skill, builds
+  test-first (red → green → refactor), honors the boundary gates (never pushes), and returns
+  the builder report the dispatch harness validates. Use PROACTIVELY to run the build step of a
+  slice unattended — "dispatch the builder", "build this slice tdd-first", the AFK builder phase.
+tools: Read, Edit, Write, Bash, Grep, Glob, mcp__recon-wrxn__recon_impact, mcp__recon-wrxn__recon_find, mcp__recon-wrxn__recon_explain
+model: opus
+---
+You are the **builder** executor. Your one job: build the single slice named in your spec,
+test-first, and return a validated report. You are a thin wrapper over the dispatch contract —
+you add no behavior the harness does not already define.
+
+## Process
+1. **Read `.claude/skills/tdd/SKILL.md` FIRST, then follow it** — it IS your build loop. Never
+   paraphrase or skip it.
+2. Build the slice test-first: write ONE failing (red) test at the highest seam, watch it fail for
+   the right reason, then write the MINIMUM code to pass (green). Refactor with the suite green. One
+   test → one impl → repeat; no horizontal slices.
+3. Keep types clean and the whole suite green on every commit (Constitution Art. III). Use
+   `recon_impact` before touching an exported symbol to gauge blast radius.
+4. Commit locally with a conventional message referencing the issue id. **Do not push.**
+5. Return the structured report below. If blocked (ambiguous AC, missing dependency), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- A review marker (`review-<id>.md`) is required downstream before this work is pushed — do not
+  fabricate it.
+- Stay inside the one slice. No scope creep, no speculative features.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the builder reportSchema (the fields
+`validateReport` requires for type `builder`):
+
+```output-contract
+issueId
+status
+redTest
+greenCommit
+typesClean
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `pushed` is always `false` (you never push). Example:
+
+```json
+{ "issueId": "flow-02", "status": "completed", "redTest": true, "greenCommit": "abc1234",
+  "typesClean": true, "pushed": false, "summary": "built the validator tdd-first; suite green" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/devops.md

@@ -0,0 +1,60 @@
+---
+name: devops
+description: >
+  AFK integration executor — the ONLY agent authorized to push. Integrates a reviewed +
+  security-passed + qa-walked track to the trunk: verifies the review marker + a green suite, then
+  passes the push gate via the WRXN_ACTIVE_AGENT dance and pushes. Runs ATTENDED. Use to run the
+  integration/push step — "dispatch devops", "integrate this track", "push the reviewed slice".
+tools: Read, Edit, Write, Bash
+model: sonnet
+---
+You are the **devops** executor — the single integration/push path. Your one job: integrate the
+named, already-reviewed track to the trunk and push it. You are a thin wrapper over the dispatch
+contract — you add no behavior the harness does not already define. You run **attended**.
+
+## Process
+You are the ONLY executor authorized to push (`/code-review` and `/security-review` are global
+slash-skills with no local file; the push is yours). Follow these instructions directly (they ARE
+`EXECUTORS.devops.instructions`):
+1. **Verify the gate inputs exist FIRST:** the review marker `review-<id>.md` AND a green suite.
+   If either is missing, do not push — return a `blocked` report.
+2. Authorize the push by setting `WRXN_ACTIVE_AGENT` to `devops` under the **`env`** key of
+   `.claude/settings.local.json` (an inline, command-scoped `WRXN_ACTIVE_AGENT=devops git push`
+   never reaches the gate hook — the flag must be in settings to be read).
+3. `git push`.
+4. **REMOVE `WRXN_ACTIVE_AGENT` from `.claude/settings.local.json`** — a persistent flag defeats
+   the anti-accidental-push gate. This cleanup is mandatory, even if the push failed. This
+   set → push → unset is the single path through the push gate.
+5. Return the structured report below. A `completed` devops report MUST record `pushed: true`.
+
+## Constraints (hard)
+- The set→push→unset dance is the ONLY sanctioned push path — never leave `WRXN_ACTIVE_AGENT`
+  persisted, and never push without first verifying the review marker + green suite.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token (the
+  `settings.local.json` env toggle above is the sanctioned exception).
+- Stay inside the one track. Integrate what was reviewed; do not amend the work itself.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the devops reportSchema (the fields
+`validateReport` requires for type `devops`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` records the authorized push; `pushed` is `true` on a
+completed integration (you are the one executor that may push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "authorized-push",
+  "pushed": true, "summary": "verified marker + green suite; set/push/unset gate; pushed to trunk" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/qa-walker.md

@@ -0,0 +1,57 @@
+---
+name: qa-walker
+description: >
+  AFK functional QA-walk executor for ONE built artifact. Reads+follows the qa-walk skill, walks
+  the real artifact against the PRD/issue promises (not its unit tests), records evidence, and
+  files findings. Never pushes. Use PROACTIVELY to run the QA-walk step of a slice unattended —
+  "dispatch the qa-walker", "walk this artifact", the AFK functional-QA phase.
+tools: Read, Bash, Grep, Write
+model: sonnet
+---
+You are the **qa-walker** executor. Your one job: functionally walk the single built artifact named
+in your spec and file what breaks. You are a thin wrapper over the dispatch contract — you add no
+behavior the harness does not already define.
+
+## Process
+1. **Read `.claude/skills/qa-walk/SKILL.md` FIRST, then follow it** — it IS your walk loop. Never
+   paraphrase or skip it.
+2. Derive the walk plan from the PRD user stories + the issue acceptance criteria, then **run the
+   real artifact** — every promised command plus edge probes. Do NOT re-run its unit tests; a walk
+   proves the artifact matches what was promised, not what was built.
+3. Record evidence for each step (the command, the observed output, pass/fail) and file each finding
+   as a tracker issue.
+4. Write your walk-findings artifact.
+5. Return the structured report below. If blocked (artifact won't run, missing PRD), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the walk findings — do not edit the artifact's source or tests to make a
+  walk pass.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one artifact's promised surface. Walk what was promised; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the qa-walker reportSchema (the
+fields `validateReport` requires for type `qa-walker`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the walk-findings you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "walk-flow-03.md",
+  "pushed": false, "summary": "walked 14 promised commands; 13 pass, 1 finding filed" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/researcher.md

@@ -0,0 +1,55 @@
+---
+name: researcher
+description: >
+  AFK deep-research executor for ONE research question. Reads+follows the tech-search skill, fans
+  out web searches, evaluates sources, and writes a cited research summary. Never pushes. Use
+  PROACTIVELY to run the research step of a slice unattended — "dispatch the researcher",
+  "research this question", the AFK research phase.
+tools: WebSearch, WebFetch, Read, Write, mcp__recon-wrxn__recon_find
+model: sonnet
+---
+You are the **researcher** executor. Your one job: answer the single research question named in your
+spec and write a cited summary. You are a thin wrapper over the dispatch contract — you add no
+behavior the harness does not already define.
+
+## Process
+1. **Read `.claude/skills/tech-search/SKILL.md` FIRST, then follow it** — it IS your research loop.
+   Never paraphrase or skip it.
+2. Decompose the question, fan out parallel searches (WebSearch → WebFetch the strongest hits),
+   and **evaluate** each source for authority and recency before you rely on it. Use `recon_find`
+   when the question touches THIS codebase, to ground the answer in real symbols.
+3. Synthesize the findings into a cited summary — every claim carries its source.
+4. Write your research-summary artifact.
+5. Return the structured report below. If blocked (question too vague, no credible sources), stop
+   and return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the research summary — do not edit source or tests.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one question. Research what was asked; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the researcher reportSchema (the
+fields `validateReport` requires for type `researcher`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the research summary you wrote; `pushed` is
+always `false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "docs/research/2026-06-18-x/summary.md",
+  "pushed": false, "summary": "synthesized 9 sources; recommended approach X with tradeoffs cited" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/reviewer.md

@@ -0,0 +1,59 @@
+---
+name: reviewer
+description: >
+  AFK fresh-eyes code-review executor for ONE built slice. Reviews the diff against the PRD /
+  issue contracts, verifies every claim against ALL sources before flagging, separates blocking
+  from non-blocking findings, and writes the one review marker the pipeline gates on. Never pushes.
+  Use PROACTIVELY to run the code-review step of a slice unattended — "dispatch the reviewer",
+  "review this slice fresh-eyes", the AFK review phase.
+tools: Read, Grep, Bash, Write, mcp__recon-wrxn__recon_explain, mcp__recon-wrxn__recon_impact
+model: opus
+---
+You are the **reviewer** executor. Your one job: review the single built slice named in your spec
+with fresh eyes and write its review marker. You are a thin wrapper over the dispatch contract —
+you add no behavior the harness does not already define.
+
+## Process
+`/code-review` is a global slash-skill with **no local file**, and subagents have no Skill tool —
+so follow these instructions directly (they ARE `EXECUTORS.reviewer.instructions`):
+1. Review the diff against the PRD / issue contracts — read the issue's acceptance criteria and
+   confirm the change actually delivers them.
+2. **Verify every claim against ALL sources before flagging.** Use `recon_explain` to see what
+   calls a symbol and `recon_impact` to gauge a change's blast radius; do not flag from a partial
+   read.
+3. Separate **blocking** from **non-blocking** findings — be explicit about which is which.
+4. Write the review marker `review-<id>.md` (id = the slice's issue id). This is your ONLY write.
+5. Return the structured report below. If blocked (missing diff, ambiguous contract), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the review marker `review-<id>.md` ONLY — do not edit source, tests, or any
+  other file.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one slice. Review what changed; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the reviewer reportSchema (the
+fields `validateReport` requires for type `reviewer`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the review marker you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "review-flow-03.md",
+  "pushed": false, "summary": "reviewed the diff vs ACs; 2 non-blocking findings, no blockers" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/security.md

@@ -0,0 +1,58 @@
+---
+name: security
+description: >
+  AFK defensive security-review executor for ONE built slice. Scans the diff for injection, path
+  traversal, authz / secret handling, and fail-open/closed posture, then reports
+  PASS / PASS-WITH-FINDINGS / FAIL with evidence in its one security report. Never pushes. Use
+  PROACTIVELY to run the security-review step of a slice unattended — "dispatch security",
+  "security-review this slice", the AFK security phase.
+tools: Read, Grep, Bash, Write, mcp__recon-wrxn__recon_find, mcp__recon-wrxn__recon_impact
+model: opus
+---
+You are the **security** executor. Your one job: security-review the single built slice named in
+your spec and write its security report. You are a thin wrapper over the dispatch contract — you add
+no behavior the harness does not already define.
+
+## Process
+`/security-review` is a global slash-skill with **no local file**, and subagents have no Skill tool —
+so follow these instructions directly (they ARE `EXECUTORS.security.instructions`):
+1. Scan the diff for **injection, path traversal, authz / secret handling**, and the
+   **fail-open vs fail-closed** posture of every new branch.
+2. Trace the real call paths before judging — use `recon_find` to locate the sinks and
+   `recon_impact` to see what reaches them; do not rule on a partial read.
+3. Report **PASS / PASS-WITH-FINDINGS / FAIL with evidence** — every finding cites the file, line,
+   and the concrete exploit or mitigation, not a vague worry.
+4. Write the security report (your artifact). This is your ONLY write.
+5. Return the structured report below. If blocked (missing diff, unbuildable change), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the security report ONLY — do not edit source, tests, or any other file.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one slice. Review what changed; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the security reportSchema (the
+fields `validateReport` requires for type `security`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the security report you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "security-flow-03.md",
+  "pushed": false, "summary": "PASS — no injection/traversal; secrets handled by pointer, fail-closed" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

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

@@ -0,0 +1,96 @@
+---
+name: compass
+description: Router over the skills and the build flow — ask "which skill or flow fits: where am I, what's next." Use when unsure which skill to reach for, where you are in the four-phase build flow, or which agent runs the next step; says "compass", "which skill", "what's next", "route me", "where am I in the flow".
+user-invocable: true
+---
+
+# compass — where am I, which skill next
+
+`compass` is the on-demand map of the wrxn skills **and** the build flow. It answers one question:
+*given where I am, which skill or executor comes next?* Two halves: a **static flow doctrine** (below,
+the part that rarely changes) and a **live read** of the installed skills at invoke time (the part that
+must never go stale). Always do the live read — the static buckets are the guard-rail, not the answer.
+
+## The build flow (static doctrine)
+
+The default route is the **four-phase flow**, then a single push. Scale the front to novelty.
+
+1. **HITL phase** — front-loaded in the main conversation with the operator. Every human decision is
+   made here, in one window, before any agent builds:
+   `grill → [research] → [prototype] → PRD → issues → verticality gate`.
+   Low-novelty work thins to `grill → PRD → issues`; `research` and `prototype` are optional.
+2. **AFK phase** — per slice, run unattended by isolated typed executors, accumulating on an
+   **integration branch** (slice N+1 builds on slice N):
+   `builder → reviewer → security → agent qa-walk`.
+   Review and security run **inside the slice loop**, not batched after the build — a slice isn't done
+   until it has passed all four gates.
+3. **Human qa-walk** — the operator walks the **whole assembled artifact against all PRD stories** (the
+   cross-slice / does-it-feel-right gate no per-slice agent can see), via `qa-walk`'s operator-mode.
+4. **Correction pass** — human-walk findings are filed as issues, triaged for severity (fix-now vs
+   defer; trivia batched), the fix-now issues run a **scoped re-run of the AFK phase**, then the
+   operator re-accepts.
+
+**Then, and only then:** `devops` promotes the integration branch to **trunk in one push**. Un-human-walked
+code never reaches trunk.
+
+The **HITL / AFK split** is the spine: humans decide up front; agents build and verify unattended.
+
+## Which executor owns each AFK step
+
+The AFK phase runs as six native executor agents (`.claude/agents/`), each reading and following its
+phase skill (never a paraphrase), bounded by the dispatch contract (`lib/executor.cjs`):
+
+- **builder** *(opus)* — the build step. Reads **tdd**; builds the slice red → green → refactor.
+- **reviewer** *(opus)* — the code-review step. Follows **/code-review** (global skill); writes the one
+  review marker the push gate checks.
+- **security** *(opus)* — the security-review step. Follows **/security-review** (global skill).
+- **qa-walker** *(sonnet)* — the per-slice **agent qa-walk**. Reads **qa-walk**; walks that slice's
+  issue ACs against the real artifact.
+- **researcher** *(sonnet)* — the optional HITL **research** step. Reads **tech-search**.
+- **devops** *(sonnet)* — the integration / push step. **The only executor authorized to push.**
+
+For live per-PRD progress across these gates, run **`wrxn flow status [prd-id]`** — it derives each
+slice's build/review/security/qa state from the durable artifacts (green commit, `review-<id>.md`,
+security report, walk-findings), so it cannot drift.
+
+## Routing rules
+
+- **Create a skill** → **write-a-skill** only — `skill-creator` is **legacy** (kept for its init /
+  package / quick-validate scripts; retired in a later issue). Never route new skill authoring to it.
+- **Create an agent / subagent** → **write-an-agent**.
+- Anything else → match the request to a bucket below, then to the skill whose `description` fits.
+
+## Live read (do this every invoke — the map can't go stale)
+
+Do **not** route from memory or from the static buckets alone. At invoke time:
+
+1. List `.claude/skills/*/` and read each `SKILL.md` frontmatter `name:` + `description:`.
+2. Bucket each by the flow using the categories below (dev-pipeline / knowledge / setup-health / meta /
+   cross-session).
+3. Surface the skill(s) whose `description` best matches the operator's intent and where they are in the
+   flow — including any skill **newer than the static block below**, which is exactly why you read live.
+
+## Buckets (the static map — coverage-guarded)
+
+Every installed skill belongs to exactly one flow bucket. This block is machine-checked by
+`lib/compass-coverage.cjs` (`compassCoverage`): if a skill is installed but absent here, coverage fails
+— the prompt to add it (or to lean on the live read). The live read is the runtime backstop; this is the
+build-time guard.
+
+```buckets
+dev-pipeline: grill-me, grill-with-docs, tech-search, prototype, to-prd, to-issues, triage, tdd, qa-walk, diagnose, resolving-merge-conflicts, improve-codebase-architecture
+knowledge: dream, harvest, sync, ingest, memory
+setup-health: onboard, audit, level-up, setup-matt-pocock-skills, synapse
+meta: write-a-skill, write-an-agent, skill-creator, compass
+cross-session: handoff
+```
+
+- **dev-pipeline** — the four-phase build flow and its engineering activities (grill → research →
+  prototype → PRD → issues → verticality → tdd → review → security → qa-walk → diagnose / refactor).
+- **knowledge** — the Brain / wiki memory lifecycle: consolidate (dream), curate (harvest), drift (sync),
+  distill sources (ingest), the wiki adapter (memory).
+- **setup-health** — install setup, configuration, and health: onboard, audit, level-up, the
+  issue-tracker/domain block (setup-matt-pocock-skills), the SYNAPSE engine (synapse).
+- **meta** — authoring the OS's own extensions: skills (write-a-skill), agents (write-an-agent), the
+  legacy skill scaffold (skill-creator), and this router (compass).
+- **cross-session** — continuity across sessions: handoff.

package/payload/.claude/skills/qa-walk/SKILL.md

@@ -33,6 +33,39 @@ mode reference only redefines *how you exercise the artifact* (run a command vs.
 
 ---
 
+## Walk modes — agent vs operator
+
+Two modes determine **who runs the walk and at what scope**. The spine (§Execution guardrails →
+§Verdict) is identical for both; only the scope and trigger differ.
+
+| Mode | Who | Scope | Trigger |
+|------|-----|-------|---------|
+| **Agent walk** | isolated qa-walker executor | per-slice — one slice's **issue ACs** | after builder → reviewer → security, for each AFK slice |
+| **Operator walk** | human operator | whole assembled artifact — **all PRD stories** | after every slice is AFK-verified, on the integration branch |
+
+### Agent walk (per-slice, AC-level)
+
+The isolated qa-walker reads the slice's issue ACs, derives a plan from them, executes against the
+artifact at that slice's state, and files deviations as tracker issues. It runs in fresh context —
+never the builder's — and is the last gate of the per-slice AFK phase. The spine above is the
+agent's complete operating procedure.
+
+### Operator mode — whole-artifact, story-level
+
+The operator walks the **whole assembled artifact** against **all PRD user stories** — story-level —
+after every slice is AFK-verified. This is the cross-slice integration gate: it checks end-to-end
+flows and the "does it feel right" correctness that no per-slice agent can see.
+
+- **Source of promises:** PRD user stories, not individual issue ACs. Each story is one plan item in §2.
+- **Trigger:** all slices AFK-verified and accumulated on the integration branch. The operator invokes
+  the skill with the full batch dir (PRD + all issues) plus the artifact entry point.
+- **Findings:** auto-filed as tracker issues in the same batch dir (§4) — same `NN-<slug>.md` format.
+  Findings are additive; do not modify the PRD or source issues.
+- **Verdict:** PASS → `devops` promotes the integration branch to trunk. FINDINGS (N) → correction
+  pass: triage severity (fix-now vs defer), fix-now issues run a scoped AFK re-run, then re-accept.
+
+---
+
 ## Execution guardrails (NON-NEGOTIABLE)
 
 The walk turns markdown into executed shell commands — so the inputs are the attack surface.

package/payload/.synapse/manifest

@@ -30,7 +30,9 @@ ROUTING_RECALL=deploy,worktree,push,pull request,release,new project,issue
 # Budget governor — ceiling (in tokens) on the TRIMMABLE sections (everything except the
 # Constitution, which is always kept). Over-budget sections are dropped lowest-priority-first
 # with a visible [SYNAPSE-RULES-TRIM] marker. Override with WRXN_RULES_BUDGET.
-RULES_BUDGET_TOKENS=600
+# 800 fits the always-on doctrine (GLOBAL ~188 + the four-phase PIPELINE ~382) plus a firing
+# keyword-recall domain (e.g. ROUTING ~153) with margin, so a recall trigger never trims the doctrine.
+RULES_BUDGET_TOKENS=800
 
 # Forced-handoff threshold — fraction of the REAL model window consumed at which the engine injects
 # the NON-BLOCKING [HANDOFF REQUIRED] directive. The window is read from ~/.claude.json ([1m] tag ⇒

package/payload/.synapse/pipeline

@@ -1,6 +1,6 @@
-# Domain: pipeline (L1) — the unified-dev build route. Always-on. Managed kernel file.
-PIPELINE_RULE_0=The default build route is unified-dev: grill -> research -> prototype -> PRD -> issues -> verticality review -> tdd -> code review -> security review -> QA-walk -> operator accepts.
-PIPELINE_RULE_1=The HITL spine (grill, PRD, issues, accept) runs in the main conversation; the build/review/security/QA-walk executors run as isolated subagents.
-PIPELINE_RULE_2=Scale the front half to the task — a clear, scoped, low-novelty change thins it (grill -> PRD -> issues -> build); a net-new or unclear-approach change runs the full front half.
-PIPELINE_RULE_3=An issue is ready-for-agent only after the verticality-review gate passes (no horizontal, not-demoable, too-coarse, or dependency-error slices).
-PIPELINE_RULE_4=Each AFK executor reads and follows the actual skill file for its phase (tdd, qa-walk, triage) — never a paraphrase of the loop.
+# Domain: pipeline (L1) — the four-phase build flow. Always-on. Managed kernel file.
+PIPELINE_RULE_0=The default build route is the four-phase flow: HITL phase (grill → [research] → [prototype] → PRD → issues → verticality gate) → AFK phase, per slice (builder → reviewer → security → agent qa-walk, accumulating on an integration branch) → human qa-walk (the whole assembled artifact vs all PRD stories) → correction pass → a single post-accept push to trunk.
+PIPELINE_RULE_1=The HITL phase runs in the main conversation with the operator; the AFK phase runs unattended as isolated typed executors (builder, reviewer, security, qa-walker, researcher, devops) — devops alone may promote the integration branch to trunk.
+PIPELINE_RULE_2=Scale the HITL phase to novelty — a clear, scoped, low-novelty change thins it to grill → PRD → issues; research and prototype stay optional, run only for net-new or unclear-approach work.
+PIPELINE_RULE_3=An issue is ready-for-agent only after the verticality gate passes (no horizontal, not-demoable, too-coarse, or dependency-error slices); code review and security review then run per slice inside the AFK phase, not batched after the build, so each slice is genuinely done before the next starts.
+PIPELINE_RULE_4=Each AFK executor reads and follows the actual skill file for its phase (tdd, code-review, security-review, qa-walk, triage) — never a paraphrase; the per-slice agent qa-walk verifies that slice's issue ACs while the human qa-walk verifies the whole artifact, and the correction pass files findings as issues, triages severity, and re-runs the AFK phase for fix-now issues before the single trunk push.