martin-loop 0.1.4 → 1.3.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+MartinLoop is an open-source project for developers building safer autonomous AI coding workflows.
+
+We expect contributors and maintainers to keep discussion respectful, technical, and useful.
+
+## Expected behavior
+
+- Be respectful and direct
+- Assume good intent
+- Give constructive technical feedback
+- Stay focused on improving the project
+- Help keep autonomous AI coding safer, cheaper, and more inspectable
+
+## Unacceptable behavior
+
+- Harassment or abusive comments
+- Personal attacks
+- Publishing private information
+- Spam or fake engagement
+- Submitting secrets, credentials, or unsafe examples
+- Encouraging unsafe agent behavior that can spend money or mutate files without clear warnings
+
+## Enforcement
+
+Maintainers may remove comments, close issues, block users, or reject contributions that violate this code of conduct.
+
+## Reporting
+
+Report concerns privately to:
+
+keesan@martinloop.com

package/README.md

@@ -1,237 +1,143 @@
-<div align="center">
+# Martin Loop
 
-<img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/martinloop-logo.png" alt="MartinLoop" width="260">
+Governed runtime for AI coding agents with budgets, policy gates, rollback evidence, and auditable run records.
 
-### A governed runtime for autonomous AI coding agents. ⭐⭐⭐
+![Martin Loop CLI release surface](./docs/assets/marketing/github-readme-cli.svg)
 
-[![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.base.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://www.npmjs.com/package/martin-loop)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/nvidia-inception-program.png" />
+  <img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/nvidia-inception-program-light.png" alt="NVIDIA Inception Program logo" width="280" />
+</picture>
 
-<br>
+Martin Loop has been accepted into the NVIDIA Inception program.
 
-**Your overnight AI pipeline estimated $2.40.**  
-**You woke up to a $65 bill.** 
- <br> 47 retries. No hard stop. No rollback. No audit trail. Nothing merged.  
- MartinLoop exists so that never happens again.✅ <br> <br>
- If you think autonomous AI coding agents need budgets, brakes, and receipts, ⭐ the repo so more builders can find it.
-<br>
+[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/language-TypeScript-3178c6)](./tsconfig.base.json)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-green)](./package.json)
 
-> AI coding agents are useful. Unbounded retry loops are not.
->
-> MartinLoop wraps agent runs with budgets, policy checks, verifier gates, rollback evidence, and inspectable run records.
-<br>
-<img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/cli-animated.svg" alt="MartinLoop CLI — governed agent run" width="720">
+AI coding agents can write files, run commands, spend provider budget, and leave behind hard-to-review state. Martin Loop wraps those actions in a runtime that answers five questions before you trust the result:
 
-</div>
+- What is the task allowed to touch?
+- What is the hard budget?
+- Which safety and policy gates ran?
+- Did the verifier actually execute?
+- Where is the evidence if the result needs review, rollback, or resume?
 
----
+Current public wording should describe Martin Loop as a **bounded governed AI-coding runtime**, not as a hands-off unrestricted production developer or broadly self-updating system. Trace-autonomy certification exists as a gate, but public trace-autonomy wording remains blocked until the signed evidence pack and external audit signoff pass.
 
-## The Problem
+## Release State
 
-A typical autonomous coding loop keeps attempting work until tests pass. Without a governance layer, that loop can keep spending, mutate files outside the intended scope, lose track of why it failed, and leave teams without a clean audit trail.
+- Phase 14 staged pilot: closed
+- Phase 15 public release: active
+- Phase 15 adds release-specific truth, packaging, and final-gate checks on top of this baseline.
 
-Ralph-style loops are powerful but they attempt ➡️ check ➡️ retry ➡️ repeat, with no strong answer to:
+## Why It Exists
 
-- What changed?
-- What did it cost?
-- Why was it allowed?
-- Why did it stop?
-- Can we inspect or resume it later?
-
-MartinLoop governs the failure mode.
-
----
-
-## The Solution
-
-✅ Martin Loop wraps AI coding loops with a governance layer.
-
-It does not try to replace the agent pattern. It makes that pattern safe to run.
-
-### What MartinLoop Does Today
-
-| Capability | Current behavior |
+| Risk in agentic coding loops | Martin Loop control |
 |---|---|
