@tacuchi/agent-workflow-cli 20.26.0 → 21.1.0

package/skills/w/loops/CODE-POLICIES.md

@@ -1,17 +1,27 @@
 # CODE-POLICIES — policies for code-editing loops
 
-They apply to **`plan-exec-loop`** (per plan phase) and **`quick-loop`** (the single task; **proportional** gate): each orders this doc read from its `## Inherits`, **together with the chassis** ([`CHASSIS.md`](CHASSIS.md)). The document loops (spec-refine, plan-new, plan-refine) edit no code and do **not** load this doc — that is why it lives apart from the chassis. These policies materialize the **DB scripts-only** and **safe git** invariants — which also stay summarized **inline** (1-2 lines) in each code-editing loop's `LOOP.md`, because advisory hosts do not follow Reads; the full normative text lives here.
+They apply to **`plan-exec-loop`** (per effective batch) and **`quick-loop`** (the single task;
+**proportional** gate): each reads this doc with the chassis. Document loops do not edit code and
+do not load it. These policies own the DB scripts-only, safe Git and closing-review invariants;
+code loops keep only a short inline floor for advisory hosts.
 
 ## Safe git — verified branch + proposed commits
 
-- **Before editing** a source's files: verify current branch = that source's expected branch (`aw check-branch --source <alias>`; see the `git` role). On mismatch → **pause and resolve with the human**; never `stash`/`reset --hard`/`checkout -- .`/`clean` without per-source confirmation.
-- **Proposed commits** (propose-then-execute, approve before): **after the closing review gate passes** (below), propose commits **per source** — in plan-exec at each phase close (or on `Cerrar`); in quick, **a single commit** at the end if there were code changes. Never `push`/`--amend`/`--no-verify`. Nothing reaches a proposed commit without review.
-- **Rejected commit**: the changes **stay in the working tree** (never reverted). Re-proposing / editing the message is allowed. Record in `CHECKPOINT` + `BACKLOG` that the phase/task remained **uncommitted** (resumable).
-- **Between-phase precondition** (plan-exec): `branch-check` validates branch *identity*, **not** working-tree *cleanliness*. Before starting the next phase, each source's working tree must be **clean** (committed) or explicitly **acknowledged** as "uncommitted changes from phase N" — so two phases never co-mingle in one commit.
+Sources are edited on a **verified** branch (`aw check-branch`), and the unit's commits are
+**proposed**: exactly one commit per affected source — at effective-batch close in plan-exec, at task
+close in quick — never `push`/`--amend`/`--no-verify`, and never a destructive clean or a branch
+switch without confirmation. A **rejected** commit leaves the changes in the tree and the unit
+recorded as uncommitted in `CHECKPOINT` and `BACKLOG`. Between units each working tree is clean or
+explicitly acknowledged; a `continuous` batch is the narrow exception that intentionally co-mingles
+its internal phases in one reviewed commit, and no batch may co-mingle with another.
+
+> **When the branch is verified, when a commit becomes available and what an approval covers is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Approving is the person's act and committing is a separate effect that comes back as the sources' real git state — which is also what makes "the checks passed" impossible to assert without having run them.
 
 ## Closing review gate (conventions, pre-commit)
 
