chore: phase 2 blueprint correction — sibling, not parity target

Probe of MacFall7/M87-Spine-lite found a sibling Python project with a
categorically different six-class taxonomy (SAFE_READ/SHELL_*/SCOPED_WRITE/
RESTRICTED_WRITE/SHELL_DANGEROUS on shell-vs-file lines with numeric risk
scores and a 5-step pipeline). spine-lite-python's taxonomy stays
canonical: state × boundary × reversibility axes with ordinal precedence,
authored from spec.

CLAUDE.md mission reworded; halt + operator resolution appended verbatim
to RECEIPTS.md as the Phase 2 day 1 opening entry; porting-notes reframed
from translation log to design history; surgical edits across nine docs
pages drop the stale TS-reference framing. Posture enum members pinned
in posture-and-hooks.md ahead of the Phase 2 ship.

Author: claude

CLAUDE.md

@@ -4,7 +4,7 @@ Operating manual for Claude Code sessions in this repo.
 
 ## Mission
 
-Python port of M87-Spine-lite (TypeScript). Deterministic policy and effects runtime for LLM tool calls. Public API and observable semantics must mirror the TypeScript reference within the closed six-class taxonomy.
+Deterministic policy and effects runtime for LLM tool calls. Public API and observable semantics are defined by the architectural invariants below; the sibling project at [MacFall7/M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite) is informational and not a parity target. See `docs/explanation/porting-notes.md` for the relationship.
 
 ## Authority
 
@@ -19,7 +19,6 @@ Mac decides — halt and ask:
 - Anything in `src/spine_lite/__init__.py`'s `__all__`.
 - New dependencies beyond `pyproject.toml`.
 - Phase boundary transitions (1→2, 2→3).
-- Semantic divergence from the TypeScript reference.
 - PyPI publish, repo visibility, GitHub Pages enablement.
 
 ## Architectural invariants
@@ -56,7 +55,7 @@ All three green or no commit. Before any push, also `coverage` and `docs`. Cover
 Halt and report when:
 
 - A phase exit gate item is unclear.
-- Python and TS reference diverge semantically and you can't tell which is right.
+- The architectural invariants above conflict with new code or new decisions.
 - A test fails you can't explain in 15 minutes.
 - You're about to add a dependency.
 - You're about to modify `__all__`.
@@ -75,14 +74,14 @@ Awaiting: <decision needed>
 ## Phase plan
 
 - **Phase 1** — scaffold + CI + docs deploy. Tags `v0.1.0a0`.
-- **Phase 2** — `manifest` and `classifier` complete. Pydantic v2 models, parity tests against TS reference fixtures, `hypothesis` for invariants. Tags `v0.2.0a0`.
+- **Phase 2** — `manifest`, `classifier`, and the closed `Posture` enum complete. Pydantic v2 models, round-trip parity tests against authored fixtures, `hypothesis` for invariants. Tags `v0.2.0a0`.
 - **Phase 3** — `posture`, `receipt`, `hook`, `cli` complete. End-to-end PreToolUse integration with Claude Code. Tags `v0.3.0a0`.
 
 Phase exit gates and receipts live in `RECEIPTS.md`.
 
 ## Scope
 
-- In-repo only. Don't touch the TypeScript reference (read-only spec).
+- In-repo only. Don't touch the sibling project at MacFall7/M87-Spine-lite (informational, not a parity target).
 - Don't invoke Patronus, Braintrust, or Arize SDKs (operator-decision pending).
 - No network calls in tests. No LLM calls anywhere in the runtime.
 

README.md

@@ -7,7 +7,7 @@
 
 Deterministic policy and effects runtime for LLM tool calls.
 
-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.
+Six-class effects taxonomy on state × boundary × reversibility axes. Ordinal precedence. Content-addressable receipts. Wires into Claude Code as a PreToolUse hook (Phase 3); usable anywhere you can shell out to a subprocess. Sibling project to [M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite) — see [Porting Notes](docs/explanation/porting-notes.md) for the relationship.
 
 ## What it does
 

RECEIPTS.md