-| Budget governance | Enforces `maxUsd`, `softLimitUsd`, `maxIterations`, and `maxTokens`; rejects attempts projected to exceed remaining budget and exits on budget or iteration exhaustion. Hard USD budget caps that stop work before the next attempt breaches policy. |
-| Verifier gate | A run only reaches `completed` when the adapter result and verifier state pass. Unsafe verifier commands are blocked before agent execution. |
-| Failure taxonomy | Classifies failures across 11 current classes, including hallucination, test regression, scope creep, repo grounding failure, environment mismatch, and budget pressure, that distinguishes real success from unsafe, invalid, or terminal behavior.|
-| Safety leash | Evaluates verifier commands, file scope, dependency or migration changes that require approval, and secret-like values in task text. **Policy-as-code**. |
-| Rollback evidence | Captures rollback boundaries and restore outcomes for repo-backed attempts when a persistence store is configured. |
-| Context distillation | Carries a distilled summary of recent attempts and remaining constraints into subsequent attempts. |
-| Run records | The CLI appends JSONL loop records under `~/.martin/runs/<workspaceId>.jsonl`; lower-level stores can also persist contracts, ledgers, and attempt artifacts.
-
-
-⭐The result is a runtime that can complete good work, refuse unsafe work, stop uneconomical work, and leave evidence behind.✅
----
-
-## The Ralph Loop, explained
-
-**"Everybody has gotten infatuated with what we call these Ralph Wiggum loops, just like send the thing off and it'll just go figure something out..A, It never figures anything out. And B, you just get this ginormous bill...**" - Chamath Palihapitiya, All-In Podcast #263, March 2026
-
-⛔ The **Ralph Loop** is the failure mode where an AI coding agent keeps trying without knowing when it should stop.
-
-The pattern is simple: attempt the task, run checks, retry on failure, repeat. The problem is not that the loop exists. The problem is that most implementations have no hard budget cap, no signed evidence layer, and no pre-execution control system. They know how to keep trying. They do **not** know when continuing is unsafe, uneconomical, or impossible.
-
-✅ Martin Loop solves the Ralph Loop problem by enforcing rules **before** damage happens:
-
-- it stops the next attempt before budget overspend
-- it classifies unsafe or invalid actions before execution
-- it appends a structured JSONL audit record for every attempt
-- it rolls back failed runs instead of leaving broken state behind
-- it reduces runaway token growth with context distillation
+| Retry loops can spend without a hard stop | Budget admission checks, soft limits, hard USD caps, iteration caps, and token caps |
+| Agents can mutate the wrong surface | Task contracts, allowed paths, denied paths, policy leashes, and rollback evidence |
+| "Verifier passed" can hide that no verifier ran | Verifier lifecycle state, failure taxonomy, and machine-readable exit reasons |
+| Failure evidence is easy to lose | Canonical run records, ledger events, receipts, and handoff artifacts |
+| Operators need proof before widening claims | Claim linting, release gates, audit packs, and signed autonomy certification artifacts |
 
-If Ralph ever burned $165.70 on your dime, you're in the right place. Martin stopped him at $4.97 with a full audit trail. LFG! 🚀 Finally a Martin Prince leash for Ralph Wiggums! :)  
+Martin Loop does not replace Claude, Codex, or other coding agents. It gives those agents an operating envelope.
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/martin-raplph.png.jpg" alt="Martin vs Ralph — governed vs ungoverned agent loop" width="240">
-</div>
+![Martin Loop architecture](./docs/assets/architecture.svg)
 
-### How It Works — Five Layers
+## What It Does Today
 
-| Layer | What it does |
+| Capability | Current behavior |
 |---|---|
