@tacuchi/agent-workflow-cli 20.23.0 → 20.24.0

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

@@ -41,7 +41,7 @@ Closing *every* gap turns the spec into a premature plan. Close what changes **w
 ## Reads
 - `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.
 
-> **Boundary with `spec-new`:** the draft arrives from a **bounded reconnaissance** of the surface ([`../../commands/spec-new.md`](../../commands/spec-new.md) § *Bounded reconnaissance*) — hypotheses, not verified facts. **Deep investigation is this loop's**: walk the dependencies, check those hypotheses, and close the doubts parked in `## Open questions`.
+> **Boundary with `spec-new`:** the draft arrives from a **bounded reconnaissance** of the surface ([`../../modules/RECONNAISSANCE.md`](../../modules/RECONNAISSANCE.md), `spec-new`'s `reconnaissance` module) — hypotheses, not verified facts. **Deep investigation is this loop's**: walk the dependencies, check those hypotheses, and close the doubts parked in `## Open questions`.
 
 **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).
 
@@ -80,31 +80,6 @@ When the project already exists, establish the current behavior the change rests
 
 **Stop when the baseline is enough to state and accept the functional change** — not when the system is documented. Digging on to pick an architecture, anticipate tasks or map every dependency is `PLAN` work, and gold-plating here. Greenfield has no baseline: skip it — that is what makes `## Behavioral changes` earn its place or not.
 
-## 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.
-
-> **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.
-
-- same outcome — more clarity, or more technical components → **`same`**: no shape question, keep refining this spec;
-- independent functional outcomes discovered → **`split`** (below);
-- purpose fundamentally changed → **`replace`** (below);
-- refactor indispensable to the outcome → a consideration for `PLAN`, never its own spec; refactor with no functional change → out of the contract;
-- evidence insufficient → **`same`** + the uncertainty recorded. Thin evidence never justifies a cut.
-
-**Split criterion** — the one `spec-new` already uses ([`../../commands/spec-new.md`](../../commands/spec-new.md) § *Split gate (multi-spec)*), 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`.
-
-**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.
-
-- **New spec:** this one is **preserved**, its purpose never silently rewritten; the new one is minted with `aw next-number docs/specs`, born **`status: draft`**, its `## Origin` recording the origin spec, the replaced purpose and the user's decision. Its path goes to the `CHECKPOINT`; the run closes reporting `/w:spec-refine <new path>` as the next step.
-- **Reformulate:** same number/path, the work treated as `refining` while rewritten; baseline, gap classification and the *ready-for-plan gate* run again over the new purpose; `status` is stamped only on the save that follows the passing gate, and the material decision lands in `## Decisions`.
-
-**Every branch has a way out that changes nothing.** The `flow` control present on every structured-choice (chassis) is that exit here: `Cerrar` closes the run **without applying the shape change** — no sibling minted, no spec reformulated, the document untouched and the decision recorded in `CHECKPOINT` as declined. And no branch writes a file without the user's confirmation: minting siblings and minting a replacement both go through the same confirm-before-write rule as an in-place save.
-
-Neither branch adds a `superseded` status or archives the replaced spec: a historical close needs its own runtime contract, out of scope here.
-
 ## Deliverable schema (the spec, edited in place)
 
 The spec is completed **in place**: the draft's sections get **completed**, a few are **added**, and the frontmatter `status` is stamped. NO separate file is created.
@@ -175,19 +150,6 @@ The choices a reader needs in order to interpret the contract, each with its why
 
 **Resolution order** — the chassis *ask-vs-research rule* with the destination step in front: settled in the conversation → **adopt** · provable by reading repos or data → **research inline** · depends on what the user wants → **ask** · defines the technical solution without changing behavior → **hand to `PLAN`** · answerable later without touching the contract → **defer explicitly**.
 
-## 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.
-
-**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.
-
-**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.
-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.
-
 ## Sequence
 
 ```
@@ -254,16 +216,6 @@ finalize:
   close refine_session ; report
 ```
 
