From de160d7da1942878df527d3c6b8944b05638ba8f Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sat, 9 May 2026 15:41:45 +0200 Subject: [PATCH] =?UTF-8?q?docs(voyage):=20CLAUDE.md=20+=20README=20+=20CH?= =?UTF-8?q?ANGELOG=20+=20annotation-quickstart=20+=20late=20doc-consistenc?= =?UTF-8?q?y=20pins=20=E2=80=94=20v4.2=20Step=2013?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 13 +- plugins/voyage/CHANGELOG.md | 116 ++++++++++++++++++ plugins/voyage/CLAUDE.md | 9 +- plugins/voyage/README.md | 50 +++++++- plugins/voyage/docs/annotation-quickstart.md | 55 +++++++++ .../voyage/tests/lib/doc-consistency.test.mjs | 62 ++++++++++ 6 files changed, 296 insertions(+), 9 deletions(-) create mode 100644 plugins/voyage/docs/annotation-quickstart.md diff --git a/README.md b/README.md index 67f795c..c43a529 100644 --- 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 ` 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) diff --git a/plugins/voyage/CHANGELOG.md b/plugins/voyage/CHANGELOG.md index 210d7a4..9c003d4 100644 --- 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.** diff --git a/plugins/voyage/CLAUDE.md b/plugins/voyage/CLAUDE.md index 2636b8c..33dda33 100644 --- 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 `` 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 ` 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 ` fills in `{dir}/research/`. `/trekplan --project ` 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 ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. +**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project ` fills in `{dir}/research/`. `/trekplan --project ` 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 ` executes and writes `{dir}/progress.json`. `/trekreview --project ` produces `{dir}/review.md`. `/trekrevise --project ` (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. diff --git a/plugins/voyage/README.md b/plugins/voyage/README.md index 7d46c58..cb4e437 100644 --- 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 --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 ``` diff --git a/plugins/voyage/docs/annotation-quickstart.md b/plugins/voyage/docs/annotation-quickstart.md new file mode 100644 index 0000000..cb314ac --- /dev/null +++ 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 --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 --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. diff --git a/plugins/voyage/tests/lib/doc-consistency.test.mjs b/plugins/voyage/tests/lib/doc-consistency.test.mjs index b3b961f..be17cca 100644 --- 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`, + ); +});