@tacuchi/agent-workflow-cli 20.17.0 → 20.21.0

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

@@ -3,7 +3,8 @@ name: plan-new-loop
 description: >-
   Generates a rich implementation plan (docs/plans/PPP-plan-<slug>.md) from a
   spec. Heir of the chassis (loops/CHASSIS.md). Deltas: the plan absorbs the
-  TECHNICAL-NOTE level + phased Tasks (### Fn blocks) with live state,
+  TECHNICAL-NOTE level + Tasks phased by verifiable functional state
+  (### Fn blocks with live state),
   code/impact-mapping research, planning gap taxonomy, and per-screen design
   SPECs via ui-design
   when the plan includes UI. If the spec is not refined it suggests
@@ -25,7 +26,7 @@ PLAN
 `/w:plan-new` — **resumable** (same chassis mechanism, keyed off CHECKPOINT).
 
 ## Reads
-`docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Refined vs draft** is distinguished by the **presence** of `## Refinement decisions` in the spec (legacy specs may also carry `## Q&A traceability`): if missing → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), but the user may proceed.
+`docs/specs/NNN-spec-*.md` (glob — locates the spec by number; or the exact path from the command argument). **Ready vs not** is read from the spec's frontmatter `status`: `ready-for-plan` → proceed (legacy compat: a frontmatter-less spec carrying `## Refinement decisions`, or the older `## Q&A traceability`, counts as ready). Otherwise → **soft-suggest** running `/w:spec-refine` first (planning over a solid spec produces better plans), **never a block**: the user may proceed. Questions the spec left with destination `PLAN` are **input to this loop**, not a reason to send it back.
 
 ## Writes
 `docs/plans/PPP-plan-<slug>.md` (`generate`; **overwrites with confirmation** if it exists) — or **several sibling plans** when an accepted split applies (§ *Split gate (multi-plan)*). It writes only `docs/plans` — never other `docs/` folders, no auto-export. If the plan **includes UI**, it also produces **design SPECs** (`NNN-SPEC-<SLUG>.md`) as artifacts **of its session** (see *Delta 4* — they are not `docs/`, no auto-export).
@@ -62,10 +63,12 @@ The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roa
                        aligned with the spec criteria. One narration, not four.
 ## Impacted            FE · BE · DB (schemas/tables/functions) · APIs · integr. (core)
 ## Dependencies        docs / sources / databases / sessions · inter-plan order on a split (opt.)
-## Tasks               (core) `### Fn — <name>` blocks — 1-line objective +
-                       complexity XS–S — each holding its `- [ ] Tn.m` tasks
-                       (≤XS, deps and live state). The `### Fn` headers are the
-                       ONLY source of phases; there is no separate Phases table.
+## Tasks               (core) `### Fn — <name>` blocks per the phase contract
+                       below: each one a verifiable functional state with its
+                       `> Estado:` line, its evidence and its `- [ ] Tn.m`
+                       units of purpose — never a list of layers or files.
+                       The `### Fn` headers are the ONLY source of phases;
+                       there is no separate Phases table.
 ## Validations         validations / constraints / business logic              (core)
 ## Risks / impact      technical risks and impacts                             (opt.)
 ## Assumptions         assumptions — only the delta over the spec, never re-imported (opt.)
@@ -76,6 +79,46 @@ The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roa
 
 > **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/LOOP.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
 
+## Phase contract (canonical)
+
+A `### Fn` block is a **verifiable state of the system**, never a list of layers, files or classes. It answers one question: *what can the system do or demonstrate at the end that it could not at the start?* The contract is defined **once** here — [`plan-refine-loop`](../plan-refine-loop/LOOP.md) and [`plan-exec-loop`](../plan-exec-loop/LOOP.md) reference it and never redefine it.
+
+```markdown
+### F1 — <result-oriented name>
+
+> Estado: pendiente
+
+**Resultado:** <the new verifiable state of the system>
+
+**Recorrido afectado:** <consumer → components → current boundary>
+
+**Trabajo:**
+- [ ] T1.1 — <coherent unit of work>
+
+**Límite de simulación:** antes <where it is> → después <where it lands, or removed>
+
+**Validación de fase:** <the primary proof that the promised state was reached>
+
+**Condición de salida:** <falsifiable result · contract preserved · simulation, if any, located or removed>
+
+**Diferido:** <work consciously reserved for another phase>
+```
+
+- **Always**: `Resultado` · `Trabajo` · `Validación de fase` · `Condición de salida`.
+- **Conditional**: `Estado inicial` (when it is not obvious) · `Recorrido afectado` (distributed change) · `Límite de simulación` (temporary behavior exists) · `Diferido` · `Dependencias` (the phase cannot run in direct sequence).
+
+**Phase state = machine state.** One `> Estado: <value>` line directly under the `### Fn` heading; vocabulary `pendiente` | `en ejecución` | `bloqueada` | `validada`, updated **in place**, never duplicated. It is what `aw status` counts (`phases_validated` / `phases_total`), **alongside — not instead of —** the checkbox progress. A phase reaches `validada` only when its work is done, its `Condición de salida` holds, its validation **ran and passed**, and the closing review gate passed. **Never** because all its checkboxes are ticked. *(Legacy plans carry no line at all: `aw status` reports them as zero phases — checkbox progress only. A missing line among stated blocks reads `pendiente`, and nothing is back-filled.)*
+
+**The state line carries its value alone** — no comment, no suffix, no annotation; an annotated value reads as `pendiente`. A blocker's reason lives on its own `> Bloqueo: <reason>` line inside the block, and in `CHECKPOINT`, `## Open questions` and `BACKLOG`.
+
+> Position disambiguates the two marks: the plan-level `> Estado: done — …` line lives under the title (plan-exec § *Delta 6*); the phase-level one lives inside its `### Fn` block.
+
+**Granularity is semantic, not mechanical.** A phase earns its place when it leaves a demonstrable state, can be reviewed as a unit, and — when the change carries temporary behavior — moves or retires a simulation. A task is a **coherent unit of purpose** and may touch several files. Naming an edit operation — "create class X", "add method Y", "update the import" — describes a **micro step**: internal to execution, recorded in `CHECKPOINT` when a resume needs it, never a plan entry. `XS–S` stays an orientation of risk and scope; it never mandates splitting a semantic task into mechanical operations.
+
+## 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.
+
 ## Delta 2 — Gap taxonomy (of "plan")
 
 Replaces the spec gap taxonomy with a planning-oriented one:
@@ -85,9 +128,13 @@ Replaces the spec gap taxonomy with a planning-oriented one:
 | Approach/Solution undefined | the how is vague | research / human |
 | Components unidentified | FE/BE/DB impact unknown | **research** (maps the code) |
 | AS-IS wiring unknown | current state unknown | **research** |
-| Phase too large | complexity > S | human (re-split) |
+| Journey unmapped | the observable contract, the participating components or the repo/process boundaries are unknown — the phases cannot be ordered | **research** |
+| Phase without a state | a `### Fn` mixes unrelated functional states, or nothing can be validated until the very end | the AI re-shapes it by state (**human** confirms an order change) |
 | Plan splittable | independently deliverable tranches — different moments/priorities, no shared deps/risk | **human consents** → split (see *Split gate (multi-plan)*) |
-| Task not atomic | complexity > XS | the AI re-splits |
+| Task named as an edit | the name states an edit operation ("create class X", "add method Y") instead of a purpose | the AI re-states it by purpose |
+| Structural micro-tasks | the plan enumerates files, classes or methods as entries | the AI groups them by purpose |
+| Simulation without lifecycle | temporary behavior exists with no phase that displaces it and no phase that retires it | the AI derives both / **human** |
+| Phase without evidence | the block declares no `Validación de fase` | the AI derives it from the criteria / **human** |
 | Over-engineered solution | approach heavier than the criteria need — needless abstraction/layer/dependency, or a phase/task not required to meet the spec (chassis § *Minimality*) | AI proposes the lighter path + **human** confirms (**probe** if "lighter works" is a runnable doubt) |
 | Missing deps | order unclear | research / human |
 | Spec criteria uncovered | tasks don't trace to acceptance criteria | the AI derives + human confirms |
@@ -132,8 +179,8 @@ Resolves the **Plan splittable** gap (Delta 2) — the canonical definition for
 ```
 plan-new-loop(spec):
   input = glob(docs/specs/NNN-spec-*.md) | argument path
-  if the spec does NOT have ## Refinement decisions:
-    soft-suggest /w:spec-refine (the user may proceed anyway)
+  if the spec is not status: ready-for-plan (nor a legacy mark):
+    soft-suggest /w:spec-refine    # never blocks — the user may proceed anyway
   session = create_or_resume("<slug>-plan-new")               # CLI prepends global NNN
   seed SESSION.Success criteria = coherence-gate checklist      # verification-first, BEFORE
   work = plan skeleton (Delta 1) derived from the spec (+ checkpoint progress if resuming)
@@ -147,7 +194,11 @@ plan-new-loop(spec):
     - every spec acceptance criterion traces to a phase/task
       (split: each criterion → exactly one sibling — complete, disjoint partition)
     - the Final behavior block of ## Solution covers the criteria
-    - ### Fn phases XS–S · tasks XS · deps without cycles · Impacted consistent with Solution
+    - every ### Fn leaves a verifiable state with its own exit condition — never a list of layers or files
+    - the order allows early integration · deps without cycles · Impacted consistent with Solution
+    - the simulation boundary, ONLY when the change carries one, is located, its displacement planned, and one phase owns its retirement
+    - every phase declares its primary evidence; per-layer tests are justified, never automatic
+    - resumable: a stop between phases leaves a stable state and a legible next intent
     - minimality (chassis § *Minimality*): the Solution is the lightest that meets its Final behavior block; no phase/task/abstraction the criteria don't require
     - (UI) every screen/UI task traces to its design SPEC and does not contradict ## UI spec
     whatever fails → comes back as a gap
@@ -163,6 +214,7 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 ## Convergence / exit
 
 - **No material gaps** → **coherence gate** (the *Sequence* checklist; the PLAN-new instance of the chassis convergence gate). Criterion→task traceability is a **checked invariant**, never a separate section.
+- **The gate judges functional states, not size.** A plan converges when every `### Fn` is a verifiable state with its exit condition and its primary evidence — plus its simulation boundary located, **only when the change carries one**; a phase that only enumerates layers or files comes back as a gap, however small it is.
 - Passes → `Guardar plan` (writes with confirmation if it exists) → `finalize`.
 - **Split branch**: `Guardar planes` writes the N siblings sequentially (mint before each write) → `finalize` — one session, one HISTORY row.
 - `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).

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

@@ -1,13 +1,14 @@
 ---
 name: plan-refine-loop
 description: >-
-  Refines an existing plan (docs/plans/PPP-plan-<slug>.md) by editing it IN
-  PLACE — an auxiliary, NOT mandatory step before plan-exec. Heir of the
-  chassis (loops/CHASSIS.md). Deltas: reuses plan-new-loop's gap taxonomy and
-  coherence gate, adds Refinement decisions (trace, no gating), and
-  produces/updates design SPECs via ui-design when the refine
-  touches UI. Started by /w:plan-refine; resumable and re-runnable on demand.
-  Invoke when an already generated plan must be adjusted before executing it.
+  Turns an existing plan (docs/plans/PPP-plan-<slug>.md) into an EXECUTABLE
+  sequence of functional states, editing it IN PLACE. Heir of the chassis
+  (loops/CHASSIS.md). Deltas: functional journey map, phases re-shaped by
+  verifiable state (contract in plan-new-loop), simulation lifecycle,
+  evidence by behavior, executability gate, replanning of partially executed
+  plans, and design SPECs via ui-design on UI changes. Started by
+  /w:plan-refine — also the return path when plan-exec stops on a structural
+  deviation; resumable and re-runnable on demand.
 ---
 
 # plan-refine-loop
@@ -22,11 +23,19 @@ PLAN
 ## Layer
 2 — the AI runs it end to end.
 
+## Objective — an executable sequence of functional states
+
+This loop turns a plan into a sequence of **verifiable states of the system**. Exit condition:
+
+> `plan-exec` can implement every phase **without inventing** contracts, observable states, structural order, simulation boundary or exit evidence.
+
+The phase contract is defined **once** in [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Phase contract (canonical)* — this loop **applies** it and never redefines it: a `### Fn` block is a state the system reaches, with its `> Estado:` line, its work, its evidence and its exit condition.
+
 ## Auxiliary / NOT mandatory
-`plan-exec` runs **any** plan, refined or not — there is **no** gate requiring plan-refine. This loop exists to incorporate changes (new requirements, scope adjustments, deps/risks spotted on re-read) **before** executing, without regenerating the plan from scratch.
+`plan-exec` runs **any** plan that is already executable, refined or not — there is **no** gate requiring plan-refine. This loop exists to incorporate changes (new requirements, scope adjustments, deps/risks spotted on re-read) **before** executing, and to give an unexecutable plan the shape its execution needs, without regenerating it from scratch.
 
 ## Started by
-`/w:plan-refine` — **resumable** (same chassis mechanism, keyed off CHECKPOINT) and **re-runnable on demand** (see *Compact / resume*).
+`/w:plan-refine` — **resumable** (same chassis mechanism, keyed off CHECKPOINT) and **re-runnable on demand** (see *Compact / resume*). Second path: **the return from execution** — `plan-exec` derives here when its entry check finds a structural gap it cannot normalize, or when it stops mid-run on a structural deviation (§ *Replanning executed work*).
 
 ## Reads
 `docs/plans/PPP-plan-*.md` (glob — locates the plan by number; or the exact path from the command argument). **Always the plan itself**: this loop edits it in place; there is no separate "refined" file. Provenance is irrelevant — generated by `plan-new`, **hand-written, or adopted** from a host planner (`plan-new` mode 4 / `persist`); existence is the only requirement.
@@ -52,25 +61,27 @@ The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md)
 
 ```markdown
 ## Refinement decisions   ← NEW (ADDED) — the run's single trace
-What was adjusted while refining and why (new requirements, scope changes,
-deps/risks). Includes what inline research resolved (ref to the session's
-CONCLUSIONS) and every doubt asked to the human, as entries
-`Q: <question> → <chosen answer> — <rationale>`.
+MATERIAL changes only: contracts, journey, shape or order of the phases,
+movement of the simulation boundary, risks that altered the plan, and work
+already executed that conditions the replanning. A doubt that changed one of
+those goes as `Q: <question> → <chosen answer> — <rationale>` (ref to the
+session's CONCLUSIONS for what research resolved). A micro-decision, or a
+question that changed nothing, is NOT transcribed.
 ```
 
 > **No gating contract** (unlike spec↔plan): the presence of `## Refinement decisions` in the plan is **audit trace only** — `plan-exec` neither requires nor checks it (it runs any plan). It serves to (a) distinguish a re-refined plan from a freshly generated one on resume, and (b) record what changed and why. *(Legacy plans may also carry `## Q&A traceability`; new runs never write it.)*
 
-> The plan **never mutates by execution** (plan-exec tracks that in the plan-doc's Tasks) — only by a (re-)refine.
+> **Execution updates progress; refinement changes structure.** `plan-exec` updates the plan's operational state in place — task checkboxes, the phase `> Estado:` line with its `> Bloqueo:` line while blocked, declared deferrals and the final plan status line. It does **not** redesign contracts, phase shape or order, participating components, evidence or simulation boundaries: those structural changes are this loop's, and a change of functional behavior belongs to `spec-refine`.
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
-Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/LOOP.md) § *Delta 2*): vague Approach/Solution, components unidentified, AS-IS wiring unknown, phase too large, task not atomic, missing deps, spec criteria uncovered, unaddressed risks, plan splittable, UI without design SPEC. **Focus difference:** plan-new **builds** the plan from scratch; plan-refine **detects what changed** against the written plan (or against the spec, if the spec was re-refined) and closes **those** gaps — typically fewer and more localized. One extra re-refine gap:
+Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/LOOP.md) § *Delta 2*), semantic rows included: journey unmapped, phase without a state, task named as an edit, structural micro-tasks, simulation without lifecycle, phase without evidence, plus the shared ones (vague Approach/Solution, components unidentified, AS-IS wiring unknown, over-engineered solution, missing deps, spec criteria uncovered, unaddressed risks, splittable plan, UI without design SPEC). **Focus difference:** plan-new **builds** the plan from scratch; plan-refine re-shapes what is already written — what changed against the plan (or against the spec, if the spec was re-refined) and what still keeps the plan from being executable. One extra re-refine gap:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
 | Plan↔spec drift | the spec was re-refined and the plan fell out of line | **research** (re-reads the spec) / **human** |
 
