diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 957ce0e..80ce5b7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "voyage", "description": "Voyage — brief, research, plan, execute, review, continue. Contract-driven Claude Code pipeline. /trekbrief, /trekplan, and /trekreview each end by building a self-contained operator-annotation HTML (scripts/annotate.mjs, modelled on claude-code-100x): select text or click any element, pick intent (Fiks/Endre/Spørsmål), write comment, copy structured prompt, paste back, Claude revises the .md.", - "version": "5.1.1", + "version": "5.5.0", "author": { "name": "Kjell Tore Guttormsen" }, diff --git a/CHANGELOG.md b/CHANGELOG.md index 54cd59a..32475c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,54 @@ 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.5.0 — 2026-06-18 — Coordinated release: brief framing enforcement (2.2) + W1–W3 narrow wins + +The coordinated release held since the framing work. Supersedes the unreleased internal milestones **v5.2–v5.4** (W2 model/effort alignment, W3 guardrail hardening, the Handover-1 public-contract formalization), landing them together with the `brief_version 2.2` schema badge and the W1 narrow wins. **Additive — no breaking change for existing consumers:** every `2.0`/`2.1` brief still validates; the new requirements gate only on briefs that *declare* `brief_version: "2.2"`. + +### Brief framing enforcement — `brief_version 2.2` (the headline) + +Three version-gated layers ship at `brief_version ≥ 2.2`, implementing the `CLAUDE.md` cross-cutting invariant "brief framing must match operator intent": + +- **`framing` enum** (`preserve | refine | replace | new-direction`) — required in frontmatter, collected in `/trekbrief` Phase 2.5 *before* any prose is written, non-skippable even in `--quick`. Enum-checked on any version (`BRIEF_INVALID_FRAMING`); missing at ≥ 2.2 → `BRIEF_MISSING_FRAMING`. +- **Memory-alignment dimension** — new `brief-reviewer` dimension 6 compares brief Intent/Goal + framing against operator memory, flagging *explicit* contradictions only (scores N/A when no memory is supplied); wired to the Phase 4e gate (`memory_alignment.score ≥ 4`). +- **Obligatory `## TL;DR`** — ≤ 5 content lines at the top of every 2.2 brief (soft cap → `BRIEF_TLDR_TOO_LONG`). + +Existing `2.0`/`2.1` briefs stay valid (forward + backward compatible), mirroring the `phase_signals ≥ 2.1` precedent. `trekreview` briefs are exempt. + +### Public contract formalization (Handover 1) + +`docs/HANDOVER-CONTRACTS.md` §Handover 1 (`brief.md` → research) is now labeled **PUBLIC CONTRACT** — the only public integration boundary of the pipeline. Froze `brief_version 2.1` as the baseline, then evolved it to `2.2` under the breaking-change protocol. Any conforming producer (not just `/trekbrief`) may feed Voyage; brief-schema changes are breaking for every downstream consumer. + +### Model & effort alignment (W2) + +- **Opus 4.8 baseline** — the `opus` alias resolves to Opus 4.8 (default reasoning effort `high`). +- **Native `effort:` frontmatter** (additive, static) on 8 agents: retrieval (`task-finder`, `git-historian`, `dependency-tracer`, `architecture-mapper`) → `medium`; adversarial-reasoning (`plan-critic`, `risk-assessor`, `contrarian-researcher`, `review-coordinator`) → `high`. The other 15 agents inherit the Opus-4.8 default. +- **Resolver model-gate fix** — `lib/profiles/phase-signal-resolver.mjs` now gates `model` against `BASE_ALLOWED_MODELS` (mirrors the existing `effort` gate); out-of-allowlist models are dropped rather than handed to a spawn. +- **Axis distinction documented** — `docs/profiles.md` §Model & effort axes separates orchestration `phase_signals.effort` (which agents/passes run) from native reasoning `effort:` (per-spawn budget) — different axes that happen to share the name `effort`. + +### Guardrails & hooks hardening (W3) + +- **Exec-form hooks** (CC-14) — all 7 hooks in `hooks/hooks.json` migrated to `{command:"node", args:["${CLAUDE_PLUGIN_ROOT}/…"]}`, removing a class of path-quoting bugs for consumers who install Voyage under a path containing spaces. +- **`disallowed-tools` enforcement** (CC-11) — `disallowed-tools: Agent, TeamCreate` added to `/trekexecute`, promoting its documented no-delegation rule from prose to enforcement (`allowed-tools` grants auto-approval but does not remove a tool from the pool; `disallowed-tools` does). +- **Universal safety executors** (CC-15) — `pre-bash-executor.mjs` / `pre-write-executor.mjs` confirmed universal by design (session-agnostic safety; narrowing to execute-only sessions would only weaken protection). + +### Narrow wins (W1 — NW1–NW3) + +- **NW1 — reviewer-output schema contract** (ungated, shipped). `lib/review/findings-schema.mjs` validates each `/trekreview` Phase 5 reviewer's JSON against a schema; on *schema* failure main re-asks for conforming JSON (bounded N=2), retiring the fragile "collect trailing JSON / re-ask on parse error" contract. +- **NW2 — trekreview Workflow port as opt-in `--workflow` flag.** Phase 5–6 (`parallel([conformance, correctness])` → plain-JS dedup-by-`(file,line,rule_key)` → `agent(coordinator)`) ported to a Workflow script, reachable via `--workflow` (default stays prose, preserving the 2.1.154+ portability floor). Bake-off verdict **POSITIVE**: fidelity-equivalent `review.md`, zero classifier interference at 9-agent concurrency, acceptable cost (≈ +4.4% tokens). +- **NW3 — synthesis-agent shipped dormant (declined per measurement).** Built + measured deterministically: Δ main-context = **0%** at all realistic BASE — delegating only trekplan Phase 7 evicts nothing, since the Phase-5 foreground reads make the outputs resident first. Not wired; re-measurement is cheap via `scripts/synthesis-measure.mjs`. See `docs/T1-synthesis-poc-results.md`. + +### CC 2.1.130→181 verification dispositions + +- **Verified clean (no regression):** CC-29 (`subagent_type` matching now case/separator-insensitive; no Voyage agent declares multiple `Agent(...)` types), CC-31 (the tightened background worktree-isolation guard aligns with Voyage's intent — `/trekplan` `TeamCreate isolation:"worktree"` with sequential fallback, `/trekexecute` Phase 2.6 worktree waves). +- **CC-08 — GH #36071 (hooks in headless `claude -p`) closed as NOT PLANNED, not fixed.** The in-prompt safety preamble is retained as the headless defense. +- **Deferred (recorded, no code):** CC-07 (`fallbackModel`), CC-12 (Stop/SubagentStop `additionalContext`), CC-13 (`background_tasks`/`session_crons` in hook input). Triggers noted in `docs/cc-upgrade-2.1.181-decision-matrix.md` §S13. + +### Release hygiene + +- **Version sync** — `plugin.json`, `package.json`, README badge, and the CHANGELOG top entry all at `5.5.0`, guarded by a new version-consistency test in `tests/lib/doc-consistency.test.mjs`. +- **`claude plugin validate` passes.** The single advisory warning (root `CLAUDE.md` not loaded as consumer project context) is **accepted by design**: it is universal across all marketplace plugins, validation still passes, and the root `CLAUDE.md` is repo/maintainer context — consumer context ships via README + command/agent frontmatter. + ## v5.1.1 — 2026-05-14 — Remediation patch (11/12 review findings closed) Additive. No breaking changes against v5.1.0. Closes 11 of 12 BLOCKER/MAJOR/MINOR findings from the v5.1.0 review (sesjon 5, review.md SHA range `8cbb33e..8f4b79c`). SC8 dogfood gate (#5) is scheduled for sesjon 8 as a fresh-CC-session operator action — its closure cannot happen inside the v5.1.1 execute session. diff --git a/README.md b/README.md index 08f9f2d..9f25ca6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # trekplan — Brief, Research, Plan, Execute, Review, Continue -![Version](https://img.shields.io/badge/version-5.1.1-blue) +![Version](https://img.shields.io/badge/version-5.5.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) @@ -10,11 +10,12 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, and zero-friction multi-session resumption. Six commands, one pipeline: -> **What's new — brief framing enforcement (`brief_version 2.2`)** — `/trekbrief` now opens with a **framing declaration** (Phase 2.5): every brief records `framing: preserve | refine | replace | new-direction` *before* any prose is written, so the plan can't quietly polish a wrong premise. Three version-gated layers ship at `brief_version ≥ 2.2`: +> **What's new in v5.5.0 — brief framing enforcement (`brief_version 2.2`) + narrow wins** — `/trekbrief` now opens with a **framing declaration** (Phase 2.5): every brief records `framing: preserve | refine | replace | new-direction` *before* any prose is written, so the plan can't quietly polish a wrong premise. Three version-gated layers ship at `brief_version ≥ 2.2`: > - **Framing field** — a required `framing` enum in frontmatter; enum-checked on any version, and a missing value at `≥ 2.2` is a blocker. Collected in Phase 2.5 before prose, non-skippable even in `--quick`. > - **Memory alignment** — a new `brief-reviewer` dimension compares the brief's Intent/Goal + framing against operator memory and flags *explicit* contradictions (a no-op that scores N/A when no memory is supplied). > - **Obligatory `## TL;DR`** — a ≤ 5-line, framing-anchored summary at the top of every brief, so a wrong premise is caught at a glance. -> Existing `2.0`/`2.1` briefs stay valid (forward + backward compatible), mirroring the `phase_signals ≥ 2.1` gate. This is a **schema-axis** change — the plugin version badge bumps at the next coordinated release; see [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md) §Handover 1 for the contract evolution. +> Existing `2.0`/`2.1` briefs stay valid (forward + backward compatible), mirroring the `phase_signals ≥ 2.1` gate. This is a **schema-axis** change — the plugin version badge bumped to **v5.5.0** at this coordinated release; see [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md) §Handover 1 for the contract evolution. +> **Also in v5.5.0:** a reviewer-output **schema contract** for `/trekreview` (validates each reviewer's JSON, re-asks on schema failure); an opt-in **`--workflow`** path for `/trekreview` Phase 5–6 (bake-off POSITIVE; default stays prose to preserve the 2.1.154+ portability floor); **Opus 4.8** baseline with native `effort:` on 8 agents; exec-form hooks + enforced `disallowed-tools` on `/trekexecute`. Full arc in [CHANGELOG.md](CHANGELOG.md). > > **What's new in v5.1.1** — Remediation patch closing 11 of 12 findings from the v5.1.0 review (SC8 dogfood gate scheduled for sesjon 8). Lukker: > - **Bug fixes (load-bearing):** YAML-number bypass in `brief-validator` (#8) + doc-consistency pin lock-in (#11) so the gate fires for both quoted and unquoted `brief_version`. diff --git a/docs/cc-upgrade-2.1.181-decision-matrix.md b/docs/cc-upgrade-2.1.181-decision-matrix.md index 51e2a5c..0adeca6 100644 --- a/docs/cc-upgrade-2.1.181-decision-matrix.md +++ b/docs/cc-upgrade-2.1.181-decision-matrix.md @@ -195,6 +195,52 @@ prose-vs-Workflow bake-off was specified but **not run**. design (thresholds POSITIVE/NEGATIVE/INCONCLUSIVE), §6 no-Workflow schema-contract PoC, all ready to run if the operator greenlights tier 1 and/or tier 2. +## S13 resolutions (RELEASE — 2026-06-18, operator-gated) + +S13 is the coordinated release that lands everything accumulated since `v5.1.1`: the +`brief_version 2.2` framing badge (held since S6), the W2/W3 hardening, and the W1 narrow wins +(NW1–NW3). Operator confirmed **two release decisions** (2026-06-18): version `5.5.0` and the +CLAUDE.md-warning disposition (below). Shipped as **v5.5.0** — see `CHANGELOG.md`. + +- **Version = `5.5.0` (operator-confirmed).** The codebase already labels the framing milestone + `v5.5` and the contract formalization `v5.4` in ~25 test/doc sites; `5.5.0` makes those true + against the shipped version. Minor bump (additive — existing `2.0`/`2.1` briefs still validate; + new requirements gate only on briefs that *declare* `2.2`). Versions `5.2`–`5.4` were never + released — internal milestone labels folded into this one coordinated entry. Synced across + `plugin.json` + `package.json` + README badge + CHANGELOG top, guarded by a new + version-consistency test in `tests/lib/doc-consistency.test.mjs`. +- **CLAUDE.md root warning — ACCEPTED BY DESIGN (operator-confirmed).** `claude plugin validate` + emits one advisory warning ("root: CLAUDE.md … is not loaded as project context; use a skill + instead"). **Verified universal** across the marketplace (`graceful-handoff` emits the identical + warning *even with* a `skills/` dir — adding a skill does NOT clear it). It is advisory only + (validation passes), and the root `CLAUDE.md` is repo/maintainer context — consumer context ships + via README + command/agent frontmatter. Removing it would lose in-repo project instructions and + break the global continuity system. Disposition recorded so future sessions do not re-chase an + impossible "fix"; `validate` stays "passed with warnings" as the expected steady state. +- **CC-08 — RESOLVED: keep the safety preamble.** GH #36071 (PreToolUse hooks don't block in + headless `-p` mode) is **CLOSED AS NOT PLANNED, not fixed** (verified against the issue + official + changelog; the recent "hook deferral" feature is a workaround, not a fix to the headless + synchronization bug). The in-prompt safety preamble (`trekexecute.md:341`, + `templates/headless-launch-template.md:48`) **stays** — do not relax it on a silence-implies-fixed + assumption. +- **CC-29 — VERIFIED clean (SHIP).** `subagent_type` matching is now case/separator-insensitive and + multiple `Agent(...)` type grants are no longer dropped. No Voyage agent declares multiple + `Agent(...)` types in `tools:`; `subagent_type` references (`/trekplan`'s `"Explore"`, the + namespaced `voyage:*` agentTypes in the trekreview Workflow port) are unaffected. Free robustness, + no code change. +- **CC-31 — VERIFIED aligned (no change).** The tightened background worktree-isolation guard + (2.1.154) reinforces exactly Voyage's intent: isolate parallel waves. `/trekplan` uses + `TeamCreate isolation:"worktree"` with a documented sequential fallback when `TeamCreate` is + unavailable; `/trekexecute` Phase 2.6 creates/merges/cleans worktrees per wave with stale-worktree + cleanup. Doc-level verification (no live multi-session wave run this session); behavior consistent + with the guard. +- **CC-07 / CC-12 / CC-13 — DEFER confirmed (recorded, no code).** CC-07 (`fallbackModel`) triggers + when `/trekexecute` Phase 2.6 launch flags are next touched. CC-12 (Stop/SubagentStop + `additionalContext`) and CC-13 (`background_tasks`/`session_crons` in Stop-hook input) adopt when + the continuity-flush / OTLP exporter is next touched. No current gap forces any of them. +- **Final gates.** `claude plugin validate` passes (one accepted advisory warning); full `node --test` + green. Test count rises by the 2 new version-consistency/changelog-entry tests. + ## Sequencing ``` diff --git a/package-lock.json b/package-lock.json index 7d55cd3..ab216ab 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "voyage", - "version": "5.1.1", + "version": "5.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "voyage", - "version": "5.1.1", + "version": "5.5.0", "license": "MIT", "engines": { "node": ">=18" diff --git a/package.json b/package.json index faab9fc..d141c9c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "voyage", - "version": "5.1.1", + "version": "5.5.0", "description": "Voyage — brief, research, plan, execute, review, continue. Contract-driven Claude Code pipeline. /trekbrief, /trekplan, and /trekreview each end by building a self-contained operator-annotation HTML (scripts/annotate.mjs, modelled on claude-code-100x): select text or click any heading/paragraph/list-item, pick intent (Fiks/Endre/Spørsmål), write comment, copy structured prompt, paste back, Claude revises the .md.", "type": "module", "engines": { diff --git a/tests/lib/doc-consistency.test.mjs b/tests/lib/doc-consistency.test.mjs index f23bc76..b4f05b0 100644 --- a/tests/lib/doc-consistency.test.mjs +++ b/tests/lib/doc-consistency.test.mjs @@ -537,6 +537,24 @@ test('CHANGELOG.md retains v4.2.0 entry (history is not rewritten)', () => { assert.match(cl, /## v4\.2\.0\b/, 'CHANGELOG.md must keep the historical "## v4.2.0" entry'); }); +test('CHANGELOG.md has v5.5.0 entry (S13 coordinated release)', () => { + const cl = read('CHANGELOG.md'); + assert.match(cl, /## v5\.5\.0\b/, 'CHANGELOG.md must include "## v5.5.0" entry — the coordinated release that lands brief_version 2.2 + NW1–NW3'); +}); + +test('version is consistent across plugin.json, package.json, README badge, and CHANGELOG top entry', () => { + // versjonssync invariant (CLAUDE.md rule): every file that names the plugin + // version must agree. Bumping one without the others is a release defect. + const pluginVersion = JSON.parse(read('.claude-plugin/plugin.json')).version; + const pkgVersion = JSON.parse(read('package.json')).version; + const badgeVersion = (read('README.md').match(/badge\/version-([\d.]+)-/) || [])[1]; + const changelogTop = (read('CHANGELOG.md').match(/## v(\d+\.\d+\.\d+)\b/) || [])[1]; + assert.ok(pluginVersion, 'plugin.json missing version'); + assert.equal(pkgVersion, pluginVersion, `package.json version ${pkgVersion} != plugin.json ${pluginVersion}`); + assert.equal(badgeVersion, pluginVersion, `README badge ${badgeVersion} != plugin.json ${pluginVersion}`); + assert.equal(changelogTop, pluginVersion, `CHANGELOG top entry v${changelogTop} != plugin.json ${pluginVersion}`); +}); + test('operational files no longer reference trekrevise (v5.0.0 removal)', () => { // Templates, the touched command/orchestrator files, settings.json, and the // handover-contracts doc must be fully scrubbed. CLAUDE.md / README.md are