martin-loop 0.1.4 → 0.1.5

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

@@ -1,48 +1,48 @@
-# Martin Loop Phase 13 OSS Core Boundary
-
-Generated: 2026-04-23T15:03:09.849Z
-
-## Verdict
-**GO**
-
-## Summary
-- Public package target: martin-loop
-- Canonical public package manager: npm
-- Intended OSS core packages: 5
-- Non-OSS workspace packages: 2
-- Local-only surfaces: 1
-- Private OSS-core packages still gated from publish: 3
-- OSS-core packages already publish-configured: 2
-- Dependency leaks: 0
-- No workspace dependency leaks detected between the intended OSS core and the non-OSS workspace surfaces.
-
-## Public Package Surface
-- Install target: `npm install martin-loop`
-- CLI target: `npx martin-loop`
-- SDK target: `import { MartinLoop } from 'martin-loop'`
-- Root `npx martin-loop` support shipped: yes
-- Root SDK import shipped: yes
-
-## Intended OSS Core Packages
-| Package | Path | Private | Publish Access | Workspace Deps |
-|---|---|---|---|---|
-| @martin/contracts | packages/contracts | yes | n/a | none |
-| @martin/core | packages/core | yes | n/a | @martin/contracts |
-| @martin/adapters | packages/adapters | yes | n/a | @martin/core |
-| @martin/cli | packages/cli | no | public | @martin/adapters, @martin/contracts, @martin/core |
-| @martin/mcp | packages/mcp | no | public | @martin/adapters, @martin/contracts, @martin/core |
-
-## Non-OSS Workspace Packages
-| Package | Path | Reason |
-|---|---|---|
-| @martin/control-plane | apps/control-plane | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
-| @martin/benchmarks | benchmarks | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
-
-## Local-Only Surfaces
-| Path | Reason |
-|---|---|
-| apps/local-dashboard | Local read-model viewer that is not yet packaged as a publishable OSS workspace. |
-
-## Dependency Leak Review
-- No workspace dependency leaks detected.
-
+# Martin Loop Phase 13 OSS Core Boundary
+
+Generated: 2026-05-11T21:47:36.834Z
+
+## Verdict
+**GO**
+
+## Summary
+- Public package target: martin-loop
+- Canonical public package manager: npm
+- Intended OSS core packages: 5
+- Non-OSS workspace packages: 2
+- Local-only surfaces: 1
+- Private OSS-core packages still gated from publish: 3
+- OSS-core packages already publish-configured: 2
+- Dependency leaks: 0
+- No workspace dependency leaks detected between the intended OSS core and the non-OSS workspace surfaces.
+
+## Public Package Surface
+- Install target: `npm install martin-loop`
+- CLI target: `npx martin-loop`
+- SDK target: `import { MartinLoop } from 'martin-loop'`
+- Root `npx martin-loop` support shipped: yes
+- Root SDK import shipped: yes
+
+## Intended OSS Core Packages
+| Package | Path | Private | Publish Access | Workspace Deps |
+|---|---|---|---|---|
+| @martin/contracts | packages/contracts | yes | n/a | none |
+| @martin/core | packages/core | yes | n/a | @martin/contracts |
+| @martin/adapters | packages/adapters | yes | n/a | @martin/core |
+| @martin/cli | packages/cli | no | public | @martin/adapters, @martin/contracts, @martin/core |
+| @martinloop/mcp | packages/mcp | no | public | none |
+
+## Non-OSS Workspace Packages
+| Package | Path | Reason |
+|---|---|---|
+| @martin/control-plane | apps/control-plane | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
+| @martin/benchmarks | benchmarks | Managed or RC-only workspace surface that stays out of the initial OSS boundary. |
+
+## Local-Only Surfaces
+| Path | Reason |
+|---|---|
+| apps/local-dashboard | Local read-model viewer that is not yet packaged as a publishable OSS workspace. |
+
+## Dependency Leak Review
+- No workspace dependency leaks detected.
+

package/docs/oss/QUICKSTART.md

@@ -1,135 +1,165 @@
-# 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"`
-
-That launch surface is now implemented in the root package facade and smoke-validated from a clean temporary install. 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 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
-
-Build first, then start the server from the workspace:
-
-```bash
-pnpm --filter @martin/mcp build
-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 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.

package/docs/oss/RALPH-LOOP-SAFETY.md

@@ -0,0 +1,113 @@
+# Ralph-Style Loop Safety Guide
+
+Ralph-style loops are useful because they keep trying until a coding task reaches a stopping condition. MartinLoop is not a replacement for that pattern. It is the governance layer that makes the pattern safer to run unattended.
+
+For install and first-run steps, start with the repo quickstart: [README.md#quick-start](../../README.md#quick-start)
+
+## 1. What Ralph-style loops do well
+
+Ralph-style loops are good at persistence:
+
+- they retry after a failed attempt
+- they keep working toward a concrete objective
+- they help teams automate long-running coding tasks that would otherwise need constant supervision
+
+That persistence is the reason teams use them. The problem is not the existence of the loop. The problem is what happens when the loop keeps running without a clear governance contract.
+
+## 2. Where unattended loops fail
+
+An unattended coding loop can fail in ways that are expensive even when no single attempt looks dramatic on its own:
+
+- spend keeps accumulating across retries
+- verifier failures repeat without a meaningful strategy change
+- file edits drift outside the intended task boundary
+- the final outcome is hard to audit because the reasoning trail is incomplete
+- operators know that the loop stopped, but not whether it stopped for success, safety, or exhaustion
+
+Those are governance failures, not only model failures.
+
+## 3. Why max iterations alone are not enough
+
+A max-iteration limit is helpful, but it only answers one question: "How many times may this loop try?"
+
+It does not answer:
+
+- how much budget can be spent before the next attempt is rejected
+- whether the verifier command is safe to run
+- whether the patch stayed inside the approved file scope
+- whether a failed run left rollback evidence behind
+- whether the recorded outcome is trustworthy enough to resume or inspect later
+
+Iteration caps are one guardrail. They are not a full control layer.
+
+## 4. What MartinLoop adds
+
+MartinLoop governs the loop before, during, and after execution:
+
+- **Budget governance** rejects work that would exceed the configured spend, token, or iteration envelope
+- **Verifier gates** only allow a run to finish as `completed` when the agent result and verification state both pass
+- **Safety leash checks** evaluate verifier commands, file boundaries, and approval-sensitive actions before work is accepted
+- **Stop reasons** make the final lifecycle state explicit, such as `completed`, `budget_exit`, or `human_escalation`
+- **Run records** append JSONL evidence under `~/.martin/runs/` so operators can inspect what happened later
+- **Rollback evidence** preserves the recovery boundary for repo-backed runs when persistence is configured
+
+That is why MartinLoop should be thought of as a companion governance layer around a Ralph-style loop, not an argument against using one.
+
+## 5. Example governed run
+
+```bash
+martin run "fix the auth regression" \
+  --budget 3.00 \
+  --soft-limit-usd 2.00 \
+  --max-iterations 2 \
+  --verify "pnpm test"
+```
+
+This changes the operator contract in a few important ways:
+
+- the next attempt can be rejected before overspend happens
+- the run still has to satisfy the verifier
+- the final state is inspectable instead of being inferred from logs alone
+
+## 6. Example stop reason
+
+MartinLoop returns an explicit lifecycle state and reason when a run stops:
+
+```json
+{
+  "decision": {
+    "shouldExit": true,
+    "lifecycleState": "budget_exit",
+    "status": "exited",
+    "reason": "Martin exited because the budget governor hit a hard limit."
+  }
+}
+```
+
+That answer is more useful than "the loop stopped" because it tells the operator whether the run ended for success, safety, or exhaustion.
+
+## 7. Example JSONL run record
+
+Each run appends a JSONL record shaped like:
+
+```json
+{
+  "loopId": "loop_example123",
+  "workspaceId": "ws_demo",
+  "projectId": "proj_demo",
+  "status": "exited",
+  "lifecycleState": "budget_exit",
+  "budget": {
+    "maxUsd": 3,
+    "softLimitUsd": 2,
+    "maxIterations": 2,
+    "maxTokens": 20000
+  },
+  "metadata": {
+    "policyProfile": "balanced",
+    "telemetryDestination": "local-only"
+  }
+}
+```
+
+The full record can also include attempts, events, verifier outcomes, and persisted artifact references. That is the evidence trail MartinLoop adds around a retrying coding loop.