@gcunharodrigues/wrxn 0.9.0 → 0.11.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');
@@ -11,10 +12,15 @@ const worktree = require('../lib/worktree.cjs');
 const executor = require('../lib/executor.cjs');
 const onboard = require('../lib/onboard.cjs');
 const connect = require('../lib/connect.cjs');
+const ship = require('../lib/ship.cjs');
+const protect = require('../lib/protect.cjs');
+const release = require('../lib/release.cjs');
 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 ciChecks = require('../lib/ci-checks.cjs');
 
 const PKG_ROOT = path.join(__dirname, '..');
 
@@ -23,6 +29,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++) {
@@ -39,6 +51,14 @@ function parseArgs(argv) {
       args.flags.root = argv[++i];
     } else if (a === '--base') {
       args.flags.base = argv[++i];
+    } else if (a === '--range') {
+      args.flags.range = argv[++i];
+    } else if (a === '--branch') {
+      args.flags.branch = argv[++i];
+    } else if (a === '--title') {
+      args.flags.title = argv[++i];
+    } else if (a === '--body') {
+      args.flags.body = argv[++i];
     } else if (a === '--path') {
       args.flags.path = argv[++i];
     } else if (a === '--executor') {
@@ -114,6 +134,22 @@ Usage:
       list                       print all registered connections (agent-readable JSON)
       get <name>                 print one connection by name
 
+  wrxn ship --title "<pr title>" [--branch <name>] [--base <main>] [--body <text>] [--dry-run] [--root <dir>]
+                                 the autonomous promote path: push the reviewed branch, open a PR,
+                                 and arm auto-merge (gh pr merge --auto --squash) — GitHub merges the
+                                 instant the server-enforced CI gate is green. --branch defaults to
+                                 the repo's current branch. --dry-run prints the promote plan without
+                                 running it (a non-destructive preview). Stops at the first failing
+                                 step (a failed push never opens a PR).
+
+  wrxn protect [--root <dir>]    apply the wrxn-main-gate server-side ruleset to this repo's origin —
+                                 the hard gate that replaces the settings.local.json env-flag dance:
+                                 block direct push to the default branch, require a PR + the wrxn-ci
+                                 check, require the branch up to date, no bypass actor. Idempotent
+                                 (create-or-update by name) and fail-soft (no gh / not admin / no remote
+                                 → a clear message, exit 0). Repo-agnostic: the slug is read from origin,
+                                 so the SAME command protects the kernel, any install, and recon-wrxn.
+
   wrxn brain query "<q>" [--json] [--limit <n>] [--type <prose|code|NodeType>] [--neighbors] [--root <dir>]
                                  ask the warm Brain (recon-wrxn's code+prose graph) from the terminal.
                                  WHOLE-BRAIN by default. Discovers the live serve door via
@@ -150,6 +186,31 @@ Usage:
                                  aios-intake.md (the deterministic half of the onboard skill;
                                  workspace installs only). Idempotent.
 
+  wrxn ci [--root <dir>]         run the universal CI checks over an install (the kernel-universal
+                                 half of the wrxn-ci gate): managed-file integrity (managed files not
+                                 drifted from kernel source), wiki-lint, synapse-manifest lint, JSON
+                                 validity, and node --check syntax over the shipped .cjs. Exits non-zero
+                                 on any failure. The wrxn-ci workflow runs this after the project's own
+                                 WRXN_TEST_CMD, so CI is never a vacuous pass — even a no-suite repo is
+                                 really gated.
+
+  wrxn release-check [--range <before>..<head>] [--root <dir>]
+                                 the CD type-gate: read the merged commit messages from the git range
+                                 (default: the HEAD commit) and decide by conventional-commit type
+                                 whether the merge publishes — feat→minor, fix/perf→patch, breaking
+                                 (type! / BREAKING CHANGE:)→major; chore/docs/refactor/test → no release.
+                                 Prints {"release":bool,"bump":...} and, in CI, appends release/bump to
+                                 $GITHUB_OUTPUT. The release-on-merge workflow gates the OIDC publish on
+                                 it. Fail-safe: a non-repo / bad range → no release.
+
+  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).`;
@@ -227,6 +288,14 @@ async function main(argv) {
     if (report.migrationsRan && report.migrationsRan.length) {
       process.stdout.write(`migrations applied: ${report.migrationsRan.join(', ')}\n`);
     }
+    // Surface the server-side gate outcome (gate-02 MED-1). A soft-skip on the PRIMARY delivery path
+    // must NOT be silent — a silent skip is the very "no-op gate believed active" defect this epic kills.
+    // Mirrors `wrxn protect`; fail-soft is preserved (this only prints, never throws, still exit 0).
+    if (report.protection) {
+      process.stdout.write(report.protection.ok
+        ? `protection: ${report.protection.detail}\n`
+        : `protection skipped: ${report.protection.reason}\n`);
+    }
     return 0;
   }
 
@@ -424,6 +493,61 @@ async function main(argv) {
     }
   }
 
+  if (cmd === 'ship') {
+    // The autonomous promote path: push the reviewed branch, open a PR, arm auto-merge — GitHub
+    // merges the instant the server-enforced CI gate is green — no env flag, no GitHub clicks. Real
+    // git/gh run via the
+    // real spawnSync invoker (ship.defaultInvoke) — that is what makes the promote "validated by
+    // invocation". --dry-run prints the plan without running it (a non-destructive preview).
+    const root = path.resolve(args.flags.root || process.cwd());
+    let branch = args.flags.branch;
+    if (!branch) {
+      // Default to the repo's current branch — the reviewed branch the devops executor stands on.
+      try {
+        branch = execFileSync('git', ['-C', root, 'branch', '--show-current'], { encoding: 'utf8' }).trim();
+      } catch { branch = ''; }
+    }
+    const title = args.flags.title;
+    const base = args.flags.base || ship.DEFAULT_BASE;
+    const body = args.flags.body || '';
+    if (!branch) { process.stderr.write('wrxn: ship requires a branch — pass --branch <name>, or run inside the git repo on the branch to promote\n'); return 2; }
+    if (!title) { process.stderr.write('wrxn: ship requires --title "<pr title>"\n'); return 2; }
+    let plan;
+    try {
+      plan = ship.buildShipPlan({ branch, title, base, body });
+    } catch (err) {
+      process.stderr.write(`wrxn: ${err.message}\n`);
+      return 2;
+    }
+    if (args.flags['dry-run']) {
+      process.stdout.write(JSON.stringify(plan, null, 2) + '\n');
+      return 0;
+    }
+    const res = ship.ship({ branch, title, base, body }); // real defaultInvoke (git + gh)
+    for (const s of res.steps) {
+      process.stdout.write(`  ${s.ok ? '✓' : '✗'} ${s.step} — ${s.detail}\n`);
+    }
+    if (res.ok) {
+      process.stdout.write(`shipped ${branch} → PR opened on ${base} with auto-merge armed (GitHub merges when CI is green)\n`);
+      return 0;
+    }
+    process.stderr.write(`wrxn: ship failed at "${res.failed}" — promote halted (no PR/auto-merge past the failure)\n`);
+    return 2;
+  }
+
+  if (cmd === 'protect') {
+    // Apply the wrxn-main-gate server-side ruleset to this repo's origin — the hard gate that replaces
+    // the disarmable settings.local.json env-flag dance (ADR 0007). Repo-agnostic: the slug is read from
+    // origin (protect.protectOrigin), so the SAME command protects the kernel, any install, and the
+    // recon-wrxn sibling. Real git/gh run via protect's defaultInvoke (no injected invoker) — that is
+    // what makes the application "validated by invocation". Fail-soft: no gh / not admin / no remote → a
+    // clear message and exit 0, so it never breaks a remote-less checkout.
+    const root = path.resolve(args.flags.root || process.cwd());
+    const res = protect.protectOrigin(root);
+    process.stdout.write(res.ok ? `wrxn protect → ${res.detail}\n` : `wrxn protect → skipped: ${res.reason}\n`);
+    return 0;
+  }
+
   if (cmd === 'brain') {
     const sub = args._[1];
     if (sub !== 'query') {
@@ -490,6 +614,182 @@ 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;
+  }
+
+  if (cmd === 'ci') {
+    const root = path.resolve(args.flags.root || process.cwd());
+    const { ok, results } = ciChecks.runChecks(root, { pkgRoot: PKG_ROOT });
+    process.stdout.write(`wrxn-ci (${root})\n`);
+    for (const c of results) {
+      process.stdout.write(`  ${c.ok ? '✓' : '✗'} ${c.name} — ${c.detail}\n`);
+      for (const f of c.failures) process.stdout.write(`      - ${f}\n`);
+    }
+    process.stdout.write(ok ? 'wrxn-ci PASS\n' : 'wrxn-ci FAIL\n');
+    return ok ? 0 : 2;
+  }
+
+  if (cmd === 'release-check') {
+    // The CD type-gate bridge (gate-05): read the merged commit messages from a git range, decide by
+    // conventional-commit type whether the merge publishes, and emit the decision. release.yml gates the
+    // OIDC publish on it; recon-wrxn (gate-06) reuses the same gate via `npx @gcunharodrigues/wrxn`.
+    // The git read lives here (CLI layer); the pure classifier (shouldRelease) is unit-tested.
+    const root = path.resolve(args.flags.root || process.cwd());
+    const range = args.flags.range;
+    let logArgs;
+    if (range && range.includes('..')) {
+      const [before, head] = range.split('..');
+      const headRef = head || 'HEAD';
+      // A zero before-sha is GitHub's "new branch" sentinel — there is no prior tip, so the range is
+      // meaningless; read only the head commit.
+      logArgs = /^0+$/.test(before)
+        ? ['-C', root, 'log', '-1', '--format=%B%x00', headRef]
+        : ['-C', root, 'log', '--format=%B%x00', range];
+    } else {
+      logArgs = ['-C', root, 'log', '-1', '--format=%B%x00', range || 'HEAD'];
+    }
+    let raw = '';
+    try {
+      raw = execFileSync('git', logArgs, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch {
+      // Not a git repo / bad range — fail SAFE: never publish on uncertainty.
+      raw = '';
+    }
+    const decision = release.shouldRelease(release.parseLog(raw));
+    // Expose the decision to the workflow's conditional publish step.
+    if (process.env.GITHUB_OUTPUT) {
+      fs.appendFileSync(process.env.GITHUB_OUTPUT, `release=${decision.release}\nbump=${decision.bump || ''}\n`);
+    }
+    process.stdout.write(JSON.stringify(decision) + '\n');
+    return 0;
+  }
+
   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 };