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
4 changes: 2 additions & 2 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "statutor",
"version": "0.7.4",
"description": "Typed project-ledger framework: four planes, single-writer files, hook-enforced mutation policies. Kernel + adapters for Claude Code, Grok Build, OpenCode, Codex, git, and custom harnesses.",
"version": "0.7.5",
"description": "Typed project-ledger framework: four planes, single-writer files, hook-enforced mutation policies. Kernel + adapters for Claude Code, Cursor, Grok Build, OpenCode, Codex, git, and custom harnesses.",
"author": {
"name": "Hoo"
}
Expand Down
30 changes: 30 additions & 0 deletions .cursor/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "python3 core/statutor_core.py hook",
"matcher": "Write|StrReplace|Shell|Delete|MultiEdit|NotebookEdit|ApplyPatch",
"timeout": 30
}
],
"beforeShellExecution": [
{
"command": "python3 core/statutor_core.py hook",
"timeout": 30
}
],
"beforeMCPExecution": [
{
"command": "python3 core/statutor_core.py hook",
"timeout": 30
}
],
"stop": [
{
"command": "python3 core/statutor_core.py hook --stop",
"timeout": 30
}
]
}
}
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.12", "3.14"]
python-version: ["3.10", "3.12", "3.14", "3.15"]
steps:
- name: Checkout
uses: actions/checkout@v7
Expand Down
12 changes: 12 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,3 +198,15 @@
**Decision:** Managed instruction/skill operations validate recorded logical/resolved target identity and content tokens, including restore and rollback. Failed post-write checks restore the prior physical artifact when safe; concurrent external edits remain untouched and retain a recovery artifact. These checks do not claim protection against an adversary replacing physical directories during operating-system calls.
**Decision:** Worker ingress follows declared capabilities. Sessions bind to the initiating worktree and ledger; per-ledger completion state prevents nested ledgers from interfering. Registry version 1 gains optional `session.ledger_root` and `worktree.completed_by_ledger` fields. Old registries remain readable, but sessions without recorded ledger scope must begin a new session before recording or completing. Scope is never guessed from a shared worktree.
**Consequences:** T-0049..T-0054. Python/root and Antigravity plugins move to 0.7.4; the native crate moves to 0.1.2; the first published OpenCode 2.x adapter remains 0.2.0 and requires the hardened Python CLI. Regression cases precede fixes in history. Publication is verified independently per registry; Git tags and checked task boxes do not substitute for registry evidence.

## D-0030 — Cursor is a protocol map; 0.7.5 closes the 0.7.4 audit
**Status:** accepted
**Context:** The 0.7.4 audit found in-loop holes (Antigravity relative TargetFile vs process CWD; truncated apply_patch allowed; malformed HEAD policy fail-open in the hook; MultiEdit/NotebookEdit unproved; matcher missing `run_terminal_cmd`; Stop could doctor process CWD; Rust receipt missing-key ≠ Python `dict.get`; worker complete hardcoded `HANDOFF.md`) and no Cursor adapter. Cursor hooks.json v1 is a distinct stdin protocol (`hook_event_name`, `workspace_roots`, permission JSON). Empty stdout plus exit 0 fail-closes Cursor permission events.
**Decision:** Ship Cursor as 0.7.5 on the existing kernel. Auto-detect `hook_event_name` in `{preToolUse, beforeShellExecution, beforeMCPExecution, stop}`. Map Write/StrReplace/Shell/Delete/MultiEdit/NotebookEdit and MCP JSON-string payloads onto `validate()`. Permission hooks always emit `{"permission":...}`; fail-open is `allow`. Empty `workspace_roots` stays silent. Stable harness id is `cursor`. Automatic hooks prove attempt only. Dogfood `.cursor/hooks.json` against `core/statutor_core.py`. Close the listed 0.7.4 holes in the same release: relative TargetFile uses workspace CWD; truncated apply_patch denies; `_PolicyFailure` in the hook is `committed policy invalid`; unproved MultiEdit/NotebookEdit deny when governed; matcher includes `run_terminal_cmd`; Stop/doctor/worker honor the overwrite_bounded basename and D-0026 empty-workspace silence; Rust `yaml_optional_string` treats a missing optional OID key as `None`.
**Consequences:** T-0056, T-0057. Python/root and Antigravity plugins move to 0.7.5; the native crate moves to 0.1.3; npm stays 0.2.0. Tab completions and unmapped MCP payloads remain git-floor gaps. Publication remains a human step. Do not reopen D-0028 empty-`old_string` Claude Edit, D-0015 bootstrap receipts, TASKS pruning, or research-note D-number relabel.

## D-0031 — Repair CLI recovery without changing the local registry format
**Status:** accepted
**Context:** The follow-up flow audit reproduced ignored root arguments, misleading completion retry conflicts, inconsistent CLI help/errors, and Cursor setup/Stop mismatches. Transparent completion replay would need new saved digest evidence, but an extra session field under schema 1 would make older strict readers reject newly written registries.
**Decision:** Preserve the schema-1 registry shape. A completed session reports `already completed` and directs the caller to inspect the recorded result or begin a new session; it never invents a competing completion. Root options work before or after machine/worker subcommands, with explicit child values taking precedence. Invalid `check` invocations return usage status 64; policy denials remain 2 and automatic hooks still fail open. Cursor Stop uses the native [`followup_message`](https://cursor.com/docs/hooks#stop) once at loop count 0, with later loops and aborted/error turns quiet. A fresh 1970 scaffold is described as not yet verified without changing its template or stamping unperformed verification. D-0029's [Unicode 16 decimal grammar](https://www.unicode.org/Public/16.0.0/ucd/extracted/DerivedNumericType.txt) stays fixed; tests no longer derive its accepted alphabet from the interpreter's Unicode database.
**Consequences:** T-0058, T-0059. Add Python 3.15 CI coverage, consumer-project Cursor install/upgrade guidance, global-skill help, and initialization recovery messages. Versions remain Python/plugins 0.7.5, npm 0.2.0, and crate 0.1.3. Publication remains a human step.
47 changes: 21 additions & 26 deletions HANDOFF.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,35 @@
<!-- statutor: plane=state | policy=overwrite_bounded (max 40 lines) | writer=executor | OVERWRITE, NEVER APPEND -->
# HANDOFF

last_verified: 2026-10-21 (UTC) by all PR CI, 15 focused checks, independent editorial review, public GitHub rendering/file hashes, and desktop/narrow layout measurements
last_worker: codex
last_verified: 2026-10-27 by `/opt/homebrew/bin/python3 -m pytest -q` (863 passed, 5 skipped)
last_worker: grok
last_machine: unknown
handoff_id: b41b8ad341034c5c85c3756a1bb00974
supersedes: 57e014efb00e443187d60ce57339a5a0
handoff_id: none
supersedes: adc8ff0ea687dddc32a72682ca45db44

## Goal
Completed the README redesign approved by the human (T-0055).
Publish GitHub tag v0.7.5 and install that release locally for live dogfood.

## Last verified state
- 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.
- PR #3 merged as d0a3bd2; public README, guides, logo, badges, and navigation verified.
- Python and plugins are 0.7.5. npm stays 0.2.0. The crate stays 0.1.3.
- Cursor is a first-class adapter. Governed MultiEdit and NotebookEdit stay
denied. Case variants match only the same directory entry. Invalid UTF-8
is a denial. apply_patch state IDs must advance. Append-only writes use
the line-subsequence test.
- Pytest on 2026-10-27: 863 passed, 5 skipped. The release gate and the host
probe still have to pass on this commit before the tag.

## Next action
No documentation work remains. Select the next milestone with the human.
Run the v0.7.5 release gate and the host probe. Tag and publish only after
both exit 0. Then install the published package with pipx.

## Gotchas
- 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.
- Hooks fail open on a validate exception. Staged mode fails closed.
- Use Homebrew Python 3.15. The system python3 is 3.9.6.
- Tag v0.7.5 starts publish.yml and uploads to PyPI. Do not move the tag.
- Host pins stay Claude 2.1.296, Codex 0.162.1, and OpenCode 2.1.1.

## Do not touch
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.
Embedded templates and init profiles; plans/archive/; the DECISIONS.md
header; root pre-commit metadata; ROADMAP.md. npm and crates.io stay pending.
Keep untracked .agents/, _local/, assets/, notes/, and plans/v0.4-dogfood.pdf.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ the CLI and initializing a ledger do not register agent hooks.
| 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) |
| Cursor | File edits, shell, and MCP when mapped | [Guide](https://github.com/hoohugokim/statutor/blob/main/adapters/cursor/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
Expand All @@ -76,7 +77,7 @@ installed, add this entry to your project's `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/hoohugokim/statutor
rev: v0.7.4
rev: v0.7.5
hooks: [{id: statutor}]
```

Expand Down
6 changes: 3 additions & 3 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
# ROADMAP

## Current milestone <!-- agent-visible -->
v0.7.4 hardening is released: Python/plugins 0.7.4, npm 0.2.0, and crate 0.1.2.
T-0049 through T-0054 are complete with independent review and registry proof.
The next milestone is undecided. Release runbook: `docs/releasing.md`.
v0.7.5 candidate: Cursor adapter plus 0.7.4 audit fixes (D-0030).
Python/plugins 0.7.5, npm still 0.2.0, crate 0.1.3. Publication remains a
human step. Release runbook: `docs/releasing.md`.

## Next milestone (human context, agents ignore)
Undecided. Candidates: live-binary E2E automation, host role-signal watch
Expand Down
4 changes: 4 additions & 0 deletions TASKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,7 @@
- [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)
- [x] T-0055 Reorganize the README around a concrete example, quickstart, and agent setup — DONE 2026-10-22: [PR #3](https://github.com/hoohugokim/statutor/pull/3) merged; README reduced from 245 to 144 lines with compact branding/navigation and four linked reference guides; Antigravity setup corrected; independent editorial review, 15 focused checks, and all PR CI pass; published images/navigation and GitHub file hashes verified
- [x] T-0056 Close 0.7.4 audit holes in kernel, Stop, worker, and Rust receipt optional-key parity (D-0030) — DONE 2026-10-22: relative TargetFile, truncated apply_patch, malformed HEAD policy, MultiEdit/NotebookEdit, run_terminal_cmd matcher, Stop/worker basename, Rust s61; pytest 785 passed / 5 skipped
- [x] T-0057 Add first-class Cursor adapter, kernel mapping, worker harness id, dogfood hooks, and 0.7.5/0.1.3 claim revision (D-0030) — DONE 2026-10-22: adapters/cursor/, .cursor/hooks.json, harness `cursor`, Python/plugins 0.7.5, crate 0.1.3; npm stays 0.2.0; publication remains a human step
- [x] T-0058 Address the flow audit (D-0031): preserve explicit CLI roots, report completed-session retries accurately without changing schema 1, validate check input, fix Cursor Stop/setup, improve help and fresh-setup guidance, and pin Unicode conformance independently of the interpreter — DONE 2026-10-23: worker 86, kernel/Cursor/Stop 340, setup diagnostics 72, and Unicode parity 3 focused tests pass; independent CLI and old-reader compatibility probes pass
- [x] T-0059 Verify the revised 0.7.5 candidate with regression probes, Python 3.15 coverage, the complete artifact gate, and independent review — DONE 2026-10-23: 853 tests with zero skips, seven Rust tests, real npm/crate audits, sdist/wheel builds and installed-wheel smoke pass at 81f9d3f; Standards/Spec pass after restoring absolute Antigravity target scoping; original candidate, shared index, and frozen history preserved
2 changes: 1 addition & 1 deletion adapters/antigravity/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "statutor",
"displayName": "Statutor Ledger",
"version": "0.7.4",
"version": "0.7.5",
"description": "Typed project-ledger discipline for agentic repos: constitution, state, log, and plan planes enforced by hooks and the git floor for Google Antigravity.",
"suggestedPrompts": [
"Initialize a Statutor ledger in this repository",
Expand Down
72 changes: 72 additions & 0 deletions adapters/cursor/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# statutor × Cursor

Cursor hooks use a version-1 `hooks.json` file and JSON over stdin/stdout.
`statutor hook` auto-detects `hook_event_name` and returns Cursor
`permission` JSON. Claude nested `hookSpecificOutput` still works for
`preToolUse` because Cursor accepts that shape too.

The kernel first resolves the nearest `.statutor.yaml` marker. Permission
events outside an opted-in ledger return `allow` without policy checks or
messages. Inside a ledger, policy comes from HEAD.
Requires Statutor **0.7.5 or newer** on `PATH`. Check `statutor version` before
enabling the hooks; earlier versions do not support Cursor hooks.

## Install once

Install or upgrade the CLI with `pipx install 'statutor>=0.7.5'` or
`pipx upgrade statutor`.

From your ledger repository, copy [hooks.json](hooks.json) from a clone of
the Statutor repository. Replace the absolute source path below with your own:

```sh
mkdir -p .cursor
cp /absolute/path/to/statutor/adapters/cursor/hooks.json .cursor/hooks.json
```

If `.cursor/hooks.json` already exists, merge the four events instead of
replacing it. Project hooks run from the repository root. This Statutor
repository already dogfoods `.cursor/hooks.json` against
`core/statutor_core.py`, so this checkout works without a global CLI.

Do not set `failClosed`. Hook crashes and missing CLI must fail open.
Invalid JSON on exit 0 would block Cursor permission events, so the kernel
always emits a permission object on a detected Cursor event.

The Stop hook reports ledger drift through Cursor's native
[`followup_message`](https://cursor.com/docs/hooks#stop). It requests at most
one follow-up per completion chain; a repeated Stop, an aborted or failed
run, and a clean ledger stay quiet.

## What the kernel treats as a mutation

| Cursor event | Canonical | Body |
|---|---|---|
| `preToolUse` `Write` | `write` | `path` / `contents` |
| `preToolUse` `StrReplace` | `edit` | `path`, `old_string`, `new_string` |
| `preToolUse` `Shell` | `bash` | `command` |
| `preToolUse` `Delete` | deny if governed | `path` |
| `preToolUse` `MultiEdit` / `NotebookEdit` | deny-unproved if governed | `path` / `file_path` |
| `beforeShellExecution` | `bash` | top-level `command` |
| `beforeMCPExecution` | mapped tool, else bash if `command` | `tool_input` JSON string |

`workspace_roots[0]` is the ledger search root when `cwd` is absent.
When `cwd` is absent, an empty workspace list is allowed without policy
checks. Stop stays quiet without a ledger workspace.

## Worker provenance

Stable harness id is `cursor`. Automatic hooks prove an attempt only.

```bash
statutor worker begin --harness cursor
statutor worker complete --session <id>
```

`--event mutation` under `cursor` is denied.

## Gaps the git floor still covers

- MCP tools whose payload cannot be mapped to write/edit/bash.
- Tab completions (`afterTabFileEdit`) are post-hoc; use `statutor staged`.
- Local Git hooks can be skipped with `--no-verify`.
30 changes: 30 additions & 0 deletions adapters/cursor/hooks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "statutor hook",
"matcher": "Write|StrReplace|Shell|Delete|MultiEdit|NotebookEdit|ApplyPatch",
"timeout": 30
}
],
"beforeShellExecution": [
{
"command": "statutor hook",
"timeout": 30
}
],
"beforeMCPExecution": [
{
"command": "statutor hook",
"timeout": 30
}
],
"stop": [
{
"command": "statutor hook --stop",
"timeout": 30
}
]
}
}
2 changes: 1 addition & 1 deletion adapters/git/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ at the statutor repo root):
# .pre-commit-config.yaml in your project
repos:
- repo: https://github.com/hoohugokim/statutor
rev: v0.7.4
rev: v0.7.5
hooks: [ { id: statutor } ]

Fallback: copy ./pre-commit into .git/hooks/. When the `statutor` CLI is
Expand Down
4 changes: 2 additions & 2 deletions adapters/grok/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Or, with no plugin, one user hook file `~/.grok/hooks/statutor.json`:
"hooks": {
"PreToolUse": [
{
"matcher": "^(Write|Edit|Bash|apply_patch|write|search_replace|hashline_edit|run_terminal_command|StrReplace|Shell)$",
"matcher": "^(Write|Edit|Bash|apply_patch|write|search_replace|hashline_edit|run_terminal_command|run_terminal_cmd|StrReplace|Shell|MultiEdit|NotebookEdit|Delete)$",
"hooks": [
{ "type": "command", "command": "statutor hook", "timeout": 30 }
]
Expand All @@ -51,7 +51,7 @@ that same layer, not beside it):

```toml
[[hooks.PreToolUse]]
matcher = "^(Write|Edit|Bash|apply_patch|write|search_replace|hashline_edit|run_terminal_command|StrReplace|Shell)$"
matcher = "^(Write|Edit|Bash|apply_patch|write|search_replace|hashline_edit|run_terminal_command|run_terminal_cmd|StrReplace|Shell|MultiEdit|NotebookEdit|Delete)$"
hooks = [
{ type = "command", command = "statutor hook", timeout = 30 },
]
Expand Down
2 changes: 1 addition & 1 deletion adapters/opencode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
the first release with object entrypoints). Both register the same guard on
tool execution and shell out to the Python kernel CLI.

1. `pipx install 'statutor>=0.7.4'` — the adapter shells out to the kernel; without the
1. `pipx install 'statutor>=0.7.5'` — the adapter shells out to the kernel; without the
CLI on `PATH` the plugin is a no-op. From a source checkout, the developer
equivalent is `python -m pip install -e .` at the repository root.
The adapter calls `statutor check --if-ledger`: it stays silent unless the
Expand Down
Loading
Loading