-## Compact / resume — SPEC keys
-
-Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the chassis (§ *Compact / resume*). SPEC keys:
-
-- The **prior-work mark** is the frontmatter `status: ready-for-plan` (legacy specs: `## Refinement decisions`, older ones also `## Q&A traceability`).
-- The **shape decision survives a resume.** It is written to `CHECKPOINT` the moment it is taken, before anything acts on it, so a compact, a `Cerrar` or a crash between the gate and the save re-enters with the shape settled — the gate is not re-run and the question is not re-asked. Only a *new* run over a spec whose baseline changed re-opens it.
-- 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.
-- **Legacy migration happens only here.** A re-refined legacy spec runs the gate like any other; on `Guardar`, its `## Refinement decisions` is renamed `## Decisions` and pruned to the material decisions — **in the same write that stamps `status`**, so the spec is never left with no mark. Specs nobody re-refines are not migrated.
-- **`Cerrar` before converging leaves the spec untouched**: the progress lives in the `CHECKPOINT`, and `status` is neither invented nor downgraded. `refining` is understood **on read** (a hand-written spec may declare it) — this loop never writes a partial spec.
-
 ## Convergence / exit
 
 - **No blocking gaps** → **ready-for-plan gate** (read-only) = **`Success criteria` green** (*verification-first*; the SPEC instance of the chassis convergence gate). The checklist:
@@ -285,3 +237,9 @@ Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the c
 - **`ui-design` capability** (UI gap) → the spec's `## UI spec` section.
 - **Owned by `PLAN` or deferred** → `## Open questions` with its destination, and nothing else in the spec.
 - **Inconclusive or unresolved research** → `## Open questions` (deferred) + the refine session's `BACKLOG.md` (only if something is deferred).
+
+## Conditional modules
+
+- `shape` — the change-shape gate and its split / replace branches → `../../modules/SPEC-CHANGE-SHAPE.md`
+- `web` — the conditional ideation gate, its triggers and verdicts → `../../modules/IDEATION-GATE.md`
+- `resume` — the SPEC keys of compact / resume → `../../modules/SPEC-REFINE-KEYS.md`

package/skills/w/modules/ADOPTED-CONTEXT.md

@@ -0,0 +1,10 @@
+# ADOPTED-CONTEXT — the host as a producer of input
+
+Loaded when the conversation already produced the analysis, plan or answers the run needs (signal `adopted`).
+
+The host is not only the loop's executor — it is a legitimate **producer** of input. Conclusions **already established in the current conversation** (a host-native analysis, answers the user already gave, a plan built with the host's planner) count as **completed research**: on entry, **adopt** them — seed `SESSION.Objective`/`Success criteria`, reference them in `CONCLUSIONS`, record provenance (`## Origin` = adopted from the host conversation) — never re-derive or re-ask them.
+
+- Adoption is **transcription, not trust**: the convergence gate still verifies adopted conclusions (*gate integrity*); anti-duplicate still applies.
+- Materialization pattern = the quick escalation's (single-pass, **NO RESEARCH**), inverted: **host → flow**.
+- Gap signals already resolved by adopted context do **not** fire (e.g. "ambiguous requirements" after a host pre-analysis).
+- To persist finished work without a loop: [`/w:persist`](../commands/persist.md) (transversal).

package/skills/w/modules/COMPACTION.md

@@ -0,0 +1,13 @@
+# COMPACTION — the loop watching its own context pressure
+
+Loaded when the run is long enough that context pressure governs its pacing (signal `compaction`).
+
+`Compactar` is not only reactive: the loop **watches its own context pressure** and raises compaction itself.
+
+- **Signal**: the host's context-pressure signal when it exists (see the *compaction* capability in [`../harness/HARNESS.md`](../harness/HARNESS.md)); with no signal the fallback is **qualitative** — at batch/phase boundaries of an already-long run, ask *"would a fresh reader need the CHECKPOINT to continue?"*. Doctrine fixes **no numeric thresholds** (harness-agnostic).
+- **Modes** — config `[compaction]` table in `.workflow/skills.toml`, key `mode` (values `confirm` | `auto`):
+  - **`confirm`** (default, also with no config): raise a **proactive structured-choice** whose `flow` control carries `Compactar` as the recommended action — the human ratifies; consent is never skipped.
+  - **`auto`** (opt-in): write `CHECKPOINT.md`, then trigger the host's compaction binding **without asking**. Viable only where the host has a **non-interactive** mechanism (see the *Harness binding matrix*); otherwise it **degrades to `confirm`**.
+- **Invariant — CHECKPOINT before compacting**: in every mode, `CHECKPOINT.md` is written (or verified fresh) **before** any compaction fires; resume keys off it.
+
+> **`Compactar`** (the `flow` control) → write `CHECKPOINT.md` in the session (in-flight progress, remaining gaps, Q&A, `attempts`) → trigger the harness **compaction** (Claude Code: `/compact`; see [`../harness/HARNESS.md`](../harness/HARNESS.md)) → resume by reading the checkpoint.

