verity-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Mahoney
+
+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/README.md

@@ -0,0 +1,30 @@
+# Verity
+
+**Prompt to production, proven.**
+
+Verity is a CI/CD-native, GitHub-native, production-lifecycle AI software delivery framework — a clean-room successor to [spec-driven-devops](https://www.npmjs.com/package/spec-driven-devops) 1.4 for projects that go *beyond MVP* into real, operated production.
+
+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).
+
+## Subsystems
+- **Relay** — role orchestration + the stream loop + dependency engine
+- **Shipyard** — CI/CD spine + Release/Deploy Operator + runtime truth (`STATUS.md`)
+- **Ledger** — GitHub-derived state engine (no stale files)
+- **Gate** — review + security + the quality gates
+- **Verify** — live "observably-works" verification
+
+## 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/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`
+
+## License
+MIT

package/commands/verity/architect.md

@@ -0,0 +1,58 @@
+---
+name: verity:architect
+description: Architect — design the stack & topology, freeze contracts, write ADRs, offer drop-in features, own the walking skeleton.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Run the Architect role: turn the locked identity + vision into a technical design —
+tech stack, service topology, frozen interface contracts, and the walking-skeleton
+plan — recording every major decision as an ADR and offering the drop-in feature
+catalog. Treat design guides as RECOMMENDATIONS, not mandates.
+
+Produces: ADRs (docs/adr/), frozen contracts (contracts/), accepted feature list,
+and the walking-skeleton definition handed to /verity:plan.
+</objective>
+
+<process>
+1. Load context: `verity identity get`. Review the relevant design guides —
+   ```bash
+   verity guides list
+   verity guides show <id>
+   ```
+   Use them to inform, not dictate. Propose viable alternatives where they fit.
+
+2. Decide the **tech stack** and **service topology** (monolith / modular-monolith /
+   multi-service). Remember: each service multiplies the CI matrix, image set, and
+   deploy surface; the slug extends per-service (`<image_prefix>-<service>`).
+   Record each significant choice as an ADR (guide said X → alternatives → chose Y, why):
+   ```bash
+   verity adr new "Choose <stack/topology decision>"
+   ```
+   Then fill in Context / Decision / Alternatives considered / Consequences.
+
+3. **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
+   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
+   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
+   features into the initial thin backlog of stages.
+
+Runtime note: if `verity` is not on PATH, use `node "$HOME/.claude/verity/bin/verity.cjs" ...`.
+</process>

package/commands/verity/build.md

@@ -0,0 +1,61 @@
+---
+name: verity:build
+description: Stage Manager — build one stage in isolation, open a green PR, hand off to review. Never merges.
+argument-hint: "<stage-number>"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Run the Stage Manager for stage $ARGUMENTS: orchestrate the build of one stage in an
+isolated context, drive its PR to green CI, and hand off to the Reviewer. "Done" = a
+green PR — this role NEVER merges (the builder must not merge its own work).
+</objective>
+
+<process>
+1. Load the stage + confirm it is unblocked:
+   ```bash
+   verity state stage $ARGUMENTS      # status + depends-on
+   verity state next                  # must include this stage (its deps are merged)
+   ```
+   If blocked, stop and report which dependency isn't merged yet.
+
+2. Create the stage branch off current `main`:
+   ```bash
+   verity stage branch $ARGUMENTS
+   ```
+
+3. Delegate the implementation to an isolated **Stage Executor** sub-agent (Task tool).
+   Pass it: the stage instruction file, the relevant frozen `contracts/`, and these rules:
+   - implement the code respecting the frozen contracts;
+   - write unit/integration/contract tests **+ the UI-smoke asset** if user-facing;
+   - add the **kill-switch flag (default OFF)** if this is a net-new feature;
+   - run the tests to green; work ONLY on the given branch — **no branch creation, no merge**;
+   - return ONLY: files changed, test results, deviations, "new contract needed?" (should be none).
+   Never paste file contents back.
+   - **Runtime fallback:** if the harness has no sub-agent/Task support, implement inline.
+
+4. Verify the executor's return against the stage's acceptance conditions
+   (`verity review checklist $ARGUMENTS` shows them): kill-switch present for features,
+   UI-smoke asset authored, additive migration only, contracts untouched. Breach → fix
+   or re-intake via `/verity:plan`.
+
+5. Push + open the PR (links the work-item; CI runs the full gate):
+   ```bash
+   verity stage pr $ARGUMENTS --issue <work-item-number>
+   ```
+
+6. Drive CI to green (executor fixes on the branch if red):
+   ```bash
+   verity state stage $ARGUMENTS      # status -> in-review when CI is green
+   ```
+   **Done = PR open + CI all-green.**
+
+7. Hand off to **/verity:review** for the merge. Do NOT merge.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/docs.md

@@ -0,0 +1,37 @@
+---
+name: verity:docs
+description: Technical Writer — public/dev docs, handoff briefs, and the architecture narrative.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+<objective>
+Run the Technical Writer. Own the human-readable layer: public/developer docs, the
+architecture narrative, and handoff briefs that let another agent pick up a feature
+cold. (ADRs belong to the Architect; runtime truth/STATUS.md to the Operator; specs
+to the Planner.)
+</objective>
+
+<process>
+1. **Public/developer docs** — keep `README.md` and `docs/` current as stages land.
+
+2. **Architecture narrative** — maintain `docs/ARCHITECTURE.md` (how it works) with a
+   "last-verified-against-commit" stamp so it can't silently drift. (Where an agent
+   reasons from code, prefer a source snapshot over prose — see the helper-bot pattern.)
+
+3. **Handoff briefs** — when a feature is delegated to another agent:
+   ```bash
+   verity handoff new <feature-slug> --title "<Feature Name>"
+   ```
+   Fill in **"Scope decisions already settled (do NOT re-litigate)"** — the highest-
+   leverage section — plus the build plan and pointers. `verity handoff` also ensures
+   `docs/handoff/README.md` (the reading-order manifest a joining agent reads first).
+
+   ```bash
+   verity handoff list
+   ```
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/golive.md

@@ -0,0 +1,32 @@
+---
+name: verity:golive
+description: Pre-go-live / first-real-data gate — force-close the "fine for now" list before real data.
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Run the BLOCKING pre-go-live gate before the project accepts real data or users
+(Security Auditor + SRE jointly). The real build accumulated a "fine until real data"
+list that never got closed — this gate forces it.
+</objective>
+
+<process>
+1. Run the checklist:
+   ```bash
+   verity golive
+   ```
+   It auto-checks what's derivable (security invariants defined, secret locations
+   recorded in STATUS, recovery plan present) and lists the manual gates.
+
+2. Resolve EVERY manual gate before go-live:
+   - Secrets rotated (no dev/exposed credentials).
+   - Throwaway accounts removed.
+   - Cross-user data isolation verified.
+   - Backup coverage for ALL persistent state.
+   - Security deep-audit sign-off (/verity:security).
+
+3. Any unresolved blocker STOPS go-live.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/map.md

