# Changelog

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/).

## Unreleased — plan_version 1.9, the trial-4 findings, session-clean tests

A new plan version, 1.9, in which every path in a step's `Files:` and on its
`Test first:` `File:` line stands first, in backticks, so the reader no longer
guesses paths from prose (decision 16). The same delivery closes the six
findings from the test repo's trial 4 and stops `npm test` from pointing a live
session's stop guard at a temp-repo lock. Every fix began with a test that
failed on the code before it. Suite 2381 (2379 pass, 0 fail, 2 skipped),
measured by `npm test` on Step 13's commit (`acd0e3d`), the commit before this
section.

Nothing here asks anything of users. Older plans warn, they do not fail: a plan
below 1.9 is read as in 6.3.1, apart from the fixes under Fixed, and gets one
warning per step whose `Files:` names a path that is not backticked.

### Doors

- two-way: plan_version 1.9 — a 1.9 plan read by 6.3.1 gets PLAN_VERSION_MISMATCH as a warning and the 6.3.1 reader, so a revert rewrites no plan.
- two-way: Files reader (three 6.3.0 answers restored) — a revert brings back 6.3.1's answers; no file format changes.
- two-way: every test file on the Test first File line — a revert reads the first file only again.
- two-way: brief-conflict mark on review findings — an older verdict gate ignores the field.
- two-way: approval commits require a Co-Authored-By trailer — only Voyage's own commands call the CLI, and they pass it.
- two-way: explorer prompts, stamp order, test env — prose and test-side only.

### Added

- **plan_version 1.9: the file first on every line.** Each entry of `Files:`
  and each `Test first:` `File:` line opens with its backticked path or paths;
  everything from the first other text on is description and is never read.
  A 1.9 plan that breaks this gets `PLAN_STEP_PATH_NOT_FIRST` or
  `PLAN_STEP_PATH_NOT_A_PATH` (errors under `--strict`, warnings without). The
  parser, the validator, the tests-only check, the plan-file sweep (K6) and red
  proof read a 1.9 plan by this grammar. 1.9 is the current target: Handover
  4, the plan template, `/trekplan`, the planning orchestrator and CLAUDE.md
  say so, and the rules introduced at 1.8 say "1.8 or later".
- **A warning for older plans.** Below 1.9, a path in `Files:` that is not
  backticked gets the warning `PLAN_STEP_PATH_UNTICKED`, under `--strict` too.
- **The brief-conflict mark.** A `/code-review` finding at the MAJOR tier whose
  recommended action goes against a brief Non-Goal or another stated choice
  drops to MINOR, marked `contradicts_brief` and `brief_lowered_from: MAJOR`;
  any other engine finding only gets the mark, and a BLOCKER is never lowered.
  `/trekreview` passes the brief's choices to the coordinator, which writes the
  mark into `review.md`; the opt-in workflow review applies the same rule and
  floors an illegal lowering. On an ALLOW or WARN review the verdict gate
  answers exit 2 for a finding lowered or marked outside that one shape:
  `brief_lowered_from` on any other finding, a mark on a reviewer finding, a
  mark or an engine finding below its catalogue tier, or a mark with a missing
  or unknown rule key.

### Fixed

- **The suite no longer hands the session id to the lock CLI.** `npm test`
  preloads a helper that removes `CLAUDE_CODE_SESSION_ID`, and every test that
  starts a child process passes an environment without it. A live session's
  stop guard is no longer pointed at a temp-repo lock.
- **The three `Files:` regressions from 6.3.1's Known issues** give 6.3.0's
  answer again: a source file after a described test is kept, a path that a
  description only mentions is not read as a file, and a backticked bare name
  such as `LICENSE` alone on a following line is read as a file.
- **Every test file on the `Test first:` `File:` line** is read, locked and
  copied for red proof, not only the first.
- **A 1.9 `Test first:` names its test only on a line that opens with
  `File:`**, the way the executor, K6 and red proof read it. Below 1.9 the
  check reads as before.
- **Engine provenance in the review.** Ingest takes `engine` from the payload,
  never from a field a reviewer wrote on its own finding, and on a severity tie
  the reviewer-agent finding is kept over the engine finding, in the
  coordinator's Pass 1 and in the workflow dedup. A brief-conflict mark can no
  longer lower a reviewer's MAJOR (operator decision 2026-10-12).
- **Explorers and reviewers stay in the repo.** `/trekplan` tells its
  brief-reviewer, the eight Phase 5 explorers, the Phase 6 deep-dives, the
  plan-critic and the scope-guardian to read local files only inside the repo
  under exploration plus the paths their prompt gives, and every explorer gets
  the brief.
- **The brief review stamp covers only text the reviewer saw.** For a `small`
  brief, the reviewer's gaps are written after the stamp, so the stamp reads
  stale and `/trekplan` reviews the brief once more.
- **Approval commits carry the caller's Co-Authored-By trailer.**
  `artifact-commit.mjs` takes `--trailer` and refuses (exit 1, before anything
  is staged or committed) a missing, multi-line or malformed trailer, an unfilled `{model}`, and
  one that names a session link. `/trekbrief`, `/trekplan` and `/trekexecute`
  pass it; `/trekexecute` prints the reason and goes on when the approval is
  logged but not committed.

### Known issues

- The session split reads a 1.9 plan as an older plan (operator answer 3).
- Marked MINOR findings still feed `recurrence` / project-memory proposals.

## v6.3.1 — 2026-10-11 — Fixes from the release review of 6.3.0, and two verdict-gate holes closed

Rounds 7 to 10 of the release review of 6.3.0. Round 7 is the WARN 6.3.0 was
released with, round 8 was BLOCK (1 BLOCKER), rounds 9 and 10 were WARN. Every
fix began with a test that failed on the code before it. Suite 2236 (2234
pass, 0 fail, 2 skipped).

Nothing here asks anything of users. Measured against 6.3.0 over the
marketplace and the test repo: the plan validator reports the same errors and
warnings for all 233 plan files, the verdict gate gives the same exit for all
123 review files, and tests-only reads the same for all 1408 plan steps.

### Doors

- two-way: tests-only is decided by the plan's `Files:` alone, and red proof no longer reads the step's diff (operator decision 2026-10-11) — a revert brings the diff check back; plans stay valid.
- two-way: the `Files:` reader keeps a plain file beside a backticked path, reads numbered entries, and keeps a description together across commas and lines — it feeds only the `PLAN_STEP_TESTS_ONLY` warning and red proof's `tests_only`; a revert restores the 6.3.0 reading.
- two-way: a trailing `# comment` is dropped from a backticked check too, so such a check now runs; one whose comment holds a double quote, `$`, a backtick or a backslash is refused out loud — 6.3.0 refused every backticked check with a comment, so nothing that ran stops running.
- two-way: the verdict gate reads the last fenced block once and answers exit 2 unless its info string is exactly `json`, or when it is never closed; a `~~~` fence is a fence — a review written by `/trekreview` reads as before; a revert reopens the two holes under Fixed.
- two-way: stops and timeouts, the release check's `--review`, `isMain` in every CLI, the test lock's command comparison, one fence reader, and cleanups — fixes; a revert restores the old behaviour.

### Fixed

- **Two verdict-gate holes, present in 6.3.0.** A review that ended with a
  clean json block and then a block holding a BLOCK verdict, written as
  `~~~json` or opened with more text after `json` on its line, passed with
  exit 0: the gate did not see the second block. Both are exit 2 now.
- **Tests-only steps.** The plan's `Files:` alone decides, and red proof,
  `/trekexecute`, `step-implementer` and the handover contract say so. A change
  already in the tree when the step began no longer counts against it, and a
  plan outside `.claude/` reads the same.
- **The `Files:` reader** keeps a plain file beside a backticked path
  (", Dockerfile", "and Makefile"), reads a numbered entry (`1.` or `1)`) as an
  entry, keeps a description together past a comma and onto the next line, and
  starts a description at a plain file followed by a colon. Lowercase
  `makefile`, `rakefile` and `justfile` are build files.
- **Checks with a comment.** A trailing `# comment` is dropped in a backticked
  check and in a command passed as written, so the words screened are the
  words run. A comment with a double quote, `$`, a backtick or a backslash is
  refused instead, because the executor hands the `Verify:` span to red proof,
  the test lock and the done line inside double quotes. Every reader refuses it
  out loud (`PLAN_VERIFICATION_NOT_RUNNABLE`, `BRIEF_SC_NOT_RUNNABLE`). A span
  that is only a comment is not-a-command.
- **Stops.** Red proof reports a command killed by its timeout as killed after
  the timeout, not "could not start". The release check tells a timeout from
  output past its buffer and from another signal. One reading of a stop
  (`stoppedBy`) serves red proof, the criteria runner, the test lock, the done
  line and the release check.
- **Release check.** A relative `--review` is read in `--repo`, or from the
  current directory when only that one exists. Two different files are exit 2,
  never guessed, and one file reached through a symlinked `--repo` is one file.
- **Every CLI uses one `isMain` helper.** Before, some did nothing and exited 0
  when run through a symlink or a path with a space.
- **Test lock.** It compares `--cmd` by its words and without its trailing
  comment.
- **One fence reader** for the gate and every reader of a trailing json block.
  A fence closes only on a run at least as long as its opener, as in Markdown,
  and CRLF and an indented fence read alike everywhere. A fence indented four
  spaces or more still counts, on purpose: Markdown's rule made a BLOCKER block
  inside a list item invisible.
- **Cleanups.** The 15-minute timeout is defined once, the findings check reads
  each cited file once per validation, and the guard writes its no-one-to-ask
  refusal once.

### Known issues

Round 11 of the release review (`0f400d3..10ac9c5`) is WARN: 0 BLOCKER, 10
MAJOR, 0 MINOR. All ten come from Claude Code's `/code-review`, which gives no
category, so each enters as MAJOR. Voyage's two reviewers and
`/security-review` found none. The operator chose to release 6.3.1 with it
(2026-10-11). None of the ten lets a gate pass. The regressions below were
checked by running them against 6.3.0. None of them occurs in the 1408 plan
steps measured above.

- The `Files:` reader still guesses paths from prose and misreads in both
  directions. Two misreads are regressions from 6.3.0:
  - A source file after a described test is dropped
    ("`tests/a.test.mjs` - new test, src/a.mjs - the fix"). The step that
    builds code then reads as tests-only and goes to the plan.
  - A path that a description only mentions is read as a file ("covers the
    parser in src/parse.mjs"). A step of only tests is then not caught and
    goes through fix rounds (at most five, then the operator).

  Red proof has no diff check behind the reader. The structural fix is to
  require every path in `Files:` to be backticked. It changes the plan
  contract and is left for a planned release.
- A json block closed on the same line as its JSON is no longer read (a
  regression from 6.3.0). The gate answers exit 2, and a reviewer is asked
  again. An opener with a blank before `json` is not json either, as in 6.3.0.
- A trailing comment with a double quote, `$`, a backtick or a backslash is
  refused in every backticked check. That includes checks that never reach a
  shell: a `## Verification` bullet, `Regression:`, `End-to-end:` and a brief
  criterion. 6.3.0 refused these too.
- Cleanups: a dead branch for a span that is only a comment, the comment
  dropped up to four times per command, a re-export of the timeout that
  nothing imports, and a test helper that copies a PATH lookup.
- An engine run that was stopped and not counted in the verdict reported three
  more, each checked by running:
  - A backticked bare name such as `LICENSE`, alone on a line after a
    description, is no longer read as a file. 6.3.0 read it.
  - One unclosed fence earlier in a review hides the review's own json block
    from the review validator. 6.3.0 found the block, and the gate answers
    exit 2 there.
  - An indented json example after a review's own block is read as the last
    block, as in 6.3.0.
- The example plan's steps 1-2 keep their tests-only warning (operator
  decision 2026-10-09).

## v6.3.0 — 2026-10-11 — The executor is coupled to the review gate, three skills, and a drilled release runbook

Wave 2 of the practice build (five orders, merged 2026-10-09) and the fix round
after it, which closes finding 1 of the test repo's third trial: a step of only
tests can never be proven red. Every fix began with a test that failed on the
old code. Suite 2194 (2192 pass, 0 fail, 2 skipped).

Two changes ask something of users (see Doors): `/trekexecute` now refuses a
plan that has no logged approval for its current content, and a check in a
brief or plan runs with no shell, as plain words with a runner's read-only
options. Plan 1.7/1.8, brief
2.0–2.2 and review 1.0/1.1 files still validate; the new step fields are
optional.

### Doors

