From 233c80b65ca512624b7ddd3fca771a18ec151727 Mon Sep 17 00:00:00 2001 From: HALCIVXIVC <25841608+hoohugokim@users.noreply.github.com> Date: Thu, 22 Oct 2026 02:38:41 +0900 Subject: [PATCH] docs: put quickstart and agent setup first in the README Add a compact SVG masthead, badges, navigation, a concrete example, and a shorter agent chooser. Move policy, architecture/API, global-layer, and worker reference into linked guides. Correct Antigravity checkout paths and batch-tool registration while preserving coverage limits. Validated GitHub Markdown rendering, navigation and file targets, 1200 px and 390 px layouts, independent editorial review, and 15 focused package/release/documentation checks. Co-Authored-By: Codex (GPT-5.5) --- HANDOFF.md | 45 ++-- README.md | 385 ++++++++++++-------------------- TASKS.md | 1 + adapters/antigravity/README.md | 32 +-- docs/architecture.md | 105 +++++++++ docs/branding/statutor-mark.svg | 24 ++ docs/global.md | 111 +++++++++ docs/policy.md | 104 +++++++++ docs/workers.md | 81 +++++++ tests/test_public_claims.py | 8 +- 10 files changed, 614 insertions(+), 282 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/branding/statutor-mark.svg create mode 100644 docs/global.md create mode 100644 docs/policy.md create mode 100644 docs/workers.md 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.

+ +

+ CI status + PyPI version + MIT license +

+ +

+ Quickstart · Agents · The ledger · Documentation +

+ +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