@@ -0,0 +1,22 @@
+---
+name: verity:map
+description: Codebase Mapper — generate an on-demand code-structure diagram.
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Generate a structural map of the codebase (distinct from the Planner's Gantt, which is
+plan/schedule). On-demand, generated, never hand-maintained.
+</objective>
+
+<process>
+1. Generate the map:
+   ```bash
+   verity map [--depth N]     # writes codebase-map.md (a Mermaid directory/module graph)
+   ```
+2. Use it for orientation — link it from `docs/handoff/README.md` so a joining agent
+   can get its bearings fast. Regenerate anytime it drifts (it's a projection, not a record).
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/plan.md

@@ -0,0 +1,67 @@
+---
+name: verity:plan
+description: Intake/Planner — the only place stages are born. Assess a request, write the stage spec + work-item, hand to the builder.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Run the Intake/Planner: turn the architecture (Mode A — initial thin backlog) or a
+single request (Mode B — the recurring stream front door) into stage specs. This is
+the ONLY place stages are born. Reads intent; writes intent (specs/contracts/
+assessments) — never mutable progress.
+
+Produces: stage-instructions/stage-N-*.md, a new contract if a seam is introduced,
+a feature-assessment, and a linked GitHub work-item.
+</objective>
+
+<process>
+1. Load context:
+   ```bash
+   verity identity get
+   verity stage list        # existing stages
+   verity contract list     # frozen contracts (must not break)
+   verity feature list      # drop-in catalog
+   ```
+   Read the architecture/ADRs (`docs/adr/`) and any vision doc.
+
+2. Capture the request: a GitHub feature-issue, a `docs/handoff/` brief, a user ask,
+   or a catalog feature (`verity feature show <id>`).
+
+3. **VERIFY AGAINST THE LIVE CODEBASE** (mandatory anti-hallucination step). Build a
+   claim/reality table — confirm the request's assumptions hold against actual source
+   before planning. Do not build on false premises.
+
+4. Impact + contract-safety analysis. Does it need a NEW contract, or threaten a
+   frozen one? Default additive.
+   - New seam → `verity contract new <name>`.
+   - Architecture-affecting → `verity adr new "<decision>"` + confirm-gate with the user.
+
+5. Decide: ACCEPT as a stage / SPLIT into several / DEFER / REJECT.
+
+6. Write the stage spec (acceptance conditions are pre-filled by type — kill-switch +
+   UI-smoke for features, regression test for bugs, exit-state for chores):
+   ```bash
+   verity stage new "<title>" --type feature|bug|chore [--depends-on N,M]
+   ```
+   Fill Objectives / What to build / Interface contracts. Record the reasoning in
+   `feature-assessments/<slug>-assessment.md` (and an ADR if the decision is architectural).
+
+7. Register the work-item for traceability (issue ↔ stage ↔ future PR). Use the
+   suggested title/labels from `stage new`:
+   ```bash
+   gh issue create --title "[stage N] <title>" --label <type> --body "...refs stage N..."
+   ```
+   Attach a Milestone-per-release; apply an intake claim if multiple agents are active.
+
+8. Hand the stage instruction + contracts to the Stage Manager (/verity:build).
+
+Mode A (initial decomposition): run steps 3–7 as a batch over the architecture to
+emit a THIN initial backlog (not a giant upfront plan), dependency-ordered.
+
+Note: `verity state`/Gantt views arrive with the state-derivation engine (Ledger);
+until then, `verity stage list` + GitHub (issues/PRs/tags) are the source of progress.
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/review.md

@@ -0,0 +1,50 @@
+---
+name: verity:review
+description: Reviewer/Integrator — adversarially review a stage's PR against source, then merge. The integration gate.
+argument-hint: "<stage-number> [pr-number]"
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+Run the Reviewer/Integrator for stage $ARGUMENTS. You did NOT write this code — adopt
+a skeptical stance. With branch protection often unavailable, your approval +
+confirmed-green CI IS the integration gate. Verify against SOURCE, then merge.
+</objective>
+
+<process>
+1. Load the pre-declared checklist (acceptance conditions + frozen contracts):
+   ```bash
+   verity review checklist $ARGUMENTS
+   ```
+
+2. Confirm CI is actually green for the PR (the floor — do not proceed on red):
+   ```bash
+   verity state stage $ARGUMENTS      # status should be in-review (CI green)
+   ```
+
+3. **Review against the ACTUAL diff/source — never the PR description.** For each
+   acceptance condition, security invariant, and touched contract, verify it in the
+   real code (Read/Grep the diff). Build a claim → checked → pass/fail verdict.
+
+4. Scope/quality: stayed within the stage, no contract drift, no secrets committed,
+   additive migration, kill-switch default-off, UI-smoke asset present.
+
+5. Verdict:
+   - **APPROVE** → merge (squash + delete-branch; the issue auto-closes via `Closes #N`):
+     ```bash
+     verity review merge <pr-number>
+     ```
+     `merge` refuses if CI is not green. Use `--assume-green` only if you have
+     independently confirmed the checks.
+   - **REQUEST CHANGES** → hand back to /verity:build with specifics.
+   - **ESCALATE** (contract/architecture concern) → round-trip through /verity:plan
+     (new/amended contract + ADR); never edit a frozen contract from here.
+
+6. After merge, merges accrue on `main`. Do NOT deploy — the Release/Deploy Operator
+   decides when to cut a release.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/security.md

@@ -0,0 +1,36 @@
+---
+name: verity:security
+description: Security Auditor — define the invariants the Reviewer enforces, and run periodic deep audits.
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Write
+---
+<objective>
+Run the Security Auditor. DEFINE the security invariants (the Reviewer enforces them
+per-PR; the Planner bakes them into acceptance conditions) and run periodic deep,
+whole-system audits. Per-PR enforcement is the Reviewer's job — not this role's.
+</objective>
+
+<process>
+1. Establish/maintain the canonical invariants:
+   ```bash
+   verity security init     # scaffolds docs/security-invariants.md (idempotent)
+   verity security show
+   ```
+   Edit the list as the threat surface grows. These flow to `verity review checklist`.
+
+2. Per-feature consult (when /verity:plan flags a new security surface): add
+   feature-specific invariants to the brief / acceptance conditions.
+
+3. Periodic deep audit (and at the pre-go-live gate):
+   - Threat model the system's trust boundaries.
+   - Dependency CVEs (complement the release Trivy image scan with app-dep scanning).
+   - AuthN/AuthZ surface; secret handling (locations only, never values — see STATUS.md).
+   - Write findings to `docs/security-report.md`; record security decisions as ADRs.
+
+4. Feed the **pre-go-live gate** (`/verity:golive`) with a sign-off.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/ship.md

@@ -0,0 +1,67 @@
+---
+name: verity:ship
+description: Release/Deploy Operator — cut a release, deploy to staging, UI-smoke verify, promote to prod, update STATUS.md.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Run the Release/Deploy Operator (Shipyard). Turn accrued merges into a verified
+production release: cut a tag, build/scan/pin images, deploy to staging, prove it
+works with a UI-smoke, then (on confirm) promote to prod and record runtime truth.
+Continuous CD to STAGING on every merge; PROD is a deliberate cut release.
+</objective>
+
+<process>
+1. **Decide the release.** Review what's merged since the last tag:
+   ```bash
+   verity release current      # latest tag / version
+   verity release changelog    # preview the Conventional-Commits changelog
+   ```
+
+2. **Pre-flight.**
+   - Environment available? If the target is asleep/off, bring it up first
+     (intermittent environments are NORMAL). If it can't be reached, file a
+     blocked-on-human work-item and stop.
+   - `main` is green. Back up the current env/digests before changing anything.
+
+3. **Cut the release** (version is DERIVED from the tag; changelog auto-generated):
+   ```bash
+   verity release cut --bump patch|minor|major
+   ```
+   The tag triggers the project's `release.yml` (build each image once → Trivy scan →
+   emit digests). Pin those digests into the env (auto-pin; never hand-copy).
+
+4. **Deploy to STAGING** using the project's generated `deploy.sh`
+   (pull pinned digests → additive migrate → up → verify).
+
+5. **UI-smoke "observably-works" GATE.** Drive the top user flows against staging,
+   asserting *behavior* (not just `/health`):
+   ```bash
+   verity smoke run --base-url <staging-url>   # flows live in .verity/smoke.json
+   ```
+   **`verified:false` → STOP; do not promote.** If it reports `gate: skipped` (no
+   headless browser available), that is NOT a pass — run `/verity:verify` (Handoff
+   Tester) manually before promoting. (`verity smoke init` scaffolds the flows;
+   needs Playwright in the project for the automated path.)
+
+6. **Promote to PROD** — human confirm-gate by default (`verity config get prod_promote`;
+   set `auto` to skip). Same byte-identical digests. Flip any kill-switch dark→enabled
+   as a deliberate, separate step.
+
+7. **Record runtime truth** (this role owns STATUS.md):
+   ```bash
+   verity status set version <version>
+   verity status set environments.prod.digest <sha256>
+   verity status set rollback_from <previous-digest-or-backup>
+   verity status secret "<NAME> @ <on-disk location>"   # locations only, never values
+   ```
+   `STATUS.md` is regenerated from `.verity/runtime.json`.
+
+8. **On failure → rollback:** re-pin the previous digests + re-run `deploy.sh` (safe
+   because migrations are additive-only); note it in STATUS.md.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/sre.md

@@ -0,0 +1,31 @@
+---
+name: verity:sre
+description: SRE — steady-state ops: recovery/backup readiness, intermittent-env, secret rotation, monitoring.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+<objective>
+Run the SRE: keep the system healthy over time and ready to recover. The deploy ACT
+is the Release/Deploy Operator's; this is continuous steady-state + a periodic
+ops-health pass.
+</objective>
+
+<process>
+1. Recovery readiness:
+   ```bash
+   verity recovery init     # scaffolds recovery-plan.md
+   ```
+   Drill rollback (re-pin previous digests + redeploy) and restore (PITR) so neither is scary.
+2. **Backup contract:** every persistent store is backed up OR explicitly marked
+   acceptable-loss — no silent gaps.
+3. **Intermittent env:** maintain the "asleep vs incident" runbook; the Operator's
+   env-precheck consumes it.
+4. **Secret lifecycle:** track rotation; flag stale/exposed credentials (feeds /verity:golive).
+5. Monitoring/alerting + SLOs beyond `/health`. Incident response → mitigate (often an
+   Operator rollback) → file an issue → post-incident note.
+Run a periodic ops-health pass on a cadence (rotation + backup audit + a drill).
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/test.md

@@ -0,0 +1,29 @@
+---
+name: verity:test
+description: Project Tester — guardian of test honesty: real CI-like tests + bug fixes.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Task
+---
+<objective>
+Run the Project Tester: make "done = green" actually MEAN something. Own the test
+SYSTEM (harness, fixtures, the CI-like environment) — not the per-stage tests, which
+the Stage Executor writes.
+</objective>
+
+<process>
+1. The anti-D4 guarantee: ensure the suite runs reproducibly **from zero** — ephemeral
+   DB, migrate-from-empty, no shared/leaked state. Wire this at the walking skeleton so
+   the debt can't accumulate across stages.
+2. Keep the tiers **honest**: fixture isolation, no masked passes; a green suite means
+   the behavior works, not that assertions were skipped.
+3. Own pipeline-test stages and cross-cutting **test-debt** (chore). Root-cause and fix
+   bugs; land fixes as normal PRs → `/verity:review`.
+4. Use `verity state` for status. (Per-stage unit/integration/contract tests belong to
+   the Stage Executor; this role owns the system they run in.)
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/verify.md

