@tacuchi/agent-workflow-cli 20.17.0 → 20.22.0

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

@@ -2,11 +2,11 @@
 name: plan-exec-loop
 description: >-
   Executes an implementation plan (docs/plans/PPP-plan-<slug>.md) as a living
-  doc: reads and updates it phase by phase while editing the real code and
-  managing DB and git. Heir of the chassis (loops/CHASSIS.md +
-  CODE-POLICIES.md). Deltas: single resumable session, safe git (verified
-  branch, per-source proposed commits, never push/--amend/--no-verify), DB
-  scripts-only (never executes DML/DDL), per-phase and final validation,
+  doc: runs it phase by phase — each phase a verifiable state — while editing
+  the real code and managing DB and git. Heir of the chassis (loops/CHASSIS.md
+  + CODE-POLICIES.md). Deltas: executability entry gate, deviation gate
+  (structural to plan-refine, functional to spec-refine), single resumable
+  session, safe git, DB scripts-only, phase proof plus progressive tests,
   pre-commit closing review gate, no auto-export. Composes git and sql.
   Started by /w:plan-exec. Invoke to implement an already generated plan.
 ---
@@ -22,10 +22,10 @@ PLAN
 2 — the AI runs it end to end.
 
 ## Started by
-`/w:plan-exec` — **resumable** (same chassis mechanism; here resume keys off the plan-doc checkboxes + CHECKPOINT, see Delta 1).
+`/w:plan-exec` — **resumable** (same chassis mechanism; here resume keys off the plan-doc phase states + checkboxes + CHECKPOINT, see Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument). It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) — plan-refine is auxiliary, not mandatory; no gate requires it. If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument) **and its source spec** (resolved through the plan's `## Origin`) — the entry gate reads both. It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) — plan-refine is auxiliary, not mandatory; no gate requires it. What it does require is an **executable shape** (§ *Entry gate — executability*). If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: phase/task state, `Open questions`).
@@ -54,16 +54,58 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 > **Compat (legacy):** old workspaces may hold `plan-exec-phase-*` sessions (one per phase) and `*-research-*` ones — historical, left as-is; new runs use a single session.
 
-## Delta 1 — One session per run; per-phase progress in the plan-doc
+## Entry gate — executability
+
+**Before touching code**, read the plan and its spec and check the shape execution depends on:
+
+1. every phase declares its `Resultado`, its `Condición de salida` and its `Validación de fase`;
+2. if temporary behavior exists, its current boundary and retirement phase are identifiable; otherwise the simulation check is not applicable;
+3. the primary proof of the first `pendiente` phase is identifiable;
+4. no structural contradiction is evident (a phase that undoes an earlier one, evidence nobody can produce).
+
+Execution **no longer accepts in silence** a plan that would force it to invent its own structure. Two outcomes:
+
+- **Minor gap** — the plan is all but executable: an exit condition derivable from what is already written, the obvious evidence unnamed, micro-tasks to group. `plan-exec` may **normalize it with consent** — one structured-choice content question, labels `Normalizar y ejecutar` (recommended) | `Ir a plan-refine`. Normalizing edits the `### Fn` blocks in place, **adds no scope and moves no boundary**, and is recorded in `DECISION` + `CHECKPOINT`.
+- **Structural gap** — phases, contracts or journey are missing, or a change that **does** carry temporary behavior leaves its boundary undeclared. It does **not** improvise: record the finding in `CHECKPOINT`, hand off to [`plan-refine-loop`](../plan-refine-loop/LOOP.md) (`/w:plan-refine`) and resume execution over the refined plan.
+
+> **A missing `Límite de simulación` is a gap only when there is something to simulate.** No task and no phase introduces temporary behavior → the block is legitimately absent and the gate passes; demanding it anyway pushes execution to invent a stub so the plan matches a template. The same holds for `Diferido` and every other conditional block.
+
+> The gate reads the **canonical phase contract** from [`plan-new-loop`](../plan-new-loop/LOOP.md) § *Phase contract (canonical)* — required sections, the `> Estado:` vocabulary, semantic granularity. Execution references it; it never redefines it. The marker is a **line of its own** inside the `### Fn` block (`> Estado: <value>`); written any other way it reads as `pendiente`.
+
+## Delta 1 — One session per run; the phase cycle in the plan-doc
 
 - Walks the plan's `### Fn` blocks under `## Tasks` in order (respecting deps) **inside the run's single session** (no session-per-phase). *(Legacy plans: a separate `## Phases` table — walk it the same way.)*
-- **Per-phase progress lives in the plan-doc** (`- [x]`) and in the single `CHECKPOINT` (Completed/Pending/Next): **artifact-first** — `CHECKPOINT.Next` is set to the imminent phase **before** starting it; the plan-doc's `- [x]` checkbox is flipped **after** completing the task.
-- Executes the phase's tasks; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). Marks `- [x]` **in the plan** (living doc; never in a separate `TASKS`).
-- **Checkbox-only residue (hard rule):** execution writes into the plan-doc **only** three things — checkbox flips (`- [ ]` → `- [x]`), deferrals appended to its `## Open questions` (the declared-gap escape hatch: Delta 4's unapplied migration, Delta 5's deferred findings, Delta 7's failed probe), and, on close, the single status line (Delta 6). Per-phase results, review-gate findings and metrics go to the session's `DECISION`/`CHECKPOINT` — **never** into the plan-doc. Phase blocks are updated **in place — NEVER append a duplicate `### Fn` block** (same contract as CHECKPOINT sections).
-- At **every phase boundary**: validate, run the **closing review gate** (Delta 5), update the `CHECKPOINT` (Completed += Phase N, Next = Phase N+1) and propose commits.
-- Records in `DECISION` only the **non-obvious**, **as it is decided** (per-phase decisions accumulate in the SINGLE `DECISION`, tagged by phase/task — e.g. `Origin: T2 (F1)`).
+- **Phase cycle** (artifact-first, one per `### Fn`): read `Resultado` + `Condición de salida` → confirm the initial state → flip `> Estado: en ejecución` and seed `CHECKPOINT.Next` → execute its tasks → run the phase proof plus the justified focused tests (Delta 4). Then: closing review gate over the phase's whole diff (Delta 5) → confirm the `Condición de salida` → flip `> Estado: validada` → update `CHECKPOINT` and propose commits (Delta 2).
+- Executes the phase's tasks; **skips** the ones already `- [x]` in the plan (the plan-doc is the per-task source of truth). **Micro steps stay internal** (canonical contract): they reach `CHECKPOINT` only when a resume needs them, never the plan.
+- **Marking order (hard rule):** a task is marked `- [x]` when its local work is finished. A phase reaches `validada` **only** when its primary proof **ran and passed**, the needed focused checks passed, its `Condición de salida` is true, the review gate is green and every remaining review finding is explicitly deferred — a blocker is never deferred into `validada`. **Never** because all its checkboxes are ticked.
+- **Intermediate states:** `bloqueada` = the phase is stopped on a live blocker — recorded in `CHECKPOINT` + the plan's `## Open questions`, back to `en ejecución` when it clears; it counts as **not validated**. A phase whose work is complete but whose operative check the AI **cannot run** (an unapplied migration — Delta 3) **stays `bloqueada`**: its finished tasks keep their boxes ticked, and the reason goes on its own `> Bloqueo:` line, dropped when the blocker clears. It counts as **not validated** until the check runs and passes. Never a silent `validada`.
+- **A blocker without a reason is not a blocker (hard rule).** Writing `> Estado: bloqueada` **always** writes its `> Bloqueo:` line in the same edit: a state that says "stopped" without saying on what is a dead end for whoever reads `aw status` next. The runtime tolerates a legacy block that states none (`blocker: null`) — this loop never produces one. `CHECKPOINT.Next` names **the action that unblocks it** ("apply migration 014, then re-run the persistence proof"), never the state it is in.
+- **Plan-doc residue (hard rule):** execution writes into the plan-doc **only** five things — checkbox flips (`- [ ]` → `- [x]`), the phase's own `> Estado:` line, its `> Bloqueo:` line while blocked, deferrals appended to its `## Open questions`, and the plan's own status mark (its `> Estado:` line and, on close, its `> Cierre:` line — Delta 6). The declared-gap hatch is Deltas 4, 5 and 7. Per-phase results, review-gate findings and metrics go to the session's `DECISION`/`CHECKPOINT` — **never** into the plan-doc. Phase blocks are updated **in place — NEVER append a duplicate `### Fn` block** (same contract as CHECKPOINT sections). The entry gate's consented normalization is the single exception, and it lands before execution starts.
+- **CHECKPOINT per phase:** on closing a phase record the **functional state reached**, the simulation boundary in force **only when the change carries one**, the tests run and their result, the non-obvious decisions, the deferrals and the next state being pursued. Enumerating every file touched is not required unless it helps a resume.
+- Records in `DECISION` only the **non-obvious**, **as it is decided** (per-phase decisions accumulate in the SINGLE `DECISION`, tagged by phase/task — e.g. `Origin: T2 (F1)`). A structural deviation is **not** settled with an entry there (§ *Deviation gate*).
 - The chassis **gap-driven** engine applies here **inside a task**: facing a non-obvious decision/doubt → inline research, a probe (Delta 7) OR structured-choice.
 
+> **Legacy plans degrade safely.** `plan-exec` still runs plans with `### Fn` blocks, `- [ ]` tasks, legacy sections and **no** `> Estado:` line: a missing line reads `pendiente`, and nothing is back-filled. A plan with every box ticked is **not** validated by that fact — the session (`CHECKPOINT`, review gate) decides. What is genuinely missing is closed by the entry gate or by `plan-refine`, never assumed.
+
+## Deviation gate
+
+Execution resolves **detail**, never **redesign**. This gate lives **only** in this loop — the chassis does not carry it.
+
+- **Local decision — `plan-exec` continues.** A class or method name; a local helper; internal code layout; imports; a choice between equivalent APIs already allowed; a fix needed to compile; a minor refactor that does not move the journey; one extra focused test for a risk found while implementing. Recorded in `DECISION` only when it is not obvious.
+- **Structural deviation — stop and return to `plan-refine`.** Stop when the change touches: an input or output; an observable state; a relevant endpoint or public contract; the set of participating components or repositories; the phase order; the simulation boundary; the integration strategy; a material dependency; the main persistence mechanism; a phase already `validada`; the evidence needed to demonstrate the result. A decision that substantially expands or shrinks the work counts too.
+- **Functional change — return to `spec-refine`.** Stop when the change touches: the expected result; the functional scope; a business rule; an acceptance criterion; the actor or consumer; or a product decision.
+
+On either return path: `CHECKPOINT` records the state reached and the trigger, the phase keeps the state it really has (`en ejecución` or `bloqueada`, never `validada`), the working tree is left committed or acknowledged (Delta 2), and the human is told through a structured-choice which command to run. Resuming later over the corrected plan is a normal `create_or_resume`.
+
+| Finding | `plan-exec` | `plan-refine` | `spec-refine` |
+|---|---|---|---|
+| Rename a helper · internal implementation · test for a local risk | continues | — | — |
+| Change the public DTO | stops | yes | yes, if behavior changes |
+| Add a participating repository | stops | yes | — |
+| Move the simulation to another boundary | stops | yes | — |
+| Change the phase order | stops | yes | — |
+| Add a functional rule · change an acceptance criterion | stops | — | yes |
+
 ## Delta 2 — Git policy: **safe branch + proposed commits**
 
 Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: branch-check before editing, rejected commit — changes stay + get recorded —, working-tree precondition between phases). **Inline:** before editing, verify each source's expected branch (`aw check-branch --source <alias>`; on mismatch → pause and resolve with the human); at each phase close and **after the review gate** (Delta 5), **proposed commits per source** (approve first) — never `push`/`--amend`/`--no-verify`.
@@ -72,23 +114,32 @@ Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Safe git*: bran
 
 Full policy in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *DB scripts-only*). **Inline:** read-only queries → the session's `SCRIPTS.sql`, executed via MCP (`sql-mutation-guard`); DDL/DML migrations → the AI **drafts them in `SCRIPTS.sql` but NEVER executes them** — their promotion to `docs/scripts/` is done by a separate `export-*`, never this loop.
 
-## Delta 4 — Validation
+## Delta 4 — Validation: phase proof + progressive tests
 
-- After executing (per phase and at the end): run tests/checks against `Validations` + the Final behavior block of `## Solution` (legacy plans: the `## Final behavior` section) + the spec's acceptance/success criteria (its `## Scenarios`, if present, are ready-made test cases: GIVEN=arrange · WHEN=act · THEN=assert).
-- A validation that **runs and fails** → back to the task (gap); no advancing.
-- **Validation depending on an unapplied migration**: since the AI never executes the DML, it **cannot run it read-only** → it is **deferred** (handoff to a DBA), it does **not block progress**. Recorded in the plan's `Open questions` + `BACKLOG`, marked "verification pending until the SQL is applied". (Reuses the chassis degrade/defer pattern + `MAX` cap → avoids the "back to the task" loop.)
+- The phase's **primary proof** is its `Validación de fase`: it demonstrates the **state reached**, not the structure written. Three levels, and the loop never descends one automatically:
+  1. **phase proof** — component interaction, endpoint smoke test, vertical run down to the stub, persistence integration, or the main path end to end;
+  2. **focused tests** — added when the layer carries its own rules, a relevant transformation, error handling, persistence, transactions, temporal logic or external integration;
+  3. **risk tests** — security, concurrency, idempotency, retries, known regressions.
+- **One vertical proof per operation while wiring** (request → controller → use case → repository → fake or stub → expected response): it demonstrates the path once instead of re-asserting the same happy path at every layer. Trivial mappers, plain DTOs and framework behavior get no dedicated test.
+- Compatible with **TDD without a test per method**: the evidence may be written before, during or after the phase's code. What is mandatory is that the `Condición de salida` be demonstrated **before** the phase is flipped to `validada`.
+- Each added test is re-weighed at the closing review gate ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Closing review gate* → *Test-value lens*, tag `overtest`): over-testing is a **finding to fix or justify**, never an automatic rejection.
+- Also run the plan's `## Validations` (cross-cutting rules and constraints) + the Final behavior block of `## Solution` (legacy plans: the `## Final behavior` section) + the spec's acceptance/success criteria (its `## Scenarios`, if present, are ready-made test cases: GIVEN=arrange · WHEN=act · THEN=assert).
+- A validation that **runs and fails** → back into the phase (gap): no advancing, no `validada`.
+- **Validation depending on an unapplied migration**: since the AI never executes the DML, it **cannot run it read-only** → the check is **deferred** (handoff to a DBA) and the phase **stays `bloqueada`**. A phase whose implementation is finished but whose operative proof cannot run does not become `validada`: the work may be complete and its boxes ticked, but the state waits until the proof runs and passes. The reason goes on its `> Bloqueo:` line, in `CHECKPOINT`, in the plan's `## Open questions` and in `BACKLOG`, marked "verification pending until the SQL is applied". (Reuses the chassis degrade/defer pattern + `MAX` cap → avoids the "back to the task" loop.)
 
-> The **final validation** is PLAN-exec's **convergence gate** = **`Success criteria` green** (*verification-first*; analogous to SPEC's *analyze gate* and plan-new's *coherence gate*): the plan is not marked *done* until it passes or is explicitly deferred (SQL handoff). For code these are **runnable tests** (TDD); for non-executable DB migrations, a **rubric** (SCRIPTS.sql valid + reviewed).
+> The **final validation** is PLAN-exec's **convergence gate** = **`Success criteria` green** (*verification-first*; analogous to SPEC's *analyze gate* and plan-new's *coherence gate*): the plan is not marked *done* until it passes. A deferred check never counts as a passed one — it keeps its phase `bloqueada` and the plan open. For code these are **runnable tests** (TDD); for non-executable DB migrations, a **rubric** (SCRIPTS.sql valid + reviewed).
 
 ## Delta 5 — Closing review gate (conventions, pre-commit)
 
-Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Closing review gate*): **independent** diff re-read + installed ambient conventions; findings → fix (re-validating the phase) or defer justified. Here only the exec wiring: it runs **between the phase validation (Delta 4) and its commits (Delta 2)**; only with the gate green are the phase's commits proposed.
+Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md) (§ *Closing review gate*): **independent** diff re-read + installed ambient conventions + the floor lenses (minimality, **test value**, **temporary simulation**, tooling); findings → fix (re-validating the phase) or defer justified. Here only the exec wiring: it runs over the phase's **whole** diff, **between the phase validation (Delta 4) and its commits (Delta 2)**; only with the gate green is the phase flipped to `validada` and its commits proposed.
 
 ## Delta 6 — Completion / close
 
-- A phase closes **done** when its tasks are `- [x]` and its validation passed **or** was deferred (SQL handoff). Possible state: **"done — SQL pending application"**.
-- All phases done → final *structured-choice* (content: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`).
-- **Marking done = ONE line in the plan-doc**, under the title's blockquote: `> Estado: done — YYYY-MM-DD · sesión NNN` (or `done — SQL pendiente de aplicar`), updated in place on a re-run. No per-phase result tables, no ✅ suffixes — that record lives in the session (`DECISION`/`CHECKPOINT`).
+- A phase closes when its `> Estado:` reads `validada`: work done, `Condición de salida` true, proof **run and passed**. A proof still waiting on an operative handoff leaves it `bloqueada`.
+- **The plan's own state is the third axis, and it stays `open` during the whole run.** Every phase `validada` is **not** the plan closed: the final validation still has to run. Keep `> Estado: open` under the title while executing — stamping it on the first write if the plan carries none — and never write `done` from the counters — a legacy plan with every box ticked is not closed by that fact (§ *Legacy plans degrade safely*).
+- **Every phase `validada` + the final validation passed** → final *structured-choice* (content: `Marcar plan done` / `Preguntar algo más`; flow: `Compactar`/`Cerrar`). `Marcar plan done` is offered under no other condition: one `bloqueada` phase keeps the plan open, however many of its tasks are ticked.
+- **Marking done = ONE status line in the plan-doc**, under the title's blockquote: `> Estado: done`, updated in place on a re-run. The machine value **stands alone** — the date and session go on their own `> Cierre: YYYY-MM-DD · sesión NNN` line right under it, for the same reason a blocker never rides on a phase's state line. It never replaces the per-phase lines inside the `### Fn` blocks — position tells the two apart. No per-phase result tables, no ✅ suffixes — that record lives in the session (`DECISION`/`CHECKPOINT`).
+- **Legacy status line, migrated on write.** A plan carrying the old single-line form (`> Estado: done — YYYY-MM-DD · sesión NNN`) is still **read** as closed; the first time this loop legitimately writes that document, it is rewritten to the two-line form. Compatibility is for reading old plans — every new write uses the normalized contract.
 - **No automatic export**: the artifacts (`SCRIPTS.sql`, `DECISION`, …) stay in the session. Promoting them to `docs/` (scripts, manuals, …) is a separate step via `export-*`.
 
 ## Delta 7 — Probe (PoC) tasks
@@ -104,43 +155,58 @@ Chassis § *Proof of concept (probe)*, instantiated for execution — for a plan
 ```
 plan-exec-loop(PPP-plan-<slug>.md):
   session = create_or_resume("<slug>-plan-exec")           # <slug> from the plan-doc; ONE session per run; CLI prepends global NNN; CHECKPOINT, resume
-  plan = read(PPP-plan-<slug>.md)
+  plan = read(PPP-plan-<slug>.md, its spec, checkpoint)
+  entry gate (executability): result · exit condition · phase proof · simulation boundary if any · no structural contradiction
+      minor gap      → structured-choice [Normalizar y ejecutar | Ir a plan-refine] → normalize in place + DECISION
+      structural gap → CHECKPOINT(blocker) → hand off to /w:plan-refine → stop
   for each Phase (### Fn block in ## Tasks; legacy: ## Phases table) in plan (in order, respecting deps):
-    if Phase done (all its Tasks - [x] in the plan): skip  # resume via plan-doc checkboxes
+    if Estado == validada: skip                            # legacy (no line): all its Tasks - [x] AND the session shows it closed
+    read Resultado + Condición de salida; confirm the initial state
+    set > Estado: en ejecución
     seed CHECKPOINT.Next = Phase N (Pending = its Tasks)   # BEFORE starting the phase: seed the intent (artifact-first)
     for each Task of the Phase:
       if Task - [x] in the plan: skip                      # intra-phase resume by checkbox
       verify each source's expected branch (branch-check)
         on mismatch → pause + resolve with the human
-      execute Task:
+      execute Task (micro steps internal — never plan entries):
         edit code in the sources (minimal change)
         if it creates a tool/utility → the ambient creating-tools skill documents it in docs/tools
         if read-only DB query → SCRIPTS.sql + execute read-only
         if DB change (DDL/DML) → draft in SCRIPTS.sql (session artifact, DO NOT execute)
-        if non-obvious decision → DECISION (tagged by phase/task, in the SINGLE DECISION)
+        deviation gate:
+            local decision       → resolve; DECISION only if non-obvious (tagged by phase/task)
+            structural deviation → CHECKPOINT(state + trigger) → stop → /w:plan-refine
+            functional change    → CHECKPOINT(state + trigger) → stop → /w:spec-refine
         if probe (PoC) task / runnable doubt → seed check → run throwaway code in the
             session folder → verdict → CONCLUSIONS/DECISION; failed → structured-choice (Delta 7)
         if doubt/gap → inline research, probe OR structured-choice   # chassis
-      mark Task - [x] IN THE PLAN                          # AFTER completing the Task; checkbox flip ONLY — results go to DECISION/CHECKPOINT
-    phase validation:
-        what runs and fails → back to the task
-        what depends on an unapplied migration → defer (Open questions + BACKLOG)
+      mark Task - [x] IN THE PLAN                          # AFTER its local work; checkbox flip ONLY — results go to DECISION/CHECKPOINT
+    phase proof (Validación de fase) + the justified focused tests:   # Delta 4 levels 1→3
+        what runs and fails → back into the phase (no validada)
+        what cannot run (unapplied migration) → defer the CHECK, never the validation: the phase stays bloqueada
     closing review gate (pre-commit):                      # Delta 5: CHECKPOINT.Next = "review phase N"
-        INDEPENDENT re-read of the phase diff + installed ambient conventions
+        INDEPENDENT re-read of the WHOLE phase diff + installed ambient conventions
+        + floor lenses: minimality · test value (overtest) · temporary simulation · tooling
         findings → fix (and re-validate the phase) OR defer justified (Open questions + BACKLOG)
-    update CHECKPOINT (Completed += Phase N, Next = Phase N+1) # AFTER: Pending→Completed + Next = next phase (see artifact-first cycle)
+    confirm the Condición de salida → set > Estado: validada  # ONLY with the proof run and passed; NEVER from the checkboxes alone
+        blocker still live       → set > Estado: bloqueada + > Bloqueo: <reason> + CHECKPOINT + Open questions
+        check not runnable (SQL) → set > Estado: bloqueada + > Bloqueo: <reason> + CHECKPOINT + Open questions + BACKLOG
+    update CHECKPOINT (functional state reached · simulation boundary if any · tests + result · decisions · deferrals · next state)
     propose commit(s) per source (approve first)           # never push/amend/--no-verify; only after the gate is green
         if rejected → changes stay; record "phase uncommitted"
     next-phase precondition: working tree clean or acknowledged
-  final validation (whatever can run; the SQL-dependent part stays as a handoff)
-  structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
-  mark plan done → ONE status line under the title blockquote (Delta 6), updated in place
+  final validation (whatever can run; a deferred check keeps its phase bloqueada)
+  if every phase validada AND the final validation passed:
+    structured_choice(content: [Marcar plan done, Preguntar algo más], flow: [Compactar, Cerrar])
+    mark plan done → > Estado: done + > Cierre: YYYY-MM-DD · sesión NNN under the title (Delta 6), in place
+  else: the plan-level > Estado: stays open → CHECKPOINT.Next = the action that unblocks the phase(s)
   # NO export: artifacts stay in the session; a separate export-* promotes them
 finalize: CHECKPOINT (+ BACKLOG if something is deferred) + close session + report
 ```
 
 ## Convergence / exit
 
-- Plan complete + validation OK (or deferred with a handoff) + **every phase passed its closing review gate** before committing → `Marcar plan done`.
+- **Every phase `validada`** + final validation **run and passed** + **every phase passed its closing review gate** before committing → `Marcar plan done`. A phase left `pendiente`, `en ejecución` or `bloqueada` keeps the plan open, whatever its checkboxes say — a proof waiting on an operative handoff (an unapplied migration) is exactly that case.
+- A **structural deviation** or a **functional change** exits this loop without converging (§ *Deviation gate*): `CHECKPOINT` + `finalize`, and the work continues in `plan-refine` / `spec-refine`. Same exit when the entry gate finds a structural gap.
 - `Cerrar` (`flow` control, at any time) → `finalize` persists `CHECKPOINT` (and `BACKLOG` only if something remained unexecuted / uncommitted / unapplied), closes the session, reports.
 - Promoting artifacts to `docs/` (via `export-*`) is **always** a later, explicit step outside this loop.

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).
@@ -54,6 +55,7 @@ The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roa
 # Plan PPP — <slug>
 
 > Derived from docs/specs/NNN-spec-<slug>.md · generated by plan-new-loop
