statutor 0.5.0__tar.gz → 0.6.0__tar.gz

{statutor-0.5.0/core/statutor.egg-info → statutor-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statutor
-Version: 0.5.0
+Version: 0.6.0
 Summary: Typed project-ledger framework for agentic repos: four planes, single-writer files, enforced mutation policies.
 Author: Hoo
 License-Expression: MIT
@@ -46,6 +46,14 @@ message data is not scanned as shell code; its opener and all actual command
 lines remain guarded. No hand-maintained CHANGELOG.md: git log + conventional
 commits.
 
+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;
@@ -99,12 +107,16 @@ 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
-baselines); `worker compare <ref>` explains sibling handoffs read-only.
+baselines); `worker compare <ref>` 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
@@ -114,9 +126,26 @@ baselines); `worker compare <ref>` explains sibling handoffs read-only.
     # .pre-commit-config.yaml
     repos:
       - repo: https://github.com/hoohugokim/statutor
-        rev: v0.5.0
+        rev: v0.6.0
         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 |
+|---|---|---|
+| `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

{statutor-0.5.0 → statutor-0.6.0}/README.md

@@ -21,6 +21,14 @@ message data is not scanned as shell code; its opener and all actual command
 lines remain guarded. No hand-maintained CHANGELOG.md: git log + conventional
 commits.
 
+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;
@@ -74,12 +82,16 @@ 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
-baselines); `worker compare <ref>` explains sibling handoffs read-only.
+baselines); `worker compare <ref>` 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
@@ -89,9 +101,26 @@ baselines); `worker compare <ref>` explains sibling handoffs read-only.
     # .pre-commit-config.yaml
     repos:
       - repo: https://github.com/hoohugokim/statutor
-        rev: v0.5.0
+        rev: v0.6.0
         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 |
+|---|---|---|
+| `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

{statutor-0.5.0 → statutor-0.6.0/core/statutor.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statutor
-Version: 0.5.0
+Version: 0.6.0
 Summary: Typed project-ledger framework for agentic repos: four planes, single-writer files, enforced mutation policies.
 Author: Hoo
 License-Expression: MIT
@@ -46,6 +46,14 @@ message data is not scanned as shell code; its opener and all actual command
 lines remain guarded. No hand-maintained CHANGELOG.md: git log + conventional
 commits.
 
+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;
@@ -99,12 +107,16 @@ 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
-baselines); `worker compare <ref>` explains sibling handoffs read-only.
+baselines); `worker compare <ref>` 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
@@ -114,9 +126,26 @@ baselines); `worker compare <ref>` explains sibling handoffs read-only.
     # .pre-commit-config.yaml
     repos:
       - repo: https://github.com/hoohugokim/statutor
-        rev: v0.5.0
+        rev: v0.6.0
         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 |
+|---|---|---|
+| `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

{statutor-0.5.0 → statutor-0.6.0}/core/statutor_core.py

@@ -25,7 +25,10 @@ Entry modes (all share the same validate() core):
                           ledger, or stay silent when none exists.
   statutor staged [CWD]   Git floor: validate staged changes (pre-commit).
                           exit 1 on violations.
-  statutor init [DIR]     Scaffold governed files from embedded templates.
+  statutor init [DIR] [--type NAME]
+                          Scaffold governed files from embedded templates.
+                          Profiles (D-0024) add conventional directories only:
+                          --type > STATUTOR_INIT_TYPE > marker detection > min.
   statutor global ...     Opt-in global instruction and skill projection manager.
   statutor machine ...    Random machine identity (mode 0600, rotation).
   statutor worker ...     Machine-local worker provenance (begin/record/show/active/complete/compare).
@@ -787,6 +790,13 @@ def _automatic_reason(tool: str, payload: dict, cwd: str) -> str | None:
     return None
 
 def run_hook() -> int:
+    if sys.stdin.isatty():
+        # A TTY means a human ran the hook with no piped event (harnesses
+        # always pipe JSON). Fail fast with usage instead of blocking on
+        # stdin forever; fail-open applies to hook *events*, not misuse.
+        print("statutor hook expects piped hook JSON on stdin; "
+              "run `statutor --help` for modes.", file=sys.stderr)
+        return 64
     try:
         event = json.load(sys.stdin)
         tool = event.get("tool_name", "")
@@ -1389,30 +1399,208 @@ governed:
 }
 
 
-def run_init(target: str) -> int:
-    os.makedirs(os.path.join(target, "plans", "archive"), exist_ok=True)
-    os.makedirs(os.path.join(target, "notes"), exist_ok=True)
-    for name, body in TEMPLATES.items():
-        path = os.path.join(target, name)
-        if os.path.exists(path):
-            print(f"skip  {name} (exists)")
+# Init profiles (D-0024): Statutor never mandates a project layout. A profile
+# adds empty *conventional* directories on top of the governed files — never
+# policy, constitution content, or ecosystem files — and every create is
+# additive and idempotent (present paths are skipped, never overwritten,
+# adopted, or followed). Definitions live here beside TEMPLATES for the same
+# reason the templates do (D-0003): a profiles/ directory would fork the
+# source of truth.
+#
+# Precedence, highest first: `--type NAME` > `STATUTOR_INIT_TYPE` > the first
+# marker hit in INIT_DETECT_ORDER > `min`. A marker written `name/` must be a
+# directory; any other marker must be a regular file. The `min` fallback prints
+# and creates exactly what pre-v0.6 `init` did. `none` adds no directory at
+# all, not even the ledger skeleton.
+
+INIT_SKELETON_DIRS: tuple[str, ...] = ("plans/archive", "notes")
+INIT_PROFILES: dict[str, dict[str, tuple[str, ...]]] = {
+    "none": {"dirs": (), "markers": ()},
+    "min": {"dirs": (), "markers": ()},
+    "python": {"dirs": ("tests",),
+               "markers": ("pyproject.toml", "setup.py", "setup.cfg")},
+    "rust": {"dirs": ("tests",), "markers": ("Cargo.toml",)},
+    "node": {"dirs": ("test",), "markers": ("package.json",)},
+    "docs": {"dirs": ("docs",), "markers": ("mkdocs.yml", "_quarto.yml", "docs/")},
+}
+INIT_DETECT_ORDER: tuple[str, ...] = ("python", "rust", "node", "docs")
+INIT_TYPE_ENV = "STATUTOR_INIT_TYPE"
+INIT_USAGE = (f"usage: statutor init [DIR] [--type {'|'.join(INIT_PROFILES)}]"
+              f"  (env: {INIT_TYPE_ENV}=NAME)")
+
+
+def _init_profile_name(raw: str, source: str) -> str:
+    name = raw.strip().lower()
+    if name not in INIT_PROFILES:
+        raise ValueError(
+            f"unknown init profile {raw!r} from {source}; "
+            f"choose one of {', '.join(INIT_PROFILES)}")
+    return name
+
+
+def _marker_present(target: str, marker: str) -> bool:
+    """`name/` markers need a directory, others a regular file (links followed)."""
+    path = os.path.join(target, marker.rstrip("/"))
+    return os.path.isdir(path) if marker.endswith("/") else os.path.isfile(path)
+
+
+def resolve_init_profile(
+    target: str, explicit: str | None = None, env: dict | None = None,
+) -> tuple[str, str]:
+    """Return `(profile, source)` for `target` without touching the disk.
+
+    `source` is `--type`, the environment variable name, `detected <marker>`,
+    or `fallback`. An empty environment value counts as unset (dotfiles often
+    export empty strings); an explicit empty `--type` is an error. `env` of
+    None consults nothing: only the CLI reads the process environment, so
+    in-process callers stay deterministic.
+    """
+    if explicit is not None:
+        return _init_profile_name(explicit, "--type"), "--type"
+    raw = (env or {}).get(INIT_TYPE_ENV, "")
+    if isinstance(raw, str) and raw.strip():
+        return _init_profile_name(raw, INIT_TYPE_ENV), INIT_TYPE_ENV
+    for name in INIT_DETECT_ORDER:
+        for marker in INIT_PROFILES[name]["markers"]:
+            if _marker_present(target, marker):
+                return name, f"detected {marker}"
+    return "min", "fallback"
+
+
+def _ensure_dir(root: str, rel: str) -> bool:
+    """Create `root/rel` one component at a time; True when the leaf was created.
+
+    Any present component that is a symlink or not a directory blocks the
+    whole path (returned as a skip): init never follows a link out of the
+    target and never adopts a file. A concurrent creator is a skip too.
+    Permission failures still propagate.
+    """
+    current = root
+    created = False
+    for part in rel.split("/"):
+        current = os.path.join(current, part)
+        if os.path.lexists(current):
+            if os.path.islink(current) or not os.path.isdir(current):
+                return False
+            created = False
             continue
-        with open(path, "w", encoding="utf-8") as fh:
-            fh.write(body)
-        print(f"write {name}")
-    claude_md = os.path.join(target, "CLAUDE.md")
-    if not os.path.exists(claude_md):
-        with open(claude_md, "w", encoding="utf-8") as fh:
-            fh.write("@AGENTS.md\n")
-        print("write CLAUDE.md (@AGENTS.md import)")
+        try:
+            os.mkdir(current)
+            created = True
+        except FileExistsError:
+            created = False
+    return created
+
+
+def _create_file(path: str, body: str) -> bool:
+    """Exclusively create `path`; False when any entry (even a dangling link) exists."""
+    try:
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+    except FileExistsError:
+        return False
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(body)
+    return True
+
+
+def _present_kind(path: str) -> str:
+    if os.path.isdir(path) and not os.path.islink(path):
+        return "exists"
+    return "present, left alone"
+
+
+def run_init(target: str, profile: str | None = None, env: dict | None = None) -> int:
+    try:
+        name, source = resolve_init_profile(target, profile, env)
+    except ValueError as exc:
+        print(f"statutor init: {exc}", file=sys.stderr)
+        print(INIT_USAGE, file=sys.stderr)
+        return 64
+    if source != "fallback":
+        print(f"profile {name} ({source})")
+    if os.path.lexists(target) and not os.path.isdir(target):
+        print(f"statutor init: target {target!r} exists and is not a directory",
+              file=sys.stderr)
+        return 1
+    try:
+        os.makedirs(target, exist_ok=True)
+        if name != "none":
+            for rel in INIT_SKELETON_DIRS:
+                _ensure_dir(target, rel)  # silent: pre-v0.6 behavior
+        for filename, body in TEMPLATES.items():
+            if _create_file(os.path.join(target, filename), body):
+                print(f"write {filename}")
+            else:
+                print(f"skip  {filename} (exists)")
+        if _create_file(os.path.join(target, "CLAUDE.md"), "@AGENTS.md\n"):
+            print("write CLAUDE.md (@AGENTS.md import)")
+        for rel in INIT_PROFILES[name]["dirs"]:
+            if _ensure_dir(target, rel):
+                print(f"mkdir {rel}/")
+            else:
+                print(f"skip  {rel}/ ({_present_kind(os.path.join(target, rel))})")
+    except OSError as exc:
+        print(f"statutor init: {exc}", file=sys.stderr)
+        return 1
     return 0
 
 
+def run_init_cli(argv: list[str], env: dict | None = None) -> int:
+    """Parse `statutor init [DIR] [--type NAME] [-- DIR]`; the CLI alone reads the env."""
+    target: str | None = None
+    profile: str | None = None
+    positional_only = False
+    i = 0
+
+    def usage_error(message: str) -> int:
+        print(f"statutor init: {message}", file=sys.stderr)
+        print(INIT_USAGE, file=sys.stderr)
+        return 64
+
+    while i < len(argv):
+        arg = argv[i]
+        if not positional_only:
+            if arg in ("-h", "--help"):
+                print(INIT_USAGE)
+                return 0
+            if arg == "--":
+                positional_only = True
+                i += 1
+                continue
+            if arg == "--type" or arg.startswith("--type="):
+                if profile is not None:
+                    return usage_error("--type given more than once")
+                if arg == "--type":
+                    if i + 1 >= len(argv):
+                        return usage_error("missing value for --type")
+                    profile = argv[i + 1]
+                    i += 2
+                else:
+                    profile = arg[len("--type="):]
+                    i += 1
+                continue
+            if arg.startswith("-"):
+                return usage_error(f"unexpected argument: {arg}")
+        if not arg:
+            return usage_error("DIR must not be empty")
+        if target is not None:
+            return usage_error(f"unexpected argument: {arg}")
+        target = arg
+        i += 1
+    environment = dict(os.environ) if env is None else env
+    return run_init(target if target is not None else os.getcwd(), profile, environment)
+
+
 # --------------------------------------------------------------------------
 
 def main() -> None:
     argv = sys.argv[1:]
-    mode = argv[0] if argv else "hook"
+    if not argv or argv[0] in ("--help", "-h"):
+        # Bare invocation must never fall through to hook mode (which blocks
+        # on stdin); print usage instead. --help exits clean, bare exits 64.
+        print(__doc__)
+        sys.exit(0 if argv else 64)
+    mode = argv[0]
     if mode in ("hook", "--claude-hook"):
         sys.exit(run_hook())
     if mode == "check":
@@ -1422,7 +1610,7 @@ def main() -> None:
     if mode == "trust" and len(argv) > 1 and argv[1] == "approve":
         sys.exit(run_trust_approve(argv[2:]))
     if mode == "init":
-        sys.exit(run_init(argv[1] if len(argv) > 1 else os.getcwd()))
+        sys.exit(run_init_cli(argv[1:]))
     if mode == "global":
         import statutor_global_cli
         sys.exit(statutor_global_cli.main(argv[1:]))

{statutor-0.5.0 → statutor-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "statutor"
-version = "0.5.0"
+version = "0.6.0"
 description = "Typed project-ledger framework for agentic repos: four planes, single-writer files, enforced mutation policies."
 readme = "README.md"
 license = "MIT"