@tacuchi/agent-workflow-cli 25.8.0 → 26.0.0

package/skills/w/loops/CHASSIS.md

@@ -1,8 +1,14 @@
 # CHASSIS — the loop engine
 
-The **common engine** of the Workline loops: every loop reads it from its `## Inherits`, **always, before its deltas**. Edit the engine **here**; heirs only reference it.
+The **common engine** of Workline loops: heirs read it before their deltas and only reference it.
 
-> **When each step below happens is no longer this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. They consume no model worker, subagent or external process: the CLI advances them locally to the first real frontier. What stays is what each rule is FOR — the half no engine carries. Answering the frontier it stops at is `aw flow submit`, and its envelope — which fields each kind of frontier demands, and where each digest comes from — is **read** with `aw flow --help`, never guessed.
+> **When:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. `aw flow submit` answers the frontier. Read its envelope and digest from `aw flow --help`, never guess. Use `--adopt` for an existing run; `aw flow recover` restores a no-effect exhausted frontier, `aw flow restart` handles stuck runs, `aw flow annul` reopens miscredited batches, and `aw flow prove` binds evidence to the checkout.
+
+## Host execution rules
+
+- Write JSON envelopes with the file tool, never heredoc or shell-built JSON; redirect the file to stdin.
+- Use a CLI verb before editing the runtime; make one call per approvable effect.
+- The user executes force-push; on Windows set `PYTHONUTF8=1` for Python consumers.
 
 ## Heirs (canonical list)
 
@@ -18,9 +24,9 @@ The two that edit code also apply [`CODE-POLICIES.md`](CODE-POLICIES.md).
 
 ## Persistent objective
 
-A loop **is a persistent objective**: it exists to fulfill the `SESSION.Objective` declared at start, and **it is not finished until the convergence gate confirms the objective was met**. Gap-driven iteration is the *method*; the artifacts are the *record*; the objective is the *frame*.
+A loop fulfills `SESSION.Objective` until its convergence gate confirms it. Gaps are the method; artifacts the record.
 
-"Don't stop until convergence" is sustained by the loop itself — its `repeat:` plus the convergence gate — never by a host hook, which is what makes it harness-agnostic.
+The loop's `repeat:` and gate sustain convergence, not a host hook.
 
 > **Inter-turn continuity.** The same `CHECKPOINT`+resume governs the **next prompt**: the objective persists **across turns**, not only within a run. Its canonical rules have their **single source** in [`../SKILL.md`](../SKILL.md) § *Operating context*; this engine executes them via *Compact / resume* (case 3).
 
@@ -125,11 +131,11 @@ Resume **keys off the `CHECKPOINT`** of the run's session, not the existence of
 ## Convergence / exit
 
 - **No material gaps** → **convergence gate** (read-only) = **`Success criteria` green** (*verification-first*). Whatever fails **comes back as a gap**; if it passes → the loop **flips the green criteria** in `SESSION.md` (`- [ ]` → `- [x]`) and offers its closing action. The checklist must reflect the real final state: a criterion left unchecked at `finalize` needs an explicit reason. Each heir names its own instance of this gate, and those instances are what realize it.
-- `Cerrar` (the `flow` control, at any time) → `finalize`, the last step of every journey. **`finalize` always persists `CHECKPOINT.md`** (resumable) and, **only if** something was deferred, writes `BACKLOG.md` (close reason + the deferred items); closes the session and reports. Progress survives even without a prior `Compactar`.
+- Finish sources → approve exact workspace paths/message or skip → `finalize` persists CHECKPOINT, deferred BACKLOG if needed, archive and HISTORY; an approved commit runs last, never push. `Cerrar` at any time uses `finalize` and preserves progress.
 
 ## docs/ boundary — no auto-export (hard rule)
 
-A loop writes into `docs/` **only** its own flow's doc plus, when it composes a capability whose own deliverable is a `docs/` category, that category — today only the **UI Design Package** under `docs/designs` (`design`). Which folders that is per flow, and refusing any delegated step whose target leaves them, is the CLI's. **Published, never graduated**: the test is the origin, not the folder. No loop **graduates/promotes artifacts** into `docs/` — migrations → `docs/scripts`, manuals → `docs/manuals`, diagrams → `docs/diagrams` are the separate **`export-*`** skills', an explicit later step; artifacts stay in their sessions until then. A task creating a tool has it documented in `docs/tools` by the ambient `creating-tools` skill (auto-discovered; Workline does not bind it).
+A loop writes into `docs/` **only** its own flow's doc plus, when it composes a capability whose own deliverable is a `docs/` category, that category — today only the **UI Design Package** under `docs/designs` (`design`). Which folders that is per flow, and refusing any delegated step whose target leaves them, is the CLI's. **Published, never graduated**: the test is the origin, not the folder. No loop **graduates/promotes artifacts** into `docs/` — migrations → `docs/scripts`, manuals → `docs/manuals`, diagrams → `docs/diagrams` are the separate **`export-*`** skills', an explicit later step; artifacts stay in their sessions until then. Reusable tooling follows the `docs/tools` contract and closing review; host help is optional.
 
 ## Conditional modules
 

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

@@ -6,19 +6,22 @@ closing-review invariants.
 
 ## Safe git — verified branch + proposed commits
 
-Sources are edited on a **verified** branch (`aw check-branch`), and the unit's commits are
-**proposed**: exactly one commit per affected source — at effective-batch close in plan-exec, at task
-close in quick — never `push`/`--amend`/`--no-verify`, and never a destructive clean or a branch
+Sources are edited on a **verified** branch (`aw check-branch`), and commits are
+**proposed**: in plan-exec the CLI commits only the batch's approved paths once per source; in quick
+the task closes with one proposed commit. Never `push`/`--amend`/`--no-verify`, a destructive clean or a branch
 switch without confirmation. A **rejected** commit leaves the changes in the tree and the unit
 recorded as uncommitted in `CHECKPOINT` and `BACKLOG`. Between units each working tree is clean or
 explicitly acknowledged; a `continuous` batch is the narrow exception that intentionally co-mingles
 its internal phases in one reviewed commit, and no batch may co-mingle with another.
 
-Concurrent flows never share a working tree: a run declares its sources and takes an **isolation
+Concurrent flows declare sources. By default a run takes an **isolation
 unit** in each before writing — a worktree on its own branch
 (`aw worktree ensure | list | release`). An edit outside is
 blocked naming the command that gets one, and at close `aw worktree integrate` merges each into
 the source's work branch; a conflict is reported, routed to `aw fix-git --path`, never alone.
+An in-place workspace declares `Modo de edición: in-place`; a plan may override it with `> Aislamiento: unidad`. In-place declares and approves only its own paths against the acquisition snapshot, without integration.
+
+For frontend sources, install dependencies (`npm ci` if the lockfile changes) inside each acquired unit: `node_modules` belongs to that worktree, never to a sibling checkout.
 
 > **When the branch is verified, when a commit becomes available and what an approval covers is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. Approving is the person's act and committing is a separate effect that comes back as the units' own git state — which is what makes "the checks passed" impossible to assert without having run them.
 
@@ -33,7 +36,7 @@ same gate before any pending commit.
 - **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; Workline does not bind it), which homes it under `docs/tools/<slug>/` per its contract. 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.
+- **Tooling check** (`docs/tools`): reusable support scripts/CLIs/generators/configs (not product code or session probes) belong under `docs/tools/<slug>/`, with README, run/output structure and an index row in `docs/tools/README.md`. Review their usability and evidence before closing. Any host help is optional, from any origin; its absence never defers the tool.
 - **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**: seed `CHECKPOINT.Next = "review <batch/task>"`; Success
   criteria require the whole diff to pass before commits.

package/skills/w/loops/README.md

@@ -47,11 +47,11 @@ The **5 loops** are heirs: they use `## Inherits` (a one-line reference to [`CHA
 
 ## Chassis / heirs
 
-The **engine lives in [`CHASSIS.md`](CHASSIS.md)** (a referenced doc, not a skill); the 5 loops — including `spec-refine-loop` — are **heirs** of that engine. The canonical heirs list and their deltas live in the chassis itself (§ *Heirs*). The chassis is **not a bindable capability**: it is the loop engine; what is pluggable are the **capabilities** a loop composes (e.g. `design`, `sql`, `git`), resolved via `.workflow/skills.toml`.
+The **engine lives in [`CHASSIS.md`](CHASSIS.md)** (a referenced doc, not a skill); all 5 loops inherit it. It is never a binding. The `design` capability has a Workline-owned floor; other assistance comes from the host when available.
 
 ## Composed capabilities (roles)
 
-Loops compose **capabilities by role**, never concrete skills; the skill fulfilling the role is resolved via `.workflow/skills.toml` (cascade: built-in → global → workspace; `off` = disabled — the loop continues and says so if it was needed). Catalog, defaults and ambient-conventions doctrine: [../roles/README.md](../roles/README.md).
+Only Workline-owned roles resolve through `.workflow/skills.toml`. External help is ambient; it is not a prerequisite, binding or gate proof. See [../roles/README.md](../roles/README.md).
 
 ## Index
 

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

@@ -111,8 +111,11 @@ reconciliation** in `CHECKPOINT`, never reported as published.
 
 ## Delta 1 — One session per run; execution-unit cycle in the plan-doc
 
+`aw flow advance --adopt` adopts an existing plan; `aw flow recover` restores exhausted no-effect frontiers, `aw flow restart` unsticks runs, `aw flow annul` reopens miscredited batches. `aw flow prove --source <alias>` supplies checkout-bound evidence to `aw flow submit` after validation.
+
 - Walk the plan's `### Fn` blocks under `## Tasks` in dependency order inside one session. Infer
   effective `continuous`/`isolated` batches first; legacy `## Phases` tables degrade the same way.
+- In-place `branch-precondition`: clean on another branch → offer switch, change document branch or cancel; dirty on another branch → pause; expected branch with user changes → proceed. Switch only with consent; the hook guards edits and the commit fences HEAD/branch against acquisition.
 - **Execution-unit cycle:** seed one batch intent; implement all its phases in order; validate and
   review at unit close; then update states/`CHECKPOINT` and enter Git. An isolated unit contains
   one phase. A continuous unit follows `PLAN-EXECUTION-BATCHES`: no proof, runner, build, lint,
@@ -123,7 +126,7 @@ reconciliation** in `CHECKPOINT`, never reported as published.
   **Never** because all its checkboxes are ticked.
 - **Intermediate states:** `bloqueada` = the phase is stopped on a live checkout blocker — recorded in `CHECKPOINT` + the plan's `## Open questions`, back to `en ejecución` when it clears; it counts as **not validated**. A proof that cannot run **stays `bloqueada`**. A deferred check never counts as a passed one. A script awaiting real-world application is a **handoff**, not a blocker: local fixture/ephemeral validation can still establish the promised behavior and the phase may become `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** in the checkout, never an operator's deployed run.
-- **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.
+- **Plan-doc residue (hard rule):** execution writes **only** checkbox flips (`- [ ]` → `- [x]`), phase `> Estado:` and `> Bloqueo:` while blocked, deferrals in `## Open questions`, and the plan's title-level `> Estado:`, `> Cierre:` and `> Assurance:` (CLI-sealed at close). Deltas 4, 5 and 7 permit declared gaps; consented normalization occurs before execution. Results, findings and metrics belong in session `DECISION`/`CHECKPOINT`, **never** the plan. Update phases **in place — NEVER append a duplicate `### Fn` block**.
 - **CHECKPOINT per execution unit:** record its effective grouping, functional states, simulation
   boundary when applicable, checks/results, decisions, deferrals and next intent. The task boxes
   and `en ejecución` marks preserve an intra-batch resume.
@@ -222,20 +225,22 @@ adds nothing of its own beyond running on a verified branch and never
   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.
+- **One vertical proof per operation**; don't repeat happy paths or test trivial mappers/DTOs.
 - `isolated` remains compatible with literal TDD. A continuous batch may author evidence before
   code, but first runs it at batch close. No phase becomes `validada` before its exit is demonstrated.
 - **Continuous means all checks at batch close.** Do not run its phase proofs, focused/risk tests,
   build, typecheck, lint or review while implementing internal phases. At close run proofs in phase
   order, then the justified checks and cross-cutting validations. `isolated` runs the same stack for
   its single phase.
-- 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). **What execution runs is the PLAN's evidence, never the spec's prose:** `plan-new` already derived those validations from the spec's acceptance criteria and its `## Scenarios`, so the spec is confirmed functionally **through** them. A criterion no validation covers is a gap of the plan, not a test to improvise here.
+- Review each test's value at close (`CODE-POLICIES.md`, `overtest`); over-testing is a finding to fix or justify, never an automatic rejection.
+- Run the plan's `## Validations` and `## Solution` Final behavior (legacy: `## Final behavior`). The PLAN's evidence, derived from spec criteria and scenarios, decides closure; a criterion without evidence is a plan gap.
 - A validation that **runs and fails** → back into the phase (gap): no advancing, no `validada`.
 
 - **SQL delivery**: validate the migration's behavior against a fixture or ephemeral database in the acquired checkout. The forward/rollback script is delivered through `SCRIPTS.sql` and `export-scripts`; a real application is an optional handoff and never keeps a phase or the plan open.
 
-> 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 local proof passes. For code and persistence these are checkout commands/tests; a script's real-world application is never a closing criterion.
+> **Final validation** is the convergence gate: `Success criteria` green on local checkout proof before `done`. A script's real-world application is never a closing criterion.
+
+For each code source, the final-validation directive names its required build and tests and whether each came from the plan's `## Validations` override or the source's versioned pipeline. A missing command leaves the gate open with the action to declare it in either place. Run both commands in the acquired checkout and return each command's real output as its own evidence; a test suite that did not run never counts. The final gate cannot be omitted by the adaptive route.
 
 ## Delta 5 — Closing review gate (conventions, pre-commit)
 
@@ -250,24 +255,23 @@ without subagents runs a clean re-read instead, and the closing report declares
 
 ## Delta 6 — Completion / close
 
-- A phase closes when its `> Estado:` reads `validada`: work done, exit condition true and proof
-  passed. In a continuous batch every phase waits for the batch review; an operative handoff leaves
-  the affected phase `bloqueada` and the unit uncommitted.
-- **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*).
+- A phase closes as `validada` only after its exit, proof and batch review pass. An operative handoff leaves it `bloqueada` and uncommitted.
+- Check each known outdated spec/plan line with `aw amend apply … --check` before closing; propose its path, edit only with approval.
+- **The plan stays `open` until final validation.** Every phase `validada` is **not** the plan closed; keep `> Estado: open` under the title (stamp it if absent); never write `done` from the counters (§ *Legacy plans degrade safely*).
 - **Every phase `validada` + final validation passed** unlocks completion, and the mark is written
   **after Git**: commit each unit, integrate it, and only then seal `done`. A run that isolates its
   writing holds commits that live on `aw/<session>` and nowhere else, so a `done` stamped before the
   merge would be true of no branch anybody reads.
 - **Integrating is part of closing, not a chore after it.** `aw worktree integrate --code <NNN>`
-  merges every unit of the session into its source's working branch, in alias order, one at a time
-  over the live branch — never a rebase, a force, a push or a silent branch switch. A **conflict is a
+  merges each unit into its sealed base, in alias order, over the live branch — never a rebase,
+  force, push or silent branch switch. A **conflict is a
   live state, not a failure**: the unit, its commits and the merge are kept, the receipt names the
-  plan, the source and the files, and `aw fix-git --path <source>` (`prepare` → `apply` →
+  plan, the source and the files, and `aw fix-git --path <reported merge path>` (`prepare` → `apply` →
   `commit --confirm`) resolves it; then integrate again to confirm and give the unit back. The plan
   is not `done` and the session does not close while a unit is still alive.
-- **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`).
+- **Marking done = ONE status line in the plan-doc** under the title: `> Estado: done`. The CLI seals `> Cierre:` with evidence of the run and `> Assurance: verified|partially_verified|unverified_accepted` on separate lines. Position distinguishes title from phase states; no per-phase result tables or suffixes (use 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-*`.
+- **No automatic export**: session artifacts stay there; only a later explicit `export-*` promotes them to `docs/`.
 
 ## Sequence
 
@@ -281,8 +285,6 @@ plan-exec-loop(PPP-plan-<slug>.md):
   batches = infer_effective_batches(pending phases, plan + live checkout)
       may merge/split declared rows without asking; legacy absence is allowed
       record batches + declaration drift in CHECKPOINT
-  commit_authorization = explicit conditional pre-authorization from the user, if any
-      record it before editing; otherwise approval is deferred to each green batch close
   for each Batch in batches:
     verify every affected source's branch; mismatch → stop + human
     seed CHECKPOINT.Next = Batch Bn (mode + phases + tasks)
@@ -306,16 +308,15 @@ plan-exec-loop(PPP-plan-<slug>.md):
     if any proof/check/review/exit condition is not green:
       preserve actual states + combined uncommitted diff; record unblocking action; stop
     set every Batch phase > Estado: validada; update CHECKPOINT
-    prepare exactly one commit per affected source, in its own isolation unit
-      pre-authorized → commit without another question
-      else → one consolidated approval for all source commits
-      rejected → changes stay; record "batch uncommitted"
+    propose one message and exact paths per changed source; show them for batch approval
+      approved → CLI commits those paths, verifies git and stores receipts before the next batch
+      Cerrar → persist the pending batch and its uncommitted changes
     if last Batch + final validation green:
       integrate: aw worktree integrate --code NNN            # every unit, alias order, live branch
-        conflict → keep unit + merge; report plan/source/files; aw fix-git --path <source>
+        conflict → keep unit + merge; report plan/source/files; aw fix-git --path <reported merge path>
                    (prepare → apply → commit --confirm) → integrate again → release
         refused (dirty checkout / off branch / uncommitted unit) → fix what it names; retry
-      then mark plan done: > Estado: done + > Cierre: YYYY-MM-DD · sesión NNN under the title (Delta 6)
+      then CLI seals plan: > Estado: done + > Cierre: run evidence + > Assurance: verdict (Delta 6)
     next-batch precondition: working trees clean or acknowledged
   if no Batch ran and phases are already validada:
     run final validation now; if green → same integrate-then-mark-done branch

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

@@ -52,38 +52,33 @@ Technical detail and roadmap stay inline:
 > Derived from docs/specs/NNN-spec-<slug>.md · generated by plan-new-loop
 > Estado: open
 > Límite de ejecución: checkout
+> Aislamiento: unidad
 
 ## Origin              source spec/prompt or adopted source + attribution
 ## Solution            AS-IS → TO-BE + "Final behavior" block (core)
 ## Impacted            sources (core)
-## Dependencies        docs · sources · DBs · sessions · inter-plan order (opt.)
-## Design references   the baselines this plan's roots pin (opt. — only with UI)
+## Dependencies        docs · sources · order (opt.)
+## Design references   the baselines this plan's roots pin (opt. — UI)
 ## Tasks               `### Fn` blocks: the ONLY source of phases (core)
 ## Execution batches   complete phase partition (core)
 ## Validations         proof (core)
 ## Implementation decisions  decisions, controls, risk (when used)
-## Risks / impact      technical risks and impacts (opt.)
-## Assumptions         delta over the spec only (opt.)
-## Open questions      pending; core when any exist; OMIT the section when empty
+## Risks / impact      risks, impact (opt.)
+## Assumptions         (opt.)
+## Handoff operativo   `- Pase a cert|prod: <corte>` (opt.; no boxes)
+## Open questions      pending; OMIT the section when empty
 ```
 
-Core sections always appear; optional ones only when warranted. Legacy readers tolerate the old
-separate sections, which new plans never write.
+Core sections are mandatory; optional ones need a cause. Legacy sections are read, never authored.
 
-> **Header, seal and evidence.** A plan born from the conversation carries
-> `> Standalone: <origen> · generated by plan-new-loop` instead of `> Derived from …` (fixed label, free
-> prose): it seals no baseline and its deviations go to the session, never to a contract note. With a
-> spec, the `> Baseline:` the CLI seals is a **functional** digest of it: an editorial edit leaves this
-> plan aligned, and a seal still reading one as divergent is re-sealed (`aw reseal`: `prepare` → `apply
-> --approval`, or a re-publication), never redesigned. `## Validations` **derives** from the spec's
-> acceptance criteria and `## Scenarios` — tests, evidence and commands live here, outcomes there.
+> **Header, seal and evidence.** Without a spec use `> Standalone: <origen> · generated by plan-new-loop`, no baseline; deviations stay in the session. Otherwise `> Derived from …` and CLI-sealed functional `> Baseline:` apply. Editorial drift calls for `aw reseal` (`prepare` → `apply --approval`) or re-publication. `## Validations` **derives** from the spec's acceptance criteria and `## Scenarios`: outcomes there, commands here.
 
 Batch syntax, inference and runtime semantics are defined once in
 [`PLAN-EXECUTION-BATCHES`](../../modules/PLAN-EXECUTION-BATCHES.md).
 
 ## Phase contract (canonical)
 
-A `### Fn` block is a **verifiable state of the system**, never a list of layers, files or classes.
+A `### Fn` is a **verifiable state of the system**, never a list of layers, files or classes.
 
 ```markdown
 ### F1 — <result-oriented name>
@@ -97,32 +92,27 @@ A `### Fn` block is a **verifiable state of the system**, never a list of layers
 **Condición de salida:** <falsifiable result · contract preserved>
 ```
 
-**Required**: `Resultado` · `Trabajo` · `Validación de fase` · `Condición de salida` · the state
-line · `Fuentes`. Every task declares `_(fuentes: …)_`, a phase subset (`workspace` or an exact
-`AGENTS.md > Fuentes` alias); `Impacted` never substitutes them. **Conditional**: `Estado inicial` when unclear · `Recorrido afectado` for a distributed
-change · `Dependencias` when direct sequence is insufficient · `Límite de simulación` (**only** when temporary behavior exists) · `Diferido` when work was consciously excluded.
-**A new phase never writes an empty conditional block.**
+**Required**: `Resultado`, `Trabajo`, `Validación de fase`, `Condición de salida`, state and `Fuentes`. Every task declares `_(fuentes: …)_` within its phase (`workspace` or `AGENTS.md > Fuentes`); `Impacted` is no substitute. **Conditional**: `Estado inicial` if unclear; `Recorrido afectado` if distributed; `Dependencias` if sequence is insufficient; `Límite de simulación` (**only** when temporary behavior exists); `Diferido` for excluded work. **A new phase never writes an empty conditional block.**
 
-**Checkout is the only closing surface**: proof is a local command, fixture, ephemeral DB or checkout
-inspection — a deployed host, product or remote read is research or a non-blocking `Handoff operativo`.
+**Preexisting failures (conditional):** only when observed, add
+`> Rojos previos: [{"file":"tests/x.test.ts","case":"suite > case"}]` inside the phase.
+Use exact runner file/full-case identifiers (JVM: class/method), no wildcards.
+`passed: true` then means no failures outside that list; unidentified failures still reject.
 
-**Phase state = machine state.** One bare `> Estado: <value>` line uses `pendiente` | `en ejecución`
-| `bloqueada` | `validada`. It is updated in place and counted
-**alongside — not instead of —** checkboxes. `validada` requires completed work, a true exit
-condition, its validation **ran and passed**, and a green review gate. **Never** because all its checkboxes are ticked.
-Legacy blocks have no line; a missing one reads `pendiente`, and nothing is back-filled.
+**Checkout is the only closing surface**: use local commands, fixtures, ephemeral DB or inspection; deployed hosts and remote reads are research or non-blocking `Handoff operativo`.
+
+**Phase state = machine state.** One bare `> Estado: <value>` line uses `pendiente` | `en ejecución` | `bloqueada` | `validada`. It is updated in place and counted **alongside — not instead of —** checkboxes. `validada` requires completed work, a true exit condition, its validation **ran and passed**, and a green review gate. **Never** because all its checkboxes are ticked. Legacy blocks have no line; a missing one reads `pendiente`, and nothing is back-filled.
 
 **The state line carries its value alone**; an annotated value reads as `pendiente`. A blocker
 uses its own `> Bloqueo: <reason>` line and the session records.
 
 **The plan carries its own state, and it is a different axis.** Its title-level value is `open` | `done`;
-only final validation writes `done` plus `> Cierre: YYYY-MM-DD · sesión NNN`.
+only the CLI seals `done`, `> Cierre:` (run evidence) and `> Assurance:` after final validation.
 Position disambiguates the two marks. `done` with open work is `inconsistent`; all phases green without
 closure is `final_validation_pending`.
 
-**Granularity is semantic, not mechanical.** A phase leaves a demonstrable state. A task is a
-coherent purpose and may touch many files; an edit operation is a **micro step**, never a plan
-entry. Size labels inform risk and scope; they never force a mechanical split.
+**Granularity is semantic, not mechanical.** Tasks express purposes across files.
+An edit is a **micro step**, not a task. Size informs risk, never forces splits.
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
@@ -149,6 +139,8 @@ Replaces the spec taxonomy with a planning one:
 
 > **Author the Solution the laziest-that-works way** (chassis § *Minimality*, generative side): reuse what the codebase/stdlib/platform already provides before adding abstractions, layers or dependencies — the gate then *confirms* minimality instead of repairing over-engineering.
 
+Final validation uses source pipelines. Override under `## Validations`: `- Validación final · \`<alias>\` · build \`<comando>\` · tests \`<comando>\``. Either command may be omitted. Alias must be a phase source, not `workspace`; each clause needs local proof.
+
 ## Delta 3 — What research investigates here
 
 Inline research maps affected code, AS-IS wiring and dependencies into `Solution`/`Impacted`.

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

@@ -29,7 +29,10 @@ This loop turns a plan into a sequence of **verifiable states of the system**. E
 
 > `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.
+This loop **applies** it and never redefines it: [`plan-new-loop`](../plan-new-loop/LOOP.md)
+§ *Phase contract (canonical)*, including conditional
+`> Rojos previos:` JSON file/case lists when failures are observed. Preserve exact identities;
+never add an empty list or waive unidentified failures. A `### Fn` demonstrates a system state.
 
 The plan's execution-unit interface is likewise defined once in
 [`PLAN-EXECUTION-BATCHES`](../../modules/PLAN-EXECUTION-BATCHES.md). This loop re-infers and
@@ -37,7 +40,8 @@ writes its complete phase partition; it never asks the human to choose an optimi
 can establish.
 
 ## Auxiliary / NOT mandatory
-`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.
+`plan-exec` runs **any executable plan**, refined or not. This optional loop incorporates changes
+before execution and repairs unexecutable structure in place.
 
 ## Started by
 `/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*).
