tracegrove 0.3.0 → 0.3.1

package/docs/agent-guide.md

@@ -0,0 +1,21 @@
+# Agent and CI command guide
+
+Use the installed binary through `npx --no-install tracegrove` so CI never fetches an unrelated package. Pass `--json` and check both exit status and report fields; do not classify a run from prose alone.
+
+| Command | Effect | Result |
+| --- | --- | --- |
+| `status --json` | Reads the current project and run state | `tracegrove.status/v1` and ordered `next` commands |
+| `discover --json` | Compares discovered routes and authored flows | Coverage suggestions, no app launch |
+| `check --json` | Compiles authoring files | `ok` and located issues; may evaluate trusted TypeScript authoring modules |
+| `doctor --dir . --json` | Checks the native plan without app launch | `tracegrove.doctor/v1`, `checks`, `errors`, `blocked`, `execution: not_started` |
+| `test --json` | Starts the selected app and executes scenarios | `tracegrove.run-summary/v1`, `outcome`, `cases`, `blockers`, `runDir`, `bundleVerified` |
+| `verify-bundle --bundle <dir> --json` | Checks existing evidence | `ok`, `problems`, `outcome`, `receipts`; no app launch |
+| `draft --intent '<goal>'` | Starts a coding agent to edit drafts | Review changed files and compile/run afterward |
+| `heal --dry-run` | Runs and diagnoses the suite | Findings without retained agent edits |
+| `heal` | May retain bounded setup/flow edits | `tracegrove.heal/v1`; inspect saved diff and backups |
+
+Exit codes: 0 clean/passed; 1 assertion failure; 2 blocked/inconclusive; 3 infrastructure failure; 4 cancellation. A top-level JSON error uses `tracegrove.cli-error/v1`, with a public class, bounded reason codes and recovery actions. Normal reports and artifacts may contain application data; protect them with your usual workspace access controls. `--json=false` selects prose errors, while `--jsonl` keeps its event stream.
+
+Agent drafting uses the configured Claude Code or Codex CLI and its existing permissions. Tracegrove's prompt is not a filesystem sandbox. The default models are explicit in the adapter, and one Claude model-alias retry is recorded when used. A requested `maxBudgetUsd` is supported by the Claude adapter; the Codex adapter blocks it rather than ignoring a spending limit. Commit or stash work before drafting or healing, review proposed changes, and preserve the original failed run. A passing compiled flow is not proof of intended behavior.
+
+The same short flows compile into the strict `workflow.*/v1` corpus. The browser, native jobs, MCP, evidence and recovery guides are shipped in this package. General portable profiles are reference-only; they cannot be passed to the present CLI as an executable target.

package/docs/browser-driver.md

@@ -2,29 +2,27 @@
 
 `BrowserDriver` runs real Chromium in a fresh, nonpersistent context. It does
 not connect to an existing browser profile. Install its pinned browser before
-running browser tests or using the driver:
+running browser tests or using the driver in a project with Tracegrove installed:
 
 ```sh
-npm ci
-PLAYWRIGHT_SKIP_BROWSER_GC=1 npx --no-install playwright install chromium
-npm test -- tests/browser-driver.test.ts
+npx --no-install playwright install chromium
 ```
 
 Linux CI uses `playwright install --with-deps chromium` to install the browser
 and its system libraries.
 
-Run the packaged browser sample through the same low-level CLI as an API case:
+Run the packaged browser sample through the same low-level CLI as an API case,
+from a directory where Tracegrove is installed:
 
 ```sh
-npm run build
-node dist/cli/main.js sample-config --sample notes-browser --output /tmp/notes-browser
-node dist/cli/main.js plan --config /tmp/notes-browser/verification/workflow.yaml --output /tmp/notes-browser-request.json
-node dist/cli/main.js run --request /tmp/notes-browser-request.json
+npx --no-install tracegrove sample-config --sample notes-browser --output "$PWD/notes-browser"
+npx --no-install tracegrove plan --config "$PWD/notes-browser/verification/workflow.yaml" --output "$PWD/notes-browser-request.json"
+npx --no-install tracegrove run --request "$PWD/notes-browser-request.json"
 ```
 
 Use fresh output paths: sample generation refuses to overwrite a project. The
 run prints its execution ID and bundle path. Pass that path to
-`node dist/cli/main.js verify-bundle --bundle <path>` for independent verification.
+`npx --no-install tracegrove verify-bundle --bundle <path>` for independent verification.
 The sample shares its real app, personas, fixture recipes, and cleanup with
 `notes-api`; only its browser runner, binding, and case differ.
 
@@ -94,11 +92,11 @@ controller-death browser cleanup remain open; no production qualification is cla
 
 ## Short flows and Grove
 
-The packaged sample also includes a short browser flow. From the repository root:
+The packaged sample also includes a short browser flow. From the same installed directory:
 
 ```sh
-node dist/cli/main.js test --config /tmp/notes-browser/tracegrove.config.yaml --grep notes.browser
-node dist/cli/main.js ui --dir /tmp/notes-browser
+npx --no-install tracegrove test --config "$PWD/notes-browser/tracegrove.config.yaml" --grep notes.browser
+npx --no-install tracegrove ui --dir "$PWD/notes-browser"
 ```
 
 Open the printed loopback address and select the browser scenario. Its step

package/docs/getting-started.md

@@ -0,0 +1,13 @@
+# Test an existing app
+
+Start with the [npm README](https://www.npmjs.com/package/tracegrove) and its synthetic Notes sample. In your own repository, install `tracegrove@0.3.1` as a development dependency, then run `npx --no-install tracegrove init`. Review the generated config and flow before running them.
+
+`tracegrove.config.yaml` names a `project`, an `app` adapter (`node`, `fastapi`, or `django`), its entry point and health route, source paths to digest, and test personas. Put flows at `tracegrove/<area>/<behavior>.flow.yaml`; their case IDs use `<area>.<behavior>`. A flow contains named steps with methods, paths, expected statuses and optional independent read requests (`observe: true`). Put reusable fixtures at `tracegrove/fixtures/<name>.fixture.yaml`. Steps can `save` a response value and refer to it later as `{name}`; inspect the generated starter flow or packaged Notes sample for a complete example. `npx --no-install tracegrove check --json` compiles these files without starting the app. `doctor --dir . --json` checks the selected native plan; it can probe an interpreter version but does not run your app.
+
+The local adapter assigns a loopback port and owned data directory. Your app must consume the injected port and `TRACEGROVE_DATA_DIR` and recognize the per-run synthetic `TRACEGROVE_TOKENS` in test mode. Keep the test token path disabled in production. The Django adapter invokes migration before start: verify that Django's configured database lives in the injected data directory. Do not point a test run at a shared or production database.
+
+Run `npx --no-install tracegrove test --json`. A passing JSON summary names `runDir`, `executionId`, per-case outcomes, and `bundleVerified`. The run folder contains readable summaries, JUnit and `bundle/`. Run `npx --no-install tracegrove verify-bundle --bundle <runDir>/bundle --json` to independently check the stored files and verdict. Verification does not rerun your app or establish who produced an unsigned bundle.
+
+If a prerequisite blocks, read `blockers[]` and the suggested recovery before retrying. A nonzero assertion result is a finding about the app or test, not a setup failure. For a single interrupt, wait for the owned cleanup and inspect its receipts. Keep the run folder until you have exported any evidence you need. `recovery-status` reads an existing checkpoint but cannot clear ownership or restart work.
+
+Browser tests need the pinned Playwright Chromium installed through your environment's approved dependency path. The browser and native job guides are in this npm package. External staging, a general cloud runner and arbitrary shell launchers are not available through the current CLI.

package/docs/native-jobs.md

@@ -61,7 +61,7 @@ name the requested job, and submitted results must retain the requested key.
 
 ## Application protocol
 
-Schemas are exported through `workflow-verify/protocol` and JSON Schema:
+Schemas are exported through `tracegrove/protocol` and JSON Schema:
 `workflow.native-job-{action,request,response,ready,observation}/v1`.
 The supervisor opens IPC only for an opted-in Node application and sets
 `TRACEGROVE_NATIVE_JOBS=node_ipc/v1`. After its worker/provider is ready, the

package/docs/result-sink.md

@@ -82,6 +82,6 @@ labels, including `WORKFLOW_VERIFY_OWNER`, do not authenticate a remote tenant.
 
 This sink verifies integrity and record consistency. It does not authenticate an
 issuer, approve a source plan, provision qualification leases, activate coverage,
-or publish an OrgX AWR record. Hosted receiver authentication, tenant delivery,
-and scoped OrgX projection require their own trusted adapters. A storage receipt
+or publish a third-party work receipt. Hosted receiver authentication, tenant delivery,
+and scoped downstream projections require their own trusted adapters. A storage receipt
 cannot stand in for those acceptance gates.

package/package.json

@@ -1,22 +1,57 @@
 {
   "name": "tracegrove",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
-  "description": "tracegrove: behaviour tests against your real app, drafted by Claude Code or Codex, sealed as re-verifiable evidence.",
+  "description": "Verify app behavior with real requests, independent readback and inspectable evidence.",
   "license": "Apache-2.0",
   "type": "module",
-  "engines": { "node": ">=22.22.0 <23" },
-  "bin": { "tracegrove": "./dist/cli/main.js", "workflow-verify": "./dist/cli/main.js" },
+  "engines": {
+    "node": ">=22.22.0 <23"
+  },
+  "bin": {
+    "tracegrove": "./dist/cli/main.js",
+    "workflow-verify": "./dist/cli/main.js"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    "./integrations/awr": { "types": "./dist/integrations/awr/index.d.ts", "default": "./dist/integrations/awr/index.js" },
-    "./authoring": { "types": "./dist/authoring/index.d.ts", "default": "./dist/authoring/index.js" },
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-    "./protocol": { "types": "./dist/protocol/index.d.ts", "default": "./dist/protocol/index.js" },
-    "./coordination": { "types": "./dist/core/coordination.d.ts", "default": "./dist/core/coordination.js" }
+    "./integrations/awr": {
+      "types": "./dist/integrations/awr/index.d.ts",
+      "default": "./dist/integrations/awr/index.js"
+    },
+    "./authoring": {
+      "types": "./dist/authoring/index.d.ts",
+      "default": "./dist/authoring/index.js"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol/index.d.ts",
+      "default": "./dist/protocol/index.js"
+    },
+    "./coordination": {
+      "types": "./dist/core/coordination.d.ts",
+      "default": "./dist/core/coordination.js"
+    }
   },
-  "files": ["dist", "schema", "samples", "docs/cleanup-followups.md", "docs/source-review.md", "docs/source-promotion.md", "docs/git-source-resolution.md", "docs/git-object-proof.md", "docs/local-review-store.md", "docs/local-scenario-store.md", "docs/local-execution-recovery.md", "docs/qualification-registration.md", "docs/qualification-results.md", "docs/replay-assessment.md", "docs/scenario-activation.md", "docs/scenario-structure.md", "docs/verified-bundles.md", "docs/developer-ux.md", "docs/architecture.md", "docs/browser-driver.md", "docs/portable-environments.md", "docs/examples/portable-environments", "docs/native-jobs.md", "docs/result-sink.md", "docs/awr-delivery.md", "docs/work-report-attachment.md", "docs/mcp-driver.md", "conformance/coordination-vectors.json", "LICENSE", "README.md", "docs/images/ui-run.png"],
+  "files": [
+    "dist",
+    "schema",
+    "samples",
+    "docs/getting-started.md",
+    "docs/agent-guide.md",
+    "docs/local-execution-recovery.md",
+    "docs/verified-bundles.md",
+    "docs/browser-driver.md",
+    "docs/native-jobs.md",
+    "docs/mcp-driver.md",
+    "LICENSE",
+    "README.md",
+    "docs/result-sink.md",
+    "docs/git-object-proof.md"
+  ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json && node scripts/copy-samples.mjs",
     "typecheck": "tsc --project tsconfig.json --noEmit && tsc --project tsconfig.container.json --noEmit",
@@ -34,8 +69,18 @@
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },
-  "peerDependencies": { "@modelcontextprotocol/sdk": "1.32.1", "@useorgx/agent-work-receipt": "0.3.0" },
-  "peerDependenciesMeta": { "@modelcontextprotocol/sdk": { "optional": true }, "@useorgx/agent-work-receipt": { "optional": true } },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@useorgx/agent-work-receipt": "0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@useorgx/agent-work-receipt": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
     "@useorgx/agent-work-receipt": "0.3.0",
@@ -43,5 +88,13 @@
     "tsx": "4.23.15",
     "typescript": "5.9.3",
     "vitest": "5.0.3"
-  }
+  },
+  "keywords": [
+    "testing",
+    "workflow",
+    "verification",
+    "cli",
+    "evidence"
+  ],
+  "homepage": "https://www.npmjs.com/package/tracegrove"
 }

package/conformance/coordination-vectors.json

@@ -1,377 +0,0 @@
-{
-  "schemaVersion": 1,
-  "vectors": [
-    {
-      "id": "reserve",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 1,
-        "generation": 0,
-        "budgetCents": 500,
-        "leases": []
-      },
-      "command": {
-        "type": "reserve",
-        "attemptId": "attempt:1",
-        "workerId": "worker:1",
-        "personaId": "persona:1",
-        "reservedCents": 300,
-        "ttlMs": 300000
-      },
-      "observedAt": 1000,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 2,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 301000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": [
-        "attempt:1"
-      ]
-    },
-    {
-      "id": "effect",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 2,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 301000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "command": {
-        "type": "effect",
-        "attemptId": "attempt:1",
-        "workerId": "worker:1",
-        "generation": 1,
-        "effectId": "effect:1"
-      },
-      "observedAt": 2000,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 3,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 301000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": []
-    },
-    {
-      "id": "heartbeat",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 3,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 301000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "command": {
-        "type": "heartbeat",
-        "attemptId": "attempt:1",
-        "workerId": "worker:1",
-        "generation": 1,
-        "ttlMs": 300000
-      },
-      "observedAt": 3000,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 4,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 303000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": [
-        "attempt:1"
-      ]
-    },
-    {
-      "id": "shared_budget",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 4,
-        "generation": 1,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 303000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "command": {
-        "type": "reserve",
-        "attemptId": "attempt:2",
-        "workerId": "worker:1",
-        "personaId": "persona:2",
-        "reservedCents": 200,
-        "ttlMs": 300000
-      },
-      "observedAt": 4000,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 5,
-        "generation": 2,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 303000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          },
-          {
-            "attemptId": "attempt:2",
-            "workerId": "worker:1",
-            "personaId": "persona:2",
-            "generation": 2,
-            "expiresAt": 304000,
-            "reservedCents": 200,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": [
-        "attempt:2"
-      ]
-    },
-    {
-      "id": "recover",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 5,
-        "generation": 2,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:1",
-            "personaId": "persona:1",
-            "generation": 1,
-            "expiresAt": 303000,
-            "reservedCents": 300,
-            "state": "active",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          },
-          {
-            "attemptId": "attempt:2",
-            "workerId": "worker:1",
-            "personaId": "persona:2",
-            "generation": 2,
-            "expiresAt": 304000,
-            "reservedCents": 200,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "command": {
-        "type": "recover",
-        "attemptId": "attempt:1",
-        "workerId": "worker:2",
-        "ttlMs": 300000
-      },
-      "observedAt": 303000,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 6,
-        "generation": 3,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:2",
-            "personaId": "persona:1",
-            "generation": 3,
-            "expiresAt": 603000,
-            "reservedCents": 300,
-            "state": "reconciling",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          },
-          {
-            "attemptId": "attempt:2",
-            "workerId": "worker:1",
-            "personaId": "persona:2",
-            "generation": 2,
-            "expiresAt": 304000,
-            "reservedCents": 200,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": [
-        "attempt:1"
-      ]
-    },
-    {
-      "id": "reconcile_heartbeat",
-      "before": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 6,
-        "generation": 3,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:2",
-            "personaId": "persona:1",
-            "generation": 3,
-            "expiresAt": 603000,
-            "reservedCents": 300,
-            "state": "reconciling",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          },
-          {
-            "attemptId": "attempt:2",
-            "workerId": "worker:1",
-            "personaId": "persona:2",
-            "generation": 2,
-            "expiresAt": 304000,
-            "reservedCents": 200,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "command": {
-        "type": "heartbeat",
-        "attemptId": "attempt:1",
-        "workerId": "worker:2",
-        "generation": 3,
-        "ttlMs": 300000
-      },
-      "observedAt": 303100,
-      "after": {
-        "scopeId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
-        "version": 7,
-        "generation": 3,
-        "budgetCents": 500,
-        "leases": [
-          {
-            "attemptId": "attempt:1",
-            "workerId": "worker:2",
-            "personaId": "persona:1",
-            "generation": 3,
-            "expiresAt": 603100,
-            "reservedCents": 300,
-            "state": "reconciling",
-            "effectIds": [
-              "effect:1"
-            ],
-            "cleanupProof": null
-          },
-          {
-            "attemptId": "attempt:2",
-            "workerId": "worker:1",
-            "personaId": "persona:2",
-            "generation": 2,
-            "expiresAt": 304000,
-            "reservedCents": 200,
-            "state": "active",
-            "effectIds": [],
-            "cleanupProof": null
-          }
-        ]
-      },
-      "clockUpdatedAttempts": [
-        "attempt:1"
-      ]
-    }
-  ]
-}