martin-loop 0.1.4 → 0.1.5

package/docs/oss/CLAUDE-CODE-WALKTHROUGH.md

@@ -0,0 +1,142 @@
+# Claude Code Walkthrough
+
+This walkthrough shows how to put MartinLoop around a Claude Code-driven coding task so the run has a budget, a verifier gate, an explicit stop reason, and an inspectable run record.
+
+Back to the repo overview: [README.md](../../README.md)
+
+## What MartinLoop adds around Claude Code
+
+Claude Code is the coding engine. MartinLoop is the governance layer around it.
+
+- **Budget**: hard USD, token, and iteration limits decide how far the run can go.
+- **Verifier**: the run only counts as complete when the post-run verification command passes.
+- **Stop reason**: MartinLoop records why the run stopped, such as `completed`, `budget_exit`, or `human_escalation`.
+- **Run record**: each run appends a JSONL record under `~/.martin/runs/` so you can inspect it later.
+
+## Prerequisites
+
+- Node.js 20+
+- `pnpm` 10.x if you are running from this repo
+- Claude Code CLI installed and authenticated
+- A repo you want Claude Code to work in
+
+## Install MartinLoop
+
+For the published CLI:
+
+```bash
+npm install -g martin-loop
+```
+
+For repo-local development in this monorepo:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Simple local run
+
+Run MartinLoop with the default Claude adapter and a verifier command:
+
+```bash
+martin run "fix the auth regression" \
+  --engine claude \
+  --budget 3.00 \
+  --verify "pnpm test"
+```
+
+What happens:
+
+- MartinLoop hands the objective to Claude Code
+- Claude Code attempts the work
+- MartinLoop runs the verifier command
+- the loop only finishes as `completed` when the agent result and verifier both pass
+
+## Budget example
+
+Use a hard cap and a smaller iteration budget when you want Claude Code to stay tightly bounded:
+
+```bash
+martin run "tighten the login retry handling" \
+  --engine claude \
+  --budget 2.00 \
+  --soft-limit-usd 1.25 \
+  --max-iterations 2 \
+  --max-tokens 20000 \
+  --verify "pnpm --filter @martin/core test"
+```
+
+This is the key MartinLoop value-add for Claude Code workflows: the agent can keep trying, but only inside a contract you can review before the spend drifts.
+
+## Verifier example
+
+Use a verifier that matches the exact scope of the change:
+
+```bash
+martin run "update the OSS quickstart wording" \
+  --engine claude \
+  --cwd . \
+  --allow-path README.md \
+  --allow-path docs/oss/** \
+  --deny-path apps/control-plane/** \
+  --accept "Only documentation files may change" \
+  --verify "pnpm --filter @martin/core test"
+```
+
+The verifier gate matters because Claude Code producing a patch is not the same thing as the repo being in a valid state.
+
+## Inspect example
+
+After a run, inspect the persisted JSONL record:
+
+```bash
+martin inspect --file ~/.martin/runs/<workspaceId>.jsonl
+```
+
+Look for:
+
+- the final lifecycle state and stop reason
+- budget and token totals
+- verifier outcome
+- attempt count and failure classification
+
+## Safe repo-local dry run
+
+If you want to validate the MartinLoop flow without real model spend, use stub mode first:
+
+### PowerShell
+
+```powershell
+$env:MARTIN_LIVE='false'
+$repoRoot = (Get-Location).Path
+pnpm run:cli -- run `
+  --cwd $repoRoot `
+  --objective "Summarize the current runtime state" `
+  --verify "pnpm --filter @martin/core test"
+Remove-Item Env:MARTIN_LIVE
+```
+
+This does not invoke Claude Code, and it will usually end with a recorded non-success stop reason because no live provider request was attempted. That is still the fastest way to confirm the loop, persistence, and verifier path are wired correctly before you switch to a live Claude run.
+
+## Common errors and troubleshooting
+
+### `claude` is not found
+
+MartinLoop can only use the Claude adapter when the Claude Code CLI is installed and available on `PATH`. Confirm the CLI itself works before you debug MartinLoop.
+
+### The run stops with `budget_exit`
+
+The configured budget, iteration limit, or token ceiling was too tight for the requested task. Either narrow the task or raise the budget intentionally.
+
+### The verifier fails even though Claude Code produced a patch
+
+That means MartinLoop did its job. The patch was attempted, but the repo did not reach a verified state. Tighten the scope, change the verifier, or ask Claude Code to address the failing checks directly.
+
+### The run exits with `human_escalation`
+
+That usually means MartinLoop detected a path that should not proceed unattended, such as an unsafe verifier or a control boundary that needs review.
+
+### `martin inspect` cannot find the file
+
+Run another task first, or point `inspect` at the correct JSONL file under `~/.martin/runs/`.

package/docs/oss/EXAMPLES.md

@@ -1,126 +1,134 @@
-# Examples
-
-These examples are grounded in the current CLI and MCP surfaces in this repo. Where an example depends on a real provider path, it is labeled that way explicitly.
-
-These are still primarily repo-local RC examples. The root `martin-loop` package facade is now real and smoke-validated, but registry publication remains a later release step.
-
-## 1. Stub-backed hello world
-
-Use this when you want a safe first pass through the loop without real model spend.
-
-### PowerShell
-
-```powershell
-$env:MARTIN_LIVE='false'
-pnpm run:cli -- run `
-  --workspace ws_demo `
-  --project proj_demo `
-  --objective "Describe the current Martin run lifecycle in one paragraph" `
-  --verify "pnpm --filter @martin/core test"
-Remove-Item Env:MARTIN_LIVE
-```
-
-Why this is useful:
-
-- exercises `runMartin`
-- writes a real loop record and artifacts
-- avoids external provider dependencies
-
-## 2. Repo-backed task with explicit scope
-
-Use allow and deny paths so the task contract is narrow and reviewable.
-
-```bash
-pnpm run:cli -- run \
-  --cwd . \
-  --objective "Tighten README wording for the OSS quickstart" \
-  --verify "pnpm --filter @martin/core test" \
-  --allow-path README.md \
-  --allow-path docs/oss/** \
-  --deny-path apps/control-plane/** \
-  --accept "Only update documentation files" \
-  --accept "Do not modify runtime code"
-```
-
-What this demonstrates:
-
-- repo root selection with `--cwd`
-- scoped file-edit boundaries
-- acceptance criteria injection into the task contract
-
-## 3. Safety-block example
-
-This example is expected to block before execution because the verifier command is unsafe.
-
-```bash
-pnpm run:cli -- run \
-  --objective "Try to run an unsafe verifier" \
-  --verify "rm -rf ."
-```
-
-Expected behavior:
-
-- the leash blocks the verifier command before adapter execution
-- the run exits through a safety-oriented path rather than pretending the command was acceptable
-- the attempt artifact set includes a persisted leash artifact when applicable
-
-The point of this example is not that `rm` exists on every machine. The point is that the raw verifier text is evaluated before the process would be allowed to run.
-
-## 4. Budget-constrained live run
-
-This is a live-provider example. Only use it when you have the relevant CLI and credentials configured.
-
-```bash
-pnpm run:cli -- run \
-  --engine codex \
-  --model o3 \
-  --objective "Refactor the CLI argument parser for clarity" \
-  --verify "pnpm --filter @martin/cli test" \
-  --budget-usd 2 \
-  --soft-limit-usd 1 \
-  --max-iterations 2
-```
-
-What to review afterward:
-
-- admission and settlement events in `ledger.jsonl`
-- cost provenance labels in the run artifacts
-- whether the loop stopped for completion, budget pressure, or lack of progress
-
-## 5. MCP invocation shape
-
-The MCP server exposes `martin_run`, `martin_inspect`, and `martin_status`.
-
-Example `martin_run` payload:
-
-```json
-{
-  "objective": "Tighten the local dashboard copy",
-  "workingDirectory": ".",
-  "engine": "claude",
-  "verificationPlan": ["pnpm --filter @martin/control-plane test"],
-  "maxUsd": 5,
-  "maxIterations": 2,
-  "maxTokens": 20000,
-  "workspaceId": "ws_mcp",
-  "projectId": "proj_mcp"
-}
-```
-
-## 6. What to inspect in artifacts
-
-For a repo-backed attempt, look at:
-
-- `contract.json`
-- `state.json`
-- `ledger.jsonl`
-- `artifacts/attempt-XXX/compiled-context.json`
-- `artifacts/attempt-XXX/diff.patch`
-- `artifacts/attempt-XXX/grounding-scan.json`
-- `artifacts/attempt-XXX/leash.json`
-- `artifacts/attempt-XXX/patch-score.json`
-- `artifacts/attempt-XXX/patch-decision.json`
-- `artifacts/attempt-XXX/rollback-boundary.json`
-- `artifacts/attempt-XXX/rollback-outcome.json`
-
-Those files are the evidence trail that backs the runtime’s claims.
+# Examples
+
+These examples are grounded in the current CLI and MCP surfaces in this repo. Where an example depends on a real provider path, it is labeled that way explicitly.
+
+These are still primarily repo-local RC examples. The root `martin-loop` package facade is now real and smoke-validated, but registry publication remains a later release step.
+
+## 1. Stub-backed hello world
+
+Use this when you want a safe first pass through the loop without real model spend.
+
+### PowerShell
+
+```powershell
+$env:MARTIN_LIVE='false'
+pnpm run:cli -- run `
+  --workspace ws_demo `
+  --project proj_demo `
+  --objective "Describe the current Martin run lifecycle in one paragraph" `
+  --verify "pnpm --filter @martin/core test"
+Remove-Item Env:MARTIN_LIVE
+```
+
+Why this is useful:
+
+- exercises `runMartin`
+- writes a real loop record and artifacts
+- avoids external provider dependencies
+
+## 2. Repo-backed task with explicit scope
+
+Use allow and deny paths so the task contract is narrow and reviewable.
+
+```bash
+pnpm run:cli -- run \
+  --cwd . \
+  --objective "Tighten README wording for the OSS quickstart" \
+  --verify "pnpm --filter @martin/core test" \
+  --allow-path README.md \
+  --allow-path docs/oss/** \
+  --deny-path apps/control-plane/** \
+  --accept "Only update documentation files" \
+  --accept "Do not modify runtime code"
+```
+
+What this demonstrates:
+
+- repo root selection with `--cwd`
+- scoped file-edit boundaries
+- acceptance criteria injection into the task contract
+
+## 3. Safety-block example
+
+This example is expected to block before execution because the verifier command is unsafe.
+
+```bash
+pnpm run:cli -- run \
+  --objective "Try to run an unsafe verifier" \
+  --verify "rm -rf ."
+```
+
+Expected behavior:
+
+- the leash blocks the verifier command before adapter execution
+- the run exits through a safety-oriented path rather than pretending the command was acceptable
+- the attempt artifact set includes a persisted leash artifact when applicable
+
+The point of this example is not that `rm` exists on every machine. The point is that the raw verifier text is evaluated before the process would be allowed to run.
+
+## 4. Budget-constrained live run
+
+This is a live-provider example. Only use it when you have the relevant CLI and credentials configured.
+
+```bash
+pnpm run:cli -- run \
+  --engine codex \
+  --model o3 \
+  --objective "Refactor the CLI argument parser for clarity" \
+  --verify "pnpm --filter @martin/cli test" \
+  --budget-usd 2 \
+  --soft-limit-usd 1 \
+  --max-iterations 2
+```
+
+What to review afterward:
+
+- admission and settlement events in `ledger.jsonl`
+- cost provenance labels in the run artifacts
+- whether the loop stopped for completion, budget pressure, or lack of progress
+
+## 5. MCP invocation shape
+
+The MCP server exposes `martin_run`, `martin_inspect`, and `martin_status`.
+
+Example `martin_run` payload:
+
+```json
+{
+  "objective": "Tighten the local dashboard copy",
+  "workingDirectory": ".",
+  "engine": "claude",
+  "verificationPlan": ["pnpm --filter @martin/control-plane test"],
+  "maxUsd": 5,
+  "maxIterations": 2,
+  "maxTokens": 20000,
+  "workspaceId": "ws_mcp",
+  "projectId": "proj_mcp"
+}
+```
+
+## 6. GitHub Actions budget gate example
+
+See [`examples/github-actions-budget-gate/`](../../examples/github-actions-budget-gate/) for a CI-safe example that runs MartinLoop with a budget cap, an explicit verifier, and an uploaded JSONL run record artifact.
+
+## 7. OpenCode-style adapter example
+
+If you want a runnable, no-credentials-required adapter sketch for another coding runtime, see [`examples/opencode-adapter/`](../../examples/opencode-adapter/). It shows how to keep MartinLoop's budget, verifier, and JSONL record shape stable around an OpenCode-style workflow without claiming a native adapter already exists.
+
+## 8. What to inspect in artifacts
+
+For a repo-backed attempt, look at:
+
+- `contract.json`
+- `state.json`
+- `ledger.jsonl`
+- `artifacts/attempt-XXX/compiled-context.json`
+- `artifacts/attempt-XXX/diff.patch`
+- `artifacts/attempt-XXX/grounding-scan.json`
+- `artifacts/attempt-XXX/leash.json`
+- `artifacts/attempt-XXX/patch-score.json`
+- `artifacts/attempt-XXX/patch-decision.json`
+- `artifacts/attempt-XXX/rollback-boundary.json`
+- `artifacts/attempt-XXX/rollback-outcome.json`
+
+Those files are the evidence trail that backs the runtime’s claims.

package/docs/oss/OSS-BOUNDARY-REPORT.json

@@ -1,113 +1,109 @@
-{
-  "generatedAt": "2026-04-23T15:03:09.849Z",
-  "verdict": "go",
-  "publicSurface": {
-    "packageName": "martin-loop",
-    "canonicalPackageManager": "npm",
-    "installCommand": "npm install martin-loop",
-    "npxCommand": "npx martin-loop",
-    "sdkImportPath": "martin-loop",
-    "supportsNpxCommand": true,
-    "supportsSdkImport": true
-  },
-  "ossCorePackages": [
-    {
-      "name": "@martin/contracts",
-      "path": "packages/contracts",
-      "private": true,
-      "publishAccess": null,
-      "workspaceDependencies": [],
-      "classification": "oss_core",
-      "classificationReason": "Intended Phase 13 OSS core surface."
-    },
-    {
-      "name": "@martin/core",
-      "path": "packages/core",
-      "private": true,
-      "publishAccess": null,
-      "workspaceDependencies": [
-        "@martin/contracts"
-      ],
-      "classification": "oss_core",
-      "classificationReason": "Intended Phase 13 OSS core surface."
-    },
-    {
-      "name": "@martin/adapters",
-      "path": "packages/adapters",
-      "private": true,
-      "publishAccess": null,
-      "workspaceDependencies": [
-        "@martin/core"
-      ],
-      "classification": "oss_core",
-      "classificationReason": "Intended Phase 13 OSS core surface."
-    },
-    {
-      "name": "@martin/cli",
-      "path": "packages/cli",
-      "private": false,
-      "publishAccess": "public",
-      "workspaceDependencies": [
-        "@martin/adapters",
-        "@martin/contracts",
-        "@martin/core"
-      ],
-      "classification": "oss_core",
-      "classificationReason": "Intended Phase 13 OSS core surface."
-    },
-    {
-      "name": "@martin/mcp",
-      "path": "packages/mcp",
-      "private": false,
-      "publishAccess": "public",
-      "workspaceDependencies": [
-        "@martin/adapters",
-        "@martin/contracts",
-        "@martin/core"
-      ],
-      "classification": "oss_core",
-      "classificationReason": "Intended Phase 13 OSS core surface."
-    }
-  ],
-  "nonOssWorkspacePackages": [
-    {
-      "name": "@martin/control-plane",
-      "path": "apps/control-plane",
-      "private": true,
-      "publishAccess": null,
-      "workspaceDependencies": [
-        "@martin/contracts"
-      ],
-      "classification": "non_oss_workspace",
-      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
-    },
-    {
-      "name": "@martin/benchmarks",
-      "path": "benchmarks",
-      "private": true,
-      "publishAccess": null,
-      "workspaceDependencies": [
-        "@martin/adapters",
-        "@martin/contracts",
-        "@martin/core"
-      ],
-      "classification": "non_oss_workspace",
-      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
-    }
-  ],
-  "localOnlySurfaces": [
-    {
-      "path": "apps/local-dashboard",
-      "reason": "Local read-model viewer that is not yet packaged as a publishable OSS workspace."
-    }
-  ],
-  "dependencyLeaks": [],
-  "summary": {
-    "ossCoreCount": 5,
-    "nonOssWorkspaceCount": 2,
-    "localOnlySurfaceCount": 1,
-    "dependencyLeakCount": 0,
-    "privateOssCoreCount": 3,
-    "publishReadyOssCoreCount": 2
-  }
-}
+{
+  "generatedAt": "2026-05-11T21:47:36.834Z",
+  "verdict": "go",
+  "publicSurface": {
+    "packageName": "martin-loop",
+    "canonicalPackageManager": "npm",
+    "installCommand": "npm install martin-loop",
+    "npxCommand": "npx martin-loop",
+    "sdkImportPath": "martin-loop",
+    "supportsNpxCommand": true,
+    "supportsSdkImport": true
+  },
+  "ossCorePackages": [
+    {
+      "name": "@martin/contracts",
+      "path": "packages/contracts",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/core",
+      "path": "packages/core",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/contracts"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/adapters",
+      "path": "packages/adapters",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/core"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martin/cli",
+      "path": "packages/cli",
+      "private": false,
+      "publishAccess": "public",
+      "workspaceDependencies": [
+        "@martin/adapters",
+        "@martin/contracts",
+        "@martin/core"
+      ],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    },
+    {
+      "name": "@martinloop/mcp",
+      "path": "packages/mcp",
+      "private": false,
+      "publishAccess": "public",
+      "workspaceDependencies": [],
+      "classification": "oss_core",
+      "classificationReason": "Intended Phase 13 OSS core surface."
+    }
+  ],
+  "nonOssWorkspacePackages": [
+    {
+      "name": "@martin/control-plane",
+      "path": "apps/control-plane",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/contracts"
+      ],
+      "classification": "non_oss_workspace",
+      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
+    },
+    {
+      "name": "@martin/benchmarks",
+      "path": "benchmarks",
+      "private": true,
+      "publishAccess": null,
+      "workspaceDependencies": [
+        "@martin/adapters",
+        "@martin/contracts",
+        "@martin/core"
+      ],
+      "classification": "non_oss_workspace",
+      "classificationReason": "Managed or RC-only workspace surface that stays out of the initial OSS boundary."
+    }
+  ],
+  "localOnlySurfaces": [
+    {
+      "path": "apps/local-dashboard",
+      "reason": "Local read-model viewer that is not yet packaged as a publishable OSS workspace."
+    }
+  ],
+  "dependencyLeaks": [],
+  "summary": {
+    "ossCoreCount": 5,
+    "nonOssWorkspaceCount": 2,
+    "localOnlySurfaceCount": 1,
+    "dependencyLeakCount": 0,
+    "privateOssCoreCount": 3,
+    "publishReadyOssCoreCount": 2
+  }
+}