@tacuchi/agent-workflow-cli 20.26.0 → 21.0.0

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.

package/skills/w/roles/README.md

@@ -12,7 +12,7 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | [`ui-spec`](ui-spec/ROLE.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` (per-screen design SPECs) |
+| `design` | [`design`](design/ROLE.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` · `plan-exec-loop` (reads, never redesigns) |
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
 | `research` | [`research`](research/ROLE.md) | should | all loops (on-demand investigation) |
@@ -25,6 +25,8 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 
 > **Ambient conventions (not roles).** Code, testing and writing standards **and tool authoring** (`creating-tools`, which writes `docs/tools`) are **not Workline roles** and are never bound: they are **standalone skills the host auto-discovers by `description`** and applies when relevant. Workline is **indifferent** (it neither reads nor looks for them). Useful families live in marketplace plugins (`dev-conventions`, `tool-builder`), but Workline does **not depend** on them.
 >
+> **`ui-design` and `ui-spec` are retired names.** The design slot is [`design`](design/ROLE.md), whose only output is the UI Design Package v1. Neither retired name is a role, a binding, an alias or an implementation: they are **rejected**, because two names for one capability are two contracts in disguise. There is no alias, no dual-read, no importer and no migration — a binding that names one is reported as `retired/unsupported`, and a design that is still needed is recreated over the package.
+>
 > **The closing review is not a role either** (deliberate decision — a `conventions`/`rules`/`review` role was evaluated and discarded): the pre-commit **closing review gate** of `plan-exec-loop`/`quick-loop` is a **loop step**; the loop creates the **moment** and the installed ambient conventions fill it. A role that "points at the marketplace skills" would re-couple what this extraction decoupled. The **minimality / anti-over-engineering** lens is **not a role either**: it is a built-in property of the convergence gate (chassis § *Minimality*), owed with no external skill and merely *raised* by whatever ambient review skills are installed — internal essence without the coupling a role would reintroduce.
 
 ---
@@ -56,7 +58,7 @@ built-in default
 ```toml
 [skills]
 # Built-in defaults (no entry needed — listed here for reference only)
-# ui-design        = "ui-spec"
+# design           = "design"
 # sql              = "sql"
 # git              = "git"
 # research         = "research"
@@ -64,7 +66,7 @@ built-in default
 # overview         = "w"
 
 # Override examples:
-ui-design        = "acme/figma-spec"    # third-party skill installed via skills.sh
+design           = "acme/figma-spec"    # third-party skill installed via skills.sh
 diagrams         = "mermaid-only"       # custom built installed locally
 sql              = "off"                # disable the sql capability
 ```
@@ -73,7 +75,7 @@ sql              = "off"                # disable the sql capability
 
 ```toml
 [skills]
-ui-design = "acme/figma-spec"
+design = "acme/figma-spec"
 ```
 
 `acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The binding is **advisory**: the resolver emits the name as-is — it does **not** verify the skill is installed and does **not** auto-fall-back to the built-in default. A typo'd name silently leaves the role bound to a skill that does not exist. Verify the resolution with `aw skills`, which warns when a bound skill is not found in the standard skill roots.
@@ -111,7 +113,7 @@ Example output:
 ```
 Role              Resolved skill          Source
 ----------------- ----------------------- -----------
-ui-design         ui-spec                 built-in
+design            design                  built-in
 sql               sql                     built-in
 git               git                     built-in
 research          research                built-in

package/skills/w/roles/design/ROLE.md

@@ -0,0 +1,217 @@
+---
+name: design
+description: >-
+  UI design authoring over the **UI Design Package v1** — the durable dossier
+  under `docs/designs/NNN-design-<slug>/` that a spec references and a plan
+  implements against. Authors **flows** (the journey: nodes, edges, actors) and
+  **screens** (the surface: states, structure, data, accessibility) as Markdown
+  with versioned YAML frontmatter, plus the rules, tokens, renditions and
+  governance records around them. Knows the package layout, the six canonical
+  schemas, the maturity ladder (`outline` → `handoff`), the reference grammar
+  `DES-NNN/SCR-NNN@rN#anchor`, and what a document must close before an
+  implementation may be planned against it. Use when a loop refines a spec,
+  builds or refines a plan, or executes one that involves screens, forms,
+  dashboards, modals or any UI surface.
+---
+
+# design — UI design over the UI Design Package v1
+
+## Role
+
+`design` — this is its **built-in default implementation**, and `design` is the
+**only public identity** of this capability. `ui-design` (the role this
+replaces) and `ui-spec` (the skill that used to fill it) are **not** aliases,
+**not** alternative implementations and **not** accepted names: a second name
+for one capability is a second contract in disguise, and the day the two
+disagree there is no way to say which one the package obeys.
+
+Rebindable in `.workflow/skills.toml` to a third-party skill or `off`.
+Resolution: built-in default → `~/.workflow/skills.toml` (global) →
+`.workflow/skills.toml` (workspace). See [`../README.md`](../README.md).
+
+## Purpose
+
+Given a UI requirement, author the **semantic** design of its journeys and
+surfaces into a package that outlives the session that produced it: durable,
+versioned, referenceable by digest, and complete enough that an implementation
+can be planned against it without reopening the design conversation.
+
+The package is the deliverable. A spec **references** it; it never contains it.
+
+## Composed by
+
+- **`spec-refine-loop`** — the requirement involves UI: reuse a compatible
+  baseline or open an `outline` revision, and leave only `## Design references`
+  in the spec document.
+- **`plan-new-loop` · `plan-refine-loop`** — the plan consumes UI: promote to
+  `handoff` exactly the closure the plan consumes, and write the exact roots
+  into each phase or task.
+- **`plan-exec-loop`** — reads and validates; **never redesigns**. A design that
+  turns out wrong stops execution and goes back to the refining loop.
+
+In all of them the composing loop contributes the human questions
+(*structured-choice*, chassis § *Structured-choice*), the gap-driven iteration
+and the curation. This skill contributes what a correct package looks like.
+
+## Knowledge
+
+### Package layout
+
+```
+docs/designs/NNN-design-<slug>/
+  design-manifest.json          mutable index — catalog, governance, currentness
+  baselines/DES-NNN-rNNN.json   immutable: what the package IS at that revision
+  flows/FLW-NNN-rNNN-<slug>.md
+  screens/SCR-NNN-rNNN-<slug>.md
+  design-system/rules/RUL-NNN-rNNN-<slug>.md
+  tokens/TOK-NNN-rNNN-<slug>.tokens.json
+  renditions/VIS-NNN-rNNN-<slug>/rendition.json
+  assets/<digest>-<name>.<ext>
+  governance/reviews/REV-NNN.json
+  governance/revocations/RVK-NNN.json
+  PACKAGE.md · design-system/DESIGN.md    regenerable projections, never sealed
+```
+
+The revision is **in the file name**, so publishing `@r2` writes a new file and
+*cannot* overwrite `@r1` — not by policy, by path. An asset carries the digest
+of its own bytes, so different content can never occupy the same name.
+
+### The two documents this skill authors
+
+Both are Markdown: versioned YAML frontmatter (identity, relations, trace,
+unknowns) plus a **fixed list of `##` sections**, once each, in order, none
+empty. A section that genuinely does not apply is declared in
+`not_applicable: {key: reason}` — silence is not closure, and the **essential**
+sections admit no such claim.
+
+| | `flow` (`workline.ui-flow/v1`) | `screen` (`workline.ui-screen/v1`) |
+|---|---|---|
+| Answers | how the journey runs | what one surface is |
+| Frontmatter core | `actors`, `entry`, `nodes`, `edges` | `default_state`, `states[]`, `flow_refs`, `dependencies` |
+| Sections | Goal and outcome · Preconditions and entry · Main journey · Alternatives and recovery · Permissions and privacy · Traceability | Purpose and context · Structure and content · Components and design-system deltas · Data, permissions and validation · States and transitions · Interaction and navigation · Responsive and adaptation · Localization · Accessibility · Edge cases and degradation · Traceability |
+| Essential (no waiver) | Goal and outcome · Main journey · Traceability | Purpose and context · Structure and content · States and transitions · Interaction and navigation · Accessibility · Traceability |
+
+### Reference grammar
+
+`DES-001/SCR-001@r2#error` — package / artifact @ revision # state anchor. A
+reference always pins the revision: **a later revision never invalidates a
+reference already fixed**. Baselines are cited as `DES-001@r2` plus the digest
+that seals them.
+
+### Maturity: `outline` → `handoff`
+
+`outline` is a legitimate state, not a failure — it exists precisely to hold
+what is not yet decided. A document may declare `handoff` only when:
+
+- its **applicable completeness** is closed (every section says something or is
+  waived with a reason);
+- it carries **no blocking unknown** (`unknowns[].blocking: true`);
+- a flow **resolves its graph** — nodes with no edges are not a journey;
+- every reference to **another package** is pinned in `external[]` by provider,
+  revision and digest;
+- no essential section answers with a **rendition and nothing else**: an
+  approved image is not the current semantics and is not a WCAG conformance.
+
+### Governance: four independent dimensions
+
+**Maturity** (`outline`/`handoff`), **review** (a `REV-*.json` that approves or
+rejects an exact baseline *by digest*), **currentness** (derived from
+`supersedes` — superseded warns and still executes) and **execution policy**
+(whether the workspace demands approval) move **separately**. An approval is
+never inherited: a new revision returns to `proposed`, and the only way to
+forbid an intact revision is an explicit, audited revocation.
+
+## Operations
+
+Five semantic operations, all over the **same** package. `create` and `update`
+are one route with a different compare-and-swap base, not two formats.
+
+| Operation | Does | Writes |
+|---|---|---|
+| `create` | first revision of a package | manifest, baseline, artifacts, projections |
+| `update` | next revision of an existing package | idem, over a declared base |
+| `validate` | judges without writing: schemas, naming, references, maturity, closure | nothing |
+| `render` | regenerates the projections | `PACKAGE.md`, `design-system/DESIGN.md` — never sealed |
+| `record` | seals a governance decision about a revision that exists | `governance/reviews/` · `governance/revocations/` |
+
+None of them may invent a layout or a schema of its own. There is no «direct
+package», no parallel Markdown render and no side JSON: **one format, one
+authority**.
+
+## Canonical authority
+
+The normative contract is the six published JSON Schemas under
+[`../../schemas/design/`](../../schemas/design/) — manifest, baseline, flow,
+screen, review, revocation — and the validators that implement them. The
+built-in floor and **every** improvement bound to this role validate their
+output against exactly those, with the same gates.
+
+- A missing external improvement **never blocks the floor**: with nothing bound,
+  the role resolves to this skill and the capability keeps working.
+- A contributor extends the domain by **adding fields to a schema**, never by
+  declaring a format of their own. Nobody redefines the canonical authority —
+  not a bound skill, not a host, not a workspace.
+
+## Boundary with Spec 014
+
+The **transversal capability lifecycle belongs to Spec 014 and is not
+reimplemented here**: skill descriptor, enable/disable lifecycle, the
+`request` / `outcome` / `receipt` envelope, routing between direct and composed
+paths, `off`, effects, and host-native projection are governed there.
+
+This contract adds **only** what is proper to the design domain: fields,
+validators and completeness. Where the two meet, Spec 014 decides the envelope
+and this one decides the payload. Duplicating either side is the failure mode
+being avoided.
+
+## CLI ↔ agent split
+
+Explicit, and it is the whole point of the handshake:
+
+- **The CLI owns** inventory, numbering, digests, validation, authorization and
+  **writing**. It is the only thing that touches the filesystem.
+- **The agent owns** exactly one step: authoring the **semantic content**. Its
+  answer is *data to be validated*, never an instruction to be trusted.
+
+Three stages, and only the third writes: `prepare` (what was read, where writing
+is allowed, and an `input_digest` sealing the state seen) → `validate` (parse the
+answer against that request; on survival, a preview and an `approval_digest`
+over the exact bytes proposed) → `apply` (recompute the input digest, check the
+approval still matches, publish all-or-nothing).
+
+## Output
+
+The package itself — new artifact files plus the revision that seals them. The
+**loop** writes (through the CLI), never this skill on its own.
+
+What this skill does **not** produce: design inside a spec or a plan document.
+A spec carries `## Design references` (package, baseline, digest, path hint); a
+plan carries the exact roots each phase or task consumes. Embedding the design
+in the document is what the package exists to end.
+
+## Retired path — `retired/unsupported`, and nothing else
+
+The legacy path is **gone**: the `ui-design` binding, the `ui-spec` skill, the
+spec's `## UI spec` section and the per-screen design SPECs that PLAN sessions
+carried. `design` is the only identity and the package above the only format.
+
+Presenting any of it — a binding or invocation naming a retired name, a `## UI
+spec` section, a session design SPEC, an output of `ui-spec-generator` — is
+reported **`retired/unsupported`**. It is never read as a contract, and never
+satisfies a gate as evidence. There is **no alias, no dual-read, no importer, no
+conversion, no migrate-on-touch and no bulk migration**: a design that is still
+needed is **recreated** over the package from current sources.
+
+What retirement does not do is destroy: every document already written stays
+exactly where it is, byte for byte, readable by whoever opens it. Retiring an
+input is not the same as deleting a record.
+
+**`ui-spec-generator` is outside this topology.** It is not a dependency, not an
+adapter and not a source of truth for anything here; nothing in Workline reads,
+invokes or imports it. Whatever becomes of that repository is its own business —
+cleaning it up is explicitly not part of this contract.
+
+## Source
+
+Requirement: `docs/specs/013-spec-estandarizar-ui-spec.md`. Contract and
+rationale: the six schemas under [`../../schemas/design/`](../../schemas/design/).