@tacuchi/agent-workflow-cli 25.7.0 → 25.9.0

package/CHANGELOG.md

@@ -12,6 +12,116 @@ 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.
 
+## [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.
+
+### Contrato
+
+- **Deja de valer:** que la guarda `sql-mutation-guard` bloquee en todo servidor lo que MySQL leería distinto. Hoy bloquea un `#` fuera de un literal (los operadores `#>`, `#>>` y `#-` de jsonb y el XOR `#`), un backtick, una `\` pegada a una comilla (como `'\'`) y un `/*! … */`. **Lo reemplaza:** la guarda lee como PostgreSQL al servidor cuyo nombre está registrado en `aw self mcp`, porque lo sirve `aw mcp serve-db`. Ahí esas cuatro formas pasan y el dollar-quoting se reconoce como literal. El servidor no registrado, o uno cuyo registro no se puede leer, se sigue leyendo también como MySQL: siguen bloqueadas las cuatro formas y además se bloquea todo literal `$…$`, como `SELECT $$texto$$`, que MySQL no lee como literal. El mensaje de bloqueo suma la línea `Motor`. **Qué hacer:** contra un servidor de Workline no hace falta reescribir nada. Contra otro servidor, reemplazá el `$$…$$` por `'…'`, o registrá el servidor con `aw self mcp` si lo sirve `serve-db`.
+- **Deja de valer:** que un `SELECT` que llama a `dblink_exec`, `dblink`, `dblink_send_query`, `dblink_open`, `query_to_xml`, `query_to_xmlschema` o `query_to_xml_and_xmlschema` pase sin mirar el SQL que esas funciones ejecutan. **Lo reemplaza:** la llamada pasa sólo si ese SQL es un único literal `'…'` o `$…$` que lee. Ese SQL es el primer argumento de `query_to_xml*` y, en `dblink*`, el último que no es `TRUE` ni `FALSE`. Se bloquea si ese literal no lee, si el SQL no es un literal (una concatenación, un cast, `E'…'`, un argumento con nombre) o si la función se llama con un nombre `U&"…"`. **Qué hacer:** pasá el SQL como un único literal. Lo que de verdad tenga que mutar va como script a `docs/scripts/`, o por la excepción que delega la persona (`AW_SQL_GUARD_ALLOW`).
+- **Deja de valer:** acreditar con un resultado externo una acción que el CLI debe ejecutar, o cerrar un lote con una prueba reciclada o sin cambios propios de su checkout. **Lo reemplaza:** las acciones internas sólo se acreditan al correr `aw flow advance`. Cada lote exige prueba de checkout por cada fuente; la huella debe diferir de la base del lote (o del inicio de la corrida en el primero), y una prueba no puede acreditar dos lotes. La validación de fase no se puede omitir y `batch-close` no cierra sin acreditación. **Qué hacer:** corré la acción con `aw flow advance` y aportá una prueba propia de cada checkout del lote, tomada después de sus cambios.
+- **Deja de valer:** que `Refinar` cierre la sesión, que `aw session-close` deje abierta la corrida en su frontera, y que `aw session-resume --reopen` sólo borre `.closed`. **Lo reemplaza:** `Refinar` vuelve a la frontera de redacción y mantiene abierta la sesión; `session-close` termina la corrida en la frontera donde estaba, y `--reopen` reabre también la corrida para retomarla desde esa frontera o desde la última frontera humana. El estado de corrida v13 es el formato de escritura; las versiones v11 y v12 se continúan y se suben al escribir. **Qué hacer:** después de `Refinar`, avanzá con `aw flow advance`; para retomar una corrida cerrada, usá `aw session-resume --reopen` y luego `aw flow advance`.
+- **Deja de valer:** que un flag desconocido se ignore y el comando siga, incluso si después espera stdin. **Lo reemplaza:** los comandos lo rechazan con `UNKNOWN_FLAG` antes de ejecutarse. Los hooks avisan por stderr y siguen con su código de salida y stdout de siempre. **Qué hacer:** quitá el flag desconocido o usá el flag que declara el comando; `aw flow submit` recibe su sobre por stdin, no por `--file`.
+- **Deja de valer:** que `aw session-resume --reopen` salga con 0 cuando no pudo reabrir la corrida y devuelve `run_error`. **Lo reemplaza:** el comando sale con un código distinto de 0 si la corrida no se pudo reabrir. **Qué hacer:** un consumidor que trataba el código 0 como reapertura exitosa debe comprobar el código de salida.
+- **Deja de valer:** que el wrapper instalado de `design` instruya `aw capability continue` y `validate` con `--request`, y `apply` con `--plan`, o que una copia compartida fuerce el `--host` de otro agente. **Lo reemplaza:** el wrapper muestra las cuatro etapas `prepare`, `continue`, `validate` y `apply`, repitiendo `--capability design`, `--operation <op>` y todos los `--input` en cada una; la respuesta se transporta como un objeto JSON por stdin y `apply` recibe `--approval <plan.proposal.digest>`. En carpetas de HOME leídas por varios hosts el wrapper va sin binding y detecta el host al correr; Gemini/Antigravity conserva `.gemini/skills/design` con binding `gemini`, ya que no lee HOME/.agents/skills. Si `aw harness` responde `unknown`, se pasa `--host <id>` en cada etapa. **Qué hacer:** después de actualizar, reinstalá las skills con `aw self install-skill --target all --confirm-all --force` (`--confirm-all` es obligatorio para `all` y `--force` reemplaza las instalaciones existentes); consultá `aw capability --help` para el sobre completo.
+
+### Added
+
+- **`--ascii` y `AW_ASCII=1` — salida humana sólo ASCII.** La transliteración se aplica a la salida humana, la ayuda y los avisos de hooks; no cambia JSON ni protocolos. `--ascii` se rechaza con `--format json` o `--json` explícitos, y `AW_ASCII=1` se ignora bajo JSON.
+- **Prueba de checkout propia para acreditar lotes.** La validación de fase pide una prueba por fuente y compara su huella acotada con la base guardada en el inicio del lote. El digest acreditado queda asociado al lote, y las pruebas de otros lotes no se pueden reciclar.
+
+### Changed
+
+- **El ciclo de vida vuelve a entrar por inserción de tramos, no rebobinando el cursor.** `Refinar` repite desde la frontera de redacción; cerrar termina el recorrido en la frontera vigente, y reabrir agrega el tramo que permite continuar sin repetir efectos ya aplicados.
+- **Un flag desconocido se detecta según el contrato de cada comando.** Todos los comandos declaran sus flags por comando o acción; los tokens de un guion también se leen como flags, salvo `-h`, `-` y `--`.
+
+### Fixed
+
+- **La guarda de SQL no distinguía el motor del servidor ni revisaba SQL ejecutado por funciones.** Ahora toma PostgreSQL del registro de `aw self mcp`, y clasifica recursivamente el literal que ejecutan `dblink*` y `query_to_xml*`. Las excepciones al clasificar bloquean con código 2, igual que cualquier SQL no permitido.
+- **Una corrida podía cerrarse o reabrirse a medias.** `Refinar` ya no la finaliza, `session-close` registra el `finalize` en su frontera y `--reopen` reabre la corrida. Un fallo al reabrirla ya no se informa como éxito.
+- **El wrapper de design y su diagnóstico no coincidían con los hosts ni con los flags de `aw capability`.** La instalación sitúa un wrapper sin binding en raíces HOME compartidas, mantiene la copia nativa con binding `gemini` para Gemini/Antigravity y retira sólo las copias antiguas propias cuando sus lectores quedan cubiertos. `aw skills` y `aw doctor` consultan las carpetas HOME reales que lee cada host, sin contar raíces legadas o sólo de proyecto; la detección de host prioriza las marcas del agente sobre la terminal Warp.
+
 ## [25.7.0] — 2026-09-26
 
 La primera versión que declara sus contratos, y la que cierra la primera ola del lote de specs 048-058, nacido del consolidado de incidencias del 2026-09-25 sobre la 25.6.1. Entran ocho planes juntos. Una corrida de `aw flow` sobrevive a actualizar el CLI y a una escritura fallida, y sale de cualquier estado trabado por un verbo propio (`aw flow restart`, `aw flow annul`). Publicar en PROD pasa a ser un acto de la persona, git-flow deja de usar `git pull` y `fix-git` deja de cerrar un merge que trae desarrollo a una rama de trabajo. La guarda de SQL deja pasar sólo lecturas. Una escritura sin `--code` ni asociación ya no cae en la sesión de otra conversación. La gramática del plan juzga las cláusulas por lo que nombran, y ningún plan se publica sin sello en silencio. `aw self update` pasa a avisar los cambios de contrato antes de instalar, aunque no en este salto: el aviso lo ejecuta la versión instalada, y la 25.6.1 no lo trae. Suma además la memoria compartida entre hosts, `aw host-memory` y `/w:recall`, y la doctrina que admite subagentes por etapa. **Diez archivos de `skills/` cambian, uno de ellos nuevo**, así que el bundle instalado ya no es el de 25.6.0. **Ningún recorrido cambia**: los cinco son idénticos a los de la 25.6.1.

