@getarbiter/cli 0.5.0

package/dist/templates/scripts/check-smoke-journeys.mjs.ejs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: INV-137 enforcement. Reads smoke-journeys.json at repo root; asserts the declared
+// CATALOG:   login/CRUD/authz acceptance floor is COVERED — every `required` journey must have
+// CATALOG:   ≥1 matching spec (glob-based, OR semantics). Reuses INV-124's algorithm but with
+// CATALOG:   INV-126's fail-closed default: applicability is archetype-computed, so a journey
+// CATALOG:   applicable to the archetype is `required` (absent status ⇒ required, never silently
+// CATALOG:   n/a). `n/a` needs a rationale ≥20 chars; all-n/a is a hard fail. A whole archetype
+// CATALOG:   with no interactive journeys declares applicable:false ⇒ SKIP (like INV-126
+// CATALOG:   required:false). SKIP when manifest absent. Boundary: file PRESENCE only — assertion
+// CATALOG:   quality is INV-118, and CI execution is the render-smoke/e2e lane's job. Because
+// CATALOG:   applicability is genuine (archetype-computed), a wired-but-dead CI job can never be
+// CATALOG:   laundered into a legitimate `n/a` here.
+// Exit codes (INV-53): 0=PASS/SKIP, 1=policy violation, 2=schema/walk/path-traversal error
+// Usage: node scripts/check-smoke-journeys.mjs [--help]
+import { readFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { globMatch, validateGlob, walkRepo } from './lib/glob-walk.mjs'
+
+const ROOT = resolve(process.cwd())
+const MANIFEST_PATH = join(ROOT, 'smoke-journeys.json')
+const ARBITER_PATH = join(ROOT, 'arbiter.json')
+const REASON_MIN_LEN = 20
+// #2043 (AC-2043.1): the login/CRUD/authz acceptance floor. A project overrides the
+// declared set via arbiter.json's smokeJourneys.requiredJourneys (schema-validated,
+// src/config/schema.ts); absent ⇒ this trio.
+const DEFAULT_REQUIRED_JOURNEYS = ['auth', 'crud', 'authz']
+
+const HELP = `Usage: node scripts/check-smoke-journeys.mjs [--help]
+
+Enforces that every declared smoke journey in smoke-journeys.json is COVERED by at
+least one real spec file — the login/CRUD/authz acceptance floor (INV-137).
+
+Rules:
+  applicable:false   — SKIP (archetype has no interactive login/CRUD/authz journeys).
+  status:"required"  — at least one glob must match ≥1 file in the repo tree.
+                       OR semantics: passes if ANY glob matches. Absent status ⇒ required
+                       (fail-closed: a journey applicable to the archetype is never silently n/a).
+  status:"n/a"       — must carry a rationale ≥${REASON_MIN_LEN} chars (auditable, genuine
+                       non-applicability only — NOT a "the CI job is dead" escape hatch).
+  All n/a            — exit 1 (a fully-skipped floor defeats the gate).
+
+SKIP:
+  When smoke-journeys.json is absent (e.g. non-governed projects), gate exits 0.
+  Re-init with arbiter init to generate the manifest.
+
+Exit codes:
+  0 — pass or SKIP (manifest absent / applicable:false)
+  1 — policy violation
+  2 — schema error, walk error, or path-traversal glob detected`
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write(`${HELP}\n`)
+  process.exit(0)
+}
+
+function globCount(pattern, allFiles) {
+  return allFiles.filter((f) => globMatch(pattern, f)).length
+}
+
+// Reads+parses arbiter.json. Returns null when absent/racily-removed (nothing to compare
+// against); exits directly (INV-96 fail-closed) on a real read or parse error.
+function loadArbiterConfig() {
+  if (!existsSync(ARBITER_PATH)) return null
+
+  let raw
+  try {
+    raw = readFileSync(ARBITER_PATH, 'utf-8')
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null // race: file removed between existsSync and read
+    process.stderr.write(
+      `[check-smoke-journeys] ERROR — cannot read arbiter.json: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    process.exit(2)
+  }
+
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    process.stderr.write(
+      `[check-smoke-journeys] FAIL — arbiter.json is malformed (${err instanceof Error ? err.message : String(err)}); ` +
+        `cannot verify archetype — fix the file or run arbiter update to regenerate\n`,
+    )
+    process.exit(1)
+  }
+}
+
+// Archetype mismatch guard: stale manifests detectable at gate time. A missing/racily-removed
+// arbiter.json legitimately skips the guard (loadArbiterConfig returns null); a CORRUPT one
+// already exited fail-closed above — silently skipping the archetype check is exactly when
+// manifest drift is most likely to hide.
+function checkArchetypeMatch(manifest, arbiter) {
+  if (!arbiter) return
+
+  const mismatch =
+    arbiter.archetype && manifest.archetype && arbiter.archetype !== manifest.archetype
+  if (!mismatch) return
+
+  process.stderr.write(
+    `[check-smoke-journeys] FAIL — manifest generated for archetype ${manifest.archetype} ` +
+      `but arbiter.json declares ${arbiter.archetype} — run arbiter update to regenerate\n`,
+  )
+  process.exit(1)
+}
+
+// AC-2043.1: the manifest must DECLARE every journey in the configured trio (by id) —
+// not just the ones a team happened to write. A missing member is a hard fail naming it,
+// independent of the coverage checks below (a subset that IS fully covered still fails).
+// Gated on arbiter.json being present/loadable: an ungoverned project (no arbiter.json)
+// has no configured floor to compare against, so the pre-#2043 declared-only behavior
+// stands — same precedent as checkArchetypeMatch above.
+function checkTrioFloor(manifest, arbiter) {
+  if (!arbiter) return
+
+  const smokeJourneys = isRecord(arbiter.smokeJourneys) ? arbiter.smokeJourneys : undefined
+  const requiredJourneys =
+    smokeJourneys &&
+    Array.isArray(smokeJourneys.requiredJourneys) &&
+    smokeJourneys.requiredJourneys.length > 0
+      ? smokeJourneys.requiredJourneys
+      : DEFAULT_REQUIRED_JOURNEYS
+
+  const declaredIds = new Set(
+    manifest.journeys.filter((j) => j && typeof j.id === 'string').map((j) => j.id),
+  )
+  const missing = requiredJourneys.filter((id) => !declaredIds.has(id))
+  if (missing.length === 0) return
+
+  process.stderr.write(
+    `[check-smoke-journeys] FAIL — smoke-journeys.json is missing required journey(s): ` +
+      `${missing.join(', ')} — declare each (status required or n/a with rationale) or ` +
+      `adjust smokeJourneys.requiredJourneys in arbiter.json\n`,
+  )
+  process.exit(1)
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function checkNaJourney(id, name, journey) {
+  const rationale = typeof journey.rationale === 'string' ? journey.rationale.trim() : ''
+  if (rationale.length >= REASON_MIN_LEN) return false
+  process.stderr.write(
+    `[check-smoke-journeys] FAIL — journey ${id} (${name}) is n/a but rationale is ` +
+      `${rationale.length} chars (min ${REASON_MIN_LEN}): "${rationale}"\n`,
+  )
+  return true
+}
+
+function checkRequiredJourney(id, name, journey, allFiles) {
+  const globs = Array.isArray(journey.globs) ? journey.globs : []
+  if (globs.length === 0) {
+    process.stderr.write(
+      `[check-smoke-journeys] FAIL — required journey ${id} (${name}) has no glob patterns ` +
+        `— add patterns or mark as n/a with rationale\n`,
+    )
+    return true
+  }
+
+  // Validate globs for path traversal
+  for (const g of globs) {
+    if (!validateGlob(g)) {
+      process.stderr.write(
+        `[check-smoke-journeys] ERROR — glob "${g}" in journey ${id} contains path traversal ` +
+          `or is absolute — only relative, non-traversal globs are allowed\n`,
+      )
+      process.exit(2)
+    }
+  }
+
+  // OR semantics: passes if ANY glob matches at least one file
+  const found = globs.some((g) => globCount(g, allFiles) > 0)
+  if (found) return false
+
+  process.stderr.write(
+    `[check-smoke-journeys] FAIL — journey ${id} (${name}) declared but empty ` +
+      `— no files matched: ${globs.join(', ')}\n`,
+  )
+  return true
+}
+
+// Validates one journey. Returns { isNa, violated } — main() aggregates counts/exit codes so
+// exit(2) schema-error paths (path-traversal globs) stay a hard process exit from here.
+function checkJourney(journey, allFiles) {
+  const id = typeof journey.id === 'string' ? journey.id : '?'
+  const name = typeof journey.name === 'string' ? journey.name : id
+  // Fail-closed default: only an explicit "n/a" is n/a; anything else (incl. an absent
+  // status) is REQUIRED — a journey applicable to the archetype cannot be silently skipped.
+  const isNa = journey.status === 'n/a'
+  const violated = isNa
+    ? checkNaJourney(id, name, journey)
+    : checkRequiredJourney(id, name, journey, allFiles)
+  return { isNa, violated }
+}
+
+// Loads smoke-journeys.json. SKIP-exits when absent; exits fail-closed on invalid JSON.
+function loadManifest() {
+  if (!existsSync(MANIFEST_PATH)) {
+    process.stdout.write('[check-smoke-journeys] SKIP — smoke-journeys.json not found\n')
+    process.exit(0)
+  }
+  try {
+    return JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`[check-smoke-journeys] ERROR — invalid JSON: ${err.message}\n`)
+    process.exit(2)
+  }
+}
+
+async function main() {
+  const manifest = loadManifest()
+  const arbiterConfig = loadArbiterConfig()
+  checkArchetypeMatch(manifest, arbiterConfig)
+
+  // Applicability SKIP (INV-126 precedent): an archetype with no interactive login/CRUD/authz
+  // journeys declares applicable:false. Checked BEFORE the all-n/a / rationale guards so a
+  // legitimately non-applicable archetype never trips them. Only an EXPLICIT false skips —
+  // an absent flag is fail-closed (falls through to the journeys checks).
+  if (manifest.applicable === false) {
+    process.stdout.write(
+      '[check-smoke-journeys] SKIP — applicable:false (archetype has no interactive smoke journeys)\n',
+    )
+    process.exit(0)
+  }
+
+  if (!Array.isArray(manifest.journeys)) {
+    process.stderr.write(
+      '[check-smoke-journeys] ERROR — manifest.journeys must be an array (schema error)\n',
+    )
+    process.exit(2)
+  }
+
+  checkTrioFloor(manifest, arbiterConfig)
+
+  // Collect all repo files once
+  const allFiles = walkRepo(ROOT)
+
+  let violations = 0
+  let naCount = 0
+  const totalJourneys = manifest.journeys.length
+
+  for (const journey of manifest.journeys) {
+    const { isNa, violated } = checkJourney(journey, allFiles)
+    if (isNa) naCount++
+    if (violated) violations++
+  }
+
+  // All-n/a hard fail
+  if (naCount > 0 && naCount === totalJourneys) {
+    process.stderr.write(
+      `[check-smoke-journeys] FAIL — all ${totalJourneys} declared journey(s) are n/a — ` +
+        `a fully-skipped floor defeats the gate\n`,
+    )
+    process.exit(1)
+  }
+
+  if (violations > 0) {
+    process.stderr.write(`[check-smoke-journeys] FAIL — ${violations} violation(s) found\n`)
+    process.exit(1)
+  }
+
+  process.stdout.write(`[check-smoke-journeys] OK — ${totalJourneys} journey(s) verified\n`)
+  process.exit(0)
+}
+
+try {
+  await main()
+} catch (err) {
+  process.stderr.write(`[check-smoke-journeys] ERROR — unexpected: ${err.message}\n`)
+  process.exit(2)
+}

package/dist/templates/scripts/check-solo-reactivation.mjs.ejs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * check-solo-reactivation.mjs — Single-developer exception reactivation check
+ *
+ * Enforces the reactivation trigger for trunk-solo+<%= governanceLevel %> projects (#1250).
+ * Per docs/governance/SOLO_DEV_EXCEPTION.md §11.10(k):
+ *   - Fires (exit 1) when ≥3 distinct authors are active in the trailing 30 days
+ *   - Fires (exit 1) when EXTERNAL_AUDIT=true environment variable is set
+ *
+ * Runs nightly via .github/workflows/06-nightly-lite.yml
+ * Generated by arbiter — do not edit manually.
+ */
+import { execFileSync } from 'node:child_process'
+
+const AUTHOR_THRESHOLD = 3
+const LOOKBACK_DAYS = 30
+
+/**
+ * Count distinct author emails in git log for the trailing N days.
+ * Case-insensitive deduplication (git may emit different casings).
+ * Returns 0 if git log produces no output (new repo or no commits in window).
+ */
+function countDistinctAuthors(days) {
+  try {
+    const since = `${days} days ago`
+    const output = execFileSync('git', ['log', `--since=${since}`, '--format=%ae'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+
+    if (!output) return 0
+
+    const emails = output
+      .split('\n')
+      .map((e) => e.trim().toLowerCase())
+      .filter(Boolean)
+    return new Set(emails).size
+  } catch (err) {
+    // git not available or not a git repository — fail closed
+    console.error('check-solo-reactivation: git not available or not a git repo — failing closed')
+    console.error(err)
+    process.exit(1)
+  }
+}
+
+function main() {
+  const externalAudit = process.env['EXTERNAL_AUDIT'] === 'true'
+  const authorCount = countDistinctAuthors(LOOKBACK_DAYS)
+
+  const authorThresholdExceeded = authorCount >= AUTHOR_THRESHOLD
+  const triggered = authorThresholdExceeded || externalAudit
+
+  if (!triggered) {
+    console.log(
+      `check-solo-reactivation: OK — ${authorCount} distinct author(s) in trailing ${LOOKBACK_DAYS}d (threshold: ${AUTHOR_THRESHOLD}). External audit: ${externalAudit}.`,
+    )
+    process.exit(0)
+  }
+
+  // Trigger: print clear remediation instructions and exit 1
+  console.error('')
+  console.error('╔══════════════════════════════════════════════════════════════╗')
+  console.error('║  SOLO-DEV EXCEPTION REACTIVATION TRIGGERED                   ║')
+  console.error('╚══════════════════════════════════════════════════════════════╝')
+  console.error('')
+
+  if (authorThresholdExceeded) {
+    console.error(
+      `REASON: ${authorCount} distinct author(s) detected in trailing ${LOOKBACK_DAYS} days`,
+    )
+    console.error(`        (threshold: ≥${AUTHOR_THRESHOLD} authors triggers reactivation)`)
+  }
+
+  if (externalAudit) {
+    console.error('REASON: EXTERNAL_AUDIT=true environment variable is set')
+  }
+
+  console.error('')
+  console.error('REQUIRED ACTIONS:')
+  console.error('')
+  console.error('  1. Add CODEOWNERS file with required reviewers:')
+  console.error('     echo "* @your-reviewer" > CODEOWNERS')
+  console.error('')
+  console.error('  2. Update arbiter.json to require peer review:')
+  console.error('     node dist/cli.js configure --set collaborationMode=peer-review')
+  console.error('')
+  console.error('  3. Regenerate governance files:')
+  console.error('     node dist/cli.js update')
+  console.error('')
+  console.error('  4. Enable branch protection with required reviewer:')
+  console.error('     node scripts/apply-branch-protection.mjs')
+  console.error('')
+  console.error(
+    'See docs/governance/SOLO_DEV_EXCEPTION.md for the full reactivation procedure.',
+  )
+  console.error('')
+
+  process.exit(1)
+}
+
+main()

package/dist/templates/scripts/check-sources.mjs.ejs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — docs/SOURCES.md gate (INV-147)
+// Generated by arbiter (src/templates/scripts/check-sources.mjs.ejs)
+//
+// Ported from arbiter's own scripts/check-sources.mjs (#2480 wave 5). The rule is identical; only
+// the registry's path differs, because a governed project keeps its documents flat under docs/
+// while arbiter keeps its own under docs/internal/PRODUCT/. Nothing else is scoped down: the
+// property this proves needs no arbiter-internal catalog, only a repository-contained excerpt.
+//
+// scripts/check-sources.mjs
+// L1 gate, tier 1: a cited source is quotable, and the quotation checks out.
+//
+// Why a hash AND a substring check, when either alone looks sufficient:
+//   - the substring check alone passes on an excerpt someone edited after the fact, so the
+//     evidence could drift away from what was actually read;
+//   - the hash alone proves the excerpt is unchanged but says nothing about whether the project's
+//     quotation appears in it at all.
+// Together they make "this source says X" falsifiable without a network call, which is what lets
+// the rule run in a pre-commit hook on a machine with no credentials.
+//
+// Explicitly NOT done here, and not by accident:
+//   - the `url` is recorded provenance, never dereferenced. A gate that fails when a website is
+//     down fails for a reason unrelated to the claim it guards; link-liveness is a separate,
+//     advisory, networked concern.
+//   - relevance ("does this source actually support the decision") is a judgement, not a decidable
+//     property. Tier 2 puts that to independent skeptics; tier 1 refuses to pretend it can settle
+//     it deterministically.
+//
+// Usage: node scripts/check-sources.mjs [--dir <repo>] [--json]
+// Exit: 0 pass or skip, 1 violation, 2 error (INV-53).
+//
+// Exports for unit tests: extractSourcesBlock, findDuplicateSourceIds, checkExcerptEvidence
+
+import { readRegularFileSync } from './lib/run-helpers.mjs'
+import { existsSync, realpathSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
+import { loadSchema, validateSchema } from './lib/agent-return-validate.mjs'
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const SOURCES_REL = join('docs', 'SOURCES.md')
+const SCHEMA_REL = join('schemas', 'source-record.schema.json')
+const START = '<!-- SOURCES_START -->'
+const END = '<!-- SOURCES_END -->'
+
+/**
+ * Pull the fenced JSON out of the sentinel block. Throws on a malformed block: a registry that
+ * cannot be parsed is an ERROR, never an empty list, because "no sources" and "the file is broken"
+ * must not produce the same green.
+ * @param {string} markdown
+ * @returns {{ sources: unknown[] }}
+ */
+export function extractSourcesBlock(markdown) {
+  const start = markdown.indexOf(START)
+  const end = markdown.indexOf(END)
+  if (start < 0 || end < 0 || end < start) {
+    throw new Error(`SOURCES.md is missing its ${START} / ${END} sentinel block`)
+  }
+  const inner = markdown.slice(start + START.length, end)
+  const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(inner)
+  if (!fence) throw new Error('SOURCES.md sentinel block contains no fenced JSON')
+  return JSON.parse(fence[1])
+}
+
+/** @param {Array<Record<string, unknown>>} sources @returns {string[]} */
+export function findDuplicateSourceIds(sources) {
+  const seen = new Set()
+  const violations = []
+  for (const s of sources) {
+    const id = String(s['id'])
+    if (seen.has(id)) violations.push(`duplicate source id "${id}"`)
+    seen.add(id)
+  }
+  return violations
+}
+
+/**
+ * Tier 1 proper, for one source: the excerpt exists, hashes to what was recorded, and contains
+ * every quoted span literally.
+ * @param {Record<string, unknown>} source
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function checkExcerptEvidence(source, root) {
+  const id = String(source['id'])
+  const rel = String(source['excerpt_path'] ?? '')
+  const violations = []
+  if (!rel) return [`${id}: no excerpt_path — a source with no committed excerpt cannot be checked`]
+  const abs = resolve(root, rel)
+  if (!isContained(root, abs)) {
+    return [`${id}: excerpt path ${rel} resolves outside the repository`]
+  }
+  const indexRel = relative(root, abs)
+  if (!existsSync(abs)) {
+    return [
+      `${id}: excerpt file ${rel} does not exist — the quotation has nothing to check against`,
+    ]
+  }
+  const physicalRoot = realpathSync(root)
+  const physicalExcerpt = realpathSync(abs)
+  if (!isContained(physicalRoot, physicalExcerpt)) {
+    return [`${id}: excerpt path ${rel} resolves outside the repository`]
+  }
+  const physicalRel = relative(physicalRoot, physicalExcerpt)
+  if (!isGitIndexed(root, indexRel) || !isGitIndexed(physicalRoot, physicalRel)) {
+    return [
+      `${id}: excerpt file ${rel} or its resolved content is not tracked by Git — commit it, ` +
+        `or stage a newly added excerpt before this pre-commit check`,
+    ]
+  }
+  const raw = readRegularFileSync(abs)
+  violations.push(...hashMismatch(id, raw, String(source['content_hash'])))
+  violations.push(...unquotedCitations(id, raw.toString('utf-8'), rel, source['citations']))
+  return violations
+}
+
+/** True when candidate is within root, including root itself. */
+function isContained(root, candidate) {
+  const path = relative(root, candidate)
+  return path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path)
+}
+
+/** Git-index membership accepts both committed files and files staged for their first commit. */
+function isGitIndexed(root, rel) {
+  try {
+    const indexed = execFileSync(
+      'git',
+      ['--literal-pathspecs', 'ls-files', '--error-unmatch', '-z', '--', rel],
+      { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+    return indexed.equals(Buffer.from(`${rel}\0`))
+    // FAIL-OPEN-INTENT: Git cannot prove index membership, so this source is rejected.
+  } catch {
+    return false
+  }
+}
+
+/** The excerpt must still BE the excerpt that was read. @returns {string[]} */
+function hashMismatch(id, raw, recorded) {
+  const actual = createHash('sha256').update(raw).digest('hex')
+  if (actual === recorded) return []
+  return [
+    `${id}: excerpt hash mismatch — recorded ${recorded.slice(0, 16)}…, file now hashes to ` +
+      `${actual.slice(0, 16)}…. The committed evidence is no longer the evidence that was read; ` +
+      `re-take the excerpt and re-record its hash.`,
+  ]
+}
+
+/** Every quoted span must appear verbatim — this is the half a hash cannot cover. @returns {string[]} */
+function unquotedCitations(id, text, rel, citations) {
+  const violations = []
+  for (const citation of Array.isArray(citations) ? citations : []) {
+    const quoted = String(/** @type {Record<string, unknown>} */ (citation)['quoted_text'] ?? '')
+    if (quoted && !text.includes(quoted)) {
+      violations.push(
+        `${id}: quoted_text is not a literal substring of ${rel} — ` +
+          `"${quoted.slice(0, 60)}${quoted.length > 60 ? '…' : ''}"`,
+      )
+    }
+  }
+  return violations
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  const i = argv.indexOf('--dir')
+  return {
+    root: i >= 0 && argv[i + 1] ? resolve(argv[i + 1]) : process.cwd(),
+    json: argv.includes('--json'),
+  }
+}
+
+/** @param {boolean} json @param {string} verdict @param {string} message @param {string[]} violations */
+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-sources: ${message}\n`)
+    return
+  }
+  for (const v of violations) process.stderr.write(`check-sources: FAIL — ${v}\n`)
+  if (verdict === 'pass') process.stdout.write(`check-sources: PASS — ${message}\n`)
+}
+
+/** @param {string[]} argv @returns {number} */
+function main(argv) {
+  const { root, json } = parseArgs(argv)
+  const path = join(root, SOURCES_REL)
+  if (!existsSync(path)) {
+    report(json, 'skip', `${SOURCES_REL} absent — this project cites no external sources`, [])
+    return 0
+  }
+
+  let doc
+  try {
+    doc = extractSourcesBlock(readRegularFileSync(path, 'utf-8'))
+  } catch (err) {
+    process.stderr.write(`check-sources: ${SOURCES_REL} could not be parsed — ${err.message}\n`)
+    return 2
+  }
+
+  let schema
+  try {
+    schema = loadSchema(resolve(scriptDir, '..', SCHEMA_REL))
+  } catch (err) {
+    process.stderr.write(`check-sources: cannot load ${SCHEMA_REL} — ${err.message}\n`)
+    return 2
+  }
+
+  const schemaViolations = validateSchema(doc, schema, schema, 'sources')
+  if (schemaViolations.length > 0) {
+    report(json, 'fail', 'schema violations', schemaViolations)
+    return 1
+  }
+
+  const sources = /** @type {Array<Record<string, unknown>>} */ (doc.sources)
+  const violations = [
+    ...findDuplicateSourceIds(sources),
+    ...sources.flatMap((s) => checkExcerptEvidence(s, root)),
+  ]
+  if (violations.length > 0) {
+    report(json, 'fail', 'source evidence violations', violations)
+    return 1
+  }
+  const quotes = sources.reduce(
+    (n, s) => n + (Array.isArray(s['citations']) ? s['citations'].length : 0),
+    0,
+  )
+  report(json, 'pass', `${sources.length} source(s), ${quotes} quotation(s) verified literal`, [])
+  return 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    process.exit(main(process.argv.slice(2)))
+  } catch (err) {
+    process.stderr.write(`check-sources: ${err?.stack ?? err}\n`)
+    process.exit(2)
+  }
+}

package/dist/templates/scripts/check-ssot-core.mjs.ejs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// <%= projectName %> — SSOT core set gate (INV-47)
+// Gate: verify every file listed in SSOT_CORE_SET.md exists on disk.
+// Exits 0: all entries exist or no SSOT_CORE_SET.md found (bootstrap mode).
+// Exits 1: one or more listed files are missing.
+// Part of the anti-drift validator family (W6).
+// Usage: node scripts/check-ssot-core.mjs [--help]
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  process.stdout.write('Usage: node scripts/check-ssot-core.mjs [--help]\nVerify every file listed in SSOT_CORE_SET.md exists on disk.\n');
+  process.exit(0);
+}
+
+const SSOT_FILE = join(process.cwd(), 'docs', 'METHOD', 'SSOT_CORE_SET.md');
+
+if (!existsSync(SSOT_FILE)) {
+  console.log('  check-ssot-core: no SSOT_CORE_SET.md found — skipping (bootstrap mode)');
+  process.exit(0);
+}
+
+const content = readFileSync(SSOT_FILE, 'utf-8');
+
+const PATH_ITEM = /^[ \t]*-[ \t]+`([^`]+)`/gm;
+
+const missing = [];
+for (const match of content.matchAll(PATH_ITEM)) {
+  const filePath = match[1];
+  const abs = join(process.cwd(), filePath);
+  if (!existsSync(abs)) {
+    missing.push(filePath);
+  }
+}
+
+if (missing.length === 0) {
+  console.log('  check-ssot-core: all SSOT_CORE_SET entries exist');
+  process.exit(0);
+}
+
+console.log(`  check-ssot-core: ${missing.length} missing file(s) listed in SSOT_CORE_SET.md:`);
+for (const f of missing) {
+  console.log(`    missing: ${f}`);
+}
+process.exit(1);