@tacuchi/agent-workflow-cli 25.8.0 → 26.0.0

package/CHANGELOG.md

@@ -12,6 +12,112 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `### Migration` sigue como notas libres.
 - Las versiones hasta la 25.6.1 sólo traen la sección donde se registró una ruptura conocida, y ahí no pretende ser completa.
 
+## [26.0.0] — 2026-09-28
+
+**Workline deja de gestionar skills ajenas: distribuye y diagnostica su bundle y capacidades propios, admite ayuda del host sin exigirla y exige validación final completa al publicar planes.**
+
+### Contrato
+
+- **Deja de valer:** la pestaña Skills, sus accesos y acciones, y `initialScreen=skills` como pantalla inicial. **Lo reemplaza:** las pestañas Status, Workline, Project, MCP y Config; una preferencia anterior abre Status en memoria sin reescribir el archivo. **Qué hacer:** elegí una pantalla existente y gestioná skills ajenas desde el host o marketplace que uses.
+- **Deja de valer:** `aw self install-plugin-skills`, `install-plugin-skills-git`, `clean-cache`, `aw plugin-cache` y `aw skill-index`; los flags de instalación de terceros, `--keep-cache` en `self install`/`install-skill` y `--prefix` en `self clean-legacy`. **Lo reemplaza:** `aw self install-skill`/`uninstall-skill` mantienen sólo el bundle propio; los comandos retirados dejan de despacharse y esos flags no son admitidos por los subcomandos propios. **Qué hacer:** adaptá scripts e instalá, actualizá o retirá skills ajenas desde el host; sus instalaciones previas no se desinstalan automáticamente.
+- **Deja de valer:** el catálogo recomendado, el inventario y readiness de terceros, y los bindings externos de `skills.toml` como selección, requisito o prueba de compatibilidad para `design` y los flows. **Lo reemplaza:** `aw skills --detail` y `aw doctor` diagnostican capacidades, floor e instalación propios; los bindings ajenos históricos se avisan como no aplicables y sus archivos quedan intactos. **Qué hacer:** revisá consumidores de diagnóstico anterior y quitá o gestioná por tu cuenta bindings que ya no aplican; `off` y `[docs]` mantienen su función propia.
+- **Deja de valer:** acreditar una mejora de `design` por metadata, un `preflight` construido al validar o un `passed: true` declarado por el host sobre un archivo con digest correcto. **Lo reemplaza:** la selección se fija con un pin persistido antes de aportar contenido; las observaciones host quedan sin crédito semántico y `validate` usa el floor con degradación cuando el package propio valida. Las propuestas de autoría siguen parciales hasta aprobación y aplicación. **Qué hacer:** iniciá el intento con `prepare` y conservá su pin y request; tratá las observaciones como información, no como gate acreditado.
+- **Deja de valer:** publicar un plan con una fuente de código sin build o tests resolubles, o repartir los comandos de `Validación final` de una fuente entre viñetas. **Lo reemplaza:** `aw plan lint` y el gate de publicación usado por `plan-new` comprueban build y tests por fuente desde el pipeline versionado o el plan, y señalan comandos ausentes y viñetas partidas. **Qué hacer:** declará ambos comandos por fuente con `aw set-pipeline` o en una sola viñeta de `## Validations`, y corré `aw plan lint` antes de publicar.
+
+### Removed
+
+- **Gestión de terceros en CLI/TUI.** Salen la pestaña Skills, su catálogo, los instaladores de plugins, la caché y el índice de skills externas; se retiran los comandos públicos de mantenimiento ajeno.
+
+### Changed
+
+- **Instalación y diagnóstico propios.** `aw self install-skill`, `aw skills --detail` y `aw doctor` se centran en Workline; la doctrina del bundle admite ayuda del host sin prescribir skills ajenas por nombre.
+- **Planes con cierre verificable.** El lint y la publicación comprueban build y tests por fuente de código y rechazan validaciones finales divididas en dos viñetas.
+
+### Fixed
+
+- **Acreditación de design por intento.** Un pin aportado sólo al validar no sustituye la fijación previa persistida; las observaciones autodeclaradas no acreditan una contribución y una observación inválida no bloquea por sí sola un floor válido.
+- **Preferencias TUI anteriores.** `initialScreen=skills` cae a Status al leer, sin alterar el archivo guardado.
+
+## [25.9.0] — 2026-09-27
+
+La ejecución acredita revisiones, pruebas y commits por lote. Las fuentes tienen rutas locales, pipeline versionado y ramas por documento. Los exports conservan el número aprobado. Las sesiones y unidades se cierran con evidencia; cada comando resuelve el workspace que le corresponde.
+
+### Contrato
+
+- **Deja de valer:** omitir `plan-exec.review-findings` o cerrar un lote sin revisar sus correcciones. **Lo reemplaza:** revisión registrada por alguien distinto de los implementadores; sin subagentes, relectura limpia declarada. `batch-close` exige el registro. **Qué hacer:** entregá la revisión y volvé a revisar las correcciones.
+- **Deja de valer:** acreditar una fase o la validación final con pruebas que no corrieron, no cargaron o introdujeron fallos. **Lo reemplaza:** el veredicto exige ejecución real y sólo admite rojos previos declarados. **Qué hacer:** corregí fallos nuevos y declará los preexistentes en el plan.
+- **Deja de valer:** bloquear fases sin tareas abiertas o acreditar cualquier lote sin cambios. **Lo reemplaza:** la fase de sólo validación exige aprobación expresa y prueba real; las demás exigen cambios propios. **Qué hacer:** aprobá el lote de sólo validación antes de acreditarlo.
+- **Deja de valer:** omitir `plan-exec.final-validation` o acreditarla con `aw status --json`. **Lo reemplaza:** build y tests reales por fuente de código, resueltos desde `## Validations` o el pipeline versionado. `plan-done` exige evidencia. **Qué hacer:** declará build y test con `aw set-pipeline` o en el plan y entregá sus salidas.
+- **Deja de valer:** inferir siempre un lote por fase y diferir todos los commits al final. **Lo reemplaza:** `## Execution batches` delimita lotes; cada lote acreditado propone commits por fuente y los crea tras aprobación. Las corridas abiertas con la cola anterior la conservan. **Qué hacer:** revisá y aprobá las rutas y mensajes de cada lote.
+- **Deja de valer:** descontar un intento por aprobar una integración o un commit. **Lo reemplaza:** la concesión queda registrada sin gastar un intento de respuesta. **Qué hacer:** distinguí aprobaciones de rechazos al leer el contador.
+- **Deja de valer:** gastar intentos en formato inválido, digest erróneo, plan inválido o prueba vencida y mostrar sólo el primer defecto. **Lo reemplaza:** `error.violations` reúne defectos detectables y `aw flow submit --check` comprueba sin escribir ni gastar intento. La directiva declara efectos, aprobación, tipos, esquema y fuentes en `expects`. **Qué hacer:** corregí las violaciones y comprobá con `--check`.
+- **Deja de valer:** una prueba sin raíz observada o perder `Compactar` y `Cerrar` tras un rechazo. **Lo reemplaza:** `proof` distingue otra raíz de un checkout cambiado y muestra el stderr de git; los controles siguen disponibles en la directiva de rechazo. **Qué hacer:** medí otra vez con `aw flow prove` en el checkout indicado.
+- **Deja de valer:** exigir `schema` y `date` al autor de una nota o cobrar dos veces un reenvío idéntico. **Lo reemplaza:** el CLI completa ambos campos, avisa de campos desconocidos y reconoce el reenvío. **Qué hacer:** entregá los campos de autor y corregí los faltantes indicados.
+- **Deja de valer:** invalidar sellos de texto por LF/CRLF o rechazar en `batch-close` las marcas que el propio CLI escribió. **Lo reemplaza:** se admiten ambos finales de línea y los digests anteriores; otras ediciones muestran diff. `PLAN_EXEC_BATCH_STALE` no cobra intento. **Qué hacer:** ante cambios de contenido, prepará `aw flow recover --reinfer-batch` y confirmá con `--approval <digest>`; repetí pruebas y revisión.
+- **Deja de valer:** escribir el estado de corrida v13. **Lo reemplaza:** v15; v14 sumó revisiones, retiro de señales y observaciones de quick, y v15 añade aislamiento al alcance. Se continúan v11–v14 y se actualizan al escribir; v7–v10 sólo se leen para diagnóstico y recuperación. **Qué hacer:** avanzá una corrida v11–v14; para v7–v10 usá `aw flow restart`. No abras v15 con un CLI anterior.
+- **Deja de valer:** una rama esperada única por fuente. **Lo reemplaza:** `aw doc-branch show|set` registra la rama por documento y fuente, hereda la de spec al plan y permite integrar unidades sin mover el checkout. **Qué hacer:** consultá con `--code` o `--doc` y registrá la rama con `set --source <alias> --rama <rama>`.
+- **Deja de valer:** reescribir siempre rutas absolutas en `## Fuentes` o podar fuentes omitidas por `workspace-init --source`. **Lo reemplaza:** `.workflow/local.json` guarda rutas de este host; `aw add-source` y `workspace-init --source` son aditivos. **Qué hacer:** registrá cada checkout con `aw add-source <alias>:<ruta>:<rama>`.
+- **Deja de valer:** estampar `Última actividad` en WORKSPACE y mostrar `Histórico:` sin archivo. **Lo reemplaza:** la actividad sale en `aw status`, la rama de trabajo figura en Fuentes y CLAUDE.md/AGENTS.md se escriben juntos. **Qué hacer:** consultá la actividad en `aw status`.
+- **Deja de valer:** descargar tres versiones completas en `fix-git prepare` o resolver conflictos sólo con texto; informar `any_merging: false` al no poder leer una fuente. **Lo reemplaza:** `--show` y `--adapt` detallan rutas pedidas; `resolutions` acepta `ours`, `theirs` y `delete`, incluso binarios. `merge-state` informa `unreadable`, `any_merging: null` y sale con 1. **Qué hacer:** pedí las rutas necesarias y tratá `unreadable` como lectura incompleta.
+- **Deja de valer:** confirmar `aw fix-git commit` sin comprobar el build. **Lo reemplaza:** la vista previa sin `--confirm` incluye build, rutas y `left_out`; confirmar ejecuta el build declarado o rechaza con `FIX_GIT_BUILD_UNDECLARED`/`FIX_GIT_BUILD_FAILED`. **Qué hacer:** declará build con `aw set-pipeline` o justificá la omisión con `--skip-build <motivo>`.
+- **Deja de valer:** cambiar en `export-* apply` el número aprobado, admitir `--overwrite` fuera de manuals o reutilizar correlativos publicados tras borrar su carpeta. **Lo reemplaza:** `EXPORT_NUMBER_TAKEN` bloquea la colisión y la numeración consulta HISTORY y pases. **Qué hacer:** prepará otra propuesta si el número quedó ocupado.
+- **Deja de valer:** sellar sólo el inventario de `export-scripts` o publicar forwards y rollbacks planos. **Lo reemplaza:** SQL y `scope.seal` entran al sello; bundles nuevos organizan forwards en 01–05, rollbacks en `rollback/` y generan `bundle.json`. Los bundles planos antiguos siguen legibles. **Qué hacer:** prepará otra vez si cambió SQL o scope y publicá con el manifiesto generado.
+- **Deja de valer:** duplicar publicaciones de `next-number --publish`, materializar un workspace ausente, admitir sólo texto en `persist` o exigir siempre dossier en manuals. **Lo reemplaza:** publicación idempotente con `--dry-run`, adjuntos binarios y manuals de canon plano o `complement` con `INDEX.md`. **Qué hacer:** usá el número reservado y la forma de manuals que corresponde a tus archivos.
+- **Deja de valer:** forzar una tercera revisión simple de design por package o aceptar revisiones editadas. **Lo reemplaza:** `update` conserva el modo simple, `screen_refs` declara citas y `aw designs`/`capability validate` verifican digests; sólo cambiar LF/CRLF avisa sin bloquear. **Qué hacer:** publicá otra revisión en lugar de editar una ya publicada.
+- **Deja de valer:** que `Cerrar` sólo pause, que `quick.db-touched` incluya lecturas o que una señal errónea no se pueda retirar. **Lo reemplaza:** `Cerrar` finaliza los cinco flujos y conserva lo pendiente; `quick.db-touched` significa mutación y `aw flow retract` retira señales no consumidas. **Qué hacer:** reabrí con `aw session-resume --reopen` si seguís; retirá una señal de mera lectura antes del gate.
+- **Deja de valer:** exigir scripts por mera lectura o commit por quick sin archivos, y dejar abierta la quick al cambiar a SPEC. **Lo reemplaza:** scripts sólo por mutación, fix vacío sin commit y escalamiento con cierre y handoff a `/w:spec-new`. **Qué hacer:** guardá DDL/DML en `SCRIPTS.sql` o `scripts/*.sql`; indicá análisis cuando corresponda.
+- **Deja de valer:** escribir para averiguar si `aw amend apply` toca contrato, contar casillas de `## Handoff operativo` como tareas o arrancar `plan-refine` sin plan. **Lo reemplaza:** `--check` consulta sin escribir; el pase se declara `- Pase a cert|prod: <corte>` y `plan-refine` exige plan existente. **Qué hacer:** comprobá con `--check` y pasá `--input docs/plans/PPP-plan-<slug>.md` si falta el plan.
+- **Deja de valer:** exigir unidad aunque el workspace elija editar en su checkout. **Lo reemplaza:** `aw set-edit-mode in-place|unit`; `> Aislamiento: unidad` prevalece. In-place prueba y commitea sólo rutas aprobadas, conserva cambios ajenos y rechaza otra rama o HEAD. **Qué hacer:** elegí `in-place` expresamente y aprobá sólo las rutas propias.
+- **Deja de valer:** fallar en `aw reset` o `aw discard` por una unidad integrada cuya carpeta ya no existe. **Lo reemplaza:** el retiro verifica recibo, inventario git y rama destino antes de revertir el rango atribuible. **Qué hacer:** ejecutalo desde el destino limpio y atendé la negativa si la atribución no es única.
+- **Deja de valer:** cargar todo el CLI en hooks fuera de un workspace o necesitar un hook `prompt` extra para `PostCompact`. **Lo reemplaza:** entrada ligera y reanudación en `resume-summary`; `sql-mutation-guard` conserva su alcance. **Qué hacer:** reinstalá hooks gestionados con `aw self install-hooks`.
+- **Deja de valer:** que `aw doctor` dé por sana la ausencia de hosts o falle sólo por un host `ready` sin binario. **Lo reemplaza:** distingue ausencia, contradicción y cobertura omitida; avisa de `dist/` alterado y upstream a PROD. **Qué hacer:** consultá sus avisos y el remedio de upstream indicado.
+- **Deja de valer:** cerrar con CHECKPOINT incompleto, `## Origin` vacío o criterios sin marcar y sin razón. **Lo reemplaza:** el cierre se niega salvo `--force` o `--abandon`; el CHECKPOINT registra el estado git real por fuente y el Recorrido termina en «Siguiente paso: ninguno». **Qué hacer:** completá origen, criterios y checkpoint; usá `--abandon` sólo para abandonar.
+- **Deja de valer:** crear HISTORY sólo al cerrar, desordenar sus filas o volver a usar un número tras `discard`. **Lo reemplaza:** la fila nace al crear, se ordena por código y se conserva al retirar; `aw history reconcile` muestra discrepancias y `aw workspace-migrate --renumber` resuelve colisiones. **Qué hacer:** reconciliá HISTORY y renumerá la sesión local si comparte número.
+- **Deja de valer:** inferir que toda sesión sin `.closed` está activa. **Lo reemplaza:** `aw session-pause --code <NNN>` y `session-close --abandon` marcan estados propios; retomar reactiva una pausada y una abandonada exige `--reopen`. **Qué hacer:** marcá el estado expresamente y usá `--reopen` para una abandonada.
+- **Deja de valer:** que el cierre deje todo el mínimo sólo en la carpeta efímera o commitee el índice ajeno. **Lo reemplaza:** archiva CHECKPOINT, DECISION, BACKLOG, SQL y evidencia consentida en `.workflow/archive/`; `aw workspace-commit` prepara y aplica con aprobación un commit por rutas, sin push. **Qué hacer:** inspeccioná la propuesta de cierre o export y aprobá el digest si querés el commit; para evidencia temporal usá `--with-evidence`.
+- **Deja de valer:** resolver un workspace por el cwd o por un marcador de `$HOME` dentro de una fuente. **Lo reemplaza:** el registro de hubs en `~/.workflow/hubs.json` resuelve al hub dueño; con varios exige `--workspace <ruta>`. La fuente no recibe `.workflow/` ni cambios de `.gitignore`. **Qué hacer:** corré una vez `aw` en el hub o indicá `--workspace` cuando haya ambigüedad.
+- **Deja de valer:** preparar una operación en un workspace y aplicarla en otro con el mismo contenido. **Lo reemplaza:** las propuestas de dos tiempos sellan la raíz real; `--workspace` selecciona la carpeta exacta y un cambio de raíz se rechaza. **Qué hacer:** aplicá desde el mismo hub o especificá su ruta con `--workspace`.
+- **Deja de valer:** compartir la rama `aw/<sesión>` entre hubs o perder unidades al mover el hub. **Lo reemplaza:** las unidades nuevas usan `aw/<hash8>/<carpeta>`; custodia y claves previas reconocen las antiguas. `aw workspace-move` mueve o repara rutas. **Qué hacer:** mudá con `aw workspace-move <destino>` o repará un movimiento manual con `--repair`.
+- **Deja de valer:** tomar `development` como rama de trabajo implícita para `worktree ensure`, `integrate` y git-flow. **Lo reemplaza:** se exige la rama del documento o una rama de trabajo declarada; `aw sources` informa si falta. **Qué hacer:** registrá la rama con `aw set-working-branch <alias> <rama>`.
+- **Deja de valer:** dejar carpetas huérfanas recuperables y ramas `aw/*` integradas tras liberar, o exigir reabrir la sesión para liberar. **Lo reemplaza:** `release`/`reclaim` terminan removes partidos, retienen archivos propios y borran por CAS sólo ramas contenidas en su base. `release` e `integrate` aceptan sesiones cerradas. **Qué hacer:** usá `aw worktree reclaim` para restos y resolvé por separado lo retenido.
+- **Deja de valer:** que una unidad con dependencias idénticas deba reinstalarlas o que el retiro borre indiscriminadamente `node_modules`. **Lo reemplaza:** la unidad enlaza las dependencias de la fuente si coinciden manifiesto y lockfile; libera sólo ese enlace verificado. **Qué hacer:** no ejecutes `npm ci` en una unidad enlazada: modificaría las dependencias de la fuente.
+- **Deja de valer:** tratar unidades vivas de multiroot como sobrantes o bloquear el cierre final por unidades vacías o preservadas. **Lo reemplaza:** la reparación quita sólo rutas sobrantes; el cierre final libera unidades vacías y preservadas y retiene las que tienen trabajo no acreditado. **Qué hacer:** consultá el motivo de retención antes de integrar o liberar.
+- **Deja de valer:** mostrar ayuda del padre para todo subverbo, ofrecer `--overwrite` en exportaciones que no lo aceptan o admitir juntos `project-md-upsert --read --init`. **Lo reemplaza:** ayuda por subverbo desde el contrato de flags, con `Usage` y opciones excluyentes; la ayuda global anuncia `--workspace`. **Qué hacer:** consultá `<comando> <subverbo> --help` y elegí sólo `--read` o `--init`.
+
+### Added
+
+- **`aw doc-branch show|set`, `aw add-source` y `aw set-pipeline`.** Registran ramas por documento, rutas locales y build/test por fuente.
+- **`aw flow submit --check`, `aw flow retract` y `aw flow recover --reinfer-batch`.** Comprueban sin gastar intento, retiran señales no consumidas y re-infieren un lote con aprobación.
+- **`aw set-edit-mode in-place|unit` y `aw set-exception-branch`.** Declaran la edición del checkout y excepciones de rama.
+- **`aw history reconcile`, `aw session-pause` y `aw sessions --sweep`.** Consultan discrepancias, pausan sesiones y limpian residuos del runtime.
+- **`aw workspace-commit` y `aw workspace-init --untrack`.** Preparan commits acotados y dejan de trackear archivos excluidos sin borrarlos.
+- **`aw workspace-move` y registro de hubs.** Resuelven fuentes compartidas y reparan rutas tras una mudanza.
+- **`export-scripts --catalog` y bundles con `bundle.json`.** Contrastan el catálogo en sólo lectura y registran el origen del SQL.
+- **Pases y specs reemplazadas.** `## Handoff operativo` admite `- Pase a cert|prod: <corte>`; `superseded` retira la spec de pendientes.
+
+### Changed
+
+- **El estado de corrida escribe v15.** Continúa v11, v12, v13 y v14; v7–v10 sólo se leen y salen por `aw flow restart`.
+- **El cierre acredita pruebas, revisiones y commits por lote.** La validación final toma build y tests del pipeline o del plan.
+- **Los números y sellos de publicación permanecen estables.** `export-* apply` conserva el número aprobado; los sellos de texto toleran LF/CRLF.
+- **La doctrina y la ayuda siguen el binario.** `> Cierre:` lleva evidencia, `> Assurance:` el veredicto; CHASSIS incluye reglas de host y las guías redirigen sobres desde archivos.
+- **El CLI conserva su catálogo propio de skills recomendadas.** El marketplace contrasta una captura del catálogo; el CLI no carga su README.
+- **`aw doctor` distingue cobertura omitida de fallo.** Comprueba integridad de `dist/` y avisa de upstreams a PROD.
+- **Dependencias de mantenimiento.** Vitest 5.0.2 y Vite 8.3.1 son de desarrollo; smol-toml 1.9.0 normaliza tablas de prototipo nulo y ws 8.22.0 sigue transitiva.
+
+### Fixed
+
+- **`aw reset` y `aw discard` reconocen unidades integradas y liberadas.** Comprueban recibo y destino antes de revertir.
+- **`fix-git` resuelve bajas, binarios y archivos adaptados.** Aplica sólo las rutas propuestas y conserva los finales de línea de Windows.
+- **`merge-state` informa fuentes ilegibles.** Devuelve `unreadable` y `any_merging: null` en vez de descartar merges sin certeza.
+- **Design comprueba revisiones y renditions.** Una tercera revisión simple sigue la ruta simple y una revisión editada falla por digest.
+- **El bloque compartido conserva fuentes.** Rutas locales quedan fuera del bloque versionado y sus dos espejos se actualizan juntos.
+- **Las unidades se liberan sin arrastrar dependencias.** Se recuperan carpetas limpias de removes partidos y se conserva el trabajo propio.
+- **El commit in-place se reconoce aunque queden cambios ajenos.** Tras una interrupción, sólo impiden reconocerlo cambios pendientes en rutas de la propuesta.
+- **La ayuda conserva `Usage` y anuncia `--workspace`.** `context-budget` puede medir el bundle desde un checkout sin hub.
+- **Una sesión pausada conserva sus reservas.** `aw claims` ya no ofrece recuperarlas; al retomarla, la reserva sigue suya. Las de una sesión abandonada siguen siendo recuperables.
+- **El cierre puede copiar la evidencia y commitearla en la misma decisión.** La copia versionada entra en el commit final del workspace.
+
 ## [25.8.0] — 2026-09-27
 
 La guarda de SQL distingue los servidores PostgreSQL registrados en `aw self mcp` y revisa el SQL que ejecutan las funciones remotas. Las corridas acreditan cada lote con prueba de su propio checkout y dejan registrar su ciclo de vida completo. Los comandos rechazan los flags desconocidos, la salida humana puede ser ASCII y el wrapper instalado de design usa el protocolo real de `aw capability` en cada host.

