martin-loop 0.1.2 → 0.1.3

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

@@ -1,113 +1,113 @@
-{
-  "generatedAt": "2026-04-21T09:43:03.509Z",
-  "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-04-22T11:35:54.851Z",
+  "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
+  }
+}

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

@@ -1,48 +1,48 @@
-# Martin Loop Phase 13 OSS Core Boundary
-
-Generated: 2026-04-21T09:43:03.509Z
-
-## 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-04-22T11:35:54.851Z
+
+## 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.
+

package/docs/oss/QUICKSTART.md

@@ -1,135 +1,135 @@
-# 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"`
+
+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.