Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 22 additions & 23 deletions HANDOFF.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,39 @@
<!-- statutor: plane=state | policy=overwrite_bounded (max 40 lines) | writer=executor | OVERWRITE, NEVER APPEND -->
# 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.
385 changes: 142 additions & 243 deletions README.md

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions TASKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
32 changes: 19 additions & 13 deletions adapters/antigravity/README.md
Original file line number Diff line number Diff line change
@@ -1,51 +1,53 @@
# 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/<name>/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

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
Expand All @@ -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",
Expand Down Expand Up @@ -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

Expand Down
105 changes: 105 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -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/).
24 changes: 24 additions & 0 deletions docs/branding/statutor-mark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading