@tacuchi/agent-workflow-cli 20.15.0 → 20.16.0

package/skills/w/commands/plan-refine.md

@@ -18,14 +18,14 @@ This command does not refine the plan itself: it delegates to `plan-refine-loop`
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
-> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-plan-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-plan-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next`; `## Open questions` only while live doubts exist).
 > 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
 > 3. **Write boundary** — this flow edits only `docs/plans/…` (in place, with confirmation); nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the plan's content) goes in the **user's language**.
 
 > **Not mandatory.** `plan-exec` runs **any** plan, refined or not — no gate requires passing through here. Use it only when the plan needs adjustments before executing.
 >
-> **Spec-less plans (hand-written / adopted).** A plan with no source spec is legitimate input. The coherence gate **degrades gracefully**: criteria trace to the plan's own `## Final behavior` / acceptance criteria instead of spec criteria — the "spec criteria uncovered" gap does not apply (see `../loops/plan-refine-loop/LOOP.md`).
+> **Spec-less plans (hand-written / adopted).** A plan with no source spec is legitimate input. The coherence gate **degrades gracefully**: criteria trace to the plan's own Final behavior block (in `## Solution`) / acceptance criteria instead of spec criteria — the "spec criteria uncovered" gap does not apply (see `../loops/plan-refine-loop/LOOP.md`).
 
 ## Input resolution
 
@@ -49,8 +49,8 @@ The skill detects prior state before starting, **keying off the `CHECKPOINT`** (
 
 1. Find the plan's refinement session under `.workflow/sessions/` (descriptor `<slug>-plan-refine` + `## Origin`) and its `CHECKPOINT.md`.
 2. **In progress** (a CHECKPOINT exists) → continue from the recorded progress (resolved gaps, Q&A).
-3. **No progress** (no CHECKPOINT and the plan does **not** have `## Refinement decisions`/`## Q&A traceability`) → start from zero reading the plan (`PPP-plan-*.md`).
-4. **Already refined / re-refine on demand** (no open CHECKPOINT but the plan **already has** the 2 sections) → **first-class operation**: while the flow stays in PLAN you can re-run `/w:plan-refine` over the same plan **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **plan itself**; on `Guardar`, edits in place with confirmation.
+3. **No progress** (no CHECKPOINT and the plan does **not** have `## Refinement decisions`) → start from zero reading the plan (`PPP-plan-*.md`).
+4. **Already refined / re-refine on demand** (no open CHECKPOINT but the plan **already has** that section) → **first-class operation**: while the flow stays in PLAN you can re-run `/w:plan-refine` over the same plan **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **plan itself**; on `Guardar`, edits in place with confirmation.
 
 ## UI → design SPECs
 

package/skills/w/commands/quick.md

@@ -17,7 +17,7 @@ For scoped, direct tasks that do not justify going through SPEC or PLAN. Creates
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
 > 1. **Size gate BEFORE any session** — if the objective exceeds a quick (≥2 clear signals: needs architecture · ≥2 sources · several deliverables · large feature/refactor · ambiguous requirements), ask first with these verbatim options: `Cambiar a SPEC` *(recommended)* · `Seguir en quick` · `Recortar alcance`. If it escalates, create **no** quick session.
-> 2. **Session first** — otherwise, before touching code, create/resume the run's session: `aw session-create --type quick --name <slug>-quick --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 2. **Session first** — otherwise, before touching code, create/resume the run's session: `aw session-create --type quick --name <slug>-quick --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next`; `## Open questions` only while live doubts exist).
 > 3. **Git/DB** — commits are **proposed**, never executed without approval; **never** `push`/`--amend`/`--no-verify`; never execute DML/DDL (SQL goes to the session's `SCRIPTS.sql`).
 > 4. **Language** — everything user-facing (questions, option labels, reports) goes in the **user's language**.
 

package/skills/w/commands/spec-new.md

@@ -80,7 +80,7 @@ Assumed facts.
 Pending doubts. ← the spec-refine-loop closes them.
 ```
 
-> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Refinement decisions` + `## Q&A traceability` (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md)). Same skeleton: the draft and the refined spec share the order.
+> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Refinement decisions` (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md); the refine drops `Open questions` when it empties). Same skeleton: the draft and the refined spec share the order.
 
 **Filling notes:**
 
@@ -88,7 +88,7 @@ Pending doubts. ← the spec-refine-loop closes them.
 - No `Type` field — `plan-new` infers the how.
 - `Scope` always carries `Out` (what stays out).
 - **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.
-- **Scenarios = behavior made concrete** (uppercase GIVEN/WHEN/THEN/AND): draft them only when the prompt already describes behavior — deriving the rest is spec-refine work, not this command's.
+- **Scenarios = behavior made concrete** (uppercase GIVEN/WHEN/THEN/AND): draft them only when the prompt already describes behavior — deriving the rest is spec-refine work, not this command's. A scenario earns its place only when it adds GIVEN setup or edge semantics the criterion does not capture — **never restate a criterion 1:1**.
 - If **UI** is involved, mention it in `Requirement`/`Context`; the `## UI spec` is authored in `spec-refine` (via the `ui-design` capability). "UI unspecified" is a first-class refinement gap.
 - The **gaps** the loop detects = weak sections of the schema (vague Requirement, Scope without `Out`, untestable criteria, open questions, undeclared assumptions, contradictions) **+ UI unspecified** when the requirement involves UI.
 - Equivalent alternative: the user creates the draft by hand. Both paths produce the same `docs/specs/NNN-spec-<slug>.md`.

package/skills/w/commands/spec-refine.md

@@ -16,7 +16,7 @@ This command does not refine the spec itself: it delegates to `spec-refine-loop`
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
-> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-spec-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-spec-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next`; `## Open questions` only while live doubts exist).
 > 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
 > 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation); nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the doc's content) goes in the **user's language**.
