@tacuchi/agent-workflow-cli 21.6.0 → 21.7.0

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

@@ -46,7 +46,7 @@ Closing *every* gap turns the spec into a premature plan. Close what changes **w
 **Adopt, do not repeat.** `spec-new`'s **facts** are reused; its **assumptions** are re-validated **only when one blocks a gap**; its `Open questions` are re-classified by destination; its one-vs-many hypothesis is re-judged at the *Change-shape gate*. The shallow sweep is never re-run wholesale. Keep the labels distinct — a spec that blurs them cannot be gated: **fact** (backed by repo, data or docs) · **inference** (unproven) · **user decision** · **deferred decision** (owner declared) · **open question** (can still move the contract).
 
 ## Writes
-Updates `docs/specs/NNN-spec-<slug>.md` **in place** (when the user picks `Guardar especificación refinada`): completes sections, **adds** `## Decisions`, closes `Open questions` as they get resolved, and stamps the frontmatter `status: ready-for-plan`. Since it overwrites an existing doc, it asks the user's **confirmation**.
+Updates `docs/specs/NNN-spec-<slug>.md` **in place** (when the user picks `Aprobar y guardar`): completes sections, **adds** `## Decisions`, closes `Open questions` as they get resolved, and stamps the frontmatter `status: ready-for-plan`. The stamp travels **inside the proposed bytes** — it is a projection of the same save, not a second write to authorize afterwards. Since it overwrites an existing doc, the preview says so and the person approves it **once**.
 
 > **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.
 
@@ -203,9 +203,11 @@ spec-refine-loop(spec):
       ideation offer declined → mark that gap exhausted    # anti re-fire; on-demand entry stays open
   # 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
+  hand the CLI the exact bytes of the refined spec, with status: ready-for-plan already stamped in them
+                       # split branch → the same bytes carry the extracted siblings as status: draft
+  the CLI seals them into ONE proposal and shows its preview: destination, weight, what it replaces
+  Aprobar y guardar  → the CLI writes every file of the preview, together or not at all ; goto finalize
+  Refinar            → nothing is written and the refinement stays open
   flow Compactar/Cerrar → handle the same way
 finalize:
   write CHECKPOINT (refine_session)                     # always persisted

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

@@ -6,6 +6,13 @@ 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.
 
+A design is **simple** — one authored `DESIGN.md`, everything else derived — by
+default, or an expanded **package** with a declared cause; that vocabulary and the
+authoring contract live in
+[`../roles/design/CONTRACT.md`](../roles/design/CONTRACT.md), and `aw designs`
+prints each mode. Only two consequences reach a citing document: the block is
+identical for both, and the mode decides which task-pin form is legal.
+
 ## The reference block
 
 ```markdown
@@ -16,44 +23,32 @@ design; neither contains one. The block below is all they carry.
   digest: `sha256:<64 hex>`
 ```
 
+A simple design's hint is its `DESIGN.md`.
+
 - `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.
+  `DES-001` or a title are rejected: each answers a different question next year.
 - `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.
+- Several designs are several blocks. One 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
+region or component tables, mockups, embedded images. Those live at their own
+revision — carrying them makes a design that cannot be superseded without editing
+its consumer. Publishing is the loop writing a composed deliverable through the
 CLI, not graduating a session artifact (chassis § *docs/ boundary*).
 
-## Evidence and lifecycle
-
-`trace` marks each criterion `visual`, `interaction` or `not_visual`. Preview
-only visual acceptance; interaction relies on states, semantics and implementation
-proof, never a storyboard merely to satisfy format.
-
-The CLI marks a delta **compact** only with an existing surface, ≤2 screens, and
-no journey, rule, token, asset, external dependency, blocker or adaptation.
-Compact publishes one `handoff` for PLAN to reuse. Otherwise it is **expanded**:
-SPEC keeps `outline`; PLAN promotes only its consumed closure. The model authors
-content, not this routing.
-
 ## 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. **Classify the lifecycle.** Compact publishes `handoff` now; otherwise open
-   `outline`, which may hold unknowns until PLAN promotes its implemented roots.
-3. **Publish, then reference.** Citing a baseline that was never published is the
-   dangling reference this contract removes.
+2. **Classify the lifecycle.** Compact publishes one `handoff` for PLAN to reuse;
+   otherwise open `outline`, which may hold unknowns until PLAN promotes its
+   implemented roots.
+3. **Publish, then reference.** Citing a baseline never published is the dangling
+   reference this contract removes.
 
 `spec-new` only **records the need**; it mints nothing. The section sits right
 before `## Decisions`.
@@ -61,55 +56,54 @@ 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.
+   means the spec never closed its design — a gap back to `spec-refine`.
+2. **Express what this plan implements as exact roots.**
 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. **Reuse a valid `handoff`, or promote exactly the missing closure.** A compact
-   handoff from SPEC is already the plan's baseline, not work to repeat.
-5. **Publish the revision**, then write the roots.
+   is *not* followed — the inverse relation drags in designs nobody consumes.
+4. **Reuse a valid `handoff`, or promote exactly the missing closure**, then
+   publish the revision and 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:
+`## Dependencies`, before `## Tasks`, never a copy of the spec's: that is what
+lets a refine move it to `@r5` while a sibling stays on `@r4`. A task pinning a
+baseline its plan never declared resolves against nothing, and says so.
 
 ```markdown
 - [ ] T3.2 — Alta de familia desde el formulario · DES-001@r4 / SCR-002@r2#empty
+- [ ] T3.3 — Aviso de duplicado · DES-007@r1
 ```
 
