context-guard-cli 2.2.0__tar.gz → 2.5.0__tar.gz

{context_guard_cli-2.2.0 → context_guard_cli-2.5.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, v2.2]
+    branches: [main, 'v[0-9]*']
   pull_request:
-    branches: [main, v2, v2.1, v2.2]
+    branches: [main]
 
 jobs:
   test:

{context_guard_cli-2.2.0 → context_guard_cli-2.5.0}/.gitignore

@@ -8,3 +8,5 @@ dist/
 PLAN.md
 PLAN-2.1.md
 RUNBOOK_HUMANO.md
+.claude/*.local.json
+uv.lock

{context_guard_cli-2.2.0 → context_guard_cli-2.5.0}/CHANGELOG.md

@@ -6,6 +6,62 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ---
 
+## [2.5.0] - 2026-09-03
+
+### Added
+
+- Support for Cursor as a host adapter: `cg setup --host cursor` installs
+  `.cursor/rules/context-guard.mdc` (both globally in `~/.cursor/rules` and
+  per-project) and optionally registers `context-guard-mcp` in `.cursor/mcp.json`
+  via `--with-mcp`.
+- `cg new` automatically detects Cursor and materialises `.cursor/rules/context-guard.mdc`
+  in newly created changes.
+- Documentation for Cursor's cooperative approval gate model in
+  `docs/adapters/cursor/PERMISSIONS.md`.
+
+### Changed
+
+- Unified Gemini/Antigravity global skill installation path to
+  `~/.gemini/config/skills/context-guard/SKILL.md` (the canonical machine-local
+  configuration root shared across Gemini CLI, IDE, Desktop, and ACP).
+  This fixes broken symlinks when `~/.gemini/config/skills/` was not yet created.
+  Any legacy owned skill file at `~/.gemini/antigravity-cli/skills/context-guard/SKILL.md`
+  is cleaned up automatically on setup.
+
+## [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

{context_guard_cli-2.2.0 → context_guard_cli-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: context-guard-cli
-Version: 2.2.0
+Version: 2.5.0
 Summary: The transactional memory layer for AI coding agents — your context survives crashes, compaction, and session loss
 License-Expression: MIT
 License-File: LICENSE
@@ -95,7 +95,7 @@ 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
+`cg setup` detects Claude Code, OpenCode, Antigravity and Cursor, 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.
@@ -201,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 |
@@ -243,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
@@ -276,7 +307,7 @@ an open transaction). Activate it once per clone with
 ## Adapters and permission configuration
 
 Thin, per-harness wrappers ship inside the package under
-`context_guard/_data/hosts/{claude-code,opencode,antigravity}/` — each points
+`context_guard/_data/hosts/{claude-code,opencode,antigravity,cursor}/` — 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
@@ -302,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
@@ -312,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.2.0 → context_guard_cli-2.5.0}/README.es.md

@@ -80,7 +80,7 @@ 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
+`cg setup` detecta Claude Code, OpenCode, Antigravity y Cursor, 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
 tocó, y correrlo de nuevo no cambia nada.
@@ -190,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 |
@@ -233,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
@@ -266,7 +297,7 @@ fase completada o una transacción abierta). Activalo una vez por clon con
 ## Adapters y configuración de permisos
 
 Dentro del paquete, en `context_guard/_data/hosts/{claude-code,opencode,
-antigravity}/`, viven wrappers finos por harness — cada uno apunta a
+antigravity,cursor}/`, viven wrappers finos por harness — cada uno apunta a
 `phases/{plan,execute,verify}.md` en vez de duplicarlos. Cómo poner
 `cg approve` detrás del permission prompt de cada harness está documentado en
 [docs/adapters/](docs/adapters/), un `PERMISSIONS.md` por host, junto con el
@@ -296,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
@@ -306,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.2.0 → context_guard_cli-2.5.0}/README.md

@@ -82,7 +82,7 @@ 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
+`cg setup` detects Claude Code, OpenCode, Antigravity and Cursor, 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.
@@ -188,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 |
@@ -230,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
@@ -263,7 +294,7 @@ an open transaction). Activate it once per clone with
 ## Adapters and permission configuration
 
 Thin, per-harness wrappers ship inside the package under
-`context_guard/_data/hosts/{claude-code,opencode,antigravity}/` — each points
+`context_guard/_data/hosts/{claude-code,opencode,antigravity,cursor}/` — 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
@@ -289,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
@@ -299,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.2.0 → context_guard_cli-2.5.0}/TUTORIAL.es.md

@@ -1,6 +1,6 @@
 # Tutorial: memoria persistente para tu asistente de programación con context-guard
 
-*Para personas que usan asistentes de IA (Claude Code, OpenCode, Antigravity) y quieren que no se olviden de lo que estaban haciendo. No hace falta ser experto: si sabés abrir una terminal y copiar comandos, podés seguir esta guía.*
+*Para personas que usan asistentes de IA (Claude Code, OpenCode, Antigravity, Cursor) y quieren que no se olviden de lo que estaban haciendo. No hace falta ser experto: si sabés abrir una terminal y copiar comandos, podés seguir esta guía.*
 
 ---
 
@@ -27,7 +27,7 @@ Una aclaración honesta, porque este proyecto se toma en serio la honestidad: co
 - **Una computadora con terminal.** macOS, Linux, o Windows con WSL.
 - **Python 3.10 o más nuevo.** Verificalo con `python3 --version`. Si no lo tenés, instalalo desde [python.org](https://www.python.org/downloads/).
 - **git.** Verificalo con `git --version`.
-- **Un asistente de programación instalado**: Claude Code, OpenCode o Antigravity. Cualquiera de los tres funciona; los comandos del asistente son los mismos.
+- **Un asistente de programación instalado**: Claude Code, OpenCode, Antigravity o Cursor. Cualquiera funciona; los comandos del asistente son los mismos.
 - **Un proyecto** donde trabajar. Puede ser uno existente o una carpeta nueva; solo necesita ser un repositorio git (si no lo es, entrá a la carpeta y corré `git init`).
 
 ---

{context_guard_cli-2.2.0 → context_guard_cli-2.5.0}/context_guard/_data/hosts/antigravity/skills/context-guard/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: context-guard
 description: >-
-  Use when the user asks for a multi-step coding task, when they ask 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.
+  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_cli-2.5.0/context_guard/_data/hosts/cursor/mcp.snippet.json

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

context_guard_cli-2.5.0/context_guard/_data/hosts/cursor/rules/context-guard.mdc

@@ -0,0 +1,20 @@
+---
+description: Active persistence contract and phase discipline for context-guard
+globs: 
+alwaysApply: true
+---
+<!-- 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.2.0 → context_guard_cli-2.5.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.2.0 → context_guard_cli-2.5.0}/context_guard/guard/assets.py

@@ -17,7 +17,7 @@ from .errors import EXIT_GENERIC, GuardError
 
 PHASES = ("plan", "execute", "verify")
 
-HOSTS = ("claude-code", "opencode", "antigravity")
+HOSTS = ("claude-code", "opencode", "antigravity", "cursor")
 
 # 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,
@@ -26,6 +26,7 @@ SNIPPETS = {
     "claude-code": ("settings", "mcp"),
     "opencode": ("agent", "permissions", "mcp"),
     "antigravity": ("hooks",),
+    "cursor": ("mcp",),
 }
 
 
@@ -62,8 +63,7 @@ def iter_host_files(host):
     `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.
-    """
+    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)})")
 

{context_guard_cli-2.2.0 → context_guard_cli-2.5.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,
@@ -130,16 +131,24 @@ def parse_args(argv=None):
     p_new = subparsers.add_parser("new")
     p_new.add_argument("--context", default=".")
     p_new.add_argument("name")
-    p_new.add_argument("--host", choices=["claude", "opencode", "antigravity"],
+    p_new.add_argument("--host", choices=["claude", "opencode", "antigravity", "cursor"],
                        default=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.
     p_setup = subparsers.add_parser("setup")
-    p_setup.add_argument("--host", choices=["claude", "opencode", "antigravity", "all"],
+    p_setup.add_argument("--host", choices=["claude", "opencode", "antigravity", "cursor", "all"],
                          default="all")
     p_setup.add_argument("--with-mcp", action="store_true",
                          help="Also register the context-guard-mcp server. "
@@ -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),

{context_guard_cli-2.2.0 → context_guard_cli-2.5.0}/context_guard/guard/commands.py

@@ -29,10 +29,18 @@ from .transaction import (
     cmd_checkpoint,
 )
 from .migrate import cmd_migrate
+from .plan_import import (
+    neutralize_sentinel,
+    parse_plan,
+    phase_objective,
+    phase_tasks,
+)
 from .setup import (
     antigravity_detected,
+    cursor_detected,
     diverged_phases,
     materialise_antigravity_rule,
+    materialise_cursor_rule,
     materialise_phases,
     run_setup,
 )
@@ -137,10 +145,79 @@ def cmd_new(context, change, host=None):
     materialise_phases(context)
     if host == "antigravity" or (host is None and antigravity_detected()):
         materialise_antigravity_rule(context)
+    if host == "cursor" or (host is None and cursor_detected()):
+        materialise_cursor_rule(context)
 
     return CommandResult(f"SUCCESS|CHANGE_CREATED|{name}|phase=PLAN", EXIT_OK)
 
 
+def cmd_new_from_plan(context, change, plan_path, phase=None, host=None):
+    """Materialise a phased PLAN-N.md as one change per phase.
+
+    Each change is created through cmd_new — the scaffolding logic is not
+    forked — and only then are objective.md and tasks.md overwritten with the
+    content derived from the plan. snapshot.md is deliberately left [PENDING]:
+    it records the state of the repository at the moment work starts, which no
+    plan can know in advance.
+
+    A pre-written objective is not an approved one. The change lands in PLAN
+    with no `approval` in its manifest, so the commit into EXECUTE still fails
+    with APPROVAL_REQUIRED until a human runs `cg approve`.
+    """
+    # Parsed before anything is created: a plan with no phases must leave no
+    # half-imported changes behind.
+    plan = parse_plan(plan_path)
+
+    selected = plan.phases
+    if phase is not None:
+        wanted = phase.strip().upper()
+        selected = [p for p in plan.phases if p.id == wanted]
+        if not selected:
+            available = ",".join(p.id for p in plan.phases)
+            return CommandResult(
+                f"FAIL|PHASE_NOT_IN_PLAN|{phase}|available={available}",
+                EXIT_VALIDATION,
+            )
+
+    lines = []
+    created = 0
+    for p in selected:
+        change_name = f"{change}-{p.id.lower()}"
+        result = cmd_new(context, change_name, host=host)
+
+        if result.exit_code != EXIT_OK:
+            if "CHANGE_EXISTS" in result.message:
+                # Never overwrite a change already in flight.
+                lines.append(f"SKIP|CHANGE_EXISTS|{change_name}")
+                continue
+            return result
+
+        paths = get_paths(context, change_name)
+        created += 1
+        lines.append(f"SUCCESS|CHANGE_CREATED|{change_name}|phase=PLAN")
+
+        derived = {
+            "objective.md": phase_objective(plan, p),
+            "tasks.md": phase_tasks(plan, p),
+        }
+        for filename, content in derived.items():
+            # A plan quoting the scaffold sentinel would otherwise write a
+            # change the hard gate refuses as unfilled. Reported, never silent.
+            content, neutralized = neutralize_sentinel(content)
+            _write_artifact(paths["base"], filename, content)
+            if neutralized:
+                lines.append(
+                    f"NOTE|SENTINEL_NEUTRALIZED|{change_name}|{filename}")
+
+    lines.append(f"IMPORTED|{created}|from={os.path.basename(plan_path)}")
+    return CommandResult("\n".join(lines), EXIT_OK)
+
+
+def _write_artifact(base_dir, filename, content):
+    with open(os.path.join(base_dir, filename), "w", encoding="utf-8") as f:
+        f.write(content)
+
+
 def cmd_list(context):
     """Lista los changes activos con su fase actual.