- one-way: `/trekexecute` refuses a plan whose logged approval does not cover its current sha256 (K2) — a plan written before 6.2.0, written by hand, or edited after its approval stops at Phase 1; run `/trekplan --project <dir>` and answer "Approve" (from 6.3.0).
- two-way: `/trekexecute` reviews by itself in the closing run (`/simplify` → `/trekreview` → verdict gate, K7) and keeps the main merge closed on BLOCK or an undecided verdict; step check (K9), `Regression:` (K10), architecture rules (K5) and plan-file sweep (K6) run at step end and after the last step — a revert restores the old executor; nothing to do for users.
- two-way: the approval guard refuses a merge into main, a push, a tag or publish and destructive git in the permission mode that shows no prompts — a revert lets them through again; nothing to migrate.
- two-way: `progress-validator` rejects the runner's `exitCode` in `plan_verification.failed_criteria` (C15) — the executor's own prose always wrote `exit_code`.
- two-way: skills workshop — form check, model-free routing test, `test-first` and `debugging` preloaded into `step-implementer` — new files and one `skills:` line; a revert removes them.
- two-way: `researching-sources` skill, preloaded by the five web-search agents and named by `/trekresearch` — the agents' copied rule text moved into the skill; a revert puts it back.
- two-way: `Regression:` (K10) and `On failure:` action words (K11) — an optional field and a warning; plans without them validate as before.
- two-way: trial 2's minor fixes (B8, B11, B12, C13, C14, C16, C17) — checks, prose and agent text; a revert restores the old behaviour.
- two-way: release check and runbook — new files; a revert removes them, and nothing else reads them.
- two-way: tests-only steps (`PLAN_STEP_TESTS_ONLY`, red-proof `--plan/--step` → `tests_only`, which also reads the step's own diff, executor routes them to the plan) — a warning and an optional flag; a revert removes them, plans stay valid.
- two-way: timing tests under load (hook helper kill limit 30 s, SC #14 fastest of three against 800 ms) — test-only.
- two-way: example plan `On failure:` lines open with a K11 word, and its verbose-content test moves into the step that wires the output (6 steps, progress.json follows) — text in an example.
- two-way: `/trekreview` saves the reviewer's whole answer for the findings check and names `FINDING_PROSE_LINE_OUT_OF_RANGE` — command text.
- two-way: the criteria runner's commands run without `NODE_TEST_CONTEXT` — a false green under `node --test` is now red; nothing to do for users.
- two-way: the fixes from the release review of 6.3.0 (rounds 1-6) — checks and prose; `progress.json` may now say `simplify: "revert-refused"` (an optional value); a revert restores the old behaviour.
- one-way: a check in a brief or plan (criteria, `Regression:`, proof of red, the done line, the test lock) runs with no shell: its words reach the runner as written, so only plain words run (no quote, backslash, `$`, brace, or `~`/`@` at a word's start; a glob only for `node --test` on Node 21 and later; no path that climbs out with `..` or starts at `/`, git included; a trailing `# comment` in a shell fence is dropped) with a short list of read-only options per runner — git without `--output` or `--no-index`, `node --test` with a built-in `--test-reporter` only, nothing after `make test`, only paths after `npm test --`; an option that writes a file or loads code is refused — a criterion that used one (`git log --grep="x"`, `pytest -k foo`, `pytest tests/test_*.py`, `jest --coverage`, `go test -timeout 30s`) is now NOT RUN at review and not runnable on a 1.8 plan; wrap it in `bash tests/<script>.sh` (from 6.3.0).
- two-way: the phase-model resolver text says `effort` comes only from the brief's phase signal — prose only, no code change.

### Added

- **`/trekexecute` is coupled to the gates** (order 6).
  - Plan approval (K2): `approval-log.mjs verify --kind plan` before step 1;
    `not-logged`, `mismatch`, `expired`, `broken` and `diverged` halt with what
    to do. Exit 2 is never a pass.
  - Step end: the step check (K9; exit 2 is "not measured") and the step's
    `Regression:` command (K10, new `lib/verification/regression-check.mjs`
    through the criteria runner) run green before the checkpoint.
  - After the last step: architecture rules (K5) and the plan-file sweep
    (K6); a violation or a file no step names turns `completed` into
    `partial`.
  - The closing run reviews by itself (Phase 7.2): run the thing,
    `/simplify`, `/trekreview`, verdict gate. A BLOCK adds the review's
    remediation steps after the plan validator accepts them and the operator
    re-approves the plan, at most `TREKEXECUTE_MAX_REVIEW_ROUNDS` (3) times.
  - The main-merge gate is a lock on the verdict, and where the guard asks,
    the executor does not ask again (one question per merge).
  - `progress.json` gains optional coupling fields (Handover 5).
- **Skills** (orders 7a and 7b), the first three: `voyage:test-first` and
  `voyage:debugging`, preloaded by `step-implementer`, and
  `voyage:researching-sources`, preloaded by the five web-search agents and
  named by `/trekresearch` at spawn. `lib/skills/skill-lint.mjs` checks the
  form; `lib/skills/routing.mjs` is a model-free routing test over the
  skills, the 7 commands and the 21 spawnable agents (collision at 0.75 fails;
  thresholds pinned). Eval cases `evals/skill-*` are written, not run.
  Authoring method: `docs/skills-authoring.md`.
- **Release and rollback** (order 8). `docs/release-runbook.md` (before, the
  release, both rollback paths drilled in a sandbox) and
  `scripts/release-check.mjs`: clean tree, `npm test` at HEAD, review verdict
  not BLOCK and covering HEAD, a `### Doors` list. 0 ready, 1 not ready, 2
  could not run.
- **Plan step rules** (order 9). `Regression:` — one allowlisted command,
  unpiped (`PLAN_STEP_REGRESSION_NOT_RUNNABLE`); `On failure:` opens with
  revert | retry | skip | escalate, or `PLAN_STEP_ON_FAILURE_UNKNOWN` warns.
  Minors open after the last critic round are listed for the operator, and
  `--extra-round` records the round they pick.
- **Tests-only steps** (order 10). `PLAN_STEP_TESTS_ONLY` warns on a step
  whose files are all tests; `red-proof --plan/--step` reports `tests_only`,
  and `/trekexecute` sends such a step to the plan instead of into fix rounds
  that cannot succeed. `/trekplan`, the plan template and `plan-critic` say
  the test belongs in the step that builds the behaviour.

### Fixed

- The approval guard refused only a merge into main and a push in the
  permission mode that shows no prompts; a tag, a publish and destructive git
  went through unattended. Now every call it would ask about is refused there.
- Plan-review dedup merges two findings on the same file:line with the same
  content; the Jaccard threshold for every other pair is unchanged.
- `/trekbrief` Step 4c says the brief reviewer runs in the background and is
  waited for.
- The Phase 4 size count includes `.mjs`, `.cjs`, `.mts`, `.cts`.
- `criteria-runner --evidence` shows the first output line on PASS rows.
- The findings schema checks `path:line` citations in finding prose against
  the file; `/trekreview` checks the reviewer's whole answer and names
  `FINDING_PROSE_LINE_OUT_OF_RANGE`.
- `git-historian` never proposes changing a file the brief froze, and names
  the remote from `git remote -v`.
- The criteria runner's commands run without `NODE_TEST_CONTEXT`, so a test
  run inside `node --test` can no longer pass falsely.
- Timing tests tolerate load (fastest of three; hook helper kill limit 30 s),
  and the K2 hook tests use unique session ids per run.
- The example plan's `On failure:` lines use the K11 words, and its
  verbose-content test moves into the step that wires the output. Steps 1-2
  (golden capture, stability harness) keep their tests-only warning; a step
  type for them is a later question, and step 2's heading no longer says it
  must fail.
- The resolver text in four commands says `effort` comes only from the
  brief's phase signal.
- Release review of 6.3.0 (seven rounds; rounds 1-3 BLOCK, rounds 4-7 WARN;
  every finding of rounds 1-6 fixed with a test that failed first, round 7's
  under Known issues): the guard refuses where
  no one can be asked also when its rules will not load; review steps appended
  by `/trekexecute` are held to the step rules on any plan version and need a
  `Verify:` (`plan-validator --steps-from`); a restore the guard refuses is
  recorded as `revert-refused` and stops the run before review, never as
  reverted; every check Voyage runs runs with no shell (round 5, the
  operator's structural fix after the patching of the shell screen did not
  converge), as plain words and each runner's read-only options; the release
  check compares version files without their version, lets the README change
  only in the badge's version, reads `scope_sha_end` as a commit sha, sees a
  file moved after the review, ignores Voyage's own artifacts committed after
  the review, runs the cheap checks first, stops a suite that never ends,
  works for a plugin in a subdirectory and never reports a crash as "not
  ready"; the plan-file sweep reads `Files:` as v6.2.0 did, and the
  tests-only check has its own reader, and red proof also reads the step's
  diff (see Known issues); skill frontmatter and routing read YAML values, comments and tags
  as YAML does; `regression-check` prints the progress.json status and runs
  through the criteria runner itself. `/trekexecute` says plainly that review
  steps in the template's own form stop with a re-plan.

### Known issues — for 6.3.1

The seventh round of the release review is WARN: 0 BLOCKER, 12 MAJOR, 0
MINOR. The operator chose to release 6.3.0 with it (2026-10-11); the findings
go into 6.3.1.

- Tests-only steps: when red proof decides, the step's diff in the documented
  flow holds only the test, so it cannot overrule the plan's `Files:` reading;
  a change already in the working tree when the step started counts against
  tests-only; an unbackticked file next to a backticked path in `Files:` is
  not read.
- Red proof reports a command killed by its timeout as "could not start". The
  release check calls a suite killed for too much output a timeout, and reads
  `--review` from the current directory instead of `--repo`.
- A trailing `# comment` is dropped in a fenced check but not in a backticked
  one.
- The example plan's steps 1-2 keep their tests-only warning (operator
  decision 2026-10-09; a step type for them is a later question).
- Four cleanups: the 15-minute timeout defined in three places, a line count
  read once per citation, `isMain` copied into five more CLIs, and a
  roundabout condition in the guard.
- Found while writing the review, and present in 6.2.0 too: the findings check
  ends a reviewer's json block at the first triple backtick, even one inside a
  JSON string.

## v6.2.0 — 2026-10-08 — Intent, plan gate, step helpers, guards and a review that is a gate

Wave 1 of the practice build (five parallel orders, merged 2026-10-06), the
fixes from two end-to-end trials in a separate test repo, and the defects an
independent reader found in those fixes. Every fix began with a test that
failed on the old code. Suite 1972 (1970 pass, 0 fail, 2 skipped).

Nothing that was valid becomes invalid: plan 1.7, brief 2.0–2.2 and review 1.0
files still validate. The new fields are optional, and the new rules apply only
from plan 1.8 and review 1.1.

### Added

- **Intent (`/trekbrief`).** A size class
  (`ceremony: small|bounded|architectural`; absent = `architectural`) sets the
  question budget, and the brief asks one round of questions with the
  recommendation first. "høres bra ut", "gjør som du vil" and an empty answer
  are not approval. `lib/util/approval-log.mjs` keeps an append-only,
  hash-chained approval log in the target repo, bound to the approved
  content's sha256. `lib/util/artifact-commit.mjs` commits it.
  `/trekplan` Phase 1 halts on a broken, missing or mismatched entry.
- **Plan 1.8 and the plan gate (`/trekplan`).**
  - Plan 1.8 requires `Test first:` on every step and one `End-to-end:` step.
    New optional fields: `Interface in:`, `Interface out:`, `Review focus:`.
  - An architectural plan gets a `## Design` part.
  - The critic loop has at most 3 rounds, and the plan records them.
    `lib/validators/plan-gate.mjs` decides: 0 go, 1 stop, 2 could not run.
    An open MAJOR stops the plan, and after the last round the operator
    decides.
  - `plan-critic` now checks 12 dimensions.
  - New `lib/verification/arch-rules.mjs` runs the target repo's own
    dependency-cruiser or import-linter.
  - New `lib/verification/plan-scope-sweep.mjs` lists changed files that no
    step names.
- **Step helpers and proof by command (`/trekexecute`).**
  - One fresh `step-implementer` helper per plan step (new agent: opus, effort
    high, no Agent tool).
  - One controller reads the diff and gives two verdicts: does the step meet
    the plan, and does it hold the quality.
  - Fix rounds go up, at most 5: helper, then plan, then operator.
  - New `lib/verification/red-proof.mjs`: the step's test must fail at the
    start point and pass at the result.
  - New `lib/verification/test-integrity.mjs` (the floor guard) catches
    removed asserts, skipped tests, stubs and loosened thresholds.
  - New `lib/verification/done-line.mjs` writes the done line only when the
    test command exits 0.
  - A closed stop list and a decision log appear in the final report.
- **Guards** (command hooks only, none runs a model).
  - `pre-bash-executor` answers "ask" before a merge into main, a push, a
    tag or publish, and destructive git. `post-approval-log` records the
    answer.
  - `pre-plan-gate` runs the plan gate when a Voyage plan leaves plan mode.
  - The test lock (`lib/util/test-lock.mjs`, `pre-write-executor`,
    `stop-test-lock`) refuses edits to a locked test file, and refuses "done"
    until the step's own test command is seen green.
  - `post-edit-check` runs the target repo's own formatter or linter. It runs
    only during a Voyage plan run or after opt-in.
  - New `lib/verification/step-check.mjs` checks each step when it ends.
- **The review is a gate (`/trekreview`, review 1.1).**
  - `verdict: ALLOW | WARN | BLOCK` is required.
    `lib/review/verdict-gate.mjs` reads it: 0 ALLOW/WARN, 1 BLOCK, 2 could not
    decide (never green). A control that did not run gives exit 2.
  - Claude Code's `/code-review` and `/security-review` run as the engine.
    Their findings enter through `lib/review/engine-findings.mjs` under three
    rule keys. `CODE_REVIEW_IMPROVEMENT` (MINOR) covers simplification,
    efficiency, reuse, style and readability. The rule catalogue now has 15
    keys.
  - No finding is struck for length. Only MINOR and SUGGESTION text is
    trimmed, and the trims are counted.
  - The coordinator lists what it declined to judge.
  - Every BLOCKER becomes a numbered remediation step.
  - A finding class seen in two reviews is proposed as a project-memory line
    (`lib/review/recurrence.mjs`). The operator approves each line.
- **Checks when a brief or plan is written.** A success criterion or Verify
  line that the criteria runner could never run is caught when the brief or
  plan is written, not when the review runs. The brief validator warns
  (`BRIEF_SC_NOT_RUNNABLE`, `BRIEF_SC_SUBPOINTS`, `BRIEF_SC_BASH_NOT_PINNED`).
  For a 1.8 plan, the plan validator reports `PLAN_VERIFICATION_NOT_RUNNABLE`,
  `PLAN_STEP_VERIFY_NOT_RUNNABLE`, `PLAN_END_TO_END_NOT_RUNNABLE` and
  `PLAN_END_TO_END_NOT_VERIFIED`: as errors under `--strict`, otherwise as
  warnings.

### Fixed

- The write guard covers `Edit` and `NotebookEdit`, not only `Write`, and
  fails closed.
- The review keeps findings that are right:
  - an engine finding is never set aside for Actionability;
  - `recommended_action` is the engine's own fix, or otherwise a test-first
    step, never the failure scenario;
  - a cited line past the end of a file is caught;
  - finding ids are computed, not typed by a model.
- A MINOR `/code-review` finding outside the reviewed range no longer holds
  ALLOW back. A MAJOR one still does.
- The plan template's checkpoint stages the step's files
  (`git add … && git commit`). The pre-compact hook reads that form.
- The brief template's examples are commands the runner accepts.
  `/trekcontinue` and `/trekexecute` call `lib/` through the plugin root.
- Manifest `must_contain` uses `grep -E -e … --`, so a pattern such as
  `--sep` is not read as an option.
- `/trekreview`, `/trekresearch` and `/trekcontinue` write stats through
  `stats-append` and report a failed write.
- `annotate` prints an absolute path.
- A test lock marked green may stop while it waits for its controller.
- `/trekplan` runs every exploration agent, and reviews the brief again only
  when it has changed since `/trekbrief` reviewed it.

## v6.1.1 — 2026-10-05 — /trekexecute writes what it promises

A patch release. `/trekexecute` no longer loses its telemetry when the harness
does not export `CLAUDE_PLUGIN_DATA`, its progress-file prose now matches its
own validator, and no agent is pinned below reasoning effort `high`.

### Fixed

- `lib/stats/event-emit.mjs` falls back to the same data directory as
  `stats-append` and the yardstick when `CLAUDE_PLUGIN_DATA` is unset, instead
  of skipping silently. Every `written:false` (failed write, usage error,
  `payload-not-json`) exits 1 with a reason. The CLI also runs when it is
  invoked through a symlink or a path with a space.
- `main-merge-approved`, `main-merge-declined` and `gates_mode_flag_override`
  are known events.
- `/trekexecute` Phase 8, Phase 9 and the `gates_mode_flag_override` record all
  write through a writer that resolves the directory. A failed write is printed
  in one line and the run continues.
- Phase 8 passes each event payload on stdin through a quoted heredoc
  (`event-emit.mjs --payload -`), so the shell expands nothing in it. Before,
  the plan path went into a single-quoted argument: a path with a quote
  character broke the shell parse, and a quoted pair could run a command
  substitution.
- The progress-file schema and status rules in `/trekexecute` use the
  validator's vocabulary (`in_progress`, `completed`, `plan_version`).
  `progress-validator` now accepts the run status `stopped` and the step
  status `blocked`, both of which the command writes. A legacy `passed` step
  is still treated as `completed` on resume.
- `architecture-mapper`, `dependency-tracer`, `git-historian` and `task-finder`
  pin `effort: high` (was `medium`). No agent is pinned below `high`; the rest
  follow the session.

## v6.1.0 — 2026-10-05 — The yardstick's use counter gets a source

The use row in `scripts/yardstick.mjs` now counts an order as used only when
a Voyage record names the order's id. Counting itself stays off
(`USE_COUNTING_SINCE = null`) until the operator declares the work done; the
tool ships first, the measurement comes after.

### Added

- `lib/stats/claimed-order.mjs` finds the one coord-queue order the session
  has claimed (repo-mailbox's claim contract, read-only). Exactly one claimed
  order is an attribution; zero or several is `null` plus a reason, never a
  guess.
- `/trekbrief` stats records carry `order_id`, `order_claimed_at` and
  `order_reason`, added by the writer (`stats-append`), never typed by the
  model. The fields are on all five stats surfaces and are not exported.
- `facts.ordersNamedByARecord` in the yardstick output: a known-positive
  diagnostic for the use row.

### Changed

- Yardstick use: the slug join is replaced by an order-id join. YES = a
  trekbrief record names the order's id; declared NO = the order's own
  `arbeidsform: ordre` line; no record = not measured, never a no.
- `/trekbrief --approve` now runs Phase 7 after a successful stamp, so the
  approval leaves a trekbrief record (`mode: "approve"`).

### Fixed

- The CLI main-guard in `stats-append` and `yardstick` compares real paths,
  so it no longer silently does nothing under a symlink or a space in the
  path.

## v6.0.0 — 2026-10-02 — Voyage never starts Claude Code

Operator decision 2026-09-27: nothing Voyage ships starts a Claude Code
session. Work that needs another session becomes an order plus a starter
line that the user runs in a session they open themselves; parallel work
inside one session uses subagents. This is a breaking change for anyone who
relied on Voyage launching sessions.

### Changed (breaking)

- `/trekexecute` multi-session path (Phase 2.6) no longer launches child
  sessions and no longer finishes in one call. It prepares one wave at a
  time: a worktree per session, one session order per session
  (`.claude/trekplan-sessions/{slug}/orders/`, written by the new
  `lib/util/session-orders.mjs`) with a `/trekexecute --session N <plan>`
  starter, and stops. Running the same command again reads each session's
  progress file, merges the wave sequentially and prepares the next one. A
  plan with W waves takes W + 1 parent runs plus one session per order.
  New Hard rule 21: never start Claude Code.
- Sessions now run under the user's own permission mode and tool set: the
  per-session tool allowlist and the permission-bypass mode are gone, and
  `brief.md` / `architecture/overview.md` are no longer injected as an
  appended system prompt.
- Phase 7.6 recovery writes a bounded recovery order for a session you open,
  and the run stops as `partial`; nothing dispatches it automatically.
- `/trekplan --decompose` (and its alias `--export headless`): the
  session-decomposer writes `orders.md` instead of a `launch.sh`, and the
  "launch" reply is gone.
- `/trekresearch --engine deep-research`: the pre-gate no longer runs the
  Claude Code binary to read its version; the post-hoc check decides. The
  `version-below-floor` reason token is gone (that case now reports
  `no-cited-report`).
- No `{session-dir}/logs/session-N.log` is written any more; progress files
  are the source of truth, and each wave's progress files are archived to
  `orders/wave-W-session-N.progress.json` before its worktrees are removed.
- `--dry-run` no longer prints a billing line.

### Removed

- The `ANTHROPIC_API_KEY` billing check, the hooks-fire version precheck, the
  headless safety preamble and the per-child tool, turn and budget flags —
  they existed only for launched children. The `TREKEXECUTE_MAX_TURNS` and
  `TREKEXECUTE_MAX_BUDGET_USD` environment variables are ignored.
- `templates/headless-launch-template.md` and
  `scripts/q3-cache-prefix-experiment.mjs` (a finished experiment that
  started the binary; its results stay in `docs/`).
- README: the billing-safety and headless MCP-tuning sections, and the
  fourth security layer (scoped per-child tool access), which went with the
  launched children.

### Fixed

- Every `VOYAGE_ROOT` resolution in `/trekexecute` (multi-session Step 0 and
  plan verification), `/trekreview` and `/trekresearch` now finds the
  installed plugin: the literal `${CLAUDE_PLUGIN_ROOT}` that Claude Code
  substitutes, else the highest installed version in the plugin cache. Before,
  these blocks always exited 2.
- The multi-session path never force-deletes. Worktrees are removed only
  when git agrees they are clean and session branches are deleted only once
  merged; anything git refuses is kept and listed in the report with what to
  do. Before, a failed session, a merge conflict or a refused merge deleted
  every `trek/{slug}/*` branch of the wave, finished work included.
- Collecting a wave never tears down a session that is still running (an
  unknown status counts as running); it stops when the main checkout has
  uncommitted changes or has switched branch, and tells a refused merge from
  a real conflict. The parent run must start in the main checkout, never in a
  session's worktree or a subdirectory's view of it.
- A merged-waves record, bound to the plan's path and content hash, keeps a
  re-run from preparing an already merged wave again; a different plan or an
  edited plan is refused with the way out named. The record is cleared only
  when the final merge is confirmed.

### Added

- `tests/lib/no-claude-code-launch.test.mjs`: fails when any tracked file
  outside a reasoned, exact-count exemption list carries a way to start
  Claude Code; proven on a known-positive fixture for every pattern. The one
  operator-run exception is the fixed test set (`docs/proevesett.md`).
- `tests/lib/session-orders.test.mjs`: runs the order writer on a fixture
  plan and proves the orders land, statuses classify, progress is archived,
  merged waves are remembered, and nothing is started.
- `tests/lib/plugin-root-resolution.test.mjs`: runs every `VOYAGE_ROOT`
  block, substituted and unsubstituted.

## v5.11.1 — 2026-09-23 — dead references to a retired repository removed

### Changed

- The annotation surface's provenance is described as the pattern it follows
  (pencil toggle, intent buttons, popover form, structured export) instead of
  by naming a repository that no longer exists: `.claude-plugin/plugin.json`
  and `package.json` descriptions, `README.md`, `docs/architecture.md`, the
  v5.0.3 entry below, and two comments in `scripts/annotate.mjs` and
  `tests/scripts/annotate.test.mjs`. No behavior change.

### Added

- `tests/lib/retired-references.test.mjs` fails when any tracked text file or
  path contains a term from the gitignored local list
  `tests/.excluded-terms.local.txt`. The scanner is validated against a planted
  known-positive, an empty scan fails closed, and the named exemption list is
  empty and rot-checked. Without the local list the scan is skipped with an
  explicit message.

## v5.11.0 — 2026-09-23 — /trekplan plans only against an approved intent

### Added

- **Intent approval gate.** `/trekplan` (both `--brief` and `--project`, also
  `--quick`, no override flag) runs `lib/validators/intent-approval.mjs --check`
  before it reads the brief. It **halts** on `BRIEF_INTENT_NOT_APPROVED`,
  `BRIEF_INTENT_APPROVAL_STALE` or `BRIEF_INTENT_APPROVAL_INVALID`, and an
  approval check that cannot run halts too. The marker is `intent_approved_hash`
  (sha256 over the normalized `## Intent` + `## Goal`) plus `intent_approved_at`.
  Editing either section after approval makes it stale. `/trekbrief` Phase 4h
  shows Intent and Goal verbatim and stamps only on "Approve".
  `/trekbrief --approve <project-dir | brief-file>` does that step alone for a brief
  from any producer. A `## ` line inside a code block or HTML comment is not a
  heading, and each section must appear exactly once. The marker is a trace that the
  step ran against this text, not a signature: any session on the same machine can
  stamp.
- **`scripts/yardstick.mjs`** prints Voyage's three numbers (use, trust,
  interrupts) with the denominator and the source each one was read from. It
  exits non-zero while any number cannot be counted, and today it is RED.
- **`scripts/end-state-gate.mjs`** counts the distance to "Voyage is finished"
  (defects, experiments, dormant agents, open decisions). It is fail-closed: an
  entry whose check cannot run counts as open.
- **Plugin eval suite (`evals/`, `docs/proevesett.md`)**: eight cases run as
  real `claude -p` children with only Voyage loaded, deterministic graders,
  and each expectation committed before its first run. Measured stability: every
  case 5 of 5 over three full runs, and the sequencing-gate case 15 of 15.
- `lib/stats/stats-append.mjs`: `/trekbrief` and `/trekplan` stats records
  land in the data dir the yardstick reads when `CLAUDE_PLUGIN_DATA` is empty,
  and a failed write is reported, not skipped silently. `intent_approved`
  reaches the OTel field allowlist.

### Changed

- **Handover 1 (PUBLIC CONTRACT): a brief from any producer now stops at
  `/trekplan` until its intent is approved.** The schema change is additive (two
  optional fields, no `brief_version` bump). The requirement sits in the
  consumer. See `docs/HANDOVER-CONTRACTS.md` §Handover 1.
- The arg parser has a CLI. `/trekreview` runs it with `$ARGUMENTS` and relays
  `Error: --project <dir> is required.` from code (it passed `"$@"`, which the
  Bash tool never has, so the parser never ran).

### Fixed

- `/trekexecute` runs the plan's `## Verification` on the single-session path
  too (D-03), and `/trekreview` runs the brief's success-criteria commands and
  gives the reviewer the result (D-04), through `lib/verification/criteria-runner.mjs`.
- The criteria runner screens with an **allowlist** of test runners, not a
  denylist, and refuses writes a brief may not perform. A backticked span runs only
  when it is a command, and the runner reads the repo's own plan format.
- The end-state gate can no longer be turned green by editing its own ledger,
  and a behaviour probe must fell a stub, not just name a test.
- The review gold-scorer key separator is written as an escape, not a raw
  NUL byte. The `/trekresearch` swarm engine points only at the External agents block.
- Docs no longer claim an opus orchestrator: the commands follow the session model.

### Removed

- `/trekplan`'s "execute with team" path: Claude Code 2.1.178 removed
  TeamCreate/TeamDelete, so it always fell back to sequential execution.
- `TaskCreate`/`TaskUpdate` from `/trekplan`'s tool lists. Claude Code 2.1.233
  stopped offering them on current models, and no prose called them.

## v5.10.1 — 2026-09-03 — gemini-bridge dropped; fail-closed review verdicts

### Removed

- **`gemini-bridge` is dropped from the pipeline (operator directive).** The
  agent file is deleted and every live surface that could still steer a run
  toward it is cleared: `commands/trekresearch.md` (the Bridge-agent launch
  block, the `--local` help text, the high-effort always-on pair, the stats
  record, the graceful-degradation list), `commands/trekplan.md`,
  `commands/trekbrief.md`, `agents/research-orchestrator.md` (mode table,
  agent table, prompting block, summary line), `README.md` (feature prose, mode
  table, agent prose, the mermaid EXTERNAL node, the `* = conditional` legend,
  the optional-MCP requirement, the `--local` section), `CLAUDE.md`,
  `settings.json` (the whole `trekresearch.geminiBridge` block),
  `templates/research-brief-template.md` (the *Gemini Second Opinion* section
  and the sources-table `gemini` type), `templates/trekbrief-template.md`,
  `docs/architecture.md`, `docs/command-modes.md`.
- **`/trekplan` high-effort Adversarial Pass 2 degrades explicitly.** It now
  emits a `## Adversarial Pass 2 (v5.1.1 high-effort)` section whose status
  reads **"unavailable, skipped"**, rather than failing or vanishing: a
  high-effort plan carrying no Pass 2 marker is indistinguishable from one whose
  Pass 2 crashed. `/trekresearch` high effort forces only `contrarian-researcher`
  always-on, which remains the complete adversarial coverage.
- **Not removed:** `gemini_used` survives as a vestigial `/trekresearch` stats
  field pinned to `false`. Dropping it would break the observability export
  schema for existing consumers, and no consumer asked for that.
- Agent inventory: **24 → 23 files** (20 spawnable + 3 orchestrator reference
  docs; `synthesis-agent` still dormant). Counts reconciled in `README.md` and
  `CLAUDE.md`; the `<example>`-block floor in
  `tests/lib/agent-frontmatter.test.mjs` moves 34 → 32 because an agent
  legitimately left the inventory — not because examples went missing from a
  surviving one.
- Pinned by 5 new tests in `tests/lib/doc-consistency.test.mjs`, including a
  **known-positive control** asserting the historical records *still do* carry
  gemini references — so the empty result on live surfaces is a measurement and
  not a broken query. CHANGELOG entries and measurement/decision docs keep their
  references deliberately: they record what a past version did.

### Fixed

- **`/trekreview` verdicts are fail-closed.** A finding removed by Pass 2 or
  Pass 3, and a reviewer whose payload was thrown away or never arrived, were
  arithmetically identical to a finding that never existed — all three pushed
  the verdict toward `ALLOW`. Measured before the fix: a BLOCKER with a
  101-character title → `ALLOW`; a payload carrying one ad-hoc `rule_key` was
  skipped whole at ingest, taking a valid BLOCKER sibling with it → `ALLOW`.
  `lib/review/coordinator-contract.mjs` now splits every removal two ways —
  **dropped** when the test refuted the finding as a claim about this codebase,
  **unverified** otherwise — and a non-empty `unverified` bucket, or a reviewer
  in `expectedReviewers` that did not report, forbids `ALLOW` (verdict `WARN`,
  with `allow_blocked_by` naming why). The rule never *raises* a verdict: the
  severity catalogue and the BLOCKER/MAJOR thresholds are untouched. New
  exports: `classifySuppression`, `REFUTING_REASONS`, `UNVERIFIED_REASONS`;
  `runContract` gains `unverified`, `missing_reviewers`,
  `unattributable_payloads` and `allow_blocked_by` (`suppressed` stays the
  union, so existing consumers keep their meaning). A payload that fails schema
  without carrying a `reviewer` name is counted as unattributable rather than
  reported as a reviewer called "unnamed reviewer" — naming one would invent an
  agent nobody launched and double-count with `expectedReviewers`.
  Mirrored in `agents/review-coordinator.md` (Pass 2/3 fate columns, the new
  §*Suppression is two-valued*, Pass 4 threshold table) and
  `commands/trekreview.md` (Phase 5 reviewer accounting → STOP; Phase 6).
  Driven test-first: 11 new tests in `tests/lib/coordinator-contract.test.mjs`,
  incl. a known-positive control proving `ALLOW` is still reachable.

### Docs

- **T1 §6 PoC status corrected — it was already run and declined.**
  `docs/T1-cc26-delegated-orchestration.md` §8 item 3 still claimed both the §6
  synthesis-agent PoC and the §5 full bake-off were "designed but unbuilt". That
  was written in S7 and falsified the same afternoon by S12, which ran the §6
  PoC and recorded **Δ main-context (faithful flow) = 0.0%, NEGATIVE**
  (`docs/T1-synthesis-poc-results.md`; reproduce with
  `node scripts/synthesis-measure.mjs`). The stale wording caused the settled
  PoC to be re-ordered as new work on 2026-09-02, so it is struck rather than
  deleted and §6 gained an explicit **RUN AND DECLINED** status block. The
  finding is structural, not stochastic: `/trekplan` Phase 5 spawns the
  exploration swarm **foreground** (`commands/trekplan.md:158,338-341`), so the
  6–10 outputs are already resident in main before Phase 7 begins — delegating
  only the Phase-7 digest returns on top of them and evicts nothing. A saving
  needs the Phase-5 delivery moved off-main, which is §5.
- **§5's environment premise updated (measured 2026-09-03, CC 2.1.259).** S12
  recorded the live bake-off as blocked for want of an `ANTHROPIC_API_KEY`;
  `claude -p --output-format stream-json` in fact runs on subscription auth with
  no API key and now emits a `subagent_stats` block (spawned / max_depth /
  refused) that did not exist in June — a ready-made classifier-interference
  counter for §5's feasibility guard. S12's other blocker (the installed plugin
  is the cache copy, so a repo-local agent is invisible to `claude -p`) stands
  unmeasured. This changes nothing about the §6 verdict; it lowers the cost of §5.

- **`/trekresearch --engine deep-research`: document the real version window.**
  Claude Code **2.1.218** changed `/deep-research` to start only when the operator
  invokes it; from there the Skill tool refuses a model invocation outright with
  `disable-model-invocation` (measured in a real `--engine deep-research` run on
  2026-09-01 — the SC3 fallback to `swarm` held). The engine was built against
  2.1.196 and the prose still promised a path Claude Code has removed
  ("requires Claude Code 2.1.154+"). `commands/trekresearch.md` (flag bullet +
  pre-gate + fallback reason tokens), `docs/command-modes.md` and `README.md` now
  state the closed window `2.1.154 <= CC < 2.1.218` and name
  `disable-model-invocation` as the expected fallback reason on any current CC.
  The pre-gate gained an upper ceiling (still a numeric comparison, not a string
  one). **The flag is kept** as an additive opt-in that never hard-fails; no
  `lib/` change, no adapter-contract change, no default change, no version bump.
  Pinned by `tests/lib/doc-consistency.test.mjs`.

## v5.10.0 — 2026-08-18 — STORM bounded research loop (default-off) + the Agent-tool `name` spawn defect

Additive. Every new research mechanism ships **inert**: `VOYAGE_STORM_ENABLED` is
unset by default, and with it unset both new `/trekresearch` phases are no-ops.
The one change that affects consumers regardless of flags is the spawn rule under
*Fixed* — it changes how any repo should call the Agent tool.

### STORM bounded loop — shipped, default-off, behind a pre-registered adoption gate

- `/trekresearch` Phase 4.5 (dimension discovery, under the existing
  `maxDimensions: 8` ceiling) and Phase 5 (bounded multi-turn follow-up,
  replacing the single follow-up pass) run only at `effort: high` **and** only
  when `VOYAGE_STORM_ENABLED=1`. Unset, Phase 5 is inert because
  `lib/util/research-loop-cap.mjs` grants a budget of 0, and Phase 4.5 is inert
  because its skip-guard reads the flag directly (it never calls the cap) — two
  independent off-switches, so a bug in one does not silently activate the other.
- `TREKRESEARCH_MAX_CONV_TURNS` (default `3`; invalid values fall back to `3`)
  sets turns per dimension. The total budget is that value × `maxDimensions`.
- New `lib/util/research-loop-cap.mjs`: an append-only ledger the cap counts its
  own turns from. Each turn slot is claimed with `O_EXCL`, so the bound survives
  concurrent turns; an unreadable ledger **fails closed** in both modules; and
  the enforcement boundary is a denial tombstone rather than the turn count, so
  a crash mid-turn cannot hand back a free turn.
- New `hooks/scripts/pre-agent-cap.mjs`, registered as a `PreToolUse` hook on
  `WebSearch|WebFetch|Task`: the budget is enforced by the harness, not by prose
  in a command file. `VOYAGE_DISABLE_CAP_HOOK=1` switches it off.
  `docs/spike-pretooluse-subagent-reach.md` records the measured reach of
  `PreToolUse` into sub-agent tool calls — including where the gap is.
- Five measurement fields (`unique_sources`, `dimensions_baseline`, `conv_turns`,
  `empty_turns`, `dimensions_baseline_preserved`) are emitted to
  `trekresearch-stats.jsonl` and allowlisted in `lib/exporters/field-allowlist.mjs`.
  All five are counters or booleans — none carry prose or paths.
- `scripts/storm-measure.mjs` + `docs/storm-measurement.md`: the adoption gate,
  with thresholds registered **before** the first measurement by design.
  ≥ 30 % improvement on either metric → adopt; < 15 % → decline; an empty arm is
  `insufficient-data`, not a decline. Decline is a no-op — the mechanism simply
  stays default-off; adopt is one constant. No measurement has been run yet.

### Added — outbound query privacy gate

- `lib/validators/query-privacy-gate.mjs` inspects a research query before it
  leaves the machine, in the same two-tier shape as the existing SSRF gate: a
  WARN tier (absolute filesystem paths, repo-internal identifiers) that
  `--soft` / `VOYAGE_QUERY_PRIVACY_ALLOW=1` can override, and a HARD-BLOCK tier
  (secret-shaped tokens) that **nothing** overrides. Called only from the two new
  high-effort steps; the existing single-pass path is unchanged.

### Fixed — the Agent tool's `name` parameter silently breaks a subagent's return channel

- **Consumers of this pipeline should read `docs/agent-return-channel-defect.md`.**
  Passing `name` to the Agent tool does not label a subagent — it changes what is
  spawned: `taskKind: "in_process_teammate"` / `spawnDepth: 0` instead of a real
  subagent (`spawnDepth: 1`). A teammate's final text is not a return value; it
  reaches the parent only if the teammate itself calls `SendMessage(to: "main")`.
  Voyage's reviewer agents carry `tools: [Read, Glob, Grep]` — no `SendMessage` —
  so when named they are *structurally* unable to answer. No error, no warning.
  Measured numerators (66-line target): named without explicit `SendMessage`
  **0/5** returned · named + explicit `SendMessage` **1/1** · unnamed **3/3** ·
  work actually performed while named **5/5** — only delivery fails, and the
  output is recoverable from
  `~/.claude/projects/<project>/<session>/subagents/agent-*.jsonl`.
  Independently confirmed at 3730 lines / 277 KB by `akashic-intelligence`
  (4/4 correct final text on disk); the *returning* arm above 66 lines remains
  inferred rather than observed, and the doc says so.
- The four spawning commands (`trekbrief`, `trekplan`, `trekresearch`,
  `trekreview`) now state the rule at their spawn sites and name the mechanism.
  `trekexecute` spawns nothing and is excluded. The `doc-consistency` test
  **derives** the spawning set from the command files, so the pin cannot go
  vacuous when a command starts or stops spawning.

### Fixed — hook and validator hardening

- The destructive-command rule anchored on command position rather than any
  substring (a path containing a blocked word no longer trips it), and the
  bypasses that anchoring itself opened are closed.
- The secret-detection validator hard-blocks token formats the run-length
  patterns missed.
- The exporter allowlist covers `/trekresearch`'s `engine` field, with the JSONL
  schema fixture pinned to agree — a new stats field is otherwise dropped
  silently at export.

### Docs

- README: first screen aligned with the org repo standard, complete AI
  disclosure, and the Gemini MCP tool contract described inline instead of via a
  dead cookbook link. Governance keeps one canonical file, not a local copy.
- `/trekresearch`: STORM mechanisms documented across four surfaces; the
  Independence crossing's two risks split, each naming its own control.
- `docs/*.pdf` is gitignored — `origin` is a public mirror and must never carry
  operator PDFs.

### Tests

- Suite baseline 832 (830 pass / 0 fail / 2 skip) → **1013 (1011 / 0 / 2)**.
  New coverage: research-loop-cap (including the concurrency and fail-closed
  paths), the cap hook's crash-time marker branches, the query privacy gate, the
  measurement harness's decision rule, and the spawn-rule doc pin.

## v5.9.1 — 2026-07-03 — Fix /trekendsession load-time crash (eager-exec placeholders)

Patch, no functional additions.

### Fixed

- `/trekendsession` was unusable in every invocation: two of its three `` !`...` `` eager-exec blocks (Phase 3 atomic-write, Phase 4 validator call) contained unresolved runtime placeholders (`<project-dir>` etc.). The harness executes eager-exec blocks at command LOAD time, so zsh parsed `<project-dir>` as input redirection and the command aborted before the model saw a single instruction. Both blocks are now plain runtime Bash fences with the `{curly}` placeholder convention (shell-inert), matching `trekplan.md`/`trekresearch.md`. The Phase 1 discovery block (self-contained) keeps its legitimate eager-exec prefix; `trekcontinue.md`'s discovery block was runtime-verified unaffected.
- Latent secondary bug in the same blocks: cwd-relative plugin paths (`lib/validators/...`, `./lib/util/atomic-write.mjs`) would have failed with `ERR_MODULE_NOT_FOUND` even after substitution, since the Bash cwd is the user's repo. Both now use absolute `${CLAUDE_PLUGIN_ROOT}` paths per the existing command convention (Node ESM accepts absolute-path import specifiers — verified on Node 18+).

### Added

- Regression guard `tests/commands/trekendsession.test.mjs`: scans every `` !` ``-block in `commands/*.md` for unresolved `<angle>`/`{curly}` placeholders (this bug class is silent until first invocation), plus structure tests pinning Phase 3/4 as runtime Bash with `${CLAUDE_PLUGIN_ROOT}` paths and exactly one surviving eager block. Suite baseline 828 → 832 (830 pass / 0 fail / 2 skip).

## v5.9.0 — 2026-07-02 — Fable model tier + deep-research engine

Additive, plus one behavior alignment: profile `phase_models` now reach sub-agent spawn sites (previously documented but never wired), and the seven command orchestrators no longer pin `model: opus` — frontmatter omits `model:`, so the orchestrator follows the session model.

### Fable model tier

- `fable` (→ Claude Fable 5, Mythos-class, positioned above Opus) is an accepted model value throughout the validation chain: `BASE_ALLOWED_MODELS` widened to `['sonnet', 'opus', 'fable']` in `lib/validators/profile-validator.mjs` — the single source imported by brief-validator and phase-signal-resolver (two-layer gate preserved; accept-fable AND reject-unknown-model covered at both layers). No env gate — haiku's `VOYAGE_ALLOW_HAIKU` opt-in stays as-is.
- `/trekbrief` Phase 3.5 tier loop offers a 4th option: `fable → {effort: high, model: fable}`. AskUserQuestion's 4-option maximum is now fully used — a 5th tier requires a loop redesign. The fable tier reuses `effort: high` orchestration semantics; `EFFORT_LEVELS` is unchanged.
- New built-in profile `lib/profiles/fable.yaml` (all six phases on `fable`, modeled on premium; registered in `BUILTIN_NAMES` with a `loadProfile('fable')` canary test so a registry regression fails loudly instead of silently resolving premium). Premium stays the default.
- Reasoning effort is inherited from the session: Fable 5's default effort is `high`, NOT xhigh, and switching model resets effort — set xhigh at session level (`/effort xhigh`, the `effortLevel` setting, or `CLAUDE_CODE_EFFORT_LEVEL`). Documented canonically in `docs/profiles.md` §Model & effort axes.
- `claude-fable-5` added to the cost `PRICE_TABLE` ($10/MTok input, $50/MTok output; cache write 5m $12.50 / 1h $20; cache read $1 — verified 2026-07-02 against the official platform pricing docs). `PRICE_TABLE_VERSION` bumped to `2026-07-02`. Without the entry, every fable run would report `cost_usd: null` in the observability export.
- Profile tables + allowlist prose updated across README, `docs/profiles.md`, `docs/operations.md`, `docs/HANDOVER-CONTRACTS.md`, `docs/architecture.md`, `docs/command-modes.md`, templates, and CLAUDE.md; the S15 doc pins now machine-check the fable row cell-for-cell against `fable.yaml`. The `^(opus|sonnet)…` regex claim in two docs was corrected — validation is an exact string match against `BASE_ALLOWED_MODELS`; the regex never existed in code.

### Behavior alignment: profile `phase_models` now reach sub-agent spawns

- Pre-existing wiring gap (found in exploration): all four pipeline commands invoked only the brief-only `phase-signal-resolver.mjs`, so the `?? profile.phase_models[<phase>]` half of the documented composition rule never executed — `--profile <x>` never reached sub-agent spawns.
- Fixed with a single composed resolver: `resolver.mjs --resolve-phase-model` now returns `{effort, model, source}` (brief > profile > default, with effort passed through atomically) and is the one CLI the four pipeline commands invoke. A doc-consistency pin requires the composed invocation and forbids the brief-only CLI in command Bash blocks.
- **Behavior change (contract alignment):** `--profile economy/balanced` now genuinely reaches sub-agent spawn sites for the first time — behavior aligns with what the docs have long claimed. The premium default is unaffected in practice (premium resolves `opus`, which equals the frontmatter fallback).
- Command frontmatter: the `model: opus` line is DELETED from all seven commands — omission (not the disputed `inherit` literal) is the spelling both official surfaces document as session-inheritance, guarded by a frontmatter-absence doc pin. Accepted tradeoff: in a sonnet session the orchestrator runs on sonnet; re-add a frontmatter pin for deterministic orchestrator choice. The 24 `agents/*.md` `model: opus` pins are untouched (spawn-time injection wins; frontmatter is the fallback). `/trekcontinue`/`/trekendsession` spawn no exploration swarm and get no spawn-site injection; the continue phase is covered at resolver level and follows the session model.

### Bundled unreleased work (since v5.8.0)

- `/trekresearch --engine {swarm|deep-research}` (`581489a..9374820`): opt-in delegation of the external research phase to Claude Code's built-in `/deep-research` workflow, with in-context adapter + self-check, availability fallback to swarm (never hard-fails), and doc-consistency pins across surfaces.
- brief-validator CLI no-flag invocation fix (`926b768`).
- Deep-research engine research notes + docs (`60e9e7a`, `9d8e043`).

### Operator + consume-side notes

- The operator-global CLAUDE.md policy "Opus 4.8 default for all subagents" predates the fable tier; updating it is an operator action outside this repo.
- `/plugin update` compares against a stale local marketplace clone and can report "already at the latest version" after this release (Claude Code issues #35752 / #38271, both closed-not-planned). Reliable refresh: remove + re-add the marketplace, or `git pull --ff-only` in the marketplace clone. Cross-version skew consequence: a stale cached v5.8 brief-validator REJECTS fable-bearing briefs with `BRIEF_INVALID_MODEL` — enum widening is safe for new readers of old data, not old readers of new data.
- Org `availableModels` with `enforceAvailableModels: true` can make an inheriting orchestrator silently fall back to the first allowed model.

### Release hygiene

- Suite (measured with bare `npm test` at release): **828 (826 pass / 0 fail / 2 skipped)** — +17 over the pre-release ground-truth baseline of 811 measured 2026-07-02 (allowlist/gate coverage, fable profile pins, composed-resolver + frontmatter-absence doc pins, PRICE_TABLE case).
- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.9.0`, guarded by `doc-consistency.test.mjs`.

## v5.8.0 — 2026-06-30 — offline gold-scored output eval (SKAL-1·4b)

Additive — no behavior change, no breaking change. Internal eval infrastructure only (`lib/` + `tests/` + docs); no command, agent, profile, or Handover contract touched.

### Gold-scored output eval (SKAL-1·4b)

- The review-coordinator self-eval gains its **scoring run**, building on the deterministic coordinator contract + golden corpus shipped as the 4a foundation in v5.7.0.
- `lib/review/gold-scorer.mjs`: `scoreFindings(runFindings, goldFindings)` matches at **`(file, rule_key)` granularity** (line + severity deliberately ignored) → `{ tp, fp, fn, precision, recall, f1, matched, missed, spurious }`; `scoreVerdict` checks exact verdict match. Pure — no I/O, no LLM, no network. Vacuous-set conventions (empty run → recall 0; empty gold → precision 0; f1 collapses to 0) are documented in the module header.
- `tests/fixtures/bakeoff-rich/runs/run-perfect.json`: the first **committed run** — reviewer payloads that, fed through `runContract`, reproduce all 5 seeded gold findings. The regression guard: any future contract change that silently suppresses or skips a seeded finding breaks the eval.
- `tests/lib/gold-eval.test.mjs`: the **scoring run**, wired into `node --test`. Asserts `run-perfect` scores precision/recall/f1 = 1.0 and `verdict == expected_verdict` (BLOCK). Offline: committed payloads, no live agent spawn (the LLM-in-the-loop grading is the separate 4c tier).
- **Third test-census category.** `lib/util/test-census.mjs` now reports a `goldEval` bucket (matched by `GOLD_EVAL_FILE_RE`) separately from `behavior` and `docPins` — a scoring run is neither behavior coverage nor a prose pin, so the honest-count invariant is a 3-way sum.
- `docs/eval-corpus/README.md`: SKAL-1·4b moved from "Future hardening" to an implemented section documenting the scorer, run format, and census category.
- Suite: **822 (820 pass / 0 fail / 2 skip)**, up from 809 (+10 scorer behavior tests, +3 eval scoring-run tests). The scorer test covers the discriminating paths (false negatives + false positives) and the degenerate empty-run / empty-gold cases, not merely the all-match case.
- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.8.0`, guarded by `doc-consistency.test.mjs`.

## v5.7.1 — 2026-06-29 — relocate agent `<example>` blocks to body (always-loaded token trim)

Performance/packaging change — no behavior change, no breaking change. (M4)

### Always-loaded token trim

- The 17 example-bearing agents each carried two `<example>` blocks (34 total) inside their `description:` frontmatter. voyage launches its agents **by name** from the orchestrator commands, so those auto-selection examples were paying a per-turn token tax for a path the pipeline never uses. They are now relocated **verbatim** into each agent's body under a `## When to use — examples` section — preserved, not deleted.
- Frontmatter `description` chars across all 24 agents: **17,672 → 4,945** — roughly **3,180 fewer always-loaded tokens per turn** for every session with voyage enabled. The 7 zero-example agents are untouched; no system prompt, tools, model, or `name` changed.
- New invariant test in `tests/lib/agent-frontmatter.test.mjs`: no `<example>` in any frontmatter `description`, and ≥ 34 `<example>` retained across agent bodies (relocation moves, never deletes). Suite: **807 pass / 0 fail / 2 skip**.
- **The saving only reaches a machine after `/plugin marketplace update` + reload** — the delta is not instant on the machine that ships the release.
- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.7.1`, guarded by `doc-consistency.test.mjs`.

## v5.7.0 — 2026-06-26 — opt-in token/cost metering (SKAL-2) + eval foundation (SKAL-1·4a)

Additive — no breaking change. Two unreleased work-streams land together.

### Opt-in token/cost metering (SKAL-2) — the headline

- Pure token-usage parser + cache-aware USD cost (`lib/stats/token-usage.mjs`): parses MAIN-CONTEXT usage from the transcript, dedups by requestId (last-wins, streaming-placeholder mitigation), excludes sidechain records, and REFUSES to estimate (`cost_usd:null, is_estimate:true`) for models absent from the frozen PRICE_TABLE.
- CWE-212 export boundary: token-usage schema allowlist in the OTLP exporter; `session_id`/`transcript_path`/`cwd` stripped at export, asserted both ways.
- Cross-session aggregation in `cache-analyzer` (total tokens + cost).
- Capture folded into the EXISTING `otel-export.mjs` Stop hook, gated behind the `VOYAGE_TOKEN_METER` env var (default off), fail-open. v1 scope = main-context only; sub-agent turns are a documented v2 follow-on.

### Eval foundation (SKAL-1·4a)

- `gold.json` golden corpus + loader/validator; review-coordinator contract reference impl + deterministic test; two-sided gate coverage for the `BRIEF_*` BLOCKERs; eval-corpus frozen-failure home.

### Release hygiene

- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.7.0`, guarded by `doc-consistency.test.mjs`.
- Canonical `node --test`: **807** (805 pass / 0 fail / 2 skipped).

## v5.6.1 — 2026-06-24 — leaner always-loaded agent listing (reference/dormant agent descriptions trimmed)

Additive — no breaking change, **no runtime behavior change**. Trims the always-loaded token cost of the agent listing that Claude Code injects into every session.

### Reference/dormant agents now carry one-line descriptions

- **The 3 `*-orchestrator` reference docs** (`planning-/research-/review-orchestrator`) and the **dormant `synthesis-agent`** carried multi-paragraph `description:` frontmatter (full rationale + CC-2.1.172 history + a usage example) that Claude Code injects into every session — despite none of them being spawnable from the live `/trek*` pipeline. Their `description:` is now a single line; the full rationale already lives, and remains, in each file's body. **~700 tokens trimmed** from the always-loaded agent listing, no capability change.
- The three orchestrators retain the self-declaration **"reference document, not a spawnable capability"** (pinned by `doc-consistency.test.mjs`); `synthesis-agent` retains its **DORMANT / not-wired** flag and the `docs/T1-synthesis-poc-results.md` pointer.
- Surfaced via dogfooding with `config-audit`'s always-loaded token audit. Canonical `node --test`: **754 pass, 0 fail** (756 total, 2 skipped); the agent-inventory + frontmatter pins stay green.

### Version sync

- `plugin.json`, `package.json`, `package-lock.json`, the README badge, and the CHANGELOG top entry all at `5.6.1`, guarded by the version-consistency test in `tests/lib/doc-consistency.test.mjs`.

## v5.6.0 — 2026-06-20 — `/trekexecute` loop hardening: machine-verifiable completion + bounded recovery

Additive — no breaking change. Hardens the `/trekexecute` execution loop so termination is *machine-verifiable* and recovery is *bounded by an explicit budget*, closing the "runs forever" and "declares done without proof" failure modes. Five focused changes; canonical `node --test` 744 → **756** (0 fail).

### Machine-verifiable completion gate (the headline)

- **Stop-signal contract** — `/trekexecute` reports `completed` only when a machine-checkable contract holds: the Phase 7.5 manifest audit PASSes, the stop signal exits 0, and the success criteria are green. **Hard Rule 18** is promoted from prose guidance to an enforced gate, anchored in the Phase 7.5 audit rather than the model's self-assessment.

### Bounded recovery — cap hierarchy + global budget

- **`TREKEXECUTE_MAX_RECOVERY_ITERATIONS`** — a global recovery-iteration budget (default **25**, env-overridable) sits above the per-step caps as a three-axis cap hierarchy (recovery depth · per-step retry · global budget), codified as **Hard Rule 20**. Stops an unbounded recover→retry→recover spiral that the per-step caps alone could not bound.
- **`iterations_remaining` signal** — surfaced in the progress schema and the summary JSON, with a deterministic gate cross-check (`iterations_remaining == cap − (recovery_depth + Σ attempts-beyond-first)`) that catches a never-decremented counter. Shape-validated in `lib/.../progress-validator.mjs` (`PROGRESS_ITERATIONS_REMAINING_INVALID`: non-negative integer, additive-optional — never required at top level).

### Doc consistency

- **Fan-out hedge harmonized** — the `CLAUDE.md` design-principle line is aligned to the measured claim (parallel wall-clock + structured artifact handoffs as the load-bearing benefit; main-context relief stays explicitly *not demonstrated*), with a banned-phrase **forward-guard** in `tests/lib/doc-consistency.test.mjs` so the over-claim cannot reappear.

### Release hygiene

- **Version sync** — `plugin.json`, `package.json`, `package-lock.json`, the README badge, and the CHANGELOG top entry all at `5.6.0`, guarded by the version-consistency test in `tests/lib/doc-consistency.test.mjs`.

## 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`). Emits a `status` field (`verified | n_a | contradictions`) so a score-5 N/A (no memory available) is distinguishable from a score-5 verified-aligned brief — the gate passes in both cases, and `status` is what tells the operator whether the wrong-premise defense actually ran.
- **Obligatory `## TL;DR`** — ≤ 5 content lines at the top of every 2.2 brief (soft cap → `BRIEF_TLDR_TOO_LONG`).
- **Opt-in version floor** — `--min-brief-version <ver>` on `/trekplan` + `/trekresearch` (forwarded to the validator as `--min-version`) raises a `BRIEF_VERSION_BELOW_MINIMUM` *warning* — never a block — when a brief declares a version below the floor. Closes the producer-elective hole where a `2.0`/`2.1` brief silently sidesteps framing enforcement; `docs/HANDOVER-CONTRACTS.md` §Handover 1 now documents pre-2.2 = zero framing enforcement and the two remedies (require `2.2` upstream, or pass the floor flag).

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 **opt-in-defensible** (POSITIVE on the measured axes — fidelity-equivalent `review.md`, zero classifier interference at 9-agent concurrency, ≈ +4.4% tokens — but on a single un-archived run: the raw per-run data was never committed, so the numbers cannot be re-derived; see `docs/T2-bakeoff-results.md` §Reproducibility caveat).
- **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`.
- **Honest test count (S19)** — `lib/util/test-census.mjs` + `tests/lib/test-census.test.mjs` report the behavior-test count separately from the doc-consistency prose-pin count, so the cited total no longer oversells behavior coverage. Pruned 3 redundant/tautological prose-pins from `doc-consistency.test.mjs` (each provably subsumed by a structural invariant or behavior test). Devil's-advocate audit §Top changes #8.
- **`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.

### Bug fixes (load-bearing)

- **#8 YAML-number bypass closed.** `lib/validators/brief-validator.mjs` now coerces `brief_version` to string before comparison; both `brief_version: 2.1` (parsed as Number) and `brief_version: "2.1"` (parsed as String) trigger the v5.1+ sequencing gate. Previously the unquoted form silently bypassed the gate. Three regression tests added in `tests/validators/brief-validator.test.mjs`.
- **#11 Doc-consistency pin lock-in.** `tests/lib/doc-consistency.test.mjs` pins `templates/trekbrief-template.md` to emit `brief_version: "2.1"` (quoted) so future template edits can't reintroduce the bypass.

### Wiring (closes #9 + #12)

- **`lib/profiles/phase-signal-resolver.mjs` helper** (new). Reads `brief.phase_signals` (or `phase_signals_partial`) and the active profile's `phase_models`, returns the resolved `{effort, model, source}` per phase. Composition rule: brief signal wins per-phase, profile fills gaps. The resolver controls only the orchestrator and the model parameter at `Agent`-spawn sites — sub-agents otherwise read `model:` from their own `agents/*.md` frontmatter (still pinned to `opus`).
- **4 downstream commands wired.** `/trekplan`, `/trekresearch`, `/trekreview`, `/trekexecute` each invoke the resolver in their Phase 1 (or equivalent first-phase block), capture the result as `phase_signal_result`, and pass it to `Agent` tool calls explicitly. Per-command low-effort code-paths reuse existing `--quick`-equivalent logic.
- **`resolvePhaseModel` orchestrator-override added** (#9 part A). Profile-tier model picks are overridden when `brief.phase_signals[<phase>].model` is set. Non-interference verified by new test `tests/lib/profile-resolver.test.mjs` (Step 7 TDD pair, Red→Green).
- **`brief-validator --soft` gate required uniformly** in `/trekresearch` + `/trekexecute` (previously only `/trekplan` + `/trekreview`). `BRIEF_V51_MISSING_SIGNALS` halts all 4 commands with a clear hint pointing back to `/trekbrief`.

### Test refactor (closes #1 #2 #3 #4 #6 #7 #10)

- **Runtime SC1 walk for `tests/commands/trekbrief.test.mjs`** (#1). Replaces prose-grep with `resolvePhaseSignal` invariant: returns non-null for all 4 entries in `PHASE_SIGNAL_PHASES` when applied to a fixture brief with a committed `phase_signals` block; returns gate-fire when applied to a v2.1 brief missing the block.
- **Per-tier resolver-output + missing-signals falsification** (#2 #3 #6 #10). `tests/commands/trekplan.test.mjs`, `trekresearch.test.mjs`, `trekreview.test.mjs`, `trekexecute.test.mjs` each refactored from doc-pin pattern to runtime assertion against 4 new fixture briefs (`tests/fixtures/briefs/{low,standard,high,partial}.md`).
- **Dedicated SC5 profile-resolver non-interference test** (#7). `tests/lib/profile-resolver.test.mjs` asserts that brief-emitted signals are not overridden by `VOYAGE_PROFILE`, and that `--profile` does not silently override brief-emitted answers.
- **#4 SC5 invariant** locked at resolver level rather than test-strategy level (no scope expansion — see `source_findings` audit trail in plan.md frontmatter).
- **Total test delta:** +12 tests (539 baseline + 12 + 4 doc-pins from Step 10 = 555 expected; actual 578 because the existing tests grew underneath us during the v5.1.0→v5.1.1 cycle). 0 fail, 2 skipped.

### Documentation (closes #5 scheduling + Decision B high-effort)

- **#5 SC8 dogfood scheduling.** `REMEMBER.md` (gitignored) gains a `## v5.1.1 sesjon 8 — DOGFOOD GATE OBSERVATIONS` reserved placeholder with concrete procedure: fresh CC-session → real v5.1-eligible task → Phase 3.5 observation → 5 specific questions to answer. The actual observation is a sesjon 8 manual operator action; sesjon 7 produces scaffolding only.
- **Decision B high-effort behavior locked per command** (operator-confirmed, decisions.local.json):
  - `/trekplan` high: gemini-bridge plan-review Pass 2 on the post-revision plan (replaces fragile plan-critic doubling per risk-assessor finding — line numbers shift after revisions, breaking dedup triplets).
  - `/trekresearch` high: full swarm + `contrarian-researcher` AND `gemini-bridge` always-on regardless of normal triggering rules.
  - `/trekreview` high: skip Pass 3 reasonableness filter; coordinator applies `PLAN_EXECUTE_DRIFT` normalization for unknown rule_keys (preserves original in `original_rule_key`).
  - `/trekexecute` high: `gates_mode = 'closed'` automatically; explicit `--gates` flag still wins.
- **Brief Non-Goal amendment** (`.claude/projects/2026-05-13-trekflow-solo-lane/brief.md`, gitignored): low/high effort tiers now locked in v5.1.1; standard remains fallthrough default. Continue + brief phases remain effort-less.
- **Brief SC1 amendment** (same file, gitignored): SC1 "4 AskUserQuestion calls" interpreted as the resolver-invariant `resolvePhaseSignal` returns non-null for all 4 entries in `PHASE_SIGNAL_PHASES`. The literal AskUserQuestion mocking interpretation would require a state-machine harness module (significant scope expansion); the resolver-invariant interpretation is authorized as equivalent. **Operator-confirmed via Pre-Step-10 autonomy gate.**

### Known scheduling

SC8 (#5) dogfood-gate closure happens in sesjon 8 (fresh CC-session, manual `/trekbrief` walk-through). v5.1.1 push to Forgejo gated on sesjon 9 `/trekreview` returning `ALLOW`. If sesjon 9 returns `BLOCK`, loop back to sesjon 6 (new remediation plan).

### Source findings audit trail

Plan-frontmatter `source_findings:` lists the 12 review-finding IDs each step closes. Audit trail traces `review.md` → `/trekplan --brief review.md` (Handover 6) → `plan.md` → `/trekexecute` → individual commits.

## 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 operator's reference

**No new breaking changes beyond v5.0.0.** Forks consuming v5.0.2's
annotation HTML keep working — the file path and entry point are
unchanged. The internal localStorage key bumps from `voyage-annotate:` to
`voyage-annotate:v2:` to avoid mixing the v5.0.2 shape (line-click,
freeform notes) with the v5.0.3 shape (intent-tagged annotations).

### Why

v5.0.2 shipped a too-simple annotation surface: click a line, write a
freeform note, save. The operator pointed at an existing
annotation surface in another project as the actual
reference — pencil-toggle mode, text-selection capture, three intent
categories (**Fiks** / **Endre** / **Spørsmål**), a popover form at the
cursor, structured markdown export with intent labels. v5.0.3 brings
`scripts/annotate.mjs` up to that pattern.

This reference had been mentioned by the operator early in the
conversation; the iteration through v5.0.0 / v5.0.1 / v5.0.2 reflects me
reading past it and trying alternatives instead of just matching it. The
loss is real and is documented here in plain terms so future maintainers
don't repeat it.

### Changed

- **`scripts/annotate.mjs`** — rewritten to match the
  reference annotation UX:
  - **Article rendering** — markdown is rendered to proper HTML elements
    (`<h1>`/`<p>`/`<ul>`/`<li>`/`<table>`/`<blockquote>`/`<pre>`), not as
    line-numbered raw lines. Document reads as a normal article.
  - **Annotatable elements** — every heading, paragraph, list item, table
    cell, blockquote, and code block gets a stable `data-anchor-id`.
  - **Pencil-toggle button** in the topbar — annotation mode default ON.
    Toggle OFF to read normally and follow links.
  - **Click any annotatable element** (in mode) → opens a form popover
    at the cursor with: section context (auto-detected from nearest
    h1/h2), anchored snippet (the exact selected substring via
    `window.getSelection()` if any text is highlighted, else the
    element's text content up to 200 chars), three intent buttons
    (**Fiks** / **Endre** / **Spørsmål**), comment textarea, Cancel +
    Save. Save is disabled until an intent is picked.
  - **Sidebar panel** — collapsed by default; "Show annotations" button
    in the topbar opens it. Annotations grouped by section, sorted by
    document order. Each card shows the intent badge (colored by
    category), the anchored snippet, the operator comment, and a delete
    button. Click a card to scroll the article to that element + flash
    highlight.
  - **Copy Prompt** — structured markdown:
    `### N. [Intent] Section: <section>` + `Quote: «<snippet>»` +
    `Comment: <text>`. Copies to clipboard.
  - **Clear all** — wipes every annotation for the current artifact
    (after confirm).
  - **Persistence** — `localStorage` key `voyage-annotate:v2:<abs path>`.
    Refresh/close/reopen the same HTML keeps every annotation.
  - **Toast feedback** for save / copy / clear.
- **`tests/scripts/annotate.test.mjs`** — refreshed for the v5.0.3 shape:
  pins the three intent buttons (`data-intent="fiks"` / `"endre"` /
  `"spørsmål"`), form popover, selection capture, section auto-detect,
  `voyage-annotate:v2:` storage key prefix, `data-anchor-id` coverage,
  Copy Prompt + Clear all affordances, and the markdown renderer's
  heading / list / table / blockquote / code-fence output. 12 tests
  (up from 10), all passing.

### Notes

- The producing commands (`/trekbrief` Step 4g, `/trekplan` Phase 10,
  `/trekreview` Phase 8) call `scripts/annotate.mjs` the same way as in
  v5.0.2 — no change to their wiring beyond the build-output now being
  the v5.0.3 interactive surface.
- `npm test`: 518 tests, 516 pass, 0 fail, 2 skipped (up from 516 — 2
  new annotate tests for hostile-content escape + renderMarkdown table/
  blockquote coverage).
- Reference: the annotation UI section of the existing surface the
  operator pointed at.
- Version bump 5.0.2 → 5.0.3 in `.claude-plugin/plugin.json`,
  `package.json`, `package-lock.json`, plugin `README.md` badge.

## v5.0.2 — 2026-05-13 — Operator-driven annotation HTML (the actual fix)

**No new breaking changes beyond v5.0.0.** Forks that consumed the v5.0.1
`/playground document-critique` invocation from the producing commands'
final report should switch to opening the `.html` that `scripts/annotate.mjs`
now produces directly.

### Why

v5.0.0 added a read-only `scripts/render-artifact.mjs` HTML render that
didn't afford annotation. v5.0.1 deleted that and pointed operators at
`/playground document-critique` instead — but the `document-critique`
template pre-generates **Claude's** suggestions and asks the operator to
approve/reject them. The operator asked for the opposite: a surface where
**they** select content and write **their own** notes, then ship those
notes back to Claude. v5.0.1 still missed the actual ask.

v5.0.2 ships `scripts/annotate.mjs` — a small, focused, zero-dependency
Node script that takes any artifact `.md` and writes a self-contained
HTML next to it. The HTML renders the document with line numbers, lets
the operator click any line to attach their own note, keeps a sidebar of
all notes (editable + deletable, persisted in `localStorage` per artifact
path so refresh doesn't lose work), and exposes a "Copy Prompt" button
that gathers every note into one structured prompt. The operator copies
that prompt and pastes it back into Claude; Claude revises the `.md`
freehand from the notes. **One file → one HTML → click + write notes →
copy prompt → paste back.** No Claude-generated suggestions in the loop.
The operator drives every annotation.

This is the v4.2/v4.3 *concept* (operator-driven annotation) without the
broken v4.2/v4.3 UX, without the 388 KB SPA, without `/trekrevise`,
without anchor parsers + Handover 8 + the JSON batch round-trip. ~430
lines of self-contained `.mjs`. Zero npm deps. Deterministic.

### Added

- **`scripts/annotate.mjs`** — operator-annotation HTML generator. Takes `<artifact.md>`, writes `<artifact>.html` (or `--out <file>`). Self-contained, design-system-aligned (light + dark + print), zero external network, deterministic. CLI: `node scripts/annotate.mjs <artifact.md> [--out <file.html>]`. Also `npm run annotate -- <artifact.md>`.
- **`tests/scripts/annotate.test.mjs`** (10 tests) — self-contained HTML shape, no external `<link>`/`<script src>`, inline script parses, source content + path embedded, HTML escaping in title + body (XSS surface), determinism, default output path, arg parsing, and the operator-driven affordances (Click any line, Your annotations sidebar, Copy Prompt, Clear all, localStorage).
- **`npm run annotate`** convenience script.

### Changed

- **`commands/trekbrief.md` Step 4g, `commands/trekplan.md` Phase 10, `commands/trekreview.md` Phase 8** — each now runs `scripts/annotate.mjs` after the artifact is final and prints the resulting `file://<abs path>` link with explicit "Click any line to add YOUR OWN note" instructions. The v5.0.1 `/playground build a document-critique playground for …` line is removed from all three.
- **`tests/lib/doc-consistency.test.mjs`** — replaced the v5.0.1 `/playground` pins with v5.0.2 pins: `scripts/annotate.mjs` exists; producing commands invoke it; producing commands no longer print the v5.0.1 `/playground document-critique` line; producing commands signal operator-driven annotation in their prose; CHANGELOG has a v5.0.2 entry.
- **Plugin `CLAUDE.md` + `README.md` + root `CLAUDE.md` + root `README.md` + `.claude-plugin/marketplace.json`** — voyage description updated from "v5.0.1 /playground invocation" to "v5.0.2 operator-annotation HTML (`scripts/annotate.mjs`)".

### Notes

- `/playground` is unchanged — the official `claude-plugins-official` `playground` skill is great for the Claude-leads, operator-reacts flow; it just wasn't the right tool for operator-leads, Claude-reacts.
- `npm test`: 516 tests, 514 pass, 0 fail, 2 skipped (up from 503 — 10 new `annotate.test.mjs` tests + 3 net new doc-consistency pins).
- Version bump 5.0.1 → 5.0.2 in `.claude-plugin/plugin.json`, `package.json`, `package-lock.json`, plugin `README.md` badge.

## v5.0.1 — 2026-05-13 — Drop the standalone HTML render; print a literal /playground invocation

**No new breaking changes beyond v5.0.0.** Forks that consumed
`scripts/render-artifact.mjs` directly (or invoked `npm run render`) must
remove that integration. Nothing else moves.

### Why

v5.0.0 had `/trekbrief`, `/trekplan`, and `/trekreview` each finish by
*both* rendering a read-only `{artifact}.html` view (via the new
`scripts/render-artifact.mjs`) *and* printing a vague instruction to "run
the `/playground` plugin (`document-critique` template) on the `.md` and
paste the prompt back". In practice the operator saw two HTMLs in their
project dir, no annotation UI on the rendered `.html`, and had to guess
the right `/playground` invocation. The read-only `.html` added confusion
without affording annotation — it duplicated work the `/playground`
HTML already does (formatted document on the left, annotations on the
right, Copy Prompt button at the bottom).

v5.0.1 deletes the redundant render and makes the printed `/playground`
invocation literal and copy-paste-ready. One paste from the operator
launches the `playground` skill, which loads its `document-critique`
template, reads the `.md`, builds the interactive HTML, opens it. Mark
suggestions, click Copy Prompt, paste back. Done.

### Removed

- **`scripts/render-artifact.mjs`** — the v5.0.0 standalone Markdown→HTML renderer (~280 lines, zero deps). Redundant with `/playground`'s HTML.
- **`tests/scripts/render-artifact.test.mjs`** (and the now-empty `tests/scripts/` dir).
- **`npm run render`** script alias in `package.json`.
- All references to `render-artifact.mjs`, `brief.html`, `plan.html`, `review.html` in `CLAUDE.md` (plugin + root), `README.md` (plugin + root), `.claude-plugin/marketplace.json`, and the three command files' final-output blocks.

### Changed

- **`commands/trekbrief.md` Step 4g (Finalize), `commands/trekplan.md` Phase 10 (Present and refine), `commands/trekreview.md` Phase 9 (Present summary)** — each now ends by printing a single boxed block with the literal text `/playground build a document-critique playground for {abs_path}` and a one-paragraph explanation of the paste-mark-copy-paste loop. The literal string is pinned by `tests/lib/doc-consistency.test.mjs` so it cannot soften back into "run the `/playground` plugin" without a test failure.
- **`tests/lib/doc-consistency.test.mjs`** — replaced the v5.0.0 `render-artifact.mjs exists` + `producing commands reference render-artifact.mjs` pins with v5.0.1 pins: `render-artifact.mjs` *no longer* exists; producing commands include the literal `/playground build a document-critique playground for` invocation; producing commands no longer reference `render-artifact.mjs`; `package.json scripts.render` is gone; CHANGELOG has both v5.0.0 and v5.0.1 entries.
- **Plugin `CLAUDE.md`** — "Render-and-link (v5.0.0)" paragraph rewritten to "Post-command annotation invocation (v5.0.1)" explaining the literal-paste contract; project-directory contract no longer lists `.html` siblings; "State" section's project-root inventory no longer lists `.html` files.
- **Plugin `README.md`** — "Rendered artifacts & annotation (v5.0.0)" section rewritten to "Reviewing and annotating artifacts (v5.0.1)" with a worked example of the printed output and a "What v5.0.1 changed from v5.0.0" sub-note. Top-of-README one-liner + bottom "Known limitations" note updated.
- **Root `CLAUDE.md`** + **root `README.md`** + **`.claude-plugin/marketplace.json`** — voyage description updated to v5.0.1 + the one-paste invocation model.

### Notes

- `/playground` is the `playground` skill from `claude-plugins-official`. It must be installed in the operator's environment for the printed command to work. If it isn't, the same effect is achievable by pasting the `.md` content into Claude with "review this and suggest changes" — manual freehand revision.
- `npm test`: 503 tests, 501 pass, 0 fail, 2 skipped (down from 509 — 8 `render-artifact.test.mjs` tests removed; the doc-consistency pins were updated to v5.0.1 contracts, net +2 tests).
- Version bump 5.0.0 → 5.0.1 in `.claude-plugin/plugin.json`, `package.json`, `package-lock.json`, plugin `README.md` badge.

## v5.0.0 — 2026-05-12 — Remove the bespoke playground; render artifacts to HTML + link

**Breaking.** `/trekrevise` is removed. The `playground/` directory, Handover 8
(annotation → revision), and all of its supporting `lib/` modules and tests are
gone. Forks that depended on `/trekrevise`, the playground HTML, `lib/parsers/anchor-parser.mjs`,
`lib/parsers/annotation-digest.mjs`, `lib/util/markdown-write.mjs`, or
`lib/util/revision-guard.mjs` must migrate to the official `/playground` plugin
(`document-critique` / `diff-review` templates).

### Why

v4.2/v4.3 built a ~388 KB bespoke playground SPA — vendored markdown-it +
highlight.js + DOMPurify, a design-system copy, a dashboard, drill-down, custom
annotation gestures, an anchor parser, and a Playwright e2e suite — to let
operators annotate brief/plan/review artifacts in a browser and fold those
annotations back via `/trekrevise` (Handover 8). A 2026-05-12 browser
walkthrough found it borderline unusable (annotation broken in the drill-down,
dashboard didn't take over, no in-context anchor markers, wrong anchor
derivation, broken `guide-panel` chrome). And it duplicated work the official
`/playground` plugin already does well: `document-critique` and `diff-review`
templates produce clean, self-contained single-file HTML for exactly this. The
NIH cost was real; the lasting value of v4.2/v4.3 is this cautionary record.
Lesson: reach for existing capabilities before building bespoke ones, and
walk the UI in a browser before shipping it.

### Removed

- **`plugins/voyage/playground/`** — the whole directory: `voyage-playground.html`, its `README.md`, vendored `lib/` (markdown-it / highlight.js / DOMPurify / manifests), and the vendored `playground-design-system/` copy (the canonical `shared/playground-design-system/` is untouched — other plugins still use it).
- **`/trekrevise`** — `commands/trekrevise.md` and the `trekrevise` block in `settings.json`.
- **Handover 8 (annotation → revision)** — deleted from `docs/HANDOVER-CONTRACTS.md`; back to seven handovers.
- **`lib/parsers/anchor-parser.mjs`**, **`lib/parsers/annotation-digest.mjs`**, **`lib/util/markdown-write.mjs`** (`readAndUpdate`), **`lib/util/revision-guard.mjs`**.
- **`scripts/vendor-playground-libs.mjs`**, **`playwright.config.mjs`**, **`tests/e2e/`** (a11y + network specs + snapshots), **`tests/playground/`**, **`tests/fixtures/playground/`**, **`tests/fixtures/screenshot-project/`**, **`tests/fixtures/annotation/`**.
- **Tests for the removed modules** — `tests/parsers/anchor-parser.test.mjs`, `tests/parsers/annotation-digest.test.mjs`, `tests/integration/annotation-roundtrip.test.mjs`, `tests/integration/annotation-block-boundary.test.mjs`, `tests/integration/annotation-export-schema.test.mjs`, `tests/integration/schema-rollback.test.mjs`, `tests/lib/revision-guard.test.mjs`, `tests/lib/markdown-write.test.mjs`, `tests/lib/source-annotations.test.mjs`, `tests/validators/{brief,plan,review}-validator-annotation-fields.test.mjs`, and the old `tests/scripts/render-artifact.test.mjs` (a fresh one ships in this release).
- **`docs/annotation-quickstart.md`**, **`docs/sc1-checklist-verification.md`**, **`docs/screenshots/`**.
- **`commands/trekplan.md` Phase 9 `plan_critic`-injection block** (and its `agents/planning-orchestrator.md` mirror) — it `import`ed the now-deleted `lib/util/markdown-write.mjs`. The `plan_critic` frontmatter field is no longer written.
- **`devDependencies` (`@axe-core/playwright`, `@playwright/test`)** and the `test:e2e` script in `package.json`; `package-lock.json` synced (no runtime deps — it's near-empty).
- The annotation-frontmatter HTML-comment preambles in `templates/{trekbrief,plan,trekreview}-template.md` (the validators still tolerate unknown frontmatter keys; nothing emits `revision:` / `source_annotations:` / `annotation_digest:` anymore).

### Added

- **`scripts/render-artifact.mjs`** — a small (~280 lines), zero-dependency Node renderer. Reads a `.md` artifact, folds frontmatter into a `<details>` block, renders a hand-rolled markdown subset (ATX headings, ordered/unordered/nested lists, fenced code blocks, inline code, bold/italic, links, blockquotes, GitHub-style tables, horizontal rules), and emits a self-contained HTML file with an inlined, design-system-aligned stylesheet (light + dark + print). **Zero external network, zero build step, deterministic** (byte-identical on re-run). CLI: `node scripts/render-artifact.mjs <artifact.md> [--out <file.html>]`; also `npm run render`.
- **Render-and-link step** at the end of `/trekbrief`, `/trekplan`, and `/trekreview` — each renders its just-written `.md` to `{project_dir}/{artifact}.html` and prints the `file://` link plus a one-liner: to annotate, run the `/playground` plugin (`document-critique`) on the `.md` and paste the generated prompt back; Claude revises the artifact freehand.
- **`tests/scripts/render-artifact.test.mjs`** (fresh, 8 tests) — self-contained-document shape, frontmatter `<details>` folding, title derivation, headings/code-fences/lists/tables/blockquotes rendering, HTML escaping, determinism, default output path, arg parsing.
- **`tests/lib/doc-consistency.test.mjs` v5.0.0 pins** — `playground/` gone, `commands/trekrevise.md` gone, Handover 8 gone, `render-artifact.mjs` exists, producing commands reference `render-artifact.mjs` and `/playground`, CHANGELOG has a v5.0.0 entry and retains the v4.2.0 entry, and no source file (outside CHANGELOG) references `trekrevise`.

### Notes

- Resolves the three v4.3.1-deferred findings as moot: `87069b35` and `c6c64a58` targeted `playground/voyage-playground.html` (deleted); `4cc3bfc9` targeted the Phase 9 `readAndUpdate` block in `commands/trekplan.md` (deleted).
- Command count: seven → six (`/trekbrief`, `/trekresearch`, `/trekplan`, `/trekexecute`, `/trekreview`, `/trekcontinue`; plus the `/trekendsession` helper).
- `npm test` is the fork-readiness gate; `npm run test:e2e` is gone (no Playwright).

## v4.3.0 — 2026-05-10 — Playground rebuild: dashboard-centric + visual parity + anchor-rendering matures

**Additive. No breaking changes. Forward-compat with every brief / plan / review / playground export written before v4.3.**

The v4.2 playground proved the annotation loop. v4.3 rebuilds it from the ground up against the design-system reference (`plugins/llm-security/playground/llm-security-playground.html`) and brings anchor-rendering to maturity. Dashboard-centric layout, file://-loader (webkitdirectory + drag-drop + URL-parameter), block-boundary anchor placement, screenshots-spor convention, and a hardened test pyramid (Groups A-D).

### Added

- **Dashboard-centric layout** — `fleet-grid` of `fleet-tile` per artifact (brief / plan / research / review) with status badges; click drills into artifact-detail surface. Two-overflate-modell matches voyage's domain (one plugin, no onboarding) — alternative 4-overflate-router rejected per Alternatives Considered.
- **File://-loader with three entry points** — `webkitdirectory` directory-picker (Chromium primary, Firefox 150+ secondary with Windows-bug guard), drag-drop with `webkitGetAsEntry` recursive walk, and URL-parameter `?project=/abs/path` ergonomic shortcut. Path-traversal + symlink/dotfile filter (`isProjectPathSafe`) blocks `..` / `node_modules/` / `dist/` / `build/` / hidden-paths with `aria-live` announces.
- **Anchor-rendering matures** — block-boundary placement with code-fence/table/list-item fallback (Prettier #18066 workaround); browser-side `parseAnchor` mirrors Node-side `lib/parsers/anchor-parser.mjs` regex; numbered-badge gutter + yellow-tint highlight replaces v4.2's pencil-icon; hidden-by-default sidebar-rail with ordered list, filter, and jumplist count; J/K keyboard navigation + Esc dismiss + aria-live announces; two-opacity pattern (active 100% / inactive 40% / resolved 30% strikethrough).
- **A11Y panel built from DS-primitives** (Wave 5 Step 22) — `guide-panel--info` container with `key-stats` severity-grid + `findings__items` ordered list; `wireA11yToggle` couples topbar-button to panel; `window.__voyage.scheduleRender({ a11yViolations })` hook lets Playwright spec populate severities.
- **Screenshots-spor convention** (Wave 5 Step 23) — `window.__voyage` namespace with `navigate(target)`, `scheduleRender({ a11yViolations })`, and `getProjectArtifacts()` methods; `docs/screenshots/README.md` documents manual + Playwright-driven screenshot procedure (defers inline gallery to v4.4).
- **DOMPurify ≥ 3.1.1 vendored** (Wave 5 Step 24) — `playground/lib/dompurify.min.js` (22 KB UMD bundle); `sanitizeAnnotation` wraps user-comment markdown rendering; total bundle 388 KB / 460 KB HALT-gate (72 KB margin). HTML-comment indirect prompt-injection mitigation (Wave 5 Step 25) gates `stripUnsafeComments` via `parseAnchor` allowlist before `md.render`.
- **Voyage-scope DS-tokens** (Wave 0 Step 1) — `--color-scope-voyage` + `badge--scope-voyage` added additively to `shared/playground-design-system/dist/base.css` and re-synced into the playground vendor copy. Other plugins (architect / okr / llm-security / config-audit) re-sync on next playground touch (additive-only change).
- **Test pyramid Groups A-D** (Wave 7) — Group A 17 static-HTML grep tests (SC1 10-element checklist + SC3 webkitdirectory/drag-drop + SC6 export markers + SC7 tag-level no-CDN), Group B 9 structure tests (DS-tokens + theme-toggle + sidebar-tab + keyboard pattern), Group C 7 export-bundle schema + `annotation_digest` SHA-256 validity tests (SC-GAP-3), Group D 4 Playwright e2e tests (light/dark axe-core + pixel-diff baseline + zero-external-network authoritative gate).
- **Playwright + @axe-core/playwright devDeps** + `playwright.config.mjs` — `testDir: 'tests/e2e'`, `snapshotPathTemplate: '{testDir}/snapshots/{arg}{ext}'`, `npm run test:e2e` script. Chromium browser binary installed locally.
- **`tests/fixtures/playground/`** — `v43-export-bundle.json` (canonical export shape) + `v43-plan-pre-annotate.md` (revision: 0 seed with ANN-0001/ANN-0002 anchors).
- **`tests/e2e/snapshots/a11y-baseline.json`** — WCAG-violations delta-baseline (`aria-hidden-focus`, `color-contrast` per `.key-stat--critical__label`); a11y spec compares current against baseline, fails only on NEW or GROWN violations. Actual fix deferred to v4.4 (HTML FROZEN in Sesjon 6).
- **`docs/sc1-checklist-verification.md`** — per-element pass/fail with evidence (Group A test references + manual side-by-side); 8/10 PASS literal + 2/10 PASS-redef (Element 4 onboarding-grid → fleet-grid, Element 6 screenshots-spor → hooks + docs convention) per scope-guardian Assumptions 21+22.
- **`playground/README.md`** — v4.3 architecture, three entry-point usage, `.claude/projects/` discoverability, annotation flow, `window.__voyage` hooks, known limitations (FF150-Win, no FSA, baseline'd WCAG), bundle-size breakdown, test-suite overview.

### Changed

- **Test count: 672 → 711 pass / 0 fail / 2 skipped** (713 total — Groups A/B/C node-test additions from the rebuild and the Sesjon 13–18 re-review remediation; +5 Playwright e2e specs run via `npm run test:e2e`).
- **Theme bootstrap IIFE** (Wave 2 Step 6) sets `data-theme="dark"` as default; respects `localStorage('voyage-theme')` → `prefers-color-scheme: dark` matchMedia → fallback `dark`. Theme-toggle button in topbar (Wave 2 Step 7) persists user choice.
- **Page-shell pattern** (Wave 2 Step 9) — `page__eyebrow` + `page__title` + `page__lede` + `page__meta` matches DS reference.
- **Annotation export filename** — `annotated-{target}.md` where target = brief|plan|review|artifact (derived from frontmatter).

### Fixed

- **Browser-side anchor regex** synced with Node-side allowlist (Wave 4 Step 16) — `VOYAGE_ANCHOR_RE` / `VOYAGE_ANCHOR_ID_RE` mirror `lib/parsers/anchor-parser.mjs:20-25`; `parseAnchor` validates ID + intent + line-number per attribute regex.
- **Hard-coded WIP token strings** (Wave 1 Step 4) — voyage tokens normalized to canonical `--color-scope-voyage` + `--ds-color-*` tokens; literal pixel font-sizes replaced with DS scale.
- **Plan-determinism test reference path** (Wave 0 Step 3) — `tests/synthetic/plan-determinism.test.mjs:115` updated to `plan-run-C.md` (alphabetic convention matching A/B).

### Re-review remediation (Sesjon 13–18)

After the rebuild, an independent `/trekreview` (Sesjon 13) flagged 11 findings (5 BLOCKER + 5 MAJOR + 1 MINOR). Waves 1–3 of remediation closed **all 11** with delivered code + tests — notably reinstating an **inline screenshots gallery** (`renderScreenshotGallery`, finding `31d28f65`; supersedes the original "deferred to v4.4" item below), wrapping `renderArtifact`'s `bodyHtml` in `DOMPurify.sanitize` (`1d3591d4`), converting the SC2 a11y spec to absolute zero-violation mode and removing `a11y-baseline.json` (`09132940`), documenting the Phase 9 `plan_critic` frontmatter injection (`906f155d`), and asserting the `.fleet-grid` 4-column CSS parity (`99707f51`). A Sesjon 18 re-review then found 3 **new** findings introduced by the remediation code itself — deferred to v4.3.1 (see *Known issues* below).

### Deferred to v4.4

- WCAG-violations fix (HTML FROZEN in Sesjon 6 per Wave 7 verification-only scope; superseded for the a11y-spec by the absolute zero-violation conversion in the Sesjon 13–18 remediation).
- File System Access API (FSA) write-back (currently `Blob`-download only).
- `<project>/design/`-folder traversal.
- `IndexedDB` primary persistence (localStorage stays primary for v4.3).
- Hybrid claude-design-skill → canvas → frontend-design workflow (research/02 deferred to v4.4+).

### Known issues — deferred to v4.3.1 → all resolved in v5.0.0 (moot)

The Sesjon 18 re-review surfaced 3 findings in code the Sesjon 13–18 remediation introduced. They were deferred to a planned v4.3.1 patch; **v5.0.0 makes all three moot** by removing the playground entirely:

- **`87069b35` (SECURITY_INJECTION, defense-in-depth)** — `renderScreenshotGallery()` interpolated `screenshots[].dataUrl` raw into an `<img src>`. **Moot in v5.0.0** — `playground/voyage-playground.html` is deleted.
- **`4cc3bfc9` (PLAN_EXECUTE_DRIFT)** — `commands/trekplan.md` Phase 9 used a backtick template literal as an ES `import` specifier (`SyntaxError`). **Moot in v5.0.0** — the Phase 9 `plan_critic`-injection-via-`readAndUpdate` block is deleted.
- **`c6c64a58` (MISSING_TEST)** — no test covered the gallery `dataUrl` injection path. **Moot in v5.0.0** — the gallery and its host file are deleted.

### Notes

- Brief, research (4 briefs), plan, and execute (6 sessions) all produced from the v4.3 pipeline itself. SC11 pipeline-self-eat gate continues to hold.
- Path A/B/C decision (cache-first / sequential `--no-ff` waves / hybrid identical-tool) unchanged from v3.4.0 — Path B remains in production.
- Plan quality score 86/100 Grade A APPROVE_WITH_NOTES (adversarial review Phase 9, 22 revisions documented in plan.md Revisions table). Sesjon 13–18 remediation plans reviewed independently; Sesjon 18 re-review verdict BLOCK with 3 findings (now v4.3.1).

## v4.2.0 — 2026-05-09 — Annotation pipeline + first voyage playground

**Additive. No breaking changes. Forward-compat with every brief / plan / review written before v4.2.**

Voyage's first interactive playground. The `/trekrevise` command and the
annotation pipeline (Handover 8) close the operator-feedback loop: render an
artifact in the browser, anchor comments at block boundaries, export a batch,
paste back as `/trekrevise --apply` for in-place revision with audit trail.

### Added

- **`/trekrevise` command** (`commands/trekrevise.md`) — seventh pipeline
  command. Phase 1 parse/validate, Phase 2 read source + rollback hygiene,
  Phase 3 parse anchors + validate placement, Phase 4 compute revision
  diff + digest, Phase 5 atomic apply, Phase 6 post-write integrity check,
  Phase 7 optional review-gate, Phase 8 stats + report. Accepts
  `--profile`, `--gates`, `--reason`, `--from-file`, `--target`.
- **Handover 8 (annotation → revision)** documented in
  `docs/HANDOVER-CONTRACTS.md` (~100 lines). Producer/consumer contract,
  schema for the four additive frontmatter fields (`revision`,
  `source_annotations`, `annotation_digest`, `revision_reason`), block-level
  anchor format, lifecycle, single-iteration MVP rationale.
- **`playground/voyage-playground.html`** — single self-contained HTML file
  with vendored `markdown-it` v14.1+ + `highlight.js` (no `marked` per Issue
  #3515). Three annotation creation gestures (drag-select, hover-anchor,
  click-anchor), modal form with intent taxonomy (change/add/remove/
  clarify/risk), sidebar with critique-card-list, export flow with
  one-click clipboard copy, A11Y baseline (keyboard nav, ARIA roles,
  focus traps).
- **`playground/lib/`** vendored markdown-it + highlight.js + front-matter
  plugin, with `VENDOR-MANIFEST.json` recording version + license + sha.
  Locked at minimum versions per research-03.
- **`scripts/render-artifact.mjs`** server-side render CLI — emits the same
  HTML the playground produces. Used by the SC11 pipeline-self-eat gate
  (rendering `.claude/projects/*/brief.md` + `plan.md` exits 0 with
  non-empty output).
- **`scripts/vendor-playground-libs.mjs`** vendor-refresh helper — fetches
  pinned versions and updates the manifest.
- **`lib/parsers/anchor-parser.mjs`** — pure-function anchor parser:
  `parseAnchors`, `addAnchors`, `stripAnchors`, `validateAnchorPlacement`.
  Block-boundary discipline (no in-list, no mid-paragraph, no line-start
  collisions). Round-trip tested with byte-identical fixture
  (`tests/fixtures/annotation/annotation-example.md`).
- **`lib/parsers/annotation-digest.mjs`** — pure-function deterministic
  SHA-256 over canonical-sorted `source_annotations`. First 16 hex chars.
  Idempotent: same batch → same digest.
- **`lib/util/markdown-write.mjs`** — `serializeFrontmatter` +
  `atomicWriteMarkdown` (tmp-file + rename, same crash-safety as
  `atomic-write.mjs`).
- **`lib/util/revision-guard.mjs`** — atomic-write rollback guard for
  `/trekrevise` Phase 6 round-trip integrity check (plan-critic M4).
  Restores byte-identical pre-write file from `*.local.bak` on failure.
- **`docs/annotation-quickstart.md`** — operator-facing 7-step
  walkthrough, references `tests/fixtures/annotation/annotation-example.md`
  for hands-on verification.
- **`tests/fixtures/annotation/`** — 5 fixtures covering `brief`, `plan`,
  `plan-large`, `review`, and the canonical `annotation-example.md`.
- **9 new test files** + extension to `tests/lib/doc-consistency.test.mjs`:
  - `tests/lib/markdown-write.test.mjs` (round-trip)
  - `tests/parsers/anchor-parser.test.mjs` (parse/add/strip/validate)
  - `tests/parsers/annotation-digest.test.mjs` (determinism)
  - `tests/validators/{brief,plan,review}-validator-annotation-fields.test.mjs`
    (forward-compat: validators tolerate the four optional fields)
  - `tests/integration/annotation-roundtrip.test.mjs` (SC2/SC3/SC7
    byte-identical + scale)
  - `tests/integration/schema-rollback.test.mjs` (SC5b validator-FAIL
    rollback)
  - `tests/integration/source-annotations.test.mjs` (frontmatter
    audit trail)

### Changed

- **Forward-compat policy** documented in `lib/validators/{brief,plan,
  review}-validator.mjs` headers — validators silently accept the four
  optional annotation fields without bumping `*_version`.
- **`tests/lib/doc-consistency.test.mjs`** extended with ~16 new pins:
  Handover 8 section, templates' annotation-field comment blocks,
  `playground/` directory, `marked`-ban, `scripts/render-artifact.mjs`,
  `lib/util/revision-guard.mjs`, `parseAnchors` round-trip on the example
  fixture, `/trekrevise` in CLAUDE.md / plugin README / marketplace root
  README, `## v4.2.0` in CHANGELOG, `docs/annotation-quickstart.md`
  existence + ≤7 numbered steps + `annotation-example.md` literal
  reference.
- **`PIPELINE_COMMANDS` constant** in doc-consistency tests — was 6
  (brief/research/plan/execute/review/continue), now 7 (+ revise). Pin
  test renamed from "all six pipeline commands" to "all seven pipeline
  commands".
- **`settings.json` known-scopes allowlist** — `'trekrevise'` added to
  the recognized top-level scope list (was added in Wave 2 Step 6 to
  keep tests green pre-Step 12).
- **Templates** (`templates/{plan,trekbrief,trekreview}-template.md`)
  prefixed with comment-only documentation block of the four optional
  annotation fields. No `*_version` change; existing templates still
  parse and validate identically.

### Notes

- **`marked` is banned** from `playground/*` (risk-assessor H1 +
  doc-consistency pin). Issue #3515 corrupts content silently after
  HTML comments in lists — voyage anchors after step-list would be
  invisible. `markdown-it` v14.1+ is the locked renderer.
- **Single-iteration MVP** per research-05. Each operator batch produces
  one `revision:` increment. Multi-iteration loops (revise → re-review
  → revise again) are deferred indefinitely; the brief's SC4 wording is
  single-revision.
- **No `*_version` bump** for v4.2 — the four new fields are additive.
  Brief/plan/review artifacts written before v4.2 validate as
  `revision: 0` without migration.
- **Atomic-write contract** for `/trekrevise` — single
  `writeFileSync`+`renameSync` (research-05 Option B). Option C
  (`atomicWriteJson + Edit-tool` split-write) was inadmissible per
  risk-assessor C2: no crash-safe window between frontmatter patch and
  body Edit.
- **608 tests pass** (606 → 0 fail → 2 skipped Docker) — baseline
  before v4.2 was 490; this release adds ~118 tests.

## v4.1.0 — 2026-05-09

**Additive. No breaking changes. Forward-compat with all v4.0.0 plans.**

Two new feature surfaces: model profiles (`--profile <name>`) and
opt-in OpenTelemetry / Prometheus export at session-end.

### Added

- **Model profile system** (`lib/profiles/{economy,balanced,premium}.yaml`,
  `lib/profiles/resolver.mjs`, `lib/validators/profile-validator.mjs`).
  Three built-in tiers + custom-yaml support. Lookup order: explicit
  `--profile` flag → plan frontmatter `profile:` → `VOYAGE_PROFILE`
  env-var → `balanced` default. See `docs/profiles.md` for the decision
  tree, custom authoring, and cost estimation disclaimer.
- **`--profile <name>` flag** documented in all 6 pipeline commands
  (`commands/trek{brief,research,plan,execute,review,continue}.md`).
- **5 additive profile fields** in JSONL stats (`profile`,
  `profile_source`, `phase_models`, `model_used`,
  `phase_models_resolved`) for cost-attribution and drift detection.
- **OpenTelemetry / Prometheus export** at session-end via new Stop
  hook (`hooks/scripts/otel-export.mjs`, wired in `hooks/hooks.json`).
  Strict opt-in via `VOYAGE_EXPORT_MODE`:
  - `textfile` — Prometheus exposition format → node-exporter textfile
  - `otlp` — OTLP/JSON POST → otel-collector
  - `off` (default) — no work done
- **Local Docker Compose stack** at `examples/observability/`
  (Prometheus 3.0.1 + node-exporter 1.10.2 + Grafana 11.4.0 + OTel
  Collector 0.115.0, all version-pinned per research/01).
- **Operator documentation** at `docs/observability.md` (151 lines:
  env-var matrix, security mitigations, limitations, CVE-pinned
  minimum versions).
- **Cross-tier Jaccard smoke test**
  (`tests/integration/profile-jaccard-smoke.test.mjs`) with parked-
  synthetic fixtures and 0.55 conservative starting threshold per
  research/02. Empirical recalibration deferred to v4.2.
- **MANIFEST_PROFILE_DRIFT warning** in `plan-validator --strict`
  when plan frontmatter `profile:` differs from any step manifest's
  `profile_used`. Plan remains valid (warning, not error).

### Changed

- **`lib/parsers/arg-parser.mjs` FLAG_SCHEMA** — additively adds
  `--profile <name>` to all 6 commands. Existing flags unchanged.
- **`lib/parsers/manifest-yaml.mjs` schema** — additively adds new
  `OPTIONAL_STRING_KEYS` collection with `profile_used` as the first
  member. Forward-compat: legacy plans without `profile_used` parse
  unchanged; new plans with it round-trip cleanly.

### Fixed

- **Doc-consistency coverage** now spans all 6 pipeline commands
  (was 5 — `/trekcontinue` was missing per HIGH risk-assessor).
- **Plan-validator strict mode** detects profile-drift between plan-
  level frontmatter and step-level manifests (brief Assumptions
  block 7).

### Notes

- Forward-compat: every v4.0.0 plan validates `valid: true` under
  v4.1.0's `plan-validator --strict`. No migration needed.
- Tests: 361 baseline → 484 pass + 2 skipped (Docker-dependent).
- Path A/B/C decision (v3.4.0) is unchanged. Path C remains closed.
- v4.2 deferred items: ROUGE-L scoring, char-4gram MinHash, empirical
  Jaccard re-calibration, `balanced.external_research_enabled`
  operator-override.

## v4.0.0 — 2026-05-05

**Breaking. Rebrand. No migration path.**

The `ultraplan-local` plugin is renamed to **Voyage**. All seven commands
are renamed from `/ultra*-local` to `/trek*`:

- `/ultrabrief-local` → `/trekbrief`
- `/ultraresearch-local` → `/trekresearch`
- `/ultraplan-local` → `/trekplan`
- `/ultraexecute-local` → `/trekexecute`
- `/ultrareview-local` → `/trekreview`
- `/ultracontinue-local` → `/trekcontinue`
- `/ultraplan-end-session-local` → `/trekendsession`

Internal renames: FLAG_SCHEMA keys, stats filenames, env vars, branch
namespace, type discriminators, hook stderr prefixes, settings.json scope
keys all updated to `trek*` form. Plugin identity is now `voyage`.

No backward compatibility. Old artifacts on user disks are orphaned.
Fork-and-own users re-fork from main if they want to follow upstream;
there is no migration helper.

See `TRADEMARKS.md` for the new trademark hygiene notice clarifying
independence from Anthropic.

Out-of-scope handoff (operator follow-up): plugin directory rename
`plugins/ultraplan-local/` → `plugins/voyage/`, marketplace-root
coordination across `../../README.md`, `../../CLAUDE.md`, and
`../../.claude-plugin/marketplace.json`.

## [3.4.1] - 2026-05-04 — `/ultracontinue-local` hot-fix + ultra-cc-architect doc-rydding

Forward-patch on top of v3.4.0. Fixes four bugs in the multi-session
resumption path discovered post-3.3.0 ship, plus a doc-rydding sweep
that generalizes references to the `ultra-cc-architect` plugin (no
longer publicly distributed). Non-breaking: the `architecture/overview.md`
filesystem contract (Handover 3) is preserved for any compatible
producer.

### Fixed

- **Bug 1 — `/ultracontinue-local` Phase 0 + auto-discovery.**
  `commands/ultracontinue-local.md` no longer prints a usage block on
  bare invocation; it enters auto-discovery (sorts active state files
  numerically by `Date.parse(updated_at)`, not lexicographically — fixes
  cross-timezone wrong-order). `--help` / `-h` is the only flag that
  surfaces the usage block. (Steps 1–3)
- **Bug 2 — Phase 2 placeholder leakage.** `{state-file-path}`,
  `{project-dir}`, `{path-a}` and similar template tokens are gone from
  `commands/ultracontinue-local.md` Phase 2 prose. The command now reads
  the resolved path inline rather than asking the model to substitute.
  (Steps 4–5)
- **Bug 3 — frontmatter consistency for `NEXT-SESSION-PROMPT.local.md`.**
  Producers (`/ultraexecute-local` Phase 8, `/ultraplan-end-session-local`)
  now write `produced_by:` + `produced_at:` (ISO-8601) frontmatter on the
  prompt file. `/ultracontinue-local` Phase 1.5 cross-checks `produced_at`
  against the sibling state file's `updated_at` and refuses to proceed on
  inconsistency (`NEXT_SESSION_PROMPT_INCONSISTENT`). Files without
  frontmatter remain tolerated (warning, not error) for backwards
  compatibility. State-anchored staleness check is the primary signal;
  24h wall-clock is a soft warning only. (Steps 6–8)
- **Bug 4 — `--cleanup` for completed projects.** `/ultracontinue-local
  --cleanup <project-dir>` (dry-run by default) and
  `/ultracontinue-local --cleanup --confirm <project-dir>` (deletes the
  state file + sibling prompt file). Refuses non-completed status with
  no force flag. Idempotent — safe to re-run after partial cleanup.
  (Steps 9–10)
- **ESM/CJS regression in `commands/ultraplan-end-session-local.md`.**
  Phase 3 now invokes `atomicWriteJson` via `node --input-type=module`
  rather than the broken `require()` call. State writes from the helper
  command are no longer silently lost on Node 18+. (Collateral in Step 7)
- **`plugin.json` description drift.** "Five-command" → "Six-command";
  trailing `ultra-cc-architect` sentence removed. (Step 13)

### Added

- `lib/util/cleanup.mjs` — refuse-unless-completed gate + dry-run +
  confirm-aware deleter for state file and sibling prompt file.
- `lib/validators/next-session-prompt-validator.mjs` — frontmatter
  validator + state-anchored staleness check + CLI shim.
- `tests/commands/ultracontinue.test.mjs` — new test directory; covers
  SC-1 (auto-discovery sort + usage block), SC-2 (.md diagnostic),
  SC-3 (path-guard ALLOW + no placeholder), SC-4 (consistency), SC-5
  (cleanup wiring).
- `tests/validators/next-session-prompt-validator.test.mjs` — unit
  coverage for frontmatter consistency: matching, mismatch, wall-clock,
  no-frontmatter, missing-field.
- `tests/lib/cleanup.test.mjs` — cleanup util tests.
- `--cleanup` + `--confirm` flags on `/ultracontinue-local`.

### Changed

- `docs/HANDOVER-CONTRACTS.md` Handover 7 gains a § Lifecycle subsection
  documenting producer/consumer arbeidsdeling, the stale-file principle
  (operator-invoked `--cleanup`, no auto-cleanup, no force flag), the
  `produced_by:` + `produced_at:` frontmatter contract, and idempotency.
- `CLAUDE.md`, `README.md`, `SECURITY.md` — generalize references to
  `ultra-cc-architect` plugin to "opt-in upstream architect plugin (not
  bundled)". `CHANGELOG.md` historical references are preserved with a
  2026-05-04 banner stating the plugin is no longer publicly distributed.

### Tests

- 322 (v3.3.0 baseline) → 358 (post-Wave 4) → 361 (Step 11 doc-pins) →
  ~363 at release. New tests: arg-parser FLAG_SCHEMA extensions,
  ultracontinue auto-discovery + diagnostic + path-guard +
  consistency + cleanup wiring, next-session-prompt-validator
  frontmatter checks, cleanup util, and 3 new doc-consistency pins
  for Handover 7 § Lifecycle + next-session-prompt-validator CLI shim.

## [3.4.0] - 2026-05-04 — Ultra-pipeline speedup

Hardenings + scaffolding to support an autonomy chain from brief approval
through main-merge with parallel-wave execution. Non-breaking: all existing
flags continue to work; `--gates` is opt-in autonomy control. Plan-step
delivery covered by 18 plan-v2 steps split across three Waves.

### Added — autonomy + parallelism

- `lib/util/autonomy-gate.mjs` — autonomy-gate state machine (idle → approved → executing → merge-pending → main-merged) for the brief-to-merge chain (Step 4)
- `lib/review/plan-review-dedup.mjs` — deterministic plan-review dedup helpers reused by Phase 9 inline dedup (Step 5)
- `lib/stats/event-emit.mjs` — single-source stats event emitter for autonomy-gate transitions and main-merge-gate (Step 6 + 12)
- `--gates {open|closed|adaptive}` flag on all four pipeline commands (Step 11). Controls how many autonomy checkpoints surface to the operator. Default `adaptive`.
- `hooks/scripts/post-compact-flush.mjs` — PostCompact hook re-injects session-state after context compaction so multi-session work survives a compaction boundary (Step 13)

### Added — hardenings + defense-in-depth

- `commands/ultraplan-local.md` Phase 8 schema-drift defense — post-generation `plan-validator --strict` run blocks plans containing narrative `Fase`/`Phase` headers or missing Manifest YAML; addresses the documented Opus-4.7 plan/list-emission drift (Step 7, builds on v1.8.0 fix in commit `9ecd669`)
- `commands/ultraplan-local.md` Phase 9 parallelization with inline dedup — single-message multi-Agent dispatch + plan-review-dedup helper (Step 8)
- `commands/ultraexecute-local.md` Phase 2.6 wave-executor — 11 sub-hardenings for plugin-in-monorepo + gitignored-state topology: GIT_OPTIONAL_LOCKS, --max-turns, --max-budget-usd, scoped --allowedTools, --append-system-prompt-file, SHARED_CONTEXT_FILE, SAFETY_PREAMBLE, deferred git push origin, push-before-cleanup ordering, GH #36071 awareness (Step 9)
- `templates/headless-launch-template.md` — mirrors Phase 2.6 hardenings so the headless launcher is consistent with Phase 2.6 prose (Step 10)
- `commands/ultraplan-local.md` + `agents/planning-orchestrator.md` Phase 8 main-merge gate — emit stats event for main-merge gate decisions (Step 12)

### Added — quality infrastructure

- `tests/lib/agent-frontmatter.test.mjs` — pins agent frontmatter invariants (Step 1-test)
- `tests/synthetic/plan-run-A.md` + `plan-run-B.md` + `plan-determinism.test.mjs` — SC7 plan-determinism floor (Jaccard ≥ 0.833) (Step 15)
- `tests/synthetic/review-run-A.md` + `review-run-B.md` + `review-determinism.test.mjs` — SC7 review-determinism floor (Jaccard ≥ 0.833) (Step 15)
- `tests/hooks/path-guard.test.mjs` — pins pre-write-executor BLOCK rules; regression detection if BLOCK_RULES are silently weakened (Step 18)
- `tests/hooks/bash-guard.test.mjs` — pins pre-bash-executor BLOCK rules (Step 18)
- `examples/01-add-verbose-flag/perf-measure.local.sh` (gitignored) — operator-driven SC1 wall-time measurement harness (Step 16)
- `examples/01-add-verbose-flag/perf-baseline.local.md` (gitignored) — SC1 gate template + measurement protocol (Step 16)

### Changed

- `lib/parsers/manifest-yaml.mjs` — schema extended additively to recognize `skip_commit_check` and `memory_write` flags (forward-compat: unknown keys ignored). Used by Step 14 and other steps that legitimately don't produce a git commit (Step 4)
- `.gitignore` — generalized `*.local.md` + `*.local.json` rules into a single `*.local.*` glob, covering `.local.sh` and any future `.local.<ext>` (Step 16)
- `package.json` — `version` 3.3.0 → 3.4.0
- `.claude-plugin/plugin.json` — `version` 3.3.0 → 3.4.0
- `README.md` + `CLAUDE.md` — version refs + `--gates` flag docs + Wave 1+2+3 architecture notes
- Marketplace root `README.md` — ultraplan-local version line bumped 3.3.0 → 3.4.0

### Memory updates (Step 14)

- `~/.claude/projects/-Users-ktg--claude-plugins-marketplaces-ktg-plugin-marketplace/memory/project_ultraplan_opus47_gap.md` — rewritten per Path B (memory truth gate). New body:
  (a) historical context referencing commit `9ecd669` (v1.8.0 fix, 2026-04-17),
  (b) empirical evidence (5 organic plans 2026-04-18 → 2026-05-01 all clean per research/04 D1),
  (c) defense-in-depth added in Step 7 (`commands/ultraplan-local.md` Phase 8),
  (d) residual risk surface for plugins NOT using ultraplan-local prompt arch.
- `~/.claude/projects/.../memory/MEMORY.md` — one-liner updated to flag mitigation status. The drift mechanism stays a known model-level risk; the plugin-level mitigation is documented.

These memory edits are recorded here because the files live outside the
repo and have no git checkpoint of their own.

### Architecture decision (Path B not Path C)

Brief offered three architectural options for the speedup work:

- Path A — cache-first (drop --allowedTools per child) — REJECTED. Inverts security model; plugin hooks don't fire reliably in `claude -p` (research/06 GH #36071).
- Path B — sequential `--no-ff` parallel waves with manifest-driven failure recovery — CHOSEN. v3.4.0 ships this.
- Path C — hybrid (cache-warm sentinel + identical-tool parallel) — DEFERRED to v3.5.0 contingent on cache-telemetry data harvested by Step 6's stats events. Requires unverified Q3 (CLAUDE_CODE_FORK_SUBAGENT cache-prefix preservation at 150-250K context).

### Tests

- 265 baseline (post-Wave-2) → ~290+ green after Wave 3 (Steps 15 + 18 add ~25 tests; doc-consistency may add a couple more pin tests)

### Open Questions for v1.1

- Real-LLM determinism measurement — synthetic floor (0.833) is anchored; the foreign-repo run against `examples/01-add-verbose-flag/` for SC1+SC4+SC5 measurement is a separate post-ship session.
- Cache-telemetry harvest — Step 6 stats events emit shapes useful for Path C decision; harvesting + analysis is v1.1 work.
- Marketplace-level autonomy-gate — currently per-plugin scope. Marketplace-wide policy + dashboards are out of scope for this solo project.

## [3.3.0] - 2026-05-01

Adds `/ultracontinue-local` — a zero-friction multi-session resumption command —
plus the contracted **Handover 7 (.session-state.local.json)** that any
session-end mechanism may write. Non-breaking: existing brief / research / plan /
execute / review pipelines are untouched. The state file is the contract;
`/ultracontinue` only reads.

### Added

- `/ultracontinue-local` command — read `.session-state.local.json` and immediately resume the next session in a multi-session ultraplan project (model: opus)
- `/ultraplan-end-session-local` helper — informal multi-session flows write the state file via this command (model: sonnet)
- `lib/validators/session-state-validator.mjs` — schema-v1 validator + CLI shim for `.session-state.local.json` (forward-compat: unknown top-level keys ignored)
- `lib/util/atomic-write.mjs` — `atomicWriteJson(path, obj)` extracted from `pre-compact-flush.mjs` for reuse
- `tests/fixtures/session-state/{valid-in-progress,malformed}.json` — synthetic fixtures
- Handover 7 (.session-state.local.json) — full schema documented in HANDOVER-CONTRACTS.md
- Doc-consistency pins: `Handover 7`, `session-state-validator` CLI shim, `/ultracontinue-local` in CLAUDE.md commands table
- ~22 new tests (163 baseline → 185 green; atomic-write + session-state-validator + doc-consistency pin extensions)

### Changed

- `commands/ultraexecute-local.md` — Phase 8 (canonical end-of-session), Phase 2.55 (pre-flight stop), Phase 4 (entry-condition stop) now write `.session-state.local.json` as a sibling to `progress.json` (Handover 7 producer)
- `hooks/scripts/pre-compact-flush.mjs` — also refreshes `.session-state.local.json` before context compaction (monotonic; never advances state to a non-resumable status)
- `.gitignore` — covers `*.local.json` (state files never enter git)

### Tests

- 163 baseline → 185 green (+22 new)

### Open Questions for v1.1

- graceful-handoff convergence: graceful-handoff v2.2 may dual-write `.session-state.local.json` so a single chat-end mechanism feeds `/ultracontinue`. v3.3.0 ships the contract; convergence is additive.
- `/continue` builtin Claude Code collision (unverified) — `/ultracontinue` prefix mitigates risk; monitor release notes.

## [3.2.0] - 2026-05-01

Adds `/ultrareview-local` as the fifth and final command in the ultra-suite —
independent post-hoc review of delivered code against the brief — and the
contracted **Handover 6 (review → plan)** feedback loop. Non-breaking: existing
brief/research/plan/execute pipelines are untouched.

### Added

- `/ultrareview-local` command — fifth and final command in ultra-suite (independent post-hoc review of delivered code against brief)
- `lib/validators/review-validator.mjs` — schema validator for new `type: ultrareview` artifact
- `lib/review/rule-catalogue.mjs` — 12 canonical rule keys (version-pinned)
- `lib/parsers/finding-id.mjs` — stable SHA1 finding-ID computation
- `lib/parsers/jaccard.mjs` — Jaccard similarity for determinism testing
- 4 new agents: review-orchestrator (opus inline ref), brief-conformance-reviewer, code-correctness-reviewer, review-coordinator (Judge Agent pattern)
- Handover 6 (review → plan) — contracted feedback loop documented in HANDOVER-CONTRACTS.md
- ~43 new tests (109 → ~152 baseline; rule-catalogue + finding-id + jaccard + review-validator + brief-validator extension + arg-parser extension + project-discovery extension + 4 doc-consistency pins + 3 review-determinism integration + 3 source-findings SC3(b) integration)

### Changed

- `brief-validator.mjs` accepts `type: ultrareview` in addition to `ultrabrief` (Handover 6 enabler)
- `/ultraplan-local` consumes `type: ultrareview` brief — extracts findings as plan goals + populates `source_findings` array in plan frontmatter
- `lib/parsers/project-discovery.mjs` discovers `review.md` and supports `'review'` phase
- `lib/parsers/arg-parser.mjs` adds `ultrareview` command to FLAG_SCHEMA
- `hooks/scripts/session-title.mjs` adds `/ultrareview-local` to COMMANDS map
- Severity vocabulary aligned with llm-security: `Critical | High | Medium | Low | Info` (rule-catalogue retains the 4-tier brief vocabulary; 5-tier migration is a v1.1 candidate)

### Tests

- 109 baseline → ~152 green (+43 new)

### Open Questions for v1.1

- Migrate 4-tier severity (BLOCKER/MAJOR/MINOR/SUGGESTION) → llm-security 5-tier (Critical/High/Medium/Low/Info) — research/02 advised but deferred to keep brief contract intact.
- Real-LLM determinism measurement (current SC4 test uses synthetic fixtures).
- SC2 end-to-end false-positive integration test (currently agent-prompt-level only).

## [3.1.0] - 2026-05-01

Quality program: pure quality lift, no scope creep. Built around the
fork-er onramp — anyone cloning this plugin should get value out of
the box. 109 zero-dep tests gate readiness.

### Added — testing & validation infrastructure (Spor 0+1)

- `package.json` with `node:test` runner and zero npm dependencies (`engines.node>=18`)
- `lib/util/{result,frontmatter}.mjs` — Result-shape helpers and a hand-rolled YAML subset parser supporting list-of-dicts (the form used by `must_contain` in real plans)
- `lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize}.mjs` — primitive parsers
- `lib/validators/{brief,research,plan,progress}-validator.mjs` and `lib/validators/architecture-discovery.mjs` — wrappers over parsers, each with a CLI shim (`if (import.meta.url === ...)`) so they can be invoked from Bash via `node ${CLAUDE_PLUGIN_ROOT}/lib/validators/X.mjs`
- `tests/lib/*` + `tests/validators/*` — 109 tests
- `tests/lib/doc-consistency.test.mjs` — pins agent-table count, command-table coverage, plan_version invariant, and settings.json scope cleanliness; first-red surfaces drift between docs and code

### Changed — wiring (Spor 1)

| Site | Was | Is |
|------|-----|-----|
| `/ultrabrief-local` Phase 4g | implicit trust | `node lib/validators/brief-validator.mjs --json` |
| `/ultraplan-local` Phase 1 | inline frontmatter parse + `test -f` | brief-validator `--soft` + research-validator `--dir` + architecture-discovery |
| `agents/planning-orchestrator.md` Phase 5.5 | three `grep -cE` calls | single `node lib/validators/plan-validator.mjs --strict --json` |
| `/ultraexecute-local` Phase 2.3 (`--validate`) | inline regex | `plan-validator --strict` + `progress-validator` |

Validators default to `strict: false`. Only `--validate` mode and Phase 5.5 use `--strict`. Existing in-flight projects under `.claude/projects/` continue to work.

### Added — handover contracts (Spor 2)

- `docs/HANDOVER-CONTRACTS.md` (~310 lines) — single source of truth for the 5 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume). Per-handover sections: Producer / Consumer / Path conventions / Frontmatter schema / Body invariants / Validation strategy / Versioning / Failure modes. Architecture handover is explicitly an external contract — drift-WARN never drift-FAIL.

