@tacuchi/agent-workflow-cli 20.26.0 → 21.1.0

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.
@@ -123,6 +123,10 @@ The choices a reader needs in order to interpret the contract, each with its why
 
 > **Acceptance criteria = static testable criteria** (the "what"): plan-exec validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]` in the spec; the spec never mutates by execution, only by a re-refine.
 
+## Who decides what
+
+> **Directed tranche:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — it opens the session, resolves the shape gate, decides when the ideation offer and the ambiguity question appear, evaluates the ready-for-plan gate and holds the save until its result comes back. What stays here is the *why*: the taxonomy, the checklist and what each branch means. The split gate keeps its rule in [`../../modules/SPLIT-GATE.md`](../../modules/SPLIT-GATE.md), which the PLAN flows still read.
+
 ## Gap taxonomy — signal, resolver, destination
 
 `detect_gaps(work)` looks for these signals. Each is **classified by destination before its resolver is chosen**: closing a `PLAN`-owned question here is the failure mode this taxonomy exists to prevent.
@@ -140,7 +144,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 |
@@ -155,22 +159,17 @@ The choices a reader needs in order to interpret the contract, each with its why
 ```
 spec-refine-loop(spec):
   input = glob(NNN-spec*.md) | argument (path)          # always the spec itself (in place)
-  refine_session = create_or_resume("<slug>-spec-refine")  # <slug> from the spec; CLI prepends global NNN
-  seed SESSION.Success criteria = acceptance criteria + ready-for-plan checklist  # verification-first, BEFORE
+  refine_session = the run's session          # the CLI opens or resumes it and verifies its seed
+  SESSION.Success criteria = acceptance criteria + ready-for-plan checklist  # what its gate evaluates later
   work = read(input)  (+ apply checkpoint progress if resuming)
   adopt(spec-new facts + assumptions + open questions + conversation)  # never re-derive (§ Reads)
   baseline = resolve_current_behavior(work)      # inline research, ONLY what the change rests on
