@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-use-cases.mjs.ejs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — docs/USE_CASES.md gate (UC-NN, INV-149)
+//
+// Emitted twin of arbiter's scripts/check-use-cases.mjs. The rules are identical; only the three
+// document paths differ, because a governed project keeps its documents flat under docs/ while
+// arbiter keeps its own under docs/internal/PRODUCT/ and docs/internal/METHOD/. That divergence is
+// pinned in .dogfood-divergences.json and is the whole of it.
+//
+// This gate does its real work HERE rather than in arbiter, and the asymmetry is structural, not
+// an omission. arbiter's feature matrix rows are cross-cutting capability areas, so one of its use
+// cases would name nearly all of them and the link would carry no information. In a product, a use
+// case names one or two features — that ratio is what makes the edge worth checking.
+// CATALOG: validates the use-case SSOT against schemas/use-case.schema.json, resolves every
+// CATALOG: featureId into the feature matrix, and joins use cases to the tabletop scenarios that
+// CATALOG: exercise them — in both directions, so neither a use case nothing walks nor a scenario
+// CATALOG: naming a use case that does not exist can hide.
+// CATALOG: rejected fold-in into check-feature-matrix.mjs because that gate reads the matrix as
+// CATALOG: the SSOT and grades each requirement's evidence chain; this one reads a different
+// CATALOG: document and treats the matrix as a NAMESPACE to resolve into. A matrix can be
+// CATALOG: perfectly graded while every use case pointing at it names a feature that was renamed.
+// CATALOG: rejected fold-in into check-tabletop-evidence.mjs because that gate owns the scenario
+// CATALOG: catalogue and its evidence; the join is read from this side because the dangling
+// CATALOG: direction that matters (a use case nothing exercises) is invisible from the scenario.
+//
+// scripts/check-use-cases.mjs
+// L1 gate (UC-NN, #2480 wave 8): a use case names an actor, a goal, and features that exist.
+//
+// Asserts:
+//   1. the SSOT's fenced JSON block parses and satisfies schemas/use-case.schema.json — which is
+//      where `featureIds` minItems:1 lives, because a use case demanding no feature is a promise
+//      with nothing behind it,
+//   2. no two use cases share an id,
+//   3. every featureId resolves to a row in the feature matrix. This is the rule the whole gate
+//      exists for: a use-case matrix decays by renames, and a dangling featureId reads exactly
+//      like coverage,
+//   4. THE JOIN, both ways — a tabletop scenario's `Exercises:` names a declared use case, and a
+//      use case whose status is `exercised` is named by some scenario. A status nobody walks is a
+//      claim, and this gate's job is to make it a checkable one,
+//   5. `status: linked` or `exercised` requires every featureId to resolve (rule 3 applies to all
+//      rows; the ladder adds no exemption, it only adds the scenario requirement).
+//
+// A missing SSOT is a SKIP, not a violation: a project need not have codified its use cases.
+// The skip prints its reason and surfaces as `verdict: "skip"` under --json, so it cannot be
+// mistaken for a pass by a reader or by runCheck's marker grep.
+//
+// --emit writes the machine projection forma consumes (schema arbiter-use-cases-v1), written ONLY
+// after every rule has passed — so an invalid set cannot produce a projection, the property the
+// milestone gate established and the reason the emit lives in the gate rather than in a generator.
+//
+// Usage: node scripts/check-use-cases.mjs [--dir <repo>] [--json] [--emit <path>]
+// Exit: 0 pass or skip, 1 violation, 2 error (INV-53).
+//
+// Exports for unit tests: extractBlock, findDuplicateIds, findDanglingFeatures, parseMatrixIds,
+//                         parseScenarioExercises, findJoinViolations, collectViolations,
+//                         useCaseProjection
+
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isMainModule, readRegularFileSync } from './lib/run-helpers.mjs'
+import { loadSchema, validateSchema } from './lib/agent-return-validate.mjs'
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const SSOT_REL = join('docs', 'USE_CASES.md')
+const MATRIX_REL = join('docs', 'FEATURE_MATRIX.md')
+const SCENARIOS_REL = join('docs', 'TABLETOP-SCENARIOS.md')
+const SCHEMA_REL = join('schemas', 'use-case.schema.json')
+const SENTINEL = 'USE_CASES'
+
+/**
+ * The fenced JSON between `<!-- USE_CASES_START -->` and `<!-- USE_CASES_END -->`. The SSOT is a
+ * markdown document carrying a machine block, exactly as the ID registry is: a use-case matrix is
+ * read by people far more often than by this gate, and a bare .json would optimise for the rarer
+ * reader.
+ * @returns {{ ok: true, document: unknown } | { ok: false, error: string }}
+ */
+export function extractBlock(text) {
+  const start = text.indexOf(`<!-- ${SENTINEL}_START -->`)
+  const end = text.indexOf(`<!-- ${SENTINEL}_END -->`)
+  if (start === -1 || end === -1 || end < start) {
+    return { ok: false, error: `has no ${SENTINEL}_START/${SENTINEL}_END sentinel pair` }
+  }
+  const fence = /```json\n([\s\S]*?)\n```/.exec(text.slice(start, end))
+  if (!fence)
+    return { ok: false, error: `has no \`\`\`json fence between the ${SENTINEL} sentinels` }
+  try {
+    return { ok: true, document: JSON.parse(fence[1]) }
+    // FAIL-OPEN-INTENT: not fail-open — a malformed block is RETURNED as a blocking result and the caller exits 1 naming the file. The audit reads a catch that does not rethrow; this one surfaces the error through its return type instead, which is the same contract the artifact-schema hook uses.
+  } catch (err) {
+    return { ok: false, error: `block is not valid JSON — ${err.message}` }
+  }
+}
+
+/** Duplicate ids. The schema validates each item alone and cannot see them. */
+export function findDuplicateIds(useCases) {
+  const seen = new Set()
+  const out = []
+  for (const uc of useCases) {
+    const id = String(uc['id'])
+    if (seen.has(id)) out.push(`duplicate use-case id "${id}"`)
+    seen.add(id)
+  }
+  return out
+}
+
+/** Every feature id declared in the matrix's table rows. */
+export function parseMatrixIds(matrixText) {
+  const ids = new Set()
+  for (const line of matrixText.split('\n')) {
+    const m = /^\|\s*([A-Za-z][A-Za-z0-9_-]*)\s*\|/.exec(line)
+    if (!m) continue
+    const id = m[1]
+    // The header row and the separator are the two non-rows that match the shape.
+    if (/^(feature_id|id|---+)$/i.test(id)) continue
+    ids.add(id)
+  }
+  return ids
+}
+
+/**
+ * featureIds naming nothing in the matrix. The decay mode this gate exists for: a matrix row gets
+ * renamed, every use case pointing at it keeps reading like coverage, and nothing notices.
+ */
+export function findDanglingFeatures(useCases, matrixIds) {
+  const out = []
+  for (const uc of useCases) {
+    for (const f of Array.isArray(uc['featureIds']) ? uc['featureIds'] : []) {
+      if (matrixIds.has(String(f))) continue
+      out.push(
+        `use case ${String(uc['id'])}: featureId "${String(f)}" is not a row in ${MATRIX_REL}`,
+      )
+    }
+  }
+  return out
+}
+
+/** `- **Exercises:** \`UC-NN\`` per scenario block, as a map of use-case id -> scenario headings. */
+export function parseScenarioExercises(text) {
+  const byUseCase = new Map()
+  for (const block of text.split(/^## (?=\d+\. )/m).slice(1)) {
+    const body = `## ${block}`
+    const heading = body.split('\n')[0].replace(/^## /, '').trim()
+    const line = /^- \*\*Exercises:\*\*\s*(.*)$/m.exec(body)
+    if (!line) continue
+    for (const m of line[1].matchAll(/UC-[0-9]{2,3}/g)) {
+      if (!byUseCase.has(m[0])) byUseCase.set(m[0], [])
+      byUseCase.get(m[0]).push(heading)
+    }
+  }
+  return byUseCase
+}
+
+/**
+ * The join, both ways. A scenario naming a use case that does not exist, and a use case CLAIMING
+ * `exercised` that no scenario walks. The second direction is the one invisible from the scenario
+ * side, which is why the join is read from here.
+ */
+export function findJoinViolations(useCases, exercises) {
+  const known = new Set(useCases.map((uc) => String(uc['id'])))
+  const out = []
+  for (const [id, headings] of exercises) {
+    if (known.has(id)) continue
+    out.push(
+      `${SCENARIOS_REL}: scenario "${headings[0]}" exercises "${id}", which is not a declared use case`,
+    )
+  }
+  for (const uc of useCases) {
+    if (String(uc['status']) !== 'exercised') continue
+    const id = String(uc['id'])
+    if (exercises.has(id)) continue
+    out.push(
+      `use case ${id} claims status "exercised" but no tabletop scenario names it — status is not a walk`,
+    )
+  }
+  return out
+}
+
+/** Every structural rule, once the document is known schema-valid. */
+export function collectViolations(useCases, matrixIds, exercises) {
+  return [
+    ...findDuplicateIds(useCases),
+    ...findDanglingFeatures(useCases, matrixIds),
+    ...findJoinViolations(useCases, exercises),
+  ]
+}
+
+function report(json, verdict, message, violations) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ verdict, message, violations }, null, 2)}\n`)
+    return
+  }
+  if (verdict === 'skip') {
+    process.stdout.write(`[SKIP] check-use-cases: ${message}\n`)
+    return
+  }
+  for (const v of violations) process.stderr.write(`check-use-cases: FAIL — ${v}\n`)
+  if (verdict === 'pass') process.stdout.write(`check-use-cases: PASS — ${message}\n`)
+}
+
+/** Rewrite `useCases.useCases[2]` as `UC-30` so a schema error names the row a reader can find. */
+export function annotateSchemaViolations(violations, useCases) {
+  return violations.map((v) =>
+    v.replace(/^useCases\.useCases\[(\d+)\]/, (_m, i) => {
+      const id = useCases[Number(i)]?.['id']
+      return id ? `use case ${String(id)}` : `use case #${i}`
+    }),
+  )
+}
+
+/**
+ * The machine projection a viewer consumes. Only what a traceability view needs: who wants what,
+ * which features it rests on, and whether a scenario has actually walked it.
+ *
+ * `exercisedBy` is DERIVED here rather than copied from the declared `status`, because the two can
+ * disagree and only one of them is checkable — the gate has just proven which scenarios name this
+ * use case, so the projection carries the measurement, not the claim.
+ * @param {Array<Record<string, unknown>>} useCases
+ * @param {Map<string, string[]>} exercises
+ */
+export function useCaseProjection(useCases, exercises) {
+  return {
+    schema: 'arbiter-use-cases-v1',
+    useCases: [...useCases]
+      .sort((a, b) => String(a['id']).localeCompare(String(b['id'])))
+      .map((uc) => {
+        const id = String(uc['id'])
+        /** @type {Record<string, unknown>} */
+        const row = {
+          id,
+          actor: uc['actor'],
+          goal: uc['goal'],
+          featureIds: [...(Array.isArray(uc['featureIds']) ? uc['featureIds'] : [])].sort(),
+          exercisedBy: (exercises.get(id) ?? []).slice().sort(),
+        }
+        // Omitted when absent rather than defaulted, so "no journey declared" stays distinguishable
+        // from "declared as belonging to none".
+        if (Array.isArray(uc['journeyIds'])) row['journeyIds'] = [...uc['journeyIds']].sort()
+        if (typeof uc['prdRef'] === 'string') row['prdRef'] = uc['prdRef']
+        if (typeof uc['status'] === 'string') row['status'] = uc['status']
+        return row
+      }),
+  }
+}
+
+/**
+ * Load the schema and validate. A schema that will not load is exit 2, not 1 (INV-53): the gate
+ * could not tell, which is a different claim from "a use case is wrong" and must not be filed as
+ * one — the emitted twin ships its schema alongside it precisely so this cannot happen silently.
+ * @returns {{ code: number } | { doc: Record<string, unknown> }}
+ */
+function validateDocument(document, json) {
+  let schema
+  try {
+    schema = loadSchema(resolve(scriptDir, '..', SCHEMA_REL))
+  } catch (err) {
+    process.stderr.write(`check-use-cases: cannot load ${SCHEMA_REL} — ${err.message}\n`)
+    return { code: 2 }
+  }
+  const violations = validateSchema(document, schema, schema, 'useCases')
+  if (violations.length === 0) return { doc: document }
+  const list = Array.isArray(document?.useCases) ? document.useCases : []
+  report(json, 'fail', 'schema violations', annotateSchemaViolations(violations, list))
+  return { code: 1 }
+}
+
+/** Write the projection. Called only after every rule has passed. */
+function emitProjection(emit, useCases, exercises, json) {
+  mkdirSync(dirname(emit), { recursive: true })
+  const doc = useCaseProjection(useCases, exercises)
+  writeFileSync(emit, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8')
+  if (!json) process.stdout.write(`check-use-cases: projection written to ${emit}\n`)
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  const i = argv.indexOf('--dir')
+  const e = argv.indexOf('--emit')
+  return {
+    root: i >= 0 && argv[i + 1] ? resolve(argv[i + 1]) : process.cwd(),
+    json: argv.includes('--json'),
+    emit: e >= 0 && argv[e + 1] ? resolve(argv[e + 1]) : null,
+  }
+}
+
+function main(argv) {
+  const { root, json, emit } = parseArgs(argv)
+  const ssot = join(root, SSOT_REL)
+  if (!existsSync(ssot)) {
+    report(json, 'skip', `${SSOT_REL} absent — no use cases codified in this project`, [])
+    return 0
+  }
+
+  const extracted = extractBlock(readRegularFileSync(ssot, 'utf-8'))
+  if (!extracted.ok) {
+    report(json, 'fail', 'unreadable SSOT', [`${SSOT_REL} ${extracted.error}`])
+    return 1
+  }
+
+  const validated = validateDocument(extracted.document, json)
+  if (validated.code !== undefined) return validated.code
+  const doc = validated.doc
+
+  const useCases = doc.useCases
+  const matrixPath = join(root, MATRIX_REL)
+  if (!existsSync(matrixPath)) {
+    // Not a skip: use cases EXIST and every one of them names features. Without the matrix the
+    // central rule cannot run, and passing anyway would report coverage this gate never checked.
+    report(json, 'fail', 'missing namespace', [
+      `${useCases.length} use case(s) declared but ${MATRIX_REL} is absent — every featureId is unresolvable`,
+    ])
+    return 1
+  }
+  const matrixIds = parseMatrixIds(readRegularFileSync(matrixPath, 'utf-8'))
+
+  const scenariosPath = join(root, SCENARIOS_REL)
+  const exercises = existsSync(scenariosPath)
+    ? parseScenarioExercises(readRegularFileSync(scenariosPath, 'utf-8'))
+    : new Map()
+
+  const violations = collectViolations(useCases, matrixIds, exercises)
+  if (violations.length > 0) {
+    report(json, 'fail', 'structural violations', violations)
+    return 1
+  }
+  if (emit) emitProjection(emit, useCases, exercises, json)
+  const walked = useCases.filter((uc) => exercises.has(String(uc['id']))).length
+  report(
+    json,
+    'pass',
+    `${useCases.length} use case(s), every featureId resolves, ${walked} exercised by a scenario`,
+    [],
+  )
+  return 0
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    process.exit(main(process.argv.slice(2)))
+  } catch (err) {
+    // Exit 2, not 1 (INV-53): 1 means a use case is wrong, 2 means the gate could not tell.
+    process.stderr.write(`check-use-cases: ERROR — ${err?.stack ?? err}\n`)
+    process.exit(2)
+  }
+}