@@ -0,0 +1,31 @@
+---
+name: verity:verify
+description: Handoff Tester — adversarial end-user testing on the LIVE app + re-verify-on-live after deploy.
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Run the Handoff Tester (the Verify subsystem). Act PURELY as an adversarial end-user
+who cannot see or edit the code — find what scripted smokes can't. This is the role
+whose loss (at consolidation) caused the hotfix treadmill; keep the wall even when one
+agent plays every role.
+</objective>
+
+<process>
+1. **Exploratory live testing:** drive the deployed app from the user's side and find
+   NEW failure modes. File structured issues:
+   ```bash
+   gh issue create --label bug --title "[bug] ..." --body "repro / expected / actual / correlation-id / filed-by"
+   ```
+2. **Re-verify-on-live after every deploy:** re-drive each prior fix/feature on the
+   LIVE app to confirm it observably works (the round-trip whose absence is the C5
+   hotfix treadmill).
+3. A found user-facing failure → the fix carries an auto-attached **regression UI-smoke**
+   (the Planner adds it as an acceptance condition) so it can never recur.
+
+Enforce the wall even single-agent: no source access while wearing this hat — test
+behavior, not the author's intent.
+
+Runtime fallback: `node "$HOME/.claude/verity/bin/verity.cjs" ...` if `verity` is off PATH.
+</process>

package/commands/verity/vision.md

@@ -0,0 +1,55 @@
+---
+name: verity:vision
+description: Vision — clarify the idea, lock the project identity, and scaffold the repo.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Run the Vision role: turn an idea into a LOCKED project identity and a scaffolded
+repo with an honest hygiene CI. (Walking-skeleton version: ideation is trimmed to
+name + one-line description; the full vision document comes later.)
+
+Produces: `.verity/identity.json` + the governance/hygiene file set, committed.
+</objective>
+
+<process>
+1. Ask the user for a project **name**, a one-line **description**, and the
+   **GitHub owner** (org or user) the repo will live under.
+
+2. Propose a slug, then validate it and check availability:
+   ```bash
+   verity slug "<name>" --raw
+   verity identity check <slug> --owner <owner>
+   ```
+   Surface any validation issues or name conflicts (npm / GitHub). Iterate with the
+   user until the slug is valid and available — or they consciously accept a conflict.
+
+3. Lock the identity (immutable — renaming later is a migration, not an edit):
+   ```bash
+   verity identity lock "<name>" <slug> --owner <owner>
+   ```
+
+4. Scaffold the repo from the locked manifest:
+   ```bash
+   verity scaffold init --description "<description>"
+   ```
+
+5. Initialize git and make the bootstrap commit (this one lands BEFORE any branch
+   protection — the only commit that does, per framework-spec §3):
+   ```bash
+   git init && git add -A && git commit -m "Initial commit — scaffolded by Verity"
+   ```
+
+6. Report what happened and tell the user how to bring the pipeline online:
+   ```bash
+   gh repo create <owner>/<slug> --source=. --push
+   ```
+   Then watch the hygiene CI run and go green. That green pipeline on a fresh repo
+   is the project's foundation — every later stage rides it.
+
+Runtime note: if `verity` is not on PATH, invoke the installed copy instead:
+`node "$HOME/.claude/verity/bin/verity.cjs" ...`
+</process>