-  shape = change_shape_gate(work, baseline)      # BEFORE closing details → same | split | replace
-  if shape != same:                              # RESOLVED HERE — never queued into pending_human
-    ans = structured_choice(content: [the offer of THIS branch],   # split and replace never share labels
-                            flow: [Compactar, Cerrar])
-    write CHECKPOINT (the decision + its consequence)  # BEFORE acting: a resume re-enters already decided
-    flow Cerrar → goto finalize                  # closed without applying the change; the spec stays untouched
-    `Una sola spec`           → shape resolved as same; keep refining this spec
+  on the shape branch (see ../../modules/SPEC-CHANGE-SHAPE.md for what each one means):
+    `Una sola spec`           → keep refining this spec
     `Dividir en varias specs` → the accepted cut is fixed now; its writes wait for `Guardar specs`
     `Crear una nueva spec`    → mint draft with confirmation (## Origin) ; THIS spec untouched ;
                                 CHECKPOINT.Next = refine it ; goto finalize
-    `Reformular esta spec`    → same number/path ; re-run baseline + this gate before any stamp
+    `Reformular esta spec`    → same number/path ; re-run baseline before any stamp
   attempts = {}                                          # anti re-fire per gap
   repeat:
     gaps = classify_by_destination(detect_gaps(work)) minus the "exhausted" gaps
@@ -180,11 +179,12 @@ 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
-      else if gap = Unexplored solution space and a trigger fires:
-        pending_human.push("ideation offer")     # `Explorar ideas` | `Seguir sin ideación`
+      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:
+        declare the trigger signal               # the CLI decides whether the offer appears
       else if factual(gap) and attempts[gap] < MAX:
         if it needs DB and >1 MCP without default → queue "MCP choice" in pending_human
         res = research_inline(gap)           # current session: ANALYSIS-FILE → CONCLUSIONS (+read-only SCRIPTS.sql)
@@ -201,11 +201,8 @@ spec-refine-loop(spec):
       work = integrate(work, ans)            # → Decisions / Open questions
       ideation offer accepted → run the round NOW, then its verdicts as a NEW ≤3+flow batch (§ Ideation gate)
       ideation offer declined → mark that gap exhausted    # anti re-fire; on-demand entry stays open
-  # no BLOCKING gaps → ready-for-plan gate = Success criteria green (read-only) before offering Guardar:
-  issues = ready_for_plan(work)   # § Convergence / exit — PLAN-owned questions never fail it
-  if issues: blocking += issues ; continue        # findings come back into the loop as gaps
-  ans = structured_choice(content: [Guardar refinada | Guardar specs, Preguntar algo más],
-                        flow: [Compactar, Cerrar])
+  # no BLOCKING gaps → the CLI evaluates the ready-for-plan gate over the run's
+  # Success criteria and asks for their real state; whatever fails comes back as a gap.
   Guardar            → edit_in_place_with_confirm(spec) + stamp status: ready-for-plan ; goto finalize
                        # split branch → also mint + write the extracted siblings as status: draft
   Preguntar algo más → continue
@@ -226,7 +223,7 @@ finalize:
   - **Minimality** — no gold-plating: every criterion and scope item earns its place (chassis § *Minimality*); speculative scope is cut or deferred, and no technical solution was imposed that the requirement did not ask for;
   - `PLAN` can continue without inventing behavior, scope or product decisions.
 - Whatever fails **comes back as a gap**. A question owned by `PLAN` **never** fails the gate: it is recorded with its destination, not closed.
-- Passes → offer `Guardar especificación refinada` (split branch: `Guardar specs`) → `edit_in_place_with_confirm(spec)` + `status: ready-for-plan` → `finalize`.
+- Passes → `edit_in_place_with_confirm(spec)` + `status: ready-for-plan` → `finalize`. The stamp only counts once the document really carries it.
 - `Cerrar` → the chassis `finalize` (always persists `CHECKPOINT`; `BACKLOG` **only if** something is deferred — here: close reason + deferred `Open questions`).
 
 ## Integration (where each resolution lands)
@@ -234,12 +231,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/COMPACTION.md

@@ -2,12 +2,8 @@
 
 Loaded when the run is long enough that context pressure governs its pacing (signal `compaction`).
 
-`Compactar` is not only reactive: the loop **watches its own context pressure** and raises compaction itself.
+`Compactar` is not only reactive: the loop **watches its own context pressure** and raises compaction itself. Recognizing that pressure is judgment — the host's signal where it exists (*compaction* capability in [`../harness/HARNESS.md`](../harness/HARNESS.md)), otherwise the **qualitative** question *"would a fresh reader need the CHECKPOINT to continue?"* at a boundary of an already-long run. Doctrine fixes **no numeric thresholds**: a number that means anything is a number about one host.
 
-- **Signal**: the host's context-pressure signal when it exists (see the *compaction* capability in [`../harness/HARNESS.md`](../harness/HARNESS.md)); with no signal the fallback is **qualitative** — at batch/phase boundaries of an already-long run, ask *"would a fresh reader need the CHECKPOINT to continue?"*. Doctrine fixes **no numeric thresholds** (harness-agnostic).
-- **Modes** — config `[compaction]` table in `.workflow/skills.toml`, key `mode` (values `confirm` | `auto`):
-  - **`confirm`** (default, also with no config): raise a **proactive structured-choice** whose `flow` control carries `Compactar` as the recommended action — the human ratifies; consent is never skipped.
-  - **`auto`** (opt-in): write `CHECKPOINT.md`, then trigger the host's compaction binding **without asking**. Viable only where the host has a **non-interactive** mechanism (see the *Harness binding matrix*); otherwise it **degrades to `confirm`**.
-- **Invariant — CHECKPOINT before compacting**: in every mode, `CHECKPOINT.md` is written (or verified fresh) **before** any compaction fires; resume keys off it.
+> **Which mode runs, and whether the host can honour it, is not this document's call:** `aw checkpoint-write --can-pause` decides it from the `[compaction]` config (`mode` = `confirm` | `auto`), the host's binding and the session's state. `auto` needs a **non-interactive** mechanism and **degrades to `confirm`** without one; **CHECKPOINT before compacting** holds in every mode. What this document keeps is why: consent is never skipped where a person can be asked, and a compaction that fires before the checkpoint loses the thread it was meant to protect.
 
 > **`Compactar`** (the `flow` control) → write `CHECKPOINT.md` in the session (in-flight progress, remaining gaps, Q&A, `attempts`) → trigger the harness **compaction** (Claude Code: `/compact`; see [`../harness/HARNESS.md`](../harness/HARNESS.md)) → resume by reading the checkpoint.

package/skills/w/modules/DB-SCRIPTS-ONLY.md

@@ -10,3 +10,5 @@ Distinguished by **execution**, not by file (see the [`SCRIPTS.sql`](../artifact
 - **DDL/DML migrations** (schema/data changes) → the AI **drafts them in `SCRIPTS.sql`** (session artifact) but **NEVER executes them**.
 
 > Mutating SQL **stays in the session**; it is never moved to `docs/`. Its promotion to `docs/scripts/` (forward + rollback) is done by a separate `export-*`, never by the loop.
+
+> **Showing beats asserting here:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — it asks the session's script back, because no narration tells drafting from running.

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

@@ -0,0 +1,113 @@
+# 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*).
+
+## `handoff` asks to SEE it
+
+A `handoff` screen owes evidence, not only prose: a local static preview of its
+`default_state`, and a `trace` classifying every criterion `visual`,
+`interaction` or `not_visual`. A package published under the earlier gate can stop
+qualifying; it reports `DESIGN_VISUAL_EVIDENCE_REQUIRED` with the screen, the
+criterion and the fix.
+
+## 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. The section sits 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 is the inverse relation, and 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 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.
+- **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/IDEATION-GATE.md

@@ -4,13 +4,13 @@ Loaded when a trigger says the solution space is unexplored (signal `web`).
 
 ## Ideation gate (creativity)
 
-The loop's one **divergent** gate: every other resolver closes a gap; this one widens the option space before the spec hardens around its first idea. **Unexplored solution space is not a universal gap** — it stays shut unless a trigger fires, because exploring what is already decided burns context and invites gold-plating.
+The loop's one **divergent** gate: every other resolver closes a gap; this one widens the option space before the spec hardens around its first idea. **Unexplored solution space is not a universal gap** — exploring what is already decided burns context and invites gold-plating, so the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document: you declare whether a trigger fires, and the offer appears only then.
 
-**Triggers (≥1).** The user knows the problem but not the desired outcome · several functional directions carry materially different consequences · the spec adopted the first alternative prematurely · a choice can materially change scope · the alternatives change experience, rules or acceptance · the user asks to explore.
+**Triggers.** The user knows the problem but not the desired outcome · several functional directions carry materially different consequences · the spec adopted the first alternative prematurely · a choice can materially change scope · the alternatives change experience, rules or acceptance · the user asks to explore.
 
 **Not triggers.** More than one technical solution exists · no library is chosen yet · the system uses several technologies · every implementation admits alternatives · the request is already functionally clear. Purely technical alternatives belong to `PLAN`.
 
-1. **Offer & consent.** The gap enters the batch as a content question — `Explorar ideas` vs `Seguir sin ideación` — carrying the AI's recommendation like any other. Declining marks the gap **exhausted** (never re-offered this run); an explicit user request for ideas at any point counts as an accepted offer (on-demand entry). Alternatives already weighed in the conversation are *adopted context* — the gap does not fire.
+1. **Offer & consent.** Declining marks the gap **exhausted** (never re-offered this run); an explicit user request for ideas at any point counts as an accepted offer (on-demand entry). Alternatives already weighed in the conversation are *adopted context* — the trigger does not fire.
 2. **Ideation round** (one per consent). Propose fresh ideas and **combinations** (the user's + found ones). If the host exposes **web-research** ([`../harness/HARNESS.md`](../harness/HARNESS.md)), the accepted offer also authorizes that round's web searches — no per-search consent; findings + sources land in the session's `CONCLUSIONS`, like inline research. Without the capability, ideate offline (own knowledge + workspace + repos) and **declare it** — never silently.
 
 **Verdicts (back to convergence).** Present the top ≤3 ideas via the same structured-choice, each with a recommended verdict: `Adoptar` → integrate into `Requirement`/`Scope`/criteria + record it in `## Decisions` (the choice and its why, with the source/URL when web-found) · `Descartar` → the reason goes to `CONCLUSIONS`, not to the spec · `Aparcar` → `## Open questions` with its destination. Ideas beyond the top 3 stay summarized in `CONCLUSIONS`. Divergence is bounded by *Minimality* (chassis): nothing enters the spec without an explicit `Adoptar`. This gate exists **only** in this loop — `spec-new` stays single-pass (bounded reconnaissance at most, no web) and the plan/quick loops inherit none of it.

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,65 @@
+# 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 stays eligible while nothing observable
+breaks it. Anything else is `isolated`; if every phase is eligible, the whole plan is one batch.
+
+> **Which facts break eligibility, and what one of them costs, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. It emits the closed vocabulary of those facts at the boundary that asks for them.
+
+This is an inference from observable facts, not a preference question. 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: current evidence wins over the declared
+partition. 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
+
+The batch — not the phase — is the execution boundary: implementation runs straight through, and
+every proof, check, review and state flip happens once at its close. This is the narrow exception to
+the chassis' per-phase artifact beat and clean-tree rule, and task checkboxes plus phase states are
+what keep it resumable. The order of those closing steps is the CLI's, per the note above.
+
+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. Approving is not committing,
+and a check that never ran is not a green batch. For the last pending batch the same approval also
+covers marking the fully validated plan `done`, so that final write rides in the source's single
+commit instead of asking a second time.
+
+> **What proves the batch was green is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — positionally, behind the delegated validation and the review, neither of which a narration can pass.

package/skills/w/modules/PLAN-INPUT.md

@@ -5,12 +5,14 @@ Loaded when the input is not plainly a `ready-for-plan` spec (signal `input`).
 ## plan-new — four modes
 
 1. **Ready spec** (`docs/specs/NNN-spec-<slug>.md` whose frontmatter declares `status: ready-for-plan`) → ideal. Proceed straight to the loop.
-2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first. It is a suggestion, **never a block**: the user may proceed. Questions the spec left with destination `PLAN` are this flow's **input**, not a reason to send it back.
+2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first, **never a block**. Questions the spec left with destination `PLAN` are this flow's **input**, not a reason to send it back.
 3. **Prompt** (no spec referenced) → propose the SPEC flow; **by default launch `/w:spec-new`** with that prompt and continue the natural flow from there.
-4. **External plan content** — the argument carries an **already-built plan** (host plan mode, hand-written, another agent's) → **adopt it**. Single pass, **NO RESEARCH**: materialize as `docs/plans/PPP-plan-<slug>.md` (`aw next-number docs/plans`), normalized to the rich-plan schema with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` or `/w:plan-exec`. Anti-duplicate: a plan whose `## Origin` matches this objective → recommend resuming it, never a second one. Adoption **never regenerates over** an existing plan-doc.
+4. **External plan content** — the argument carries an **already-built plan** (host plan mode, hand-written, another agent's) → **adopt it**. Single pass, **NO RESEARCH**: materialize as `docs/plans/PPP-plan-<slug>.md`, normalized to the rich-plan schema with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` or `/w:plan-exec`. Anti-duplicate: a plan whose `## Origin` matches this objective is resumed, never duplicated. Adoption **never regenerates over** an existing plan-doc.
 
 > **Mode 3 vs 4:** a prompt that *describes a wish* → SPEC (mode 3); content that *already is a plan* → adopt (mode 4).
 
+> **What adoption may do once the mode is settled is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document.
+
 > **Ready vs not** is read from the spec's frontmatter `status`, never from the filename. **Legacy compat:** a spec with no frontmatter that carries `## Refinement decisions` — or the older `## Q&A traceability` — counts as ready the same way.
 
 ## plan-refine — three modes
@@ -23,4 +25,4 @@ Loaded when the input is not plainly a `ready-for-plan` spec (signal `input`).
 
 ## Numbering
 
-The plan is named `docs/plans/PPP-plan-<slug>.md`. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the slug is short kebab-case from the Requirement (`[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars). It does **not inherit the spec's `NNN`** — the link is established by reference in `## Origin`, never by number.
+The plan is named `docs/plans/PPP-plan-<slug>.md`; `aw next-number docs/plans` mints `PPP` and the slug comes from the Requirement. It does **not inherit the spec's `NNN`** — the link is established by reference in `## Origin`, never by number.

package/skills/w/modules/PLAN-REFINE-SPLIT.md

@@ -9,4 +9,6 @@ The gate itself — signals, offer, anti-duplicate, sibling contract, partition
 - The original plan **keeps its number/path**: it is rewritten **reduced** to its remaining tranche (in place, with confirmation). The extracted tranches become newly minted sibling plans (`aw next-number docs/plans` immediately before each write); their `## Origin` records "split from `docs/plans/PPP-plan-<slug>.md`" + the source spec + the siblings by path.
 - The gate also fires on **partially executed** plans. **Completed tasks (`- [x]`) never move to a sibling** — execution history stays anchored to the original path (plan-exec sessions' `## Origin` keep resolving); only pending work is extracted.
 - The split is recorded in `## Refinement decisions` (what moved where + why); original + siblings together keep the **complete, disjoint partition** of the spec criteria (spec-less: the Delta 2 degradation applies).
-- **Closing action** on the split branch: `Guardar planes` (edit the original reduced + write the extracted siblings); the normal branch keeps `Guardar plan refinado`.
+- **Closing action** on the split branch edits the original reduced and writes the extracted siblings — after the confirmation, never before it.
+
+> **When the cut fires, and that the write follows the confirmation, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. The offer's alternatives are its too.

package/skills/w/modules/PLAN-SPLIT-GATE.md

@@ -4,11 +4,13 @@ Loaded when the plan may have to become more than one document (signal `split`).
 
 ## Split gate (multi-plan)
 
-Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for **both** plan loops (`plan-refine-loop` references it, never redefines it). It fires **only on clear signals** (≥2 of: tranches independently executable/deliverable · no shared deps/risk between tranches · different requested moments/priorities · the plan far exceeds S-complexity phases · the user asked for staging); borderline → **one plan, no question**. It can be assessed during decomposition or at the coherence gate, always **before** `Guardar`.
+Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for **both** plan loops (`plan-refine-loop` references it, never redefines it). It fires **only on clear signals** of independently deliverable tranches, and never on a borderline plan.
 
-- **The offer** enters the batch as a **content question** (counts in the ≤3): the body shows the proposed cut in the **user's language** — per sibling, a name + slug, a 1-line scope, the phase mapping and the order. Labels: `Dividir en varios planes` (recommended when the signals hold) | `Un solo plan`. Declining marks the gap **exhausted** (no re-offer this run); a free-form answer adjusts the cut. The accepted cut is seeded into `CHECKPOINT` — a resume does **not** re-ask.
-- **Anti-duplicate** (the `create_or_resume` spirit): if sibling plans whose `## Origin` references this same spec/split already exist, the recommended option becomes resuming them (`/w:plan-refine` / `/w:plan-exec` semantics) — never a second set.
-- **On acceptance** — same run, same session (one session per run, one HISTORY row): **all N siblings are elaborated complete** in this run — each gets the full Delta 1 schema and is immediately executable (`plan-exec` runs any plan; a seed without `## Tasks` would break that contract). Context pressure is absorbed by self-regulation (chassis § *Compact / resume*). Numbering: `aw next-number docs/plans` **immediately before each write** — numbers come out consecutive, so every sibling path is known after the first mint.
+> **Which signals count, how many it takes, and therefore whether the offer appears at all, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Recognizing a signal is judgment; counting them is a rule.
+
+- **The offer** enters the batch as a **content question** (counts in the ≤3): the body shows the proposed cut in the **user's language** — per sibling, a name + slug, a 1-line scope, the phase mapping and the order. Declining marks the gap **exhausted** (no re-offer this run); a free-form answer adjusts the cut. The accepted cut is seeded into `CHECKPOINT` — a resume does **not** re-ask.
+- **Anti-duplicate** (the `create_or_resume` spirit): sibling plans whose `## Origin` references this same spec/split are resumed, never minted a second time.
+- **On acceptance** — same run, same session (one session per run, one HISTORY row): **all N siblings are elaborated complete** in this run — each gets the full Delta 1 schema and is immediately executable (`plan-exec` runs any plan; a seed without `## Tasks` would break that contract). Context pressure is absorbed by self-regulation (chassis § *Compact / resume*). Numbering follows [`PLAN-INPUT`](PLAN-INPUT.md) § *Numbering*, minted immediately before each write.
 - **Sibling contract**: each `## Origin` records the shared source spec + `split (part i/N)` + the **siblings by path** + the order; `## Dependencies` (the existing optional section) carries the inter-plan order — **acyclic and advisory** (`plan-exec` does not enforce it; it only orients what to attack first).
 - **Coherence gate, re-framed**: every spec acceptance criterion traces to **exactly one** sibling — a **complete, disjoint partition**; each sibling's Final behavior block (in `## Solution`) covers its subset; the union covers the spec. Spec-less plans anchor the partition to their own Final behavior block / `Validations`.
-- **Closing action** on the split branch: `Guardar planes` (the single-plan branch keeps `Guardar plan`).
+- **Closing action** on the split branch writes every sibling in the same run; the single-plan branch writes one document. Both are the same confirmation step, and its alternatives are the CLI's.

package/skills/w/modules/PROMPT-CONTINUITY.md

@@ -10,4 +10,6 @@ Loaded when a bare prompt continues an existing work line (signal `resume`).
 2. `"second prompt"` (**no command**, related work) → does **not** create another session: **continues/reopens the most recent one** (from step 1) and appends the new scripts to **that same** `SCRIPTS.sql`.
 3. `/w:quick "third prompt"` (**command** again) → **new** session, new loop.
 
-> The **command** signals "new work line"; a **bare prompt** means "same line" → by default continue/reopen the most recent session (the *last started*). Clearly unrelated → offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to the **no-flow** branch (write into `docs/` by convention + numbering). No workspace → **vanilla** behavior.
+> **Which line a prompt joins is not this document's call:** a command opens a new one through `aw session-create`, a bare prompt continues the most recent through `aw resume`. Both fire **before** a run exists, so no journey has a step for them. The reason stays: the **command** is the signal for "new work line", so nobody loses a thread by not typing one, or forks one by typing it twice.
+
+Whether a prompt really belongs to the open line is judgment. Clearly unrelated → offer choosing (`continuar NNN` | `trabajo nuevo`) or fall to the **no-flow** branch (`docs/` by convention + numbering). No workspace → **vanilla** behavior.

package/skills/w/modules/SPEC-CHANGE-SHAPE.md

@@ -8,14 +8,14 @@ Loaded when the investigation may have changed the spec shape (signal `shape`).
 
 | Finding | What it asks | What it writes |
 |---|---|---|
-| **`split`** — independent functional outcomes discovered | `Dividir en varias specs` \| `Una sola spec` | the original, rewritten reduced, **plus** one new file per extracted outcome |
+| **`split`** — independent functional outcomes discovered | cardinality: one spec, or several siblings | the original, rewritten reduced, **plus** one new file per extracted outcome |
 | **`replace`** — the purpose itself changed | `Crear una nueva spec` \| `Reformular esta spec` | `Crear` → one **new** file, this spec untouched · `Reformular` → **no new file**: this same file, same number, same path |
 
 ## Change-shape gate
 
-Runs once the baseline exists and **before** closing details: the investigation can reveal the draft's shape was wrong. Does the spec still carry **one** functional outcome, did its purpose survive, can the delivery be accepted as a unit? The verdict is **one of three shapes** — `same` | `split` | `replace` — each with its own branch; only the last two ask anything.
+The investigation can reveal the draft's shape was wrong. Does the spec still carry **one** functional outcome, did its purpose survive, can the delivery be accepted as a unit? The verdict is **one of three shapes** — `same` | `split` | `replace` — each with its own branch; only the last two ask anything.
 
-> **Resolved before the gap loop starts, never carried into it (hard rule).** A `split` or a `replace` is asked, answered and applied **immediately** — its own structured-choice, in its own step, between the baseline and the first gap batch. It never travels in `pending_human`: that collection is rebuilt on every iteration and is reserved for questions about functional, technical or scope **gaps**, so a shape decision parked there is erased by the next batch — or never asked at all, because a spec with no blocking gap breaks out of the loop before the batch is built. The resolution lands in `CHECKPOINT` **before** anything else runs, so a resume re-enters with the shape already decided and never re-asks it.
+> **When it runs, and that it never travels inside the gap loop, is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Why it matters: a shape decision parked among the gap questions is erased by the next batch — or never asked at all, because a spec with no blocking gap leaves the loop before a batch is built.
 
 - same outcome — more clarity, or more technical components → **`same`**: no shape question, keep refining this spec;
 - independent functional outcomes discovered → **`split`** (below);
@@ -25,7 +25,7 @@ Runs once the baseline exists and **before** closing details: the investigation
 
 **Split criterion** — the one `spec-new` already uses ([`SPLIT-GATE.md`](SPLIT-GATE.md), `spec-new`'s `split` module), never a different one: divide **only** when each part can be refined, accepted and planned on its own. Repos, technologies, layers or teams are **secondary evidence**, never the reason.
 
-**Split semantics (in place).** The offer enters the batch as a content question — `Dividir en varias specs` | `Una sola spec`; declining marks it **exhausted** for the run. On acceptance: the original **keeps its number/path**, rewritten reduced to its remaining outcome; each extracted outcome is minted with `aw next-number docs/specs` right before its write and is born **`status: draft`**. Siblings are **not** elaborated here — unlike the multi-plan gate, where `plan-exec` would break on a plan with no `## Tasks`; a draft spec is legitimate input to this very loop — so the run keeps refining the **reduced original** and reports `/w:spec-refine` as each sibling's next step. Every `## Origin` records "split from `docs/specs/NNN-spec-<slug>.md`" + the siblings **by path**. Closing action on this branch: `Guardar specs`.
+**Split semantics (in place).** The offer enters the batch as a content question. On acceptance: the original **keeps its number/path**, rewritten reduced to its remaining outcome; each extracted outcome is minted with `aw next-number docs/specs` right before its write and is born **`status: draft`**. Siblings are **not** elaborated here — unlike the multi-plan gate, where `plan-exec` would break on a plan with no `## Tasks`; a draft spec is legitimate input to this very loop — so the run keeps refining the **reduced original** and reports `/w:spec-refine` as each sibling's next step. Every `## Origin` records "split from `docs/specs/NNN-spec-<slug>.md`" + the siblings **by path**. Closing action on this branch: `Guardar specs`.
 
 **Replace semantics.** Its offer is its own — `Crear una nueva spec` | `Reformular esta spec`, **never** the split labels: what gets decided is which identity carries the new purpose. Recommend **a new spec** when the main functional outcome or the actor/consumer changed; **reformulating** when the user confirms this file is still the same unit of work and wants to keep its identity.
 

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.
 
 ---
@@ -49,6 +51,8 @@ built-in default
 2. **Role with no binding at any level** → use the built-in default (table above). No config needed for the common case.
 3. **`off`** → capability disabled. The loop continues without it; if the task required it, the loop reports why it cannot proceed or asks the human.
 
+**A role whose skill declares a capability descriptor is stricter**, because there the binding decides what RUNS and not just which name is written: unset or the canonical name enables the built-in floor plus whatever compatible improvements the host selected; `off` applies the descriptor's per-operation policy and no host, wrapper or legacy name reverts it; anything else is `misconfigured` — a replacement binding does not select an improvement, and the file is never rewritten for you. Existing workspaces are not migrated: `aw skills --detail` explains the reclassification and the owner adopts unset, the canonical name or `off`.
+
 ---
 
 ## skills.toml format
@@ -56,7 +60,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 +68,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 +77,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 +115,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