martin-loop 0.1.0 → 0.1.2

package/docs/EXAMPLES.md

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

@@ -1,127 +0,0 @@
-# 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/release/CLAIM-TO-CAPABILITY.md

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