chore(voyage): release v5.0.0 — remove bespoke playground + /trekrevise + Handover 8; render produced artifacts to HTML + link, annotate via /playground
The v4.2/v4.3 bespoke playground SPA (~388 KB), the /trekrevise command, Handover 8 (annotation → revision), the supporting lib/ modules (anchor-parser, annotation-digest, markdown-write, revision-guard), the Playwright e2e suite, and the @playwright/test / @axe-core/playwright devDeps are removed. A browser walkthrough found the playground borderline unusable, and it duplicated the official /playground plugin's document-critique / diff-review templates. In their place: scripts/render-artifact.mjs — a small, zero-dependency renderer that turns a brief/plan/review .md into a self-contained, design-system-styled, zero-network .html (frontmatter folded into a <details> block). /trekbrief, /trekplan, and /trekreview call it on their last step and print the file:// link; to annotate, run /playground (document-critique) on the .md and paste the generated prompt back. Resolves the v4.3.1-deferred findings as moot (their target files are deleted). npm test green: 509 tests, 507 pass, 0 fail, 2 skipped. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
0f197f6ff6
commit
916d30f63e
96 changed files with 620 additions and 14716 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# trekplan — Brief, Research, Plan, Execute, Review, Continue
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -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, operator-driven artifact annotation, and zero-friction multi-session resumption. Seven 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, and zero-friction multi-session resumption. Six commands, one pipeline:
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
|
|
@ -17,10 +17,11 @@ 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`.
|
||||
`/trekbrief`, `/trekplan`, and `/trekreview` also render their artifact to a self-contained `.html` next to it and print the `file://` link — annotate via the official `/playground` plugin (`document-critique`) and paste its prompt back.
|
||||
|
||||
Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md` (+ `brief.html`), `research/NN-*.md`, `plan.md` (+ `plan.html`), `sessions/`, `progress.json`, and `review.md` (+ `review.html`).
|
||||
|
||||
### Division of labor
|
||||
|
||||
|
|
@ -31,7 +32,6 @@ 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.
|
||||
|
||||
|
|
@ -503,65 +503,37 @@ Both arguments are required. No interactive prompt — headless-safe.
|
|||
|
||||
---
|
||||
|
||||
## `/trekrevise` — Annotation playground (v4.2 + v4.3 rebuild)
|
||||
## Rendered artifacts & annotation (v5.0.0)
|
||||
|
||||
Voyage's interactive playground. Open `playground/voyage-playground.html` in
|
||||
any modern browser, point it at a `.claude/projects/<slug>/`-mappe, and
|
||||
browse + annotate every artifact (brief / plan / research / review) directly.
|
||||
The playground is a single self-contained HTML file with vendored
|
||||
`markdown-it` + `highlight.js` + `DOMPurify` ≥ 3.1.1 — no build step, no
|
||||
network calls, no telemetry.
|
||||
`/trekbrief`, `/trekplan`, and `/trekreview` each finish by rendering their
|
||||
just-written `.md` to a self-contained `.html` next to it
|
||||
(`{project_dir}/brief.html`, `plan.html`, `review.html`) and printing the
|
||||
`file://` link. The renderer (`scripts/render-artifact.mjs`) is a small,
|
||||
zero-dependency Node script: it folds frontmatter into a `<details>` block,
|
||||
puts code fences in styled `<pre>`, renders tables/lists/links, and inlines a
|
||||
compact design-system-aligned stylesheet. **No external network, no build
|
||||
step, no telemetry.** Two runs on the same input produce byte-identical HTML.
|
||||
|
||||
**v4.3 rebuild** (2026-05-10) — dashboard-centric layout with `fleet-grid` of
|
||||
`fleet-tile` per artifact and drill-down detail surface. Three file://-loader
|
||||
entry points: `webkitdirectory` directory-picker (Chromium primary, FF150+
|
||||
secondary), drag-drop with `webkitGetAsEntry` recursive walk, and URL-parameter
|
||||
`?project=/abs/path` ergonomic shortcut. Hidden-by-default sidebar-rail with
|
||||
J/K keyboard navigation + Esc dismiss; two-opacity pattern (active 100% /
|
||||
inactive 40% / resolved 30% strikethrough). A11Y panel built from DS-primitives.
|
||||
Path-traversal + symlink/dotfile filter (`isProjectPathSafe`) blocks
|
||||
`..` / `node_modules/` / `dist/` / `build/` / hidden-paths. Total bundle 388 KB
|
||||
under 460 KB HALT-gate. Test pyramid Groups A-D — 17 static-HTML + 9 structure +
|
||||
7 schema/digest tests (`npm test`) plus 4 Playwright e2e (light/dark axe-core
|
||||
delta-baseline + pixel-diff smoke + zero-external-network gate via
|
||||
`npm run test:e2e`). See [`playground/README.md`](playground/README.md) +
|
||||
[`docs/sc1-checklist-verification.md`](docs/sc1-checklist-verification.md).
|
||||
|
||||
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.
|
||||
To **annotate** an artifact, run the official `/playground` plugin
|
||||
(`document-critique` template) on the `.md` file and paste the prompt it
|
||||
generates back into the conversation — Claude then revises the artifact
|
||||
freehand from your notes. The `/playground` plugin already produces clean,
|
||||
self-contained single-file HTML for exactly this; voyage no longer ships its
|
||||
own annotation UI.
|
||||
|
||||
```bash
|
||||
# Open the playground (one-time)
|
||||
open plugins/voyage/playground/voyage-playground.html
|
||||
# Or render an artifact server-side via the CLI helper:
|
||||
# Render any artifact manually (the producing commands do this automatically):
|
||||
node plugins/voyage/scripts/render-artifact.mjs \
|
||||
.claude/projects/2026-05-09-feature/plan.md \
|
||||
--out /tmp/plan.html
|
||||
.claude/projects/2026-05-09-feature/plan.md
|
||||
# → writes .claude/projects/2026-05-09-feature/plan.html, prints the path
|
||||
```
|
||||
|
||||
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.
|
||||
> **Removed in v5.0.0.** v4.2/v4.3 shipped a ~388 KB bespoke playground SPA +
|
||||
> `/trekrevise` + Handover 8 (annotation → revision). A browser walkthrough
|
||||
> found it borderline unusable, and it duplicated the official `/playground`
|
||||
> plugin's `document-critique` / `diff-review` templates. All of it — the SPA,
|
||||
> the command, the supporting `lib/` modules, the anchor parser, the Playwright
|
||||
> e2e suite — was deleted. See [CHANGELOG.md](CHANGELOG.md) § v5.0.0.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -685,7 +657,7 @@ Borrowed pattern from `llm-security` (commit `97c5c9d`); extending the plugin sh
|
|||
|
||||
### Handover contracts
|
||||
|
||||
`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the file formats that pass between the four pipeline commands (brief → research → plan → execute). When you fork the plugin or extend a stage, that document tells you what every producer must write and what every consumer is allowed to assume. It also documents the *external* contract for `architecture/overview.md` (owned by an opt-in upstream architect plugin, not bundled) — discovery only, drift-warn never drift-fail.
|
||||
`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the file formats that pass between the pipeline commands (seven handovers: brief → research, research → plan, architecture → plan, plan → execute, progress.json resume, review → plan, `.session-state.local.json`). When you fork the plugin or extend a stage, that document tells you what every producer must write and what every consumer is allowed to assume. It also documents the *external* contract for `architecture/overview.md` (owned by an opt-in upstream architect plugin, not bundled) — discovery only, drift-warn never drift-fail.
|
||||
|
||||
### PreCompact resume integrity (CC v2.1.105+)
|
||||
|
||||
|
|
@ -695,7 +667,7 @@ The `pre-compact-flush.mjs` hook directly fixes the documented P0 in `docs/treke
|
|||
|
||||
**Infrastructure-as-code (IaC) gets reduced value.** The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like `architecture-mapper` and `test-strategist` produce less useful output for IaC. Use trekplan for the structural plan, then supplement IaC-specific steps manually.
|
||||
|
||||
**v4.3.0 — 3 known re-review findings deferred to v4.3.1.** A Sesjon 13–18 independent-review remediation closed all 11 findings from the first `/trekreview`, but a re-review found 3 new ones in the remediation code: `87069b35` (`renderScreenshotGallery` interpolates `screenshots[].dataUrl` raw into an `<img src>` — defense-in-depth only; *not* exploitable from the operator file-load path, only via the `window.__voyage.scheduleRender` hook which needs JS already running in the page), `4cc3bfc9` (a backtick template literal as an ES `import` specifier in `commands/trekplan.md:745` Phase 9 — SyntaxError; the documented fallback keeps `plan.md` valid, just without `plan_critic`), and `c6c64a58` (no test covers the gallery `dataUrl` injection path). A plan-critic-reviewed Wave-4 remediation plan is ready; v4.3.1 ships the fixes. See [CHANGELOG.md](CHANGELOG.md) § "Known issues — deferred to v4.3.1".
|
||||
**Rendered HTML is read-only.** `scripts/render-artifact.mjs` produces a static, self-contained view for browsing — it is not an editor. To revise an artifact from operator feedback, run the `/playground` plugin (`document-critique`) on the `.md` and paste its prompt back. The markdown subset the renderer supports covers what the artifact templates emit (headings, lists, code fences, tables, links, blockquotes, bold/italic, inline code); exotic markdown extensions are not rendered.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue