Merge pull request #22 from gtrabanco/feat/04-running-economically

docs(04-running-economically): context hygiene, cross-family review, prompt-cache guidance

Author: gtrabanco

CHANGELOG.es.md

@@ -141,6 +141,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 #### `execute-phase`
 | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|
+| 1.14.1 | 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.14.0 | 2026-07-05 | menor | El checkpoint de revisión cada 2 fases es ahora una **recomendación, no una parada obligatoria**: el bloque de cierre recomienda `/review-change` con "continuar a la siguiente fase" como alternativa listada, y el envelope mantiene `state: CONTINUE` en los checkpoints (consultivo) — `READY_FOR_REVIEW` queda reservado a la unidad terminada. La **revisión de fin de unidad sigue siendo obligatoria** (alimenta `audit-pr`), y el gate de dependencias no cambia (sigue bloqueando y exigiendo `--force`). Referencias cruzadas de `review-change` 1.10.1 actualizadas. |
 | 1.13.1 | 2026-07-05 | parche | "Reanudar una fase interrumpida" enunciado como contrato explícito: al entrar en una rama con trabajo previo de la fase pedida, reconciliar los ticks de `TASKS.md` contra la evidencia y continuar desde la primera tarea sin marcar (reentrada idempotente — de la que depende el veredicto `RESUMABLE` de `workflow-status`); un libro sin siguiente tarea única → parar e informar, nunca adivinar. El comportamiento ya era práctica del Step 0; ahora está escrito. |
 | 1.13.0 | 2026-07-05 | menor | El hand-off de cierre de unidad gana una alternativa `/generate-docs` — impresa solo cuando el mapa de documentación del proyecto declara un bloque `Docs site`; las páginas generadas viajan en el PR de la unidad. |
@@ -197,6 +198,7 @@ Cómo funciona el pinning realmente, **verificado** contra el CLI `skills`:
 #### `review-change`
 | Versión | Fecha | Tipo | Qué cambió |
 |---|---|---|---|
+| 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. |
 | 1.9.0 | 2026-07-04 | minor | Guardrail: los cuerpos del forge creados vía triage-issue son Markdown — no pre-escapes el texto de los hallazgos; los cuerpos van por `--body-file`, nunca inline. |

CHANGELOG.md

@@ -139,6 +139,7 @@ How pinning actually works, verified against the `skills` CLI:
 #### `execute-phase`
 | Version | Date | Type | What changed |
 |---|---|---|---|
+| 1.14.1 | 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.14.0 | 2026-07-05 | minor | The every-2-phases review checkpoint is now a **recommendation, not a blocking stop**: the closing block recommends `/review-change` with "continue to the next phase" as a listed alternative, and the envelope keeps `state: CONTINUE` at checkpoints (advisory) — `READY_FOR_REVIEW` is reserved for the finished unit. The **end-of-unit review stays mandatory** (feeds `audit-pr`), and the dependency gate is unchanged (still blocks, still requires `--force` to override). `review-change` 1.10.1 cross-references updated. |
 | 1.13.1 | 2026-07-05 | patch | "Resuming an interrupted phase" stated as an explicit contract: on entry to a branch with prior work for the requested phase, reconcile `TASKS.md` ticks against evidence and continue from the first unticked task (idempotent re-entry — what `workflow-status`'s `RESUMABLE` verdict relies on); a ledger with no unique next task → stop and report, never guess. Behavior was already Step-0 practice; now it is written. |
 | 1.13.0 | 2026-07-05 | minor | Unit close-out hand-off gains a `/generate-docs` alternative — printed only when the project's documentation map declares a `Docs site` block; generated pages ride the unit's PR. |
@@ -195,6 +196,7 @@ How pinning actually works, verified against the `skills` CLI:
 #### `review-change`
 | Version | Date | Type | What changed |
 |---|---|---|---|
+| 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. |
 | 1.9.0 | 2026-07-04 | minor | Guardrail: forge bodies filed via triage-issue are Markdown — don't pre-escape finding text; bodies go through `--body-file`, never inline. |

README.es.md

@@ -326,11 +326,14 @@ npx skills add gtrabanco/agentic-workflow#claude
 `effort:` se mapea al presupuesto de razonamiento/thinking de tu modelo (`high` →
 razonamiento máximo; `medium` → por defecto; sin ese control → respeta solo la
 división fuerte/barato de arriba). Dos invariantes sobreviven a cualquier mapeo:
-**nunca revises un cambio con un modelo más débil que el que lo escribió**, y
-**los veredictos de auditoría (el gate de fusión) van al modelo más fuerte que
-tengas**. Espera que los modelos más débiles sigan el workflow correctamente —
-las skills están escritas como checklists y formatos de salida fijos — pero con
-un juicio menos profundo: la disciplina se mantiene, el techo se mueve.
+**nunca revises un cambio con un modelo más débil que el que lo escribió — 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), y **los veredictos de auditoría (el gate de fusión)
+van al modelo más fuerte que tengas**. Espera que los modelos más débiles sigan
+el workflow correctamente — las skills están escritas como checklists y
+formatos de salida fijos — pero con un juicio menos profundo: la disciplina se
+mantiene, el techo se mueve.
 
 ## Orquestación programática
 

