ktg-plugin-marketplace/plugins/voyage/tests/lib/doc-consistency.test.mjs

// tests/lib/doc-consistency.test.mjs
// Pin invariants between prose (CLAUDE.md, README.md) and source files
// (agents/*.md, commands/*.md, templates/, settings.json).
//
// When this test fails, fix the source-of-truth — do NOT rewrite the test to
// hide drift. Borrowed pattern from llm-security commit 97c5c9d.

import { test } from 'node:test';
import { strict as assert } from 'node:assert';
import { readFileSync, readdirSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseDocument } from '../../lib/util/frontmatter.mjs';

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, '..', '..');

function read(rel) { return readFileSync(join(ROOT, rel), 'utf-8'); }
function listMd(rel) { return readdirSync(join(ROOT, rel)).filter(f => f.endsWith('.md')); }

test('CLAUDE.md agents table row count == agents/*.md file count', () => {
  const md = read('CLAUDE.md');
  const agentFiles = listMd('agents');
  const agentTable = md.split('## Agents')[1] || '';
  const tableSection = agentTable.split('\n## ')[0];
  const dataRows = tableSection
    .split('\n')
    .filter(l => l.startsWith('|') && !l.match(/^\|[\s-]+\|/) && !l.match(/^\|\s*Agent\s*\|/));
  assert.equal(
    dataRows.length,
    agentFiles.length,
    `Drift: ${agentFiles.length} agent files vs ${dataRows.length} CLAUDE.md table rows. ` +
    `Sync agents/ ↔ CLAUDE.md.`,
  );
});

test('CLAUDE.md commands table mentions every commands/*.md file', () => {
  const md = read('CLAUDE.md');
  const commandFiles = listMd('commands');
  for (const f of commandFiles) {
    const cmdName = `/${f.replace(/\.md$/, '')}`;
    assert.ok(
      md.includes(cmdName),
      `commands/${f} not mentioned in CLAUDE.md (looked for ${cmdName})`,
    );
  }
});

test('every command frontmatter name matches its filename', () => {
  for (const f of listMd('commands')) {
    const text = read(`commands/${f}`);
    const doc = parseDocument(text);
    if (!doc.valid) continue;
    const expected = f.replace(/\.md$/, '');
    if (doc.parsed.frontmatter && doc.parsed.frontmatter.name !== undefined) {
      assert.equal(
        doc.parsed.frontmatter.name,
        expected,
        `commands/${f} frontmatter.name="${doc.parsed.frontmatter.name}" should be "${expected}"`,
      );
    }
  }
});

