context-guard-cli 2.1.0__tar.gz → 2.4.0__tar.gz

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/.github/workflows/ci.yml

@@ -1,10 +1,14 @@
 name: CI
 
+# The push list is a pattern, not an enumeration: cycle branches follow vX.Y
+# and the old explicit list went stale silently — v2.5 got no CI on push, only
+# once its PR opened. On pull_request the filter matches the *base* branch, so
+# main alone covers every PR into it.
 on:
   push:
-    branches: [main, v2, v2.1]
+    branches: [main, 'v[0-9]*']
   pull_request:
-    branches: [main, v2, v2.1]
+    branches: [main]
 
 jobs:
   test:

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/CHANGELOG.md

@@ -6,6 +6,91 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ---
 
+## [2.4.0] - 2026-08-06
+
+The bridge between a plan and a change was copy-paste. A phased `PLAN-N.md`
+already holds what `cg new` leaves as `[PENDING]`; now the tool reads it.
+
+### Added
+
+- `cg new <name> --from-plan <file>` imports a phased `PLAN-N.md`, creating
+  one change per `## F<N>` phase (`<name>-f1`, `<name>-f2`, …). Each phase's
+  prose and spec become `objective.md`; its test items and acceptance
+  criteria become `tasks.md` in the `- [ ] N.M <text>` form `next-task`
+  already parses. `--phase F2` imports one phase. `snapshot.md` stays
+  `[PENDING]` — it records the repository state at start, which no plan
+  written beforehand can know.
+- `context_guard/guard/plan_import.py`: `parse_plan()` reads a plan into
+  title, one-sentence objective, and phases. Headings delimit phases;
+  `**Spec:**`, `**Tests:**` and `**Acceptance criteria:**` sub-blocks are
+  recognized in English and Spanish. A missing sub-block is empty, not an
+  error; a file with no phase heading is `FAIL|PLAN_NO_PHASES|<path>`.
+  Parsed with `re` alone — no new dependencies.
+- Changes imported from a plan carry no approval. `cg commit --next-phase
+  EXECUTE` still exits 6 until a human runs `cg approve`, once per phase.
+  Covered by an adversarial test: a pre-written objective is not a reviewed
+  one.
+- Re-importing skips changes that already exist
+  (`SKIP|CHANGE_EXISTS|<name>`) instead of overwriting work in flight.
+- A plan quoting the scaffold sentinel `[PENDING]` in its own prose — any
+  plan about context-guard itself — would have produced a change the
+  PLAN→EXECUTE gate refuses as unfilled, stuck before the approval gate was
+  ever reached. The brackets are stripped on import and the substitution is
+  reported (`NOTE|SENTINEL_NEUTRALIZED|<change>|<file>`). Fixed on the
+  import side deliberately: the artifact really was filled, so loosening the
+  gate would have loosened it for every change, imported or not.
+
+## [2.2.0] - 2026-08-02
+
+Triggered by real dogfooding: Antigravity never raised the context-guard
+protocol in a fresh project, because `cg setup` only installed its
+enforcement hook, nothing discoverable.
+
+### Added
+
+- A discovery skill for Antigravity, installed by `cg setup` at
+  `~/.gemini/antigravity-cli/skills/context-guard/SKILL.md` alongside the existing
+  deny hook. Antigravity loads skills by progressive disclosure — only the
+  name and description sit in context until the model picks it — which is
+  what makes this affordable without repeating 2.0's bug 6.0.4
+  (`~/.gemini/GEMINI.md` contamination of every project on the machine,
+  which stays permanently out of scope). The skill carries the three-phase
+  DAG, the operative `cg` commands, and marks `cg approve` human-only.
+- `cg setup --project <dir>` now installs the Antigravity workspace rule
+  directly, instead of that artifact only ever being written by `cg new`.
+- A shared ownership-marker check: a skill or rule file not written by
+  context-guard is never overwritten — reported as `SKIP|SKILL_EXISTS|<path>`
+  and left alone, whether hit through `cg setup` or `cg new`.
+
+### Fixed
+
+- Antigravity detection now checks for `agy` — the CLI's actual binary name
+  — and `~/.gemini/antigravity-cli`, its state directory. The prior check
+  named `antigravity`, which resolves on PATH to an unrelated program.
+- `cg setup --project` was overwriting an `.agents/rules/context-guard.md`
+  a team had edited; `cg new` never did. Both paths now honor the same
+  ownership marker.
+
+### Changed
+
+- README.md, README.es.md and TUTORIAL.es.md Install sections lead with
+  `uv tool install context-guard-cli` / `pipx install`, isolated installs
+  that land `cg` on PATH globally — what a once-per-machine `cg setup`
+  assumes. `pip install` remains documented as a fallback. Explicit warning
+  added against `uv pip install context-guard-cli`, which installs into
+  whichever project venv is active rather than the machine, silently
+  defeating a global `cg setup`.
+- `docs/adapters/VERIFY.md`: step 2 no longer checks Antigravity discovery
+  via `agy inspect`, which does not exist as a subcommand — replaced with
+  the actual verification, behavioral: a new session, a multi-step task,
+  and whether the agent invokes `cg` unprompted. Step 5 no longer names
+  `--with-antigravity-hook`, a flag removed in 2.1; the deny hook installs
+  by default now, declined with `--no-hooks`.
+- VERIFY.md is complete for all three hosts — Claude Code, OpenCode and
+  Antigravity — closing the gap the README used to admit openly. The line
+  stating the OpenCode and Antigravity adapters had not been run against a
+  live host is removed; both have been.
+
 ## [2.1.0] - 2026-08-01
 
 ### Added

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-guard-cli
-Version: 2.1.0
+Version: 2.4.0
 Summary: The transactional memory layer for AI coding agents — your context survives crashes, compaction, and session loss
 License-Expression: MIT
 License-File: LICENSE
@@ -82,10 +82,19 @@ illustrative shorthand.
 Two lines, once per machine:
 
 ```bash
-pip install context-guard-cli
+uv tool install context-guard-cli
 cg setup
 ```
 
+No `uv`? `pipx install context-guard-cli` works the same way. Both install
+into an isolated environment and put `cg` on PATH globally — the whole point,
+since `cg setup` configures your machine once, not once per project.
+`pip install context-guard-cli` also works, as a fallback for a plain Python
+install with no `uv`/`pipx` available. **Do not use `uv pip install
+context-guard-cli`**: that installs into whichever venv is currently active —
+a single project's, if you happen to be inside one — not onto the machine,
+which silently defeats the point of a global `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
@@ -106,6 +115,22 @@ cd context-guard && uv venv && uv pip install -e ".[dev]"
 git config core.hooksPath .githooks   # activates the pre-commit gate below
 ```
 
+## Upgrading
+
+```bash
+uv tool upgrade context-guard-cli && cg setup
+```
+
+The second command is not optional. `cg setup` copies commands, skills and
+permission snippets into your host configs; upgrading the package does not
+touch those copies, so a new version's adapter fixes only reach a machine
+once `cg setup` runs again. It is idempotent — safe to run any time.
+
+Phase files already materialised in a project (`.context-guard/phases/`)
+are never overwritten, by design: a project keeps the phases it was started
+with, including your edits. Delete a phase file and run `cg new` to pull the
+current version.
+
 ## How it works
 
 ```
@@ -176,6 +201,7 @@ unconditional block just gets `--no-verify`d, which leaves no trace at all.
 | Command | Purpose |
 |---|---|
 | `cg new <name> --context <path>` | Create a change and begin PLAN |
+| `cg new <name> --from-plan <file> [--phase F2]` | Import a phased `PLAN-N.md` as one change per phase |
 | `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 |
@@ -218,6 +244,36 @@ shows what is active; `cg archive` moves a finished one to
 `state.ini` and context-guard 1.x's flat `.context-guard/` — in place and
 idempotently, preserving any recorded human approval it finds.
 
+## From a phased plan
+
+If a cycle was already planned as a phased `PLAN-N.md` — the artifact
+[disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold)
+produces after you talk a project through with an assistant — `cg new
+--from-plan` materialises it instead of you retyping it:
+
+```bash
+cg new redis --from-plan PLAN-3.md
+```
+
+One change per `## F<N>` phase, named `redis-f1`, `redis-f2`, … Each phase's
+prose and spec become its `objective.md`; its test items and acceptance
+criteria become `tasks.md` as `- [ ] N.M <text>`, the shape `cg next-task`
+already claims. `--phase F2` imports a single phase. Re-running skips changes
+that already exist (`SKIP|CHANGE_EXISTS|<name>`) rather than overwriting work
+in flight.
+
+`snapshot.md` stays `[PENDING]`: it records the state of the repository when
+work starts, which no plan written beforehand can know.
+
+**Importing does not approve anything.** Each change lands in PLAN with no
+approval in its manifest, so `cg commit --next-phase EXECUTE` still exits 6
+until a human runs `cg approve` — once per phase. A pre-written objective is
+still an unreviewed one.
+
+The full flow: talk the project through → `disciplined-scaffold` writes
+`PLAN-N.md` → `cg new --from-plan` → each phase executes under the same
+approval gate as any other change.
+
 ## Pre-commit hook
 
 `.githooks/pre-commit` rejects commits touching more than a threshold number
@@ -256,9 +312,7 @@ 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.
+`cg setup` installs the right one for each detected host.
 
 ## How this compares
 
@@ -279,6 +333,11 @@ 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.
 
+[disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold) is
+the lighter step before this one: markdown-only phase discipline, no
+transactional state. When a project outgrows it, `cg new --from-plan` reads
+the `PLAN-N.md` it produced — see [From a phased plan](#from-a-phased-plan).
+
 ## Development
 
 ```bash
@@ -289,7 +348,9 @@ 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()`.
+pattern. Tests write only under `tempfile.mkdtemp()`; the sole read-only
+fixtures on disk are the sample plans in `tests/fixtures/`, which exist
+because `--from-plan` parses documents rather than generating them.
 
 ## License
 

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/README.es.md

@@ -66,10 +66,20 @@ nada acá es un resumen ilustrativo.
 Dos líneas, una vez por máquina:
 
 ```bash
-pip install context-guard-cli
+uv tool install context-guard-cli
 cg setup
 ```
 
+¿No tenés `uv`? `pipx install context-guard-cli` hace lo mismo. Ambos
+instalan en un entorno aislado y dejan `cg` en el PATH global — que es el
+punto, porque `cg setup` configura tu máquina una vez, no una vez por
+proyecto. `pip install context-guard-cli` también funciona, como alternativa
+para una instalación de Python simple sin `uv`/`pipx` disponible. **No uses
+`uv pip install context-guard-cli`**: eso instala en el venv que esté activo
+en ese momento — el de un proyecto puntual, si estás parado adentro de
+uno — no en la máquina, lo que anula en silencio el sentido de un `cg setup`
+global.
+
 `cg setup` detecta Claude Code, OpenCode y Antigravity, instala los slash
 commands, y deja `cg approve` detrás del permission prompt de cada uno — ver
 [Adapters](#adapters-y-configuración-de-permisos). Imprime cada archivo que
@@ -91,6 +101,23 @@ cd context-guard && uv venv && uv pip install -e ".[dev]"
 git config core.hooksPath .githooks   # activa el gate de pre-commit de más abajo
 ```
 
+## Actualizar
+
+```bash
+uv tool upgrade context-guard-cli && cg setup
+```
+
+El segundo comando no es opcional. `cg setup` copia los comandos, skills y
+snippets de permisos dentro de la configuración de tus hosts; actualizar el
+paquete no toca esas copias, así que las correcciones de adapters de una
+versión nueva recién llegan a la máquina cuando se vuelve a correr
+`cg setup`. Es idempotente — se puede correr las veces que quieras.
+
+Las fases ya materializadas en un proyecto (`.context-guard/phases/`) nunca
+se sobrescriben, por diseño: cada proyecto conserva las fases con las que
+empezó, incluidas tus ediciones. Borrá el archivo de fase y corré `cg new`
+para traer la versión actual.
+
 ## Cómo funciona
 
 ```
@@ -163,6 +190,7 @@ garantía de corrección, y viene con un bypass auditado
 | Comando | Propósito |
 |---|---|
 | `cg new <nombre> --context <ruta>` | Crea un change y arranca PLAN |
+| `cg new <nombre> --from-plan <archivo> [--phase F2]` | Importa un `PLAN-N.md` por fases como un change por fase |
 | `cg list --context <ruta>` | Lista los changes activos y su fase |
 | `cg begin --phase <FASE> --context <ruta>` | Inicia una transacción para la fase dada |
 | `cg approve [--by <quién>] [--hotfix --reason "<texto>"]` | Solo humano: registra el visto bueno que `commit` exige para entrar a EXECUTE |
@@ -206,6 +234,36 @@ de forma independiente en el mismo proyecto. `cg new <nombre>` crea uno;
 1.x — in situ y de forma idempotente, preservando cualquier aprobación
 humana registrada que encuentre.
 
+## Desde un plan por fases
+
+Si el ciclo ya se planificó como un `PLAN-N.md` por fases — el artefacto que
+produce [disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold)
+después de debatir un proyecto con el asistente — `cg new --from-plan` lo
+materializa en vez de que lo retipees:
+
+```bash
+cg new redis --from-plan PLAN-3.md
+```
+
+Un change por cada fase `## F<N>`, nombrados `redis-f1`, `redis-f2`, … La
+prosa y el spec de cada fase se vuelven su `objective.md`; sus ítems de test
+y criterios de aceptación se vuelven `tasks.md` en formato `- [ ] N.M
+<texto>`, el que `cg next-task` ya reclama. `--phase F2` importa una sola
+fase. Re-ejecutar saltea los changes que ya existen
+(`SKIP|CHANGE_EXISTS|<nombre>`) en vez de pisar trabajo en curso.
+
+`snapshot.md` queda `[PENDING]`: registra el estado del repositorio al
+arrancar, que ningún plan escrito de antemano puede conocer.
+
+**Importar no aprueba nada.** Cada change entra en PLAN sin aprobación en su
+manifest, así que `cg commit --next-phase EXECUTE` sigue saliendo con código
+6 hasta que un humano corra `cg approve` — una vez por fase. Un objetivo
+pre-escrito sigue siendo un objetivo sin revisar.
+
+El flujo completo: debatir el proyecto → `disciplined-scaffold` escribe
+`PLAN-N.md` → `cg new --from-plan` → cada fase se ejecuta bajo el mismo gate
+de aprobación que cualquier otro change.
+
 ## Hook de pre-commit
 
 `.githooks/pre-commit` rechaza commits que tocan más de un umbral de
@@ -269,6 +327,11 @@ lo referido a convertir un prompt en un buen spec en primer lugar. Usá
 context-guard junto con cualquiera de ellos que ya te genere el
 `objective.md` — está diseñado para consumir uno, no para escribirlo.
 
+[disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold) es
+el paso liviano previo a este: disciplina de fases en markdown, sin estado
+transaccional. Cuando un proyecto lo supera, `cg new --from-plan` lee el
+`PLAN-N.md` que produjo — ver [Desde un plan por fases](#desde-un-plan-por-fases).
+
 ## Desarrollo
 
 ```bash
@@ -279,7 +342,10 @@ python -m unittest discover -s tests
 
 Framework: `unittest`. Cada fix se entrega con un test adversarial que
 reproduce el bypass que cierra; ver `tests/test_adversarial_*.py` para el
-patrón. Sin fixtures en disco fuera de `tempfile.mkdtemp()`.
+patrón. Los tests solo escriben bajo `tempfile.mkdtemp()`; los únicos
+fixtures en disco son los planes de ejemplo de solo lectura en
+`tests/fixtures/`, que existen porque `--from-plan` parsea documentos en vez
+de generarlos.
 
 ## Licencia
 

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/README.md

@@ -69,10 +69,19 @@ illustrative shorthand.
 Two lines, once per machine:
 
 ```bash
-pip install context-guard-cli
+uv tool install context-guard-cli
 cg setup
 ```
 
+No `uv`? `pipx install context-guard-cli` works the same way. Both install
+into an isolated environment and put `cg` on PATH globally — the whole point,
+since `cg setup` configures your machine once, not once per project.
+`pip install context-guard-cli` also works, as a fallback for a plain Python
+install with no `uv`/`pipx` available. **Do not use `uv pip install
+context-guard-cli`**: that installs into whichever venv is currently active —
+a single project's, if you happen to be inside one — not onto the machine,
+which silently defeats the point of a global `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
@@ -93,6 +102,22 @@ cd context-guard && uv venv && uv pip install -e ".[dev]"
 git config core.hooksPath .githooks   # activates the pre-commit gate below
 ```
 
+## Upgrading
+
+```bash
+uv tool upgrade context-guard-cli && cg setup
+```
+
+The second command is not optional. `cg setup` copies commands, skills and
+permission snippets into your host configs; upgrading the package does not
+touch those copies, so a new version's adapter fixes only reach a machine
+once `cg setup` runs again. It is idempotent — safe to run any time.
+
+Phase files already materialised in a project (`.context-guard/phases/`)
+are never overwritten, by design: a project keeps the phases it was started
+with, including your edits. Delete a phase file and run `cg new` to pull the
+current version.
+
 ## How it works
 
 ```
@@ -163,6 +188,7 @@ unconditional block just gets `--no-verify`d, which leaves no trace at all.
 | Command | Purpose |
 |---|---|
 | `cg new <name> --context <path>` | Create a change and begin PLAN |
+| `cg new <name> --from-plan <file> [--phase F2]` | Import a phased `PLAN-N.md` as one change per phase |
 | `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 |
@@ -205,6 +231,36 @@ shows what is active; `cg archive` moves a finished one to
 `state.ini` and context-guard 1.x's flat `.context-guard/` — in place and
 idempotently, preserving any recorded human approval it finds.
 
+## From a phased plan
+
+If a cycle was already planned as a phased `PLAN-N.md` — the artifact
+[disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold)
+produces after you talk a project through with an assistant — `cg new
+--from-plan` materialises it instead of you retyping it:
+
+```bash
+cg new redis --from-plan PLAN-3.md
+```
+
+One change per `## F<N>` phase, named `redis-f1`, `redis-f2`, … Each phase's
+prose and spec become its `objective.md`; its test items and acceptance
+criteria become `tasks.md` as `- [ ] N.M <text>`, the shape `cg next-task`
+already claims. `--phase F2` imports a single phase. Re-running skips changes
+that already exist (`SKIP|CHANGE_EXISTS|<name>`) rather than overwriting work
+in flight.
+
+`snapshot.md` stays `[PENDING]`: it records the state of the repository when
+work starts, which no plan written beforehand can know.
+
+**Importing does not approve anything.** Each change lands in PLAN with no
+approval in its manifest, so `cg commit --next-phase EXECUTE` still exits 6
+until a human runs `cg approve` — once per phase. A pre-written objective is
+still an unreviewed one.
+
+The full flow: talk the project through → `disciplined-scaffold` writes
+`PLAN-N.md` → `cg new --from-plan` → each phase executes under the same
+approval gate as any other change.
+
 ## Pre-commit hook
 
 `.githooks/pre-commit` rejects commits touching more than a threshold number
@@ -243,9 +299,7 @@ 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.
+`cg setup` installs the right one for each detected host.
 
 ## How this compares
 
@@ -266,6 +320,11 @@ 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.
 
+[disciplined-scaffold](https://github.com/fdomerlo/disciplined-scaffold) is
+the lighter step before this one: markdown-only phase discipline, no
+transactional state. When a project outgrows it, `cg new --from-plan` reads
+the `PLAN-N.md` it produced — see [From a phased plan](#from-a-phased-plan).
+
 ## Development
 
 ```bash
@@ -276,7 +335,9 @@ 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()`.
+pattern. Tests write only under `tempfile.mkdtemp()`; the sole read-only
+fixtures on disk are the sample plans in `tests/fixtures/`, which exist
+because `--from-plan` parses documents rather than generating them.
 
 ## License
 

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/TUTORIAL.es.md

@@ -37,7 +37,7 @@ Una aclaración honesta, porque este proyecto se toma en serio la honestidad: co
 Abrí la terminal y corré:
 
 ```bash
-pip install context-guard-cli
+uv tool install context-guard-cli
 cg setup
 ```
 
@@ -48,8 +48,14 @@ aprobación (paso 4). Al terminar imprime la lista exacta de archivos que
 tocó — nada oculto. Podés correrlo las veces que quieras: si ya está
 instalado, no duplica nada.
 
-*(Si usás `uv`, que es más rápido: `uv tool install context-guard-cli` y
-después `cg setup`.)*
+¿No tenés `uv`? `pipx install context-guard-cli` hace lo mismo. Si ninguno de
+los dos está disponible, `pip install context-guard-cli` también funciona,
+como alternativa.
+
+> **Ojo con esta:** `uv pip install context-guard-cli` *no* es lo mismo que
+> `uv tool install`. Instala la herramienta adentro del entorno virtual de
+> tu proyecto actual, no en tu máquina — y `cg setup` necesita que `cg` esté
+> disponible en cualquier terminal, no solo dentro de ese proyecto.
 
 Verificá que quedó todo:
 
@@ -64,9 +70,40 @@ herramienta; todo lo que hagas con context-guard empieza con `cg`.
 un cambio en un proyecto nuevo, `cg new` escribe ahí lo que falte. No
 necesitás descargar este repositorio ni copiar archivos a mano.
 
-> **Si algo falla:** el error más común es que `pip` instaló pero la terminal
-> no encuentra `cg`. Cerrá y reabrí la terminal. Si persiste, probá
-> `python3 -m pip install --user context-guard-cli` y de nuevo cerrar/reabrir.
+> **¿Dónde quedó instalado?** `uv tool install` y `pipx` ponen `cg` en un
+> directorio propio (`~/.local/bin` en Linux/macOS típicamente) y lo agregan
+> al PATH por vos. `pip install` sin `--user` lo deja donde viva tu Python
+> del sistema; con `--user`, en `~/.local/bin` también. Si el paso de
+> verificación de arriba no encuentra `cg`, es casi siempre esto: el
+> directorio existe pero tu terminal no lo tiene en el PATH todavía.
+
+> **Si algo falla:** el error más común es que la instalación terminó bien
+> pero la terminal no encuentra `cg`. Cerrá y reabrí la terminal. Si
+> persiste, probá `python3 -m pip install --user context-guard-cli` y de
+> nuevo cerrar/reabrir.
+
+---
+
+## 3.1. Cómo actualizar
+
+Cuando salga una versión nueva, dos comandos en uno:
+
+```bash
+uv tool upgrade context-guard-cli && cg setup
+```
+
+*(Con pipx: `pipx upgrade context-guard-cli && cg setup`.)*
+
+**Por qué son dos y no uno:** el primero actualiza el programa; el segundo
+vuelve a copiar los comandos y la configuración dentro de tu asistente. Si
+hacés solo el primero, tu asistente sigue usando las instrucciones viejas y
+las mejoras de la versión nueva no aparecen. Correr `cg setup` de más nunca
+rompe nada.
+
+**Tus proyectos viejos siguen como estaban.** Las guías de fase que se
+copiaron dentro de cada proyecto no se pisan al actualizar — a propósito,
+para no borrar cambios que hayas hecho. Los proyectos nuevos arrancan con
+las guías actualizadas.
 
 ---
 
@@ -172,7 +209,8 @@ Diagnostica y libera lo que quedó colgado de procesos muertos. Nunca resuelvas
 | Ver el avance | `cg status` | — |
 | Retomar tras un corte | `/cg-continue` | Continúa donde quedó |
 | Destrabar | `cg doctor --fix` | — |
+| Actualizar | `uv tool upgrade context-guard-cli && cg setup` | — |
 
-Instalación (una vez): `pip install context-guard-cli` y luego `cg setup` una vez por máquina.
+Instalación (una vez): `uv tool install context-guard-cli` y luego `cg setup` una vez por máquina.
 
 Documentación completa, en inglés y español, en el [repositorio](https://github.com/fdomerlo/context-guard).

context_guard_cli-2.4.0/context_guard/_data/hosts/antigravity/skills/context-guard/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: context-guard
+description: >-
+  Use when the user asks to build, implement, or scaffold an application or
+  feature; for any multi-step coding task; to resume work after a lost,
+  crashed or compacted session; or in any project that already contains a
+  `.context-guard/` directory. Drives the `cg` CLI so a phase-governed change
+  keeps its plan, its progress and its verification on disk instead of in
+  the conversation.
+---
+
+<!-- context-guard:begin -->
+# context-guard
+
+`cg` (long form: `context-guard`) is a transactional state manager. A change
+moves through fixed phases and nothing advances without passing that phase's
+gate, so a session that dies mid-task resumes instead of restarting.
+
+## The pipeline
+
+```
+PLAN --approve--> EXECUTE --tasks done--> VERIFY --approve--> ARCHIVE
+```
+
+| Phase   | Produces                               | Gate to leave it              |
+|---------|----------------------------------------|-------------------------------|
+| PLAN    | `objective.md`, `tasks.md`             | human approval, then `commit` |
+| EXECUTE | code changes, `tasks.md` checked off   | every task checked off        |
+| VERIFY  | `review-report.md`, `verify-report.md` | human approval, then archive  |
+
+`cg commit` rejects any transition outside that order.
+
+## On entering a phase, read that phase's file
+
+The full instructions live in `.context-guard/phases/plan.md`,
+`.context-guard/phases/execute.md` and `.context-guard/phases/verify.md` —
+not in this skill. Load the file for the phase you are entering and follow
+it exactly.
+
+## Commands
+
+- `cg new <name>` — scaffold a change, open PLAN, write the phase files.
+- `cg status` — what phase the change is in and what is still pending. Run
+  this first when resuming, before reading any code.
+- `cg next-task` — the next unchecked task, during EXECUTE.
+- `cg commit --next-phase <PHASE>` — advance, once the gate passes.
+- `cg list`, `cg validate`, `cg checkpoint`, `cg rollback` — inspect, check,
+  snapshot, undo.
+
+Every command takes `--change <name>`. Pass it whenever more than one change
+is active: `cg` errors rather than guessing which one you meant.
+
+## `cg approve` is human-only
+
+Never run `cg approve` yourself, and never run it "on behalf of" the user.
+When `cg commit` exits 6 (`APPROVAL_REQUIRED`), stop, show the human the
+artifacts the gate covers, and ask them to run the approval themselves.
+Editing `.context-guard/**/manifest.json` by hand is the same violation by
+another route: it forges the state the gate reads.
+<!-- context-guard:end -->

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/context_guard/_data/phases/plan.md

@@ -122,8 +122,13 @@ 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`.
+auto-generates a checkpoint of the DAG state.
+
+Report to the user that PLAN is locked and EXECUTE is open. Then, in this
+same turn, load `.context-guard/phases/execute.md` and continue directly —
+do not wait for `/cg-continue`. Only stop and suggest `/cg-continue` if you
+are ending the turn for an unrelated reason, or the session might not
+continue (e.g., you are about to hit a context limit).
 
 ## Rules
 

{context_guard_cli-2.1.0 → context_guard_cli-2.4.0}/context_guard/guard/cli.py

@@ -12,6 +12,7 @@ from .commands import (
     cmd_approve,
     cmd_check_lock,
     cmd_new,
+    cmd_new_from_plan,
     cmd_setup,
     cmd_list,
     cmd_migrate,
@@ -135,6 +136,14 @@ def parse_args(argv=None):
                        help="Also materialise this host's workspace files "
                             "(Antigravity's rule file). Detected automatically "
                             "when omitted.")
+    p_new.add_argument("--from-plan", dest="from_plan", default=None,
+                       help="Import a phased PLAN-N.md, creating one change "
+                            "per phase (<name>-f1, <name>-f2, ...) with "
+                            "objective.md and tasks.md derived from it. The "
+                            "approval gate is unchanged: each change still "
+                            "needs cg approve to reach EXECUTE.")
+    p_new.add_argument("--phase", default=None,
+                       help="With --from-plan, import only this phase (e.g. F2).")
 
     # setup takes no --context: it configures hosts, not a change. --project
     # opts back into 2.0's per-project install for teams committing the config.
@@ -180,7 +189,12 @@ def dispatch(args):
     """
     change = getattr(args, "change", None)
     handlers = {
-        "new": lambda: cmd_new(args.context, args.name, args.host),
+        "new": lambda: (
+            cmd_new_from_plan(args.context, args.name, args.from_plan,
+                              phase=args.phase, host=args.host)
+            if args.from_plan
+            else cmd_new(args.context, args.name, args.host)
+        ),
         "setup": lambda: cmd_setup(
             host=args.host, with_mcp=args.with_mcp, project=args.project,
             no_hooks=args.no_hooks),