@tacuchi/agent-workflow-cli 20.26.0 → 21.1.0

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.
@@ -26,12 +26,12 @@ PLAN
 `/w:plan-new` — **resumable** (same chassis mechanism, keyed off CHECKPOINT).
 
 ## Reads
-`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.
+`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`, never from the filename, and a spec that is not ready is a **soft suggestion** to refine first, never a block — the four input modes are in [`PLAN-INPUT`](../../modules/PLAN-INPUT.md). 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`.
+> **Naming** follows [`PLAN-INPUT`](../../modules/PLAN-INPUT.md) § *Numbering*: `aw next-number docs/plans` mints `PPP` and the slug is short kebab-case from the Requirement. To locate plans, glob `docs/plans/PPP-plan-*.md`.
 
 > **Adoption (command mode 4):** an **externally-built plan** (host plan mode, hand-written, another agent) is materialized by the **command** in a single pass — this loop does not run: transcribe + normalize into the Delta 1 schema, `## Origin` = "adopted from <source>" + attribution; then `plan-refine` closes schema gaps (its coherence gate degrades for spec-less plans). See `../../modules/PLAN-INPUT.md` (the command's `input` module).
 
@@ -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:**
+**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.**
 
-```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*).
+**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.
 
-**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.)*
+**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 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 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`.
 
-**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.)*
-
-**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,19 @@ 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.
-- 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.
+- **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 → the save confirmation and, only after it, the write (confirmed again if the document
+  exists) → `finalize`. On the split branch the same step writes the N siblings.
+
+> **When the gate is evaluated, when the offer appears and with what alternatives, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. The *Sequence* above stays as the loop's shape; it is not its scheduler.
 - `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`

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

@@ -6,7 +6,7 @@ description: >-
   (loops/CHASSIS.md). Deltas: functional journey map, phases re-shaped by
   verifiable state (contract in plan-new-loop), simulation lifecycle,
   evidence by behavior, executability gate, replanning of partially executed
-  plans, and design SPECs via ui-design on UI changes. Started by
+  plans, and design revisions scoped to the delta on UI changes. Started by
   /w:plan-refine — also the return path when plan-exec stops on a structural
   deviation; resumable and re-runnable on demand.
 ---
