docs(voyage): CLAUDE.md + README + CHANGELOG + annotation-quickstart + late doc-consistency pins — v4.2 Step 13

2026-05-09 15:41:45 +02:00 · 2026-05-09 15:41:45 +02:00 · de160d7da1
commit de160d7da1
parent 6d57314937
6 changed files with 296 additions and 9 deletions
--- a/README.md
+++ b/README.md
@ -77,19 +77,22 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud

 ---

-### [Voyage](plugins/voyage/) `v4.0.0`
+### [Voyage](plugins/voyage/) `v4.2.0`

-Deep requirements gathering, research, implementation planning, self-verifying execution, independent post-hoc review, and zero-friction multi-session resumption with specialized agent swarms, adversarial review, and failure recovery. Six-command (brief, research, plan, execute, review, continue) universal pipeline.
+Deep requirements gathering, research, implementation planning, self-verifying execution, independent post-hoc review, operator-driven artifact annotation via voyage's first marketplace playground, and zero-friction multi-session resumption — with specialized agent swarms, adversarial review, and failure recovery. Seven-command (brief, research, plan, execute, review, **revise**, continue) universal pipeline.
+
+v4.2.0 (non-breaking) adds the `/trekrevise` command and the **Handover 8 (annotation → revision)** annotation pipeline. New `playground/voyage-playground.html` (single self-contained HTML with vendored `markdown-it` + `highlight.js`) lets operators paste a brief/plan/review, drag-select or hover-anchor comments, and export a `/trekrevise --apply` batch. Round-trippable in-place revision: byte-identical body outside anchor blocks (SC2), idempotent `annotation_digest` (SC3), additive frontmatter — no `*_version` bump, every brief / plan / review written before v4.2 validates as `revision: 0` without migration. Single-iteration MVP per research-05; multi-iteration loops deferred. Includes `lib/parsers/anchor-parser.mjs` + `lib/parsers/annotation-digest.mjs`, `lib/util/markdown-write.mjs` + `lib/util/revision-guard.mjs`, `scripts/render-artifact.mjs` server-side render CLI, and `docs/annotation-quickstart.md` ≤7-step operator walkthrough.

 v4.0.0 (breaking) renames the plugin from `ultraplan-local` to **Voyage** and all seven commands from `/ultra*-local` to `/trek*` to remove name collision with Anthropic's `/ultraplan` and `/ultrareview` features. No migration path — fork-and-own users re-fork from main. See `plugins/voyage/TRADEMARKS.md` and `plugins/voyage/CHANGELOG.md`.

-Six commands, one pipeline with clear division of labor:
+Seven commands, one pipeline with clear division of labor:

 - **`/trekbrief`** — Capture intent. Dynamic, quality-gated interview: a section-driven completeness loop (Phase 3) followed by a `brief-reviewer` stop-gate (Phase 4, max 3 review iterations). Required sections must reach an initial-signal gate AND pass review across completeness, consistency, testability, scope clarity, and research-plan validity before `brief.md` is written. Identifies research topics with copy-paste-ready `/trekresearch` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive.
 - **`/trekresearch`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions.
 - **`/trekplan`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers `architecture/overview.md` when produced upstream and cross-references its `cc_features_proposed` against exploration findings.
 - **`/trekexecute`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution.
 - **`/trekreview`** — Close the iteration loop. Independent post-hoc reviewer reads `brief.md` from scratch and evaluates the diff produced by execute. Two parallel reviewers (brief-conformance + code-correctness) plus a Judge Agent (review-coordinator) for dedup and reasonableness filtering. Severity-tagged findings (Critical/High/Medium/Low/Info) with stable 40-char hex IDs feed back into planning via Handover 6 (`/trekplan --brief review.md` → remediation plan with `source_findings:` audit trail).
+- **`/trekrevise`** — (v4.2) Apply operator annotations from the playground back into the source artifact. Operator opens `playground/voyage-playground.html`, anchors comments on `brief.md` / `plan.md` / `review.md`, exports a batch, pastes back as `/trekrevise --apply`. Round-trippable in-place revision via Handover 8: `revision:` counter, `source_annotations:` audit trail, deterministic `annotation_digest` (SHA-256 prefix). Idempotence — replaying the same batch yields identical digest with no body diff outside anchor refresh. Single-iteration MVP.
 - **`/trekcontinue`** — Zero-friction multi-session resumption. In a fresh chat, type `/trekcontinue` — reads `.session-state.local.json` (Handover 7), prints a 3-line summary, and immediately begins executing the next session. Any session-end mechanism may write the state file (`/trekexecute` Phase 8/2.55/4 do so automatically; `/trekendsession` helper writes it for informal flows). Forward-compat schema (unknown top-level keys ignored) so future producers can extend additively.

 All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, `review.md`, and `.session-state.local.json` (gitignored). `--project <dir>` works across `/trekresearch`, `/trekplan`, `/trekexecute`, `/trekreview`, and (optionally) `/trekcontinue`.