-> **Spec-less degradation (hand-written / adopted plans).** When the plan has **no source spec** (`## Origin` = adopted / hand-written), the spec-anchored checks **degrade gracefully**: "spec criteria uncovered" and "plan↔spec drift" do **not** apply — criterion→task traceability anchors to the plan's **own** Final behavior block (in `## Solution`) / `## Validations` instead. The rest of the taxonomy (atomicity, deps, Impacted↔Solution, UI→SPEC) applies unchanged. Normalizing an adopted plan to the full Delta 1 schema **is** this loop's job (missing `(core)` sections are gaps).
+> **Spec-less degradation (hand-written / adopted plans).** When the plan has **no source spec** (`## Origin` = adopted / hand-written), the spec-anchored checks **degrade gracefully**: "spec criteria uncovered" and "plan↔spec drift" do **not** apply — criterion→task traceability anchors to the plan's **own** Final behavior block (in `## Solution`) / `## Validations` instead. The rest of the taxonomy (phase shape, simulation, evidence, deps, Impacted↔Solution, UI→SPEC) applies unchanged. Normalizing an adopted plan to the full Delta 1 schema **is** this loop's job (missing `(core)` sections are gaps).
 
 > **Adjust the Solution the laziest-that-works way** (chassis § *Minimality*, generative side): reuse what already exists before adding abstractions, layers or dependencies — the coherence gate only *confirms* minimality, and a re-refine is a chance to *remove* over-building, not add it.
 
