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

context_guard/__init__.py

@@ -0,0 +1 @@
+"""context-guard package."""

context_guard/_data/hosts/antigravity/hooks.snippet.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": {
+          "tool": "run_command",
+          "commandPattern": "^\\s*(cg|context-guard)\\s+approve\\b"
+        },
+        "action": {
+          "decision": "deny",
+          "message": "human-only command — ask the user to run it"
+        }
+      }
+    ]
+  }
+}

context_guard/_data/hosts/antigravity/rules/context-guard.md

@@ -0,0 +1,15 @@
+<!-- context-guard:begin -->
+## ACTIVE PERSISTENCE CONTRACT: context-guard
+MANDATORY BOOTSTRAP — read before responding to anything in a project that
+has a `.context-guard/` directory:
+1. Read `AGENTS.md` at the project root and follow it as your state contract.
+2. State manager binary: `cg` (or `context-guard`). Operative subcommands:
+   begin | commit | rollback | checkpoint | status | next-task | validate
+   Human-only subcommand (never run by the agent): `cg approve`.
+   If `commit` returns EXIT_APPROVAL_REQUIRED (6): stop and ask the user to
+   run `cg approve --change <name>` themselves.
+3. Check `.context-guard/changes/*/manifest.json` for an active change and
+   act accordingly (cold start, resume via `cg status`, or report a stuck
+   lock — never fix a stuck lock by editing the manifest by hand).
+4. Phase instructions live in `.context-guard/phases/{plan,execute,verify}.md`.
+<!-- context-guard:end -->

context_guard/_data/hosts/claude-code/commands/cg-continue.md

@@ -0,0 +1,13 @@
+---
+description: Resume the active context-guard change from where it left off
+---
+
+Change (optional): $ARGUMENTS
+
+1. Run `cg status [--change $ARGUMENTS]`.
+2. Load and follow, exactly, the file matching the reported `lock_phase`:
+   - PLAN    -> `.context-guard/phases/plan.md`
+   - EXECUTE -> `.context-guard/phases/execute.md`
+   - VERIFY  -> `.context-guard/phases/verify.md`
+3. If the lock is held by another agent, stop and report the conflict —
+   do not retry automatically.

context_guard/_data/hosts/claude-code/commands/cg-new.md

@@ -0,0 +1,11 @@
+---
+description: Start a new context-guard change and run its PLAN phase
+---
+
+Change name: $ARGUMENTS (ask the user for one if empty).
+
+1. Run `cg new $ARGUMENTS`
+2. Load `.context-guard/phases/plan.md` and follow it exactly for this
+   change, through its human review gate.
+3. Never run `cg commit --next-phase EXECUTE` without an explicit
+   go-ahead from the user in this chat.

context_guard/_data/hosts/claude-code/mcp.snippet.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "context-guard": {
+      "command": "context-guard-mcp"
+    }
+  }
+}

context_guard/_data/hosts/claude-code/settings.snippet.json

@@ -0,0 +1,12 @@
+{
+  "_comment": "Merge into .claude/settings.json. PLAN.md 0.6: cg approve is cooperative by itself; putting it on the ask list is the hard control that pairs with it.",
+  "permissions": {
+    "ask": [
+      "Bash(cg approve*)",
+      "Bash(context-guard approve*)"
+    ],
+    "deny": [
+      "Edit(.context-guard/**/manifest.json)"
+    ]
+  }
+}

context_guard/_data/hosts/opencode/agent.snippet.json

@@ -0,0 +1,7 @@
+{
+  "context-guard": {
+    "mode": "all",
+    "description": "Context Guard — transactional memory for AI coding agents",
+    "prompt": "Read AGENTS.md at the project root and follow it as your state contract. Phase instructions live in .context-guard/phases/{plan,execute,verify}.md. Use the cg CLI (begin/commit/rollback/checkpoint/status/next-task/validate); cg approve is a human-only command. If commit returns exit code 6 (APPROVAL_REQUIRED), stop and ask the user to run cg approve themselves."
+  }
+}

context_guard/_data/hosts/opencode/commands/cg-continue.md

@@ -0,0 +1,16 @@
+---
+description: Resume the active context-guard change from where it left off
+agent: context-guard
+---
+
+!`cg status --format json`
+
+Change (optional): $ARGUMENTS. The status above is already current — do not
+re-run `cg status` yourself.
+
+1. Load and follow, exactly, the file matching the reported `lock_phase`:
+   - PLAN    -> `.context-guard/phases/plan.md`
+   - EXECUTE -> `.context-guard/phases/execute.md`
+   - VERIFY  -> `.context-guard/phases/verify.md`
+2. If the lock is held by another agent, stop and report the conflict —
+   do not retry automatically.

context_guard/_data/hosts/opencode/commands/cg-new.md

@@ -0,0 +1,12 @@
+---
+description: Start a new context-guard change and run its PLAN phase
+agent: context-guard
+---
+
+Change name: $ARGUMENTS (ask the user for one if empty).
+
+1. Run `cg new $ARGUMENTS`
+2. Load `.context-guard/phases/plan.md` and follow it exactly for this
+   change, through its human review gate.
+3. Never run `cg commit --next-phase EXECUTE` without an explicit
+   go-ahead from the user in this chat.

context_guard/_data/hosts/opencode/mcp.snippet.json

@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "context-guard": {
+      "type": "local",
+      "command": ["context-guard-mcp"],
+      "enabled": true
+    }
+  }
+}

context_guard/_data/hosts/opencode/permissions.snippet.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "cg approve*": "ask",
+      "context-guard approve*": "ask"
+    },
+    "edit": {
+      ".context-guard/**/manifest.json": "deny"
+    }
+  }
+}

context_guard/_data/phases/execute.md

@@ -0,0 +1,99 @@
+# EXECUTE Phase
+
+## Purpose
+
+EXECUTE is the only phase that changes the project's source code. It works
+through `tasks.md` task by task until the change is implemented.
+
+**Prerequisite:** `lock_phase == EXECUTE` — this only happens after the human
+approved the PLAN commit.
+
+## What to do
+
+### Step 1: Begin the transaction
+
+```bash
+cg begin --context <path> --phase EXECUTE --change <change-name>
+```
+
+### Step 2: Read the context
+
+Before writing any code:
+
+1. **Plan** — read `objective.md` for intent and scope.
+2. **Tasks** — read `tasks.md` for the full breakdown.
+3. **Existing code** — read the files each task actually touches.
+
+### Step 3: Detect TDD mode
+
+Check, in order: a project config declaring `tdd: true`, existing test
+patterns in the codebase (a `tests/` directory with a consistent style is a
+strong signal), otherwise assume standard mode (code first).
+
+### Step 4: Implement tasks
+
+**TDD mode (RED → GREEN → REFACTOR)**, for each task:
+1. Read the task description and any related acceptance criteria.
+2. **RED**: write a test describing the expected behavior → confirm it FAILS.
+3. **GREEN**: implement the minimum code to make it pass → confirm it PASSES.
+4. **REFACTOR**: clean up without changing behavior → confirm it still PASSES.
+5. Check the task off in `tasks.md` (`- [x]`).
+
+> CRITICAL: run tests in a real terminal. Simulating or inferring results is
+> not allowed.
+
+**Standard mode**, for each task: read the description, read existing code
+patterns, write the code, check the task off.
+
+Default batch size: 3 tasks per invocation, adjusted to available context.
+For task lists that support parallel work, `cg next-task --context <path>
+--change <name>` and `cg claim-task` let multiple agents work the same
+change without stepping on each other — each claim carries a lease, so a
+crashed agent's tasks become available again automatically; see `AGENTS.md`.
+
+### Step 5: Verify progress with the middleware
+
+```bash
+cg check-completion --context <path> --change <change-name>
+```
+
+Reports `total`, `completed`, and whether every task is done — the agent
+never counts checkboxes by hand.
+
+### Step 6: Report
+
+```markdown
+## Implementation progress
+
+**Change**: {change-name}
+**Mode**: {TDD | Standard}
+
+### Completed tasks
+- [x] [T001] {description}
+
+### Files changed
+| File | Action | What happened |
+|------|--------|----------------|
+
+### Deviations from the plan
+{List, or "None — implementation matches the plan."}
+
+### Issues found
+{List, or "None."}
+
+### Status
+{N}/{total} tasks complete. {Ready for VERIFY / next batch pending}
+```
+
+## Rules
+
+- Always follow the plan's decisions — do not improvise architecture.
+- Always match existing code patterns and conventions.
+- Check tasks off in `tasks.md` as you complete them, never in bulk at the
+  end.
+- If the plan turns out to be wrong or incomplete, write it down as a
+  deviation — never diverge silently.
+- If a task is blocked, stop and report it instead of skipping ahead.
+
+Once every task is checked off, run `cg commit --context <path> --change
+<change-name> --next-phase VERIFY` and move on to `phases/verify.md`.

context_guard/_data/phases/plan.md

@@ -0,0 +1,136 @@
+# PLAN Phase
+
+## Purpose
+
+PLAN absorbs exploration, proposal, and scoping into a single block of work.
+It produces `objective.md` and `tasks.md` and submits them to a **mandatory
+human review** before the change is allowed into EXECUTE.
+
+```
+draft  →  human review  →  commit
+```
+
+The commit into EXECUTE is the event that closes PLAN. **The agent must
+never run that commit without an explicit go-ahead from the human.**
+
+## What to do
+
+### Step 1: Begin the transaction
+
+```bash
+cg begin --context <path> --phase PLAN --change <change-name>
+```
+
+If the change is new, `cg new <change-name> --context <path>` does this for
+you and scaffolds `objective.md`, `snapshot.md`, `tasks.md`,
+`review-report.md`, `verify-report.md` in
+`.context-guard/changes/<change-name>/`, all starting as `[PENDING]`.
+
+### Step 2: Discover the stack
+
+```bash
+ls package.json pyproject.toml composer.json go.mod Cargo.toml docker-compose.yml 2>/dev/null
+```
+
+Read whatever manifests exist to identify the stack, framework, and tooling
+before analyzing anything.
+
+### Step 3: Explore and analyze
+
+- Is this new functionality, a bug fix, or a refactor?
+- Read the relevant code: entry points, affected modules, existing tests.
+- Compare approaches if there are real alternatives.
+
+### Step 4: Draft the artifacts
+
+Write directly to disk, replacing the `[PENDING]` scaffolds:
+
+**`objective.md`**
+```markdown
+# Objective: {Change Title}
+
+## Intent
+{What problem this solves and why}
+
+## Scope
+### In scope
+- {deliverable}
+### Out of scope
+- {deferred}
+
+## Success criteria
+- [ ] {measurable outcome}
+
+## Open questions
+- [ ] {unresolved question — mark blocking ones with [!]}
+```
+
+**`tasks.md`**
+```markdown
+# Tasks: {Change Title}
+
+## Phase 1: {e.g. Infrastructure}
+- [ ] [T001] {atomic task with a concrete file path}
+
+## Phase 2: {e.g. Core implementation}
+- [ ] [T002] {atomic task}
+
+## Phase 3: {e.g. Testing}
+- [ ] [T003] {atomic task}
+```
+
+Task rules: one task = one file or logical module (no "monster tasks"); IDs
+follow `[Txxx]` — `check-completion` and `next-task` parse them; group by
+infrastructure → implementation → testing; reference success criteria as
+acceptance checks.
+
+Optionally update `snapshot.md` with a short state-of-the-world summary if
+the change spans multiple sessions — `cg validate` requires the file to
+exist (alongside `objective.md`) and checks size and language, though it
+does not check for a leftover `[PENDING]`; that is `commit`'s job.
+
+### Step 5: Human review gate
+
+**The agent cannot proceed on its own — this is the one barrier only a human
+can cross.**
+
+1. Present `objective.md` and `tasks.md` with an executive summary.
+2. List architecture decisions and open questions explicitly.
+3. Run `cg validate --context <path> --change <change-name>` and fix
+   anything it flags (missing file, oversized artifact, non-English text) —
+   it does not check for `[PENDING]`; confirm by eye that both artifacts
+   are actually filled in before asking for approval.
+4. Ask the human, in this conversation, to review and confirm.
+5. Ask them to record it — **never run this yourself**:
+
+```bash
+cg approve --context <path> --change <change-name> --by <who>
+```
+
+Without it, Step 6 fails with `APPROVAL_REQUIRED` (exit 6). The approval is
+spent by the commit it authorizes, so if the plan is revised afterwards the
+human has to approve again. The harness's permission prompt on `cg approve`
+(configured per `adapters/*/PERMISSIONS.md`) is what makes that confirmation
+hard to skip rather than merely polite.
+
+### Step 6: Commit and close PLAN
+
+Only after the human confirms:
+
+```bash
+cg commit --context <path> --change <change-name> --next-phase EXECUTE
+```
+
+This advances `lock_phase` to `EXECUTE`, releases the phase lock, and
+auto-generates a checkpoint of the DAG state. Report to the user that PLAN is
+locked and EXECUTE is open, with the suggested next command: `/cg-continue`.
+
+## Rules
+
+- Never commit into EXECUTE without explicit human approval.
+- If the human requests changes, regenerate only the sections asked for, not
+  the whole artifact.
+- Blocking open questions (`[!]`) must be resolved before requesting review.
+- Always read the real code — never assume about the codebase.
+- `objective.md` and `tasks.md` are separate artifacts with separate
+  purposes; do not merge them into one file.

context_guard/_data/phases/verify.md

@@ -0,0 +1,129 @@
+# VERIFY Phase
+
+## Purpose
+
+VERIFY is the final quality gate. It proves — with evidence from real
+execution, not static reasoning alone — that the implementation is complete
+and correct. If the verdict is APPROVED, the **archive step** runs
+immediately as part of this same phase.
+
+## What to do
+
+### Step 1: Begin the transaction
+
+```bash
+cg begin --context <path> --phase VERIFY --change <change-name>
+```
+
+### Step 2: Read the context
+
+1. **Plan** — `objective.md` for intent and success criteria.
+2. **Tasks** — `tasks.md` for what was supposed to happen.
+
+### Step 3: Check completeness
+
+```bash
+cg check-completion --context <path> --change <change-name>
+```
+
+List any incomplete tasks. Mark CRITICAL if core tasks are unfinished,
+WARNING if only cleanup tasks remain.
+
+### Step 4: Check correctness against the objective
+
+For each success criterion in `objective.md`: is there real evidence in the
+codebase that it's met? Mark CRITICAL if a criterion has no implementation,
+WARNING if only partially covered.
+
+### Step 5: Run tests and build for real
+
+> CRITICAL: use a real terminal. Simulating or inferring results is not
+> allowed.
+
+Detect and run the project's test command (`package.json` scripts, `pytest`/
+`pyproject.toml`, a `Makefile` target, or whatever `objective.md` calls out)
+and its build/typecheck command if one exists. A missing build step is a
+WARNING, not a CRITICAL — some projects have none.
+
+### Step 6: Write `review-report.md` and `verify-report.md`
+
+`review-report.md` covers static findings (code quality, plan adherence,
+deviations). `verify-report.md` covers dynamic evidence:
+
+```markdown
+## Verification report
+
+**Change**: {change-name}
+
+### Completeness
+| Metric | Value |
+|--------|-------|
+| Total tasks | {N} |
+| Completed | {N} |
+| Incomplete | {N} |
+
+### Build and test run
+**Build**: pass / fail
+**Tests**: {N} passed / {N} failed / {N} skipped
+
+### Issues found
+**CRITICAL**: {list, or "None"}
+**WARNING**: {list, or "None"}
+
+### Verdict
+{APPROVED / APPROVED WITH WARNINGS / REJECTED}
+```
+
+### Step 7: Decide
+
+```text
+If there are CRITICAL issues:
+  → run `cg rollback --context <path> --change <change-name>`
+  → report the issues to the user; the change returns to EXECUTE
+
+If the verdict is APPROVED or APPROVED WITH WARNINGS:
+  → run `cg commit --context <path> --change <change-name> --next-phase ARCHIVE`
+  → continue immediately to Step 8 (archive), in the same invocation
+```
+
+---
+
+### Step 8: ARCHIVE — close out the change
+
+This runs automatically after an APPROVED verdict, in the same `/cg-continue`
+invocation that ran VERIFY. There is no separate manual archive command for
+this path.
+
+1. Confirm `verify-report.md` and `review-report.md` contain no `[PENDING]`
+   and no unresolved CRITICAL issue. If they do, abort.
+2. Check `git status --porcelain`: a dirty tree blocks archiving — ask the
+   user to commit first.
+3. Run:
+   ```bash
+   cg archive --context <path> --change <change-name>
+   ```
+   This copies `.context-guard/changes/<change-name>/` to
+   `.context-guard/changes/archive/<change-name>/` and removes the live
+   change directory. The archive is an audit trail — never edit or delete an
+   archived change.
+4. Report to the user:
+   ```markdown
+   ## Change archived
+
+   **Change**: {change-name}
+   **Archived at**: .context-guard/changes/archive/{change-name}/
+
+   The change has been planned, implemented, verified, and archived.
+   Ready for the next `/cg-new`.
+   ```
+
+## Rules
+
+- Always read real source and run real tests — static analysis alone is not
+  verification.
+- CRITICAL issues must be resolved before archiving.
+- WARNING issues should be resolved but do not block.
+- Do not fix problems found during VERIFY — only report them; fixes happen
+  back in EXECUTE.
+- Never archive while `verify-report.md` has an unresolved CRITICAL issue.
+- Never modify or delete an already-archived change.