-| **1. Task Contract** | Objective, verifier plan, repo root, allowed/denied paths, acceptance criteria, workspace, project, and budget. |
-| **2. Policy & Budget** | Defaults from `martin.config.yaml`; CLI flags override. Budget preflight rejects attempts before execution. |
-| **3. Agent Adapters** | Claude CLI, Codex CLI, direct-provider, and stub adapters normalize execution results into the core runtime contract. |
-| **4. Safety & Verification** | Verifier commands, file scope, approval-boundary changes, secret-like values, and grounding determine whether work is kept. |
-| **5. Persistence** | CLI writes JSONL records under `~/.martin/runs/`. Repo-backed runs can also persist contracts, ledgers, diffs, and rollback artifacts. |
-
----
-
-## See It In Action
-
-Same task, same starting state. MartinLoop completes in one verified attempt at `$2.30`. The uncontrolled loop retries four times, spends `$5.20`, and fails with no audit trail.
-
-Martin Loop matters because it turns AI coding from an opaque experiment into something that can be governed, replayed, verified, and trusted.
-
-<div align="center">
-  <img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/side-by-side.svg" alt="Martin vs Ralph — governed vs ungoverned agent loop side-by-side benchmark comparison" width="720" height="1080">
-</div>
+| Budget governance | Enforces `maxUsd`, `softLimitUsd`, `maxIterations`, and `maxTokens`; rejects attempts projected to exceed remaining budget. |
+| Safety leash | Blocks unsafe verifier commands, out-of-scope writes, secret-like task text, and policy-restricted surfaces before accepting work. |
+| Adapter execution | Normalizes Claude CLI, Codex CLI, direct-provider, and stub execution into one runtime result contract. |
+| Verification gate | A run reaches `completed` only when adapter execution and verifier state both support the result. |
+| Rollback evidence | Captures rollback boundaries and restore outcomes for repo-backed attempts when persistence is configured. |
+| Trace intelligence | Reads run ledgers and reports loop patterns such as recovery exhaustion, verifier blind spots, oscillation, and budget pressure. |
+| Guarded improvement | Emits improvement evidence and promotion artifacts; trusted-surface promotion remains policy-gated and claim-safe. |
+| MCP package | Provides a standalone `@martinloop/mcp` server with `martin_run`, `martin_inspect`, and `martin_status`. |
 
+## Quick Start
 
-Reproducible locally:
+Install the public package:
 
-```sh
-pnpm --filter @martin/benchmarks test
-pnpm --filter @martin/benchmarks eval
-pnpm --filter @martin/benchmarks eval:phase12
+```bash
+npm install martin-loop
+npx martin-loop --help
 ```
 
----
+Run a provider-free stub loop first:
 
-## Quick Start
-
-```sh
-npm install -g martin-loop
+```bash
+MARTIN_LIVE=false MARTIN_NO_BRIEF=1 npx martin-loop run --objective "Summarize this repository" --yes
 ```
 
-This installs both the `martin-loop` package and the `martin` command alias. The package is currently published on npm as version `0.1.2`.
-
-### Public Package Surface
-
-The frozen public package surface for this release candidate is:
+Run a governed task with budget and verifier controls:
 
-- Install target: `npm install martin-loop`
-- CLI target: `npx martin-loop`
-- SDK target: `import { MartinLoop } from "martin-loop"`
-
-The `martin` command alias is installed for local operator convenience, but the public CLI surface is `npx martin-loop`.
-
-### Run a governed task
-
-```sh
-martin run "fix the auth regression" \
+```bash
+npx martin-loop run \
+  --objective "Fix the auth regression" \
   --budget 3.00 \
-  --verify "pnpm test"
+  --verify "pnpm test" \
+  --allow-path "src/**" \
+  --deny-path ".env*"
 ```
 
-You can also pass the objective explicitly:
+Inspect a persisted run record:
 
-```sh
-martin run --objective "fix the auth regression" --budget 3.00 --verify "pnpm test"
+```bash
+npx martin-loop inspect --file ~/.martin/runs/<workspaceId>.jsonl
 ```
 
-For a no-spend repo-local dry run, use the stub adapter:
+## MCP Server
 
-```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
-```
-
-### Inspect or resume runs
+Use the standalone MCP package when an MCP host needs to invoke Martin Loop:
 
-```sh
-martin inspect --file ~/.martin/runs/<workspaceId>.jsonl
-martin resume <loopId>
+```bash
+npx @martinloop/mcp
 ```
 
-`inspect` prints a portfolio summary for records in the file. `resume` looks up a persisted loop record by ID under `~/.martin/runs/`.
+Claude Code examples:
 
----
-
-## CLI
+```bash
+claude mcp add --scope user martin-loop -- npx @martinloop/mcp
+```
 
-```text
-martin run <objective> [options]
+Windows PowerShell or cmd:
 
-  --objective <text>      The task to accomplish, or pass it as the first positional arg
-  --budget <n>            Hard cost cap in USD
-  --budget-usd <n>        Alias for --budget
-  --soft-limit-usd <n>    Soft budget threshold in USD
-  --verify <cmd>          Verifier command after each attempt
-  --max-iterations <n>    Maximum number of attempts
-  --max-tokens <n>        Maximum total token budget
-  --engine <name>         Adapter to use: claude (default) or codex
-  --model <name>          Override the adapter model
-  --cwd <path>            Repo root for the run
-  --allow-path <glob>     Restrict agent writes to this path pattern; repeatable
-  --deny-path <glob>      Block this path pattern; repeatable
-  --accept <criterion>    Add an acceptance criterion; repeatable
-  --config <path>         Path to a martin.config.yaml file
-  --workspace <id>        Workspace ID for the run record
-  --project <id>          Project ID for the run record
-  --metadata <key=value>  Attach metadata to the run record; repeatable
+```powershell
+claude mcp add --scope user martin-loop cmd /c "npx @martinloop/mcp"
 ```
 
-The public CLI also includes `inspect`, `resume`, and a `bench` redirect that points reviewers to the workspace benchmark harness.
+The standalone MCP package is intentionally narrow. It exposes:
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/Keesan12/martin-loop/main/docs/assets/cli-static.svg" alt="MartinLoop CLI terminal output" width="720">
-</div>
+- `martin_run`
+- `martin_inspect`
+- `martin_status`
 
----
+Official registry publication is a guarded release step. The local package gate is:
 
-## Policy File
+```bash
+pnpm --filter @martinloop/mcp test
+pnpm --filter @martinloop/mcp build
+pnpm --filter @martinloop/mcp smoke:pack
+pnpm --filter @martinloop/mcp smoke:published
+```
 
-Drop a `martin.config.yaml` in your repo root to set governance defaults:
+## Public Package Surface
 
-```yaml
-budget:
-  maxUsd: 5.00
-  softLimitUsd: 3.75
-  maxIterations: 5
-  maxTokens: 40000
-
-governance:
-  destructiveActionPolicy: approval
-  telemetryDestination: local-only
-  verifierRules:
-    - pnpm test
-```
+Frozen public install targets:
 
-CLI flags override config values when provided.
+- Install: `npm install martin-loop`
+- CLI: `npx martin-loop`
+- SDK: `import { MartinLoop } from "martin-loop"`
+- MCP: `npx @martinloop/mcp`
 
----
+The root package facade vendors the runtime, adapters, CLI, SDK, contracts, policy, audit exporter, and HeadlessOS core into `dist/`. Internal workspace package names such as `@martin/core` and `@martin/adapters` are implementation details unless separately published.
 
 ## TypeScript SDK
 
-```sh
-npm install martin-loop
-```
-
 ```typescript
 import {
   MartinLoop,
@@ -249,7 +155,7 @@ const loop = new MartinLoop({
       maxUsd: 3.00,
       softLimitUsd: 2.25,
       maxIterations: 3,
-      maxTokens: 20_000
+      maxTokens: 20000
     }
   }
 });
@@ -274,72 +180,119 @@ const loop = new MartinLoop({
 });
 ```
 
-The lower-level `runMartin` function is also exported for callers that want to assemble the runtime input directly.
+`runMartin` is also exported for callers that want to assemble runtime input directly.
 
----
+## CLI Reference
 
-## Workspace Map
+```text
+martin-loop run <objective> [options]
 
-| Package or app | Role |
-|---|---|
-| `martin-loop` | Root public npm facade that vendors the runtime, CLI, adapters, and contracts into `dist/`. |
-| `@martin/contracts` | Shared types for loops, policy, governance, budget, telemetry, and rollback. |
-| `@martin/core` | Runtime controller, policy engine, safety leash, grounding, persistence, and rollback logic. |
-| `@martin/adapters` | Claude CLI, Codex CLI, direct-provider, and stub adapter surfaces. |
-| `@martin/cli` | Local CLI implementation for `run`, `inspect`, `resume`, and the benchmark redirect. |
-| `@martin/mcp` | MCP server tools: `martin_run`, `martin_inspect`, and `martin_status`. |
-| `benchmarks/` | Workspace-only deterministic benchmark and RC validation harness. |
-| `apps/control-plane/` | Hosted control-plane workstream, outside the initial npm package surface. |
-| `apps/local-dashboard/` | Local dashboard/read-model viewer, not currently packaged as public npm API. |
+  --objective <text>      Task to accomplish, or pass it as the first positional arg
+  --budget <n>            Hard cost cap in USD
+  --budget-usd <n>        Alias for --budget
+  --soft-limit-usd <n>    Soft budget threshold in USD
+  --verify <cmd>          Verifier command after each attempt
+  --max-iterations <n>    Maximum number of attempts
+  --max-tokens <n>        Maximum total token budget
+  --engine <name>         Adapter to use: claude or codex
+  --model <name>          Adapter model override
+  --cwd <path>            Repo root for the run
+  --allow-path <glob>     Restrict agent writes to this path pattern; repeatable
+  --deny-path <glob>      Block this path pattern; repeatable
+  --accept <criterion>    Acceptance criterion; repeatable
+  --config <path>         Path to martin.config.yaml
+  --workspace <id>        Workspace ID for the run record
+  --project <id>          Project ID for the run record
+  --metadata <key=value>  Attach metadata to the run record; repeatable
+```
 