package/dist/templates/scripts/check-validator-helptext.mjs.ejs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// <%= projectName %> — validator --help text coverage check (INV-89)
+// Validates that all anti-drift check-*.mjs scripts support a --help flag.
+// Exits 0 when all anti-drift validators have --help; exits 1 when any are missing it.
+// Part of the anti-drift validator family (W6).
+//
+// Usage: node scripts/check-validator-helptext.mjs [--dir <path>] [--help]
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    [
+      'Usage: node scripts/check-validator-helptext.mjs [options]',
+      '',
+      'Validates that all anti-drift check-*.mjs scripts support a --help flag.',
+      'Exits 0 when all validators have --help; exits 1 when any are missing it.',
+      '',
+      'Options:',
+      '  --dir <path>    Root directory to scan (default: cwd)',
+      '  --help, -h      Show this help and exit',
+      '',
+    ].join('\n'),
+  );
+  process.exit(0);
+}
+
+const dirArg = args.indexOf('--dir');
+const CWD = dirArg >= 0 && args[dirArg + 1] ? resolve(args[dirArg + 1]) : process.cwd();
+
+const SCRIPTS_DIR = join(CWD, 'scripts');
+
+// Anti-drift validator family marker
+const FAMILY_MARKER = 'anti-drift validator family (W6)';
+
+let violations = 0;
+let checked = 0;
+
+if (!existsSync(SCRIPTS_DIR)) {
+  process.stdout.write('check-validator-helptext: SKIP — no scripts/ directory found\n');
+  // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+  process.stdout.write('[SKIP] no scripts/ directory found\n');
+  process.exit(0);
+}
+
+const entries = readdirSync(SCRIPTS_DIR, { withFileTypes: true });
+for (const entry of entries) {
+  if (!entry.isFile()) continue;
+  if (!entry.name.startsWith('check-') || !entry.name.endsWith('.mjs')) continue;
+
+  const fullPath = join(SCRIPTS_DIR, entry.name);
+  let content;
+  try {
+    content = readFileSync(fullPath, 'utf-8');
+  } catch {
+    continue;
+  }
+
+  // Only check anti-drift family scripts
+  if (!content.includes(FAMILY_MARKER)) continue;
+
+  checked++;
+  if (!content.includes('--help')) {
+    process.stderr.write(`[FAIL] ${entry.name}: no --help flag support found (INV-89)\n`);
+    violations++;
+  }
+}
+
+if (violations > 0) {
+  process.stderr.write(
+    `check-validator-helptext: FAIL — ${violations}/${checked} validator(s) missing --help support (INV-89)\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `check-validator-helptext: OK — all ${checked} anti-drift validators support --help (INV-89)\n`,
+);
+process.exit(0);

package/dist/templates/scripts/check-wiki-lint.mjs.ejs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: Validates wiki/ for broken wikilinks, orphan pages, stale source hashes, and citation integrity (INV-116).
+// CATALOG: Rejected fold-in into check-doc-links.mjs because [[wikilinks]] have distinct syntax from markdown links.
+// CATALOG: Rejected fold-in into check-ssot-core.mjs because wiki/ is generated content, not a curated SSOT inventory.
+//
+// Usage:
+//   node scripts/check-wiki-lint.mjs              # run against wiki/ in CWD
+//   node scripts/check-wiki-lint.mjs --wiki-dir <dir>   # run against a specific wiki dir
+//   node scripts/check-wiki-lint.mjs --assert-stale     # keep the stale dimension for an untracked wiki (#2585)
+// Exits 0 if all clean; exits 1 if any violation found.
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const wikiDirArg = args.find((a) => a.startsWith('--wiki-dir='))?.split('=')[1]
+  ?? (args[args.indexOf('--wiki-dir') + 1] !== undefined && !args[args.indexOf('--wiki-dir') + 1].startsWith('-')
+    ? args[args.indexOf('--wiki-dir') + 1]
+    : null);
+const root = process.cwd();
+const WIKI_DIR = wikiDirArg ? resolve(wikiDirArg) : join(root, 'wiki');
+
+if (!existsSync(WIKI_DIR)) {
+  process.stdout.write('  check-wiki-lint: wiki/ not found — skipping (bootstrap mode)\n');
+  process.exit(0);
+}
+
+const mdFiles = readdirSync(WIKI_DIR).filter((f) => f.endsWith('.md'));
+if (mdFiles.length === 0) {
+  process.stdout.write('  check-wiki-lint: wiki/ is empty — skipping (bootstrap mode)\n');
+  process.exit(0);
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return {};
+  const fm = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    fm[line.slice(0, colon).trim()] = line.slice(colon + 1).trim().replace(/^['"]|['"]$/g, '');
+  }
+  return fm;
+}
+
+function extractWikilinks(text) {
+  return [...text.matchAll(/\[\[([^\]]+?)\]\]/g)].map((m) => m[1].trim()).filter(Boolean);
+}
+
+function slug(filename) {
+  return filename.replace(/\.md$/, '').toLowerCase();
+}
+
+const pages = new Map();
+for (const file of mdFiles) {
+  const text = readFileSync(join(WIKI_DIR, file), 'utf-8');
+  const fm = parseFrontmatter(text);
+  const links = extractWikilinks(text).map((l) => l.toLowerCase());
+  pages.set(slug(file), { file, fm, links });
+}
+
+let violations = 0;
+
+for (const [, { file, links }] of pages) {
+  for (const link of links) {
+    if (!pages.has(link)) {
+      process.stdout.write(
+        `  check-wiki-lint [broken-link]: wiki/${file} references [[${link}]] which does not exist\n`,
+      );
+      violations++;
+    }
+  }
+}
+
+const indexSlug = 'index';
+if (!pages.has(indexSlug)) {
+  process.stdout.write('  check-wiki-lint [orphan]: wiki/INDEX.md not found\n');
+  violations++;
+} else {
+  const reachable = new Set([indexSlug]);
+  const queue = [indexSlug];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const page = pages.get(current);
+    if (!page) continue;
+    for (const link of page.links) {
+      if (!reachable.has(link) && pages.has(link)) {
+        reachable.add(link);
+        queue.push(link);
+      }
+    }
+  }
+  for (const [s, { file }] of pages) {
+    if (s === indexSlug) continue;
+    if (!reachable.has(s)) {
+      process.stdout.write(
+        `  check-wiki-lint [orphan]: wiki/${file} is unreachable from INDEX.md\n`,
+      );
+      violations++;
+    }
+  }
+}
+
+// stale: asserted only when the wiki dir is git-tracked (#2585). An untracked (generated,
+// gitignored) wiki goes stale as a side effect of merging; that is not a review property.
+const ls = spawnSync('git', ['ls-files', '--', WIKI_DIR], { encoding: 'utf-8', cwd: root });
+const wikiTracked = ls.status === 0 && ls.stdout.trim().length > 0;
+// --assert-stale: a caller asking about freshness itself (arbiter obsidian --validate-only) keeps it.
+const assertStale = wikiTracked || args.includes('--assert-stale');
+if (!assertStale) {
+  process.stdout.write(
+    '  check-wiki-lint [stale:skip] — wiki dir is not git-tracked (generated, gitignored), so ' +
+      'page freshness is local derived state, not a review property (#2585); ' +
+      'run `node scripts/gen-wiki.mjs` to refresh it\n',
+  );
+}
+
+for (const [, { file, fm }] of assertStale ? pages : []) {
+  const sourcePath = fm['source'];
+  const sourceSha = fm['source_sha'];
+  if (!sourcePath || !sourceSha) continue;
+  const absSource = join(root, sourcePath);
+  if (!existsSync(absSource)) continue;
+  try {
+    const actualSha = execFileSync('git', ['hash-object', absSource], { encoding: 'utf-8', cwd: root }).trim();
+    if (actualSha !== sourceSha) {
+      process.stdout.write(`  check-wiki-lint [stale]: wiki/${file} source_sha is stale\n`);
+      violations++;
+    }
+  } catch { /* git not available */ }
+}
+
+let trackedFiles = new Set();
+try {
+  const lsOutput = execFileSync('git', ['ls-files', '--', 'docs/'], { encoding: 'utf-8', cwd: root });
+  trackedFiles = new Set(lsOutput.trim().split('\n').filter(Boolean));
+} catch { /* git not available */ }
+
+for (const [, { file, fm }] of pages) {
+  if (slug(file) === 'index') continue;
+  const sourcePath = fm['source'];
+  if (!sourcePath) {
+    process.stdout.write(`  check-wiki-lint [citation]: wiki/${file} missing source: field\n`);
+    violations++;
+    continue;
+  }
+  if (trackedFiles.size > 0 && !trackedFiles.has(sourcePath)) {
+    process.stdout.write(`  check-wiki-lint [citation]: wiki/${file} source '${sourcePath}' not tracked\n`);
+    violations++;
+  }
+}
+
+if (violations === 0) {
+  process.stdout.write(`  check-wiki-lint: ${mdFiles.length} wiki pages OK\n`);
+  process.exit(0);
+} else {
+  process.stdout.write(`  check-wiki-lint: ${violations} violation(s) found\n`);
+  process.exit(1);
+}

package/dist/templates/scripts/check-workflow-docs-sync.mjs.ejs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// <%= projectName %> — workflow documentation sync checker (INV-89)
+// Validates that all workflow files are documented in docs/ directory.
+// Exits 0 when all workflows are documented; exits 0 (WARN) when undocumented found.
+// Part of the anti-drift validator family (W6).
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write([
+    'Usage: node scripts/check-workflow-docs-sync.mjs [options]',
+    '',
+    'Validates that all workflow files are documented in docs/ directory.',
+    'Exits 0 when all workflows are documented; exits 0 (WARN) when undocumented found.',
+    '',
+    'Options:',
+    '  --dir <path>    Root directory to scan (default: cwd)',
+    '  --help, -h      Show this help and exit',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+const dirArg = args.indexOf('--dir');
+const CWD = dirArg >= 0 && args[dirArg + 1] ? resolve(args[dirArg + 1]) : process.cwd();
+const WORKFLOWS_DIR = join(CWD, '.github', 'workflows');
+const DOCS_DIR = join(CWD, 'docs');
+const EXEMPT_PREFIXES = ['_'];
+
+if (!existsSync(WORKFLOWS_DIR)) {
+  process.stdout.write('check-workflow-docs-sync: SKIP — no .github/workflows/ directory\n');
+  // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+  process.stdout.write('[SKIP] no .github/workflows/ directory\n');
+  process.exit(0);
+}
+if (!existsSync(DOCS_DIR)) {
+  process.stdout.write('check-workflow-docs-sync: SKIP — no docs/ directory\n');
+  // #2052: recognized marker so runCheck surfaces SKIP, not PASS, in the gate summary.
+  process.stdout.write('[SKIP] no docs/ directory\n');
+  process.exit(0);
+}
+
+function gatherDocContent(dir) {
+  let content = '';
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return content;
+  }
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      content += gatherDocContent(full);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      try {
+        content += readFileSync(full, 'utf-8') + '\n';
+      } catch { /* ignore */ }
+    }
+  }
+  return content;
+}
+
+const docContent = gatherDocContent(DOCS_DIR);
+let violations = 0;
+let checked = 0;
+
+const wfEntries = readdirSync(WORKFLOWS_DIR, { withFileTypes: true });
+for (const entry of wfEntries) {
+  if (!entry.isFile()) continue;
+  if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml')) continue;
+  const name = basename(entry.name, entry.name.endsWith('.yml') ? '.yml' : '.yaml');
+  if (EXEMPT_PREFIXES.some((p) => entry.name.startsWith(p))) continue;
+  checked++;
+  if (!docContent.includes(name) && !docContent.includes(entry.name)) {
+    process.stderr.write(`[WARN] workflow "${entry.name}" not referenced in any docs/ markdown (INV-89)\n`);
+    violations++;
+  }
+}
+
+if (violations > 0) {
+  process.stdout.write(
+    `check-workflow-docs-sync: WARN — ${violations}/${checked} workflow(s) not documented in docs/ (INV-89)\n`,
+  );
+  // Warning only — docs are often written after implementation
+  process.exit(0);
+}
+process.stdout.write(`check-workflow-docs-sync: OK — all ${checked} workflows referenced in docs/ (INV-89)\n`);
+process.exit(0);