@intentset/cli 0.1.0

package/src/outputs.ts

@@ -0,0 +1,65 @@
+/**
+ * Explicit outputs (`graph --out`, `architecture check --write-baseline`,
+ * `evidence import --out`, `publish --out`) may write only what they are
+ * named to write, and never a file the repository is made of: a document in
+ * scope, the configuration, the registries, the architecture configuration
+ * or an exception record, a source file, a manifest. Tools never rewrite
+ * those (invariant 1). A target outside the repository is the caller's
+ * business.
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+import { ARCHITECTURE_CONFIG_PATH, EXCEPTIONS_PATTERNS } from "@intentset/architecture";
+import { matchAny } from "./glob.ts";
+import { CONFIG_PATH, type Repository } from "./repository.ts";
+
+const SOURCE = /\.(?:[cm]?[jt]sx?|md|ya?ml)$/;
+const MANIFEST = /(?:^|\/)(?:package\.json|tsconfig[^/]*\.json)$/;
+
+/** The target as a repository-relative POSIX path, "" for the root itself, or null when it lies outside the root. */
+export function insideRoot(root: string, target: string): string | null {
+  const path = relative(root, target);
+  if (path === "") return "";
+  if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) return null;
+  return path.split(sep).join("/");
+}
+
+/**
+ * Why `target` (absolute) may not be written, or null when it may. A document
+ * that would land in scope is refused even when it does not exist yet, since
+ * the next run would read it as canonical.
+ */
+export function outputProblem(repo: Repository, target: string): string | null {
+  const path = insideRoot(repo.root, target);
+  if (path === null) return null;
+  if (path === "") return "is the repository root";
+  const reads = new Set([
+    CONFIG_PATH,
+    ARCHITECTURE_CONFIG_PATH,
+    ...(repo.config.registries === null ? [] : [repo.config.registries]),
+    ...repo.inputs.map((input) => input.path),
+  ]);
+  if (reads.has(path) || matchAny(EXCEPTIONS_PATTERNS, path)) return "is a file the repository reads";
+  if (matchAny(repo.config.scope, path) && !matchAny(repo.config.ignore, path)) {
+    return "is inside the documents' scope, where it would be read as canonical";
+  }
+  if (existsSync(target) && (SOURCE.test(path) || MANIFEST.test(path))) return "is a source file or manifest";
+  return null;
+}
+
+/**
+ * Why a directory may not receive generated output, or null when it may: it
+ * is the root, or a Markdown file written into it would fall inside the
+ * documents' scope, where generated files would sooner or later be read as
+ * canonical. An ignored directory, such as dist/, is the place for them.
+ */
+export function outputDirProblem(repo: Repository, dir: string): string | null {
+  const path = insideRoot(repo.root, dir);
+  if (path === null) return null;
+  if (path === "") return "is the repository root";
+  const probe = `${path}/generated.md`;
+  if (matchAny(repo.config.scope, probe) && !matchAny(repo.config.ignore, probe)) {
+    return "is inside the documents' scope; write generated output to an ignored directory such as dist/";
+  }
+  return null;
+}

package/src/reports.ts

