Merge pull request #23 from gtrabanco/feat/05-adversarial-context-clean-review

feat(review): adversarial find stance + context-clean end-review contract

Author: gtrabanco

CHANGELOG.es.md

@@ -198,6 +198,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 #### `review-change`
 | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|
+| 1.11.0 | 2026-07-09 | menor | El turn contract gana una casilla obligatoria de contexto limpio: la revisión final obligatoria de fin de unidad debe correr en una conversación que NO implementó el cambio — si lo hizo, PARAR y hacer hand-off a una nueva. "When to use" reescrito para exponer el requisito en prosa (la sección Portability ya existente referencia la línea de preferencia de familia de modelo cruzada de la feature 04; sin cambios aquí). |
 | 1.10.2 | 2026-07-09 | parche | El invariante de modelo en Portability se extiende: "nunca revises con un modelo más débil — y prefiere una familia de modelo distinta a la del autor" (instancias de la misma familia comparten puntos ciegos de entrenamiento; una familia cruzada descorrelaciona errores). Solo redacción. |
 | 1.10.1 | 2026-07-05 | parche | Referencias cruzadas actualizadas para `execute-phase` 1.14.0: el hand-off cada 2 fases se describe ahora como checkpoint recomendado y omitible; la revisión final obligatoria antes del merge no cambia. |
 | 1.10.0 | 2026-07-05 | menor | Envelope máquina: cada invocación termina ahora con un bloque JSON fijo (state, unit, phase, pr, findings, blockers, dependencies, next + pista de tier de modelo) para orquestación programática — esquema en la skill interna `orchestration-envelope`, protocolo en `docs/workflow/ORCHESTRATION.md`. Los hallazgos fix-now y los números de issue creados viajan en el envelope; la deriva de SPEC recurrente activa el flag de recomendación de product-audit. |
@@ -303,7 +304,8 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 | Skill | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|---|
 | `orchestration-envelope` | 1.0.0 | 2026-07-05 | — | Nuevo contrato interno: el esquema JSON del envelope máquina (11 estados, claves fijas, regla de parseo último-json-cercado) que toda skill de cara al usuario emite como su salida final absoluta. |
-| `review-implementation` | 1.0.3 | 2026-07-04 | parche | Sin cambio de comportamiento: el frontmatter `model:`/`effort:` de esta skill se trasladó a `docs/workflow/model-routing.yml` (usado solo para construir la rama `#claude`). |
+| `review-implementation` | 1.1.0 | 2026-07-09 | menor | La postura de la Fase 1 ("Find") ahora es adversarial por defecto: "asume que el diff está MAL — tu trabajo es probar que no funciona". La tabla de ejes y la rúbrica de clasificación de la Fase 2 no cambian. |
+| | 1.0.3 | 2026-07-04 | parche | Sin cambio de comportamiento: el frontmatter `model:`/`effort:` de esta skill se trasladó a `docs/workflow/model-routing.yml` (usado solo para construir la rama `#claude`). |
 | | 1.0.2 | 2026-07-02 | parche | La referencia a revisiones companion ahora apunta al pack de revisión interno (`review-*`) |
 | | 1.0.1 | 2026-06-09 | parche | Descripción acortada 96 → 36 palabras (contexto siempre cargado); cuerpo sin cambios |
 | | 1.0.0 | 2026-06-05 | — | El motor de hallazgos + rúbrica de clasificación que compone `review-change` |
@@ -346,6 +348,18 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 
 ## Registro cronológico (más reciente primero)
 
