martin-loop 0.1.0

package/README.md

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

package/dist/bin/martin-loop.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/martin-loop.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { executeCli } from "@martin/cli";
+const args = process.argv.slice(2);
+executeCli(args)
+    .then((result) => {
+    if (result.stdout) {
+        process.stdout.write(`${result.stdout}\n`);
+    }
+    if (result.stderr) {
+        process.stderr.write(`${result.stderr}\n`);
+    }
+    process.exitCode = result.exitCode;
+})
+    .catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=martin-loop.js.map

package/dist/bin/martin-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"martin-loop.js","sourceRoot":"","sources":["../../src/bin/martin-loop.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,UAAU,CAAC,IAAI,CAAC;KACb,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;IACf,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AACrC,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { runMartin } from "@martin/core";
+export * from "@martin/core";
+export * from "@martin/adapters";
+export * from "@martin/sdk";
+export { executeCli, parseCliArguments, renderCliHelp } from "@martin/cli";
+export declare const MartinLoop: {
+    run: typeof runMartin;
+};
+export type MartinLoopFacade = typeof MartinLoop;

package/dist/index.js

@@ -0,0 +1,9 @@
+import { runMartin } from "@martin/core";
+export * from "@martin/core";
+export * from "@martin/adapters";
+export * from "@martin/sdk";
+export { executeCli, parseCliArguments, renderCliHelp } from "@martin/cli";
+export const MartinLoop = {
+    run: runMartin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,GAAG,EAAE,SAAS;CACf,CAAC"}

package/docs/EXAMPLES.md

@@ -0,0 +1,96 @@
+# Examples
+
+Runnable examples for the Martin Loop CLI and SDK.
+
+## 1. Stub-backed hello world
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --objective "Describe the current Martin run lifecycle" \
+  --verify "echo verified"
+```
+
+## 2. Scoped task with path boundaries
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --engine claude \
+  --objective "Tighten the README wording for the quickstart section" \
+  --verify "pnpm --filter @martin/core test" \
+  --allow-path README.md \
+  --allow-path docs/** \
+  --deny-path apps/** \
+  --budget-usd 0.25 \
+  --accept "Only update documentation files" \
+  --accept "Do not modify runtime source code"
+```
+
+## 3. Leash block
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --objective "Run a dangerous verifier" \
+  --verify "rm -rf ."
+```
+
+## 4. Budget-constrained live run
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --engine claude \
+  --objective "Refactor the CLI argument parser for clarity" \
+  --verify "pnpm --filter @martin/cli test" \
+  --budget-usd 1.00 \
+  --soft-limit-usd 0.60 \
+  --max-iterations 3
+```
+
+## 5. Multi-adapter fallback chain
+
+```ts
+import { runMartin } from "@martin/core";
+
+const result = await runMartin({
+  workspaceId: "ws_local",
+  projectId: "proj_example",
+  task: {
+    title: "Fix the failing test",
+    objective: "Fix the failing test without widening scope.",
+    verificationPlan: ["pnpm test"]
+  },
+  budget: {
+    maxUsd: 2,
+    softLimitUsd: 1,
+    maxIterations: 6,
+    maxTokens: 20_000
+  },
+  adapter,
+  fallbackAdapters: [fallbackAdapter]
+});
+
+console.log(result.decision.lifecycleState);
+```
+
+## 6. Inspect a completed run
+
+```bash
+pnpm --filter @martin/cli exec martin inspect --file ~/.martin/runs/<run-id>/loop-record.json
+```
+
+## 7. MCP invocation
+
+```json
+{
+  "tool": "martin_run",
+  "arguments": {
+    "objective": "Repair the flaky test in auth.test.ts",
+    "workingDirectory": ".",
+    "engine": "claude",
+    "verificationPlan": ["pnpm test"],
+    "maxUsd": 1.0,
+    "maxIterations": 4,
+    "workspaceId": "ws_local",
+    "projectId": "proj_auth"
+  }
+}
+```

package/docs/QUICKSTART.md

@@ -0,0 +1,127 @@
+# Quickstart
+
+Martin Loop runs AI coding agents with hard budget caps, grounding enforcement, and a full audit trail. This guide gets you running in under 5 minutes.
+
+## Prerequisites
+
+- Node.js 20+
+- `pnpm` 10.x
+- Optional: Claude Code CLI for live Claude runs
+- Optional: OpenAI Codex CLI plus credentials for Codex runs
+
+## Install
+
+### From source
+
+```bash
+git clone https://github.com/martinloop/martin-loop
+cd martin-loop
+pnpm install
+pnpm build
+```
+
+This OSS snapshot is validated through the workspace packages, so the examples below use the repo-local CLI entrypoint.
+
+## Your first run (stub mode, no spend)
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --objective "Summarize the current runtime state" \
+  --verify "echo ok"
+```
+
+This exercises the full loop using a stub adapter, so no model is called. Check what was written:
+
+```bash
+pnpm --filter @martin/cli exec martin inspect --file ~/.martin/runs/latest/loop-record.json
+```
+
+## Live run with a budget cap
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --engine claude \
+  --objective "Fix the failing test in packages/core/tests/leash.test.ts" \
+  --verify "pnpm --filter @martin/core test" \
+  --budget-usd 0.50 \
+  --max-iterations 4
+```
+
+Martin will stop at $0.50 regardless of task completion. Budget is a hard cap, not a soft suggestion.
+
+## Safety demo
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --objective "Run an unsafe verifier" \
+  --verify "rm -rf ."
+```
+
+Expected: the run exits immediately with a leash violation.
+
+## Scoped run with path restrictions
+
+```bash
+pnpm --filter @martin/cli exec martin run \
+  --engine claude \
+  --objective "Improve the README wording" \
+  --verify "echo docs-only" \
+  --allow-path README.md \
+  --allow-path docs/** \
+  --deny-path packages/** \
+  --budget-usd 0.25
+```
+
+## Config file
+
+Martin reads `martin.config.yaml` from the current directory automatically:
+
+```yaml
+engine: claude
+budgetUsd: 1.00
+maxIterations: 6
+verificationPlan:
+  - pnpm test
+allowedPaths:
+  - src/**
+deniedPaths:
+  - .env
+  - secrets/**
+```
+
+Then run:
+
+```bash
+pnpm --filter @martin/cli exec martin run --objective "Refactor the auth handler"
+```
+
+## MCP server
+
+```bash
+node packages/mcp/dist/server.js
+```
+
+Tools exposed: `martin_run`, `martin_inspect`, `martin_status`
+
+## What to inspect after a run
+
+```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
+```
+
+## Validation check
+
+```bash
+pnpm test
+pnpm build
+pnpm typecheck
+```

package/docs/README.md

@@ -0,0 +1,89 @@
+# 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`
+- `@martin/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.
+- `@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.
+
+## Planned public launch target
+
+The current engineering memo keeps these public-launch targets as the intended release shape:
+
+- install target: `npm install martin-loop`
+- CLI target: `npx martin-loop ...`
+- SDK target: `import { MartinLoop } from "martin-loop"`
+
+Those targets are not the validated operator path for this OSS snapshot yet. In the current repo, the honest workflow is still the repo-local path documented below and in the quickstart, because registry publication and broader release packaging remain later steps.
+
+## Reproducibility
+
+From the repo root:
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+pnpm typecheck
+```
+
+Those are the commands validated in this workspace today. Earlier RC-only commands such as `pnpm rc:validate` or `pnpm public:smoke` are referenced in older planning notes, but they are not shipped as runnable scripts in this repo snapshot.
+
+## RC gate commands
+
+The current repo-local validation gate is:
+
+- `pnpm test`
+- `pnpm build`
+- `pnpm typecheck`
+
+Treat anything broader than those commands as release-planning work that still needs to be reintroduced explicitly before launch.
+
+## Where to go next
+
+- [`docs/QUICKSTART.md`](./QUICKSTART.md) for clone-to-first-run setup
+- [`docs/EXAMPLES.md`](./EXAMPLES.md) for grounded CLI and MCP examples
+- [`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/release/CLAIM-TO-CAPABILITY.md

@@ -0,0 +1,19 @@
+# Claim To Capability
+
+This matrix keeps the public story tied to proof. Every public claim category must point either to repo-owned artifacts or to a frozen external reference record. If a row cannot be defended by evidence, the claim must stay softened or out of market copy.
+
+| Claim category | Current boundary | Evidence type | Evidence reference | Status |
+|---|---|---|---|---|
+| Runtime and artifact truth | Artifact-backed runtime lifecycle, grounding, accounting, and rollback behavior only | repo | `docs/oss/RELEASE-SURFACE-REPORT.md`, `docs/oss/OSS-BOUNDARY-REPORT.md`, `pnpm rc:validate` | ready |
+| Evidence-backed contradiction detection | Completion claims are accepted only when repo-backed change evidence and verifier truth support them; this is contradiction detection, not semantic intent reading | repo | `packages/core/src/evidence/claim-audit.ts`, `packages/core/tests/runtime.test.ts` | ready |
+| Deterministic supported-path recovery | Recovery is deterministic only across the declared adapter/model matrix the runtime and CLI construct; unsupported paths must be surfaced honestly | repo | `packages/core/tests/runtime.test.ts`, `packages/cli/tests/cli-recovery-topology.test.ts` | ready |
+| Public package install and CLI surface | Public install target stays `martin-loop`; operator truth still starts from the repo until human publish | repo | `pnpm public:smoke`, `pnpm release:package:validate` | ready |
+| Repo-backed safety, rollback, and grounding proof | Repo-backed mutations must remain explainable from artifacts alone | repo | `pnpm repo:smoke`, `docs/pilot/PILOT-GATE-REVIEW.md` | ready |
+| Pilot closeout evidence | Phase 14 claims stay bounded to 2 accepted `disposable_internal`, 2 accepted `low_risk_real`, and gate `GO` | repo | `docs/pilot/PILOT-RUN-TRACKER.md`, `docs/review-packs/2026-04-05-phase14-pilot-04/review.md` | ready |
+| Website copy and positioning | Website copy must not outrun the shipped public surface or the pilot evidence | external reference | `docs/release/external-evidence/WEBSITE-SURFACE-REFERENCE.md` | ready_for_signoff |
+| Pricing and feature gating | Pricing and packaging statements must align with the single-facade `martin-loop` release and the current feature gate truth | external reference | `docs/release/external-evidence/PRICING-SURFACE-REFERENCE.md` | ready_for_signoff |
+| Privacy commitments | Privacy claims must stay inside the shipped operator and data-handling behavior | external reference | `docs/release/external-evidence/PRIVACY-POLICY-REFERENCE.md` | ready_for_signoff |
+| Terms and access control | Terms must reflect the current access model, manual release sequence, and support boundaries | external reference | `docs/release/external-evidence/TERMS-OF-SERVICE-REFERENCE.md` | ready_for_signoff |
+| Product claim matrix | Marketing or launch claims stay frozen to the reviewed matrix until a human owner widens them intentionally | external reference | `docs/release/external-evidence/PRODUCT-CLAIM-MATRIX-REFERENCE.md` | ready_for_signoff |
+| Semantic hallucination detection | Not claimed. The live repo still exposes a structural short-response heuristic, but release language must not present that as semantic truth understanding | repo | `PRODUCTION-READINESS-AUDIT-REPORT.md`, `docs/handoffs/2026-04-08-h2-h3-complete-handoff.md` | not_claimed |
+| Universal autonomous self-recovery | Not claimed. Release language is limited to deterministic recovery across the declared supported adapter/model matrix and explicit single-path disclosures | repo | `PRODUCTION-READINESS-AUDIT-REPORT.md`, `packages/cli/tests/cli-recovery-topology.test.ts` | not_claimed |

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "martin-loop",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Martin Loop — The world's first truthfully hardened agentic coding loop.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "martin-loop": "./dist/bin/martin-loop.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "coding-loop",
+    "llm",
+    "automation",
+    "cli"
+  ],
+  "author": "Vakeesan Mahalingam and Gobi Shanthan",
+  "license": "MIT",
+  "homepage": "https://martinloop.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/martinloop/martin-loop.git"
+  },
+  "dependencies": {
+    "@martin/adapters": "0.1.0",
+    "@martin/sdk": "0.1.0",
+    "@martin/cli": "0.1.0",
+    "@martin/contracts": "0.1.0",
+    "@martin/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "scripts": {
+    "build": "pnpm -r build && tsc -p tsconfig.json",
+    "test": "pnpm -r test",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r exec tsc --noEmit && tsc -p tsconfig.json --noEmit"
+  }
+}