@@ -0,0 +1,103 @@
+/**
+ * The sections a level adds to a report, as text and as JSON. Every count
+ * says what it counts and over what; what could not be checked is listed as
+ * not checked, never folded into a pass (invariant 6); coverage is counts
+ * and never a percentage (Core §8).
+ */
+import type { ArchitectureResult } from "@intentset/architecture";
+import type { ClaimCounts } from "@intentset/verification";
+import { count } from "./output.ts";
+import type { EvidenceRun, Session } from "./session.ts";
+
+export function architectureLines(result: ArchitectureResult, skipped: readonly string[]): string[] {
+  const s = result.summary;
+  const lines = [
+    `Architecture (${s.level}, ${s.mode} mode): ${count(s.slices, "active slice")}; ` +
+      `${count(s.filesClaimed, "file")} claimed, ${s.filesUnclaimed} unclaimed, ${s.outOfScope} out of scope (counted, not reported); ` +
+      `${count(s.edges, "import edge")}, ${s.crossSliceEdges} across slices; ${count(s.cycles, "cycle")}; ` +
+      `${s.excepted} excepted, ${s.baselined} baselined, ${count(s.baselineStale, "stale baseline entry", "stale baseline entries")}`,
+    `Not checked, so not a pass (${s.unresolved.length}):${s.unresolved.length === 0 ? " none" : ""}`,
+    ...s.unresolved.map((item) => `  - ${item}`),
+    `Left to review, which this check cannot decide from source (${s.reviewRequired.length}):`,
+    ...s.reviewRequired.map((item) => `  - ${item}`),
+  ];
+  if (skipped.length > 0) {
+    lines.push(`Not read, over 1 MiB (${skipped.length}):`, ...skipped.map((path) => `  - ${path}`));
+  }
+  return lines;
+}
+
+function ofCounts(part: ClaimCounts, whole: ClaimCounts): string {
+  return [
+    `${part.behaviors} of ${count(whole.behaviors, "behavior")}`,
+    `${part.rules} of ${count(whole.rules, "rule")}`,
+    `${part.scenarios} of ${count(whole.scenarios, "scenario")}`,
+  ].join(", ");
+}
+
+export function evidenceLines(run: EvidenceRun): string[] {
+  const { coverage, classification } = run.check;
+  const snap = run.snapshot;
+  const scope =
+    snap.scope === null || snap.scope === undefined
+      ? "every product and release"
+      : `${snap.scope.product} ${snap.scope.release}`;
+  const from = run.files.length === 0 ? "no evidence files" : run.files.join(", ");
+  const d = coverage.denominator;
+  const lines = [
+    `Evidence: ${count(run.records, "run record")} from ${from}; assessed at ${snap.commit === null ? "no commit" : `commit ${snap.commit}`}, graph ${snap.graphHash}, for ${scope}`,
+    `Coverage over ${count(d.behaviors, "behavior")}, ${count(d.rules, "rule")} and ${count(d.scenarios, "scenario")} that are not retired:`,
+    `  linked:    ${ofCounts(coverage.linked, d)}  (${coverage.measures.linked})`,
+    `  verified:  ${ofCounts(coverage.verified, d)}  (${coverage.measures.verified})`,
+    `  manual:    linked ${ofCounts(coverage.manual.linked, d)}; verified ${ofCounts(coverage.manual.verified, d)}`,
+    `  automated: linked ${ofCounts(coverage.automated.linked, d)}; verified ${ofCounts(coverage.automated.verified, d)}`,
+    "Verifications at this snapshot:",
+  ];
+  const ids = Object.keys(classification.verifications);
+  if (ids.length === 0) lines.push("  none");
+  for (const id of ids) {
+    const v = classification.verifications[id];
+    lines.push(`  ${id}  ${v.method}  ${v.status}${v.note === undefined ? "" : `  (${v.note})`}`);
+  }
+  lines.push(
+    `Not checked, so not a pass (${coverage.unresolved.length}):${coverage.unresolved.length === 0 ? " none" : ""}`,
+  );
+  for (const item of coverage.unresolved) lines.push(`  - ${item.subject}: ${item.reason}`);
+  return lines;
+}
+
+export function publicationLines(checked: readonly string[]): string[] {
+  return [
+    `Publication readiness: ${count(checked.length, "active knowledge artifact")} checked for a current review and availability${
+      checked.length === 0 ? "" : ` (${checked.join(", ")})`
+    }`,
+  ];
+}
+
+/** Every section the session's level added, as text lines, blank-line separated. */
+export function levelSections(session: Session): string[] {
+  const sections: string[][] = [];
+  if (session.architecture !== undefined)
+    sections.push(architectureLines(session.architecture, session.tree?.skipped ?? []));
+  if (session.evidence !== undefined) sections.push(evidenceLines(session.evidence));
+  if (session.publication !== undefined) sections.push(publicationLines(session.publication.checked));
+  return sections.flatMap((lines) => ["", ...lines]);
+}
+
+/** The same sections as JSON members. */
+export function levelJson(session: Session): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (session.architecture !== undefined) {
+    out.architecture = { summary: session.architecture.summary, skipped: session.tree?.skipped ?? [] };
+  }
+  if (session.evidence !== undefined) {
+    const { files, records, snapshot, check } = session.evidence;
+    const verifications: Record<string, unknown> = {};
+    for (const [id, v] of Object.entries(check.classification.verifications)) {
+      verifications[id] = { method: v.method, status: v.status, ...(v.note === undefined ? {} : { note: v.note }) };
+    }
+    out.evidence = { files, records, snapshot, coverage: check.coverage, verifications };
+  }
+  if (session.publication !== undefined) out.publication = { checked: session.publication.checked };
+  return out;
+}