+> Estado: open        ← plan-level machine state (open | done); plan-exec closes it
 
 ## Origin              source spec · prompt (bootstrapped via spec-new) · "adopted from <source>" + attribution (external plan — /w:plan-new mode 4 / /w:persist)
 ## Solution            the how (core): 1–2 summary sentences + the AS-IS → TO-BE
@@ -62,10 +64,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 +80,54 @@ 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.
+
+**Required — every phase, always:**
+
+```markdown
+### F1 — <result-oriented name>
+
+> Estado: pendiente
+
+**Resultado:** <the new verifiable state of the system>
+
+**Trabajo:**
+- [ ] T1.1 — <coherent unit of work>
+
+**Validación de fase:** <the primary proof that the promised state was reached>
+
+**Condición de salida:** <falsifiable result · contract preserved>
+```
+
+**Conditional — added to that block only when its own condition holds:**
+
+```markdown
+**Estado inicial:** <where the phase starts>
+**Recorrido afectado:** <consumer → components → current boundary>
+**Dependencias:** <phase(s) that must land first>
+**Límite de simulación:** antes <where it is> → después <where it lands, or removed>
+**Diferido:** <work consciously reserved for another phase>
+```
+
+- **Required**: `Resultado` · `Trabajo` · `Validación de fase` · `Condición de salida`, plus the `> Estado:` line.
+- **Conditional**: `Estado inicial` (when it is not obvious) · `Recorrido afectado` (distributed change) · `Dependencias` (the phase cannot run in direct sequence) · `Límite de simulación` (**only** when temporary behavior exists) · `Diferido` (only when work was consciously excluded).
+
+**A new phase never writes an empty conditional block.** No temporary behavior in the change → no `Límite de simulación` line at all; nothing consciously excluded → no `Diferido`. Writing the label with `no aplica` under it is the failure mode this split exists to prevent: it invites inventing a stub to justify the heading, and turns a contract into a form to fill in. The gates check the same way — an absent conditional block is not a gap (§ *Convergence / exit*).
+
+**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`.
+
+**The plan carries its own state, and it is a different axis.** One `> Estado:` line under the title, vocabulary `open` | `done`, born `open` with the plan; `plan-exec` writes `done` only after the final validation, adding a `> Cierre: YYYY-MM-DD · sesión NNN` line for the date and session (§ *Delta 6* there). `aw status` derives `plan_state` from that declaration **and** both counters: a `done` over open tasks or unvalidated phases reads `inconsistent`, and every phase `validada` with no closure reads `final_validation_pending` — still open. Position disambiguates the two marks: the plan-level one lives under the title, the phase-level one inside its `### Fn` block. *(Legacy: `> Estado: done — YYYY-MM-DD · sesión NNN` is still read; the next legitimate write normalizes it.)*
+
+**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 +137,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 +188,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 +203,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 +223,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,29 @@ 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 plan's own status mark. 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`.
+
+> **Normalize on write, never invent.** A save through this loop leaves the document on the current contract. The plan-level `> Estado:` line sits under the title — `open`, unless execution already closed it, and then with the date and session on their own `> Cierre:` line. Each `### Fn` carries its required blocks, and **no conditional block is written empty**: a phase with no temporary behavior gets no `Límite de simulación`, one with nothing excluded gets no `Diferido`. Normalizing is a rewrite of form — it never changes a phase's state, never ticks a box, and never closes a plan.
 
 ## 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 +95,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 +167,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 +179,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 +196,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.