@tacuchi/agent-workflow-cli 25.8.0 → 25.9.0

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

@@ -68,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>`;
@@ -77,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

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

@@ -5,7 +5,7 @@ description: >-
   changes as versioned scripts (never executing them): writes statements to the
   session `SCRIPTS.sql` with `@category` + `@stmt` markers, applies project SQL
   style (canonical header, BEGIN/COMMIT, idempotency, explicit schema, CTEs over
-  DO/LOOP), classifies into the 4 categories, and knows how rollbacks are derived
+   DO/LOOP), classifies into the 5 categories, and knows how rollbacks are derived
   on export. DB access is read-only via MCP — DML/DDL is NEVER executed (invariant 4).
   Use when a loop writes migrations / queries, when research reads schema, or when
   export-scripts consolidates the bundle.
@@ -41,11 +41,12 @@ The AI **never executes DML/DDL** against any DB, through any channel (MCP, `psq
 - Choose only a registered connection; the registry, not environment-name conventions, supplies its exact DSN variable.
 - A remote snapshot is recorded before plan approval and is never refreshed from `plan-exec`.
 
-### Staging — a single `SCRIPTS.sql` per session
+### Staging — separate forward and rollback artifacts per session
 
 ```
 .workflow/sessions/<folder>/
-└── SCRIPTS.sql      (consolidated: ALL of the session's statements)
+├── SCRIPTS.sql           (forward migrations and type-A reads)
+└── SCRIPTS.rollback.sql  (reverse migrations, never applied with the forward)
 ```
 
 Every statement is **appended** with a pair of comment markers:
@@ -58,13 +59,13 @@ CREATE TABLE IF NOT EXISTS <schema>.<table> (
 );
 ```
 
-- `@category` classifies (4 canonical values, below).
+- `@category` classifies (5 canonical values, below).
 - `@stmt` gives the deterministic slug `NN-verb-target`; `export-scripts` derives the filename when splitting.
-- Order inside the file = chronological append order. The final per-category execution order (01→02→03→04) is resolved by `export-scripts`, not here.
+- Order inside the file = chronological append order. The final category order (01→02→03→04→05) is resolved by `export-scripts`.
 - A global `BEGIN;` at the top of the file, `COMMIT;` at the end. Individual statements carry **no** BEGIN/COMMIT of their own.
-- **No** per-file `.rollback.sql` during exec — the rollback is generated on export.
+- Put session reverses in `SCRIPTS.rollback.sql`, never after the forwards. Export pairs each forward with its own `.rollback.sql` under `rollback/`.
 
-### The 4 categories (`@category`)
+### The 5 categories (`@category`)
 
 | Marker | Detection patterns |
 |---|---|
@@ -72,8 +73,9 @@ CREATE TABLE IF NOT EXISTS <schema>.<table> (
 | `02-ddl-funciones` | `CREATE [OR REPLACE] FUNCTION/PROCEDURE`, `DROP FUNCTION/PROCEDURE` |
 | `03-migracion` | `UPDATE`, `INSERT ... SELECT`, `DELETE` over existing data, column transformations |
 | `04-inserts` | `INSERT INTO ... VALUES`, catalog seeds, initial configuration data |
+| `05-grants` | `GRANT`/`REVOKE`, `ALTER … OWNER TO`, `ALTER DEFAULT PRIVILEGES` |
 
-**Mandatory execution order**: 01 → 02 → 03 → 04. `SCRIPTS.sql` may mix categories chronologically; `export-scripts` orders the final bundle.
+**Mandatory execution order**: 01 → 02 → 03 → 04 → 05. `SCRIPTS.sql` may mix categories chronologically; `export-scripts` orders the final bundle.
 
 ### SQL style
 
@@ -110,12 +112,12 @@ CREATE TABLE IF NOT EXISTS <schema>.<table> (
 2. **Verify idempotency** of the statement.
 3. **Append** with the marker pair (`@category` + `@stmt`).
 4. **Style check** — canonical header, CTEs over DO/LOOP, explicit schema.
-5. **Never** renumber or move (there is a single `SCRIPTS.sql`).
-6. **Never** generate `.rollback.sql` during exec.
+5. **Never** renumber or move `SCRIPTS.sql` during exec.
+6. Keep the inverse in the separate `SCRIPTS.rollback.sql`.
 
-### Rollback (generated by `export-scripts`, not here)
+### Rollback (session draft and export)
 
-`export-scripts` reads the consolidated forwards and generates **a single** `00-ROLLBACK.sql` at the bundle root, in reverse order. Know the strategies to write reversible forwards:
+Write session reverses in `SCRIPTS.rollback.sql`. `export-scripts` pairs each final forward with `rollback/<categoría>/NN-<nombre>.rollback.sql` and derives `rollback/00-global/00-ROLLBACK.sql` in safe reverse order. Know the strategies to write reversible forwards:
 
 | Forward | Rollback |
 |---|---|
@@ -131,8 +133,8 @@ CREATE TABLE IF NOT EXISTS <schema>.<table> (
 
 ## Output
 
-- During loops: statements appended to `.workflow/sessions/<folder>/SCRIPTS.sql` (session artifact, never `docs/`).
-- Via `export-scripts`: the `docs/scripts/NNN-export-scripts-YYYY-MM-DD/` bundle — `00-ROLLBACK.sql` + `01-<CATEGORY>.sql` … (continuous numbering, no gaps for empty categories) + `README.md`. Canonical category order: `DDL-TABLES → DDL-FUNCTIONS → DML → INSERTS`.
+- During loops: forwards in `SCRIPTS.sql`, reverses in `SCRIPTS.rollback.sql` (session artifacts, never `docs/`).
+- Via `export-scripts`: five category folders (`01-ddl-tablas` … `05-grants`) with numbered forwards, matching reverses in `rollback/<categoría>/` and the global reverse in `rollback/00-global/00-ROLLBACK.sql`; empty categories have no folder.
 
 It never writes `docs/` from a loop (invariant 1: only `export-*` exports). It never executes anything against a DB (invariant 4).
 

package/skills/w/schemas/design/ui-screen.v1.schema.json

@@ -88,6 +88,15 @@
       },
       "uniqueItems": true
     },
+    "screen_refs": {
+      "description": "Optional screen revisions cited by this screen's body; a state anchor cites the declared revision.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^DES-(?:[0-9]{3}|[1-9][0-9]{3,})/SCR-(?:[0-9]{3}|[1-9][0-9]{3,})@r[1-9][0-9]{0,5}$"
+      },
+      "uniqueItems": true
+    },
     "dependencies": {
       "type": "object",
       "additionalProperties": false,