@@ -36,8 +36,8 @@ The skill detects prior state before starting, **keying off the `CHECKPOINT`** (
 
 1. Find the spec's refinement session under `.workflow/sessions/` and its `CHECKPOINT.md`.
 2. **In progress** (a CHECKPOINT exists) → continue from the recorded progress (resolved gaps, Q&A).
-3. **No progress** (no CHECKPOINT and the spec does **not** have `## Refinement decisions`/`## Q&A traceability`) → start from zero reading the spec (`NNN-spec*.md`).
-4. **Already refined / re-refine on demand** (no open CHECKPOINT but the spec **already has** the 2 sections) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **spec itself**; on `Guardar`, edits in place with confirmation.
+3. **No progress** (no CHECKPOINT and the spec does **not** have `## Refinement decisions`) → start from zero reading the spec (`NNN-spec*.md`).
+4. **Already refined / re-refine on demand** (no open CHECKPOINT but the spec **already has** that section) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **spec itself**; on `Guardar`, edits in place with confirmation.
 
 > **Compat (legacy):** the `NNN-spec*.md` glob also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs. Re-running spec-refine edits them in place from then on.
 

package/skills/w/exports/README.md

@@ -25,8 +25,8 @@
 | Export | Composes | Reads (artifacts / sessions + corpus) | Writes (its ONLY category) |
 |---|---|---|---|
 | [`export-scripts`](export-scripts/EXPORT.md) | `sql` | type-B `SCRIPTS.sql` (DDL/DML migrations) across N sessions + standalone `docs/scripts/*.sql` | `docs/scripts/NNN-export-scripts-<date>/` (numbered forwards + `00-ROLLBACK.sql`) |
-| [`export-manuals`](export-manuals/EXPORT.md) | — (prose: ambient conventions) | sessions + `DECISION` + plan-doc (`Solution`, `Final behavior`, `Validations`) + touched code | `docs/manuals/` |
-| [`export-diagrams`](export-diagrams/EXPORT.md) | `diagrams` | source code of the sources + plan-doc (`AS-IS` / `TO-BE`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
+| [`export-manuals`](export-manuals/EXPORT.md) | — (prose: ambient conventions) | sessions + `DECISION` + plan-doc (`Solution` incl. Final behavior block, `Validations`) + touched code | `docs/manuals/` |
+| [`export-diagrams`](export-diagrams/EXPORT.md) | `diagrams` | source code of the sources + plan-doc (AS-IS → TO-BE delta in `Solution`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
 | [`export-reports`](export-reports/EXPORT.md) | — (prose: ambient conventions) | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
 
 > **Composition over ownership:** an export that owns a derived artifact does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export. `export-manuals` and `export-reports` produce **prose**, which follows **ambient writing conventions** (the host auto-applies an installed writing skill if present) — they do **not** compose or bind a `writing` role.

package/skills/w/exports/export-diagrams/EXPORT.md

@@ -1,6 +1,6 @@
 ---
 name: export-diagrams
-description: "Generates the workspace's architecture and flow diagrams in `docs/diagrams/` consolidating the sources' code + the plan-doc (`Current state (AS-IS)` / `Target state (TO-BE)`, `Impacted`) of N sessions. Produces context, containers, components, integrations and data model (when read-only MCP is available). Default `mermaid` (renders on GitHub, `mermaid.ink` link for preview); `c4`/structurizr opt-in via `--engine`. Output in `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` (or `.md`). Read-only/report: emits only the diagram source (the reader renders it); never commits nor mutates anything; MCP reads only. Composes the `diagrams` capability. Use for 'system diagram', 'workspace C4', 'architecture/flow map'. User-invoked via `/w:export-diagrams`."
+description: "Generates the workspace's architecture and flow diagrams in `docs/diagrams/` consolidating the sources' code + the plan-doc (the AS-IS → TO-BE delta in `## Solution`, `Impacted`) of N sessions. Produces context, containers, components, integrations and data model (when read-only MCP is available). Default `mermaid` (renders on GitHub, `mermaid.ink` link for preview); `c4`/structurizr opt-in via `--engine`. Output in `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/` (or `.md`). Read-only/report: emits only the diagram source (the reader renders it); never commits nor mutates anything; MCP reads only. Composes the `diagrams` capability. Use for 'system diagram', 'workspace C4', 'architecture/flow map'. User-invoked via `/w:export-diagrams`."
 ---
 
 # export-diagrams — architecture and flow diagrams from code + plan-doc
@@ -26,7 +26,7 @@ The **`diagrams`** capability (built-in default `diagrams`), resolved via `.work
 ## What it does
 
 1. Inspects the workspace sources' code (structure, wiring, integrations, technologies).
-2. Reads the plan-doc from the sessions: `Current state (AS-IS)` / `Target state (TO-BE)` and `Impacted` (what changed and where).
+2. Reads the plan-doc from the sessions: the AS-IS → TO-BE delta in `## Solution` (legacy plans: separate `Current state (AS-IS)` / `Target state (TO-BE)` sections) and `Impacted` (what changed and where).
 3. (Optional) With read-only MCP available and a data-model request: queries DB schemas (reads only).
 4. Resolves the engine (`--engine`) and consolidates the architecture/flows touched by the N sessions.
 5. Renders the diagrams (composes `diagrams`): context, containers, components, integrations, data model (when it applies).
@@ -50,7 +50,7 @@ In plan mode it **describes**, never writes: the resolved engine, the levels/sec
 **`agent-workflow` CLI (alias `aw`)** — never read hardcoded paths:
 
 - `aw release-data [--since sessionNNN] [--source <alias>]` — enumerates the corpus (ALL sessions; input for the AS-IS/TO-BE delta). `aw sessions` alone lists only ACTIVE sessions — never use it as the corpus.
-- `aw session-artifacts --code <NNN> --dump objetivo` — locates the session and its plan-doc reference; `AS-IS`/`TO-BE`/`Impacted` are read from the plan-doc by its path.
+- `aw session-artifacts --code <NNN> --dump objetivo` — locates the session and its plan-doc reference; the AS-IS → TO-BE delta and `Impacted` are read from the plan-doc by its path.
 - `aw next-number docs/diagrams` — deterministic numbering (the CLI handles destination-folder resolution).
 
 **Filesystem / code**:
@@ -90,7 +90,7 @@ Per source: basic structure, internal components (modules, services, commands, h
 
 ### Step 3 — Read the corpus delta
 
-Per filtered session (`aw session-artifacts --code <NNN> --dump objetivo`): follow the plan-doc reference and read `Current state (AS-IS)` / `Target state (TO-BE)` and `Impacted`. Used to highlight what changed over the current snapshot.
+Per filtered session (`aw session-artifacts --code <NNN> --dump objetivo`): follow the plan-doc reference and read the AS-IS → TO-BE delta in `## Solution` (legacy plans: separate AS-IS/TO-BE sections) and `Impacted`. Used to highlight what changed over the current snapshot.
 
 ### Step 4 — Inspect MCP (optional)
 
@@ -121,5 +121,5 @@ Functionally idempotent: each invocation takes the next `NNN`; it never overwrit
 
 - Design: `docs/referencias/workflow-exports/export-diagrams.md` · family: [`../README.md`](../README.md).
 - Composed capability: `diagrams` (built-in default; see `docs/referencias/workflow-roles/`).
-- Input: plan-doc `AS-IS`/`TO-BE`/`Impacted` (see `docs/plans`).
+- Input: plan-doc `## Solution` (AS-IS → TO-BE delta) + `Impacted` (see `docs/plans`).
 - Siblings: [`../export-scripts/EXPORT.md`](../export-scripts/EXPORT.md) · [`../export-manuals/EXPORT.md`](../export-manuals/EXPORT.md) · [`../export-reports/EXPORT.md`](../export-reports/EXPORT.md).

package/skills/w/exports/export-manuals/EXPORT.md

@@ -1,6 +1,6 @@
 ---
 name: export-manuals
-description: "Operations / onboarding manuals (operator/support audience). Synthesizes the workspace's technical manuals into `docs/manuals/` consolidating N sessions (`exec`/`quick`) + `docs/`. Reads each session's `DECISION` and the plan-doc (`Solution`, `Final behavior`, `Validations`) + the touched code in the sources (how what was built operates/works). Two modes: `complement` (default, overwrites `INDEX.md` pointing at the detected manuals) and `regenerate` (produces a `NNN-export-manuals-YYYY-MM-DD/` dossier with 1 manual per topic). Audience: operators / support / onboarding. Read-only/report: it never commits nor mutates sessions. The prose follows the ambient writing conventions (the host auto-applies an installed writing skill when present). Use for 'operations manual', 'how what we shipped works', 'technical onboarding pack', 'manuals index'. User-invoked via `/w:export-manuals`."
+description: "Operations / onboarding manuals (operator/support audience). Synthesizes the workspace's technical manuals into `docs/manuals/` consolidating N sessions (`exec`/`quick`) + `docs/`. Reads each session's `DECISION` and the plan-doc (`Solution` — including its Final behavior block —, `Validations`) + the touched code in the sources (how what was built operates/works). Two modes: `complement` (default, overwrites `INDEX.md` pointing at the detected manuals) and `regenerate` (produces a `NNN-export-manuals-YYYY-MM-DD/` dossier with 1 manual per topic). Audience: operators / support / onboarding. Read-only/report: it never commits nor mutates sessions. The prose follows the ambient writing conventions (the host auto-applies an installed writing skill when present). Use for 'operations manual', 'how what we shipped works', 'technical onboarding pack', 'manuals index'. User-invoked via `/w:export-manuals`."
 ---
 
 # export-manuals — technical manuals from sessions + `docs/`
@@ -26,7 +26,7 @@ The manual's prose follows the **ambient** writing conventions: the host auto-ap
 
 ## What it does
 
-1. Reads the session corpus (`exec`/`quick`): per session, `DECISION` + the plan-doc (`Solution`, `Final behavior`, `Validations`).
+1. Reads the session corpus (`exec`/`quick`): per session, `DECISION` + the plan-doc (`Solution` — including its Final behavior block; legacy plans: a separate `## Final behavior` section —, `Validations`).
 2. Inspects the touched code in the sources (how what was built operates/works) — read-only.
 3. Detects topics (declared in `SESSION` — its `## Objective` —, or inferred by operational keywords).
 4. Resolves the mode (`complement` or `regenerate`).
@@ -97,13 +97,13 @@ List `docs/manuals/*.md` (excluding `INDEX.md` and `NNN-export-manuals-*/` subdi
 
 ### Step 3 — Detect topics
 
-For every filtered corpus session (`aw session-artifacts --code <NNN> --dump objetivo,decisiones`): take the dump's `DECISION` + the plan-doc (`Solution`/`Final behavior`/`Validations`) + the touched code. **Primary** topic: the topic in `SESSION` (its `## Objective`). **Secondary**: inference by operational keywords ("configure", "install", "step by step", "how to …" — in the user's language). Filter by `--topics` when present. List (slug, confidence, origin sessions).
+For every filtered corpus session (`aw session-artifacts --code <NNN> --dump objetivo,decisiones`): take the dump's `DECISION` + the plan-doc (`Solution` with its Final behavior block/`Validations`) + the touched code. **Primary** topic: the topic in `SESSION` (its `## Objective`). **Secondary**: inference by operational keywords ("configure", "install", "step by step", "how to …" — in the user's language). Filter by `--topics` when present. List (slug, confidence, origin sessions).
 
 ### Step 4 — Synthesize (prose: ambient conventions)
 
 **`complement` mode** — one `INDEX.md`: header + manual count + table (Topic · Slug · Manual present/`[pending]` · Origin sessions) + "Next steps" when there are pending topics.
 
-**`regenerate` mode** — 1 `.md` per topic in the dossier, each with: Purpose · Prerequisites · Numbered steps (how to operate) · Final behavior (from the plan-doc) · Post-use validation · Relevant decisions (`DECISION`) · Troubleshooting · References. Every manual must let the operator complete the task **without** calling the development team. Plus a dossier `README.md` with the index. The prose follows the ambient writing conventions (host).
+**`regenerate` mode** — 1 `.md` per topic in the dossier, each with: Purpose · Prerequisites · Numbered steps (how to operate) · Final behavior (from the plan-doc's `Solution`) · Post-use validation · Relevant decisions (`DECISION`) · Troubleshooting · References. Every manual must let the operator complete the task **without** calling the development team. Plus a dossier `README.md` with the index. The prose follows the ambient writing conventions (host).
 
 ### Step 5 — Write or report
 

package/skills/w/loops/CHASSIS.md

@@ -68,7 +68,7 @@ The loop works **artifact-first**: the artifact is **seeded before** executing a
 
 > The artifact expresses the **intent** (Pending/Next, before) and then the **result** (Completed/DECISION, after), at **every** gap/phase boundary — not only on `Compactar`/`Cerrar`. Session artifacts are the run's live log; the spec/plan is the **guiding base**.
 
-> **Fixed form (hard rule):** an artifact keeps its template's `##` headings **exactly** and is updated **in place** — appending a **duplicate heading** is a contract violation. When a scaffolded section is filled, its `<!-- … -->` guidance comment is **replaced** by the real content. Canonical headings per artifact: its template under [`../artifacts/`](../artifacts/) (CHECKPOINT contract: `Completed` · `Pending / Next` · `Open questions`).
+> **Fixed form (hard rule):** an artifact keeps its template's `##` headings **exactly** and is updated **in place** — appending a **duplicate heading** is a contract violation. When a scaffolded section is filled, its `<!-- … -->` guidance comment is **replaced** by the real content. Canonical headings per artifact: its template under [`../artifacts/`](../artifacts/) (CHECKPOINT contract: `Completed` · `Pending / Next`; `Open questions` only while live doubts exist).
 
 ## Gap-driven convergent engine
 
@@ -133,7 +133,7 @@ Investigation is **inline**: an activity **inside the run's current session**, n
   3. Execute them **read-only** via MCP (respect `sql-mutation-guard`: never DML/DDL).
 - **Inconclusive research** (DB unavailable, insufficient evidence, unresolvable factual gap):
   - The investigation closes with status **`inconclusive`** in `CONCLUSIONS` and reports why.
-  - The loop **degrades** the gap: to a **human question** (next batch → the flow's Q&A record: `Q&A traceability` in refine loops, `DECISION` in code-editing ones) or, failing that, **defers** it to the flow doc's `## Open questions` (spec/plan) — or the session's `BACKLOG` when the flow has no doc (quick).
+  - The loop **degrades** the gap: to a **human question** (next batch → the flow's Q&A record: a `Q:` entry in `## Refinement decisions` in refine loops, `DECISION` in code-editing ones) or, failing that, **defers** it to the flow doc's `## Open questions` (spec/plan) — or the session's `BACKLOG` when the flow has no doc (quick).
   - The gap is marked **"already tried via research"** (`attempts[gap]++`, `MAX` cap) so `detect_gaps` does **not** re-fire it in a loop → guarantees convergence.
 
 ## Proof of concept (probe)
@@ -169,7 +169,7 @@ Resume **keys off the `CHECKPOINT`** of the run's session, not the existence of
 2. **No progress** (no CHECKPOINT and the input doc does **not** have the flow's prior-work mark) → start from zero reading the input doc (plus any *adopted context* — settled in-conversation conclusions are input, not something to re-derive).
 3. **Already converged / re-run on demand** (no open CHECKPOINT but the doc **already has** the mark) → **first-class operation**: while the flow stays in its stage, re-running the command over the same input **as many times as needed** is supported. `create_or_resume` finds the existing session — typically **closed** after convergence — by descriptor + `## Origin` and **reopens** it (see *Internal sessions*: detection via `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reopening via `aw session-resume --code <NNN> --reopen`); incremental work reading the **doc itself**.
 
-> Each heir defines its **prior-work mark**: in the refine loops, the presence of `## Refinement decisions` + `## Q&A traceability` in the doc; in plan-exec, the plan-doc's `- [x]` checkboxes; quick has no doc (resume by CHECKPOINT only).
+> Each heir defines its **prior-work mark**: in the refine loops, the presence of `## Refinement decisions` in the doc (legacy docs may also carry `## Q&A traceability`); in plan-exec, the plan-doc's `- [x]` checkboxes; quick has no doc (resume by CHECKPOINT only).
 
 > **`Compactar`** (the `flow` control, across all 3 cases) → 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/loops/plan-exec-loop/LOOP.md

@@ -56,9 +56,10 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 ## Delta 1 — One session per run; per-phase progress in the plan-doc
 
-- Walks the plan's `Phases` in order (respecting deps) **inside the run's single session** (no session-per-phase).
+- Walks the plan's `### Fn` blocks under `## Tasks` in order (respecting deps) **inside the run's single session** (no session-per-phase). *(Legacy plans: a separate `## Phases` table — walk it the same way.)*
 - **Per-phase progress lives in the plan-doc** (`- [x]`) and in the single `CHECKPOINT` (Completed/Pending/Next): **artifact-first** — `CHECKPOINT.Next` is set to the imminent phase **before** starting it; the plan-doc's `- [x]` checkbox is flipped **after** completing the task.
-- Executes the phase's `Tasks`; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). Marks `- [x]` + state **in the plan** (living doc; never in a separate `TASKS`).
+- Executes the phase's tasks; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). Marks `- [x]` **in the plan** (living doc; never in a separate `TASKS`).
+- **Checkbox-only residue (hard rule):** execution writes into the plan-doc **only** three things — checkbox flips (`- [ ]` → `- [x]`), deferrals appended to its `## Open questions` (the declared-gap escape hatch: Delta 4's unapplied migration, Delta 5's deferred findings, Delta 7's failed probe), and, on close, the single status line (Delta 6). Per-phase results, review-gate findings and metrics go to the session's `DECISION`/`CHECKPOINT` — **never** into the plan-doc. Phase blocks are updated **in place — NEVER append a duplicate `### Fn` block** (same contract as CHECKPOINT sections).
 - At **every phase boundary**: validate, run the **closing review gate** (Delta 5), update the `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) and propose commits.
 - Records in `DECISION` only the **non-obvious**, **as it is decided** (per-phase decisions accumulate in the SINGLE `DECISION`, tagged by phase/task — e.g. `Origin: T2 (F1)`).
 - The chassis **gap-driven** engine applies here **inside a task**: facing a non-obvious decision/doubt → inline research, a probe (Delta 7) OR structured-choice.
@@ -73,7 +74,7 @@ Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *DB scripts-only
 
 ## Delta 4 — Validation
 
-- After executing (per phase and at the end): run tests/checks against `Validations` + `Final behavior` + the spec's acceptance/success criteria (its `## Scenarios`, if present, are ready-made test cases: GIVEN=arrange · WHEN=act · THEN=assert).
+- After executing (per phase and at the end): run tests/checks against `Validations` + the Final behavior block of `## Solution` (legacy plans: the `## Final behavior` section) + the spec's acceptance/success criteria (its `## Scenarios`, if present, are ready-made test cases: GIVEN=arrange · WHEN=act · THEN=assert).
 - A validation that **runs and fails** → back to the task (gap); no advancing.
 - **Validation depending on an unapplied migration**: since the AI never executes the DML, it **cannot run it read-only** → it is **deferred** (handoff to a DBA), it does **not block progress**. Recorded in the plan's `Open questions` + `BACKLOG`, marked "verification pending until the SQL is applied". (Reuses the chassis degrade/defer pattern + `MAX` cap → avoids the "back to the task" loop.)
 
@@ -87,6 +88,7 @@ Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Closing review ga
 
 - A phase closes **done** when its tasks are `- [x]` and its validation passed **or** was deferred (SQL handoff). Possible state: **"done — SQL pending application"**.
 - All phases done → final *structured-choice* (content: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
+- **Marking done = ONE line in the plan-doc**, under the title's blockquote: `> Estado: done — YYYY-MM-DD · sesión NNN` (or `done — SQL pendiente de aplicar`), updated in place on a re-run. No per-phase result tables, no ✅ suffixes — that record lives in the session (`DECISION`/`CHECKPOINT`).
 - **No automatic export**: the artifacts (`SCRIPTS.sql`, `DECISION`, …) stay in the session. Promoting them to `docs/` (scripts, manuals, …) is a separate step via `export-*`.
 
 ## Delta 7 — Probe (PoC) tasks
@@ -103,7 +105,7 @@ Chassis § *Proof of concept (probe)*, instantiated for execution — for a plan
 plan-exec-loop(PPP-plan-<slug>.md):
   session = create_or_resume("<slug>-plan-exec")           # <slug> from the plan-doc; ONE session per run; CLI prepends global NNN; CHECKPOINT, resume
   plan = read(PPP-plan-<slug>.md)
-  for each Phase in plan (in order, respecting deps):
+  for each Phase (### Fn block in ## Tasks; legacy: ## Phases table) in plan (in order, respecting deps):
     if Phase done (all its Tasks - [x] in the plan): skip  # resume via plan-doc checkboxes
     seed CHECKPOINT.Next = Phase N (Pending = its Tasks)   # BEFORE starting the phase: seed the intent (artifact-first)
     for each Task of the Phase:
@@ -119,7 +121,7 @@ plan-exec-loop(PPP-plan-<slug>.md):
         if probe (PoC) task / runnable doubt → seed check → run throwaway code in the
             session folder → verdict → CONCLUSIONS/DECISION; failed → structured-choice (Delta 7)
         if doubt/gap → inline research, probe OR structured-choice   # chassis
-      mark Task - [x] + state IN THE PLAN                  # AFTER completing the Task (the plan-doc is the per-task source of truth)
+      mark Task - [x] IN THE PLAN                          # AFTER completing the Task; checkbox flip ONLY — results go to DECISION/CHECKPOINT
     phase validation:
         what runs and fails → back to the task
         what depends on an unapplied migration → defer (Open questions + BACKLOG)
@@ -132,7 +134,7 @@ plan-exec-loop(PPP-plan-<slug>.md):
     next-phase precondition: working tree clean or acknowledged
   final validation (whatever can run; the SQL-dependent part stays as a handoff)
   structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
-  mark plan done (or "done — SQL pending application")
+  mark plan done → ONE status line under the title blockquote (Delta 6), updated in place
   # NO export: artifacts stay in the session; a separate export-* promotes them
 finalize: CHECKPOINT (+ BACKLOG if something is deferred) + close session + report
 ```

package/skills/w/loops/plan-new-loop/LOOP.md

@@ -3,8 +3,9 @@ name: plan-new-loop
 description: >-
   Generates a rich implementation plan (docs/plans/PPP-plan-<slug>.md) from a
   spec. Heir of the chassis (loops/CHASSIS.md). Deltas: the plan absorbs the
-  TECHNICAL-NOTE level + Phases/Tasks with live state, code/impact-mapping
-  research, planning gap taxonomy, and per-screen design SPECs via ui-design
+  TECHNICAL-NOTE level + phased Tasks (### Fn blocks) with live state,
+  code/impact-mapping research, planning gap taxonomy, and per-screen design
+  SPECs via ui-design
   when the plan includes UI. If the spec is not refined it suggests
   spec-refine first. Started by /w:plan-new; resumable. Invoke when a spec
   must become an executable plan.
@@ -24,7 +25,7 @@ PLAN
 `/w:plan-new` — **resumable** (same chassis mechanism, keyed off CHECKPOINT).
 
 ## Reads
-`docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Refined vs draft** is distinguished by the **presence** of `## Refinement decisions` / `## Q&A traceability` in the spec: if missing → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), but the user may proceed.
+`docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Refined vs draft** is distinguished by the **presence** of `## Refinement decisions` in the spec (legacy specs may also carry `## Q&A traceability`): if missing → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), but the user may proceed.
 
 ## Writes
 `docs/plans/PPP-plan-<slug>.md` (`generate`; **overwrites with confirmation** if it exists) — or **several sibling plans** when an accepted split applies (§ *Split gate (multi-plan)*). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the plan **includes UI**, it also produces **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its session** (see *Delta 4* — they are not `docs/`, no auto-export).
@@ -55,23 +56,23 @@ The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roa
 > Derived from docs/specs/NNN-spec-<slug>.md · generated by plan-new-loop
 
 ## Origin              source spec · prompt (bootstrapped via spec-new) · "adopted from <source>" + attribution (external plan — /w:plan-new mode 4 / /w:persist)
-## Summary             the how, in 1–2 sentences                                (core)
-## Solution            technical/functional explanation of the implementation  (core)
+## Solution            the how (core): 1–2 summary sentences + the AS-IS → TO-BE
+                       delta (current vs target wiring, brief) + a closing
+                       "Final behavior" block — how the flow behaves at the end,
+                       aligned with the spec criteria. One narration, not four.
 ## Impacted            FE · BE · DB (schemas/tables/functions) · APIs · integr. (core)
-## Dependencies        docs / sources / databases / sessions                   (opt.)
-## Current state (AS-IS)   current wiring (interfaces and methods), brief      (opt.)
-## Target state (TO-BE)    target wiring                                       (opt.)
-## Final behavior      how the flow behaves at the end (aligned with the spec criteria) (core)
-## Phases              grouping phases (complexity XS–S)                       (core)
-## Tasks               tasks per phase (≤XS), with deps and live state (- [ ]) (core)
+## Dependencies        docs / sources / databases / sessions · inter-plan order on a split (opt.)
+## Tasks               (core) `### Fn — <name>` blocks — 1-line objective +
+                       complexity XS–S — each holding its `- [ ] Tn.m` tasks
+                       (≤XS, deps and live state). The `### Fn` headers are the
+                       ONLY source of phases; there is no separate Phases table.
 ## Validations         validations / constraints / business logic              (core)
 ## Risks / impact      technical risks and impacts                             (opt.)
-## Assumptions         assumptions                                             (opt.)
-## Estimated time      XS–XL sizing (development + internal testing)           (opt.)
-## Open questions      pending                                                 (core)
+## Assumptions         assumptions — only the delta over the spec, never re-imported (opt.)
+## Open questions      pending — core when any exist; OMIT the section when empty
 ```
 
-> **Scales with complexity:** the `(core)` sections go **always**; the `(opt.)` ones only when the plan warrants them — a small plan may omit `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Concise > exhaustive.
+> **Scales with complexity:** the `(core)` sections go **always**; the `(opt.)` ones only when the plan warrants them — a small plan may omit `Dependencies`, `Risks`, `Assumptions`. Concise > exhaustive. *(Legacy plans: `Summary`, `Current state (AS-IS)`, `Target state (TO-BE)`, `Final behavior`, `Phases` and `Estimated time` existed as separate sections — readers tolerate both shapes; new plans never write them.)*
 
 > **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/LOOP.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
 
@@ -97,7 +98,7 @@ Replaces the spec gap taxonomy with a planning-oriented one:
 
 ## Delta 3 — What research investigates here
 
-The chassis' **inline** research specializes: mapping **code/impact** — affected FE/BE/DB components, AS-IS wiring, dependencies. It feeds the `Solution`, `Impacted`, `Current state (AS-IS)` sections. The chassis DB rule applies unchanged (read-only queries into `SCRIPTS.sql`, MCP chosen via a content question when >1 without default).
+The chassis' **inline** research specializes: mapping **code/impact** — affected FE/BE/DB components, AS-IS wiring, dependencies. It feeds `Solution` (its AS-IS → TO-BE delta) and `Impacted`. The chassis DB rule applies unchanged (read-only queries into `SCRIPTS.sql`, MCP chosen via a content question when >1 without default).
 
 ## Delta 4 — Design SPECs (when the plan includes UI)
 
@@ -123,7 +124,7 @@ Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for
 - **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.
 - **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` covers its subset; the union covers the spec. Spec-less plans anchor the partition to their own `Final behavior` / `Validations`.
+- **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`).
 
 ## Sequence
@@ -131,7 +132,7 @@ Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for
 ```
 plan-new-loop(spec):
   input = glob(docs/specs/NNN-spec-*.md) | argument path
-  if the spec does NOT have ## Refinement decisions + ## Q&A traceability:
+  if the spec does NOT have ## Refinement decisions:
     soft-suggest /w:spec-refine (the user may proceed anyway)
   session = create_or_resume("<slug>-plan-new")               # CLI prepends global NNN
   seed SESSION.Success criteria = coherence-gate checklist      # verification-first, BEFORE
@@ -145,9 +146,9 @@ plan-new-loop(spec):
   coherence gate (read-only) = Success criteria green:
     - every spec acceptance criterion traces to a phase/task
       (split: each criterion → exactly one sibling — complete, disjoint partition)
-    - Final behavior covers the criteria
-    - phases XS–S · tasks XS · deps without cycles · Impacted consistent with Solution
-    - minimality (chassis § *Minimality*): the Solution is the lightest that meets Final behavior; no phase/task/abstraction the criteria don't require
+    - the Final behavior block of ## Solution covers the criteria
+    - ### Fn phases XS–S · tasks XS · deps without cycles · Impacted consistent with Solution
+    - minimality (chassis § *Minimality*): the Solution is the lightest that meets its Final behavior block; no phase/task/abstraction the criteria don't require
     - (UI) every screen/UI task traces to its design SPEC and does not contradict ## UI spec
     whatever fails → comes back as a gap
   if split accepted (§ Split gate (multi-plan)): work = the N sibling plans (same session; cut in CHECKPOINT)

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

@@ -4,8 +4,8 @@ description: >-
   Refines an existing plan (docs/plans/PPP-plan-<slug>.md) by editing it IN
   PLACE — an auxiliary, NOT mandatory step before plan-exec. Heir of the
   chassis (loops/CHASSIS.md). Deltas: reuses plan-new-loop's gap taxonomy and
-  coherence gate, adds Refinement decisions / Q&A traceability (trace, no
-  gating), and produces/updates design SPECs via ui-design when the refine
+  coherence gate, adds Refinement decisions (trace, no gating), and
+  produces/updates design SPECs via ui-design when the refine
   touches UI. Started by /w:plan-refine; resumable and re-runnable on demand.
   Invoke when an already generated plan must be adjusted before executing it.
 ---
@@ -32,7 +32,7 @@ PLAN
 `docs/plans/PPP-plan-*.md` (glob — locates the plan by number; or the exact path from the command argument). **Always the plan itself**: this loop edits it in place; there is no separate "refined" file. Provenance is irrelevant — generated by `plan-new`, **hand-written, or adopted** from a host planner (`plan-new` mode 4 / `persist`); existence is the only requirement.
 
 ## Writes
-Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions` + `## Q&A traceability`. Since it overwrites an existing doc, it asks the user's **confirmation**. On an accepted split (§ *Split gate — refine semantics*) it also **creates** the extracted sibling plans (newly minted `docs/plans` files). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the refine **touches UI**, it also produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its own session** (see *Delta 4* — they are not `docs/`, no auto-export).
+Updates `docs/plans/PPP-plan-<slug>.md` **in place** (when the user picks `Guardar plan refinado`): completes/adjusts sections and **adds** `## Refinement decisions`. Since it overwrites an existing doc, it asks the user's **confirmation**. On an accepted split (§ *Split gate — refine semantics*) it also **creates** the extracted sibling plans (newly minted `docs/plans` files). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the refine **touches UI**, it also produces/updates **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its own session** (see *Delta 4* — they are not `docs/`, no auto-export).
 
 ## Inherits
 
@@ -48,19 +48,17 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Delta 1 — Deliverable: the PLAN, edited in place
 
-The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md) produces (§ *Delta 1 — RICH PLAN*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** two trace sections:
+The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md) produces (§ *Delta 1 — RICH PLAN*: `Solution` (with its Final behavior block)/`Impacted`/`Tasks` (`### Fn` blocks)/`Validations`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** one trace section:
 
 ```markdown
-## Refinement decisions   ← NEW (ADDED)
+## Refinement decisions   ← NEW (ADDED) — the run's single trace
 What was adjusted while refining and why (new requirements, scope changes,
 deps/risks). Includes what inline research resolved (ref to the session's
-CONCLUSIONS).
-
-## Q&A traceability       ← NEW (ADDED)
-Every doubt asked to the human + the chosen answer.
+CONCLUSIONS) and every doubt asked to the human, as entries
+`Q: <question> → <chosen answer> — <rationale>`.
 ```
 
-> **No gating contract** (unlike spec↔plan): the presence of `## Refinement decisions`/`## Q&A traceability` in the plan is **audit trace only** — `plan-exec` neither requires nor checks it (it runs any plan). It serves to (a) distinguish a re-refined plan from a freshly generated one on resume, and (b) record what changed and why.
+> **No gating contract** (unlike spec↔plan): the presence of `## Refinement decisions` in the plan is **audit trace only** — `plan-exec` neither requires nor checks it (it runs any plan). It serves to (a) distinguish a re-refined plan from a freshly generated one on resume, and (b) record what changed and why. *(Legacy plans may also carry `## Q&A traceability`; new runs never write it.)*
 
 > The plan **never mutates by execution** (plan-exec tracks that in the plan-doc's Tasks) — only by a (re-)refine.
 
@@ -72,7 +70,7 @@ Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-l
 |---|---|---|
 | Plan↔spec drift | the spec was re-refined and the plan fell out of line | **research** (re-reads the spec) / **human** |
 
-> **Spec-less degradation (hand-written / adopted plans).** When the plan has **no source spec** (`## Origin` = adopted / hand-written), the spec-anchored checks **degrade gracefully**: "spec criteria uncovered" and "plan↔spec drift" do **not** apply — criterion→task traceability anchors to the plan's **own** `## Final behavior` / `## Validations` instead. The rest of the taxonomy (atomicity, deps, Impacted↔Solution, UI→SPEC) applies unchanged. Normalizing an adopted plan to the full Delta 1 schema **is** this loop's job (missing `(core)` sections are gaps).
+> **Spec-less degradation (hand-written / adopted plans).** When the plan has **no source spec** (`## Origin` = adopted / hand-written), the spec-anchored checks **degrade gracefully**: "spec criteria uncovered" and "plan↔spec drift" do **not** apply — criterion→task traceability anchors to the plan's **own** Final behavior block (in `## Solution`) / `## Validations` instead. The rest of the taxonomy (atomicity, deps, Impacted↔Solution, UI→SPEC) applies unchanged. Normalizing an adopted plan to the full Delta 1 schema **is** this loop's job (missing `(core)` sections are gaps).
 
 > **Adjust the Solution the laziest-that-works way** (chassis § *Minimality*, generative side): reuse what already exists before adding abstractions, layers or dependencies — the coherence gate only *confirms* minimality, and a re-refine is a chance to *remove* over-building, not add it.
 
@@ -95,7 +93,7 @@ The gate itself — signals, offer, anti-duplicate, sibling contract, partition
 
 ## Compact / resume — PLAN-refine keys
 
-Full mechanism (3 cases, `Compactar`, re-run with `--reopen`) in the chassis (§ *Compact / resume*). PLAN-refine keys: prior-work mark = `## Refinement decisions` + `## Q&A traceability` **in the plan**; re-refine on demand is **first-class** as many times as needed while the flow stays in PLAN.
+Full mechanism (3 cases, `Compactar`, re-run with `--reopen`) in the chassis (§ *Compact / resume*). PLAN-refine keys: prior-work mark = `## Refinement decisions` **in the plan** (legacy plans may also carry `## Q&A traceability`); re-refine on demand is **first-class** as many times as needed while the flow stays in PLAN.
 
 > **Inter-turn continuity** (chassis, row 2): a flow command opens a "new work line" (new session) — **except re-running the same flow over the same input** (same plan), which does `create_or_resume` (resumes/reopens instead of duplicating).
 
@@ -115,8 +113,8 @@ plan-refine-loop(plan):
       ui-design (Delta 4, only new/changed screens)
     integrate + update CHECKPOINT                              # artifact-first cycle
   coherence gate (read-only) = Success criteria green:
-    - plan-new checklist (criterion→task · Final behavior · XS–S/XS · deps · Impacted↔Solution · UI→current SPEC · minimality)
-      # spec-less plan (adopted/hand-written): criteria anchor to the plan's own Final behavior/Validations (see Delta 2)
+    - plan-new checklist (criterion→task · Final behavior block of Solution · XS–S/XS · deps · Impacted↔Solution · UI→current SPEC · minimality)
+      # spec-less plan (adopted/hand-written): criteria anchor to the plan's own Final behavior block/Validations (see Delta 2)
     - re-refine's own check: the plan is REALIGNED with what changed
     whatever fails → comes back as a gap
   if split accepted (plan-new-loop § Split gate (multi-plan)): work = original reduced + extracted siblings
@@ -124,7 +122,7 @@ plan-refine-loop(plan):
     Guardar planes → edit original reduced (confirmation) + write extracted siblings + record in Refinement decisions
   else:
     structured_choice(content: [Guardar plan refinado, Preguntar algo más], flow: [Compactar, Cerrar])
-    Guardar → edit in place (with confirmation) + insert/update Refinement decisions + Q&A traceability
+    Guardar → edit in place (with confirmation) + insert/update Refinement decisions
 finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close session + report
 ```
 

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

@@ -5,8 +5,8 @@ description: >-
   until it is unambiguous. Heir of the chassis (loops/CHASSIS.md). Deltas:
   spec gap taxonomy, analyze gate, ideation gate (consented brainstorming,
   optional web-research), ## UI spec section via the ui-design
-  capability, and adds Refinement decisions + Q&A traceability — the refined
-  mark plan-new detects. Started by /w:spec-refine (or the live escalation
+  capability, and adds Refinement decisions — the refined mark plan-new
+  detects. Started by /w:spec-refine (or the live escalation
   from quick-loop); resumable via CHECKPOINT and re-runnable on demand.
   Invoke to refine/disambiguate a specification before planning.
 ---
@@ -34,7 +34,7 @@ It is also started by the **live escalation from `quick-loop`** (entry gate or m
 - `docs/specs/NNN-spec*.md` (glob — locates the spec by number; also catches the legacy `NNN-spec.md`), **or** the exact path passed as the command argument. **Always the spec itself**: this loop edits it in place; there is no separate "refined" file.
 
 ## Writes
-Updates `docs/specs/NNN-spec-<slug>.md` **in place** (when the user picks `Guardar especificación refinada`): completes sections and **adds** `## Refinement decisions` + `## Q&A traceability`, closing `Open questions` as they get resolved. 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 `Guardar especificación refinada`): completes sections and **adds** `## Refinement decisions`, closing `Open questions` as they get resolved. Since it overwrites an existing doc, it asks the user's **confirmation**.
 
 > **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*).
 
@@ -62,7 +62,7 @@ Other transversal capabilities the engine always uses: `research` (**inline**
 
 ## Deliverable schema (the spec, edited in place)
 
-The spec is completed **in place**: the draft's sections get **completed** + two new ones are **added** (`Refinement decisions`, `Q&A traceability`). NO separate file is created.
+The spec is completed **in place**: the draft's sections get **completed** + one new one is **added** (`Refinement decisions`). NO separate file is created.
 
 ```markdown
 # Spec NNN — <slug>
@@ -74,23 +74,24 @@ The spec is completed **in place**: the draft's sections get **completed** + two
 ## Context                (complete)
 ## Scope                  (clear In / Out)
 ## Acceptance criteria    (testable, - [ ]; EARS style; behavioral ones expand in ## Scenarios)
-## Scenarios              (opt. — GIVEN/WHEN/THEN/AND blocks; each traces to ≥1 criterion)
+## Scenarios              (opt. — GIVEN/WHEN/THEN/AND blocks; each traces to ≥1 criterion.
+                           Only when it adds GIVEN setup or edge semantics the criterion
+                           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).
 
-## Refinement decisions   ← NEW (ADDED)
+## Refinement decisions   ← NEW (ADDED) — the run's single trace
 What was defined while refining and why. Includes what inline research
-resolved (ref. the session's CONCLUSIONS) and the ideation verdicts (§ Ideation gate).
+resolved (ref. the session's CONCLUSIONS), the ideation verdicts (§ Ideation
+gate) and every doubt asked to the human, as entries
+`Q: <question> → <chosen answer> — <rationale>`.
 
-## Q&A traceability       ← NEW (ADDED)
-Every doubt asked to the human + the chosen answer.
-
-## Open questions         (ideally "None"; whatever remains is deferred)
+## Open questions         (whatever remains is deferred; OMIT the section when empty)
 ```
 
-> **Refined mark (contract with PLAN):** the presence of `## Refinement decisions` + `## Q&A traceability` distinguishes a refined spec from a draft — plan-new detects it this way, NOT by filename; without those 2 sections plan-new soft-suggests spec-refine.
+> **Refined mark (contract with PLAN):** the presence of `## Refinement decisions` distinguishes a refined spec from a draft — plan-new detects it this way, NOT by filename; without that section plan-new soft-suggests spec-refine. *(Legacy specs also carry `## Q&A traceability` — they still count as refined; new runs never write it.)*
 
 > **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.
 
@@ -104,7 +105,7 @@ Every doubt asked to the human + the chosen answer.
 | Incomplete context | systems/components unidentified | **research** |
 | Blurry scope | `Out` missing, or In/Out overlap | **human** |
 | Untestable criteria | acceptance not verifiable | **human** (derive + confirm — often as a `### Scenario`) |
-| Scenario missing | behavioral criterion without a `### Scenario` | the AI drafts GIVEN/WHEN/THEN + **human** confirms |
+| Scenario missing | behavioral criterion whose behavior is NOT captured by its WHEN/THEN (needs GIVEN setup or edge semantics; a criterion a scenario would only restate 1:1 is not a gap) | the AI drafts GIVEN/WHEN/THEN + **human** confirms |
 | Open questions pending | explicit doubts | by nature |
 | Hidden assumptions | the spec assumes unstated things | **research** validates / **human** confirms |
 | Internal contradiction | sections contradict each other | **human** |
@@ -154,7 +155,7 @@ spec-refine-loop(spec):
       switch(flow):
         Compactar → write CHECKPOINT (refine_session) ; compact(harness) ; continue
         Cerrar    → goto finalize
-      work = integrate(work, ans)            # → Q&A traceability / Open questions
+      work = integrate(work, ans)            # → Refinement decisions (Q: entries) / Open questions
       ideation offer accepted → run the round NOW, then its verdicts as a NEW ≤3+flow batch (§ Ideation gate) → integrate
       ideation offer declined → mark that gap exhausted    # anti re-fire; on-demand entry stays open
   # no material gaps → analyze gate = Success criteria green (read-only) before offering Guardar:
@@ -162,7 +163,7 @@ spec-refine-loop(spec):
   if issues: gaps += issues ; continue            # findings come back into the loop as gaps
   ans = structured_choice(content: [Guardar refinada, Preguntar algo más],
                         flow: [Compactar, Cerrar])
-  Guardar            → edit_in_place_with_confirm(spec)  # completes sections + inserts UI spec/Refinement decisions/Q&A ; goto finalize
+  Guardar            → edit_in_place_with_confirm(spec)  # completes sections + inserts UI spec/Refinement decisions ; goto finalize
   Preguntar algo más → continue
   flow Compactar/Cerrar → handle the same way
 finalize:
@@ -175,12 +176,12 @@ finalize:
 
 Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the chassis (§ *Compact / resume*). SPEC keys:
 
-- The **prior-work mark** is the presence of `## Refinement decisions` + `## Q&A traceability` in the spec (the *refined mark*, see *Deliverable schema*).
+- The **prior-work mark** is the presence of `## Refinement decisions` in the spec (the *refined mark*, see *Deliverable schema*; legacy specs may also carry `## Q&A traceability`).
 - Re-refining on demand is a **first-class operation** while the flow stays in SPEC (new requirements, scope changes, after re-reading the spec): it always reads the **spec itself**, incremental re-refinement; on `Guardar`, edits in place with confirmation.
 
 ## Convergence / exit
 
-- **No material gaps** → **analyze gate** (read-only) = **`Success criteria` green** (*verification-first*; the SPEC instance of the chassis convergence gate): every acceptance criterion traces to the `Requirement`, no internal contradictions, coherent `Scope` In/Out, `Open questions` closed or explicitly deferred. **Minimality** — no gold-plating: every criterion and scope item earns its place (chassis § *Minimality*); speculative scope is cut or deferred. Scenarios must trace to ≥1 criterion — and behavioral criteria to ≥1 scenario — without contradicting `Scope`. Whatever fails **comes back as a gap**; if it passes → offer `Guardar especificación refinada`.
+- **No material gaps** → **analyze gate** (read-only) = **`Success criteria` green** (*verification-first*; the SPEC instance of the chassis convergence gate): every acceptance criterion traces to the `Requirement`, no internal contradictions, coherent `Scope` In/Out, `Open questions` closed or explicitly deferred. **Minimality** — no gold-plating: every criterion and scope item earns its place (chassis § *Minimality*); speculative scope is cut or deferred. Scenarios must trace to ≥1 criterion — and add GIVEN setup or edge semantics beyond it (a 1:1 restatement of a criterion is gold-plating: cut it) — without contradicting `Scope`. Whatever fails **comes back as a gap**; if it passes → offer `Guardar especificación refinada`.
 - `Guardar` → `edit_in_place_with_confirm(spec)` and `finalize`.
 - `Cerrar` → the chassis `finalize` (always persists `CHECKPOINT`; `BACKLOG` **only if** something is deferred — here: close reason + deferred `Open questions`).
 
@@ -188,6 +189,6 @@ Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the c
 
 - Resolved via **inline research** → the spec's `## Refinement decisions` (+ ref to the session's `CONCLUSIONS`).
 - Resolved via **ideation** → per verdict (§ *Ideation gate*): `Adoptar` → the spec's sections + `## Refinement decisions` · `Descartar` → there · `Aparcar` → `## Open questions`.
-- Resolved via **human** → the spec's `## Q&A traceability`.
+- Resolved via **human** → the same `## Refinement decisions`, as a `Q: <question> → <chosen answer> — <rationale>` entry.
 - Resolved via the **`ui-design` capability** (UI gap) → the spec's `## UI spec` section.
 - **Inconclusive or unresolved research** → the spec's `## Open questions` (deferred) + the refine session's `BACKLOG.md` (only if something is deferred).