|
1 | 1 | # Changelog |
2 | 2 |
|
| 3 | +## 3.0.0 |
| 4 | + |
| 5 | +Three-command split, a harness-agnostic rewrite, and a de-overlapped |
| 6 | +review layer. The loop is now `/spec -> /plan -> /implement`, mapping to |
| 7 | +three gates (spec validation, plan review, code review) one gate per |
| 8 | +command, with a convergence back-edge where `/implement` re-runs the |
| 9 | +plan-review gate in-session. This release rolls up every change since |
| 10 | +2.5.0. Breaking change: `/implement` no longer plans. |
| 11 | + |
| 12 | +### Added |
| 13 | +- **`/plan` skill**: decomposes a spec into an ordered, dependency-aware |
| 14 | + chunk plan, writes the JSON tracker, and runs the `review-plan` gate |
| 15 | + before any code is written. This is the old `/implement` Phases 1-2.5 |
| 16 | + (analysis, chunk decomposition, dependency graph, tracker creation, |
| 17 | + plan-review gate), promoted from a buried mid-`/implement` checkpoint to |
| 18 | + a first-class command. The plan-review gate is the most important |
| 19 | + checkpoint in the loop, now its own visible step. |
| 20 | +- **Convergence back-edge**: when a code-time finding (Phase 3) reveals |
| 21 | + that the *plan* was wrong (not just the code), `/implement` appends |
| 22 | + corrective chunks to the tracker and re-gates in-session by spawning the |
| 23 | + `review-plan` agent directly (not by re-invoking `/plan`, which would |
| 24 | + regenerate the tracker), preserving completed chunks and looping under a |
| 25 | + bounded guard until the plan and code converge. `/plan` gained a |
| 26 | + `/spec`-style detect-existing-tracker branch so a re-run merges into the |
| 27 | + existing tracker instead of resetting completed work. |
| 28 | +- **`spec_doc` tracker field**: `/plan` records the source spec path so |
| 29 | + `/implement` and `review-impl` bind to the exact spec instead of |
| 30 | + globbing the spec directory (sharpens spec -> tracker traceability). |
| 31 | +- **Shared concern vocabulary**: the seven concerns common to `review-plan` |
| 32 | + (plan-time) and the Phase 3 checklist (code-time) are now documented as |
| 33 | + one vocabulary in `quality-checklist.md`, so the reviewers speak the same |
| 34 | + language at both altitudes (the eighth concern is phase-specific: TDD |
| 35 | + Quality of the plan vs Blindspots in the code). |
| 36 | +- **Three-state acceptance-criteria verification**: `review-impl` |
| 37 | + classifies each criterion CONFIRMED / PLAUSIBLE / REFUTED, each backed by |
| 38 | + a quoted line, recall-biased (default PLAUSIBLE; only CONFIRMED when a |
| 39 | + real test would go red on regression). Ported from the `red-team` |
| 40 | + verification model. |
| 41 | +- **Spec validation evidence rule**: every WARN/FAIL in the spec |
| 42 | + validation checklist must quote the exact spec line it refers to, the |
| 43 | + same discipline the review agents apply to code. |
| 44 | +- **validate.sh checks**: a harness-agnosticism check fails if any |
| 45 | + harness-specific mechanic (`Shift+Tab`, `Ctrl+G`, `/compact`, `/rename`, |
| 46 | + `--resume`, and similar) reappears in the skill or agent prose; the |
| 47 | + structural suite (~220 checks) also enforces the three-skill layout, |
| 48 | + phase sequencing, JSON validity, no project-specific leaks, and no em |
| 49 | + dashes in any published file. |
| 50 | +- **Empirical validation**: the higher-risk changes, the |
| 51 | + `review-impl`/`red-team` de-overlap (does a defect ever fall between |
| 52 | + them?) and the three-state false-positive catch, were validated with an |
| 53 | + A/B eval harness over seeded fixtures rather than by inspection alone. |
| 54 | + |
| 55 | +### Changed |
| 56 | +- **`/implement` is now build-only** (3 phases): Load the Plan (locate the |
| 57 | + tracker, hard-stop unless its `plan_review` gate passed, orient on the |
| 58 | + next chunk), TDD Cycle per chunk (red/green/verify), and Quality |
| 59 | + Verification (8-point checklist + parallel `review-impl` + `red-team` |
| 60 | + gate). It refuses to start the TDD cycle on a tracker whose `plan_review` |
| 61 | + is missing or FAIL, telling the user to run `/plan` first. |
| 62 | +- **`/spec` hands off to `/plan`** instead of `/implement`; its downstream |
| 63 | + mapping now routes spec sections to `/plan` (analysis, chunking) and |
| 64 | + `/implement` (tests) phases. |
| 65 | +- **Plan artifacts moved with the plan**: `tracker-schema.md` and |
| 66 | + `chunk-template.md` now live under `skills/plan/references/`; |
| 67 | + `quality-checklist.md` stays under `skills/implement/references/` (it is |
| 68 | + the Phase 3 code checklist). Each skill cross-references the one shared |
| 69 | + file it needs. |
| 70 | +- **review-impl narrowed to a conformance gate**: it verifies plan match, |
| 71 | + acceptance criteria (with quoted test evidence), test quality, and |
| 72 | + regression only. Adversarial correctness, robustness/blindspots, |
| 73 | + standards violations, and cleanup are deferred to `red-team`, which |
| 74 | + already does them better. This removes the overlap between the two |
| 75 | + Quality-Verification reviewers while preserving their |
| 76 | + conformance-vs-correctness separation. |
| 77 | +- **Harness-agnostic instructions**: removed terminal-specific mechanics |
| 78 | + from the skill prose in favor of portable behavior. Plan presentation |
| 79 | + states the principle (planning is read-only; present a plan; get explicit |
| 80 | + approval) and lets the harness supply the mechanism; context management |
| 81 | + and session resumption describe the intent instead of naming specific |
| 82 | + keystrokes or commands. Exploration and check-running steps use |
| 83 | + conditional phrasing: use a subagent or parallel-tool capability if the |
| 84 | + harness has one, otherwise sequential is the default. The workflow tables |
| 85 | + are retitled "Mapping to the Explore -> Plan -> Code Loop" with no harness |
| 86 | + brand in the header. |
| 87 | +- **review-plan / review-impl repointing**: `review-plan`'s description now |
| 88 | + says "in the /plan skill"; both agents read "the project's engineering |
| 89 | + `PROJECT.md`" rather than "PROJECT.md in the skill directory" (there are |
| 90 | + now three skills); `review-impl`'s Criterion 5 and the checklist |
| 91 | + reference `/implement` Phase 3 (Quality Verification). Agent names are |
| 92 | + unchanged (`review-plan`, `review-impl`, `red-team`). |
| 93 | +- **review-plan Criterion 1** renamed "Scope, Completeness & Traceability" |
| 94 | + with explicit spec -> plan -> tracker forward/backward traceability |
| 95 | + language. |
| 96 | +- **Scaffolding trim**: default to continuing multi-chunk work in one |
| 97 | + session rather than resetting between chunks; reset only when context |
| 98 | + degrades. Chunk decomposition prefers the fewest independently-testable |
| 99 | + chunks. |
| 100 | + |
| 101 | +### Migration |
| 102 | +- The workflow gains one user-invoked step: after `/spec`, run `/plan`, |
| 103 | + then `/implement`. Trackers created by an older `/implement` run without |
| 104 | + a `plan_review` field will be refused by the new `/implement`; run |
| 105 | + `/plan` (pointed at the existing tracker/spec) to gate them, or set |
| 106 | + `plan_review` manually if the plan was already reviewed. Hand-setting |
| 107 | + `plan_review: "PASS"` bypasses the review-plan gate: `/implement` trusts |
| 108 | + the field and cannot tell a gate-written verdict from a typed one. |
| 109 | + |
| 110 | +### Fixed (design stress-test) |
| 111 | +Hardening from an adversarial review of the whole v3.0.0 design: |
| 112 | +- **Plan-time gate crash-safety**, the symmetric twin of the convergence |
| 113 | + fix. `/plan` creates the tracker with `plan_review: "PENDING"` (never a |
| 114 | + pre-stamped `PASS`), writes `FAIL` to disk *before* re-running on a gate |
| 115 | + FAIL, and bounds the FAIL/re-run loop, so a crash mid-review can no |
| 116 | + longer leave a stale `PASS` that `/implement` would build against. |
| 117 | +- **`error` and `in_progress` chunks are no longer dead-ends.** `error` is |
| 118 | + documented as non-terminal (re-entered like `in_progress`); `/implement` |
| 119 | + Phase 1.3 validates the chunk graph (rejecting `depends_on` cycles and |
| 120 | + dangling ids); resumption re-enters an unfinished chunk before searching |
| 121 | + for the next `pending` one, so a blocked feature is surfaced, not |
| 122 | + silently left with the Phase 3 gate un-triggered. |
| 123 | +- **Convergence re-gate loop is now counted.** `convergence_rounds` is |
| 124 | + bumped before *each* `review-plan` re-gate (not only when chunks are |
| 125 | + appended), so the two-round cap bounds the re-gate loop too; a bail-out |
| 126 | + cleanup path is documented. |
| 127 | +- **Spec back-edge.** A finding that an acceptance *criterion itself* is |
| 128 | + wrong now routes to `/spec` (update mode) instead of into the plan gate |
| 129 | + built to reject it. |
| 130 | +- **Honest degradation without subagents / without a project rule file.** |
| 131 | + The gates document that a harness with no subagent capability degrades |
| 132 | + to a non-isolated self-check; `/implement` Phase 3 covers standards and |
| 133 | + architecture with a self-check when no `PROJECT.md`/`CLAUDE.md` exists |
| 134 | + (where `red-team`'s conventions angle would otherwise return nothing). |
| 135 | +- **Docs.** Softened the "1:1 gates" phrasing (`/implement` touches two |
| 136 | + gates via convergence); README's table notes review-plan's convergence |
| 137 | + spawn; tracker writes documented as atomic. |
| 138 | + |
3 | 139 | ## 2.5.0 |
4 | 140 |
|
5 | 141 | ### Changed |
|
0 commit comments