package/README.md

@@ -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
@@ -181,7 +183,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
@@ -9,6 +10,24 @@ import { resolve } from "node:path";
  */
 /** Stands in for the blob id of an untracked path git cannot hash; never a real one. */
 const UNHASHABLE_BLOB = "unhashable";
+const DELETED_BLOB = "deleted";
+/** `ls-files -s` entries of mode 160000, by path: the commit each submodule is pinned at. */
+function gitlinksOf(staged) {
+    const gitlinks = new Map();
+    for (const entry of nulSeparated(staged)) {
+        const tab = entry.indexOf("\t");
+        const [mode, object] = entry.slice(0, tab).split(" ");
+        if (mode === "160000" && object !== undefined)
+            gitlinks.set(entry.slice(tab + 1), object);
+    }
+    return gitlinks;
+}
+function nulSeparated(bytes) {
+    return bytes
+        .toString("utf8")
+        .split("\0")
+        .filter((entry) => entry.length > 0);
+}
 function nonInteractiveGitEnv() {
     const env = {};
     for (const [key, value] of Object.entries(process.env)) {
@@ -31,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);
         }
@@ -48,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));
@@ -91,24 +125,103 @@ 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");
         hash.update(patch.stdout);
         hash.update("status\0", "utf8");
         hash.update(status.stdout);
