open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

chore(voyage): release v5.0.0 — remove bespoke playground + /trekrevise + Handover 8; render produced artifacts to HTML + link, annotate via /playground

Browse source 
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:
Kjell Tore Guttormsen 2026-05-12 14:05:07 +02:00
commit 916d30f63e
96 changed files with 620 additions and 14716 deletions
Download patch file Download diff file Expand all files Collapse all files

302
plugins/voyage/tests/lib/doc-consistency.test.mjs
View file

@ -80,7 +80,7 @@ test('commands/trekexecute.md still parses v1.7 plan schema', () => {
test('settings.json has only known top-level scopes after Spor 0 cleanup', () => {
const cfg = JSON.parse(read('settings.json'));
const known = ['trekplan', 'trekresearch', 'trekrevise'];
const known = ['trekplan', 'trekresearch'];
for (const k of Object.keys(cfg)) {
assert.ok(known.includes(k), `Unknown top-level scope in settings.json: ${k}`);
}
@ -94,10 +94,9 @@ test('settings.json no longer carries vestigial exploration block', () => {
'agentTeam block was vestigial — should be deleted in v3.1.0 Spor 0');
});
test('CLAUDE.md mentions all seven pipeline commands', () => {
test('CLAUDE.md mentions all six pipeline commands', () => {
// v4.1 Step 21 — added /trekcontinue to coverage (was 5/6 before).
// v4.2 Step 12 — added /trekrevise (Handover 8 producer), bringing the
// canonical pipeline to seven commands.
// v5.0.0 — /trekrevise removed (bespoke playground retired); back to six.
const md = read('CLAUDE.md');
for (const c of [
'/trekbrief',
@ -105,7 +104,6 @@ test('CLAUDE.md mentions all seven pipeline commands', () => {
'/trekplan',
'/trekexecute',
'/trekreview',
'/trekrevise',
'/trekcontinue',
]) {
assert.ok(md.includes(c), `CLAUDE.md missing reference to ${c}`);
@ -261,7 +259,6 @@ const PIPELINE_COMMANDS = [
'trekplan.md',
'trekexecute.md',
'trekreview.md',
'trekrevise.md',
'trekcontinue.md',
];
@ -403,246 +400,87 @@ test('commands/trekplan.md Phase 8 seals Opus-4.7 schema-drift defense', () => {
);
});
// --- v4.2 Step 12 — Handover 8 + annotation pipeline pins ---
// --- v5.0.0 — bespoke playground + /trekrevise + Handover 8 removed ---
//
// CLAUDE.md / README.md / CHANGELOG / annotation-quickstart pins are deferred
// to Step 13 (post-write of those files). Step 12 only pins HANDOVER-CONTRACTS,
// templates, scaffold-files, and the parseAnchors round-trip on the example
// fixture.
// The v4.2/v4.3 bespoke playground SPA, the /trekrevise command, and
// Handover 8 (annotation → revision) were removed in v5.0.0. Producing
// commands now render artifacts to self-contained HTML via
// scripts/render-artifact.mjs and direct operators at the official
// `/playground` plugin for annotation. These pins lock the removal in.
import { existsSync, statSync } from 'node:fs';
import { existsSync } from 'node:fs';
test('HANDOVER-CONTRACTS.md contains Handover 8 section (annotation → revision)', () => {
test('playground/ directory no longer exists (removed in v5.0.0)', () => {
assert.ok(
!existsSync(join(ROOT, 'playground')),
'plugins/voyage/playground/ should be deleted — the bespoke playground was retired in v5.0.0',
);
});
test('commands/trekrevise.md no longer exists (removed in v5.0.0)', () => {
assert.ok(
!existsSync(join(ROOT, 'commands/trekrevise.md')),
'/trekrevise was removed in v5.0.0 — its command file should be gone',
);
});
test('Handover 8 deleted from HANDOVER-CONTRACTS.md (back to seven handovers)', () => {
const text = read('docs/HANDOVER-CONTRACTS.md');
assert.ok(
text.includes('## Handover 8'),
'docs/HANDOVER-CONTRACTS.md should document Handover 8 (annotation → revision) — added in v4.2',
);
assert.ok(!text.includes('## Handover 8'), 'Handover 8 section should be removed in v5.0.0');
assert.ok(text.includes('## Handover 7'), 'Handover 7 must remain');
});
test('HANDOVER-CONTRACTS.md Handover 8 names annotation_digest and source_annotations', () => {
const text = read('docs/HANDOVER-CONTRACTS.md');
const h8Start = text.indexOf('## Handover 8');
assert.ok(h8Start >= 0, 'Handover 8 heading missing');
const h8End = text.indexOf('## Stability summary', h8Start);
assert.ok(h8End > h8Start, 'Stability summary heading missing — could not bound Handover 8');
const h8 = text.slice(h8Start, h8End);
assert.ok(
h8.includes('annotation_digest'),
'Handover 8 section should document the annotation_digest frontmatter field',
);
assert.ok(
h8.includes('source_annotations'),
'Handover 8 section should document the source_annotations frontmatter field',
);
assert.ok(
h8.includes('revision'),
'Handover 8 section should document the revision counter field',
);
});
test('templates/plan-template.md documents annotation revision fields', () => {
const tpl = read('templates/plan-template.md');
assert.ok(
tpl.includes('revision:'),
'plan-template.md must document optional revision counter (Handover 8)',
);
assert.ok(
tpl.includes('source_annotations:'),
'plan-template.md must document optional source_annotations list (Handover 8)',
);
assert.ok(
tpl.includes('annotation_digest'),
'plan-template.md must document optional annotation_digest field (Handover 8)',
);
});
test('templates/trekbrief-template.md documents annotation revision fields', () => {
const tpl = read('templates/trekbrief-template.md');
assert.ok(
tpl.includes('revision:'),
'trekbrief-template.md must document optional revision counter (Handover 8)',
);
assert.ok(
tpl.includes('source_annotations:'),
'trekbrief-template.md must document optional source_annotations list (Handover 8)',
);
assert.ok(
tpl.includes('annotation_digest'),
'trekbrief-template.md must document optional annotation_digest field (Handover 8)',
);
});
test('templates/trekreview-template.md documents annotation revision fields', () => {
const tpl = read('templates/trekreview-template.md');
assert.ok(
tpl.includes('revision:'),
'trekreview-template.md must document optional revision counter (Handover 8)',
);
assert.ok(
tpl.includes('source_annotations:'),
'trekreview-template.md must document optional source_annotations list (Handover 8)',
);
assert.ok(
tpl.includes('annotation_digest'),
'trekreview-template.md must document optional annotation_digest field (Handover 8)',
);
});
test('playground/ directory exists at voyage root (Handover 8 producer surface)', () => {
const playgroundDir = join(ROOT, 'playground');
assert.ok(existsSync(playgroundDir), 'playground/ directory missing');
assert.ok(statSync(playgroundDir).isDirectory(), 'playground/ is not a directory');
// Self-contained HTML must exist
assert.ok(
existsSync(join(playgroundDir, 'voyage-playground.html')),
'playground/voyage-playground.html missing — operator-facing entry point',
);
});
test('playground/ files do NOT import or reference `marked` (risk-assessor H1)', () => {
// Walk playground/ recursively. Exclude vendor/playground-design-system
// (consumed via the shared design system; not part of voyage's playground
// markdown renderer). Exclude any *MANIFEST.json files. Assert no file
// contains the standalone identifier `marked` (case-sensitive, word-boundary).
// markdown-it is the locked renderer per research-03 + alternatives table.
const playgroundDir = join(ROOT, 'playground');
assert.ok(existsSync(playgroundDir), 'playground/ directory missing — cannot verify marked-ban');
const offenders = [];
function walk(dir) {
for (const entry of readdirSync(dir)) {
const p = join(dir, entry);
const s = statSync(p);
if (s.isDirectory()) {
// Skip vendor design-system trees (shared infra, not voyage's renderer)
if (entry === 'playground-design-system') continue;
walk(p);
} else if (s.isFile()) {
// Skip vendor manifest JSONs
if (entry.endsWith('MANIFEST.json')) continue;
if (entry === 'VENDOR-MANIFEST.json') continue;
const txt = readFileSync(p, 'utf-8');
if (/\bmarked\b/.test(txt)) {
offenders.push(p.slice(ROOT.length + 1));
}
}
}
}
walk(playgroundDir);
assert.deepStrictEqual(
offenders,
[],
`playground/ files contain banned identifier "marked": ${offenders.join(', ')}. ` +
`Use markdown-it instead — see plan Alternatives table (Issue #3515 disqualifies marked).`,
);
});
test('scripts/render-artifact.mjs exists (SC1/SC11 self-render gate)', () => {
test('scripts/render-artifact.mjs exists (v5.0.0 render-and-link step)', () => {
assert.ok(
existsSync(join(ROOT, 'scripts/render-artifact.mjs')),
'scripts/render-artifact.mjs missing — required by SC1 (offline render) and SC11 (pipeline-self-eat)',
'scripts/render-artifact.mjs is required — producing commands call it to render artifacts to HTML',
);
});
test('lib/util/revision-guard.mjs exists (plan-critic M4 — atomic-write rollback guard)', () => {
assert.ok(
existsSync(join(ROOT, 'lib/util/revision-guard.mjs')),
'lib/util/revision-guard.mjs missing — required for /trekrevise rollback hygiene',
);
});
test('tests/fixtures/annotation/annotation-example.md parses cleanly via parseAnchors (ESM)', async () => {
// Plan-critic m4 — fix the SC12 require/import mixup. Use ESM dynamic import,
// not require(). The parser is pure — no I/O, no side effects.
const { parseAnchors } = await import('../../lib/parsers/anchor-parser.mjs');
const fixturePath = join(ROOT, 'tests/fixtures/annotation/annotation-example.md');
assert.ok(existsSync(fixturePath), 'tests/fixtures/annotation/annotation-example.md missing');
const result = parseAnchors(readFileSync(fixturePath, 'utf-8'));
assert.ok(
result.valid,
`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);
test('producing commands reference render-artifact.mjs (render-and-link step)', () => {
for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
assert.ok(
n >= 1 && n <= 7,
`${path} contains step ${s} — only 1.-7. permitted (single-screen quickstart)`,
read(`commands/${f}`).includes('render-artifact.mjs'),
`commands/${f} must wire the render-artifact.mjs render-and-link step (v5.0.0)`,
);
}
assert.ok(
text.includes('tests/fixtures/annotation/annotation-example.md'),
`${path} must reference the canonical example fixture for hands-on verification`,
);
});
test('commands/trekplan.md Phase 9 documents plan_critic injection via readAndUpdate (906f155d)', () => {
// Phase 9 (adversarial review) writes the plan-critic verdict back into
// plan.md frontmatter AFTER plan-review-dedup completes. The inject must
// happen post-Phase-8 (write) because Phase 8 precedes Phase 9 in the
// pipeline — the value cannot be in Phase 8's frontmatter template.
// Both the field name (plan_critic) and the inject mechanism
// (readAndUpdate from lib/util/markdown-write.mjs) must be documented
// so future maintainers can trace the contract.
const text = read('commands/trekplan.md');
assert.match(
text,
/plan_critic/,
'commands/trekplan.md must document plan_critic frontmatter field (906f155d)',
);
assert.match(
text,
/readAndUpdate/,
'commands/trekplan.md must reference readAndUpdate from lib/util/markdown-write.mjs (906f155d)',
);
test('producing commands point operators at the /playground plugin for annotation', () => {
for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
assert.ok(
read(`commands/${f}`).includes('/playground'),
`commands/${f} must mention the /playground plugin as the annotation path (v5.0.0)`,
);
}
});
test('CHANGELOG.md has v5.0.0 entry', () => {
const cl = read('CHANGELOG.md');
assert.match(cl, /## v5\.0\.0\b/, 'CHANGELOG.md must include "## v5.0.0" entry');
});
test('CHANGELOG.md retains v4.2.0 entry (history is not rewritten)', () => {
const cl = read('CHANGELOG.md');
assert.match(cl, /## v4\.2\.0\b/, 'CHANGELOG.md must keep the historical "## v4.2.0" entry');
});
test('operational files no longer reference trekrevise (v5.0.0 removal)', () => {
// Templates, the touched command/orchestrator files, settings.json, and the
// handover-contracts doc must be fully scrubbed. CLAUDE.md / README.md are
// intentionally allowed to mention /trekrevise in their "removed in v5.0.0"
// prose — those are historical notes, not live references.
const targets = [
'settings.json',
'docs/HANDOVER-CONTRACTS.md',
'templates/plan-template.md', 'templates/trekbrief-template.md', 'templates/trekreview-template.md',
'commands/trekplan.md', 'commands/trekbrief.md', 'commands/trekreview.md',
'agents/planning-orchestrator.md',
];
for (const t of targets) {
assert.ok(
!read(t).includes('trekrevise'),
`${t} still references trekrevise — it was removed in v5.0.0`,
);
}
});