diff --git a/HANDOFF.md b/HANDOFF.md
index e983dd8..9fcefd5 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -1,40 +1,39 @@
# HANDOFF
-last_verified: 2026-10-21 (UTC) by release/tag CI, exact-index gate (769 passed, zero skips), registry payload comparisons, clean installs, and runtime smoke
+last_verified: 2026-10-21 (UTC) by 15 documentation/package/release checks, independent editorial review, GitHub rendering, and desktop/narrow layout measurements
last_worker: codex
last_machine: unknown
-handoff_id: f825979d18e44892bc8645f473f1f1da
-supersedes: b2bb593f0c7b485b814379cf546642cd
+handoff_id: 57e014efb00e443187d60ce57339a5a0
+supersedes: f825979d18e44892bc8645f473f1f1da
## Goal
-Completed hardened Python/plugins 0.7.4, npm adapter 0.2.0, and crate 0.1.2
-(D-0029, T-0049..T-0054), following the v0.7.3 audit. All channels verified.
+Publish the README redesign approved by the human (T-0055).
## Last verified state
-- Floor preserves worktree, Git mode, strict policy, glob, and state identity.
- Independent checks: 109 differential cases, 307 policies, 149,481 globs.
-- Global lifecycle binds logical/resolved targets and rolls back safe owned
- replacements. Global tests: 100 passed. Worker family: 90 passed.
-- Native batch edits preserve CRLF. Stop fails open on malformed metadata.
- Gate snapshots exact index; original HEAD/tree authorizes trust receipts.
-- Runtime review PASS+NOTES and Standards PASS through 7a6f25c; no findings.
- Completed specifications moved unchanged into plans/archive.
-- Current fake-profile probes: Claude 2.1.296, Codex 0.162.1, OpenCode 2.1.1.
- Rust 1.75 release build, seven unit tests, and conformance pass.
-- PR #2 merged as 0572042; tag v0.7.4 CI and PyPI publisher both passed.
-- Public payloads match the tag; registry installs and hook tests pass. GitHub has all four artifacts.
+- README is 144 lines, with a compact masthead, badges, navigation, example,
+ quickstart, agent chooser, Git setup, and visible coverage limits.
+- Four linked guides preserve policy/trust, architecture/API, optional global
+ instructions/skills, and worker provenance. Repository links resolve.
+- Antigravity setup now names a real checkout location, registers batch edits,
+ and describes fail-open behavior and the local Git hook's bypass honestly.
+- GitHub Markdown rendering preserves all navigation targets and four images.
+ Browser DOM layout has no article overflow at 1200 px and 390 px widths.
+- Independent editorial review PASS; 15 focused checks pass, including real
+ npm/Cargo payload audits. Runtime code, versions, and policy are unchanged.
+- Hardened release remains Python/plugins 0.7.4, npm 0.2.0, and crate 0.1.2.
+ PR #2/tag publication and public package verification remain complete.
## Next action
-No release work remains. Select the next milestone with the human.
-Local CLI and Claude plugin are 0.7.4; restart Claude to load the plugin.
+Publish the documentation branch, verify CI, merge, and check remote assets.
## Gotchas
-- Legacy worker sessions lack ledger scope: begin a new session to mutate.
-- Global probes prove only their reported native surfaces; Claude has no
- offline personal-skill catalog. Real-home global migration is separate.
+- CLI installation and project initialization do not register agent hooks.
+- Hooks fail open; staged checks fail closed. Git hooks allow --no-verify.
+- Begin fresh legacy worker sessions after upgrading; restart Claude for its
+ already-updated 0.7.4 plugin. Global migration remains a separate opt-in.
## Do not touch
-Embedded TEMPLATES/INIT_PROFILES; frozen archive; DECISIONS.md header;
+Embedded templates/init profiles; frozen archive; DECISIONS.md header;
root pre-commit metadata. Preserve untracked .agents/, _local/, assets/,
notes/, and plans/v0.4-dogfood.pdf.
diff --git a/README.md b/README.md
index 728ec93..557d79d 100644
--- a/README.md
+++ b/README.md
@@ -1,245 +1,144 @@
-# statutor
-
-Statutor keeps a typed project ledger for repos that more than one coding
-agent edits. Four planes each have one writer and a mutation policy. Hooks
-apply that policy before a tool writes, and `statutor staged` applies it
-again to the git index. The active policy is the committed `.statutor.yaml`.
-
-The name is the agent noun of *statuere*: one who enacts. One kernel serves
-Claude Code, Grok Build, OpenCode, Codex, Google Antigravity, the git
-pre-commit floor, and any harness that calls `validate`. Release notes live
-on GitHub Releases. There is no hand-maintained CHANGELOG.md.
-
-| Plane | Files | Policy | Enforced by |
-|---|---|---|---|
-| Constitution | AGENTS.md (+ CLAUDE.md = `@AGENTS.md`) | hard cap 200 lines | hook + git floor |
-| State | HANDOFF.md | overwrite-only, ≤ 40 lines, required sections | hook + git floor |
-| State | TASKS.md | stable T-NNNN ids; mutable checkbox/detail/order | hook + git floor + doctor |
-| Log | DECISIONS.md | append-only, insertions only, supersede-never-edit | hook + git floor |
-| Plan | ROADMAP.md, plans/ → plans/archive/ (frozen) | archive immutable | hook + git floor |
-
-Plus a **bash guard** on every harness: shell writes to governed files
-(`>>`, `sed -i`, `tee`, ...) are denied — the editor tools are the audited
-path. Automatic adapters stay silent outside a repository explicitly marked
-by `.statutor.yaml`. A complete quoted heredoc used as `git commit -F -`
-message data is not scanned as shell code; its opener and all actual command
-lines remain guarded.
-
-The policies are ordered by reversibility and the guardrails follow that
-order: a HANDOFF overwrite is reversible, a TASKS checkbox or detail edit is
-reversible with history, a DECISIONS append is irreversible by policy, and an
-archived plan is frozen (only `git mv` INTO `plans/archive/` is allowed). Text
-an agent reads or quotes — a note, a heredoc, a tool result — informs its
-proposal but never authorizes a mutation: only the declared policy under the
-committed HEAD snapshot gates a write, in-loop and at the git floor alike.
-
-State task identities are durable: an existing ID cannot disappear or be
-renamed, while its checkbox, detail, and position may change. New IDs advance
-beyond the committed maximum. v0.4 intentionally has no pruning operation;
-completed entries remain until a separately specified identity-preserving
-archive exists (D-0016).
-
-## Kernel / adapter architecture
-
- core/statutor_core.py single-file kernel: validate() + embedded templates
- modes: hook | check | staged | init | trust approve
- (fail-open hooks; staged floor fails closed)
- core/statutor_doctor.py drift linter (stale stamps, budgets, unarchived plans)
- core/statutor_global.py global-layer roots, schemas, hashes, CAS, backups
- core/statutor_global_cli.py opt-in global instruction lifecycle and CLI
- core/statutor_skills.py portable Agent Skill validation and projections
- hooks/stop_doctor.py Claude Code Stop hook: runs statutor-doctor after each
- turn and surfaces its WARN/ERROR lines as
- additionalContext — non-blocking, silent when the
- ledger is clean or the cwd isn't a statutor ledger at all
- pyproject.toml pipx install → `statutor`, `statutor-doctor` on PATH
-
-| Adapter | Mechanism | Coverage |
+
+
+
+
+
Statutor
+
+
Keep project rules, handoffs, and decisions intact across coding-agent sessions.
+
+Statutor gives a repository a small set of files for its rules, current work,
+and decision history. Hooks check supported tool calls before they write.
+The Git check validates the staged result against the committed policy.
+
+```text
+Append a new decision → allowed
+Rewrite an earlier decision → blocked
+Edit an ordinary source file → allowed
+```
+
+## Quickstart
+
+### Install and initialize
+
+Requires Python 3.10 or later. Run these commands in your project directory:
+
+```sh
+pipx install statutor
+statutor init .
+```
+
+Existing files stay unchanged. `init` creates the ledger and detects a small
+project profile. Use `statutor init . --type none` for governed files only.
+[Profiles and policy](https://github.com/hoohugokim/statutor/blob/main/docs/policy.md).
+
+### Choose your agent
+
+Connect an adapter to check supported tool calls during a session. Installing
+the CLI and initializing a ledger do not register agent hooks.
+
+| Agent | In-loop checks | Setup |
|---|---|---|
-| Claude Code (repo root is the plugin) | PreToolUse `Write\|Edit\|Bash\|apply_patch` → `statutor hook`; Stop → `hooks/stop_doctor.py` | full in-loop + drift surfacing |
-| Google Antigravity (`adapters/antigravity/`) | PreToolUse (`run_command\|write_to_file\|replace_file_content`) → `statutor hook`; Stop → `statutor hook --stop` | full in-loop + drift surfacing |
-| OpenCode (`adapters/opencode/statutor.ts`) | 2.x `ctx.tool.hook("execute.before")`, 1.x `tool.execute.before` → `statutor check --if-ledger` | in-loop (shell/write/edit/patch)¹ |
-| Codex CLI (`adapters/codex/`) | PreToolUse (Claude-compatible protocol) → `statutor hook` | bash guard + apply_patch² |
-| Grok Build (repo root is the plugin; `adapters/grok/`) | PreToolUse `search_replace\|write\|run_terminal_command` → `statutor hook`; Stop → `hooks/stop_doctor.py` | editor + shell in-loop, drift once per turn³ |
-| git (`adapters/git/`, `.pre-commit-hooks.yaml`) | `statutor staged` in local pre-commit and CI | staged-index backstop |
-| native (`crates/statutor/`) | `statutor-staged`, conformance-gated ≡ Python | local staged floor without Python |
-| Custom harnesses (`statutor check`, or import `validate`) | embed in your own tool dispatch | full in-loop |
-
-¹ in-loop for OpenCode 2.x `shell`/`write`/`edit`/`patch` and 1.x
-`bash`/`write`/`edit`/`apply_patch`; the kernel parses patch envelopes
-(T-0011), with two partial-diff blind spots: required sections
-on an Update File and server-namespaced MCP tool ids — the git floor
-covers both. Subagent tool calls
-DO fire plugin hooks (verified on the 1.x hook surface, opencode v1.18.21,
-2026-08-21); the
-opposite claim (sst/opencode#5894) was a misdiagnosis, stale-closed
-2026-04-15.
-² Codex hooks are on by default since rust-v0.124.0 (2026-04-23) — the old
-`[features].codex_hooks` flag is a deprecated legacy alias, and hooks need
-a one-time trust approval (`/hooks`). Codex sends edits as tool_name
-`apply_patch` + `{"command":
-""}`, which `guard_apply_patch()` parses (frozen/delete/
-append-only/cap checks; see adapters/codex/). Residual gaps: MCP tools
-and Update-File section checks — so the git floor remains
-mandatory there.
-³ Grok Build reuses the Claude hook protocol. The kernel canonicalizes
-`search_replace`, `write`, `run_terminal_command`, and the Cursor-preset
-names `StrReplace` and `Shell`. A truncated tool body, or a `hashline_edit`
-with no `old_string`, is denied when the path is governed. Register the
-root plugin once (`grok plugin install`) or the `~/.grok/hooks/` snippet in
-`adapters/grok/`, not both. MCP tool ids and bash-mode `!` commands stay
-with the git floor. The capability pin is Grok Build 1.0.62.
-
-Worker provenance (v0.5, `statutor machine`/`statutor worker`): automatic
-hooks on every host prove an **attempt** only and record nothing by
-themselves — the hook path stays fail-open. Ingress is executor- or
-custom-run (`begin` → `record --event attempt` → attributed rewrite →
-`complete --session`); `--event mutation` under an automatic harness is
-denied. `worker capabilities` reports proven surfaces and gaps per host
-(verified against Claude Code 2.1.258, Codex CLI 0.152.1, OpenCode 1.18.20,
-Grok Build 1.0.62 baselines); `worker compare ` explains sibling handoffs read-only. The
-machine-local registry is a bounded ring (50 sessions per project, 20 leases
-per worktree), not an audit trail; durable provenance is the attributed
-HANDOFF lineage in Git history, which lives as long as the repository does.
-
-## Install
-
- pipx install statutor # or: pip install -e .
- statutor init . # scaffold any repo, any harness
- statutor init . --type none # governed files only; env: STATUTOR_INIT_TYPE
-
- # Claude Code (this repo doubles as the plugin):
- /plugin marketplace add https://github.com/hoohugokim/statutor
- /plugin install statutor@hoo-plugins --scope project
- # then: /statutor-init /handoff /decide /statutor-doctor
-
- # Grok Build — same repo, one registration (see adapters/grok/):
- grok plugin marketplace add https://github.com/hoohugokim/statutor
- grok plugin install statutor --trust
-
- # .pre-commit-config.yaml
- repos:
- - repo: https://github.com/hoohugokim/statutor
- rev: v0.7.4
- hooks: [{id: statutor}]
-
-`init` never mandates a layout (D-0024). It selects a profile — `--type NAME`,
-else `STATUTOR_INIT_TYPE`, else the first marker found in the order below, else
-`min` — and adds only empty conventional directories on top of the governed
-files, `plans/archive/`, `notes/`, and the `CLAUDE.md` bridge. Present paths
-are skipped, never overwritten, adopted, or followed; no profile writes
-policy, constitution content, or ecosystem files, and the `min` fallback
-prints and creates exactly what the pre-v0.6 `init` did.
-
-| Profile | Adds | Selected by |
+| Claude Code | File edits, shell, and patches | [Plugin commands below](#claude-code) |
+| Codex CLI | Shell and patches | [Guide](https://github.com/hoohugokim/statutor/blob/main/adapters/codex/README.md) |
+| OpenCode | File edits, shell, and patches | [Guide](https://github.com/hoohugokim/statutor/blob/main/adapters/opencode/README.md) |
+| Google Antigravity | File edits, batch edits, and shell | [Guide](https://github.com/hoohugokim/statutor/blob/main/adapters/antigravity/README.md) |
+| Grok Build | File edits and shell | [Guide](https://github.com/hoohugokim/statutor/blob/main/adapters/grok/README.md) |
+| Custom agents | Checks through the CLI or Python API | [API and architecture](https://github.com/hoohugokim/statutor/blob/main/docs/architecture.md) |
+
+#### Claude Code
+
+Run these slash commands inside Claude Code:
+
+```text
+/plugin marketplace add https://github.com/hoohugokim/statutor
+/plugin install statutor@hoo-plugins --scope project
+```
+
+The repository is the plugin. It includes `/statutor-init`, `/handoff`,
+`/decide`, and `/statutor-doctor`.
+
+### Enable the Git backstop
+
+Hooks cover different tools on each agent. Use the staged-index check in
+addition to your agent adapter. With [pre-commit](https://pre-commit.com/#installation)
+installed, add this entry to your project's `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+ - repo: https://github.com/hoohugokim/statutor
+ rev: v0.7.4
+ hooks: [{id: statutor}]
+```
+
+Then install the Git hook and check the ledger:
+
+```sh
+pre-commit install
+statutor-doctor .
+```
+
+Run `statutor staged .` to check the current index directly. A
+[native Rust binary](https://github.com/hoohugokim/statutor/blob/main/crates/statutor/README.md)
+provides the same staged checks without Python.
+[Git setup and limits](https://github.com/hoohugokim/statutor/blob/main/adapters/git/README.md).
+
+## How the ledger works
+
+Each file has a designated writer and a mutation policy. Four planes separate
+rules, current state, decisions, and plans:
+
+| Plane | Default files | Rule |
|---|---|---|
-| `python` | `tests/` | `pyproject.toml`, `setup.py`, `setup.cfg` |
-| `rust` | `tests/` | `Cargo.toml` |
-| `node` | `test/` | `package.json` |
-| `docs` | `docs/` | `mkdocs.yml`, `_quarto.yml`, an existing `docs/` |
-| `min` | nothing further | fallback when no marker matches, or explicitly |
-| `none` | nothing, not even `plans/archive/` or `notes/` | `--type none` or `STATUTOR_INIT_TYPE=none` only |
-
-Per-repo policy lives in `.statutor.yaml`. In-loop checks use the committed
-HEAD snapshot; the git floor judges the transaction under both HEAD and the
-candidate index snapshot, so an unstaged or co-staged weakening cannot disable
-existing rules. The format is a strict, zero-dependency YAML subset shared by
-Python and Rust; malformed or unsupported committed/candidate policy denies.
-Before the marker's first commit, automatic hooks use embedded defaults. An
-edited worktree policy does not change hook behavior until it passes trust
-approval and becomes HEAD in a separate commit.
-
-After bootstrap, changing `.statutor.yaml` or Statutor's exact
-`CLAUDE.md` → `@AGENTS.md` bridge requires an exact-tree Git-local receipt:
-
- git add .statutor.yaml
- statutor trust approve . --decision D-0015 --reason "why this changes trust"
- statutor staged .
-
-Approval displays the reserved diff and all staged paths, then requires the
-complete candidate tree ID. The mode-0600 receipt expires on any HEAD or index
-change and is never committed.
-
-## Release gate
-
-With Python `build`/`pytest`/`PyYAML`, Cargo, and Node 24/npm available, stage the candidate and
-run `python scripts/release_gate.py`. The gate tests the exact Git index, audits
-all package payloads, builds the Python sdist and wheel in scratch space,
-installs the wheel into an isolated target, and smoke-tests both console
-scripts. A tagged release additionally passes `--tag vX.Y.Z --dist-dir dist`;
-verified artifacts are copied only after every check succeeds.
-
-The v0.4 global layer also has a separate, opt-in current-host probe:
-`python scripts/global_e2e.py --json`. It pins the tested Claude, Codex, and
-OpenCode versions, rehomes every host under a temporary profile, performs no
-model or external network request, and proves native discovery where an offline surface
-exists, modified-target refusal, and exact uninstall recovery. It is not part
-of the hermetic release gate and never mutates the caller's real home.
-
-The current global-layer baselines are Claude Code 2.1.296, Codex CLI 0.162.1,
-and OpenCode 2.1.1. Codex exposes the prompt catalog; OpenCode exposes its
-skill catalog through a private loopback API. Claude has no offline personal
-skill catalog probe. These checks do not extend the worker capability claims.
-
-## Portable user layer (v0.4)
-
-The global layer is opt-in and separate from project ledgers. `init` creates
-only human-owned canonical sources and versioned state; it does not change any
-host file. `plan`, `status`, and `--json` are read-only. `apply` owns only
-whole generated files it created, while `adopt HOST` backs up an existing
-regular file and imports its bytes verbatim into that host's canonical overlay.
-
- statutor global init
- statutor global plan --json
- statutor global apply --host codex
- statutor global status --json
- statutor global doctor --json
- statutor global adopt claude
- statutor global uninstall --host codex
-
- statutor global skill import ./my-skill
- statutor global skill plan --json
- statutor global skill apply
- statutor global skill status --json
- statutor global skill sync
- statutor global skill uninstall
-
-Every mutation prints its resolved plan first. Existing unmanaged targets are
-conflicts, managed hand edits are never overwritten or removed, and uninstall
-restores the original backup. `--home`, `--config-root`, and `--state-root`
-provide explicit isolated roots for tests and alternate profiles. Codex
-overrides and OpenCode's Claude fallback are reported as precedence warnings;
-Statutor never rewrites them.
-
-Imported skills are copied to a new human-owned canonical source, then
-projected as complete trees to `$HOME/.agents/skills` and Claude's personal
-skills root. Core `SKILL.md` metadata and the complete tree are validated;
-host-specific frontmatter is preserved. Identical unmanaged trees require
-explicit `--adopt-identical`, differing or hand-edited trees are conflicts,
-and names in a foreign `.agents/.skill-lock.json` remain entirely foreign.
-OpenCode discovers the portable and Claude projections, so Statutor reports
-whether those duplicates are identical instead of creating a third native
-OpenCode copy.
-
-Unified `global status` is a fast, read-only inventory of effective instruction
-precedence, ownership, disabled/foreign skills, duplicate names, legacy/native/
-admin/plugin roots, and catalog size. `global doctor` performs the deeper full-
-tree audit: managed drift and receipt topology, generated headers, unsafe links,
-active divergent duplicates, Codex's configured instruction cap, and Statutor's
-32 KiB skill-description diagnostic budget (reported explicitly as a Statutor
-budget, not a host limit). Status exits zero when inventory completes; doctor
-exits one when the audit contains errors. Neither command invokes a host binary
-or performs a network request.
-
-## Provenance
-
-Framework doctrine distilled from: the AGENTS.md open standard
-, Claude Code memory & hooks docs
-, ,
-Anthropic on long-running agent harnesses
-
-and context engineering
-,
-MADR , Keep a Changelog
-, Conventional Commits
-, pre-commit .
+| Constitution | `AGENTS.md` | Human-owned rules, capped at 200 lines |
+| State | `HANDOFF.md`, `TASKS.md` | Bounded handoff; stable task IDs |
+| Log | `DECISIONS.md` | Append new decisions; preserve earlier entries |
+| Plan | `ROADMAP.md`, `plans/` | Archived plans are frozen |
+
+The default handoff is limited to 40 lines. Task checkboxes, descriptions, and
+ordering can change; existing IDs remain. `CLAUDE.md` bridges to `AGENTS.md`.
+See [policy and trust](https://github.com/hoohugokim/statutor/blob/main/docs/policy.md)
+for writer roles, budgets, shell checks, and intentional policy changes.
+
+## Optional capabilities
+
+- [Global instructions and skills](https://github.com/hoohugokim/statutor/blob/main/docs/global.md):
+ preview and manage shared instructions and skills across supported hosts.
+ This is a separate opt-in operation from project initialization.
+- [Worker provenance](https://github.com/hoohugokim/statutor/blob/main/docs/workers.md):
+ record sessions and attributed handoffs. Automatic hooks prove attempts,
+ never successful mutation, and record nothing by themselves.
+
+## Coverage and limits
+
+Automatic adapters stay silent outside a repository explicitly marked
+by `.statutor.yaml`. Hook failures allow the session to continue. The staged
+floor fails closed on invalid policy or Git errors. It inspects the local
+index; Git hooks can be bypassed with `--no-verify`.
+
+MCP tools and some partial-patch checks remain outside in-loop coverage.
+Use the Git backstop to check their staged results. Agent-specific guides
+above describe each adapter's scope and verified behavior.
+
+## Documentation
+
+[Policy and trust](https://github.com/hoohugokim/statutor/blob/main/docs/policy.md) ·
+[Architecture and API](https://github.com/hoohugokim/statutor/blob/main/docs/architecture.md) ·
+[Global layer](https://github.com/hoohugokim/statutor/blob/main/docs/global.md) ·
+[Workers](https://github.com/hoohugokim/statutor/blob/main/docs/workers.md) ·
+[Releasing](https://github.com/hoohugokim/statutor/blob/main/docs/releasing.md) ·
+[Release notes](https://github.com/hoohugokim/statutor/releases)
+
+For local development, run `pip install -e .`, `pytest -q`, and
+`statutor-doctor .`. The kernel has no third-party dependencies; PyYAML is
+optional. [Architecture](https://github.com/hoohugokim/statutor/blob/main/docs/architecture.md)
+covers the source layout, validation modes, design references, and contribution checks.
diff --git a/TASKS.md b/TASKS.md
index 795bc7b..c0c9f8a 100644
--- a/TASKS.md
+++ b/TASKS.md
@@ -55,3 +55,4 @@
- [x] T-0052 Guard Antigravity multi-replacement edits, harden Stop event parsing, make OpenCode candidate tests hermetic, and gate Antigravity version parity — DONE 2026-10-22: batch reconstruction preserves CRLF; malformed Stop events fail open; candidate CLI shim and exact-snapshot/original-receipt gates pass; full suite 756 passed, two dedicated package audits deferred to full gate
- [x] T-0053 Reconcile release docs, tracked runbooks, completed specifications, and current-host verification; prove hardened artifacts and obtain independent review — DONE 2026-10-22: exact-index artifact gate at ab454d5 passed 769 tests with zero skips, seven Rust tests, all package audits and installed-wheel smoke; native Claude/Codex/OpenCode probes pass; independent runtime PASS+NOTES and Standards PASS
- [x] T-0054 Release the hardened Python/plugin, npm adapter, and native crate through available channels — DONE 2026-10-22: [GitHub v0.7.4](https://github.com/hoohugokim/statutor/releases/tag/v0.7.4), [PyPI 0.7.4](https://pypi.org/project/statutor/0.7.4/), [npm 0.2.0](https://www.npmjs.com/package/statutor/v/0.2.0), and [crate 0.1.2](https://crates.io/crates/statutor/0.1.2) verified; published payloads match release source; clean registry installs and runtime smoke pass; tag CI/publisher successful; local CLI/plugin updated to 0.7.4 (Claude restart required)
+- [ ] T-0055 Reorganize the README around a concrete example, quickstart, and agent setup; add compact branding, relocate reference guides, verify rendering and links, and publish the documentation update
diff --git a/adapters/antigravity/README.md b/adapters/antigravity/README.md
index 597a81f..5de4d12 100644
--- a/adapters/antigravity/README.md
+++ b/adapters/antigravity/README.md
@@ -1,20 +1,19 @@
# statutor × Google Antigravity
-Statutor provides first-class, native support for **Google Antigravity** (AGY /
-Gemini harness) alongside Claude Code, Codex, and OpenCode, with zero background
-daemons and 100% fail-open hook safety.
+Statutor checks Google Antigravity's native file and command tools. Hook
+errors allow the session to continue; the local Git floor fails closed.
## 1. Overview & Capabilities
| Layer | Antigravity Native Surface | Statutor Integration |
|---|---|---|
| **Constitution** | `AGENTS.md` (hierarchical walk to repo root) | Read directly; capped at soft 120 / hard 200 lines |
-| **Pre-Mutation Hooks** | `PreToolUse` in `hooks.json` (`run_command`, `write_to_file`, `replace_file_content`) | Validates all 4 planes, bash guard, append policies |
+| **Pre-Mutation Hooks** | `PreToolUse` in `hooks.json` (`run_command`, `write_to_file`, `replace_file_content`, `multi_replace_file_content`) | Validates all 4 planes, bash guard, append policies |
| **Drift Monitoring** | `Stop` in `hooks.json` | Runs `statutor-doctor`; warns on drift, bounded to 1 continuation |
| **Procedures & Skills** | `skills//SKILL.md` (progressive disclosure) | Bundles 5 skills: `statutor`, `statutor-init`, `statutor-doctor`, `handoff`, `decide` |
| **Rules Projection** | `rules/AGENTS.md` in plugin bundle | Injects four-plane invariants into active agent context |
| **Worker Provenance** | `last_worker: antigravity` in `HANDOFF.md` | Machine-local session tracking (`statutor worker`) |
-| **Absolute Backstop** | Pre-commit git hook | `statutor staged .` floor remains the unbypassable trust boundary |
+| **Git backstop** | Local pre-commit hook | `statutor staged .` checks the index; `--no-verify` bypasses the commit hook |
## 2. Installation
@@ -22,30 +21,33 @@ Requires `statutor` on `PATH` (`pip install -e .` or `pipx install statutor`).
### Option A: Install as a Workspace Plugin (Recommended)
-Copy or symlink this directory into your project's `.agents/plugins/` directory:
+Run these commands from the project you want to protect. Keep the adapter in
+a separate Statutor checkout, then link it into that project's plugin directory:
```bash
-mkdir -p .agents/plugins
-ln -s "$(pwd)/adapters/antigravity" .agents/plugins/statutor
+mkdir -p "$HOME/.local/share" .agents/plugins
+git clone https://github.com/hoohugokim/statutor.git "$HOME/.local/share/statutor-source"
+ln -s "$HOME/.local/share/statutor-source/adapters/antigravity" .agents/plugins/statutor
```
-Or declare it in `.agents/plugins.json`:
+If you already have a checkout, use its absolute path instead. As an alternative
+to the link, declare that absolute path in `.agents/plugins.json`:
```json
{
"entries": [
- { "path": "adapters/antigravity" }
+ { "path": "/absolute/path/to/statutor/adapters/antigravity" }
]
}
```
### Option B: Install Globally
-To enable Statutor across all projects on your workstation:
+To register the adapter across projects, use the checkout created above:
```bash
mkdir -p ~/.gemini/config/plugins
-ln -s /path/to/statutor/adapters/antigravity ~/.gemini/config/plugins/statutor
+ln -s "$HOME/.local/share/statutor-source/adapters/antigravity" ~/.gemini/config/plugins/statutor
```
### Option C: Direct Hook Integration
@@ -57,7 +59,7 @@ If you prefer using `.agents/hooks.json` directly without packaging as a plugin:
"statutor": {
"PreToolUse": [
{
- "matcher": "run_command|write_to_file|replace_file_content",
+ "matcher": "run_command|write_to_file|replace_file_content|multi_replace_file_content",
"hooks": [
{
"type": "command",
@@ -100,6 +102,10 @@ normalizes tool names and arguments:
or deleting settled decisions is blocked.
- `TASKS.md`: Task IDs (`T-NNNN`) cannot be deleted or renumbered; checkbox toggles
and details are allowed.
+* **`multi_replace_file_content`** (`TargetFile`, `ReplacementChunks`):
+ Reconstructs the candidate from nonoverlapping replacements and validates
+ the complete result. Ambiguous or malformed chunks are denied on governed
+ files. Existing line endings are preserved.
## 4. Multi-Agent & Subagent Orchestration
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..d3e1d2f
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,105 @@
+# Architecture and enforcement
+
+[Start here](../README.md) · [Ledger rules](policy.md) · [Global instructions](global.md) · [Worker provenance](workers.md)
+
+The canonical Python kernel validates proposed file changes. Adapters translate
+agent tool events into that shared contract. The staged validator checks the
+complete Git index independently of which tool produced it.
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| [`core/statutor_core.py`](../core/statutor_core.py) | `validate()`, embedded templates and init profiles, policy parsing, hook/check/staged/init/trust commands. No third-party dependencies. |
+| [`core/statutor_doctor.py`](../core/statutor_doctor.py) | Drift diagnostics for dates, budgets, state records, and consumed plans. |
+| [`hooks/stop_doctor.py`](../hooks/stop_doctor.py) | Non-blocking drift feedback at the end of an agent turn. |
+| [`core/statutor_global.py`](../core/statutor_global.py) | Global roots, schemas, hashes, target identity, atomic replacement, backups, and recovery. |
+| [`core/statutor_global_cli.py`](../core/statutor_global_cli.py) | Opt-in global instruction planning, adoption, apply, and uninstall. |
+| [`core/statutor_skills.py`](../core/statutor_skills.py) | Agent Skill validation and complete-tree projections. |
+| [`core/statutor_global_status.py`](../core/statutor_global_status.py) | Global inventory, precedence, ownership, and deeper doctor diagnostics. |
+| [`core/statutor_worker.py`](../core/statutor_worker.py) | Machine-local worker evidence, session identity, and HANDOFF lineage checks. |
+| [`crates/statutor/`](../crates/statutor/README.md) | Native staged-index implementation, conformance-gated against Python. |
+
+Templates live only in the kernel. The package exposes the `statutor` and
+`statutor-doctor` console scripts. PyYAML is optional; enforcement does not
+require it.
+
+## Enforcement layers
+
+| Layer | Input | Failure behavior |
+|---|---|---|
+| Automatic hook | A supported pre-tool event in a marked ledger | Denies known policy violations; fails open on an internal hook error. |
+| Explicit `statutor check` | A tool name, JSON payload, and directory | Exit 2 reports a policy denial. |
+| `statutor staged` | HEAD and the current worktree's staged index | Fails closed on invalid policy or Git read errors. |
+| `statutor-doctor` | Ledger files and policy | Reports drift without mutating files. |
+
+Automatic adapters stay silent outside the nearest `.statutor.yaml` ledger.
+Explicit checks can be used by custom integrations. The
+[policy guide](policy.md) explains committed-policy authority and bootstrap.
+
+## Agent adapters
+
+The root of this repository is the Claude Code plugin. Grok Build uses the
+same hook protocol and plugin with its own tool vocabulary. OpenCode uses a
+TypeScript adapter with 2.x `setup()` and 1.x `server()` entrypoints. Codex
+uses the shared hook command for shell and `apply_patch` events. Antigravity
+normalizes native tool arguments, including batch replacements.
+
+Use each adapter guide for registration and exact coverage:
+[Codex](../adapters/codex/README.md),
+[OpenCode](../adapters/opencode/README.md),
+[Antigravity](../adapters/antigravity/README.md), and
+[Grok Build](../adapters/grok/README.md).
+
+Hook coverage varies by host. Server-namespaced MCP tool IDs and required
+sections in partial Update File patches are known gaps. The floor judges the
+final staged blob, including its exact line count and required sections.
+Historical OpenCode subagent coverage was verified on 1.x; that result does
+not prove 2.x subagent coverage. Stop feedback reports drift, not completion.
+
+## Custom integrations
+
+Call the CLI before a proposed write. Exit 2 means the integration must deny it:
+
+```sh
+statutor check --if-ledger write '{"file_path":"notes/example.md","content":"example"}' .
+```
+
+For an application that installs the Python package in its own environment,
+call `validate()` with the tool name, complete payload, and project directory:
+
+```python
+from statutor_core import validate
+
+reason = validate("write", {"file_path": "notes/example.md", "content": "example"}, cwd=".")
+if reason is not None:
+ raise ValueError(reason)
+```
+
+`validate()` returns a denial reason or `None`. The caller performs the actual
+write only after validation succeeds. It does not register hooks or write files.
+
+## Local Git floor
+
+The [Git adapter](../adapters/git/README.md) runs `statutor staged` in local
+pre-commit and CI checks. The native `statutor-staged` binary implements the
+same local staged-index contract without requiring Python. It is not a
+server-side pre-receive validator and does not promise fully static linkage.
+`--no-verify` remains an explicit unverified escape from a local commit hook.
+
+Tests compare expected verdicts and Python/Rust output. The
+[release gate](releasing.md) also audits real package contents and smoke-tests
+an installed wheel from an isolated candidate snapshot.
+
+## Design references
+
+The name comes from the agent noun of *statuere*, one who enacts. The design
+draws on the [AGENTS.md standard](https://agents.md/),
+[Claude memory](https://code.claude.com/docs/en/memory) and
+[hooks](https://code.claude.com/docs/en/hooks), Anthropic's
+[long-running agent harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+and [context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents),
+[MADR](https://adr.github.io/madr/),
+[Keep a Changelog](https://keepachangelog.com/),
+[Conventional Commits](https://www.conventionalcommits.org/), and
+[pre-commit](https://pre-commit.com/).
diff --git a/docs/branding/statutor-mark.svg b/docs/branding/statutor-mark.svg
new file mode 100644
index 0000000..3e20c3c
--- /dev/null
+++ b/docs/branding/statutor-mark.svg
@@ -0,0 +1,24 @@
+
diff --git a/docs/global.md b/docs/global.md
new file mode 100644
index 0000000..088b4ea
--- /dev/null
+++ b/docs/global.md
@@ -0,0 +1,111 @@
+# Global instructions and skills
+
+[Start here](../README.md) · [Architecture](architecture.md) · [Worker provenance](workers.md)
+
+The optional global layer manages shared instructions and Agent Skills for
+Claude Code, Codex, and OpenCode. It is separate from project-ledger
+enforcement. Humans own the canonical sources; Statutor owns only complete
+generated targets that it created or explicitly adopted.
+
+## Set up shared instructions
+
+```sh
+statutor global init
+statutor global plan --json
+```
+
+`init` creates canonical sources and versioned state without changing host
+instruction files. Edit the common `AGENTS.md` and host overlays at the paths
+reported by the plan. Review the resolved targets before applying one host:
+
+```sh
+statutor global apply --host codex
+statutor global status --json
+statutor global doctor --json
+```
+
+| Host | Instruction target |
+|---|---|
+| Claude Code | `$CLAUDE_CONFIG_DIR/CLAUDE.md`, normally `~/.claude/CLAUDE.md` |
+| Codex | `$CODEX_HOME/AGENTS.md`, normally `~/.codex/AGENTS.md` |
+| OpenCode | `$XDG_CONFIG_HOME/opencode/AGENTS.md`, normally `~/.config/opencode/AGENTS.md` |
+
+An existing unmanaged target is a conflict. To import an existing Claude
+instruction file into its host overlay with an original backup, explicitly
+adopt it:
+
+```sh
+statutor global adopt claude
+```
+
+To remove managed projections and restore their original backups:
+
+```sh
+statutor global uninstall --host codex
+```
+
+Every mutation displays its resolved plan first. Writes check content tokens
+and the recorded logical and resolved target identities. Managed hand edits
+and retargeted parents cause refusal. Safe rollback restores the prior owned
+artifact; external edits are preserved with recovery evidence. These checks
+do not promise protection against adversarial directory replacement inside
+operating-system calls. See [D-0018 and D-0029](../DECISIONS.md).
+
+## Manage reusable skills
+
+```sh
+statutor global skill import ./my-skill
+statutor global skill plan --json
+statutor global skill apply
+statutor global skill status --json
+```
+
+Import creates a new human-owned canonical skill source. Statutor validates
+`SKILL.md` metadata and the complete tree while preserving host-specific
+frontmatter. The source projects to `$HOME/.agents/skills` and Claude's
+personal skills root. OpenCode discovers those projections; Statutor creates
+no third OpenCode-native copy.
+
+Edit the canonical source, then use `statutor global skill sync` to update
+managed copies. `statutor global skill uninstall` restores their initial
+backups. Identical unmanaged trees need explicit `--adopt-identical` on plan
+and apply. Differing or hand-edited trees remain conflicts. Names in a foreign
+`.agents/.skill-lock.json` remain foreign.
+
+## Inspect ownership and precedence
+
+`global status` is a fast, read-only inventory. It reports instruction
+precedence, disabled or foreign skills, duplicate names, legacy/native/admin/
+plugin roots, and catalog size. `global doctor` checks full trees for managed
+drift, receipt topology, unsafe links, generated headers, and active divergent
+duplicates. Its 32 KiB skill-description budget is a Statutor diagnostic,
+not a host limit.
+
+Status exits zero when inventory completes. Doctor exits one if it finds
+errors. Neither command invokes host binaries or makes network requests.
+Codex overrides and OpenCode's Claude fallback appear as precedence warnings;
+Statutor does not rewrite host configuration, overrides, plugin/admin/system
+content, or foreign locks.
+
+Use `--home`, `--config-root`, and `--state-root` to select explicit isolated
+roots for tests or alternate profiles. Real-home migration is an opt-in
+operation, separate from testing.
+
+## Run the native host probe
+
+From a source checkout with the tested host binaries installed:
+
+```sh
+python scripts/global_e2e.py --json
+```
+
+The probe rehomes hosts under a temporary profile and never mutates the
+caller's real home. It makes no model or external network request. OpenCode
+uses a private loopback server. The probe checks modified-target refusal,
+uninstall recovery, and native discovery where an offline command exists.
+
+Verified global-layer baselines are Claude Code 2.1.296, Codex CLI 0.162.1,
+and OpenCode 2.1.1. Codex exposes its prompt catalog; OpenCode exposes a skill
+catalog. Claude has no offline personal-skill catalog probe. OpenCode
+instruction projections are checked on disk, without exercising model-context
+loading. These results do not expand [worker capability claims](workers.md).
diff --git a/docs/policy.md b/docs/policy.md
new file mode 100644
index 0000000..20b7673
--- /dev/null
+++ b/docs/policy.md
@@ -0,0 +1,104 @@
+# Ledger rules and policy
+
+[Start here](../README.md) · [Architecture](architecture.md) · [Worker provenance](workers.md)
+
+Use this guide when changing ledger rules, choosing an initialization profile,
+or approving a policy change. The default ledger separates four kinds of record.
+
+| Plane | Default files | Writer | Rule |
+|---|---|---|---|
+| Constitution | `AGENTS.md` | Human | Keep the shared instructions within the configured line budget. |
+| State | `HANDOFF.md` | Executor | Replace the shift-change note; preserve its required sections and line cap. |
+| State | `TASKS.md` | Orchestrator | Preserve task IDs while updating status, detail, and order. |
+| Log | `DECISIONS.md` | Decision recorder | Add records; supersede earlier decisions with new records. |
+| Plan | `ROADMAP.md`, `plans/` | Human | Keep the active plan separate from the frozen archive. |
+
+The default hard cap is 200 physical lines for `AGENTS.md` and 40 for
+`HANDOFF.md`. `CLAUDE.md` contains `@AGENTS.md` as a compatibility bridge.
+The committed `.statutor.yaml` defines each project's actual filenames and rules.
+
+## Initialize a project
+
+```sh
+statutor init .
+```
+
+Initialization creates missing ledger files and skips existing paths. It never
+overwrites or adopts an existing constitution, policy, or `CLAUDE.md`, and it
+does not follow existing paths while creating the scaffold.
+
+Profiles add empty conventional directories. Selection follows this order:
+`--type NAME`, then `STATUTOR_INIT_TYPE`, then the first detected marker in
+the table below, then `min`.
+
+| Profile | Additional directories | Detection markers |
+|---|---|---|
+| `python` | `tests/` | `pyproject.toml`, `setup.py`, `setup.cfg` |
+| `rust` | `tests/` | `Cargo.toml` |
+| `node` | `test/` | `package.json` |
+| `docs` | `docs/` | `mkdocs.yml`, `_quarto.yml`, existing `docs/` |
+| `min` | None beyond `plans/archive/` and `notes/` | Fallback or explicit selection |
+| `none` | None, including no `plans/archive/` or `notes/` | Explicit selection only |
+
+```sh
+statutor init . --type none
+```
+
+Profiles do not impose a project layout or write ecosystem configuration.
+The profile decision is [D-0024 in the decision log](../DECISIONS.md).
+
+## Preserve record identity
+
+Each task occupies one line, such as `- [ ] T-0001 Describe the work`.
+IDs have at least four decimal digits and must be unique. An existing ID
+cannot disappear or be renamed. Its checkbox, detail, and position may change.
+New IDs must exceed the committed maximum. Completed tasks remain in place;
+there is no pruning operation. [D-0016](../DECISIONS.md) defines this contract.
+
+For append-only records, committed lines remain byte-identical and in order.
+Add a new decision to supersede an earlier one. Frozen archive files cannot
+be edited, deleted, or added directly. Move an existing plan into
+`plans/archive/` to archive it.
+
+## Use editor tools for governed files
+
+The shell guard denies write commands targeting governed files, including
+redirects, `sed -i`, and `tee`. Editor tools give Statutor the proposed content
+to validate. The Git floor checks the complete staged result afterward.
+
+A complete quoted heredoc used as `git commit -F -` message data is excluded
+from shell-code scanning. Its opener and actual command lines remain guarded.
+Quoted text, notes, and tool output provide context; they do not authorize a
+mutation. See [D-0019](../DECISIONS.md) for the shell-message exception.
+
+## Change policy with explicit approval
+
+In-loop checks use the committed HEAD policy. The Git floor judges a staged
+transaction under both the HEAD policy and the candidate index policy.
+Unstaged or co-staged weakening cannot disable the existing rules.
+
+The policy format is a strict, zero-dependency YAML subset shared by Python
+and Rust. Malformed or unsupported policy and Git read failures deny at the
+floor. Before the marker's first commit, automatic hooks use embedded defaults.
+An edited worktree policy becomes hook authority only after it is committed.
+
+After bootstrap, changes to `.statutor.yaml` or Statutor's exact
+`CLAUDE.md` bridge require an exact-tree Git-local approval receipt:
+
+```sh
+git add .statutor.yaml
+statutor trust approve . --decision D-0015 --reason "why this changes trust"
+statutor staged .
+```
+
+Use the decision ID that records your own project's change. Approval displays
+the reserved diff and every staged path, then requires the full candidate
+tree ID. The mode-0600 receipt is never committed and expires if HEAD or any
+staged entry changes, including a Git mode change.
+
+Approval permits the trust-root transition; it does not relax the old policy
+for another ledger mutation in the same commit. Commit an approved weakening
+first, then make the newly permitted change separately. Receipts record
+authorization, not human authentication. Local hooks can still be bypassed
+with `--no-verify`. See [D-0015 and D-0029](../DECISIONS.md) and the
+[Git adapter](../adapters/git/README.md).
diff --git a/docs/workers.md b/docs/workers.md
new file mode 100644
index 0000000..a5578d7
--- /dev/null
+++ b/docs/workers.md
@@ -0,0 +1,81 @@
+# Worker provenance and handoffs
+
+[Start here](../README.md) · [Ledger rules](policy.md) · [Global instructions](global.md)
+
+Worker provenance records who attempted work locally and who completed a
+shift. Automatic policy hooks record nothing by themselves. A pre-tool event
+proves an attempt, not a successful mutation or completed handoff.
+
+## Start a tracked shift
+
+Run this from the intended ledger and worktree, using your actual agent ID:
+
+```sh
+statutor worker begin --harness codex --json
+```
+
+Keep the returned session ID, machine ID, and baseline handoff ID. Recording
+and completion must use that session in its originating ledger and worktree.
+After upgrading an old registry, begin a fresh session if its existing entry
+lacks recorded ledger scope. Version-1 registries remain readable.
+
+Custom wiring can record an attempted operation. Replace `SESSION_ID` with
+the ID returned by `begin`:
+
+```sh
+statutor worker record --harness codex --event attempt --session SESSION_ID
+```
+
+Use `statutor worker capabilities --json` to inspect declared evidence and
+verification baselines for each agent. Automatic agent integrations cannot
+record `--event mutation`; only a human or a custom integration with actual
+post-success evidence may do so. An `unknown` agent proves activity only.
+Roles and origin agents stay `unknown` unless explicitly proved.
+
+## Complete the handoff
+
+First rewrite `HANDOFF.md` with the required sections and a current verification
+stamp. For portability across time zones, use the UTC verification date.
+Set `last_worker` to the session's agent and `last_machine` to its machine ID.
+Generate a fresh handoff ID:
+
+```sh
+statutor worker new-id
+```
+
+Set `handoff_id` to the new value and `supersedes` to the baseline ID returned
+by `begin`. Then record completion:
+
+```sh
+statutor worker complete --session SESSION_ID
+```
+
+Completion validates the HANDOFF attribution and revision lineage. It refuses
+a stale or foreign session and detects a competing local completion. An active
+lease is a machine-local presence hint, not proof that useful work occurred.
+The registry retains at most 50 sessions per project and 20 leases per
+worktree. Durable completion history lives in HANDOFF revisions committed to Git.
+
+## Inspect and reconcile
+
+```sh
+statutor machine show --json
+statutor worker show --basis completed --json
+statutor worker active --json
+statutor worker compare other-branch --json
+```
+
+The machine ID is random and stored in mode-0600 state. It is not derived from
+hardware, network addresses, hostnames, or accounts. Copied installations must
+rotate identity explicitly with `statutor machine rotate --confirm`.
+
+The local registry omits prompts, tool payloads, and conversation content.
+It is a bounded record of local evidence, not a cross-machine activity service.
+The optional [global instruction layer](global.md) does not synchronize it.
+
+`worker compare` reads a caller-supplied local Git ref. It explains sibling
+handoffs and lists the IDs a reconciliation must supersede. It does not fetch,
+merge, rewrite HANDOFF, or choose a winner. Once both histories are available,
+write one reconciled HANDOFF with a fresh ID and all relevant IDs in
+`supersedes`, then complete the session. See
+[D-0020 through D-0022 and D-0029](../DECISIONS.md).
diff --git a/tests/test_public_claims.py b/tests/test_public_claims.py
index 906f4f6..c8e9bf4 100644
--- a/tests/test_public_claims.py
+++ b/tests/test_public_claims.py
@@ -29,10 +29,12 @@ def test_install_snippets_use_real_repository_and_supported_pin() -> None:
def test_global_e2e_is_explicit_and_real_home_safe() -> None:
root = (ROOT / "README.md").read_text(encoding="utf-8")
+ guide = _read("docs/global.md")
script = (ROOT / "scripts/global_e2e.py").read_text(encoding="utf-8")
- assert "python scripts/global_e2e.py --json" in root
- assert "temporary profile" in root
- assert "never mutates the caller's real home" in root
+ assert "docs/global.md" in root
+ assert "python scripts/global_e2e.py --json" in guide
+ assert "temporary profile" in guide
+ assert "never mutates the caller's real home" in " ".join(guide.split())
assert "never points a host at the caller's real home" in script
assert "never performs a\nmodel or external network request" in script