martin-loop 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +362 -362
- package/docs/oss/EXAMPLES.md +126 -126
- package/docs/oss/OSS-BOUNDARY-REPORT.json +113 -113
- package/docs/oss/OSS-BOUNDARY-REPORT.md +48 -48
- package/docs/oss/QUICKSTART.md +135 -135
- package/docs/oss/README.md +93 -93
- package/docs/oss/RELEASE-SURFACE-REPORT.json +45 -45
- package/docs/oss/RELEASE-SURFACE-REPORT.md +35 -35
- package/package.json +10 -12
package/docs/oss/QUICKSTART.md
CHANGED
|
@@ -1,135 +1,135 @@
|
|
|
1
|
-
# Quickstart
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## Public launch target vs current RC path
|
|
6
|
-
|
|
7
|
-
The frozen public launch target is:
|
|
8
|
-
|
|
9
|
-
- `npm install martin-loop`
|
|
10
|
-
- `npx martin-loop ...`
|
|
11
|
-
- `import { MartinLoop } from "martin-loop"`
|
|
12
|
-
|
|
13
|
-
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.
|
|
14
|
-
|
|
15
|
-
## Prerequisites
|
|
16
|
-
|
|
17
|
-
- Node.js 20+ recommended
|
|
18
|
-
- `pnpm` 10.x
|
|
19
|
-
- A clean local checkout of this repo
|
|
20
|
-
|
|
21
|
-
Optional for live runs:
|
|
22
|
-
|
|
23
|
-
- Claude Code CLI for the Claude adapter path
|
|
24
|
-
- OpenAI Codex CLI plus credentials for the Codex adapter path
|
|
25
|
-
|
|
26
|
-
## Install and build
|
|
27
|
-
|
|
28
|
-
From the repo root:
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
pnpm install
|
|
32
|
-
pnpm build
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Run the RC validation matrix
|
|
36
|
-
|
|
37
|
-
```bash
|
|
38
|
-
pnpm rc:validate
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
What this does:
|
|
42
|
-
|
|
43
|
-
- creates an isolated temporary home or profile directory
|
|
44
|
-
- points Martin run artifacts at that clean location
|
|
45
|
-
- runs the current build, lint, test, benchmark, and certification matrix
|
|
46
|
-
- writes step logs into a temp `martin-rc-validation-*` directory
|
|
47
|
-
|
|
48
|
-
Use this when you want to answer, "Can a fresh environment still reproduce the current RC baseline?"
|
|
49
|
-
|
|
50
|
-
## RC gate commands
|
|
51
|
-
|
|
52
|
-
The current Phase 13 RC gate is made of these commands:
|
|
53
|
-
|
|
54
|
-
- `pnpm oss:validate`
|
|
55
|
-
- `pnpm public:smoke`
|
|
56
|
-
- `pnpm repo:smoke`
|
|
57
|
-
- `pnpm rc:validate`
|
|
58
|
-
- `pnpm pilot:prep:validate`
|
|
59
|
-
- `pnpm release:matrix:local`
|
|
60
|
-
|
|
61
|
-
Recommended order for a fresh local reviewer:
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
pnpm oss:validate
|
|
65
|
-
pnpm public:smoke
|
|
66
|
-
pnpm repo:smoke
|
|
67
|
-
pnpm rc:validate
|
|
68
|
-
pnpm release:matrix:local
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
`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`.
|
|
72
|
-
|
|
73
|
-
## Stub-safe CLI run
|
|
74
|
-
|
|
75
|
-
This is the safest first run because it avoids real provider spend.
|
|
76
|
-
|
|
77
|
-
### PowerShell
|
|
78
|
-
|
|
79
|
-
```powershell
|
|
80
|
-
$env:MARTIN_LIVE='false'
|
|
81
|
-
pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
|
|
82
|
-
Remove-Item Env:MARTIN_LIVE
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
### Bash
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
MARTIN_LIVE=false pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
This path uses the stub adapter and still exercises the loop, persistence, and policy surfaces.
|
|
92
|
-
|
|
93
|
-
## Config-driven run
|
|
94
|
-
|
|
95
|
-
The repo ships an example config at `martin.config.example.yaml`.
|
|
96
|
-
|
|
97
|
-
Martin auto-looks for `martin.config.yaml` in the invocation root, or you can pass `--config <path>`.
|
|
98
|
-
|
|
99
|
-
Example:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
pnpm run:cli -- run --config martin.config.example.yaml --objective "Run with repo defaults" --verify "pnpm --filter @martin/core test"
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
## Inspect a saved run
|
|
106
|
-
|
|
107
|
-
Martin persists runs under `~/.martin/runs/` by default, or under `MARTIN_RUNS_DIR` if you override it.
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
pnpm run:cli -- inspect --file path/to/loop-record.json
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
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.
|
|
114
|
-
|
|
115
|
-
## MCP server
|
|
116
|
-
|
|
117
|
-
Build first, then start the server from the workspace:
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
pnpm --filter @martin/mcp build
|
|
121
|
-
node packages/mcp/dist/server.js
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
The current MCP tools are:
|
|
125
|
-
|
|
126
|
-
- `martin_run`
|
|
127
|
-
- `martin_inspect`
|
|
128
|
-
- `martin_status`
|
|
129
|
-
|
|
130
|
-
## Notes for reviewers
|
|
131
|
-
|
|
132
|
-
- Fresh-home behavior matters. Do not rely only on a long-lived `~/.martin` directory.
|
|
133
|
-
- Exact-versus-estimated cost labels are meaningful and should not be merged in docs or dashboards.
|
|
134
|
-
- The repo contains control-plane code, but the public OSS boundary is still being finalized during Phase 13.
|
|
135
|
-
- The benchmark harness remains a workspace-level RC surface; `martin bench` is not part of the publishable CLI boundary yet.
|
|
1
|
+
# Quickstart
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Public launch target vs current RC path
|
|
6
|
+
|
|
7
|
+
The frozen public launch target is:
|
|
8
|
+
|
|
9
|
+
- `npm install martin-loop`
|
|
10
|
+
- `npx martin-loop ...`
|
|
11
|
+
- `import { MartinLoop } from "martin-loop"`
|
|
12
|
+
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
## Prerequisites
|
|
16
|
+
|
|
17
|
+
- Node.js 20+ recommended
|
|
18
|
+
- `pnpm` 10.x
|
|
19
|
+
- A clean local checkout of this repo
|
|
20
|
+
|
|
21
|
+
Optional for live runs:
|
|
22
|
+
|
|
23
|
+
- Claude Code CLI for the Claude adapter path
|
|
24
|
+
- OpenAI Codex CLI plus credentials for the Codex adapter path
|
|
25
|
+
|
|
26
|
+
## Install and build
|
|
27
|
+
|
|
28
|
+
From the repo root:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pnpm install
|
|
32
|
+
pnpm build
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Run the RC validation matrix
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pnpm rc:validate
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
What this does:
|
|
42
|
+
|
|
43
|
+
- creates an isolated temporary home or profile directory
|
|
44
|
+
- points Martin run artifacts at that clean location
|
|
45
|
+
- runs the current build, lint, test, benchmark, and certification matrix
|
|
46
|
+
- writes step logs into a temp `martin-rc-validation-*` directory
|
|
47
|
+
|
|
48
|
+
Use this when you want to answer, "Can a fresh environment still reproduce the current RC baseline?"
|
|
49
|
+
|
|
50
|
+
## RC gate commands
|
|
51
|
+
|
|
52
|
+
The current Phase 13 RC gate is made of these commands:
|
|
53
|
+
|
|
54
|
+
- `pnpm oss:validate`
|
|
55
|
+
- `pnpm public:smoke`
|
|
56
|
+
- `pnpm repo:smoke`
|
|
57
|
+
- `pnpm rc:validate`
|
|
58
|
+
- `pnpm pilot:prep:validate`
|
|
59
|
+
- `pnpm release:matrix:local`
|
|
60
|
+
|
|
61
|
+
Recommended order for a fresh local reviewer:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pnpm oss:validate
|
|
65
|
+
pnpm public:smoke
|
|
66
|
+
pnpm repo:smoke
|
|
67
|
+
pnpm rc:validate
|
|
68
|
+
pnpm release:matrix:local
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`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`.
|
|
72
|
+
|
|
73
|
+
## Stub-safe CLI run
|
|
74
|
+
|
|
75
|
+
This is the safest first run because it avoids real provider spend.
|
|
76
|
+
|
|
77
|
+
### PowerShell
|
|
78
|
+
|
|
79
|
+
```powershell
|
|
80
|
+
$env:MARTIN_LIVE='false'
|
|
81
|
+
pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
|
|
82
|
+
Remove-Item Env:MARTIN_LIVE
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Bash
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
MARTIN_LIVE=false pnpm run:cli -- run --objective "Summarize the current runtime state" --verify "pnpm --filter @martin/core test"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
This path uses the stub adapter and still exercises the loop, persistence, and policy surfaces.
|
|
92
|
+
|
|
93
|
+
## Config-driven run
|
|
94
|
+
|
|
95
|
+
The repo ships an example config at `martin.config.example.yaml`.
|
|
96
|
+
|
|
97
|
+
Martin auto-looks for `martin.config.yaml` in the invocation root, or you can pass `--config <path>`.
|
|
98
|
+
|
|
99
|
+
Example:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pnpm run:cli -- run --config martin.config.example.yaml --objective "Run with repo defaults" --verify "pnpm --filter @martin/core test"
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Inspect a saved run
|
|
106
|
+
|
|
107
|
+
Martin persists runs under `~/.martin/runs/` by default, or under `MARTIN_RUNS_DIR` if you override it.
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
pnpm run:cli -- inspect --file path/to/loop-record.json
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
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.
|
|
114
|
+
|
|
115
|
+
## MCP server
|
|
116
|
+
|
|
117
|
+
Build first, then start the server from the workspace:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pnpm --filter @martin/mcp build
|
|
121
|
+
node packages/mcp/dist/server.js
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The current MCP tools are:
|
|
125
|
+
|
|
126
|
+
- `martin_run`
|
|
127
|
+
- `martin_inspect`
|
|
128
|
+
- `martin_status`
|
|
129
|
+
|
|
130
|
+
## Notes for reviewers
|
|
131
|
+
|
|
132
|
+
- Fresh-home behavior matters. Do not rely only on a long-lived `~/.martin` directory.
|
|
133
|
+
- Exact-versus-estimated cost labels are meaningful and should not be merged in docs or dashboards.
|
|
134
|
+
- The repo contains control-plane code, but the public OSS boundary is still being finalized during Phase 13.
|
|
135
|
+
- The benchmark harness remains a workspace-level RC surface; `martin bench` is not part of the publishable CLI boundary yet.
|
package/docs/oss/README.md
CHANGED
|
@@ -1,93 +1,93 @@
|
|
|
1
|
-
# Martin OSS Core
|
|
2
|
-
|
|
3
|
-
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.
|
|
4
|
-
|
|
5
|
-
## What the OSS core includes today
|
|
6
|
-
|
|
7
|
-
- `@martin/contracts`: shared loop, policy, grounding, leash, budget, and rollback types
|
|
8
|
-
- `@martin/core`: the runtime controller, persistence layer, grounding scanner, leash engine, patch-truth scoring, and rollback restoration logic
|
|
9
|
-
- `@martin/adapters`: normalized Claude CLI, Codex CLI, and direct-provider or stub adapter surfaces
|
|
10
|
-
- `@martin/cli`: the local operator CLI for `run`, `inspect`, and `resume`
|
|
11
|
-
- `@martin/mcp`: the MCP server surface for `martin_run`, `martin_inspect`, and `martin_status`
|
|
12
|
-
|
|
13
|
-
## What is still outside the initial OSS promise
|
|
14
|
-
|
|
15
|
-
- The root workspace now exposes the `martin-loop` public package facade, but registry publication is still a later release step.
|
|
16
|
-
- `@martin/contracts`, `@martin/core`, and `@martin/adapters` are still marked `private` in their package manifests.
|
|
17
|
-
- The hosted control-plane and local dashboard remain in the repo, but they are not yet the finalized public OSS boundary.
|
|
18
|
-
- The benchmark harness remains a workspace-only RC surface under `benchmarks/` and is not part of the publishable CLI boundary yet.
|
|
19
|
-
- Final licensing, public package publishing, and managed-product packaging are still gated behind later Phase 13 to Phase 15 work.
|
|
20
|
-
|
|
21
|
-
That means this repo is ready for grounded engineering review and RC validation, but it is not yet claiming a finished public OSS release.
|
|
22
|
-
|
|
23
|
-
## Runtime truth the current core enforces
|
|
24
|
-
|
|
25
|
-
- Explicit policy phases: `GATHER`, `ADMIT`, `PATCH`, `VERIFY`, `RECOVER`, `ESCALATE`, `ABORT`, `HANDOFF`
|
|
26
|
-
- Grounding scans against repo anatomy before success is accepted
|
|
27
|
-
- Blocking leash behavior for unsafe verifier commands, file-scope violations, approval-boundary changes, and secret handling
|
|
28
|
-
- Provenance-aware accounting using `actual`, `estimated`, and `unavailable`
|
|
29
|
-
- Persisted attempt artifacts under `~/.martin/runs/<runId>/artifacts/attempt-XXX/`
|
|
30
|
-
- Patch-truth scoring plus rollback boundary and restore outcome artifacts for discarded or blocked repo-backed attempts
|
|
31
|
-
|
|
32
|
-
## Trust profiles
|
|
33
|
-
|
|
34
|
-
Martin currently exposes these execution profiles:
|
|
35
|
-
|
|
36
|
-
- `strict_local`: safest default for local repo work
|
|
37
|
-
- `ci_safe`: tighter CI-oriented behavior
|
|
38
|
-
- `staging_controlled`: controlled outbound or network allowances with approvals
|
|
39
|
-
- `research_untrusted`: looser network posture for research-oriented runs while still enforcing approval boundaries
|
|
40
|
-
|
|
41
|
-
## Accounting labels
|
|
42
|
-
|
|
43
|
-
Martin keeps cost provenance explicit:
|
|
44
|
-
|
|
45
|
-
- `actual`: reported directly by the provider or adapter settlement
|
|
46
|
-
- `estimated`: derived from pricing logic or modeled usage
|
|
47
|
-
- `unavailable`: the adapter could not produce a trustworthy number
|
|
48
|
-
|
|
49
|
-
Do not collapse those labels when building dashboards, docs, or public claims.
|
|
50
|
-
|
|
51
|
-
## Frozen public launch target
|
|
52
|
-
|
|
53
|
-
The current engineering memo freezes these public-launch targets for release planning:
|
|
54
|
-
|
|
55
|
-
- install target: `npm install martin-loop`
|
|
56
|
-
- CLI target: `npx martin-loop ...`
|
|
57
|
-
- SDK target: `import { MartinLoop } from "martin-loop"`
|
|
58
|
-
|
|
59
|
-
Those targets are now implemented in the root package facade and verified through a clean-install smoke test. During the current RC phase, the honest operator path still includes the repo-local workflow documented below and in the quickstart, because public registry publication and broader release packaging remain later steps.
|
|
60
|
-
|
|
61
|
-
## Reproducibility
|
|
62
|
-
|
|
63
|
-
From the repo root:
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
pnpm install
|
|
67
|
-
pnpm build
|
|
68
|
-
pnpm rc:validate
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
`pnpm rc:validate` runs the current RC matrix in an isolated temp home so fresh-home behavior is checked instead of depending on warmed `~/.martin` state. Use `pnpm rc:validate:install` when you also want the RC run to perform a clean `pnpm install --frozen-lockfile` first.
|
|
72
|
-
|
|
73
|
-
## RC gate commands
|
|
74
|
-
|
|
75
|
-
The current release-candidate gate is:
|
|
76
|
-
|
|
77
|
-
- `pnpm oss:validate`
|
|
78
|
-
- `pnpm public:smoke`
|
|
79
|
-
- `pnpm repo:smoke`
|
|
80
|
-
- `pnpm rc:validate`
|
|
81
|
-
- `pnpm pilot:prep:validate`
|
|
82
|
-
- `pnpm release:matrix:local`
|
|
83
|
-
|
|
84
|
-
`pnpm rc:validate` now includes the machine-checked release-surface audit in addition to the existing build, test, benchmark, provider-path, OSS-boundary, and control-plane checks.
|
|
85
|
-
|
|
86
|
-
## Where to go next
|
|
87
|
-
|
|
88
|
-
- [`docs/oss/QUICKSTART.md`](./QUICKSTART.md) for clone-to-first-run setup
|
|
89
|
-
- [`docs/oss/EXAMPLES.md`](./EXAMPLES.md) for grounded CLI and MCP examples
|
|
90
|
-
- [`docs/oss/OSS-BOUNDARY-REPORT.md`](./OSS-BOUNDARY-REPORT.md) for the current machine-checked OSS boundary and public-surface status
|
|
91
|
-
- [`docs/oss/RELEASE-SURFACE-REPORT.md`](./RELEASE-SURFACE-REPORT.md) for the current machine-checked release-surface audit
|
|
92
|
-
- [`docs/pilot/README.md`](../pilot/README.md) for the pilot-prep package that remains explicitly gated behind Phase 13 completion
|
|
93
|
-
- [`../../README.md`](../../README.md) for the repo-level RC status and workspace map
|
|
1
|
+
# Martin OSS Core
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## What the OSS core includes today
|
|
6
|
+
|
|
7
|
+
- `@martin/contracts`: shared loop, policy, grounding, leash, budget, and rollback types
|
|
8
|
+
- `@martin/core`: the runtime controller, persistence layer, grounding scanner, leash engine, patch-truth scoring, and rollback restoration logic
|
|
9
|
+
- `@martin/adapters`: normalized Claude CLI, Codex CLI, and direct-provider or stub adapter surfaces
|
|
10
|
+
- `@martin/cli`: the local operator CLI for `run`, `inspect`, and `resume`
|
|
11
|
+
- `@martin/mcp`: the MCP server surface for `martin_run`, `martin_inspect`, and `martin_status`
|
|
12
|
+
|
|
13
|
+
## What is still outside the initial OSS promise
|
|
14
|
+
|
|
15
|
+
- The root workspace now exposes the `martin-loop` public package facade, but registry publication is still a later release step.
|
|
16
|
+
- `@martin/contracts`, `@martin/core`, and `@martin/adapters` are still marked `private` in their package manifests.
|
|
17
|
+
- The hosted control-plane and local dashboard remain in the repo, but they are not yet the finalized public OSS boundary.
|
|
18
|
+
- The benchmark harness remains a workspace-only RC surface under `benchmarks/` and is not part of the publishable CLI boundary yet.
|
|
19
|
+
- Final licensing, public package publishing, and managed-product packaging are still gated behind later Phase 13 to Phase 15 work.
|
|
20
|
+
|
|
21
|
+
That means this repo is ready for grounded engineering review and RC validation, but it is not yet claiming a finished public OSS release.
|
|
22
|
+
|
|
23
|
+
## Runtime truth the current core enforces
|
|
24
|
+
|
|
25
|
+
- Explicit policy phases: `GATHER`, `ADMIT`, `PATCH`, `VERIFY`, `RECOVER`, `ESCALATE`, `ABORT`, `HANDOFF`
|
|
26
|
+
- Grounding scans against repo anatomy before success is accepted
|
|
27
|
+
- Blocking leash behavior for unsafe verifier commands, file-scope violations, approval-boundary changes, and secret handling
|
|
28
|
+
- Provenance-aware accounting using `actual`, `estimated`, and `unavailable`
|
|
29
|
+
- Persisted attempt artifacts under `~/.martin/runs/<runId>/artifacts/attempt-XXX/`
|
|
30
|
+
- Patch-truth scoring plus rollback boundary and restore outcome artifacts for discarded or blocked repo-backed attempts
|
|
31
|
+
|
|
32
|
+
## Trust profiles
|
|
33
|
+
|
|
34
|
+
Martin currently exposes these execution profiles:
|
|
35
|
+
|
|
36
|
+
- `strict_local`: safest default for local repo work
|
|
37
|
+
- `ci_safe`: tighter CI-oriented behavior
|
|
38
|
+
- `staging_controlled`: controlled outbound or network allowances with approvals
|
|
39
|
+
- `research_untrusted`: looser network posture for research-oriented runs while still enforcing approval boundaries
|
|
40
|
+
|
|
41
|
+
## Accounting labels
|
|
42
|
+
|
|
43
|
+
Martin keeps cost provenance explicit:
|
|
44
|
+
|
|
45
|
+
- `actual`: reported directly by the provider or adapter settlement
|
|
46
|
+
- `estimated`: derived from pricing logic or modeled usage
|
|
47
|
+
- `unavailable`: the adapter could not produce a trustworthy number
|
|
48
|
+
|
|
49
|
+
Do not collapse those labels when building dashboards, docs, or public claims.
|
|
50
|
+
|
|
51
|
+
## Frozen public launch target
|
|
52
|
+
|
|
53
|
+
The current engineering memo freezes these public-launch targets for release planning:
|
|
54
|
+
|
|
55
|
+
- install target: `npm install martin-loop`
|
|
56
|
+
- CLI target: `npx martin-loop ...`
|
|
57
|
+
- SDK target: `import { MartinLoop } from "martin-loop"`
|
|
58
|
+
|
|
59
|
+
Those targets are now implemented in the root package facade and verified through a clean-install smoke test. During the current RC phase, the honest operator path still includes the repo-local workflow documented below and in the quickstart, because public registry publication and broader release packaging remain later steps.
|
|
60
|
+
|
|
61
|
+
## Reproducibility
|
|
62
|
+
|
|
63
|
+
From the repo root:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pnpm install
|
|
67
|
+
pnpm build
|
|
68
|
+
pnpm rc:validate
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`pnpm rc:validate` runs the current RC matrix in an isolated temp home so fresh-home behavior is checked instead of depending on warmed `~/.martin` state. Use `pnpm rc:validate:install` when you also want the RC run to perform a clean `pnpm install --frozen-lockfile` first.
|
|
72
|
+
|
|
73
|
+
## RC gate commands
|
|
74
|
+
|
|
75
|
+
The current release-candidate gate is:
|
|
76
|
+
|
|
77
|
+
- `pnpm oss:validate`
|
|
78
|
+
- `pnpm public:smoke`
|
|
79
|
+
- `pnpm repo:smoke`
|
|
80
|
+
- `pnpm rc:validate`
|
|
81
|
+
- `pnpm pilot:prep:validate`
|
|
82
|
+
- `pnpm release:matrix:local`
|
|
83
|
+
|
|
84
|
+
`pnpm rc:validate` now includes the machine-checked release-surface audit in addition to the existing build, test, benchmark, provider-path, OSS-boundary, and control-plane checks.
|
|
85
|
+
|
|
86
|
+
## Where to go next
|
|
87
|
+
|
|
88
|
+
- [`docs/oss/QUICKSTART.md`](./QUICKSTART.md) for clone-to-first-run setup
|
|
89
|
+
- [`docs/oss/EXAMPLES.md`](./EXAMPLES.md) for grounded CLI and MCP examples
|
|
90
|
+
- [`docs/oss/OSS-BOUNDARY-REPORT.md`](./OSS-BOUNDARY-REPORT.md) for the current machine-checked OSS boundary and public-surface status
|
|
91
|
+
- [`docs/oss/RELEASE-SURFACE-REPORT.md`](./RELEASE-SURFACE-REPORT.md) for the current machine-checked release-surface audit
|
|
92
|
+
- [`docs/pilot/README.md`](../pilot/README.md) for the pilot-prep package that remains explicitly gated behind Phase 13 completion
|
|
93
|
+
- [`../../README.md`](../../README.md) for the repo-level RC status and workspace map
|
|
@@ -1,45 +1,45 @@
|
|
|
1
|
-
{
|
|
2
|
-
"generatedAt": "2026-04-
|
|
3
|
-
"publicSurface": {
|
|
4
|
-
"packageName": "martin-loop",
|
|
5
|
-
"installCommand": "npm install martin-loop",
|
|
6
|
-
"npxCommand": "npx martin-loop",
|
|
7
|
-
"sdkImportStatement": "import { MartinLoop } from \"martin-loop\""
|
|
8
|
-
},
|
|
9
|
-
"rcGateCommands": [
|
|
10
|
-
"pnpm oss:validate",
|
|
11
|
-
"pnpm public:smoke",
|
|
12
|
-
"pnpm repo:smoke",
|
|
13
|
-
"pnpm rc:validate",
|
|
14
|
-
"pnpm pilot:prep:validate",
|
|
15
|
-
"pnpm release:matrix:local"
|
|
16
|
-
],
|
|
17
|
-
"docCoverage": {
|
|
18
|
-
"readme": {
|
|
19
|
-
"path": "README.md",
|
|
20
|
-
"hasPublicSurface": true,
|
|
21
|
-
"hasRcGateCommands": true,
|
|
22
|
-
"hasRegistryCaution": true
|
|
23
|
-
},
|
|
24
|
-
"ossReadme": {
|
|
25
|
-
"path": "docs\\oss\\README.md",
|
|
26
|
-
"hasPublicSurface": true,
|
|
27
|
-
"hasAccountingLabels": true,
|
|
28
|
-
"hasTrustProfiles": true,
|
|
29
|
-
"hasRegistryCaution": true
|
|
30
|
-
},
|
|
31
|
-
"quickstart": {
|
|
32
|
-
"path": "docs\\oss\\QUICKSTART.md",
|
|
33
|
-
"hasPublicSurface": true,
|
|
34
|
-
"hasRcGateCommands": true,
|
|
35
|
-
"hasRegistryCaution": true
|
|
36
|
-
},
|
|
37
|
-
"examples": {
|
|
38
|
-
"path": "docs\\oss\\EXAMPLES.md",
|
|
39
|
-
"hasRegistryCaution": true
|
|
40
|
-
}
|
|
41
|
-
},
|
|
42
|
-
"deprecatedFiles": [],
|
|
43
|
-
"verdict": "go",
|
|
44
|
-
"failures": []
|
|
45
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"generatedAt": "2026-04-23T15:03:11.006Z",
|
|
3
|
+
"publicSurface": {
|
|
4
|
+
"packageName": "martin-loop",
|
|
5
|
+
"installCommand": "npm install martin-loop",
|
|
6
|
+
"npxCommand": "npx martin-loop",
|
|
7
|
+
"sdkImportStatement": "import { MartinLoop } from \"martin-loop\""
|
|
8
|
+
},
|
|
9
|
+
"rcGateCommands": [
|
|
10
|
+
"pnpm oss:validate",
|
|
11
|
+
"pnpm public:smoke",
|
|
12
|
+
"pnpm repo:smoke",
|
|
13
|
+
"pnpm rc:validate",
|
|
14
|
+
"pnpm pilot:prep:validate",
|
|
15
|
+
"pnpm release:matrix:local"
|
|
16
|
+
],
|
|
17
|
+
"docCoverage": {
|
|
18
|
+
"readme": {
|
|
19
|
+
"path": "README.md",
|
|
20
|
+
"hasPublicSurface": true,
|
|
21
|
+
"hasRcGateCommands": true,
|
|
22
|
+
"hasRegistryCaution": true
|
|
23
|
+
},
|
|
24
|
+
"ossReadme": {
|
|
25
|
+
"path": "docs\\oss\\README.md",
|
|
26
|
+
"hasPublicSurface": true,
|
|
27
|
+
"hasAccountingLabels": true,
|
|
28
|
+
"hasTrustProfiles": true,
|
|
29
|
+
"hasRegistryCaution": true
|
|
30
|
+
},
|
|
31
|
+
"quickstart": {
|
|
32
|
+
"path": "docs\\oss\\QUICKSTART.md",
|
|
33
|
+
"hasPublicSurface": true,
|
|
34
|
+
"hasRcGateCommands": true,
|
|
35
|
+
"hasRegistryCaution": true
|
|
36
|
+
},
|
|
37
|
+
"examples": {
|
|
38
|
+
"path": "docs\\oss\\EXAMPLES.md",
|
|
39
|
+
"hasRegistryCaution": true
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"deprecatedFiles": [],
|
|
43
|
+
"verdict": "go",
|
|
44
|
+
"failures": []
|
|
45
|
+
}
|
|
@@ -1,35 +1,35 @@
|
|
|
1
|
-
# Martin Loop Phase 13 Release Surface Audit
|
|
2
|
-
|
|
3
|
-
Generated: 2026-04-
|
|
4
|
-
|
|
5
|
-
## Verdict
|
|
6
|
-
**GO**
|
|
7
|
-
|
|
8
|
-
## Public Package Surface
|
|
9
|
-
- Package target: martin-loop
|
|
10
|
-
- Install target: `npm install martin-loop`
|
|
11
|
-
- CLI target: `npx martin-loop`
|
|
12
|
-
- SDK target: `import { MartinLoop } from "martin-loop"`
|
|
13
|
-
|
|
14
|
-
## RC Gate Commands
|
|
15
|
-
- `pnpm oss:validate`
|
|
16
|
-
- `pnpm public:smoke`
|
|
17
|
-
- `pnpm repo:smoke`
|
|
18
|
-
- `pnpm rc:validate`
|
|
19
|
-
- `pnpm pilot:prep:validate`
|
|
20
|
-
- `pnpm release:matrix:local`
|
|
21
|
-
|
|
22
|
-
## Doc Coverage
|
|
23
|
-
| Surface | Path | Checks |
|
|
24
|
-
|---|---|---|
|
|
25
|
-
| Root README | README.md | public surface: yes, RC gate: yes, registry caution: yes |
|
|
26
|
-
| OSS README | docs/oss/README.md | public surface: yes, accounting labels: yes, trust profiles: yes, registry caution: yes |
|
|
27
|
-
| Quickstart | docs/oss/QUICKSTART.md | public surface: yes, RC gate: yes, registry caution: yes |
|
|
28
|
-
| Examples | docs/oss/EXAMPLES.md | registry caution: yes |
|
|
29
|
-
|
|
30
|
-
## Deprecated Files
|
|
31
|
-
- None.
|
|
32
|
-
|
|
33
|
-
## Findings
|
|
34
|
-
- No release-surface drift detected across the audited RC docs and commands.
|
|
35
|
-
|
|
1
|
+
# Martin Loop Phase 13 Release Surface Audit
|
|
2
|
+
|
|
3
|
+
Generated: 2026-04-23T15:03:11.006Z
|
|
4
|
+
|
|
5
|
+
## Verdict
|
|
6
|
+
**GO**
|
|
7
|
+
|
|
8
|
+
## Public Package Surface
|
|
9
|
+
- Package target: martin-loop
|
|
10
|
+
- Install target: `npm install martin-loop`
|
|
11
|
+
- CLI target: `npx martin-loop`
|
|
12
|
+
- SDK target: `import { MartinLoop } from "martin-loop"`
|
|
13
|
+
|
|
14
|
+
## RC Gate Commands
|
|
15
|
+
- `pnpm oss:validate`
|
|
16
|
+
- `pnpm public:smoke`
|
|
17
|
+
- `pnpm repo:smoke`
|
|
18
|
+
- `pnpm rc:validate`
|
|
19
|
+
- `pnpm pilot:prep:validate`
|
|
20
|
+
- `pnpm release:matrix:local`
|
|
21
|
+
|
|
22
|
+
## Doc Coverage
|
|
23
|
+
| Surface | Path | Checks |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Root README | README.md | public surface: yes, RC gate: yes, registry caution: yes |
|
|
26
|
+
| OSS README | docs/oss/README.md | public surface: yes, accounting labels: yes, trust profiles: yes, registry caution: yes |
|
|
27
|
+
| Quickstart | docs/oss/QUICKSTART.md | public surface: yes, RC gate: yes, registry caution: yes |
|
|
28
|
+
| Examples | docs/oss/EXAMPLES.md | registry caution: yes |
|
|
29
|
+
|
|
30
|
+
## Deprecated Files
|
|
31
|
+
- None.
|
|
32
|
+
|
|
33
|
+
## Findings
|
|
34
|
+
- No release-surface drift detected across the audited RC docs and commands.
|
|
35
|
+
|
package/package.json
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "martin-loop",
|
|
3
3
|
"private": false,
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.4",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Martin Loop dual-track monorepo for the OSS runtime and hosted SaaS control plane.",
|
|
7
7
|
"license": "MIT",
|
|
8
|
-
"packageManager": "pnpm@10.17.1",
|
|
9
8
|
"main": "./dist/index.js",
|
|
10
9
|
"types": "./dist/index.d.ts",
|
|
11
10
|
"bin": {
|
|
@@ -27,9 +26,16 @@
|
|
|
27
26
|
"publishConfig": {
|
|
28
27
|
"access": "public"
|
|
29
28
|
},
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@types/node": "^22.13.10",
|
|
31
|
+
"@types/react": "^19.0.12",
|
|
32
|
+
"@types/react-dom": "^19.0.5",
|
|
33
|
+
"tsx": "^4.19.3",
|
|
34
|
+
"typescript": "^5.8.2",
|
|
35
|
+
"vitest": "^3.0.8"
|
|
36
|
+
},
|
|
30
37
|
"scripts": {
|
|
31
38
|
"build": "pnpm -r build && node ./scripts/build-public-facade.mjs",
|
|
32
|
-
"prepublishOnly": "pnpm build",
|
|
33
39
|
"test": "pnpm -r test",
|
|
34
40
|
"lint": "pnpm -r lint",
|
|
35
41
|
"oss:validate": "node ./scripts/oss-boundary.mjs",
|
|
@@ -44,13 +50,5 @@
|
|
|
44
50
|
"run:cli": "pnpm --filter @martin/cli dev",
|
|
45
51
|
"eval": "pnpm --filter @martin/benchmarks eval",
|
|
46
52
|
"dev:dashboard": "node apps/local-dashboard/server.js"
|
|
47
|
-
},
|
|
48
|
-
"devDependencies": {
|
|
49
|
-
"@types/node": "^22.13.10",
|
|
50
|
-
"@types/react": "^19.0.12",
|
|
51
|
-
"@types/react-dom": "^19.0.5",
|
|
52
|
-
"tsx": "^4.19.3",
|
|
53
|
-
"typescript": "^5.8.2",
|
|
54
|
-
"vitest": "^3.0.8"
|
|
55
53
|
}
|
|
56
|
-
}
|
|
54
|
+
}
|