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

## v5.1.0 — 2026-05-13 — Per-phase effort + model dialog

Additive. No breaking changes. Forward-compat with all v5.0.x briefs.

### Why

The voyage pipeline runs a single profile-tier setting for every task. For
typo fixes and small bugfixes the full `brief → research → plan → execute
→ review` ceremony is over-engineered; for risky migrations the same
profile-tier is too thin. v5.1 hands ceremony-level back to the operator
per phase in the same dialog that produces the brief — without removing
the disciplined defaults that protect high-stakes work. Independent of
v4.1's profile system: composition happens at the command level (brief
signal wins per-phase, profile fills gaps). No `/trekflow`, no helper
module, no per-command effort dictionary — composition is documented
prose in each downstream command.

### Added

- **`/trekbrief` Phase 3.5** — between Phase 3 completeness exit and
  Phase 4 draft, 4 tier-coupled `AskUserQuestion` calls commit an effort
  level (`low | standard | high`) and an optional `model` (`sonnet |
  opus`) per downstream phase (`research`, `plan`, `execute`, `review`).
  Tier mapping: `low → {effort: low, model: sonnet}`, `standard →
  {effort: standard}` (model omitted; composition falls through to
  profile), `high → {effort: high, model: opus}`. Force-stop pattern
  (Phase 4f verbatim) records `phase_signals_partial: true` instead.
  `--quick` skips Phase 3.5 entirely and auto-writes
  `phase_signals_partial: true`.
- **`brief-validator` extension** — 6 new issue codes:
  `BRIEF_INVALID_PHASE_SIGNALS`, `BRIEF_INVALID_PHASE_SIGNAL_PHASE`,
  `BRIEF_INVALID_EFFORT`, `BRIEF_INVALID_MODEL`,
  `BRIEF_SIGNALS_MUTUALLY_EXCLUSIVE`, `BRIEF_V51_MISSING_SIGNALS` +
  exported `PHASE_SIGNAL_PHASES` + `EFFORT_LEVELS` constants. The
  `BASE_ALLOWED_MODELS` const in `lib/validators/profile-validator.mjs`
  was promoted to `export const` so the brief validator can re-use it.
- **HANDOVER-CONTRACTS amendments** — Handover 1 gets 5 inserts:
  versioning row → `2.1`, two new schema-table rows (`phase_signals`,
  `phase_signals_partial`), v5.1 sequencing-gate validation row,
  versioning-paragraph expansion explaining the version-conditional
  gate, 6 new failure-mode bullets.
- **Template bump** — `templates/trekbrief-template.md` → `brief_version
  2.1` with a default `phase_signals:` block (4 phases × `effort:
  standard`, model omitted) and a commented `phase_signals_partial:
  true` line showing the force-stop alternative.
- **Composition rule (v5.1)** — new `## Composition rule (v5.1)`
  sub-section in each of `commands/{trekplan,trekresearch,trekexecute,
  trekreview}.md`. Documents `effort_for_phase = brief.phase_signals[
  <phase>]?.effort ?? 'standard'` and `model_for_phase =
  brief.phase_signals[<phase>]?.model ?? profile.phase_models[<phase>]`.
  Per command: `effort == low` activates that command's existing
  `--quick`-equivalent code-path (`/trekplan` skips Phase 5 agent swarm,
  `/trekresearch` inline research, `/trekreview` correctness-only,
  `/trekexecute` `--gates open` + sequential-only).
- **Sequencing-gate surface** in 4 downstream commands — when
  `brief-validator.mjs` returns `BRIEF_V51_MISSING_SIGNALS` in `errors`,
  halt with a one-line user-readable message pointing back to
  `/trekbrief`. Enforcement is validator-only.
- **5 new minimal command test files** under `tests/commands/` —
  `trekbrief.test.mjs` (3 cases), `trekplan.test.mjs` /
  `trekresearch.test.mjs` / `trekreview.test.mjs` (2 cases each),
  `trekexecute.test.mjs` (2 cases). Pattern D (read .md, assert prose
  patterns). Verifies sequencing-gate surface + low-effort prose.
- **5 new doc-consistency pins** — template `brief_version 2.1` +
  `phase_signals:` block, HANDOVER schema rows, voyage CLAUDE.md +
  README.md mention `phase_signals`.
- **2 new fixtures** — `tests/fixtures/brief-with-phase-signals.md` +
  `brief-without-phase-signals.md` (backward-compat).

### Changed

- `brief_version` bumped `2.0 → 2.1`. The bump exists because v2.1
  activates the **version-conditional sequencing gate** — the only check
  in the brief validator that triggers on `brief_version` rather than
  field-presence. The forward-compat policy still applies to the field
  itself (unknown frontmatter keys flow through).

### Notes

- Test count grows by ≥ 17 new cases minimum: 6 brief-validator + 11
  command-test minimums. Realistic delta is ~25 new cases (Step 6 adds 5
  doc-consistency pins on top). Target ≥ 533 pass at Step 10 verify.
- `MIGRATION.md` was deliberately NOT created — v5.1 is an additive
  minor (brief_version 2.0 → 2.1, not major). v5.4 may promote
  `phase_signals` from optional to required (breaking change → 3.0).
- High-effort behaviors for `/trekplan` / `/trekresearch` /
  `/trekreview` are deferred to v5.1.1 per brief Non-Goal ("No complete
  per-phase effort dictionary"). v5.1 locks only the low-effort floor.
- `phase_signals_present` stats emission is also deferred to v5.1.1
  (opt-in observability per Research 03 Q5).

## v5.0.3 — 2026-05-13 — Annotation UX matches the claude-code-100x reference

**No new breaking changes beyond v5.0.0.** Forks consuming v5.0.2's
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 the existing
`claude-code-100x/build-site.js` annotation system 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
  `claude-code-100x/build-site.js` 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: `~/repos/claude-code-100x/claude-code-100x/build-site.js`
  lines 1431–2255 (annotation UI section).
- 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