context-guard-cli 2.1.0__py3-none-any.whl

context_guard_cli-2.1.0.dist-info/METADATA

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: context-guard-cli
+Version: 2.1.0
+Summary: The transactional memory layer for AI coding agents — your context survives crashes, compaction, and session loss
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp<2.0.0,>=1.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Context Guard
+
+[![CI](https://github.com/fdomerlo/context-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/fdomerlo/context-guard/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/context-guard-cli)](https://pypi.org/project/context-guard-cli/)
+
+**The transactional memory layer for AI coding agents — your context survives crashes, compaction, and session loss.**
+
+*[Leer en español](README.es.md)*
+
+*[Aqui un tutorial (también en español) para usuarios no técnicos y novatos](TUTORIAL.es.md)*
+
+---
+
+## The problem
+
+Long-running agent sessions degrade. Context drift, "lost in the middle,"
+completion hallucination (the agent believes it finished before it verified
+anything), and — the one that actually loses work — a crash or a compaction
+mid-task that leaves the repository half-edited with no way back.
+
+context-guard is not another agent framework and it does not write code. It
+is a small, deterministic state machine that sits between an agent and a
+project: a manifest on disk that survives the agent's process ending, a
+strict `PLAN → EXECUTE → VERIFY → ARCHIVE` pipeline the agent cannot skip
+phases in, and a transaction log that can be rolled back. If the session
+dies, the manifest is what the next session reads to pick up exactly where
+the last one left off — that persistence, not the pipeline shape, is the
+point.
+
+## Quickstart
+
+Five commands: plan a change, get a human to sign off on it, advance into
+execution, claim a task, and check where things stand.
+
+<!-- quickstart:start -->
+```bash
+# (1) start a change — this begins PLAN and scaffolds the artifacts
+cg new redis-cache
+
+# fill in the plan — an agent writes this, not you
+cat > .context-guard/changes/redis-cache/objective.md <<'EOF'
+# Objective: Add Redis caching
+Cache the top-N query results behind a 60s TTL.
+EOF
+cat > .context-guard/changes/redis-cache/tasks.md <<'EOF'
+- [ ] 1.1 Add the redis client dependency
+- [ ] 1.2 Wrap the query path with a cache lookup
+EOF
+
+# (2) a human reviews objective.md and tasks.md, then approves
+cg approve
+
+# (3) the recorded approval unlocks EXECUTE
+cg commit --next-phase EXECUTE
+
+# (4) claim the next task atomically — safe with several agents at once
+cg next-task
+
+# (5) one-shot rehydration after a crash, a compaction, or a new session
+cg status
+```
+<!-- quickstart:end -->
+
+Every line above runs as written against a fresh directory; nothing here is
+illustrative shorthand.
+
+## Install
+
+Two lines, once per machine:
+
+```bash
+pip install context-guard-cli
+cg setup
+```
+
+`cg setup` detects Claude Code, OpenCode and Antigravity, installs the slash
+commands, and puts `cg approve` behind each one's permission prompt — see
+[Adapters](#adapters-and-permission-configuration). It prints every file it
+touched, and running it again changes nothing.
+
+Per project there is no install step: `cg new` writes the phase documents
+into `.context-guard/phases/` the first time you start a change.
+
+**Optional — the MCP server**, for hosts with no shell (Claude Desktop is the
+case it exists for): `cg setup --with-mcp` registers it. Every adapter works
+completely without it; MCP is an alternative transport, not a requirement.
+
+**Contributing** ([development](#development) has the rest):
+
+```bash
+git clone https://github.com/fdomerlo/context-guard.git
+cd context-guard && uv venv && uv pip install -e ".[dev]"
+git config core.hooksPath .githooks   # activates the pre-commit gate below
+```
+
+## How it works
+
+```
+PLAN  →  EXECUTE  →  VERIFY  →  ARCHIVE
+```
+
+Each change (`.context-guard/changes/<name>/`) moves through this pipeline
+one phase at a time, enforced by code, not by convention:
+
+- **`begin`** refuses to start a phase that is not the manifest's
+  `lock_phase` — the DAG is checked before work starts, not only when it is
+  claimed done.
+- **`commit`** validates the phase's artifacts (`objective.md` + `tasks.md`
+  for PLAN, `review-report.md` + `verify-report.md` for VERIFY) contain no
+  leftover `[PENDING]` marker before advancing `lock_phase`.
+- **`begin` on a fresh PLAN** auto-scaffolds five markdown files —
+  `objective.md`, `snapshot.md`, `tasks.md`, `review-report.md`,
+  `verify-report.md` — each starting as `[PENDING]`, so the agent edits
+  templates instead of inventing a shape from scratch.
+- **`rollback`** restores the exact manifest snapshot taken when the phase
+  began.
+- **Session and write locks** are OS-level (`O_CREAT|O_EXCL`), with
+  liveness-checked stale detection, so two agents on the same change do not
+  silently race each other.
+- **Task claims** carry a lease (`claim-task` / `next-task` / `doctor
+  --fix`), so several agents can work one change concurrently without two of
+  them picking the same task.
+- **`--change <name>`** scopes every command to one change. Several changes
+  active and no `--change` given is an error naming them — never a silent
+  guess at "the first one."
+
+## Threat Model
+
+Read this before you rely on context-guard for anything you actually care
+about.
+
+The pipeline enforcement (`begin`/`commit` validating the DAG and the
+artifacts) is real code, not a system prompt suggestion — an agent using the
+`cg` tool cannot accidentally skip a phase or advance past `[PENDING]`
+artifacts. But that enforcement is **cooperative**: it only binds an agent
+that calls `cg` in the first place. An agent with a shell can write directly
+to `manifest.json`, or simply not use the tool at all, and nothing in the
+process stops it.
+
+The one command that is explicitly **human-only** is `cg approve`. It
+records the sign-off `commit --next-phase EXECUTE` requires. The name it
+records (`--by`, defaulting to the OS user) is **audit metadata, not
+authentication**: it says who to ask about this approval later, and an agent
+could pass any string it liked. The command itself is just as cooperative as
+the rest: an agent with a shell can
+run `cg approve` itself, and nothing in `cg` prevents that. The actual hard
+control does not live in `cg` at all — it is your harness's permission
+prompt on the `cg approve` command, configured per host in
+`docs/adapters/*/PERMISSIONS.md`. That prompt runs outside the agent's process,
+which is the only place a control that does not depend on the agent's
+cooperation can live. `approve` is deliberately not exposed as an MCP tool,
+for the same reason: an MCP tool is a channel the permission prompt does not
+see.
+
+The pre-commit hook is the one layer that runs entirely outside the agent's
+process — git invokes it regardless of what the agent chose to do — but it
+is a perimeter check on file count, not a guarantee about correctness, and it
+ships with an audited bypass (`CONTEXT_GUARD_BYPASS=1`) by design: an
+unconditional block just gets `--no-verify`d, which leaves no trace at all.
+
+## CLI reference
+
+| Command | Purpose |
+|---|---|
+| `cg new <name> --context <path>` | Create a change and begin PLAN |
+| `cg list --context <path>` | List active changes and their phase |
+| `cg begin --phase <PHASE> --context <path>` | Start a transaction for the given phase |
+| `cg approve [--by <who>] [--hotfix --reason "<text>"]` | Human-only: record the sign-off `commit` into EXECUTE requires |
+| `cg commit --next-phase <PHASE> --context <path>` | Validate the current phase's artifacts and advance the DAG |
+| `cg rollback --context <path>` | Restore the manifest snapshot taken at `begin` |
+| `cg checkpoint --summary "<text>" --context <path>` | Persist a session summary for warm-boot resume |
+| `cg claim --context <path>` | Acquire the session lock, taking over a stale one if needed |
+| `cg release --context <path> --agent-id <id>` | Release the session lock (ownership-checked) |
+| `cg claim-task --task-id <id> --context <path>` | Claim one task with a lease |
+| `cg release-task --task-id <id> --agent-id <id> --context <path>` | Release a claimed task |
+| `cg next-task --context <path>` | Claim and return the next unclaimed pending task |
+| `cg check-completion --context <path>` | Deterministic count of checked-off tasks |
+| `cg validate --context <path>` | Lint session artifacts: existence, size cap, language |
+| `cg status --context <path>` | One-shot summary for rehydration after context loss |
+| `cg doctor --context <path> [--fix]` | Diagnose (or repair) stale claims and locks |
+| `cg archive --context <path>` | Move a completed change to `changes/archive/` |
+| `cg migrate --context <path>` | Convert a legacy state-guard or context-guard 1.x layout in place |
+
+Every command accepts `--format json`. `cg` and `context-guard` are the same
+binary under two entry points.
+
+## MCP server
+
+`context-guard-mcp` exposes eight tools over stdio — the four transactional
+ones plus four read-only ones for hosts with no shell (Claude Desktop is the
+case these exist for):
+
+`begin_transaction`, `commit_transaction`, `rollback_transaction`,
+`save_checkpoint`, `get_status`, `check_completion`, `validate`, `next_task`.
+
+`cg approve` is not an MCP tool. See Threat Model above.
+
+## Multi-change
+
+State lives under `.context-guard/changes/<name>/`, one manifest and lock
+set per change, so several changes can be planned and executed
+independently in the same project. `cg new <name>` creates one; `cg list`
+shows what is active; `cg archive` moves a finished one to
+`changes/archive/`. `cg migrate` converts both legacy layouts — state-guard's
+`state.ini` and context-guard 1.x's flat `.context-guard/` — in place and
+idempotently, preserving any recorded human approval it finds.
+
+## Pre-commit hook
+
+`.githooks/pre-commit` rejects commits touching more than a threshold number
+of files when no change shows the protocol was engaged (a completed phase or
+an open transaction). Activate it once per clone with
+`git config core.hooksPath .githooks`.
+
+- **Threshold**: `hook.file_threshold` in a change's manifest, or the
+  `CONTEXT_GUARD_FILE_THRESHOLD` environment variable, which wins over the
+  manifest. Across several active changes, the strictest configured value
+  applies.
+- **`files_in_scope`**: staged files outside an executing change's declared
+  scope produce a warning, never a block.
+- **Bypass**: `CONTEXT_GUARD_BYPASS=1 CONTEXT_GUARD_BYPASS_REASON='...' git
+  commit ...`. Every bypass is appended to `.context-guard/bypass.log` with
+  a timestamp and the file list — the door stays open, but nobody walks
+  through it unrecorded.
+
+## Exit codes
+
+| Code | Name | Meaning |
+|---|---|---|
+| `[0]` | `EXIT_OK` | Success. |
+| `[1]` | `EXIT_GENERIC` | Corrupt manifest, or no session at this context/change. |
+| `[2]` | `EXIT_LOCK_HELD` | Another agent holds the lock or claim. Retryable with backoff. |
+| `[3]` | `EXIT_LOCK_CONTENDED` | Lost the takeover race for a stale lock. Retryable. |
+| `[4]` | `EXIT_VALIDATION` | Missing artifact, leftover `[PENDING]`, oversized artifact, or non-English text. |
+| `[5]` | `EXIT_BAD_TRANSITION` | The phase requested is not the DAG's current `lock_phase`. Do not retry. |
+| `[6]` | `EXIT_APPROVAL_REQUIRED` | `commit` into EXECUTE with no recorded `cg approve`. Only a human resolves it. |
+
+## Adapters and permission configuration
+
+Thin, per-harness wrappers ship inside the package under
+`context_guard/_data/hosts/{claude-code,opencode,antigravity}/` — each points
+at `phases/{plan,execute,verify}.md` rather than duplicating them. How to put
+`cg approve` behind each harness's permission prompt is documented in
+[docs/adapters/](docs/adapters/), one `PERMISSIONS.md` per host, alongside the
+manual smoke-test checklist in [docs/adapters/VERIFY.md](docs/adapters/VERIFY.md).
+`cg setup` installs the right one for each detected host. The OpenCode and Antigravity
+adapters are ported from state-guard and covered by static tests only — they
+have not been run against a live host of either.
+
+## How this compares
+
+context-guard is not a spec-writing tool, and it is not trying to be one.
+
+| | context-guard | spec-kit | Kiro | bare `AGENTS.md` |
+|---|---|---|---|---|
+| Generates specs/plans from a prompt | No | Yes | Yes | No |
+| IDE-native experience | No (CLI + MCP) | Depends on host | Yes | No |
+| Enforces phase order in code, not prose | **Yes** | No | Partial | No |
+| Atomic manifest, survives a crash mid-phase | **Yes** | No | No | No |
+| OS-level locking for concurrent agents | **Yes** | No | No | No |
+| Human-approval gate before execution | **Yes** | No | No | No |
+
+What we do that they do not: runtime enforcement of a state machine that
+outlives the agent's process. What they do that we do not: everything about
+turning a prompt into a good spec in the first place. Use context-guard
+together with whichever of them already generates your `objective.md` — it
+was designed to consume one, not to write one.
+
+## Development
+
+```bash
+git clone https://github.com/fdomerlo/context-guard.git
+cd context-guard && uv venv && uv pip install -e .
+python -m unittest discover -s tests
+```
+
+Framework: `unittest`. Every fix ships with an adversarial test that
+reproduces the bypass it closes; see `tests/test_adversarial_*.py` for the
+pattern. No fixtures on disk outside `tempfile.mkdtemp()`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

context_guard_cli-2.1.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+context_guard/__init__.py,sha256=H72uwUdIexHxAJjD5PnYBkrlVbYGa5UfOq2Ip2IJxbs,29
+context_guard/mcp_server.py,sha256=XSZa-FcToAQuYM99IZSrJdonDvZbOX-oj9s86r-ayik,11576
+context_guard/_data/hosts/antigravity/hooks.snippet.json,sha256=4Q-IPllMmHojp_HAZYncSVvyTQd0USw7RNt5vZSba70,325
+context_guard/_data/hosts/antigravity/rules/context-guard.md,sha256=VzxWOyk0H-Wq6D_xNbtu0r71YKdrrqdKTl0YOYLB7iY,928
+context_guard/_data/hosts/claude-code/mcp.snippet.json,sha256=awepjaQwV7DBlctPYgtHOX87Aupcv2MWIvseUQ1Cu0A,92
+context_guard/_data/hosts/claude-code/settings.snippet.json,sha256=g9O5t3ZowK3lADDPbqVkYdJd0NYP93d5r8DfINVBjs8,345
+context_guard/_data/hosts/claude-code/commands/cg-continue.md,sha256=n4wKaY0xNdzW445nGv9GAuIZVdZXOJoBc-i-AUkqyHU,485
+context_guard/_data/hosts/claude-code/commands/cg-new.md,sha256=5dbF_dEXry363UA9BurIlhbnLJpAMLoUx0w12HAVtDI,382
+context_guard/_data/hosts/opencode/agent.snippet.json,sha256=WM0LRPX8QlPBr9O7Q08Q3lgIm6tvPt8W6qVNMpVGq-4,510
+context_guard/_data/hosts/opencode/mcp.snippet.json,sha256=f8KX2rco5SwLNlsDFFTg0W1geiNQq8bo0yfYNCdDnik,133
+context_guard/_data/hosts/opencode/permissions.snippet.json,sha256=F41dGpQ-ucL4WhJVr7PYbX-ZCL4Fa4iEibSZlWY_tXM,229
+context_guard/_data/hosts/opencode/commands/cg-continue.md,sha256=j2oPCd-bBuOpHYPZArfrmKi7n2EeDQH9uU4tsYbvtA0,569
+context_guard/_data/hosts/opencode/commands/cg-new.md,sha256=NAl0DNGDZWWFnpo6-H54V_kSFGStUg1IDRmTKLp7KrY,403
+context_guard/_data/phases/execute.md,sha256=ADcDdhfjAWmLdDU_1Sm1-u6Llcsq-1ZRLwCOsb-yATU,3143
+context_guard/_data/phases/plan.md,sha256=p6SSbBqx7rWj9Gl1woaG9w3Cp9myvBi3vi0ICDWyVFY,4341
+context_guard/_data/phases/verify.md,sha256=uyIMTxXJ-gWDBnAmslThZBZPPClMVbXnE_A-_UdBdYo,3912
+context_guard/guard/__init__.py,sha256=3SnNGZIYKJa-7XUy310WITknYOfT4ppksSXwP985wII,35
+context_guard/guard/assets.py,sha256=FYEOYM9x-45LdT8FSeW84tHAX4PTN0D6WhZue659nJk,3703
+context_guard/guard/cli.py,sha256=kKJAatVKEpngj564aFAMYHIfi7e9_R355FuoqyAm5uk,11878
+context_guard/guard/commands.py,sha256=ikAyEw0UQSL7uPXKUyOvxEzZA6yo_RCMa2sy0iKL-TA,29798
+context_guard/guard/errors.py,sha256=gE37Z3-3V6tNDEoz2oGDy5GHS-zQ3VHMiF8sFZCFqR8,2812
+context_guard/guard/locking.py,sha256=CO82IWLbFfXVZxgsc-_dR_mpfTH_d3XpJAvodC-2DOo,6502
+context_guard/guard/manifest.py,sha256=dTMdJDn1UjRG7KxODICmCFriXHnxuU3LGvu4ohZGod0,1965
+context_guard/guard/migrate.py,sha256=pK-10Dbw7fIg00pPckFE8KLlL6BmrCC_WUKGCqXgu-k,10598
+context_guard/guard/paths.py,sha256=lCINd-BvMqlZMDElxzkfpw-kdfk9WVgCkxv1Lhbeq_s,6838
+context_guard/guard/setup.py,sha256=X0ISWUasmyRuzKxhGTcBRwnacHeHgrpvmG8aL7sgXLI,18240
+context_guard/guard/transaction.py,sha256=wgdo9qaflHV5j92rsVTpy8hXFOF7peSaY90c-4iXuXE,16008
+context_guard_cli-2.1.0.dist-info/METADATA,sha256=jIPMt-3J8iCIizYx3BYiZs1EptojS5y2_FbWQr87Pg8,13556
+context_guard_cli-2.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+context_guard_cli-2.1.0.dist-info/entry_points.txt,sha256=SpGuOnXXj_0uw7BD1B6Ap7hhJJrbH33n9F7NoiphWUQ,147
+context_guard_cli-2.1.0.dist-info/licenses/LICENSE,sha256=hReNFwlnYKKvbkKeQpzX8V5WmE0fsHaNDQb8q4iPLRY,1071
+context_guard_cli-2.1.0.dist-info/RECORD,,

context_guard_cli-2.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

context_guard_cli-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+cg = context_guard.guard.cli:main
+context-guard = context_guard.guard.cli:main
+context-guard-mcp = context_guard.mcp_server:main

context_guard_cli-2.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Merlo
+
+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.