docs(voyage): add CHANGELOG entry for v5.1.0

plugins/voyage/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## v5.1.0 — 2026-05-13 — Per-phase effort + model dialog
+
+Additive. No breaking changes. Forward-compat with all v5.0.x briefs.
+
+### Why
+
+The voyage pipeline runs a single profile-tier setting for every task. For
+typo fixes and small bugfixes the full `brief → research → plan → execute
+→ review` ceremony is over-engineered; for risky migrations the same
+profile-tier is too thin. v5.1 hands ceremony-level back to the operator
+per phase in the same dialog that produces the brief — without removing
+the disciplined defaults that protect high-stakes work. Independent of
+v4.1's profile system: composition happens at the command level (brief
+signal wins per-phase, profile fills gaps). No `/trekflow`, no helper
+module, no per-command effort dictionary — composition is documented
+prose in each downstream command.
+
+### Added
+
+- **`/trekbrief` Phase 3.5** — between Phase 3 completeness exit and
+  Phase 4 draft, 4 tier-coupled `AskUserQuestion` calls commit an effort
+  level (`low | standard | high`) and an optional `model` (`sonnet |
+  opus`) per downstream phase (`research`, `plan`, `execute`, `review`).
+  Tier mapping: `low → {effort: low, model: sonnet}`, `standard →
+  {effort: standard}` (model omitted; composition falls through to
+  profile), `high → {effort: high, model: opus}`. Force-stop pattern
+  (Phase 4f verbatim) records `phase_signals_partial: true` instead.
+  `--quick` skips Phase 3.5 entirely and auto-writes
+  `phase_signals_partial: true`.
+- **`brief-validator` extension** — 6 new issue codes:
+  `BRIEF_INVALID_PHASE_SIGNALS`, `BRIEF_INVALID_PHASE_SIGNAL_PHASE`,
+  `BRIEF_INVALID_EFFORT`, `BRIEF_INVALID_MODEL`,
+  `BRIEF_SIGNALS_MUTUALLY_EXCLUSIVE`, `BRIEF_V51_MISSING_SIGNALS` +
+  exported `PHASE_SIGNAL_PHASES` + `EFFORT_LEVELS` constants. The
+  `BASE_ALLOWED_MODELS` const in `lib/validators/profile-validator.mjs`
+  was promoted to `export const` so the brief validator can re-use it.
+- **HANDOVER-CONTRACTS amendments** — Handover 1 gets 5 inserts:
+  versioning row → `2.1`, two new schema-table rows (`phase_signals`,
+  `phase_signals_partial`), v5.1 sequencing-gate validation row,
+  versioning-paragraph expansion explaining the version-conditional
+  gate, 6 new failure-mode bullets.
+- **Template bump** — `templates/trekbrief-template.md` → `brief_version
+  2.1` with a default `phase_signals:` block (4 phases × `effort:
+  standard`, model omitted) and a commented `phase_signals_partial:
+  true` line showing the force-stop alternative.
+- **Composition rule (v5.1)** — new `## Composition rule (v5.1)`
+  sub-section in each of `commands/{trekplan,trekresearch,trekexecute,
+  trekreview}.md`. Documents `effort_for_phase = brief.phase_signals[
+  <phase>]?.effort ?? 'standard'` and `model_for_phase =
+  brief.phase_signals[<phase>]?.model ?? profile.phase_models[<phase>]`.
+  Per command: `effort == low` activates that command's existing
+  `--quick`-equivalent code-path (`/trekplan` skips Phase 5 agent swarm,
+  `/trekresearch` inline research, `/trekreview` correctness-only,
+  `/trekexecute` `--gates open` + sequential-only).
+- **Sequencing-gate surface** in 4 downstream commands — when
+  `brief-validator.mjs` returns `BRIEF_V51_MISSING_SIGNALS` in `errors`,
+  halt with a one-line user-readable message pointing back to
+  `/trekbrief`. Enforcement is validator-only.
+- **5 new minimal command test files** under `tests/commands/` —
+  `trekbrief.test.mjs` (3 cases), `trekplan.test.mjs` /
+  `trekresearch.test.mjs` / `trekreview.test.mjs` (2 cases each),
+  `trekexecute.test.mjs` (2 cases). Pattern D (read .md, assert prose
+  patterns). Verifies sequencing-gate surface + low-effort prose.
+- **5 new doc-consistency pins** — template `brief_version 2.1` +
+  `phase_signals:` block, HANDOVER schema rows, voyage CLAUDE.md +
+  README.md mention `phase_signals`.
+- **2 new fixtures** — `tests/fixtures/brief-with-phase-signals.md` +
+  `brief-without-phase-signals.md` (backward-compat).
+
+### Changed
+
+- `brief_version` bumped `2.0 → 2.1`. The bump exists because v2.1
+  activates the **version-conditional sequencing gate** — the only check
+  in the brief validator that triggers on `brief_version` rather than
+  field-presence. The forward-compat policy still applies to the field
+  itself (unknown frontmatter keys flow through).
+
+### Notes
+
+- Test count grows by ≥ 17 new cases minimum: 6 brief-validator + 11
+  command-test minimums. Realistic delta is ~25 new cases (Step 6 adds 5
+  doc-consistency pins on top). Target ≥ 533 pass at Step 10 verify.
+- `MIGRATION.md` was deliberately NOT created — v5.1 is an additive
+  minor (brief_version 2.0 → 2.1, not major). v5.4 may promote
+  `phase_signals` from optional to required (breaking change → 3.0).
+- High-effort behaviors for `/trekplan` / `/trekresearch` /
+  `/trekreview` are deferred to v5.1.1 per brief Non-Goal ("No complete
+  per-phase effort dictionary"). v5.1 locks only the low-effort floor.
+- `phase_signals_present` stats emission is also deferred to v5.1.1
+  (opt-in observability per Research 03 Q5).
+
 ## v5.0.3 — 2026-05-13 — Annotation UX matches the claude-code-100x reference
 
 **No new breaking changes beyond v5.0.0.** Forks consuming v5.0.2's