package/src/repository.ts

@@ -0,0 +1,220 @@
+/**
+ * Loading a repository: the one place the CLI reads the tree. Everything here
+ * is a read. The commit comes from `git rev-parse HEAD`, which reads the
+ * object store and writes nothing; any failure becomes `commit: null` with
+ * the reason, because the export and every report must say which snapshot
+ * they describe and a missing commit is a fact to state, not to invent.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  type Config,
+  compareStrings,
+  type Diagnostic,
+  type DocumentInput,
+  EMPTY_REGISTRIES,
+  type Registries,
+  hasErrors,
+  plainCarrier,
+  readConfig,
+  readRegistries,
+} from "@intentset/core";
+import { marksetCarrier } from "@intentset/markset-adapter";
+import { matchAny } from "./glob.ts";
+
+/** Where the configuration lives, relative to the repository root. Its presence is what makes a directory a root. */
+export const CONFIG_PATH = ".intentset/config.yaml";
+
+export const CARRIERS = {
+  markset: marksetCarrier,
+  plain: plainCarrier,
+} as const;
+export type CarrierName = keyof typeof CARRIERS;
+
+export interface Repository {
+  /** Absolute path of the repository root. */
+  root: string;
+  config: Config;
+  /** One per document in scope, sorted by repository-relative path. */
+  inputs: DocumentInput[];
+  registries: Registries;
+  /** CFG001 from the configuration and CFG002 from the registries, sorted as core sorts. */
+  diagnostics: Diagnostic[];
+  /** False when the configuration itself has an error: then no scope is known and nothing was enumerated. */
+  configOk: boolean;
+  commit: string | null;
+  commitUnavailable?: string;
+  /** True when tracked files differ from that commit, so the commit alone does not describe what was read. */
+  uncommitted?: boolean;
+}
+
+/**
+ * The repository root: `explicit` when given (it must hold the configuration),
+ * otherwise the nearest directory at or above `cwd` that does. Null when none.
+ */
+export function findRoot(cwd: string, explicit: string | undefined): string | null {
+  if (explicit !== undefined) {
+    const root = resolve(cwd, explicit);
+    return existsSync(join(root, CONFIG_PATH)) ? root : null;
+  }
+  let dir = resolve(cwd);
+  for (;;) {
+    if (existsSync(join(dir, CONFIG_PATH))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Core §11: read the configuration, the documents in its scope with the chosen carrier, the registries and the commit. */
+export function loadRepository(root: string, carrier: CarrierName): Repository {
+  const read = readConfig(readFileSync(join(root, CONFIG_PATH), "utf8"), CONFIG_PATH);
+  const config = read.config;
+  const diagnostics = [...read.diagnostics];
+  const configOk = !hasErrors(read.diagnostics);
+  const inputs: DocumentInput[] = [];
+  let registries: Registries = { ...EMPTY_REGISTRIES, resources: [] };
+
+  if (configOk) {
+    const parse = CARRIERS[carrier];
+    for (const path of enumerate(root, config)) {
+      inputs.push(parse(path, readFileSync(join(root, path), "utf8")));
+    }
+    if (config.registries !== null) {
+      const file = join(root, config.registries);
+      const text = isFile(file) ? readFileSync(file, "utf8") : null;
+      const loaded = readRegistries(text, config.registries);
+      registries = loaded.registries;
+      diagnostics.push(...loaded.diagnostics);
+    }
+  }
+  return { root, config, inputs, registries, diagnostics, configOk, ...readCommit(root) };
+}
+
+/**
+ * Core §11 scope: every file `listFiles` returns that matches a `scope`
+ * pattern, as sorted repository-relative POSIX paths.
+ */
+export function enumerate(root: string, config: Pick<Config, "scope" | "ignore">): string[] {
+  return listFiles(root, config.ignore).filter((path) => matchAny(config.scope, path));
+}
+
+/**
+ * Every regular file under `root` that no `ignore` pattern matches, sorted.
+ * In a git repository the list is git's own (`ls-files --cached --others
+ * --exclude-standard`): tracked files and untracked ones .gitignore does not
+ * exclude, so build output and untracked worktrees stay out. Elsewhere it is
+ * a directory walk. Either way symbolic links are left out, so nothing read
+ * lies outside the repository, and a tracked file deleted from the working
+ * tree is not listed.
+ */
+export function listFiles(root: string, ignore: readonly string[]): string[] {
+  const listed = gitFiles(root) ?? walk(root, ignore);
+  const nested = nestedCheckouts(root);
+  return listed.filter(
+    (path) => !matchAny(ignore, path) && !ignoredDirectory(ignore, path) && !nested(path) && isFile(join(root, path)),
+  );
+}
+
+/**
+ * A directory with its own `.git` is another checkout (a nested repository or
+ * a worktree), not part of this one. git lists an untracked worktree's files
+ * one by one, so without this a repository with worktrees under it is read
+ * twice: Streamlane's `.claude/worktrees` made every package appear twice.
+ */
+function nestedCheckouts(root: string): (path: string) => boolean {
+  const cache = new Map<string, boolean>();
+  return (path) => {
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      const dir = parts.slice(0, i).join("/");
+      let found = cache.get(dir);
+      if (found === undefined) {
+        found = existsSync(join(root, dir, ".git"));
+        cache.set(dir, found);
+      }
+      if (found) return true;
+    }
+    return false;
+  };
+}
+
+/** True when some directory containing `path` is ignored, as the walk would never have entered it. */
+function ignoredDirectory(ignore: readonly string[], path: string): boolean {
+  const parts = path.split("/");
+  for (let i = 1; i < parts.length; i++) if (matchAny(ignore, parts.slice(0, i).join("/"))) return true;
+  return false;
+}
+
+function gitFiles(root: string): string[] | null {
+  try {
+    const out = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 256 * 1024 * 1024,
+    });
+    return [...new Set(out.split("\0").filter((path) => path !== ""))].sort(compareStrings);
+  } catch {
+    return null;
+  }
+}
+
+/** Every regular file under `root` that no `ignore` pattern matches, by walking; ignored directories are not entered. */
+export function walk(root: string, ignore: readonly string[]): string[] {
+  const out: string[] = [];
+  const visit = (relative: string): void => {
+    const entries = readdirSync(relative === "" ? root : join(root, relative), { withFileTypes: true });
+    for (const entry of entries) {
+      const path = relative === "" ? entry.name : `${relative}/${entry.name}`;
+      if (matchAny(ignore, path)) continue;
+      if (entry.isDirectory() && existsSync(join(root, path, ".git"))) continue;
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile()) out.push(path);
+    }
+  };
+  visit("");
+  return out.sort(compareStrings);
+}
+
+/** The commit at HEAD in `root`, or null and the reason none could be read. */
+export function readCommit(root: string): { commit: string | null; commitUnavailable?: string; uncommitted?: boolean } {
+  try {
+    const commit = execFileSync("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+    if (/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(commit)) {
+      // --no-optional-locks: asking whether the tree is clean must not refresh git's index either.
+      const status = execFileSync("git", ["--no-optional-locks", "status", "--porcelain", "--untracked-files=no"], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      return status.trim() === "" ? { commit } : { commit, uncommitted: true };
+    }
+    return { commit: null, commitUnavailable: `git rev-parse printed "${commit}", which is not a commit ID.` };
+  } catch (error) {
+    return { commit: null, commitUnavailable: commitFailure(error) };
+  }
+}
+
+function commitFailure(error: unknown): string {
+  const failure = error as { code?: string; status?: number | null; stderr?: string };
+  if (failure.code === "ENOENT") return "git is not installed, so no commit could be read.";
+  const detail = (failure.stderr ?? "").trim().split("\n")[0] ?? "";
+  if (/not a git repository/i.test(detail)) return "The repository root is not inside a git repository.";
+  if (failure.status === 1 && detail === "") return "The git repository has no commit at HEAD yet.";
+  return detail === "" ? "git rev-parse HEAD failed." : `git rev-parse HEAD failed: ${detail}`;
+}
+
+/** A regular file, not a symbolic link to one. */
+function isFile(path: string): boolean {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/session.ts

@@ -0,0 +1,276 @@
+/**
+ * The shared front half of every reading command: find the root, load the
+ * repository, and run every check the requested level asks for, each level
+ * including the ones below it (Core §11):
+ *
+ *   L1  core: parse, identity, fields, typed links, hierarchy, lifecycle, narrative
+ *   L2  + ownership (core) and the architecture check over the repository tree
+ *   L3  + run records classified against this snapshot, and current-pass coverage
+ *   L4  + publication readiness: active knowledge is review-current and carries availability
+ *   L5  is a claim about continuous CI, which one run cannot check; main refuses it
+ *
+ * Returns an exit code instead when the command cannot proceed, having said
+ * why. Nothing here writes.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  type ArchitectureResult,
+  type BaselineEntry,
+  checkArchitecture,
+  type Mode,
+  parseBaseline,
+} from "@intentset/architecture";
+import {
+  type Artifact,
+  compareStrings,
+  type Diagnostic,
+  type Graph,
+  graphHash,
+  hasErrors,
+  LEVELS,
+  type Level,
+  sortDiagnostics,
+  type ValidationResult,
+  validate,
+} from "@intentset/core";
+import { reviewStatus } from "@intentset/publisher";
+import {
+  checkEvidence,
+  type EvidenceCheck,
+  type EvidenceSnapshot,
+  type RunRecord,
+  type RunScope,
+  readRunRecords,
+} from "@intentset/verification";
+import { insideRoot } from "./outputs.ts";
+import { formatDiagnostic, type Io, type Snapshot } from "./output.ts";
+import { type CarrierName, CONFIG_PATH, findRoot, loadRepository, type Repository } from "./repository.ts";
+import { readTree, type Tree } from "./tree.ts";
+
+/** Where run records are read from when no --evidence is given. Local output: not to be committed. */
+export const EVIDENCE_DIR = ".intentset/evidence";
+
+export interface SessionOptions {
+  root?: string;
+  carrier: CarrierName;
+  level: Level;
+  /** L2 and above: architecture mode and baseline. */
+  mode?: Mode;
+  baseline?: string;
+  /** L3 and above: evidence files as given (relative to cwd); undefined reads EVIDENCE_DIR. */
+  evidence?: string[];
+  /** L3 and above: the exact product and release evidence is assessed for; null considers every scope. */
+  scope?: RunScope | null;
+  /** The day exceptions expire against; default today, UTC. */
+  today?: string;
+}
+
+export interface EvidenceRun {
+  /** The files read, as repository-relative paths where they lie inside the root. */
+  files: string[];
+  records: number;
+  check: EvidenceCheck;
+  snapshot: EvidenceSnapshot;
+}
+
+export interface Session {
+  repo: Repository;
+  level: Level;
+  /** Core's result with every level's diagnostics folded in, so `ok` and the export carry them all. */
+  result: ValidationResult;
+  diagnostics: Diagnostic[];
+  errors: number;
+  warnings: number;
+  snapshot: Snapshot;
+  tree?: Tree;
+  architecture?: ArchitectureResult;
+  evidence?: EvidenceRun;
+  /** L4: the active knowledge artifacts checked for publication readiness, by ID. */
+  publication?: { checked: string[] };
+}
+
+const at = (level: Level, floor: Level) => LEVELS.indexOf(level) >= LEVELS.indexOf(floor);
+
+/** Load and check at the level, or return the exit code (2) after reporting why the repository could not be read. */
+export function openSession(command: string, options: SessionOptions, io: Io): Session | number {
+  const root = findRoot(io.cwd, options.root);
+  if (root === null) {
+    const where = options.root === undefined ? "this directory or any above it" : options.root;
+    io.stderr(
+      `intentset ${command}: no ${CONFIG_PATH} in ${where}.\n` +
+        "Run `intentset init` at the repository root to create one, or pass --root <dir>.\n",
+    );
+    return 2;
+  }
+  const repo = loadRepository(root, options.carrier);
+  if (!repo.configOk) {
+    io.stderr(`intentset ${command}: the configuration has errors, so the scope is unknown.\n`);
+    for (const d of sortDiagnostics(repo.diagnostics)) io.stderr(formatDiagnostic(d));
+    return 2;
+  }
+  const level = options.level;
+  const validated = validate(repo.inputs, repo.registries, { level });
+  const graph = validated.graph;
+  const snapshot: Snapshot = { commit: repo.commit, graphHash: graphHash(graph) };
+  if (repo.commitUnavailable !== undefined) snapshot.commitUnavailable = repo.commitUnavailable;
+  if (repo.uncommitted === true) snapshot.uncommitted = true;
+  const all: Diagnostic[] = [...validated.diagnostics, ...repo.diagnostics];
+  const session: Omit<Session, "result" | "diagnostics" | "errors" | "warnings"> = { repo, level, snapshot };
+
+  if (at(level, "L2")) {
+    let baseline: BaselineEntry[] = [];
+    if (options.baseline !== undefined) {
+      const read = readBaseline(resolve(io.cwd, options.baseline));
+      if (typeof read === "string") {
+        io.stderr(`intentset ${command}: --baseline ${options.baseline}: ${read}\n`);
+        return 2;
+      }
+      baseline = read;
+    }
+    const tree = readTree(root, repo.config);
+    const architecture = checkArchitecture(
+      graph,
+      repo.registries,
+      { files: tree.files },
+      {
+        level,
+        mode: options.mode ?? "migration",
+        baseline,
+        today: options.today ?? new Date().toISOString().slice(0, 10),
+        ...(repo.config.registries === null ? {} : { registriesPath: repo.config.registries }),
+      },
+    );
+    session.tree = tree;
+    session.architecture = architecture;
+    all.push(...architecture.diagnostics);
+  }
+
+  if (at(level, "L3")) {
+    const files = evidenceFiles(root, io.cwd, options.evidence);
+    const records: RunRecord[] = [];
+    const seen = new Set<string>();
+    const shown: string[] = [];
+    for (const file of files) {
+      const path = insideRoot(root, file) ?? file;
+      let json: unknown;
+      try {
+        json = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        io.stderr(`intentset ${command}: evidence ${path} is not readable JSON: ${(error as Error).message}\n`);
+        return 2;
+      }
+      const read = readRunRecords(json, path);
+      all.push(...read.diagnostics);
+      // The same record imported into two files is one run, not two.
+      for (const record of read.records) {
+        const key = JSON.stringify(record);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        records.push(record);
+      }
+      shown.push(path);
+    }
+    const evidenceSnapshot: EvidenceSnapshot = {
+      commit: snapshot.commit,
+      graphHash: snapshot.graphHash,
+      scope: options.scope ?? null,
+    };
+    const check = checkEvidence(graph, records, evidenceSnapshot, {
+      level,
+      files: session.tree?.paths,
+      evidencePath: shown.length === 1 ? shown[0] : null,
+    });
+    session.evidence = { files: shown, records: records.length, check, snapshot: evidenceSnapshot };
+    all.push(...check.diagnostics);
+  }
+
+  if (at(level, "L4")) {
+    const readiness = publicationReadiness(graph);
+    session.publication = { checked: readiness.checked };
+    all.push(...readiness.diagnostics);
+  }
+
+  const diagnostics = sortDiagnostics(all);
+  const errors = diagnostics.filter((d) => d.severity === "error").length;
+  const result: ValidationResult = { graph, diagnostics, ok: !hasErrors(diagnostics) };
+  return { ...session, result, diagnostics, errors, warnings: diagnostics.length - errors };
+}
+
+/** A baseline file's entries, or why it could not be read. */
+function readBaseline(file: string): BaselineEntry[] | string {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    return `could not be read: ${(error as Error).message}`;
+  }
+  try {
+    return parseBaseline(text);
+  } catch (error) {
+    return (error as Error).message;
+  }
+}
+
+/** The evidence files to read: those given, else every `*.json` in EVIDENCE_DIR, sorted. Absolute paths. */
+export function evidenceFiles(root: string, cwd: string, given: string[] | undefined): string[] {
+  if (given !== undefined && given.length > 0) return given.map((file) => resolve(cwd, file));
+  const dir = join(root, EVIDENCE_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".json"))
+    .sort(compareStrings)
+    .map((name) => join(dir, name));
+}
+
+/**
+ * Core §9 and §11 at L4: every knowledge artifact that is neither draft nor
+ * retired is current against the sources it was reviewed against, and says
+ * where it applies. Anything else is CORE008, because it could not be
+ * published as current.
+ */
+export function publicationReadiness(graph: Graph): { checked: string[]; diagnostics: Diagnostic[] } {
+  const checked: string[] = [];
+  const diagnostics: Diagnostic[] = [];
+  for (const id of [...graph.artifacts.keys()].sort(compareStrings)) {
+    const artifact = graph.artifacts.get(id) as Artifact;
+    const { meta } = artifact;
+    if (meta.type !== "knowledge" || meta.status === "draft" || meta.status === "retired") continue;
+    checked.push(id);
+    const report = (field: string, message: string, remediation: string) =>
+      diagnostics.push({
+        code: "CORE008",
+        severity: "error",
+        origin: "publication",
+        artifact: id,
+        path: artifact.path,
+        field,
+        message,
+        remediation,
+      });
+    if (meta.availability === undefined) {
+      report(
+        "/intentset/availability",
+        `${meta.status} knowledge ${id} has no availability, so no release could publish it (Core §7: missing access information fails closed).`,
+        "Add availability with the products, releases, roles, editions and flags the guidance applies to.",
+      );
+    }
+    const review = reviewStatus(graph, artifact);
+    if (review.status === "current") continue;
+    const reasons: string[] = [];
+    if (review.changed.length > 0) reasons.push(`${review.changed.join(", ")} changed since review`);
+    if (review.missing.length > 0) reasons.push(`no review pin for ${review.missing.join(", ")}`);
+    if (review.reviewer === null) reasons.push("it names no reviewer");
+    if (review.reviewedAt === null) reasons.push("it gives no review date");
+    report(
+      review.reviewer === null
+        ? "/intentset/reviewedBy"
+        : review.reviewedAt === null
+          ? "/intentset/reviewedAt"
+          : "/intentset/extensions/intentset.org~1review",
+      `${meta.status} knowledge ${id} needs review: ${reasons.join("; ")} (Core §9).`,
+      "Review the knowledge against its current sources, then update reviewedBy, reviewedAt and the intentset.org/review pins (Core §9).",
+    );
+  }
+  return { checked, diagnostics };
+}