README.md

@@ -317,7 +317,9 @@ npx skills add gtrabanco/agentic-workflow#claude
 `effort:` maps to your model's reasoning/thinking budget (`high` → maximum
 reasoning; `medium` → default; no such control → just honor the strong/cheap
 split above). Two invariants survive any mapping: **never review a change with a
-model weaker than the one that wrote it**, and **audit verdicts (the merge gate)
+model weaker than the one that wrote it — and prefer a different model family
+than the writer's** (same-family instances share training blind spots,
+cross-family decorrelates errors), and **audit verdicts (the merge gate)
 get the strongest model you have**. Expect weaker models to follow the workflow
 correctly — the skills are written as checklists and fixed output formats — but
 produce shallower judgment; the discipline holds, the ceiling moves.

docs/LOGS.md

@@ -44,3 +44,10 @@ tidy past entries — they're a record.
 - **Summary:** Real-world field testing of the workflow on Hermes Agent (open-weight models via NaN.builders) surfaced several gaps this session closed: an `#inheritance` skill variant (auto-synced branch, `model:`/`effort:` stripped) so any agent inherits its own session model; a full NaN.builders model-routing section in both READMEs (concrete picks per skill, fallback ladder, a downloadable PDF cheat sheet) after the user pushed back that the first pass wasn't concrete enough; Hermes-specific install/invocation docs (global installs per agent, `hermes bundles create` since Hermes only slash-routes bundles, not bare skills); a hard dependency gate in `execute-phase` (transitive `Depends on:` closure must be merged, `--force` escape hatch) plus fix-first priority in `ship-roadmap`'s SELECT and a plan-time blocker check in `plan-feature`; then, after the user reported Hermes-driven runs skipping commits/PRs/branch discipline, a `## Turn contract` section added to the top of every user-facing skill (weak models drop end-of-document duties) with an artifact-language precedence rule (explicit instruction > project's declared docs language > English — conversation language never decides) and an explicit PR close-out contract (print the PR URL in chat, link the roadmap/fix-index row as `done · [#pr](url)`); finally, made the *detector* skills (`audit-docs`, `product-audit`, `review-change`, `audit-pr`) mechanically verify all of the above actually held, rather than assuming a frontier model's compliance.
 - **Decisions:** Model-equivalence picks for NaN.builders are dated (July 2026) with an explicit re-check warning — model names churn in months, the precedence rules don't. `#inheritance` strips `model:`/`effort:` entirely instead of setting `model: inherit` — cleaner for agents with no such concept at all, and auto-synced via GitHub Action on every push to `main` so it never goes stale. Turn contracts go at the top of each skill (not the bottom) specifically because weak models truncate/skim toward the end of a long document — this is the single highest-leverage fix from this session. PR close-out requires printing the URL in chat because "not every agent shows open PRs" (Hermes doesn't); a roadmap row of bare `done` is now treated as an unfinished unit, not a cosmetic gap. Detector skills got explicit, mechanical (grep/git log, not inference) checks for every hardening rule instead of trusting a model to notice drift — this is what actually makes the workflow self-healing across model strength.
 - **Next:** Run `/product-audit` (or `/audit-docs --fix`) against the sosfelinos project now that Hermes has the refreshed `#inheritance` skills, to reconcile the bare-`done` roadmap rows Hermes left and confirm the new checks 1-13 actually fire. Then do a live A/B: same feature, once via Claude Code and once via Hermes/NaN, to verify parity on branch discipline, commit/PR creation, and the PR-link close-out. Consider whether `bump-skill` should also auto-tag releases (`release-YYYY-MM-DD`) — it was done manually twice this session.
