martin-loop 0.1.0 → 0.1.2

package/README.md

@@ -1,89 +1,344 @@
-# Martin Loop
-
-Governed AI coding runtime with hard budget controls, grounding enforcement, rollback, and a persistent audit trail.
-
-## What is validated in this repo
-
-- `@martin/core`: runtime controller, policy engine, grounding, leash, rollback
-- `@martin/contracts`: shared types for loop, failure, budget, and grounding
-- `@martin/adapters`: Claude CLI, Codex CLI, and direct-provider adapters
-- `@martin/cli`: repo-local `martin` CLI
-- `@martin/mcp`: MCP server surface
-- `@martin/sdk`: governance, handoff, and migration primitives
-
-The workspace packages are validated in this snapshot. Public `martin-loop` packaging remains later release work and should not be treated as the verified install path yet.
-
-## Repo-local install
-
-```bash
-git clone https://github.com/martinloop/martin-loop
-cd martin-loop
-pnpm install
-pnpm build
-```
-
-## Quick start
-
-```bash
-pnpm --filter @martin/cli exec martin run \
-  --objective "Repair the flaky auth test" \
-  --verify "pnpm test"
-```
-
-```bash
-pnpm --filter @martin/cli exec martin inspect --file ~/.martin/runs/latest/loop-record.json
-```
-
-See [docs/QUICKSTART.md](docs/QUICKSTART.md) for the fuller walkthrough and [docs/EXAMPLES.md](docs/EXAMPLES.md) for more runnable examples.
-
-## Programmatic usage
-
-```ts
-import { runMartin } from "@martin/core";
-
-const result = await runMartin({
-  workspaceId: "ws_local",
-  projectId: "proj_auth",
-  task: {
-    title: "Repair the flaky auth test",
-    objective: "Repair the flaky auth test without widening scope.",
-    verificationPlan: ["pnpm test"]
-  },
-  budget: {
-    maxUsd: 0.5,
-    softLimitUsd: 0.3,
-    maxIterations: 4,
-    maxTokens: 20_000
-  },
-  adapter
-});
-
-console.log(result.decision.lifecycleState);
-```
-
-## Validation
-
-```bash
-pnpm test
-pnpm build
-pnpm typecheck
-```
-
-## Artifacts
-
-```text
-~/.martin/runs/<run-id>/
-  contract.json
-  state.json
-  ledger.jsonl
-  artifacts/attempt-001/
-    diff.patch
-    grounding-scan.json
-    leash.json
-    patch-decision.json
-    rollback-outcome.json
-```
-
-## License
-
-MIT. See [LICENSE](LICENSE).
+<div align="center">
+
+<!-- <img src="docs/assets/martinloop_logo_1.png" alt="MartinLoop" width="200"> -->
+
+# MartinLoop
+
+### The agentic AI governance runtime. Hard enforcement, not suggestions.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-7c3aed?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](./tsconfig.json)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](#quick-start)
+[![npm](https://img.shields.io/badge/npm-martin--loop-cc3534?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/package/martin-loop)
+
+<br>
+
+> **Your overnight AI pipeline estimated $2.40.**
+> **You woke up to $165.**
+>
+> 47 retries. No hard stop. No rollback. No audit trail. Nothing merged.
+> **MartinLoop exists so that never happens again.**
+
+</div>
+
+---
+
+## ⚡ Quick Start
+
+## Release Surface
+
+The frozen public package surface for this RC is:
+
+```sh
+npm install martin-loop
+npx martin-loop
+```
+
+```typescript
+import { MartinLoop } from "martin-loop"
+```
+
+Phase 13 RC gate commands:
+
+```sh
+pnpm oss:validate
+pnpm public:smoke
+pnpm repo:smoke
+pnpm rc:validate
+pnpm pilot:prep:validate
+pnpm release:matrix:local
+```
+
+Registry publication is intentionally held for a later release step; this repository can validate the package surface locally before publishing.
+
+---
+
+### 1. Install
+
+```sh
+npm install -g martin-loop
+```
+
+This gives you two commands: `martin` and `martin-loop` (both identical).
+
+### 2. Run a governed task
+
+```sh
+martin run "fix the auth regression" \
+  --budget 3.00 \
+  --verify "pnpm test"
+```
+
+What each flag does:
+- `--budget 3.00` — hard kill at $3.00. The subprocess is terminated at the limit.
+- `--verify "pnpm test"` — shell command run after each attempt. Loop only exits success when it passes.
+
+The first argument after `run` is your objective. You can also use `--objective`:
+
+```sh
+martin run --objective "fix the auth regression" --budget 3.00 --verify "pnpm test"
+```
+
+### 3. Resume an interrupted run
+
+```sh
+martin resume <loopId>
+```
+
+Loads the persisted loop record from `~/.martin/runs/` by ID.
+
+### 4. Inspect a run file
+
+```sh
+martin inspect --file ~/.martin/runs/<workspaceId>.jsonl
+```
+
+Prints a portfolio summary (total cost, attempts, outcomes) for all loops in the file.
+
+---
+
+## 🖥️ All CLI Flags
+
+```
+martin run <objective> [options]
+
+  --objective <text>      The task to accomplish (or pass as first positional arg)
+  --budget <n>            Hard cost cap in USD (subprocess killed at limit)
+  --budget-usd <n>        Alias for --budget
+  --verify <cmd>          Shell command used as the verifier after each attempt
+  --max-iterations <n>    Maximum number of attempts (default: 3)
+  --engine <name>         Adapter to use: claude (default) or codex
+  --model <name>          Override the model (e.g. claude-sonnet-4-6)
+  --cwd <path>            Repo root for the run (default: current directory)
+  --allow-path <glob>     Restrict agent to this path pattern (repeatable)
+  --deny-path <glob>      Block agent from this path pattern (repeatable)
+  --accept <criterion>    Add an acceptance criterion injected into the prompt (repeatable)
+  --config <path>         Path to a martin.config.yaml policy file
+  --workspace <id>        Workspace ID for the run record (default: ws_default)
+  --project <id>          Project ID for the run record (default: proj_default)
+  --metadata <key=value>  Attach metadata to the run record (repeatable)
+```
+
+---
+
+## 📋 Policy File (martin.config.yaml)
+
+Drop a `martin.config.yaml` in your repo root to set governance defaults:
+
+```yaml
+budget:
+  maxUsd: 5.00
+  softLimitUsd: 3.75
+  maxIterations: 5
+  maxTokens: 40000
+
+governance:
+  destructiveActionPolicy: approval
+  telemetryDestination: local-only
+  verifierRules:
+    - pnpm test
+```
+
+The CLI picks this up automatically. CLI flags always override the config file.
+
+---
+
+## 📦 TypeScript SDK
+
+Install as a library:
+
+```sh
+npm install martin-loop
+```
+
+```typescript
+import {
+  MartinLoop,
+  createClaudeCliAdapter,
+  createCodexCliAdapter
+} from 'martin-loop'
+
+const loop = new MartinLoop({
+  adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
+  defaults: {
+    budget: {
+      maxUsd: 3.00,
+      softLimitUsd: 2.25,
+      maxIterations: 3,
+      maxTokens: 20_000
+    }
+  }
+})
+
+const result = await loop.run({
+  workspaceId: 'my-workspace',
+  projectId: 'my-project',
+  task: {
+    title: 'Fix auth regression',
+    objective: 'Fix the failing auth regression tests',
+    verificationPlan: ['pnpm test'],
+    repoRoot: process.cwd()
+  },
+  budget: {
+    maxUsd: 3.00,
+    softLimitUsd: 2.25,
+    maxIterations: 3,
+    maxTokens: 20_000
+  }
+})
+
+// result.decision.status          → 'completed' | 'exited' | 'failed'
+// result.decision.lifecycleState  → 'completed' | 'budget_exit' | 'human_escalation' | ...
+// result.loop.cost.actualUsd      → actual USD spent
+// result.loop.attempts.length     → number of attempts made
+// result.decision.reason          → why the loop exited
+```
+
+### Using Codex instead of Claude
+
+```typescript
+const loop = new MartinLoop({
+  adapter: createCodexCliAdapter({ workingDirectory: process.cwd() })
+})
+```
+
+### Using the lower-level `runMartin` directly
+
+```typescript
+import { runMartin, createClaudeCliAdapter } from 'martin-loop'
+
+const result = await runMartin({
+  workspaceId: 'ws_default',
+  projectId: 'proj_default',
+  task: {
+    title: 'Fix auth regression',
+    objective: 'Fix the failing auth regression tests',
+    verificationPlan: ['pnpm test'],
+    repoRoot: process.cwd()
+  },
+  budget: {
+    maxUsd: 3.00,
+    softLimitUsd: 2.25,
+    maxIterations: 3,
+    maxTokens: 20_000
+  },
+  adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() })
+})
+```
+
+---
+
+## 🧠 Architecture
+
+Five governance layers from policy to runtime enforcement.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                   MartinLoop Governance Stack            │
+├──────────────────────┬───────────────────────────────────┤
+│  Autonomy Envelope   │  Surface · Path · Command         │
+│  (policy-enforced)   │  Leash — pre-execution gate       │
+├──────────────────────┼───────────────────────────────────┤
+│  Model Router        │  Cost-aware adapter selection     │
+│                      │  Fallback chain + model override  │
+├──────────────────────┼───────────────────────────────────┤
+│  Agent Adapters      │  Claude Code · Codex · any CLI   │
+│                      │  Direct + stub adapters           │
+├──────────────────────┼───────────────────────────────────┤
+│  Safety Leash        │  Pre-execution verification gate  │
+│                      │  Filesystem + secret + command    │
+├──────────────────────┼───────────────────────────────────┤
+│  Persistence         │  Per-run JSONL in ~/.martin/runs/ │
+│                      │  Portfolio inspect + resume       │
+└──────────────────────┴───────────────────────────────────┘
+```
+
+---
+
+## 🛡️ What MartinLoop Enforces Today
+
+**1. Hard budget cap.**
+Every run has a `maxUsd` limit. When the cost reaches that limit the subprocess is terminated — not warned.
+
+**2. Iteration cap.**
+Every run has a `maxIterations` limit. The loop exits when it is hit, regardless of progress.
+
+**3. Filesystem leash.**
+If `allowedPaths` or `deniedPaths` are configured, any attempt that writes outside the envelope is blocked and rolled back before the patch is kept.
+
+**4. Secret leash.**
+Values that look like secrets (API keys, tokens) in the task objective or acceptance criteria are blocked before any attempt runs.
+
+**5. Verifier gate.**
+The loop only marks a run successful if the verifier command exits `0`. A passing verifier is required for a `completed` lifecycle state.
+
+**6. Rollback on failure.**
+When an attempt is discarded (failed verifier, safety violation, patch decision), MartinLoop restores the filesystem to the pre-attempt state using a git-backed snapshot.
+
+**7. Run persistence.**
+Every run is written to `~/.martin/runs/<workspaceId>.jsonl`. Use `martin resume` and `martin inspect` to read it back.
+
+---
+
+## 📦 OSS Packages
+
+| Package | What It Does |
+|---------|-------------|
+| `martin-loop` | Self-contained facade — everything below, vendored and published |
+| `@martin/core` | Runtime controller, leash, router, rollback, policy engine |
+| `@martin/cli` | `martin run` · `inspect` · `resume` CLI commands |
+| `@martin/adapters` | Claude Code, Codex CLI, direct-provider, stub adapters |
+| `@martin/contracts` | Shared types: loop, policy, leash, budget, rollback |
+
+All `@martin/*` packages are workspace-internal. Install `martin-loop` from npm — it bundles them all.
+
+---
+
+## 🔧 Development
+
+**Requirements:** Node 20+ · pnpm 8+
+
+```sh
+# Clone and install
+git clone https://github.com/Keesan12/MartinLoop
+cd martin-loop && pnpm install
+
+# Full test suite
+pnpm test
+
+# Type check all packages
+pnpm -r lint
+
+# Build all packages + public facade
+pnpm build
+
+# Publish (after build)
+npm publish
+```
+
+---
+
+## 🤝 Contributing
+
+```sh
+git checkout -b feat/your-feature
+
+# Make changes, then:
+pnpm -r lint && pnpm test   # must stay green
+
+git commit -m "feat: describe what you built"
+git push -u origin feat/your-feature
+# Open a PR against main
+```
+
+Conventional commits: `feat:` · `fix:` · `chore:` · `docs:` · `refactor:` · `test:`
+
+---
+
+<div align="center">
+
+**MIT Licensed** · [martinloop.com](https://martinloop.com) · [keesan@martinloop.com](mailto:keesan@martinloop.com)
+
+*"AI coding accountability: completes good work · refuses bad work · stops uneconomical work."*
+
+</div>

package/docs/oss/EXAMPLES.md

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

@@ -0,0 +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
+  }
+}