verity-framework 0.1.0

package/verity/bin/lib/install.cjs

@@ -0,0 +1,109 @@
+// Verity adapter / installer — the Runtime Adapter layer (framework-spec.md §4b).
+// Same role-command CONTENT, transformed into each harness's format + install
+// location. Claude Code is the reference harness; OpenCode is the second adapter.
+// Capability differences (no Task sub-agents / no hooks on OpenCode) are handled by
+// the commands' own "implement inline" fallback — the content already degrades.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PKG_ROOT = path.join(__dirname, '..', '..', '..');
+
+function commandFiles(srcCommands) {
+  return fs.readdirSync(srcCommands).filter((n) => n.endsWith('.md'));
+}
+
+function copyInternals(target) {
+  fs.cpSync(path.join(PKG_ROOT, 'verity'), path.join(target, 'verity'), { recursive: true });
+}
+
+function claudeDir(opts) {
+  return opts.target || process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function installClaude(opts = {}) {
+  const target = claudeDir(opts);
+  const installed = [];
+
+  // 1. Role command files → <target>/commands/verity/ (Claude Code uses them as-is)
+  const srcCommands = path.join(PKG_ROOT, 'commands', 'verity');
+  const destCommands = path.join(target, 'commands', 'verity');
+  fs.mkdirSync(destCommands, { recursive: true });
+  for (const name of commandFiles(srcCommands)) {
+    fs.copyFileSync(path.join(srcCommands, name), path.join(destCommands, name));
+    installed.push(path.join('commands', 'verity', name));
+  }
+
+  // 2. Engine internals → <target>/verity/ (self-contained fallback for the CLI)
+  copyInternals(target);
+  installed.push('verity/');
+
+  return { harness: 'claude', target, installed };
+}
+
+// --- OpenCode adapter ---
+
+function openCodeDir(opts) {
+  return (
+    opts.target || process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencode')
+  );
+}
+
+// Transform a Claude command .md into OpenCode's command format:
+// - frontmatter reduced to `description:` (OpenCode's per-command field; the
+//   Claude-only `allowed-tools` allowlist + `name` are dropped — OpenCode manages
+//   permissions globally and derives the command id from the filename)
+// - the Claude-specific CLI fallback path is rewritten to the OpenCode config dir
+function transformForOpenCode(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) {
+    return content;
+  }
+  const description = (m[1].match(/^description:\s*(.+)$/m) || [])[1] || '';
+  const body = m[2].replace(
+    /\$HOME\/\.claude\/verity/g,
+    '${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}/verity',
+  );
+  return `---\ndescription: ${description}\n---\n${body}`;
+}
+
+function installOpenCode(opts = {}) {
+  const target = openCodeDir(opts);
+  const installed = [];
+
+  // Role commands → <target>/command/, flattened to verity-<name>.md (invoked /verity-<name>)
+  const srcCommands = path.join(PKG_ROOT, 'commands', 'verity');
+  const destCommands = path.join(target, 'command');
+  fs.mkdirSync(destCommands, { recursive: true });
+  for (const name of commandFiles(srcCommands)) {
+    const out = `verity-${name}`;
+    const transformed = transformForOpenCode(fs.readFileSync(path.join(srcCommands, name), 'utf8'));
+    fs.writeFileSync(path.join(destCommands, out), transformed);
+    installed.push(path.join('command', out));
+  }
+
+  copyInternals(target);
+  installed.push('verity/');
+
+  return { harness: 'opencode', target, installed };
+}
+
+function dispatch(_args, flags) {
+  if (flags.opencode) {
+    return installOpenCode({ target: flags.target });
+  }
+  if (flags.codex || flags.gemini) {
+    throw new Error('only the claude and opencode adapters are implemented so far');
+  }
+  return installClaude({ target: flags.target });
+}
+
+module.exports = {
+  installClaude,
+  installOpenCode,
+  transformForOpenCode,
+  openCodeDir,
+  dispatch,
+  claudeDir,
+  PKG_ROOT,
+};

package/verity/bin/lib/ledger.cjs

