@tacuchi/agent-workflow-cli 25.8.0 → 26.0.0

package/skills/w/roles/README.md

@@ -1,31 +1,25 @@
 # roles/ — Capability role catalog
 
-> Built-in default implementations of the **capability roles** that loops and exports compose.
-> A role is a slot in the system; a skill is one concrete implementation of that slot.
-> Changing implementation = changing one line in `skills.toml`.
+> Only Workline-owned capabilities are binding roles. Other skills are host-native help, never Workline dependencies.
 
 ---
 
 ## Capability catalog
 
-All 6 roles, their built-in defaults, their tier, and which loops/exports compose them:
+The owned roles and their built-in defaults:
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
 | `design` | [`design`](design/ROLE.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` · `plan-exec-loop` (reads, never redesigns) |
-| `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
-| `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
-| `research` | [`research`](research/ROLE.md) | should | all loops (on-demand investigation) |
-| `diagrams` | [`diagrams`](diagrams/ROLE.md) | should | `export-diagrams` |
 | `overview` | `w` | should | any loop (orientation about Workline itself) |
 
 **Tiers:**
 - `must` — core to almost every session; built-in always active unless explicitly `off`.
 - `should` — loaded on-demand; active by default but lower priority to override.
 
-> **Ambient conventions (not roles).** Code, testing and writing standards **and tool authoring** (`creating-tools`, which writes `docs/tools`) are **not Workline roles** and are never bound: they are **standalone skills the host auto-discovers by `description`** and applies when relevant. Workline is **indifferent** (it neither reads nor looks for them). Useful families live in marketplace plugins (`dev-conventions`, `tool-builder`), but Workline does **not depend** on them.
+> **Ambient help (not roles).** Code, testing, writing, SQL, Git, research, diagrams and tool authoring are available when the host exposes them. Workline does not bind, inventory, install or require them.
 >
-> **An external skill is a technique, never an authorization.** Installing one adds a technique the host may apply when it is relevant; it moves no boundary this system already fixed. Concretely: a skill recommending a validation library does not override the repo's own decision; a reference to subagents is not delegation authority; one that writes documents of its own still lands where the work's custody says; an interview or a checklist it proposes does not become a step of SPEC, PLAN or QUICK; and none of them authorizes a dependency, an agent, an architecture change or an extra validation. **Absence is not a blocker either:** a flow whose optional skill is missing, refused or incompatible runs its base behavior, and says so instead of reporting a check it never ran — a real dependency of the task is named as such. What Workline controls is its **recommendation** and its **managed installation**; a host that discovers instructions by another route is outside that control, so neither a catalog filter nor a `skills.toml` `off` is ever announced as a universal switch.
+> **An external skill is a technique, never an authorization.** Host help cannot override Workline's gates, permissions, destinations or validated receipts. Its absence never blocks core flows; its mere presence never credits an improvement.
 >
 > **`ui-design` and `ui-spec` are retired names.** The design slot is [`design`](design/ROLE.md), whose only output is the UI Design Package v1. Neither retired name is a role, a binding, an alias or an implementation: they are **rejected**, because two names for one capability are two contracts in disguise. There is no alias, no dual-read, no importer and no migration — a binding that names one is reported as `retired/unsupported`, and a design that is still needed is recreated over the package.
 >
@@ -47,13 +41,11 @@ built-in default
 
 **Resolution rules:**
 
-1. **Role with a binding** (workspace, or global if not workspace) → use that skill name.
-   - If the name exists under `roles/<name>/` → it is a built-in skill.
-   - If not → it is a third-party skill installed by name on the host (e.g. via skills.sh).
+1. **Owned role with a binding** → its canonical Workline skill name or `off` applies. Other names are warned as inapplicable, with the file left untouched.
 2. **Role with no binding at any level** → use the built-in default (table above). No config needed for the common case.
 3. **`off`** → capability disabled. The loop continues without it; if the task required it, the loop reports why it cannot proceed or asks the human.
 
-**A role whose skill declares a capability descriptor is stricter**, because there the binding decides what RUNS and not just which name is written: unset or the canonical name enables the built-in floor plus whatever compatible improvements the host selected; `off` applies the descriptor's per-operation policy and no host, wrapper or legacy name reverts it; anything else is `misconfigured` — a replacement binding does not select an improvement, and the file is never rewritten for you. Existing workspaces are not migrated: `aw skills --detail` explains the reclassification and the owner adopts unset, the canonical name or `off`.
+**`design`** uses its built-in floor for required operations. A legacy replacement binding does not select a contributor or disable the floor; `off` follows the descriptor's per-operation policy. `[docs]` is independent and remains supported.
 
 ---
 
@@ -63,44 +55,20 @@ built-in default
 [skills]
 # Built-in defaults (no entry needed — listed here for reference only)
 # design           = "design"
-# sql              = "sql"
-# git              = "git"
-# research         = "research"
-# diagrams         = "diagrams"
 # overview         = "w"
 
-# Override examples:
-design           = "acme/figma-spec"    # third-party skill installed via skills.sh
-diagrams         = "mermaid-only"       # custom built installed locally
-sql              = "off"                # disable the sql capability
+# Per-operation policy for an owned capability:
+# design           = "off"
 ```
 
-### Override: point to a third-party skill
-
-```toml
-[skills]
-design = "acme/figma-spec"
-```
-
-`acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The binding is **advisory**: the resolver emits the name as-is — it does **not** verify the skill is installed and does **not** auto-fall-back to the built-in default. A typo'd name silently leaves the role bound to a skill that does not exist. Verify the resolution with `aw skills`, which warns when a bound skill is not found in the standard skill roots.
-
 ### Override: disable a capability
 
 ```toml
 [skills]
-sql = "off"
-```
-
-The loop that composes `sql` will skip it. If the task required the capability and the role is `off`, the loop should inform the human and ask how to proceed.
-
-### Override: use a different built-in
-
-```toml
-[skills]
-diagrams = "diagrams-lite"   # if a "diagrams-lite" built-in were registered
+design = "off"
 ```
 
-Only meaningful if multiple built-ins for the same role are registered. Currently each role has exactly one built-in default.
+The `design` descriptor decides operation by operation: validation retains its own floor while authoring operations are disabled.
 
 ---
 
@@ -118,10 +86,6 @@ Example output:
 Role              Resolved skill          Source
 ----------------- ----------------------- -----------
 design            design                  built-in
-sql               sql                     built-in
-git               git                     built-in
-research          research                built-in
-diagrams          mermaid-only            global      (~/.workflow/skills.toml)
 overview          w                       built-in
 ```
 
@@ -149,4 +113,4 @@ Each `ROLE.md` follows this schema:
 | `## Output` | what it produces and where (if any) |
 | `## Source` | recycled from (if applicable) |
 
-See [`research/ROLE.md`](research/ROLE.md) as a reference implementation.
+See [`design/ROLE.md`](design/ROLE.md) as a reference implementation.

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

@@ -25,7 +25,9 @@ replaces) and `ui-spec` (the skill that used to fill it) are **not** aliases,
 for one capability is a second contract in disguise, and the day the two
 disagree there is no way to say which one the package obeys.
 
