docs(readme): bring the README up to 6.4.0

- Changelog list: v6.0.0 to v6.4.0 replace v5.5.0 to v5.8.0. - Profile system: custom profiles live in voyage-profiles/ (repo root or ~/.claude), never lib/profiles/ (resolver.mjs findProfilePath); env is not read on a resume; brief phase_signals come before the profile. docs/profiles.md had the same wrong path. - Annotation: the install-section paragraph described the v5.0.2 UX and linked a dead anchor; the v5.0.3 history note moved to a CHANGELOG pointer. - Architecture slot replaces "Disable the architect bridge"; the producer is no longer distributed and any Handover 3 producer fits. - Stale facts fixed: review severities, seven handovers, session titles for six commands, the brief's framing field, Upgrading since v6.0.0, the npm test path, the tree root and docs list, the add-an-agent steps. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:36:15 +02:00 · 2026-10-17 00:36:15 +02:00 · 4d9b44096a
commit 4d9b44096a
parent a3fa5de42a
2 changed files with 45 additions and 44 deletions
--- a/README.md
+++ b/README.md
@ -38,7 +38,7 @@ Or enable directly in `~/.claude/settings.json`:
 }
 ```

-`/trekbrief`, `/trekplan`, and `/trekreview` each end by running `scripts/annotate.mjs` against the just-written artifact and printing the resulting `file://<abs path>` link. The operator opens the HTML in a browser, clicks any line of the document, writes their own note in the inline textarea, watches a sidebar of all notes (editable, deletable, persisted in browser `localStorage`), and clicks "Copy Prompt" to get one structured prompt that they paste back into Claude — Claude then revises the `.md` from the notes. **The operator drives every annotation.** See [Reviewing and annotating artifacts](#reviewing-and-annotating-artifacts-v502).
+`/trekbrief`, `/trekplan`, and `/trekreview` each end by printing a `file://` link to an HTML copy of the artifact they wrote, where you mark up the text in a browser and copy your notes back to Claude as one prompt. **You drive every annotation.** See [Reviewing and annotating artifacts](#reviewing-and-annotating-artifacts).

 Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, and `review.md`.

@ -50,7 +50,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
 | `/trekresearch` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
 | `/trekplan` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when an opt-in upstream architect plugin (not bundled) is installed. | `plan.md` with Manifest blocks + `plan_version: 1.9` |
 | `/trekexecute` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
-| `/trekreview` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: trekreview`) with stable 40-char hex finding-IDs |
+| `/trekreview` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (BLOCKER/MAJOR/MINOR/SUGGESTION) and a required verdict that `verdict-gate.mjs` decides on; findings feed back into planning via Handover 6. | `review.md` (`type: trekreview`) with stable 40-char hex finding-IDs |

 **Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.

@ -130,7 +130,7 @@ An optional architect step can sit between research and plan — `/trekplan` aut
 Concrete capabilities, observable in the code — not aspirations.

 **Across all profiles:**
- Strategy-to-execution on four explicit handover points. Each transition is a filesystem contract (`docs/HANDOVER-CONTRACTS.md`), not a conversation. You can stop after any stage and resume later without context loss.
+- Strategy-to-execution on seven explicit handover points. Each transition is a filesystem contract (`docs/HANDOVER-CONTRACTS.md`), not a conversation. You can stop after any stage and resume later without context loss.
 - Resume safety after long sessions. The PreCompact hook reconciles `progress.json` with git history before context compaction (CC v2.1.105+) — closes a documented `--resume` failure mode.
 - Schema discipline. `plan-validator --strict` enforces `### Step N:` form and rejects narrative drift (`### Fase`, `### Phase`, `### Stage`, `### Steg`) before execution.
 - Audit trail by construction. Every executed step records `commit_sha`, `verify_passed`, `files_changed` in `progress.json`.
@ -139,7 +139,7 @@ Concrete capabilities, observable in the code — not aspirations.

 **Team (2–10).** Plan files are handover-ready — a colleague can pick up a project directory without re-asking "what did you mean here?". `--decompose` splits a plan into self-contained session specs plus `orders.md`, one starter line per session that each person runs in a session they open. The plan-critic semantic rubric gives the team a shared definition of "this plan defers decisions to the executor".

-**Virksomhet / regulated environment.** Defense-in-depth security across three layers (plugin hooks, prompt-level denylist, pre-execution plan scan). `disableSkillShellExecution: true` recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from voyage commands.
+**Organization / regulated environment.** Defense-in-depth security across three layers (plugin hooks, prompt-level denylist, pre-execution plan scan). `disableSkillShellExecution: true` recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from voyage commands.

 ## Non-goals

@ -189,6 +189,7 @@ If you say "stop" or "enough" during Phase 4, the current review findings are su

 ### What the brief contains

+- **Framing** — `framing: preserve | refine | replace | new-direction` in the frontmatter, asked as its own question (Phase 2.5) so a wrong premise is not polished; required from `brief_version 2.2`, as is a `## TL;DR`
 - **Intent** — why this matters, motivation, user need (load-bearing)
 - **Goal** — concrete end state in 1-3 sentences
 - **Non-Goals** — explicitly out of scope
@ -472,7 +473,7 @@ prompt-injection vector that the plugin's own hooks cannot fully mitigate

 A `UserPromptSubmit` hook (`hooks/scripts/session-title.mjs`) sets the
 session title to `voyage:<command>:<slug>` whenever you invoke one of
-the four voyage commands. This makes the sessions of a multi-session run and
+the six pipeline commands. This makes the sessions of a multi-session run and
 session-picker output trivially identifiable. Slug derivation:

 | Invocation | Session title |
@ -664,7 +665,7 @@ baseline from obra/superpowers (MIT); the skills' content from Superpowers, agen
 mattpocock/skills (MIT); the with-and-without effect loop from Anthropic's skill-creator
 (Apache-2.0). Only ideas are borrowed, no code; pinned commits in each `SKILL.md`.

-## Reviewing and annotating artifacts (v5.0.3)
+## Reviewing and annotating artifacts

 `/trekbrief`, `/trekplan`, and `/trekreview` each end by running
 `scripts/annotate.mjs` against the just-written `.md` and printing the
@ -727,18 +728,9 @@ annotation surface the operator pointed at:
 You select / click, pick intent, write comment, repeat. When you're
 done, Copy Prompt, paste back into this chat. Claude revises the `.md`
 freehand from your notes. **The operator drives every annotation.**
-Claude never pre-generates suggestions in this flow.
-
-> **What v5.0.3 changed from v5.0.2.** v5.0.2 was operator-led but the UX
-> was too thin — click a line, type a freeform note, save. The reference
-> the operator pointed at (an existing annotation surface in another project)
-> already had the right pattern: pencil-toggle, selection capture, three
-> intent categories, popover form, structured markdown export. v5.0.3
-> rebuilds `scripts/annotate.mjs` against that reference. v5.0.0 / v5.0.1
-> / v5.0.2 are all superseded; only the v5.0.0 removals (bespoke
-> playground SPA, `/trekrevise`, Handover 8, supporting `lib/` modules,
-> Playwright e2e + devDeps) stay. See [CHANGELOG.md](CHANGELOG.md)
-> § v5.0.0 → § v5.0.3.
+Claude never pre-generates suggestions in this flow. The surface has worked
+this way since v5.0.3; how it got here is in [CHANGELOG.md](CHANGELOG.md)
+§ v5.0.0 → § v5.0.3.

 ---

@ -874,7 +866,7 @@ An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-speci

 ## Upgrading

-Migration notes for breaking changes (v1.x → v2.0, v2.x → v3.0) live in [CHANGELOG.md](CHANGELOG.md) and [MIGRATION.md](MIGRATION.md). v3.x non-breaking — minor bumps within v3 add features without changing pipeline contracts.
+Migration notes for breaking changes live in [CHANGELOG.md](CHANGELOG.md) and [MIGRATION.md](MIGRATION.md). The last breaking release is v6.0.0: Voyage no longer starts Claude Code sessions, so multi-session work comes back as session orders you start yourself. Since v6.3.0 every CHANGELOG section says under `### Doors` whether each delivery is a one-way or a two-way door, and which changes ask something of users. Older brief, plan and review versions keep validating; newer rules apply from the version that introduced them.

 ## Releasing and rolling back

@ -885,8 +877,7 @@ A Voyage release follows [docs/release-runbook.md](docs/release-runbook.md): bef
 The plugin ships with `node:test`-based unit tests and a `lib/` directory of pure-JS validators wired into the commands. Forking the plugin for internal use? Run `npm test` to confirm the parsers, validators, and doc-consistency invariants still hold:

 ```bash
-cd plugins/trekplan
-npm test    # runs all tests under tests/**/*.test.mjs
+npm test    # from the repo root; runs all tests under tests/**/*.test.mjs
 ```

 Validators (zero npm deps, hand-rolled YAML subset):
@ -921,7 +912,7 @@ The `pre-compact-flush.mjs` hook directly fixes the documented P0 in `docs/treke

 ## Profile system (v4.1.0)

-Four built-in model profiles plus operator-defined `<custom>.yaml` (drop in `lib/profiles/`). Each profile pins `phase_models` for the six pipeline phases. The active profile is recorded in plan.md frontmatter as `profile: <name>` and emitted to JSONL stats for cost-attribution.
+Four built-in model profiles (`lib/profiles/*.yaml`) plus your own: a `<name>.yaml` in `voyage-profiles/` at the repo root, or in `~/.claude/voyage-profiles/`. A custom file with a built-in's name is ignored. Each profile pins `phase_models` for the six pipeline phases. The active profile is recorded in plan.md frontmatter as `profile: <name>` and emitted to JSONL stats for cost-attribution.

 | Profile | Brief | Research | Plan | Execute | Review | Continue | Use case |
 |---------|-------|----------|------|---------|--------|----------|----------|
@ -934,9 +925,11 @@ Lookup order:

 1. Explicit `--profile <name>` flag passed to the command
 2. Plan-file frontmatter `profile:` (when resuming via `/trekexecute --resume` or `/trekcontinue`)
-3. `VOYAGE_PROFILE` environment variable
+3. `VOYAGE_PROFILE` environment variable (not read on a resume)
 4. Default `premium`

+A brief's `phase_signals` (written by `/trekbrief`) can set the model for research, plan, execute and review; where it does, it comes before the profile.
+
 See [`docs/profiles.md`](docs/profiles.md) for the decision tree, custom-profile authoring, and cost estimation disclaimer (the per-profile cost numbers are *anslag*, not contractual SLAs).

 ## Observability (v4.1.0)
@ -970,7 +963,7 @@ For per-profile cost estimates, see [`docs/profiles.md`](docs/profiles.md).
 Top-level layout:

 ```
-trekplan/
+voyage/
 ├── agents/        24 specialized agents (all `model: opus`-pinned; per-phase model set by `--profile`)
 │                  └ 21 spawnable (1 dormant: synthesis-agent, Δ≈0) + 3 orchestrator reference docs (not spawned)
 ├── commands/      6 slash commands (trekbrief, trekresearch, trekplan, trekexecute, trekreview, trekcontinue) + trekendsession helper
@ -979,7 +972,7 @@ trekplan/
 ├── hooks/         12 hooks (pre-bash, pre-write, pre-agent-cap, pre-plan-gate, session-title, post-bash-stats, post-approval-log, post-edit-check, pre-compact-flush, post-compact-flush, otel-export, stop-test-lock)
 ├── lib/           Zero-dep parsers and validators (CLI shims under lib/validators/)
 ├── tests/         comprehensive node:test suite — `npm test` is the fork-readiness gate
-├── docs/          HANDOVER-CONTRACTS.md + architect-bridge-test.md
+├── docs/          HANDOVER-CONTRACTS.md, architecture.md, operations.md, profiles.md, command-modes.md, release-runbook.md
 └── examples/      01-add-verbose-flag/ — calibrated end-to-end pipeline demo
 ```

@ -1001,12 +994,14 @@ synthesis.
   cp agents/architecture-mapper.md agents/my-new-agent.md
   ```
 2. Update the frontmatter `name`, `description`, `tools`, and `model`.
-   Use `sonnet` unless the agent needs deep reasoning (most don't).
-3. Add the agent to the swarm in `agents/planning-orchestrator.md`
-   Phase 5 — register it under the codebase-size bucket where it
-   should fire (always / medium+ / large only).
-4. Update the agent table in `CLAUDE.md` and `README.md` to keep the
-   doc-consistency test green:
+   Every shipped agent is `model: opus`; the profile picks the model at
+   the spawn site, so the pin is only the fallback.
+3. Add the agent to the swarm in `commands/trekplan.md` Phase 5
+   (the command runs the swarm inline; `agents/planning-orchestrator.md`
+   is a reference copy of that workflow) — register it under the
+   codebase-size bucket where it should fire.
+4. Update the agent table in `CLAUDE.md` and the agent count in the
+   `README.md` architecture block to keep the doc-consistency test green:
   ```bash
   npm test -- tests/lib/doc-consistency.test.mjs
   ```
@ -1033,7 +1028,7 @@ document it in your team's CLAUDE.md.

 ### Plugin data contract

-The four commands write to a single project directory (`.claude/projects/{date}-{slug}/`).
+The pipeline commands write to a single project directory (`.claude/projects/{date}-{slug}/`).
 The full schema for every artifact is in [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md).
 That document is the single source of truth for:

@ -1048,13 +1043,16 @@ that doc *and* the corresponding `lib/validators/*.mjs` *and* run
 `npm test` — the validators and doc-consistency tests will catch
 schema drift.

-### Disable the architect bridge
+### Use or skip the architecture slot

-`/trekplan` auto-discovers `architecture/overview.md` if an
-opt-in upstream architect plugin (not bundled) produced one. To
-suppress this, leave the `architecture/` directory absent from your
-project directory. Discovery is additive — missing file is fine, no
-error.
+`/trekplan` reads `architecture/overview.md` in the project directory
+as priors when the file is there. The architect plugin that once wrote
+it is no longer publicly distributed; any producer that writes the
+format in [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md)
+§ Handover 3 fits the slot, and none is privileged. To skip it, leave
+`architecture/` out of the project directory: a missing file is fine,
+and a file that does not match the format gives warnings, never a
+failure.

 ## Changelog

@ -1062,11 +1060,11 @@ Full version history → [CHANGELOG.md](CHANGELOG.md).

 Recent, in one line each:

- **v5.8.0** — offline gold-scored output eval (SKAL-1·4b): `lib/review/gold-scorer.mjs` grades a committed agent-run fixture against the golden corpus at `(file, rule_key)` granularity; suite census gains a `goldEval` category. Offline + deterministic, no live agent spawn.
- **v5.7.1** — leaner always-loaded agent listing (`<example>` blocks moved into agent bodies, ~3,180 tok/turn, no behavior change).
- **v5.7.0** — opt-in per-session token/cost metering (SKAL-2) + eval foundation (SKAL-1·4a).
- **v5.6.1** — one-line `description:` for the four reference/dormant agents (~700 tok).
- **v5.5.0** — brief **framing** enforcement (`brief_version 2.2`) + a `/trekreview` reviewer-schema contract. Additive, no breaking changes.
+- **v6.4.0** — `plan_version 1.9` (the file first on every `Files:` and `Test first:` line), the fixes from the test repo's fourth trial, tests that no longer touch a live session's stop guard, and a critic loop that converges (rounds 2+ in diff mode, counted by rule A). Older plans warn, they do not fail.
+- **v6.3.1** — fixes from the release review of 6.3.0, and two holes in the verdict gate closed. Nothing asks anything of users.
+- **v6.3.0** — `/trekexecute` refuses a plan without a logged approval of its current text and runs its own review at the end as a gate; three skills (`test-first`, `debugging`, `researching-sources`); a drilled release runbook.
+- **v6.2.0** — approved intent, the plan gate, one fresh step helper per plan step, guards as command hooks, and a review that is a gate (`verdict:` required).
+- **v6.0.0** — breaking: Voyage never starts Claude Code; multi-session work becomes session orders you start yourself.

 ## Contributing