context_guard/guard/__init__.py

@@ -0,0 +1 @@
+# context-guard middleware package

context_guard/guard/assets.py

@@ -0,0 +1,94 @@
+"""Accessors for the artifacts shipped as package data (PLAN-2.1 F1).
+
+Everything a host needs — the three phase documents, each host's slash
+commands, rule files and config snippets — lives under `context_guard/_data/`
+and is reached through `importlib.resources`. Never through paths relative to
+this file or to the working directory: the package has to work installed from
+a wheel, with no clone of the repo anywhere on the machine.
+
+Names are validated against a fixed allowlist rather than joined onto the data
+directory. These accessors are called with values that come from CLI flags, so
+a joined path would turn `cg` into a reader for arbitrary files.
+"""
+
+from importlib import resources
+
+from .errors import EXIT_GENERIC, GuardError
+
+PHASES = ("plan", "execute", "verify")
+
+HOSTS = ("claude-code", "opencode", "antigravity")
+
+# Which snippets each host ships, keyed by the short name callers pass. The
+# file is always "<name>.snippet.json"; the mapping exists to be an allowlist,
+# not to spell out a naming convention.
+SNIPPETS = {
+    "claude-code": ("settings", "mcp"),
+    "opencode": ("agent", "permissions", "mcp"),
+    "antigravity": ("hooks",),
+}
+
+
+class AssetNotFoundError(GuardError):
+    """A requested phase, host or snippet is not part of the packaged data."""
+
+    def __init__(self, message):
+        super().__init__(f"FAIL|ASSET_NOT_FOUND|{message}", EXIT_GENERIC)
+
+
+def _data_root():
+    """The `_data` directory as a Traversable.
+
+    `files()` targets the package and joins from there, so this resolves the
+    same whether the package sits in a source checkout or in site-packages.
+    """
+    return resources.files("context_guard").joinpath("_data")
+
+
+def get_phase(name):
+    """Return the text of `_data/phases/<name>.md`.
+
+    `name` must be one of PHASES — anything else raises, including a value that
+    happens to name a real file elsewhere in the tree.
+    """
+    if name not in PHASES:
+        raise AssetNotFoundError(f"unknown phase '{name}' (expected one of {', '.join(PHASES)})")
+    return _data_root().joinpath("phases", f"{name}.md").read_text(encoding="utf-8")
+
+
+def iter_host_files(host):
+    """Yield `(relpath, text)` for every file this host installs.
+
+    `relpath` is relative to the host's directory and always uses forward
+    slashes, because callers join it onto a target directory to write the file
+    out. Raises for an unknown host instead of yielding nothing: a `cg setup`
+    that installs zero files and exits 0 looks exactly like success.
+    """
+    if host not in HOSTS:
+        raise AssetNotFoundError(f"unknown host '{host}' (expected one of {', '.join(HOSTS)})")
+
+    root = _data_root().joinpath("hosts", host)
+
+    def walk(node, prefix):
+        # Sorted so the file order — and therefore any output listing what was
+        # installed — is stable across platforms and filesystems.
+        for child in sorted(node.iterdir(), key=lambda c: c.name):
+            relpath = f"{prefix}{child.name}"
+            if child.is_dir():
+                yield from walk(child, f"{relpath}/")
+            else:
+                yield relpath, child.read_text(encoding="utf-8")
+
+    yield from walk(root, "")
+
+
+def read_snippet(host, name):
+    """Return the text of `_data/hosts/<host>/<name>.snippet.json`."""
+    if host not in HOSTS:
+        raise AssetNotFoundError(f"unknown host '{host}' (expected one of {', '.join(HOSTS)})")
+    if name not in SNIPPETS[host]:
+        raise AssetNotFoundError(
+            f"host '{host}' has no '{name}' snippet "
+            f"(expected one of {', '.join(SNIPPETS[host])})")
+    return _data_root().joinpath(
+        "hosts", host, f"{name}.snippet.json").read_text(encoding="utf-8")