context-guard-cli 2.1.0__tar.gz

context_guard_cli-2.1.0/.agents/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_cli-2.1.0/.githooks/pre-commit

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Pre-commit gate for context-guard.
+
+Rejects commits touching more than N files when nothing shows the
+PLAN -> EXECUTE -> VERIFY protocol was ever engaged for this context.
+"""
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+
+DEFAULT_FILE_THRESHOLD = 2
+BYPASS_LOG = ".context-guard/bypass.log"
+GUARD_DIR = ".context-guard"
+
+
+def repo_root():
+    return subprocess.check_output(
+        ["git", "rev-parse", "--show-toplevel"], text=True
+    ).strip()
+
+
+def staged_files():
+    out = subprocess.check_output(
+        ["git", "diff", "--cached", "--name-only"], text=True
+    )
+    return [f for f in out.splitlines() if f.strip()]
+
+
+def manifest_paths(root):
+    """Every manifest in the context, newest layout first.
+
+    Since the multi-change refactor state lives in
+    .context-guard/changes/{name}/manifest.json. The flat path is still read so
+    a 1.x repo that has not run `cg migrate` yet is not blocked by an upgrade
+    of the hook alone.
+    """
+    base = os.path.join(root, ".context-guard")
+    paths = []
+    changes_dir = os.path.join(base, "changes")
+    if os.path.isdir(changes_dir):
+        for entry in sorted(os.listdir(changes_dir)):
+            if entry == "archive":
+                continue
+            candidate = os.path.join(changes_dir, entry, "manifest.json")
+            if os.path.exists(candidate):
+                paths.append(candidate)
+    flat = os.path.join(base, "manifest.json")
+    if os.path.exists(flat):
+        paths.append(flat)
+    return paths
+
+
+def load_manifests(root):
+    """Parse every manifest, skipping the ones we cannot read.
+
+    A corrupt manifest is a context-guard problem; letting it raise here would
+    make it a git problem too and leave the user unable to commit the fix.
+    """
+    manifests = []
+    for path in manifest_paths(root):
+        try:
+            with open(path) as f:
+                manifests.append(json.load(f))
+        except (OSError, ValueError):
+            continue
+    return manifests
+
+
+def file_threshold(manifests):
+    """How many staged files are allowed outside the protocol.
+
+    Precedence: the environment wins, then the manifests, then the default. The
+    env var is the per-invocation escape hatch, so committed configuration must
+    not be able to override it.
+
+    Across changes the strictest configured value wins. Picking "the first one"
+    would resolve a repo-wide policy by directory order; the minimum is
+    order-independent and errs toward asking rather than toward silence.
+    """
+    from_env = os.environ.get("CONTEXT_GUARD_FILE_THRESHOLD")
+    if from_env is not None:
+        try:
+            return int(from_env)
+        except ValueError:
+            pass
+
+    configured = []
+    for manifest in manifests:
+        value = manifest.get("hook", {}).get("file_threshold")
+        try:
+            configured.append(int(value))
+        except (TypeError, ValueError):
+            # A typo in the manifest must not silently disable the hook.
+            continue
+    return min(configured) if configured else DEFAULT_FILE_THRESHOLD
+
+
+def out_of_scope(manifests, files):
+    """Staged files that no executing change declared as its scope.
+
+    Advisory only, per PLAN.md F4. Blocking here would put the hook in the way
+    of the user's own flow on a field the agent fills in by hand, and a soft
+    check that hardens into a blocker is how you end up with an agent that
+    cannot commit.
+
+    Only changes actually in EXECUTE are considered: in PLAN the scope has not
+    been decided yet, so every file would be "out" of it and the warning would
+    be noise from the first commit.
+    """
+    scopes = []
+    for manifest in manifests:
+        if manifest.get("lock_phase") != "EXECUTE":
+            continue
+        scopes.extend(manifest.get("files_in_scope") or [])
+    if not scopes:
+        # Not declared is not the same as "nothing is allowed" — the manifest
+        # ships with files_in_scope empty.
+        return []
+
+    stray = []
+    for path in files:
+        # The guard's own state is written by every phase; warning about it on
+        # every commit is how a soft check gets tuned out.
+        if path == GUARD_DIR or path.startswith(GUARD_DIR + "/"):
+            continue
+        if any(path == s or path.startswith(s.rstrip("/") + "/") for s in scopes):
+            continue
+        stray.append(path)
+    return stray
+
+
+def protocol_engaged(manifests):
+    """True if any change is doing the work.
+
+    One engaged change is enough: the staged files belong to whichever change
+    is active, and the hook cannot tell which without guessing — the
+    alphabetical guess PLAN.md 1.3 forbids by name.
+    """
+    for manifest in manifests:
+        txn = manifest.get("transaction", {})
+        if manifest.get("completed_phases") or txn.get("txn_status") == "in_progress":
+            return True
+    return False
+
+
+def log_bypass(root, files, reason):
+    path = os.path.join(root, ".context-guard")
+    os.makedirs(path, exist_ok=True)
+    with open(os.path.join(path, "bypass.log"), "a") as f:
+        f.write(f"{datetime.now().isoformat()}|{reason}|files={len(files)}|{','.join(files)}\n")
+
+
+def main():
+    root = repo_root()
+    files = staged_files()
+    manifests = load_manifests(root)
+
+    # Advisory, and checked on every commit regardless of size: a one-file
+    # change outside the declared scope is just as worth mentioning, and this
+    # branch never affects the exit code.
+    stray = out_of_scope(manifests, files)
+    if stray:
+        print(
+            f"[context-guard] WARN: {len(stray)} staged file(s) outside "
+            f"files_in_scope: {', '.join(stray)}",
+            file=sys.stderr,
+        )
+
+    threshold = file_threshold(manifests)
+    if len(files) <= threshold:
+        sys.exit(0)
+
+    if protocol_engaged(manifests):
+        sys.exit(0)
+
+    if os.environ.get("CONTEXT_GUARD_BYPASS") == "1":
+        reason = os.environ.get("CONTEXT_GUARD_BYPASS_REASON", "unspecified")
+        log_bypass(root, files, reason)
+        print(f"[context-guard] BYPASS recorded in {BYPASS_LOG}", file=sys.stderr)
+        sys.exit(0)
+
+    print(
+        f"[context-guard] COMMIT REJECTED: {len(files)} files staged "
+        f"(threshold={threshold}) with no phase engaged.\n"
+        f"  -> Start the protocol first: cg new <change> or cg begin --phase <PHASE>.\n"
+        f"  -> Escape hatch: CONTEXT_GUARD_BYPASS=1 CONTEXT_GUARD_BYPASS_REASON='...' git commit ...\n",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+if __name__ == "__main__":
+    main()

context_guard_cli-2.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v2, v2.1]
+  pull_request:
+    branches: [main, v2, v2.1]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        # The dev extra pulls in `build`, without which tests/test_packaging.py
+        # skips — and that file is the only proof the wheel actually carries
+        # the embedded artifacts (PLAN-2.1 F1).
+        run: pip install ".[dev]"
+      - name: Run tests
+        run: python -m unittest discover -s tests

context_guard_cli-2.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish
+
+# Publishing is driven by a GitHub release, not by a push: creating the
+# release is the human act that authorises a version going out, and it is the
+# only step of this pipeline a person performs.
+on:
+  release:
+    types: [published]
+
+jobs:
+  # A separate job, not a step, so `needs:` below is a real gate. A test step
+  # sitting above an upload step in the same job can be skipped, reordered or
+  # made non-fatal by a later edit without anything failing loudly.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        # The dev extra carries `build`; without it the packaging tests skip,
+        # and the check that proves the wheel actually contains its data
+        # would silently not run on the very wheel being published.
+        run: pip install ".[dev]"
+      - name: Run tests
+        run: python -m unittest discover -s tests
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    # Trusted Publishing: PyPI hands out a short-lived credential to this
+    # workflow, in this repository, in this environment, and to nothing else.
+    # The alternative — an API token in a secret — is a long-lived credential
+    # that publishes from anywhere it leaks to. Binding the capability to the
+    # place the check runs is the same principle as putting `cg approve`
+    # behind the harness permission prompt rather than trusting the agent.
+    #
+    # `environment` must match the pending publisher registered on PyPI
+    # (owner fdomerlo, repository context-guard, workflow publish.yml,
+    # environment pypi). A mismatch fails as an opaque OIDC error.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

context_guard_cli-2.1.0/.gitignore

@@ -0,0 +1,10 @@
+.context-guard/
+__pycache__/
+*.pyc
+*.tmp
+*.zip
+.venv/
+dist/
+PLAN.md
+PLAN-2.1.md
+RUNBOOK_HUMANO.md

context_guard_cli-2.1.0/AGENTS.md

@@ -0,0 +1,93 @@
+# Context Guard — Agent Guide
+
+## Overview
+
+Transactional state manager for AI agents via CLI and MCP. Enforces a strict
+`PLAN → EXECUTE → VERIFY → ARCHIVE` pipeline per change, with atomic rollback.
+State lives in `<project-root>/.context-guard/changes/{name}/manifest.json`.
+
+## Entrypoints
+
+- **CLI**: `cg` (short) or `context-guard` (long) — `context_guard.guard.cli:main`
+- **MCP server**: `context-guard-mcp` — transactional tools plus read-only ones
+  (`get_status`, `next_task`, `check_completion`, `validate`)
+
+## Multi-change
+
+Every command accepts `--change <name>`. Omit it only when exactly one change
+is active — with several, the command errors and asks you to be explicit; it
+never guesses. `cg new <name>` scaffolds a change and begins PLAN. `cg list`
+shows active changes. `cg archive` moves a finished one to `changes/archive/`.
+`cg migrate` converts a legacy single-change or state-guard layout in place.
+
+## Pipeline phases
+
+Full instructions for each phase live in `.context-guard/phases/{plan,execute,
+verify}.md`, installed into the project from the package's embedded copy —
+load the file for the phase you are entering and follow it. Do not skip a
+phase; `commit` rejects any transition outside this table.
+
+| Phase   | Produces                              | Then                          |
+|---------|----------------------------------------|--------------------------------|
+| PLAN    | `objective.md`, `tasks.md`             | human review, then `cg approve` |
+| EXECUTE | code changes, `tasks.md` checked off   | `check-completion`             |
+| VERIFY  | `review-report.md`, `verify-report.md` | archive on approval             |
+
+## Hard gates (validated on `commit`)
+
+- **PLAN → EXECUTE**: `objective.md` + `tasks.md` must exist and contain no
+  `[PENDING]`.
+- **VERIFY → ARCHIVE**: `review-report.md` + `verify-report.md` must exist and
+  contain no `[PENDING]`.
+
+`begin` on a fresh PLAN auto-scaffolds 5 markdown files in the change
+directory, all initialized with `[PENDING]`.
+
+## The `cg approve` step
+
+Before running `commit --next-phase EXECUTE`, present `objective.md` and
+`tasks.md` to the human and wait for explicit go-ahead — never advance the
+phase unprompted. `commit` enforces this: without a recorded approval it fails
+with `APPROVAL_REQUIRED` (code 6).
+
+`cg approve [--change <name>] [--by <who>] [--hotfix --reason "<text>"]` records
+it. **Never run it yourself** — ask the human to. `--by` is required: there is
+no default, so an agent that runs it anyway cannot pass silently as the
+environment's `$USER`. The approval is spent by the
+commit it authorizes, so a new iteration of the plan needs a new one.
+`--hotfix` skips PLAN and opens EXECUTE directly; it requires a reason, which
+is persisted. The real control is your harness's permission prompt: put
+`cg approve` on the "ask" list (see `docs/adapters/*/PERMISSIONS.md`) so a human
+confirms it out of band, not just in the conversation.
+
+## Exit codes (schema v3)
+
+`0` OK · `1` GENERIC · `2` LOCK_HELD (retry) · `3` LOCK_CONTENDED (retry) ·
+`4` VALIDATION · `5` BAD_TRANSITION (do not retry) · `6` APPROVAL_REQUIRED
+(human-only). `--format json` is available on every command.
+
+## Testing
+
+- Framework: **unittest**, run: `python -m unittest discover -s tests`
+- Tests use `tempfile.mkdtemp()` — no fixtures, no services
+
+## Architecture notes
+
+- `context_guard/guard/`: `paths` (change resolution), `errors`, `manifest`
+  (atomic tmp+rename), `locking` (session + write lock, stale via PID/mtime),
+  `transaction` (`begin`/`commit`/`rollback`), `commands`, `cli`.
+- Task claims use a lease (`claim-task`/`next-task`/`doctor --fix`) for
+  multi-agent swarms working the same change concurrently.
+- Language enforcement: artifacts must be in English; `validate` rejects
+  Spanish text.
+- Pre-commit hook (`git config core.hooksPath .githooks`) rejects large
+  commits outside an active transaction. Threshold: `hook.file_threshold` in
+  the manifest (strictest across changes) or `CONTEXT_GUARD_FILE_THRESHOLD`,
+  which wins. Files outside `files_in_scope` warn, never block. Bypass:
+  `CONTEXT_GUARD_BYPASS=1 CONTEXT_GUARD_BYPASS_REASON='...' git commit ...`
+  — recorded in `.context-guard/bypass.log`.
+- `files_in_scope` and `hook.file_threshold` are manual-only fields: no `cg`
+  command writes either one. To use them, edit
+  `.context-guard/changes/<name>/manifest.json` directly — `files_in_scope`
+  is a list of path prefixes, `hook` is `{"file_threshold": <int>}`. Both
+  default to unset (empty scope, threshold 2) and work fine left alone.

context_guard_cli-2.1.0/CHANGELOG.md

@@ -0,0 +1,271 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.1.0] - 2026-08-01
+
+### Added
+
+- `cg setup` installs the host adapters for Claude Code, OpenCode and
+  Antigravity. Global scope by default — one command per machine — with
+  `--project <dir>` keeping 2.1's predecessor behaviour of installing into a
+  single project for teams that commit the configuration.
+- The phase documents and every host artifact now ship inside the package as
+  data, so nothing needs a clone of this repository to install.
+- `cg setup --no-hooks` declines Antigravity's `PreToolUse` deny hook, which
+  is installed by default. That hook is what stops the agent from running
+  `cg approve` itself, so the file it writes is annotated in the summary with
+  what it is and how to skip it.
+
+### Changed
+
+- `--context` defaults to the working directory on every subcommand, and
+  `--by` defaults to the OS user, so with a single active change the whole
+  human approval is `cg approve` with no flags at all.
+- **`--by` is no longer required.** 2.0 required it, arguing that inheriting
+  the environment made an agent-run approve indistinguishable from a
+  human-run one. The flag never authenticated anyone — an agent can pass any
+  string — and requiring it put friction on the one step that must not be
+  automated. It is audit metadata: who to ask about an approval later. The
+  authentication was and remains the harness permission prompt, which the
+  Threat Model now says explicitly.
+- Naming a change that does not exist reports
+  `FAIL|CHANGE_NOT_FOUND|<name>|available: <list>` instead of
+  `FAIL|NO_SESSION`, which read as a broken project rather than a typo. A
+  mistyped name also no longer creates the change it names: `begin` used to
+  answer a misspelling by bringing that change into being.
+- `cg new` materialises `.context-guard/phases/*.md` into the project from the
+  packaged copy, which is what makes a globally installed slash command work
+  in a project nobody prepared. A phase file that already exists is never
+  overwritten; `cg doctor` reports the difference as INFO.
+
+### Fixed
+
+- `cg setup --host antigravity` no longer crashes on an existing
+  `hooks.json` whose shape it did not expect (`{"hooks": [...]}` raised
+  `AttributeError` with a raw traceback). The shape is validated before the
+  merge; anything unrecognised or unparseable is reported and left byte-for-
+  byte untouched, and a host that cannot be configured no longer aborts the
+  others in the same run.
+
+### Removed
+
+- `adapters/install.sh`, with no compatibility wrapper. Run `cg setup`
+  instead.
+- `--with-antigravity-hook`. The deny hook is installed by
+  `cg setup --host antigravity`, since at global scope it was the only thing
+  that flag's host had to install.
+
+### Known gaps
+
+Deliberately out of scope for 2.1, recorded here so the decisions outlive the
+plan that made them:
+
+- No `get.sh` curl-pipe bootstrap; installation is `pip install` plus
+  `cg setup`.
+- No `cg setup --uninstall`. The exact list of files each run touches is
+  printed for that reason — it is the only record of what to remove by hand.
+- The tutorial exists in Spanish only; no English mirror yet.
+- `cg setup` and the three host adapters are still unverified against a real
+  host session. `docs/adapters/VERIFY.md` is the manual checklist.
+
+## [2.0.0] - 2026-07-31
+
+### The state-guard merge
+
+context-guard 2.0 folds state-guard into this repo: one process instead of two
+diverging philosophies. state-guard's multi-change layout, phased
+`plan → execute → verify` workflow, and cooperative approval model are ported
+here on top of context-guard's atomic manifest and DAG-enforced transaction
+core — the better architecture of the two, kept as the skeleton. state-guard
+is retired; its repository now points here.
+
+### Core fixes (audited bypasses closed)
+
+- `begin` now validates `lock_phase` before starting a phase. Previously the
+  DAG was only checked on `commit`, so an agent that never committed was never
+  stopped from working a phase it was never authorized to start.
+- Orphaned session locks (lockfile present, no metadata) now age off the
+  file's own mtime instead of deadlocking forever.
+- A write lock held by a live process is no longer stolen by age alone; a hard
+  cap (10x the normal TTL) still recovers one abandoned by a reused PID.
+- Task claims carry a lease; `next-task` reclaims expired ones and logs the
+  takeover, `doctor --fix` releases claims whose owning PID is gone.
+- `release` / `release-task` now require `--agent-id` (or an explicit
+  `--force`, logged in the manifest) — an anonymous release could previously
+  free a lock or claim it did not own.
+- Exit codes are unified across the whole CLI: `0` OK, `1` GENERIC, `2`
+  LOCK_HELD, `3` LOCK_CONTENDED, `4` VALIDATION, `5` BAD_TRANSITION, `6`
+  APPROVAL_REQUIRED. `--format json` is available on every command.
+
+### Multi-change
+
+- State moves from a single `.context-guard/manifest.json` to
+  `.context-guard/changes/{name}/`, so several changes can be planned,
+  executed, and locked independently in the same project.
+- New commands: `cg new <name>`, `cg list`, `cg archive --change <name>`.
+- `cg migrate` converts both legacy layouts (state-guard's `state.ini` and
+  context-guard 1.x's flat directory) in place, idempotently. A 1.x layout's
+  own `archive/` subdirectories are copied into `changes/archive/` too, not
+  just its live changes. Phases state-guard tracked that this pipeline does
+  not recognise (a `hotfix` bypass state, for example) land in a
+  `legacy_phases` field instead of silently corrupting `completed_phases`.
+- Every command accepts `--change`; with several changes active and no flag,
+  commands report the ambiguity and name them — never guess the first one
+  alphabetically, the bug both predecessor repos shipped with.
+
+### Human approval gate
+
+- `cg approve --change <name> --by <who> [--hotfix --reason "<text>"]`
+  records a human sign-off in the manifest. `commit --next-phase EXECUTE`
+  refuses without one (`APPROVAL_REQUIRED`, exit 6). The approval is consumed
+  by the commit it authorizes, so a later iteration of the plan needs a new
+  one. `--by` is required — no default, so an agent-run approve cannot pass
+  silently as the environment's `$USER`.
+- `--hotfix` is the audited door out of the pipeline: it requires a reason,
+  jumps straight to EXECUTE, and records PLAN as skipped rather than
+  completed.
+- The gate is cooperative by construction — see Threat Model in the README.
+  The hard control is your harness's permission prompt on `cg approve`,
+  documented per host in `adapters/*/PERMISSIONS.md`. `approve` is
+  deliberately not exposed over MCP, for the same reason.
+
+### Pre-commit hook, promoted
+
+- Reads the multi-change layout (previously blind to it, and blocking every
+  large commit regardless of protocol state).
+- File threshold is configurable via `hook.file_threshold` in the manifest or
+  `CONTEXT_GUARD_FILE_THRESHOLD` (env wins); the strictest configured value
+  applies across changes.
+- Files staged outside `files_in_scope` on an executing change now warn, never
+  block. Output is in English. The audited bypass
+  (`CONTEXT_GUARD_BYPASS=1 CONTEXT_GUARD_BYPASS_REASON=...`) is unchanged.
+
+### Phases and adapters
+
+- `phases/{plan,execute,verify}.md`, ported from state-guard, translated to
+  English, trimmed, and integrated with `[PENDING]` and `cg approve`.
+- Thin per-harness adapters in `adapters/{claude-code,opencode,antigravity}/`
+  plus `install.sh`, all installing per-project now — OpenCode and
+  Antigravity used to write into `$HOME` (a stale absolute path to the repo
+  clone for OpenCode's generated commands, a global `~/.gemini/GEMINI.md`
+  injection for Antigravity that contaminated every project on the machine).
+  Nine confirmed bugs closed in the pass: the deprecated OpenCode `tools`
+  key, a missing manifest-edit `deny` on both OpenCode and Claude Code,
+  inconsistent command names across hosts (unified on `/cg-new` /
+  `/cg-continue`), a missing Antigravity deny hook on `run_command`, and no
+  MCP server registration anywhere.
+- `install.sh` gains `--host claude|opencode|antigravity|all`, `--with-mcp`
+  (registers `context-guard-mcp` per host; optional, every adapter works
+  without it), and `--with-antigravity-hook` (opt-in, touches user config).
+  Every config merge is idempotent and preserves what was already there;
+  the installer prints the exact list of files it touched.
+- Each adapter documents its own permission configuration for `cg approve`
+  in `PERMISSIONS.md`; OpenCode and Antigravity are marked unverified —
+  rewritten and covered by tests that actually run `install.sh`, but never
+  driven through a real host session. `adapters/VERIFY.md` is the manual
+  checklist for closing that gap.
+- `AGENTS.md` rewritten to under 100 lines as the single contract an agent
+  loads.
+
+### MCP server
+
+- Gains the four read tools promised since F3: `get_status`, `next_task`,
+  `check_completion`, `validate`, alongside the existing transactional four.
+- `approve` is not an MCP tool — see Threat Model.
+
+### Packaging
+
+- `mcp` dependency pinned with an upper bound (`>=1.0.0,<2.0.0`).
+- `requires-python = ">=3.10"`, tested in CI across 3.10–3.13.
+- `cg` ships as a short entry point alongside `context-guard`.
+- MIT license added.
+- `requirements.txt` removed — it carried `mcp>=1.0.0` with no upper bound,
+  the exact drift fixed in `pyproject.toml`, and nothing in the repo
+  consumed it. `pyproject.toml` is the single source of truth.
+- `.claude/` excluded from the sdist after a `uv build` dry run showed it
+  bundling `.claude/settings.local.json` — untracked, ignored by this
+  machine's global gitignore rather than the repo's own, carrying absolute
+  local paths.
+
+---
+
+## [1.2.0] - 2026-07-28
+
+### 🔒 Git Hard Gate (Pre-Commit Hook)
+
+- Implemented a Git pre-commit hook (`.githooks/pre-commit`) that rejects commits touching more than 2 files without an active `context-guard` transaction.
+- Prevents large changes to the repository that bypass the `PLAN → EXECUTE → VERIFY` protocol.
+- Supports an emergency bypass via `CONTEXT_GUARD_BYPASS=1`, automatically logged to `.context-guard/bypass.log`.
+
+### 📦 Package Namespace Fix
+
+- Renamed the source directory from `scripts/` to `context_guard/` to avoid global collisions in Python, standardizing the module name with the tool's name.
+- Updated internal imports to use relative references (`from .X import Y`) within the `guard` submodule, decoupling it from the root package name.
+- Updated the entry point in `pyproject.toml` to reflect the new structure: `context_guard.mcp_server:main`.
+
+---
+
+## [1.1.0] - 2026-07-28
+
+### 🏗️ Automatic Artifact Scaffolding
+
+- **`_scaffold_artifacts(context_path)`** in `transaction.py`:
+  - When a `PLAN` transaction starts via `begin_transaction`, five Markdown templates are auto-generated in `.context-guard/` if they do not already exist: `objective.md`, `snapshot.md`, `tasks.md`, `review-report.md`, and `verify-report.md`.
+  - Each template is initialized with the `[PENDING]` marker to guide the LLM on which fields need to be completed before advancing phase.
+
+### 🚧 Hard Gates in `cmd_commit`
+
+- Strict Python-side validations before authorizing phase transitions (no dependency on system prompt compliance):
+  - **`PLAN` → `EXECUTE`**: Verifies that `objective.md` and `tasks.md` exist and contain no `[PENDING]`. Otherwise returns `EXIT_VALIDATION` with a descriptive message.
+  - **`VERIFY` → `ARCHIVE`**: Verifies that `review-report.md` and `verify-report.md` exist and contain no `[PENDING]`. Otherwise returns `EXIT_VALIDATION` with a descriptive message.
+
+### 📜 Updated MCP Docstrings (`mcp_server.py`)
+
+- `begin_transaction`: Documents the auto-scaffolding of the 5 `.md` files in the `PLAN` phase.
+- `commit_transaction`: Documents the strict Hard Gate validation rules per file and per phase, exposing the constraints to the LLM via the tool schema.
+
+### ✅ Test Suite Improvements
+
+- New test cases in `test_transaction.py`:
+  - `test_begin_valid_phase`: verifies creation of the 5 scaffold artifacts with `[PENDING]` content.
+  - `test_commit_hard_gate_plan_to_execute_pending`: validates rejection when `PLAN` files still contain markers.
+  - `test_commit_hard_gate_verify_to_archive_pending`: validates rejection when `VERIFY` files still contain markers.
+- Updated `test_phases.py` and `test_mcp_server.py` to prepare valid artifacts before each `commit_transaction`.
+- Full suite: **111 tests, 0 failures**.
+
+---
+
+## [1.0.0] - 2026-07-28
+
+### 🚀 Highlights and Core Features
+
+- **Native MCP Server (Model Context Protocol):**
+  - Exposes native tools over `stdio` transport: `begin_transaction`, `commit_transaction`, `rollback_transaction`, and `save_checkpoint`.
+  - Transparent integration with MCP clients such as Claude Desktop, Antigravity, OpenCode, and Cursor.
+
+- **3-State Transactional Pipeline (DAG):**
+  - Strict implementation of the phase sequence: `PLAN` $\longrightarrow$ `EXECUTE` $\longrightarrow$ `VERIFY` $\longrightarrow$ `ARCHIVE`.
+  - Validates allowed transitions to prevent arbitrary phase jumps by the LLM.
+
+- **Atomicity and Rollback Mechanism:**
+  - Automatic `manifest.json` snapshots taken on `begin_transaction`.
+  - `rollback_transaction` tool restores the exact prior state on execution failures or failed tests during the `VERIFY` phase.
+
+- **Concurrency Control and Write Lock (OS-level):**
+  - OS-level session locks and write mutexes (`O_CREAT|O_EXCL`) to prevent race conditions (*TOCTOU*) between concurrent agents or sessions.
+  - Automatic detection and recovery of orphaned (*stale*) locks via PID verification and timestamping.
+
+- **Per-Project Absolute Path Anchoring:**
+  - Isolated, transparent persistence inside each project's root directory (`<PROJECT_ROOT>/.context-guard/`), eliminating contamination of the home directory (`$HOME`).
+
+- **Standard Packaging and Zero-Install Support (`uvx`):**
+  - Added `pyproject.toml` with the `hatchling` backend and the `context-guard` executable entry point.
+  - Supports one-line execution with no prior clone via `uvx git+https://github.com/fdomerlo/context-guard.git`.
+
+- **Tool Discovery Optimization (i18n):**
+  - Docstrings and auto-summaries standardized in English to maximize language model adherence during tool discovery and selection.