@tacuchi/agent-workflow-cli 20.25.0 → 21.0.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.
@@ -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`

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
@@ -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
@@ -169,7 +177,7 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 
 ## 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/spec-refine-loop/LOOP.md

@@ -5,8 +5,8 @@ description: >-
   until PLAN can design without inventing behavior, scope or product
   decisions. Heir of the chassis (loops/CHASSIS.md). Deltas: current-behavior
   baseline, change-shape gate, gap taxonomy classified by destination,
-  conditional ideation gate, ## UI spec via the ui-design capability, and the
-  ready-for-plan gate that stamps the status frontmatter plan-new reads.
+  conditional ideation gate, ## Design references via the design capability, and
+  the ready-for-plan gate that stamps the status frontmatter plan-new reads.
   Started by /w:spec-refine (or the live escalation from quick-loop);
   resumable via CHECKPOINT and re-runnable on demand.
 ---
@@ -50,7 +50,7 @@ Updates `docs/specs/NNN-spec-<slug>.md` **in place** (when the user picks `Guard
 
 > **Not every shape decision creates a file** (§ *Change-shape gate*). An accepted **split** writes the reduced original **and** the extracted sibling specs; a replacement by **`Crear una nueva spec`** writes one new file and leaves this one untouched; **`Reformular esta spec`** creates nothing — it edits this same file, same number, same path. Every write, new or overwriting, is confirmed first.
 
-> **Boundary invariant:** this loop writes **only** into `docs/specs`. It never graduates/exports other artifacts to `docs/` — that is separate `export-*` work (chassis § *docs/ boundary*).
+> **Boundary invariant:** this loop writes **only** into `docs/specs` and, when the requirement involves UI, the **design package** it composes under `docs/designs` (chassis § *docs/ boundary* — the package is the capability's own deliverable, not a graduated artifact). It never graduates/exports anything else to `docs/` — that is separate `export-*` work.
 
 ## Internal sessions — SPEC instance
 
@@ -66,9 +66,9 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Composes
 
-The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*) is resolved by **composing** the **`ui-design`** capability (built-in default `ui-spec`; rebindable via `.workflow/skills.toml`): it authors the UI spec natively (structure, vocabulary, Markdown format). It is the chassis' composed-capability resolution mode (next to *research*, *probe* and *human*): the loop contributes iteration/Q&A (design system, theme, variants, disambiguation) **via the same structured-choice**, and integrates the result as the spec's `## UI spec` section.
+The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*) is resolved by the composed **`design`** capability ([`../../roles/design/ROLE.md`](../../roles/design/ROLE.md)) over the **UI Design Package v1**: reuse a compatible baseline or open an `outline` revision, publish it through the CLI, and leave in the spec **only** its `## Design references` — package, baseline hint and digest. The loop contributes iteration/Q&A (design system, theme, variants, disambiguation) **via the same structured-choice**; the capability contributes what a correct package looks like. Full rule: [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md).
 
-> **Two levels of the same capability:** here (SPEC) it produces `## UI spec` — the UI's *what*, coarse grain; in PLAN the plan loops produce **per-screen design SPECs** derived from that section (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+> **Two levels of the same capability:** here (SPEC) the design closes at `outline` and the spec keeps its exact reference; in PLAN the plan loops promote to `handoff` exactly the closure they implement and pin the exact roots (see [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md)). One package, two questions — never two formats.
 
 Other transversal capabilities the engine always uses: `research` (**inline** — chassis § *Research*), `sql` (DB rule inside research — chassis). All resolved by config; `off` → the loop continues without the capability and, if it was needed, says so or asks. The spec's **prose** follows the **ambient** writing conventions (the host auto-applies an installed writing skill if present), not a composed role.
 
@@ -106,8 +106,8 @@ status: ready-for-plan    ← stamped on Guardar (vocabulary: draft | refining |
                            does not capture — NEVER a 1:1 restatement of a criterion)
 ## Assumptions            (declared)
 
-## UI spec                (opt. — if UI is involved; via the ui-design capability / ui-spec skill)
-Structured Markdown description (screens → regions/components). See [`ui-spec`](../../roles/ui-spec/ROLE.md).
+## Design references      (opt. — if UI is involved; via the composed design capability)
+The exact package, baseline hint and digest — never the design itself. See [`design`](../../roles/design/ROLE.md).
 
 ## Decisions              ← ADDED — the material decisions, NOT the run's history
 The choices a reader needs in order to interpret the contract, each with its why.