@@ -112,3 +112,125 @@ All 10 items clear. **Phase 1 closed.**
 - None. Phase 2 (manifest + classifier, ~5 working days, target `v0.2.0a0`) is gated on operator go per `CLAUDE.md`.
 
 **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.
+
+---
+
+### Phase 2 Day 1 Opening — 2026-05-08
+
+Phase 2 opened with a §9 halt. The halt and the operator's resolution are recorded here verbatim for the run-registry trail.
+
+**§9 HALT (verbatim):**
+
+```
+HALT: Reference repo's spec diverges from Phase 1's invariants in ways that make
+      a straight parity port mechanically impossible.
+
+Context:
+- The blueprint and CLAUDE.md describe a "TS reference" at MacFall7/M87-Spine-lite.
+- WebFetch confirms the repo exists and is public, but it's implemented in Python
+  (hooks/guard.py, hooks/governor.py), not TypeScript. The "TS reference" framing
+  in the blueprint is stale.
+- Bigger issue: the reference's six-class taxonomy is *categorically different*
+  from what shipped in Phase 1.
+
+Reference (M87-Spine-lite, README verbatim):                 │  Phase 1 (spine-lite-python):
+                                                             │
+  SAFE_READ          (risk 0.00, auto-approve)               │  READ
+  SHELL_SAFE         (risk 0.01, auto-approve)               │  WRITE
+  SHELL_MUTATING     (risk 0.04, auto-approve)               │  NETWORK
+  SCOPED_WRITE       (risk 0.02, auto-approve)               │  EXECUTE
+  RESTRICTED_WRITE   (risk 0.08, manual approval)            │  SPAWN
+  SHELL_DANGEROUS    (risk 0.10, blocked)                    │  DESTRUCTIVE
+
+  + numeric risk scores                                      │  + ordinal precedence
+  + per-class default disposition                            │  + most_restrictive collapse
+  + 5-step deny→network→safe→mutating→default pipeline       │  + classifier returns Decision
+  + 7 invariants about governance philosophy                 │  + 7 invariants about implementation
+
+- These are not "the same six things with different labels." The reference draws axes
+  on shell-vs-file and risk-magnitude; Phase 1 draws axes on state-vs-boundary-vs-
+  reversibility. There's no NETWORK in the reference; there's no SAFE_READ vs
+  SHELL_SAFE distinction in Phase 1.
+- Phase 1 shipped 2026-05-08 as v0.1.0a0, merged via PR #1, repo public, Pages live.
+  Mac signed off on the action-centric taxonomy and the 7 implementation invariants
+  in CLAUDE.md.
+- This is exactly the §9 stop condition: "TS reference and Python implementation
+  diverge semantically and you cannot determine which is correct." Except now
+  it's clear the divergence isn't fixable by translation — it's a different design.
+
+Options:
+1. Treat the reference as a sibling project, not a parity target. Phase 2 implements
+   manifest + classifier from the contract document already drafted in
+   docs/concepts/posture-and-hooks.md and docs/how-to/wire-claude-code.md (author-
+   from-spec, same pattern as Phase 1). Add a porting-notes entry recording that
+   the reference informed the design but is not the byte-equality target — its
+   taxonomy and ours are categorically different. Parity tests become "round-trip
+   our own fixtures" rather than "byte-equal against external fixtures."
+
+2. Retract Phase 1's taxonomy. Re-tag v0.1.0a0 as deprecated, bump to v0.1.1a0
+   with the reference's SAFE_READ/SHELL_*/SCOPED_WRITE/RESTRICTED_WRITE/SHELL_DANGEROUS,
+   then resume Phase 2 against that baseline. Brings byte-for-byte parity back
+   on the table.
+
+3. Both taxonomies, with a translation layer. Phase 1 names stay public; manifest
+   schema accepts reference-style names and maps them. Mapping is judgment-heavy
+   (does SHELL_SAFE map to EXECUTE or to READ depending on the call?), so parity
+   becomes case-by-case rather than mechanical.
+
+4. The reference repo isn't actually the spec — CLAUDE.md is, and you confirmed
+   that in Phase 1 by directing "FLIP TO OPTION 1: author scaffold from blueprint
+   spec." Phase 2 follows the same pattern. The reference is consulted as
+   inspiration, cited in porting-notes, but isn't a parity gate.
+
+Recommendation: Option 1 (or equivalently Option 4 — they're the same path with
+different labels).
+
+Awaiting:
+- Pick 1, 2, 3, or 4 for the parity question.
+- (a) or (b) for the Posture enum question.
+- Anything else worth logging in porting-notes before Phase 2 starts.
+```
+
+**Operator resolution (verbatim):**
+
+```
+DECISION ON HALT:
+
+Parity question: Option 1. Reference (MacFall7/M87-Spine-lite) is a sibling project,
+not a parity target. Phase 1's taxonomy is correct and final. spine-lite-python
+authors from spec, same pattern as Phase 1.
+
+Posture question: sub-option (a). Ship Posture enum in Phase 2 with manifest
+validation. Closed-enum + one-line __all__ addition.
+
+BLUEPRINT CORRECTION (do this in commit 1 of Phase 2 before code lands):
+
+Update CLAUDE.md and docs/explanation/porting-notes.md:
+- Reference repo is a Python sibling, not "TS reference"
+- Reference is informational, not a parity target
+- spine-lite-python's design rationale: broader taxonomy (state × boundary ×
+  reversibility axes), ordinal precedence over risk scores, suitable for any LLM
+  tool call not just bash
+- Record that the reference's taxonomy (SAFE_READ / SHELL_SAFE / SHELL_MUTATING /
+  SCOPED_WRITE / RESTRICTED_WRITE / SHELL_DANGEROUS + numeric risk scores +
+  5-step pipeline) was reviewed and explicitly not adopted
+
+Coverage 100% on manifest.py, classifier.py, posture.py (enum scope only).
+Six-commit Conventional Commits shape preserved (the blueprint correction is
+commit 1, then 5 functional commits).
+
+Begin from blueprint correction commit. Halt at exit gate.
+```
+
+**What landed in commit 1 of Phase 2:**
+
+- `CLAUDE.md` mission rewritten to drop "TS reference" framing; sibling project recorded as informational, not a parity target.
+- `docs/explanation/porting-notes.md` reframed from "translation log" to "design history" with a Sibling Project section, a Phase 2 opening entry recording this halt and resolution, and a Phase 1 entry pinning the taxonomy as `spine-lite-python`'s spec.
+- `docs/concepts/posture-and-hooks.md` updated to remove the "subject to refinement" caveat from the posture table and pin the four members (`INTERACTIVE`, `AUTONOMOUS`, `DRY_RUN`, `LOCKED`) with their string values.
+- `docs/explanation/architecture.md` reference-implementation paragraph rewritten as a sibling-project note.
+- `docs/explanation/faq.md` "Why Python after TypeScript?" question replaced with "How does this relate to M87-Spine-lite?", plus three other in-place corrections.
+- `docs/concepts/effects-taxonomy.md`, `docs/concepts/overview.md`, `docs/how-to/contribute.md`, `docs/how-to/use-the-api.md`, `docs/reference/glossary.md`: surgical edits to drop TS-reference framing.
+- `README.md` and `docs/index.md` headlines reworded: `spine-lite-python` is described directly, sibling project credited but not framed as a port target.
+- This receipt entry.
+
+**Next:** Phase 2 functional commits begin (Posture → manifest → classifier → fixtures+tests → release+exit-receipt).

