@tacuchi/agent-workflow-cli 20.26.0 → 21.0.0

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.
@@ -72,20 +74,64 @@ Execution **no longer accepts in silence** a plan that would force it to invent
 
 > 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):** mark a task when its local work finishes and each reached phase
+  `en ejecución`. After the whole unit is green, flip all its phases to `validada`. Each still
+  requires its proof, focused checks, exit condition and the combined review;
+  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 +154,10 @@ 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). Inline: branch-check every source
+before the unit; after its green review, produce exactly one proposed commit per affected source.
+Use one consolidated approval, or the explicit conditional pre-authorization already recorded in
+`CHECKPOINT`. 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,21 @@ 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.
+  `Marcar plan done` is offered under no other condition. On the last batch, its one consolidated Git approval also authorizes
+  this mark before committing, so the status write lands in the same source commit. Explicit
+  green-commit pre-authorization applies it without another question.
 - **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 +209,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.

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

@@ -5,8 +5,8 @@ description: >-
   spec. Heir of the chassis (loops/CHASSIS.md). Deltas: the plan absorbs the
   TECHNICAL-NOTE level + Tasks phased by verifiable functional state
   (### Fn blocks with live state),
-  code/impact-mapping research, planning gap taxonomy, and per-screen design
-  SPECs via ui-design
+  code/impact-mapping research, planning gap taxonomy, and promotion of the
+  design closure to handoff via `design`
   when the plan includes UI. If the spec is not refined it suggests
   spec-refine first. Started by /w:plan-new; resumable. Invoke when a spec
   must become an executable plan.
@@ -29,7 +29,7 @@ PLAN
 `docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Ready vs not** is read from the spec's frontmatter `status`: `ready-for-plan` → proceed (legacy compat: a frontmatter-less spec carrying `## Refinement decisions`, or the older `## Q&A traceability`, counts as ready). Otherwise → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), **never a block**: the user may proceed. Questions the spec left with destination `PLAN` are **input to this loop**, not a reason to send it back.
 
 ## Writes
-`docs/plans/PPP-plan-<slug>.md` (`generate`; **overwrites with confirmation** if it exists) — or **several sibling plans** when an accepted split applies (§ *Split gate (multi-plan)*). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the plan **includes UI**, it also produces **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its session** (see *Delta 4* — they are not `docs/`, no auto-export).
+`docs/plans/PPP-plan-<slug>.md` (`generate`; **overwrites with confirmation** if it exists) — or **several sibling plans** when an accepted split applies (§ *Split gate (multi-plan)*). With UI, also the design revision it publishes under `docs/designs` (chassis § *docs/ boundary*). It never graduates/exports anything else to `docs/` — that is separate `export-*` work.
 
 > **slug**: short kebab-case derived from the spec's Requirement — only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the loop builds the full name. To locate plans, glob `docs/plans/PPP-plan-*.md`.
 
@@ -49,80 +49,72 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Delta 1 — Deliverable: the RICH PLAN (`PPP-plan-<slug>.md`)
 
-The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roadmap:
+The plan keeps technical detail and roadmap inline:
 
 ```markdown
 # Plan PPP — <slug>
 
 > Derived from docs/specs/NNN-spec-<slug>.md · generated by plan-new-loop
-> Estado: open        ← plan-level machine state (open | done); plan-exec closes it
-
-## Origin              source spec · prompt (bootstrapped via spec-new) · "adopted from <source>" + attribution (external plan — /w:plan-new mode 4 / /w:persist)
-## Solution            the how (core): 1–2 summary sentences + the AS-IS → TO-BE
-                       delta (current vs target wiring, brief) + a closing
-                       "Final behavior" block — how the flow behaves at the end,
-                       aligned with the spec criteria. One narration, not four.
-## Impacted            FE · BE · DB (schemas/tables/functions) · APIs · integr. (core)
-## Dependencies        docs / sources / databases / sessions · inter-plan order on a split (opt.)
-## Tasks               (core) `### Fn — <name>` blocks per the phase contract
-                       below: each one a verifiable functional state with its
-                       `> Estado:` line, its evidence and its `- [ ] Tn.m`
-                       units of purpose — never a list of layers or files.
-                       The `### Fn` headers are the ONLY source of phases;
-                       there is no separate Phases table.
-## Validations         validations / constraints / business logic              (core)
-## Risks / impact      technical risks and impacts                             (opt.)
-## Assumptions         assumptions — only the delta over the spec, never re-imported (opt.)
-## Open questions      pending — core when any exist; OMIT the section when empty
+> Estado: open
+
+## Origin              source spec/prompt or adopted source + attribution
+## Solution            the how: brief AS-IS → TO-BE + closing "Final behavior" block (core)
+## Impacted            FE · BE · DB · APIs · integrations (core)
+## Dependencies        docs · sources · DBs · sessions · inter-plan order (opt.)
+## Design references   the baselines this plan's roots pin (opt. — only with UI)
+## Tasks               `### Fn` blocks: the ONLY source of phases (core)
+## Execution batches   complete phase partition; contract in PLAN-EXECUTION-BATCHES (core)
+## Validations         cross-cutting validations and constraints (core)
+## Risks / impact      technical risks and impacts (opt.)
+## Assumptions         delta over the spec only (opt.)
+## Open questions      pending; core when any exist; OMIT the section when empty
 ```
 
-> **Scales with complexity:** the `(core)` sections go **always**; the `(opt.)` ones only when the plan warrants them — a small plan may omit `Dependencies`, `Risks`, `Assumptions`. Concise > exhaustive. *(Legacy plans: `Summary`, `Current state (AS-IS)`, `Target state (TO-BE)`, `Final behavior`, `Phases` and `Estimated time` existed as separate sections — readers tolerate both shapes; new plans never write them.)*
+Core sections always appear; optional ones only when warranted. Legacy readers tolerate the old
+separate sections. New plans never write them. The exec session has no `TECHNICAL-NOTE` or own
+`TASKS`: detail and progress live in this plan.
 
-> **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/LOOP.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
+Batch syntax, inference and runtime semantics are defined once in
+[`PLAN-EXECUTION-BATCHES`](../../modules/PLAN-EXECUTION-BATCHES.md).
 
 ## Phase contract (canonical)
 
-A `### Fn` block is a **verifiable state of the system**, never a list of layers, files or classes. It answers one question: *what can the system do or demonstrate at the end that it could not at the start?* The contract is defined **once** here — [`plan-refine-loop`](../plan-refine-loop/LOOP.md) and [`plan-exec-loop`](../plan-exec-loop/LOOP.md) reference it and never redefine it.
-
-**Required — every phase, always:**
+A `### Fn` block is a **verifiable state of the system**, never a list of layers, files or classes.
+This is the single contract; the other PLAN loops reference it.
 
 ```markdown
 ### F1 — <result-oriented name>
-
 > Estado: pendiente
 
 **Resultado:** <the new verifiable state of the system>
-
 **Trabajo:**
 - [ ] T1.1 — <coherent unit of work>
-
 **Validación de fase:** <the primary proof that the promised state was reached>
-
 **Condición de salida:** <falsifiable result · contract preserved>
 ```
 
-**Conditional — added to that block only when its own condition holds:**
-
-```markdown
-**Estado inicial:** <where the phase starts>
-**Recorrido afectado:** <consumer → components → current boundary>
-**Dependencias:** <phase(s) that must land first>
-**Límite de simulación:** antes <where it is> → después <where it lands, or removed>
-**Diferido:** <work consciously reserved for another phase>
-```
-
-- **Required**: `Resultado` · `Trabajo` · `Validación de fase` · `Condición de salida`, plus the `> Estado:` line.
-- **Conditional**: `Estado inicial` (when it is not obvious) · `Recorrido afectado` (distributed change) · `Dependencias` (the phase cannot run in direct sequence) · `Límite de simulación` (**only** when temporary behavior exists) · `Diferido` (only when work was consciously excluded).
-
-**A new phase never writes an empty conditional block.** No temporary behavior in the change → no `Límite de simulación` line at all; nothing consciously excluded → no `Diferido`. Writing the label with `no aplica` under it is the failure mode this split exists to prevent: it invites inventing a stub to justify the heading, and turns a contract into a form to fill in. The gates check the same way — an absent conditional block is not a gap (§ *Convergence / exit*).
+**Required**: `Resultado` · `Trabajo` · `Validación de fase` · `Condición de salida` · the state
+line. **Conditional**: `Estado inicial` when unclear · `Recorrido afectado` for a distributed
+change · `Dependencias` when direct sequence is insufficient · `Límite de simulación` (**only** when temporary behavior exists) · `Diferido` when work was consciously excluded.
+**A new phase never writes an empty conditional block.**
 
-**Phase state = machine state.** One `> Estado: <value>` line directly under the `### Fn` heading; vocabulary `pendiente` | `en ejecución` | `bloqueada` | `validada`, updated **in place**, never duplicated. It is what `aw status` counts (`phases_validated` / `phases_total`), **alongside — not instead of —** the checkbox progress. A phase reaches `validada` only when its work is done, its `Condición de salida` holds, its validation **ran and passed**, and the closing review gate passed. **Never** because all its checkboxes are ticked. *(Legacy plans carry no line at all: `aw status` reports them as zero phases — checkbox progress only. A missing line among stated blocks reads `pendiente`, and nothing is back-filled.)*
+**Phase state = machine state.** One bare `> Estado: <value>` line uses `pendiente` | `en ejecución`
+| `bloqueada` | `validada`. It is updated in place and counted
+**alongside — not instead of —** checkboxes. `validada` requires completed work, a true exit
+condition, its validation **ran and passed**, and a green review gate. **Never** because all its checkboxes are ticked.
+Legacy blocks have no line; a missing one reads `pendiente`, and nothing is back-filled.
 
-**The state line carries its value alone** — no comment, no suffix, no annotation; an annotated value reads as `pendiente`. A blocker's reason lives on its own `> Bloqueo: <reason>` line inside the block, and in `CHECKPOINT`, `## Open questions` and `BACKLOG`.
+**The state line carries its value alone**; an annotated value reads as `pendiente`. A blocker
+uses its own `> Bloqueo: <reason>` line and the session records.
 
-**The plan carries its own state, and it is a different axis.** One `> Estado:` line under the title, vocabulary `open` | `done`, born `open` with the plan; `plan-exec` writes `done` only after the final validation, adding a `> Cierre: YYYY-MM-DD · sesión NNN` line for the date and session (§ *Delta 6* there). `aw status` derives `plan_state` from that declaration **and** both counters: a `done` over open tasks or unvalidated phases reads `inconsistent`, and every phase `validada` with no closure reads `final_validation_pending` — still open. Position disambiguates the two marks: the plan-level one lives under the title, the phase-level one inside its `### Fn` block. *(Legacy: `> Estado: done — YYYY-MM-DD · sesión NNN` is still read; the next legitimate write normalizes it.)*
+**The plan carries its own state, and it is a different axis.** Its title-level value is `open` | `done`;
+only final validation writes `done` plus `> Cierre: YYYY-MM-DD · sesión NNN`.
+Position disambiguates the two marks. `done` with open work is `inconsistent`; all phases green without
+closure is `final_validation_pending`.
 
-**Granularity is semantic, not mechanical.** A phase earns its place when it leaves a demonstrable state, can be reviewed as a unit, and — when the change carries temporary behavior — moves or retires a simulation. A task is a **coherent unit of purpose** and may touch several files. Naming an edit operation — "create class X", "add method Y", "update the import" — describes a **micro step**: internal to execution, recorded in `CHECKPOINT` when a resume needs it, never a plan entry. `XS–S` stays an orientation of risk and scope; it never mandates splitting a semantic task into mechanical operations.
+**Granularity is semantic, not mechanical.** A phase leaves a demonstrable state. A task is a
+coherent purpose and may touch many files; an edit operation is a **micro step**, never a plan
+entry. `XS–S` informs risk and scope but does not force mechanical splitting.
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
@@ -140,17 +132,19 @@ Replaces the spec gap taxonomy with a planning-oriented one:
 | Structural micro-tasks | the plan enumerates files, classes or methods as entries | the AI groups them by purpose |
 | Simulation without lifecycle | temporary behavior exists with no phase that displaces it and no phase that retires it | the AI derives both / **human** |
 | Phase without evidence | the block declares no `Validación de fase` | the AI derives it from the criteria / **human** |
+| Invalid execution batches | phases are missing/duplicated or cross an ineligible continuous boundary | the AI re-infers the maximal partition |
 | Over-engineered solution | approach heavier than the criteria need — needless abstraction/layer/dependency, or a phase/task not required to meet the spec (chassis § *Minimality*) | AI proposes the lighter path + **human** confirms (**probe** if "lighter works" is a runnable doubt) |
 | Missing deps | order unclear | research / human |
 | Spec criteria uncovered | tasks don't trace to acceptance criteria | the AI derives + human confirms |
 | Unaddressed risks | technical risks unmitigated/undeclared | human / **probe** (Delta 5) |
-| UI without design SPEC *(if it applies)* | the plan includes UI (FE/screens in `Impacted`, `## UI spec` in the spec, or UI tasks) without `NNN-SPEC-*.md` in the session | **`ui-design` capability** |
+| UI without design *(if it applies)* | the plan includes UI (FE/screens in `Impacted`, `## Design references` in the spec, or UI tasks) and pins no exact root, or its roots are not `handoff` | **`design`** (promote the closure, pin the roots) |
 
 > **Author the Solution the laziest-that-works way** (chassis § *Minimality*, generative side): reuse what the codebase/stdlib/platform already provides before proposing new abstractions, layers or dependencies — the coherence gate then only *confirms* minimality, never repairs over-engineering after the fact.
 
 ## Delta 3 — What research investigates here
 
-The chassis' **inline** research specializes: mapping **code/impact** — affected FE/BE/DB components, AS-IS wiring, dependencies. It feeds `Solution` (its AS-IS → TO-BE delta) and `Impacted`. The chassis DB rule applies unchanged (read-only queries into `SCRIPTS.sql`, MCP chosen via a content question when >1 without default).
+Inline research maps affected code, AS-IS wiring and dependencies into `Solution`/`Impacted`.
+The chassis DB rule applies unchanged.
 
 ## Sequence
 
@@ -159,30 +153,31 @@ plan-new-loop(spec):
   input = glob(docs/specs/NNN-spec-*.md) | argument path
   if the spec is not status: ready-for-plan (nor a legacy mark):
     soft-suggest /w:spec-refine    # never blocks — the user may proceed anyway
-  session = create_or_resume("<slug>-plan-new")               # CLI prepends global NNN
-  seed SESSION.Success criteria = coherence-gate checklist      # verification-first, BEFORE
+  session = create_or_resume("<slug>-plan-new")
+  seed SESSION.Success criteria = coherence-gate checklist
   work = plan skeleton (Delta 1) derived from the spec (+ checkpoint progress if resuming)
-  repeat:                                                      # chassis engine
+  work.Execution batches = infer maximal phase partition (PLAN-EXECUTION-BATCHES)
+  repeat:
     gaps = detect_gaps(work)  (Delta 2 taxonomy)  minus the exhausted ones
     if gaps == ∅: break
     batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
-      research (maps code/impact — Delta 3) · human (structured-choice) · probe (Delta 5) · ui-design (Delta 4)
-    integrate + update CHECKPOINT                              # artifact-first cycle
+      research · human (structured-choice) · probe · design (promote closure + pin roots)
+    integrate + update CHECKPOINT
   coherence gate (read-only) = Success criteria green:
-    - every spec acceptance criterion traces to a phase/task
-      (split: each criterion → exactly one sibling — complete, disjoint partition)
+    - every spec criterion traces to a phase/task (split: exactly one sibling)
     - the Final behavior block of ## Solution covers the criteria
     - every ### Fn leaves a verifiable state with its own exit condition — never a list of layers or files
     - the order allows early integration · deps without cycles · Impacted consistent with Solution
-    - the simulation boundary, ONLY when the change carries one, is located, its displacement planned, and one phase owns its retirement
-    - every phase declares its primary evidence; per-layer tests are justified, never automatic
-    - resumable: a stop between phases leaves a stable state and a legible next intent
-    - minimality (chassis § *Minimality*): the Solution is the lightest that meets its Final behavior block; no phase/task/abstraction the criteria don't require
-    - (UI) every screen/UI task traces to its design SPEC and does not contradict ## UI spec
+    - ONLY when the change carries simulation, its displacement and retirement are owned
+    - every phase declares primary evidence; layer tests are justified
+    - Execution batches partitions every phase once and crosses only eligible boundaries
+    - resumable between units and within one through states/checkboxes
+    - minimality: no solution/phase/task heavier than Final behavior requires
+    - (UI) every screen/UI task pins an exact root against a declared baseline · that closure is handoff · nothing outside it was promoted
     whatever fails → comes back as a gap
-  if split accepted (§ Split gate (multi-plan)): work = the N sibling plans (same session; cut in CHECKPOINT)
+  if split accepted: work = N sibling plans
     structured_choice(content: [Guardar planes, Preguntar algo más], flow: [Compactar, Cerrar])
-    Guardar planes → per sibling: aw next-number docs/plans → write (confirmation if it exists)
+    Guardar planes → mint + write each sibling
   else:
     structured_choice(content: [Guardar plan, Preguntar algo más], flow: [Compactar, Cerrar])
     Guardar → write docs/plans/PPP-plan-<slug>.md (confirmation if it exists)
@@ -192,16 +187,17 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 ## Convergence / exit
 
 - **No material gaps** → **coherence gate** (the *Sequence* checklist; the PLAN-new instance of the chassis convergence gate). Criterion→task traceability is a **checked invariant**, never a separate section.
-- **The gate judges functional states, not size.** A plan converges when every `### Fn` is a verifiable state with its exit condition and its primary evidence — plus its simulation boundary located, **only when the change carries one**; a phase that only enumerates layers or files comes back as a gap, however small it is.
+- **The gate judges functional states, not size.** Each phase needs an exit condition, evidence and,
+  **only when the change carries one**, its simulation lifecycle.
 - Passes → `Guardar plan` (writes with confirmation if it exists) → `finalize`.
-- **Split branch**: `Guardar planes` writes the N siblings sequentially (mint before each write) → `finalize` — one session, one HISTORY row.
+- **Split branch**: `Guardar planes` writes the N siblings → `finalize`.
 - `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).
 
-> **After generating:** the plan can go straight to `plan-exec`, or — if changes arise before executing (new requirements, scope adjustments) — pass through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) (`/w:plan-refine`, auxiliary and **not mandatory**), which refines it in place.
+> **After generating:** run `plan-exec`; use optional `plan-refine` when the structure changes first.
 
 ## Conditional modules
 
 - `split` — the canonical multi-plan gate → `../../modules/PLAN-SPLIT-GATE.md`
 - `split` — the incremental journey shape → `../../modules/INCREMENTAL-STRATEGY.md`
-- `ui` — per-screen design SPECs → `../../modules/PLAN-DESIGN-SPECS.md`
+- `ui` — the design closure to promote and the roots to pin → `../../modules/DESIGN-REFERENCES.md`
 - `probe` — probe (PoC) tasks → `../../modules/PLAN-PROBE-TASKS.md`