@@ -82,6 +93,57 @@ Same as plan-new (maps code/impact: FE/BE/DB components, AS-IS wiring, deps), bu
 
 Same mechanism as [`plan-new-loop`](../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.
 
+## Functional journey map
+
+Before re-shaping phases, the plan must answer what execution would otherwise have to invent. The answers land **inside the existing sections** (`## Solution`, `## Impacted`, the `### Fn` blocks) — this loop adds no plan section beyond its trace:
+
+- **Observable contract** — who starts the operation, what inputs it provides, what successful result and what errors or states it observes, which contracts are created or changed, and what must stay compatible.
+- **Technical journey** — participating components and their approximate order, boundaries between repos or processes, where persistence and external integrations sit, what already exists and what must be wired.
+- **Incremental strategy** — the first demonstrable journey and, **only when the change carries temporary behavior**, where a safe simulation can live, how it is displaced and which phase retires it (reference shapes: [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Incremental strategy*).
+- **Evidence** — the primary proof of each phase, which rules deserve an isolated test, which integrations need a real one, and what cannot be validated because of operational constraints (that one goes to `## Open questions`).
+
+> **Bounded research** (Delta 3, sharpened): investigate **only** what is needed to order the phases — journey, boundaries, existing contracts, where the simulation can live, risks that change the plan's design. What `plan-exec` resolves locally is **not** pre-investigated here.
+
+## 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.
+
+## Evidence by behavior
+
+Each phase carries proof of behavior, not of structure. Three levels, **chosen** — never descended automatically:
+
+1. **Primary phase proof** — demonstrates the state the phase promised: component interaction, endpoint smoke, a vertical run down to the stub, persistence integration, or the end-to-end happy path.
+2. **Focused proofs** — where a layer owns rules, a relevant transformation, error handling, persistence, transactions, temporal logic or an external integration.
+3. **Risk proofs** — security, concurrency, idempotency, retries, known regressions, plausible high-impact failures.
+
+The primary proof lives **inside its `### Fn` block** (`Validación de fase`); `## Validations` keeps the cross-cutting rules and constraints. A simulation gets only the minimum proof that demonstrates the wiring — no suite is built around what the next phase retires.
+
+> **Necessity gate** (design criterion, not a record to keep): what behavior does the test demonstrate, what unique failure would it catch, is that already demonstrated elsewhere, does it target a stable boundary or an internal detail, does the layer own logic or risk, is it still worth keeping once the simulation is gone? No clear answer → it is not planned. Whatever slips through and only mirrors structure is flagged `overtest` by execution's closing review gate.
+
+## Executability gate
+
+This loop's instance of the chassis convergence gate — the same one `plan-exec` verifies on entry. Whatever fails comes back as a gap:
+
+- **Contract** — relevant inputs, outputs and observable states identified; the final behavior matches the spec; no functional criterion invented here.
+- **Journey** — main components identified, order reasonable, repo/process boundaries visible, the described architecture the one the project actually has.
+- **Phases** — each leaves a verifiable state with its exit condition, none is a list of layers or files, the order allows early integration, deferrals are explicit.
+- **Simulation** *(only when the change carries one)* — initial boundary identified, every displacement foreseen, one phase owns the retirement, nothing can stay active by accident. No temporary behavior → the check does not apply, and no empty `Límite de simulación` is required.
+- **Evidence** — every phase declares its primary proof, per-layer tests are justified, the same scenario is not duplicated by default, declared risks have evidence or an explicit deferral.
+- **Resumability** — tasks legible enough for a `CHECKPOINT`, intermediate states stable, pending work distinguishable from work already `validada`.
+
+## 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`](../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.
+
 ## Split gate — refine semantics
 
 The gate itself — signals, offer, anti-duplicate, sibling contract, partition — is defined **once** in [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Split gate (multi-plan)* (this flow's guaranteed load already includes that file); this loop only adds the **in-place semantics** of splitting an existing plan:
@@ -103,8 +165,11 @@ Full mechanism (3 cases, `Compactar`, re-run with `--reopen`) in the chassis (§
 plan-refine-loop(plan):
   input = glob(docs/plans/PPP-plan-*.md) | argument path       # always the plan itself (in place)
   session = create_or_resume("<slug>-plan-refine")             # reopens if it exists (see Compact / resume)
-  seed SESSION.Success criteria = coherence-gate checklist     # verification-first, BEFORE
-  work = read(plan) (+ the spec if realignment is needed; + checkpoint progress if resuming)
+  seed SESSION.Success criteria = executability-gate checklist # verification-first, BEFORE
+  work = read(plan) (+ the spec if realignment is needed; + checkpoint/exec history if resuming or returning from plan-exec)
+  journey = map(observable contract, technical journey, incremental strategy, evidence)  # bounded research
+  work = phases grouped by verifiable state (phase contract) + simulation lifecycle if any + primary proof each
+  keep validated phases and their completed tasks; redesign ONLY pending work
   repeat:                                                      # chassis engine
     gaps = detect_gaps(work)  (plan-new taxonomy + plan↔spec drift)  minus the exhausted ones
     if gaps == ∅: break
@@ -112,8 +177,9 @@ plan-refine-loop(plan):
       research (scoped to the delta — Delta 3) · human (structured-choice) · probe (chassis) ·
       ui-design (Delta 4, only new/changed screens)
     integrate + update CHECKPOINT                              # artifact-first cycle
-  coherence gate (read-only) = Success criteria green:
-    - plan-new checklist (criterion→task · Final behavior block of Solution · XS–S/XS · deps · Impacted↔Solution · UI→current SPEC · minimality)
+  executability gate (read-only) = Success criteria green:
+    - contract · journey · phases · simulation · evidence · resumability (§ Executability gate)
+    - plan-new checklist (criterion→task · Final behavior block of Solution · deps · Impacted↔Solution · UI→current SPEC · minimality)
       # spec-less plan (adopted/hand-written): criteria anchor to the plan's own Final behavior block/Validations (see Delta 2)
     - re-refine's own check: the plan is REALIGNED with what changed
     whatever fails → comes back as a gap
@@ -128,7 +194,9 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 
 ## Convergence / exit
 
-- **No material gaps** → **coherence gate** (the *Sequence* checklist; plan-new's gate + the re-refine's own realignment check).
+- **No material gaps** → **executability gate** (the *Sequence* checklist: contract · journey · phases · simulation · evidence · resumability, plus plan-new's coherence checks and the re-refine's own realignment check).
 - Passes → `Guardar plan refinado` (edits in place with confirmation) → `finalize`.
 - **Split branch**: `Guardar planes` edits the original reduced and writes the extracted siblings → `finalize`.
 - `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).
+
+> **After refining:** the plan goes to `plan-exec`, which re-checks this same gate on entry — a plan saved here should never bounce back for its structure.

package/skills/w/loops/quick-loop/LOOP.md

@@ -58,7 +58,7 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
   - **`Recortar alcance`** → the AI proposes the **sub-task that DOES fit** a quick; the loop continues with it (`SESSION.Objective` = the sub-task; the original prompt goes into the session's `## Origin`) and the rest is deferred to `BACKLOG` ("trimmed at the gate — may warrant its own spec, `/w:spec-new`").
   - **Anti-duplicate** (the `create_or_resume` spirit): if a spec whose `## Origin` references this same objective already exists (or an equivalent `*-spec-refine` session), the recommended option becomes **resuming that spec** (`/w:spec-refine` semantics) — never a second draft.
 - **Live transition to SPEC** (shared by the gate and mid-loop escalation). On acceptance, the work line **moves to the SPEC flow**: the explicit consent in the structured-choice **equals invoking the destination command** (*consented exception* — rule 3 of the *Continuity rule*, [`../../SKILL.md`](../../SKILL.md) § *Operating context*). On the SPEC side:
-  1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs`, slug, schema, single-pass **NO RESEARCH**. `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists).
+  1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs`, slug, schema, single-pass **NO RESEARCH** — its bounded reconnaissance does **not** re-fire (this run's context arrives adopted). `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists). The draft is born `status: draft`: only the SPEC gate promotes it to `ready-for-plan`.
   2. **Load and execute** [`../spec-refine-loop/LOOP.md`](../spec-refine-loop/LOOP.md) — over that spec (trampoline pattern).
   3. The run's session is that loop's **normal** `NNN-<slug>-spec-refine` (the CLI numbers it; its `## Origin` records the escalation). **Invariant 2 intact**: quick, while it is quick, never writes `docs/` — the draft is written by the SPEC flow, post-consent.
 - **Mid-loop escalation + handoff**: if the task grows (same gate signals) → propose moving up to **SPEC/PLAN** (structured-choice, recommendation first). If the user accepts: