verity-framework 0.1.0

package/verity/bin/lib/scaffold.cjs

@@ -0,0 +1,66 @@
+// Verity scaffold — generate a target repo's Layer-1 governance + hygiene files
+// from the locked identity manifest (framework-spec.md §6, walking-skeleton plan §6).
+// Stack-AGNOSTIC: the emitted CI is the honest hygiene gate (secret-scan + a
+// structure check) that's genuinely green on a fresh repo. Lint/test gates are
+// added later when the Architect chooses the stack (the progressive gate).
+const fs = require('node:fs');
+const path = require('node:path');
+
+const identity = require('./identity.cjs');
+const config = require('./config.cjs');
+const { render } = require('./core.cjs');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+
+const FILES = [
+  { out: 'README.md', tmpl: 'README.md.tmpl' },
+  { out: 'LICENSE', tmpl: 'LICENSE.tmpl' },
+  { out: '.gitignore', tmpl: 'gitignore.tmpl' },
+  { out: '.github/workflows/ci.yml', tmpl: 'ci.yml.tmpl' },
+  { out: '.github/ISSUE_TEMPLATE/bug_report.yml', tmpl: 'bug_report.yml.tmpl' },
+  { out: 'STATUS.md', tmpl: 'STATUS.md.tmpl' },
+];
+
+function readTemplate(name) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+}
+
+function init(cwd, opts = {}) {
+  const { manifest } = identity.get(cwd); // throws if identity not locked yet
+  const owner = manifest.owner || manifest.name || manifest.slug;
+  const vars = {
+    name: manifest.name,
+    slug: manifest.slug,
+    owner,
+    image_prefix: manifest.image_prefix || '',
+    description: opts.description || '',
+    year: String(new Date().getFullYear()),
+  };
+
+  const created = [];
+  const skipped = [];
+  for (const file of FILES) {
+    const dest = path.join(cwd, file.out);
+    if (fs.existsSync(dest) && !opts.force) {
+      skipped.push(file.out);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, render(readTemplate(file.tmpl), vars));
+    created.push(file.out);
+  }
+
+  config.ensure(cwd);
+  return { created, skipped, slug: manifest.slug };
+}
+
+function dispatch(args, flags) {
+  const verb = args[0];
+  const cwd = flags.cwd || process.cwd();
+  if (verb === 'init') {
+    return init(cwd, { description: flags.description, force: Boolean(flags.force) });
+  }
+  throw new Error(`unknown scaffold verb: ${verb || '(none)'} — use init`);
+}
+
+module.exports = { render, init, dispatch, FILES };

package/verity/bin/lib/security.cjs

@@ -0,0 +1,44 @@
+// Security Auditor (framework-spec.md §6, Role 12). DEFINES the invariants; the
+// Reviewer ENFORCES them per-PR. The invariants live in docs/security-invariants.md
+// (committed, canonical) and are read by `review checklist`.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'security-invariants.md.tmpl');
+
+function invariantsPath(cwd) {
+  return path.join(cwd, 'docs', 'security-invariants.md');
+}
+
+function init(cwd, opts = {}) {
+  const p = invariantsPath(cwd);
+  if (fs.existsSync(p) && !opts.force) {
+    return { created: false, path: p };
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, fs.readFileSync(TEMPLATE, 'utf8'));
+  return { created: true, path: p };
+}
+
+function read(cwd) {
+  const p = invariantsPath(cwd);
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+}
+
+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') {
+    const content = read(cwd);
+    if (!content) {
+      throw new Error('no docs/security-invariants.md — run `verity security init`');
+    }
+    return { path: invariantsPath(cwd), content };
+  }
+  throw new Error(`unknown security verb: ${verb || '(none)'} — use init|show`);
+}
+
+module.exports = { invariantsPath, init, read, dispatch };

package/verity/bin/lib/smoke.cjs

@@ -0,0 +1,170 @@
+// UI-smoke "observably-works" gate (framework-spec.md §6, the N2 highest-leverage
+// gate). Drives the REAL UI and asserts BEHAVIOR — the class of failure (dead button,
+// HTMX stub, cache-stale UI) that CI and /health pass while shipping broken.
+//
+// Capability-gated (needs a headless browser): if none is available the gate DEGRADES
+// to a non-pass ("manual Handoff Tester required") — never a false green. The browser
+// driver + the capability probe are injectable so the orchestration is testable.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'smoke.json.tmpl');
+
+function specPath(cwd) {
+  return path.join(cwd, '.verity', 'smoke.json');
+}
+
+function loadSpec(cwd) {
+  const p = specPath(cwd);
+  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null;
+}
+
+function validateSpec(spec) {
+  const issues = [];
+  if (!spec || !Array.isArray(spec.flows)) {
+    issues.push('spec.flows must be an array');
+  } else {
+    spec.flows.forEach((f, i) => {
+      if (!f.name) {
+        issues.push(`flow ${i}: missing name`);
+      }
+      if (!Array.isArray(f.steps)) {
+        issues.push(`flow ${i}: steps must be an array`);
+      }
+    });
+  }
+  return { valid: issues.length === 0, issues };
+}
+
+// Translate a declarative flow into a self-contained Playwright script (pure → testable).
+function buildScript(baseUrl, flow) {
+  const lines = [
+    "const { chromium } = require('playwright');",
+    '(async () => {',
+    '  const browser = await chromium.launch();',
+    '  const page = await browser.newPage();',
+    '  try {',
+  ];
+  for (const step of flow.steps) {
+    if ('goto' in step) {
+      const url = /^https?:/.test(step.goto) ? step.goto : `${baseUrl || ''}${step.goto}`;
+      lines.push(`    await page.goto(${JSON.stringify(url)});`);
+    } else if ('click' in step) {
+      lines.push(`    await page.click(${JSON.stringify(step.click)});`);
+    } else if ('fill' in step) {
+      lines.push(
+        `    await page.fill(${JSON.stringify(step.fill)}, ${JSON.stringify(step.value || '')});`,
+      );
+    } else if ('expectSelector' in step) {
+      lines.push(
+        `    await page.waitForSelector(${JSON.stringify(step.expectSelector)}, { timeout: 8000 });`,
+      );
+    } else if ('expectText' in step) {
+      lines.push(
+        `    { const _c = await page.content(); if (!_c.includes(${JSON.stringify(step.expectText)})) throw new Error('missing text: ' + ${JSON.stringify(step.expectText)}); }`,
+      );
+    }
+  }
+  lines.push(
+    '    await browser.close();',
+    '  } catch (e) {',
+    '    await browser.close();',
+    '    console.error(e.message);',
+    '    process.exit(1);',
+    '  }',
+    '})();',
+  );
+  return lines.join('\n');
+}
+
+function defaultProbe(cwd) {
+  for (const bin of ['playwright', 'puppeteer']) {
+    if (fs.existsSync(path.join(cwd, 'node_modules', '.bin', bin))) {
+      return { available: true, tool: bin };
+    }
+  }
+  return { available: false, tool: null };
+}
+
+function playwrightDriver(cwd) {
+  return (baseUrl, flow) => {
+    execFileSync('node', ['-e', buildScript(baseUrl, flow)], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  };
+}
+
+function runSmoke(cwd, opts = {}) {
+  const spec = opts.spec || loadSpec(cwd);
+  if (!spec) {
+    throw new Error('no smoke spec — run `verity smoke init` then edit .verity/smoke.json');
+  }
+  const v = validateSpec(spec);
+  if (!v.valid) {
+    throw new Error(`invalid smoke spec: ${v.issues.join('; ')}`);
+  }
+  const probe = opts.probe ? opts.probe(cwd) : defaultProbe(cwd);
+  if (!probe.available) {
+    return {
+      gate: 'skipped',
+      verified: false,
+      reason:
+        'no headless browser available — run /verity:verify (Handoff Tester) manually. This is NOT a pass.',
+      flows: [],
+      raw: 'skipped',
+    };
+  }
+  const baseUrl = opts.baseUrl || spec.baseUrl || '';
+  const driver = opts.driver || playwrightDriver(cwd);
+  const flows = spec.flows.map((f) => {
+    try {
+      driver(baseUrl, f);
+      return { name: f.name, passed: true };
+    } catch (e) {
+      return { name: f.name, passed: false, error: e.message };
+    }
+  });
+  const verified = flows.length > 0 && flows.every((f) => f.passed);
+  return {
+    gate: verified ? 'passed' : 'failed',
+    verified,
+    reason: verified ? 'all flows passed' : 'one or more flows failed',
+    flows,
+    raw: verified ? 'passed' : 'failed',
+  };
+}
+
+function init(cwd, opts = {}) {
+  const p = specPath(cwd);
+  if (fs.existsSync(p) && !opts.force) {
+    return { created: false, path: p };
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  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] || 'run';
+  if (verb === 'init') {
+    return init(cwd, { force: Boolean(flags.force) });
+  }
+  if (verb === 'run') {
+    return runSmoke(cwd, { baseUrl: flags['base-url'] });
+  }
+  throw new Error(`unknown smoke verb: ${verb} — use init|run`);
+}
+
+module.exports = {
+  specPath,
+  loadSpec,
+  validateSpec,
+  buildScript,
+  defaultProbe,
+  runSmoke,
+  init,
+  dispatch,
+};

package/verity/bin/lib/stage.cjs

@@ -0,0 +1,180 @@
+// Stage instructions — stage-instructions/stage-N-slug.md (framework-spec.md §6,
+// Intake/Planner). This is the ONLY place stages are born. Acceptance conditions are
+// pre-filled by work-type so the two biggest interview gaps (kill-switch + UI-smoke)
+// can't be forgotten on a feature.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { generateSlug, render } = require('./core.cjs');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'stage.md.tmpl');
+const TYPES = new Set(['feature', 'bug', 'chore']);
+
+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 nextNumber(cwd) {
+  const dir = stageDir(cwd);
+  if (!fs.existsSync(dir)) {
+    return 1;
+  }
+  const nums = fs
+    .readdirSync(dir)
+    .map(stageNum)
+    .filter((n) => n > 0);
+  return nums.length > 0 ? Math.max(...nums) + 1 : 1;
+}
+
+function acceptanceFor(type) {
+  const suiteGreen = '- [ ] Existing suite stays green; CI all-green';
+  if (type === 'bug') {
+    return [
+      '- [ ] Reproduction captured + a regression test (fails before, passes after)',
+      suiteGreen,
+    ].join('\n');
+  }
+  if (type === 'chore') {
+    return ['- [ ] Clear exit-state defined (what "done" means here)', suiteGreen].join('\n');
+  }
+  // feature (default) — the two interview gaps baked in:
+  return [
+    '- [ ] Kill-switch / dark-launch flag (default OFF) for this net-new feature',
+    '- [ ] UI-smoke "observably-works" check authored for any user-facing surface',
+    '- [ ] Additive migration only (no destructive schema change)',
+    suiteGreen,
+  ].join('\n');
+}
+
+function create(cwd, title, opts = {}) {
+  if (!title) {
+    throw new Error('stage new requires a title');
+  }
+  const type = opts.type || 'feature';
+  if (!TYPES.has(type)) {
+    throw new Error(`unknown stage type "${type}" — use feature|bug|chore`);
+  }
+  const num = nextNumber(cwd);
+  const slug = generateSlug(title) || 'stage';
+  const rel = path.join('stage-instructions', `stage-${num}-${slug}.md`);
+  const file = path.join(cwd, rel);
+  fs.mkdirSync(stageDir(cwd), { recursive: true });
+  fs.writeFileSync(
+    file,
+    render(fs.readFileSync(TEMPLATE, 'utf8'), {
+      number: String(num),
+      title,
+      type,
+      depends_on: opts.dependsOn || 'none',
+      acceptance: acceptanceFor(type),
+    }),
+  );
+  // Suggested GitHub work-item the Planner opens for traceability (issue <-> stage <-> PR).
+  const issue = {
+    title: `[stage ${num}] ${title}`,
+    labels: [type, 'needs-triage'],
+    body: `Stage ${num} (${type}) — see \`${rel}\`.`,
+  };
+  return { number: num, slug, type, path: file, rel, issue };
+}
+
+function list(cwd) {
+  const dir = stageDir(cwd);
+  const stages = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((n) => n.endsWith('.md'))
+        .sort((a, b) => stageNum(a) - stageNum(b))
+    : [];
+  return { stages };
+}
+
+// --- Stage Manager acts (branch / PR) ---
+
+function findStageFile(cwd, n) {
+  const dir = stageDir(cwd);
+  if (!fs.existsSync(dir)) {
+    return null;
+  }
+  return fs.readdirSync(dir).find((name) => stageNum(name) === n) || null;
+}
+
+function branchName(cwd, n) {
+  const file = findStageFile(cwd, n);
+  if (!file) {
+    throw new Error(`no stage ${n}`);
+  }
+  const slug = file.replace(/^stage-\d+-/, '').replace(/\.md$/, '');
+  return `feat/stage-${n}-${slug}`;
+}
+
+function acceptanceText(cwd, n) {
+  const file = findStageFile(cwd, n);
+  if (!file) {
+    throw new Error(`no stage ${n}`);
+  }
+  const text = fs.readFileSync(path.join(stageDir(cwd), file), 'utf8');
+  const m = text.match(/##\s+Acceptance conditions\s*\n([\s\S]*?)(?:\n##\s|$)/);
+  return (m ? m[1] : '').trim();
+}
+
+function prSpec(cwd, n, opts = {}) {
+  const file = findStageFile(cwd, n);
+  if (!file) {
+    throw new Error(`no stage ${n}`);
+  }
+  const text = fs.readFileSync(path.join(stageDir(cwd), file), 'utf8');
+  const title = (text.match(/^#\s+Stage\s+\d+:\s+(.+)$/m) || [])[1] || `stage ${n}`;
+  const closes = opts.issue ? `\n\nCloses #${opts.issue}` : '';
+  const body = `Stage ${n}.\n\n### Acceptance conditions\n${acceptanceText(cwd, n)}${closes}`;
+  return { title: `[stage ${n}] ${title.trim()}`, body, branch: branchName(cwd, n) };
+}
+
+function run(cmd, args, cwd) {
+  execFileSync(cmd, args, { stdio: 'inherit', cwd });
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'new') {
+    return create(cwd, args[1], { type: flags.type, dependsOn: flags['depends-on'] });
+  }
+  if (verb === 'list') {
+    return list(cwd);
+  }
+  if (verb === 'branch') {
+    const name = branchName(cwd, Number(args[1]));
+    if (!flags['dry-run']) {
+      run('git', ['-C', cwd, 'checkout', '-b', name], cwd);
+    }
+    return { branch: name, created: !flags['dry-run'], raw: name };
+  }
+  if (verb === 'pr') {
+    const spec = prSpec(cwd, Number(args[1]), { issue: flags.issue });
+    if (!flags['dry-run']) {
+      run('gh', ['pr', 'create', '--title', spec.title, '--body', spec.body], cwd);
+    }
+    return { ...spec, opened: !flags['dry-run'] };
+  }
+  throw new Error(`unknown stage verb: ${verb || '(none)'} — use new|list|branch|pr`);
+}
+
+module.exports = {
+  stageDir,
+  nextNumber,
+  acceptanceFor,
+  create,
+  list,
+  findStageFile,
+  branchName,
+  acceptanceText,
+  prSpec,
+  dispatch,
+};

package/verity/bin/lib/status.cjs

@@ -0,0 +1,117 @@
+// Release/Deploy Operator — runtime-truth artifact (framework-spec.md §4.6 / D6).
+// `.verity/runtime.json` is the structured single-writer (Operator) store; STATUS.md
+// is the committed human-readable rendering of it. Records secret LOCATIONS only —
+// never values ("a map to secrets, not a copy").
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getAt, setAt, coerce } = require('./config.cjs');
+
+const DEFAULTS = {
+  version: null,
+  deployed_at: null,
+  rollback_from: null,
+  environments: {},
+  secret_locations: [],
+  notes: [],
+};
+
+function runtimePath(cwd) {
+  return path.join(cwd, '.verity', 'runtime.json');
+}
+
+function read(cwd) {
+  const p = runtimePath(cwd);
+  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : { ...DEFAULTS };
+}
+
+function write(cwd, data) {
+  fs.mkdirSync(path.dirname(runtimePath(cwd)), { recursive: true });
+  fs.writeFileSync(runtimePath(cwd), `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function section(title, items) {
+  const out = [`## ${title}`];
+  if (items && items.length > 0) {
+    for (const x of items) {
+      out.push(`- ${x}`);
+    }
+  } else {
+    out.push('- (none)');
+  }
+  out.push('');
+  return out;
+}
+
+function render(cwd, data) {
+  const envItems = Object.entries(data.environments || {}).map(
+    ([k, v]) => `**${k}:** ${typeof v === 'object' ? JSON.stringify(v) : v}`,
+  );
+  const lines = [
+    '# Status & Handoff',
+    '',
+    '> Runtime/ops truth (framework-spec §4.6). Generated from `.verity/runtime.json`',
+    '> by the Release/Deploy Operator. Secret LOCATIONS only — never values.',
+    '',
+    `**Live version:** ${data.version || '(none)'}`,
+    `**Deployed at:** ${data.deployed_at || '(not deployed)'}`,
+    `**Rollback from:** ${data.rollback_from || '(n/a)'}`,
+    '',
+    ...section('Environments', envItems),
+    ...section(
+      'Secret locations (names + on-disk locations only, never values)',
+      data.secret_locations,
+    ),
+    ...section('Coordination notes', data.notes),
+  ];
+  fs.writeFileSync(path.join(cwd, 'STATUS.md'), `${lines.join('\n').trim()}\n`);
+}
+
+function show(cwd) {
+  return { runtime: read(cwd) };
+}
+
+function set(cwd, field, rawValue) {
+  if (!field) {
+    throw new Error('status set requires a field');
+  }
+  const data = read(cwd);
+  setAt(data, field, coerce(rawValue));
+  write(cwd, data);
+  render(cwd, data);
+  return { field, value: getAt(data, field), runtime: runtimePath(cwd) };
+}
+
+function append(cwd, listField, value) {
+  const data = read(cwd);
+  const list = Array.isArray(data[listField]) ? data[listField] : [];
+  list.push(value);
+  data[listField] = list;
+  write(cwd, data);
+  render(cwd, data);
+  return { field: listField, count: list.length };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0] || 'show';
+  if (verb === 'show') {
+    return show(cwd);
+  }
+  if (verb === 'set') {
+    return set(cwd, args[1], args[2]);
+  }
+  if (verb === 'note') {
+    return append(cwd, 'notes', args.slice(1).join(' '));
+  }
+  if (verb === 'secret') {
+    return append(cwd, 'secret_locations', args.slice(1).join(' '));
+  }
+  if (verb === 'render') {
+    render(cwd, read(cwd));
+    return { rendered: path.join(cwd, 'STATUS.md') };
+  }
+  throw new Error(`unknown status verb: ${verb} — use show|set|note|secret|render`);
+}
+
+module.exports = { DEFAULTS, runtimePath, read, render, show, set, append, dispatch };