package/skills/w/modules/DB-RESEARCH-RULE.md

@@ -0,0 +1,11 @@
+# DB-RESEARCH-RULE — the single exception to research autonomy
+
+Loaded when the run reads or writes a database (signal `db`).
+
+Investigation is otherwise autonomous: the AI investigates inline and reports without asking permission. A database is the one place where it asks first.
+
+1. **MCP choice**: if the gap needs DB and there is **>1 candidate MCP with no configured default**, the AI asks which one to use. That question goes through the **same structured-choice** as a **content question** (counts inside the ≤3 + `flow` limit), **before** running queries. A single MCP or a default → no question.
+2. Write the queries **first** into the session's `SCRIPTS.sql`.
+3. Execute them **read-only** via MCP (respect `sql-mutation-guard`: never DML/DDL).
+
+> The AI **never executes DML/DDL**. A migration is drafted in the session's `SCRIPTS.sql` and handed off; promoting it to `docs/scripts/` is a separate `export-*`, never a loop.

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

@@ -0,0 +1,12 @@
+# DB-SCRIPTS-ONLY — mutating SQL is drafted, never executed
+
+Loaded when a code-editing run touches the database (signal `db`).
+
+## DB scripts-only — the AI never executes DML/DDL
+
+Distinguished by **execution**, not by file (see the [`SCRIPTS.sql`](../artifacts/artifacts-core/SCRIPTS.sql) schema):
+
+- **Read-only queries** (diagnosis/validation) → `SCRIPTS.sql` (session artifact); the AI **does** execute them read-only via MCP (`sql-mutation-guard`).
+- **DDL/DML migrations** (schema/data changes) → the AI **drafts them in `SCRIPTS.sql`** (session artifact) but **NEVER executes them**.
+
+> Mutating SQL **stays in the session**; it is never moved to `docs/`. Its promotion to `docs/scripts/` (forward + rollback) is done by a separate `export-*`, never by the loop.

package/skills/w/modules/EXEC-DB-POLICY.md

@@ -0,0 +1,7 @@
+# EXEC-DB-POLICY — the DB rule inside execution
+
+Loaded when a phase touches the database (signal `db`).
+
+## Delta 3 — DB policy: **the AI never executes DML**
+
+Full policy in [`DB-SCRIPTS-ONLY.md`](DB-SCRIPTS-ONLY.md), the `db` module of [`../loops/CODE-POLICIES.md`](../loops/CODE-POLICIES.md). **Inline:** read-only queries → the session's `SCRIPTS.sql`, executed via MCP (`sql-mutation-guard`); DDL/DML migrations → the AI **drafts them in `SCRIPTS.sql` but NEVER executes them** — their promotion to `docs/scripts/` is done by a separate `export-*`, never this loop.

package/skills/w/modules/EXEC-PROBE-TASKS.md

@@ -0,0 +1,11 @@
+# EXEC-PROBE-TASKS — probe (PoC) tasks inside execution
+
+Loaded when the run hits a probe task or a runnable doubt (signal `probe`).
+
+## Delta 7 — Probe (PoC) tasks
+
+Chassis § *Proof of concept (probe)*, instantiated for execution — for a plan's explicit probe task or a runnable doubt inside a task:
+
+- Seed the question + pass/fail check → run **throwaway code in the session folder** (never the source tree, never committed; DB probe = read-only) → verdict in `CONCLUSIONS`, consequences in `DECISION` (tagged by task) → mark the task with its verdict.
+- A **failed probe does not fail the phase** — it de-risked it: surface it (structured-choice); reshaping the plan goes to `Open questions` + `BACKLOG` (or `/w:plan-refine`).
+- **Promotion**: probe code reaches the sources only as a normal task edit (branch-check + review gate) — never by committing the probe.

package/skills/w/modules/IDEATION-GATE.md

@@ -0,0 +1,16 @@
+# IDEATION-GATE — widen the option space before the spec hardens
+
+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.
+
+**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.
+
+**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.
+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/INCREMENTAL-STRATEGY.md

@@ -0,0 +1,7 @@
+# INCREMENTAL-STRATEGY — the reference shape of an incremental change
+
+Loaded when the work is being staged into tranches or phases (signal `split`).
+
+## Incremental strategy (reference, never a template)
+
+A change spread over consumer, service and data often lands well as: consumer shell → minimal real integration → vertical skeleton → real implementation from the source outwards → hardening → finish. **Reference to adapt, never a mandatory shape.** Backend-only, CLI, batch, library and database-only changes have their own journey, and inserting a layer the project does not have fails the minimality lens. A small change may be **one phase**, when that phase already is a coherent verifiable state.

package/skills/w/modules/LAUNCH-DETECTION.md

@@ -0,0 +1,26 @@
+# LAUNCH-DETECTION — how the run command and the launch mode are derived
+
+Loaded when the CLI's detection is wrong, ambiguous or must be overridden (signal `detection`).
+
+## Detection (how "run the project locally" is derived)
+
+- **npm** — a run script first (`dev` > `start` > `serve`, → `server`); else a CLI/app entry
+  (`bin` > `main`) run with `node`, **building first** (`npm run build`) when a `build` script
+  exists — a TypeScript CLI runs from its compiled output (→ `interactive`).
+- **gradle** / **maven** — `./gradlew bootRun` / `./mvnw spring-boot:run` (`server`).
+- **angular** — `npm start` (`server`).
+- **Launch mode** governs how the TUI "Lanzar" (and the wrapper) run the app: `interactive` =
+  foreground, owns the TTY (the UI appears); `server` = backgrounded, output tee'd to the log.
+  The heuristic guesses it; `--mode` overrides. A `build` step, when present, runs before the
+  launch in both modes.
+
+## Behavior
+
+- **Idempotent** — a pristine generated file is refreshed; a hand-edited one (its hash marker no
+  longer matches) is **preserved**. `--force` overwrites hand-edited files too (reported as
+  `overwritten`).
+- **`--source <alias>`** (repeatable) restricts to the given sources; default = every declared source.
+- **`--mode interactive|server`** overrides the detected mode for the selected source(s).
+- **`--command "<cmd>"`** overrides the run command for a **single** selected source
+  (self-contained: it drops the auto build).
+- **`--dry-run`** classifies every file and writes nothing.

package/skills/w/modules/PERSIST-ROUTING.md