@@ -31,6 +31,11 @@ This loop turns a plan into a sequence of **verifiable states of the system**. E
 
 The phase contract is defined **once** in [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Phase contract (canonical)* — this loop **applies** it and never redefines it: a `### Fn` block is a state the system reaches, with its `> Estado:` line, its work, its evidence and its exit condition.
 
+The plan's execution-unit interface is likewise defined once in
+[`PLAN-EXECUTION-BATCHES`](../../modules/PLAN-EXECUTION-BATCHES.md). This loop re-infers and
+writes its complete phase partition; it never asks the human to choose an optimization the repo
+can establish.
+
 ## Auxiliary / NOT mandatory
 `plan-exec` runs **any** plan that is already executable, refined or not — there is **no** gate requiring plan-refine. This loop exists to incorporate changes (new requirements, scope adjustments, deps/risks spotted on re-read) **before** executing, and to give an unexecutable plan the shape its execution needs, without regenerating it from scratch.
 
@@ -41,7 +46,7 @@ The phase contract is defined **once** in [`plan-new-loop`](../plan-new-loop/LOO
 `docs/plans/PPP-plan-*.md` (glob — locates the plan by number; or the exact path from the command argument). **Always the plan itself**: this loop edits it in place; there is no separate "refined" file. Provenance is irrelevant — generated by `plan-new`, **hand-written, or adopted** from a host planner (`plan-new` mode 4 / `persist`); existence is the only requirement.
 
 ## Writes
-Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions`. Since it overwrites an existing doc, it asks the user's **confirmation**. On an accepted split (§ *Split gate — refine semantics*) it also **creates** the extracted sibling plans (newly minted `docs/plans` files). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the refine **touches UI**, it also produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its own session** (see *Delta 4* — they are not `docs/`, no auto-export).
+Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions`. Since it overwrites an existing doc, it asks the user's **confirmation**. On an accepted split (§ *Split gate — refine semantics*) it also **creates** the extracted sibling plans (newly minted `docs/plans` files). It writes `docs/plans` and, when the refine **touches UI**, the **revision it publishes** — scoped to the artifacts the delta actually affects — of the design package under `docs/designs` (chassis § *docs/ boundary*; see [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md)). It never graduates/exports anything else to `docs/` — that is separate `export-*` work.
 
 ## Inherits
 
@@ -57,7 +62,8 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Delta 1 — Deliverable: the PLAN, edited in place
 
-The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md) produces (§ *Delta 1 — RICH PLAN*: `Solution` (with its Final behavior block)/`Impacted`/`Tasks` (`### Fn` blocks)/`Validations`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** one trace section:
+The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md) produces, including
+the core `## Execution batches` section. plan-refine completes it in place and adds one trace:
 
 ```markdown
 ## Refinement decisions   ← NEW (ADDED) — the run's single trace
@@ -73,7 +79,7 @@ question that changed nothing, is NOT transcribed.
 
 > **Execution updates progress; refinement changes structure.** `plan-exec` updates the plan's operational state in place — task checkboxes, the phase `> Estado:` line with its `> Bloqueo:` line while blocked, declared deferrals and the plan's own status mark. It does **not** redesign contracts, phase shape or order, participating components, evidence or simulation boundaries: those structural changes are this loop's, and a change of functional behavior belongs to `spec-refine`.
 
-> **Normalize on write, never invent.** A save through this loop leaves the document on the current contract. The plan-level `> Estado:` line sits under the title — `open`, unless execution already closed it, and then with the date and session on their own `> Cierre:` line. Each `### Fn` carries its required blocks, and **no conditional block is written empty**: a phase with no temporary behavior gets no `Límite de simulación`, one with nothing excluded gets no `Diferido`. Normalizing is a rewrite of form — it never changes a phase's state, never ticks a box, and never closes a plan.
+> **Normalize on write, never invent.** A save through this loop leaves the document on the current contract, and **no conditional block is written empty**: a phase with no temporary behavior gets no `Límite de simulación`, one with nothing excluded gets no `Diferido`. Normalizing is a rewrite of form — it never changes a phase's state, never ticks a box, and never closes a plan.
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
@@ -123,6 +129,7 @@ This loop's instance of the chassis convergence gate — the same one `plan-exec
 - **Phases** — each leaves a verifiable state with its exit condition, none is a list of layers or files, the order allows early integration, deferrals are explicit.
 - **Simulation** *(only when the change carries one)* — initial boundary identified, every displacement foreseen, one phase owns the retirement, nothing can stay active by accident. No temporary behavior → the check does not apply, and no empty `Límite de simulación` is required.
 - **Evidence** — every phase declares its primary proof, per-layer tests are justified, the same scenario is not duplicated by default, declared risks have evidence or an explicit deferral.
+- **Execution batches** — every phase appears once; maximal continuous ranges cross no decision, proof, handoff, irreversible action or required recovery boundary.
 - **Resumability** — tasks legible enough for a `CHECKPOINT`, intermediate states stable, pending work distinguishable from work already `validada`.
 
 ## Sequence
@@ -135,17 +142,18 @@ plan-refine-loop(plan):
   work = read(plan) (+ the spec if realignment is needed; + checkpoint/exec history if resuming or returning from plan-exec)
   journey = map(observable contract, technical journey, incremental strategy, evidence)  # bounded research
   work = phases grouped by verifiable state (phase contract) + simulation lifecycle if any + primary proof each
+  work.Execution batches = infer maximal phase partition (PLAN-EXECUTION-BATCHES)
   keep validated phases and their completed tasks; redesign ONLY pending work
   repeat:                                                      # chassis engine
     gaps = detect_gaps(work)  (plan-new taxonomy + plan↔spec drift)  minus the exhausted ones
     if gaps == ∅: break
     batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
       research (scoped to the delta — Delta 3) · human (structured-choice) · probe (chassis) ·
-      ui-design (Delta 4, only new/changed screens)
+      design (revisions only for the artifacts this refine affects; behavior/acceptance → spec-refine first)
     integrate + update CHECKPOINT                              # artifact-first cycle
   executability gate (read-only) = Success criteria green:
-    - contract · journey · phases · simulation · evidence · resumability (§ Executability gate)
-    - plan-new checklist (criterion→task · Final behavior block of Solution · deps · Impacted↔Solution · UI→current SPEC · minimality)
+    - contract · journey · phases · simulation · evidence · execution batches · resumability (§ Executability gate)
+    - plan-new checklist (criterion→task · Final behavior block of Solution · deps · Impacted↔Solution · UI→exact roots · minimality)
       # spec-less plan (adopted/hand-written): criteria anchor to the plan's own Final behavior block/Validations (see Delta 2)
     - re-refine's own check: the plan is REALIGNED with what changed
     whatever fails → comes back as a gap
@@ -161,15 +169,17 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 ## Convergence / exit
 
 - **No material gaps** → **executability gate** (the *Sequence* checklist: contract · journey · phases · simulation · evidence · resumability, plus plan-new's coherence checks and the re-refine's own realignment check).
-- Passes → `Guardar plan refinado` (edits in place with confirmation) → `finalize`.
-- **Split branch**: `Guardar planes` edits the original reduced and writes the extracted siblings → `finalize`.
+- Passes → the save confirmation and, only after it, the in-place edit → `finalize`. On the split
+  branch the same step edits the original reduced and writes the extracted siblings.
+
+> **When the gate is evaluated, when the offer appears and with what alternatives, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. The write follows the confirmation, never the other way round.
 - `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).
 
 > **After refining:** the plan goes to `plan-exec`, which re-checks this same gate on entry — a plan saved here should never bounce back for its structure.
 
 ## Conditional modules
 
-- `ui` — design SPECs for changed screens → `../../modules/PLAN-REFINE-DESIGN-SPECS.md`
+- `ui` — the design closure, the roots, and this loop's delta rule → `../../modules/DESIGN-REFERENCES.md`
 - `simulation` — the life of temporary behavior → `../../modules/SIMULATION-LIFECYCLE.md`
 - `replan` — replanning executed work → `../../modules/REPLANNING.md`
 - `split` — splitting a plan in place → `../../modules/PLAN-REFINE-SPLIT.md`

package/skills/w/loops/quick-loop/LOOP.md

@@ -48,20 +48,20 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 ## QUICK delta — minimal ceremony
 
+> **Directed tranche:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — it names the boundary in force, its alternatives, and the exact invocation when something has to run outside. What stays here is the *why*, plus every step that is judgment or preference.
+
 - **No phases, no plan-doc**: the prompt **is** the task (a single unit). No roadmap.
 - **Proportional verification-first** (minimal ceremony): even here the check is **seeded before**, sized to the task. Code: one test (bug repro → fix) or "existing build/lint/tests stay green" (chore). **Analysis/design**: a **short falsifiable rubric**, *ratified by the user* before pursuing it. It is the run's `SESSION.Success criteria` (see [chassis § *Verification-first*](../CHASSIS.md)).
 - **Git and DB inline** (full policies in [`../CODE-POLICIES.md`](../CODE-POLICIES.md)): before editing, verify each source's expected branch (`aw check-branch`); **proposed** commit (approve first) — never `push`/`--amend`/`--no-verify`. The AI **never executes DML/DDL**: migrations are drafted into the session's `SCRIPTS.sql` (read-only queries do run, via MCP).
 - **One session. One commit** proposed at the end (only if there were code changes), **after the proportional closing review gate** ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Closing review gate*): diff re-read + ambient conventions; fix or defer; nothing reaches the commit unreviewed.
-- **Entry SIZE GATE** (before creating the session): on receiving the objective, evaluate whether it **exceeds a quick**. It fires **only on clear signals** (≥2 of: needs architecture · ≥2 sources · multiple deliverables · large feature/refactor · ambiguous requirements needing elicitation); signals already resolved by *adopted context* do **not** fire (e.g. a host pre-analysis in this conversation that removed the ambiguity — chassis § *Adopted context*); borderline → **continue in quick without asking** (if it later grows, mid-loop escalation covers it). A **resume** of an existing quick does **not** re-fire the gate. If it fires → **structured-choice** (1 content question, recommendation first + `flow` control; `Cerrar` here = abort, nothing created yet):
-  - **`Cambiar a SPEC`** (recommended) → **no quick session is created**: run the *Live transition to SPEC* (next bullet).
-  - **`Seguir en quick`** → continue normally (`create_or_resume` + loop).
-  - **`Recortar alcance`** → the AI proposes the **sub-task that DOES fit** a quick; the loop continues with it (`SESSION.Objective` = the sub-task; the original prompt goes into the session's `## Origin`) and the rest is deferred to `BACKLOG` ("trimmed at the gate — may warrant its own spec, `/w:spec-new`").
-  - **Anti-duplicate** (the `create_or_resume` spirit): if a spec whose `## Origin` references this same objective already exists (or an equivalent `*-spec-refine` session), the recommended option becomes **resuming that spec** (`/w:spec-refine` semantics) — never a second draft.
+- **Entry SIZE GATE** (before creating the session): a quick that should have been a spec costs more than the ceremony it saved, so the size of the objective is judged **before** anything exists. Your part is recognizing the signals; the threshold, the question and its options are the CLI's. A signal already resolved by *adopted context* is **not** a signal (chassis § *Adopted context*). A **resume** of an existing quick never re-fires it.
+  - **`Recortar alcance`**, if chosen: propose the **sub-task that DOES fit** a quick (`SESSION.Objective` = the sub-task; the original prompt goes into `## Origin`) and defer the rest to `BACKLOG` ("trimmed at the gate — may warrant its own spec, `/w:spec-new`").
+  - **`Cambiar a SPEC`**, if chosen: **no quick session is created** — run the *Live transition to SPEC* (next bullet).
 - **Live transition to SPEC** (shared by the gate and mid-loop escalation). On acceptance, the work line **moves to the SPEC flow**: the explicit consent in the structured-choice **equals invoking the destination command** (*consented exception* — rule 3 of the *Continuity rule*, [`../../SKILL.md`](../../SKILL.md) § *Operating context*). On the SPEC side:
   1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs`, slug, schema, single-pass **NO RESEARCH** — its bounded reconnaissance does **not** re-fire (this run's context arrives adopted). `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists). The draft is born `status: draft`: only the SPEC gate promotes it to `ready-for-plan`.
   2. **Load and execute** [`../spec-refine-loop/LOOP.md`](../spec-refine-loop/LOOP.md) — over that spec (trampoline pattern).
   3. The run's session is that loop's **normal** `NNN-<slug>-spec-refine` (the CLI numbers it; its `## Origin` records the escalation). **Invariant 2 intact**: quick, while it is quick, never writes `docs/` — the draft is written by the SPEC flow, post-consent.