@ -114,9 +117,9 @@ v3.1.0 also adds: `docs/HANDOVER-CONTRACTS.md` as the single source of truth for

 Defense-in-depth security: plugin hooks block destructive commands and sensitive path writes, prompt-level denylist works in headless sessions, pre-execution plan scan catches dangerous commands before they run, scoped `--allowedTools` replaces `--dangerously-skip-permissions` in parallel sessions. Recommended hardening: `disableSkillShellExecution: true` for fork-ers handling untrusted plans (CC v2.1.91+).

-Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export, resume
+Modes: default, brief-driven, project-scoped, research-enriched, foreground, quick, decompose, export, resume, revise

-23 specialized agents · 6 commands (+ 1 helper) · 5 plugin hooks · 185 tests · No cloud dependency
+23 specialized agents · 7 commands (+ 1 helper) · 5 plugin hooks · 600+ tests · First marketplace playground (v4.2) · No cloud dependency

 → [Full documentation](plugins/voyage/README.md) · [Migration guide](plugins/voyage/MIGRATION.md)

--- a/plugins/voyage/CHANGELOG.md
+++ b/plugins/voyage/CHANGELOG.md
@ -4,6 +4,122 @@ 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/).

+## 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.**
--- a/plugins/voyage/CLAUDE.md
+++ b/plugins/voyage/CLAUDE.md
@ -233,21 +233,24 @@ Local Docker Compose stack: `examples/observability/`. Operator docs: `docs/obse

 **Continue:** `/trekcontinue` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `<project-dir>` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/trekendsession` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/trekexecute`.

+**Revise (v4.2):** `/trekrevise --project <dir>` consumes a batch exported from `playground/voyage-playground.html` and folds operator annotations back into the source artifact (`brief.md` / `plan.md` / `review.md`). Phase 1 parse + validate, Phase 2 read source + rollback hygiene (`*.local.bak` via `lib/util/revision-guard.mjs`), Phase 3 parse anchors + validate placement (`lib/parsers/anchor-parser.mjs` — block-boundary discipline), Phase 4 compute revision diff + deterministic SHA-256 digest (`lib/parsers/annotation-digest.mjs`), Phase 5 atomic apply via `lib/util/markdown-write.mjs`, Phase 6 round-trip integrity (`stripAnchors`-of-written equals pre-write body), Phase 7 optional review-gate when target is plan and review.md exists, Phase 8 stats + report. Single-iteration MVP — each batch produces one `revision:` increment with `source_annotations:` audit trail. **Handover 8** (`docs/HANDOVER-CONTRACTS.md`) — additive frontmatter; no `*_version` bump; artifacts written before v4.2 validate as `revision: 0`.
+
 **Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.

-**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project <dir>` fills in `{dir}/research/`. `/trekplan --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/trekexecute --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
+**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project <dir>` fills in `{dir}/research/`. `/trekplan --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/trekexecute --project <dir>` executes and writes `{dir}/progress.json`. `/trekreview --project <dir>` produces `{dir}/review.md`. `/trekrevise --project <dir>` (v4.2) folds operator annotations back into any of the three artifacts in-place, with audit trail in frontmatter. All artifacts live in one project directory.

 **Project-directory contract (v3.0.0):** trekplan owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer.

 ```
 .claude/projects/{YYYY-MM-DD}-{slug}/
-  brief.md           ← trekbrief writes; everyone reads
+  brief.md           ← trekbrief writes; everyone reads; trekrevise mutates in-place
  research/*.md      ← trekresearch writes; plan + architect read
  architecture/      ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
    overview.md
    gaps.md
-  plan.md            ← trekplan writes; trekexecute reads
+  plan.md            ← trekplan writes; trekexecute reads; trekrevise mutates in-place
  progress.json      ← trekexecute writes
+  review.md          ← trekreview writes; trekplan reads (Handover 6); trekrevise mutates in-place
 ```

 No code-level dependency between plugins — the contract is filesystem-level only.
--- a/plugins/voyage/README.md
+++ b/plugins/voyage/README.md
@ -8,7 +8,7 @@

 *AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*

-A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, and zero-friction multi-session resumption. Six commands, one pipeline:
+A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, operator-driven artifact annotation, and zero-friction multi-session resumption. Seven commands, one pipeline:

 | Command | What it does |
 |---------|-------------|
