Skip to content

Commit a8148eb

Browse files
authored
fix(execute-phase): trigger-based review checkpoint cadence (#92)
## Summary Replaces `execute-phase`'s fixed every-2-phases review-checkpoint rule with three mechanical, independently-checkable triggers, closing the workflow-cost regression #64's phase-atomicity lint (merged, PR #75) introduces. - **Layer boundary** — the next phase declares a different `Layer:` than the one just committed. - **Accumulation** — `git diff --stat <baseline>..HEAD` exceeds 400 changed lines or 8 changed files since the last-reviewed marker. - **Sensitivity** — the just-closed phase touches auth, payments, destructive migrations, secrets, or CI config → immediate single-reviewer checkpoint. - Specifies the `Last reviewed: <sha>` marker's home (`progress.md` header), sole writer (`execute-phase`), and its `git merge-base` fallback when absent. Checkpoints stay single-reviewer and skippable; the mandatory terminal `review-change` and its adversarial hook (`#76`'s cadence — once per unit) are untouched by contract, verified via `git diff` showing no change inside that block. ## Changes - `skills/execute-phase/SKILL.md` (2.5.2 → 2.6.0, minor) — new "Review checkpoint triggers" section, rewritten cadence paragraph, rewritten checkpoint hand-off block, plus two residual hyphenated "every-2-phases" references (L517, L629) a broad sweep caught during hardening that the P1 space-form grep missed. - `skills/review-change/SKILL.md` (2.4.0 → 2.4.1, patch) — two cross-reference restatements only; adversarial section byte-unchanged. - Bilingual cadence-doc parity (EN + ES together, same commit): `docs/workflow/SKILLS.md`, `docs/workflow/FEATURE_WORKFLOW.md`, `docs/workflow/PORTABLE_PROMPT.md`, `docs/workflow/MIGRATION.md`, `README.md`. - `CHANGELOG.md` + `CHANGELOG.es.md` — version rows + release-log entries. - `docs/workflow/GOLDEN_FIXTURE.md` + `.es.md` — dated smoke-test run-log row. ## Test plan - [x] `npx skills add . --list` → exit 0, every skill discovered including the bumped `execute-phase`/`review-change`. - [x] `grep -rniE "every.?2.?phases|every.?two.?phases|per-2-phase|2-phase.checkpoint"` across every touched skill/doc → `0` current-behavior hits (CHANGELOG hits are frozen history + this fix's own "what changed" rows). - [x] `git diff main -- skills/review-change/SKILL.md` shows only the two targeted cross-reference lines changed; the adversarial "Cadence — once per unit" block is byte-identical. - [x] GOLDEN_FIXTURE smoke: two live Claude Haiku 4.5 runs (layer-boundary-fires scenario, no-trigger-fires scenario) both reproduced the fixed "Checkpoint hand-off" block exactly, correct trigger naming/reasoning, correct omission logic, zero invented steps — logged in `docs/workflow/GOLDEN_FIXTURE.md` + `.es.md`. - [x] `bump-skill` lint (all 5 authoring rules) clean on both changed skills. Closes #77
2 parents 9c5ab1f + 4b81887 commit a8148eb

18 files changed

Lines changed: 582 additions & 44 deletions

File tree

CHANGELOG.es.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
142142
#### `execute-phase`
143143
| Versión | Fecha | Tipo | Qué cambió |
144144
|---|---|---|---|
145+
| 2.6.0 | 2026-07-18 | menor | Fix #77: sustituye la cadencia fija de checkpoint de revisión cada 2 fases por tres disparadores mecánicos — **límite de capa** (la siguiente fase declara un `Layer:` distinto), **acumulación** (`git diff --stat <baseline>..HEAD` > 400 líneas u > 8 ficheros desde el marcador última-revisión), y **sensibilidad** (fase de auth/pagos/migración destructiva/secretos/CI) — más la especificación del marcador `Last reviewed: <sha>` en `progress.md` (único escritor `execute-phase`, respaldo `git merge-base` si está ausente). La revisión final obligatoria y la cadencia adversarial de `review-change` no cambian. |
145146
| 2.5.2 | 2026-07-18 | parche | Fix #76: el hand-off obligatorio de revisión de fin de unidad ahora anota cuándo `review-change` recomienda `--adversarial N` en esa revisión terminal — solo redacción, la cadencia del checkpoint cada 2 fases no cambia. |
146147
| 2.5.1 | 2026-07-18 | parche | Fix #66: se aclaró el paso de retro-relleno de la enmienda en la guardia de descope — tras crear el issue de seguimiento y enlazarlo en el cuerpo del issue, editar explícitamente la fila `## Amendments` para sustituir el marcador `#<n>` por el número real del issue y commitear ese cambio; una fila que aún lea el marcador literal falla la comprobación simétrica de fila sin enlazar de `audit-pr`. |
147148
| 2.5.0 | 2026-07-17 | menor | Fix #66: nueva **guardia de descope** en la Política de issues — antes de crear cualquier issue, se clasifica como trabajo descubierto (se archiva libremente) o descope (solapa un criterio de aceptación/tarea de la SPEC no entregado del todo); un descope PARA antes de crear el issue, exigiendo primero una entrada `## Amendments` fechada y aprobada por el usuario (formato de fila canónico definido una sola vez aquí). Nueva entrada en la lista de prohibiciones y casilla del contrato de turno que exige que la guardia se aplicase a cada issue creado en el turno. |
@@ -226,6 +227,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
226227
#### `review-change`
227228
| Versión | Fecha | Tipo | Qué cambió |
228229
|---|---|---|---|
230+
| 2.4.1 | 2026-07-18 | parche | Fix #77: reformula las dos referencias cruzadas a la cadencia de `execute-phase` ("When to use" y "Relationship to other skills") desde el intervalo retirado de cada 2 fases hacia la nueva cadencia basada en disparadores (límite de capa/acumulación/sensibilidad); la sección adversarial "Cadence — once per unit" y su nota de límite con `#77` no cambian. |
229231
| 2.4.0 | 2026-07-18 | menor | Fix #76: hace que `--adversarial N` sea usable por flotas de modelos débiles orquestadas a mano — checklist de recomendación de 4 casillas (sustituye el disparador L/sensible únicamente, añade una condición "revisor no es el más fuerte/es más débil que el autor" expuesta como línea de informe, nunca auto-detectada), escalera fija de N (2 por defecto, 3 en seguridad/familia única, >3 desaconsejado), roles de revisor asignados por índice (R1 corrección, R2 seguridad, R3 cobertura de SPEC) con la guarda de rol-como-prioridad-no-alcance, contratos de revisor/merge de fuente única, un nuevo modo de fusión `--merge` con lista de prohibiciones, plantillas de bloques para pegar en Portability, y un ancla de cadencia una-vez-por-unidad (límite explícito con `#77`). |
230232
| 2.3.0 | 2026-07-17 | menor | Fix #65: el bloque `→ Next:` de `Decision: FAIL` ahora recomienda la nueva skill independiente `/fold-findings` (clasificación congelada, lista de prohibiciones que cierra las válvulas de escape de volcado-a-known-issues/downgrade/aflojar-tests/supresión) como la vía de fold, en lugar de la línea de prosa inline "fold the fix-now findings"; la forma fija multilínea y los sub-bullets de `/audit-pr`/no-fix-now/product-audit no cambian. |
231233
| 2.2.1 | 2026-07-17 | parche | El bloque `→ Next:` del paso 11 ahora se ramifica explícitamente según `Decision`: un bloque `FAIL` recomienda foldear los hallazgos fix-now (gate en verde, commit + push, re-ejecutar `/review-change`) con `/audit-pr` degradado a sub-bullet condicionado a la tabla limpia; un bloque `PASS` mantiene `/audit-pr — merge gate`. La condición de recurrencia de `/product-audit` ahora es una casilla explícita sí/no, y el bloque debe emitirse como líneas literales múltiples, nunca como prosa unida con `·`. Corrige el issue #63 — modelos débiles (observado: qwen3.6-thinking) copiaban la plantilla estática única anterior de forma literal, recomendando el merge gate incluso en `FAIL`. |
@@ -427,6 +429,16 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
427429

428430
## Registro cronológico (más reciente primero)
429431

432+
- **2026-07-18 — disparadores de cadencia del checkpoint de revisión (fix 77).**
433+
Bump MENOR para `execute-phase` (2.6.0): el checkpoint fijo cada 2 fases se
434+
sustituye por tres disparadores mecánicos — límite de capa, acumulación
435+
(umbrales de `git diff --stat`), y sensibilidad — más una especificación del
436+
marcador `Last reviewed: <sha>` en `progress.md`. Bump PARCHE para
437+
`review-change` (2.4.1): sus dos referencias cruzadas de cadencia se
438+
reformulan al modelo de disparadores; la cadencia adversarial
439+
una-vez-por-unidad no cambia. Paridad de docs de cadencia en
440+
`SKILLS`/`FEATURE_WORKFLOW`/`PORTABLE_PROMPT`/`MIGRATION`/README (EN+ES).
441+
430442
- **2026-07-18 — usabilidad del modo adversarial en flotas débiles (fix 76).**
431443
Bump MENOR para `review-change` (2.4.0): el modo `--adversarial N` gana una
432444
checklist de recomendación de 4 casillas (condición de modelo, nunca

CHANGELOG.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,7 @@ How pinning actually works, verified against the `skills` CLI:
141141
#### `execute-phase`
142142
| Version | Date | Type | What changed |
143143
|---|---|---|---|
144+
| 2.6.0 | 2026-07-18 | minor | Fix #77: replaced the fixed every-2-phases review-checkpoint cadence with three mechanical triggers — **layer boundary** (next phase declares a different `Layer:`), **accumulation** (`git diff --stat <baseline>..HEAD` > 400 lines or > 8 files since the last-reviewed marker), and **sensitivity** (auth/payments/destructive-migration/secrets/CI phase) — plus the `Last reviewed: <sha>` marker spec in `progress.md` (sole writer `execute-phase`, `git merge-base` fallback when absent). The mandatory terminal review and `review-change`'s adversarial cadence are unchanged. |
144145
| 2.5.2 | 2026-07-18 | patch | Fix #76: the mandatory end-of-unit review hand-off notes when `review-change` recommends `--adversarial N` at that terminal review — wording only, the every-2-phases checkpoint cadence is unchanged. |
145146
| 2.5.1 | 2026-07-18 | patch | Fix #66: clarified the descope guard's amendment-backfill step — after creating the follow-up issue and linking it in the issue body, explicitly edit the `## Amendments` row to replace the `#<n>` placeholder with the real issue number and commit that edit; a row still reading the literal placeholder fails `audit-pr`'s symmetric unlinked-row check. |
146147
| 2.5.0 | 2026-07-17 | minor | Fix #66: new **descope guard** in the Issue policy — before creating any issue, classify it discovered-work (file freely) vs. descope (overlaps a SPEC acceptance criterion/phase task not fully delivered); a descope STOPs before the issue is created, requiring a user-approved, dated `## Amendments` entry first (canonical row format defined once here). New Forbidden-list entry and turn-contract box asserting the guard ran on every issue created in the turn. |
@@ -225,6 +226,7 @@ How pinning actually works, verified against the `skills` CLI:
225226
#### `review-change`
226227
| Version | Date | Type | What changed |
227228
|---|---|---|---|
229+
| 2.4.1 | 2026-07-18 | patch | Fix #77: restated the two `execute-phase` cadence cross-references ("When to use" and "Relationship to other skills") from the retired every-2-phases interval to the new trigger-based cadence (layer boundary/accumulation/sensitivity); the adversarial "Cadence — once per unit" section and its `#77` boundary note are unchanged. |
228230
| 2.4.0 | 2026-07-18 | minor | Fix #76: made `--adversarial N` usable by hand-orchestrated weak-model fleets — a 4-box recommendation checklist (replaces the L/sensitive-only trigger, adds a "reviewer not strongest/weaker than author" condition surfaced as a report line, never auto-detected), a fixed N ladder (2 default, 3 on security/single-family, >3 discouraged), index-assigned reviewer roles (R1 correctness, R2 security, R3 SPEC-coverage) with a role-is-priority-not-scope guardrail, single-sourced reviewer/merge contracts, a new `--merge` fusion entry point with a forbidden-drop list, Portability paste-block templates, a once-per-unit cadence anchor (explicit `#77` boundary), and `→ Next:` wiring at the terminal review. |
229231
| 2.3.0 | 2026-07-17 | minor | Fix #65: the `Decision: FAIL` `→ Next:` block now recommends the new standalone `/fold-findings` skill (frozen classification, forbidden list closing the known-issues-dump/downgrade/test-loosening/suppression escape hatches) as the fold path, replacing the inline "fold the fix-now findings" prose line; the multi-line fixed shape and the `/audit-pr`/non-fix-now/product-audit sub-bullets are unchanged. |
230232
| 2.2.1 | 2026-07-17 | patch | Step 11's `→ Next:` block now branches explicitly on `Decision`: a `FAIL` block recommends folding the fix-now findings (gate green, commit + push, re-run `/review-change`) with `/audit-pr` demoted to a table-clean sub-bullet, a `PASS` block keeps `/audit-pr — merge gate`; the `/product-audit` recurrence condition is now an explicit yes/no checkbox, and the block must render as multiple literal lines, never `·`-joined prose. Fixes #63 — weak models (observed: qwen3.6-thinking) were copying the old single static template verbatim, recommending the merge gate even on `FAIL`. |
@@ -426,6 +428,16 @@ How pinning actually works, verified against the `skills` CLI:
426428

427429
## Release log (chronological, newest first)
428430

431+
- **2026-07-18 — review checkpoint cadence triggers (fix 77).** MINOR bump
432+
for `execute-phase` (2.6.0): the fixed every-2-phases checkpoint is
433+
replaced by three mechanical triggers — layer boundary, accumulation
434+
(`git diff --stat` thresholds), and sensitivity — plus a `Last reviewed:
435+
<sha>` marker spec in `progress.md`. PATCH bump for `review-change`
436+
(2.4.1): its two cadence cross-references restated to the trigger model;
437+
the adversarial once-per-unit cadence is untouched. Cadence docs parity
438+
across `SKILLS`/`FEATURE_WORKFLOW`/`PORTABLE_PROMPT`/`MIGRATION`/README
439+
(EN+ES).
440+
429441
- **2026-07-18 — adversarial mode weak-fleet usability (fix 76).** MINOR bump
430442
for `review-change` (2.4.0): the `--adversarial N` mode gains a 4-box
431443
recommendation checklist (model condition, never auto-detected), a fixed

README.es.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ con ningún modelo. Un único camino disciplinado:
116116

117117
| Skill | Qué hace |
118118
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
119-
| `execute-phase` | Implementa una fase por invocación — de una feature (por defecto), de una feature pequeña `XS/S`, o de un fix (`--fix`); las fases de XS/S y fixes viven en el `## Phases` del SPEC (≥ 2 fases, la final siempre `Hardening & PR` — la cadena de cierre en su propio turno), y un SPEC legacy sin `## Phases` se ejecuta de una pasada. **Gate de dependencias primero**: el cierre transitivo de `Depends on:` debe estar fusionado, o se detiene con la cadena incumplida y el orden de construcción (`--force` lo salta, registrado); después una **precondición de estado propio** redirige una unidad por debajo de `planned` (`idea` → `/design-feature`, `defined` → `/plan-feature`); luego un **guardia de pre-vuelo de lint de fase** ejecuta la checklist canónica de atomicidad de 8 casillas contra la fase objetivo, deteniéndose con un bloque fijo ante cualquier FAIL (`--force` lo salta, registrado). **Tests primero** en trabajo de dominio/orquestación, nunca commitea en rojo, verificada por el gate, un commit por fase; **recomienda un checkpoint de `review-change` cada 2 fases (omitible) y hace hand-off una vez al final (obligatorio)**. **Guardia de descope**: antes de crear cualquier issue, lo clasifica como trabajo descubierto (se archiva libremente) o descope (solapa un criterio de aceptación/tarea incumplido) — un descope PARA hasta que exista una entrada `## Amendments` fechada y aprobada por el usuario; un issue nunca es el primer registro de un descope. **Una fase = una sesión** en modelos no-frontera (nunca dos fases en una misma conversación — el patrón por lotes de `/loop` ya reinvoca por fase). Una unidad terminada **siempre abre su PR, imprime la URL del PR en el chat y pasa a `done`** (construida, no mergeada); ningún turno acaba con el árbol sucio, y con el PR abierto cada commit se pushea inmediatamente. |
119+
| `execute-phase` | Implementa una fase por invocación — de una feature (por defecto), de una feature pequeña `XS/S`, o de un fix (`--fix`); las fases de XS/S y fixes viven en el `## Phases` del SPEC (≥ 2 fases, la final siempre `Hardening & PR` — la cadena de cierre en su propio turno), y un SPEC legacy sin `## Phases` se ejecuta de una pasada. **Gate de dependencias primero**: el cierre transitivo de `Depends on:` debe estar fusionado, o se detiene con la cadena incumplida y el orden de construcción (`--force` lo salta, registrado); después una **precondición de estado propio** redirige una unidad por debajo de `planned` (`idea` → `/design-feature`, `defined` → `/plan-feature`); luego un **guardia de pre-vuelo de lint de fase** ejecuta la checklist canónica de atomicidad de 8 casillas contra la fase objetivo, deteniéndose con un bloque fijo ante cualquier FAIL (`--force` lo salta, registrado). **Tests primero** en trabajo de dominio/orquestación, nunca commitea en rojo, verificada por el gate, un commit por fase; **recomienda un checkpoint de `review-change` según una cadencia basada en disparadores — límite de capa, acumulación o sensibilidad (omitible) — y hace hand-off una vez al final (obligatorio)**. **Guardia de descope**: antes de crear cualquier issue, lo clasifica como trabajo descubierto (se archiva libremente) o descope (solapa un criterio de aceptación/tarea incumplido) — un descope PARA hasta que exista una entrada `## Amendments` fechada y aprobada por el usuario; un issue nunca es el primer registro de un descope. **Una fase = una sesión** en modelos no-frontera (nunca dos fases en una misma conversación — el patrón por lotes de `/loop` ya reinvoca por fase). Una unidad terminada **siempre abre su PR, imprime la URL del PR en el chat y pasa a `done`** (construida, no mergeada); ningún turno acaba con el árbol sucio, y con el PR abierto cada commit se pushea inmediatamente. |
120120

121121
### Revisión y auditoría — _cambio → PR → producto_
122122

@@ -481,7 +481,7 @@ Tutorial completo en **[`docs/workflow/`](docs/workflow/README.md)**. En resumen
481481
→ el router detecta idea / issue / slug acotado → entrevista · análisis del issue · scaffold
482482
→ rellena el SPEC + PLAN + TASKS + … y registra la entrada en el roadmap
483483
/execute-phase <NN> <phase> # una fase cada vez, verificada por el gate, un commit cada una
484-
→ checkpoint de revisión recomendado cada 2 fases (obligatorio al final)
484+
→ checkpoint de revisión recomendado por disparador (límite de capa/acumulación/sensibilidad; obligatorio al final)
485485
→ una unidad terminada siempre abre su PR + pasa a `done` (construida, no mergeada)
486486
/review-change # obligatorio: revisiones aplicables, clasificadas; no-fix-now → triage-issue
487487
/audit-pr # gate de fusión: listo o bloqueantes (nunca fusionar con docs pendientes)

0 commit comments

Comments
 (0)