docs/concepts/effects-taxonomy.md

@@ -57,7 +57,7 @@ Anything finer is a manifest concern (the *which* file, the *which* host), not a
 A taxonomy that grows at runtime is a taxonomy that drifts. Adding a seventh class would require:
 
 1. Updating `Effect` and `PRECEDENCE` in `effects.py`.
-2. Updating the parity tests against the TypeScript reference.
+2. Updating the parity tests and the porting-notes log.
 3. Updating every consumer that exhaustively matches on `Effect`.
 4. A migration note in `CHANGELOG.md` and `docs/explanation/porting-notes.md`.
 5. Project-level sign-off — recorded as a HALT against [`CLAUDE.md`](https://github.com/MacFall7/spine-lite-python/blob/main/CLAUDE.md).
@@ -75,4 +75,4 @@ The `effects` module contains zero I/O, zero clocks, zero randomness. This is en
 - [Concepts / Overview](overview.md) — where the taxonomy fits in the pipeline.
 - [Reference / API](../reference/api.md#effects) — the auto-generated `Effect`, `PRECEDENCE`, `most_restrictive` reference.
 - [Reference / Glossary](../reference/glossary.md) — term-by-term definitions.
-- [Explanation / Porting Notes](../explanation/porting-notes.md) — how the Python form relates to the TypeScript reference.
+- [Explanation / Porting Notes](../explanation/porting-notes.md) — design history and the relationship to the sibling project.

docs/concepts/overview.md

@@ -38,7 +38,7 @@ The PreToolUse **hook** is just an I/O wrapper that maps stdin/stdout to and fro
 
 ## What's closed
 
-The effects taxonomy is closed at six classes. Adding a class is a project-level decision that requires updating the precedence ordering, the parity tests against the TypeScript reference, and the docstrings. It is not a runtime extension point.
+The effects taxonomy is closed at six classes. Adding a class is a project-level decision that requires updating the precedence ordering, the parity tests, the porting-notes log, and the docstrings. It is not a runtime extension point.
 
 This is a feature, not a limitation. A taxonomy that grows at runtime is a taxonomy that drifts. The six classes were chosen to cover every observable side effect a tool call can produce. If something looks like a seventh class, it's probably an existing class with new arguments.
 

docs/concepts/posture-and-hooks.md

@@ -10,7 +10,7 @@ A manifest is the policy document for a tool. It declares:
 - The set of effects each invocation can produce.
 - Posture constraints — under which postures the tool may be invoked, and under which it must be refused.
 
-Manifests are validated as Pydantic v2 models and round-trip the TypeScript reference fixtures byte-for-byte after JSON normalisation.
+Manifests are validated as Pydantic v2 models and round-trip authored fixtures byte-for-byte after JSON normalisation.
 
 ## Classifier (Phase 2)
 
@@ -27,18 +27,18 @@ Pure function. Given a tool call and a manifest, returns a `Decision` carrying:
 
 No I/O. No clocks. Same input → same output, every time.
 
-## Posture state machine (Phase 3)
+## Posture state machine
 
-A posture is the current operational mode. Transitions are pure value-in-value-out functions; no hidden state.
+The closed `Posture` enum lands in Phase 2 (manifest validation depends on it). Transition functions land in Phase 3.
 
-Postures (planned, subject to refinement against the TypeScript reference):
+Posture is the current operational mode. Transitions (Phase 3) are pure value-in-value-out functions; no hidden state.
 
-| Posture | Meaning |
-|---|---|
-| `INTERACTIVE` | Operator is at the keyboard; ambiguous calls escalate to a prompt. |
-| `AUTONOMOUS` | No operator in the loop; ambiguous calls fail closed. |
-| `DRY_RUN` | Classification only; no `WRITE`/`NETWORK`/`EXECUTE`/`SPAWN`/`DESTRUCTIVE` effects fire. |
-| `LOCKED` | Refuse everything except explicitly allow-listed read-only calls. |
+| Posture | Value | Meaning |
+|---|---|---|
+| `INTERACTIVE` | `"interactive"` | Operator is at the keyboard; ambiguous calls escalate to a prompt. |
+| `AUTONOMOUS` | `"autonomous"` | No operator in the loop; ambiguous calls fail closed. |
+| `DRY_RUN` | `"dry_run"` | Classification only; no `WRITE`/`NETWORK`/`EXECUTE`/`SPAWN`/`DESTRUCTIVE` effects fire. |
+| `LOCKED` | `"locked"` | Refuse everything except explicitly allow-listed read-only calls. |
 
 Transitions are total — every `(posture, decision)` pair has a defined next posture or a `PostureError`. There are no implicit transitions.
 
@@ -81,4 +81,4 @@ echo $?  # 0 = allow, non-zero = deny
 
 - [Concepts / Overview](overview.md) — pipeline shape.
 - [How-To / Wire into Claude Code](../how-to/wire-claude-code.md) — operator runbook.
-- [Explanation / Porting Notes](../explanation/porting-notes.md) — how this maps to the TypeScript reference.
+- [Explanation / Porting Notes](../explanation/porting-notes.md) — design history and the relationship to the sibling project.

docs/explanation/architecture.md

@@ -70,9 +70,11 @@ Adding a class is permitted but expensive. The process is in [Effects Taxonomy /
 
 The architecture stays the same across phases. Each phase fills in pure modules that adhere to the same purity contract.
 
-## Reference implementation
+## Sibling project
 
-The TypeScript reference lives at [MacFall7/M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite). Treat it as the spec for semantic behaviour. Where Python idiom diverges from TypeScript (typing, dataclass shape, exception names), prefer the Python form and document the call in [Porting Notes](porting-notes.md). Anything that changes observable behaviour is a divergence and needs project-level sign-off.
+[MacFall7/M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite) is a Python sibling project: a governance framework for Claude Code shell commands with a different six-class taxonomy drawn on shell-vs-file lines. It's informational and citable, not a parity target. See [Porting Notes](porting-notes.md) for the full relationship.
+
+`spine-lite-python`'s spec is canonical and lives in this repository: the architectural invariants in `CLAUDE.md`, the [Invariants](invariants.md) page, and the design rationale recorded as decisions are made.
 
 ## See also
 

docs/explanation/faq.md

@@ -6,7 +6,7 @@ Six lines that matter for safety review. `READ` vs. `WRITE` (did anything change
 
 ## Why is the taxonomy closed?
 
-A taxonomy that grows at runtime is a taxonomy that drifts. Adding a class would require updating the precedence ordering, the parity tests against the TypeScript reference, every consumer that exhaustively matches on `Effect`, and every receipt that hashed under the old ordering. The cost is real; the benefit (better fit for one new use case) is local. So: closed by default, with an explicit project-level process for extension.
+A taxonomy that grows at runtime is a taxonomy that drifts. Adding a class would require updating the precedence ordering, the parity tests, the porting-notes log, every consumer that exhaustively matches on `Effect`, and every receipt that hashed under the old ordering. The cost is real; the benefit (better fit for one new use case) is local. So: closed by default, with an explicit project-level process for extension.
 
 ## Why no LLM calls inside the runtime?
 
@@ -16,13 +16,13 @@ The runtime's job is to classify and decide. Calling a model to second-guess tha
 
 Receipts are content-addressable. Two operators replaying the same session see byte-identical receipts. That property only holds if the runtime is deterministic — same input → same output, every time. The cost is that wall-clock time can only enter at the I/O boundary (the hook); the benefit is that "what happened?" has a SHA-stable answer.
 
-## Why Python after TypeScript?
+## How does this relate to M87-Spine-lite?
 
-The TypeScript reference is the spec. The Python port is what you install in environments where Python is already the language of choice — Claude Code agents written in Python, internal CLIs, CI pipelines, Jupyter sessions. Both implementations target the same observable behaviour.
+[MacFall7/M87-Spine-lite](https://github.com/MacFall7/M87-Spine-lite) is a sibling project with a different scope: a governance framework for Claude Code shell commands, with a six-class taxonomy drawn on shell-vs-file lines and numeric risk-delta scores. `spine-lite-python` is broader (any LLM tool call, not just bash) and uses ordinal precedence rather than numeric scores. The two designs are categorically different, not relabelings of each other. See [Porting Notes](porting-notes.md) for the full story.
 
 ## Why Pydantic v2 for the manifest?
 
-Pydantic v2 is the de facto standard for typed Python schemas, has fast Rust-backed validation, and round-trips JSON cleanly. The TypeScript reference uses Zod; Pydantic v2 is the closest match in the Python ecosystem.
+Pydantic v2 is the de facto standard for typed Python schemas, has fast Rust-backed validation, and round-trips JSON cleanly. The frozen + extra-forbid model config gives us schema strictness without writing a custom validator.
 
 ## What happens when a tool call has no declared effects?