package/README.md

@@ -24,7 +24,7 @@ Workline has three layers plus a permanent `docs/` zone:
 - **Layer 2 · Loops** — the AI runs them whole: `spec-refine-loop` · `plan-new-loop` · `plan-refine-loop` · `plan-exec-loop` · `quick-loop` — all heirs of the shared engine `skills/w/loops/CHASSIS.md` (+ `CODE-POLICIES.md` for the code-editing loops). Each loop is a **persistent goal** that runs until its success criteria are green (verification-first); gap-driven, with **structured-choice** lifecycle control (compact/close — the host's own question surface where one is reachable, **labeled markdown** where none is; the binding per host is stamped into what gets installed) and resumable `CHECKPOINT`.
 - **Layer 3 · Sessions + artifacts** — internal, ephemeral process state under `.workflow/sessions/` (`SESSION` · `CHECKPOINT` · `BACKLOG` · `SCRIPTS.sql` · `ANALYSIS-FILE` · `CONCLUSIONS` · `DECISION` · …). Sessions are slug-named folders, created by loops, never by the user.
 
-**Pluggable capabilities.** Loops compose capability **roles** (`design`, `sql`, `git`, `research`, `diagrams`, `overview`); the concrete skill bound to each role is resolved via `.workflow/skills.toml` (cascade: built-in default → `~/.workflow/skills.toml` → workspace). Inspect bindings with `aw skills` (advisory: it also warns when a bound skill is not installed in the standard skill roots — the binding itself is not auto-validated). Code/testing/writing conventions **and tool authoring** (`creating-tools`) are **not** roles — they're ambient skills the host auto-applies when present, independent of Workline. Per-source launch scripts live under `.workflow/launch/` (machine-specific, gitignored); created tools live under `docs/tools/`.
+**Capacidades propias.** `design` conserva su floor y operaciones; `overview` orienta sobre Workline. Sólo estos roles propios se resuelven por `skills.toml` (default → global → workspace). `off` conserva el contrato por operación y los bindings históricos ajenos se avisan sin usar ni reescribir. `aw skills --detail` informa únicamente capacidades propias y wrappers; el host puede aportar otras ayudas sin preregistro ni dependencia para SPEC, PLAN y QUICK. Para instalar o retirar skills ajenas, usá el host o marketplace que elijas. Los scripts de arranque por fuente viven en `.workflow/launch/` y las herramientas creadas en `docs/tools/`.
 
 **Invariants.** No auto-export (only `export-*` writes `docs/`); the spec and plan are documents, not artifacts; DB scripts-only (never executes DML/DDL); git-safe (verifies the per-source working branch before edits; proposes commits).
 
@@ -93,6 +93,8 @@ The bundle's internal manuals (`loops/*/LOOP.md`, `roles/*/ROLE.md`, `exports/*/
 
 Opt-out flags: `--skill-only`, `--no-commands`, `--no-hooks`. Override the source with `--from /path/to/skills/w`. Other flags: `--confirm-all` (required with `--target all`), `--keep-cache`, `--force`, `--dry-run`.
 
+To add the `UserPromptSubmit` branch advisory to an existing Claude or Kimi installation, rerun `aw self install-hooks --target claude` or `--target kimi`; updating the CLI alone does not reinstall hooks. Editing remains protected by `branch-check` on all managed hosts.
+
 **What `--target all` means.** Every **host** — never the shared skills dirs, which are install destinations rather than hosts and are reached explicitly (`--target agents`). `install` and `uninstall` use the same set, so the round trip matches: what `all` installs is what `all` removes. (`oz` installs into `~/.agents/skills`, so that directory is still covered under `all` through its host.)
 
 ### Support levels and how long a verification is worth
@@ -125,7 +127,6 @@ Running `agent-workflow` (or `aw`) with no arguments opens the tab-based TUI:
 | **Workline** | Per-host administration of the bundled `w` SKILL (install / reinstall / uninstall, `hooks armed` state) plus a compact flows overview. |
 | **Project** | Workspace sources, branches and git-flow actions. |
 | **MCP** | Tools PostgreSQL de solo lectura. `mcp-connections.json` v2 es la única autoridad de alias, provider y variable DSN: registrá con `aw self mcp use-env --name alpha --dsn-var ALPHA_DATABASE_URL`. La TUI instala descriptores absolutos en user scope; `aw mcp setup` conserva además el modo workspace portable dependiente de `PATH`. Cada host muestra configuración, launchability, recarga pendiente y carga observada; Codex queda opcional porque existe el fallback local `aw tool call`. |
-| **Skills** | Standalone third-party skills manager (skills.sh model): the source is an `owner/repo`, a git URL (`#ref` supported) or an absolute local path, and **the skill is chosen by its path inside that source** — nested under another skill included, several leaves at once in one proposal — with an explicitly declared path validated against the source even when the walk did not list it. Installing materializes a canonical copy in `~/.agents/skills/<name>` (the open-standard dir every non-Claude host scans) plus a symlink replica in `~/.claude/skills/<name>` (copy fallback where symlinks are unavailable) and a copy in `~/.gemini/skills/<name>`. Seeded with a **curated catalog** (`SKILL_CATALOG`): every reviewed entry carries its verdict — keep, conditional, repair/replace, candidate or withdrawn — plus the condition that makes it pertinent, its known limits and the revision the review inspected. The habitual set the list opens on is derived from it, so withdrawing an entry keeps its reason readable and touches no file; reviewed alternatives stay documented as reserves without being offered. It mirrors the companion marketplace README for the entries that list names — the verdicts, conditions and reserves live here. **Every change goes through one door:** a proposal is prepared and previewed (its exact set, sources, destinations and effects), and applying it sends that proposal's own digest as the approval — a source that moved, one more destination or a different byte produces another digest and has to be approved again. Applying keeps a per-destination backup and a journal next to the registry (outside every host discovery root), so a failure compensates in reverse order and an interrupted run is detected on reopen, offering to restore the previous state. The result is reported per destination, with its verification stated separately: what is checked is the bytes this manager wrote in the locations it manages — never that a host reloaded anything, and never that a catalog filter or a `skills.toml` `off` switched a skill off everywhere. |
 | **Config** | Namespace, host-targeting preferences, and the workspace branch defaults (written to the WORKSPACE block). |
 
 ### PostgreSQL MCP y fallback local
@@ -181,7 +182,9 @@ Workspace artifacts live under `.<namespace>/`. Resolution order (first match wi
 - `sessions` / `session-create --type <research|refine|exec|quick>` / `session-close` / `session-resume` / `session-artifacts` — internal session lifecycle (used by the loops).
 - `checkpoint-read` / `checkpoint-write` — `CHECKPOINT.md` handling.
 - `flow <advance|submit>` — the direction engine: `advance` applies every consecutive `cli`-owned transition of a flow run and returns the directive of the first non-deterministic frontier; `submit` takes the response as JSON via stdin (`--approval <digest>` for effects) and keeps advancing.
-- `sources` / `check-branch` / `set-working-branch` / `set-qa-branch` — multi-source git-safety (per-source base / working / QA branches).
+- `sources` / `check-branch` / `set-working-branch` / `set-qa-branch` / `set-exception-branch` — multi-source git-safety (per-source base / working / QA / exception branches).
+- `set-edit-mode in-place|unit` — declares checkout editing or isolated units in the WORKSPACE block; plans can require `> Aislamiento: unidad`.
+- `doc-branch show|set` — propone y asocia una rama de trabajo por documento y fuente, heredada por sus planes; `show` no modifica nada.
 - `git-flow <sync|to-dev|to-qa|to-prod> [--source|--all] [--target] [--dry-run]` — run the per-source branch flows (sync working ← base, promote to dev/QA/prod) with conflict-pause; `--all` processes every source and reports each one. Also surfaced as Project-tab actions.
 - `release-data` — corpus reader backing the `export-*` skills.
 - `self install-skill` / `self doctor` / `self update` / `mcp` — CLI maintenance.

package/dist/adapters/git-cli.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { appendFile, lstat, readFile, readlink } from "node:fs/promises";
 import { resolve } from "node:path";
+import { checkSafeRelativePath } from "../domain/safe-path.js";
 /**
  * Non-interactive git env: `GIT_TERMINAL_PROMPT=0` makes git FAIL FAST instead of
  * blocking on a terminal credential prompt (a push against a repo needing creds
@@ -49,8 +50,8 @@ export class GitCliAdapter {
         return new Error(`git ${label} failed in ${repoPath}: ${stderr.trim()}`);
     }
     /** Run git, throwing `git <label> failed in <repo>: <stderr>` on non-zero exit. */
-    async mustRun(label, args, repoPath) {
-        const result = await this.process.run("git", args, this.opts(repoPath));
+    async mustRun(label, args, repoPath, extra = {}) {
+        const result = await this.process.run("git", args, this.opts(repoPath, extra));
         if (result.code !== 0) {
             throw this.failed(label, repoPath, result.stderr);
         }
@@ -66,7 +67,22 @@ export class GitCliAdapter {
     }
     async isGitRepo(repoPath) {
         const result = await this.process.run("git", ["rev-parse", "--git-dir"], this.opts(repoPath));
-        return result.code === 0;
+        if (result.code === 0)
+            return true;
+        if (/not a git repository/i.test(result.stderr))
+            return false;
+        throw this.failed("rev-parse", repoPath, result.stderr);
+    }
+    async readConfig(repoPath, key) {
+        const result = await this.process.run("git", ["config", "--get", key], this.opts(repoPath));
+        if (result.code === 1)
+            return null;
+        if (result.code !== 0)
+            throw this.failed(`config --get ${key}`, repoPath, result.stderr);
+        return result.stdout.trim();
+    }
+    async writeLocalConfig(repoPath, key, value) {
+        await this.mustRun(`config --local ${key}`, ["config", "--local", key, value], repoPath);
     }
     async currentBranch(repoPath) {
         const result = await this.process.run("git", ["rev-parse", "--abbrev-ref", "HEAD"], this.opts(repoPath));
@@ -109,11 +125,18 @@ export class GitCliAdapter {
      * Git's output is hashed as BYTES and never decoded: a digest that has to be
      * reproducible cannot depend on a text encoding it does not need.
      */
-    async checkoutFingerprint(repoPath) {
+    async checkoutFingerprint(repoPath, excluded) {
+        const scope = excluded === undefined ? [] : [".", ...excluded.map((p) => `:(exclude)${p}`)];
         const [patch, status, untracked] = await Promise.all([
-            this.mustRunBinary("diff for checkout fingerprint", ["diff", "--binary", "--full-index", "--no-ext-diff", "HEAD", "--"], repoPath),
-            this.mustRunBinary("status for checkout fingerprint", ["status", "--porcelain=v2", "-z"], repoPath),
-            this.mustRunBinary("untracked files for checkout fingerprint", ["ls-files", "--others", "--exclude-standard", "-z"], repoPath),
+            this.mustRunBinary("diff for checkout fingerprint", ["diff", "--binary", "--full-index", "--no-ext-diff", "HEAD", "--", ...scope], repoPath),
+            this.mustRunBinary("status for checkout fingerprint", ["status", "--porcelain=v2", "-z", ...(excluded === undefined ? [] : ["--", ...scope])], repoPath),
+            this.mustRunBinary("untracked files for checkout fingerprint", [
+                "ls-files",
+                "--others",
+                "--exclude-standard",
+                "-z",
+                ...(excluded === undefined ? [] : ["--", ...scope]),
+            ], repoPath),
         ]);
         const hash = createHash("sha256");
         hash.update("patch\0", "utf8");
@@ -121,6 +144,16 @@ export class GitCliAdapter {
         hash.update("status\0", "utf8");
         hash.update(status.stdout);
         await this.hashUntracked(hash, repoPath, untracked.stdout);
+        if (excluded !== undefined) {
+            // hash-object alone follows symlinks and omits execute bits. A no-index
+            // patch includes both Git's file mode and a symlink's destination.
+            for (const path of nulSeparated(untracked.stdout).sort()) {
+                const patch = await this.process.runBinary("git", ["diff", "--no-index", "--binary", "--no-ext-diff", "--", "/dev/null", path], this.opts(repoPath));
+                if (patch.code !== 0 && patch.code !== 1)
+                    throw this.failed("untracked state", repoPath, patch.stderr.toString());
+                hash.update(patch.stdout);
+            }
+        }
         return `sha256:${hash.digest("hex")}`;
     }
     /**
@@ -329,6 +362,17 @@ export class GitCliAdapter {
             throw err;
         }
     }
+    async mergeBases(repoPath) {
+        const result = await this.process.run("git", ["merge-base", "--all", "HEAD", "MERGE_HEAD"], this.opts(repoPath));
+        if (result.code === 1)
+            return [];
+        if (result.code !== 0)
+            throw this.failed("merge-base --all", repoPath, result.stderr);
+        return result.stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
     async conflictedFiles(repoPath) {
         const result = await this.process.run("git", ["diff", "--name-only", "--diff-filter=U"], this.opts(repoPath));
         if (result.code !== 0) {
@@ -356,9 +400,9 @@ export class GitCliAdapter {
         const hashes = new Map();
         if (listed.code === 0) {
             for (const line of listed.stdout.split("\n")) {
-                const match = /^\d+ ([0-9a-f]{40}) ([123])\t/.exec(line);
-                if (match?.[1] && match[2])
-                    hashes.set(match[2], match[1]);
+                const match = /^(\d{6}) ([0-9a-f]{40}|[0-9a-f]{64}) ([123])\t/.exec(line);
+                if (match?.[1] && match[2] && match[3])
+                    hashes.set(match[3], { mode: match[1], hash: match[2] });
             }
         }
         const base = await this.readStage(repoPath, hashes.get("1"));
@@ -373,12 +417,41 @@ export class GitCliAdapter {
             binary: present.some((s) => s.content === null),
         };
     }
-    async readStage(repoPath, hash) {
-        if (hash === undefined)
-            return { hash: null, content: null, bytes: 0 };
+    async indexEntry(repoPath, path) {
+        const listed = await this.mustRun(`ls-files -s ${path}`, ["ls-files", "-s", "--", path], repoPath);
+        const match = /^(\d{6}) ([0-9a-f]{40}|[0-9a-f]{64}) 0\t/.exec(listed.stdout);
+        return match?.[1] && match[2] ? { mode: match[1], hash: match[2] } : null;
+    }
+    async isWorktreeCleanPath(repoPath, path) {
+        const result = await this.process.run("git", ["diff", "--quiet", "--", path], this.opts(repoPath));
+        if (result.code === 0)
+            return true;
+        if (result.code === 1)
+            return false;
+        throw this.failed(`diff --quiet ${path}`, repoPath, result.stderr);
+    }
+    async readBlob(repoPath, hash) {
+        const stage = await this.readStage(repoPath, { hash, mode: "100644" });
+        return { content: stage.content, bytes: stage.bytes };
+    }
+    async hashBlob(repoPath, content) {
+        const result = await this.mustRun("hash-object", ["hash-object", "-w", "--no-filters", "--stdin"], repoPath, { stdin: content });
+        return result.stdout.trim();
+    }
+    async setIndexEntry(repoPath, path, mode, hash) {
+        await this.mustRun(`update-index ${path}`, ["update-index", "--add", "--cacheinfo", `${mode},${hash},${path}`], repoPath);
+        await this.mustRun(`checkout-index ${path}`, ["checkout-index", "-f", "--", path], repoPath);
+    }
+    async removeIndexEntry(repoPath, path) {
+        await this.mustRun(`update-index --force-remove ${path}`, ["update-index", "--force-remove", "--", path], repoPath);
+    }
+    async readStage(repoPath, entry) {
+        if (entry === undefined)
+            return { hash: null, content: null, bytes: 0, mode: null };
+        const { hash, mode } = entry;
         const result = await this.process.runBinary("git", ["cat-file", "-p", hash], this.opts(repoPath));
         if (result.code !== 0)
-            return { hash, content: null, bytes: 0 };
+            return { hash, content: null, bytes: 0, mode };
         // A NUL byte is the same heuristic git itself uses to call a blob binary.
         const binary = result.stdout.includes(0);
         // The size is the bytes git stored, which a decoded blob no longer measures.
@@ -386,6 +459,7 @@ export class GitCliAdapter {
             hash,
             content: binary ? null : result.stdout.toString("utf8"),
             bytes: result.stdout.length,
+            mode,
         };
     }
     async stagePath(repoPath, path) {
@@ -408,6 +482,71 @@ export class GitCliAdapter {
             parents: await this.parentsOf(repoPath, after),
         };
     }
+    async commitPaths(repoPath, message, paths) {
+        if (paths.length === 0 ||
+            paths.some((path) => path.length === 0 ||
+                path.startsWith("-") ||
+                path.includes("\0") ||
+                !checkSafeRelativePath(path).ok)) {
+            throw new Error("git commitPaths exige rutas relativas explícitas no vacías");
+        }
+        const before = await this.headSha(repoPath);
+        await this.mustRun("add -- paths", ["add", "--", ...paths], repoPath);
+        await this.mustRun("commit --only -- paths", ["commit", "--only", "-m", message, "--", ...paths], repoPath);
+        const after = await this.headSha(repoPath);
+        if (after === null || after === before)
+            throw new Error(`git commitPaths no movió HEAD en ${repoPath}`);
+        return {
+            branch: (await this.currentBranch(repoPath)) ?? null,
+            before,
+            after,
+            parents: await this.parentsOf(repoPath, after),
+        };
+    }
+    async dirtyPaths(repoPath) {
+        const changes = await this.localChanges(repoPath);
+        const byPath = new Map();
+        for (const change of changes) {
+            const files = [change.path, ...(change.from === null ? [] : [change.from])];
+            for (const path of files) {
+                const absolute = resolve(repoPath, path);
+                let bytes = "deleted";
+                try {
+                    const stats = await lstat(absolute);
+                    bytes = stats.isSymbolicLink() ? await readlink(absolute) : await readFile(absolute);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                const digest = createHash("sha256")
+                    .update(change.code)
+                    .update("\0")
+                    .update(change.head_mode ?? "")
+                    .update("\0")
+                    .update(change.worktree_mode ?? "")
+                    .update("\0")
+                    .update(bytes)
+                    .digest("hex");
+                byPath.set(path, digest);
+            }
+        }
+        return [...byPath]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([path, digest]) => ({ path, digest }));
+    }
+    async commitInfo(repoPath, sha) {
+        const [message, changed, parents] = await Promise.all([
+            this.mustRun("show --format=%B", ["show", "-s", "--format=%B", sha], repoPath),
+            this.mustRun("diff-tree --name-only", ["diff-tree", "--root", "--no-commit-id", "-r", "-z", "--name-only", sha], repoPath),
+            this.parentsOf(repoPath, sha),
+        ]);
+        return {
+            message: message.stdout.trimEnd(),
+            paths: changed.stdout.split("\0").filter(Boolean).sort(),
+            parents,
+        };
+    }
     async head(repoPath) {
         return this.headSha(repoPath);
     }
@@ -455,6 +594,65 @@ export class GitCliAdapter {
             return [];
         return result.stdout.split("\0").filter((p) => p.length > 0);
     }
+    async treeEntries(repoPath, rev) {
+        const result = await this.mustRun("ls-tree", ["ls-tree", "-r", "-z", rev], repoPath);
+        return result.stdout
+            .split("\0")
+            .filter(Boolean)
+            .map((item) => {
+            const match = /^(\d+) blob ([0-9a-f]+)\t(.+)$/s.exec(item);
+            if (!match?.[1] || !match[2] || !match[3])
+                throw new Error(`entrada ls-tree ilegible en ${repoPath}`);
+            return { mode: match[1], hash: match[2], path: match[3] };
+        });
+    }
+    async hashWorktreePath(repoPath, path, symlink) {
+        if (symlink) {
+            const target = await readlink(path);
+            return (await this.mustRun("hash-object", ["hash-object", "--stdin"], repoPath, { stdin: target })).stdout.trim();
+        }
+        return (await this.mustRun("hash-object", ["hash-object", "--no-filters", path], repoPath)).stdout.trim();
+    }
+    async worktreeFileMode(path) {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            return "120000";
+        if (!stat.isFile())
+            throw new Error(`no es un archivo recuperable: ${path}`);
+        return stat.mode & 0o111 ? "100755" : "100644";
+    }
+    async ignoredOutsideIndex(repoPath, treePath, relativePath) {
+        const gitDir = (await this.mustRun("rev-parse --absolute-git-dir", ["rev-parse", "--absolute-git-dir"], repoPath)).stdout.trim();
+        const result = await this.process.run("git", [
+            `--git-dir=${gitDir}`,
+            `--work-tree=${treePath}`,
+            "check-ignore",
+            "--no-index",
+            "-q",
+            "--",
+            relativePath,
+        ], this.opts(repoPath));
+        if (result.code !== 0 && result.code !== 1)
+            throw this.failed("check-ignore", repoPath, result.stderr);
+        return result.code === 0;
+    }
+    async ignoredInSource(repoPath, relativePath) {
+        const result = await this.process.run("git", ["check-ignore", "--no-index", "-q", "--", relativePath], this.opts(repoPath));
+        if (result.code !== 0 && result.code !== 1)
+            throw this.failed("check-ignore", repoPath, result.stderr);
+        return result.code === 0;
+    }
+    async excludePattern(repoPath, pattern) {
+        const exclude = (await this.mustRun("rev-parse --git-path", ["rev-parse", "--git-path", "info/exclude"], repoPath)).stdout.trim();
+        const path = resolve(repoPath, exclude);
+        const existing = await readFile(path, "utf8").catch((err) => {
+            if (err.code === "ENOENT")
+                return "";
+            throw err;
+        });
+        if (!existing.split(/\r?\n/).includes(pattern))
+            await appendFile(path, `${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${pattern}\n`);
+    }
     async operationState(repoPath) {
         // git's own pseudo-refs are the record of an interrupted operation, and asking
         // git for them keeps this adapter needing only one binary: a `test -d` on
@@ -507,8 +705,8 @@ export class GitCliAdapter {
     async setRef(repoPath, ref, sha) {
         return this.attempt("update-ref", ["update-ref", ref, sha], repoPath);
     }
-    async deleteRef(repoPath, ref) {
-        return this.attempt("update-ref -d", ["update-ref", "-d", ref], repoPath);
+    async deleteRef(repoPath, ref, expectedOld) {
+        return this.attempt("update-ref -d", ["update-ref", "-d", ref, ...(expectedOld ? [expectedOld] : [])], repoPath);
     }
     /** Run git and report whether it agreed, with its own words when it did not. */
     async attempt(label, args, cwd) {
@@ -547,6 +745,16 @@ export class GitCliAdapter {
             .map((line) => line.trim())
             .filter((line) => line.length > 0);
     }
+    async upstreamBranch(repoPath, branch) {
+        const result = await this.mustRun("for-each-ref upstream", ["for-each-ref", "--format=%(upstream)", `refs/heads/${branch}`], repoPath);
+        return result.stdout.trim() || null;
+    }
+    async readAtRef(repoPath, ref, path) {
+        const result = await this.process.run("git", ["show", `${ref}:${path}`], this.opts(repoPath));
+        if (result.code !== 0)
+            return null;
+        return result.stdout;
+    }
     async originFetchRefspecs(repoPath) {
         const result = await this.process.run("git", ["config", "--get-all", "remote.origin.fetch"], this.opts(repoPath));
         // `config --get-all` exits 1 when the key is unset: no refspec, not a failure.