@@ -0,0 +1,244 @@
+// Ledger — the state-derivation engine (framework-spec.md §5). READ-ONLY w.r.t.
+// state: it NEVER writes a state file. Integration state is DERIVED by correlating
+// local stage specs (intent) with GitHub issues/PRs/tags (progress). A transition
+// IS a GitHub act, so there is nothing to keep in sync and nothing to conflict on.
+//
+// The GitHub snapshot is injectable (opts.snapshot) so derivation is unit-testable
+// without network; the default shells out to `gh` + `git` best-effort (offline →
+// empty snapshot → everything reads as "planned", which is honest).
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+function stageDir(cwd) {
+  return path.join(cwd, 'stage-instructions');
+}
+
+function stageNum(name) {
+  const m = name.match(/^stage-(\d+)-/);
+  return m ? Number(m[1]) : 0;
+}
+
+function parseStageFile(cwd, name) {
+  const text = fs.readFileSync(path.join(stageDir(cwd), name), 'utf8');
+  const title = (text.match(/^#\s+Stage\s+\d+:\s+(.+)$/m) || [])[1] || name;
+  const type = (text.match(/\*\*Type:\*\*\s*(\w+)/) || [])[1] || 'feature';
+  const depRaw = ((text.match(/\*\*Depends on:\*\*\s*(.+)$/m) || [])[1] || 'none').trim();
+  const dependsOn =
+    depRaw.toLowerCase() === 'none'
+      ? []
+      : depRaw
+          .split(',')
+          .map((s) => Number(s.trim()))
+          .filter((n) => Number.isFinite(n) && n > 0);
+  return { number: stageNum(name), title: title.trim(), type, dependsOn, file: name };
+}
+
+function readStages(cwd) {
+  const dir = stageDir(cwd);
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(dir)
+    .filter((n) => n.endsWith('.md'))
+    .map((n) => parseStageFile(cwd, n))
+    .sort((a, b) => a.number - b.number);
+}
+
+function matchesStage(title, number) {
+  return typeof title === 'string' && title.startsWith(`[stage ${number}]`);
+}
+
+function prMatches(pr, number) {
+  return (
+    matchesStage(pr.title, number) ||
+    (typeof pr.headRefName === 'string' && pr.headRefName.startsWith(`feat/stage-${number}-`))
+  );
+}
+
+// Status precedence: merged (PR merged or issue closed) > in-review/building (PR open,
+// by CI) > claimed (issue assigned) > planned.
+function deriveStatus(stage, snapshot) {
+  const issue = (snapshot.issues || []).find((i) => matchesStage(i.title, stage.number));
+  const pr = (snapshot.prs || []).find((p) => prMatches(p, stage.number));
+  const claimed = !!(issue && Array.isArray(issue.assignees) && issue.assignees.length > 0);
+
+  let status = 'planned';
+  if (claimed) {
+    status = 'claimed';
+  }
+  if (issue && issue.state === 'CLOSED') {
+    status = 'merged';
+  }
+  if (pr) {
+    if (pr.state === 'MERGED') {
+      status = 'merged';
+    } else if (pr.state === 'OPEN') {
+      status = pr.ciGreen ? 'in-review' : 'building';
+    }
+  }
+  return {
+    number: stage.number,
+    title: stage.title,
+    type: stage.type,
+    dependsOn: stage.dependsOn,
+    status,
+    issue: issue ? issue.number : null,
+    pr: pr ? pr.number : null,
+  };
+}
+
+function unblocked(derived) {
+  const merged = new Set(derived.filter((s) => s.status === 'merged').map((s) => s.number));
+  return derived
+    .filter((s) => s.status !== 'merged' && s.dependsOn.every((d) => merged.has(d)))
+    .map((s) => s.number);
+}
+
+function semverKey(tag) {
+  return tag
+    .replace(/^v/, '')
+    .split('.')
+    .map((x) => Number.parseInt(x, 10) || 0);
+}
+
+function latestTag(tags) {
+  if (!tags || tags.length === 0) {
+    return null;
+  }
+  return [...tags]
+    .sort((a, b) => {
+      const ka = semverKey(a);
+      const kb = semverKey(b);
+      for (let i = 0; i < 3; i += 1) {
+        if ((ka[i] || 0) !== (kb[i] || 0)) {
+          return (ka[i] || 0) - (kb[i] || 0);
+        }
+      }
+      return 0;
+    })
+    .pop();
+}
+
+function project(cwd, opts = {}) {
+  const snapshot = opts.snapshot || fetchSnapshot(cwd);
+  const stages = readStages(cwd).map((s) => deriveStatus(s, snapshot));
+  return {
+    online: snapshot.online !== false,
+    release: latestTag(snapshot.tags),
+    stages,
+    next: unblocked(stages),
+  };
+}
+
+function summarize(proj) {
+  const byStatus = {};
+  for (const s of proj.stages) {
+    byStatus[s.status] = (byStatus[s.status] || 0) + 1;
+  }
+  return {
+    total: proj.stages.length,
+    byStatus,
+    release: proj.release,
+    next: proj.next,
+    online: proj.online,
+    raw: `${proj.stages.length} stages · release ${proj.release || '(none)'} · next ${JSON.stringify(proj.next)}`,
+  };
+}
+
+// --- default GitHub source (best-effort; never throws) ---
+function ghJson(args) {
+  try {
+    return JSON.parse(
+      execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }),
+    );
+  } catch {
+    return null;
+  }
+}
+
+function rollupGreen(rollup) {
+  if (!Array.isArray(rollup) || rollup.length === 0) {
+    return false;
+  }
+  const ok = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+  return rollup.every((c) => ok.has(c.conclusion || c.state));
+}
+
+function fetchSnapshot(cwd) {
+  const issues =
+    ghJson([
+      'issue',
+      'list',
+      '--state',
+      'all',
+      '--limit',
+      '300',
+      '--json',
+      'number,title,state,labels,assignees',
+    ]) || [];
+  const prsRaw =
+    ghJson([
+      'pr',
+      'list',
+      '--state',
+      'all',
+      '--limit',
+      '300',
+      '--json',
+      'number,title,state,headRefName,statusCheckRollup',
+    ]) || [];
+  const prs = prsRaw.map((p) => ({ ...p, ciGreen: rollupGreen(p.statusCheckRollup) }));
+  let tags = [];
+  try {
+    tags = execFileSync('git', ['-C', cwd, 'tag'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    tags = [];
+  }
+  const online = ghJson(['repo', 'view', '--json', 'name']) !== null;
+  return { issues, prs, tags, online };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0] || 'view';
+  const proj = project(cwd, {});
+  if (verb === 'view') {
+    return proj;
+  }
+  if (verb === 'next') {
+    return { next: proj.next, raw: JSON.stringify(proj.next) };
+  }
+  if (verb === 'summary') {
+    return summarize(proj);
+  }
+  if (verb === 'graph') {
+    return { graph: proj.stages.map((s) => ({ number: s.number, dependsOn: s.dependsOn })) };
+  }
+  if (verb === 'stage') {
+    const n = Number(args[1]);
+    const found = proj.stages.find((s) => s.number === n);
+    if (!found) {
+      throw new Error(`no stage ${args[1]}`);
+    }
+    return found;
+  }
+  throw new Error(`unknown state verb: ${verb} — use view|next|stage|summary|graph`);
+}
+
+module.exports = {
+  readStages,
+  parseStageFile,
+  deriveStatus,
+  unblocked,
+  latestTag,
+  project,
+  summarize,
+  dispatch,
+};

package/verity/bin/lib/map.cjs

@@ -0,0 +1,77 @@
+// Codebase Mapper (framework-spec.md §6, Role 14) — on-demand, generated code-STRUCTURE
+// diagram (distinct from the Planner's Gantt/schedule). Walks the directory tree and
+// emits a Mermaid graph to codebase-map.md. Never hand-maintained — regenerate anytime.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const IGNORE = new Set(['node_modules', '.git', 'dist', '.verity', '.verity-cache']);
+
+function build(cwd, maxDepth) {
+  const rootName = path.basename(path.resolve(cwd)) || 'root';
+  const nodes = [];
+  const edges = [];
+  const ids = new Map();
+  let counter = 0;
+
+  const idFor = (key, label) => {
+    if (!ids.has(key)) {
+      const id = `n${counter}`;
+      counter += 1;
+      ids.set(key, id);
+      nodes.push({ id, label });
+    }
+    return ids.get(key);
+  };
+
+  const walk = (dir, parentKey, parentId, depth) => {
+    if (depth >= maxDepth) {
+      return;
+    }
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const dirs = entries
+      .filter((e) => e.isDirectory() && !IGNORE.has(e.name))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of dirs) {
+      const childKey = `${parentKey}/${e.name}`;
+      const childId = idFor(childKey, e.name);
+      edges.push([parentId, childId]);
+      walk(path.join(dir, e.name), childKey, childId, depth + 1);
+    }
+  };
+
+  const rootId = idFor(rootName, rootName);
+  walk(cwd, rootName, rootId, 0);
+  return { nodes, edges };
+}
+
+function render({ nodes, edges }) {
+  const lines = ['# Codebase Map', '', '```mermaid', 'graph TD'];
+  for (const n of nodes) {
+    lines.push(`  ${n.id}["${n.label}"]`);
+  }
+  for (const [from, to] of edges) {
+    lines.push(`  ${from} --> ${to}`);
+  }
+  lines.push('```', '');
+  return lines.join('\n');
+}
+
+function generate(cwd, opts = {}) {
+  const maxDepth = Number(opts.depth) > 0 ? Number(opts.depth) : 2;
+  const graph = build(cwd, maxDepth);
+  const out = path.join(cwd, 'codebase-map.md');
+  fs.writeFileSync(out, render(graph));
+  return { path: out, nodes: graph.nodes.length, edges: graph.edges.length };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  return generate(cwd, { depth: flags.depth });
+}
+
+module.exports = { build, render, generate, dispatch };