-Rebindable in `.workflow/skills.toml` to a third-party skill or `off`.
+`skills.toml` accepts the canonical name or `off`; legacy external names are
+reported but cannot select a contributor. The host may contribute independently
+in an attempt, subject to Workline's own validation and permissions.
 Resolution: built-in default → `~/.workflow/skills.toml` (global) →
 `.workflow/skills.toml` (workspace). See [`../README.md`](../README.md).
 
@@ -106,7 +108,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 +117,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/diagrams/ROLE.md

@@ -12,7 +12,7 @@ description: >
 
 ## Role
 
-`diagrams` — built-in default implementation. Rebindable to another skill (third-party or `off`) in `.workflow/skills.toml`.
+Diagram authoring can use host-native help without a Workline binding; the export retains its own destination and validation rules.
 
 ## Purpose
 

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

@@ -14,12 +14,14 @@ description: >-
 
 ## Role
 
-`git` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). This skill encodes invariant 5: **safe git**.
+Git-safe execution is a Workline invariant, independent of host skills and bindings.
 
 ## Purpose
 
 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

@@ -14,7 +14,7 @@ description: >
 
 ## Role
 
-`research` — built-in default implementation. Rebindable to another skill (third-party or `off`) in `.workflow/skills.toml`.
+Research uses the loop's own gap-driven method. Any additional host-native help is optional, not a Workline binding.
 
 ## Purpose
 
@@ -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.
@@ -15,7 +15,7 @@ description: >-
 
 ## Role
 
-`sql` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). When `off`, the loop continues without DB authoring help and says so if the task needed it.
+DB scripts-only is Workline policy. SQL authoring help is ambient, supplied by the host when available and never required to enforce that policy.
 
 ## Purpose
 
@@ -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,

package/dist/application/capability/descriptor-loader.js

@@ -1,109 +0,0 @@
-/**
- * Reading the descriptor an installed skill claims to satisfy.
- *
- * The claim crosses a trust boundary: the frontmatter and the JSON next to it
- * were authored by whoever wrote the skill, and nothing about being installed
- * makes either of them true. So the loader verifies before it believes, in this
- * order, and stops at the first failure:
- *
- * 1. the metadata key exists — its absence is not an error, it means the skill
- *    is ambient and gets no Workline surface;
- * 2. the locator is a confined relative path to a `.json`, sealed with a digest;
- * 3. the resolved file is a real file inside the skill's own directory and NOT a
- *    symlink — a link is how a confined path reaches outside anyway;
- * 4. the bytes produce the sealed digest;
- * 5. the contract version is one this CLI implements, checked before any other
- *    field is read.
- *
- * A failure never loads partially and never touches a binding.
- */
-import { join } from "node:path";
-import { CAPABILITY_DESCRIPTOR_METADATA_KEY, parseDescriptorLocator, verifyDescriptorPayload, } from "../../domain/capability/descriptor.js";
-import { getSkillVersion, parseSkillFrontmatter } from "../../domain/skill-frontmatter.js";
-/** Read a skill's `SKILL.md` head. Returns null when there is no readable one. */
-export async function readSkillHead(fs, skillDir, dirName) {
-    const skillMd = join(skillDir, "SKILL.md");
-    if (!(await fs.exists(skillMd)))
-        return null;
-    let text;
-    try {
-        text = await fs.readText(skillMd);
-    }
-    catch {
-        return null;
-    }
-    const fm = parseSkillFrontmatter(text);
-    if (fm === null)
-        return null;
-    return {
-        name: fm.fields.name?.trim() || dirName,
-        version: getSkillVersion(fm),
-        locatorValue: fm.metadata[CAPABILITY_DESCRIPTOR_METADATA_KEY] ?? null,
-        skillMd,
-    };
-}
-export async function loadDescriptor(fs, skillDir, head) {
-    if (head.locatorValue === null)
-        return { state: "absent" };
-    const parsed = parseDescriptorLocator(head.locatorValue);
-    if (!parsed.ok) {
-        return {
-            state: "invalid",
-            failure: { code: parsed.code, message: parsed.message, action: parsed.action },
-        };
-    }
-    const absolute = join(skillDir, parsed.locator.path);
-    const link = await fs.lstat(absolute);
-    if (link === null) {
-        return {
-            state: "invalid",
-            failure: {
-                code: "CAPABILITY_DESCRIPTOR_MISSING",
-                message: `'${head.name}' declara un descriptor en '${parsed.locator.path}' y ahí no hay nada`,
-                action: "publicá el descriptor junto al SKILL.md, o quitá la clave de metadata",
-            },
-        };
-    }
-    // A confined relative path still lands outside if the target is a link. The
-    // containment rule is about WHICH BYTES get read, not about how the path looks.
-    if (link.isSymlink || link.type !== "file") {
-        return {
-            state: "invalid",
-            failure: {
-                code: "CAPABILITY_DESCRIPTOR_NOT_CONFINED",
-                message: `'${parsed.locator.path}' no es un archivo dentro del directorio de la skill`,
-                action: "publicá el descriptor como archivo real, sin enlaces simbólicos",
-            },
-        };
-    }
-    let bytes;
-    try {
-        bytes = await fs.readText(absolute);
-    }
-    catch {
-        return {
-            state: "invalid",
-            failure: {
-                code: "CAPABILITY_DESCRIPTOR_UNREADABLE",
-                message: `no se pudo leer '${parsed.locator.path}'`,
-                action: "revisá permisos del archivo del descriptor",
-            },
-        };
-    }
-    const verified = verifyDescriptorPayload(parsed.locator, bytes);
-    if (!verified.ok) {
-        return {
-            state: "invalid",
-            failure: { code: verified.code, message: verified.message, action: verified.action },
-        };
-    }
-    return {
-        state: "loaded",
-        loaded: {
-            descriptor: verified.descriptor,
-            path: parsed.locator.path,
-            digest: parsed.locator.digest,
-        },
-    };
-}
-//# sourceMappingURL=descriptor-loader.js.map

package/dist/application/capability/descriptor-loader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"descriptor-loader.js","sourceRoot":"","sources":["../../../src/application/capability/descriptor-loader.ts"],"names":[],"mappings":"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"}