-The `@martin/core`, `@martin/adapters`, and `@martin/contracts` package manifests are still private workspace packages; the public install target is the root `martin-loop` facade.
+The public CLI also includes `inspect`, `resume`, and a `bench` redirect that points reviewers to the workspace benchmark harness.
+
+## Configuration
 
----
+Drop a `martin.config.yaml` in the 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
+```
+
+CLI flags override config values when provided.
+
+## Claim Boundaries
+
+Martin Loop has implemented guarded learning, signed promotion artifacts, trace-autonomy certification tooling, and fail-closed claim gates. That is not the same as an unrestricted self-modifying production system.
+
+Do not use unqualified public wording for full hands-off operation, unrestricted system writes, any-part self-updates, fully self-learning behavior, or improvement claims without scope and evidence qualifiers.
+
+The bounded future trace-intelligence claim is allowed only after the trace-autonomy certification gate, signed bundle, required live evidence, and external audit signoff pass.
 
 ## Development
 
-Requirements: Node 20+ and pnpm 10.x.
+Requirements:
 
-```sh
+- Node 20+
+- pnpm 10.x
+
+```bash
 git clone https://github.com/Keesan12/martin-loop.git
 cd martin-loop
 pnpm install
-
+pnpm build
 pnpm test
 pnpm lint
-pnpm build
 ```
 
-```md
-Current RC gate commands:
+Release and claim gates:
 
-```sh
+```bash
 pnpm oss:validate
+pnpm release:surface:validate
 pnpm public:smoke
+pnpm mcp:published:smoke
 pnpm repo:smoke
 pnpm rc:validate
 pnpm pilot:prep:validate
+pnpm claims:lint
+pnpm release:gate:review
 pnpm release:matrix:local
-Caution: Registry Publication
-
-This package is published through the public martin-loop package surface. Treat registry publication as a guarded release step: verify the RC gate commands, confirm the version follows semantic versioning, and document breaking changes before publishing.
-
-> **Caution:** This package is live on npm. Treat registry publication as a guarded release step — verify the RC gate commands, confirm semantic versioning, and document breaking changes before publishing.
-
-The repository is organized as a dual-track workspace: the OSS runtime and package facade are present and published, while the hosted control-plane, local dashboard, and benchmark harness remain gated in private workspace for future release rather than the primary npm package API.
+```
 
-Helpful docs:
+Useful evidence docs:
 
 - [OSS quickstart](./docs/oss/QUICKSTART.md)
 - [OSS examples](./docs/oss/EXAMPLES.md)
 - [OSS boundary report](./docs/oss/OSS-BOUNDARY-REPORT.md)
 - [Release surface report](./docs/oss/RELEASE-SURFACE-REPORT.md)
+- [Release gate review](./docs/release/RELEASE-GATE-REVIEW.md)
+- [Phase 3 autonomy handoff](./docs/handoffs/2026-05-07-phase3-autonomy-implementation-handoff.md)
 