@ -17,6 +17,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep
 | **`/trekplan`** | Plan — agent swarm exploration, Opus planning, adversarial review |
 | **`/trekexecute`** | Execute — disciplined step-by-step implementation with failure recovery |
 | **`/trekreview`** | Review — independent post-hoc review of delivered code against the brief, severity-tagged findings |
+| **`/trekrevise`** | Revise — apply operator annotations from the playground back into brief/plan/review with audit trail (Handover 8, v4.2) |
 | **`/trekcontinue`** | Continue — read `.session-state.local.json` and resume the next session in a multi-session project |

 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`.
@ -30,6 +31,7 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
 | `/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.7` |
 | `/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 |
+| `/trekrevise` | **Re-fold operator annotations** — operator opens the playground, anchors comments on a brief/plan/review, exports the batch, pastes back as `/trekrevise --apply`. Round-trippable in-place revision: `revision:` counter, `source_annotations:` audit trail, deterministic `annotation_digest`. Single-iteration MVP per Handover 8. | revised `brief.md` / `plan.md` / `review.md` with frontmatter audit trail |

 **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.

@ -501,6 +503,52 @@ Both arguments are required. No interactive prompt — headless-safe.

 ---

+## `/trekrevise` — Annotation playground (v4.2)
+
+Voyage's first interactive playground. Open `playground/voyage-playground.html`
+in any modern browser, paste your `brief.md`, `plan.md`, or `review.md`, and
+annotate the rendered artifact directly. The playground is a single
+self-contained HTML file with vendored `markdown-it` + `highlight.js` —
+no build step, no network calls, no telemetry.
+
+The annotation lifecycle is **Handover 8 — annotation → revision** (see
+`docs/HANDOVER-CONTRACTS.md`). Three stages:
+
+1. **Annotate** — drag-select text or hover-anchor a paragraph; fill the
+   modal with comment + intent (`change` / `add` / `remove` / `clarify` /
+   `risk`). Anchors are placed only at block boundaries; the playground
+   refuses placement inside list items, mid-paragraph, or at line-start
+   collision points.
+2. **Export** — click "Eksporter batch" to copy a complete
+   `/trekrevise --project <dir> --apply '{...JSON...}'` invocation to your
+   clipboard.
+3. **Apply** — paste the command in Claude Code chat. `/trekrevise` parses
+   the batch, re-runs placement validation, atomically writes anchor comment
+   blocks back into the source artifact, increments `revision:`, appends to
+   `source_annotations:`, and recomputes the deterministic `annotation_digest`.
+
+The artifact's body remains byte-identical outside anchor blocks (SC2). Re-applying
+the same batch yields the same digest (idempotence — SC3). The frontmatter
+audit trail makes every revision traceable in git.
+
+```bash
+# Open the playground (one-time)
+open plugins/voyage/playground/voyage-playground.html
+# Or render an artifact server-side via the CLI helper:
+node plugins/voyage/scripts/render-artifact.mjs \
+  .claude/projects/2026-05-09-feature/plan.md \
+  --out /tmp/plan.html
+```
+
+For a step-by-step walkthrough, see
+[`docs/annotation-quickstart.md`](docs/annotation-quickstart.md).
+
+**Single-iteration MVP:** Each operator batch produces one `revision:` bump.
+Multi-iteration loops (revise → re-review → revise again) are deferred
+indefinitely per research-05; the brief's SC4 wording is single-revision.
+
+---
+
 ## The full pipeline

 ```
--- a/plugins/voyage/docs/annotation-quickstart.md
+++ b/plugins/voyage/docs/annotation-quickstart.md
@ -0,0 +1,55 @@
+# Annotation playground — quickstart
+
+The `/trekrevise` command and the `playground/voyage-playground.html` page
+let you annotate any voyage artifact (`brief.md`, `plan.md`, or `review.md`)
+and fold the annotations back in-place with a deterministic audit trail.
+
+This is **Handover 8** in `docs/HANDOVER-CONTRACTS.md`. For schema details,
+read that document first.
+
+## Hands-on with the example fixture
+
+The plugin ships a canonical fixture at
+`tests/fixtures/annotation/annotation-example.md` that is the same shape an
+operator would annotate. Use it to verify your playground works before
+touching a real project.
+
+## Seven steps from artifact to revised file
+
+1. **Open the playground.** Open `plugins/voyage/playground/voyage-playground.html`
+   in any modern browser. No build, no server, no network calls — the page
+   ships vendored `markdown-it` and `highlight.js` under `playground/lib/`.
+
+2. **Paste the artifact content.** Copy the full body of your `brief.md`,
+   `plan.md`, or `review.md` (including frontmatter) into the textarea on
+   the left. The right pane renders the markdown live. For larger artifacts
+   you can also generate the rendered HTML offline with
+   `node plugins/voyage/scripts/render-artifact.mjs <path> --out /tmp/x.html`.
+
+3. **Anchor a comment.** Drag-select text inside a paragraph, or hover a
+   block-level element and click the anchor button that appears. The
+   playground refuses anchors inside list items, mid-paragraph, or at
+   line-start collision points — only block boundaries are valid (per the
+   placement discipline in `lib/parsers/anchor-parser.mjs`).
+
+4. **Fill the modal.** Choose an intent (`change`, `add`, `remove`,
+   `clarify`, or `risk`), write your comment, save. Repeat for every
+   anchor you want in this batch. The sidebar shows your batch growing as
+   a critique-card-list.
+
+5. **Export the batch.** Click "Eksporter batch". The playground copies a
+   complete `/trekrevise --project <dir> --apply '{...JSON...}'` invocation
+   to your clipboard. The JSON encodes every anchor, intent, and comment.
+
+6. **Apply via `/trekrevise`.** Paste the command in your Claude Code chat.
+   The command parses + validates the batch, atomically writes anchor
+   comment blocks back into the source artifact, increments `revision:`,
+   appends entries to `source_annotations:`, and recomputes
+   `annotation_digest`. Body content outside anchor blocks remains
+   byte-identical.
+
+7. **Verify and iterate.** Re-open the revised file in the playground to
+   see anchors as inline comment markers. If you want another revision
+   pass, repeat from step 3 — each batch produces one `revision:` bump.
+   Single-iteration MVP per research-05; multi-iteration loops are
+   deferred.
--- a/plugins/voyage/tests/lib/doc-consistency.test.mjs
+++ b/plugins/voyage/tests/lib/doc-consistency.test.mjs
@ -563,3 +563,65 @@ test('tests/fixtures/annotation/annotation-example.md parses cleanly via parseAn
    `parseAnchors failed on annotation-example.md fixture: ${JSON.stringify(result.errors || [])}`,
  );
 });
+
+// --- v4.2 Step 13 — late doc-consistency pins (post-write of CLAUDE / READMEs / CHANGELOG / quickstart) ---
+//
+// These were deferred from Step 12 per plan-critic M1 ordering finding —
+// Step 13 is where these files are written, so pins go here.
+
+test('plugin README.md mentions /trekrevise in commands section', () => {
+  // Already covered for CLAUDE.md by the "all seven pipeline commands" test;
+  // this pin extends coverage to the plugin-level README.
+  const md = read('README.md');
+  assert.ok(
+    md.includes('/trekrevise'),
+    'plugin README.md must reference /trekrevise (added in v4.2 Step 13)',
+  );
+});
+
+test('marketplace root README.md mentions /trekrevise and v4.2.0', () => {
+  // ../../README.md is the marketplace landing — must surface v4.2 ship.
+  // Path traversal is allowed here per feedback_plugin_scope_strict
+  // (root README updates are explicitly in Step 13's scope).
+  const md = read('../../README.md');
+  assert.ok(
+    md.includes('/trekrevise') || md.includes('trekrevise'),
+    'marketplace root README.md must reference /trekrevise (v4.2)',
+  );
+  assert.ok(
+    md.includes('v4.2.0'),
+    'marketplace root README.md must reference voyage v4.2.0',
+  );
+});
+
+test('CHANGELOG.md has v4.2.0 entry', () => {
+  const cl = read('CHANGELOG.md');
+  assert.match(
+    cl,
+    /## v4\.2\.0\b/,
+    'CHANGELOG.md must include "## v4.2.0" entry per Keep-a-Changelog 1.1.0',
+  );
+});
+
+test('docs/annotation-quickstart.md exists with ≤7 numbered steps and example-fixture reference', () => {
+  // SC12 — operator-facing quickstart. The plan caps numbered steps at 7
+  // to keep cognitive load minimal; reference to the example fixture
+  // anchors the doc to a concrete artifact operators can replay.
+  const path = 'docs/annotation-quickstart.md';
+  assert.ok(existsSync(join(ROOT, path)), `${path} missing`);
+  const text = read(path);
+  // Numbered top-level steps: lines starting with "1." through "7." at
+  // line-start. Forbid 8.+ line-starts.
+  const numberedSteps = (text.match(/^[1-9]\./gm) || []);
+  for (const s of numberedSteps) {
+    const n = parseInt(s, 10);
+    assert.ok(
+      n >= 1 && n <= 7,
+      `${path} contains step ${s} — only 1.-7. permitted (single-screen quickstart)`,
+    );
+  }
+  assert.ok(
+    text.includes('tests/fixtures/annotation/annotation-example.md'),
+    `${path} must reference the canonical example fixture for hands-on verification`,
+  );
+});