### Added — PreCompact resume integrity (Spor 2, P0 fix)

- `hooks/scripts/pre-compact-flush.mjs` — PreCompact-event hook (CC v2.1.105+) that reconciles `progress.json` with git history before context compaction. Atomic write (tmp + rename), monotonic only (current_step never decreases), fail-open (always exit 0). Closes the documented progress.json drift bug from `docs/ultraexecute-v2-observations-from-config-audit-v4.md` — `--resume` now works after long conversations.
- `hooks/hooks.json` registers the PreCompact entry.

### Added — examples (Spor 3)

- `examples/01-add-verbose-flag/` — calibrated end-to-end pipeline demo for a small realistic task (add `--verbose` to a CLI parser). Includes `brief.md`, `research/01-cli-parser-conventions.md`, `plan.md` (7 steps with full manifest YAML), and `progress.json`. All four artifacts pass their respective validators. Hand-calibrated, not LLM-generated, so the example stays reviewable.
- `examples/REGENERATED.md` per example documents calibration date and regeneration triggers.
- `examples/README.md` walks fork-ers through what to study first.

### Changed — plan-critic semantic rubric (Spor 3, P0 fix)

`agents/plan-critic.md` rule #7 split into two parts:

1. **Literal blockers** (exact-string): `TBD`, `TODO`, `FIXME`, `XXX` always fire.
2. **Semantic rubric** (instruction-shaped): 8 deferred-decision tests covering vague modifiers, imperatives without targets, forward references without expansion, volume/quality without spec, edge-cases delegated, production-readiness delegated, path mismatch, and over-stuffed steps.

