@tacuchi/agent-workflow-cli 21.0.0 → 21.1.0

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

@@ -34,6 +34,14 @@ 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
@@ -44,10 +52,8 @@ CLI, not graduating a session artifact (chassis § *docs/ boundary*).
 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`.
+`spec-new` only **records the need**; it mints nothing. The section sits right
+before `## Decisions`.
 
 ## PLAN — promote the closure, pin the roots
 
@@ -58,8 +64,8 @@ right before `## Decisions`.
    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.
+   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.
@@ -89,17 +95,15 @@ root: an approved image is not the current semantics, nor a conformance claim.
 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.
+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 —
-  that is what makes a published revision immutable rather than merely
-  discouraged from changing.
+  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.

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/PLAN-EXECUTION-BATCHES.md

@@ -26,27 +26,19 @@ The phase contracts, dependencies, risks and open questions are the reproducible
 
 ## Inference
 
-Choose the maximal consecutive `continuous` ranges. A range is eligible only when all of these
-are true:
+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.
 
-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.
+> **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.
 
-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.
+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.
-It may merge or split the declared batches without asking: current evidence wins.
-The declared section remains planning structure;
+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
@@ -54,20 +46,10 @@ records them in `CHECKPOINT`; it does not normalize the plan merely to add the s
 
 ## 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.
+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
@@ -75,10 +57,9 @@ 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.
+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

@@ -51,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

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

@@ -0,0 +1,80 @@
+# design — invocation contract
+
+The single authority for **how** `design` is invoked. The installed wrapper
+(`design/SKILL.md`) and [`ROLE.md`](ROLE.md) both point here instead of
+restating it: two descriptions of one contract disagree the day either changes.
+
+The machine-readable form is the descriptor published next to the wrapper
+(`workline-capability.json`, schema `../../schemas/capability-descriptor.schema.json`).
+This file is what a person or a loop reads.
+
+## One door, four stages
+
+```
+aw capability prepare  --capability design --operation <op> [--input k=v ...]
+aw capability continue                                       # stdin: {"parent": <request>}
+aw capability validate                                       # stdin: {"request": …, "answer": …}
+aw capability apply --approval <digest>                      # stdin: {"request": …, "plan": …}
+```
+
+The verbs are **stages**, never operations: the operation travels in the
+envelope. Every attempt returns `outcome`, `output` and `receipt`. A
+`needs_input` is answered with `continue`, which builds the NEXT attempt of the
+same `invocation_id` — it never reuses the previous request.
+
+## What each caller may invoke
+
+| Caller | Operations | Then |
+|---|---|---|
+| direct wrapper | all five | converses in the host; opens no flow session or document |
+| SPEC REFINE | `create` · `update` · `validate` | keeps its own questions, gate and publication |
+| PLAN NEW · PLAN REFINE | `update` · `validate` | closes its plan over the revision it references |
+| PLAN EXEC · QUICK | `validate` | **consumes** the package inside its own lifecycle |
+
+There is no sixth `consume` operation: consuming is what a flow DOES with a
+validated package, not something it asks the capability to do. An operation
+outside its row is refused, never improvised. A flow may add gates of its own and
+may never lower one the capability already failed; a durable output produced
+through the direct route is adopted later **by exact reference** — same identity,
+revision and digest — with no recreation and no format conversion.
+
+## Sources, and what an omission costs
+
+The v1 catalog: Markdown or text, images and screenshots, PDF, DOCX, PPTX, host
+context or attachments, an existing package, and provider locators. Binary
+documents are read by the **host's** multimodal capability — no parser ships in
+the CLI — so what the catalog declares is what the domain can account for.
+
+Every source ends in one of five dispositions, and each one that is not `used`
+carries its reason: `used` · `skipped` (a decision) · `unsupported` (a format v1
+never promised, every retired UI format included) · `unavailable` (it should
+have been readable and was not) · `redacted` (withheld on purpose).
+
+The consequence is fail-closed: a source that did not contribute blocks
+`handoff` unless someone states, in writing, why the design does not need it. A
+run that silently dropped a requirements document and still declared itself
+ready for implementation is the failure this exists to prevent. Original
+documents are never copied into the package unless a person names them, and
+never when they are sensitive.
+
+## Where the output lands
+
+Inside a workspace the package defaults to `docs/designs/` and is discoverable
+by the index — which is what lets a spec or a plan reference it later without it
+ever having had a relationship with those flows. Outside a workspace the caller
+must name an explicit root; the result is still a conformant, portable package,
+and it is simply not indexed. What never happens is a guess: no root declared,
+nothing written.
+
+## What the direct route does not do
+
+- Never creates, advances, closes or publishes a SPEC, PLAN or QUICK session or
+  document.
+- Never initializes a workspace: an operation that needs one and does not find
+  it returns an explicit result.
+- Never exercises an effect the descriptor does not declare, nor one that
+  requires approval without asking for it first.
+
+`off` is decided per operation by the descriptor and no host, wrapper or legacy
+name reverts it. `aw skills --detail` reports the live state, its evidence and
+the next action.

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

@@ -164,6 +164,13 @@ 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.
 
+### How it is invoked
+
+Both routes reach the same dispatcher and each caller has a fixed row of
+operations it may ask for. That contract is stated once, in
+[`CONTRACT.md`](CONTRACT.md) — the same file the installed wrapper points at.
+Nothing about invocation is restated here.
+
 ## CLI ↔ agent split
 
 Explicit, and it is the whole point of the handshake: