# Upgrade Guide — v1.0.9

<!-- bump: patch -->

## What Changed

Adds an 8th reviewer to the /spec-converge pipeline: the lessons-aware reviewer. Its only job is to check a draft spec against the canonical Instar Design Principles + Lessons Learned index (landed v1.0.7) plus the running agent's local memory entries, then surface any documented lesson the spec contradicts or fails to engage with.

This is the structural defense for the recurrence pattern Echo just walked through: across six recently-merged primitive PRs, multiple specs backtracked on already-documented lessons. None of the seven existing reviewers (4 internal perspective-based + 3 external cross-model) carried the brief "does this spec respect what we've already learned." The author was running convergence on their own spec under hybrid-C pre-authorization that included a self-verify step against the foundational specs they themselves had written — a circular check that surfaced nothing.

The lessons-aware reviewer breaks the circle by injecting a reviewer whose only context is the catalog of paid-for lessons, independent of the spec author's framing. When a spec contradicts a lesson, the reviewer flags it as critical. When a spec touches a surface a lesson covers but never engages with the lesson, the reviewer flags it as high. Findings are signals, not authority — the convergence orchestrator + spec author + user (via the approved tag) decide whether to ship.

Two artifacts: a reviewer prompt template at skills/spec-converge/templates/reviewer-lessons-aware.md and a SKILL.md update that declares the reviewer, changes references from seven reviewers to eight, and locks the lessons-aware reviewer as non-skippable even in pattern-instance abbreviated convergence. v0.1 enforcement is prompt-level — the SKILL.md states the reviewer MUST run. v0.2 will add a deterministic check in the convergence-tag writer that refuses to stamp the spec without a lessons-aware findings section in the report.

Bootstrap exception applied: this spec ships the reviewer itself, so the reviewer cannot run through itself. A manual lessons-aware check is documented in the spec body against the canonical index — same bootstrap pattern /spec-converge used when first introduced.

## Evidence

The first version of this reviewer was shipped previously, but the merge target ended up on a now-deleted intermediate branch and never propagated to main. This re-land replays the same commit cleanly against current main, with the same artifacts and the same lessons-engaged frontmatter.

The artifacts themselves verify the reviewer template loads the canonical principles plus lessons index, asks the three required questions (Q1 contradictions, Q2 unengaged-but-applicable, Q3 behavioral-rule applicability), and outputs structured findings keyed to P1-P10, L1-L17, B1-B39. The SKILL.md "MUST run" enforcement is present in the v0.1 prompt-level form, with v0.2 deterministic check tracked.

## What to Tell Your User

- "The spec-converge skill now has an eighth reviewer whose only job is to check a draft against everything we've already learned. The four internal perspective reviewers and three external cross-model reviewers stayed the same; the new one reads the principles and lessons index that landed in v1.0.7 and surfaces anything the spec contradicts or forgets to engage with. This is the structural defense against the backtracks we hit when the spec author was also the one running convergence under pre-authorization."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Lessons-aware reviewer (8th in /spec-converge) | Runs automatically on every convergence round. Findings are surfaced in the convergence report alongside the other seven reviewers' output. |
| Non-skippable in abbreviated convergence | Pattern-instance abbreviated convergence may skip the three externals to save cost, but the lessons-aware reviewer always runs — the structural defense against circular self-verify. |
| Per-agent lessons loaded | Reviewer reads the running agent .instar/memory/feedback_*.md entries plus the canonical index, so per-agent specific lessons surface even before promotion. |

## Deferred (Tracked Follow-ups)

- v0.2 deterministic convergence-tag enforcement: refuse to write the review-convergence tag unless the report contains a lessons-aware findings section.
- v0.2 cross-repo reviewer: today the prompt assumes a single agent memory location; cross-repo specs need disambiguation between author memory and Echo memory.
- Sentinel mirror-trust + backfill amendment (audit-identified) and the broader Migration Parity backfills + Testing Integrity Tier-3 gaps remain as next-session work.