test('templates/plan-template.md declares plan_version: 1.7', () => {
  const tpl = read('templates/plan-template.md');
  assert.match(tpl, /plan_version:\s*['"]?1\.7['"]?/);
});

test('commands/trekexecute.md still parses v1.7 plan schema', () => {
  const cmd = read('commands/trekexecute.md');
  const tpl = read('templates/plan-template.md');
  const tplVersion = (tpl.match(/plan_version:\s*['"]?([\d.]+)['"]?/) || [])[1];
  assert.ok(tplVersion, 'templates/plan-template.md missing plan_version');
  assert.ok(
    cmd.includes(`plan_version`) || cmd.includes(`Step N:`) || cmd.includes('### Step '),
    'commands/trekexecute.md should reference v1.7 plan-schema parsing',
  );
});

test('settings.json has only known top-level scopes after Spor 0 cleanup', () => {
  const cfg = JSON.parse(read('settings.json'));
  const known = ['trekplan', 'trekresearch'];
  for (const k of Object.keys(cfg)) {
    assert.ok(known.includes(k), `Unknown top-level scope in settings.json: ${k}`);
  }
});

test('settings.json no longer carries vestigial exploration block', () => {
  const cfg = JSON.parse(read('settings.json'));
  assert.equal(cfg.trekplan?.exploration, undefined,
    'exploration block was vestigial — should be deleted in v3.1.0 Spor 0');
  assert.equal(cfg.trekplan?.agentTeam, undefined,
    'agentTeam block was vestigial — should be deleted in v3.1.0 Spor 0');
});

test('CLAUDE.md mentions all six pipeline commands', () => {
  // v4.1 Step 21 — added /trekcontinue to coverage (was 5/6 before).
  // v5.0.0 — /trekrevise removed (bespoke playground retired); back to six.
  const md = read('CLAUDE.md');
  for (const c of [
    '/trekbrief',
    '/trekresearch',
    '/trekplan',
    '/trekexecute',
    '/trekreview',
    '/trekcontinue',
  ]) {
    assert.ok(md.includes(c), `CLAUDE.md missing reference to ${c}`);
  }
});

test('HANDOVER-CONTRACTS.md contains Handover 6 section', () => {
  const text = read('docs/HANDOVER-CONTRACTS.md');
  assert.ok(
    text.includes('## Handover 6'),
    'docs/HANDOVER-CONTRACTS.md should document Handover 6 (review → plan)',
  );
});

test('HANDOVER-CONTRACTS.md contains Handover 7 section (session-state)', () => {
  const text = read('docs/HANDOVER-CONTRACTS.md');
  assert.ok(
    text.includes('## Handover 7'),
    'docs/HANDOVER-CONTRACTS.md should document Handover 7 (.session-state.local.json) ' +
    'consumed by /trekcontinue',
  );
  assert.ok(
    text.includes('.session-state.local.json'),
    'Handover 7 section should name the artifact path',
  );
});

test('review-validator has CLI shim', () => {
  const text = read('lib/validators/review-validator.mjs');
  assert.ok(
    text.includes('import.meta.url === '),
    'lib/validators/review-validator.mjs should expose the standard CLI shim ' +
    '(if (import.meta.url === `file://${process.argv[1]}`)) so commands can call it from Bash',
  );
});

test('session-state-validator has CLI shim', () => {
  const text = read('lib/validators/session-state-validator.mjs');
  assert.ok(
    text.includes('import.meta.url === '),
    'lib/validators/session-state-validator.mjs should expose the standard CLI shim ' +
    '(if (import.meta.url === `file://${process.argv[1]}`)) so /trekcontinue can call it from Bash',
  );
});

test('next-session-prompt-validator has CLI shim', () => {
  const text = read('lib/validators/next-session-prompt-validator.mjs');
  assert.ok(
    text.includes('import.meta.url === '),
    'lib/validators/next-session-prompt-validator.mjs should expose the standard CLI shim ' +
    '(if (import.meta.url === `file://${process.argv[1]}`)) so /trekcontinue Phase 1.5 can call it from Bash',
  );
});

test('HANDOVER-CONTRACTS.md Handover 7 documents § Lifecycle subsection', () => {
  const text = read('docs/HANDOVER-CONTRACTS.md');
  const h7Start = text.indexOf('## Handover 7');
  assert.ok(h7Start >= 0, 'Handover 7 heading missing');
  const h7End = text.indexOf('## Stability summary', h7Start);
  assert.ok(h7End > h7Start, 'Stability summary heading missing — could not bound Handover 7');
  const h7 = text.slice(h7Start, h7End);
  assert.ok(
    h7.includes('Lifecycle'),
    'Handover 7 section should include a § Lifecycle subsection (SC-5 stale-file principle)',
  );
});

test('HANDOVER-CONTRACTS.md Handover 7 § Lifecycle names --cleanup and produced_by contract', () => {
  const text = read('docs/HANDOVER-CONTRACTS.md');
  const h7Start = text.indexOf('## Handover 7');
  const h7End = text.indexOf('## Stability summary', h7Start);
  const h7 = text.slice(h7Start, h7End);
  assert.ok(
    h7.includes('--cleanup'),
    'Handover 7 § Lifecycle should mention --cleanup as the operator-invoked stale-file remover',
  );
  assert.ok(
    h7.includes('produced_by'),
    'Handover 7 § Lifecycle should document the produced_by frontmatter contract for NEXT-SESSION-PROMPT.local.md',
  );
});

test('CLAUDE.md mentions /trekcontinue command', () => {
  const md = read('CLAUDE.md');
  assert.ok(
    md.includes('/trekcontinue') || md.includes('trekcontinue'),
    'CLAUDE.md should document /trekcontinue in the Commands table ' +
    '(added in v3.3.0 alongside the new command file)',
  );
});

test('rule-catalogue has exactly 12 entries', async () => {
  const mod = await import('../../lib/review/rule-catalogue.mjs');
  assert.strictEqual(
    mod.RULE_CATALOGUE.length,
    12,
    'lib/review/rule-catalogue.mjs RULE_CATALOGUE size invariant: must be 12 (v1.0 baseline)',
  );
});

test('headless-launch-template.md mirrors Phase 2.6 hardenings', () => {
  const tpl = read('templates/headless-launch-template.md');
  for (const needle of [
    'GIT_OPTIONAL_LOCKS',
    '--max-turns',
    '--max-budget-usd',
    '--append-system-prompt-file',
    'SHARED_CONTEXT_FILE',
    'SAFETY_PREAMBLE',
    'git push origin',
    'GH #36071',
    'push-before-cleanup',
  ]) {
    assert.ok(
      tpl.includes(needle),
      `templates/headless-launch-template.md should include "${needle}" (Step 10 mirrors Phase 2.6)`,
    );
  }
});

test('Phase 9 prose mandates parallel single-message dispatch + inline dedup', () => {
  const cmd = read('commands/trekplan.md');
  const orch = read('agents/planning-orchestrator.md');
  // Single-message reinforcement appears in both (command + orchestrator)
  assert.ok(
    cmd.includes('single assistant message turn'),
    'commands/trekplan.md Phase 9 should reinforce single-message parallel dispatch',
  );
  assert.ok(
    orch.includes('single assistant message turn'),
    'agents/planning-orchestrator.md Phase 6 should mirror the single-message parallel-dispatch contract',
  );
  // Dedup CLI shim is wired in both
  assert.ok(
    cmd.includes('plan-review-dedup.mjs'),
    'commands/trekplan.md Phase 9 should call lib/review/plan-review-dedup.mjs after both reviewers complete',
  );
  assert.ok(
    orch.includes('plan-review-dedup.mjs'),
    'agents/planning-orchestrator.md Phase 6 should reference the dedup helper',
  );
});

// --- v4.1 Step 21 — pin --profile + phase_models on the 6 commands ---
//
// CLAUDE.md / README.md pinning is deferred to Step 22 (post-write of
// those documents). Step 21 only verifies command-file content, which
// was written in Step 7 (Wave 3).

const PIPELINE_COMMANDS = [
  'trekbrief.md',
  'trekresearch.md',
  'trekplan.md',
  'trekexecute.md',
  'trekreview.md',
  'trekcontinue.md',
];

test('every pipeline command-file documents the --profile flag (SC #20)', () => {
  for (const f of PIPELINE_COMMANDS) {
    const text = read(`commands/${f}`);
    assert.match(
      text,
      /--profile\b/,
      `commands/${f}: --profile flag is required documentation in v4.1`,
    );
  }
});

test('command-files mentioning model profiles use canonical name `phase_models`', () => {
  // Reject legacy / brainstormed alternatives that would confuse readers.
  const FORBIDDEN = ['model_per_phase', 'phase_to_model', 'profile_phase_models'];
  for (const f of PIPELINE_COMMANDS) {
    const text = read(`commands/${f}`);
    for (const bad of FORBIDDEN) {
      assert.ok(
        !text.includes(bad),
        `commands/${f}: forbidden alias "${bad}" — canonical name is "phase_models"`,
      );
    }
  }
});

test('at least one pipeline command-file references `phase_models` canonical name', () => {
  // Sanity: not every command has to enumerate phase_models inline (e.g.
  // trekbrief and trekcontinue may only mention --profile), but ≥ 1
  // command-file must spell out the canonical name so the regression test
  // pins drift.
  let mentioned = 0;
  for (const f of PIPELINE_COMMANDS) {
    if (read(`commands/${f}`).includes('phase_models')) mentioned += 1;
  }
  assert.ok(
    mentioned >= 1,
    `expected ≥ 1 command-file to mention canonical name "phase_models", got ${mentioned}`,
  );
});

// --- v4.1 Step 22 — post-write CLAUDE.md / README.md pinning ---
//
// Plan-critic Blocker 2 fix: Step 21 only pinned commands/*.md (which
// are written in Step 7 / Wave 3). Step 22 writes the top-level docs
// and extends pinning here so doc-consistency stays green AFTER Step 22.

test('CLAUDE.md documents --profile flag', () => {
  const md = read('CLAUDE.md');
  assert.match(
    md,
    /--profile\b/,
    'CLAUDE.md must document the --profile flag (v4.1 SC #20)',
  );
});

test('CLAUDE.md uses canonical name `phase_models`', () => {
  const md = read('CLAUDE.md');
  assert.match(
    md,
    /phase_models/,
    'CLAUDE.md must use canonical name "phase_models" (v4.1 SC #20)',
  );
  for (const bad of ['model_per_phase', 'phase_to_model', 'profile_phase_models']) {
    assert.ok(
      !md.includes(bad),
      `CLAUDE.md must NOT use legacy alias "${bad}"`,
    );
  }
});

test('README.md documents --profile flag for all 6 commands', () => {
  // SG1: README flag-table coverage is gating for SC #20. README is the
  // primary discovery surface for new users.
  const md = read('README.md');
  // Top-level Profile system section is required so the flag is
  // discoverable independent of per-command tables.
  assert.match(md, /## Profile system/, 'README.md missing top-level "## Profile system" section');
  // Every per-command Modes table must include --profile (count of
  // --profile occurrences should be ≥ 6 — one per command + Profile
  // system section).
  const profileMentions = (md.match(/--profile\b/g) || []).length;
  assert.ok(
    profileMentions >= 6,
    `README.md must mention --profile ≥ 6 times (one per command + section), got ${profileMentions}`,
  );
});

test('CHANGELOG.md has v4.1.0 entry', () => {
  const cl = read('CHANGELOG.md');
  assert.match(
    cl,
    /## v4\.1\.0\b/,
    'CHANGELOG.md must include "## v4.1.0" entry per Keep-a-Changelog 1.1.0',
  );
});

test('docs/profiles.md exists and documents Custom.yaml authoring', () => {
  const dp = read('docs/profiles.md');
  assert.ok(dp.length > 1000, 'docs/profiles.md must be substantive (> 1000 chars)');
  // Must document custom-profile authoring (Step 22 manifest must_contain
  // pattern: "Custom.yaml" — case-insensitive match handled here as
  // /[Cc]ustom[. ]/ to allow either "custom.yaml" or "Custom profile" prose).
  assert.match(
    dp,
    /[Cc]ustom\.yaml|[Cc]ustom profile|<custom>\.yaml/,
    'docs/profiles.md must document custom profile authoring',
  );
});

test('commands/trekplan.md Phase 8 seals Opus-4.7 schema-drift defense', () => {
  const cmd = read('commands/trekplan.md');
  // Locate Phase 8 section
  const phase8Start = cmd.indexOf('## Phase 8');
  assert.ok(phase8Start >= 0, 'Phase 8 heading missing');
  const phase8End = cmd.indexOf('## Phase 9', phase8Start);
  assert.ok(phase8End > phase8Start, 'Phase 9 heading missing — could not bound Phase 8');
  const phase8 = cmd.slice(phase8Start, phase8End);
  // Required regex source-of-truth references
  assert.ok(
    phase8.includes('STEP_HEADING_REGEX'),
    'Phase 8 should inline STEP_HEADING_REGEX so format contract survives without orchestrator-doc loading',
  );
  assert.ok(
    phase8.includes('FORBIDDEN_HEADING_REGEX'),
    'Phase 8 should inline FORBIDDEN_HEADING_REGEX (Step 7 — schema-drift seal)',
  );
  // Required validator self-check
  assert.ok(
    phase8.includes('plan-validator.mjs --strict'),
    'Phase 8 should mandate post-write `plan-validator.mjs --strict` self-check',
  );
  // Forbidden-headings list (literal "FORBIDDEN" appears more than once: in regex const + in human-readable list)
  assert.ok(
    /FORBIDDEN/.test(phase8),
    'Phase 8 should explicitly enumerate FORBIDDEN headings',
  );
});

// --- v5.0.0 / v5.0.1 — bespoke playground removed; /playground invocation explicit ---
//
// v5.0.0 removed the bespoke playground SPA, /trekrevise, and Handover 8.
// v5.0.1 dropped the v5.0.0 stop-gap (scripts/render-artifact.mjs) and made
// the producing commands print a literal, copy-paste-ready /playground
// document-critique invocation instead. These pins lock both removals in
// AND pin the new copy-paste invocation as the operator-facing contract.

import { existsSync } from 'node:fs';

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'), 'Handover 8 section should be removed in v5.0.0');
  assert.ok(text.includes('## Handover 7'), 'Handover 7 must remain');
});

test('scripts/render-artifact.mjs is still removed (v5.0.1 + v5.0.2)', () => {
  assert.ok(
    !existsSync(join(ROOT, 'scripts/render-artifact.mjs')),
    'scripts/render-artifact.mjs should be deleted — v5.0.1 dropped the standalone HTML render; v5.0.2 kept it removed (annotate.mjs is the replacement)',
  );
});

test('scripts/annotate.mjs exists (v5.0.2 operator-annotation HTML generator)', () => {
  assert.ok(
    existsSync(join(ROOT, 'scripts/annotate.mjs')),
    'scripts/annotate.mjs is required — producing commands call it to build the operator-annotation HTML',
  );
});

test('producing commands reference scripts/annotate.mjs (v5.0.2 render-and-link step)', () => {
  // v5.0.0 → v5.0.1 → v5.0.2 chain: v5.0.0 added an HTML render that didn't
  // afford annotation; v5.0.1 pointed at /playground document-critique (which
  // pre-generates Claude's suggestions, not operator-driven annotation); v5.0.2
  // ships scripts/annotate.mjs — an operator-driven annotation surface where
  // the OPERATOR clicks lines and writes their own notes. Pin the wiring.
  for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
    assert.ok(
      read(`commands/${f}`).includes('scripts/annotate.mjs'),
      `commands/${f} must invoke scripts/annotate.mjs to build the operator-annotation HTML (v5.0.2)`,
    );
  }
});

test('producing commands no longer print the v5.0.1 /playground document-critique line', () => {
  // v5.0.1 told operators to copy-paste "/playground build a document-critique
  // playground for X" — but that flow pre-generates Claude's suggestions. The
  // operator asked for their own annotations, not a critique of Claude's.
  // v5.0.2 removes that line from the producing commands' final report.
  for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
    assert.ok(
      !read(`commands/${f}`).includes('/playground build a document-critique'),
      `commands/${f} must not print the v5.0.1 /playground document-critique invocation — v5.0.2 replaces it with annotate.mjs`,
    );
  }
});

test('producing commands tell the operator the flow is THEIR own annotations', () => {
  // Pin language: every producing command's prose must mention that the
  // OPERATOR drives annotation, not Claude. Phrase variants are allowed
  // ("YOUR OWN note", "operator drives", etc.) — we look for the operator-
  // ownership signal.
  for (const f of ['trekbrief.md', 'trekplan.md', 'trekreview.md']) {
    const text = read(`commands/${f}`);
    assert.ok(
      /YOUR OWN|operator drives|your own/i.test(text),
      `commands/${f} must signal that the operator drives annotation (v5.0.2 contract)`,
    );
  }
});

test('package.json still has no "npm run render" script (removed in v5.0.1)', () => {
  const pkg = JSON.parse(read('package.json'));
  assert.equal(
    pkg.scripts && pkg.scripts.render,
    undefined,
    'package.json scripts.render should remain gone',
  );
});

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 has v5.0.1 entry', () => {
  const cl = read('CHANGELOG.md');
  assert.match(cl, /## v5\.0\.1\b/, 'CHANGELOG.md must include "## v5.0.1" entry');
});

test('CHANGELOG.md has v5.0.2 entry', () => {
  const cl = read('CHANGELOG.md');
  assert.match(cl, /## v5\.0\.2\b/, 'CHANGELOG.md must include "## v5.0.2" 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`,
    );
  }
});