verity-framework 0.1.0

package/verity/bin/verity.cjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// Verity CLI dispatcher — the deterministic "notebook" layer (framework-spec.md §9).
+// READ-ONLY w.r.t. integration state; performs framework-conventional acts and
+// authors the few writable artifacts. JSON by default; --raw for plain values;
+// --cwd to target another project directory.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const core = require('./lib/core.cjs');
+const config = require('./lib/config.cjs');
+const identity = require('./lib/identity.cjs');
+const scaffold = require('./lib/scaffold.cjs');
+const install = require('./lib/install.cjs');
+const adr = require('./lib/adr.cjs');
+const contract = require('./lib/contract.cjs');
+const catalog = require('./lib/catalog.cjs');
+const stage = require('./lib/stage.cjs');
+const ledger = require('./lib/ledger.cjs');
+const review = require('./lib/review.cjs');
+const release = require('./lib/release.cjs');
+const status = require('./lib/status.cjs');
+const security = require('./lib/security.cjs');
+const handoff = require('./lib/handoff.cjs');
+const map = require('./lib/map.cjs');
+const recovery = require('./lib/recovery.cjs');
+const golive = require('./lib/golive.cjs');
+const smoke = require('./lib/smoke.cjs');
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--raw') {
+      flags.raw = true;
+    } else if (a === '--json') {
+      flags.json = true;
+    } else if (a === '--cwd') {
+      i += 1;
+      flags.cwd = argv[i];
+    } else if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        i += 1;
+        flags[key] = next;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function emit(result, flags) {
+  if (flags.raw) {
+    const raw = result && typeof result === 'object' && 'raw' in result ? result.raw : result;
+    let text = '';
+    if (raw === null || raw === undefined) {
+      text = '';
+    } else if (typeof raw === 'object') {
+      // A structured result with no scalar `raw` — emit compact JSON, never "[object Object]".
+      text = JSON.stringify(raw);
+    } else {
+      text = String(raw);
+    }
+    process.stdout.write(`${text}\n`);
+    return;
+  }
+  const json = JSON.stringify(result, null, 2);
+  // Large payloads spill to a tempfile (the 1.4 convention) so we never blow a
+  // consumer's buffer; the caller reads the @file: path.
+  if (json.length > 50000) {
+    const tmp = path.join(os.tmpdir(), `verity-${process.pid}-${Date.now()}.json`);
+    fs.writeFileSync(tmp, json);
+    process.stdout.write(`@file:${tmp}\n`);
+    return;
+  }
+  process.stdout.write(`${json}\n`);
+}
+
+const COMMANDS = {
+  slug(rest) {
+    const slug = core.generateSlug(rest.join(' '));
+    return { slug, validation: core.validateSlug(slug), raw: slug };
+  },
+  timestamp() {
+    const ts = new Date().toISOString();
+    return { timestamp: ts, raw: ts };
+  },
+  'verify-path'(rest, flags) {
+    const base = flags.cwd || process.cwd();
+    const target = path.resolve(base, rest[0] || '');
+    const exists = fs.existsSync(target);
+    return { path: target, exists, raw: String(exists) };
+  },
+  config(rest, flags) {
+    return config.dispatch(rest, flags);
+  },
+  identity(rest, flags) {
+    return identity.dispatch(rest, flags);
+  },
+  scaffold(rest, flags) {
+    return scaffold.dispatch(rest, flags);
+  },
+  install(rest, flags) {
+    return install.dispatch(rest, flags);
+  },
+  adr(rest, flags) {
+    return adr.dispatch(rest, flags);
+  },
+  contract(rest, flags) {
+    return contract.dispatch(rest, flags);
+  },
+  guides(rest) {
+    return catalog.guidesDispatch(rest);
+  },
+  feature(rest) {
+    return catalog.featureDispatch(rest);
+  },
+  stage(rest, flags) {
+    return stage.dispatch(rest, flags);
+  },
+  state(rest, flags) {
+    return ledger.dispatch(rest, flags);
+  },
+  review(rest, flags) {
+    return review.dispatch(rest, flags);
+  },
+  release(rest, flags) {
+    return release.dispatch(rest, flags);
+  },
+  status(rest, flags) {
+    return status.dispatch(rest, flags);
+  },
+  security(rest, flags) {
+    return security.dispatch(rest, flags);
+  },
+  handoff(rest, flags) {
+    return handoff.dispatch(rest, flags);
+  },
+  map(rest, flags) {
+    return map.dispatch(rest, flags);
+  },
+  recovery(rest, flags) {
+    return recovery.dispatch(rest, flags);
+  },
+  golive(rest, flags) {
+    return golive.dispatch(rest, flags);
+  },
+  smoke(rest, flags) {
+    return smoke.dispatch(rest, flags);
+  },
+};
+
+function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const noun = positional[0];
+
+  if (!noun || noun === 'help') {
+    emit(
+      {
+        commands: Object.keys(COMMANDS),
+        usage: 'verity <command> [args] [--raw] [--cwd <dir>]',
+      },
+      flags,
+    );
+    return;
+  }
+
+  const handler = COMMANDS[noun];
+  if (!handler) {
+    process.stderr.write(
+      `${JSON.stringify({ error: `unknown command: ${noun}`, commands: Object.keys(COMMANDS) })}\n`,
+    );
+    process.exit(1);
+  }
+
+  try {
+    emit(handler(positional.slice(1), flags), flags);
+  } catch (err) {
+    process.stderr.write(`${JSON.stringify({ error: err.message })}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/verity/design-guides/contracts-first.md

@@ -0,0 +1,32 @@
+---
+title: Contracts-First Design
+topic: architecture
+applies-to: new, existing
+---
+
+# Contracts-First Design
+
+> A **recommendation** with one hard rule: once a contract is frozen, you do not
+> break it.
+
+## The rule
+
+Define the interface contracts between components (wire format, auth, schema,
+envelope) **early**, freeze them at **v1**, and make every later change **additive**.
+A breaking change is a *new contract*, not an edit — so consumers never shift under
+each other's feet.
+
+## Why it carries production work
+
+In a real multi-stage build, a frozen contract is what lets later stages — and
+*other agents* — extend the system safely without re-litigating the core. Iteration
+becomes "additive, contract-compatible stages" instead of risky re-architecture
+against already-deployed code.
+
+## How to apply
+
+- For each seam between components, run `verity contract new <name>` and fill in
+  Exposes / Consumes / Schema.
+- Reviewer/Integrator verifies every PR against the frozen contracts.
+- If a stage genuinely needs a new seam, the Intake/Planner issues a *new* contract;
+  the existing one is never reopened.

package/verity/design-guides/features/helper-bot.md

@@ -0,0 +1,61 @@
+---
+title: In-App Help Agent
+id: helper-bot
+topic: feature
+applies-to: new, existing
+---
+
+# Drop-in Feature: In-App Help Agent
+
+> Feature #1 in the catalog. An *application* feature Verity can scaffold into the
+> app being built (NOT a framework agent). The Architect offers it; if accepted,
+> its stages fold into the Intake/Planner's backlog.
+
+## What it is
+
+A help surface inside the product: a restricted **mode of the app's own chat loop**,
+isolated by a separate, read-only tool registry. It answers user questions with real
+evidence, drafts GitHub issues (human-confirmed), and accretes a living FAQ.
+
+## Applicability / prerequisites
+
+- The app has (or will have) a chat/LLM loop and a web UI surface.
+- Structured, queryable logs (or a place to add them).
+- A GitHub repo (for issue drafting) and a CI/CD pipeline (Verity provides this).
+
+## Architectural requirements (→ ADRs)
+
+- Structured JSON logging the agent can read (`logs/app.log` or equivalent).
+- A `?` help entry point opening an isolated help session (separate window/panel).
+- A **separate, least-privilege tool registry** for help mode (security by construction).
+- A baked **read-only source snapshot** (`git archive HEAD`) so the bot reasons from
+  the *deployed* code — freshness becomes a build property, not a maintenance chore.
+
+## Reusable pattern (parameterized by the app's log schema + repo)
+
+- Help = restricted mode of the main chat loop (not a new service).
+- Caller-scoped, **non-widenable** log reads (the model can't query other users).
+- **Draft-then-confirm** external actions (issue filing is human-in-the-loop).
+- A read/append markdown FAQ as lightweight institutional memory.
+
+## Stages injected — new-app recipe
+
+1. Structured JSON logging. 2. Architecture-doc/source-snapshot wiring. 3. Help UI
+(`?` → isolated session). 4. Help-mode agent + restricted tool registry. 5. Draft
+GitHub issue endpoint (auth + label + rate-limit + redact). 6. FAQ read/append + batch job.
+
+## Stages injected — retrofit recipe
+
+1. Point the agent at existing log output (add a formatter if unstructured).
+2. Write the architecture/source grounding. 3. Drop in a floating help widget at the
+app-shell level. 4. Backend wiring (agent + GitHub hook + FAQ) without touching app code.
+
+## Conflicts / deps
+
+- Depends on the CI/CD spine (Verity) for the source-snapshot bake at release.
+- No conflicts with other catalog features.
+
+## Config knobs
+
+- `HELP_ENABLED` kill-switch (default off — ship dark, enable by flag).
+- FAQ recency/TTL weighting.

package/verity/design-guides/stack-and-topology.md

@@ -0,0 +1,38 @@
+---
+title: Stack & Topology Selection
+topic: architecture
+applies-to: new, existing
+---
+
+# Stack & Topology Selection
+
+> A **recommendation**, not a mandate. Deviate when the project justifies it — and
+> record the deviation as an ADR (`verity adr new`).
+
+## Default lean
+
+- **Boring, well-supported stacks** over novel ones. The cost of a production
+  project is operations over years, not the first week of coding.
+- **Server-rendered + progressive enhancement** before a SPA, unless the UX truly
+  needs a rich client. Fewer moving parts, fewer build steps, fewer ways to ship a
+  blank page (the "HTMX stub" class of failure).
+- **Pin dependencies and commit the lockfile** from day one — non-reproducible
+  builds are silent drift.
+
+## Topology
+
+- Start as a **modular monolith**. Split a service out only when there is a real
+  reason (independent scaling, a hard team/ownership boundary, a different runtime).
+- Every service you add multiplies the CI build matrix, the image set, and the
+  deploy surface. The slug extends per-service: `ghcr.io/<owner>/<slug>-<service>`.
+
+## Walking skeleton first
+
+Before feature work, prove a **thinnest end-to-end slice** that is green in CI,
+deployed, and UI-smoked. Wiring the real test/deploy environment first kills the
+"9 stages done before CI ever ran green" failure at the root.
+
+## When to deviate
+
+If the team's expertise, an existing codebase, or a hard requirement points
+elsewhere, choose it — and write the ADR capturing *guide said X, we chose Y, because Z*.

package/verity/templates/LICENSE.tmpl

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{owner}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/verity/templates/README.md.tmpl

@@ -0,0 +1,14 @@
+# {{name}}
+
+{{description}}
+
+> Scaffolded by [Verity](https://github.com/seanerama/verity-framework) — prompt to production, proven.
+
+## Status
+
+See [`STATUS.md`](STATUS.md) for live runtime state (deployed version, environments).
+
+## Project identity
+
+- **slug:** `{{slug}}`
+- **images:** `{{image_prefix}}`

package/verity/templates/STATUS.md.tmpl

@@ -0,0 +1,27 @@
+# {{name}} — Status & Handoff
+
+> Runtime/ops truth (framework-spec §4.6). Owned by the **Release/Deploy Operator**,
+> updated on every deploy. Records secret **locations** only — never values.
+
+**As of:** not yet deployed
+
+## TL;DR
+
+Scaffolded by Verity. Nothing deployed yet.
+
+## Live deployment
+
+- (none)
+
+## Images
+
+- prefix: `{{image_prefix}}`
+- (no releases yet)
+
+## Secrets
+
+- (none configured) — when set, list NAMES + on-disk LOCATIONS only, never values.
+
+## Coordination notes
+
+- (none)

package/verity/templates/adr.md.tmpl

@@ -0,0 +1,21 @@
+# {{number}}. {{title}}
+
+- **Status:** {{status}}
+- **Date:** {{date}}
+
+## Context
+
+(Why is this decision needed? What forces are at play?)
+
+## Decision
+
+(What did we decide?)
+
+## Alternatives considered
+
+(What did the design guide recommend? What viable alternatives existed, and why did
+we choose this one over them? — recommend-not-mandate, framework-spec §4.3.)
+
+## Consequences
+
+(Trade-offs accepted. What does this make easier or harder later?)

package/verity/templates/bug_report.yml.tmpl

@@ -0,0 +1,44 @@
+name: "Bug report"
+description: "A defect found during testing or use. Filed by an agent, operator, or user."
+title: "[bug] "
+labels: ["bug", "needs-triage"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: "One or two sentences — what's wrong."
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: "Numbered, from a known state."
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual result
+      description: "What happened instead. Include any error text verbatim."
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: "URL + client, and roughly when (UTC helps)."
+    validations:
+      required: true
+  - type: input
+    id: filed_by
+    attributes:
+      label: Filed by
+      description: "Which machine / agent / person found this."

package/verity/templates/ci.yml.tmpl

@@ -0,0 +1,36 @@
+name: CI
+# {{name}} — Verity hygiene gate (stack-agnostic).
+# Honestly green on a fresh scaffold: secret-scan + a structure check, no faked
+# pass. Lint and test gates are added when the Architect chooses the stack and the
+# walking skeleton lands (the progressive gate — framework-spec §3).
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pull-requests: read # gitleaks lists PR commits via the API on pull_request
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  structure:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Required files present
+        run: |
+          for f in README.md LICENSE; do
+            test -f "$f" || { echo "missing required file: $f"; exit 1; }
+          done
+          echo "structure ok"
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/verity/templates/contract.md.tmpl

@@ -0,0 +1,21 @@
+# Contract: {{name}}
+
+- **Status:** frozen v1
+- **Owner:** (which component owns this contract)
+
+## Exposes
+
+(The interface this provides to others — endpoints, methods, events.)
+
+## Consumes
+
+(What this needs from other components.)
+
+## Schema / wire
+
+(Concrete shapes: request/response, auth/JWT, the envelope format.)
+
+## Versioning
+
+Frozen at **v1**. Changes are **additive only** — a breaking change is a NEW
+contract, not an edit (framework-spec §4.3). Every consumer depends on this shape.

package/verity/templates/gitignore.tmpl

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.tgz
+.DS_Store
+.env
+.env.*
+!.env.*.example
+# Verity's derived state cache — never authoritative (framework-spec §5)
+.verity-cache/

package/verity/templates/handoff-brief.md.tmpl

@@ -0,0 +1,32 @@
+# Handoff — {{title}}
+
+**For:** the agent picking up `{{slug}}`. Orient via `docs/handoff/README.md` first.
+
+## What we're building
+
+(One paragraph: the feature and its boundary — what it touches, what it does not.)
+
+## Scope decisions already settled (do NOT re-litigate)
+
+> The single highest-leverage section: it lets an independent worker build the RIGHT
+> thing with no clarification round-trip. Be specific.
+
+1.
+2.
+3.
+
+## Build plan
+
+1.
+
+## Security checklist (the reviewer will verify against source)
+
+See `docs/security-invariants.md`; call out anything feature-specific here.
+
+## Out of scope (don't build now)
+
+-
+
+## Pointers
+
+`docs/handoff/README.md` → `STATUS.md` → `docs/ARCHITECTURE.md`. Frozen contracts in `contracts/`.

package/verity/templates/handoff-readme.md.tmpl

@@ -0,0 +1,21 @@
+# Handoff — agent quickstart
+
+Reading order for an agent (or person) joining this project cold — this is what makes
+"rejoin with zero setup" real (framework-spec §6, H5):
+
+1. **`STATUS.md`** — what's live right now (deployed version, environments).
+2. **`docs/ARCHITECTURE.md`** — how the system works.
+3. **The brief in this folder** for the feature you're picking up.
+4. **`verity state view`** — what's done and what's unblocked next.
+
+## The working loop
+
+```
+verity stage branch <N>     # branch for the stage
+# implement + write tests (incl. UI-smoke if user-facing)
+verity stage pr <N> --issue <M>
+# CI must be all-green
+/verity:review              # a DIFFERENT reviewer verifies against source + merges
+```
+
+You never merge your own work. Contracts are frozen — additive changes only.

package/verity/templates/recovery-plan.md.tmpl

@@ -0,0 +1,29 @@
+# Recovery Plan
+
+> Owned by the **SRE** (framework-spec §6, Role 10). Steady-state readiness — NOT the
+> deploy act (that's the Release/Deploy Operator).
+
+## Rollback
+
+- Re-pin the previous image digests and re-run the project's `deploy.sh`.
+- Safe because migrations are **additive-only** (an image rollback never strands the schema).
+- Back up the env before every deploy (`.env.bak.pre-<version>`).
+
+## Backup coverage (every persistent store listed — backed up OR acceptable-loss)
+
+- [ ] Database — backed up (PITR / scheduled)
+- [ ] (other volumes) — backed up, or **explicitly** marked acceptable-loss
+      (no silent gaps — the un-backed-up-FAQ-volume lesson)
+
+## Intermittent environment ("asleep vs incident")
+
+- If health/SSH is unreachable: is the environment deallocated on a schedule? Start it
+  first. Only treat it as an incident once confirmed up. (This is a NORMAL state.)
+
+## Secret lifecycle
+
+- [ ] Rotation schedule defined; no never-rotated/exposed credentials at go-live.
+
+## Incident response
+
+- Triage → mitigate (often: an Operator rollback) → file an issue → post-incident note.

package/verity/templates/security-invariants.md.tmpl

@@ -0,0 +1,14 @@
+# Security Invariants
+
+> Defined by the **Security Auditor**; ENFORCED by the **Reviewer** on every PR
+> (framework-spec §6). Verify each against the ACTUAL diff/source — not the PR
+> description. Edit this list as the system's threat surface grows.
+
+- [ ] Least-privilege tool/permission registries — a mode is never offered tools it doesn't need
+- [ ] Caller-scoped reads are NON-WIDENABLE (a user can only ever see their own data)
+- [ ] Path / symlink confinement on any file access
+- [ ] External or consequential actions are draft-then-confirm, never autonomous
+- [ ] No secrets in the repo, image, or source snapshot (names/locations only)
+- [ ] Migrations are additive (no destructive schema change)
+- [ ] AuthN/AuthZ enforced on every new endpoint
+- [ ] Inputs validated; outputs escaped (no injection / XSS)

package/verity/templates/smoke.json.tmpl

@@ -0,0 +1,21 @@
+{
+  "baseUrl": "http://localhost:8080",
+  "flows": [
+    {
+      "name": "home page loads and renders",
+      "steps": [
+        { "goto": "/" },
+        { "expectSelector": "body" }
+      ]
+    },
+    {
+      "name": "example: the help button actually opens help",
+      "steps": [
+        { "goto": "/" },
+        { "click": "#help-button" },
+        { "expectSelector": "#help-panel" },
+        { "expectText": "How can I help" }
+      ]
+    }
+  ]
+}

package/verity/templates/stage.md.tmpl

@@ -0,0 +1,28 @@
+# Stage {{number}}: {{title}}
+
+- **Type:** {{type}}
+- **Depends on:** {{depends_on}}
+
+## Objectives
+
+(What this stage accomplishes — the smallest shippable unit of value.)
+
+## What to build
+
+(Files, components, endpoints.)
+
+## Interface contracts
+
+- **Exposes:** (what this provides to other stages)
+- **Consumes:** (what this needs — reference frozen `contracts/`)
+
+## Testing requirements
+
+(Unit / integration / contract tests. For user-facing work, author the UI-smoke asset
+the Operator runs post-deploy.)
+
+## Acceptance conditions
+
+{{acceptance}}
+
+## Pipeline test: NO