@tacuchi/agent-workflow-cli 20.17.0 → 20.21.0

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

@@ -1,5 +1,5 @@
 ---
-description: Use when the user wants to capture a NEW requirement, idea or wish as a spec — not to refine an existing draft (that's spec-refine). Generates a specification draft (docs/specs/NNN-spec-<slug>.md) from a prompt, in a single pass. Can split a multi-part prompt into several sibling specs (split gate). Step 1 of the SPEC flow; starts no loop.
+description: Use when the user wants to capture a NEW requirement, idea or wish as a spec — not to refine an existing draft (that's spec-refine). Generates a specification draft (docs/specs/NNN-spec-<slug>.md) from a prompt, in a single pass: a bounded reconnaissance of the workspace sources first, then the scope decision — one spec, or several sibling specs (split gate). Step 1 of the SPEC flow; starts no loop.
 argument-hint: <prompt with the requirement or idea>
 allowed-tools:
   [
@@ -13,35 +13,70 @@ allowed-tools:
 
 Generates `docs/specs/NNN-spec-<slug>.md` in a single pass from the prompt in `$ARGUMENTS`. Starts no loop.
 
-> ## ⛔ Single-pass — NO RESEARCH (hard rule)
+> ## ⛔ Single-pass — BOUNDED RECONNAISSANCE, NO DEEP RESEARCH (hard rule)
 >
-> This command **only paraphrases** the user's input into the draft schema. It is **one sequential pass**: read `$ARGUMENTS` → (split gate: at most ONE structured-choice — see § *Split gate (multi-spec)*) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
+> This command frames the user's input into the draft schema after a **single, bounded look** at the context. It is **one sequential pass**: read `$ARGUMENTS` → adopt what the conversation already settled → **reconnaissance** (see § *Bounded reconnaissance*) → scope hypothesis → (split gate: at most ONE structured-choice — see § *Split gate (multi-spec)*) → fill the sections → write the file(s). Nothing else. It must take **seconds, not minutes**.
 >
-> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, or deep code investigation — **even if the harness is in a maximum-effort/depth mode** (e.g. ultracode/max-effort in Claude Code).
+> **FORBIDDEN**, no exceptions: launching sub-agents/workflows (`Task`/`Agent`/`Workflow`), research sessions, web searches, following implementation chains, running code/tests/apps, querying databases — **even if the harness is in a maximum-effort/depth mode** (e.g. ultracode/max-effort in Claude Code).
 >
-> This **overrides** any mode or session instruction saying "run a workflow for every substantial task". Those modes do **not** apply to `spec-new`: this command overrides them. If a section is uncertain, **do not investigate it** — declare it under `## Open questions` or `## Assumptions` and move on.
+> This **overrides** any mode or session instruction saying "run a workflow for every substantial task". Those modes do **not** apply to `spec-new`: this command overrides them. If a section stays uncertain after the reconnaissance, **do not dig further** — declare it under `## Open questions` or `## Assumptions` and move on.
 >
 > Deep investigation (closing gaps, mapping code, querying DB, autonomous research) is **`spec-refine`** work, not this command's.
 
-With a raw user prompt, first run the **§ Split gate (multi-spec)** assessment (below): the split offer, if any, happens **before writing anything**. Then:
+With a raw user prompt, first run the **§ Bounded reconnaissance** pass, then the **§ Split gate (multi-spec)** assessment (both below): the split offer, if any, happens **before writing anything**. Then:
 
-1. Run `aw next-number docs/specs` (the only shell tool needed): it returns JSON — use the `next` field as `NNN`. This command builds the slug.
+1. Run `aw next-number docs/specs` (the only shell tool needed beyond the reconnaissance): it returns JSON — use the `next` field as `NNN`. This command builds the slug.
 2. Derive the `<slug>`: short kebab-case from the Requirement — only `[a-z0-9-]`, ≤ ~5 words / ≤ 40 chars.
-3. Create `docs/specs/NNN-spec-<slug>.md` paraphrasing `$ARGUMENTS` into the draft schema (below). Repo reading: optional and minimal (e.g. one file the user cited) — never a sweep or research. On an accepted split: repeat steps 1-3 per part, minting immediately before each write.
+3. Create `docs/specs/NNN-spec-<slug>.md` framing `$ARGUMENTS` into the draft schema (below); the reconnaissance findings land **only** where the filling notes allow. On an accepted split: repeat steps 1-3 per part, minting immediately before each write.
 4. Show the generated file(s) and the suggested next step (`/w:spec-refine docs/specs/NNN-spec-<slug>.md`).
 
+## Bounded reconnaissance
+
+A scope decision taken from the prompt alone mistakes **technical** boundaries for **functional** ones. So, before deciding, take **one** shallow look at the terrain — enough to form a reasonable hypothesis of the functional unit, never enough to answer how it will be built.
+
+**Scope:** it runs **only on a raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff). The reuse entries at the end of this file skip it: the quick escalation and the `persist` adoption arrive with their context **already established**, and adopting it is transcription, not reconnaissance (**NO RESEARCH** — chassis § *Adopted context*).
+
+One pass, in this order: **adopt** what the conversation already settled (never re-derive it), **identify** the candidate sources, **look** at their surface, **stop**.
+
+- **Sources allowed** (a permission, not an obligation to read them all):
+  - the workspace's registered sources — `aw sources --no-git`, or the `WORKSPACE` block;
+  - each candidate source's main instructions file, plus the head of its `README`;
+  - build manifests: `package.json`, `pom.xml`, `build.gradle`, `requirements.txt`, equivalents;
+  - a top-level directory listing per candidate source;
+  - one or two entry points the prompt itself names, plus a handful of search hits.
+- **Budget: ≤5 reads + ≤3 searches.** Read a whole file only when a head or a search will not do. The ceiling is a **cap, never a target**.
+- **Stop at the first of these:**
+  - the evidence already decides one spec vs sibling specs;
+  - the next question needs a deep technical chain;
+  - it would need running code, tests or services;
+  - it would need an external source that is not available;
+  - the remaining uncertainty does not block a first draft;
+  - the digging starts answering *how it will be built* instead of *what functional unit was asked for*.
+- **Never:** follow a full import/call chain, run anything, query a database, search the web, or open a source the prompt gives no reason to open.
+
+**Scope hypothesis (internal).** The pass ends in a short judgement: functional outcome · likely sources · apparent responsibility of each · coupling · independent acceptance · recommended shape · confidence. It is **reasoning, not an artifact** — never persisted, never printed verbatim. It exists so the cut is never intuitive but opaque; its only visible residue is what the filling notes admit.
+
+**Degrade safely.** A missing workspace, unreachable sources or contradictory evidence **never** block the command and **never** justify a speculative cut. Keep **one spec**, declare the assumption used, and record the uncertainty for `spec-refine`. Prefer the functional outcome the user declared over any inference drawn from the code.
+
 ## Split gate (multi-spec)
 
-Right after reading `$ARGUMENTS` and **before writing anything**, assess whether the prompt bundles **several independent requirements**. The gate fires **only on clear signals** (≥2 of: independent deliverables/goals · explicit enumeration of distinct features · different requested moments or order · unrelated subsystems); borderline → **one spec, no question**. It applies only to a **raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff); it **never fires** on the reuse entries below — the quick escalation and the `persist` adoption arrive already scoped to one objective.
+Right after the reconnaissance and **before writing anything**, assess whether the prompt bundles **several independent outcomes**. The unit is the **functional outcome**, not the technical boundary: distinct repos, a frontend/backend pair, several microservices, a migration plus the code it enables — all **secondary evidence**, never on their own a reason to divide.
+
+**Divide only when each part is a result that can be refined, accepted and planned on its own** — its own purpose, its own acceptance criteria, worth delivering even if the other part is dropped. The gate fires **only on clear signals** (≥2 of: independent deliverables/goals · explicit enumeration of distinct features · different requested moments or order · users or value that do not depend on each other). Borderline, or evidence too thin to tell → **one spec, no question**: the hypothesis goes to `## Assumptions` and the doubt to `## Open questions`. It applies only to a **raw user prompt** (direct invocation, or the `plan-new` mode-3 handoff); it **never fires** on the reuse entries below — the quick escalation and the `persist` adoption arrive already scoped to one objective.
 
-- **The offer** — the command's **only** interaction: **one** structured-choice (1 content question + the `flow` control; `Cerrar` = abort, nothing is written yet). The question body shows the proposed cut in the **user's language**: per part, a name + slug, a 1-line scope and the suggested order. Labels: `Dividir en varias specs` (recommended when the signals hold) | `Una sola spec`. A free-form answer adjusts the cut (merge/rename/drop parts); if one part remains, proceed as a single spec.
-- **On acceptance** — still single-pass, still **NO RESEARCH** (the cut is paraphrase of the prompt, never investigation): per part, mint with `aw next-number docs/specs` **immediately before each write**, then write that draft. Numbers come out consecutive, so every sibling path is known after the first mint.
+- **The offer** — the command's **only** interaction: **one** structured-choice (≤2 content questions + the `flow` control; `Cerrar` = abort, nothing is written yet). The question body shows the proposed cut in the **user's language**: per part, a name + slug, a 1-line scope and the suggested order. Labels: `Dividir en varias specs` (recommended when the signals hold) | `Una sola spec`. A free-form answer adjusts the cut (merge/rename/drop parts); if one part remains, proceed as a single spec.
+- **The second content question** is allowed **only** for a functional ambiguity with two incompatible readings that would change the number of specs (or leave the requested outcome unidentifiable). Anything smaller — confirming an observable technology, closing an implementation detail, raising confidence from medium to high — is **not** asked: it goes to `## Assumptions` or `## Open questions`.
+- **On acceptance** — still single-pass: the cut comes from the prompt plus the reconnaissance already done, never from a second look. Per part, mint with `aw next-number docs/specs` **immediately before each write**, then write that draft. Numbers come out consecutive, so every sibling path is known after the first mint.
 - **Sibling contract**: each `## Origin` records the shared prompt + `split (part i/N)` + the **siblings by path** + the suggested order; each `## Scope` Out points to the sibling that owns the excluded part. Cross-reference by path, never by bare number.
 - **Report**: list the N files and suggest the next step per spec (`/w:spec-refine` on the first — each sibling refines and plans at its own moment).
 
 ## Draft schema (`NNN-spec-<slug>.md`)
 
 ```markdown
+---
+status: draft
+---
+
 # Spec NNN — <slug>
 
 ## Origin            (opt.)
@@ -80,26 +115,29 @@ Assumed facts.
 Pending doubts. ← the spec-refine-loop closes them.
 ```
 
-> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Refinement decisions` (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md); the refine drops `Open questions` when it empties). Same skeleton: the draft and the refined spec share the order.
+> **`Open questions` goes last** — the refined spec **inserts before `Open questions`** `## UI spec` (if there is UI) + `## Decisions`, and may add `## Affected capabilities` / `## Behavioral changes` right after `Context` when the change touches behavior that already exists (refined schema in the [`spec-refine-loop`](../loops/spec-refine-loop/LOOP.md); the refine drops `Open questions` when it empties). Same skeleton: the draft and the refined spec share the order.
 
 **Filling notes:**
 
 - The draft's **content** is written in the **user's language** (the schema headings stay as-is).
 - No `Type` field — `plan-new` infers the how.
+- **`status: draft`** in the frontmatter is the draft's maturity mark. This command writes no other value: only the `spec-refine` gate promotes a spec to `ready-for-plan`.
 - `Scope` always carries `Out` (what stays out).
+- **Where the reconnaissance lands** — `Context`: the facts that place the request (sources apparently involved, a module's observed responsibility, the relevant technology), with **at most one path per component** as an anchor; never a technical inventory. `Assumptions`: the inferences that let the draft advance. `Open questions`: what would need walking the implementation, a human decision, or a source that is not available.
+- **The code found never widens `Scope`** and never becomes a requirement: **acceptance criteria derive from the user's intent**. The reconnaissance may lend the right vocabulary, name existing actors and boundaries, and avoid obvious contradictions. It must not invent behavior nobody asked for, turn a current technical decision into a user requirement, or impose an implementation as a criterion.
 - **Acceptance criteria = static testable criteria** (the "what"): `plan-exec` validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]` in the spec; the spec never mutates by execution, only by a re-refine.
 - **Scenarios = behavior made concrete** (uppercase GIVEN/WHEN/THEN/AND): draft them only when the prompt already describes behavior — deriving the rest is spec-refine work, not this command's. A scenario earns its place only when it adds GIVEN setup or edge semantics the criterion does not capture — **never restate a criterion 1:1**.
 - If **UI** is involved, mention it in `Requirement`/`Context`; the `## UI spec` is authored in `spec-refine` (via the `ui-design` capability). "UI unspecified" is a first-class refinement gap.
 - The **gaps** the loop detects = weak sections of the schema (vague Requirement, Scope without `Out`, untestable criteria, open questions, undeclared assumptions, contradictions) **+ UI unspecified** when the requirement involves UI.
 - Equivalent alternative: the user creates the draft by hand. Both paths produce the same `docs/specs/NNN-spec-<slug>.md`.
 
-> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft following **this same procedure** (steps 1-3: same schema, same NO RESEARCH single-pass hard rule), with `## Origin` = "escalated from `/w:quick`" + the original prompt. No need to type `/w:spec-new`: the consent in the structured-choice equals invoking it.
+> **Reuse by escalation:** the live escalation from `/w:quick` (see [`../loops/quick-loop/LOOP.md`](../loops/quick-loop/LOOP.md) § *QUICK delta*) materializes its draft following **this same procedure** (steps 1-3: same schema, same single-pass hard rule — with **NO RESEARCH** and no reconnaissance: the objective and its context arrive adopted), with `## Origin` = "escalated from `/w:quick`" + the original prompt. No need to type `/w:spec-new`: the consent in the structured-choice equals invoking it.
 >
-> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft with this same procedure, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass — adoption is transcription, not investigation (chassis § *Adopted context*).
+> **Reuse by adoption:** [`/w:persist`](persist.md) (requirement-shaped content) materializes its spec draft with this same procedure, with `## Origin` = "adopted from host conversation" + attribution. Paraphrasing conclusions **already established in this conversation** is still single-pass, and needs no reconnaissance — adoption is transcription, not investigation (chassis § *Adopted context*).
 
 ## Plan mode
 
-Resolves `NNN` by reading `docs/specs/`, describes the draft(s) it would generate — split gate included: it reports the proposed cut — without writing any file.
+Resolves `NNN` by reading `docs/specs/`, runs the same bounded reconnaissance (read-only in either mode) and describes the draft(s) it would generate — split gate included: it reports the proposed cut — without writing any file.
 
 ## Resources
 

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

@@ -1,5 +1,5 @@
 ---
-description: Use when a spec draft exists and needs disambiguating or completing before planning (close open questions, sharpen criteria) — not for the first draft (that's spec-new). Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (from spec-new, hand-written, or the quick escalation). Updates it in place.
+description: Use when a spec draft exists and needs disambiguating or completing before planning (close the blocking functional gaps, sharpen criteria, hand the technical ones to PLAN) — not for the first draft (that's spec-new). Starts or resumes the specification refinement loop (spec-refine-loop). Input: docs/specs/NNN-spec-<slug>.md (from spec-new, hand-written, or the quick escalation). Updates it in place and marks it status: ready-for-plan.
 argument-hint: <docs/specs/NNN-spec-<slug>.md>
 allowed-tools:
   [
@@ -12,14 +12,15 @@ allowed-tools:
 
 # spec-refine — trampoline to the refinement loop
 
-This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes gaps and produces the refined spec.
+This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes the blocking gaps and leaves the spec ready for planning.
 
 > **Hard floor — applies even if you read nothing beyond this file:**
 >
 > 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-spec-refine --objetivo "<one-line objective>"`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next`; `## Open questions` only while live doubts exist).
 > 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
-> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation); nothing else lands in `docs/`.
+> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation), stamping the spec's frontmatter `status: ready-for-plan` on save; nothing else lands in `docs/`.
 > 4. **Language** — everything user-facing (questions, option labels, the doc's content) goes in the **user's language**.
+> 5. **Converge, do not close everything** — the target is `ready-for-plan`, not a spec without unknowns: close what can change **what** gets built; hand architecture and implementation questions to `PLAN`, recorded in `## Open questions` with their destination.
 
 ## Run the loop
 
@@ -36,10 +37,10 @@ The skill detects prior state before starting, **keying off the `CHECKPOINT`** (
 
 1. Find the spec's refinement session under `.workflow/sessions/` and its `CHECKPOINT.md`.
 2. **In progress** (a CHECKPOINT exists) → continue from the recorded progress (resolved gaps, Q&A).
-3. **No progress** (no CHECKPOINT and the spec does **not** have `## Refinement decisions`) → start from zero reading the spec (`NNN-spec*.md`).
-4. **Already refined / re-refine on demand** (no open CHECKPOINT but the spec **already has** that section) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **spec itself**; on `Guardar`, edits in place with confirmation.
+3. **No progress** (no CHECKPOINT and the spec is not `status: ready-for-plan`) → start from zero reading the spec (`NNN-spec*.md`).
+4. **Already ready / re-refine on demand** (no open CHECKPOINT but the spec **already declares** `status: ready-for-plan`) → **first-class operation**: while the flow stays in SPEC you can re-run this command over the same spec **as many times as needed** (new requirements, scope changes, re-reads). The loop does `create_or_resume` — it locates the existing refine session (even closed) and **reopens** it instead of duplicating — and re-refines reading the **spec itself**; on `Guardar`, edits in place with confirmation.
 
-> **Compat (legacy):** the `NNN-spec*.md` glob also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs. Re-running spec-refine edits them in place from then on.
+> **Compat (legacy):** a spec with no frontmatter that carries `## Refinement decisions` (or the older `## Q&A traceability`) counts as ready — case 4 — but the mark does **not** exempt it from the gate: the re-refine runs it in full and, on `Guardar`, renames that section to `## Decisions` in the same write that stamps `status`. The `NNN-spec*.md` glob also catches old `NNN-spec.md` / `NNN-spec-refined.md` specs; re-running spec-refine edits them in place from then on.
 
 ## Plan mode
 

package/skills/w/commands/status.md

@@ -17,26 +17,31 @@ Shows, simple and direct, the workspace state grouped as **Done / Missing / Disc
 1. Run `aw status` (returns JSON; backed by `status-service`).
 2. Render a readable summary from the JSON — do **not** show the raw JSON. Use the `relative` field verbatim (it comes pre-humanized in the user's language — Spanish). Head it with `workspace.name`.
 3. Group into three blocks (the dashboard is user-facing → render it in the user's language; the canonical Spanish labels below):
-   - `▸ HECHO` — specs with `refined: true`; plans with their progress (`tasks_done`/`tasks_total`, `progress_pct`); `closed` sessions.
-   - `▸ FALTA` — `active` sessions; plans with pending tasks (`tasks_total − tasks_done`); specs with `open_questions > 0`.
+   - `▸ HECHO` — specs whose `status` is `ready-for-plan` (the JSON keeps `refined: true` as its boolean mirror); plans with their progress (`tasks_done`/`tasks_total`, `progress_pct`) **and** their validated phases (`phases_validated`/`phases_total`); `closed` sessions.
+   - `▸ FALTA` — `active` sessions; plans with pending tasks (`tasks_total − tasks_done`) or phases still to validate (`phases_total − phases_validated`); specs whose `status` is `draft` or `refining`; specs with `open_questions > 0`.
    - `▸ DESCARTÓ` — every item in `discarded[]` (`kind: deferred` = deferred in BACKLOG; `kind: excluded` = excluded in CHECKPOINT), with its `text`.
 4. Every line ends with its relative date after ` · ` (e.g. `· ayer en la mañana`). An empty section shows `— (nada)`. Never invent data not present in the JSON.
 5. If `workspace.initialized` is `false` and everything is empty → say the folder is not an agent-workflow workspace (no `.workflow/`) and suggest `/w:workspace-init`.
 6. **Host context (opportunistic, read-only).** After the dashboard, if the host exposes *cheap* host-memory (see [`../harness/HARNESS.md`](../harness/HARNESS.md) § *host-memory* — e.g. the auto-memory `MEMORY.md` on Claude Code), append a `▸ CONTEXTO DEL HOST` section with a few signals of recent focus relevant to this workspace. If there is no cheap host memory, **omit the section silently**. Never run an expensive transcript scan here and **never ask** — this is a read-only dashboard; the enrichment is additive and must not slow the default output.
 
+> **Checkboxes measure work; phases measure state.** `progress_pct` stays checkbox-derived — it never reads the phase marks. A validated phase (`> Estado: validada` in the plan-doc) is the real signal of functional state, so a plan at 100% with `phases_validated: 0` is **work implemented, not validated**: report it in both blocks and say so. A `bloqueada` phase is that same gap made explicit — every box ticked, its verification still pending — and belongs in both blocks too: the work under `▸ HECHO`, the phase under `▸ FALTA` with what it waits on (its `> Bloqueo:` line). `phases_total: 0` means a legacy plan with no phase marks — show only its checkbox progress, never a `0/0`.
+
+> **The frontmatter governs spec maturity.** The spec's `status` (`draft` | `refining` | `ready-for-plan`) is the primary source, and readiness is never inferred from a section the spec happens to carry. A `status` that is absent, empty or unknown reads `draft` and the spec is reported as pending; only a spec with **no frontmatter at all** falls back to the two legacy marks (`## Refinement decisions`, `## Q&A traceability`).
+
 Suggested format (plain text; user-facing labels in Spanish):
 
 ```
 Workspace: <name>
 
 ▸ HECHO
-  • plan <slug> — <done>/<total> tareas (<pct>%) · <relative>
-  • spec <slug> — refinado · <relative>
+  • plan <slug> — <done>/<total> tareas (<pct>%) · <validadas>/<fases> fases validadas · <relative>
+  • spec <slug> — lista para plan · <relative>
   • <folder> (<type>) — cerrada · <relative>
 
 ▸ FALTA
   • <folder> (<type>) — activa · <relative>
-  • plan <slug> — <pendientes> tareas pendientes
+  • plan <slug> — <pendientes> tareas pendientes · <sin validar> fases sin validar
+  • spec <slug> — borrador · <relative>
   • spec <slug> — <n> preguntas abiertas
 
 ▸ DESCARTÓ

package/skills/w/loops/CHASSIS.md

@@ -125,7 +125,7 @@ The host is not only the loop's executor — it is a legitimate **producer** of
 
 Investigation is **inline**: an activity **inside the run's current session**, never a separate session. It writes its artifacts (`ANALYSIS-FILE` → `CONCLUSIONS`, + read-only `SCRIPTS.sql` if it queries DB) into the **session's own folder**.
 
-- **Autonomous**: the AI investigates inline and reports **without asking permission**. The human learns of it at integration time (in the flow's decision record — e.g. `## Refinement decisions` in the refine loops, `DECISION` in the code-editing ones) and keeps control via the `flow` control.
+- **Autonomous**: the AI investigates inline and reports **without asking permission**. The human learns of it at integration time (in the flow's decision record — each heir names its own) and keeps control via the `flow` control.
 - **Scope**: the current conversation (*adopted context* — settled conclusions are reused, never re-derived) + workspace + associated repos (sources) + DB MCPs.
 - **DB rule** (the single exception to autonomy):
   1. **MCP choice**: if the gap needs DB and there is **>1 candidate MCP with no configured default**, the AI asks which one to use. That question goes through the **same structured-choice** as a **content question** (counts inside the ≤3 + `flow` limit), **before** running queries. A single MCP or a default → no question.
@@ -133,7 +133,7 @@ Investigation is **inline**: an activity **inside the run's current session**, n
   3. Execute them **read-only** via MCP (respect `sql-mutation-guard`: never DML/DDL).
 - **Inconclusive research** (DB unavailable, insufficient evidence, unresolvable factual gap):
   - The investigation closes with status **`inconclusive`** in `CONCLUSIONS` and reports why.
-  - The loop **degrades** the gap: to a **human question** (next batch → the flow's Q&A record: a `Q:` entry in `## Refinement decisions` in refine loops, `DECISION` in code-editing ones) or, failing that, **defers** it to the flow doc's `## Open questions` (spec/plan) — or the session's `BACKLOG` when the flow has no doc (quick).
+  - The loop **degrades** the gap: to a **human question** (next batch → the flow's decision record) or, failing that, **defers** it to the flow doc's `## Open questions` (spec/plan) — or the session's `BACKLOG` when the flow has no doc (quick).
   - The gap is marked **"already tried via research"** (`attempts[gap]++`, `MAX` cap) so `detect_gaps` does **not** re-fire it in a loop → guarantees convergence.
 
 ## Proof of concept (probe)
@@ -169,7 +169,7 @@ Resume **keys off the `CHECKPOINT`** of the run's session, not the existence of
 2. **No progress** (no CHECKPOINT and the input doc does **not** have the flow's prior-work mark) → start from zero reading the input doc (plus any *adopted context* — settled in-conversation conclusions are input, not something to re-derive).
 3. **Already converged / re-run on demand** (no open CHECKPOINT but the doc **already has** the mark) → **first-class operation**: while the flow stays in its stage, re-running the command over the same input **as many times as needed** is supported. `create_or_resume` finds the existing session — typically **closed** after convergence — by descriptor + `## Origin` and **reopens** it (see *Internal sessions*: detection via `aw sessions --state all` / `aw resume-summary --include-recent-closed`, reopening via `aw session-resume --code <NNN> --reopen`); incremental work reading the **doc itself**.
 
-> Each heir defines its **prior-work mark**: in the refine loops, the presence of `## Refinement decisions` in the doc (legacy docs may also carry `## Q&A traceability`); in plan-exec, the plan-doc's `- [x]` checkboxes; quick has no doc (resume by CHECKPOINT only).
+> Each heir defines its **prior-work mark** and its own legacy tolerances: spec-refine keys off the spec's frontmatter `status`; plan-refine off `## Refinement decisions` in the plan; plan-exec off the plan-doc's `- [x]` checkboxes; quick has no doc (resume by CHECKPOINT only).
 
 > **`Compactar`** (the `flow` control, across all 3 cases) → write `CHECKPOINT.md` in the session (in-flight progress, remaining gaps, Q&A, `attempts`) → trigger the harness **compaction** (Claude Code: `/compact`; see [`../harness/HARNESS.md`](../harness/HARNESS.md)) → resume by reading the checkpoint.
 

package/skills/w/loops/CODE-POLICIES.md

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

package/skills/w/loops/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,55 @@ 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, journey or simulation boundary are missing. 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.
+
+> 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`.
+- **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, on close, the single plan status 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 +111,30 @@ 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`.
+- **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 line in the plan-doc**, under the title's blockquote: `> Estado: done — YYYY-MM-DD · sesión NNN`, updated in place on a re-run. 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`).
 - **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 +150,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 → ONE status line under the title blockquote (Delta 6), updated in place
+  else: the plan stays open → CHECKPOINT.Next = run the pending validation of the blocked 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.