Calibrated against 5-phrase corpus the v3.0 exact-string blacklist missed: "implement as needed", "wire it up", "make it production-ready", "add tests where appropriate", "handle edge cases" — all five now flagged with rule citations.

### Added — CC v2.1.x feature adoption (Spor 3)

- **F8** — `MCP_CONNECTION_NONBLOCKING=true` documented under "Headless multi-session tuning" in README (CC v2.1.89+) for parallel `claude -p` sessions
- **F9** — `hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `ultra:<command>:<slug>` titles for ultra invocations
- **F3** — `hooks/scripts/post-bash-stats.mjs` (PostToolUse, CC v2.1.97+) appends `duration_ms` per Bash call to `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`
- **F12** — `disableSkillShellExecution: true` recommended in README "Security hardening" + `SECURITY.md` (CC v2.1.91+) for fork-ers handling untrusted plans

**Deferred:** F2 (hook `if`-field scoping). The plan called for scoping pre-bash-executor / pre-write-executor to ultraexecute sessions to "reduce false-positives in brief/plan" — but brief/plan don't issue Bash commands that match the destructive denylist, so the rationale doesn't hold. Universal protection wins.

### Added — security & extension docs (Spor 3)

- `SECURITY.md` — Forgejo private-issue reporting, supported = current minor only, scope (4 hooks + denylist), hardening recommendations
- `docs/architect-bridge-test.md` — manual smoke checklist for the ultraplan ↔ ultra-cc-architect bridge (1 paragraph, intentionally not CI)
- `README.md` — new "Extending the plugin" section: how to add an agent, switch the planning model, disable external research, find the data contract, disable the architect bridge

### Removed — vestigial config (Spor 0)

- `settings.json` `exploration` and `agentTeam` blocks (read by zero code; verified via grep before deletion)
- `docs/ultra-suite-brief_2.md` archived as `_archive-` (was paste from another plugin's work)

### Tests

109 tests, all green. `npm test` is the fork-readiness gate.

### Hook table (after v3.1.0)

| Hook | Event | CC version | Purpose |
|------|-------|-----------|---------|
| pre-bash-executor.mjs | PreToolUse(Bash) | 2.0+ | Block destructive shell commands |
| pre-write-executor.mjs | PreToolUse(Write) | 2.0+ | Block writes to sensitive paths |
| session-title.mjs | UserPromptSubmit | 2.1.94+ | Set `ultra:<cmd>:<slug>` titles |
| post-bash-stats.mjs | PostToolUse(Bash) | 2.1.97+ | Log Bash `duration_ms` to JSONL |
| pre-compact-flush.mjs | PreCompact | 2.1.105+ | Reconcile progress.json with git history |

### Files changed

This release is plugin-internal — no breaking changes to artifact formats or CLI surface. Forkers should `npm test` after pulling to confirm readiness.

## [3.0.0] - 2026-04-30

_Note (2026-05-04): the ultra-cc-architect plugin is no longer publicly distributed. The architecture/overview.md filesystem contract remains supported but no public producer ships._

### Architect extracted to its own plugin

The `/ultra-cc-architect-local` and `/ultra-skill-author-local` commands, all
seven of their agents, the `cc-architect-catalog` skill, the `ngram-overlap.mjs`
script, and the skill-factory test fixtures moved out of `ultraplan-local` and
into the new `ultra-cc-architect` plugin (v0.1.0).

### Why

`ultraplan-local` had drifted into containing two distinct domains:

1. A **universal planning pipeline** (brief → research → plan → execute) that
   is technology-agnostic and works for any implementation task.
2. A **Claude-Code-specific architecture phase** that only makes sense when
   building features for Claude Code itself.

Keeping them in one plugin caused three problems:

- Users who wanted only the planning pipeline had to clone an unfinished
  CC-feature catalog and seven architect/skill-author agents they would
  never invoke.
- The architect catalog (~11 seed skills) and the planning pipeline lived on
  different release cadences. Architect work blocked pipeline development
  and vice-versa.
- New users saw six commands when only four belonged to the core flow.

The architect was already marked `optional, v2.2` and was fully decoupled at
the code level — only one filesystem touchpoint remained: `/ultraplan-local`
auto-discovers `architecture/overview.md` if present, and gracefully handles
its absence. The split is therefore non-breaking for the planning flow.

### What moved to `ultra-cc-architect`

- **Commands:** `/ultra-cc-architect-local`, `/ultra-skill-author-local`
- **Agents:** `architect-orchestrator`, `feature-matcher`, `gap-identifier`,
  `architecture-critic`, `skill-author-orchestrator`, `concept-extractor`,
  `skill-drafter`, `ip-hygiene-checker`
- **Skills:** `skills/cc-architect-catalog/` (13 files)
- **Scripts:** `scripts/ngram-overlap.mjs`, `scripts/ngram-overlap.test.mjs`
- **Test fixtures:** `tests/fixtures/skill-factory/`,
  `tests/fixtures/skill-drafter/`

All moves used `git mv`, so history follows the files into the new plugin.

### What stayed unchanged in ultraplan-local

- `/ultraplan-local` Phase 1 still auto-discovers `architecture/overview.md`.
  The discovery is filesystem-based, not plugin-based — installing both
  plugins gives you the full pipeline (brief → research → architect → plan
  → execute).
- `agents/planning-orchestrator.md` retains its architecture-note
  cross-reference.
- All other commands (`/ultrabrief-local`, `/ultraresearch-local`,
  `/ultraexecute-local`) are untouched.

### Migration

If you only used `/ultrabrief-local`, `/ultraresearch-local`,
`/ultraplan-local`, and `/ultraexecute-local`: no action needed. Update the
plugin and continue.

If you used `/ultra-cc-architect-local` or `/ultra-skill-author-local`:
install the new plugin alongside this one. In `~/.claude/settings.json`:

```json
{
  "enabledPlugins": {
    "ultraplan-local@ktg-plugin-marketplace": true,
    "ultra-cc-architect@ktg-plugin-marketplace": true
  }
}
```

Custom seed skills you added to `cc-architect-catalog/` follow with the
catalog. Use `git log --follow` if you need to track them in the new
location.

### plugin.json changes

- `version`: `2.4.0` → `3.0.0`
- `description`: now describes a four-command pipeline; CC-feature matching
  is described as living in the separate `ultra-cc-architect` plugin
- `keywords`: removed `cc-architecture`

## [2.4.0] - 2026-04-19

### Breaking change — background mode removed

Default mode for `/ultraplan-local`, `/ultraresearch-local`,
`/ultra-cc-architect-local`, and auto-mode in `/ultrabrief-local` is now
foreground. The command blocks the session until the brief/plan is ready.

### Why

Background mode promised a swarm of specialized agents (docs-researcher,
community-researcher, architecture-mapper, plan-critic, feature-matcher,
gap-identifier, …) spawned by a background orchestrator. It did not work:
the Claude Code harness does not expose the Agent tool to sub-agents
(including ones run with `run_in_background: true`). The orchestrator
silently degraded to inline reasoning in a single Opus context, without
WebSearch, Tavily, WebFetch, or Gemini. Briefs were tagged "high confidence"
but were built on guesses from training data.

Source: github.com/anthropics/claude-code/issues/19077

Empirically confirmed in a plugin investigation on 2026-04-19: a probe
sub-agent reported its exposed tools as `Bash, Edit, Glob, Grep, Read,
Skill, ToolSearch, Write`. The Agent tool was not present, active or
deferred. Foreground execution from the main context spawns sub-agents
correctly (docs-researcher with Tavily intact).

### What changes

- Default execution: foreground for all four commands.
- `--fg` flag is preserved as a no-op alias (backward compatibility).
- Orchestrator agent files (`agents/research-orchestrator.md`,
  `agents/planning-orchestrator.md`, `agents/architect-orchestrator.md`)
  are redefined from "background executor" to "inline reference" — the
  command markdown itself runs the phases in the main context where the
  Agent tool is available.
- `ultrabrief-local` auto-mode now runs research sequentially inline
  instead of parallel background. The ANTHROPIC_API_KEY billing check
  is removed (irrelevant for foreground runs on subscription).
- `skills/cc-architect-catalog/background-agents-reference.md` has been
  corrected: Shape A (orchestrator handoff) is now documented as an
  anti-pattern, nested spawn from a sub-agent is NOT SUPPORTED.

### For headless/long-running runs

Use `claude -p` in a separate terminal window. Each headless session has
its own main context with the Agent tool, so the swarm works correctly.

### Migration

No code changes required for users. Scripts or documentation that assume
background execution must be updated — the commands now block until done.

## [2.3.2] - 2026-04-18

### Fixed — skill-drafter slug-collision hint

`skill-drafter` now checks for an existing file at
`{catalog_root}/<slug>.md` before writing its draft to `.drafts/`.
When a collision is detected, the agent prepends a warning block to
its confirmation output showing the overwrite risk and a suggested
qualified slug derived from the concept handle. The draft is still
written to `.drafts/<slug>.md` — the check is a hint, not a block.

**Why.** v2.3.0 dogfood surfaced the risk (logged as
`post_dogfood_findings[0]` in that run's `progress.json`): when the
drafter produced `.drafts/hooks-pattern.md` with an existing approved
`hooks-pattern.md` seed present at the catalog root, the pipeline
gave no signal that manual `mv` during promotion would silently
overwrite the seed. The v2.3.1 qualified-slug convention gave us the
mechanism to resolve collisions, but `skill-drafter` still didn't
surface them at the right moment — before promotion, not after.

**Changes.**

- `agents/skill-drafter.md` — new Step 2 "Check for slug collision at
  the catalog root" between slug computation (Step 1) and reading the
  source (Step 3). Subsequent workflow steps renumbered 3→7. New
  "Suggesting a qualifier" guidance derives a kebab-case qualifier
  from the `concept` field (or source basename as fallback). Output
  format gains a `Collision:` field (`none | approved | pending |
  auto-merged | soft`) and an optional warning block when the
  collision is non-none. New Hard Rule "Slug-collision pre-write
  check".
- `tests/fixtures/skill-drafter/slug-collision-expected.md` — new
  reference fixture documenting the expected confirmation-output
  shape across four scenarios (no collision, approved collision,
  soft pending collision, collision with no good qualifier).
  Skill-drafter is prompt-driven and not auto-tested; the fixture
  anchors the shape for human verification and downstream parsers.

**Non-breaking.** No changes to `.drafts/` layout, frontmatter
contract, tool scope, or filename regex. Existing pipelines see an
extra field (`Collision:`) and an optional warning block — both
purely additive. No version-gated changes in
`skill-author-orchestrator` or `ip-hygiene-checker`.

## [2.3.1] - 2026-04-18

### Added — Qualified slug convention for cc-architect-catalog

Catalog files now follow `<cc_feature>[-<qualifier>]-<layer>.md`. The
unqualified slug (e.g., `hooks-pattern.md`) remains the canonical
baseline for a `(feature, layer)` pair. Qualified slugs (e.g.,
`hooks-observability-pattern.md`) cover specific sub-patterns without
displacing the baseline.

**Why.** v2.3.0 dogfood surfaced a design gap: the skill-factory
produced a draft `hooks-pattern.md` from a specialized source (progressive-
alert observability) that collided with the existing generic `hooks-pattern.md`
seed. Promoting would have replaced the general pattern with a narrow
one; discarding would have lost real catalog growth. Qualified slugs
resolve this by letting one feature host multiple named patterns at
different abstraction levels.

**Changes.**

- `skills/cc-architect-catalog/SKILL.md` — slug convention section added;
  coverage table gains "qualified patterns" column; matcher logic
  documented for N patterns per feature; modification rules cover
  qualified-vs-canonical choice and slug-collision handling.
- `agents/feature-matcher.md` — catalog map is now
  `cc_feature → {layer → [skills]}`; new "Selecting among multiple
  patterns per feature" section (baseline by default, qualified when
  justified, multiple when non-overlapping, never purely cosmetic);
  `supporting_skill` accepts one-or-more skill names.
- `agents/gap-identifier.md` — adds `pattern_count[cc_feature]` signal
  to the catalog coverage audit.
- `agents/architecture-critic.md` — adds supporting-skill verification:
  every cited skill name must exist in the catalog; blocker severity.
- First qualified skill: `hooks-observability-pattern.md` (promoted from
  `.drafts/`, sourced from `ai-psychosis/README.md`, ngram-overlap 0.01,
  review_status approved).

**Non-breaking.** Existing unqualified slugs keep working. No changes to
`cc_feature` taxonomy. Hallucination gate unchanged (still validates
against `cc_feature` values, not slugs).

## [2.3.0] - 2026-04-18

### Added — Skill-factory Fase 1 MVP (`/ultra-skill-author-local`)

Manual one-skill-at-a-time generator for the `cc-architect-catalog`.
Channel 2 of the skill-factory strategy: a curated local source enters,
one draft skill exits in `skills/cc-architect-catalog/.drafts/`, with
n-gram containment scored against the source and stamped into the
draft frontmatter (or the draft is deleted when overlap is too high).

**Why now.** `/ultra-cc-architect-local` (v2.2.0) enforces a
hallucination gate that only permits feature proposals backed by the
catalog. With 10 seed skills covering 8 features × 2 layers, the
`feature-matcher` rarely finds a match and silently produces empty
proposals. Fase 1 unblocks catalog growth without spinning up
automation: one source, one draft, manual review, manual `mv` for
promotion.

**Pipeline.** Sequential, no retry, no parallelism:

```
/ultra-skill-author-local <source>
  → concept-extractor (sonnet, JSON output, gap-class C/D + cc_feature gate)
  → skill-drafter (sonnet, .drafts/<slug>.md with 9-field frontmatter)
  → ip-hygiene-checker (sonnet, runs scripts/ngram-overlap.mjs)
      verdict accepted/needs-review → stamp ngram_overlap_score
      verdict rejected               → rm draft (no preservation)
```

**IP-hygiene utility.** Pure Node stdlib. Word-5-gram containment
similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-
run secondary signal. Verdict bands: accepted (<0.15 AND <8),
needs-review (mid), rejected (≥0.35 OR ≥15). Short-text fallback to
n=4 when min(words) <500. CLI emits JSON.

**Calibration fixtures.** Three source/draft pairs in
`tests/fixtures/skill-factory/` pin the verdict bands against
representative prose: accepted (containment 0.014), needs-review
(0.211), rejected (0.676). Re-verify any threshold change against
these fixtures.

**New files:**

- `commands/ultra-skill-author-local.md`
- `agents/skill-author-orchestrator.md` (opus)
- `agents/concept-extractor.md` (sonnet)
- `agents/skill-drafter.md` (sonnet)
- `agents/ip-hygiene-checker.md` (sonnet)
- `scripts/ngram-overlap.mjs` + `scripts/ngram-overlap.test.mjs`
- `skills/cc-architect-catalog/.drafts/.gitkeep`
- `tests/fixtures/skill-factory/{source,draft}-{accepted,needs-review,rejected}.md`
- `tests/fixtures/skill-factory/README.md`

**Non-goals (explicit, Fase 1):**

- No automation, cron, or watcher
- No CC changelog diffing or auto-research
- No batch processing or review command
- No decision-layer skills (cross-feature comparison is Fase 2+)
- No URL or remote sources — local files only
- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism

**New stats file:**
`${CLAUDE_PLUGIN_DATA}/ultra-skill-author-local-stats.jsonl`.

## [2.2.0] - 2026-04-18

### Added — `/ultra-cc-architect-local` optional pipeline step

New optional command that sits between `/ultraresearch-local` and
`/ultraplan-local`. Reads the task brief plus any research briefs, matches the
task against available Claude Code features (Hooks, Subagents, Skills, Output
Styles, MCP, Plan Mode, Worktrees, Background Agents), and produces an
**architecture note** with brief-anchored rationale and an explicit coverage-
gap section.

Pipeline position (5-steg):

```
/ultrabrief-local → /ultraresearch-local → /ultra-cc-architect-local (optional)
                                         → /ultraplan-local → /ultraexecute-local
```

The architecture note is designed as *priors* for planning, not mandates —
`/ultraplan-local` still runs its own exploration and may override proposals
with evidence.

**New files:**

- `commands/ultra-cc-architect-local.md` — command entry point (7 faser:
  parse → background → read inputs → feature matching → synthesize → review
  → present).
- `agents/architect-orchestrator.md` (opus) — background orchestrator.
- `agents/feature-matcher.md` (sonnet) — matches CC features against brief +
  research, with brief-anchored rationale per feature and a documented fallback
  minimum list when the catalog is empty.
- `agents/gap-identifier.md` (sonnet) — emits issue-ready gap drafts (no
  auto-posting; no auto-generation).
- `agents/architecture-critic.md` (sonnet) — adversarial review with a
  hallucination gate (features outside catalog + fallback list → blocker).
- `skills/cc-architect-catalog/SKILL.md` — manifest + frontmatter contract.
- 10 seed skills in `skills/cc-architect-catalog/`:
  `hooks-reference`, `hooks-pattern`, `subagents-reference`, `subagents-pattern`,
  `skills-reference`, `output-styles-reference`, `mcp-reference`,
  `plan-mode-reference`, `worktrees-reference`, `background-agents-reference`.
  All handwritten (no third-party content copied, per brief §4.4).

**New flags:**

- `--project <dir>` (required) — reads `{dir}/brief.md` + `{dir}/research/*.md`,
  writes to `{dir}/architecture/`.
- `--fg` — foreground execution.
- `--quick` — skip adversarial review.
- `--no-gaps` — do not write `gaps.md` (gap-section remains inside
  `overview.md`).

**New stats file:** `${CLAUDE_PLUGIN_DATA}/ultra-cc-architect-local-stats.jsonl`.

### Changed — `/ultraplan-local` auto-discovers architecture notes

Brief §5 of the `ultra-cc-architect` design said "no changes to existing
commands". This release makes one permitted, documented exception:
`/ultraplan-local` now auto-discovers `{project_dir}/architecture/overview.md`
when running in project mode. The file is additive context — missing file
produces no error, and behavior when the file is absent is identical to
v2.1.0. Non-breaking.

**Minimal edits:**

- `commands/ultraplan-local.md` — Phase 1 `--project` branch sets
  `has_architecture_note` / `architecture_note_path` when the file exists.
  Phase 3 launch prompt passes `Architecture note: {path or "none"}` to the
  orchestrator.
- `agents/planning-orchestrator.md` — Input section documents the new
  optional field. Phase 4 synthesis cross-references proposed features with
  exploration findings and carries the note's Coverage gaps into Risks and
  Mitigations when relevant.

### Non-goals (explicit)

- **Skill-factory is not part of this release.** Cataloging, n-gram
  computation, auto-generation from CC changelog, concept extraction from
  reference repos — all deferred to a separate development process. Together
  with v2.2.0's architect command, that process will eventually land as v3.0.
- No `/ultra-auto` chaining.
- No auto-creation of Forgejo/GitHub issues from gap drafts.
- No changes to `/ultrabrief-local`, `/ultraresearch-local`, or
  `/ultraexecute-local`.

## [2.1.0] - 2026-04-18

### Changed — Dynamic, quality-gated interview in `/ultrabrief-local`

The Phase 3 interview is no longer a hardcoded Q1–Q8 list with a numeric
cap (3–4 questions in `--quick`, 5–8 in default). It is now a
**section-driven completeness loop**: the command maintains per-section
state (Intent, Goal, Success Criteria, Research Plan, and five optional
sections), picks the next question from the section with the weakest
signal, and keeps probing until all four required sections meet an
initial-signal gate. Quality drives the loop, not a counter.

Phase 4 adds a **draft → brief-reviewer → revise** loop. The brief is
drafted in memory, written to `brief.md.draft`, reviewed by the
`brief-reviewer` agent as a stop-gate, and only renamed to `brief.md`
after all five dimensions pass (`completeness/consistency/testability/
scope_clarity ≥ 4` and `research_plan == 5`). If the gate fails, a
targeted follow-up is generated from the weakest dimension's detail
field and the draft is re-reviewed. The loop is capped at 3 review
iterations to bound cost; exhaustion writes the brief with
`brief_quality: partial` and an explicit `## Brief Quality` section.

Force-stop path: when the user says "stop" during Phase 4, the current
review findings are surfaced with per-dimension scores before asking
whether to continue or accept a partial brief. No silent exits.

Not breaking. The `/ultrabrief-local [--quick] <task>` interface is
unchanged from the outside; only internals change. `--quick` now means
"start compact, escalate if gates fail" rather than "max 4 questions".

### Added

- **JSON output from `brief-reviewer`** — the agent now emits a final
  fenced `json` block with per-dimension `score` (1–5) and `detail`
  arrays (`gaps`, `issues`, `weak_criteria`, `unclear_sections`,
  `invalid_topics`) alongside the existing prose report. The JSON block
  is mandatory; empty arrays and `score: 5` are required when a
  dimension passes cleanly. `planning-orchestrator` continues to use
  the prose verdict unchanged.
- **`brief_quality` frontmatter field** on task briefs — `complete`
  (default) when the Phase 4 gate passed, or `partial` when the
  iteration cap was hit or the user force-stopped with known issues.
  `planning-orchestrator` can inspect this to decide how heavily to
  weight brief sections as assumptions.
- **`review_iterations` and `brief_quality` in ultrabrief-stats** —
  recorded per run for telemetry.

### Changed

- Hard rule added: `/ultrabrief-local` never writes `brief.md` while the
  review gate is pending. The draft lives in `brief.md.draft` until the
  loop terminates.
- Hard rule added: no hard cap on Phase 3 questions; the brief-review
  gate is the only loop bound (3-iteration cap) and is in Phase 4.

## [2.0.0] - 2026-04-18

### Breaking — Four-command pipeline with dedicated brief step

v2.0.0 introduces `/ultrabrief-local` as a first-class step in the pipeline.
The interview previously embedded inside `/ultraplan-local` has been extracted
into a dedicated command that produces a structured **task brief** — the
contract between user intent and planning. `/ultraplan-local` now requires
a brief as input and no longer conducts interviews.

All artifacts converge into one **project directory**:
`.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`,
`plan.md`, `sessions/`, and `progress.json`. `--project <dir>` works across
`/ultraresearch-local`, `/ultraplan-local`, and `/ultraexecute-local`.

See [MIGRATION.md](MIGRATION.md) for v1 → v2 upgrade guide.

### Breaking changes

- **`/ultraplan-local` requires `--brief <path>` or `--project <dir>`.** Running
  without either exits with an error and a pointer to `/ultrabrief-local`.
- **`/ultraplan-local --spec <path>` is removed.** Convert specs to briefs by
  adding `## Intent` and `## Research Plan` sections (see MIGRATION.md).
- **Interview inside `/ultraplan-local` is removed.** Planning no longer asks
  questions — all intent must be captured in the brief upstream.
- **`spec-reviewer` agent renamed to `brief-reviewer`** with a new 5th dimension
  (Research Plan validity). Old spec-reviewer file is deleted.

### Added

- **`/ultrabrief-local` command** — interactive interview (3-8 questions with
  adaptive depth) that produces a task brief with explicit research plan.
  Features: project directory creation, research topic identification with
  copy-paste-ready `/ultraresearch-local` commands, optional auto-orchestration
  (Claude runs research + plan in foreground), and stats tracking.
- **`templates/ultrabrief-template.md`** — canonical task brief format with
  `## Intent`, `## Goal`, `## Non-Goals`, `## Constraints / Preferences / NFRs`,
  `## Success Criteria`, `## Research Plan` (N topics with research_question,
  scope, confidence, cost), and `## Open Questions / Assumptions`.
- **`brief-reviewer` agent** — renamed from spec-reviewer with a new
  5th dimension: Research Plan validity (each topic has a valid
  research question ending in `?`, has `Required for plan steps:` and
  `Confidence needed:`, and research files exist when `auto_research: true`).
- **`--project <dir>` flag** on `/ultraresearch-local`, `/ultraplan-local`,
  and `/ultraexecute-local`. Single directory holds the full pipeline's
  artifacts. `/ultraresearch-local --project` auto-increments
  `{dir}/research/NN-slug.md`.
- **Two-kinds-of-briefs terminology** documented across README and CLAUDE.md:
  "task brief" (from `/ultrabrief-local`) vs "research brief" (from
  `/ultraresearch-local`). Prefix used consistently in agent prompts and docs.
- **MIGRATION.md** — step-by-step guide for upgrading v1 projects to v2.

### Changed

- **`planning-orchestrator`** now accepts `Brief file:` input instead of
  `Spec file:`. Intent→Context mapping: brief's `## Intent` + `## Goal` feed
  the plan's Context section directly (structured, no inference needed).
  Phase 1b now uses `brief-reviewer` instead of `spec-reviewer`. With
  `Project dir:` in input, writes plan to `{dir}/plan.md`.
- **`/ultraresearch-local`** supports `--project <dir>` with auto-indexed
  output path (`{dir}/research/NN-slug.md`, where NN is the next available
  two-digit index).
- **`/ultraexecute-local`** supports `--project <dir>`. Reads `{dir}/plan.md`,
  writes progress to `{dir}/progress.json`.
- **plugin.json** description rewritten to reflect four-command pipeline.

### Removed

- `/ultraplan-local --spec <path>` flag. Spec files are not a valid input for
  v2.0+. Convert to brief via `/ultrabrief-local` or manual conversion (see
  MIGRATION.md).
- Interview Phase in `/ultraplan-local` (was Phase 2). Use `/ultrabrief-local`
  to conduct the interview upstream.
- `agents/spec-reviewer.md` file. Replaced by `agents/brief-reviewer.md`.

### Rationale

The v1.x interview inside `/ultraplan-local` conflated two concerns: capturing
intent and producing an executable plan. Briefs and plans have different
lifecycles — a brief should be reviewable and editable before any research or
planning starts, because every downstream decision traces back to it. Extracting
the brief into its own command makes the pipeline more honest: the brief is the
source of truth for *what we want*, research briefs are sources of truth for
*what we learned*, and the plan is the contract for *how we'll do it*. Separating
these makes each artifact reviewable on its own terms and enables deterministic
re-planning from the same brief when research reveals new constraints.

The explicit `## Research Plan` section in briefs closes a common gap: plans
were implicitly assuming knowledge that neither the user nor Claude had verified.
Research topics are now declared upfront, scoped, and traceable back to plan
decisions.

## [1.8.0] - 2026-04-17

### Opus 4.7 prompt literalism — closing the schema-drift gap

Opus 4.7 reads agent instructions more literally than 4.6 (per 4.7 system
card §6.3.1.1). The v1.7 planning-orchestrator described the Step+Manifest
schema via prose + procedural rules ("read the template"), which 4.6
inferred correctly but 4.7 sometimes rendered as narrative "Fase N" prose.
The result: plans that executed cleanly on 4.6 were rejected by
ultraexecute Phase 2 parsing on 4.7 — first observed during v6.2.0 planning
for `llm-security`. v1.8.0 closes the gap by replacing prose rules with a
literal copyable template, explicit forbidden-format clauses, and a
pre-handoff schema self-check.

### Added

- **Inline literal Step+Manifest template** in `planning-orchestrator`
  Phase 5 — a complete, copyable example (JWT middleware step) replaces
  "read the template" prose. Removes ambiguity about heading format,
  field order, and manifest YAML structure.
- **Forbidden heading-format clause** in Phase 5 — explicit denylist for
  `## Fase N`, `### Phase N`, `### Stage N`, and other narrative formats
  the executor cannot parse. Negative constraints land harder on 4.7.
- **Phase 5.5 schema self-check** in `planning-orchestrator` — after
  writing the plan, grep-verify canonical `### Step N:` count matches
  `manifest:` count, and narrative heading count is zero. Rewrite plan
  if self-check fails, before handing to plan-critic.
- **`--validate` mode** in `ultraexecute-local` — schema-only check that
  parses steps and manifests, reports `READY | FAIL` with specific
  error hints, and exits without security scan or execution. Intended
  as a fast sanity-check between `/ultraplan-local` and full execution:
  ```bash
  /ultraplan-local "task"
  /ultraexecute-local --validate <plan>.md   # READY or actionable FAIL
  /ultraexecute-local <plan>.md              # full execution
  ```

### Changed

- `planning-orchestrator` Phase 5 now embeds the canonical Step template
  inline (~60 lines of literal example) rather than referring to
  `templates/plan-template.md`. Template file remains authoritative for
  cross-referencing but is no longer load-bearing for plan generation.
- `ultraexecute-local` Phase 2.3 added as a hard exit point for
  `--validate` mode; Phase 2.4 security scan explicitly skips this mode.

### Rationale

v1.7.0's self-verifying chain assumed the orchestrator reliably produces
the v1.7 schema. That held on 4.6. v1.8.0 makes the assumption robust to
4.7-style literal interpretation by moving from "describe the format" to
"show the exact format and forbid alternatives", plus a self-check loop
before human-visible output. Pairs with `--validate` as a user-facing
verification step that catches any residual drift before execution side
effects begin.

## [1.7.0] - 2026-04-12

### The self-verifying plan chain

Wave 1 of a parallel 6-session build revealed three failure modes: (1) a
session reported `status=completed` after only 2/5 steps — last tool call
was an arbitrary file review, not a completion check; (2) 3/6 sessions
had push blocked inside the sub-agent bash sandbox *after* all work was
done; (3) plans and blueprints were prose, so the orchestrator had no
machine-readable way to verify completion. v1.7.0 closes all three by
making the plan itself an executable contract.

### Added

- **Per-step verification manifest** in plan format (`plan_version: 1.7`).
  Every step now ends with a YAML `manifest:` block declaring
  `expected_paths`, `min_file_count`, `commit_message_pattern`,
  `bash_syntax_check`, `forbidden_paths`, `must_contain`. The manifest is
  the objective completion predicate — the Verify command is necessary but
  not sufficient.
- **Plan-critic dimension 10 — Manifest quality (hard gate).** Missing
  or invalid manifest (unparseable regex, path contradiction, missing
  block) is a `major` finding. v1.6 plans get a legacy-mode warning
  instead of a block.
- **Session Manifest aggregate** in session specs — synthesized by
  `session-decomposer` as the union of per-step manifests. Gives
  `ultraexecute-local` a single YAML block per session to audit against.
- **Step 0: Sandbox pre-flight** — obligatory first step in every
  generated session spec. Runs `git push --dry-run origin HEAD`; exit 77
  = sandbox cannot push, session status becomes `blocked` (not `failed`),
  no real work attempted. Escape hatch: `ULTRAEXECUTE_SKIP_PREFLIGHT=1`.
- **Launch script pre-flight** — `headless-launch-template.md` adds a
  `git push --dry-run` check outside the sandbox, before any session
  spawns, catching credential issues at the earliest possible point.
- **Phase 7.5 — Manifest audit (independent).** After all steps complete,
  `ultraexecute-local` re-verifies expected paths, commit count, commit
  message patterns, bash syntax, and forbidden-path untouched-ness from
  git log and filesystem. Agent's own bookkeeping is ignored. Disagreement
  with progress file → status overridden to `partial`.
- **Phase 7.6 — Recovery dispatch (bounded).** When Phase 7.5 detects
  drift in multi-session parent context, synthesize a temp session spec
  containing only missing steps and dispatch via existing
  `claude -p "/ultraexecute-local --session N"`. `recovery_depth ≤ 2`
  hard cap — third drift escalates to user.
- **Hard Rule 17: Manifest is the completion predicate.** A step may
  not be marked passed if its manifest does not verify, regardless of
  Verify's exit code.
- **Hard Rule 18: Last-activity rule.** Executor's final tool call
  before Phase 8 must be a manifest check, never an arbitrary file
  review. Prevents hallucinated completion.

### Changed

- **Plan template (`templates/plan-template.md`)** — adds
  `plan_version: 1.7` metadata line, `Manifest:` field on every step,
  "Manifest — objective completion predicate" section.
- **Plan-critic scoring** rebalanced: Headless readiness 0.15 → 0.10,
  Manifest quality 0.05 added. Legacy v1.6 plans skip the Manifest
  dimension and keep Headless readiness at 0.15.
- **Planning-orchestrator Phase 5** adds "Manifest generation rules
  (REQUIRED for every step)" with mechanical derivation from `Files:`
  and Checkpoint. Validates regex compilation and path existence before
  handoff to plan-critic.
- **Session-decomposer** parses plan manifests and propagates them
  verbatim into session specs. For v1.7+ plans with missing manifests:
  abort with pointer to failing step. For legacy v1.6 plans: synthesize
  minimal manifests and flag `legacy_synthesis: true`.
- **ultraexecute-local Phase 2** parses manifest YAML. Ugyldig YAML =
  abort with pointer to step. v<1.7 plans: synthesize + log
  `legacy_plan: true`.
- **ultraexecute-local Phase 6** — sub-step D renamed to D1 "Command
  verification"; new D2 "Manifest verification" runs after D1 with 5
  checks. F "Checkpoint" adds `checkpoint_drift` logging when HEAD
  message doesn't match `commit_message_pattern` (non-fatal).
- **Phase 8 report** — table gets Manifest column; JSON summary adds
  `plan_version`, `manifest_audit`, `drift_details`, `recovery_dispatched`,
  `recovery_depth`, `legacy_plan`. Result vocabulary strict:
  `completed | partial | blocked | failed | stopped`.
- **Division of labor clarified** in README — `/ultraresearch-local`
  gathers context (no decisions), `/ultraplan-local` transforms intent
  into an executable contract (manifests, plan-critic gate),
  `/ultraexecute-local` executes the contract disciplined (does NOT
  compensate for weak plans — escalates).

## [1.6.0] - 2026-04-08

### Added

- **`/ultraresearch-local` command** — deep research combining local codebase analysis
  with external knowledge. Produces structured research briefs with triangulation,
  confidence ratings, and source quality assessment. Supports modes: default (background),
  `--quick` (inline), `--local` (codebase only), `--external` (web only), `--fg` (foreground).
- **6 new agents** for the research pipeline:
  - `research-orchestrator` (opus) — runs full research pipeline as background task
  - `docs-researcher` (sonnet) — official documentation via Tavily, WebSearch, Microsoft Learn
  - `community-researcher` (sonnet) — real-world experience from issues, blogs, discussions
  - `security-researcher` (sonnet) — CVEs, audit history, supply chain risks
  - `contrarian-researcher` (sonnet) — counter-evidence and overlooked alternatives
  - `gemini-bridge` (sonnet) — independent second opinion via Gemini Deep Research MCP
- **Research brief template** (`templates/research-brief-template.md`) — structured format
  with dimensions, confidence ratings, triangulation, and source quality assessment.
- **`--research` flag for `/ultraplan-local`** — accepts up to 3 research brief paths.
  Enriches the interview (focuses on decisions, not facts) and injects brief context into
  exploration agents. Research-scout skips already-covered technologies.
- **Research-aware planning orchestrator** — `planning-orchestrator.md` now accepts research
  briefs, injects summaries into sub-agent prompts, and cross-references brief findings
  during synthesis.
- **Research settings** in `settings.json` — configurable Gemini bridge (enabled/timeout),
  interview depth, dimension limits, and stats tracking.

### Changed

- Plugin description and keywords updated to reflect research capabilities.
- CLAUDE.md expanded with ultraresearch command, modes, agents, architecture, and state.

## [1.5.0] - 2026-04-07

### Fixed

- **CRITICAL: Parallel session data loss** — Phase 2.6 ran parallel `claude -p` sessions
  in the same working directory, causing git race conditions and repository corruption.
  Each parallel session now runs in its own git worktree with isolated branch, index,
  and working files. Branches are merged back sequentially after each wave completes.

### Added

- **Phase 2.55 (Pre-flight safety checks)** — validates clean working tree, committed
  plan file, no scope fence overlaps between parallel sessions, and no stale worktrees
  before launching parallel execution.
- **Git worktree isolation** for all parallel sessions — one branch per session
  (`ultraplan/{slug}/session-{N}`), merged with `--no-ff` after wave completion.
- **Merge conflict detection** — if merging a session branch produces conflicts, the merge
  is aborted and conflicting files are reported. No silent data loss.
- **Unconditional worktree cleanup** — worktrees and session branches are always removed,
  even on failure. Manual cleanup commands are reported if automated cleanup fails.
- **Hard rules 11-13** — worktree isolation mandatory, cleanup unconditional, merge
  sequentially with conflict abort.
- **Session-scoped progress file naming** — `--session N` uses
  `.ultraexecute-progress-{slug}-session-{N}.json` to prevent merge conflicts.

### Changed

- Headless launch template uses git worktrees with `cleanup_worktrees` trap on EXIT,
  clean-tree pre-flight check, and sequential merge after each wave.
- Phase 2.6 rewritten with 5-step worktree lifecycle: create → launch → wait → merge → cleanup.

## [1.4.0] - 2026-04-06

### Renamed

- **`/ultraexecute` → `/ultraexecute-local`** — renamed for namespace consistency with `/ultraplan-local` and future-proofing against potential Anthropic naming. File: `commands/ultraexecute.md` → `commands/ultraexecute-local.md`. Note: `ultraexecute_summary` JSON key and `ultraexecute-stats.jsonl` filename are unchanged for backward compatibility.

### Added

- **`convention-scanner` agent** (sonnet) — dedicated agent for discovering coding conventions: naming, directory layout, import style, error handling, test patterns, git commit style, documentation patterns. Replaces inline Explore agent prompt for medium+ codebases.
- **Success Criteria section** in spec template — falsifiable "definition of done" conditions that the spec-reviewer validates and ultraexecute-local uses for verification.
- **Dry-run multi-session preview** — `--dry-run` now shows session groupings, wave structure, billing status, and `claude -p` commands when plan has an Execution Strategy.
- **External verification rule** in headless launch template — wave verification must run commands independently, never parse session logs as proof.
- **Billing preamble** in headless launch template — `unset ANTHROPIC_API_KEY` prevents accidental API billing.
- **Phase mapping comment** in planning-orchestrator — documents how orchestrator phases 1-7 map to command phases 4-10.

### Fixed

- **`git add -A` in escalation** — replaced with targeted staging of only files from completed steps. Prevents staging secrets, binaries, or unrelated work.
- **False `background: true` claim** — command documentation incorrectly stated the orchestrator has `background: true` in its frontmatter. Corrected to explain `run_in_background` on the Agent tool.

### Changed

- Execution Strategy reconciliation in session-decomposer — respects existing `## Execution Strategy` as input instead of re-analyzing from scratch. Warns on file-overlap conflicts.
- Headless launch template uses `--dangerously-skip-permissions` instead of `--allowedTools` for more robust headless execution.
- Session-decomposer updated with `--dangerously-skip-permissions` and `unset ANTHROPIC_API_KEY` for generated scripts.
- Convention Scanner references in command and orchestrator updated to use dedicated plugin agent.
- ROADMAP.md translated from Norwegian to English.
- plugin.json: added homepage, repository, license, keywords. Version bumped to 1.4.0.
- README badge updated to v1.4.0.

## [1.3.0] - 2026-04-06

### Added

- **Session-aware parallel execution** — `/ultraexecute` auto-detects `## Execution Strategy` in plans and orchestrates multi-session parallel execution via `claude -p`. No manual `bash launch.sh` required.
  - **`--fg` flag** — force foreground sequential execution, ignoring Execution Strategy
  - **`--session N` flag** — execute only session N from the plan's Execution Strategy (used by child processes)
  - **Phase 2.5 (Execution strategy decision)** — determines single-session vs multi-session mode
  - **Phase 2.6 (Multi-session orchestration)** — launches parallel `claude -p` sessions per wave, waits for completion, aggregates results
- **Execution Strategy in plan template** — new `## Execution Strategy` section with sessions, waves, scope fences, and execution order. Generated by planning-orchestrator for plans with > 5 steps.
- **Execution Strategy generation in planning-orchestrator** — Phase 5 analyzes step file-overlap to build dependency graph, groups connected components into sessions of 3–5 steps, and organizes sessions into parallel waves.

### Changed

- planning-orchestrator Phase 5 extended with Execution Strategy generation logic
- ultraplan-local Phase 8 now lists Execution Strategy as 10th required plan section
- Plan template includes `## Execution Strategy` section template with grouping rules
- CLAUDE.md updated with new ultraexecute modes and architecture
- plugin.json version bumped to 1.3.0

## [1.2.0] - 2026-04-06

### Added

- **`/ultraexecute` command** — disciplined plan executor with 9-phase workflow. Reads an ultraplan or session spec, executes steps sequentially with strict failure recovery, tracks progress for resume, and reports results in machine-parseable JSON.
  - 4 modes: default (execute), `--resume` (continue from checkpoint), `--dry-run` (validate without executing), `--step N` (single step)
  - Per-step protocol: implement → verify → on-failure handling → checkpoint
  - Failure recovery from plan's On failure clauses (revert/retry/skip/escalate)
  - 3-attempt retry cap per step (initial + 2 retries)
  - Progress file (`.ultraexecute-progress-{slug}.json`) for crash recovery and resume
  - Entry/exit condition checking for session specs
  - Scope fence enforcement for session specs (never-touch file protection)
  - JSON summary block in output for headless log parsing
  - Stats tracking to `ultraexecute-stats.jsonl`

### Changed

- CLAUDE.md restructured with two commands table (plan + execute)
- plugin.json version bumped to 1.2.0

## [1.1.0] - 2026-04-06

### Added

- **`--decompose` mode** — splits an existing plan into self-contained headless sessions. Analyzes step dependencies, groups steps into sessions of 3–5 steps each, identifies parallel execution waves, and generates session specs + dependency graph + launch script.
- **`--export headless` format** — shortcut for `--decompose`. Produces the same session decomposition output.
- **session-decomposer agent** (sonnet) — dedicated agent for plan decomposition. Parses step dependencies, builds dependency graph, groups steps into sessions, generates session specs with scope fences and failure handling.
- **Session spec template** (`templates/session-spec-template.md`) — defines the format for individual session specs: context, scope fence, steps, entry/exit conditions, failure handling, handoff state.
- **Headless launch template** (`templates/headless-launch-template.md`) — template for generating bash launch scripts that execute sessions in parallel waves using `claude -p`.
- **Failure recovery per step** — plan template now includes `On failure:` (revert/retry/skip/escalate) and `Checkpoint:` (git commit) fields for every implementation step.
- **Headless readiness dimension** in plan-critic — new 9th review dimension checking for On failure clauses, Checkpoint fields, and circuit breakers. Weighted at 0.15 in the quality score.

### Changed

- Plan-critic scoring rebalanced: 6 dimensions (was 5), weights adjusted to accommodate headless readiness
- Plan template step format extended with On failure and Checkpoint fields
- Planning-orchestrator Phase 5 updated with failure recovery generation requirements
- CLAUDE.md updated with new agent, modes, and state paths

## [1.0.0] - 2026-04-06

### Added

- **`--quick` mode** — skips exploration agent swarm. Runs interview → lightweight Glob/Grep scan → planning → adversarial review. For when the developer knows the codebase and needs structure, not cartography.
- **`--export` mode** — generates shareable output from an existing plan file. Three formats: `pr` (PR description), `issue` (issue comment), `markdown` (clean plan without internal metadata).
- **task-finder three-tier categorization** — findings categorized as Must-change (must be modified), Must-respect (contract that must not break), or Reference (context/reuse). Replaces flat file list.
- **Adaptive interview depth** — interview adapts to answer quality. Detailed answers trigger fewer, more targeted questions. Short/uncertain answers trigger simpler questions with offered alternatives.
- **Complete `plugin.json` metadata** — author, homepage, repository, license, keywords added.
- **README badges** — version, license, and platform badges.
- **Known limitations section in README** — IaC projects (Terraform, Helm, Pulumi, CDK) get reduced value from exploration agents.
- **Forgejo issue templates** — bug report and feature request YAML templates.
- **CONTRIBUTING.md** — rewritten for honest solo-project model.

### Changed

- plugin.json version bumped to 1.0.0
- Command header updated to Ultraplan Local v1.0
- Orchestrator accepts `mode: quick` in prompt for lightweight scanning path

## [0.4.0] - 2026-04-06

### Added

- **3 new agents** for information-complete planning:
  - `task-finder` — dedicated agent for finding task-relevant files, functions, types, and reuse candidates. Replaces inline Explore agent.
  - `git-historian` — analyzes git log, blame, active branches, code ownership, and hot files for planning context.
  - `spec-reviewer` — reviews spec quality (completeness, consistency, testability, scope clarity) before exploration begins. New Phase 1b/4b.
- **Plan scoring** — plan-critic produces a quantitative quality score (0–100) across 5 weighted dimensions with letter grades (A–D) and verdicts (APPROVE/REVISE/REPLAN).
- **No-placeholder rule** — plan-critic flags TBD, TODO, vague instructions, and underspecified steps as unconditional blockers. 3+ blockers = REPLAN regardless of score.
- **`[ASSUMPTION]` marking** — planning-orchestrator marks all unverifiable claims and warns when >3 assumptions exist.

### Changed

- **All agents run for all codebase sizes.** Small codebases get the same 6 core agents as large ones. Agent turns scale down for small codebases instead of dropping agents entirely.
- Phase 4b (spec review) added before exploration in both command and orchestrator.
- Orchestrator Phase 2 agent table expanded: 6 always + 1 conditional + 1 medium-only.
- Plan-critic review checklist expanded with no-placeholder checks (section 7) and scoring output.
- Orchestrator rules updated with assumption-marking and no-placeholder requirements.

## [0.3.0] - 2026-04-05

### Added

- **planning-orchestrator agent** — dedicated background agent (`background: true`) that handles Phases 4–10 autonomously. Replaces generic background agent spawning with a purpose-built orchestrator running on Opus with `maxTurns: 50`.
- **`effort` and `maxTurns` on all agents** — fine-grained cost and depth control:
  - Exploration agents: `effort: medium`, `maxTurns: 15–20`
  - Review agents (plan-critic, scope-guardian): `effort: high`, `maxTurns: 10`
  - Research-scout: `effort: medium`, `maxTurns: 10`
- **Plugin `settings.json`** — default configuration for mode, research, agent counts, interview limits, and team settings. Users can override in their own settings.
- **Worktree isolation for Agent Teams** — team members use `isolation: "worktree"` to prevent file conflicts during parallel implementation
- **Session tracking** (Phase 12) — writes JSONL records to `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` with task metadata, agent counts, review verdicts, and outcomes

### Changed

- Phase 3 now launches the `planning-orchestrator` agent instead of a generic background agent
- Agent Team implementation uses worktree isolation by default

## [0.2.0] - 2026-04-05

### Added

- **Interview phase** — iterative requirements gathering with AskUserQuestion before exploration. Produces a spec file that feeds into planning.
- **7 specialized agents** in `agents/` directory:
  - `architecture-mapper` — deep architecture analysis, anti-patterns, smell detection
  - `dependency-tracer` — import-chain following, data-flow analysis, side-effect catching
  - `test-strategist` — test strategy design based on existing patterns
  - `risk-assessor` — threat modeling, edge cases, failure modes
  - `plan-critic` — dedicated adversarial reviewer with hardcoded critical perspective
  - `scope-guardian` — scope creep and scope gap detection
  - `research-scout` — external research via WebSearch/Tavily for unfamiliar technologies
- **External research capability** — research-scout agent searches documentation, known issues, and best practices when the task involves external/unfamiliar technology
- **Background mode** — default mode runs interview in foreground, then plans in background. User is notified when done.
- **Spec-driven mode** (`--spec`) — skip interview, provide a pre-written spec file, plan entirely in background
- **Foreground mode** (`--fg`) — all phases in foreground, blocks session (v0.1.0 behavior)
- **Agent Team support** — when plan has 3+ independent steps, offers parallel implementation via Agent Teams
- **Spec template** in `templates/spec-template.md`
- **Research Sources section** in plan template for citing external research
- **Dual adversarial review** — plan-critic and scope-guardian run in parallel

### Changed

- Exploration agents replaced with named specialized agents from `agents/` directory
- Agent count scales with codebase: 3 (small), 5 (medium), 7 (large)
- Plan template extended with Research Sources and external tech fields
- Handoff phase supports "execute with team" option
- Command workflow expanded from 9 to 11 phases

## [0.1.0] - 2026-04-05

### Added

- Initial release
- `/ultraplan` slash command with 6-phase workflow
- Parallel Sonnet exploration (3 agents: architecture, task-relevant, conventions)
- Opus-driven plan generation from structured template
- Plan refinement loop with execute/save handoff
- Plan template with context, analysis, steps, alternatives, risks, verification
- Cross-platform support (Mac, Linux, Windows) — pure markdown, no scripts