@tacuchi/agent-workflow-cli 11.0.1 → 12.0.0

package/skills/w/roles/README.md

@@ -0,0 +1,154 @@
+# 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`.
+
+---
+
+## Capability catalog
+
+All 10 roles, their built-in defaults, their tier, and which loops/exports compose them:
+
+| Role | Default built-in | Tier | Composed by |
+|---|---|---|---|
+| `ui-design` | [`ui-spec`](../ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
+| `sql` | `sql` | must | research sessions · `plan-exec-loop` · `quick-loop` · `export-scripts` |
+| `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
+| `coding-standards` | `coding-standards` | must | `plan-exec-loop` · `quick-loop` |
+| `writing` | `writing` | must | all loops · `export-manuals` · `export-reports` |
+| `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
+| `testing` | [`testing`](testing/SKILL.md) | should | `plan-exec-loop` · `quick-loop` |
+| `tools` | [`tools`](tools/SKILL.md) | should | `plan-exec-loop` |
+| `diagrams` | [`diagrams`](diagrams/SKILL.md) | should | `export-diagrams` |
+| `overview` | `workflow` | should | any loop (orientation about the workflow 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.
+
+---
+
+## Binding cascade
+
+The CLI resolves which skill fulfills a role at compose-time using a 3-level cascade:
+
+```
+built-in default
+    ↓  (overridden by, if present)
+~/.workflow/skills.toml        (global — applies to all workspaces on this machine)
+    ↓  (overridden by, if present)
+.workflow/skills.toml          (workspace — applies only to this workspace)
+```
+
+**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).
+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.
+
+---
+
+## skills.toml format
+
+```toml
+[skills]
+# Built-in defaults (no entry needed — listed here for reference only)
+# ui-design        = "ui-spec"
+# sql              = "sql"
+# git              = "git"
+# coding-standards = "coding-standards"
+# writing          = "writing"
+# research         = "research"
+# testing          = "testing"
+# tools            = "tools"
+# diagrams         = "diagrams"
+# overview         = "workflow"
+
+# Override examples:
+testing          = "off"                # disable testing capability
+ui-design        = "acme/figma-spec"    # third-party skill installed via skills.sh
+diagrams         = "mermaid-only"       # custom built installed locally
+```
+
+### Override: point to a third-party skill
+
+```toml
+[skills]
+ui-design = "acme/figma-spec"
+```
+
+`acme/figma-spec` must be installed on the host (e.g. via `skills.sh install acme/figma-spec`). The CLI resolves the skill by name; if not found, it falls back to the built-in default and warns.
+
+### Override: disable a capability
+
+```toml
+[skills]
+testing = "off"
+```
+
+The loop that composes `testing` will skip it. If the task required testing 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
+```
+
+Only meaningful if multiple built-ins for the same role are registered. Currently each role has exactly one built-in default.
+
+---
+
+## Inspecting resolved bindings
+
+```bash
+aw skills
+```
+
+Lists the resolved binding for every role in the current workspace, showing which level of the cascade provided it (built-in / global / workspace) and whether it is `off`.
+
+Example output:
+
+```
+Role              Resolved skill      Source
+----------------- ------------------- -----------
+ui-design         ui-spec             built-in
+sql               sql                 built-in
+git               git                 built-in
+coding-standards  coding-standards    built-in
+writing           writing             built-in
+research          research            built-in
+testing           off                 workspace   (.workflow/skills.toml)
+tools             tools               built-in
+diagrams          mermaid-only        global      (~/.workflow/skills.toml)
+overview          workflow            built-in
+```
+
+---
+
+## Adding a new role
+
+1. Define the role in this README (name, default built-in, tier, composed by).
+2. Author the built-in skill under `roles/<name>/SKILL.md` following the schema.
+3. Register it in the CLI resolver so `aw skills` lists it.
+4. Document the binding key in the `skills.toml` reference above.
+
+## Authoring a built-in skill
+
+Each `SKILL.md` follows this schema:
+
+| Section | Content |
+|---|---|
+| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `testing`, etc.) |
+| Frontmatter `description:` | rich description: what + when; drives automatic selection |
+| `## Role` | which capability role this implements (its skills.toml slot) |
+| `## Purpose` | what it does |
+| `## Composed by` | which loops/exports use it and when |
+| `## Knowledge` | reusable know-how: vocabulary, rules, schema, examples |
+| `## Output` | what it produces and where (if any) |
+| `## Source` | recycled from (if applicable) |
+
+See [`research/SKILL.md`](research/SKILL.md) as a reference implementation.

package/skills/w/roles/coding-standards/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: coding-standards
+description: >-
+  Coding standards capability — built-in default for the `coding-standards` role.
+  Stack-agnostic principles (SOLID, fail-fast, descriptive names, small methods,
+  reuse over duplication) plus per-stack conventions (Java/Spring, Angular/TypeScript,
+  Node), security (no secrets in code or logs, parametrized SQL, DB read-only via MCP),
+  HTTP error handling (never silence errors), logging levels, and FE-BE integration
+  rules (unified sparse DTO, PATCH for edit, no hidden fallbacks). Use when a loop
+  implements, reviews or refactors code.
+---
+
+# coding-standards — Coding standards capability
+
+## Role
+
+`coding-standards` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`).
+
+## Purpose
+
+Aportar los estándares de código que la IA aplica al **implementar, revisar o refactorizar**. Read-only por diseño: carga reglas, no edita ni ejecuta nada por sí misma — el loop consumidor materializa el código.
+
+## Composed by
+
+- **`plan-exec-loop`** — al implementar/refactorizar las tasks del plan.
+- **`quick-loop`** — al implementar el atajo liviano.
+
+## Knowledge
+
+### Principios generales
+
+- **SOLID** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion.
+- **Fail fast** — validar y retornar al inicio del método (early returns, evitar nesting).
+- **Nombres descriptivos** — el código habla por sí mismo; comentarios solo para el "por qué".
+- **Métodos pequeños** — una sola responsabilidad por función.
+- **Composición sobre herencia**.
+- **Reutilización antes que duplicación (DRY)** — antes de crear componente/función/clase, revisar si ya existe en `shared/` (frontend) o `common/`/`util/` (backend). Si un patrón aparece 2-3 veces, proponer extracción.
+
+### Estándares por stack
+
+- **Java / Spring Boot**: Constructor Injection (sin Field Injection), `@Transactional(readOnly=true)` para lecturas, Java records para DTOs Request/Response, Jakarta Validation para inputs.
+- **Angular / TypeScript**: constructor injection, `async` pipe en templates, evitar `any`, FormBuilder reactivo sobre `ngModel` directo, arquitectura `@data`/`@presentation`, normalización de tipos.
+- **Node / otros**: mismos principios generales; aplicar las convenciones idiomáticas del proyecto detectado.
+
+### Integración FE-BE (cuando el cambio cruza frontend y backend)
+
+- **R1 — Sparse DTO unificado**: mismo DTO `<Feature>SaveRequest` para create + edit, todos los campos nullable. `null` = "no tocar".
+- **R2 — PATCH para edit**: `@PatchMapping` en BE, `http.patch()` en FE. POST solo para create. PUT solo si replace total justificado.
+- **R3 — FE envía solo cambios**: payload diff entre `formValue` y entidad original.
+- **R4 — Sin fallbacks que oculten errores**: prohibido `catchError(() => of([]))` en FE; prohibido try/catch con fallback al método legacy en BE durante migraciones. Usar feature flags explícitas para rollout gradual.
+- **R5 — Validación BE con Bean Validation + groups**: `@NotNull(groups = OnCreate.class)` para distinguir reglas POST vs PATCH cuando comparten DTO.
+- **R6 — DB stub-first**: funciones/SP nuevas arrancan devolviendo mock (`RETURN '[]'::jsonb`); implementación real en una fase posterior.
+
+### Seguridad
+
+- **Nunca** exponer secrets, API keys ni credenciales en código.
+- **Nunca** logear datos sensibles (contraseñas, tokens, datos personales).
+- **Siempre** parametrizar queries SQL (nunca concatenar strings).
+- **BD vía MCP es READONLY**. Modificaciones a BD solo como scripts SQL versionados (ver rol `sql`); las aplica el **usuario**, nunca la IA — ni por MCP, ni `Bash`, ni `psql`, ni driver. (Invariante 4.)
+
+### Manejo de errores HTTP
+
+- **Nunca** silenciar errores HTTP con `catchError(() => of([]))` ni equivalentes. Los errores del backend se propagan al usuario (toast/mensaje) para detectar regresiones en guardado/sincronización/creación. Para reintentos usar operadores explícitos (`retry`, `retryWhen`), no silenciar.
+
+### Logging
+
+- `ERROR` — fallos que requieren atención inmediata.
+- `WARN` — situaciones inesperadas pero manejadas.
+- `INFO` — eventos de negocio relevantes (inicio/fin de procesos).
+- `DEBUG` — detalle técnico para diagnóstico.
+
+### Convenciones de BD (nomenclatura)
+
+Esquemas `esq_`, tablas `tb_`, sequences `seq_`, funciones `fn_`/procedimientos `sp_`, patrón maestra-detalle, auditoría en `esq_audit`. Para autoría de scripts SQL (estilo, header, categorías, rollback) usar el rol **`sql`**.
+
+## Output
+
+Ninguno propio. La skill aporta reglas; el código lo escribe el loop. Cuando el cambio toca BD, delega la autoría de scripts al rol `sql`. Nunca exporta a `docs/` (invariante 1).
+
+## Source
+
+Reciclada de `standards/coding-standards/` (SKILL.md + references Java/Spring, Angular/TypeScript, fe-be-integration, database-conventions, frontend-structure, project-structure). Los principios UX de mantenimientos CRUD (formularios, listados, modales) viven en el rol `ui-spec`/`ui-design`; la autoría de scripts SQL en el rol `sql`. Se descarta la dependencia de `profile.json` y de comandos CLI de la doctrina vieja.

package/skills/w/roles/diagrams/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: diagrams
+description: >
+  Autoría de diagramas de arquitectura y sistema: C4 (Context, Container, Component),
+  PlantUML y Structurizr DSL. Compuesta por export-diagrams para producir el contenido
+  de docs/diagrams/. Selecciona el motor de render según el flag --diagrams del export
+  (Structurizr default, Mermaid y PlantUML opt-in). Incluye link mermaid.ink por cada
+  bloque Mermaid para preview sin renderer local.
+---
+
+# diagrams — Diagram authoring capability
+
+## Role
+
+`diagrams` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
+
+## Purpose
+
+Autorar diagramas de arquitectura con notación C4 (Levels 1-3) usando el motor que el export configure. Produce source renderizable (DSL, PUML, Mermaid) — **no renderiza visualmente**; el render lo hace el lector con sus herramientas. Cubre el estándar C4 formal (Structurizr DSL), el opt-in embebido (Mermaid nativo) y el opt-in exportable (PlantUML).
+
+## Composed by
+
+| Export | Cuándo la compone |
+|---|---|
+| `export-diagrams` | para generar el contenido de `docs/diagrams/NNN-*/` |
+
+Cualquier loop puede componerla también si necesita producir un diagrama inline durante ejecución (raro; el caso primario es `export-diagrams`).
+
+## Knowledge
+
+### Engine matrix
+
+| `--diagrams` flag | Motor | Archivos producidos | Cuándo elegirlo |
+|---|---|---|---|
+| `structurizr` (default) | Structurizr DSL | `workspace.dsl` + Mermaid auxiliar embebido en `.md` | Dossier técnico formal; soporte de tooling externo (structurizr.com, structurizr-lite) |
+| `mermaid` | Mermaid C4 nativo | solo `.md` con bloques Mermaid | Preferir render embebido sin DSL separado; GitHub/GitLab lo renderizan inline |
+| `plantuml` | PlantUML C4-stdlib | `arquitectura.puml` + nota en `.md` | Equipos con pipeline PlantUML instalado |
+
+**Regla canónica**: `export-diagrams` usa Structurizr DSL por defecto (C4 formal, separa modelo de vistas). Mermaid es opt-in cuando se prefiere render embebido.
+
+### C4 model — levels
+
+#### Level 1: Context (C4Context)
+
+El sistema como caja única + actores + sistemas vecinos. Perspectiva de negocio.
+
+```mermaid
+C4Context
+  title Diagrama de Contexto: <PRODUCTO>
+  Person(dev, "Developer", "Miembro del equipo")
+  System(sistema, "<PRODUCTO>", "<descripcion corta>")
+  System_Ext(extA, "<Sistema A>", "<rol>")
+  Rel(dev, sistema, "Usa")
+  Rel(sistema, extA, "<integracion>")
+```
+
+#### Level 2: Container (C4Container)
+
+Aplicaciones, servicios, data stores que componen el sistema. Una fuente declarada en `WORKSPACE` = un contenedor.
+
+```mermaid
+C4Container
+  title Diagrama de Contenedores: <PRODUCTO>
+  Person(dev, "Developer")
+  System_Boundary(sistema, "<PRODUCTO>") {
+    Container(svcA, "<Servicio A>", "<tech>", "<responsabilidad>")
+    Container(svcB, "<Servicio B>", "<tech>", "<responsabilidad>")
+    ContainerDb(db, "Base de datos", "<motor>", "<uso>")
+  }
+  System_Ext(extA, "<Sistema A>")
+  Rel(dev, svcA, "Usa")
+  Rel(svcA, db, "Lee/escribe")
+  Rel(svcA, extA, "<protocolo>")
+```
+
+#### Level 3: Component (C4Component)
+
+Módulos internos relevantes de un contenedor. Solo para contenedores con complejidad interna suficiente. Un diagrama por contenedor; el resto se omite.
+
+```mermaid
+C4Component
+  title Componentes: <Contenedor>
+  Container_Boundary(cont, "<Contenedor>") {
+    Component(compA, "<Componente A>", "<tech>", "<responsabilidad>")
+    Component(compB, "<Componente B>", "<tech>", "<responsabilidad>")
+  }
+  Rel(compA, compB, "<interaccion>")
+```
+
+Si ningún contenedor justifica C4 Component → omitir la sección con nota inline `_(Sin contenedores con complejidad interna suficiente para C4 Component.)_`.
+
+### Structurizr DSL template
+
+```dsl
+workspace "<PRODUCTO>" "<descripcion>" {
+
+  model {
+    // Personas
+    dev = person "Developer" "Miembro del equipo"
+
+    // Sistema bajo análisis
+    sistema = softwareSystem "<PRODUCTO>" "<descripcion>" {
+      svcA = container "<Servicio A>" "<tech>" "<responsabilidad>"
+      svcB = container "<Servicio B>" "<tech>" "<responsabilidad>"
+      db   = container "Base de datos" "<motor>" "<uso>" "Database"
+    }
+
+    // Sistemas externos
+    extA = softwareSystem "<Sistema A>" "<rol>" "External"
+
+    // Relaciones
+    dev   -> sistema "Usa"
+    svcA  -> db      "Lee/escribe"
+    svcA  -> extA    "<protocolo>"
+  }
+
+  views {
+    systemContext sistema "Context" {
+      include *
+      autoLayout
+    }
+
+    container sistema "Container" {
+      include *
+      autoLayout
+    }
+
+    // Una vista por contenedor con C4 Component relevante:
+    component svcA "SvcA-Components" {
+      include *
+      autoLayout
+    }
+
+    theme default
+  }
+}
+```
+
+Render online gratuito: [structurizr.com/dsl](https://structurizr.com/dsl) o structurizr-lite (Docker).
+
+### PlantUML C4-stdlib template
+
+```plantuml
+@startuml arquitectura
+
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+title <PRODUCTO> — Diagrama de Contexto C4
+
+Person(dev, "Developer", "Miembro del equipo")
+System(sistema, "<PRODUCTO>", "<descripcion>")
+System_Ext(extA, "<Sistema A>", "<rol>")
+
+Rel(dev, sistema, "Usa")
+Rel(sistema, extA, "<protocolo>")
+
+SHOW_LEGEND()
+@enduml
+```
+
+Render: [plantuml.com](https://plantuml.com) o `plantuml.jar` local.
+
+### Mermaid auxiliar (bajo Structurizr default)
+
+Cuando `--diagrams structurizr`, el archivo `.md` incluye también un bloque Mermaid derivado del DSL como **fallback offline** (lectores sin acceso a structurizr.com/dsl pueden leerlo directamente):
+
+```
+```mermaid
+C4Context
+  title ...
+```
+
+> Ver diagrama renderizado: <https://mermaid.ink/img/BASE64>
+```
+
+El `BASE64` es el código Mermaid plano codificado en base64 URL-safe (RFC 4648 §5; alfabeto `A-Z a-z 0-9 - _`). **Cada bloque Mermaid lleva su propio link** inmediatamente después del fence de cierre.
+
+### Sequence diagrams (opt-in)
+
+Para flujos críticos de integración (no C4 estructural), un `sequenceDiagram` Mermaid complementa el C4 Container:
+
+```mermaid
+sequenceDiagram
+  participant Dev
+  participant SvcA
+  participant DB
+  Dev->>SvcA: POST /resource
+  SvcA->>DB: INSERT
+  DB-->>SvcA: OK
+  SvcA-->>Dev: 201 Created
+```
+
+Solo si aporta claridad real — no agregar sequence diagrams por defecto.
+
+### Entity-Relationship (modelo de datos)
+
+Cuando `export-diagrams` incluye `--scope datos` y hay MCP configurado:
+
+```mermaid
+erDiagram
+  TABLA_A ||--o{ TABLA_B : "tiene"
+  TABLA_A {
+    int id PK
+    string nombre
+  }
+  TABLA_B {
+    int id PK
+    int a_id FK
+    string detalle
+  }
+```
+
+MCP read-only: `\d <tabla>` + `SELECT count(*)` para magnitud (aplicar cost guard: ver skill `research` o `sql`).
+
+### Output file structure
+
+```
+docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/
+├── README.md            # indice + how-to-read + motores usados
+├── arquitectura.md      # documento principal con C4 + Mermaid auxiliar
+├── workspace.dsl        # solo con --diagrams structurizr (default)
+└── arquitectura.puml    # solo con --diagrams plantuml
+```
+
+### Render rules
+
+1. Sin cota de palabras — completitud > concisión para documentación técnica.
+2. Diagrama principal (al menos C4Context + C4Container) es obligatorio; sin ellos el output no es válido.
+3. C4Component solo si el contenedor lo justifica.
+4. Sequence y erDiagram son opcionales; solo si aportan claridad real.
+5. Cada bloque `mermaid` lleva el link `mermaid.ink` como blockquote inline.
+6. Placeholders `{{PLACEHOLDER}}` siempre reemplazados — nunca dejar marcadores sin rellenar.
+
+## Output
+
+Produce en `docs/diagrams/NNN-export-diagrams-YYYY-MM-DD/`:
+- `README.md`
+- `arquitectura.md` (siempre)
+- `workspace.dsl` (si `--diagrams structurizr`)
+- `arquitectura.puml` (si `--diagrams plantuml`)
+
+Escribe solo `docs/diagrams/` (invariant #1 y #2: solo `export-*` gradua a `docs/`; esta skill la compone `export-diagrams`).
+
+## Source
+
+Reciclado de `agent-workflow/exports/export-arq/` del bundle viejo (v1.3.0). Se conserva: el modelo C4 Levels 1-3, los tres motores (Structurizr default, Mermaid opt-in, PlantUML opt-in), las plantillas DSL y PUML, la regla de link `mermaid.ink` por bloque Mermaid, la estructura de output, el cost guard para MCP. Se descarta: la lógica de lectura de AW-PROJECT legacy, los comandos CLI `agent-workflow next-number`/`history-data`/etc. (son detalles de implementación del CLI, no de la skill), y el scope `--diagrams` como input flag (lo recibe el export que compone esta skill).

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

@@ -0,0 +1,98 @@
+---
+name: git
+description: >-
+  Git-safe capability — built-in default for the `git` role. Verifies the expected
+  work branch per source before editing, proposes commits (one per source) and only
+  commits when the user approves, and NEVER runs push, --amend, --no-verify, force,
+  merge/rebase/cherry-pick, tags, or destructive resets without explicit user request.
+  Read-only git (status/log/diff/branch) is always allowed. Use when a loop is about
+  to edit code or when the user asks to commit / save / push changes.
+---
+
+# git — git-safe capability
+
+## Role
+
+`git` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). This skill encodes invariant 5: **git seguro**.
+
+## Purpose
+
+Operar git de forma **segura y controlada**: verificar la rama esperada antes de editar, **proponer** commits por fuente, y nunca ejecutar operaciones destructivas o de publicación sin pedido explícito del usuario.
+
+## Composed by
+
+- **`plan-exec-loop`** — verifica rama antes de cada edit; propone commits al cerrar/checkpoint.
+- **`quick-loop`** — igual, en el atajo liviano.
+
+(Cualquier flujo que edite código o que el usuario quiera commitear lo usa.)
+
+## Knowledge
+
+### Operaciones prohibidas sin solicitud explícita del usuario
+
+Lista cerrada. La IA **nunca** las ejecuta por iniciativa propia:
+
+- `git commit` (incluye `--amend`)
+- `git push` (incluye `--force` / `-f`)
+- `git merge` · `git rebase` · `git cherry-pick`
+- `git tag` (crear o editar)
+- `git reset --hard` · `git restore .` · `git checkout -- .` · `git clean -fd` · `git stash` (cuando hay trabajo sin commit)
+
+Y **siempre** prohibido, aún cuando el usuario pida commit: `--no-verify` (respetar los hooks pre-commit), `--force`, trailers `Co-Authored-By`, firmas de modelo.
+
+### Operaciones read-only (siempre permitidas, sin preguntar)
+
+`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (cambio de rama) **no** es read-only: requiere `AskUserQuestion` aunque no sea destructivo (ver verificación de rama).
+
+### Verificación de rama (antes de editar)
+
+La rama esperada **nunca se asume desde la rama actual** — el usuario pudo cambiarla a mano. Verificar contra la rama de trabajo declarada por fuente antes de cualquier `Write/Edit`.
+
+Campos por fuente: `alias`, `path`, `main_branch` (base, default `certificacion`), `expected_work_branch`, `current_branch`, `match` (`current == expected`), `dirty` (cambios sin commit).
+
+Casos:
+
+- **`match=true`** → OK, editar.
+- **`match=false, dirty=false`** (Caso A — rama distinta, repo limpio) → `AskUserQuestion`: hacer `git checkout <expected>` / mantener current y actualizar la expectativa de la sesión / cancelar.
+- **`match=false, dirty=true`** (Caso B — rama distinta + cambios sin commit) → **pausar y esperar resolución manual**. No proponer checkout (podría perder trabajo). Pedir al usuario commit/stash/discard y avisar cuando continuar.
+- **Cross-fuente (hub)**: si las fuentes tocadas apuntan a ramas distintas sin declararlo, **hard gate** — bloquear avance con `AskUserQuestion` (alinear todas / declarar divergencia explícita / cancelar).
+- **HEAD detached** → tratar como Caso A.
+- **Fuente fuera de git** (`is_repo=false`) → informar, no bloquear.
+
+### Commits — propose-then-execute, una fuente a la vez
+
+Ante cualquier pedido o disparo de commit (cierre de loop, "commitea esto", "guardá los cambios"):
+
+1. Resolver las fuentes y su estado dirty/rama.
+2. Si hay 1+ fuentes `dirty=true`, invocar **una sola** `AskUserQuestion` con un tab por fuente dirty (máx 4 simultáneas; si N>4, en tandas):
+   - Header del tab: el `alias` de la fuente.
+   - Opciones: "Aprobar sugerido (Recomendado)" con el mensaje canónico / "Saltar esta fuente". `Other` = mensaje custom.
+3. Ejecutar `git -C <path> commit -m "<msg>"` solo en las fuentes aprobadas, **una a una**. Respetar hooks (sin `--no-verify`).
+4. Si una fuente tiene `match=false` (rama distinta a la esperada): **omitirla y abortar su commit**; avisar para alinear la rama primero.
+5. Si todas están `dirty=false` → skip silencioso, informar en chat que no hay nada que commitear.
+
+**Bypass** (Regla 5): si el usuario aporta el mensaje literal exacto (`-m "..."`, comillas), commitear directo sin `AskUserQuestion`, pero seguir validando rama, hooks y formato. Si el literal viola el formato, avisar antes de ejecutar.
+
+### Formato canónico del mensaje
+
+- **Una sola línea**, corta (≤72 chars sugerido), descriptiva (qué cambia, no cómo).
+- Incluir el código de sesión activa (`session<NNN>` como tag o en el prefijo) cuando aplique.
+- Prefijo Conventional Commits **opcional** (`feat:` `fix:` `docs:` `chore:` `refactor:` `test:`).
+- **Prohibido**: multi-línea/body, trailers `Co-Authored-By`, firmas de modelo, emojis (salvo pedido explícito), `--no-verify`.
+
+Válidos:
+```
+session007: agrega politica de commits controlados
+feat(session012): nuevo export-scripts
+fix(session018): corrige drift en hooks.json
+```
+
+Fuera de sesión activa: relajar a "1 línea + sin co-author"; el tag `session<NNN>` se omite. El propose-then-execute sigue activo.
+
+## Output
+
+Ninguno en `docs/`. Produce commits **solo** cuando el usuario aprueba, en los repos fuente. La verificación de rama puede actualizar la expectativa de rama de la sesión si el usuario lo elige.
+
+## Source
+
+Reciclada de la doctrina vieja: `doctrine/session/references/commits-policy.md` (Reglas 1-5: propose-then-execute, formato canónico, bypass) + `doctrine/session/references/branch-verification.md` (Casos A/B/C, cross-fuente hard gate). Se descarta la dependencia de comandos CLI específicos (`agent-workflow sources`): la verificación se hace con git read-only directo más la rama de trabajo declarada por la sesión.