You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,17 @@ All notable changes to this project are documented here. The format follows [Kee
4
4
5
5
## [Unreleased]
6
6
7
+
### Added
8
+
9
+
-`SECURITY.md` with vulnerability-reporting process, supported-version policy, and the runtime trust model.
10
+
- Documentation site restructured into Diátaxis quadrants (Tutorial / How-To / Reference / Explanation) plus a History section. New pages: getting-started, concepts/{overview,effects-taxonomy,posture-and-hooks}, how-to/{use-the-api,wire-claude-code,contribute,release}, reference/{cli,exceptions,glossary}, explanation/{invariants,faq}, history/phase-1.
11
+
- Iron-clad README with status grid, repository layout, and links into the docs site.
12
+
13
+
### Changed
14
+
15
+
-`docs/architecture.md`, `docs/design-rationale.md`, `docs/porting-notes.md`, `docs/integration-claude-code.md`, and `docs/api.md` moved under `docs/explanation/`, `docs/how-to/`, and `docs/reference/`.
16
+
-`CONTRIBUTING.md` reduced to a quick-start that points at the long form in the docs site.
The quick-start. The full contributor guide lives at [docs/how-to/contribute.md](https://macfall7.github.io/spine-lite-python/how-to/contribute/).
4
+
3
5
This repo is governed under M87 Studio. External PRs are welcome, but the closed six-class effects taxonomy and the public API surface are non-negotiable — proposals to change either need a written rationale on an issue before code lands.
- Direct prose. No marketing copy, no LLM boilerplate, no performative empathy.
38
-
39
-
## Architecture rules
32
+
If you don't have nox, the underlying tools work directly:
40
33
41
-
The closed six-class effects taxonomy and the precedence ordering are the spec. The five core modules — `effects.py`, `classifier.py`, `posture.py`, `manifest.py`, `receipt.py` — are pure: no I/O, no timestamps, no randomness. I/O lives in `hook.py`, `cli.py`, and tests.
34
+
```bash
35
+
uv run ruff check .
36
+
uv run ruff format --check .
37
+
uv run mypy src tests
38
+
uv run pytest --cov=spine_lite --cov-fail-under=95
39
+
uv run mkdocs build --strict
40
+
```
42
41
43
-
## Tests
42
+
## Style at a glance
44
43
45
-
`pytest` for everything. `hypothesis` for invariants and determinism. The TypeScript reference fixtures (added in Phase 2) are used as-is — no mocking. No network calls in tests; the runtime is offline by design.
- Direct prose. No marketing tone, no LLM boilerplate.
46
49
47
-
## Reviewing
50
+
## Architecture rules
48
51
49
-
The build operates under explicit phase gates documented in `CLAUDE.md`. Reviews should focus on:
52
+
The closed six-class effects taxonomy and the precedence ordering are the spec. The five pure modules (`effects.py`, `manifest.py`, `classifier.py`, `posture.py`, `receipt.py`) contain no I/O, no clocks, no randomness. I/O lives in `hook.py`, `cli.py`, and tests.
50
53
51
-
1. Public API stability (anything in `__all__`).
52
-
2. Determinism in the pure modules.
53
-
3. Parity with the TypeScript reference where applicable.
54
-
4. Test coverage on the modules touched.
54
+
If your change cannot be made within those rules, that's an issue for discussion — not a PR.
55
55
56
-
## Releases
56
+
## Where to read more
57
57
58
-
Versioning is SemVer with explicit phase tags: `0.1.0a0` (Phase 1), `0.2.0a0` (Phase 2), `0.3.0a0` (Phase 3). PyPI publishing is gated on a project-level sign-off, not on CI alone.
Deterministic policy and effects runtime for LLM tool calls.
4
9
5
-
A Python port of [M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite). Same closed effects taxonomy, same precedence rules, same posture state machine — typed, tested, and shipped as a `pip`-installable package.
10
+
A Python port of [M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite). Same closed effects taxonomy, same precedence rules, same posture state machine — typed, tested, packaged.
11
+
12
+
## What it does
13
+
14
+
You give it a tool call and a manifest of declared effects. It returns a deterministic decision: which effects fire, what the dominant class is, and a structured receipt you can replay by SHA. Built to wire into Claude Code as a PreToolUse hook; usable anywhere you can shell out to a subprocess.
15
+
16
+
The runtime is offline by design — no clocks, no randomness, no network, no LLM calls inside the runtime itself.
6
17
7
18
## Status
8
19
9
-
Alpha. Phase 1 ships the scaffold, the closed effects taxonomy, and the public exception hierarchy. The classifier, posture state machine, hook adapter, and the rest of the CLI land in Phases 2 and 3. See `RECEIPTS.md` for build progress and `docs/architecture.md` for the plan.
> PyPI release lands at the end of Phase 3. Until then, install from source.
26
+
See [`RECEIPTS.md`](RECEIPTS.md) for build progress and [docs/history/phase-1.md](https://macfall7.github.io/spine-lite-python/history/phase-1/) for the Phase 1 narrative.
12
27
13
28
## Install
14
29
30
+
PyPI publish lands at the end of Phase 3. Until then, install from source:
|`EXECUTE`| subprocess invocation, no fork |`subprocess.run`, `os.system`, shell pipeline |
77
+
|`SPAWN`| subprocess that may fork-and-detach |`Popen` with no `wait`, daemon launch, `nohup`|
78
+
|`DESTRUCTIVE`| irreversible state change |`rm -rf`, `git push --force`, dropping a table |
43
79
44
-
| Effect | Meaning |
45
-
| --- | --- |
46
-
|`READ`| observation only |
47
-
|`WRITE`| persistent state change to caller-owned storage |
48
-
|`NETWORK`| outbound network call |
49
-
|`EXECUTE`| subprocess invocation |
50
-
|`SPAWN`| fork-and-detach subprocess |
51
-
|`DESTRUCTIVE`| irreversible change |
80
+
Ordered by precedence: `DESTRUCTIVE > SPAWN > EXECUTE > NETWORK > WRITE > READ`. `most_restrictive()` collapses any non-empty set to the highest class.
52
81
53
-
Ordered by precedence: `DESTRUCTIVE > SPAWN > EXECUTE > NETWORK > WRITE > READ`. `most_restrictive()` collapses any non-empty set to the highest class. Same input produces the same output every time. No clocks, no randomness, no I/O in the core.
82
+
Same input → same output, every time. No clocks, no randomness, no I/O in the core.
54
83
55
-
## What this is not
84
+
## What this isn't
56
85
57
-
- Not a model. No LLM calls happen inside spine-lite.
58
-
- Not a sandbox. It classifies and decides; enforcement happens in the hook.
59
-
- Not extensible at runtime. The taxonomy is closed by design — extending it is a project-level decision.
86
+
-**Not a model.** No LLM calls happen inside the runtime.
87
+
-**Not a sandbox.** It classifies and decides; enforcement happens in the hook adapter.
88
+
-**Not extensible at runtime.** The taxonomy is closed by design — extending it is a project-level decision.
89
+
-**Not a network library.** There are zero network calls in the runtime, ever.
60
90
61
91
## Documentation
62
92
63
-
Full docs publish to GitHub Pages once Phase 1 is signed off.
93
+
Full docs at <https://macfall7.github.io/spine-lite-python/>. Quick links:
94
+
95
+
-[**Getting Started**](https://macfall7.github.io/spine-lite-python/getting-started/) — five-minute install + first decision.
96
+
-[**Concepts / Overview**](https://macfall7.github.io/spine-lite-python/concepts/overview/) — mental model end to end.
97
+
-[**How-To / Use the API**](https://macfall7.github.io/spine-lite-python/how-to/use-the-api/) — practical patterns, today.
98
+
-[**How-To / Wire into Claude Code**](https://macfall7.github.io/spine-lite-python/how-to/wire-claude-code/) — operator runbook.
99
+
-[**Reference / API**](https://macfall7.github.io/spine-lite-python/reference/api/) — auto-generated from docstrings.
├── SECURITY.md # vulnerability reporting + trust model
118
+
├── pyproject.toml # hatchling build, deps pinned via uv.lock
119
+
└── uv.lock # tracked; CI cache keys against it
120
+
```
64
121
65
122
## Contributing
66
123
67
-
See `CONTRIBUTING.md`. The closed effects taxonomy and the public API are non-negotiable; proposals to change either need a written rationale on an issue first.
124
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the quick-start and [docs/how-to/contribute.md](https://macfall7.github.io/spine-lite-python/how-to/contribute/) for the long form. The closed effects taxonomy and the public API are non-negotiable; proposals to change either need a written rationale on an issue first.
125
+
126
+
## Security
127
+
128
+
See [SECURITY.md](SECURITY.md). The runtime is deterministic and offline; trust questions live in your manifest.
129
+
130
+
## Governance
131
+
132
+
This repo runs under M87 Studio with explicit phase boundaries. Authority split, halt conditions, and verification gates are in [`CLAUDE.md`](CLAUDE.md). Phase exit gates and receipts are in [`RECEIPTS.md`](RECEIPTS.md).
Copy file name to clipboardExpand all lines: RECEIPTS.md
+58Lines changed: 58 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,3 +54,61 @@ Append-only build log for spine-lite-python. Mirrored to the canonical M87 run-r
54
54
- Three exit-gate items (1, 2, 3) require operator action: confirm CI green on the 9-cell matrix, flip repo visibility to public, enable GitHub Pages.
55
55
56
56
**Next:** Halt for Mac at the Phase 1 exit gate. Phase 2 (manifest + classifier, ~5 working days) does not start without an explicit go.
57
+
58
+
---
59
+
60
+
### Phase 1 Day 2 Receipt — 2026-05-08
61
+
62
+
**Repo:** spine-lite-python branch `claude/setup-project-structure-3YeiT`, ahead of `main` by the docs-expansion commits below.
63
+
**Duration:**~1.5 hours (continuation of the same Claude Code Web session).
64
+
65
+
**Tasks completed:**
66
+
67
+
-**CI fix.** Two commits resolving the `setup-uv@v3` cache-key failure: untrack `uv.lock` from `.gitignore` (with the `design-rationale.md` entry inverted), then commit the lockfile (1,396 lines, 68 packages). Operator confirmed all 9 matrix cells green and merged via PR #1 (`d90e72c`). Repo now public; GitHub Pages live at <https://macfall7.github.io/spine-lite-python/>.
68
+
-**Documentation expansion to archivist grade.** Restructured `docs/` into Diátaxis quadrants (Tutorial / How-To / Reference / Explanation) plus a History section. Twelve new pages, three substantial rewrites of moved pages, mkdocs nav updated, mkdocs --strict clean.
69
+
-**Top-level prose rewritten.** Iron-clad README (status grid, repository layout, copy-paste install, today-vs-later capability matrix, deep links into the docs site), SECURITY.md added (vulnerability reporting, supported versions, trust model, threat model, dependency policy), CONTRIBUTING.md reduced to a quick-start that points at the long-form guide in `docs/how-to/contribute.md`.
| 9 | All commits in Conventional Commits format | ✓ |
106
+
| 10 | Receipt appended | ✓ |
107
+
108
+
All 10 items clear. **Phase 1 closed.**
109
+
110
+
**Open items / halts:**
111
+
112
+
- None. Phase 2 (manifest + classifier, ~5 working days, target `v0.2.0a0`) is gated on operator go per `CLAUDE.md`.
113
+
114
+
**Next:** Halt for Mac at the Phase 1 → Phase 2 transition. Per blueprint §11, completion of Phase 1 unblocks the Braintrust application thread on the operator's side.
0 commit comments