@@ -140,7 +140,7 @@ The choices a reader needs in order to interpret the contract, each with its why
 | Hidden assumptions | the spec assumes unstated things | **research** validates / **human** confirms | SPEC |
 | Over-specified requirement | scope/criteria gold-plated — beyond the actual need (chassis § *Minimality*) | **human** (AI proposes the cut, human ratifies) | SPEC |
 | Unexplored solution space *(conditional)* | the spec settles on the first conceivable approach **and** a trigger fires (see *Ideation gate*) | **human consents** → **ideation** | SPEC — only on a trigger |
-| UI unspecified *(if it applies)* | the requirement involves UI but `## UI spec` is missing | **`ui-design` capability** | SPEC |
+| UI unspecified *(if it applies)* | the requirement involves UI but `## Design references` is missing | composed **`design`** capability | SPEC |
 | Architecture | how to distribute technical responsibilities | — | **`PLAN`** — declare, never close here |
 | Implementation | library, class, method, pattern, folder layout | — | **`PLAN`** / `EXEC` — outside the spec |
 | Executable technical risk | whether an integration really works | — | **`PLAN`** (probe), unless the answer changes the contract |
@@ -180,9 +180,10 @@ spec-refine-loop(spec):
     batch = top ≤3 blocking ; pending_human = []   # gap questions ONLY — the shape was resolved above
     seed CHECKPOINT.Pending/Next = batch (refine_session) # BEFORE: seed the intent (artifact-first)
     for each gap in batch:
-      if gap = UI (requirement involves UI, ## UI spec missing):
-        compose ui-design → author ## UI spec    # design-system/theme via structured-choice (counts in the batch)
-        work = integrate(work, ui)               # → ## UI spec
+      if gap = UI (requirement involves UI, ## Design references missing):
+        compose design → reuse a compatible baseline OR publish an `outline` revision
+                                                 # design-system/theme via structured-choice (counts in the batch)
+        work = integrate(work, design)           # → ## Design references (package + hint + digest)
       else if gap = Unexplored solution space and a trigger fires:
         pending_human.push("ideation offer")     # `Explorar ideas` | `Seguir sin ideación`
       else if factual(gap) and attempts[gap] < MAX:
@@ -234,12 +235,13 @@ finalize:
 - **Inline research** → the fact lands in `## Context` / `## Behavioral changes`; if it settles a choice, the choice goes to `## Decisions` (+ ref to the session's `CONCLUSIONS`).
 - **Ideation** → per verdict (§ *Ideation gate*): `Adoptar` → the spec's sections + `## Decisions` · `Descartar` → `CONCLUSIONS` · `Aparcar` → `## Open questions`.
 - **Human** → `## Decisions`, as the decision plus its why. **Not** a `Q:` transcript: the question-by-question trace stays in the session.
-- **`ui-design` capability** (UI gap) → the spec's `## UI spec` section.
+- **Composed `design`** (UI gap) → the package under `docs/designs/` (published through the CLI) + the spec's `## Design references` section, and nothing else in the spec.
 - **Owned by `PLAN` or deferred** → `## Open questions` with its destination, and nothing else in the spec.
 - **Inconclusive or unresolved research** → `## Open questions` (deferred) + the refine session's `BACKLOG.md` (only if something is deferred).
 
 ## Conditional modules
 
 - `shape` — the change-shape gate and its split / replace branches → `../../modules/SPEC-CHANGE-SHAPE.md`
+- `ui` — what the spec keeps when the requirement involves UI → `../../modules/DESIGN-REFERENCES.md`
 - `web` — the conditional ideation gate, its triggers and verdicts → `../../modules/IDEATION-GATE.md`
 - `resume` — the SPEC keys of compact / resume → `../../modules/SPEC-REFINE-KEYS.md`

package/skills/w/modules/DESIGN-REFERENCES.md

@@ -0,0 +1,109 @@
+# DESIGN-REFERENCES — how a spec and a plan cite design instead of carrying it
+
+Loaded when the run involves UI (signal `ui`).
+
+The **UI unspecified** gap is resolved by the [`design`](../roles/design/ROLE.md)
+capability over the **UI Design Package v1**. A spec and a plan **reference** a
+design; neither contains one. The block below is all they carry.
+
+## The reference block
+
+```markdown
+## Design references
+
+- package: `DES-001@r4`
+  baseline_hint: `docs/designs/007-design-alta-familia/baselines/DES-001-r004.json`
+  digest: `sha256:<64 hex>`
+```
+
+- `package` pins **identity and revision**. `latest`, a folder slug, a bare
+  `DES-001` or a title are rejected: each answers a different question next year
+  than it does today.
+- `baseline_hint` is a **location hint**, never the identity. A renamed dossier
+  keeps the reference valid and reports the hint as stale.
+- `digest` seals the exact bytes; one that no longer matches never resolves
+  quietly.
+- Several packages are several blocks. A package named in prose **without being
+  pinned** is reported, not ignored.
+
+**Never in the document**: Screen Specifications, flow graphs, state inventories,
+region or component tables, mockups, embedded images. Those live in the package,
+at their own revision — a document carrying them is a document whose design
+cannot be superseded without editing it.
+
+Publishing the package is the loop writing a composed deliverable through the
+CLI, not graduating a session artifact (chassis § *docs/ boundary*).
+
+## SPEC — close the requirement at `outline`
+
+1. **Reuse before minting.** `aw designs` lists what the workspace already has; a
+   compatible baseline is reused rather than given a second identity.
+2. **Otherwise open an `outline` revision.** Not a shortcut: the spec closes *what*
+   the interface must accomplish and legitimately still holds unknowns. `handoff`
+   is PLAN's call — PLAN knows what will actually be implemented.
+3. **Publish, then reference.** Citing a baseline that was never published is the
+   dangling reference this contract removes.
+
+`spec-new` only **records the need**; it mints nothing. Design-system, theme and
+surface ambiguities are resolved like any other SPEC gap — *structured-choice*,
+counting inside the same ≤3 batch. The section sits where `## UI spec` used to,
+right before `## Decisions`.
+
+## PLAN — promote the closure, pin the roots
+
+1. **Read the spec's `## Design references`.** No section and a plan with screens
+   means the spec never closed its design — a gap back to `spec-refine`, not
+   something PLAN invents.
+2. **Express what this plan implements as exact roots** — the flows, screens and
+   screen states its phases will build.
+3. **Compute the closure**: a flow reaches its nodes, a screen its flows, and both
+   reach the rules, tokens and assets they depend on. It stops there. `flow_refs`
+   is *not* followed — it records which flows visit a screen, so following it drags
+   in designs the plan never consumes.
+4. **Promote exactly that closure to `handoff`**, nothing else. Ten screens in
+   `outline` and three promoted is a package's normal shape; promoting it wholesale
+   because one task needed one screen makes maturity meaningless.
+5. **Publish the revision**, then write the roots.
+
+The plan declares its own `## Design references` — same block — after
+`## Dependencies`, before `## Tasks`. **Its own, not a copy of the spec's**: that
+is what lets a refine move this plan to `@r5` while a sibling stays on `@r4`. A
+plan whose task pins a baseline it never declared resolves against nothing, and
+says so.
+
+Then each phase or task pins the exact roots it consumes:
+
+```markdown
+- [ ] T3.2 — Alta de familia desde el formulario · DES-001@r4 / SCR-002@r2#empty
+```
+
+`<package>@rN / <artifact>@rN[#state]`. Both revisions are mandatory; the anchor
+is optional and only a screen has one. A phase whose tasks share one root may pin
+it once at phase level. Never acceptable: naming `DES-001` without a revision —
+`plan-exec` reports it instead of guessing. And a rendition never answers for a
+root: an approved image is not the current semantics, nor a conformance claim.
+
+## quick — read it, never rewrite it
+
+`quick` **reads and validates** (`aw designs`, `aw designs --plan`); it changes
+nothing a baseline seals — normative content, a maturity, an approval. A visual
+tweak that turns out to need a new state or a redrawn journey **escalates with the
+evidence it gathered**: `plan-refine` for the package, `spec-refine` when behavior
+or acceptance moves. Editing it silently moves the revision with nobody's approval
+while every consumer stays pinned to the old digest.
+
+## plan-refine — the delta, and only the delta
+
+- **New revisions only for the artifacts the refine actually affects.** An
+  untouched screen keeps its revision, maturity and digest.
+- **Never re-point another consumer.** Two plans may pin the same baseline;
+  publishing `@rN+1` for one leaves the other's reference exactly as it was —
+  that is what makes a published revision immutable rather than merely
+  discouraged from changing.
+- **Re-point only this plan** — its `## Design references` and the tasks whose
+  artifacts moved. The spec's section is not touched: it records the baseline the
+  *requirement* closed on.
+- **Behavior or acceptance changed → `spec-refine` first.** Redrawing a journey,
+  adding a state the requirement never described or moving an acceptance criterion
+  is a functional change. Closing it here leaves the spec and the package
+  disagreeing with no way to tell which is right.

package/skills/w/modules/PERSIST-ROUTING.md

@@ -7,6 +7,7 @@ Loaded when classifying what to persist (signal `classification`).
 | **Analysis / conclusions / design notes** | findings, comparisons, diagnoses, adjudications, recommendations | `research` → `docs/research/NNN-research-<slug>.md` |
 | **Requirement** | describes a *wish*: what should exist/change, acceptance criteria derivable | `spec` → `docs/specs/NNN-spec-<slug>.md`, born `status: draft`, `## Origin` = "adopted from host conversation" → offer `/w:spec-refine` |
 | **Plan** | already answers the *how*: phases/tasks/solution — e.g. the host plan-mode output | `plan` → `docs/plans/NNN-plan-<slug>.md` (adoption) → offer `/w:plan-refine` / `/w:plan-exec` |
+| **Durable UI idea** | screens, flows, states meant to last | `spec` **first**, then the design in the package it identifies ([`DESIGN-REFERENCES.md`](DESIGN-REFERENCES.md)); never a Screen Specification *instead of* the Requirement, and `persist` writes no package |
 | Mixed / ambiguous | e.g. analysis that ends in a requirement | one `persist` per document, each confirmed; a research doc plus a spec draft that cites it is a valid split |
 
 ## `docs/research/` — the analysis home (owned by this command)

package/skills/w/modules/PLAN-EXECUTION-BATCHES.md

@@ -0,0 +1,84 @@
+# PLAN execution batches
+
+This module is the single contract for grouping PLAN phases into execution units. `plan-new`
+and `plan-refine` declare the intended units; `plan-exec` infers them again from live state.
+
+## Plan interface
+
+Every new or refined plan carries this core section after `## Tasks`:
+
+```markdown
+## Execution batches
+
+- B1 · continuous · F1-F3
+- B2 · isolated · F4
+```
+
+Rows use sequential `B1..Bn` ids and form a complete, disjoint phase partition in order. A batch
+contains consecutive phases and uses one of two exact modes:
+
+- `continuous` — implement every phase first; validate and review the combined diff at batch
+  close; then create one commit per changed Git source.
+- `isolated` — the traditional cycle for one phase. It is still a batch, so the same state,
+  validation, review and Git rules apply at its close.
+
+The phase contracts, dependencies, risks and open questions are the reproducible evidence.
+
+## Inference
+
+Choose the maximal consecutive `continuous` ranges. A range is eligible only when all of these
+are true:
+
+1. Every dependency is already satisfied or is an earlier phase in the same range.
+2. No phase result, proof, probe or human decision determines how a later phase must be built.
+3. There is no unresolved question, live blocker, operative handoff or irreversible external
+   action between its phases.
+4. No intermediate commit, release, review or deployment is a required recovery boundary.
+5. The combined change is coherent, recoverable and reviewable as one unit.
+
+Anything else is `isolated`. If every phase is eligible, the whole plan is one batch. This is an
+AI inference from observable facts, not a preference question; planning writes it without asking.
+The PLAN gate fails when a phase is missing, duplicated, reordered or grouped across an
+ineligible boundary.
+
+## Runtime authority
+
+Before editing, `plan-exec` repeats the inference over pending phases using the plan plus live
+dependencies, branches, working trees, blockers and risks.
+It may merge or split the declared batches without asking: current evidence wins.
+The declared section remains planning structure;
+the effective batches and any difference are recorded in `CHECKPOINT`.
+
+A legacy plan without `## Execution batches` is valid. Execution infers effective batches and
+records them in `CHECKPOINT`; it does not normalize the plan merely to add the section.
+
+## Continuous cycle
+
+For one effective batch:
+
+1. Verify every affected source and seed one batch intent before editing.
+2. Implement its phases in order. Mark local tasks done and set reached phases to `en ejecución`,
+   but run no phase proof, test runner, build, lint or closing review between them.
+3. After all implementation is written, run every phase proof in order, then the justified
+   focused/risk checks and applicable cross-cutting validations. The last pending batch also runs
+   the plan's final validation here, before Git.
+4. Fix failures autonomously and rerun the affected checks. Review the whole batch diff once.
+5. Only when every check, exit condition and review is green, flip all batch phases to `validada`,
+   update `CHECKPOINT`, and enter the Git step.
+
+This is the narrow exception to the chassis' per-phase artifact beat and clean-tree rule: the
+batch is the execution boundary. Task checkboxes and phase states keep it resumable.
+
+A real blocker or structural/functional deviation stops immediately. No unproven phase becomes
+`validada`; the combined changes remain uncommitted and the actual states plus the unblocking
+action go to `CHECKPOINT`.
+
+## Git authorization
+
+A green batch produces exactly one proposed commit per affected source. One consolidated approval
+covers all of those commits. If the user explicitly pre-authorized commits conditional on every
+batch check passing, record that authorization before editing and commit without another question.
+A failed or unrun check never satisfies the condition and never creates a commit. For the last
+pending batch, the same authorization also marks the fully validated plan `done` before committing,
+so that final plan write is included in the source's single commit; there is no second completion
+question or commit.