stepgate 0.1.0__tar.gz

stepgate-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.stepgate/.lock

stepgate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo Costta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stepgate-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: stepgate
+Version: 0.1.0
+Summary: A step-gated micro-change protocol CLI for coding agents: propose, approve, execute, verify — one small step at a time.
+Project-URL: Homepage, https://github.com/LeoCostta/stepgate
+Project-URL: Repository, https://github.com/LeoCostta/stepgate
+Project-URL: Issues, https://github.com/LeoCostta/stepgate/issues
+Author: Leo Costta
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,codex,coding-agents,guardrails,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: filelock>=3.12
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stepgate
+
+[![PyPI version](https://img.shields.io/pypi/v/stepgate)](https://pypi.org/project/stepgate/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/stepgate/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**A step-gated micro-change protocol for coding agents.**
+
+Coding agents (Claude Code, Codex, …) working on large or loosely-scoped tasks
+tend to mix contexts, silently expand scope, touch files unrelated to the
+original request, or declare success without real evidence. `stepgate` makes
+the correct workflow — investigate, propose, wait for approval, execute only
+what was approved, verify, suggest the next step — **the single natural path
+of action**, so that deviating from it is visible and recorded, never silent.
+
+`stepgate` is *not* an enforcement tool. It never blocks your code, your
+editor, your commits, or git. You can always edit anything, commit anything,
+and cancel any agent session at any time. What it gives you is structure and
+an honest, append-only trail of what was proposed, approved, executed, and
+verified — across every agent working on the repo, even concurrently.
+
+## Install
+
+```bash
+pipx install stepgate   # recommended: one global install per machine
+# or: pip install stepgate
+```
+
+Then, at the root of any project:
+
+```bash
+stepgate init
+```
+
+This creates `.stepgate/` (state + append-only history) and injects an
+instruction block into `AGENTS.md`/`CLAUDE.md` telling agents to use the
+protocol. It is idempotent and never overwrites anything you wrote in those
+files — only the text between its own markers is ever touched. If your
+project already has a domain guardrails document, point to it with
+`--guardrails GUARDRAILS.md` and the generated block will reference it.
+
+## The protocol
+
+Every micro-change is a proposal moving through a state machine, validated by
+the CLI itself:
+
+```
+PENDING ──approve──► APPROVED ──exec-log──► EXECUTED ──verify──► VERIFIED ──close──► CLOSED
+   │
+   └─reject──► REJECTED          (any non-terminal state) ──abandon──► ABANDONED
+```
+
+A proposal covers six points, each written as natural flowing prose (not a
+telegraphic form): **what** will change now, **why** this step comes first,
+**where** (files/contracts/flows touched), **how** it will be implemented,
+the **expected result**, and the **verification** that will demonstrate it.
+
+Key rule: *a micro-change reduces the scope of execution, never the depth of
+investigation* — the agent still investigates everything it needs to
+understand before proposing, even if it will only implement a small piece.
+
+## A real cycle
+
+You ask your agent to fix a race condition. It investigates, then proposes:
+
+```bash
+stepgate propose --agent claude --file plan.json
+```
+
+You read it rendered as prose, and approve with a tweak:
+
+```bash
+stepgate show
+stepgate approve --adjust --note "rename the function to apply_sanity_loss_atomic"
+```
+
+The agent implements **only** what was approved, logs it (a `git diff --stat`
+is captured automatically as objective evidence), and verifies:
+
+```bash
+stepgate exec-log --summary "atomic decrement migration + typing" --files "migrations/013.sql,types.ts"
+stepgate verify --evidence "type-check ok, simulated concurrency test passed"
+```
+
+You close the cycle; the agent suggests — but does not start — the next step:
+
+```bash
+stepgate close
+stepgate next --suggest "wire SalaJogo.tsx to the new function via supabase.rpc(...)"
+```
+
+The suggestion stays visible in `stepgate status` until a new proposal is
+opened. The full trail lives in `stepgate history` — chronological, across
+all sessions and agents, append-only.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `stepgate init` | Create `.stepgate/`, inject the agent instruction block |
+| `stepgate propose --agent X --file plan.json` | Register a micro-change plan (PENDING) |
+| `stepgate show` | Render the active proposal as readable prose |
+| `stepgate approve [--adjust --scope ... --note ...]` | Approve (optionally with reduced scope) |
+| `stepgate reject --note "..."` | Reject a pending proposal |
+| `stepgate exec-log --summary "..." --files "..."` | Record execution (+ automatic `git diff --stat`) |
+| `stepgate verify --evidence "..."` | Record verification evidence |
+| `stepgate close` | Close a verified micro-change |
+| `stepgate abandon --reason "..."` | Cleanly abandon from any non-terminal state |
+| `stepgate next --suggest "..."` | Record a next-step suggestion (opens nothing) |
+| `stepgate status` | Current session + aggregated project view |
+| `stepgate history [--session X] [--since DATE]` | Append-only, cross-session log |
+| `stepgate doctor` | Report corrupted/invalid state files (fixes nothing) |
+
+Multiple agents can work concurrently: each session has its own state file
+(`.stepgate/sessions/claude-2026-07-09-1.json` — human-readable names, not
+hashes), writes are file-locked, and `propose`/`status` warn — informationally,
+never blockingly — when two active proposals touch the same files.
+
+## Design principles
+
+- **Never block.** No git hooks, no file locks on your code, no commit gates.
+  The file lock in `.stepgate/` protects only stepgate's own state files.
+- **Never act silently.** No auto-repair, no auto-expiry of stale sessions,
+  no rewriting of history. `doctor` diagnoses; a human decides.
+- **Non-interactive by design.** No prompts or confirmations, so it behaves
+  identically in a terminal, a desktop app, or an IDE side-panel extension.
+- **Structure when you opt in.** Editing code without a proposal is a
+  legitimate flow, not an error. The state machine gives shape to the agent
+  workflow — it is never a requirement for the code to change.
+
+## License
+
+[MIT](LICENSE) © Leo Costta

stepgate-0.1.0/README.md

@@ -0,0 +1,133 @@
+# stepgate
+
+[![PyPI version](https://img.shields.io/pypi/v/stepgate)](https://pypi.org/project/stepgate/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/stepgate/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**A step-gated micro-change protocol for coding agents.**
+
+Coding agents (Claude Code, Codex, …) working on large or loosely-scoped tasks
+tend to mix contexts, silently expand scope, touch files unrelated to the
+original request, or declare success without real evidence. `stepgate` makes
+the correct workflow — investigate, propose, wait for approval, execute only
+what was approved, verify, suggest the next step — **the single natural path
+of action**, so that deviating from it is visible and recorded, never silent.
+
+`stepgate` is *not* an enforcement tool. It never blocks your code, your
+editor, your commits, or git. You can always edit anything, commit anything,
+and cancel any agent session at any time. What it gives you is structure and
+an honest, append-only trail of what was proposed, approved, executed, and
+verified — across every agent working on the repo, even concurrently.
+
+## Install
+
+```bash
+pipx install stepgate   # recommended: one global install per machine
+# or: pip install stepgate
+```
+
+Then, at the root of any project:
+
+```bash
+stepgate init
+```
+
+This creates `.stepgate/` (state + append-only history) and injects an
+instruction block into `AGENTS.md`/`CLAUDE.md` telling agents to use the
+protocol. It is idempotent and never overwrites anything you wrote in those
+files — only the text between its own markers is ever touched. If your
+project already has a domain guardrails document, point to it with
+`--guardrails GUARDRAILS.md` and the generated block will reference it.
+
+## The protocol
+
+Every micro-change is a proposal moving through a state machine, validated by
+the CLI itself:
+
+```
+PENDING ──approve──► APPROVED ──exec-log──► EXECUTED ──verify──► VERIFIED ──close──► CLOSED
+   │
+   └─reject──► REJECTED          (any non-terminal state) ──abandon──► ABANDONED
+```
+
+A proposal covers six points, each written as natural flowing prose (not a
+telegraphic form): **what** will change now, **why** this step comes first,
+**where** (files/contracts/flows touched), **how** it will be implemented,
+the **expected result**, and the **verification** that will demonstrate it.
+
+Key rule: *a micro-change reduces the scope of execution, never the depth of
+investigation* — the agent still investigates everything it needs to
+understand before proposing, even if it will only implement a small piece.
+
+## A real cycle
+
+You ask your agent to fix a race condition. It investigates, then proposes:
+
+```bash
+stepgate propose --agent claude --file plan.json
+```
+
+You read it rendered as prose, and approve with a tweak:
+
+```bash
+stepgate show
+stepgate approve --adjust --note "rename the function to apply_sanity_loss_atomic"
+```
+
+The agent implements **only** what was approved, logs it (a `git diff --stat`
+is captured automatically as objective evidence), and verifies:
+
+```bash
+stepgate exec-log --summary "atomic decrement migration + typing" --files "migrations/013.sql,types.ts"
+stepgate verify --evidence "type-check ok, simulated concurrency test passed"
+```
+
+You close the cycle; the agent suggests — but does not start — the next step:
+
+```bash
+stepgate close
+stepgate next --suggest "wire SalaJogo.tsx to the new function via supabase.rpc(...)"
+```
+
+The suggestion stays visible in `stepgate status` until a new proposal is
+opened. The full trail lives in `stepgate history` — chronological, across
+all sessions and agents, append-only.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `stepgate init` | Create `.stepgate/`, inject the agent instruction block |
+| `stepgate propose --agent X --file plan.json` | Register a micro-change plan (PENDING) |
+| `stepgate show` | Render the active proposal as readable prose |
+| `stepgate approve [--adjust --scope ... --note ...]` | Approve (optionally with reduced scope) |
+| `stepgate reject --note "..."` | Reject a pending proposal |
+| `stepgate exec-log --summary "..." --files "..."` | Record execution (+ automatic `git diff --stat`) |
+| `stepgate verify --evidence "..."` | Record verification evidence |
+| `stepgate close` | Close a verified micro-change |
+| `stepgate abandon --reason "..."` | Cleanly abandon from any non-terminal state |
+| `stepgate next --suggest "..."` | Record a next-step suggestion (opens nothing) |
+| `stepgate status` | Current session + aggregated project view |
+| `stepgate history [--session X] [--since DATE]` | Append-only, cross-session log |
+| `stepgate doctor` | Report corrupted/invalid state files (fixes nothing) |
+
+Multiple agents can work concurrently: each session has its own state file
+(`.stepgate/sessions/claude-2026-07-09-1.json` — human-readable names, not
+hashes), writes are file-locked, and `propose`/`status` warn — informationally,
+never blockingly — when two active proposals touch the same files.
+
+## Design principles
+
+- **Never block.** No git hooks, no file locks on your code, no commit gates.
+  The file lock in `.stepgate/` protects only stepgate's own state files.
+- **Never act silently.** No auto-repair, no auto-expiry of stale sessions,
+  no rewriting of history. `doctor` diagnoses; a human decides.
+- **Non-interactive by design.** No prompts or confirmations, so it behaves
+  identically in a terminal, a desktop app, or an IDE side-panel extension.
+- **Structure when you opt in.** Editing code without a proposal is a
+  legitimate flow, not an error. The state machine gives shape to the agent
+  workflow — it is never a requirement for the code to change.
+
+## License
+
+[MIT](LICENSE) © Leo Costta

stepgate-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stepgate"
+dynamic = ["version"]
+description = "A step-gated micro-change protocol CLI for coding agents: propose, approve, execute, verify — one small step at a time."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Leo Costta" }]
+keywords = ["cli", "coding-agents", "workflow", "claude-code", "codex", "guardrails"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "rich>=13.0",
+    "filelock>=3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/LeoCostta/stepgate"
+Repository = "https://github.com/LeoCostta/stepgate"
+Issues = "https://github.com/LeoCostta/stepgate/issues"
+
+[project.scripts]
+stepgate = "stepgate.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.version]
+path = "src/stepgate/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = [".stepgate", "AGENTS.md", "CLAUDE.md", ".gitignore"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

stepgate-0.1.0/src/stepgate/__init__.py

@@ -0,0 +1,3 @@
+"""stepgate: a step-gated micro-change protocol CLI for coding agents."""
+
+__version__ = "0.1.0"

stepgate-0.1.0/src/stepgate/__main__.py

@@ -0,0 +1,4 @@
+from stepgate.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stepgate-0.1.0/src/stepgate/cli.py

@@ -0,0 +1,126 @@
+"""stepgate command-line interface.
+
+All commands are non-interactive by design (no prompts, no confirmations) so
+they behave identically in a terminal, a desktop app, or an IDE side-panel
+extension. User-facing errors are printed as clear messages, never as raw
+Python tracebacks.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from stepgate import __version__
+from stepgate.model import StepgateError
+
+
+def _add_session_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--agent", help="calling agent name (e.g. claude, codex)")
+    parser.add_argument("--session", help="explicit session name to target")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="stepgate",
+        description=(
+            "Step-gated micro-change protocol for coding agents: propose, "
+            "approve, execute, verify - one small step at a time. stepgate "
+            "structures the flow; it never blocks your code, your commits, "
+            "or your git."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"stepgate {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="create .stepgate/ and inject the agent instruction block")
+    p.add_argument("--guardrails", help="path to an existing domain guardrails doc to reference")
+
+    p = sub.add_parser("propose", help="register a micro-change plan (state: PENDING)")
+    p.add_argument("--file", required=True, help="JSON file with the six plan fields")
+    p.add_argument("--new-session", action="store_true", help="start a fresh session")
+    _add_session_flags(p)
+
+    p = sub.add_parser("show", help="show the active proposal rendered as prose")
+    _add_session_flags(p)
+
+    p = sub.add_parser("approve", help="PENDING -> APPROVED")
+    p.add_argument("--adjust", action="store_true", help="approve with an adjusted/reduced scope")
+    p.add_argument("--scope", help="comma-separated adjusted scope (files/areas)")
+    p.add_argument("--note", help="note describing the adjustment")
+    _add_session_flags(p)
+
+    p = sub.add_parser("reject", help="PENDING -> REJECTED")
+    p.add_argument("--note", required=True, help="reason for rejection")
+    _add_session_flags(p)
+
+    p = sub.add_parser("exec-log", help="APPROVED -> EXECUTED (consolidated summary)")
+    p.add_argument("--summary", required=True, help="what was done, consolidated")
+    p.add_argument("--files", help="comma-separated files that were touched")
+    _add_session_flags(p)
+
+    p = sub.add_parser("verify", help="EXECUTED -> VERIFIED")
+    p.add_argument("--evidence", required=True, help="tests/runs/evidence demonstrating the result")
+    _add_session_flags(p)
+
+    p = sub.add_parser("close", help="VERIFIED -> CLOSED")
+    _add_session_flags(p)
+
+    p = sub.add_parser("abandon", help="any non-terminal state -> ABANDONED")
+    p.add_argument("--reason", required=True, help="why the proposal is being abandoned")
+    _add_session_flags(p)
+
+    p = sub.add_parser("next", help="record a next-step suggestion (does not open a proposal)")
+    p.add_argument("--suggest", required=True, help="the suggested next step")
+    _add_session_flags(p)
+
+    p = sub.add_parser("status", help="current session state + aggregated project view")
+    _add_session_flags(p)
+
+    p = sub.add_parser("history", help="chronological, cross-session log")
+    p.add_argument("--session", help="filter by session name")
+    p.add_argument("--since", help="filter by ISO date (e.g. 2026-07-09)")
+
+    sub.add_parser("doctor", help="scan .stepgate/ and report problems (never fixes anything)")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Consoles with limited encodings (e.g. cp1252 on legacy Windows) must
+    # degrade output gracefully, never crash with a UnicodeEncodeError.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(errors="replace")
+            except (OSError, ValueError):
+                pass
+
+    args = build_parser().parse_args(argv)
+
+    from stepgate.commands import doctor, init_cmd, lifecycle, views
+
+    handlers = {
+        "init": init_cmd.cmd_init,
+        "propose": lifecycle.cmd_propose,
+        "show": views.cmd_show,
+        "approve": lifecycle.cmd_approve,
+        "reject": lifecycle.cmd_reject,
+        "exec-log": lifecycle.cmd_exec_log,
+        "verify": lifecycle.cmd_verify,
+        "close": lifecycle.cmd_close,
+        "abandon": lifecycle.cmd_abandon,
+        "next": lifecycle.cmd_next,
+        "status": views.cmd_status,
+        "history": views.cmd_history,
+        "doctor": doctor.cmd_doctor,
+    }
+    try:
+        return handlers[args.command](args)
+    except StepgateError as exc:
+        print(f"stepgate: error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stepgate-0.1.0/src/stepgate/commands/doctor.py

@@ -0,0 +1,62 @@
+"""stepgate doctor: scan .stepgate/ and report problems without fixing
+anything. A diagnostic tool, never a repair tool — and never a gate: even
+when it finds problems, nothing else is blocked."""
+
+from __future__ import annotations
+
+import json
+
+from stepgate import render
+from stepgate.model import Session
+from stepgate.store import Store
+
+
+def cmd_doctor(args) -> int:
+    store = Store.find()
+    problems: list[str] = []
+
+    if store.config_path.exists():
+        try:
+            config = json.loads(store.config_path.read_text(encoding="utf-8"))
+            for key in ("project_name", "agents", "verify_command"):
+                if key not in config:
+                    problems.append(f"{store.config_path}: missing expected key '{key}'")
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            problems.append(f"{store.config_path}: not valid JSON ({exc})")
+    else:
+        problems.append(f"{store.config_path}: missing (run 'stepgate init' to recreate it)")
+
+    if store.sessions_dir.is_dir():
+        for path in sorted(store.sessions_dir.glob("*.json")):
+            try:
+                Session.from_dict(json.loads(path.read_text(encoding="utf-8")))
+            except (json.JSONDecodeError, UnicodeDecodeError, KeyError, TypeError) as exc:
+                problems.append(f"{path}: corrupted or invalid ({exc.__class__.__name__}: {exc})")
+    else:
+        problems.append(f"{store.sessions_dir}: missing directory")
+
+    if store.history_path.exists():
+        for i, line in enumerate(
+            store.history_path.read_text(encoding="utf-8").splitlines(), start=1
+        ):
+            if not line.strip():
+                continue
+            try:
+                json.loads(line)
+            except json.JSONDecodeError:
+                problems.append(f"{store.history_path}: invalid JSON at line {i}")
+    else:
+        problems.append(f"{store.history_path}: missing file")
+
+    if not problems:
+        render.info(f"[green]doctor: no problems found in {store.dir}[/]")
+        return 0
+    render.info(f"[yellow]doctor: found {len(problems)} problem(s) in {store.dir}:[/]")
+    for problem in problems:
+        render.info(f"  - {problem}")
+    render.info(
+        "[dim]stepgate never repairs state automatically - please inspect the "
+        "files above manually. Other sessions and normal project work are "
+        "not blocked by this.[/]"
+    )
+    return 1