tracegrove 0.3.0 → 0.3.1

package/README.md

@@ -1,61 +1,26 @@
 # tracegrove
 
-**Behaviour tests your app has to actually pass, written by you or by a coding agent, with evidence anyone can re-verify.**
+Tracegrove runs behavior checks against an app you launch locally, then saves an evidence bundle you can inspect and verify again. This 0.x release supports Node, FastAPI, and Django samples on POSIX hosts. Linux is exercised in CI; Windows process-tree execution is unsupported. Other hosts need their own qualification.
 
-tracegrove starts your real FastAPI, Django or Node app, walks it through scenarios written as
-short YAML files, checks every effect with an independent read, cleans up what it created, and
-seals the whole run into a bundle that `verify-bundle` can re-derive byte for byte. Claude Code
-or Codex can draft the scenarios from your routes and your intent, with explicit low-cost defaults,
-and tracegrove re-checks everything they write before you see it. When a run breaks, `tracegrove heal`
-fixes setup mistakes and drifted tests, proves every fix with a re-run, and reports real product
-bugs instead of editing them away.
+![Tracegrove showing a verified sample run](https://cdn.jsdelivr.net/npm/tracegrove@0.3.0/docs/images/ui-run.png)
 
-![tracegrove ui: a run shown as a tree of scenarios, each step with its request, timing and status](docs/images/ui-run.png)
+## Try the sample
 
-## First run: an isolated app and verified evidence
-
-The [consolidated implementation and release plan](docs/capability-schema-foundation.md) records
-what is implemented, in progress, planned and blocked, with exact PRs and evidence.
-
-This candidate is unpublished. Start from an authorized checkout of the reviewed commit;
-run the following from its root. Do not install an unrelated registry package with `npx tracegrove`.
-The first run needs **Node >=22.22.0 and <23**, npm with lockfile-v3 support, a POSIX shell,
-writable workspace/temp storage and loopback sockets. Linux is exercised in CI; macOS is
-implemented through the POSIX host but remains unqualified on Hope's offline Mac. Windows
-process-tree execution is blocked. This API sample needs no Docker, Python, browser, model,
-cloud account or application credentials. Dependency installation needs authorized npm access.
-Use one shell session for these blocks. Agents with stateless shell calls should execute the
-bootstrap, build and quickstart blocks together so the selected PATH and writable npm cache persist.
-
-Check `node --version`. If Node 22 is absent and this environment permits dependency installation,
-this optional bootstrap installs a pinned toolchain into an owned temporary folder:
+You need Node.js >=22.22.0 and <23, npm, a POSIX shell, writable temporary storage, and local loopback sockets. Use a provisioned Node 22 runtime; the Node 24 line has not been qualified. The notes sample needs no Docker, browser, Python, cloud account, or coding agent. Install from npm in an empty directory:
 
 ```bash
-TRACEGROVE_TOOLS="$(mktemp -d)"
-npm install --prefix "$TRACEGROVE_TOOLS" --cache "$TRACEGROVE_TOOLS/cache" node@22.23.3 npm@10.9.9
-export PATH="$TRACEGROVE_TOOLS/node_modules/.bin:$PATH"
-node --version
+mkdir tracegrove-demo && cd tracegrove-demo
+npm init -y
+npm install --save-dev --save-exact tracegrove@0.3.1
 ```
 
-Keep that PATH for the verifier **and the app it launches**. If installation or network access is
-denied, select an already provisioned environment; do not change network or permission settings.
-Then build (the temporary npm cache also works in clouds with a read-only home directory):
-
-```bash
-export npm_config_cache="$(mktemp -d)"
-npm ci
-npm run build
-```
-
-Run this single quickstart. It creates an empty owned sample directory, checks configuration and
-runtime prerequisites, starts a real notes app with isolated synthetic fixtures, and re-verifies
-the saved evidence. No agent CLI is invoked.
+Run this block in the same directory. It creates a synthetic Notes API, checks prerequisites, runs two scenarios, and verifies the saved evidence. The `TRACEGROVE_CLI` override is for maintainers testing a local build.
 
 <!-- onboarding-quickstart:start -->
 ```bash
 set -euo pipefail
-TRACEGROVE_CLI="$PWD/dist/cli/main.js"
-TRACEGROVE_DEMO="$(mktemp -d)"
+TRACEGROVE_CLI="${TRACEGROVE_CLI:-$PWD/node_modules/tracegrove/dist/cli/main.js}"
+TRACEGROVE_DEMO="$(mktemp -d "$PWD/tracegrove-notes-XXXXXX")"
 node "$TRACEGROVE_CLI" sample-config --sample notes-api --output "$TRACEGROVE_DEMO"
 node "$TRACEGROVE_CLI" doctor --config "$TRACEGROVE_DEMO/verification/workflow.yaml" --json
 node "$TRACEGROVE_CLI" check --dir "$TRACEGROVE_DEMO" --json
@@ -66,524 +31,32 @@ printf 'Evidence retained at %s\n' "$TRACEGROVE_RUN"
 ```
 <!-- onboarding-quickstart:end -->
 
-Expected: doctor has `blocked: false`, check has `ok: true`, test exits 0 with
-`outcome: passed` and `bundleVerified: true`, and verification has `ok: true`.
-`TRACEGROVE_RUN` contains `summary.json`, `summary.md`, `junit.xml`, `request.json` and `bundle/`.
-The run's receipts retain fixture removal and host-process cleanup confirmations. Keep the
-evidence before deleting your sample directory; ephemeral clouds require exporting it through
-an already authorized artifact destination. A successful process exit alone is insufficient.
-
-For a browser journey, install the pinned Playwright Chromium through the environment's approved
-dependency setup (`npx --no-install playwright install chromium`; Linux also needs its system
-libraries), generate `--sample notes-browser` into a **different empty directory**, and select
-`test --grep notes.browser`. Missing browser/system dependencies are blockers, not permission
-to install system packages or open ports automatically. For a small human UI use
-`node "$TRACEGROVE_CLI" ui --dir "$TRACEGROVE_DEMO"`; when the cloud has no authorized UI preview,
-use the JSON and saved artifacts. Public inbound access is unnecessary for the CLI journey.
-
-| Environment | Current qualification and needed setup |
-| --- | --- |
-| This Codex Linux cloud | Actual native/API/browser fixture journeys recorded; Node 22 and writable temp needed. General portable-profile dispatch and host network confinement remain unqualified. |
-| GitHub-hosted Linux CI | Native, browser, Django and two isolated Docker sample lanes exercised. This does not qualify every coding-cloud runtime. |
-| Hope's macOS machine | Offline; actual clean-start/journey/cleanup evidence unavailable. Needs Node 22, app dependencies, allowed process/loopback access and artifact storage. |
-| Other Codex or Claude coding clouds | Unqualified until capability discovery and the same clean-start journey pass. Do not assume Docker, persistent disks, root, browser libraries or inbound access. |
-| OrgX-triggered cloud/workflow | Unqualified. Task dispatch alone does not provide a runner, workspace, secret broker, network policy or cleanup lease. |
-| Existing external staging | No general external-host adapter or secret broker is wired into this CLI. Declaring an origin/placement does not enable it; keep blocked until authorized adapter qualification. |
-
-The [portable environment contract and rollout gates](docs/portable-environments.md) give the exact
-current-versus-needed matrix, generated SDK templates and credential-reference contract. Those
-templates are experimental SDK records, **not** additional `tracegrove.config.yaml` fields.
-
-If a check fails, use its code and recovery action. `check --dir` validates authoring;
-`doctor --dir <project> --json` finds the authoring config, writes its derived corpus and checks
-the selected native plan. From a project subdirectory, `doctor --json` finds the config above it.
-`doctor --config <low-level workflow.yaml> --profile <name> --json` checks the existing host plan.
-Doctor returns `tracegrove.doctor/v1` JSON with the selected host/corpus refs, source/runtime
-digests, checks, errors and recovery actions; exit 2 means blocked. It never starts the app,
-but can invoke the configured interpreter with `--version`. Browser executable presence is
-installation metadata; engine launch, system libraries and video capture remain untested.
-Its result always says `execution: not_started` and `verificationVerdict: not_evaluated`.
-Portable SDK profiles and external staging are not executable doctor configurations.
-Neither command proves a running app. Top-level failures with `--json` return
-`tracegrove.cli-error/v1` on stdout with a quiet stderr, a public error class, bounded reason codes,
-recovery actions and the process exit code. Doctor retains its `tracegrove.doctor/v1` report.
-These error envelopes omit exception text, paths, argument values and stacks; successful reports,
-doctor diagnostics and retained artifacts keep their existing contents and access requirements.
-`--json false` and `--json=false` retain prose errors; `--jsonl` retains its existing event stream
-and top-level error behavior. Completed `test --json` reports keep their established schema.
-Exit 1 means assertion failure, 2 blocked/inconclusive, 3 infrastructure failure,
-4 cancellation. Do not retry assertions into a clean result or discard the first attempt.
-
-Retry `test` only after fixing the reported cause; it creates a fresh execution with owned
-fixtures and preserves prior run folders. To stop, send one interrupt and allow cleanup to finish;
-unconfirmed cleanup requires reconciliation of that run's owned resources before another attempt.
-For recorded local recovery state, use `recovery-status --state-dir <owned-state> --execution <id> --json`.
-It reports a bounded read-only checkpoint and historical evidence; it never clears ownership,
-recovers locks or admits a retry. See [local recovery inspection](docs/local-execution-recovery.md#read-only-recovery-inspection).
-`verify-bundle` and UI recording playback inspect saved evidence; a new `test` performs new actions.
-New `test` reports include `executionId` and the actual `stateDir` for recovery and export.
-The UI Cancel run button targets the current operation and waits for settlement. Closing the
-UI requests cancellation before returning; inspect saved receipts for cleanup status. Saved-run
-results and recordings are freshly checked against sealed evidence, while names and flow paths
-remain unsealed annotations. Historical steps are never relabeled using current flow positions.
-
-Credentials belong in the environment's authorized resolver. Never put real credentials in
-flows, `app.env`, launch args, profiles or artifacts. The sample issues temporary synthetic persona
-tokens in memory; execution permissions remain the host's separate authority.
-
-What makes it different:
-
-- **Real app, real requests.** No mocks of your own code. Every step is an HTTP call to the app
-  tracegrove launched for this run, on a free port with its own data dir and per-persona tokens.
-- **Independent readback.** `observe: true` re-reads state through a separate request and polls
-  until the expectation holds, so "the endpoint said 204" is never mistaken for "it's deleted".
-- **Owned cleanup.** Fixtures are created through your API, read back, and deleted with a confirmed
-  404/410, in reverse order, even when a scenario fails.
-- **Evidence, not logs.** Each run is a sealed bundle with source digests, receipts and the frozen
-  request. `verify-bundle` rehashes it and re-reduces the verdict on another machine.
-- **Agents under the hood, never trusted blindly.** Claude Code or Codex writes drafts; tracegrove
-  compiles them itself and only a real run produces a verdict.
-
-## Quickstart: test your own app
-
-Tracegrove drops into an existing FastAPI, Django or Node repo with one config file and one
-YAML file per test. Those short files compile into the strict corpus described below, so every
-run still gets attested source identity, independent readback, owned cleanup and a sealed,
-re-verifiable evidence bundle.
-
-```text
-npx --no-install tracegrove init          # detects FastAPI / Django / Node, writes tracegrove.config.yaml + an example flow
-npx --no-install tracegrove test          # compile, plan, run, verify; results in .tracegrove/runs/latest/
-npx --no-install tracegrove heal          # something broke? fix what is safe, prove it, report the rest
-npx --no-install tracegrove               # inside a project: where things stand and what to run next
-```
-
-`tracegrove test` prints the run as a small tree: passing scenarios stay folded, failing ones unfold
-to the step that broke with what was expected and what came back, followed by the next command
-worth running. On a terminal it shows a live line of what is happening (starting the app, which
-step, cleanup) and uses colour unless `NO_COLOR` is set.
+Success means `doctor` reports `blocked: false`, `check` reports `ok: true`, `test` reports `outcome: passed` and `bundleVerified: true`, and `verify-bundle` reports `ok: true`. Keep the evidence directory if you need the receipts; after exporting it, remove the temporary sample with `rm -rf "$TRACEGROVE_DEMO"` in that same shell. The sample uses in-memory synthetic persona tokens and an isolated app data directory. A passing sample does not qualify your app or host.
 
-```yaml
-# tracegrove.config.yaml
-project: notes
-app:
-  adapter: fastapi            # node | fastapi | django | command
-  entry: app.main:app
-  sources: [app/**/*.py]      # bytes attested as "what was tested"
-personas:
-  owner: { subject: alice }   # the first persona is the default caller
-  intruder: { subject: bob }
-```
-
-```yaml
-# tracegrove/notes/crud.flow.yaml  ->  case id notes.crud
-title: Create, read, deny a stranger and delete a note
-steps:
-  - name: create
-    POST: /notes
-    json: { title: Fresh note, body: hello }
-    expect: 201
-    save: { noteId: note.id }
-  - name: read back
-    GET: /notes/{noteId}
-    observe: true             # independent readback, polled until expect holds
-    expect: { status: 200, json: { note.title: Fresh note } }
-  - name: intruder is denied
-    GET: /notes/{noteId}
-    as: intruder
-    expect: { status: 403, absent: [note] }
-```
+## Test your app
 
-Tracegrove picks a free port, passes it (and a fresh data directory and one random bearer token
-per persona) to the app through `PORT`, `TRACEGROVE_DATA_DIR` and `TRACEGROVE_TOKENS`
-(`{token: subject}` JSON), and waits on `app.health`. The app accepts those tokens in test mode;
-`tracegrove init` prints the five-line snippet for the detected framework.
+Run `npx --no-install tracegrove init` in a project with Tracegrove installed. It creates `tracegrove.config.yaml` and a starter flow. Adjust the app entry, health route, source paths, and personas, then run `npx --no-install tracegrove check` followed by `npx --no-install tracegrove test --json`. For a human view, run `npx --no-install tracegrove ui`.
 
-| `adapter` | launches |
-| --- | --- |
-| `node` | `node <entry>` |
-| `fastapi` | `<python> -m uvicorn <entry> --host 127.0.0.1 --port {port}` (python: `.venv/bin/python`, else `python3`) |
-| `django` | `manage.py migrate --noinput && manage.py runserver 127.0.0.1:{port} --noreload` in the `entry` folder |
-| `command` | Reserved; BLOCKED until the application runtime can be independently observed |
-
-Conventions:
+Your app must accept the per-run test persona tokens provided through `TRACEGROVE_TOKENS`, or use another reviewed test-only authentication path. Keep that path disabled in production. The Node, FastAPI, and Django adapters start the app on an assigned local port. Django's migration step must point at a database inside `TRACEGROVE_DATA_DIR`; check its settings before running so it cannot migrate another database. Tracegrove does not provision a database or cloud runner for you.
 
-- Flows live in `tracegrove/<area>/<behavior>.flow.yaml`; the case id is `<area>.<behavior>`.
-- Fixtures live in `tracegrove/fixtures/<name>.fixture.yaml` and are used with `given: { alias: name }`;
-  their saved values are `{alias.output}` in later steps. They are created through the API, read
-  back independently and deleted with a confirmed 404/410 absence.
-- `save: { name: dot.path }` makes `{name}` available to later steps; `expect.json` keys are dot
-  paths into the response body. Prefer block style for anything containing `{` or `[` (or quote it).
-- The effect envelope (methods, path prefixes, create budget) is derived from the steps.
-- Each run writes `.tracegrove/runs/<UTC time>_<outcome>_<id>/` with `summary.md`, `summary.json`,
-  `junit.xml`, the frozen `request.json` and the verified `bundle/`; `runs/latest` points at the
-  newest. Add `.tracegrove/` to `.gitignore` (init does).
-- Editor validation: point `yaml.schemas` at `schema/tracegrove_config_v1.json` and
-  `schema/tracegrove_flow_v1.json`.
+Results are saved under `.tracegrove/runs/<run>/` with `summary.json`, `summary.md`, `junit.xml`, and `bundle/`. Bundle verification checks file integrity and recomputes the verdict; bundles are unsigned, so a receiving system still needs to trust their producer. Press Ctrl-C once to request cancellation and wait for cleanup. If cleanup is unconfirmed, inspect the receipts before another attempt.
 
-Runnable samples: `src/samples/notes-api` (Node), `src/samples/fastapi-notes`,
-`src/samples/django-notes`. `tracegrove compile` writes the derived v1 corpus to
-`.tracegrove/compiled/` if you want to inspect it or drop to the low-level commands.
+[Getting started with your app](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/getting-started.md) · [Verified bundles and cleanup](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/verified-bundles.md) · [Recovery inspection](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/local-execution-recovery.md)
 
-## Self-healing: `tracegrove heal`
+## For coding agents and CI
 
-```text
-npx --no-install tracegrove heal                 # diagnose, repair, re-run, keep only what passes
-npx --no-install tracegrove heal --dry-run       # show what it would change; change nothing
-npx --no-install tracegrove heal --no-agent      # setup fixes only, no coding agent
-npx --no-install tracegrove heal --undo latest   # put back every change the last heal kept
-npx --no-install tracegrove test --heal          # run, and heal if anything fails
-```
+Use `status --json` to find the next action, `discover --json` to compare routes and flows, `check --json` to compile, and `test --json` to execute. The `test` summary uses `tracegrove.run-summary/v1` and includes `outcome`, `runDir`, `bundleVerified`, `cases`, and `blockers`. `doctor` uses `tracegrove.doctor/v1`; top-level JSON errors use `tracegrove.cli-error/v1`. Keep the first failed run and its evidence when diagnosing a retry.
 
-Heal reads the latest failure and sorts every problem into one of a few kinds, then acts on each:
-
-| Finding | What heal does |
+| Exit | Meaning |
 | --- | --- |
-| **Setup**: the app never answered its health check | Finds GET routes and string literals in your source that look like health endpoints (`/health`, `/healthz`, `/ready`, …), tries them one at a time in `tracegrove.config.yaml`, and keeps the first one under which the app actually starts. |
-| **Setup**: the Python interpreter is missing or lacks the framework | Tries `.venv`, `venv` and `PATH` interpreters that can import FastAPI and uvicorn (or Django) and keeps the one tracegrove recognizes. |
-| **Authoring**: a flow does not compile | Hands the `check` issues to your coding agent, limited to the named files. |
-| **Failing check** | Asks the agent to read the handlers and recent changes and call each failure **test drift** (the app changed on purpose; update the flow) or a **product bug** (the app is wrong; leave the flow alone). |
-| **Evidence** or **infrastructure** | Never repaired; explained, with the run folder to read. |
-
-Repair safeguards and their limits:
-
-- **Drift edits need an explicit verdict and a passing case.** A successful agent must provide
-  one matching drift verdict before an edit is admitted. Missing, malformed, conflicting or
-  foreign verdicts are rejected. Candidate flow edits must compile and pass their case;
-  setup fixes must clear their setup check. Other failures stay reported.
-- **Product bugs stay red.** A case the agent calls a product bug keeps its failing test, the heal
-  exits 1, and the report says what is wrong in one sentence.
-- **Mechanical guards reject deleted steps, renamed steps, fewer checks and success/denial
-  flips**, for example `403` to `200`. These guards and an agent verdict do not prove intended
-  product behavior or semantic equivalence: inspect the saved diff. Watched edits outside the
-  failing flows and newly discovered files are restored or removed; this is not an agent sandbox.
-- **Undo preserves subsequent edits.** Kept changes have backups and complete file hashes under
-  `.tracegrove/heals/<id>/` next to `report.json` (schema `tracegrove.heal/v1`). Undo restores only
-  the exact recorded healed file. Changed files, altered backups and old reports without these
-  bindings require manual undo. Heal and undo share a local lock; keep other editors and tools
-  idle because they do not participate in it.
-- **Cancellation waits for the owned operation.** The UI cancels by operation ID and stops new
-  mutations during shutdown. Agent exit precedes rollback of unretained heal edits. Inspect the
-  saved report and run receipts for retained setup fixes and cleanup status.
-- **Comments survive.** Config edits go through a YAML document model, so your comments and
-  formatting stay put.
-
-In the UI, **Heal** (or `h`) runs the same thing with the agent's progress streaming in, then
-shows findings, each kept change as a diff, and **Undo all**.
-
-The Heal tab ships inside the CLI. The optional repository illustration `docs/images/ui-heal.png` is excluded from the npm package; no UI behavior depends on it.
-
-## The grove: `tracegrove ui`
-
-```text
-npx --no-install tracegrove ui                          # current folder, working tree
-npx --no-install tracegrove ui --dir ../api --branch feature/billing
-```
-
-A local page (bound to 127.0.0.1, with a per-session token on anything that writes), light and
-dark, down to phone width:
-
-- **Run.** Your scenarios as a bonsai: the trunk is the run, each branch a scenario, each twig a
-  step with its request, its slice of the run clock and the observed status. Failures collect in
-  **Needs a fix**; pick a step to see expected against observed and the evidence line. Run all,
-  run one scenario, or switch to any earlier run.
-- **Discover.** Pick the working tree or any git branch (read with `git show`, nothing is checked
-  out). Routes from FastAPI decorators, Django `path()` and Express-style routers are listed with
-  the flows that reach them, changed-on-this-branch first. Draft a skeleton for one route, or write
-  what should be true in **Intent** and press **Draft with Claude**: what the agent reads, edits
-  and says streams in live, and its flows arrive already checked, with **Run the new scenarios**
-  one click away.
-- **Heal.** Diagnose and repair with one button, watch the agent work, review every kept change as
-  a diff, see product bugs called out, and undo any heal. Earlier heals stay listed.
-- **History.** A grid with one column per run and one row per scenario, so a single case's record
-  and the whole set read at a glance. Any cell opens that run at that scenario.
-- **Settings.** Choose Claude Code, Codex or none, and the model. Installed CLIs are detected.
-
-While a run is going, the step being executed pulses in the tree and the header says what is
-happening, from real run events rather than a timer. **⌘K** (or **Ctrl K**, or `/`) opens a command
-palette for every action, scenario and branch; `j`/`k` move through scenarios, `r` reruns the
-selected one, `R` runs all, `h` heals, `1`–`5` switch tabs and `?` lists the keys. Pruning and
-healing both offer **Undo** in the confirmation.
-
-**Pruning is a rename.** Prune a scenario and its file becomes `*.flow.yaml.pruned`: the compiler
-skips it, the tree shows it as a dashed branch, and **Graft back** restores it. Nothing is deleted.
-
-Discovery is a static heuristic that proposes tests; it is never evidence. Only `tracegrove test`
-produces a verdict.
-
-## Agents under the hood
-
-tracegrove does not ship a model. It drives the coding agent you already use, headless:
-
-| Provider | Command it runs | Default model |
-| --- | --- | --- |
-| `claude` (default) | `claude -p … --model claude-haiku-5-5 --output-format stream-json --permission-mode acceptEdits --allowedTools Read,Write,Edit,Glob,Grep,Bash(tracegrove check/list/discover)` | `claude-haiku-5-5` |
-| `codex` | `codex exec --sandbox workspace-write --model gpt-6-luna` | `gpt-6-luna` |
-| `none` | nothing; discovery and templates only | |
-
-The agent gets the discovery report, your intent, the naming conventions, an existing flow as an
-example, the persona names and the JSON Schemas. Its instructions request drafts under
-`tracegrove/discovered/` and read-only checks; its CLI permissions remain the execution boundary.
-Its stream of events is shown live in the terminal and the UI. If Claude Code rejects the
-configured model id, tracegrove retries once with the `haiku` alias and records that in the
-result (a dotted id such as `claude-haiku-4.5` is corrected to `claude-haiku-4-5` up front). The
-agent runs as its own session even when tracegrove is itself driven from inside Claude Code.
-After it exits, tracegrove lists changed flow files and compiles the project. Compilation is
-not independent confirmation of the developer's intent. A configured `maxBudgetUsd` is
-supported by the Claude adapter; Codex blocks that setting until enforced accounting exists.
-
-Where the choice comes from, highest first:
-
-1. `--agent` / `--model` on `tracegrove draft`
-2. `.tracegrove/settings.json`, your own choice, written by **Settings** in the UI or `tracegrove settings --agent codex`
-3. `agent:` in `tracegrove.config.yaml`, the team default:
-
-   ```yaml
-   agent:
-     provider: claude      # claude | codex | none
-     model: claude-haiku-5-5  # optional
-     maxBudgetUsd: 0.50    # optional spend cap per draft (Claude Code)
-   ```
-4. The explicit low-cost defaults above. No inherited CLI model or silent provider fallback.
-
-### Commands built for agents
-
-Every one takes `--json`; the first five never start your app:
-
-```text
-tracegrove status                    # where things stand plus an ordered `next` list of commands and why
-tracegrove discover [--branch <b>]   # routes vs. flows that reach them; changed files first
-tracegrove check                     # compile only; exit 0 when clean, 2 with file:path-located issues
-tracegrove list                      # flows with ids, tags and steps
-tracegrove draft --intent "<what should be true>" [--agent claude|codex] [--model <m>]
-tracegrove settings [--agent …] [--model …]
-tracegrove heal [--dry-run] [--no-agent]   # runs the suite; returns findings, kept diffs and `next`
-```
-
-So any agent, including one you run yourself, can loop: `status` → `discover` → write flows →
-`check` → `test` → `heal` → follow `next`. `tracegrove init` writes `tracegrove/AGENTS.md` with
-these conventions and the loop, so Claude Code, Codex or Cursor pick them up from the repo.
-
-## How it fits together
-
-Prefer TypeScript? Use `tracegrove.config.ts` with `defineConfig`, `.flow.ts`
-with `flow`, and `.fixture.ts` with `fixture`, all exported by
-`workflow-verify/authoring`. These reuse the YAML validation and execution path.
-See [typed authoring](docs/developer-ux.md#typescript-authoring) for examples,
-module evaluation bounds, and supported TypeScript syntax.
-
-```text
- tracegrove.config.yaml + tracegrove/**/*.flow.yaml + fixtures
-        │  authoring compiler (src/authoring)
-        ▼
- .tracegrove/compiled/  (strict workflow.*/v1 corpus, $file refs frozen to sha256)
-        │  planner → admission + local ledger → executor
-        │     hosts: local_process | mock_loopback   surface: http   fixtures: API create/readback/cleanup
-        ▼
- trusted reducer → bundle writer → verify-bundle → .tracegrove/runs/<run>/
-```
-
-The everyday flow is `init` → `ui` or `draft` (discover, write with an agent, prune) → `test` → read the
-run in the grove or with `show` → hand the bundle to anyone who runs `verify-bundle`.
-
-What the adapters cover now and what's next:
-
-| Area | Supported now | Next |
-| --- | --- | --- |
-| App launch | node, fastapi, django; free port, data dir, per-persona tokens. Command wrappers remain blocked | `app.setup` commands (alembic, prisma, knex) |
-| Seeding | Fixtures created through the app's API, read back, deleted with confirmed absence | SQL seeding, repo seed commands (factory_boy, Prisma seed), snapshots |
-| Databases | SQLite via `TRACEGROVE_DATA_DIR` | `db: postgres` per-run database with `DATABASE_URL`, DB-state oracles, Redis/Mongo services |
-| Async jobs | Separate-worker SQLite samples through HTTP or native Node IPC: persisted output, idempotency, cancellation, owner isolation | Independently supervised/attested Celery/RQ/BullMQ workers and broker services; hosted provider qualification |
-| Third parties | Whole-app mock host for the contract lane (low-level corpus only) | Outbound interceptor (stub/record/pass-through per provider), record and replay, email/webhook capture |
-| Data pipelines | None | `job` surface for dbt/Airflow/Dagster runs, table oracles (row counts, schema, golden files), DuckDB first |
-| Browser | Typed short flows and low-level corpus, authenticated local personas, DOM/API assertions, sealed video and Grove playback | Staging qualification, trace/redaction collectors and controller-death cleanup |
-
-The full gap analysis by layer, with priorities, is in [docs/architecture.md](docs/architecture.md).
-
-## The verification core
-
-This is the Phase 1a implementation of the plan in
-`orgx/docs/architecture/workflow-verification-platform.md`. It is a prototype; nothing below is a
-production claim.
-
-What exists and is exercised by tests:
-
-- Canonical JSON codec with shared vectors and SHA-256 self digests (`ref.digest` excluded).
-- Strict versioned schemas (Zod 4) exported as JSON Schema under `schema/`, checked in sync.
-- Project corpus loader: YAML/JSON beside the product source, `{ $file: ./path }` references
-  frozen into exact refs, a frozen corpus manifest, digest-verified lookup.
-- Compiler, planner (`plan` is side-effect free and returns blockers with owner and action),
-  admission with idempotent redelivery, local single-writer ledger with stale-lock recovery.
-- Executor: local process host with launcher-computed identity attestation and issued
-  credentials, mock loopback host for the `mock_contract` lane, real HTTP driver with
-  per-operation deadlines, registered fixture actions with independent readback and
-  reverse-order cleanup, boundary observations, sealed receipts, trusted reducer.
-- Evidence bundle writer and `verify-bundle`, which rehashes every file, rechecks every self
-  digest, re-derives assertions from the frozen case and re-reduces the verdict.
-- `tracegrove` CLI (also installed as `workflow-verify`): `init`, `test`, `list`, `show`, `compile`, `ui`, `discover`, `check`, `draft`, `settings`, `sample-config`, `validate`, `doctor`, `plan`, `cases`, `rerun`, `controller`, `seed --preview`,
-  `run`, `inspect`, `export`, `verify-bundle`, `schema`. Exit codes 0/1/2/3/4.
-- A real file-backed notes API sample with its corpus, plus an offline contract lane.
-
-The local controller owns an exclusive ledger and accepts authenticated loopback commands
-for one project. CLI runs delegate to that writer; concurrent redelivery reconciles the same
-execution. Case lookup uses bounded pages with snapshot-bound cursors. `rerun` freezes a fresh
-campaign while preserving case digests and original request lineage. Use
-`inspect --request` for static frozen-plan checks and `inspect --bundle` for independently
-verified evidence. [Inspection and export](docs/verified-bundles.md#inspect-and-hand-off-a-frozen-run)
-use sealed snapshots; lifecycle reruns require fresh owner registration.
-
-The POSIX local host uses a trusted supervisor with an IPC ownership channel. If
-the controller is killed, the supervisor terminates the application process group
-and removes its owned workspace. A process-kill test checks both effects. This
-does not establish recovery after the supervisor itself is killed, distributed
-fencing, or cleanup of external provider resources. Windows local launches are
-blocked until a process-tree ownership implementation exists.
-
-Bundle verification checks sealed required files, host capability records, target attestations,
-fixture completeness and boundary observations. It rejects empty/traversal manifests and
-producer resealing that removes required observations. This verifies portable integrity and
-record consistency; the importer still needs its own issuer trust and access policy.
-The [verified snapshot reader](docs/verified-bundles.md) supplies complete checked
-records from the same bounded bytes used by the reducer, without rereading payloads.
-
-`verifySourceCitation` checks exact repository/commit/path identity, document and
-file digests, and inclusive line excerpt bytes through authorized trusted host ports.
-It preserves UTF-8 and CRLF bytes, rejects traversal, unsupported files and unavailable
-objects, and never falls back to the current checkout. These checks establish cited
-source bytes. The source-analysis API connects them to runnable change elements and
-the authenticated review policy; it does not establish passing product behavior.
-
-The Phase 2 review API (`editPlan`, `reviewPlan`) binds exact source-plan
-digests and scopes. Every specification edit clears its review. Concurrent edits and
-reviews use a host-owned atomic compare-and-swap port; losing writes publish neither
-review nor projection. Reviewer identity and policy come from authenticated host
-admission. Tests exercise stale tokens, concurrent writers, resolver tampering and
-denied authority. This API has no hosted store, execution-admission integration or
-scenario activation. Resolving and validating source citations and coverage policy
-are enforced through trusted source-analysis and policy ports before approval; hosted
-implementations remain separate work. These records alone are not authority for product execution.
-See [source-backed review](docs/source-review.md) for the immutable checks and atomic host contract.
-`source-resolve` and `GitSourceReader` [freeze local Git commit pairs and full diffs](docs/git-source-resolution.md)
-and read cited immutable objects after checkout changes. They supply source facts;
-independent review policy, full source transport and runtime identity remain separate gates.
-`LocalReviewStore` connects that API to the existing single-writer journal and preserves
-reviews/source checks across reopen. [Local review storage](docs/local-review-store.md)
-requires trusted host admission and source checking; it does not supply distributed authority.
-`promoteScenario` binds actual current review storage to a proposed scenario and retains
-the full plan, gaps and source-validation snapshot. [Source promotion](docs/source-promotion.md)
-remains separate from structural validation, execution and activation.
-
-Scenario qualification now has a typed registration/invalidation API with exact-matrix
-and monotonic-history checks. [Structural validation](docs/scenario-structure.md) shares
-the executor's static preflight and atomically moves authorized proposed/degraded
-scenarios to validating, without running them. The lifecycle API records pending work
-and invalidates semantic edits;
-it does not qualify or activate coverage. See [registration contract](docs/qualification-registration.md).
-`reduceQualificationRound` binds an entire verified terminal campaign to the registered
-cell/attempt allocations, retaining failed and mock evidence without granting a live
-proof level. See [terminal result contract](docs/qualification-results.md) for the host authority boundary.
-`LocalQualificationResults` retains those complete rounds through the existing immutable
-result sink and supplies a durable replay-assessment index, with fresh issuer checks on reads.
-`assessScenarioReplay` derives readiness from authenticated complete rounds, retains pending
-and failed history, requires at least two independent live campaigns and checks the latest
-admitted round. [Replay assessment](docs/replay-assessment.md) is read-only.
-`activateScenario` rechecks that evidence and publishes an authenticated activation through
-an atomic host port, with exact round selection and idempotent receipt recovery. See
-[activation contract](docs/scenario-activation.md); hosted authority and activated regression execution remain open.
-`LocalScenarioStore.activationPorts(results, authority)` publishes the active projection,
-receipt and full assessment records together on the existing local ledger, after fresh
-evidence and explicit owner authorization checks. Historical receipts cannot reverse invalidation.
-`LocalScenarioStore` persists actual registration on the local ledger. The SDK's
-`prepareQualificationExecution` and explicit runtime owner connect those admissions
-to new executions using allocated cell identities, with current authority checks
-before effects. See [registered execution](docs/qualification-registration.md#executing-a-registered-round).
-
-`result-ingest --bundle <run/bundle> --sink <directory>` retains an independently
-re-verified local bundle in the existing single-writer ledger and an immutable
-archive. `results --sink <directory>` lists scoped receipts;
-`results --sink <directory> --id <result-id>` freshly re-verifies a retained result
-after the producer's directory is gone. The [result sink](docs/result-sink.md)
-preserves failed and mocked outcomes, rejects conflicting deliveries, and never
-treats storage acceptance as issuer authentication, qualification, or activation.
-
-The optional [AWR delivery adapter](docs/awr-delivery.md) freezes a redacted report
-and destination in that same ledger. `awr-prepare`, `awr-inspect`, and `awr-deliver`
-separate preparation from authenticated import, retain failed product verdicts,
-and retry the original key after a lost acknowledgement without rerunning tests.
-Imported evidence remains unverified; native work acceptance is a separate gate.
-The [work-report attachment stage](docs/work-report-attachment.md) links an imported
-report to its original frozen work binding, rechecks hosted receipt identity, and
-recovers lost attachment acknowledgements independently of import or execution.
-
-The [local browser runner](docs/browser-driver.md) executes typed UI steps alongside HTTP
-fixtures and independent readback, and verifies recordings in the portable bundle.
-Browser short flows run through `tracegrove test`; Grove plays receipt-bound recordings
-after rechecking the bundle. See the browser sample and guide for the exact syntax.
-Still open: full runtime source selection,
-hosted review and qualification, coordination acceptance, `seed --apply`, and distributed crash recovery.
-Selected Git base/head trees can now be materialized into private independent
-directories with [Git object proofs](docs/git-object-proof.md) checked against actual
-file bytes and rechecked by the launch supervisor. Metadata-only proof checks do not
-establish runtime verification. Add `--source-repository-role application` to bind a
-single resolver-head snapshot to its measured Git-object repository tuple and frozen
-source selection. Local revision qualification is covered; hosted issuer authentication
-and remote repository ownership remain separate.
-Use `source-materialize`; the [source guide](docs/git-source-resolution.md#run-selected-revisions-independently)
-shows running the same saved flow against each revision. `test --source-snapshot`
-binds local launch content to the manifest: the supervisor verifies and copies the
-pinned tree into its owned workspace. Automatic authenticated runtime revision
-attestation remains open.
-Agent drafting checks compilation; it does not confirm intended behavior or approve a plan.
-
-## Zero-OrgX quickstart (low-level corpus)
-
-```text
-npm install && npm run build
-node dist/cli/main.js sample-config --sample notes-api --output ./notes
-node dist/cli/main.js doctor --config ./notes/verification/workflow.yaml
-node dist/cli/main.js plan --config ./notes/verification/workflow.yaml --output ./out/request.json
-node dist/cli/main.js run --request ./out/request.json
-node dist/cli/main.js verify-bundle --bundle ./notes/verification/.workflow-verify/executions/<id>
-```
-
-No OrgX account, database, Docker, Python or model call is involved. The real sample's
-proof claim is local application behavior at the attested source digest, not deployment.
-
-To exercise asynchronous work, generate `sample-config --sample report-jobs --output
-./reports`, then run `tracegrove test --config ./reports/tracegrove.config.yaml`.
-The [report jobs sample](src/samples/report-jobs/README.md) uses a real separate worker
-and persisted SQLite queue. Completion requires an independent output readback;
-accepting a submission alone cannot pass. Its controlled missing-output defect
-produces a sealed failed attempt. No model calls or external accounts are used.
-For low-level commands, use the config path printed by sample generation.
-For native `job.submit`, `job.observe`, and `job.cancel`, generate
-`sample-config --sample report-native --output ./native-reports` instead.
-The [native job bridge](docs/native-jobs.md) uses the same application, worker,
-and storage with typed Node IPC requests and job observations. Hosted providers,
-independent worker attestation and distributed crash recovery remain open.
-
-For local MCP tools, install the pinned optional SDK and generate
-`sample-config --sample notes-mcp --output ./mcp-notes`. The
-[MCP protocol driver](docs/mcp-driver.md) uses the same planner, persona, evidence
-and CLI path, with explicit tool/call limits and independent HTTP readback.
-Protocol results do not qualify a widget host or mobile surface.
-
-## Checks
-
-For clean, credential-free Docker runs, see [container qualification](containers/README.md). Native real HTTP and offline contract lanes produce separate saved bundles.
-
-```text
-npm run verify            # typecheck, schema sync, unit and end-to-end tests
-npm run test:conformance  # verifier conformance cases (refusals and non-green results)
-```
+| 0 | Passed or clean |
+| 1 | Assertion failed |
+| 2 | Blocked or inconclusive |
+| 3 | Infrastructure failed |
+| 4 | Cancelled |
 
-## Repository provenance
+`draft` runs a configured Claude Code or Codex CLI and may edit flow files. `heal` runs the suite and can edit setup or flow files after its checks. Commit or stash your work before either command; review every proposed diff. `heal --dry-run` inspects without keeping edits. An agent verdict or a successful compile does not prove that a changed test still expresses your intent.
 
-This private repository was extracted with `git subtree split` from
-`hopeatina/orgx:packages/tracegrove` at OrgX commit
-`6da4205e0cef9fbd75b0e8e04cdfc6d5de669910`. The extracted bootstrap commit is
-`92f163c49812e373bdb04550ea3771b278eab0cd`.
+[Agent command and JSON guide](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/agent-guide.md) · [Browser driver](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/browser-driver.md) · [Native jobs](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/native-jobs.md) · [MCP driver](https://cdn.jsdelivr.net/npm/tracegrove@0.3.1/docs/mcp-driver.md)
 
-`codex/bootstrap` is the default branch. Releases are tagged on GitHub; v0.2.0 is the first,
-with the authoring layer, the grove UI and agent drafting. The standalone sample installs a pinned package archive,
-so its CI needs no cross-repository credential.
+Apache-2.0 licensed.