@tacuchi/agent-workflow-cli 20.17.0 → 20.22.0

package/skills/w/SKILL.md

@@ -65,11 +65,15 @@ USER invokes
 | **PLAN** (the *how* + execute) | `plan-new` · `plan-refine` *(aux, optional)* · `plan-exec` | `docs/plans` | `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` |
 | **QUICK** (lightweight shortcut) | `quick` | — | `quick-loop` |
 
-Typical chain: prompt → `spec-new` generates `docs/specs/NNN-spec-<slug>.md` → `spec-refine` runs the loop and refines **that same spec in place** → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → *(optional)* `plan-refine` adjusts **that same plan in place** if changes arise before executing → `plan-exec` executes and updates the plan (living doc) + artifacts in sessions. Promoting anything else to `docs/` is **always** a separate step via `export-*`.
+Typical chain: prompt → `spec-new` generates `docs/specs/NNN-spec-<slug>.md` → `spec-refine` runs the loop and refines **that same spec in place** until PLAN can design without inventing behavior, stamping `status: ready-for-plan` → `plan-new` → `docs/plans/PPP-plan-<slug>.md` → *(optional)* `plan-refine` adjusts **that same plan in place** if changes arise before executing → `plan-exec` executes and updates the plan (living doc) + artifacts in sessions. Promoting anything else to `docs/` is **always** a separate step via `export-*`.
+
+> **A plan is a sequence of functional states.** Every `### Fn` phase names a verifiable state of the system, carries its own primary proof, and — **only when the change carries one** — declares where a temporary simulation lives and when it retires. Its `> Estado:` line (`pendiente` | `en ejecución` | `bloqueada` | `validada`) is machine state that `aw status` counts **alongside** the checkbox progress: ticking every checkbox is **not** validation, and neither is a proof nobody ran — a phase whose check could not be executed stays `bloqueada` until it runs and passes, stating on its `> Bloqueo:` line what it waits on. Execution runs those states without redesigning them — a structural deviation returns to `plan-refine`, a functional one to `spec-refine`.
+
+> **Three axes, and none stands in for another.** A **task completed** is work done (checkboxes); a **phase validated** is a functional state demonstrated (`> Estado: validada`); a **plan closed** is the whole solution validated — the plan's own `> Estado:` line under the title (`open` | `done`, with the date and session on its `> Cierre:` line). 100% of tasks does not imply validated phases, every phase validated does not imply the **final validation** ran, and a `done` declared over open work is a contradiction `aw status` reports as `inconsistent` rather than a closure. The runtime derives that third axis (`plan_state`) from the declaration **and** the counters; it never infers it from either alone.
 
 QUICK can **escalate live to SPEC** when the objective exceeds a quick (entry size gate) or the task grows mid-loop: with consent via structured-choice, the work line moves to the SPEC flow (draft via the `spec-new` procedure + `spec-refine-loop` directly); escalation to PLAN stays **deferred** (seed + pointer). See `loops/quick-loop/LOOP.md` § *QUICK delta*.
 
-Both authoring entry points can **split** with consent: `spec-new` may split a multi-part prompt into **sibling specs** (its split gate — one structured-choice before writing anything), and the plan loops may split a plan into independently deliverable **sibling plans** (`plan-new-loop` § *Split gate (multi-plan)*; plan-refine adds the in-place semantics). Siblings cross-reference **by path**; a split stays inside the same work line — it is not an escalation.
+Both authoring entry points can **split** with consent: `spec-new` may split a multi-part prompt into **sibling specs** (its split gate — one structured-choice before writing anything, decided **after** its bounded reconnaissance of the sources), and the plan loops may split a plan into independently deliverable **sibling plans** (`plan-new-loop` § *Split gate (multi-plan)*; plan-refine adds the in-place semantics). Siblings cross-reference **by path**; a split stays inside the same work line — it is not an escalation. The cut follows the **independent functional outcome**: distinct repos or technologies are evidence, never the reason.
 
 ### Operating context — where everything lands
 
@@ -100,11 +104,11 @@ The flows are **composable with host-native work, never exclusive**. The host is
 ### The commands (`/w:` namespace)
 
 - `/w:workspace-init` — initializes the workspace.
-- `/w:spec-new` — generates an initial spec (single-pass, no loop).
-- `/w:spec-refine` — starts `spec-refine-loop` to refine the spec.
-- `/w:plan-new` — starts `plan-new-loop` to derive an executable plan from the refined spec.
-- `/w:plan-refine` — starts `plan-refine-loop` to refine the plan in place (auxiliary, **not mandatory**) before executing.
-- `/w:plan-exec` — starts `plan-exec-loop` to execute and maintain the plan.
+- `/w:spec-new` — generates an initial spec (single-pass, no loop; a bounded reconnaissance of the sources precedes the scope decision).
+- `/w:spec-refine` — starts `spec-refine-loop` to refine the spec until it is `ready-for-plan`: the blocking functional decisions closed, the architecture/implementation ones declared for PLAN.
+- `/w:plan-new` — starts `plan-new-loop` to derive an executable plan from the ready spec.
+- `/w:plan-refine` — starts `plan-refine-loop` to turn the plan, in place, into an executable sequence of functional states (auxiliary, **not mandatory**); it is also the return path when execution hits a structural deviation.
+- `/w:plan-exec` — starts `plan-exec-loop` to execute the planned states and maintain the plan: it validates each phase before closing it, and never silently redesigns what it was given.
 - `/w:quick` — starts `quick-loop` (shortcut, no `docs/`; escalates live to SPEC when the objective exceeds a quick).
 - `/w:export-scripts` · `/w:export-manuals` · `/w:export-diagrams` · `/w:export-reports` — promote artifacts to `docs/`.
 

package/skills/w/artifacts/artifacts-core/CHECKPOINT.md

