martin-loop 0.1.4 → 1.3.0

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-12T17:46:27.776Z",
+  "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
+  }
+}

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-12T17:46:27.776Z
+
+## 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,6 +1,6 @@
 # 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.
+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
 
@@ -9,8 +9,9 @@ The frozen public launch target is:
 - `npm install martin-loop`
 - `npx martin-loop ...`
 - `import { MartinLoop } from "martin-loop"`
+- `npx @martinloop/mcp`
 
-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.
+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
 
@@ -53,6 +54,7 @@ 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`
@@ -63,6 +65,7 @@ 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
@@ -114,10 +117,42 @@ For persisted run folders, inspect the `contract.json`, `state.json`, `ledger.js
 
 ## MCP server
 
-Build first, then start the server from the workspace:
+The publish-ready MCP install target is:
 
 ```bash
-pnpm --filter @martin/mcp build
+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
 ```
 

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.

package/docs/oss/README.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -8,15 +8,16 @@ Martin Loop is a governed AI coding-loop runtime. The core runtime is real and v
 - `@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`
-- `@martin/mcp`: the MCP server surface for `martin_run`, `martin_inspect`, and `martin_status`
+- `@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, but registry publication is still a later release step.
+- 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.
 
@@ -55,8 +56,9 @@ The current engineering memo freezes these public-launch targets for release pla
 - 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 targets are now implemented in the root package facade and verified through a clean-install 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 later steps.
+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
 
@@ -76,6 +78,7 @@ 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`

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

@@ -1,45 +1,46 @@
-{
-  "generatedAt": "2026-04-23T15:03:11.006Z",
-  "publicSurface": {
-    "packageName": "martin-loop",
-    "installCommand": "npm install martin-loop",
-    "npxCommand": "npx martin-loop",
-    "sdkImportStatement": "import { MartinLoop } from \"martin-loop\""
-  },
-  "rcGateCommands": [
-    "pnpm oss:validate",
-    "pnpm public:smoke",
-    "pnpm repo:smoke",
-    "pnpm rc:validate",
-    "pnpm pilot:prep:validate",
-    "pnpm release:matrix:local"
-  ],
-  "docCoverage": {
-    "readme": {
-      "path": "README.md",
-      "hasPublicSurface": true,
-      "hasRcGateCommands": true,
-      "hasRegistryCaution": true
-    },
-    "ossReadme": {
-      "path": "docs\\oss\\README.md",
-      "hasPublicSurface": true,
-      "hasAccountingLabels": true,
-      "hasTrustProfiles": true,
-      "hasRegistryCaution": true
-    },
-    "quickstart": {
-      "path": "docs\\oss\\QUICKSTART.md",
-      "hasPublicSurface": true,
-      "hasRcGateCommands": true,
-      "hasRegistryCaution": true
-    },
-    "examples": {
-      "path": "docs\\oss\\EXAMPLES.md",
-      "hasRegistryCaution": true
-    }
-  },
-  "deprecatedFiles": [],
-  "verdict": "go",
-  "failures": []
-}
+{
+  "generatedAt": "2026-05-12T17:46:28.520Z",
+  "publicSurface": {
+    "packageName": "martin-loop",
+    "installCommand": "npm install martin-loop",
+    "npxCommand": "npx martin-loop",
+    "sdkImportStatement": "import { MartinLoop } from \"martin-loop\""
+  },
+  "rcGateCommands": [
+    "pnpm oss:validate",
+    "pnpm public:smoke",
+    "pnpm mcp:published:smoke",
+    "pnpm repo:smoke",
+    "pnpm rc:validate",
+    "pnpm pilot:prep:validate",
+    "pnpm release:matrix:local"
+  ],
+  "docCoverage": {
+    "readme": {
+      "path": "README.md",
+      "hasPublicSurface": true,
+      "hasRcGateCommands": true,
+      "hasRegistryCaution": true
+    },
+    "ossReadme": {
+      "path": "docs\\oss\\README.md",
+      "hasPublicSurface": true,
+      "hasAccountingLabels": true,
+      "hasTrustProfiles": true,
+      "hasRegistryCaution": true
+    },
+    "quickstart": {
+      "path": "docs\\oss\\QUICKSTART.md",
+      "hasPublicSurface": true,
+      "hasRcGateCommands": true,
+      "hasRegistryCaution": true
+    },
+    "examples": {
+      "path": "docs\\oss\\EXAMPLES.md",
+      "hasRegistryCaution": true
+    }
+  },
+  "deprecatedFiles": [],
+  "verdict": "go",
+  "failures": []
+}