@@ -0,0 +1,16 @@
+# PERSIST-ROUTING — which shape goes where
+
+Loaded when classifying what to persist (signal `classification`).
+
+| Shape | Signals | Category → destination |
+|---|---|---|
+| **Analysis / conclusions / design notes** | findings, comparisons, diagnoses, adjudications, recommendations | `research` → `docs/research/NNN-research-<slug>.md` |
+| **Requirement** | describes a *wish*: what should exist/change, acceptance criteria derivable | `spec` → `docs/specs/NNN-spec-<slug>.md`, born `status: draft`, `## Origin` = "adopted from host conversation" → offer `/w:spec-refine` |
+| **Plan** | already answers the *how*: phases/tasks/solution — e.g. the host plan-mode output | `plan` → `docs/plans/NNN-plan-<slug>.md` (adoption) → offer `/w:plan-refine` / `/w:plan-exec` |
+| Mixed / ambiguous | e.g. analysis that ends in a requirement | one `persist` per document, each confirmed; a research doc plus a spec draft that cites it is a valid split |
+
+## `docs/research/` — the analysis home (owned by this command)
+
+`docs/research` hosts standalone analyses: neither spec nor plan, but worth keeping. Belongs to **no flow**; `export-*` never writes it; loops never read it implicitly (a flow uses it by **reference** — cited in a spec's `## Origin` or a quick prompt). It is git-shareable, unlike sessions (gitignored, machine-local, loop-owned), which makes it the exchange surface for **N agents analyzing the same situation**.
+
+> **Anti-duplicate is a decision, not an accident.** The inventory carries each existing document's summary and digest. Same work already there → `mode: "update"` (proving you saw the current bytes via `target_digest`) or `state: "ambiguous"` so the user chooses between updating and writing a sibling perspective. A second near-identical document is never created silently.

package/skills/w/modules/PLAN-DESIGN-SPECS.md

@@ -0,0 +1,12 @@
+# PLAN-DESIGN-SPECS — per-screen design SPECs when the plan includes UI
+
+Loaded when the plan includes UI (signal `ui`).
+
+## Delta 4 — Design SPECs (when the plan includes UI)
+
+The **UI without design SPEC** gap is resolved by **composing** the **`ui-design`** capability (built-in default [`ui-spec`](../roles/ui-spec/ROLE.md); rebindable via `.workflow/skills.toml`; `off` → degrades to human / `Open questions`):
+
+- It authors **one design SPEC per screen** as a session artifact: `NNN-SPEC-<SLUG>.md` (numbering local to the session — see [`SPEC.md`](../artifacts/artifacts-design/SPEC.md)).
+- It **derives** from the spec's `## UI spec` section when present (splits it per screen and raises it to executable detail); otherwise it authors from the `Requirement` (design system/theme/ambiguities via *structured-choice*, counts in the batch).
+- The plan's **UI Tasks reference** their SPEC's path — that reference is the **source of truth** — and `plan-exec-loop` reads them as the design reference.
+- It is the chassis' composed-capability resolution mode (next to *research*, *probe* and *human*).

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

@@ -0,0 +1,26 @@
+# PLAN-INPUT — what the argument to a plan command actually is
+
+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.
+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.
+
+> **Mode 3 vs 4:** a prompt that *describes a wish* → SPEC (mode 3); content that *already is a plan* → adopt (mode 4).
+
+> **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
+
+1. **Existing plan** (`docs/plans/PPP-plan-<slug>.md`) → proceed, **regardless of provenance**: generated, hand-written, or adopted. Existence is the only requirement.
+2. **No plan** → **soft-suggest** `/w:plan-new` first; the user decides.
+3. **Returned by `plan-exec`** (its entry check found the plan unexecutable, or execution stopped on a structural deviation) → proceed carrying that finding: phases already `validada` stay, only pending work is re-designed.
+
+> **Spec-less plans are legitimate input.** The coherence gate **degrades gracefully**: criteria trace to the plan's own Final behavior block instead of spec criteria, and the "spec criteria uncovered" gap does not apply.
+
+## 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.

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

@@ -0,0 +1,26 @@
+# PLAN-MODE — what every Workline command does when the host is planning
+
+Loaded only when the host reports it is in plan mode (signal `plan-mode`). Sixteen commands
+used to carry a paragraph of this each; the rule was the same in all of them, so it is stated
+once here.
+
+## The rule
+
+In plan mode a command **describes** and **writes nothing**. It resolves its input, states what
+it would do and what it would touch, and stops:
+
+- **Flow commands** (`spec-new`, `spec-refine`, `plan-new`, `plan-refine`, `plan-exec`, `quick`):
+  describe the loop actions they would run — the gaps they would close, the questions they would
+  ask, the phases they would execute, the files they would touch and the commits they would
+  propose. No session is created, no loop is started, no document is written.
+- **Direct surfaces** (`status`, `resume`, `persist`, `fix-git`, `generate-launch`,
+  `workspace-init`, `export-*`): run their read-only `prepare` step if they have one and report
+  what it returned. Never `validate`, never `apply`.
+
+## Two things it does NOT change
+
+1. **A read-only command is already safe.** `status` and `resume` write nothing in any mode;
+   plan mode does not make them describe instead of answering.
+2. **The gates that would fire still get named.** A size gate that would escalate, a spec that
+   would be sent back to refine, a structural deviation that would stop execution — plan mode
+   reports them as part of the description instead of hiding them until the real run.

package/skills/w/modules/PLAN-PROBE-TASKS.md

@@ -0,0 +1,10 @@
+# PLAN-PROBE-TASKS — probes that de-risk a plan early
+
+Loaded when the plan rests on a runnable assumption (signal `probe`).
+
+## Delta 5 — Probe (PoC) tasks — de-risk early
+
+Chassis § *Proof of concept (probe)*, instantiated for planning. Two placements:
+
+- **Plan-shaping unknown** (the `Solution` itself depends on the answer) → run the probe **inline now**; the verdict (`CONCLUSIONS`) feeds `Solution` / `Risks / impact`.
+- **Execution-time risk** (a task will build on a risky, runnable assumption) → encode an explicit **probe task**, placed **early** — before the tasks that depend on its verdict; the matching `Risks / impact` entry references it.

package/skills/w/modules/PLAN-REFINE-DESIGN-SPECS.md

@@ -0,0 +1,7 @@
+# PLAN-REFINE-DESIGN-SPECS — design SPECs for the screens a refine touches
+
+Loaded when the refine touches UI (signal `ui`).
+
+## Delta 4 — Design SPECs (when the refine touches UI)
+
+Same mechanism as [`plan-new-loop`](../loops/plan-new-loop/LOOP.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.

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

@@ -0,0 +1,9 @@
+# PLAN-REFINE-KEYS — the compact / resume keys of a plan refinement
+
+Loaded when the run resumes or re-runs a refinement of this plan (signal `resume`).
+
+## 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` **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).

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

@@ -0,0 +1,12 @@
+# PLAN-REFINE-SPLIT — splitting a plan that already exists
+
+Loaded when an existing plan may have to be split in place (signal `split`).
+
+## Split gate — refine semantics
+
+The gate itself — signals, offer, anti-duplicate, sibling contract, partition — is defined **once** in [`PLAN-SPLIT-GATE.md`](PLAN-SPLIT-GATE.md), `plan-new-loop`'s `split` module (this flow's guaranteed load already includes that file); this loop only adds the **in-place semantics** of splitting an existing plan:
+
+- 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`.

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

@@ -0,0 +1,14 @@
+# PLAN-SPLIT-GATE — the canonical multi-plan split gate
+
+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`.
+
+- **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.
+- **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`).

package/skills/w/modules/PROBE.md

@@ -0,0 +1,12 @@
+# PROBE — proof of concept, the resolver for executable doubt
+
+Loaded when the run rests on a runnable assumption that reading cannot settle (signal `probe`).
+
+## Proof of concept (probe)
+
+A **probe** (PoC / spike) is the resolver for **executable doubt**: research *reads*, a probe *runs* — an **atomic, throwaway-by-default** experiment answering **one falsifiable question** (does this connection / SDK / UI behavior work as assumed?). De-risk atomic parts **early**, never everything at the end.
+
+- **When**: risky assumption + not answerable by reading + failure would invalidate downstream work. Proposed via **structured-choice**.
+- **Lifecycle** (verification-first applies to the probe): seed question + pass/fail check **BEFORE** → run minimal → verdict in `CONCLUSIONS` (consequences → `DECISION`) → **discard** or promote to a real task/test.
+- **Isolation**: probe code lives in the **session folder** (gitignored) — never the source tree, **never committed**; DB probes are read-only (never DDL/DML).
+- A **failed probe is a finding, not a failure** — report it; the human decides if the plan reshapes.

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

@@ -0,0 +1,13 @@
+# PROMPT-CONTINUITY — one work line across several prompts
+
+Loaded when a bare prompt continues an existing work line (signal `resume`).
+
+## Continuity across prompts (operating context)
+
+`quick` is where the **continuity rule** ([`../../SKILL.md`](../../SKILL.md) § *Operating context*) shows most clearly. Inside a workspace:
+
+1. `/w:quick "first prompt"` (**command**) → creates session `NNN-<slug>-quick`, starts the loop. Scripts go to **its** `SCRIPTS.sql`.
+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.

package/skills/w/modules/RECONNAISSANCE.md

@@ -0,0 +1,48 @@
+# RECONNAISSANCE — the bounded look that precedes a scope decision
+
+Loaded when a draft is being cut from a raw prompt and the terrain is not yet known (signal
+`reconnaissance`).
+
+## Bounded reconnaissance
+
+A scope decision taken from the prompt alone mistakes **technical** boundaries for **functional**
+ones. So, before deciding, take **one** shallow look at the terrain — enough to form a reasonable
+hypothesis of the functional unit, never enough to answer how it will be built.
+
+**Scope of the pass.** It runs **only on a raw user prompt** (direct invocation, or the `plan-new`
+mode-3 handoff). The reuse entries skip it: the quick escalation and the `persist` adoption arrive
+with their context **already established**, and adopting it is transcription, not reconnaissance
+(**NO RESEARCH** — chassis section *Adopted context*).
+
+One pass, in this order: **adopt** what the conversation already settled (never re-derive it),
+**identify** the candidate sources, **look** at their surface, **stop**.
+
+- **Sources allowed** (a permission, not an obligation to read them all):
+  - the workspace's registered sources — `aw sources --no-git`, or the `WORKSPACE` block.
+  - each candidate source's main instructions file, plus the head of its `README`.
+  - build manifests: `package.json`, `pom.xml`, `build.gradle`, `requirements.txt`, equivalents.
+  - a top-level directory listing per candidate source.
+  - one or two entry points the prompt itself names, plus a handful of search hits.
+- **Budget: ≤5 reads + ≤3 searches.** Read a whole file only when a head or a search will not
+  do. The ceiling is a **cap, never a target**.
+- **Stop at the first of these:**
+  - the evidence already decides one spec vs sibling specs.
+  - the next question needs a deep technical chain.
+  - it would need running code, tests or services.
+  - it would need an external source that is not available.
+  - the remaining uncertainty does not block a first draft.
+  - the digging starts answering *how it will be built* instead of *what functional unit was
+    asked for*.
+- **Never:** follow a full import/call chain, run anything, query a database, search the web, or
+  open a source the prompt gives no reason to open.
+
+**Scope hypothesis (internal).** The pass ends in a short judgement: functional outcome · likely
+sources · apparent responsibility of each · coupling · independent acceptance · recommended shape
+· confidence. It is **reasoning, not an artifact** — never persisted, never printed verbatim. It
+exists so the cut is never intuitive but opaque; its only visible residue is what the filling
+notes admit.
+
+**Degrade safely.** A missing workspace, unreachable sources or contradictory evidence **never**
+block the command and **never** justify a speculative cut. Keep **one spec**, declare the
+assumption used, and record the uncertainty for `spec-refine`. Prefer the functional outcome the
+user declared over any inference drawn from the code.

package/skills/w/modules/REPLANNING.md

@@ -0,0 +1,12 @@
+# REPLANNING — re-planning a plan that is already partly executed
+
+Loaded when the plan is already partially executed (signal `replan`).
+
+## Replanning executed work
+
+A partially executed plan is replanned **forward**, never rewritten backwards:
+
+- Phases already `validada` **stay as they are**, and their result becomes the initial state of what follows. Completed tasks are not re-written as if they had never happened.
+- Only pending work is re-designed. A `validada` phase that the new shape invalidates gets a **compensating correction** as a new phase — never a silent edit of the closed one.
+- **Return from `plan-exec`** (structural deviation — [`plan-exec-loop`](../loops/plan-exec-loop/LOOP.md) § *Deviation gate*): the deviation enters as a **material gap** of this run. Changed input or output, observable state, public contract, participating components, phase order, simulation boundary or integration strategy — all land in `## Refinement decisions` with what execution already proved.
+- **Legacy plans** (no phase state, micro-task shape) are migrated to the phase contract when this round touches them: completed tasks preserved, micro-tasks grouped by purpose, results and exit conditions derived from the spec and from the plan itself. Functional evidence that neither backs is **not invented** — it becomes an `## Open questions` entry.

package/skills/w/modules/SESSION-NUMBERING.md

@@ -0,0 +1,19 @@
+# SESSION-NUMBERING — who owns the NNN, and how a session is found again
+
+Loaded when the run has to locate or name a session beyond creating its own (signal `sessions`).
+
+## The CLI owns the number (hard rule)
+
+`aw session-create` prepends a **global, sequential** `NNN` by scanning **all** sessions under `.workflow/sessions/` (any type). The caller passes **only the descriptor** via `--name` — **never** a number. Numbering neither restarts per type nor collides, and every folder is **self-describing**: `NNN-<slug>-<flow>` (e.g. `002-correo-otp-spec-refine`, `003-correo-otp-plan-new`, `004-correo-otp-plan-exec`, `005-validacion-correo-quick`).
+
+> `<run>` = the session's **descriptor** (no number), always shaped **`<slug>-<flow>`**: `<slug>-spec-refine`, `<slug>-plan-new`, `<slug>-plan-refine`, `<slug>-plan-exec`, `<slug>-quick`. The `<slug>` is **descriptive** and comes from the flow's input doc — `docs/specs/NNN-spec-<slug>.md` for spec-refine/plan-new; `docs/plans/PPP-plan-<slug>.md` for plan-refine/plan-exec; the prompt for quick — so the folder says at a glance what it is about, not just which flow created it. Research being **inline** in this same session, there are no child `*-research-*` sessions to number (compat: old ones are historical).
+
+## Finding one again
+
+**Resume**: locate the existing session by **scanning** `.workflow/sessions/` for descriptor + `## Origin` (which spec/plan), **not** by reconstructing the number (global, not derivable from the artifact). `aw session-resume --code <NNN | folder>` resolves both forms.
+
+**Reopen to continue**: `aw session-resume --code <NNN> --reopen` reactivates a **closed** session (removes `.closed` → active) to keep working in it; without `--reopen`, resume is read-only. To detect the most recent closed one: `aw resume-summary --include-recent-closed` (or `aw sessions --state all`).
+
+## When the durable record fails to update
+
+`aw session-close` also upserts the session's row in `.workflow/HISTORY.md` — the durable record, since `sessions/` is gitignored. That upsert is **non-fatal**: on `history_error` in its output, re-run `aw history-update --code <NNN> --state closed`. `aw session-artifacts` inspects what a session holds.

package/skills/w/modules/SIMULATION-LIFECYCLE.md

@@ -0,0 +1,11 @@
+# SIMULATION-LIFECYCLE — the life of temporary behavior in a plan
+
+Loaded when the journey introduces temporary behavior (signal `simulation`).
+
+## Simulation lifecycle
+
+**This section applies only when the journey introduces temporary behavior** — a stub, fake, in-memory adapter, controlled fixture or temporary response. None in the change → no `Límite de simulación`, and no artificial phase invented to retire one. When there is, it is planned, never improvised: every simulation declares **purpose · location · the contract it stands for · the phase where it appears · the phase where it moves or disappears · what prevents its accidental selection in a production runtime · the minimum proof needed while it exists**.
+
+- **Explicit over hidden**: `Stub…` / `Fake…`, in-memory adapter, temporary provider or controlled fixture — never a hardcode buried inside production code.
+- **Displacement rule**: each affected phase writes its `Límite de simulación` as normalized prose — `antes <where it is>` → `después <where it lands, or removed>` — never as an implicit assumption.
+- **Removal gate**: the change is not complete while a main-path simulation stays active, a configuration can still select it, the plan does not explain why it remains, or its removal was never validated. Test doubles isolated from the production runtime may stay.

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

@@ -0,0 +1,37 @@
+# SPEC-CHANGE-SHAPE — same, split or replace
+
+Loaded when the investigation may have changed the spec shape (signal `shape`).
+
+## The two shape branches are not the same question
+
+`split` and `replace` are different findings, so they ask different things and do different things — reusing one for the other asks about cardinality when what changed was purpose:
+
+| 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 |
+| **`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.
+
+> **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.
+
+- same outcome — more clarity, or more technical components → **`same`**: no shape question, keep refining this spec;
+- independent functional outcomes discovered → **`split`** (below);
+- purpose fundamentally changed → **`replace`** (below);
+- refactor indispensable to the outcome → a consideration for `PLAN`, never its own spec; refactor with no functional change → out of the contract;
+- evidence insufficient → **`same`** + the uncertainty recorded. Thin evidence never justifies a cut.
+
+**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`.
+
+**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.
+
+- **New spec:** this one is **preserved**, its purpose never silently rewritten; the new one is minted with `aw next-number docs/specs`, born **`status: draft`**, its `## Origin` recording the origin spec, the replaced purpose and the user's decision. Its path goes to the `CHECKPOINT`; the run closes reporting `/w:spec-refine <new path>` as the next step.
+- **Reformulate:** same number/path, the work treated as `refining` while rewritten; baseline, gap classification and the *ready-for-plan gate* run again over the new purpose; `status` is stamped only on the save that follows the passing gate, and the material decision lands in `## Decisions`.
+
+**Every branch has a way out that changes nothing.** The `flow` control present on every structured-choice (chassis) is that exit here: `Cerrar` closes the run **without applying the shape change** — no sibling minted, no spec reformulated, the document untouched and the decision recorded in `CHECKPOINT` as declined. And no branch writes a file without the user's confirmation: minting siblings and minting a replacement both go through the same confirm-before-write rule as an in-place save.
+
+Neither branch adds a `superseded` status or archives the replaced spec: a historical close needs its own runtime contract, out of scope here.

package/skills/w/modules/SPEC-REFINE-KEYS.md

@@ -0,0 +1,14 @@
+# SPEC-REFINE-KEYS — compact / resume keys for SPEC
+
+Loaded when a refinement resumes or re-runs over the same spec (signal `resume`).
+
+## Compact / resume — SPEC keys
+
+Full mechanism (3 cases, `Compactar`, re-run on demand with `--reopen`) in the chassis (§ *Compact / resume*). SPEC keys:
+
+- The **prior-work mark** is the frontmatter `status: ready-for-plan` (legacy specs: `## Refinement decisions`, older ones also `## Q&A traceability`).
+- The **shape decision survives a resume.** It is written to `CHECKPOINT` the moment it is taken, before anything acts on it, so a compact, a `Cerrar` or a crash between the gate and the save re-enters with the shape settled — the gate is not re-run and the question is not re-asked. Only a *new* run over a spec whose baseline changed re-opens it.
+- 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.
+- **Legacy migration happens only here.** A re-refined legacy spec runs the gate like any other; on `Guardar`, its `## Refinement decisions` is renamed `## Decisions` and pruned to the material decisions — **in the same write that stamps `status`**, so the spec is never left with no mark. Specs nobody re-refines are not migrated.
+- **`Cerrar` before converging leaves the spec untouched**: the progress lives in the `CHECKPOINT`, and `status` is neither invented nor downgraded. `refining` is understood **on read** (a hand-written spec may declare it) — this loop never writes a partial spec.
+- **The legacy glob still resolves.** `NNN-spec*.md` also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs; re-running spec-refine edits them in place from then on.