+- **2026-07-09 — revisión adversarial con contexto limpio.** Endurece la
+  revisión final obligatoria de fin de unidad contra el fallo de compartir
+  contexto, donde la conversación que escribió un cambio también lo revisa:
+  la postura de la Fase 1 de `review-implementation` 1.1.0 ahora es
+  adversarial por defecto ("asume que el diff está MAL — prueba que no
+  funciona"), y `review-change` 1.11.0 gana una casilla obligatoria en su
+  turn contract que exige que la revisión final corra en una conversación
+  que no implementó el cambio (si lo hizo, PARAR y hacer hand-off). Referencia
+  la línea de preferencia de familia de modelo cruzada de la feature
+  `04-running-economically` en lugar de repetirla. Feature
+  `05-adversarial-context-clean-review`.
+
 - **2026-07-05 — recuperación de caídas del orquestador.** Los drivers
   externos (incluidos servidores Node/opencode solo-REST) ganan una ruta de
   reinicio segura: `workflow-status` 1.1.0 clasifica los turnos

CHANGELOG.md

@@ -196,6 +196,7 @@ How pinning actually works, verified against the `skills` CLI:
 #### `review-change`
 | Version | Date | Type | What changed |
 |---|---|---|---|
+| 1.11.0 | 2026-07-09 | minor | Turn contract gains a mandatory context-clean box: the mandatory end-of-unit review must run in a conversation that did NOT implement the change — if it did, STOP and hand off to a fresh one. "When to use" reworded to state the requirement in prose (the pre-existing Portability section already points to feature 04's cross-family model-preference line; unchanged here). |
 | 1.10.2 | 2026-07-09 | patch | Portability's model invariant extended: "never review with a weaker model — and prefer a different model **family** than the writer's" (same-family instances share training blind spots; cross-family decorrelates errors). Wording-only. |
 | 1.10.1 | 2026-07-05 | patch | Cross-references updated for `execute-phase` 1.14.0: the every-2-phases hand-off is now described as a recommended, skippable checkpoint; the mandatory-before-merge end review is unchanged. |
 | 1.10.0 | 2026-07-05 | minor | Machine envelope: every invocation now ends with a fixed JSON block (state, unit, phase, pr, findings, blockers, dependencies, next + model-tier hint) for programmatic orchestration — schema in the internal `orchestration-envelope` skill, protocol in `docs/workflow/ORCHESTRATION.md`. fix-now findings and filed issue numbers ride the envelope; recurring SPEC drift sets the product-audit recommendation flag. |
@@ -301,7 +302,8 @@ How pinning actually works, verified against the `skills` CLI:
 | Skill | Version | Date | Type | What changed |
 |---|---|---|---|---|
 | `orchestration-envelope` | 1.0.0 | 2026-07-05 | — | New internal contract: the machine-envelope JSON schema (11 states, fixed keys, last-fenced-json parse rule) every user-facing skill emits as its absolute last output. |
-| `review-implementation` | 1.0.3 | 2026-07-04 | patch | No behavior change: this skill's `model:`/`effort:` frontmatter moved to `docs/workflow/model-routing.yml` (used only to build the `#claude` branch). |
+| `review-implementation` | 1.1.0 | 2026-07-09 | minor | Phase 1 ("Find") stance is now adversarial by default: "assume the diff is WRONG — your job is to prove it does not work." The axis table and the Phase 2 classification rubric are unchanged. |
+| | 1.0.3 | 2026-07-04 | patch | No behavior change: this skill's `model:`/`effort:` frontmatter moved to `docs/workflow/model-routing.yml` (used only to build the `#claude` branch). |
 | | 1.0.2 | 2026-07-02 | patch | Companion-review reference now points at the internal review pack (`review-*`) |
 | | 1.0.1 | 2026-06-09 | patch | Description shortened 96 → 36 words (always-loaded context); body unchanged |
 | | 1.0.0 | 2026-06-05 | — | The findings engine + classification rubric `review-change` composes |
@@ -344,6 +346,17 @@ How pinning actually works, verified against the `skills` CLI:
 
 ## Release log (chronological, newest first)
 
+- **2026-07-09 — adversarial context-clean review.** Hardens the mandatory
+  end-of-unit review against the context-sharing failure mode where the
+  conversation that wrote a change also reviews it: `review-implementation`
+  1.1.0's Phase 1 stance is now adversarial by default ("assume the diff is
+  WRONG — prove it does not work"), and `review-change` 1.11.0 gains a
+  mandatory turn-contract box requiring the end review to run in a
+  conversation that did not implement the change (STOP and hand off
+  otherwise). References feature `04-running-economically`'s cross-family
+  model-preference line rather than restating it. Feature
+  `05-adversarial-context-clean-review`.
+
 - **2026-07-05 — orchestrator crash recovery.** External drivers (REST-only
   Node/opencode servers included) get a safe restart path: `workflow-status`
   1.1.0 classifies interrupted turns from ground truth into

README.es.md

@@ -107,7 +107,7 @@ con ningún modelo. Un único camino disciplinado:
 
 | Skill           | Alcance         | Qué hace                                                                                                                                                                                                            |
 | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `review-change` | el **cambio**   | Ejecuta solo las revisiones que **aplican a tu plataforma** (código, seguridad, verify, diseño, a11y, marca, rendimiento, SEO) y clasifica → una tabla de decisión + una checklist explícita de verificación manual; un árbol sucio o commits sin push en la rama del PR son hallazgos `workflow` fix-now |
+| `review-change` | el **cambio**   | Ejecuta solo las revisiones que **aplican a tu plataforma** (código, seguridad, verify, diseño, a11y, marca, rendimiento, SEO) — adversariales por defecto, asumiendo que el diff está mal hasta probar lo contrario — y clasifica → una tabla de decisión + una checklist explícita de verificación manual; un árbol sucio o commits sin push en la rama del PR son hallazgos `workflow` fix-now. La revisión final obligatoria **debe correr en una conversación que no implementó el cambio** — si lo hizo, parar y hacer hand-off a una nueva |
 | `audit-pr`      | el **PR**       | Gate de fusión: criterios de aceptación cumplidos, todas las fases hechas, docs/tests/CI en verde, `Closes #N`, ejes de revisión limpios → **listo para fusionar o una lista de bloqueantes**, siempre con la URL completa del PR; con MERGE-READY publica un comentario datado y ligado al SHA en el propio PR. Auto-merge opt-in: con una política documentada fusiona PRs MERGE-READY tras un checklist de limpieza fail-closed (algo pendiente → push, esperar CI, re-auditar) |
 | `product-audit` | el **producto** | Chequeo de salud periódico de espectro completo; mina las docs de features → propone issues + altas/bajas en el roadmap (**nunca arregla automáticamente**)                                                         |
 | `audit-docs`    | las **docs**    | Audita docs ↔ roadmap ↔ código ↔ índice de fixes en busca de desviaciones                                                                                                                                           |

README.md

@@ -105,7 +105,7 @@ path: **plan → execute → review → audit → merge.**
 
 | Skill           | Scope           | What it does                                                                                                                                                                                   |
 | --------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `review-change` | the **change**  | Runs only the reviews that **apply to your platform** (code, security, verify, design, a11y, brand, perf, SEO) and classifies → one decision table + an explicit manual-verification checklist; a dirty tree or unpushed commits on the PR branch are fix-now `workflow` findings |
+| `review-change` | the **change**  | Runs only the reviews that **apply to your platform** (code, security, verify, design, a11y, brand, perf, SEO) — adversarially by default, assuming the diff is wrong until proven otherwise — and classifies → one decision table + an explicit manual-verification checklist; a dirty tree or unpushed commits on the PR branch are fix-now `workflow` findings. The mandatory end review **must run in a conversation that did not implement the change** — if it did, stop and hand off to a fresh one |
 | `audit-pr`      | the **PR**      | Merge gate: acceptance met, all phases done, docs/tests/CI green, `Closes #N`, review axes clean → **merge-ready or a list of blockers**, always with the PR's full URL; on MERGE-READY it posts a dated, SHA-bound comment on the PR itself. Opt-in auto-merge: with a documented policy it merges MERGE-READY PRs after a fail-closed cleanliness checklist (anything pending → push, wait for CI, re-audit) |
 | `product-audit` | the **product** | Periodic full-spectrum health check; mines feature docs → proposes issues + roadmap add/remove (**never auto-fixes**)                                                                          |
 | `audit-docs`    | the **docs**    | Audits docs ↔ roadmap ↔ code ↔ fix index for drift                                                                                                                                             |

docs/features/05-adversarial-context-clean-review/CHECKLIST.md

@@ -0,0 +1,43 @@
+# Completion checklist — 05-adversarial-context-clean-review
+
+- Schema migration applied — n/a, docs-only change.
+- Core layer has no outer imports — n/a, no code.
+- Orchestration idempotent + typed errors — n/a, no code.
+- Adapters implement ports — n/a, no code.
+- Tests pass — n/a, no test layer; textual/structural gate below is "green".
+- Type-check/lint green — `npx skills add . --list` discovers both edited
+  skills; frontmatter parses.
+- UI strings localized — n/a, no UI.
+- Domain value-object rules respected — n/a, no code.
+- User-facing limitations disclosed — n/a, internal workflow-quality change,
+  no external product surface.
+- New deps pinned — n/a, no dependencies added.
+
+## Acceptance criteria verification
+
+1. `grep -iq "assume the diff is wrong" skills/review-implementation/SKILL.md`
+   → PASS.
+2. Phase 1 axis table (10 axes) and the entire Phase 2 classification section
+   are unchanged in structure — confirmed by diff review: only the Phase 1
+   opening sentence changed; the axis table and Phase 2 are untouched.
+3. `grep -n "did NOT implement" skills/review-change/SKILL.md` → matches
+   inside the `## Turn contract` fence.
+4. Cross-family model preference is referenced (not re-authored) in
+   `review-change`'s Portability section, which already pointed at the
+   preference; `review-change`'s "When to use" points at the same
+   turn-contract box rather than restating feature 04's text.
+5. `grep -rq "adversarial N\|--adversarial" skills/review-change
+   skills/review-implementation` → no match (PASS, nothing introduced).
+6. `review-implementation` 1.0.3 → 1.1.0 (minor); `review-change` 1.10.2 →
+   1.11.0 (minor). Matching rows added to `CHANGELOG.md` and
+   `CHANGELOG.es.md`; README/README.es.md skills tables updated for
+   `review-change`'s cell (behavior changed); model/effort tables untouched
+   (no tier change).
+7. `npx skills add . --list` still discovers every skill, both edited files
+   parse.
+
+## Decisions not captured in the SPEC
+
+None — implementation followed the SPEC's Design section verbatim (Edit 1,
+Edit 2, no caller edits needed since neither `audit-pr` nor `product-audit`
+restate the neutral Phase 1 stance).