@@ -13,8 +13,10 @@
 ## Completed
 What already happened: finished phases/tasks/gaps with their outcome (ref: plan-doc `docs/plans/PPP-plan.md`, the spec's gaps, or `TASKS.md` if the session created its own split). Fold the key context a resume needs (settled decisions, discoveries) into these bullets.
 
+> **Implemented is not validated (exec sessions).** A phase lands here only once the plan-doc's `> Estado: validada` was flipped. Work that is written but not yet proven stays in `Pending / Next` with its validation pending — a full set of ticked tasks never promotes a phase into this section. Each closed phase records the **functional state reached** and, **only when the change carries one**, the **simulation boundary in force** — that, not the list of files touched, is what a resume actually needs.
+
 ## Pending / Next
-The intent: what remains and what comes immediately next (seeded BEFORE executing — artifact-first). A resume starts here.
+The intent: what remains and what comes immediately next (seeded BEFORE executing — artifact-first). A resume starts here. In exec: the next functional state being pursued, plus any blocker or deferral that keeps a phase out of `validada`. A phase left `bloqueada` states here **what is missing to validate it** — applying the migration, an environment, a third party — so the next run knows what to execute before flipping the state.
 
 ## Open questions
 Live doubts not yet resolved — the section exists only while there are any (rule 1). Deferred ones move to the session's `BACKLOG` or the flow doc's `## Open questions`.

package/skills/w/artifacts/artifacts-exec/DECISION.md

@@ -9,3 +9,5 @@ Reference work unit (per the owning loop):
 
 ## Decision
 Non-obvious decisions. For each: the decision taken, the reason, and the alternatives considered.
+
+> **Local decisions only.** This log records what execution legitimately resolved on its own (naming, a local helper, internal code layout, a refactor that does not move the journey). A **structural deviation** is not settled with an entry here — a changed input or output, observable state, public contract, set of participating components, phase order, simulation boundary or integration strategy **stops execution** and returns to `plan-refine`; a functional change returns to `spec-refine`. See [`plan-exec-loop`](../../loops/plan-exec-loop/LOOP.md) § *Deviation gate*.

package/skills/w/commands/README.md

@@ -16,7 +16,7 @@
 |---|---|---|
 | [`workspace-init`](workspace-init.md) | Workspace bootstrap | single-pass, interactive |
 | [`spec-new`](spec-new.md) | Generates the spec draft (`docs/specs/NNN-spec-<slug>.md`) | single-pass, no loop |
-| [`spec-refine`](spec-refine.md) | Refines the spec **in place** until unambiguous | starts `spec-refine-loop` |
+| [`spec-refine`](spec-refine.md) | Refines the spec **in place** until it is `ready-for-plan` | starts `spec-refine-loop` |
 | [`plan-new`](plan-new.md) | Derives the executable plan (`docs/plans/PPP-plan-<slug>.md`) from the spec | starts `plan-new-loop` |
 | [`plan-refine`](plan-refine.md) | Refines the plan **in place** before executing (aux, optional) | starts `plan-refine-loop` |
 | [`plan-exec`](plan-exec.md) | Executes the plan (code/DB/git) and maintains it as a living doc | starts `plan-exec-loop` |

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

@@ -1,5 +1,5 @@
 ---
-description: Use when a plan is ready to implement — this is where the real work happens: code edits, proposed SQL scripts, created tools. Starts or resumes the execution loop (plan-exec-loop) over an existing plan. Git-safe (proposes commits, never push/--amend/--no-verify). Not for creating or refining the plan (plan-new / plan-refine).
+description: Use when a plan is ready to implement — this is where the real work happens: code edits, proposed SQL scripts, created tools. Starts or resumes the execution loop (plan-exec-loop) over an existing plan, phase by phase, validating each phase before closing it. Checks executability on entry; structural or functional deviations return to plan-refine / spec-refine. Git-safe (proposes commits, never push/--amend/--no-verify). Not for creating or refining the plan (plan-new / plan-refine).
 argument-hint: <docs/plans/PPP-plan-<slug>.md>
 allowed-tools:
   [
@@ -12,7 +12,7 @@ allowed-tools:
 
 # plan-exec — trampoline to the execution loop
 
-Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase by phase. The plan (`docs/plans/PPP-plan-<slug>.md`) is a living document the loop keeps updated (phase and task state).
+Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase by phase — each phase a **verifiable state of the system**, not a batch of technical chores. The plan (`docs/plans/PPP-plan-<slug>.md`) is a living document the loop keeps updated: each `### Fn` carries its own `> Estado:` line (`pendiente` | `en ejecución` | `bloqueada` | `validada`) next to its task checkboxes.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
@@ -32,7 +32,10 @@ Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase
 
 ## What the loop does (summary)
 
-- Reads and updates `docs/plans/PPP-plan-<slug>.md` (living doc: phase/task state).
+- **Executability check on entry**: reads the plan **and its spec** and verifies each phase declares its result, its exit condition and its proof, and — **only when the change carries temporary behavior** — that its simulation boundary and retirement phase are identifiable. A minor gap is normalized **with your consent** (`Normalizar y ejecutar` | `Ir a plan-refine`); a structural one is recorded and handed off to `/w:plan-refine` — it never invents the plan's structure (see `../loops/plan-exec-loop/LOOP.md` § *Entry gate — executability*).
+- **Deviation gate**: local detail (a name, a helper, internal layout) is resolved inline. A **structural** deviation — a contract, the participating components, the phase order, the simulation boundary — stops execution and returns to `/w:plan-refine`; a **functional** change (result, scope, business rule, acceptance criterion) returns to `/w:spec-refine` (§ *Deviation gate*).
+- **Validation before closing each phase**: the phase's own proof plus the justified focused tests run first; the phase flips to `validada` only with the exit condition true and the review gate green — **never** just because its checkboxes are ticked (§ *Delta 4*). A proof that **cannot be run** (a migration nobody applied yet) leaves the phase `bloqueada`, with its reason on a `> Bloqueo:` line: the work stays ticked, the plan stays open, and the state only becomes `validada` once that proof runs and passes.
+- Reads and updates `docs/plans/PPP-plan-<slug>.md` (living doc: phase state, task checkboxes, deferrals).
 - Edits code in the workspace sources (a single execution session per run; execution is still phase by phase, there is just no session per phase).
 - If it creates a tool/utility, the ambient `creating-tools` skill documents it in `docs/tools/` (auto-discovered; Workline does not bind it).
 - **Closing review gate** at every phase boundary, **before proposing the commits**: re-reads the diff (independent pass) applying the **installed ambient conventions** and fixes or defers findings — nothing reaches a commit unreviewed (see `../loops/plan-exec-loop/LOOP.md` § *Delta 5*).

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

@@ -25,14 +25,14 @@ SPEC → PLAN bridge. Turns the "what" (refined spec) into the "how" (plan). Del
 
 The skill evaluates `$ARGUMENTS` (specs live in place — `docs/specs/NNN-spec-<slug>.md`; locate via the `docs/specs/NNN-spec-*.md` glob or the exact path):
 
-1. **Refined spec** (`docs/specs/NNN-spec-<slug>.md` that **already has** `## Refinement decisions`) → ideal. Proceed straight to `plan-new-loop`.
-2. **Draft spec** (same file, but **without** that section) → **soft-suggest** running `/w:spec-refine` first; planning over a solid spec produces better plans (the user may proceed anyway).
+1. **Ready spec** (`docs/specs/NNN-spec-<slug>.md` whose frontmatter declares `status: ready-for-plan`) → ideal. Proceed straight to `plan-new-loop`.
+2. **Spec not ready** (`status: draft` / `refining`, or no mark at all) → **soft-suggest** running `/w:spec-refine` first; planning over a solid spec produces better plans. 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 using the SPEC flow; **by default launch `/w:spec-new`** with that prompt to create the draft, and continue the natural flow from there.
 4. **External plan content** — the argument/conversation carries an **already-built plan** (host plan mode output, 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 (`../loops/plan-new-loop/LOOP.md` § *Delta 1*) with only what the source provides. `## Origin` = "adopted from <source>" + attribution (host · model · date). Then offer `/w:plan-refine` (closes schema gaps) 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). Doctrine: `../loops/CHASSIS.md` § *Adopted context*.
 
-> **Refined vs draft** is distinguished by the **presence** of `## Refinement decisions` in the spec, never by the filename (there is no `-refined` anymore). Legacy specs may also carry `## Q&A traceability` — they count as refined the same way.
+> **Ready vs not** is read from the spec's frontmatter `status`, never from the filename (there is no `-refined` anymore). **Legacy compat:** a spec with no frontmatter that carries `## Refinement decisions` — or the older `## Q&A traceability` — counts as ready the same way.
 
 ## Run the loop
 
@@ -43,6 +43,10 @@ The skill evaluates `$ARGUMENTS` (specs live in place — `docs/specs/NNN-spec-<
 
 > Do not try `Skill: plan-new-loop` — it is not registered as a skill. The command **is** the entry; the loop is its body.
 
+## Phases are functional states
+
+The plan is born with `### Fn` phases that each leave a **verifiable state of the system** — each with its `> Estado:` line, its primary evidence and its exit condition — never a list of files, classes or layers. The blocks beyond those are **conditional**: a phase with no temporary behavior gets no `Límite de simulación`, and one with nothing excluded gets no `Diferido` — a heading is never written empty to satisfy a template. The plan itself is born `> Estado: open` under the title; only `plan-exec` closes it. Contract: `../loops/plan-new-loop/LOOP.md` § *Phase contract (canonical)*.
+
 ## Numbering notes
 
 The plan is named `docs/plans/PPP-plan-<slug>.md`. `aw next-number docs/plans` returns JSON (field `next` = `PPP`); the loop builds the full name (slug = short kebab-case from the Requirement: `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars). It does **not inherit the spec's `NNN`**. The link to the spec is established by reference (`## Origin` / "Derived from") in the plan, never by number.

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

@@ -1,5 +1,5 @@
 ---
-description: Use when an existing plan needs changes before executing — new requirements, scope tweaks — not to generate one (plan-new) nor execute it (plan-exec). Starts or resumes the plan refinement loop (plan-refine-loop). An auxiliary, NOT mandatory step of the PLAN flow — refines an existing plan in place. Input: a docs/plans/PPP-plan-<slug>.md — generated by plan-new, hand-written, or adopted from a host planner (plan-new mode 4 / persist). May extract tranches into sibling plans.
+description: Use when a plan must become executable before running it — new requirements, scope tweaks, phases shaped as file lists, or a structural deviation returned by plan-exec. Not to generate one (plan-new) nor execute it (plan-exec). Starts or resumes plan-refine-loop, which re-shapes the plan in place into a sequence of verifiable functional states. Input: a docs/plans/PPP-plan-<slug>.md — from plan-new, hand-written or adopted. May extract tranches into sibling plans.
 argument-hint: <docs/plans/PPP-plan-<slug>.md>
 allowed-tools:
   [
@@ -23,7 +23,7 @@ This command does not refine the plan itself: it delegates to `plan-refine-loop`
 > 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.
+> **Not mandatory.** `plan-exec` runs **any** plan that is already executable, refined or not — no gate requires passing through here. Use it when the plan needs adjustments before executing, or when execution cannot start without inventing structure.
 >
 > **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`).
 
@@ -33,6 +33,9 @@ The skill evaluates `$ARGUMENTS` (plans live in place — `docs/plans/PPP-plan-<
 
 1. **Existing plan** (`docs/plans/PPP-plan-<slug>.md`) → proceed to `plan-refine-loop` — **regardless of provenance**: generated by `plan-new`, hand-written, or adopted from a host planner (existence is the only requirement).
 2. **No plan** (the arg references no plan, or none exists) → **soft-suggest** running `/w:plan-new` first (there is nothing to refine yet); the user decides.
+3. **Returned by `plan-exec`** (its entry check found the plan unexecutable, or execution stopped on a structural deviation) → proceed to `plan-refine-loop` carrying that finding: phases already `validada` stay, only pending work is re-designed (see `../loops/plan-refine-loop/LOOP.md` § *Replanning executed work*).
+
+> **Expected output: an executable plan.** The loop converges on its **executability gate** — each phase a verifiable state with its evidence, its exit condition and, **only when the change carries temporary behavior**, its simulation boundary — so `plan-exec` implements it without inventing contracts, observable states, order or evidence.
 
 ## Run the loop
 

package/skills/w/commands/resume.md

@@ -35,21 +35,28 @@ Same hard floor: this mode **proposes** the route — it never starts the target
 ## Run
 
 1. **Workline level — compose `/w:status`.** Read-and-follow [`status.md`](status.md) to produce the prioritized summary (it already renders `aw status` and, when available, the host-context section). Do **not** re-implement the summary. For deeper session detail, `aw resume-summary [--include-recent-closed]` gives the primary session's CHECKPOINT state, and `aw session-resume --code <NNN>` the full checkpoint of any other active or closed session.
-2. **Interpret the stage marks.** Map each signal to its stage: spec `refined` / `open_questions`; plan checkbox progress (`tasks_done` / `tasks_total`); session `checkpoint_present` / `status`. Associate a session to its plan or spec by **slug** — there is no linkage field in the `aw status` output, so infer it from `folder` / `slug`; when precision matters, confirm by the session's `## Origin` (§ *Directed resume*).
-3. **Build the prioritized pending list** — fixed order: **session with CHECKPOINT > plan half-done > spec unrefined > host context**.
+2. **Interpret the stage marks.** Map each signal to its stage: the spec's `status` (`draft`/`refining` = SPEC work still open · `ready-for-plan` = it can go to PLAN) + `open_questions`; plan progress on **all three axes** — checkboxes (`tasks_done` / `tasks_total`), validated phases (`phases_validated` / `phases_total`) and closure (`plan_state`, with `final_validation_pending` and `blocked_phases[]`); session `checkpoint_present`. A `status` that is absent, empty or unknown reads `draft`: that work stays in SPEC and never routes to PLAN on an unreadable mark. Associate a session to its plan or spec by **slug** — there is no linkage field in the `aw status` output, so infer it from `folder` / `slug`; when precision matters, confirm by the session's `## Origin` (§ *Directed resume*).
+3. **Build the prioritized pending list** — fixed order: **session with CHECKPOINT > plan half-done > spec not ready > host context**.
 4. **Host level (second source).** If the workline level does not explain the pending work (or no Workline flow was used), rely on the host-context already surfaced by `/w:status`; escalate it to a proposal and, only if needed, use the host-memory *deep* tier or ask the user (universal fallback: git / `docs/` signals + a question). See [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory*.
 5. **Propose (only when ≥1 pending).** One structured-choice with the top ≤3 options by the priority order; each option **routes** to its command (table below). Every proposal carries `Retomar` (recommended) and `Descartar` / `Cerrar` (secondary).
 6. **Nothing pending.** Show the `/w:status` summary and state clearly that there is nothing pending — **do not ask**.
 
 ## Routing (stage → command)
 
-Priority: **session+CHECKPOINT > plan half-done > spec unrefined > host context**.
+Priority: **session+CHECKPOINT > plan half-done > spec not ready > host context**.
+
+> **Every box ticked is not a finished plan.** A plan with `phases_validated` below `phases_total` still has functional state to reach — work implemented, not validated — so it counts as half-done and routes to `/w:plan-exec`, which re-enters at the first phase that is not `validada`. A phase left `bloqueada` routes the same way: `/w:plan-exec` re-enters **through it** to run the validation still pending, and the plan stays open until that phase reads `validada`. A plan with `phases_total: 0` is a legacy plan (no phase marks) and is judged by its checkboxes alone.
+
+> **`plan_state` decides whether a plan is resumable at all.** Only `done` is finished; everything else routes back to `/w:plan-exec` with a different re-entry point. `final_validation_pending: true` means the phases are green but the final validation never ran — the plan re-enters **at that validation**, not at a phase. `inconsistent` means the document contradicts itself (`done` declared over open work, or an unreadable value): the re-entry is **repairing the state first**, and the proposal says so instead of pretending there is work to implement.
 
 | Pending detected | `Retomar` (recommended) | Secondary |
 |---|---|---|
-| spec unrefined | `/w:spec-refine` | `Descartar` |
-| spec refined, no plan | `/w:plan-new` | `Descartar` |
-| plan half-done (checkboxes) | `/w:plan-exec` | `Cerrar` |
+| spec not ready (`draft` / `refining`, or a `status` absent or unreadable) | `/w:spec-refine` | `Descartar` |
+| spec `ready-for-plan`, no plan | `/w:plan-new` | `Descartar` |
+| plan `open` — open checkboxes **or** phases not `validada` | `/w:plan-exec` | `Cerrar` |
+| plan `open` with `final_validation_pending` — everything validated, no closure | `/w:plan-exec`, from the final validation | `Cerrar` |
+| plan `inconsistent` — `done` over open work, or an unreadable value | `/w:plan-exec`, repairing the state first | `Cerrar` |
+| plan `done` | — not resumed automatically | — |
 | active session with CHECKPOINT | continue / reopen (`aw session-resume --reopen`) | `Cerrar` |
 | host context only (no workline) | best next step for what was found | `Descartar` |
 

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

@@ -1,5 +1,5 @@
 ---
-description: Use when the user wants to capture a NEW requirement, idea or wish as a spec — not to refine an existing draft (that's spec-refine). Generates a specification draft (docs/specs/NNN-spec-<slug>.md) from a prompt, in a single pass. Can split a multi-part prompt into several sibling specs (split gate). Step 1 of the SPEC flow; starts no loop.
+description: Use when the user wants to capture a NEW requirement, idea or wish as a spec — not to refine an existing draft (that's spec-refine). Generates a specification draft (docs/specs/NNN-spec-<slug>.md) from a prompt, in a single pass: a bounded reconnaissance of the workspace sources first, then the scope decision — one spec, or several sibling specs (split gate). Step 1 of the SPEC flow; starts no loop.
 argument-hint: <prompt with the requirement or idea>
 allowed-tools:
   [
@@ -13,35 +13,70 @@ allowed-tools:
 
 Generates `docs/specs/NNN-spec-<slug>.md` in a single pass from the prompt in `$ARGUMENTS`. Starts no loop.
 
-> ## ⛔ Single-pass — NO RESEARCH (hard rule)
+> ## ⛔ Single-pass — BOUNDED RECONNAISSANCE, NO DEEP RESEARCH (hard rule)
 >
-> This command **only paraphrases** the user's input into the draft schema. It is **one sequential pass**: read `$ARGUMENTS` → (split gate: at most ONE structured-choice — see § *Split gate (multi-spec)*) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
+> This command frames the user's input into the draft schema after a **single, bounded look** at the context. It is **one sequential pass**: read `$ARGUMENTS` → adopt what the conversation already settled → **reconnaissance** (see § *Bounded reconnaissance*) → scope hypothesis → (split gate: at most ONE structured-choice — see § *Split gate (multi-spec)*) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
 >
-> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, or deep code investigation — **even if the harness is in a maximum-effort/depth mode** (e.g. ultracode/max-effort in Claude Code).
+> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, following implementation chains, running code/tests/apps, querying databases — **even if the harness is in a maximum-effort/depth mode** (e.g. ultracode/max-effort in Claude Code).
 >
-> This **overrides** any mode or session instruction saying "run a workflow for every substantial task". Those modes do **not** apply to `spec-new`: this command overrides them. If a section is uncertain, **do not investigate it** — declare it under `## Open questions` or `## Assumptions` and move on.
+> This **overrides** any mode or session instruction saying "run a workflow for every substantial task". Those modes do **not** apply to `spec-new`: this command overrides them. If a section stays uncertain after the reconnaissance, **do not dig further** — declare it under `## Open questions` or `## Assumptions` and move on.
 >
 > Deep investigation (closing gaps, mapping code, querying DB, autonomous research) is **`spec-refine`** work, not this command's.
 
-With a raw user prompt, first run the **§ Split gate (multi-spec)** assessment (below): the split offer, if any, happens **before writing anything**. Then:
+With a raw user prompt, first run the **§ Bounded reconnaissance** pass, then the **§ Split gate (multi-spec)** assessment (both below): the split offer, if any, happens **before writing anything**. Then:
 
-1. Run `aw next-number docs/specs` (the only shell tool needed): it returns JSON — use the `next` field as `NNN`. This command builds the slug.
+1. Run `aw next-number docs/specs` (the only shell tool needed beyond the reconnaissance): it returns JSON — use the `next` field as `NNN`. This command builds the slug.
 2. Derive the `<slug>`: short kebab-case from the Requirement — only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars.
-3. Create `docs/specs/NNN-spec-<slug>.md` paraphrasing `$ARGUMENTS` into the draft schema (below). Repo reading: optional and minimal (e.g. one file the user cited) — never a sweep or research. On an accepted split: repeat steps 1-3 per part, minting immediately before each write.
+3. Create `docs/specs/NNN-spec-<slug>.md` framing `$ARGUMENTS` into the draft schema (below); the reconnaissance findings land **only** where the filling notes allow. On an accepted split: repeat steps 1-3 per part, minting immediately before each write.
 4. Show the generated file(s) and the suggested next step (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).
 
+## 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:** it runs **only on a raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff). The reuse entries at the end of this file 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 § *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.
+
 ## Split gate (multi-spec)
 
-Right after reading `$ARGUMENTS` and **before writing anything**, assess whether the prompt bundles **several independent requirements**. The gate fires **only on clear signals** (≥2 of: independent deliverables/goals · explicit enumeration of distinct features · different requested moments or order · unrelated subsystems); borderline → **one spec, no question**. It applies only to a **raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff); it **never fires** on the reuse entries below — the quick escalation and the `persist` adoption arrive already scoped to one objective.
+Right after the reconnaissance and **before writing anything**, assess whether the prompt bundles **several independent outcomes**. The unit is the **functional outcome**, not the technical boundary: distinct repos, a frontend/backend pair, several microservices, a migration plus the code it enables — all **secondary evidence**, never on their own a reason to divide.
+
+**Divide only when each part is a result that can be refined, accepted and planned on its own** — its own purpose, its own acceptance criteria, worth delivering even if the other part is dropped. The gate fires **only on clear signals** (≥2 of: independent deliverables/goals · explicit enumeration of distinct features · different requested moments or order · users or value that do not depend on each other). Borderline, or evidence too thin to tell → **one spec, no question**: the hypothesis goes to `## Assumptions` and the doubt to `## Open questions`. It applies only to a **raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff); it **never fires** on the reuse entries below — the quick escalation and the `persist` adoption arrive already scoped to one objective.
 
-- **The offer** — the command's **only** interaction: **one** structured-choice (1 content question + the `flow` control; `Cerrar` = abort, nothing is written yet). The question body shows the proposed cut in the **user's language**: per part, a name + slug, a 1-line scope and the suggested order. Labels: `Dividir en varias specs` (recommended when the signals hold) | `Una sola spec`. A free-form answer adjusts the cut (merge/rename/drop parts); if one part remains, proceed as a single spec.
-- **On acceptance** — still single-pass, still **NO RESEARCH** (the cut is paraphrase of the prompt, never investigation): per part, mint with `aw next-number docs/specs` **immediately before each write**, then write that draft. Numbers come out consecutive, so every sibling path is known after the first mint.
+- **The offer** — the command's **only** interaction: **one** structured-choice (≤2 content questions + the `flow` control; `Cerrar` = abort, nothing is written yet). The question body shows the proposed cut in the **user's language**: per part, a name + slug, a 1-line scope and the suggested order. Labels: `Dividir en varias specs` (recommended when the signals hold) | `Una sola spec`. A free-form answer adjusts the cut (merge/rename/drop parts); if one part remains, proceed as a single spec.
+- **The second content question** is allowed **only** for a functional ambiguity with two incompatible readings that would change the number of specs (or leave the requested outcome unidentifiable). Anything smaller — confirming an observable technology, closing an implementation detail, raising confidence from medium to high — is **not** asked: it goes to `## Assumptions` or `## Open questions`.
+- **On acceptance** — still single-pass: the cut comes from the prompt plus the reconnaissance already done, never from a second look. Per part, mint with `aw next-number docs/specs` **immediately before each write**, then write that draft. Numbers come out consecutive, so every sibling path is known after the first mint.
 - **Sibling contract**: each `## Origin` records the shared prompt + `split (part i/N)` + the **siblings by path** + the suggested order; each `## Scope` Out points to the sibling that owns the excluded part. Cross-reference by path, never by bare number.
 - **Report**: list the N files and suggest the next step per spec (`/w:spec-refine` on the first — each sibling refines and plans at its own moment).
 
 ## Draft schema (`NNN-spec-<slug>.md`)
 
 ```markdown
+---
+status: draft
+---
+
 # Spec NNN — <slug>
 
 ## Origin            (opt.)
@@ -80,26 +115,29 @@ 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` (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.
+> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Decisions`, and may add `## Affected capabilities` / `## Behavioral changes` right after `Context` when the change touches behavior that already exists (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:**
 
 - The draft's **content** is written in the **user's language** (the schema headings stay as-is).
 - No `Type` field — `plan-new` infers the how.
+- **`status: draft`** in the frontmatter is the draft's maturity mark. This command writes no other value: only the `spec-refine` gate promotes a spec to `ready-for-plan`.
 - `Scope` always carries `Out` (what stays out).
+- **Where the reconnaissance lands** — `Context`: the facts that place the request (sources apparently involved, a module's observed responsibility, the relevant technology), with **at most one path per component** as an anchor; never a technical inventory. `Assumptions`: the inferences that let the draft advance. `Open questions`: what would need walking the implementation, a human decision, or a source that is not available.
+- **The code found never widens `Scope`** and never becomes a requirement: **acceptance criteria derive from the user's intent**. The reconnaissance may lend the right vocabulary, name existing actors and boundaries, and avoid obvious contradictions. It must not invent behavior nobody asked for, turn a current technical decision into a user requirement, or impose an implementation as a criterion.
 - **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. 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`.
 
-> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft following **this same procedure** (steps 1-3: same schema, same NO RESEARCH single-pass hard rule), with `## Origin` = "escalated from `/w:quick`" + the original prompt. No need to type `/w:spec-new`: the consent in the structured-choice equals invoking it.
+> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft following **this same procedure** (steps 1-3: same schema, same single-pass hard rule — with **NO RESEARCH** and no reconnaissance: the objective and its context arrive adopted), with `## Origin` = "escalated from `/w:quick`" + the original prompt. No need to type `/w:spec-new`: the consent in the structured-choice equals invoking it.
 >
-> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft with this same procedure, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass — adoption is transcription, not investigation (chassis § *Adopted context*).
+> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft with this same procedure, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass, and needs no reconnaissance — adoption is transcription, not investigation (chassis § *Adopted context*).
 
 ## Plan mode
 
-Resolves `NNN` by reading `docs/specs/`, describes the draft(s) it would generate — split gate included: it reports the proposed cut — without writing any file.
+Resolves `NNN` by reading `docs/specs/`, runs the same bounded reconnaissance (read-only in either mode) and describes the draft(s) it would generate — split gate included: it reports the proposed cut — without writing any file.
 
 ## Resources
 

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

@@ -1,5 +1,5 @@
 ---
-description: Use when a spec draft exists and needs disambiguating or completing before planning (close open questions, sharpen criteria) — not for the first draft (that's spec-new). Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (from spec-new, hand-written, or the quick escalation). Updates it in place.
+description: Use when a spec draft exists and needs disambiguating or completing before planning (close the blocking functional gaps, sharpen criteria, hand the technical ones to PLAN) — not for the first draft (that's spec-new). Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (from spec-new, hand-written, or the quick escalation). Updates it in place and marks it status: ready-for-plan.
 argument-hint: <docs/specs/NNN-spec-<slug>.md>
 allowed-tools:
   [
@@ -12,14 +12,27 @@ allowed-tools:
 
 # spec-refine — trampoline to the refinement loop
 
-This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes gaps and produces the refined spec.
+This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes the blocking gaps and leaves the spec ready for planning.
 
 > **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` 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/`.
+> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation), stamping the spec's frontmatter `status: ready-for-plan` on save; nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the doc's content) goes in the **user's language**.
+> 5. **Converge, do not close everything** — the target is `ready-for-plan`, not a spec without unknowns: close what can change **what** gets built; hand architecture and implementation questions to `PLAN`, recorded in `## Open questions` with their destination.
+> 6. **Shape before gaps** — if the investigation shows the spec must be **split** or **replaced**, ask and resolve that **before** the gap questions, in its own question, and record the answer in `CHECKPOINT`. Never mix it into the gap batch.
+
+## The two shape branches are not the same question
+
+The loop's *change-shape gate* can find that one spec is the wrong container. `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 |
+
+Both branches keep the `Cerrar` control, which closes the run **without applying the change**. No file — new or overwritten — is written without confirmation.
 
 ## Run the loop
 
@@ -36,10 +49,10 @@ 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`) → 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.
+3. **No progress** (no CHECKPOINT and the spec is not `status: ready-for-plan`) → start from zero reading the spec (`NNN-spec*.md`).
+4. **Already ready / re-refine on demand** (no open CHECKPOINT but the spec **already declares** `status: ready-for-plan`) → **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.
+> **Compat (legacy):** a spec with no frontmatter that carries `## Refinement decisions` (or the older `## Q&A traceability`) counts as ready — case 4 — but the mark does **not** exempt it from the gate: the re-refine runs it in full and, on `Guardar`, renames that section to `## Decisions` in the same write that stamps `status`. 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.
 
 ## Plan mode
 

package/skills/w/commands/status.md

@@ -17,12 +17,21 @@ Shows, simple and direct, the workspace state grouped as **Done / Missing / Disc
 1. Run `aw status` (returns JSON; backed by `status-service`).
 2. Render a readable summary from the JSON — do **not** show the raw JSON. Use the `relative` field verbatim (it comes pre-humanized in the user's language — Spanish). Head it with `workspace.name`.
 3. Group into three blocks (the dashboard is user-facing → render it in the user's language; the canonical Spanish labels below):
-   - `▸ HECHO` — specs with `refined: true`; plans with their progress (`tasks_done`/`tasks_total`, `progress_pct`); `closed` sessions.
-   - `▸ FALTA` — `active` sessions; plans with pending tasks (`tasks_total − tasks_done`); specs with `open_questions > 0`.
+   - `▸ HECHO` — specs whose `status` is `ready-for-plan` (the JSON keeps `refined: true` as its boolean mirror); plans whose `plan_state` is `done`, with their progress (`tasks_done`/`tasks_total`, `progress_pct`) **and** their validated phases (`phases_validated`/`phases_total`); `closed` sessions.
+   - `▸ FALTA` — `active` sessions; plans whose `plan_state` is `open` (pending tasks `tasks_total − tasks_done`, phases still to validate `phases_total − phases_validated`, or a final validation that never ran); plans whose `plan_state` is `inconsistent`, **naming the contradiction**; specs whose `status` is `draft` or `refining`; specs with `open_questions > 0`.
    - `▸ DESCARTÓ` — every item in `discarded[]` (`kind: deferred` = deferred in BACKLOG; `kind: excluded` = excluded in CHECKPOINT), with its `text`.
 4. Every line ends with its relative date after ` · ` (e.g. `· ayer en la mañana`). An empty section shows `— (nada)`. Never invent data not present in the JSON.
-5. If `workspace.initialized` is `false` and everything is empty → say the folder is not an agent-workflow workspace (no `.workflow/`) and suggest `/w:workspace-init`.
-6. **Host context (opportunistic, read-only).** After the dashboard, if the host exposes *cheap* host-memory (see [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory* — e.g. the auto-memory `MEMORY.md` on Claude Code), append a `▸ CONTEXTO DEL HOST` section with a few signals of recent focus relevant to this workspace. If there is no cheap host memory, **omit the section silently**. Never run an expensive transcript scan here and **never ask** — this is a read-only dashboard; the enrichment is additive and must not slow the default output.
+5. **Say what blocks a phase.** Every entry of `blocked_phases[]` is rendered with its `number`, its `name` and its `blocker` — `• F3 — Persistencia real — bloqueada: falta aplicar la migración`. A `blocker: null` is a legacy block that stated no reason: render it as `bloqueada` with `motivo no declarado`, never a guess.
+6. If `workspace.initialized` is `false` and everything is empty → say the folder is not an agent-workflow workspace (no `.workflow/`) and suggest `/w:workspace-init`.
+7. **Host context (opportunistic, read-only).** After the dashboard, if the host exposes *cheap* host-memory (see [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory* — e.g. the auto-memory `MEMORY.md` on Claude Code), append a `▸ CONTEXTO DEL HOST` section with a few signals of recent focus relevant to this workspace. If there is no cheap host memory, **omit the section silently**. Never run an expensive transcript scan here and **never ask** — this is a read-only dashboard; the enrichment is additive and must not slow the default output.
+
+> **Three axes, none of them a substitute for another.** A task completed answers *what work was done* (`tasks_done`/`tasks_total`); a phase validated answers *what functional state was demonstrated* (`phases_validated`/`phases_total`); a plan closed answers *whether the whole solution was validated* (`plan_state`). `progress_pct` stays checkbox-derived — it never reads the phase marks. A plan at 100% with `phases_validated: 0` is **work implemented, not validated**: report it in both blocks and say so. `phases_total: 0` means a legacy plan with no phase marks — show only its checkbox progress, never a `0/0`.
+
+> **`plan_state` is derived, never declared alone.** `open` (or nothing declared) keeps the plan in `▸ FALTA`, **including** a plan whose every box is ticked and every phase validated: that one carries `final_validation_pending: true` and is reported as `validación final pendiente` — the work is complete, the final validation never ran. `done` reaches `▸ HECHO` only when the counters back the declaration. `inconsistent` means the document declares `done` while tasks or phases stay open, or declares a value nobody can read: it belongs in `▸ FALTA` **with the contradiction named** (`declara done con 2 tareas abiertas`), because only a human repairs it.
+
+> **A blocked phase says what it waits on.** A `bloqueada` phase is the implemented-not-validated gap made explicit — every box ticked, its verification still pending — and belongs in both blocks: the work under `▸ HECHO`, the phase under `▸ FALTA` with its `> Bloqueo:` reason, so the reader knows the next action instead of only the state.
+
+> **The frontmatter governs spec maturity.** The spec's `status` (`draft` | `refining` | `ready-for-plan`) is the primary source, and readiness is never inferred from a section the spec happens to carry. A `status` that is absent, empty or unknown reads `draft` and the spec is reported as pending; only a spec with **no frontmatter at all** falls back to the two legacy marks (`## Refinement decisions`, `## Q&A traceability`).
 
 Suggested format (plain text; user-facing labels in Spanish):
 
@@ -30,13 +39,17 @@ Suggested format (plain text; user-facing labels in Spanish):
 Workspace: <name>
 
 ▸ HECHO
-  • plan <slug> — <done>/<total> tareas (<pct>%) · <relative>
-  • spec <slug> — refinado · <relative>
+  • plan <slug> — cerrado · <done>/<total> tareas (<pct>%) · <validadas>/<fases> fases validadas · <relative>
+  • spec <slug> — lista para plan · <relative>
   • <folder> (<type>) — cerrada · <relative>
 
 ▸ FALTA
   • <folder> (<type>) — activa · <relative>
-  • plan <slug> — <pendientes> tareas pendientes
+  • plan <slug> — <pendientes> tareas pendientes · <sin validar> fases sin validar
+  • plan <slug> — validación final pendiente (todo validado, sin cierre)
+  • plan <slug> — inconsistente: declara done con <n> tareas abiertas
+  • F3 — Persistencia real — bloqueada: falta aplicar la migración
+  • spec <slug> — borrador · <relative>
   • spec <slug> — <n> preguntas abiertas
 
 ▸ DESCARTÓ

package/skills/w/loops/CHASSIS.md

@@ -125,7 +125,7 @@ The host is not only the loop's executor — it is a legitimate **producer** of
 
 Investigation is **inline**: an activity **inside the run's current session**, never a separate session. It writes its artifacts (`ANALYSIS-FILE` → `CONCLUSIONS`, + read-only `SCRIPTS.sql` if it queries DB) into the **session's own folder**.
 
-- **Autonomous**: the AI investigates inline and reports **without asking permission**. The human learns of it at integration time (in the flow's decision record — e.g. `## Refinement decisions` in the refine loops, `DECISION` in the code-editing ones) and keeps control via the `flow` control.
+- **Autonomous**: the AI investigates inline and reports **without asking permission**. The human learns of it at integration time (in the flow's decision record — each heir names its own) and keeps control via the `flow` control.
 - **Scope**: the current conversation (*adopted context* — settled conclusions are reused, never re-derived) + workspace + associated repos (sources) + DB MCPs.
 - **DB rule** (the single exception to autonomy):
   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.
@@ -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: 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 loop **degrades** the gap: to a **human question** (next batch → the flow's decision record) 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` 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).
+> Each heir defines its **prior-work mark** and its own legacy tolerances: spec-refine keys off the spec's frontmatter `status`; plan-refine off `## Refinement decisions` in the plan; plan-exec off 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/CODE-POLICIES.md

@@ -25,6 +25,8 @@ After validation (of the phase in plan-exec; of the task in quick, proportional)
 - **Independent re-read** of the diff (subagent or clean re-read — the engine's *independent verification*: it does not assume the implementation is correct; *only command output counts*).
 - **Apply the installed ambient conventions** relevant to the touched stack (code/stack standards, security, diff review, the workspace's own families) — the host **auto-discovers them by `description`**. Workline **names and binds no** concrete conventions skill: **it creates the moment; the installed skills fill it** (that is why review is **not a role** — see [`../roles/README.md`](../roles/README.md)). With no convention skills installed → minimal generic checklist: SOLID/early-return, clear names, DRY, no silenced errors, no secrets/PII, parametrized SQL, no dead code, + the plan's `Validations` (if any).
 - **Minimality lens** (floor — holds with **no external skill**; chassis § *Minimality*): re-read the diff for over-building. Flag `delete` (dead/speculative code), `stdlib` (reinvented standard library), `native` (a dep or code doing what the platform already does), `yagni` (one-implementation abstraction, config nobody sets, one-caller layer), `shrink` (same behavior, fewer lines). An installed ambient review skill *raises* this; it never lowers it.
+- **Test-value lens** (floor, next to minimality): every test the diff adds must demonstrate an observable behavior, protect a business rule, verify a contract, exercise a real integration or prevent a known regression. Flag `overtest` for the ones that only mirror structure — a test per class or method, mocked call chains, the same happy path re-asserted at every layer, trivial getters/setters/mappers, cases written for coverage, broad snapshots where a functional assertion is clearer. Bounded by *Gate integrity*: `overtest` prunes redundancy, **never** a check that guards behavior, a trust boundary, security or accessibility.
+- **Temporary simulation check** (only when the change carries one): stubs, fakes and in-memory adapters are **explicit and named as such** (`Stub…` / `Fake…`), they sit at the boundary the plan declares, and no configuration can select them in a production runtime. A simulation still active on the main path with no declared removal is a finding, not a detail.
 - **Tooling check** (`docs/tools`): did the run create **reusable auxiliary tooling** (support scripts/CLIs/generators/reusable configs — not product code, not session probes)? → the host applies the **ambient `creating-tools` skill** (auto-discovered by its `description`; Workline does not bind it) so the tool gets its home under `docs/tools/<slug>/` (README + run/output structure per that skill's contract + its index row). Host without such a skill → the loop still **never writes `docs/tools` itself**: **declare the gap** — the homeless tool goes to the plan's `Open questions` + `BACKLOG` (in quick, `BACKLOG`) — never silent.
 - **Findings**: **fix** them in the working tree and **re-run validation** (the gate does not replace the tests: it re-verifies after fixing), or **defer them justified** (→ the plan's `Open questions` + `BACKLOG`; in quick, `BACKLOG`); the non-obvious → `DECISION`. Gate integrity (see [`CHASSIS.md`](CHASSIS.md) § *Verification-first*): never weaken a check or lower a convention to pass.
 - **Artifact-first + verification-first**: `CHECKPOINT.Next = "review <phase/task>"` before the pass; `SESSION.Success criteria` includes from the start "the diff passed the review gate before its commits".

package/skills/w/loops/README.md

@@ -16,14 +16,16 @@ The 5 loops run the same **common engine**, whose canon lives in [`CHASSIS.md`](
 
 | Loop (`name:`) | Flow | Started by | Reads | Writes |
 |---|---|---|---|---|
-| [`spec-refine-loop`](spec-refine-loop/LOOP.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (the spec itself) | `docs/specs/NNN-spec-<slug>.md` (in place) |
-| [`plan-new-loop`](plan-new-loop/LOOP.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
-| [`plan-refine-loop`](plan-refine-loop/LOOP.md) | PLAN | `/w:plan-refine` *(aux, optional)* | `docs/plans/PPP-plan-*.md` (the plan itself) | `docs/plans/PPP-plan-<slug>.md` (in place) |
+| [`spec-refine-loop`](spec-refine-loop/LOOP.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (the spec itself) | `docs/specs/NNN-spec-<slug>.md` (in place) **and, with confirmation, sibling specs** (accepted split) **or one replacement spec** (`Crear una nueva spec`) |
+| [`plan-new-loop`](plan-new-loop/LOOP.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md`, **or N sibling plans** (accepted split) |
+| [`plan-refine-loop`](plan-refine-loop/LOOP.md) | PLAN | `/w:plan-refine` *(aux, optional)* | `docs/plans/PPP-plan-*.md` (the plan itself) | `docs/plans/PPP-plan-<slug>.md` (in place) **plus the extracted sibling plans** (accepted split) |
 | [`plan-exec-loop`](plan-exec-loop/LOOP.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); the rest via `export-*` |
 | [`quick-loop`](quick-loop/LOOP.md) | QUICK | `/w:quick` | — (prompt) | edits code + light session; **no** `docs/` |
 
 > `/w:spec-new` has no loop (single-pass). Hence **6 commands / 5 loops**.
 
+> **A single run may write several documents.** Splitting, and replacing by a new spec, produce more than one file — always **inside the same flow's folder**, always **after confirmation**, never in another `docs/` zone: the `docs/` boundary below bounds *where* a loop writes, not *how many* files it writes there. `Reformular esta spec` is the counter-case: a replacement that creates nothing and edits the same file in place.
+
 ### `docs/` boundary (hard rule)
 
 Every loop writes **only** its own flow's doc (SPEC→`docs/specs` · PLAN→`docs/plans` · QUICK→none) and **never** graduates other artifacts to `docs/` — that promotion belongs to the separate, explicit `export-*` skills. Canon: [`CHASSIS.md`](CHASSIS.md) § *docs/ boundary*.