martin-loop 0.1.5 → 1.3.0

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

@@ -1,113 +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.
+# 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.

package/docs/oss/README.md

@@ -1,96 +1,96 @@
-# Martin OSS Core
-
-Martin Loop is a governed AI coding-loop runtime. The core runtime is real and verified through the Phase 12 certification gate; the repo is now in Phase 13 release-candidate engineering, which means the focus is reproducibility, OSS boundary cleanup, and pilot readiness rather than new feature invention.
-
-## What the OSS core includes today
-
-- `@martin/contracts`: shared loop, policy, grounding, leash, budget, and rollback types
-- `@martin/core`: the runtime controller, persistence layer, grounding scanner, leash engine, patch-truth scoring, and rollback restoration logic
-- `@martin/adapters`: normalized Claude CLI, Codex CLI, and direct-provider or stub adapter surfaces
-- `@martin/cli`: the local operator CLI for `run`, `inspect`, and `resume`
-- `@martinloop/mcp`: the MCP server surface for `martin_run`, `martin_inspect`, and `martin_status`
-
-## What is still outside the initial OSS promise
-
-- The root workspace now exposes the `martin-loop` public package facade, and `@martinloop/mcp` now has a standalone tarball shape validated via `pnpm --filter @martinloop/mcp smoke:pack`, but registry publication is still a separate release step.
-- `@martin/contracts`, `@martin/core`, and `@martin/adapters` are still marked `private` in their package manifests.
-- The hosted control-plane and local dashboard remain in the repo, but they are not yet the finalized public OSS boundary.
-- The benchmark harness remains a workspace-only RC surface under `benchmarks/` and is not part of the publishable CLI boundary yet.
-- Final licensing, public package publishing, and managed-product packaging are still gated behind later Phase 13 to Phase 15 work.
-
-That means this repo is ready for grounded engineering review and RC validation, but it is not yet claiming a finished public OSS release.
-
-## Runtime truth the current core enforces
-
-- Explicit policy phases: `GATHER`, `ADMIT`, `PATCH`, `VERIFY`, `RECOVER`, `ESCALATE`, `ABORT`, `HANDOFF`
-- Grounding scans against repo anatomy before success is accepted
-- Blocking leash behavior for unsafe verifier commands, file-scope violations, approval-boundary changes, and secret handling
-- Provenance-aware accounting using `actual`, `estimated`, and `unavailable`
-- Persisted attempt artifacts under `~/.martin/runs/<runId>/artifacts/attempt-XXX/`
-- Patch-truth scoring plus rollback boundary and restore outcome artifacts for discarded or blocked repo-backed attempts
-
-## Trust profiles
-
-Martin currently exposes these execution profiles:
-
-- `strict_local`: safest default for local repo work
-- `ci_safe`: tighter CI-oriented behavior
-- `staging_controlled`: controlled outbound or network allowances with approvals
-- `research_untrusted`: looser network posture for research-oriented runs while still enforcing approval boundaries
-
-## Accounting labels
-
-Martin keeps cost provenance explicit:
-
-- `actual`: reported directly by the provider or adapter settlement
-- `estimated`: derived from pricing logic or modeled usage
-- `unavailable`: the adapter could not produce a trustworthy number
-
-Do not collapse those labels when building dashboards, docs, or public claims.
-
-## Frozen public launch target
-
-The current engineering memo freezes these public-launch targets for release planning:
-
-- install target: `npm install martin-loop`
-- CLI target: `npx martin-loop ...`
-- SDK target: `import { MartinLoop } from "martin-loop"`
-- MCP target (publish-ready): `npx @martinloop/mcp`
-
-Those runtime targets are implemented in the root package facade and verified through a clean-install smoke test. The MCP target is packaged and verified through a tarball launch smoke test. During the current RC phase, the honest operator path still includes the repo-local workflow documented below and in the quickstart, because public registry publication and broader release packaging remain separate release steps.
-
-## Reproducibility
-
-From the repo root:
-
-```bash
-pnpm install
-pnpm build
-pnpm rc:validate
-```
-
-`pnpm rc:validate` runs the current RC matrix in an isolated temp home so fresh-home behavior is checked instead of depending on warmed `~/.martin` state. Use `pnpm rc:validate:install` when you also want the RC run to perform a clean `pnpm install --frozen-lockfile` first.
-
-## RC gate commands
-
-The current release-candidate gate is:
-
-- `pnpm oss:validate`
-- `pnpm public:smoke`
-- `pnpm repo:smoke`
-- `pnpm rc:validate`
-- `pnpm pilot:prep:validate`
-- `pnpm release:matrix:local`
-
-`pnpm rc:validate` now includes the machine-checked release-surface audit in addition to the existing build, test, benchmark, provider-path, OSS-boundary, and control-plane checks.
-
-## Where to go next
-
-- [`docs/oss/QUICKSTART.md`](./QUICKSTART.md) for clone-to-first-run setup
-- [`docs/oss/EXAMPLES.md`](./EXAMPLES.md) for grounded CLI and MCP examples
-- [`docs/oss/CLAUDE-CODE-WALKTHROUGH.md`](./CLAUDE-CODE-WALKTHROUGH.md) for a Claude Code-specific governed-run walkthrough
-- [`docs/oss/RALPH-LOOP-SAFETY.md`](./RALPH-LOOP-SAFETY.md) for a technical guide to governing Ralph-style loops safely
-- [`docs/oss/OSS-BOUNDARY-REPORT.md`](./OSS-BOUNDARY-REPORT.md) for the current machine-checked OSS boundary and public-surface status
-- [`docs/oss/RELEASE-SURFACE-REPORT.md`](./RELEASE-SURFACE-REPORT.md) for the current machine-checked release-surface audit
-- [`docs/pilot/README.md`](../pilot/README.md) for the pilot-prep package that remains explicitly gated behind Phase 13 completion
-- [`../../README.md`](../../README.md) for the repo-level RC status and workspace map
+# Martin OSS Core
+
+Martin Loop is a governed AI coding-loop runtime. The core runtime is real and verified through the Phase 12 certification gate; the repo is now in the Phase 15 public-release lane, which means the focus is release truth, packaging, and final-gate evidence rather than new feature invention.
+
+## What the OSS core includes today
+
+- `@martin/contracts`: shared loop, policy, grounding, leash, budget, and rollback types
+- `@martin/core`: the runtime controller, persistence layer, grounding scanner, leash engine, patch-truth scoring, and rollback restoration logic
+- `@martin/adapters`: normalized Claude CLI, Codex CLI, and direct-provider or stub adapter surfaces
+- `@martin/cli`: the local operator CLI for `run`, `inspect`, and `resume`
+- `@martinloop/mcp`: the MCP server surface for `martin_run`, `martin_inspect`, and `martin_status`
+
+## What is still outside the initial OSS promise
+
+- The root workspace now exposes the `martin-loop` public package facade, and `@martinloop/mcp` now has a standalone tarball shape plus a published-package smoke validated via `pnpm --filter @martinloop/mcp smoke:pack` and `pnpm --filter @martinloop/mcp smoke:published`, but registry publication is still a separate release step.
+- `@martin/contracts`, `@martin/core`, and `@martin/adapters` are still marked `private` in their package manifests.
+- The hosted control-plane and local dashboard remain in the repo, but they are not yet the finalized public OSS boundary.
+- The benchmark harness remains a workspace-only RC surface under `benchmarks/` and is not part of the publishable CLI boundary yet.
+- Final licensing, public package publishing, and managed-product packaging are still gated behind later Phase 13 to Phase 15 work.
+- Internal workspace packages remain non-public release internals unless the release lane explicitly widens that surface.
+
+That means this repo is ready for grounded engineering review and RC validation, but it is not yet claiming a finished public OSS release.
+
+## Runtime truth the current core enforces
+
+- Explicit policy phases: `GATHER`, `ADMIT`, `PATCH`, `VERIFY`, `RECOVER`, `ESCALATE`, `ABORT`, `HANDOFF`
+- Grounding scans against repo anatomy before success is accepted
+- Blocking leash behavior for unsafe verifier commands, file-scope violations, approval-boundary changes, and secret handling
+- Provenance-aware accounting using `actual`, `estimated`, and `unavailable`
+- Persisted attempt artifacts under `~/.martin/runs/<runId>/artifacts/attempt-XXX/`
+- Patch-truth scoring plus rollback boundary and restore outcome artifacts for discarded or blocked repo-backed attempts
+
+## Trust profiles
+
+Martin currently exposes these execution profiles:
+
+- `strict_local`: safest default for local repo work
+- `ci_safe`: tighter CI-oriented behavior
+- `staging_controlled`: controlled outbound or network allowances with approvals
+- `research_untrusted`: looser network posture for research-oriented runs while still enforcing approval boundaries
+
+## Accounting labels
+
+Martin keeps cost provenance explicit:
+
+- `actual`: reported directly by the provider or adapter settlement
+- `estimated`: derived from pricing logic or modeled usage
+- `unavailable`: the adapter could not produce a trustworthy number
+
+Do not collapse those labels when building dashboards, docs, or public claims.
+
+## Frozen public launch target
+
+The current engineering memo freezes these public-launch targets for release planning:
+
+- install target: `npm install martin-loop`
+- CLI target: `npx martin-loop ...`
+- SDK target: `import { MartinLoop } from "martin-loop"`
+- MCP target (publish-ready): `npx @martinloop/mcp`
+
+Those runtime targets are implemented in the root package facade and verified through a clean-install smoke test. The MCP target is packaged and verified through a tarball launch smoke test. During the current RC phase, the honest operator path still includes the repo-local workflow documented below and in the quickstart, because public registry publication and broader release packaging remain separate release steps.
+
+## Reproducibility
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm build
+pnpm rc:validate
+```
+
+`pnpm rc:validate` runs the current RC matrix in an isolated temp home so fresh-home behavior is checked instead of depending on warmed `~/.martin` state. Use `pnpm rc:validate:install` when you also want the RC run to perform a clean `pnpm install --frozen-lockfile` first.
+
+## RC gate commands
+
+The current release-candidate gate is:
+
+- `pnpm oss:validate`
+- `pnpm public:smoke`
+- `pnpm mcp:published:smoke`
+- `pnpm repo:smoke`
+- `pnpm rc:validate`
+- `pnpm pilot:prep:validate`
+- `pnpm release:matrix:local`
+
+`pnpm rc:validate` now includes the machine-checked release-surface audit in addition to the existing build, test, benchmark, provider-path, OSS-boundary, and control-plane checks.
+
+## Where to go next
+
+- [`docs/oss/QUICKSTART.md`](./QUICKSTART.md) for clone-to-first-run setup
+- [`docs/oss/EXAMPLES.md`](./EXAMPLES.md) for grounded CLI and MCP examples
+- [`docs/oss/OSS-BOUNDARY-REPORT.md`](./OSS-BOUNDARY-REPORT.md) for the current machine-checked OSS boundary and public-surface status
+- [`docs/oss/RELEASE-SURFACE-REPORT.md`](./RELEASE-SURFACE-REPORT.md) for the current machine-checked release-surface audit
+- [`docs/pilot/README.md`](../pilot/README.md) for the pilot-prep package that remains explicitly gated behind Phase 13 completion
+- [`../../README.md`](../../README.md) for the repo-level RC status and workspace map

package/docs/oss/RELEASE-SURFACE-REPORT.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-11T21:47:37.407Z",
+  "generatedAt": "2026-05-12T17:46:28.520Z",
   "publicSurface": {
     "packageName": "martin-loop",
     "installCommand": "npm install martin-loop",
@@ -9,6 +9,7 @@
   "rcGateCommands": [
     "pnpm oss:validate",
     "pnpm public:smoke",
+    "pnpm mcp:published:smoke",
     "pnpm repo:smoke",
     "pnpm rc:validate",
     "pnpm pilot:prep:validate",

package/docs/oss/RELEASE-SURFACE-REPORT.md

@@ -1,6 +1,6 @@
 # Martin Loop Phase 13 Release Surface Audit
 
-Generated: 2026-05-11T21:47:37.407Z
+Generated: 2026-05-12T17:46:28.520Z
 
 ## Verdict
 **GO**
@@ -14,6 +14,7 @@ Generated: 2026-05-11T21:47:37.407Z
 ## RC Gate Commands
 - `pnpm oss:validate`
 - `pnpm public:smoke`
+- `pnpm mcp:published:smoke`
 - `pnpm repo:smoke`
 - `pnpm rc:validate`
 - `pnpm pilot:prep:validate`