+
+## 2026-07-09T00:00:00Z — feat/03-orchestrator-crash-recovery — manual
+- **Commits:** 18 (`d503e47…5f1689a`)
+- **Files:** new `skills/generate-docs/SKILL.md`; `skills/{execute-phase,audit-docs,init-workspace,review-perf,workflow-status,review-change}/SKILL.md`; `docs/workflow/{ORCHESTRATION,FEATURE_WORKFLOW,SKILLS}.md`; `template/CLAUDE.md`; `docs/features/ROADMAP.md` (new) + full planning artifacts for `01-generate-docs`, `02-measured-perf-review`, `03-orchestrator-crash-recovery`; README.md/README.es.md; CHANGELOG.md/CHANGELOG.es.md (28 files, +1651/-58 total)
+- **Summary:** Planned and shipped three independent features end-to-end through the full workflow (plan → execute → review-change → fold → audit-pr → merge): `01-generate-docs` (new `generate-docs` skill: adapter-discovered incremental docs, deterministic knowledge map, opt-in review export — PR #8, merged), `02-measured-perf-review` (`init-workspace` performance-tooling interview + `review-perf` runs declared benchmarks — PR #9, merged), and `03-orchestrator-crash-recovery` (`workflow-status` crash-recovery verdicts `CLEAN|RESUMABLE|AMBIGUOUS` mapped onto existing envelope states, driver restart protocol in ORCHESTRATION.md, plus a user-requested change making the every-2-phases `review-change` checkpoint a recommendation instead of a forced stop — PR #10, audited MERGE-READY at `5f1689a`, awaiting the user's merge). Two review-change passes on the three PRs caught and folded real findings: merge-order/shared-file coupling between the PRs, a mechanical-check false positive, crash-recovery envelope-precedence and no-upstream-branch gaps, and stale "mandatory checkpoint" wording left in `FEATURE_WORKFLOW.md` after the checkpoint change. After the PRs, an extended strategic conversation (informed by the Bun-in-Rust port article) produced an 11-unit backlog for the workflow's next evolution, persisted to cross-session memory (`agentic-workflow-backlog.md`, not this branch) rather than committed here.
+- **Decisions:** Every review-change pass on this repo's own PRs must run mechanically (real `git merge-tree`, real greps, real `gh` calls) rather than by inference — this is what caught the shared-file merge coupling before it became a live conflict. `review-perf` measures instead of estimates only when the project declares a `Performance commands` block; TS/JS tool names (Biome, mitata, 0x, sonarjs) stay confined to marked "adapter example" sections to preserve the stack-agnostic contract. The crash-recovery verdict deliberately reuses existing envelope states (`OK`/`CONTINUE`/`NEEDS_INPUT`) instead of adding new ones, so the npm schema package needs no release. The 2-phase review checkpoint is now a skippable recommendation but the end-of-unit review and the dependency gate are explicitly unchanged — this was a scoped, user-requested exception, not a general relaxation, and is flagged as such in the PR's CHECKLIST.md so `audit-pr` doesn't read it as scope creep. The 11-unit backlog (JSON envelope removal down to only `workflow-status`; a new `design-feature` skill splitting product design from `plan-feature`'s engineering role, with SPEC filled in two halves and a roadmap `idea→defined→planned→…` pipeline; adversarial context-clean review; cheap-model phase economics; an `init-workspace` upgrade mode) was deliberately NOT written into this repo's own roadmap yet — it lives in persistent memory so each unit can be planned atomically in a fresh session without re-deriving the discussion.
+- **Next:** Merge PR #10 (https://github.com/gtrabanco/agentic-workflow/pull/10 — MERGE-READY at `5f1689a`, the human merges). Then, in fresh sessions, work the backlog in order via `/plan-feature "U<n> del backlog agentic-workflow (memoria agentic-workflow-backlog)"`: U1 docs-pack (context hygiene, cross-family review, driver cache guidance) → U2 adversarial context-clean review → U3 `design-feature` core (major, redirects `plan-feature` when a feature isn't `defined`) → U4 roadmap states → U5 phase economics → U6 skill/MCP discovery in `product-audit` → U7 envelope removal (only after the user's Node/opencode driver has a repair loop) → U8/U9 (`--adversarial N`, golden fixture) → U10 `init-workspace` upgrade mode (deliberately late — migrates blocks U3-U5 introduce) → U11 final docs batch (model tables, diagrams, MIGRATION.md) always last.