-        const paths = untracked.stdout
-            .toString("utf8")
-            .split("\0")
-            .filter((path) => path.length > 0)
-            .sort();
+        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")}`;
+    }
+    /**
+     * The content of the tree under `root` alone, without the excluded subpaths.
+     *
+     * `checkoutFingerprint` measures the whole repository relative to HEAD, so in a
+     * hub a neighbouring project moves it, and so does a commit or a `git add` that
+     * changes no byte under `root`. This one is what a batch is compared against:
+     * every path under `root` git tracks or would track, each with the blob id of
+     * its bytes on disk — so only what the files hold decides whether they changed.
+     */
+    async scopedFingerprint(root, excluded) {
+        const pathspec = ["--", ".", ...excluded.map((path) => `:(exclude)${path}`)];
+        const [listed, removed, staged] = await Promise.all([
+            this.mustRunBinary("paths for scoped fingerprint", ["ls-files", "-z", "--cached", "--others", "--exclude-standard", ...pathspec], root),
+            this.mustRunBinary("deleted paths for scoped fingerprint", ["ls-files", "-z", "--deleted", ...pathspec], root),
+            this.mustRunBinary("index for scoped fingerprint", ["ls-files", "-z", "-s", ...pathspec], root),
+        ]);
+        const deleted = new Set(nulSeparated(removed.stdout));
+        const paths = [...new Set(nulSeparated(listed.stdout))].sort();
+        // A submodule is a directory git records by commit: its entry stands for its
+        // content, and handing it to `hash-object` would fail the whole batch. It is
+        // the commit STAGED in this repository, so work inside the submodule counts
+        // once the parent records it.
+        const gitlinks = gitlinksOf(staged.stdout);
+        const present = paths.filter((path) => !deleted.has(path) && !gitlinks.has(path));
+        const blobs = await this.blobsOf(root, present);
+        for (const [path, commit] of gitlinks)
+            blobs.set(path, `gitlink:${commit}`);
+        const hash = createHash("sha256");
         for (const path of paths) {
-            const blob = await this.process.run("git", ["hash-object", "--no-filters", "--", path], this.opts(repoPath));
+            hash.update(path, "utf8");
+            hash.update("\0", "utf8");
+            hash.update(deleted.has(path) ? DELETED_BLOB : (blobs.get(path) ?? UNHASHABLE_BLOB), "utf8");
+            hash.update("\0", "utf8");
+        }
+        return `sha256:${hash.digest("hex")}`;
+    }
+    /**
+     * The blob id of each path's bytes, in one `hash-object` when it can.
+     *
+     * A path git cannot hash, or one whose name breaks the line protocol, sends the
+     * batch to the per-path fallback, where an unhashable entry is recorded as such
+     * instead of taking the whole tree down.
+     */
+    async blobsOf(cwd, paths) {
+        const blobs = new Map();
+        if (paths.length === 0)
+            return blobs;
+        const batch = paths.some((path) => path.includes("\n"))
+            ? null
+            : await this.process.run("git", ["hash-object", "--no-filters", "--stdin-paths"], this.opts(cwd, { stdin: `${paths.join("\n")}\n` }));
+        const ids = batch?.code === 0 ? batch.stdout.trim().split("\n") : [];
+        if (ids.length === paths.length) {
+            paths.forEach((path, index) => blobs.set(path, ids[index]));
+            return blobs;
+        }
+        for (const path of paths) {
+            const blob = await this.process.run("git", ["hash-object", "--no-filters", "--", path], this.opts(cwd));
+            if (blob.code === 0)
+                blobs.set(path, blob.stdout.trim());
+        }
+        return blobs;
+    }
+    /** Each untracked path with its blob id, in a stable order. */
+    async hashUntracked(hash, cwd, listing) {
+        for (const path of nulSeparated(listing).sort()) {
+            const blob = await this.process.run("git", ["hash-object", "--no-filters", "--", path], this.opts(cwd));
             hash.update("untracked\0", "utf8");
             hash.update(path, "utf8");
             hash.update("\0", "utf8");
@@ -119,7 +232,6 @@ export class GitCliAdapter {
             hash.update(blob.code === 0 ? blob.stdout.trim() : UNHASHABLE_BLOB, "utf8");
             hash.update("\0", "utf8");
         }
-        return `sha256:${hash.digest("hex")}`;
     }
     async repoPrefix(repoPath) {
         const result = await this.process.run("git", ["rev-parse", "--show-prefix"], this.opts(repoPath));
@@ -250,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) {
@@ -277,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"));
@@ -294,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.
@@ -307,6 +459,7 @@ export class GitCliAdapter {
             hash,
             content: binary ? null : result.stdout.toString("utf8"),
             bytes: result.stdout.length,
+            mode,
         };
     }
     async stagePath(repoPath, path) {
@@ -329,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);
     }
@@ -376,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
@@ -428,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) {
@@ -468,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.