-After validation (of the phase in plan-exec; of the task in quick, proportional) and **before proposing its commits** (also on an early `Cerrar`, before proposing the pending commits), the diff passes a **closing review gate**:
+After validation and before commits, the whole execution-unit diff passes a **closing review
+gate**: an effective batch in plan-exec, or the proportional task in quick. Early `Cerrar` uses the
+same gate before any pending commit.
 
 - **Independent re-read** of the diff (subagent or clean re-read — the engine's *independent verification*: it does not assume the implementation is correct; *only command output counts*).
 - **Apply the installed ambient conventions** relevant to the touched stack (code/stack standards, security, diff review, the workspace's own families) — the host **auto-discovers them by `description`**. Workline **names and binds no** concrete conventions skill: **it creates the moment; the installed skills fill it** (that is why review is **not a role** — see [`../roles/README.md`](../roles/README.md)). With no convention skills installed → minimal generic checklist: SOLID/early-return, clear names, DRY, no silenced errors, no secrets/PII, parametrized SQL, no dead code, + the plan's `Validations` (if any).
@@ -20,9 +30,8 @@ After validation (of the phase in plan-exec; of the task in quick, proportional)
 - **Temporary simulation check** (only when the change carries one): stubs, fakes and in-memory adapters are **explicit and named as such** (`Stub…` / `Fake…`), they sit at the boundary the plan declares, and no configuration can select them in a production runtime. A simulation still active on the main path with no declared removal is a finding, not a detail.
 - **Tooling check** (`docs/tools`): did the run create **reusable auxiliary tooling** (support scripts/CLIs/generators/reusable configs — not product code, not session probes)? → the host applies the **ambient `creating-tools` skill** (auto-discovered by its `description`; Workline does not bind it) so the tool gets its home under `docs/tools/<slug>/` (README + run/output structure per that skill's contract + its index row). Host without such a skill → the loop still **never writes `docs/tools` itself**: **declare the gap** — the homeless tool goes to the plan's `Open questions` + `BACKLOG` (in quick, `BACKLOG`) — never silent.
 - **Findings**: **fix** them in the working tree and **re-run validation** (the gate does not replace the tests: it re-verifies after fixing), or **defer them justified** (→ the plan's `Open questions` + `BACKLOG`; in quick, `BACKLOG`); the non-obvious → `DECISION`. Gate integrity (see [`CHASSIS.md`](CHASSIS.md) § *Verification-first*): never weaken a check or lower a convention to pass.
-- **Artifact-first + verification-first**: `CHECKPOINT.Next = "review <phase/task>"` before the pass; `SESSION.Success criteria` includes from the start "the diff passed the review gate before its commits".
-
-Only with the gate green are the commits proposed.
+- **Artifact-first + verification-first**: seed `CHECKPOINT.Next = "review <batch/task>"`; Success
+  criteria require the whole diff to pass before commits.
 
 ## Location
 

package/skills/w/loops/README.md

@@ -47,7 +47,7 @@ The **5 loops** are heirs: they use `## Inherits` (a one-line reference to [`CHA
 
 ## Chassis / heirs
 
-The **engine lives in [`CHASSIS.md`](CHASSIS.md)** (a referenced doc, not a skill); the 5 loops — including `spec-refine-loop` — are **heirs** of that engine. The canonical heirs list and their deltas live in the chassis itself (§ *Heirs*). The chassis is **not a bindable capability**: it is the loop engine; what is pluggable are the **capabilities** a loop composes (e.g. `ui-design`, `sql`, `git`), resolved via `.workflow/skills.toml`.
+The **engine lives in [`CHASSIS.md`](CHASSIS.md)** (a referenced doc, not a skill); the 5 loops — including `spec-refine-loop` — are **heirs** of that engine. The canonical heirs list and their deltas live in the chassis itself (§ *Heirs*). The chassis is **not a bindable capability**: it is the loop engine; what is pluggable are the **capabilities** a loop composes (e.g. `design`, `sql`, `git`), resolved via `.workflow/skills.toml`.
 
 ## Composed capabilities (roles)
 

package/skills/w/loops/plan-exec-loop/LOOP.md

@@ -2,12 +2,10 @@
 name: plan-exec-loop
 description: >-
   Executes an implementation plan (docs/plans/PPP-plan-<slug>.md) as a living
-  doc: runs it phase by phase — each phase a verifiable state — while editing
-  the real code and managing DB and git. Heir of the chassis (loops/CHASSIS.md
-  + CODE-POLICIES.md). Deltas: executability entry gate, deviation gate
-  (structural to plan-refine, functional to spec-refine), single resumable
-  session, safe git, DB scripts-only, phase proof plus progressive tests,
-  pre-commit closing review gate, no auto-export. Composes git and sql.
+  doc: re-infers isolated or continuous phase batches, edits real code, then
+  validates/reviews/commits each effective batch. Heir of CHASSIS.md and
+  CODE-POLICIES.md. Keeps the executability and deviation gates, one resumable
+  session, safe git, DB scripts-only and no auto-export. Composes git and sql.
   Started by /w:plan-exec. Invoke to implement an already generated plan.
 ---
 
@@ -25,7 +23,7 @@ PLAN
 `/w:plan-exec` — **resumable** (same chassis mechanism; here resume keys off the plan-doc phase states + checkboxes + CHECKPOINT, see Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument) **and its source spec** (resolved through the plan's `## Origin`) — the entry gate reads both. It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) — plan-refine is auxiliary, not mandatory; no gate requires it. What it does require is an **executable shape** (§ *Entry gate — executability*). If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument) **and its source spec** (resolved through the plan's `## Origin`) — the entry gate reads both. It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) — plan-refine is auxiliary, not mandatory; no gate requires it. What it does require is an **executable shape** (§ *Entry gate — executability*). If the plan pins design, it also reads the **UI Design Package** revisions its `## Design references` and its tasks name — **read-only**, at the exact revision each one fixed (§ *Design precondition gate*).
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: phase/task state, `Open questions`).
@@ -40,6 +38,10 @@ Full rule in the chassis (§ *docs/ boundary — no auto-export*). Here: the onl
 
 Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **and** **[`../CODE-POLICIES.md`](../CODE-POLICIES.md)** — the *code-editing loop policies* — **always before** these deltas. *(If `../` does not resolve: same names next to this file — global layout rule, chassis § Reference resolution.)*
 
+Read the shared execution-unit contract in
+[`PLAN-EXECUTION-BATCHES`](../../modules/PLAN-EXECUTION-BATCHES.md); it owns batch syntax,
+inference, the deferred-validation cycle and conditional Git authorization.
+
 ## Composes
 
 `git` (safe branch + proposed commits) · `sql` (DB rule). Both resolved via `.workflow/skills.toml`; `off` → the loop continues without the capability and, if it was needed, says so or asks.
@@ -65,27 +67,72 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 Execution **no longer accepts in silence** a plan that would force it to invent its own structure. Two outcomes:
 
-- **Minor gap** — the plan is all but executable: an exit condition derivable from what is already written, the obvious evidence unnamed, micro-tasks to group. `plan-exec` may **normalize it with consent** — one structured-choice content question, labels `Normalizar y ejecutar` (recommended) | `Ir a plan-refine`. Normalizing edits the `### Fn` blocks in place, **adds no scope and moves no boundary**, and is recorded in `DECISION` + `CHECKPOINT`.
+- **Minor gap** — the plan is all but executable: an exit condition derivable from what is already written, the obvious evidence unnamed, micro-tasks to group. Normalizing edits the `### Fn` blocks in place, **adds no scope and moves no boundary**, and is recorded in `DECISION` + `CHECKPOINT`.
 - **Structural gap** — phases, contracts or journey are missing, or a change that **does** carry temporary behavior leaves its boundary undeclared. It does **not** improvise: record the finding in `CHECKPOINT`, hand off to [`plan-refine-loop`](../plan-refine-loop/LOOP.md) (`/w:plan-refine`) and resume execution over the refined plan.
 
+> **Which outcome a declared gap produces, and whether anybody is asked to consent, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Normalization is offered on a minor gap and on nothing else — a structural one is not something to consent to.
+
 > **A missing `Límite de simulación` is a gap only when there is something to simulate.** No task and no phase introduces temporary behavior → the block is legitimately absent and the gate passes; demanding it anyway pushes execution to invent a stub so the plan matches a template. The same holds for `Diferido` and every other conditional block.
 
 > The gate reads the **canonical phase contract** from [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Phase contract (canonical)* — required sections, the `> Estado:` vocabulary, semantic granularity. Execution references it; it never redefines it. The marker is a **line of its own** inside the `### Fn` block (`> Estado: <value>`); written any other way it reads as `pendiente`.
 
-## Delta 1 — One session per run; the phase cycle in the plan-doc
-
-- Walks the plan's `### Fn` blocks under `## Tasks` in order (respecting deps) **inside the run's single session** (no session-per-phase). *(Legacy plans: a separate `## Phases` table — walk it the same way.)*
-- **Phase cycle** (artifact-first, one per `### Fn`): read `Resultado` + `Condición de salida` → confirm the initial state → flip `> Estado: en ejecución` and seed `CHECKPOINT.Next` → execute its tasks → run the phase proof plus the justified focused tests (Delta 4). Then: closing review gate over the phase's whole diff (Delta 5) → confirm the `Condición de salida` → flip `> Estado: validada` → update `CHECKPOINT` and propose commits (Delta 2).
+After this gate and before editing, infer the effective batches over pending phases. The live
+checkout may merge or split the plan's declaration without consent; record the result and drift in
+`CHECKPOINT`. A missing `## Execution batches` is legacy compatibility, not an entry gap.
+
+## Design precondition gate (fail-closed, per task)
+
+Applies **only** to a task that pins design (`DES-001@r4 / SCR-002@r2#empty`). Run
+`aw designs --plan <plan-doc>` before implementing the batch; it answers per task
+and the verdict is the command's, not the implementer's.
+
+**Four causes block, and each names the artifact and the corrective action:** the
+reference does not resolve · its digest no longer matches the bytes · the revision
+is **revoked** · the applicable **closure** does not reach `handoff`. A blocked
+task is not implemented, its phase stays `en ejecución` or `bloqueada`, and the
+correction goes to `/w:plan-refine` — or to `/w:spec-refine` when it changes
+behavior or acceptance.
+
+**One cause only warns:** a revision **superseded** by a newer one but intact
+stays executable. Publishing `@r5` never invalidates the `@r4` a task pinned on
+purpose; only an explicit, audited revocation does. A **stale path hint** warns
+the same way — identity resolved, the recorded path moved.
+
+> **`plan-exec` never redesigns.** Completing an `outline` artifact, inventing a
+> missing state or promoting a revision to `handoff` are design decisions and
+> belong to the refine that owns them. Full contract in
+> [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md) (signal `ui`).
+
+**Publishing a document together with a package revision is one transition.** A
+spec or plan whose reference moves is written in the **same** all-or-nothing batch
+as the revision it points at, so no reader ever sees a document citing a baseline
+that is not there, or a revision no document reached. An effect the batch cannot
+cover — anything outside the workspace files — is recorded as **pending
+reconciliation** in `CHECKPOINT`, never reported as published.
+
+## Delta 1 — One session per run; execution-unit cycle in the plan-doc
+
+- Walk the plan's `### Fn` blocks under `## Tasks` in dependency order inside one session. Infer
+  effective `continuous`/`isolated` batches first; legacy `## Phases` tables degrade the same way.
+- **Execution-unit cycle:** seed one batch intent; implement all its phases in order; validate and
+  review at unit close; then update states/`CHECKPOINT` and enter Git. An isolated unit contains
+  one phase. A continuous unit follows `PLAN-EXECUTION-BATCHES`: no proof, runner, build, lint,
+  review or commit between its phases.
 - Executes the phase's tasks; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). **Micro steps stay internal** (canonical contract): they reach `CHECKPOINT` only when a resume needs them, never the plan.
-- **Marking order (hard rule):** a task is marked `- [x]` when its local work is finished. A phase reaches `validada` **only** when its primary proof **ran and passed**, the needed focused checks passed, its `Condición de salida` is true, the review gate is green and every remaining review finding is explicitly deferred — a blocker is never deferred into `validada`. **Never** because all its checkboxes are ticked.
+- **Marking order (hard rule):** a phase reaches `validada` only with its proof run and passed, its
+  exit condition true and the combined review green; a blocker is never deferred into `validada`.
+  **Never** because all its checkboxes are ticked.
 - **Intermediate states:** `bloqueada` = the phase is stopped on a live blocker — recorded in `CHECKPOINT` + the plan's `## Open questions`, back to `en ejecución` when it clears; it counts as **not validated**. A phase whose work is complete but whose operative check the AI **cannot run** (an unapplied migration — Delta 3) **stays `bloqueada`**: its finished tasks keep their boxes ticked, and the reason goes on its own `> Bloqueo:` line, dropped when the blocker clears. It counts as **not validated** until the check runs and passes. Never a silent `validada`.
 - **A blocker without a reason is not a blocker (hard rule).** Writing `> Estado: bloqueada` **always** writes its `> Bloqueo:` line in the same edit: a state that says "stopped" without saying on what is a dead end for whoever reads `aw status` next. The runtime tolerates a legacy block that states none (`blocker: null`) — this loop never produces one. `CHECKPOINT.Next` names **the action that unblocks it** ("apply migration 014, then re-run the persistence proof"), never the state it is in.
 - **Plan-doc residue (hard rule):** execution writes into the plan-doc **only** five things — checkbox flips (`- [ ]` → `- [x]`), the phase's own `> Estado:` line, its `> Bloqueo:` line while blocked, deferrals appended to its `## Open questions`, and the plan's own status mark (its `> Estado:` line and, on close, its `> Cierre:` line — Delta 6). The declared-gap hatch is Deltas 4, 5 and 7. Per-phase results, review-gate findings and metrics go to the session's `DECISION`/`CHECKPOINT` — **never** into the plan-doc. Phase blocks are updated **in place — NEVER append a duplicate `### Fn` block** (same contract as CHECKPOINT sections). The entry gate's consented normalization is the single exception, and it lands before execution starts.
-- **CHECKPOINT per phase:** on closing a phase record the **functional state reached**, the simulation boundary in force **only when the change carries one**, the tests run and their result, the non-obvious decisions, the deferrals and the next state being pursued. Enumerating every file touched is not required unless it helps a resume.
+- **CHECKPOINT per execution unit:** record its effective grouping, functional states, simulation
+  boundary when applicable, checks/results, decisions, deferrals and next intent. The task boxes
+  and `en ejecución` marks preserve an intra-batch resume.
 - Records in `DECISION` only the **non-obvious**, **as it is decided** (per-phase decisions accumulate in the SINGLE `DECISION`, tagged by phase/task — e.g. `Origin: T2 (F1)`). A structural deviation is **not** settled with an entry there (§ *Deviation gate*).
 - The chassis **gap-driven** engine applies here **inside a task**: facing a non-obvious decision/doubt → inline research, a probe (Delta 7) OR structured-choice.
 
-> **Legacy plans degrade safely.** `plan-exec` still runs plans with `### Fn` blocks, `- [ ]` tasks, legacy sections and **no** `> Estado:` line: a missing line reads `pendiente`, and nothing is back-filled. A plan with every box ticked is **not** validated by that fact — the session (`CHECKPOINT`, review gate) decides. What is genuinely missing is closed by the entry gate or by `plan-refine`, never assumed.
+> **Legacy plans degrade safely:** a missing line reads `pendiente`; missing execution batches are
+> inferred into `CHECKPOINT`; neither is back-filled. Checked boxes alone prove nothing.
 
 ## Deviation gate
 
@@ -108,7 +155,9 @@ On either return path: `CHECKPOINT` records the state reached and the trigger, t
 
 ## Delta 2 — Git policy: **safe branch + proposed commits**
 
-Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: branch-check before editing, rejected commit — changes stay + get recorded —, working-tree precondition between phases). **Inline:** before editing, verify each source's expected branch (`aw check-branch --source <alias>`; on mismatch → pause and resolve with the human); at each phase close and **after the review gate** (Delta 5), **proposed commits per source** (approve first) — never `push`/`--amend`/`--no-verify`.
+Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md), and its gating is the CLI's: this loop
+adds nothing of its own beyond running on a verified branch and never
+`push`/`--amend`/`--no-verify`.
 
 ## Delta 4 — Validation: phase proof + progressive tests
 
@@ -117,7 +166,12 @@ Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: bran
   2. **focused tests** — added when the layer carries its own rules, a relevant transformation, error handling, persistence, transactions, temporal logic or external integration;
   3. **risk tests** — security, concurrency, idempotency, retries, known regressions.
 - **One vertical proof per operation while wiring** (request → controller → use case → repository → fake or stub → expected response): it demonstrates the path once instead of re-asserting the same happy path at every layer. Trivial mappers, plain DTOs and framework behavior get no dedicated test.
-- Compatible with **TDD without a test per method**: the evidence may be written before, during or after the phase's code. What is mandatory is that the `Condición de salida` be demonstrated **before** the phase is flipped to `validada`.
+- `isolated` remains compatible with literal TDD. A continuous batch may author evidence before
+  code, but first runs it at batch close. No phase becomes `validada` before its exit is demonstrated.
+- **Continuous means all checks at batch close.** Do not run its phase proofs, focused/risk tests,
+  build, typecheck, lint or review while implementing internal phases. At close run proofs in phase
+  order, then the justified checks and cross-cutting validations. `isolated` runs the same stack for
+  its single phase.
 - Each added test is re-weighed at the closing review gate ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Closing review gate* → *Test-value lens*, tag `overtest`): over-testing is a **finding to fix or justify**, never an automatic rejection.
 - Also run the plan's `## Validations` (cross-cutting rules and constraints) + the Final behavior block of `## Solution` (legacy plans: the `## Final behavior` section) + the spec's acceptance/success criteria (its `## Scenarios`, if present, are ready-made test cases: GIVEN=arrange · WHEN=act · THEN=assert).
 - A validation that **runs and fails** → back into the phase (gap): no advancing, no `validada`.
@@ -127,13 +181,19 @@ Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: bran
 
 ## Delta 5 — Closing review gate (conventions, pre-commit)
 
-Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Closing review gate*): **independent** diff re-read + installed ambient conventions + the floor lenses (minimality, **test value**, **temporary simulation**, tooling); findings → fix (re-validating the phase) or defer justified. Here only the exec wiring: it runs over the phase's **whole** diff, **between the phase validation (Delta 4) and its commits (Delta 2)**; only with the gate green is the phase flipped to `validada` and its commits proposed.
+Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md): independent re-read, ambient
+conventions and the floor lenses. It covers the execution unit's **whole** diff after every phase
+proof/check and before states or Git advance. Findings are fixed and the affected checks rerun, or
+deferred with justification when they are not blockers.
 
 ## Delta 6 — Completion / close
 
-- A phase closes when its `> Estado:` reads `validada`: work done, `Condición de salida` true, proof **run and passed**. A proof still waiting on an operative handoff leaves it `bloqueada`.
+- A phase closes when its `> Estado:` reads `validada`: work done, exit condition true and proof
+  passed. In a continuous batch every phase waits for the batch review; an operative handoff leaves
+  the affected phase `bloqueada` and the unit uncommitted.
 - **The plan's own state is the third axis, and it stays `open` during the whole run.** Every phase `validada` is **not** the plan closed: the final validation still has to run. Keep `> Estado: open` under the title while executing — stamping it on the first write if the plan carries none — and never write `done` from the counters — a legacy plan with every box ticked is not closed by that fact (§ *Legacy plans degrade safely*).
-- **Every phase `validada` + the final validation passed** → final *structured-choice* (content: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`). `Marcar plan done` is offered under no other condition: one `bloqueada` phase keeps the plan open, however many of its tasks are ticked.
+- **Every phase `validada` + final validation passed** unlocks completion, and on the last batch the
+  same Git approval covers this mark, so the status write lands in the same source commit.
 - **Marking done = ONE status line in the plan-doc**, under the title's blockquote: `> Estado: done`, updated in place on a re-run. The machine value **stands alone** — the date and session go on their own `> Cierre: YYYY-MM-DD · sesión NNN` line right under it, for the same reason a blocker never rides on a phase's state line. It never replaces the per-phase lines inside the `### Fn` blocks — position tells the two apart. No per-phase result tables, no ✅ suffixes — that record lives in the session (`DECISION`/`CHECKPOINT`).
 - **Legacy status line, migrated on write.** A plan carrying the old single-line form (`> Estado: done — YYYY-MM-DD · sesión NNN`) is still **read** as closed; the first time this loop legitimately writes that document, it is rewritten to the two-line form. Compatibility is for reading old plans — every new write uses the normalized contract.
 - **No automatic export**: the artifacts (`SCRIPTS.sql`, `DECISION`, …) stay in the session. Promoting them to `docs/` (scripts, manuals, …) is a separate step via `export-*`.
@@ -147,54 +207,58 @@ plan-exec-loop(PPP-plan-<slug>.md):
   entry gate (executability): result · exit condition · phase proof · simulation boundary if any · no structural contradiction
       minor gap      → structured-choice [Normalizar y ejecutar | Ir a plan-refine] → normalize in place + DECISION
       structural gap → CHECKPOINT(blocker) → hand off to /w:plan-refine → stop
-  for each Phase (### Fn block in ## Tasks; legacy: ## Phases table) in plan (in order, respecting deps):
-    if Estado == validada: skip                            # legacy (no line): all its Tasks - [x] AND the session shows it closed
-    read Resultado + Condición de salida; confirm the initial state
-    set > Estado: en ejecución
-    seed CHECKPOINT.Next = Phase N (Pending = its Tasks)   # BEFORE starting the phase: seed the intent (artifact-first)
-    for each Task of the Phase:
-      if Task - [x] in the plan: skip                      # intra-phase resume by checkbox
-      verify each source's expected branch (branch-check)
-        on mismatch → pause + resolve with the human
-      execute Task (micro steps internal — never plan entries):
-        edit code in the sources (minimal change)
-        if it creates a tool/utility → the ambient creating-tools skill documents it in docs/tools
-        if read-only DB query → SCRIPTS.sql + execute read-only
-        if DB change (DDL/DML) → draft in SCRIPTS.sql (session artifact, DO NOT execute)
-        deviation gate:
-            local decision       → resolve; DECISION only if non-obvious (tagged by phase/task)
-            structural deviation → CHECKPOINT(state + trigger) → stop → /w:plan-refine
-            functional change    → CHECKPOINT(state + trigger) → stop → /w:spec-refine
-        if probe (PoC) task / runnable doubt → seed check → run throwaway code in the
-            session folder → verdict → CONCLUSIONS/DECISION; failed → structured-choice (Delta 7)
-        if doubt/gap → inline research, probe OR structured-choice   # chassis
-      mark Task - [x] IN THE PLAN                          # AFTER its local work; checkbox flip ONLY — results go to DECISION/CHECKPOINT
-    phase proof (Validación de fase) + the justified focused tests:   # Delta 4 levels 1→3
-        what runs and fails → back into the phase (no validada)
-        what cannot run (unapplied migration) → defer the CHECK, never the validation: the phase stays bloqueada
-    closing review gate (pre-commit):                      # Delta 5: CHECKPOINT.Next = "review phase N"
-        INDEPENDENT re-read of the WHOLE phase diff + installed ambient conventions
-        + floor lenses: minimality · test value (overtest) · temporary simulation · tooling
-        findings → fix (and re-validate the phase) OR defer justified (Open questions + BACKLOG)
-    confirm the Condición de salida → set > Estado: validada  # ONLY with the proof run and passed; NEVER from the checkboxes alone
-        blocker still live       → set > Estado: bloqueada + > Bloqueo: <reason> + CHECKPOINT + Open questions
-        check not runnable (SQL) → set > Estado: bloqueada + > Bloqueo: <reason> + CHECKPOINT + Open questions + BACKLOG
-    update CHECKPOINT (functional state reached · simulation boundary if any · tests + result · decisions · deferrals · next state)
-    propose commit(s) per source (approve first)           # never push/amend/--no-verify; only after the gate is green
-        if rejected → changes stay; record "phase uncommitted"
-    next-phase precondition: working tree clean or acknowledged
-  final validation (whatever can run; a deferred check keeps its phase bloqueada)
-  if every phase validada AND the final validation passed:
-    structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
-    mark plan done → > Estado: done + > Cierre: YYYY-MM-DD · sesión NNN under the title (Delta 6), in place
-  else: the plan-level > Estado: stays open → CHECKPOINT.Next = the action that unblocks the phase(s)
+  batches = infer_effective_batches(pending phases, plan + live checkout)
+      may merge/split declared rows without asking; legacy absence is allowed
+      record batches + declaration drift in CHECKPOINT
+  commit_authorization = explicit conditional pre-authorization from the user, if any
+      record it before editing; otherwise approval is deferred to each green batch close
+  for each Batch in batches:
+    verify every affected source's branch; mismatch → stop + human
+    seed CHECKPOINT.Next = Batch Bn (mode + phases + tasks)
+    for each Phase in Batch:
+      if Estado == validada: skip
+      read Resultado + Condición de salida; set > Estado: en ejecución
+      for each pending Task:
+        execute minimal work; keep DB/tool policies; apply deviation gate
+          local decision → resolve; DECISION only if non-obvious
+          structural/functional deviation → CHECKPOINT + stop → refine destination
+          probe whose verdict shapes later work → batch was ineligible; stop/re-infer
+        mark Task - [x] after its local work
+      # continuous: advance directly to the next phase; run NO validation/review/commit here
+    at Batch close, in phase order:
+      run every Validación de fase, then justified focused/risk checks
+      run applicable plan Validations; last Batch also runs final validation before Git
+      failures → fix + rerun affected checks
+      unrun operative check → phase bloqueada + > Bloqueo: + CHECKPOINT + Open questions
+    closing review gate over the WHOLE BATCH diff
+      findings → fix + rerun affected checks OR defer justified if non-blocking
+    if any proof/check/review/exit condition is not green:
+      preserve actual states + combined uncommitted diff; record unblocking action; stop
+    set every Batch phase > Estado: validada; update CHECKPOINT
+    prepare exactly one commit per affected source
+      if last Batch + final validation green:
+        pre-authorized → mark plan done, then commit once per affected source without asking
+        otherwise → structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
+          Marcar plan done → approve; mark done; commit all source changes once
+      else if pre-authorized → commit without another question
+      else → one consolidated approval for all source commits
+      rejected → changes stay; record "batch uncommitted"
+    next-batch precondition: working trees clean or acknowledged
+  if no Batch ran and phases are already validada:
+    run final validation now
+    if green:
+      use the same pre-authorized/final structured-choice completion branch
+      when authorized → mark plan done with > Estado: done + > Cierre: YYYY-MM-DD · sesión NNN under the title (Delta 6), then commit that source once
+  if plan is not done:
+    the plan-level > Estado: stays open → CHECKPOINT.Next = the action that unblocks the phase(s)
   # NO export: artifacts stay in the session; a separate export-* promotes them
 finalize: CHECKPOINT (+ BACKLOG if something is deferred) + close session + report
 ```
 
 ## Convergence / exit
 
-- **Every phase `validada`** + final validation **run and passed** + **every phase passed its closing review gate** before committing → `Marcar plan done`. A phase left `pendiente`, `en ejecución` or `bloqueada` keeps the plan open, whatever its checkboxes say — a proof waiting on an operative handoff (an unapplied migration) is exactly that case.
+- **Every phase `validada`** + final validation passed + every effective batch reviewed before its
+  commits → `Marcar plan done`. Any pending/running/blocked phase keeps the plan open.
 - A **structural deviation** or a **functional change** exits this loop without converging (§ *Deviation gate*): `CHECKPOINT` + `finalize`, and the work continues in `plan-refine` / `spec-refine`. Same exit when the entry gate finds a structural gap.
 - `Cerrar` (`flow` control, at any time) → `finalize` persists `CHECKPOINT` (and `BACKLOG` only if something remained unexecuted / uncommitted / unapplied), closes the session, reports.
 - Promoting artifacts to `docs/` (via `export-*`) is **always** a later, explicit step outside this loop.