@@ -137,6 +141,8 @@ This loop's instance of the chassis convergence gate — the same one `plan-exec
 - **Execution batches** — every phase appears once; maximal continuous ranges cross no decision, proof, handoff, irreversible action or required recovery boundary.
 - **Resumability** — tasks legible enough for a `CHECKPOINT`, intermediate states stable, pending work distinguishable from work already `validada`.
 
+The CLI alone seals `> Cierre:` with run evidence and `> Assurance:` after final validation; refinement only changes the plan's structure.
+
 ## Sequence
 
 ```

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

@@ -34,7 +34,7 @@ QUICK
 
 ## Internal session
 
-- **ALWAYS** creates a light session with descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` only if something is deferred). A single session. Research is **inline** inside it (`ANALYSIS-FILE`/`CONCLUSIONS` + read-only `SCRIPTS.sql` in its folder). **Exception:** an entry-gate escalation to SPEC creates no quick session — the run never comes to exist and the session is the `spec-refine-loop` one.
+- **ALWAYS** creates a light session with descriptor `<slug>-quick` → `NNN-<slug>-quick` (Type = `quick`, ≈ `exec`): `SESSION` · `DECISION` · `SCRIPTS.sql` · `CHECKPOINT` (+ `BACKLOG` only if something is deferred). Research stays **inline** (`ANALYSIS-FILE`/`CONCLUSIONS` + read-only `SCRIPTS.sql`). Escalation closes this session before SPEC continues.
 
 ## Inherits
 
@@ -42,7 +42,7 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 
 ## Composes
 
-`git` · `sql` (DB rule) · `research` (inline). Resolved via `.workflow/skills.toml`.
+Git safety, DB scripts-only and inline research are loop rules. Host-native help is optional and does not override them.
 
 ## QUICK delta — minimal ceremony
 
@@ -53,16 +53,16 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 - **Git and DB inline** (full policies in [`../CODE-POLICIES.md`](../CODE-POLICIES.md)): before editing, verify each source's expected branch (`aw check-branch`); **proposed** commit (approve first) — never `push`/`--amend`/`--no-verify`. The AI **never executes DML/DDL**: migrations are drafted into the session's `SCRIPTS.sql`; fixture/ephemeral checks are local proof and any remote read is research context, never closure.
 - **Fix preview, before executing**: declare the fix you are about to make — files to touch, intent, expected shape of the diff. It is **proportional**: one line for something trivial; approach, files and risks for something complex. Above the same signal threshold that fires the entry size gate (below), a person approves it (`Ejecutar tal cual` · `Ajustar el enfoque` · `Escalar a spec` → *Mid-loop escalation*). **Below the threshold there is no human stop**: the preview stays declared in the session and the task executes.
 - **One session. One commit** proposed at the end (only if there were code changes), **after the proportional closing review gate** ([`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Closing review gate*): diff re-read + ambient conventions; fix or defer; nothing reaches the commit unreviewed.
-- **Entry SIZE GATE** (before creating the session): a quick that should have been a spec costs more than the ceremony it saved, so the size of the objective is judged **before** anything exists. Your part is recognizing the signals; the threshold, its anti-duplicate search, the question and its options are the CLI's. A signal already resolved by *adopted context* is **not** a signal (chassis § *Adopted context*). A **resume** of an existing quick never re-fires it.
+- **Entry SIZE GATE** (before implementation): a quick that should have been a spec costs more than the ceremony it saved. Recognize the signals; the threshold, anti-duplicate search and alternatives are the CLI's. A signal resolved by *adopted context* is **not** a signal (chassis § *Adopted context*). A **resume** never re-fires the gate.
   - **`Recortar alcance`**, if chosen: propose the **sub-task that DOES fit** a quick (`SESSION.Objective` = the sub-task; the original prompt goes into `## Origin`) and defer the rest to `BACKLOG` ("trimmed at the gate — may warrant its own spec, `/w:spec-new`").
-  - **`Cambiar a SPEC`**, if chosen: **no quick session is created** — run the *Live transition to SPEC* (next bullet).
+  - **`Cambiar a SPEC`** closes the existing quick, preserving its request for *Live transition to SPEC*.
 - **Live transition to SPEC** (shared by the gate and mid-loop escalation). On acceptance, the work line **moves to the SPEC flow**: the explicit consent in the structured-choice **equals invoking the destination command** (*consented exception* — rule 3 of the *Continuity rule*, [`../../SKILL.md`](../../SKILL.md) § *Operating context*). On the SPEC side:
   1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs --publish spec-<slug>.md` with the finished draft on stdin (one atomic act: number assigned, document written, no reservation left), schema, single-pass **NO RESEARCH** — its bounded reconnaissance does **not** re-fire (this run's context arrives adopted). `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists). The draft is born `status: draft`: only the SPEC gate promotes it to `ready-for-plan`.
   2. **Load and execute** [`../spec-refine-loop/LOOP.md`](../spec-refine-loop/LOOP.md) — over that spec (trampoline pattern).
   3. The run's session is that loop's **normal** `NNN-<slug>-spec-refine` (the CLI numbers it; its `## Origin` records the escalation). **Invariant 2 intact**: quick, while it is quick, never writes `docs/` — the draft is written by the SPEC flow, post-consent.
 - **Mid-loop escalation + handoff**: if the task grows, declare the signals again — the CLI applies the same threshold and, if it fires, asks. If the user accepts moving up:
   1. **Any already-edited code stays** in the working tree (never reverted) and is **recorded** in `CHECKPOINT` + `BACKLOG`: "uncommitted changes in `<source>` — decide commit/discard on resume" (the "rejected commit" pattern of *Safe git*).
-  2. The quick session goes to `finalize` with the **pointer** in `BACKLOG`: to **PLAN** → "escalated to `docs/plans/PPP` — resume there" (**deferred**: seed + pointer, no live entry); to **SPEC** → "escalated to `docs/specs/NNN` — **continued live** (session `NNN-<slug>-spec-refine`)", or "escalated at the preview — continue in `/w:spec-new`" when no code and no `NNN` exist yet.
+  2. The CLI writes the escalation pointer in `BACKLOG` before closing the quick. **SPEC** continues through `/w:spec-new` with the preserved request; **PLAN** stays deferred (seed + pointer, no live entry).
   3. The artifacts (`DECISION`, `SCRIPTS.sql`) **stay in the quick session** as referenceable context, never migrated.
   4. **SPEC enters live**: after `finalize`, run the *Live transition to SPEC* (draft **only if no spec exists** for this objective; then the loop). **Asymmetry** intact: PLAN can **absorb** the progress (plan-exec picks up the existing working tree); SPEC **restarts** the design cycle and treats the half-done code as context/reference, never as ingested work.
 
@@ -71,7 +71,7 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
 ```
 quick-loop(prompt):
   # `Cambiar a SPEC` → live transition (see delta): draft (spec-new procedure) +
-  #                    load and execute ../spec-refine-loop/LOOP.md → END (no quick session)
+  #                    load ../spec-refine-loop/LOOP.md → END (quick closed by CLI)
   if the conversation already established analysis/conclusions →                 # adopted context (chassis)
     adopt them (SESSION.Origin = "adopted from host conversation"; reference in CONCLUSIONS) — never re-derive/re-ask
   author SESSION.Success criteria = the deliverable's check  # test(s) if code · short RATIFIED rubric if analysis/design
@@ -99,6 +99,7 @@ finalize: CHECKPOINT (AFTER: Pending→Completed) + BACKLOG (only if something i
 
 ## Convergence / exit
 
+- Before closing, run `aw amend apply … --check` for each spec/plan line known to be outdated. Propose its returned path; never edit without approval.
 - Closing review gate passed and commit proposed if there was code (or skipping it approved) → `Cerrar`.
 - `Cerrar`/`Compactar` (`flow` control) → persists `CHECKPOINT` + `BACKLOG` (resumable).
 - **No export**: nothing goes to `docs/` (§ *Writes*); escalating is the only way up.

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

@@ -75,7 +75,7 @@ The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*
 
 Other transversal capabilities the engine always uses: `research` (**inline** — chassis § *Research*), `sql` (DB rule inside research — chassis). All resolved by config; `off` → the loop continues without the capability and, if it was needed, says so or asks. The spec's **prose** follows the **ambient** writing conventions (the host auto-applies an installed writing skill if present), not a composed role.
 
-> **Ambient conventions (not roles):** code/testing/writing standards and `creating-tools` are standalone skills the host auto-discovers by `description` — Workline neither binds nor depends on them. Full doctrine: [../../roles/README.md](../../roles/README.md).
+> **Ambient conventions (not roles):** host help for code/testing/writing or tooling may come from any origin; Workline neither binds nor depends on it. Full doctrine: [../../roles/README.md](../../roles/README.md).
 
 ## Current-behavior baseline (brownfield first)
 

package/skills/w/modules/DESIGN-REFERENCES.md

@@ -23,16 +23,16 @@ identical for both, and the mode decides which task-pin form is legal.
   digest: `sha256:<64 hex>`
 ```
 
-A simple design's hint is its `DESIGN.md`.
+A simple design hints `DESIGN.md`; archiving its revision keeps the hint valid.
 
 - `package` pins **identity and revision**. `latest`, a folder slug, a bare
   `DES-001` or a title are rejected: each answers a different question next year.
-- `baseline_hint` is a **location hint**, never the identity. A renamed dossier
-  keeps the reference valid and reports the hint as stale.
+- `baseline_hint` is a **location hint**, never identity. A renamed dossier
+  warns stale; archiving a simple revision does not.
 - `digest` seals the exact bytes; one that no longer matches never resolves
   quietly.
-- Several designs are several blocks. One named in prose **without being pinned**
-  is reported, not ignored.
+- Several designs are several blocks. A bare id warns only if the plan pins or
+  attempts a reference; `DES-001@alias` always warns.
 
 **Never in the document**: Screen Specifications, flow graphs, state inventories,
 region or component tables, mockups, embedded images. Those live at their own
@@ -87,12 +87,10 @@ claim.
 
 ## quick — read it, never rewrite it
 
-`quick` **reads and validates** (`aw designs`, `aw designs --plan`); it changes
-nothing a baseline seals — normative content, a maturity, an approval. A tweak
-that needs a new state or a redrawn journey **escalates with the evidence it
-gathered**: `plan-refine` for the package, `spec-refine` when behavior or
-acceptance moves. Editing silently moves the revision while every consumer stays
-pinned to the old digest.
+`quick` **reads and validates** (`aw designs`, `aw designs --plan`); it never
+changes sealed content, maturity or approval. A new state or journey escalates with the
+evidence it gathered: `plan-refine` for the package, `spec-refine` when behavior
+or acceptance moves.
 
 ## plan-refine — the delta, and only the delta
 

package/skills/w/modules/PLAN-EXECUTION-BATCHES.md

@@ -57,9 +57,9 @@ action go to `CHECKPOINT`.
 
 ## Git authorization
 
-A green batch produces exactly one proposed commit per affected source. Approving is not committing,
-and a check that never ran is not a green batch. For the last pending batch the same approval also
-covers marking the fully validated plan `done`, so that final write rides in the source's single
-commit instead of asking a second time.
+A green batch proposes one message and exact paths per changed source. After its approval the CLI
+commits only those paths and verifies git before the next batch; approval alone is not a commit.
+No paths means no commit. `done` is sealed after git/integration in the workspace plan, not in a
+source commit; a later workspace-close commit may carry it. An unrun check is never green.
 
 > **What proves the batch was green is not this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document — positionally, behind the delegated validation and the review, neither of which a narration can pass.

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

@@ -14,6 +14,8 @@ Loaded when the run has to locate or name a session beyond creating its own (sig
 
 **Reopen to continue**: `aw session-resume --code <NNN> --reopen` reactivates a **closed** session (removes `.closed` → active) to keep working in it; without `--reopen`, resume is read-only. To detect the most recent closed one: `aw resume-summary --include-recent-closed` (or `aw sessions --state all`).
 
+**User-owned states:** only the person marks a session `paused` (`aw session-pause --code <NNN>`) or `abandoned` (`aw session-close --code <NNN> --abandon`). A loop never assigns either state by itself. `aw session-resume --code <NNN>` activates a paused session again; an abandoned one requires the person's explicit `--reopen`.
+
 ## When the durable record fails to update
 
 `aw session-close` also upserts the session's row in `.workflow/HISTORY.md` — the durable record, since `sessions/` is gitignored. That upsert is **non-fatal**: on `history_error` in its output, re-run `aw history-update --code <NNN> --state closed`. `aw session-artifacts` inspects what a session holds.