verity-framework 0.1.0 → 0.2.0

package/README.md

@@ -6,25 +6,89 @@ Verity is a CI/CD-native, GitHub-native, production-lifecycle AI software delive
 
 Most AI coding tools stop when the code is written. Verity keeps going until the software is tested, deployed, and **proven working in front of a user**. It runs a project as a sequence of specialized AI roles (architect, builder, reviewer, release operator, verifier…) that hand work off through clear contracts, with GitHub as the source of truth.
 
-> **Status: design complete, pre-implementation.** This repo currently tracks the design. Implementation begins with Verity's own *walking skeleton* — see [`docs/walking-skeleton-plan.md`](docs/walking-skeleton-plan.md).
+> **Status:** published — [`verity-framework@0.2.0`](https://www.npmjs.com/package/verity-framework) on npm. 13 role commands, the full Relay/Ledger/Gate/Shipyard/Verify engine, adapters for Claude Code + OpenCode, and the deployment-methods catalog (see below).
+
+## Install
+
+```bash
+npm i -g verity-framework
+verity install --claude       # or: --opencode
+```
+
+**Prerequisites:** a GitHub account · Node ≥16 · `git` and the GitHub CLI (`gh`) installed **and signed in** (`gh auth login` — installing `gh` is not the same as being authenticated). Preflight:
+
+```bash
+node -v && git --version && gh auth status
+```
+
+Then, in your AI assistant, start a project with `/verity:vision`.
+
+## Deployment methods
+
+**What it is.** A catalog of the places *you* can deploy to (an AWS box, a server on your LAN, a managed host…), plus a per-app record of where each project actually runs. Verity reads it when the **Architect** designs an app, so deployment becomes a *deliberate choice you make* — not an accident.
+
+**Why it exists.** Without it, an AI agent picks a host by whatever happens to be lying around — e.g. suggesting Render.com simply because a Render tool is installed in its environment. That's not a decision; it's a coincidence. The catalog makes the Architect ask *"here's what you can deploy to — which one for this app?"*, and record the answer as an [ADR](docs/commands.md). It also keeps host and credential details **out of git** while still letting a team share them safely.
+
+**Two files, two scopes:**
+
+| | Global catalog | Per-app access |
+|---|---|---|
+| **Path** | `~/.verity/deployment-methods.md` | `.verity/deploy-access.md` |
+| **Scope** | You, across *every* project | One app |
+| **Holds** | The deploy targets you *can* use | How to reach *this* app's host |
+| **Created** | At `verity install` (seeded once, never overwritten) | Written by the Architect, per app |
+| **In git?** | No — lives in your home dir | **No — gitignored.** A committed, secret-free pointer (`.verity/deploy-access.README.md`) tells teammates who lack it to ask the project admin |
+
+> 🔒 **Both files reference credential *locations*, never secrets.** Point at a key file (`~/.ssh/prod.pem`), an SSO profile, or a secret-store entry — never paste an actual key, password, or token. The real per-app file is shared out-of-band (not through the repo), so nothing sensitive ever lands in git history. (Same rule as `STATUS.md`.)
+
+**How to use it.** The global catalog is seeded at install with two worked examples (AWS EC2 over SSH, and a local-network server) — edit it to describe *your* real targets:
+
+```bash
+verity deployment list          # what targets you have (the Architect reads this)
+verity deployment show aws-ec2  # one method's details
+verity deployment path          # where the catalog file lives
+verity deployment edit          # open it in $EDITOR to add/adjust targets
+```
+
+When the Architect designs an app it runs `verity deployment list`, helps you **pick a target** (recording it as an ADR), and — if nothing real is configured yet — **asks how you want to deploy and offers suggestions**. It then sets up the per-app access file:
+
+```bash
+verity deployment init-access   # gitignore the real file + commit the "ask the admin" pointer
+verity deployment access        # is the access file present on this machine? if not, who to ask
+```
+
+…and writes `.verity/deploy-access.md` with how to reach this app's host. The **Release/Deploy Operator** (`/verity:ship`) consumes that target when it builds the deploy step.
+
+## Guides (interactive, beginner-friendly)
+
+Self-contained HTML — clone/download the repo and open them in any browser (no server or internet needed):
+
+- [`docs/verity-overview.html`](docs/verity-overview.html) — **Overview**: what Verity is, the mental model, how it works (no jargon assumed)
+- [`docs/verity-usage.html`](docs/verity-usage.html) — **Usage**: install + command-by-command recipes + pro tips (Claude Code / OpenCode toggle)
+- [`docs/verity-flows.html`](docs/verity-flows.html) — **Flows**: start-from-scratch vs add-to-an-existing-project, side by side
+- [`docs/verity-flows.drawio`](docs/verity-flows.drawio) — the flow diagram as an editable draw.io / diagrams.net file
+- [`docs/commands.md`](docs/commands.md) — **Command reference**: all 13 `/verity:*` role commands and what each one does
+- [`docs/explainer-kit.md`](docs/explainer-kit.md) — **Explainer kit**: a briefing for an AI to describe Verity to humans (podcast/deck/talk) — story, diagrams, soundbites, fact sheet
 
 ## Subsystems
 - **Relay** — role orchestration + the stream loop + dependency engine
-- **Shipyard** — CI/CD spine + Release/Deploy Operator + runtime truth (`STATUS.md`)
+- **Shipyard** — CI/CD spine + Release/Deploy Operator + deployment-methods catalog + runtime truth (`STATUS.md`)
 - **Ledger** — GitHub-derived state engine (no stale files)
 - **Gate** — review + security + the quality gates
 - **Verify** — live "observably-works" verification
 
-## Docs
+## Design docs
 - [`docs/framework-spec.md`](docs/framework-spec.md) — the build-ready architecture spec
-- [`docs/roles-spec.md`](docs/roles-spec.md) — working log + full rationale (all 14 roles)
+- [`docs/roles-spec.md`](docs/roles-spec.md) — working log + full rationale (all roles)
 - [`docs/interview-findings.md`](docs/interview-findings.md) — forensic interview of the real build that drove the design
 - [`docs/brand.md`](docs/brand.md) — naming / positioning
-- [`docs/features/helper-bot.md`](docs/features/helper-bot.md) — drop-in feature #1
 - [`docs/walking-skeleton-plan.md`](docs/walking-skeleton-plan.md) — the first implementation slice
 
 ## Package
 `verity-framework` (npm) · CLI binary: `verity` · Node ≥16 · host deps: `git`, `gh`
 
+## Contributing
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) — local setup, the test/lint checks, project layout, and conventions.
+
 ## License
 MIT

package/commands/verity/architect.md

@@ -34,24 +34,44 @@ and the walking-skeleton definition handed to /verity:plan.
    ```
    Then fill in Context / Decision / Alternatives considered / Consequences.
 
-3. **Freeze the core contracts** (wire/JWT/schema between components) — additive-only
+3. **Choose the deployment target.** Read the user's global catalog of where they can
+   deploy, and pick a target for THIS app — never assume one (don't reach for a host
+   just because its MCP/CLI happens to be installed):
+   ```bash
+   verity deployment list      # ~/.verity/deployment-methods.md (locations, not secrets)
+   ```
+   - Work with the user to choose a method; record the choice as an ADR.
+   - If `hasConfigured` is false (only the shipped examples remain), ASK how they want
+     to deploy and offer suggestions (managed PaaS, a VM over SSH, a local/LAN server…),
+     then help them add it: `verity deployment edit`.
+   - Set up the per-app access file (committed pointer + gitignore — no secrets in git):
+     ```bash
+     verity deployment init-access
+     ```
+     Then WRITE `.verity/deploy-access.md` with how to reach this app's host —
+     credential **locations** only (key files, SSO profiles, secret-store entries),
+     never raw secrets. That file is gitignored and shared out-of-band; teammates who
+     lack it are pointed at the project admin. The Release/Deploy Operator (`/verity:ship`)
+     consumes this target when it builds `deploy.sh`.
+
+4. **Freeze the core contracts** (wire/JWT/schema between components) — additive-only
    thereafter; a breaking change is a NEW contract, never an edit:
    ```bash
    verity contract new <seam-name>
    ```
 
-4. Offer the **drop-in feature catalog**. For each feature the user wants, note that
+5. Offer the **drop-in feature catalog**. For each feature the user wants, note that
    its stages will fold into the plan:
    ```bash
    verity feature list
    verity feature show <id>
    ```
 
-5. Define the **walking skeleton** (Stage 0): the thinnest end-to-end slice that
+6. Define the **walking skeleton** (Stage 0): the thinnest end-to-end slice that
    compiles, runs, passes one real test, goes green in CI, and deploys. This blocks
    all feature stages and proves the spine.
 
-6. Hand off to **/verity:plan** (Intake/Planner) to decompose the design + accepted
+7. Hand off to **/verity:plan** (Intake/Planner) to decompose the design + accepted
    features into the initial thin backlog of stages.
 
 Runtime note: if `verity` is not on PATH, use `node "$HOME/.claude/verity/bin/verity.cjs" ...`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verity-framework",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Verity — a CI/CD-native, GitHub-native, production-lifecycle AI software delivery framework.",
   "keywords": ["verity", "ai", "ci-cd", "github", "devops", "agent", "framework"],
   "author": "Sean Mahoney",

package/verity/bin/lib/deployment.cjs

@@ -0,0 +1,230 @@
+// Verity deployment methods (framework-spec.md — deployment-target feature).
+//
+// TWO scopes, deliberately separate:
+//
+//   1. GLOBAL catalog — `~/.verity/deployment-methods.md`. Your private inventory
+//      of where you CAN deploy (one per machine/user, reused across every project).
+//      Seeded at `verity install`, edited with `verity deployment edit`, read by the
+//      Architect with `verity deployment list`. Holds credential LOCATIONS, never
+//      secret values. NOT in any repo.
+//
+//   2. PER-PROJECT access file — `.verity/deploy-access.md`. Written by the Architect
+//      for ONE app: how to reach THAT app's host. Gitignored + shared out-of-band; a
+//      secret-free pointer (`.verity/deploy-access.README.md`) IS committed so a
+//      teammate without the file is told to get it from the project admin.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const identity = require('./identity.cjs');
+const { render } = require('./core.cjs');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+
+const ACCESS_FILE = '.verity/deploy-access.md'; // gitignored real file
+const ACCESS_POINTER = '.verity/deploy-access.README.md'; // committed pointer
+
+function readTemplate(name) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
+}
+
+// --- GLOBAL catalog -------------------------------------------------------
+
+// User-global, harness-independent, and OUTSIDE the install dir (which `verity
+// install` clobbers on every reinstall). VERITY_HOME / opts.home override for tests.
+function homeDir(opts = {}) {
+  return opts.home || process.env.VERITY_HOME || path.join(os.homedir(), '.verity');
+}
+
+function globalPath(opts = {}) {
+  return path.join(homeDir(opts), 'deployment-methods.md');
+}
+
+// Seed the catalog only if absent — NEVER clobber the user's edits.
+function ensure(opts = {}) {
+  const p = globalPath(opts);
+  if (fs.existsSync(p)) {
+    return { created: false, path: p };
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, readTemplate('deployment-methods.md.tmpl'));
+  return { created: true, path: p };
+}
+
+// Each method is a `## <id> — <Title>` section; `- **status:** <x>` tags it.
+// status defaults to `active` when a user adds a method without one; the shipped
+// samples are `example` so the Architect can tell "real option" from "placeholder".
+function parseMethods(text) {
+  const methods = [];
+  let cur = null;
+  for (const line of String(text).split('\n')) {
+    const head = line.match(/^##\s+([a-z0-9][a-z0-9-]*)\s+—\s+(.+)$/);
+    if (head) {
+      if (cur) {
+        methods.push(cur);
+      }
+      cur = { id: head[1], title: head[2].trim(), status: 'active', content: line };
+      continue;
+    }
+    if (cur) {
+      cur.content += `\n${line}`;
+      const st = line.match(/^-\s+\*\*status:\*\*\s*(.+)$/i);
+      if (st) {
+        cur.status = st[1].trim().toLowerCase();
+      }
+    }
+  }
+  if (cur) {
+    methods.push(cur);
+  }
+  return methods;
+}
+
+function list(opts = {}) {
+  const { path: p } = ensure(opts);
+  const methods = parseMethods(fs.readFileSync(p, 'utf8')).map((m) => ({
+    id: m.id,
+    title: m.title,
+    status: m.status,
+  }));
+  const configured = methods.filter((m) => m.status !== 'example');
+  return { path: p, methods, configured, hasConfigured: configured.length > 0 };
+}
+
+function show(id, opts = {}) {
+  if (!id) {
+    throw new Error('show requires a method id');
+  }
+  const { path: p } = ensure(opts);
+  const method = parseMethods(fs.readFileSync(p, 'utf8')).find((m) => m.id === id);
+  if (!method) {
+    throw new Error(`no such deployment method: ${id}`);
+  }
+  return method;
+}
+
+// Open the catalog in $EDITOR when run interactively; otherwise just report the
+// path (the agent edits via its own Write tool, not an interactive editor).
+function edit(opts = {}) {
+  const { path: p } = ensure(opts);
+  const editor = opts.editor || process.env.VISUAL || process.env.EDITOR || 'nano';
+  const isTTY = opts.isTTY !== undefined ? opts.isTTY : Boolean(process.stdout.isTTY);
+  if (!isTTY) {
+    return { path: p, editor, opened: false, hint: `open it: ${editor} ${p}` };
+  }
+  const run = opts.spawn || ((cmd, a) => spawnSync(cmd, a, { stdio: 'inherit' }));
+  run(editor, [p]);
+  return { path: p, editor, opened: true };
+}
+
+// --- PER-PROJECT access ---------------------------------------------------
+
+function adminFor(cwd) {
+  try {
+    const { manifest } = identity.get(cwd);
+    return manifest.owner || manifest.name || manifest.slug || '(project admin)';
+  } catch (_e) {
+    return '(project admin — lock identity first)';
+  }
+}
+
+// Add a line to the project .gitignore if not already present. Returns whether the
+// file changed (idempotent).
+function ensureIgnored(cwd, line) {
+  const gi = path.join(cwd, '.gitignore');
+  const text = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  if (text.split('\n').some((l) => l.trim() === line)) {
+    return false;
+  }
+  const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+  fs.writeFileSync(gi, `${text}${prefix}${line}\n`);
+  return true;
+}
+
+// Set up the committed pointer + gitignore for a project's access file. Does NOT
+// write the real access file — the Architect writes that with real host detail.
+function initAccess(cwd) {
+  fs.mkdirSync(path.join(cwd, '.verity'), { recursive: true });
+  const admin = adminFor(cwd);
+  const ignored = ensureIgnored(cwd, ACCESS_FILE);
+
+  const pointer = path.join(cwd, ACCESS_POINTER);
+  let pointerCreated = false;
+  if (!fs.existsSync(pointer)) {
+    fs.writeFileSync(pointer, render(readTemplate('deploy-access-pointer.md.tmpl'), { admin }));
+    pointerCreated = true;
+  }
+
+  return {
+    accessFile: ACCESS_FILE,
+    accessPath: path.join(cwd, ACCESS_FILE),
+    pointer: ACCESS_POINTER,
+    pointerCreated,
+    gitignoreUpdated: ignored,
+    admin,
+    next: `Write ${ACCESS_FILE} with how to reach this app's host — credential LOCATIONS only.`,
+  };
+}
+
+// Report whether THIS machine has the (gitignored) access file; if not, name the
+// admin to request it from.
+function accessStatus(cwd) {
+  const present = fs.existsSync(path.join(cwd, ACCESS_FILE));
+  const admin = adminFor(cwd);
+  return {
+    present,
+    accessFile: ACCESS_FILE,
+    pointerPresent: fs.existsSync(path.join(cwd, ACCESS_POINTER)),
+    admin,
+    message: present
+      ? `${ACCESS_FILE} is present.`
+      : `${ACCESS_FILE} not found — request it from the project admin: ${admin}.`,
+  };
+}
+
+function dispatch(args, flags) {
+  const verb = args[0];
+  const cwd = flags.cwd || process.cwd();
+  const opts = { home: flags.home };
+  if (verb === 'list') {
+    return list(opts);
+  }
+  if (verb === 'show') {
+    return show(args[1], opts);
+  }
+  if (verb === 'path') {
+    const p = globalPath(opts);
+    return { path: p, raw: p };
+  }
+  if (verb === 'ensure') {
+    return ensure(opts);
+  }
+  if (verb === 'edit') {
+    return edit(opts);
+  }
+  if (verb === 'init-access') {
+    return initAccess(cwd);
+  }
+  if (verb === 'access') {
+    return accessStatus(cwd);
+  }
+  throw new Error(
+    `unknown deployment verb: ${verb || '(none)'} — use list|show|path|edit|ensure|init-access|access`,
+  );
+}
+
+module.exports = {
+  homeDir,
+  globalPath,
+  ensure,
+  parseMethods,
+  list,
+  show,
+  edit,
+  initAccess,
+  accessStatus,
+  dispatch,
+  ACCESS_FILE,
+  ACCESS_POINTER,
+};

package/verity/bin/lib/install.cjs

@@ -7,8 +7,17 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const deployment = require('./deployment.cjs');
+
 const PKG_ROOT = path.join(__dirname, '..', '..', '..');
 
+// Part of setup: seed the user-global deployment-methods catalog (NEVER clobbered).
+// It lives in the user's home (~/.verity), independent of the harness target dir.
+function seedDeploymentMethods(opts) {
+  const seed = deployment.ensure({ home: opts.home });
+  return { ...seed, label: `${seed.path}${seed.created ? '' : ' (existing)'}` };
+}
+
 function commandFiles(srcCommands) {
   return fs.readdirSync(srcCommands).filter((n) => n.endsWith('.md'));
 }
@@ -38,7 +47,11 @@ function installClaude(opts = {}) {
   copyInternals(target);
   installed.push('verity/');
 
-  return { harness: 'claude', target, installed };
+  // 3. Seed the global deployment-methods catalog (setup step).
+  const deploymentMethods = seedDeploymentMethods(opts);
+  installed.push(deploymentMethods.label);
+
+  return { harness: 'claude', target, installed, deploymentMethods };
 }
 
 // --- OpenCode adapter ---
@@ -85,17 +98,20 @@ function installOpenCode(opts = {}) {
   copyInternals(target);
   installed.push('verity/');
 
-  return { harness: 'opencode', target, installed };
+  const deploymentMethods = seedDeploymentMethods(opts);
+  installed.push(deploymentMethods.label);
+
+  return { harness: 'opencode', target, installed, deploymentMethods };
 }
 
 function dispatch(_args, flags) {
   if (flags.opencode) {
-    return installOpenCode({ target: flags.target });
+    return installOpenCode({ target: flags.target, home: flags.home });
   }
   if (flags.codex || flags.gemini) {
     throw new Error('only the claude and opencode adapters are implemented so far');
   }
-  return installClaude({ target: flags.target });
+  return installClaude({ target: flags.target, home: flags.home });
 }
 
 module.exports = {

package/verity/bin/verity.cjs

@@ -26,6 +26,7 @@ const map = require('./lib/map.cjs');
 const recovery = require('./lib/recovery.cjs');
 const golive = require('./lib/golive.cjs');
 const smoke = require('./lib/smoke.cjs');
+const deployment = require('./lib/deployment.cjs');
 
 function parseArgs(argv) {
   const positional = [];
@@ -154,6 +155,9 @@ const COMMANDS = {
   smoke(rest, flags) {
     return smoke.dispatch(rest, flags);
   },
+  deployment(rest, flags) {
+    return deployment.dispatch(rest, flags);
+  },
 };
 
 function main() {

package/verity/templates/deploy-access-pointer.md.tmpl

@@ -0,0 +1,13 @@
+# Deployment access — obtain from the project admin
+
+This project deploys to a specific host. The access details live in
+`.verity/deploy-access.md`, which is **intentionally gitignored** — it is never
+committed, so no host or credential detail ever lands in git history.
+
+**If you do not have `.verity/deploy-access.md` on your machine, request it from the
+project admin: {{admin}}.** They maintain it and share it out-of-band (not through
+this repo).
+
+Maintainers: write or update the real file with `/verity:architect`, or by hand.
+Keep it to credential *locations* (key files, SSO profiles, secret-store entries) —
+never raw secrets.

package/verity/templates/deployment-methods.md.tmpl

@@ -0,0 +1,32 @@
+# Your Verity deployment methods
+
+> **Global to YOU, across every project.** This is your private inventory of the
+> places you *can* deploy to. The Architect (`/verity:architect`) reads it with
+> `verity deployment list` and works with you to choose a target for each app.
+>
+> ⚠️ **Reference credential LOCATIONS, never paste secrets.** Point at a key file,
+> an SSO profile, or a secret-store entry — never an actual key, password, or token.
+> This file lives at `~/.verity/deployment-methods.md`; it is NOT in any repo, but
+> treat it as sensitive anyway.
+>
+> Edit it any time with `verity deployment edit` (or open the path printed by
+> `verity deployment path`). Add one `## <id> — <Title>` section per method, and set
+> `- **status:** active` once it is real (the two below are `example` — replace or
+> delete them).
+
+## aws-ec2 — AWS EC2 over SSH (example — edit or delete)
+- **status:** example
+- **provider:** AWS
+- **host:** `<ec2-public-dns-or-elastic-ip>`
+- **user:** `ubuntu`
+- **access:** `ssh -i ~/.ssh/<your-key>.pem ubuntu@<host>` — key *location* only
+- **notes:** region `<e.g. us-east-1>`; the security group must allow your IP on
+  ports 22 (SSH) and 443 (HTTPS).
+
+## local-server — Local network server (example — edit or delete)
+- **status:** example
+- **provider:** self-hosted (LAN)
+- **host:** `<hostname-or-10.0.0.x>`
+- **user:** `<you>`
+- **access:** `ssh <user>@<host>` over the local network / VPN
+- **notes:** only reachable on the LAN or while connected to the VPN — not public.

package/verity/templates/gitignore.tmpl

@@ -7,3 +7,6 @@ dist/
 !.env.*.example
 # Verity's derived state cache — never authoritative (framework-spec §5)
 .verity-cache/
+# Per-app deployment access (host + credential locations) — shared out-of-band,
+# never committed. The committed pointer (.verity/deploy-access.README.md) stays.
+.verity/deploy-access.md