@gcunharodrigues/wrxn 0.9.0 → 0.11.0

package/lib/ci-checks.cjs

@@ -0,0 +1,296 @@
+'use strict';
+
+// WRXN universal CI checks — the pure-node predicates the `wrxn-ci` workflow runs on every PR so CI
+// is never a vacuous `true`, even on a repo with no project suite. Each predicate is a deterministic
+// function over the install tree returning { name, ok, failures: string[], detail }. The thin
+// `wrxn ci` CLI (bin/wrxn.cjs) runs them in the install cwd and exits non-zero on any failure, so the
+// SAME tested logic runs in the kernel and in every install. No side effects, node stdlib only.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { isDeepStrictEqual } = require('util');
+
+const { RECEIPT, MCP_PATH } = require('./install.cjs');
+const { loadManifest, inProfile } = require('./manifest.cjs');
+
+function result(name, failures, detail) {
+  return { name, ok: failures.length === 0, failures, detail };
+}
+
+function readReceipt(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, RECEIPT), 'utf8'));
+}
+
+// ── managed-integrity ────────────────────────────────────────────────────────
+//
+// The server-side replacement for the demoted local managed-guard hook: every kernel-managed file must
+// byte-match its canonical source in the kernel package payload — i.e. it has not drifted from
+// kernel-owned content. The managed SET is anchored to the kernel `manifest.json` (the source of
+// truth), NOT to the install's `wrxn.install.json` receipt (CF-2): the receipt is itself unprotected
+// and never integrity-checked, so deriving the set from it let an attacker edit a managed file and
+// drop/reclassify its receipt entry to pass the check (security MED-1; HIGH if an install ever takes
+// untrusted fork PRs). The receipt is trusted only for the install PROFILE (project|workspace), which
+// selects which managed files were laid. `.mcp.json` is the one file that is byte-DIVERGENT yet still
+// checked: it is managed but operator-MERGED (init/update fold the recon-wrxn server into the
+// operator's other servers rather than overwrite), so a blanket byte-equality is wrong AND a blanket
+// skip is a hole — an injected/swapped MCP `command` auto-executes on session open (security MED-2 /
+// SEC-MED-1, issue 10). Instead it is validated merge-aware (`mcpServerFailures`): every KERNEL-MANAGED
+// server entry (the keys in payload/.mcp.json, e.g. recon-wrxn) must deep-equal the payload — the exact
+// post-condition of install.cjs `mergeMcpServer` — while operator-ADDED servers (keys not in the
+// payload) are the operator's own repo content and pass. A repo with no receipt is not a wrxn install
+// (nothing managed to verify) → passes; an UNREADABLE receipt is a real defect → fails.
+function managedIntegrity(root, opts) {
+  const pkgRoot = (opts && opts.pkgRoot) || path.join(__dirname, '..');
+  const receiptPath = path.join(root, RECEIPT);
+  if (!fs.existsSync(receiptPath)) {
+    return result('managed-integrity', [], 'no wrxn.install.json — not a wrxn install, nothing to verify');
+  }
+  let receipt;
+  try {
+    receipt = readReceipt(root);
+  } catch (err) {
+    return result('managed-integrity', [`${RECEIPT} is unreadable: ${err.message}`], 'receipt corrupt');
+  }
+  let manifest;
+  try {
+    manifest = loadManifest(path.join(pkgRoot, 'manifest.json'));
+  } catch (err) {
+    return result('managed-integrity', [`kernel manifest is unreadable: ${err.message}`], 'manifest missing');
+  }
+
+  const profile = receipt.profile || 'project';
+  const managed = manifest.files.filter((f) => f.class === 'managed');
+  const failures = [];
+  let checked = 0;
+  for (const f of managed) {
+    const installed = path.join(root, f.path);
+    const canonical = path.join(pkgRoot, 'payload', f.path);
+    if (!fs.existsSync(canonical)) continue; // no kernel source to compare against → cannot be drift
+    if (!fs.existsSync(installed)) {
+      // An in-profile managed file MUST be present; an out-of-profile one is legitimately absent (a
+      // project install does not lay workspace files). The profile comes from the receipt, but it can
+      // only EXCLUDE a missing-file check — it can never suppress a present, drifted file (below).
+      if (inProfile(f.profile, profile)) {
+        failures.push(`${f.path} — managed file is missing from the install`);
+      }
+      continue;
+    }
+    // Present on disk → it must match the kernel source REGARDLESS of the claimed profile, so a flipped
+    // receipt profile cannot hide a tampered workspace-managed file (CF-2 defense-in-depth). `.mcp.json`
+    // is operator-MERGED so byte-equality is wrong → validate its kernel-managed server entries instead.
+    checked++;
+    if (f.path === MCP_PATH) {
+      failures.push(...mcpServerFailures(installed, canonical));
+    } else if (!fs.readFileSync(installed).equals(fs.readFileSync(canonical))) {
+      failures.push(`${f.path} — drifted from the kernel-owned source`);
+    }
+  }
+  return result('managed-integrity', failures, `${checked} managed file(s) checked`);
+}
+
+// Merge-aware integrity for the operator-MERGED `.mcp.json`: assert each KERNEL-MANAGED server entry
+// (a key present in the payload `.mcp.json`, e.g. recon-wrxn) is present in the install and deep-equals
+// the payload — the exact post-condition install.cjs `mergeMcpServer` writes — so a swapped/injected
+// launch `command` on a kernel server is caught. Operator-ADDED server keys (absent from the payload)
+// are the operator's own repo content and are intentionally NOT judged (no false positive). Corrupt
+// install JSON fails closed here too (jsonValidity also catches it). The payload is kernel-trusted; a
+// thrown payload parse propagates to the entrypoint (exit non-zero) — fail-closed by design.
+function mcpServerFailures(installed, canonical) {
+  let install;
+  try {
+    install = JSON.parse(fs.readFileSync(installed, 'utf8'));
+  } catch (err) {
+    return [`${MCP_PATH} — invalid JSON: ${err.message}`];
+  }
+  const payloadServers = (JSON.parse(fs.readFileSync(canonical, 'utf8')) || {}).mcpServers || {};
+  const installServers = (install && install.mcpServers) || {};
+  const failures = [];
+  for (const key of Object.keys(payloadServers)) {
+    if (!(key in installServers)) {
+      failures.push(`${MCP_PATH} — kernel-managed MCP server "${key}" is missing`);
+    } else if (!isDeepStrictEqual(installServers[key], payloadServers[key])) {
+      failures.push(`${MCP_PATH} — kernel-managed MCP server "${key}" drifted from the kernel-owned source`);
+    }
+  }
+  return failures;
+}
+
+// ── wiki-lint ─────────────────────────────────────────────────────────────────
+//
+// Every human-prose wiki page must carry a well-formed frontmatter block with the required keys
+// (name / description / tier) — the same contract the session-close wiki-lint hook flags, enforced
+// here server-side. The machine-written `_rules`/`_slots` tiers are deliberately out of scope (they
+// are not human-prose frontmatter). An empty/absent wiki tree passes. Re-implemented inline rather
+// than importing the payload hook so lib stays free of payload dependencies.
+const WIKI_TIERS = ['concepts', 'decisions', 'gotchas', 'sessions'];
+const WIKI_REQUIRED_KEYS = ['name', 'description', 'tier'];
+
+// Return the reason a page is malformed, or null when it is well-formed.
+function lintWikiPage(text) {
+  const src = String(text || '');
+  if (!src.startsWith('---')) return 'no frontmatter';
+  const end = src.indexOf('\n---', 3);
+  if (end < 0) return 'unterminated frontmatter';
+  const fm = src.slice(3, end);
+  const missing = WIKI_REQUIRED_KEYS.filter((k) => !new RegExp(`^${k}\\s*:`, 'm').test(fm));
+  if (missing.length) return `missing ${missing.join('/')}`;
+  return null;
+}
+
+function wikiLint(root) {
+  const failures = [];
+  for (const tier of WIKI_TIERS) {
+    const dir = path.join(root, '.wrxn', 'wiki', tier);
+    let names;
+    try {
+      names = fs.readdirSync(dir).filter((n) => n.endsWith('.md'));
+    } catch {
+      continue; // missing tier → nothing to lint
+    }
+    for (const name of names) {
+      let text;
+      try {
+        text = fs.readFileSync(path.join(dir, name), 'utf8');
+      } catch {
+        continue;
+      }
+      const reason = lintWikiPage(text);
+      if (reason) failures.push(`${tier}/${name} — ${reason}`);
+    }
+  }
+  return result('wiki-lint', failures, failures.length ? `${failures.length} malformed page(s)` : 'wiki frontmatter clean');
+}
+
+// ── synapse-manifest lint ─────────────────────────────────────────────────────
+//
+// The SYNAPSE engine reads `.synapse/manifest` (flat KEY=VALUE) on every prompt and, for each active
+// domain, loads its rules from the sibling file `.synapse/<domain-lowercased>`. A manifest that marks
+// a domain active but ships no domain file is a silent divergence — the engine reads nothing. This
+// lint enforces the contract: the manifest exists and parses, and every active domain (except the
+// special CONSTITUTION, whose body is sourced from .claude/constitution.md) has its domain file.
+function synapseManifestLint(root) {
+  const manifestPath = path.join(root, '.synapse', 'manifest');
+  let text;
+  try {
+    text = fs.readFileSync(manifestPath, 'utf8');
+  } catch {
+    return result('synapse-manifest', ['.synapse/manifest is absent or unreadable'], 'no manifest');
+  }
+
+  // Collect the active domains: a line `<NAME>_STATE=active` marks NAME active.
+  const active = new Set();
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^(.+)_STATE=(.*)$/);
+    if (m && m[2].trim() === 'active') active.add(m[1]);
+  }
+
+  if (active.size === 0) {
+    return result('synapse-manifest', ['.synapse/manifest declares no active domain'], 'empty manifest');
+  }
+
+  const failures = [];
+  for (const name of active) {
+    if (name === 'CONSTITUTION') continue; // sourced from .claude/constitution.md, not a domain file
+    const domainFile = path.join(root, '.synapse', name.toLowerCase());
+    if (!fs.existsSync(domainFile)) {
+      failures.push(`${name} — active in the manifest but .synapse/${name.toLowerCase()} is missing`);
+    }
+  }
+  return result('synapse-manifest', failures, `${active.size} active domain(s) checked`);
+}
+
+// ── JSON validity ─────────────────────────────────────────────────────────────
+//
+// Every wrxn-owned JSON file in the install must parse. Scope is bounded to the install receipt plus
+// the `.json` paths in the manifest (e.g. .mcp.json, .recon-wrxn.json) — never the whole tree, so it
+// can't false-positive on node_modules or an operator's own fixtures. A corrupt receipt or a
+// hand-broken config is a real defect CI should catch.
+function jsonPaths(pkgRoot) {
+  const paths = [RECEIPT];
+  try {
+    const manifest = loadManifest(path.join(pkgRoot, 'manifest.json'));
+    for (const entry of manifest.files) {
+      if (entry.path.endsWith('.json')) paths.push(entry.path);
+    }
+  } catch {
+    /* no manifest reachable → still validate the receipt */
+  }
+  return paths;
+}
+
+function jsonValidity(root, opts) {
+  const pkgRoot = (opts && opts.pkgRoot) || path.join(__dirname, '..');
+  const failures = [];
+  for (const rel of jsonPaths(pkgRoot)) {
+    const p = path.join(root, rel);
+    if (!fs.existsSync(p)) continue;
+    try {
+      JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (err) {
+      failures.push(`${rel} — invalid JSON: ${err.message}`);
+    }
+  }
+  return result('json-validity', failures, `${jsonPaths(pkgRoot).length} json path(s) checked`);
+}
+
+// ── node --check syntax ───────────────────────────────────────────────────────
+//
+// Every wrxn-shipped `.cjs` (the hooks + the .wrxn adapters) must parse — a broken hook fails open
+// silently in production, so a syntax error must never reach an install un-caught. Scope is the
+// manifest's `.cjs` entries present in the install; each is verified with a real `node --check` (parse
+// only, never executed). Returns ok when all parse, else names each offender.
+function checkSyntax(file) {
+  try {
+    execFileSync(process.execPath, ['--check', file], { stdio: 'pipe' });
+    return null;
+  } catch (err) {
+    const detail = String((err && err.stderr) || (err && err.message) || 'parse error').split('\n').find(Boolean) || 'parse error';
+    return detail.trim();
+  }
+}
+
+function cjsPaths(pkgRoot) {
+  try {
+    const manifest = loadManifest(path.join(pkgRoot, 'manifest.json'));
+    return manifest.files.filter((e) => e.path.endsWith('.cjs')).map((e) => e.path);
+  } catch {
+    return [];
+  }
+}
+
+function nodeCheck(root, opts) {
+  const pkgRoot = (opts && opts.pkgRoot) || path.join(__dirname, '..');
+  const failures = [];
+  let checked = 0;
+  for (const rel of cjsPaths(pkgRoot)) {
+    const p = path.join(root, rel);
+    if (!fs.existsSync(p)) continue;
+    checked++;
+    const err = checkSyntax(p);
+    if (err) failures.push(`${rel} — ${err}`);
+  }
+  return result('node-check', failures, `${checked} .cjs file(s) parsed`);
+}
+
+// ── the universal gate ────────────────────────────────────────────────────────
+//
+// Run every universal check over an install root. This is the gate the `wrxn ci` CLI (and thus the
+// wrxn-ci workflow) invokes — independent of any project suite, so even a no-suite repo gets a real,
+// fail-able check. ok is the AND of all checks. The project `WRXN_TEST_CMD` runs as its own workflow
+// step (skipped when `true`/empty), NOT here — these are the kernel-universal checks only.
+function runChecks(root, opts) {
+  const o = opts || {};
+  const results = [
+    managedIntegrity(root, o),
+    wikiLint(root),
+    synapseManifestLint(root),
+    jsonValidity(root, o),
+    nodeCheck(root, o),
+  ];
+  return { ok: results.every((r) => r.ok), results };
+}
+
+module.exports = { managedIntegrity, wikiLint, synapseManifestLint, jsonValidity, nodeCheck, runChecks };

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/executor.cjs

@@ -76,11 +76,14 @@ const EXECUTORS = {
     required: GENERIC_REQUIRED,
   },
   devops: {
-    skill: null, // the integration / push executor — instructions; the ONLY type that may push
+    skill: null, // the integration / promote 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 authorize the push by setting WRXN_ACTIVE_AGENT to devops under the `env` key of .claude/settings.local.json (an inline command-scoped assignment never reaches the gate hook), push, then REMOVE WRXN_ACTIVE_AGENT from .claude/settings.local.json — a persistent flag defeats the anti-accidental-push gate. This is the single path through the push gate.',
+      'You are the devops integration executor — the ONLY executor authorized to promote a track to the',
+      'trunk. Verify the track is reviewed + security-passed + qa-walked and you are on the reviewed branch,',
+      'then promote with ONE command: `wrxn ship --title "<conventional PR title>"` — it pushes the branch,',
+      'opens a PR, and arms auto-merge (`gh pr merge --auto --squash`). No env flag, no settings file, no',
+      'GitHub clicks. Confirm auto-merge is armed; the server-enforced CI ruleset then merges to the trunk',
+      'the instant CI is green. This is the single promote path through the push gate.',
     ],
     artifact: 'authorized-push',
     canPush: true,

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/lib/protect.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+// WRXN protect — the server-side hard gate (gate-redesign gate-02).
+//
+// A client-side hook can never be hard enforcement (it gates one tool surface, not the repository).
+// The only control that survives every bypass — human terminal, IDE, MCP, API, `--no-verify`, the
+// 2026-06-19 settings.local.json disarm bug — is a SERVER-SIDE GitHub branch ruleset. This module
+// builds and applies the `wrxn-main-gate` ruleset on a repo's `origin`: block direct push to the
+// default branch, require a PR (0 approvals — a solo account auto-merges its own PR), require the
+// `wrxn-ci` status check, require the branch up to date (race-safety), and NO bypass actor.
+//
+// Application is idempotent (create-or-update BY NAME — re-run = no-op) and fail-soft (no `gh`, not a
+// repo admin, no remote, or any non-zero exit → a clear message and exit 0, never a throw, so it can
+// never break `wrxn update` on a remote-less install). REUSE of lib/connect.cjs's injectable-invoker
+// shape: an injected `invoker` makes unit tests deterministic; the real `spawnSync gh`/`git` runs only
+// when no invoker is injected (the CLI layer) — that is what makes the application "validated by
+// invocation". The ruleset is repo-agnostic via `~DEFAULT_BRANCH`, so the SAME spec protects any
+// default-main repo (the kernel, every install, and the recon-wrxn sibling — gate-06).
+//
+// lib/protect.cjs is package code (invoked via bin/wrxn.cjs), NOT payload — no manifest entry,
+// consistent with lib/connect.cjs / lib/ship.cjs / lib/executor.cjs / lib/onboard.cjs.
+
+const { spawnSync } = require('child_process');
+
+const RULESET_NAME = 'wrxn-main-gate';
+const DEFAULT_CHECK = 'wrxn-ci';
+
+/**
+ * Build the `wrxn-main-gate` GitHub repository-ruleset payload. PURE — a fresh, independent object
+ * each call, no side effects. The authoritative payload (gate-02 API contract): block direct push to
+ * the default branch, require a PR with 0 approvals, require `requiredCheck` strict (up-to-date), no
+ * bypass actor. `~DEFAULT_BRANCH` keeps it repo-agnostic (no hard-coded `main`).
+ * @param {{ requiredCheck?: string }} [opts]
+ * @returns {object} the ruleset payload for POST/PUT `/repos/{slug}/rulesets`
+ */
+function buildRulesetSpec({ requiredCheck = DEFAULT_CHECK } = {}) {
+  return {
+    name: RULESET_NAME,
+    target: 'branch',
+    enforcement: 'active',
+    bypass_actors: [],
+    conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+    rules: [
+      { type: 'deletion' },
+      { type: 'non_fast_forward' },
+      {
+        type: 'pull_request',
+        parameters: {
+          required_approving_review_count: 0,
+          dismiss_stale_reviews_on_push: false,
+          require_code_owner_review: false,
+          require_last_push_approval: false,
+          required_review_thread_resolution: false,
+        },
+      },
+      {
+        type: 'required_status_checks',
+        parameters: {
+          strict_required_status_checks_policy: true,
+          required_status_checks: [{ context: requiredCheck }],
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * The real command invoker — a single spawnSync (mirrors lib/ship.cjs / lib/connect.cjs defaultInvoke).
+ * Captures stdout (needed to parse the ruleset list) and passes a body on stdin (the create/update).
+ * The CLI layer wires this implicitly (no injected invoker) — that is what makes the apply real.
+ * @returns {{ ok:boolean, status:number|null, stdout:string, stderr:string }}
+ */
+function defaultInvoke({ cmd, args, input }) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', input: input || undefined });
+  // Judge a child by its EXIT STATUS, not by whether we finished writing its stdin. The real `gh api
+  // ... --input -` reads the body from stdin; if it (or a stub) exits before draining it, spawnSync's
+  // stdin write races the child's exit and surfaces an EPIPE in `r.error` — yet it still captures the
+  // real `status`/`stdout`. Only a spawn that NEVER ran (e.g. ENOENT — `status` stays null) is a true
+  // failure here; an EPIPE on a child that exited 0 is a success, not a "command not found" skip.
+  if (r.error && r.status == null) {
+    return { ok: false, status: null, stdout: '', stderr: r.error.code || r.error.message };
+  }
+  return { ok: r.status === 0, status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+/** A fail-soft skip result — a logged-elsewhere reason, never a throw, so it never breaks `wrxn update`. */
+function softSkip(reason) {
+  return { ok: false, action: 'skipped', reason };
+}
+
+/** One-line failure detail from an invoker result (status + first stderr line). */
+function detailOf(r) {
+  const status = r.status == null ? 'no exit (command not found?)' : `exit ${r.status}`;
+  const err = String(r.stderr || '').trim().split('\n')[0];
+  return err ? `${status}: ${err}` : status;
+}
+
+/**
+ * Apply the `wrxn-main-gate` ruleset to `slug`'s repo via `gh api`. Idempotent (list → create-or-update
+ * BY NAME, so a re-run converges to a no-op) and fail-soft (no gh / not admin / no remote / any
+ * non-zero exit → a skipped result carrying a clear reason; NEVER throws). The invoker is injectable so
+ * unit tests are deterministic; the CLI layer uses the real `gh` spawn.
+ * @param {{ invoker?:Function, slug?:string, requiredCheck?:string }} [opts]
+ * @returns {{ ok:boolean, action:'created'|'updated'|'skipped', slug?:string, name?:string, detail?:string, reason?:string }}
+ */
+function applyProtection({ invoker, slug, requiredCheck = DEFAULT_CHECK } = {}) {
+  const run = invoker || defaultInvoke;
+
+  if (!slug || typeof slug !== 'string' || slug.trim() === '') {
+    return softSkip('no origin remote — the wrxn-main-gate ruleset is not applied (a remote-less install is unprotected here; protection lands when it gains a GitHub origin)');
+  }
+
+  // 1. list existing rulesets — the idempotency lookup (find one named wrxn-main-gate).
+  const list = run({ cmd: 'gh', args: ['api', `/repos/${slug}/rulesets`] });
+  if (!list.ok) {
+    return softSkip(`could not list rulesets on ${slug} (${detailOf(list)}) — is gh installed, authenticated, and admin on the repo? skipping (exit 0)`);
+  }
+  let rulesets;
+  try {
+    rulesets = JSON.parse(list.stdout || '[]');
+  } catch {
+    return softSkip(`unexpected gh output listing rulesets on ${slug} — skipping`);
+  }
+  const existing = Array.isArray(rulesets) ? rulesets.find((r) => r && r.name === RULESET_NAME) : null;
+  const body = JSON.stringify(buildRulesetSpec({ requiredCheck }));
+
+  // 2. update in place (PUT to the existing id) if present, else create (POST) — re-run = no-op.
+  if (existing) {
+    const put = run({ cmd: 'gh', args: ['api', '--method', 'PUT', `/repos/${slug}/rulesets/${existing.id}`, '--input', '-'], input: body });
+    if (!put.ok) {
+      return softSkip(`could not update the ${RULESET_NAME} ruleset on ${slug} (${detailOf(put)}) — skipping`);
+    }
+    return { ok: true, action: 'updated', slug, name: RULESET_NAME, detail: `${RULESET_NAME} updated on ${slug}` };
+  }
+  const post = run({ cmd: 'gh', args: ['api', '--method', 'POST', `/repos/${slug}/rulesets`, '--input', '-'], input: body });
+  if (!post.ok) {
+    return softSkip(`could not create the ${RULESET_NAME} ruleset on ${slug} (${detailOf(post)}) — is the token a repo admin? skipping`);
+  }
+  return { ok: true, action: 'created', slug, name: RULESET_NAME, detail: `${RULESET_NAME} created on ${slug}` };
+}
+
+/** A well-formed GitHub `owner/repo` slug: owner starts alphanumeric, repo is alnum/`.`/`_`/`-`. */
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+
+/**
+ * Parse an `owner/repo` slug from a git remote URL (ssh `git@host:owner/repo.git`, https
+ * `https://host/owner/repo.git`, with or without the `.git` suffix / a trailing slash) or a bare
+ * `owner/repo`. The captured slug is then VALIDATED against the GitHub owner/repo grammar (gate-02
+ * LOW-1, defense-in-depth): `..` traversal, spaces, `;`, `$()`, backticks, and `--flag`-looking text
+ * are rejected → null, so a malformed remote fail-soft-skips instead of reaching `gh` as data. Returns
+ * null when no well-formed slug can be read — protection then fail-soft-skips.
+ */
+function parseSlug(url) {
+  const s = String(url || '').trim();
+  if (!s) return null;
+  const m = s.match(/(?:^|[:/])([^/:]+\/[^/:]+?)(?:\.git)?\/?$/);
+  const slug = m ? m[1] : null;
+  return slug && SLUG_RE.test(slug) ? slug : null;
+}
+
+/**
+ * Derive the `owner/repo` slug of a repo's `origin` remote. Injectable git invoker for tests; the
+ * real `git` spawn runs at the CLI/update/migration layer. Returns null on no origin / parse failure
+ * (→ applyProtection soft-skips) — never throws.
+ */
+function originSlug(root, { invoker } = {}) {
+  const run = invoker || defaultInvoke;
+  const r = run({ cmd: 'git', args: ['-C', root, 'remote', 'get-url', 'origin'] });
+  if (!r.ok) return null;
+  return parseSlug(r.stdout);
+}
+
+/**
+ * Derive the origin slug of the install at `root` and apply the ruleset to it. The single entry point
+ * the CLI (`wrxn protect`), `wrxn update`, and migration 005 share. Repo-agnostic (the slug is read
+ * from origin, so it works for the kernel, any install, and recon-wrxn) and fail-soft end-to-end (a
+ * remote-less root → applyProtection's no-remote skip; never throws). Both invokers are injectable.
+ * @param {string} root install/repo root
+ * @param {{ gitInvoker?:Function, ghInvoker?:Function, requiredCheck?:string }} [opts]
+ */
+function protectOrigin(root, { gitInvoker, ghInvoker, requiredCheck } = {}) {
+  const slug = originSlug(root, { invoker: gitInvoker });
+  return applyProtection({ slug, invoker: ghInvoker, requiredCheck });
+}
+
+module.exports = {
+  RULESET_NAME,
+  DEFAULT_CHECK,
+  buildRulesetSpec,
+  defaultInvoke,
+  applyProtection,
+  parseSlug,
+  originSlug,
+  protectOrigin,
+};