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

{context_guard_cli-2.2.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, 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.4.0}/CHANGELOG.md

@@ -6,6 +6,40 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-guard-cli
-Version: 2.2.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
@@ -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
@@ -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.4.0}/README.es.md

@@ -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
@@ -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.4.0}/README.md

@@ -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
@@ -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.4.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.2.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.2.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),

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

@@ -29,6 +29,12 @@ 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,
     diverged_phases,
@@ -141,6 +147,73 @@ def cmd_new(context, change, host=None):
     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.