@osfactory/har 0.9.0 → 0.11.0

package/dist/templates/agent-skills/har-maintain.md

@@ -0,0 +1,36 @@
+# Maintain / repair the har harness
+
+The `.har/` harness has drifted from the repository (stack changed, launch/verify broken, stale scripts or docs). Bring it back in sync — do every step yourself.
+
+## 1. Run maintain
+
+```bash
+har env maintain
+```
+
+This compares the harness against the current templates and repository, refreshes har-owned files, and prints an adaptation prompt (also written to `.har/ADAPT-PROMPT.md`).
+
+## 2. Perform the adaptation yourself
+
+Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` with the repository's current stack, ports, and commands. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
+
+Also check stage drift: compare the repository's current check commands (package.json scripts, Makefile, CI) against the stages registered in `.har/stages.json`. Register missing checks (`har env add-stage <id> --custom --command "..." --verification`), and remove or fix stages whose commands no longer exist. `.har/STAGES.md` documents the contract.
+
+## 3. Finalize and prove it works
+
+```bash
+har env maintain --finalize
+har env launch 1
+har env verify 1 --full
+```
+
+Fix the harness until launch and full verify pass. Tear down afterwards if the slot isn't needed (`har env teardown 1`).
+
+## 4. Commit
+
+After the user confirms:
+
+```bash
+git add .har/ AGENT.md
+git commit -m "chore: maintain har harness"
+```

package/dist/templates/agent-skills/har-wt.md

@@ -0,0 +1,47 @@
+# Work in a har worktree slot
+
+This repository uses a `.har/` harness. All code changes happen inside a **har session worktree**, never in the main checkout. Follow this flow for the current task.
+
+Use har's worktree, not your own: do not create git worktrees yourself and do not use any built-in worktree/isolation feature of your agent harness — the har slot already provides the worktree plus ports, env, and lifecycle.
+
+## 1. Pick a slot
+
+```bash
+har env status        # or ./.har/agent-cli.sh 1 status
+```
+
+- One slot ≈ one task. If slot 1 is occupied by unrelated work, use slot 2+ (limit: `agentSlots` in `.har/stages.json`).
+- Never replace an occupied slot (`--replace`/`--force`) without the user explicitly approving it.
+
+## 2. Launch — BEFORE editing any file
+
+```bash
+har env launch <id>   # or ./.har/launch.sh <id>
+```
+
+Launch creates a fresh session worktree from HEAD and prints its **work dir** (also recorded in `.har/slots/agent-<id>.json`, path like `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>`). If a previous launch failed partway, retry with `--resume` instead of replacing.
+
+## 3. Do ALL work in the work dir
+
+- `cd` into the work dir; every read-modify-write of project files happens there.
+- The main checkout must stay clean (`git status` there shows no changes from you).
+- Edits hot-reload in the running slot; use `./.har/agent-cli.sh <id> restart` if a change doesn't take.
+- Commit early and often on the session branch — teardown keeps the branch, not uncommitted work.
+- After launch, read `.har/CLAUDE.agent.md` in the worktree for slot URLs and the definition of done.
+
+## 4. Verify through the harness
+
+```bash
+har env verify <id>          # fast loop while iterating
+har env verify <id> --full   # required before declaring work done
+```
+
+Do not substitute ad-hoc test commands for harness verification. Any edit after a full verify — even one character — requires re-running it.
+
+## 5. Finish
+
+```bash
+har env complete <id>   # full verify + validation record + teardown, keeps the session branch
+```
+
+Report to the user: verification result, the session branch name (so they can push / open a PR), and the slot preview URLs if the app is running.

package/dist/templates/agent-skills/setup-har.md

@@ -0,0 +1,70 @@
+# Set up the har harness in this repository
+
+You are onboarding this repository onto har (an agent-harness orchestrator). Do every step yourself — do not ask the user to paste prompts or run commands unless a step needs their approval.
+
+## 1. Ensure the har CLI is installed
+
+```bash
+har --version
+```
+
+If missing, install it and re-check:
+
+```bash
+npm install -g @osfactory/har
+```
+
+## 2. Pick a harness profile
+
+Inspect the repository and choose the profile that matches how agents will run it:
+
+| Profile | Use when |
+|---------|----------|
+| `default` | Web app / server with a long-running process (Next.js, Rails, Django, APIs) |
+| `cli` | CLI tool, library, or npm package — no dev server to keep alive |
+| `ios` | iOS / Swift app built with xcodebuild + Simulator |
+
+Tell the user which profile you picked and why before continuing.
+
+## 3. Initialize the harness
+
+```bash
+har env init --profile <profile>   # omit --profile for default
+```
+
+If `.har/` already exists, stop and suggest `/har-maintain` instead.
+
+## 4. Perform the adaptation yourself
+
+`har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` to this repository's real stack, ports, and commands. Do not use `--auto` and do not ask the user to paste anything.
+
+## 5. Register the project's checks as stages
+
+Convert the repository's real check commands (test, lint, typecheck, whatever CI runs) into registered stages so they run in `verify --full` and are visible to every agent. Read `.har/STAGES.md` for the contract, then:
+
+```bash
+har env add-stage unit-tests --custom --kind test --command "npm test" --verification
+```
+
+- Use `--command` for one-liner checks; use `--script` when a check needs the slot's env, ports, or artifacts (then implement the scaffolded `.har/stages/<id>.sh`).
+- Rich integrations ship as templates: `har env add-stage --list`, then e.g. `har env add-stage playwright` (web) or `har env add-stage rocketsim` (iOS).
+
+## 6. Prove the harness works
+
+```bash
+har env launch 1
+har env verify 1
+```
+
+Fix the harness scripts until both pass. Then tear down or keep the slot as the user prefers (`har env teardown 1` keeps the branch).
+
+## 7. Commit
+
+After the user confirms, commit the harness:
+
+```bash
+git add .har/ AGENT.md CLAUDE.md .claude/ .cursor/ 2>/dev/null || git add .har/ AGENT.md
+git commit -m "chore: add har agent harness"
+```
+
+Optionally recommend `har hooks install` (commit gate) and `har hooks install --claude` (worktree guard for Claude Code).

package/dist/templates/agent-skills/skills.manifest.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "id": "setup-har",
+      "body": "setup-har.md",
+      "title": "Set up the har harness in this repository",
+      "claude": {
+        "frontmatter": {
+          "name": "setup-har",
+          "description": "Install the har CLI and scaffold the .har/ agent harness in this repository (init, adapt, launch, verify, commit). User-invoked onboarding.",
+          "disable-model-invocation": true,
+          "allowed-tools": "Bash(har *) Bash(npm *) Bash(git *) Read Grep Glob Edit Write"
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-setup" }
+    },
+    {
+      "id": "har-wt",
+      "body": "har-wt.md",
+      "title": "Work in a har worktree slot",
+      "claude": {
+        "frontmatter": {
+          "name": "har-wt",
+          "description": "Use BEFORE making any code change in this repository. Launches a har harness slot, which creates an isolated git session worktree — all edits must happen there, never in the main checkout — and verifies the work through the harness when done."
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-wt" }
+    },
+    {
+      "id": "har-maintain",
+      "body": "har-maintain.md",
+      "title": "Maintain / repair the har harness",
+      "claude": {
+        "frontmatter": {
+          "name": "har-maintain",
+          "description": "Repair or update the .har/ harness when it has drifted from the repository (stack changes, broken launch/verify, stale scripts). Runs har env maintain and applies the adaptation.",
+          "disable-model-invocation": true,
+          "allowed-tools": "Bash(har *) Bash(git *) Read Grep Glob Edit Write"
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-maintain" }
+    }
+  ]
+}

package/dist/templates/claude-worktree-guard.sh.template

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Managed by `har hooks install --claude` — do not edit; reinstall to update.
+# Claude Code PreToolUse guard: block file edits in the MAIN checkout of a har repo.
+# Edits belong in a har session worktree (launch one with /har-wt). Fails open on errors.
+
+[ "$HAR_SKIP_WT_GUARD" = "1" ] && exit 0
+
+input="$(cat 2>/dev/null)" || exit 0
+[ -n "$input" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+file_path="$(printf '%s' "$input" | node -e '
+let d = "";
+process.stdin.on("data", (c) => (d += c)).on("end", () => {
+  try {
+    const t = JSON.parse(d).tool_input || {};
+    process.stdout.write(t.file_path || t.notebook_path || "");
+  } catch {}
+});' 2>/dev/null)" || exit 0
+[ -n "$file_path" ] || exit 0
+
+dir="$(dirname "$file_path")"
+while [ ! -d "$dir" ] && [ "$dir" != "/" ]; do dir="$(dirname "$dir")"; done
+toplevel="$(cd "$dir" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -n "$toplevel" ] || exit 0
+
+# Only guard har-managed repos.
+[ -f "$toplevel/.har/manifest.json" ] || [ -f "$toplevel/.har/stages.json" ] || exit 0
+
+# Linked worktrees (git-dir != common-dir) are session worktrees — allowed.
+gitdir="$(cd "$toplevel" && git rev-parse --absolute-git-dir 2>/dev/null)"
+commondir="$(cd "$toplevel" && git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
+if [ -n "$gitdir" ] && [ -n "$commondir" ] && [ "$gitdir" != "$commondir" ]; then
+  exit 0
+fi
+
+echo "har: edit blocked — $file_path is in the MAIN checkout of a har-managed repo. Run /har-wt to launch a harness slot and make all edits in its session worktree. (Human bypass: HAR_SKIP_WT_GUARD=1)" >&2
+exit 2

package/dist/templates/har-boilerplate/CLAUDE.agent.md

@@ -39,13 +39,15 @@ is alive; it does not automatically mean an agent can use the app.
 
 - [ ] Full verification returns `"status": "pass"` (`har env verify ${AGENT_ID} --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh ${AGENT_ID} --full`)
 - [ ] The slot is agent-usable for this repo's documented smoke workflow, not only health-check green
-- [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — adapt specs under `tests/` for UI changes
+- [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, adapt specs under `tests/` for UI changes
 - [ ] New behavior has automated test coverage (unit and/or browser as appropriate)
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] The user got the preview URLs to test the app themselves
 - [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
 
-Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (stops before lint and browser-e2e).
+Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (smoke + health only; `--full` adds the registered verification stages).
+
+Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.
 
 ## Project commands
 

package/dist/templates/har-boilerplate/STAGES.md

@@ -0,0 +1,91 @@
+# HAR Stages — authoring guide
+
+Stages are the harness's single vocabulary for runnable checks and lifecycle
+actions. Everything — shipped templates (`playwright`, `rocketsim`), your
+project's test/lint commands, bespoke validation scripts — registers in
+`.har/stages.json` with the same schema, and agents interact with stages only
+through that registry (CLI `har env verify`, MCP `har_run_stage` /
+`har_run_verification`), never through stack-specific tooling.
+
+## The registry: `.har/stages.json`
+
+```jsonc
+{
+  "verificationStages": ["typecheck", "unit-tests", "api-health", "browser-e2e"],
+  "stages": [
+    {
+      "id": "browser-e2e",              // stable, shell-friendly slug
+      "kind": "test",                   // setup | launch | verify | test | inspect | reset | teardown | custom
+      "description": "Playwright E2E",
+      "script": "stages/browser-e2e.sh", // relative to .har/ — OR use "command"
+      "requiresAgentId": true,           // default true for test/verify/custom kinds
+      "artifacts": [{ "path": ".har/artifacts/browser-e2e", "kind": "directory" }]
+    },
+    {
+      "id": "unit-tests-fast",
+      "kind": "test",
+      "command": "npm test -- --agent {agentId}"   // {agentId} is substituted at run time
+    }
+  ]
+}
+```
+
+Optional stage fields: `cwd` (working directory), `env` (extra env vars),
+`group`, `acceptsArgs` (extra CLI args the stage accepts, e.g. `["--full"]`).
+
+## Two ways to define a stage
+
+**Command stages** — the default for simple checks (`npm test`, `swiftlint`,
+`make check`). One JSON entry, zero files:
+
+```bash
+har env add-stage unit-tests-fast --custom --kind test --command "npm test" --verification
+```
+
+**Script stages** — for anything that needs the slot's env, ports, or
+artifacts. Scaffold a contract-compliant skeleton:
+
+```bash
+har env add-stage db-integrity --custom --script --description "Check DB invariants"
+```
+
+then implement the TODO block in `.har/stages/db-integrity.sh`.
+
+## The stage script contract
+
+Every script under `.har/stages/` must:
+
+1. Source `harness.env` and `agent-slot.sh` from `.har/`.
+2. Take the agent slot id as `$1` (validate with `validate_agent_id`); extra
+   args may follow.
+3. Load the slot env via `resolve_agent_env_file` and run checks from the
+   agent's work dir (`resolve_agent_work_dir`).
+4. Write artifacts (reports, screenshots, logs) under `.har/artifacts/<id>/`.
+5. Print **only** the normalized JSON result object on stdout
+   (`status`, `stageId`, `agent_id`, `total_ms`, …); log progress to stderr.
+6. Exit with the real status code (0 = pass).
+
+The scaffolded skeleton implements all of this — replace its TODO block.
+
+## Verification membership
+
+Listing a stage id in `verificationStages` is what includes it in
+`har env verify <id> --full`. Ids that match a registered stage run via their
+script/command; ids without a registry entry (e.g. `typecheck`, `api-health`)
+are inline steps owned by `.har/verify.sh`. Lifecycle kinds
+(`setup`/`launch`/`reset`/`teardown`/`inspect`) and `verify` itself never run
+as part of verification, even if listed.
+
+## Commit gate
+
+The registry also holds the optional `commitGate` config (installed via
+`har hooks install`): `{ "commitGate": { "mode": "block" | "warn", "scope":
+"worktrees" | "all" } }` controls whether unverified change batches may be
+committed.
+
+## Shipped stage templates
+
+`har env add-stage --list` shows available templates; `har env add-stage
+playwright` (web) or `har env add-stage rocketsim` (iOS) installs one. A
+template is just packaging: it copies files, merges `package.json` fragments,
+and registers stages through the exact same registry as `--custom`.

package/dist/templates/har-boilerplate/agent-slot.sh

@@ -662,14 +662,43 @@ escape_step_output() {
   printf '%s' "$1" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const s=d.trim().split('\n').slice(0,50).join('\n');process.stdout.write(JSON.stringify(s))})" 2>/dev/null || echo '""'
 }
 
-# Run browser-e2e on verify --full when the Playwright stage template is installed.
-run_browser_e2e_if_present() {
+# Emit "<id>\t<command>" for each registered stage listed in stages.json
+# verificationStages (used by verify --full). Ids without a matching registered
+# stage are inline verify.sh steps and skipped here; lifecycle stages
+# (setup/launch/reset/teardown/inspect) and the verify stage itself never run.
+# Authoring contract: .har/STAGES.md
+list_registered_verification_stage_commands() {
   local script_dir="$1"
   local agent_id="$2"
-  local e2e="$script_dir/stages/browser-e2e.sh"
-  if [ -x "$e2e" ]; then
-    "$e2e" "$agent_id"
-  fi
+  local registry="$script_dir/stages.json"
+  [ -f "$registry" ] || return 0
+  HAR_STAGE_REGISTRY="$registry" HAR_SCRIPT_DIR="$script_dir" HAR_AGENT_ID="$agent_id" node <<'NODE' 2>/dev/null || true
+const fs = require('fs');
+const { HAR_STAGE_REGISTRY, HAR_SCRIPT_DIR, HAR_AGENT_ID } = process.env;
+const shq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+let reg;
+try { reg = JSON.parse(fs.readFileSync(HAR_STAGE_REGISTRY, 'utf8')); } catch { process.exit(0); }
+const ids = Array.isArray(reg.verificationStages) ? reg.verificationStages : [];
+const stages = Array.isArray(reg.stages) ? reg.stages : [];
+const runnable = new Set(['test', 'custom']);
+for (const id of ids) {
+  const stage = stages.find((s) => s && s.id === id);
+  if (!stage || stage.id === 'verify' || !runnable.has(stage.kind)) continue;
+  const needsAgent = stage.requiresAgentId !== false;
+  let cmd;
+  if (stage.script) {
+    cmd = shq(HAR_SCRIPT_DIR + '/' + stage.script) + (needsAgent ? ' ' + shq(HAR_AGENT_ID) : '');
+  } else if (stage.command) {
+    cmd = stage.command.split('{agentId}').join(HAR_AGENT_ID);
+  } else {
+    continue;
+  }
+  if (stage.cwd) cmd = 'cd ' + shq(stage.cwd) + ' && ' + cmd;
+  const env = stage.env && typeof stage.env === 'object' ? stage.env : {};
+  const prefix = Object.entries(env).map(([k, v]) => k + '=' + shq(v)).join(' ');
+  process.stdout.write(id + '\t' + (prefix ? prefix + ' ' : '') + cmd + '\n');
+}
+NODE
 }
 
 # Optional project-owned "agent usable" smoke beyond health.

package/dist/templates/har-boilerplate/stages/README.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# Optional per-stage scripts live here.
-# Example: ./.har/stages/browser-e2e.sh <agent-id>
+# Per-stage scripts live here (e.g. ./.har/stages/browser-e2e.sh <agent-id>).
 #
-# Register custom stages in .har/stages.json with a project-owned command:
-#   "command": "./.har/stages/browser-e2e.sh {agentId}"
+# Read .har/STAGES.md for the authoring guide: the stage script contract,
+# command vs script stages, and how verificationStages controls verify --full.
+#
+# Scaffold a new one with:
+#   har env add-stage <id> --custom --script
 
-echo "Add stage scripts under .har/stages/ and register them in stages.json." >&2
+echo "Add stage scripts under .har/stages/ and register them in stages.json — see .har/STAGES.md." >&2
 exit 1

package/dist/templates/har-boilerplate/verify.sh

@@ -5,7 +5,8 @@
 # Usage: ./.har/verify.sh <agent-id> [--full]
 #
 # Quick (default): ecosystem smoke + health only
-# Full (--full):   + conventional tests, lint, optional readiness + browser-e2e
+# Full (--full):   + conventional tests, lint, readiness, and every registered
+#                  stage in stages.json verificationStages (see .har/STAGES.md)
 # Stock steps are examples. Replace them during adaptation to match this repo.
 set -euo pipefail
 
@@ -229,7 +230,13 @@ run_http_step "api-health" "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_P
 if [ -n "$FULL" ]; then
   run_full_checks
   run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
-  run_step "browser-e2e" "run_browser_e2e_if_present \"$SCRIPT_DIR\" \"$AGENT_ID\"" || true
+  # Registered verification stages from .har/stages.json (see .har/STAGES.md).
+  # Every stage listed in verificationStages with a registered script/command
+  # runs here -- stage templates and custom stages alike.
+  while IFS=$'\t' read -r STAGE_ID STAGE_CMD; do
+    [ -n "$STAGE_ID" ] || continue
+    run_step "$STAGE_ID" "$STAGE_CMD" || true
+  done < <(list_registered_verification_stage_commands "$SCRIPT_DIR" "$AGENT_ID")
 fi
 
 # ── Output results ────────────────────────────────────────────────────────────

package/dist/templates/har-boilerplate-cli/CLAUDE.agent.md

@@ -26,13 +26,15 @@ workflow, document the required credentials/default data and wire a smoke into
 
 - [ ] Full verification returns `"status": "pass"` (`har env verify ${AGENT_ID} --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh ${AGENT_ID} --full`)
 - [ ] The slot is agent-usable for this repo's documented smoke workflow when runtime services are involved
-- [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — adapt specs under `tests/` for UI changes
+- [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, adapt specs under `tests/` for UI changes
 - [ ] New behavior has automated test coverage
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
 
 Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
 
+Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.
+
 ## Project commands
 
 ```bash

package/dist/templates/har-boilerplate-cli/STAGES.md

@@ -0,0 +1,91 @@
+# HAR Stages — authoring guide
+
+Stages are the harness's single vocabulary for runnable checks and lifecycle
+actions. Everything — shipped templates (`playwright`, `rocketsim`), your
+project's test/lint commands, bespoke validation scripts — registers in
+`.har/stages.json` with the same schema, and agents interact with stages only
+through that registry (CLI `har env verify`, MCP `har_run_stage` /
+`har_run_verification`), never through stack-specific tooling.
+
+## The registry: `.har/stages.json`
+
+```jsonc
+{
+  "verificationStages": ["typecheck", "unit-tests", "api-health", "browser-e2e"],
+  "stages": [
+    {
+      "id": "browser-e2e",              // stable, shell-friendly slug
+      "kind": "test",                   // setup | launch | verify | test | inspect | reset | teardown | custom
+      "description": "Playwright E2E",
+      "script": "stages/browser-e2e.sh", // relative to .har/ — OR use "command"
+      "requiresAgentId": true,           // default true for test/verify/custom kinds
+      "artifacts": [{ "path": ".har/artifacts/browser-e2e", "kind": "directory" }]
+    },
+    {
+      "id": "unit-tests-fast",
+      "kind": "test",
+      "command": "npm test -- --agent {agentId}"   // {agentId} is substituted at run time
+    }
+  ]
+}
+```
+
+Optional stage fields: `cwd` (working directory), `env` (extra env vars),
+`group`, `acceptsArgs` (extra CLI args the stage accepts, e.g. `["--full"]`).
+
+## Two ways to define a stage
+
+**Command stages** — the default for simple checks (`npm test`, `swiftlint`,
+`make check`). One JSON entry, zero files:
+
+```bash
+har env add-stage unit-tests-fast --custom --kind test --command "npm test" --verification
+```
+
+**Script stages** — for anything that needs the slot's env, ports, or
+artifacts. Scaffold a contract-compliant skeleton:
+
+```bash
+har env add-stage db-integrity --custom --script --description "Check DB invariants"
+```
+
+then implement the TODO block in `.har/stages/db-integrity.sh`.
+
+## The stage script contract
+
+Every script under `.har/stages/` must:
+
+1. Source `harness.env` and `agent-slot.sh` from `.har/`.
+2. Take the agent slot id as `$1` (validate with `validate_agent_id`); extra
+   args may follow.
+3. Load the slot env via `resolve_agent_env_file` and run checks from the
+   agent's work dir (`resolve_agent_work_dir`).
+4. Write artifacts (reports, screenshots, logs) under `.har/artifacts/<id>/`.
+5. Print **only** the normalized JSON result object on stdout
+   (`status`, `stageId`, `agent_id`, `total_ms`, …); log progress to stderr.
+6. Exit with the real status code (0 = pass).
+
+The scaffolded skeleton implements all of this — replace its TODO block.
+
+## Verification membership
+
+Listing a stage id in `verificationStages` is what includes it in
+`har env verify <id> --full`. Ids that match a registered stage run via their
+script/command; ids without a registry entry (e.g. `typecheck`, `api-health`)
+are inline steps owned by `.har/verify.sh`. Lifecycle kinds
+(`setup`/`launch`/`reset`/`teardown`/`inspect`) and `verify` itself never run
+as part of verification, even if listed.
+
+## Commit gate
+
+The registry also holds the optional `commitGate` config (installed via
+`har hooks install`): `{ "commitGate": { "mode": "block" | "warn", "scope":
+"worktrees" | "all" } }` controls whether unverified change batches may be
+committed.
+
+## Shipped stage templates
+
+`har env add-stage --list` shows available templates; `har env add-stage
+playwright` (web) or `har env add-stage rocketsim` (iOS) installs one. A
+template is just packaging: it copies files, merges `package.json` fragments,
+and registers stages through the exact same registry as `--custom`.

package/dist/templates/har-boilerplate-cli/agent-slot.sh

@@ -642,14 +642,43 @@ escape_step_output() {
   printf '%s' "$1" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const s=d.trim().split('\n').slice(0,50).join('\n');process.stdout.write(JSON.stringify(s))})" 2>/dev/null || echo '""'
 }
 
-# Run browser-e2e on verify --full when the Playwright stage template is installed.
-run_browser_e2e_if_present() {
+# Emit "<id>\t<command>" for each registered stage listed in stages.json
+# verificationStages (used by verify --full). Ids without a matching registered
+# stage are inline verify.sh steps and skipped here; lifecycle stages
+# (setup/launch/reset/teardown/inspect) and the verify stage itself never run.
+# Authoring contract: .har/STAGES.md
+list_registered_verification_stage_commands() {
   local script_dir="$1"
   local agent_id="$2"
-  local e2e="$script_dir/stages/browser-e2e.sh"
-  if [ -x "$e2e" ]; then
-    "$e2e" "$agent_id"
-  fi
+  local registry="$script_dir/stages.json"
+  [ -f "$registry" ] || return 0
+  HAR_STAGE_REGISTRY="$registry" HAR_SCRIPT_DIR="$script_dir" HAR_AGENT_ID="$agent_id" node <<'NODE' 2>/dev/null || true
+const fs = require('fs');
+const { HAR_STAGE_REGISTRY, HAR_SCRIPT_DIR, HAR_AGENT_ID } = process.env;
+const shq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+let reg;
+try { reg = JSON.parse(fs.readFileSync(HAR_STAGE_REGISTRY, 'utf8')); } catch { process.exit(0); }
+const ids = Array.isArray(reg.verificationStages) ? reg.verificationStages : [];
+const stages = Array.isArray(reg.stages) ? reg.stages : [];
+const runnable = new Set(['test', 'custom']);
+for (const id of ids) {
+  const stage = stages.find((s) => s && s.id === id);
+  if (!stage || stage.id === 'verify' || !runnable.has(stage.kind)) continue;
+  const needsAgent = stage.requiresAgentId !== false;
+  let cmd;
+  if (stage.script) {
+    cmd = shq(HAR_SCRIPT_DIR + '/' + stage.script) + (needsAgent ? ' ' + shq(HAR_AGENT_ID) : '');
+  } else if (stage.command) {
+    cmd = stage.command.split('{agentId}').join(HAR_AGENT_ID);
+  } else {
+    continue;
+  }
+  if (stage.cwd) cmd = 'cd ' + shq(stage.cwd) + ' && ' + cmd;
+  const env = stage.env && typeof stage.env === 'object' ? stage.env : {};
+  const prefix = Object.entries(env).map(([k, v]) => k + '=' + shq(v)).join(' ');
+  process.stdout.write(id + '\t' + (prefix ? prefix + ' ' : '') + cmd + '\n');
+}
+NODE
 }
 
 # Optional project-owned "agent usable" smoke beyond health.

package/dist/templates/har-boilerplate-cli/stages/README.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
-# Optional per-stage scripts live here.
-# Example: ./.har/stages/browser-e2e.sh <agent-id>
+# Per-stage scripts live here (e.g. ./.har/stages/browser-e2e.sh <agent-id>).
 #
-# Register custom stages in .har/stages.json with a project-owned command:
-#   "command": "./.har/stages/browser-e2e.sh {agentId}"
+# Read .har/STAGES.md for the authoring guide: the stage script contract,
+# command vs script stages, and how verificationStages controls verify --full.
+#
+# Scaffold a new one with:
+#   har env add-stage <id> --custom --script
 
-echo "Add stage scripts under .har/stages/ and register them in stages.json." >&2
+echo "Add stage scripts under .har/stages/ and register them in stages.json — see .har/STAGES.md." >&2
 exit 1

package/dist/templates/har-boilerplate-cli/verify.sh

@@ -5,7 +5,8 @@
 # Usage: ./.har/verify.sh <agent-id> [--full]
 #
 # Quick (default): ecosystem smoke — compile/import/build only
-# Full (--full):   + conventional tests, lint, optional readiness + browser-e2e
+# Full (--full):   + conventional tests, lint, readiness, and every registered
+#                  stage in stages.json verificationStages (see .har/STAGES.md)
 # Stock steps are examples. Replace them during adaptation to match this repo.
 set -euo pipefail
 
@@ -185,7 +186,13 @@ run_quick_smoke || { [ -z "$FULL" ] && true; }
 if [ -n "$FULL" ]; then
   run_full_checks
   run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
-  run_step "browser-e2e" "run_browser_e2e_if_present \"$SCRIPT_DIR\" \"$AGENT_ID\"" || true
+  # Registered verification stages from .har/stages.json (see .har/STAGES.md).
+  # Every stage listed in verificationStages with a registered script/command
+  # runs here -- stage templates and custom stages alike.
+  while IFS=$'\t' read -r STAGE_ID STAGE_CMD; do
+    [ -n "$STAGE_ID" ] || continue
+    run_step "$STAGE_ID" "$STAGE_CMD" || true
+  done < <(list_registered_verification_stage_commands "$SCRIPT_DIR" "$AGENT_ID")
 fi
 
 END_TOTAL=$(now_ms)