-`<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.
+`<package>@rN / <artifact>@rN[#state]` pins inside a **package**: both revisions
+mandatory, the anchor optional and only on a screen, and a phase whose tasks share
+one root may pin it once at phase level. `<package>@rN` alone pins the **root** —
+the only form a **simple** design has, since there is nothing to point inside.
+Asking a simple design for an artifact blocks and sends you to its root; a package
+task pinning a whole revision is legitimate. A root pin walks no closure and
+reaches no maturity, and still resolves identity, revision and digest, refuses a
+revoked revision, and fails closed when the bytes moved. 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.
+nothing a baseline seals — normative content, a maturity, an approval. A tweak
+that needs 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 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.
+  publishing `@rN+1` for one leaves the other's reference 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.
+  artifacts moved. The spec's section records the baseline the *requirement*
+  closed on and is not touched.
 - **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.
+  adding an undescribed state or moving an acceptance criterion is functional;
+  closing it here leaves the spec and the design disagreeing with no way to tell
+  which is right.

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

@@ -22,6 +22,70 @@ 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 a person actually sees
+
+Four stages is the machinery. The **visible** journey is four moments and exactly
+one decision:
+
+```
+comprender fuentes → redactar y organizar → vista previa → Aprobar y guardar | Refinar
+```
+
+`prepare` publishes what a valid answer must contain and where it may land;
+`validate` seals the exact bytes and returns the preview; the person decides once.
+`Aprobar y guardar` runs `apply` with that digest and covers the whole proposal —
+document, manifest, index and derived state — in one atomic write. `Refinar`
+produces no effect at all and the proposal is written again. An identical retry
+reuses the approval; any change of content, destination, base, scope or effect
+class invalidates it and shows a new preview.
+
+Discovery, classification, numbering, digests, validation, publication and indexes
+never become questions of their own. What keeps its OWN boundary: sensitive
+sources, network, execution, destruction, external effects, and any scope the
+preview did not show.
+
+## Two shapes, one contract
+
+`create` and `update` publish a **simple** design by default: one authored
+`DESIGN.md` (`## Objetivo`, `## Diseño propuesto`, `## Validación`, plus
+`## Recorrido`, `## Decisiones` or `## Abiertos` only when they say something).
+The CLI derives the identity, the folder, the revision, the digest and a minimal
+manifest — the caller administers none of it, and `maturity` answers null because
+one document has no ladder to climb.
+
+The full **UI Design Package v1** appears only with a cause, and the vocabulary is
+closed to five — one is enough:
+
+| Signal | Means | Who says it |
+|---|---|---|
+| `design.independent-outcomes` | two or more results each worth delivering | agent |
+| `design.functional-blocking` | an unclosed functional decision blocks the design | agent |
+| `design.clarity-lost` | one document would stop being readable | agent |
+| `design.governance-or-system-reuse` | the package already carries governance or several revisions | **CLI derives** |
+| `design.special-source-or-effect` | a sensitive source, an external transmission, or a declared source that did not contribute | **CLI derives** |
+
+Recognizing a semantic signal is judgment and travels as `--input expansion=<id>`;
+the two structural ones are facts about the invocation, so declaring one is
+refused rather than believed. The receipt carries the mode, the signals that fired
+and the one-line cause — every artifact beyond the simple document traces back to
+the need it covers. `render` and `record` are package operations regardless.
+
+Publishing a second simple revision archives the outgoing bytes inside the same
+approved proposal, so a reference pinned to `@r1` keeps resolving after `@r2`
+lands: a published revision is never taken away by the next one.
+
+## Evidence and lifecycle inside a package
+
+`trace` marks each criterion `visual`, `interaction` or `not_visual`. Preview only
+visual acceptance; interaction relies on states, semantics and implementation
+proof, never a storyboard to satisfy format.
+
+The CLI marks a delta **compact** only with an existing surface, ≤2 screens, and
+no journey, rule, token, asset, external dependency, blocker or adaptation.
+Compact publishes one `handoff` for PLAN to reuse; otherwise SPEC keeps `outline`
+and PLAN promotes only its consumed closure. The model authors content, not this
+routing — the same split the simple route applies to expansion.
+
 ## What each caller may invoke
 
 | Caller | Operations | Then |
@@ -59,12 +123,15 @@ 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.
+Inside a workspace the design 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. On the simple route the exact folder
+is derived from the title (`docs/designs/NNN-design-<slug>/`) and travels back as
+the one allowed destination, so `target` is optional and naming it only narrows
+the default. Outside a workspace the caller MUST name an explicit root; the result
+is still a conformant, portable package — and it takes the expanded route, because
+a simple design derives its identity from an index that is not there. What never
+happens is a guess: no root declared outside a workspace, nothing written.
 
 ## What the direct route does not do
 

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

@@ -32,11 +32,20 @@ Resolution: built-in default → `~/.workflow/skills.toml` (global) →
 ## 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,
+surfaces into something 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.
+The **default deliverable is one readable `DESIGN.md`** — `## Objetivo`,
+`## Diseño propuesto`, `## Validación`, plus `## Recorrido`, `## Decisiones` or
+`## Abiertos` only when they say something. The CLI derives its identity,
+revision, digest and minimal manifest; nobody authoring a design administers any
+of that. The full package below is the **expanded** shape, and it appears only
+with a declared or derived cause — the closed vocabulary lives in
+[`CONTRACT.md`](CONTRACT.md) § *Two shapes, one contract*.
+
+Whichever shape it takes, the design is the deliverable. A spec **references**
+it; it never contains it.
 
 ## Composed by
 
@@ -56,7 +65,16 @@ and the curation. This skill contributes what a correct package looks like.
 
 ## Knowledge
 
-### Package layout
+### Simple layout — the default
+
+```
+docs/designs/NNN-design-<slug>/
+  DESIGN.md                     the ONLY authored file
+  design-manifest.json          derived: mode simple, one baseline, empty catalog
+  revisions/DESIGN-rNNN.md      the exact bytes of a revision a newer one superseded
+```
+
+### Package layout — the expanded shape
 
 ```
 docs/designs/NNN-design-<slug>/

package/skills/w/schemas/design/design-manifest.v1.schema.json

@@ -28,6 +28,10 @@
       "type": "string",
       "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})$"
     },
+    "mode": {
+      "description": "Which shape this package is. `simple` publishes one authored DESIGN.md and catalogs nothing; `package` is the full dossier of flows, screens, rules, tokens and renditions. Optional, and absent means `package` — every dossier published before the simple route stays readable without a migration.",
+      "enum": ["simple", "package"]
+    },
     "title": {
       "description": "Human name of the package.",
       "type": "string",