exonous 0.0.0-stage → 2.10.4

package/assets/machine/hooks/lib/template.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+// PR template resolution: repo template (any case) → ~/.claude/exonous/PR-TEMPLATE.md → copy shipped beside the hooks.
+const fs = require('fs');
+const path = require('path');
+const { exoDir, stateDir, repoRoot, repoKey } = require('./paths.cjs');
+
+const TEMPLATE_NAME = 'pull_request_template.md';
+const REPO_DIRS = ['.github', 'docs', ''];
+const BUNDLED = path.join(__dirname, '..', '..', 'PR-TEMPLATE.md');
+const MAX_BYTES = 64 * 1024;
+
+function sectionsOf(text) {
+  const visible = String(text)
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^(```|~~~)[\s\S]*?^\1[^\n]*$/gm, '');
+  return [...visible.matchAll(/^##(?!#)[ \t]+(.+?)[ \t#]*$/gm)].map((m) => m[1].trim());
+}
+
+function findInDir(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const matches = names.filter((n) => n.toLowerCase() === TEMPLATE_NAME).map((n) => path.join(dir, n));
+  return matches.find(usable) || null;
+}
+
+// Symlinks could point outside the repo; huge files are not templates.
+function usable(file) {
+  try {
+    const stat = fs.lstatSync(file);
+    return stat.isFile() && stat.size <= MAX_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function candidates(cwd) {
+  let root = null;
+  try {
+    root = repoRoot(cwd);
+  } catch {
+    // outside a repo only the machine templates apply
+  }
+  const repo = root ? REPO_DIRS.map((d) => () => findInDir(path.join(root, d))) : [];
+  return [...repo, () => path.join(exoDir(), 'PR-TEMPLATE.md'), () => BUNDLED];
+}
+
+/** @returns {{ path: string | null, sections: string[] }} */
+function resolveTemplate(cwd = process.cwd()) {
+  for (const candidate of candidates(cwd)) {
+    const file = candidate();
+    if (!file || !usable(file)) continue;
+    try {
+      return { path: file, sections: sectionsOf(fs.readFileSync(file, 'utf8')) };
+    } catch {
+      // unreadable: try the next one
+    }
+  }
+  return { path: null, sections: [] };
+}
+
+function draftPath(cwd = process.cwd()) {
+  return path.join(stateDir(), 'pr', `${repoKey(cwd)}.md`);
+}
+
+module.exports = { resolveTemplate, sectionsOf, draftPath };

package/assets/machine/hooks/lib/token.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+// One-shot gate tokens: commit binds the staged tree, push binds the pushed commit; both expire in 15 minutes.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { exoDir, stateDir, repoKey, gitOut, foreignOwner } = require('./paths.cjs');
+
+const TTL_MS = 15 * 60 * 1000;
+const BINDINGS = {
+  commit: ['write-tree'],
+  push: ['rev-parse', '--verify', 'HEAD^{commit}'],
+};
+
+function bindingArgs(kind) {
+  const args = BINDINGS[kind];
+  if (!args) throw new Error(`unknown token kind: ${kind}`);
+  return args;
+}
+
+function currentSha(kind, cwd) {
+  const out = gitOut(cwd, bindingArgs(kind));
+  return out ? out.trim() : null;
+}
+
+function tokenFile(kind, cwd) {
+  return path.join(stateDir(), kind, `${repoKey(cwd)}.json`);
+}
+
+const unique = () => `${process.pid}.${crypto.randomBytes(6).toString('hex')}`;
+
+/** @param {{ now?: number }} [options] */
+function mint(kind, cwd, { now = Date.now() } = {}) {
+  bindingArgs(kind);
+  for (const dir of [exoDir(), stateDir()]) {
+    const owner = foreignOwner(dir);
+    if (owner !== null) throw new Error(`${dir} is owned by uid ${owner}, not you — run exonous as that user, or fix it with sudo chown -R "$(id -un)" ~/.claude/exonous`);
+  }
+  const file = tokenFile(kind, cwd);
+  const sha = currentSha(kind, cwd);
+  if (!sha) throw new Error(`git could not read the ${kind === 'commit' ? 'staged tree' : 'HEAD commit'} in ${cwd}`);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${unique()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ sha, exp: now + TTL_MS }), { mode: 0o600, flag: 'wx' });
+  fs.renameSync(tmp, file);
+  return { file, sha, exp: now + TTL_MS };
+}
+
+function judge(raw, expected) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: 'invalid' };
+  }
+  if (!data || typeof data.sha !== 'string' || typeof data.exp !== 'number') return { ok: false, reason: 'invalid' };
+  if (Date.now() > data.exp) return { ok: false, reason: 'expired' };
+  return expected.length && expected.every((sha) => sha === data.sha) ? { ok: true } : { ok: false, reason: 'mismatch' };
+}
+
+function expectedShas(kind, cwd, expected) {
+  if (expected) return expected;
+  const sha = currentSha(kind, cwd);
+  return sha ? [sha] : [];
+}
+
+/**
+ * @param {string[]} [expected] shas the token must match; default: the current binding.
+ * @returns {{ ok: true } | { ok: false, reason: 'none'|'expired'|'mismatch'|'invalid' }}
+ */
+function verify(kind, cwd, expected) {
+  bindingArgs(kind);
+  let file;
+  let raw;
+  try {
+    file = tokenFile(kind, cwd);
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ok: false, reason: 'none' };
+  }
+  const result = judge(raw, expectedShas(kind, cwd, expected));
+  if (result.reason === 'expired') fs.rmSync(file, { force: true });
+  return result;
+}
+
+// The rename is the lock: only one consumer can move the file away, the rest see 'none'.
+function consume(kind, cwd, expected) {
+  bindingArgs(kind);
+  let file;
+  try {
+    file = tokenFile(kind, cwd);
+  } catch {
+    return { ok: false, reason: 'none' };
+  }
+  const claim = `${file}.${unique()}.claim`;
+  try {
+    fs.renameSync(file, claim);
+  } catch {
+    return { ok: false, reason: 'none' };
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(claim, 'utf8');
+  } finally {
+    fs.rmSync(claim, { force: true });
+  }
+  return judge(raw, expectedShas(kind, cwd, expected));
+}
+
+module.exports = { mint, verify, consume, TTL_MS, KINDS: Object.keys(BINDINGS) };

package/assets/machine/hooks/lib/validate-pr-body.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+
+const { validateBodyFile } = require('./pr-template-validate.cjs');
+const { resolveTemplate } = require('./template.cjs');
+
+const file = process.argv[2];
+if (!file) {
+  process.stderr.write('Usage: node validate-pr-body.cjs <path-to-body-file>\n');
+  process.exit(2);
+}
+
+const template = resolveTemplate(process.cwd());
+const result = validateBodyFile(file, process.cwd(), template);
+if (!result.ok) {
+  process.stderr.write(`${result.reason}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`PR body OK — all ${template.sections.length} template titles present (${template.path}).\n`);
+process.exit(0);

package/assets/machine/hooks/pyle.cjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+'use strict';
+
+// Pre-exec shell gate: pyle.cjs <auto|commit|pr|push> [--adapter <id>]. Node builtins + ./lib only.
+const { spawnSync } = require('child_process');
+
+// A half-updated or broken runtime must still block git/gh: Windsurf, for one, only blocks on exit 2.
+let payload, token, repoRoot, gitEnv, gitOut, analyze, isolationProblem, redirectionProblem;
+let parseOptions, has, COMMIT, PUSH, GH_PR_CREATE, validatePrCreate, prFields;
+let loadError = null;
+try {
+  payload = require('./lib/payload.cjs');
+  token = require('./lib/token.cjs');
+  ({ repoRoot, gitEnv, gitOut } = require('./lib/paths.cjs'));
+  ({ analyze, isolationProblem, redirectionProblem } = require('./lib/shell.cjs'));
+  ({ parseOptions, has, COMMIT, PUSH, GH_PR_CREATE } = require('./lib/cli-options.cjs'));
+  ({ validatePrCreate, prFields } = require('./lib/pr-template-validate.cjs'));
+} catch (err) {
+  loadError = err;
+}
+
+const MODES = ['commit', 'pr', 'push'];
+const PROTECTED = /^(main|master)$/;
+const GATED_WORD = /commit|push|\bpr\b[\s\S]*\b(create|new)\b/i;
+const GIT_WORD = /\bgit\b|\bgh\b/;
+const DISPLAY = { commit: 'git commit', push: 'git push', pr: 'gh pr create' };
+const STAGING = ['all', 'patch', 'interactive', 'include', 'only', 'pathspec-from-file'];
+// Tool hooks time out (Copilot defaults to 30 s): probe + scan stay well under that, and a timeout denies.
+const GITLEAKS_TIMEOUT_MS = 20000;
+const GITLEAKS_PROBE_MS = 5000;
+
+const TOKEN_REASONS = {
+  commit: {
+    none: 'no commit token for this repo',
+    expired: 'the commit token expired (15 min)',
+    mismatch: 'the staged changes differ from what was reviewed',
+    invalid: 'the commit token is unreadable',
+  },
+  push: {
+    none: 'no push token for this repo',
+    expired: 'the push token expired (15 min)',
+    mismatch: 'the commit being pushed is not the one the push token was minted for',
+    invalid: 'the push token is unreadable',
+  },
+};
+
+function denyText(mode, why) {
+  if (mode === 'commit') return `exonous: git commit blocked — ${why}. Run \`exonous workflow commit\`, follow it (review), then \`exonous token commit\` and retry.`;
+  if (mode === 'push') return `exonous: git push blocked — ${why}. Run \`exonous workflow commit\`, review, then \`exonous token push\` and retry.`;
+  return `exonous: gh pr create blocked — ${why}. Run \`exonous workflow pr\`, review, then retry.`;
+}
+
+// ── Commit ───────────────────────────────────────────────────────────────────
+
+// Case-insensitive: macOS and Windows resolve .GITLEAKS.toml as the config gitleaks reads.
+const GITLEAKS_SPEC = ':(glob,icase)**/.gitleaks*';
+const isGitleaksFile = (rel) => !rel.endsWith('/') && /^\.gitleaks/i.test(rel.split('/').pop());
+
+// Tracked changes from status; untracked and ignored files one by one from ls-files, which (unlike status --ignored)
+// never collapses an ignored directory into a single entry.
+function gitleaksConfigChanged(root) {
+  const tracked = gitOut(root, ['status', '--porcelain=v1', '-z', '--untracked-files=no', '--', GITLEAKS_SPEC]);
+  const others = gitOut(root, ['ls-files', '-z', '--others', '--', GITLEAKS_SPEC]);
+  if (tracked === null || others === null) return 'git could not report the gitleaks config state';
+  // -z entries are "XY path"; a rename or copy is followed by its original path as a bare entry.
+  const changed = [];
+  const tokens = tracked.split('\0');
+  for (let i = 0; i < tokens.length; i++) {
+    if (!tokens[i]) continue;
+    changed.push(tokens[i].slice(3));
+    if (/^[RC]/.test(tokens[i])) changed.push(tokens[++i] || '');
+  }
+  const files = [...new Set([...changed, ...others.split('\0')])].filter((rel) => rel && isGitleaksFile(rel));
+  return files.length ? `the gitleaks config differs from HEAD (${files.join(', ')}); a human must commit it` : null;
+}
+
+function allowCommentStaged(root) {
+  const diff = gitOut(root, ['diff', '--cached', '-U0', '--no-color', '--no-ext-diff', '--no-textconv']);
+  if (diff === null) return 'git could not read the staged diff';
+  const added = diff.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++ '));
+  return added.some((l) => l.includes('gitleaks:allow')) ? 'a staged line adds a `gitleaks:allow` comment; a human must commit it' : null;
+}
+
+function scanStaged(cwd, warnings) {
+  const root = repoRoot(cwd);
+  const tampered = gitleaksConfigChanged(root) || allowCommentStaged(root);
+  if (tampered) return tampered;
+  const run = (args, timeout = GITLEAKS_TIMEOUT_MS) => spawnSync('gitleaks', args, { cwd: root, env: gitEnv(), encoding: 'utf8', timeout });
+  // Older gitleaks lacks the flag; the staged-diff check above covers it then.
+  const help = run(['git', '--help'], GITLEAKS_PROBE_MS);
+  const args = ['git', '--staged', '--redact', '--no-banner'];
+  if (!help.error && `${help.stdout}${help.stderr}`.includes('--ignore-gitleaks-allow')) args.push('--ignore-gitleaks-allow');
+  const res = help.error && help.error.code === 'ENOENT' ? help : run(args);
+  if (res.error && res.error.code === 'ENOENT') {
+    warnings.push('exonous: gitleaks not installed — staged content was NOT scanned for secrets (https://github.com/gitleaks/gitleaks#installing).');
+    return null;
+  }
+  if (res.status === 0 && !res.error && !res.signal) return null;
+  const detail = `${res.stdout || ''}${res.stderr || ''}`.split('\n').filter((l) => l.trim()).slice(0, 15).join('\n');
+  const how = res.error ? res.error.message : res.signal ? `killed by ${res.signal}` : `exit ${res.status}`;
+  return `gitleaks did not pass the staged changes (${how}); remove any secret and re-stage, or allowlist a false positive in a separately reviewed commit${detail ? `:\n${detail}\n` : ''}`;
+}
+
+function checkCommit(call, { warnings }) {
+  const parsed = parseOptions(call.args, COMMIT);
+  if (parsed.error) return `cannot verify its options: ${parsed.error}`;
+  if (has(parsed, 'help', 'dry-run')) return null;
+  if (has(parsed, ...STAGING) || parsed.positional.length) {
+    return 'commits that stage at commit time (-a, -i, -o, -p, pathspecs) are not covered by the token; stage with `git add`, mint the token, then run a plain `git commit`';
+  }
+  const state = token.verify('commit', call.cwd);
+  if (!state.ok) return TOKEN_REASONS.commit[state.reason];
+  const leak = scanStaged(call.cwd, warnings);
+  if (leak) return leak;
+  const claimed = token.consume('commit', call.cwd);
+  return claimed.ok ? null : TOKEN_REASONS.commit[claimed.reason];
+}
+
+// ── Push ─────────────────────────────────────────────────────────────────────
+
+function currentBranch(cwd) {
+  return (gitOut(cwd, ['branch', '--show-current']) || '').trim();
+}
+
+/** dst null = destination unresolved, treated as protected. @returns {{ force: boolean, all: boolean, pushes: { src: string | null, dst: string | null }[] }} */
+function pushPlan(parsed, cwd) {
+  const force = has(parsed, 'force', 'force-with-lease', 'force-if-includes', 'mirror');
+  let all = has(parsed, 'all', 'branches', 'mirror', 'prune');
+  const deleting = has(parsed, 'delete');
+  const refspecs = parsed.opts.some((o) => o.name === 'repo') ? parsed.positional : parsed.positional.slice(1);
+  const branch = currentBranch(cwd);
+  const upstream = () => {
+    const out = gitOut(cwd, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{push}']);
+    return out && out.trim() ? out.trim().replace(/^[^/]+\//, '') : null;
+  };
+  const short = (ref) => {
+    const name = ref.replace(/^refs\/heads\//, '');
+    return name === 'HEAD' ? branch : name;
+  };
+  if (!refspecs.length) return { force, all, pushes: all ? [] : [{ src: 'HEAD', dst: upstream() }] };
+  const pushes = refspecs.map((raw) => {
+    const spec = raw.replace(/^\+/, '');
+    if (spec.includes('*') || spec === ':') all = true;
+    if (deleting) return { src: null, dst: short(spec) };
+    const colon = spec.indexOf(':');
+    if (colon === -1) return { src: spec, dst: short(spec) };
+    const src = spec.slice(0, colon);
+    return { src: src || null, dst: short(spec.slice(colon + 1) || src) };
+  });
+  return { force: force || refspecs.some((r) => r.startsWith('+')), all, pushes };
+}
+
+function checkPush(call) {
+  const override = call.configs.find((k) => /^(push|remote|branch)\./i.test(k));
+  if (override) return `inline \`-c ${override}\` changes where the push goes`;
+  const parsed = parseOptions(call.args, PUSH);
+  if (parsed.error) return `cannot verify its options: ${parsed.error}`;
+  if (has(parsed, 'help', 'dry-run')) return null;
+  const plan = pushPlan(parsed, call.cwd);
+  const guarded = plan.pushes.find((p) => p.dst === null || PROTECTED.test(p.dst));
+  const target = plan.all ? 'every branch' : guarded && (guarded.dst || 'an upstream that cannot be resolved');
+  if (!plan.force && !target) return null;
+  const what = plan.force ? 'force-push' : `push to ${target}`;
+  if (plan.all) return `${plan.force ? 'force-push' : 'push'} touches every branch; push one branch at a time`;
+  const deleted = plan.pushes.find((p) => p.src === null);
+  if (deleted) return `deleting ${deleted.dst} needs a human`;
+  const shas = plan.pushes.map((p) => (gitOut(call.cwd, ['rev-parse', '--verify', '--end-of-options', `${p.src}^{commit}`]) || '').trim());
+  const missing = plan.pushes.find((p, i) => !shas[i]);
+  if (missing) {
+    const branch = missing.src && !/[~^:@]|^HEAD$/.test(missing.src) ? missing.src.replace(/^refs\/heads\//, '') : null;
+    return branch
+      ? `there is no local branch "${branch}" to push (${what}); push the branch you mean, e.g. \`git push origin HEAD:${missing.dst}\`, after review`
+      : `cannot resolve what ${what} would send`;
+  }
+  const state = token.verify('push', call.cwd, shas);
+  if (!state.ok) return `${what} needs review; ${TOKEN_REASONS.push[state.reason]}`;
+  const claimed = token.consume('push', call.cwd, shas);
+  return claimed.ok ? null : `${what} needs review; ${TOKEN_REASONS.push[claimed.reason]}`;
+}
+
+// ── PR ───────────────────────────────────────────────────────────────────────
+
+function checkPr(call) {
+  const parsed = parseOptions(call.args, GH_PR_CREATE);
+  if (parsed.error) return `cannot verify its options: ${parsed.error}`;
+  if (has(parsed, 'help')) return null;
+  if (parsed.positional.length) return `unexpected argument "${parsed.positional[0]}"`;
+  const result = validatePrCreate(prFields(parsed), call.cwd);
+  return result.ok ? null : result.reason.replace(/\.$/, '');
+}
+
+// ── Gate ─────────────────────────────────────────────────────────────────────
+
+/** @returns {{ allow: boolean, reason?: string, warnings: string[] }} */
+function gate(mode, { command, cwd }) {
+  const warnings = [];
+  const result = analyze(command, cwd);
+  const deny = (why) => ({ allow: false, reason: denyText(mode, why), warnings });
+  if (result.forced.length) return deny(result.forced[0]);
+  const gatedWord = GATED_WORD.test(command) || result.words.some((w) => GATED_WORD.test(w));
+  const gitWord = GIT_WORD.test(command);
+  // Computed names are fine for ordinary tools; near git/gh or with computed arguments they could be anything.
+  if (result.dynamicHeads.some((h) => !h.argsStatic) || (result.dynamicHeads.length && (gitWord || gatedWord))) return deny('a command name is computed at run time');
+  if (result.dynamicScripts.length && (gitWord || gatedWord)) return deny(result.dynamicScripts[0]);
+  const call = result.calls.find((c) => c.kind === mode);
+  if (!call) return gatedWord && result.notes.length ? deny(`${result.notes[0]} on a line that mentions a gated command`) : { allow: true, warnings };
+  const alone = isolationProblem(result, call);
+  if (alone) return deny(`run \`${DISPLAY[mode]}\` alone (optionally after one \`cd <dir> &&\`): ${alone}`);
+  if (result.notes.length) return deny(result.notes[0]);
+  const redirected = redirectionProblem(call);
+  if (redirected) return deny(redirected);
+  let reason;
+  try {
+    if (mode === 'commit') reason = checkCommit(call, { warnings });
+    else if (mode === 'push') reason = checkPush(call);
+    else reason = checkPr(call);
+  } catch (err) {
+    reason = `the gate could not verify this command (${err.message})`;
+  }
+  return reason ? deny(reason) : { allow: true, warnings };
+}
+
+/** First deny across modes wins; one hook entry can gate commit, push and pr. */
+function gateAll(modes, input) {
+  const warnings = [];
+  for (const mode of modes) {
+    const result = gate(mode, input);
+    warnings.push(...result.warnings);
+    if (!result.allow) return { ...result, warnings };
+  }
+  return { allow: true, warnings };
+}
+
+// ── Entry ────────────────────────────────────────────────────────────────────
+
+const mentionsGit = (raw) => raw.includes('git') || raw.includes('gh');
+
+function option(argv, name) {
+  const i = argv.indexOf(name);
+  return i === -1 ? null : argv[i + 1] || null;
+}
+
+function finish({ code, stdout, stderr }) {
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
+}
+
+function failClosed(adapter, raw, why) {
+  if (!mentionsGit(raw)) return finish(payload.allow(adapter, [`exonous: ${why} — command not checked.`]));
+  return finish(payload.deny(adapter, `exonous: blocked — ${why}, and the input mentions git or gh. Run the command again on its own line.`));
+}
+
+function main(argv) {
+  const mode = argv[0];
+  const adapter = option(argv, '--adapter') || 'claude';
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('error', () => failClosed(adapter, raw, 'hook input was unreadable'));
+  process.stdin.on('data', (chunk) => { raw += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      if (mode !== 'auto' && !MODES.includes(mode)) return failClosed(adapter, raw, `unknown gate mode "${mode}"`);
+      const input = payload.parse(adapter, raw);
+      if (!input) return failClosed(adapter, raw, 'hook input had no shell command');
+      const result = gateAll(mode === 'auto' ? MODES : [mode], input);
+      const warn = result.warnings.map((w) => `${w}\n`).join('');
+      if (result.allow) return finish(payload.allow(adapter, result.warnings));
+      const out = payload.deny(adapter, result.reason);
+      return finish({ ...out, stderr: `${warn}${out.stderr}` });
+    } catch (err) {
+      return failClosed(adapter, raw, `gate error (${err.message})`);
+    }
+  });
+}
+
+/** No libs available: deny anything that mentions git or gh with exit 2 (the one block signal every tool honors). */
+function loadFailure(err) {
+  let raw = '';
+  const done = () => {
+    if (!GIT_WORD.test(raw)) return;
+    process.stderr.write(`exonous: blocked — the gate could not load (${err.message}); run \`exonous install\` or \`exonous doctor\`.\n`);
+    process.exitCode = 2;
+  };
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { raw += chunk; });
+  process.stdin.on('end', done);
+  process.stdin.on('error', done);
+}
+
+if (require.main === module) {
+  if (loadError) loadFailure(loadError);
+  else {
+    try {
+      main(process.argv.slice(2));
+    } catch (err) {
+      loadFailure(err);
+    }
+  }
+}
+
+module.exports = { gate, gateAll, pushPlan };

package/assets/rules/nomos.md

@@ -0,0 +1,59 @@
+# Nomos — always on
+
+Enforced by `exonous`. Pillars, never trade a higher one for a lower one: security → architecture → model governance → quality → token economy → speed. Repo `AGENTS.md`/`CLAUDE.md` win over this file; scoped `.claude/rules/exonous/` win on coding standards.
+
+Always-on set: this file and `praxis.md` (craft discipline per change — make it work, make it right, keep the practice). Both bind every agent; neither is invoked, both are already in force.
+
+## Communication — terse
+- Cut filler, pleasantries, hedges, restated questions. Fragments ok. Shape: `[subject] [what happens] [why]. [next step].`
+- Quote code, commands, paths, errors and identifiers exactly. Answer in the user's language.
+- Levels: `terse lite|full|ultra`; off with `stop terse` / `normal mode`.
+- Full prose for security warnings, irreversible actions, or a confused user — then back to terse.
+- Normal prose for commits, PR bodies and team docs.
+
+## Engineering
+- Clarify before building: name shaky assumptions, show competing readings, push back on a simpler path.
+- No speculative wrappers, options or conversions; no abstraction before a second real caller.
+- Change only what the task needs; finish affected callers, tests, fixtures, config and exports. Match local style; clean only what you orphaned. Mention unrelated dead code.
+- Done = proven: turn the task into a runnable check (bug → failing test that passes; refactor → tests green before and after).
+- Comments: default none. Only a business rule earns one, one terse line. Any comment over 2 lines in a file you edit → cut to one line.
+
+## Context economy — locate first, read second
+- Code: `atlas` (`search_graph`, `trace_path`, `get_code_snippet`, `get_architecture`) before raw reads. No graph → read raw and say so.
+- Read whole files only to edit them; otherwise read the line range you need. Never re-read a file you just edited.
+- Project memory: `project-memory search "<q>"` in the vault, then `show` only the hits that matter.
+- Subagents get a packet (goal, paths/symbols, constraints, done-criteria), never a transcript.
+
+## Verify before done
+- Run the relevant tests, type-check and lint yourself; report real output, failures included.
+- Never weaken, skip or delete a test to pass it.
+- Same file edited 3× without a passing check → stop, restate expected vs actual, re-read, new hypothesis.
+- Keep error output until understood.
+
+## Git and PRs
+- `git commit` only via `/commit-changes`; push and `gh pr create` only via `/make-pr`. Never without an explicit request.
+- Destructive ops (`rm -rf`, `reset --hard`, force-push, clean) need explicit confirmation after inspecting what is lost.
+- PR ≤ 30 changed files; body follows `.claude/PR-TEMPLATE.md`. Conventional commits.
+
+## Agents
+Only these 12 subagents exist (plus built-ins); others are remapped or blocked by a hook. Tier is fixed per agent: sonnet plans/reviews/researches, opus writes code.
+
+| Agent | Use for |
+|---|---|
+| `exo-pm` | requirements, plans, phases, backlog |
+| `exo-cto` | architecture, ADRs, tech choices |
+| `exo-researcher` | codebase mapping, docs lookup, docs writing |
+| `exo-designer` | UX/UI direction, a11y, design review |
+| `exo-frontend` · `exo-backend` · `exo-mobile` · `exo-data-ai` · `exo-devops` · `exo-infra` | implementers by domain (backend = default) |
+| `exo-qa` | review, tests, debugging, verification gate |
+| `exo-security` | AppSec, auth, secrets, dependencies |
+
+- Inline first: one domain, few files, no independent review → main thread. Delegate for parallel, cross-domain, fresh-context review or context-flooding work.
+- Multi-step delivery runs through `/deliver` (classify → plan → execute → verify → close).
+- Independent agents go out in one message. Revision rounds continue the same agent (`SendMessage`), never a respawn.
+- Every subagent report starts with `{"status":"done|partial|blocked","cause":"…","risks":[…]}`.
+
+## Design
+- Any visible UI change: `ui-design` first, then `ui-motion` / `native-ui` / `ui-mockup` as needed; `ui-patterns` only after direction is set. Announce `Using ui-design for [purpose]`.
+- Three people open every screen: the user experience (UX), developer experience (DX), and agent experience (AX) that edits it next. Serve all three, or you're robbing one to pay another.
+- Kill any label that only exists to explain the layout. If the screen needs a caption, the screen is broken.

package/assets/rules/praxis.md

@@ -0,0 +1,38 @@
+# Praxis — always on
+
+Enforced by `exonous`. Craft discipline for every code change, in this order: make it work → make it right → keep the practice. Never reach for the second before the first is proven. Interpreted from Robert C. Martin's published principles; the gate tools named below are his.
+
+## Make it work
+
+- One decision belongs in a single place. Edit the smallest surface that settles the stated problem.
+- Before code: necessity → existing repo code → standard library/platform → installed dependency → minimum clear code.
+- Equal size: edge correctness. Preserve validation, errors, required behavior, security and accessibility. A known shortcut states its limit and reason.
+- Fix the data shape before the logic. Work that unblocks every later step goes first.
+- Tests lead: a failing test, failing for the predicted reason, then the least code that turns it green. No honest test is possible → say so, never write a hollow one.
+- A new requirement is not bolted onto the old shape. Ask what the design would have been had it always been there, then ship that in slices.
+- Two fixes that fail the same gate share a false premise. Write the premise in one sentence, name who holds it, drop it. No third attempt before that.
+- Subtract complexity before adding any. Aim at an end state you can check; a planned, reversible break mid-way is allowed.
+- Work that is not obvious at a glance earns a tool: do one case by hand, then teach the tool that case.
+
+## Architecture
+
+- Shape the domain so illegal states cannot be written, and keep a glossary of its terms. Code already clear and local stays as it is.
+- Validate at the entry point, then trust the value inside. Business rules live in pure functions.
+- Parse foreign data once, where it arrives. Never quiet the compiler to move on.
+- An operation ends in the same state run twice, or resumed after a crash halfway through.
+- Actors that need no shared mutable state each get their own. If they truly share, exactly one writes, and the structure enforces it.
+
+## Make it right
+
+- Reproduce, then fix the cause. A guard that only hides the symptom is not a fix.
+- Finish one verifiable unit and check it before opening the next.
+- A test drives the code the way a caller does and asserts what that caller sees. A test that still passes when the body returns nothing gets deleted.
+- Restructure under pinned behavior: capture what it does, change the shape, prove the behavior held.
+- Quality gates, where the stack has them wired: complexity-over-coverage score under 10 (`crapper`), structural duplication under 0.8 (`dryer`), surviving mutants killed and dead code deleted (`mutator`), dependency direction read off the map (`uml-viewer`). All four live at https://github.com/unclebob.
+
+## Practice
+
+- Log each action and the reason for it; hand that log over when the work is done.
+- Keep the main thread lean: bulk work goes to a subagent, only its summary returns.
+- Reclaim a worktree once nothing in use needs it. Uncommitted work waits for a decision, never for a cleanup.
+- Commit small and ordered; each message says why, what moved, and how it was proven. Push at the end of the line of work.