-- **Mid-loop escalation + handoff**: if the task grows (same gate signals) → propose moving up to **SPEC/PLAN** (structured-choice, recommendation first). If the user accepts:
+- **Mid-loop escalation + handoff**: if the task grows, declare the signals again — the CLI applies the same threshold and, if it fires, asks. If the user accepts moving up:
   1. The **already-edited code stays** in the working tree (never reverted) and is **recorded** in `CHECKPOINT` + `BACKLOG`: "uncommitted changes in `<source>` — decide commit/discard on resume" (the "rejected commit" pattern, [`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Safe git*).
   2. The quick session goes to `finalize` with the **pointer** in `BACKLOG`: to **PLAN** → "escalated to `docs/plans/PPP` — resume there" (**deferred** as today: seed + pointer, no live entry); to **SPEC** → "escalated to `docs/specs/NNN` — **continued live** (session `NNN-<slug>-spec-refine`)".
   3. The artifacts (`DECISION`, `SCRIPTS.sql`) **stay in the quick session** as referenceable context for the new session (never migrated).
@@ -71,21 +71,13 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 ```
 quick-loop(prompt):
-  # SIZE GATE — BEFORE creating a session; new work lines only (a resume does not re-fire it)
-  if the objective exceeds a quick (≥2 clear signals — see delta):
-    if a spec / spec-refine session for this objective already exists → recommend RESUMING it (/w:spec-refine)  # anti-duplicate
-    structured_choice(content: [Cambiar a SPEC (recommended), Seguir en quick, Recortar alcance],
-                      flow: [Compactar, Cerrar])           # Cerrar here = abort (nothing created yet)
-    Cambiar a SPEC   → live transition (see delta): draft (spec-new procedure) +
-                       load and execute ../spec-refine-loop/LOOP.md → END (no quick session)
-    Recortar alcance → objective = the proposed sub-task; the rest → BACKLOG when the session is created
-    Seguir en quick  → continue
-  s = create_or_resume("<slug>-quick")      # CLI prepends global NNN; always a light session
-  seed SESSION.Objective = the prompt
+  # The CLI drives the entry gate, its anti-duplicate search and the session, and
+  # stops at each boundary it cannot decide; it verifies the seeding afterwards.
+  # `Cambiar a SPEC` → live transition (see delta): draft (spec-new procedure) +
+  #                    load and execute ../spec-refine-loop/LOOP.md → END (no quick session)
   if the conversation already established analysis/conclusions →                 # adopted context (chassis)
     adopt them (SESSION.Origin = "adopted from host conversation"; reference in CONCLUSIONS) — never re-derive/re-ask
-  seed SESSION.Success criteria = the deliverable's check   # verification-first, BEFORE: test(s) if code · short RATIFIED rubric if analysis/design
-  seed CHECKPOINT.Pending/Next = the task (s)               # BEFORE: seed the intent (artifact-first)
+  author SESSION.Success criteria = the deliverable's check  # test(s) if code · short RATIFIED rubric if analysis/design
   work the task (minimal loop):
     if it edits code → verify each source's expected branch (`aw check-branch`); mismatch → pause + resolve
     produce the deliverable: edit code (minimal change) OR author the analysis/design
@@ -93,11 +85,11 @@ quick-loop(prompt):
     if DB change (DDL/DML) → SCRIPTS.sql (session artifact, DO NOT execute)
     if non-obvious decision → DECISION
     if doubt/gap → inline research, a probe OR structured-choice   # chassis § Proof of concept
-    if the task GROWS → propose escalating to SPEC/PLAN      # structured-choice, recommendation first
-        accepts PLAN → handoff (progress stays; BACKLOG→seeded plan — resume there, deferred) → goto finalize
-        accepts SPEC → handoff (progress stays; BACKLOG→"continued live") → finalize →
-                       live transition (see delta): draft if missing + spec-refine-loop
-  convergence gate: Success criteria green                   # tests green if code · rubric satisfied if analysis/design
+    if the task GROWS → declare the signals again; if the CLI asks and the user accepts:
+        PLAN → handoff (progress stays; BACKLOG→seeded plan — resume there, deferred) → goto finalize
+        SPEC → handoff (progress stays; BACKLOG→"continued live") → finalize →
+               live transition (see delta): draft if missing + spec-refine-loop
+  convergence gate: run the Success criteria and hand back their real output
   if there were code changes:
     closing review gate (proportional):                      # diff re-read + installed ambient conventions
         findings → fix (re-validate) OR defer justified (BACKLOG)
@@ -108,11 +100,11 @@ finalize: CHECKPOINT (AFTER: Pending→Completed) + BACKLOG (only if something i
 
 ## Convergence / exit
 
-- **Success criteria green** (proportional) + closing review gate passed and commit proposed if there was code (or skipping it approved) → `Cerrar`.
+- Closing review gate passed and commit proposed if there was code (or skipping it approved) → `Cerrar`.
 - `Cerrar`/`Compactar` (`flow` control) → persists `CHECKPOINT` + `BACKLOG` (resumable).
 - **No export**: nothing goes to `docs/`. Anything worth preserving → promoted separately via `export-*`, or escalated (to SPEC **live** — the line continues in spec-refine already as SPEC flow; to PLAN **deferred**, seed + pointer).
 
-> QUICK's *convergence gate* is **proportional verification-first**: a **short** `Success criteria` seeded at start (not the *absence* of a checklist — its minimal version) — for code, "the change does what the prompt asked + tests/build green"; for analysis/design, a short ratified rubric. Minimal ceremony by design, but **always with the check declared first**.
+> QUICK's *convergence gate* is **proportional verification-first**: a **short** `Success criteria` declared at start (not the *absence* of a checklist — its minimal version). The CLI evaluates it, and it evaluates the **real output** of running those criteria — a claim that they passed is not a result.
 
 ## Conditional modules