docs/features/04-running-economically/CHECKLIST.md

@@ -0,0 +1,33 @@
+# 04 — running-economically — Completion checklist (single-pass)
+
+- [x] No schema/migrations — n/a (docs-only repo)
+- [x] Core layer imports — n/a (markdown docs and skill bodies, no code layers)
+- [x] `docs/workflow/FEATURE_WORKFLOW.md`: new `## Context hygiene & cost`
+      section (after Stage 2) — fresh conversation over compaction at unit/phase
+      end, hand-offs already fresh, compact only mid-phase for unpersisted
+      state, and the compaction cost mechanism stated (re-reads the whole
+      transcript at the current session model, fires near the context limit)
+- [x] `template/CLAUDE.md`: short fixed-rule pointer added under `## Session log`,
+      linking back to FEATURE_WORKFLOW.md's section
+- [x] `docs/workflow/ORCHESTRATION.md`: new `## Prompt-cache economics`
+      subsection (after "Replacing `/loop`") — byte-stable prefixes, ~5-min
+      window grouping, never switch model mid-unit, one-invocation-per-step
+      drivers never need compaction
+- [x] Cross-family review line added to all four locations: `review-change`
+      1.10.2, `execute-phase` 1.14.1 (both patch), `README.md`, `README.es.md`
+      — verified by `grep -rniI "prefer a different model" skills/ README.md
+      README.es.md` (3 English hits) + manual check of the Spanish equivalent
+      in README.es.md (different wording, same content)
+- [x] Gate green: `npx skills add . --list` exit 0; markdown link sweep on
+      touched files clean; stack-leak grep (`biome|mitata|sonarjs`) clean
+      outside existing adapter/equivalence sections
+- [x] CHANGELOG.md + CHANGELOG.es.md rows for `execute-phase` 1.14.1 and
+      `review-change` 1.10.2; README EN/ES skill/model tables unchanged (no new
+      skill, no tier change — only the invariant-line prose was edited)
+- [x] No new dependencies
+- [x] No skill-driven compaction automation added (explicitly out of scope per
+      issue #11 — guidance only)
+
+Decisions not in the SPEC: none — D1 (edit existing homes, no new doc), D2
+(FEATURE_WORKFLOW.md primary + template pointer), and D3 (cross-family as
+"prefer", not a hard gate) implemented as specified.