----
+## Workspace Map
+
+| Package or app | Role |
+|---|---|
+| `martin-loop` | Root public npm facade that vendors the runtime, CLI, adapters, SDK, contracts, and policy into `dist/`. |
+| `@martin/core` | Runtime controller, policy engine, safety leash, grounding, persistence, rollback, and autonomy primitives. |
+| `@martin/adapters` | Claude CLI, Codex CLI, direct-provider, and stub adapter surfaces. |
+| `@martin/cli` | Local CLI implementation for `run`, `inspect`, `resume`, `verify`, `audit`, `doctor`, `explain`, and improvement flows. |
+| `@martin/trace-intelligence` | Run-ledger analysis, trace pattern detection, improvement tasks, and trace-autonomy certification. |
+| `@martinloop/mcp` | Standalone MCP server package for `martin_run`, `martin_inspect`, and `martin_status`. |
+| `apps/control-plane` | Hosted/operator control-plane workstream, outside the initial npm package surface. |
+| `apps/local-dashboard` | Local read-model viewer, not currently packaged as public npm API. |
+| `benchmarks` | Workspace-only deterministic benchmark and RC validation harness. |
 
 ## Contributing
 
-```sh
+```bash
 git checkout -b feat/your-feature
 pnpm lint
 pnpm test
@@ -347,16 +300,8 @@ git commit -m "feat: describe what you built"
 git push -u origin feat/your-feature
 ```
 
-Conventional commit prefixes: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, and `test:`.
-
----
-
-<div align="center">
-
-**⭐Give the repo a star⭐** if you think AI coding needs budgets, brakes, and receipts.
-
-**MIT Licensed** · [martinloop.com](https://martinloop.com) · [keesan@martinloop.com](mailto:keesan@martinloop.com)
+Use conventional commit prefixes such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, and `chore:`.
 
-*"AI coding accountability: completes good work, refuses unsafe work, stops uneconomical work."*
+## License
 
-</div>
+MIT. See [LICENSE](./LICENSE).

package/demo/seeded-workspace/README.md

@@ -0,0 +1,35 @@
+# MartinLoop Demo Sandbox
+
+This workspace is the safe public demo copied by `martin-loop demo`.
+
+It is intentionally small:
+
+- `npm test` is green out of the box
+- `martin.config.yaml` keeps the budget tiny
+- the first suggested MartinLoop run can stay in stub mode with `MARTIN_LIVE=false`
+
+## Files
+
+- `src/invoice-summary.js`: tiny module used by the demo task
+- `test/invoice-summary.test.js`: Node test suite
+- `TASKS.md`: suggested objectives for a stub-safe run or a live adapter run
+- `martin.config.yaml`: low-risk governance defaults
+
+## Suggested flow
+
+```sh
+npm install
+npm test
+```
+
+Safe first run:
+
+```sh
+MARTIN_LIVE=false npx martin-loop run "Summarize the demo workspace and confirm the verifier is green" --verify "npm test"
+```
+
+Optional live run:
+
+```sh
+npx martin-loop run "Add support for a discount percentage to summarizeInvoice and update the tests" --verify "npm test" --engine codex
+```

package/demo/seeded-workspace/TASKS.md

@@ -0,0 +1,29 @@
+# Suggested Demo Tasks
+
+## Stub-safe first run
+
+Use this when you want to see MartinLoop create a governed run record without spending provider budget:
+
+```text
+Summarize the demo workspace, confirm the verifier command is green, and explain the safest next change to make.
+```
+
+Verifier:
+
+```sh
+npm test
+```
+
+## Optional live run
+
+Use this when you want a real coding task in the sandbox:
+
+```text
+Add support for a discount percentage to summarizeInvoice and update the tests while keeping the existing tax behavior intact.
+```
+
+Verifier:
+
+```sh
+npm test
+```

package/demo/seeded-workspace/martin.config.yaml

@@ -0,0 +1,11 @@
+policyProfile: strict_local
+budget:
+  maxUsd: 2
+  softLimitUsd: 1
+  maxIterations: 2
+  maxTokens: 12000
+governance:
+  destructiveActionPolicy: approval
+  telemetryDestination: local-only
+  verifierRules:
+    - npm test

package/demo/seeded-workspace/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "martin-loop-demo-sandbox",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/demo/seeded-workspace/src/invoice-summary.js

@@ -0,0 +1,11 @@
+export function summarizeInvoice(items, taxRate = 0) {
+  const subtotal = items.reduce((sum, item) => sum + item.quantity * item.unitPrice, 0);
+  const tax = Number((subtotal * taxRate).toFixed(2));
+  const total = Number((subtotal + tax).toFixed(2));
+
+  return {
+    subtotal: Number(subtotal.toFixed(2)),
+    tax,
+    total
+  };
+}