package/verity/bin/lib/recovery.cjs

@@ -0,0 +1,37 @@
+// SRE (framework-spec.md §6, Role 10) — recovery-plan.md scaffold. Steady-state
+// readiness (rollback/restore drills, backup contract, intermittent-env, secret
+// rotation), distinct from the Operator's deploy act.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'recovery-plan.md.tmpl');
+
+function planPath(cwd) {
+  return path.join(cwd, 'recovery-plan.md');
+}
+
+function init(cwd, opts = {}) {
+  const p = planPath(cwd);
+  if (fs.existsSync(p) && !opts.force) {
+    return { created: false, path: p };
+  }
+  fs.writeFileSync(p, fs.readFileSync(TEMPLATE, 'utf8'));
+  return { created: true, path: p };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'init') {
+    return init(cwd, { force: Boolean(flags.force) });
+  }
+  if (verb === 'show') {
+    if (!fs.existsSync(planPath(cwd))) {
+      throw new Error('no recovery-plan.md — run `verity recovery init`');
+    }
+    return { path: planPath(cwd), content: fs.readFileSync(planPath(cwd), 'utf8') };
+  }
+  throw new Error(`unknown recovery verb: ${verb || '(none)'} — use init|show`);
+}
+
+module.exports = { planPath, init, dispatch };

package/verity/bin/lib/release.cjs

@@ -0,0 +1,131 @@
+// Release/Deploy Operator — release half (framework-spec.md §6, Role 7 / Shipyard).
+// version DERIVED from the latest tag (so the binary can't lie about its version) +
+// changelog auto-generated from Conventional Commits. Tags/commits are injectable
+// (opts.tags / opts.commits) so the logic is unit-testable without git.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const ledger = require('./ledger.cjs');
+
+function git(cwd, args) {
+  try {
+    return execFileSync('git', ['-C', cwd, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return '';
+  }
+}
+
+function gitTags(cwd) {
+  return git(cwd, ['tag']).split('\n').filter(Boolean);
+}
+
+function commitsSince(cwd, tag) {
+  const range = tag ? `${tag}..HEAD` : 'HEAD';
+  return git(cwd, ['log', range, '--pretty=%s']).split('\n').filter(Boolean);
+}
+
+function parseVersion(tag) {
+  return tag
+    .replace(/^v/, '')
+    .split('.')
+    .map((x) => Number.parseInt(x, 10) || 0);
+}
+
+function nextVersion(currentTag, bump) {
+  const [maj, min, pat] = currentTag ? parseVersion(currentTag) : [0, 0, 0];
+  if (bump === 'major') {
+    return `${(maj || 0) + 1}.0.0`;
+  }
+  if (bump === 'minor') {
+    return `${maj || 0}.${(min || 0) + 1}.0`;
+  }
+  return `${maj || 0}.${min || 0}.${(pat || 0) + 1}`;
+}
+
+const CONVENTIONAL = /^(\w+)(\([^)]*\))?(!)?:\s*(.+)$/;
+
+function changelogFrom(commits, version) {
+  const groups = { feat: [], fix: [], chore: [], other: [] };
+  for (const c of commits) {
+    const m = c.match(CONVENTIONAL);
+    if (m && groups[m[1]]) {
+      groups[m[1]].push(m[4]);
+    } else {
+      groups.other.push(c);
+    }
+  }
+  const lines = [`## ${version}`, ''];
+  const section = (title, arr) => {
+    if (arr.length > 0) {
+      lines.push(`### ${title}`);
+      for (const s of arr) {
+        lines.push(`- ${s}`);
+      }
+      lines.push('');
+    }
+  };
+  section('Features', groups.feat);
+  section('Fixes', groups.fix);
+  section('Chores', groups.chore);
+  section('Other', groups.other);
+  return lines.join('\n').trim();
+}
+
+function prependChangelog(cwd, section) {
+  const p = path.join(cwd, 'CHANGELOG.md');
+  const header = '# Changelog';
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8').replace(header, '').trim() : '';
+  const body = `${header}\n\n${section}\n\n${existing}`.trim();
+  fs.writeFileSync(p, `${body}\n`);
+}
+
+function run(cmd, args) {
+  execFileSync(cmd, args, { stdio: 'inherit' });
+}
+
+function cut(cwd, opts = {}) {
+  const tags = opts.tags || gitTags(cwd);
+  const previous = ledger.latestTag(tags);
+  const version = nextVersion(previous, opts.bump || 'patch');
+  const tag = `v${version}`;
+  const commits = opts.commits || commitsSince(cwd, previous);
+  const changelog = changelogFrom(commits, version);
+  if (!opts.dryRun) {
+    prependChangelog(cwd, changelog);
+    run('git', ['-C', cwd, 'tag', tag]);
+    if (opts.push !== false) {
+      run('git', ['-C', cwd, 'push', 'origin', tag]);
+    }
+  }
+  return { version, tag, previous, changelog, commitCount: commits.length, applied: !opts.dryRun };
+}
+
+function current(cwd) {
+  const latest = ledger.latestTag(gitTags(cwd));
+  return { latest, version: latest ? latest.replace(/^v/, '') : null, raw: latest || '' };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'current') {
+    return current(cwd);
+  }
+  if (verb === 'changelog') {
+    return cut(cwd, { bump: flags.bump, dryRun: true });
+  }
+  if (verb === 'cut') {
+    return cut(cwd, {
+      bump: flags.bump,
+      dryRun: Boolean(flags['dry-run']),
+      push: !flags['no-push'],
+    });
+  }
+  throw new Error(`unknown release verb: ${verb || '(none)'} — use cut|changelog|current`);
+}
+
+module.exports = { nextVersion, changelogFrom, cut, current, dispatch };

package/verity/bin/lib/review.cjs

@@ -0,0 +1,74 @@
+// Reviewer/Integrator (framework-spec.md §6, Role 6). The per-PR gate, adversarial
+// to the builder. With branch protection often unavailable, the Reviewer's
+// approval + confirmed-green CI IS the integration gate — so `merge` REFUSES on red.
+const { execFileSync } = require('node:child_process');
+
+const stage = require('./stage.cjs');
+const contract = require('./contract.cjs');
+const security = require('./security.cjs');
+
+// The checklist is PRE-DECLARED (acceptance conditions from the stage spec +
+// contracts to verify conformance against). The Reviewer verifies each against the
+// actual diff/source — never the PR description (the headline behavior).
+function checklist(cwd, n) {
+  const invariants = security.read(cwd);
+  return {
+    stage: n,
+    acceptance: stage.acceptanceText(cwd, n),
+    contracts: contract.list(cwd).contracts,
+    securityInvariants: invariants || '(none defined — run `verity security init`)',
+    instructions:
+      'Verify each item against the ACTUAL diff/source, not the PR description. Confirm CI is green first.',
+  };
+}
+
+// The gate, as a pure decision so it is unit-testable without network.
+function canMerge(ciGreen) {
+  return ciGreen === true;
+}
+
+function ciGreenFor(pr, cwd) {
+  try {
+    const out = execFileSync('gh', ['pr', 'view', String(pr), '--json', 'statusCheckRollup'], {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const rollup = JSON.parse(out).statusCheckRollup || [];
+    const ok = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+    return rollup.length > 0 && rollup.every((c) => ok.has(c.conclusion || c.state));
+  } catch {
+    return false;
+  }
+}
+
+function merge(cwd, pr, flags) {
+  if (flags['dry-run']) {
+    return { pr, merged: false, dryRun: true };
+  }
+  const green = flags['assume-green'] ? true : ciGreenFor(pr, cwd);
+  if (!canMerge(green)) {
+    throw new Error(
+      `refusing to merge PR #${pr}: CI is not green (the gate, even when branch protection is unavailable)`,
+    );
+  }
+  execFileSync('gh', ['pr', 'merge', String(pr), '--squash', '--delete-branch'], {
+    stdio: 'inherit',
+    cwd,
+  });
+  return { pr, merged: true };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'checklist') {
+    return checklist(cwd, Number(args[1]));
+  }
+  if (verb === 'merge') {
+    return merge(cwd, Number(args[1]), flags);
+  }
+  throw new Error(`unknown review verb: ${verb || '(none)'} — use checklist|merge`);
+}
+
+module.exports = { checklist, canMerge, ciGreenFor, merge, dispatch };