@tacuchi/agent-workflow-cli 25.7.0 → 25.9.0

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
 
@@ -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/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.

package/skills/w/roles/design/CONTRACT.md

@@ -12,11 +12,18 @@ This file is what a person or a loop reads.
 
 ```
 aw capability prepare  --capability design --operation <op> [--input k=v ...]
-aw capability continue                                       # stdin: {"parent": <request>}
-aw capability validate                                       # stdin: {"request": …, "answer": …}
-aw capability apply --approval <digest>                      # stdin: {"request": …, "plan": …}
+aw capability continue --capability design --operation <op> [--input k=v ...] # stdin: {"parent": <request>}
+aw capability validate --capability design --operation <op> [--input k=v ...] # stdin: {"request": …, "answer": …}
+aw capability apply --capability design --operation <op> [--input k=v ...] --approval <plan.proposal.digest> # stdin: {"request": …, "plan": …, "pin": …}
 ```
 
+Repeat the same `--capability`, `--operation`, every `--input` and
+`--consumer-document` (if used) at each stage. Carry the response as one JSON
+object on stdin; `prepare` reads no stdin and `pin` is optional. Approval is the
+digest of `plan.proposal.digest`. Read `aw capability --help` for the full envelope.
+Shared wrappers have no host binding: if `aw harness` returns `unknown`, pass
+`--host <id>` at every stage.
+
 The verbs are **stages**, never operations: the operation travels in the
 envelope. Every attempt returns `outcome`, `output` and `receipt`. A
 `needs_input` is answered with `continue`, which builds the NEXT attempt of the
@@ -61,7 +68,7 @@ closed to five — one is enough:
 | `design.independent-outcomes` | two or more results each worth delivering | agent |
 | `design.functional-blocking` | an unclosed functional decision blocks the design | agent |
 | `design.clarity-lost` | one document would stop being readable | agent |
-| `design.governance-or-system-reuse` | the package already carries governance or several revisions | **CLI derives** |
+| `design.governance-or-system-reuse` | a **package** already carries governance or several revisions | **CLI derives** |
 | `design.special-source-or-effect` | a sensitive source, an external transmission, or a declared source that did not contribute | **CLI derives** |
 
 Recognizing a semantic signal is judgment and travels as `--input expansion=<id>`;
@@ -70,9 +77,11 @@ refused rather than believed. The receipt carries the mode, the signals that fir
 and the one-line cause — every artifact beyond the simple document traces back to
 the need it covers. `render` and `record` are package operations regardless.
 
-Publishing a second simple revision archives the outgoing bytes inside the same
-approved proposal, so a reference pinned to `@r1` keeps resolving after `@r2`
-lands: a published revision is never taken away by the next one.
+Publishing each successive simple revision (including the third and later ones)
+archives the outgoing bytes inside the same approved proposal. The manifest stays
+`simple`, and a reference pinned to an older revision keeps resolving. An update
+that requires package-only behavior names its expansion signal and refuses the
+conversion instead of changing the published mode.
 
 ## Evidence and lifecycle inside a package
 

package/skills/w/roles/design/ROLE.md

@@ -106,7 +106,7 @@ sections admit no such claim.
 | | `flow` (`workline.ui-flow/v1`) | `screen` (`workline.ui-screen/v1`) |
 |---|---|---|
 | Answers | how the journey runs | what one surface is |
-| Frontmatter core | `actors`, `entry`, `nodes`, `edges` | `default_state`, `states[]`, `flow_refs`, `dependencies` |
+| Frontmatter core | `actors`, `entry`, `nodes`, `edges` | `default_state`, `states[]`, `flow_refs`, optional `screen_refs`, `dependencies` |
 | Sections | Goal and outcome · Preconditions and entry · Main journey · Alternatives and recovery · Permissions and privacy · Traceability | Purpose and context · Structure and content · Components and design-system deltas · Data, permissions and validation · States and transitions · Interaction and navigation · Responsive and adaptation · Localization · Accessibility · Edge cases and degradation · Traceability |
 | Essential (no waiver) | Goal and outcome · Main journey · Traceability | Purpose and context · Structure and content · States and transitions · Interaction and navigation · Accessibility · Traceability |
 
@@ -115,7 +115,9 @@ sections admit no such claim.
 `DES-001/SCR-001@r2#error` — package / artifact @ revision # state anchor. A
 reference always pins the revision: **a later revision never invalidates a
 reference already fixed**. Baselines are cited as `DES-001@r2` plus the digest
-that seals them.
+that seals them. A screen may declare `screen_refs: [DES-001/SCR-002@r1]`
+to cite another screen or its state (`DES-001/SCR-002@r1#empty`). It does not
+extend the package closure, just like `flow_refs`.
 
 ### Maturity: `outline` → `handoff`
 

