@@ -0,0 +1,78 @@
+# Effects Taxonomy
+
+The six classes, the precedence ordering, and the rules that make them stable.
+
+## The six classes
+
+| Class | Meaning | Examples |
+|---|---|---|
+| `READ` | Pure observation. No state change anywhere the caller can see. | reading a file, listing a directory, querying without writing |
+| `WRITE` | Persistent state change to caller-owned storage. Reversible by the caller. | writing a file, updating a row, appending a log entry |
+| `NETWORK` | Outbound network call. Crosses a trust boundary; result is observable to a third party. | HTTP request, DNS lookup, Slack message, webhook fire |
+| `EXECUTE` | Subprocess invocation, no fork-and-detach. Caller waits for completion. | `subprocess.run`, `os.system`, shell pipeline |
+| `SPAWN` | Subprocess invocation that may fork-and-detach. Caller does not necessarily wait. | `Popen` with no `wait`, daemon launch, `nohup`, container `run -d` |
+| `DESTRUCTIVE` | Irreversible state change. Recovery requires backups or external intervention. | `rm -rf`, `git push --force`, dropping a table, deleting a branch |
+
+## Precedence
+
+Most restrictive at the top:
+
+```
+DESTRUCTIVE  ← highest
+SPAWN
+EXECUTE
+NETWORK
+WRITE
+READ         ← lowest
+```
+
+`spine_lite.most_restrictive(effects)` walks this ordering top-down and returns the first match. The function is total over any non-empty subset of `Effect`; it raises `ValueError` on an empty input.
+
+```python
+from spine_lite import Effect, most_restrictive
+
+most_restrictive({Effect.READ, Effect.NETWORK, Effect.WRITE})
+# <Effect.NETWORK: 'network'>
+
+most_restrictive({Effect.DESTRUCTIVE, Effect.READ})
+# <Effect.DESTRUCTIVE: 'destructive'>
+```
+
+The ordering is encoded once in [`spine_lite.PRECEDENCE`](../reference/api.md). Every comparison in the runtime resolves through that constant; reordering is a one-line change with project-level sign-off.
+
+## Why these six
+
+Each class draws a line that matters for safety review:
+
+- `READ` vs. `WRITE`: did anything change?
+- `WRITE` vs. `NETWORK`: did anything cross a trust boundary?
+- `NETWORK` vs. `EXECUTE`: did we hand control to another process?
+- `EXECUTE` vs. `SPAWN`: did the child outlive the call?
+- `SPAWN` vs. `DESTRUCTIVE`: can we undo it?
+
+Anything finer is a manifest concern (the *which* file, the *which* host), not a taxonomy concern (the *what kind of effect*).
+
+## Why closed
+
+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.
+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).
+
+If you find yourself wanting a new class, first try modelling the new behaviour as an existing class with manifest-level qualifiers. The seventh class is almost always an existing class wearing a different hat.
+
+## Determinism
+
+`most_restrictive` is a pure function. Same input set → same output, every time. No hidden state, no clocks, no randomness. The runtime depends on this property — receipts hash by SHA exactly because the inputs uniquely determine the outputs.
+
+The `effects` module contains zero I/O, zero clocks, zero randomness. This is enforced by the [Invariants](../explanation/invariants.md) and verified by the test suite.
+
+## See also
+
+- [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.
@@ -0,0 +1,68 @@
+# Overview
+
+The mental model in one page.
+
+## The pipeline
+
+```
+tool call ──┐
+            │
+manifest ───┼──► classifier ──► effect set ──► most_restrictive ──► dominant effect
+            │                        │                                    │
+posture ────┘                        │                                    │
+                                     ▼                                    ▼
+                                  posture transition ─────────────► decision
+                                                                     │
+                                                                     ▼
+                                                                   receipt
+                                                                     │
+                                                                     ▼
+                                                                  hook ──► allow / deny
+```
+
+You give the runtime three inputs:
+
+- A **tool call** — the LLM has decided to invoke a named tool with arguments.
+- A **manifest** — the policy document for that tool, including its declared effects and any posture constraints.
+- A **posture** — the current operational state (e.g., interactive vs. autonomous, dry-run vs. live).
+
+The runtime returns a single output: a **decision** carrying the dominant effect, the full effect set, the new posture, and a receipt that hashes to the same value if you re-run with the same inputs.
+
+The PreToolUse **hook** is just an I/O wrapper that maps stdin/stdout to and from the pure pipeline above.
+
+## What's pure
+
+`effects`, `manifest`, `classifier`, `posture`, and `receipt` are pure modules. No clocks, no randomness, no network, no filesystem. Same input → same output, every time. This is what makes a receipt replayable by SHA — there's no hidden state to drift.
+
+`hook` and `cli` do I/O, because something has to. They're thin adapters around the pure core.
+
+## 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.
+
+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.
+
+## What's deterministic
+
+Same tool call + same manifest + same posture → same decision + same receipt bytes. No "the timestamp differs" caveats; the receipt doesn't carry a timestamp. The hook layer is where wall-clock entropy enters, and only as input — it doesn't influence classification.
+
+## What's offline
+
+Zero network calls inside the runtime. Zero LLM calls inside the runtime. The runtime's job is to look at a tool call and decide; if you want to call a model to second-guess it, that's a separate concern that lives outside this package.
+
+## Phase boundaries
+
+| Phase | Modules complete | What you can do |
+|---|---|---|
+| 1 | `effects`, `exceptions`, `cli` (`version`) | Collapse effect sets, raise/catch typed errors, ship as a package. |
+| 2 | `+ manifest`, `classifier` | Classify a tool call against a manifest, get a `Decision`. |
+| 3 | `+ posture`, `receipt`, `hook`, `cli` (full) | End-to-end PreToolUse integration with Claude Code. |
+
+The architecture stays the same across phases. Each phase fills in pure modules that adhere to the same purity contract.
+
+## Where to go next
+
+- [Effects Taxonomy](effects-taxonomy.md) — the six classes and their precedence.
+- [Posture and Hooks](posture-and-hooks.md) — the Phase 2/3 components in outline.
+- [Architecture](../explanation/architecture.md) — why the modules are split this way.
+- [Invariants](../explanation/invariants.md) — the rules nothing in this repo gets to break.
@@ -0,0 +1,84 @@
+# Posture, Receipts, and Hooks
+
+The Phase 2 and Phase 3 components in outline. Implementations land at `v0.2.0a0` and `v0.3.0a0` respectively; what's described here is the contract those phases fill in.
+
+## Manifest (Phase 2)
+
+A manifest is the policy document for a tool. It declares:
+
+- The tool's name and signature.
+- 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.
+
+## Classifier (Phase 2)
+
+```python
+def classify(tool_call: ToolCall, manifest: Manifest) -> Decision: ...
+```
+
+Pure function. Given a tool call and a manifest, returns a `Decision` carrying:
+
+- `effects: frozenset[Effect]` — every effect the call can produce.
+- `most_restrictive: Effect` — the dominant class.
+- `rationale: str` — human-readable explanation.
+- `posture_transition: PostureTransition | None` — what the posture machine should do next.
+
+No I/O. No clocks. Same input → same output, every time.
+
+## Posture state machine (Phase 3)
+
+A posture is the current operational mode. Transitions are pure value-in-value-out functions; no hidden state.
+
+Postures (planned, subject to refinement against the TypeScript reference):
+
+| 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. |
+
+Transitions are total — every `(posture, decision)` pair has a defined next posture or a `PostureError`. There are no implicit transitions.
+
+## Receipt (Phase 3)
+
+A structured record of a single decision. Field ordering is deterministic; serialised receipts hash to identical bytes given identical inputs.
+
+A receipt carries:
+
+- The input tool call (as the manifest validated it).
+- The classified effects and dominant class.
+- The posture before and after.
+- The decision (`allow`, `deny`, `escalate`).
+- A content hash that uniquely identifies the receipt.
+
+No timestamps. The hook layer attaches wall-clock time as out-of-band metadata; the receipt itself stays content-addressable.
+
+## Hook (Phase 3)
+
+A thin I/O wrapper. Reads a hook payload from stdin, runs the pipeline, writes a decision to stdout, exits 0 (allow) or non-zero (deny).
+
+The hook is the only place in the package that touches `sys.stdin` or `sys.stdout`. Everything inside is pure.
+
+```bash
+# Phase 3 — wired into Claude Code as a PreToolUse hook
+spine-lite hook < payload.json
+echo $?  # 0 = allow, non-zero = deny
+```
+
+## CLI (Phase 3)
+
+| Subcommand | Status | Purpose |
+|---|---|---|
+| `version` | Phase 1 — shipped | Print the installed version. |
+| `validate-manifest` | Phase 2 | Validate a manifest file against the schema. |
+| `classify` | Phase 2 | One-shot classification of a tool call. |
+| `hook` | Phase 3 | stdin/stdout PreToolUse adapter for Claude Code. |
+
+## See also
+
+- [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.
@@ -0,0 +1,82 @@
+# Architecture
+
+## Mission
+
+Classify and decide on every LLM tool call before it runs. Pure, deterministic, byte-for-byte reproducible. Wire into Claude Code as a PreToolUse hook; carry the same semantics anywhere else a hook contract exists.
+
+## The runtime in one diagram
+
+```
+                     ┌──────────────────────────────────────────────┐
+                     │               pure pipeline                  │
+                     │                                              │
+   stdin payload ──► │  manifest ──► classifier ──► posture machine │ ──► stdout decision
+                     │     │              │              │          │
+                     │     ▼              ▼              ▼          │
+                     │  ManifestError  Classification-  Posture-    │
+                     │                 Error            Error       │
+                     │                                              │
+                     │              receipt (deterministic bytes)   │
+                     └──────────────────────────────────────────────┘
+   exit 0 = allow                       │
+   exit n = deny                        ▼
+                                  receipt directory (optional)
+```
+
+The hook is a thin I/O wrapper. Everything inside is pure: no clocks, no randomness, no network, no filesystem. Same input → same output, every time.
+
+## Module map
+
+| Module | Responsibility | Pure | Phase |
+| --- | --- | --- | --- |
+| `effects` | Closed six-class taxonomy + precedence + `most_restrictive` | yes | 1 ✓ |
+| `exceptions` | Hierarchy rooted at `SpineLiteError` | yes | 1 ✓ |
+| `manifest` | Tool-definition schema (Pydantic v2) | yes | 2 |
+| `classifier` | Tool call → effect set → `Decision` | yes | 2 |
+| `posture` | Posture state machine | yes | 3 |
+| `receipt` | Structured, deterministic decision records | yes | 3 |
+| `hook` | Claude Code PreToolUse stdin/stdout adapter | I/O | 3 |
+| `cli` | Operator interface (Typer) | I/O | 1 (`version`) → 3 (full) |
+
+The five pure modules contain no clocks, no randomness, no network, no filesystem. Determinism is the contract.
+
+## Why the pure / I/O split
+
+Determinism only holds if there's exactly one boundary where wall-clock entropy enters. Everything else has to be pure. The hook is that boundary; the CLI is that boundary; nothing else is.
+
+This is what makes a receipt content-addressable. A receipt that hashed differently every time you ran it would be useless for replay; the only way to get byte-stability is to keep the hot path free of timestamps, UUIDs, and randomness. The cost is one extra layer of indirection (the hook); the benefit is replayability by SHA forever.
+
+## Why a closed taxonomy
+
+A taxonomy that grows at runtime is a taxonomy that drifts. The six classes were chosen to draw the lines that matter for safety review:
+
+- `READ` vs. `WRITE`: did anything change?
+- `WRITE` vs. `NETWORK`: did anything cross a trust boundary?
+- `NETWORK` vs. `EXECUTE`: did we hand control to another process?
+- `EXECUTE` vs. `SPAWN`: did the child outlive the call?
+- `SPAWN` vs. `DESTRUCTIVE`: can we undo it?
+
+Anything finer is a manifest concern, not a taxonomy concern. If something feels like a seventh class, it's almost always an existing class with manifest-level qualifiers — *which* file the WRITE touched, *which* host the NETWORK call hit.
+
+Adding a class is permitted but expensive. The process is in [Effects Taxonomy / Why closed](../concepts/effects-taxonomy.md#why-closed) and triggers a HALT to the project lead.
+
+## Phase plan
+
+| Phase | Modules | Version | What you can do |
+|---|---|---|---|
+| 1 (shipped) | `effects`, `exceptions`, `cli` (`version`) | `v0.1.0a0` | Collapse effect sets, raise/catch typed errors, ship as a package. |
+| 2 | `+ manifest`, `classifier` | `v0.2.0a0` | Classify a tool call against a manifest, get a `Decision`. |
+| 3 | `+ posture`, `receipt`, `hook`, `cli` (full) | `v0.3.0a0` | End-to-end PreToolUse integration with Claude Code. |
+
+The architecture stays the same across phases. Each phase fills in pure modules that adhere to the same purity contract.
+
+## Reference implementation
+
+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.
+
+## See also
+
+- [Invariants](invariants.md) — the rules nothing in this repo gets to break.
+- [Design Rationale](design-rationale.md) — past decisions, with reasoning.
+- [Porting Notes](porting-notes.md) — TypeScript-to-Python translation log.
+- [FAQ](faq.md) — common questions about the design.