docs(voyage): pin Handover 8 + templates + PIPELINE_COMMANDS update — v4.2 Step 12

plugins/voyage/tests/lib/doc-consistency.test.mjs

@@ -94,8 +94,10 @@ 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 six pipeline commands', () => {
-  // Step 21 of v4.1 — added /trekcontinue to coverage (was 5/6 before).
+test('CLAUDE.md mentions all seven 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.
   const md = read('CLAUDE.md');
   for (const c of [
     '/trekbrief',
@@ -103,6 +105,7 @@ test('CLAUDE.md mentions all six pipeline commands', () => {
     '/trekplan',
     '/trekexecute',
     '/trekreview',
+    '/trekrevise',
     '/trekcontinue',
   ]) {
     assert.ok(md.includes(c), `CLAUDE.md missing reference to ${c}`);
@@ -258,6 +261,7 @@ const PIPELINE_COMMANDS = [
   'trekplan.md',
   'trekexecute.md',
   'trekreview.md',
+  'trekrevise.md',
   'trekcontinue.md',
 ];
 
@@ -398,3 +402,164 @@ test('commands/trekplan.md Phase 8 seals Opus-4.7 schema-drift defense', () => {
     'Phase 8 should explicitly enumerate FORBIDDEN headings',
   );
 });
+
+// --- v4.2 Step 12 — Handover 8 + annotation pipeline pins ---
+//
+// 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.
+
+import { existsSync, statSync } from 'node:fs';
+
+test('HANDOVER-CONTRACTS.md contains Handover 8 section (annotation → revision)', () => {
+  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',
+  );
+});
+
+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)', () => {
+  assert.ok(
+    existsSync(join(ROOT, 'scripts/render-artifact.mjs')),
+    'scripts/render-artifact.mjs missing — required by SC1 (offline render) and SC11 (pipeline-self-eat)',
+  );
+});
+
+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 || [])}`,
+  );
+});