package/skills/w/roles/git/ROLE.md

@@ -20,6 +20,8 @@ description: >-
 
 Operate git in a **safe, controlled** way: verify the expected branch before editing, **propose** commits per source, and never run destructive or publishing operations without the user's explicit request.
 
+Use `aw git-flow` for per-source development/QA/production flows; preview and request approval before an effect. A force-push is always performed by the user.
+
 ## Composed by
 
 - **`plan-exec-loop`** — verifies the branch before each edit; proposes commits on close/checkpoint.
@@ -50,19 +52,24 @@ And **always** forbidden, even when the user asks for a commit: `--no-verify` (r
 
 ### Branch verification (before editing)
 
-The expected branch is **never assumed from the current branch** — the user may have switched it by hand. Verify against the flow's own line of work before any `Write/Edit`: its isolation unit's branch when the source has units (`aw worktree`), the source's declared work branch when it has none.
+The expected branch is **never assumed from the current branch** — the user may have switched it by hand. Verify before any `Write/Edit`: the session's isolation unit branch when it owns a unit (`aw worktree`); otherwise its document's own, inherited, or registered work branch (in that order). An unrelated unit does not block a document editing the shared checkout in its expected branch.
 
-**Primary mechanism**: `aw check-branch --source <alias>` (or `--file <path-of-the-imminent-edit>`; `--strict` returns exit 2 on mismatch — useful as a gate). It returns the per-source fields already computed: `alias`, `path`, `main_branch` (base), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (uncommitted changes). **Fallback** (loose repo without workspace/CLI): compute them with direct read-only git (`git branch --show-current` + `git status --porcelain`) plus the session's declared branch.
+**Primary mechanism**: `aw check-branch --source <alias>` (or `--file <path-of-the-imminent-edit>`; `--strict` returns exit 2 on mismatch — useful as a gate). It returns the per-source fields already computed: `alias`, `path`, `main_branch` (base), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (uncommitted changes). **Fallback** (loose repo without workspace/CLI): compute them in the source checkout with `git -C <ruta-de-la-fuente> branch --show-current` and `git -C <ruta-de-la-fuente> status --porcelain` plus the session's declared branch. The hub's branch is never a proxy for a source's branch.
 
 Cases:
 
 - **`match=true`** → OK, edit.
-- **`match=false, dirty=false`** (Case A — different branch, clean repo) → *structured-choice*: `git checkout <expected>` / keep current and update the session's expectation / cancel.
+- **`match=false, dirty=false`** (Case A — different branch, clean repo) → *structured-choice*: `git checkout <expected>` / confirm `aw doc-branch set --doc <tipo:NNN> --source <alias> --rama <actual>` to use the current branch for this document / cancel.
 - **`match=false, dirty=true`** (Case B — different branch + uncommitted changes) → **pause and wait for manual resolution**. Never propose checkout (it could lose work). Ask the user to commit/stash/discard and to say when to continue.
-- **Cross-source (hub)**: if the touched sources point to different branches without declaring it, **hard gate** — block progress with *structured-choice* (align all / declare the divergence explicitly / cancel).
+- **In-place, match=true with user changes** → proceed; declare only run-owned paths against the acquisition snapshot. `branch-check` rejects development and the commit fences branch and HEAD. Never switch branches without consent.
+- **Cross-source (hub)**: `aw sources --code <NNN>` checks each source against its own expected branch; different branch names are fine when every source matches. Pause only the divergent sources.
 - **Detached HEAD** → treat as Case A.
 - **Source outside git** (`is_repo=false`) → report, do not block.
 
+To request a document branch, first run `aw doc-branch show --code <NNN>` (or `--doc <tipo:NNN>`), ask the person to confirm or change its proposed name, then run `aw doc-branch set --code <NNN> --source <alias> --rama <nombre>`. No branch is registered just by showing a proposal.
+
+Closing, releasing or reclaiming a unit preserves the document branch and its base. A later cleanup may remove only an `aw/*` unit branch already contained in that base (decision `S049/AC-10`); it never deletes either protected branch.
+
 ### Commits — propose-then-execute, one source at a time
 
 On any commit request or trigger (loop close, "commit this", "save the changes"):
@@ -99,11 +106,11 @@ Autonomous `git merge` is forbidden (above), **but** resolving an **in-progress*
 
 **The mechanics live in the CLI** (`aw fix-git prepare | apply | commit`); what follows is the reasoning it expects from you. Never edit a conflicted file, `git add` or `git commit` by hand here — see [`../../commands/fix-git.md`](../../commands/fix-git.md) for the exact invocations.
 
-1. **Detect + identify**: `aw fix-git prepare` (read-only) returns the merge direction (**theirs → ours**), the conflicted paths and, per path, its three index stages with their blob hashes. `aw merge-state` remains the lighter inspector when you only need the state.
-2. **Analyze each conflict's intent** **before** resolving — never pick a side blindly. The request already carries the three versions: `base` (common ancestor), `ours` (destination) and `theirs` (origin). Add `git log --merge -p -- <file>` when the *why* of a hunk is not evident, and read the surrounding code for coherence.
-3. **Resolve** by composing the complete resolved file: pick **ours**, **theirs**, **combine** both intents, or **rewrite** to satisfy both — with no `<<<<<<<` / `=======` / `>>>>>>>` left. The CLI writes and stages it; a leftover marker is rejected, and so is a path that is no longer in conflict.
-4. **Ask** (*structured-choice*) when the intent is **ambiguous** or both sides are **incoherent** with each other (not combinable without losing something): answer `state: "ambiguous"` so nothing is written, then ask one content question per doubtful file/hunk (≤3 + `flow` control), options "Ours (`<destination>`)" / "Theirs (`<origin>`)" / "Combine" / "Edit manually". **Never invent** a resolution under real doubt. A **binary** conflict is never resolved automatically: propose `git checkout --ours|--theirs`.
-5. **Proposed commit**: completing the merge is a `git commit` (the merge commit) → **propose-then-execute** like any commit (canonical format above; outside a session → 1 line without the `session<NNN>` tag; never `--no-verify`/`--amend`/`push`). It is a **separate, confirmed** invocation — `aw fix-git commit --message "<msg>" --confirm` — which refuses while any file stays unmerged. The `git-commit-advisor` hook gates it.
+1. **Detect + identify**: `aw merge-state` reports unreadable sources and units, never "no merge" when they could not be inspected. `aw fix-git prepare` (read-only) summarizes each conflict's path, `kind`, binary, bytes, EOL, allowed resolutions and max bytes; it warns about multiple merge bases (virtual base). It seals the index-stage hashes but does not ship the full contents by default. Repeat `--show <path>` for each file whose three versions are needed. `--adapt <path>` includes a tracked file merged cleanly but needing a semantic adjustment, including after all conflicts were resolved while MERGE_HEAD remains.
+2. **Analyze intent** before resolving — never pick a side blindly. With `--show` read `base` (ancestor), `ours` (destination), `theirs` (origin). Add `git log --merge -p -- <file>` when the *why* of a hunk is not evident, and read adjacent code for coherence.
+3. **Resolve** with a complete text `{path,content}` without conflict markers, or a `resolution` `{path,choice}` where `choice` is `ours`, `theirs` or `delete`. A binary takes the intact `ours`/`theirs` blob via the CLI; absent stage → `delete`. Apply a subset and repeat prepare/apply for the remaining files. The CLI updates the index with Git plumbing and checks out with repo attributes/EOL, with no hand-run `git add` or `git checkout`.
+4. **Ask** (*structured-choice*) when intent is ambiguous or both sides are incoherent: answer `state: "ambiguous"`, ask one content question per doubtful file/hunk (≤3 + `flow` control), with consequences for each option. Never guess. A binary is not an exception to the intent rule — choosing `ours`/`theirs` still needs evidence.
+5. **Proposed commit**: `aw fix-git commit --message "<msg>"` without `--confirm` previews the message, build, included files and `left_out`. After approval repeat with `--confirm` and a **long host timeout**: it runs the versioned source build in the merge repo and refuses failed/undeclared builds or unmerged files. `ninguno` or `--skip-build "<motivo>"` is explicit and visible with its origin; the result also warns if build ran on a tree different from the commit. Never hand-run `git commit`, `--no-verify`, `--amend` or push.
 6. **Escape hatch**: if the merge must not complete, `git merge --abort` **after user confirmation** (*structured-choice*) — leaves the repo as before the merge.
 
 > **Resume via git**: the merge state in `.git` (MERGE_HEAD + index) **is** the checkpoint; re-running `/w:fix-git` resumes from the remaining conflicts. No session, no artifact.

package/skills/w/roles/research/ROLE.md

@@ -89,7 +89,7 @@ Every loop loads it on demand:
 
 ### Read-only git (git-safe, invariant #5)
 
-Only: `git log`, `git show`, `git diff`, `git blame`, `git branch --show-current`.
+Only: `git log`, `git show`, `git diff`, `git blame`, `git -C <ruta-de-la-fuente> branch --show-current`. Read each source at its own path, never infer its branch from the hub.
 Never during investigation: `commit`, `push`, `merge`, `rebase`, `reset`, `checkout`.
 
 ### Inconclusive closure