martin-loop 0.1.5 → 1.3.0

package/docs/oss/EXAMPLES.md

@@ -1,134 +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. 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.
+# 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,5 +1,5 @@
 {
-  "generatedAt": "2026-05-11T21:47:36.834Z",
+  "generatedAt": "2026-05-12T17:46:27.776Z",
   "verdict": "go",
   "publicSurface": {
     "packageName": "martin-loop",

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

@@ -1,6 +1,6 @@
 # Martin Loop Phase 13 OSS Core Boundary
 
-Generated: 2026-05-11T21:47:36.834Z
+Generated: 2026-05-12T17:46:27.776Z
 
 ## Verdict
 **GO**

package/docs/oss/QUICKSTART.md

@@ -1,165 +1,170 @@
-# Quickstart
-
-This quickstart is intentionally conservative. It is written for a fresh engineer validating the current Phase 13 release-candidate state, not for a hypothetical future public release.
-
-## Public launch target vs current RC path
-
-The frozen public launch target is:
-
-- `npm install martin-loop`
-- `npx martin-loop ...`
-- `import { MartinLoop } from "martin-loop"`
-- `npx @martinloop/mcp`
-
-That runtime launch surface is implemented in the root package facade and smoke-validated from a clean temporary install. The MCP package shape is also smoke-validated from a packed tarball. This quickstart still documents the honest RC-from-source path because public registry publication is a separate release step.
-
-## Prerequisites
-
-- Node.js 20+ recommended
-- `pnpm` 10.x
-- A clean local checkout of this repo
-
-Optional for live runs:
-
-- Claude Code CLI for the Claude adapter path
-- OpenAI Codex CLI plus credentials for the Codex adapter path
-
-## Install and build
-
-From the repo root:
-
-```bash
-pnpm install
-pnpm build
-```
-
-## Run the RC validation matrix
-
-```bash
-pnpm rc:validate
-```
-
-What this does:
-
-- creates an isolated temporary home or profile directory
-- points Martin run artifacts at that clean location
-- runs the current build, lint, test, benchmark, and certification matrix
-- writes step logs into a temp `martin-rc-validation-*` directory
-
-Use this when you want to answer, "Can a fresh environment still reproduce the current RC baseline?"
-
-## RC gate commands
-
-The current Phase 13 RC gate is made of these commands:
-
-- `pnpm oss:validate`
-- `pnpm public:smoke`
-- `pnpm repo:smoke`
-- `pnpm rc:validate`
-- `pnpm pilot:prep:validate`
-- `pnpm release:matrix:local`
-
-Recommended order for a fresh local reviewer:
-
-```bash
-pnpm oss:validate
-pnpm public:smoke
-pnpm repo:smoke
-pnpm rc:validate
-pnpm release:matrix:local
-```
-
-`pnpm release:matrix:local` runs the full local OS lane for the current machine. The repository also defines Windows, macOS, and Linux CI lanes in `.github/workflows/phase13-release-matrix.yml`.
-
-## Stub-safe CLI run
-
-This is the safest first run because it avoids real provider spend.
-
-### PowerShell
-
-```powershell
-$env:MARTIN_LIVE='false'
-pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
-Remove-Item Env:MARTIN_LIVE
-```
-
-### Bash
-
-```bash
-MARTIN_LIVE=false pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
-```
-
-This path uses the stub adapter and still exercises the loop, persistence, and policy surfaces.
-
-## Config-driven run
-
-The repo ships an example config at `martin.config.example.yaml`.
-
-Martin auto-looks for `martin.config.yaml` in the invocation root, or you can pass `--config <path>`.
-
-Example:
-
-```bash
-pnpm run:cli -- run --config martin.config.example.yaml --objective "Run with repo defaults" --verify "pnpm --filter @martin/core test"
-```
-
-## Inspect a saved run
-
-Martin persists runs under `~/.martin/runs/` by default, or under `MARTIN_RUNS_DIR` if you override it.
-
-```bash
-pnpm run:cli -- inspect --file path/to/loop-record.json
-```
-
-For persisted run folders, inspect the `contract.json`, `state.json`, `ledger.jsonl`, and `artifacts/attempt-XXX/` files together. Those artifacts are the source of truth for runtime behavior.
-
-## MCP server
-
-The publish-ready MCP install target is:
-
-```bash
-npx @martinloop/mcp
-```
-
-Claude Code one-line install:
-
-```bash
-# macOS/Linux
-claude mcp add --scope user martin-loop -- npx @martinloop/mcp
-
-# Windows PowerShell/cmd
-claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
-```
-
-Official MCP Registry publication has an extra metadata step beyond npm packaging. Do not mark `@martinloop/mcp` registry-ready unless both of these exist and match:
-
-- `packages/mcp/package.json` with `mcpName`
-- `packages/mcp/server.json` with the official server metadata
-
-After publishing `@martinloop/mcp` to npm, run the official registry publisher from `packages/mcp`:
-
-```bash
-mcp-publisher login github
-mcp-publisher publish
-```
-
-For repo-local verification from source:
-
-```bash
-pnpm --filter @martinloop/mcp build
-pnpm --filter @martinloop/mcp smoke:pack
-node packages/mcp/dist/server.js
-```
-
-The current MCP tools are:
-
-- `martin_run`
-- `martin_inspect`
-- `martin_status`
-
-## Notes for reviewers
-
-- Fresh-home behavior matters. Do not rely only on a long-lived `~/.martin` directory.
-- Exact-versus-estimated cost labels are meaningful and should not be merged in docs or dashboards.
-- The repo contains control-plane code, but the public OSS boundary is still being finalized during Phase 13.
-- The benchmark harness remains a workspace-level RC surface; `martin bench` is not part of the publishable CLI boundary yet.
+# Quickstart
+
+This quickstart is intentionally conservative. It is written for a fresh engineer validating the active Phase 15 release lane, not for a hypothetical future public release.
+
+## Public launch target vs current RC path
+
+The frozen public launch target is:
+
+- `npm install martin-loop`
+- `npx martin-loop ...`
+- `import { MartinLoop } from "martin-loop"`
+- `npx @martinloop/mcp`
+
+That runtime launch surface is implemented in the root package facade and smoke-validated from a clean temporary install. The MCP package shape is also smoke-validated from a packed tarball. This quickstart still documents the honest RC-from-source path because public registry publication is a later release step.
+
+## Prerequisites
+
+- Node.js 20+ recommended
+- `pnpm` 10.x
+- A clean local checkout of this repo
+
+Optional for live runs:
+
+- Claude Code CLI for the Claude adapter path
+- OpenAI Codex CLI plus credentials for the Codex adapter path
+
+## Install and build
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Run the RC validation matrix
+
+```bash
+pnpm rc:validate
+```
+
+What this does:
+
+- creates an isolated temporary home or profile directory
+- points Martin run artifacts at that clean location
+- runs the current build, lint, test, benchmark, and certification matrix
+- writes step logs into a temp `martin-rc-validation-*` directory
+
+Use this when you want to answer, "Can a fresh environment still reproduce the current RC baseline?"
+
+## RC gate commands
+
+The current Phase 13 RC gate is made of these commands:
+
+- `pnpm oss:validate`
+- `pnpm public:smoke`
+- `pnpm mcp:published:smoke`
+- `pnpm repo:smoke`
+- `pnpm rc:validate`
+- `pnpm pilot:prep:validate`
+- `pnpm release:matrix:local`
+
+Recommended order for a fresh local reviewer:
+
+```bash
+pnpm oss:validate
+pnpm public:smoke
+pnpm mcp:published:smoke
+pnpm repo:smoke
+pnpm rc:validate
+pnpm release:matrix:local
+```
+
+`pnpm release:matrix:local` runs the full local OS lane for the current machine. The repository also defines Windows, macOS, and Linux CI lanes in `.github/workflows/phase13-release-matrix.yml`.
+
+## Stub-safe CLI run
+
+This is the safest first run because it avoids real provider spend.
+
+### PowerShell
+
+```powershell
+$env:MARTIN_LIVE='false'
+pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
+Remove-Item Env:MARTIN_LIVE
+```
+
+### Bash
+
+```bash
+MARTIN_LIVE=false pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
+```
+
+This path uses the stub adapter and still exercises the loop, persistence, and policy surfaces.
+
+## Config-driven run
+
+The repo ships an example config at `martin.config.example.yaml`.
+
+Martin auto-looks for `martin.config.yaml` in the invocation root, or you can pass `--config <path>`.
+
+Example:
+
+```bash
+pnpm run:cli -- run --config martin.config.example.yaml --objective "Run with repo defaults" --verify "pnpm --filter @martin/core test"
+```
+
+## Inspect a saved run
+
+Martin persists runs under `~/.martin/runs/` by default, or under `MARTIN_RUNS_DIR` if you override it.
+
+```bash
+pnpm run:cli -- inspect --file path/to/loop-record.json
+```
+
+For persisted run folders, inspect the `contract.json`, `state.json`, `ledger.jsonl`, and `artifacts/attempt-XXX/` files together. Those artifacts are the source of truth for runtime behavior.
+
+## MCP server
+
+The publish-ready MCP install target is:
+
+```bash
+npx @martinloop/mcp
+```
+
+Claude Code one-line install:
+
+```bash
+# macOS/Linux
+claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+
+# Windows PowerShell/cmd
+claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
+```
+
+Official MCP Registry publication has an extra metadata step beyond npm packaging. Do not mark `@martinloop/mcp` registry-ready unless both of these exist and match:
+
+- `packages/mcp/package.json` with `mcpName`
+- `packages/mcp/server.json` with the official server metadata
+
+After publishing `@martinloop/mcp` to npm, run the official registry publisher from `packages/mcp`:
+
+```bash
+mcp-publisher login github
+mcp-publisher publish
+```
+
+For repo-local verification from source:
+
+```bash
+pnpm --filter @martinloop/mcp lint
+pnpm --filter @martinloop/mcp test
+pnpm --filter @martinloop/mcp build
+pnpm --filter @martinloop/mcp smoke:pack
+pnpm --filter @martinloop/mcp smoke:published
+node packages/mcp/dist/server.js
+```
+
+The current MCP tools are:
+
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
+
+## Notes for reviewers
+
+- Fresh-home behavior matters. Do not rely only on a long-lived `~/.martin` directory.
+- Exact-versus-estimated cost labels are meaningful and should not be merged in docs or dashboards.
+- The repo contains control-plane code, but the public OSS boundary is still being finalized during Phase 13.
+- The benchmark harness remains a workspace-level RC surface; `martin bench` is not part of the publishable CLI boundary yet.