Metadata-Version: 2.4
Name: stepgate
Version: 0.2.1
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://badge.fury.io/py/stepgate.svg)](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.
When an agent proposes a micro-change, it must also present those six points
back to the user in flowing prose before execution, not only inside the CLI
panel.

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

The agent brings that proposal back to you in prose, you can inspect the same
content in the CLI, and then you 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. Running `stepgate next` with no `--suggest` only shows the currently
recorded suggestion; it does not create or change one. 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 "..."]` | With `--suggest`, record a next-step suggestion; without it, show the current one |

The four flow verbs also accept Portuguese aliases - English stays the default:
`aprovar` = `approve`, `rejeitar` = `reject`, `fechar` = `close`,
`proximo` = `next`.
| `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) (c) Leo Costta
