kataster 0.3.1 → 0.6.0

package/.claude/lib/repo.ts

@@ -18,6 +18,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { graphLabel, graphOrigin, graphToolLabel, queryToolGraph, type ToolGraph } from "./toolgraph.ts";
+import { classifyPackageRoles, clusterSlices, sourceFiles, type PackageRole, type SliceSuggestion } from "./slices.ts";
 
 export const ROOT = resolve(import.meta.dirname, "..", "..");
 export const REPO_MAP_JSON = join("docs", "architecture", "repo-map.json");
@@ -51,6 +52,9 @@ export interface RepoPackage {
   hasTests: boolean;
   adopted: boolean;
   adoptedAt?: string;
+  /** Domain, layer or shared infrastructure – a layer package is not a domain slice. */
+  role?: PackageRole;
+  roleReasons?: string[];
   /** Nx project name when it differs from the package name. */
   projectName?: string;
 }
@@ -66,6 +70,8 @@ export interface RepoMap {
   tooling: Tooling;
   packages: RepoPackage[];
   ranking: RankedPackage[];
+  /** Concept clusters by shared stem/table – a suggestion for layered repositories, not a verdict. */
+  slices?: SliceSuggestion[];
   /** Optional enrichment from the build tool; the manifest graph stays the source of truth. */
   toolGraph?: ToolGraph;
 }
@@ -73,6 +79,7 @@ export interface RepoMap {
 export interface SliceProposal {
   domain?: RepoPackage;
   library?: RepoPackage;
+  cluster?: SliceSuggestion;
 }
 
 type Json = Record<string, unknown>;
@@ -612,8 +619,20 @@ export function scanRepo(root: string, options: { toolGraph?: boolean } = {}): R
   for (const pkg of packages) pkg.consumers.sort();
   packages.sort((a, b) => a.path.localeCompare(b.path));
 
+  // A layered repository needs concept slices: generic packages such as services/ or utils/ host many concepts
+  // and must not be proposed as a domain. The scan is shared by the role assignment and the clustering.
+  const files = sourceFiles(root);
+  const roles = classifyPackageRoles(root, packages, files);
+  for (const pkg of packages) {
+    const role = roles.get(pkg.path);
+    if (!role) continue;
+    pkg.role = role.role;
+    pkg.roleReasons = role.reasons;
+  }
+
   const ranking = rankPackages(root, packages);
-  const map: RepoMap = { version: 1, tooling, packages, ranking };
+  const slices = clusterSlices(root, packages, files);
+  const map: RepoMap = { version: 1, tooling, packages, ranking, slices };
   // Enrichment only. The manifest graph remains the source of truth, so the map stays usable without the
   // build tool: Turbo exposes a task graph, Nx a project graph, Bazel its BUILD deps.
   if (options.toolGraph !== false && tooling.kind !== "none") {
@@ -654,7 +673,9 @@ export function rankPackages(root: string, packages: RepoPackage[]): RankedPacka
   return packages
     .map((pkg) => {
       const changes = churn.get(pkg.name) ?? 0;
-      const score = 0.55 * (changes / maxChurn) + 0.3 * (pkg.consumers.length / maxConsumers) + 0.15 * (pkg.kind === "library" ? 0.4 : 1);
+      const base = 0.55 * (changes / maxChurn) + 0.3 * (pkg.consumers.length / maxConsumers) + 0.15 * (pkg.kind === "library" ? 0.4 : 1);
+      // A layer package can have churn and fan-in, but it is not a domain: keep it visible, rank it low.
+      const score = pkg.role === "layer" ? base * 0.15 : base;
       const reasons: string[] = [];
       if (changes) reasons.push(`${changes} changed file${changes === 1 ? "" : "s"} in recent history`);
       if (pkg.consumers.length) {
@@ -662,6 +683,8 @@ export function rankPackages(root: string, packages: RepoPackage[]): RankedPacka
         reasons.push(`${n} package${n === 1 ? "" : "s"} ${n === 1 ? "depends" : "depend"} on it`);
       }
       if (pkg.kind !== "package") reasons.push(pkg.kind === "library" ? "shared library" : pkg.kind);
+      if (pkg.role === "layer") reasons.push("layer package – hosts many concepts, not a domain slice");
+      if (pkg.role === "shared") reasons.push("shared infrastructure – not a domain slice");
       if (!reasons.length) reasons.push("no churn or consumers recorded");
       return { path: pkg.path, score: Math.round(score * 100) / 100, reasons };
     })
@@ -671,15 +694,21 @@ export function rankPackages(root: string, packages: RepoPackage[]): RankedPacka
 export function proposeSlices(map: RepoMap): SliceProposal {
   const byPath = new Map(map.packages.map((p) => [p.path, p]));
   const ranked = map.ranking.map((r) => byPath.get(r.path)).filter((p): p is RepoPackage => p !== undefined);
-  const domain = ranked.find((p) => p.kind === "app" || p.kind === "service") ?? ranked.find((p) => p.kind !== "library") ?? ranked[0];
-  if (!domain) return {};
+  const domainCandidates = ranked.filter((p) => p.role !== "layer");
+  const domain =
+    domainCandidates.find((p) => p.kind === "app" || p.kind === "service") ??
+    domainCandidates.find((p) => p.kind !== "library") ??
+    domainCandidates[0];
+
+  const cluster = map.slices?.find((slice) => !slice.adopted);
+  if (!domain) return cluster ? { cluster } : {};
 
   const libs = domain.internalDeps
     .map((name) => map.packages.find((p) => p.name === name))
     .filter((p): p is RepoPackage => p !== undefined && p.kind === "library")
     .sort((a, b) => b.consumers.length - a.consumers.length);
   const library = libs[0] ?? ranked.find((p) => p.kind === "library" && p.name !== domain.name);
-  return { domain, library };
+  return { domain, library, cluster };
 }
 
 // --------------------------------------------------------------------------
@@ -806,13 +835,13 @@ export function renderRepoMapMarkdown(map: RepoMap): string {
     "",
     "## Packages",
     "",
-    "| Package | Path | Kind | Language | Depends on | Used by | Adopted |",
-    "|---|---|---|---|---|---|---|",
+    "| Package | Path | Kind | Role | Language | Depends on | Used by | Adopted |",
+    "|---|---|---|---|---|---|---|---|",
   ];
 
   for (const pkg of [...map.packages].sort((a, b) => a.path.localeCompare(b.path))) {
     out.push(
-      `| ${tableCell(pkg.name)} | \`${pkg.path}\` | ${pkg.kind} | ${pkg.language} | ` +
+      `| ${tableCell(pkg.name)} | \`${pkg.path}\` | ${pkg.kind} | ${pkg.role ?? "–"} | ${pkg.language} | ` +
         `${pkg.internalDeps.length ? pkg.internalDeps.map((d) => `\`${d}\``).join(", ") : "–"} | ` +
         `${pkg.consumers.length ? pkg.consumers.map((d) => `\`${d}\``).join(", ") : "–"} | ` +
         `${pkg.adopted ? "yes" : "–"} |`,
@@ -820,6 +849,50 @@ export function renderRepoMapMarkdown(map: RepoMap): string {
   }
   out.push("");
 
+  const layers = map.packages.filter((pkg) => pkg.role === "layer");
+  if (layers.length) {
+    out.push(
+      "## Layer packages",
+      "",
+      "These packages are layers of the application, not domain slices. Their concepts cut across them.",
+      "",
+      "| Package | Path | Why |",
+      "|---|---|---|",
+    );
+    for (const pkg of layers) {
+      out.push(`| ${tableCell(pkg.name)} | \`${pkg.path}\` | ${tableCell((pkg.roleReasons ?? []).join("; "))} |`);
+    }
+    out.push("");
+  }
+
+  if (map.slices?.length) {
+    out.push(
+      "## Slice suggestions (shared concepts)",
+      "",
+      "Files that share a concept stem or a table across layers. These are suggestions – confirm the scope with the user.",
+      "",
+      "| Concept | Layers | Files | Tables | Why | Adopted |",
+      "|---|---|---|---|---|---|",
+    );
+    for (const slice of map.slices) {
+      out.push(
+        `| ${slice.name} | ${slice.layers.join(", ") || "–"} | ${slice.files.length} | ` +
+          `${slice.tables.map((t) => `\`${t}\``).join(", ") || "–"} | ${tableCell(slice.reasons.join("; "))} | ` +
+          `${slice.adopted ? "yes" : "–"} |`,
+      );
+    }
+    out.push("");
+    out.push(
+      "Adopt a concept slice with:",
+      "",
+      "```bash",
+      "node .claude/skills/adopt/scripts/slice.ts --cluster <name>",
+      "node .claude/skills/adopt/scripts/repo-map.ts --adopt-slice <name>",
+      "```",
+      "",
+    );
+  }
+
   const edges = map.packages.flatMap((pkg) => pkg.internalDeps.map((dep) => [pkg, dep] as const));
   if (edges.length) {
     const nodes = new Map<string, RepoPackage>();
@@ -871,12 +944,23 @@ export function renderRepoMapMarkdown(map: RepoMap): string {
   });
   out.push("");
 
-  const { domain, library } = proposeSlices(map);
-  if (domain) {
-    const label = domain.path === "." ? "root package" : `\`${domain.path}\``;
-    out.push("## Suggested first slice", "", `- **Domain:** ${label} (${domain.name})`);
-    if (library) out.push(`- **Shared library:** \`${library.path}\` (${library.name})`);
-    out.push("", "Adopt one domain and at most one shared library per session. Then mark the slice adopted:", "", "```bash", `node .claude/skills/adopt/scripts/repo-map.ts --adopt ${domain.path}`, "```", "");
+  const { domain, library, cluster } = proposeSlices(map);
+  if (domain || cluster) {
+    out.push("## Suggested first slice", "");
+    if (cluster) {
+      out.push(`- **Concept:** \`${cluster.name}\` – ${cluster.layers.join(", ") || "one layer"} (${cluster.files.length} file(s))`);
+      out.push(`  Start with \`node .claude/skills/adopt/scripts/slice.ts --cluster ${cluster.name}\`.`);
+    }
+    if (domain) {
+      const label = domain.path === "." ? "root package" : `\`${domain.path}\``;
+      out.push(`- **Package:** ${label} (${domain.name})`);
+      if (library) out.push(`- **Shared library:** \`${library.path}\` (${library.name})`);
+    }
+    out.push("", "Adopt one concept or domain plus at most one shared library per session. Then mark it adopted:");
+    out.push("", "```bash");
+    if (cluster) out.push(`node .claude/skills/adopt/scripts/repo-map.ts --adopt-slice ${cluster.name}`);
+    if (domain) out.push(`node .claude/skills/adopt/scripts/repo-map.ts --adopt ${domain.path}`);
+    out.push("```", "");
   }
   return out.join("\n");
 }
@@ -904,15 +988,26 @@ export function rootBlock(map: RepoMap, root = resolve(import.meta.dirname, ".."
     lines.push(`- **Layout:** ${groupsList.slice(0, 8).map((g) => `\`${g.dir}/\` (${g.total})`).join(", ")}`);
   }
   lines.push("- **Detail:** `docs/architecture/repo-map.md` – package list, dependency edges, consumers, adoption ranking.");
-  if (adopted.length) {
+  const openSlices = (map.slices ?? []).filter((slice) => !slice.adopted).slice(0, 5);
+  if (openSlices.length) {
+    lines.push(
+      `- **Concept slices:** ${openSlices.map((slice) => `\`${slice.name}\` (${slice.layers.join(", ") || "one layer"})`).join(", ")}` +
+        " – candidates for `/adopt`, not confirmed domains.",
+    );
+  }
+  const adoptedSlices = (map.slices ?? []).filter((slice) => slice.adopted);
+  if (adopted.length || adoptedSlices.length) {
+    const labels = [
+      ...adopted.map((p) => (p.path === "." ? "root package" : `\`${p.path}\``)),
+      ...adoptedSlices.map((slice) => `concept \`${slice.name}\``),
+    ];
     const rest = map.packages.length - adopted.length;
-    const labels = adopted.map((p) => (p.path === "." ? "root package" : `\`${p.path}\``));
     lines.push(
       `- **Adopted slices:** ${labels.join(", ")}` +
-        (rest ? `. Everything else is **not adopted**: run \`/adopt <path>\` before inferring domain there.` : "."),
+        (rest ? ". Everything else is **not adopted**: run `/adopt` before inferring domain there." : "."),
     );
   } else {
-    lines.push("- **No package is adopted yet.** Run `/adopt` before inferring domain from code.");
+    lines.push("- **No slice is adopted yet.** Run `/adopt` before inferring domain from code.");
   }
   lines.push("", "## Commands", "", "| Scope | Command |", "|---|---|");
 
@@ -1173,12 +1268,41 @@ export function markAdopted(root: string, path: string, date = new Date().toISOS
   return map;
 }
 
+export function markSliceAdopted(root: string, name: string, date = new Date().toISOString().slice(0, 10)): RepoMap {
+  const map = readRepoMap(root);
+  if (!map) throw new Error(`no ${REPO_MAP_JSON} – run repo-map.ts first`);
+  const slices = map.slices ?? (map.slices = []);
+  let slice = slices.find((entry) => entry.name === name);
+  if (!slice) {
+    // An ad-hoc scope (glob, route, table, event) has no generated cluster; keep it as an explicit adoption.
+    slice = {
+      name,
+      terms: [],
+      tables: [],
+      files: [],
+      packages: [],
+      layers: [],
+      score: 0,
+      reasons: ["marked adopted manually"],
+    };
+    slices.push(slice);
+  }
+  slice.adopted = true;
+  slice.adoptedAt = date;
+  writeRepoMap(root, map);
+  writeRootBlock(root, map);
+  return map;
+}
+
 /** Stable view for staleness checks: generated docs and ranking may change with history. */
 export function stableMap(map: RepoMap): string {
   const packages = [...map.packages]
     .sort((a, b) => a.path.localeCompare(b.path))
     .map(({ adopted: _adopted, adoptedAt: _adoptedAt, consumers: _consumers, ...rest }) => rest);
-  return JSON.stringify({ version: map.version, tooling: map.tooling, packages }, null, 2);
+  const slices = [...(map.slices ?? [])]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(({ adopted: _adopted, adoptedAt: _adoptedAt, ...rest }) => rest);
+  return JSON.stringify({ version: map.version, tooling: map.tooling, packages, slices }, null, 2);
 }
 
 export function findPackage(map: RepoMap, path: string): RepoPackage | undefined {

package/.claude/lib/research.ts

@@ -0,0 +1,303 @@
+/**
+ * Research files (`docs/research/<topic>.md`) – evidence for cross-cutting decisions, not a specification.
+ *
+ * The researcher agent is read-only and returns structured findings. The main session writes them verbatim into a
+ * research file with frontmatter: topic, question, created, retrieved, expires and the stack versions queried.
+ * Expiry is computed when the file is written or refreshed (`retrieved + research.expiryMonths`), never on read.
+ *
+ * This module owns the format, the review gate and the status helpers. It does not import discovery.ts: discovery.ts
+ * imports this module for story warnings, and a cycle would make both unreadable.
+ *
+ * Same rules as the rest of the payload: Node >= 22.18, erasable TypeScript only, one runtime dependency (`yaml`).
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { loadResearchConfig, type Obj, type ResearchConfig } from "./config.ts";
+
+export const ROOT = resolve(import.meta.dirname, "..", "..");
+export const RESEARCH_DIR = join(ROOT, "docs", "research");
+
+export type ResearchStatus = "valid" | "expired" | "missing" | "invalid";
+
+/** Today's date in UTC, `YYYY-MM-DD`. */
+export function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TOPIC_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function isValidDate(value: unknown): value is string {
+  if (typeof value !== "string" || !DATE_RE.test(value)) return false;
+  const date = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
+/** `date` plus `months`, in UTC; a month-end date is clamped to the target month's last day. */
+export function addMonths(date: string, months: number): string {
+  const base = new Date(`${date}T00:00:00Z`);
+  if (Number.isNaN(base.getTime())) throw new Error(`invalid date '${date}'`);
+  const target = new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth() + Math.trunc(months), 1));
+  const lastDay = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+  const day = Math.min(base.getUTCDate(), lastDay);
+  return `${target.toISOString().slice(0, 7)}-${String(day).padStart(2, "0")}`;
+}
+
+/** Project-relative POSIX path for display; absolute when the file is outside the project. */
+export function relPath(path: string): string {
+  const r = relative(ROOT, path);
+  return r.startsWith("..") || resolve(r) === r ? path : r.split(sep).join("/");
+}
+
+/** All research files: Markdown, no README, no `_`-prefixed drafts. */
+export function researchFiles(): string[] {
+  if (!existsSync(RESEARCH_DIR)) return [];
+  return readdirSync(RESEARCH_DIR)
+    .filter((name) => name.endsWith(".md") && name !== "README.md" && !name.startsWith("_"))
+    .sort()
+    .map((name) => join(RESEARCH_DIR, name));
+}
+
+export interface ResearchDocument {
+  meta: Obj;
+  body: string;
+}
+
+/** Parses a research file. Throws on a missing or broken frontmatter. */
+export function parseResearchFile(path: string): ResearchDocument {
+  const text = readFileSync(path, "utf8").replaceAll("\r\n", "\n");
+  if (!text.startsWith("---\n")) throw new Error("YAML frontmatter is missing (file must start with '---')");
+  const end = text.indexOf("\n---", 4);
+  if (end === -1) throw new Error("frontmatter is not closed with '---'");
+  const meta = parseYaml(text.slice(4, end)) ?? {};
+  if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+    throw new Error("frontmatter must be an object");
+  }
+  return { meta: meta as Obj, body: text.slice(end + 4).replace(/^\n+/, "") };
+}
+
+export interface ResearchValidation {
+  errors: string[];
+  warnings: string[];
+  doc: ResearchDocument | null;
+}
+
+const FINDING_FIELDS = ["Statement", "Source", "Retrieved", "Tier", "Confidence", "Domain-model impact"] as const;
+
+/** Validates the persisted format. Expiry itself is a status, not a format error. */
+export function validateResearchFile(path: string): ResearchValidation {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  let doc: ResearchDocument;
+  try {
+    doc = parseResearchFile(path);
+  } catch (error) {
+    return { errors: [error instanceof Error ? error.message : String(error)], warnings, doc: null };
+  }
+
+  const meta = doc.meta;
+  const topic = typeof meta.topic === "string" ? meta.topic : "";
+  if (!topic) {
+    errors.push("frontmatter: required field 'topic' is missing");
+  } else if (!TOPIC_RE.test(topic)) {
+    errors.push(`frontmatter: topic '${topic}' must be lowercase kebab-case`);
+  } else if (basename(path, ".md") !== topic) {
+    errors.push(`frontmatter: topic '${topic}' must match the file name '${basename(path)}'`);
+  }
+
+  if (typeof meta.question !== "string" || !meta.question.trim()) {
+    errors.push("frontmatter: required field 'question' is missing or empty");
+  }
+  for (const field of ["created", "retrieved", "expires"] as const) {
+    if (!isValidDate(meta[field])) {
+      errors.push(`frontmatter: '${field}' must be a valid date (YYYY-MM-DD)`);
+    }
+  }
+  if (!Array.isArray(meta.stack) || !meta.stack.every((entry) => typeof entry === "string")) {
+    errors.push("frontmatter: 'stack' must be a list of version strings");
+  }
+
+  if (isValidDate(meta.created) && isValidDate(meta.retrieved) && meta.created > meta.retrieved) {
+    errors.push("frontmatter: 'created' must not be after 'retrieved'");
+  }
+  if (isValidDate(meta.retrieved) && isValidDate(meta.expires) && meta.expires <= meta.retrieved) {
+    errors.push("frontmatter: 'expires' must be after 'retrieved'");
+  }
+
+  if (!/^#\s+Research:\s*\S/m.test(doc.body)) {
+    errors.push("body: heading '# Research: <topic>' is missing");
+  }
+  if (!/^##\s+Question\s*$/m.test(doc.body)) {
+    errors.push("body: section '## Question' is missing");
+  }
+  if (!/^##\s+Findings\s*$/m.test(doc.body)) {
+    errors.push("body: section '## Findings' is missing");
+  }
+  if (!/^##\s+Conflicts, caveats and gaps\s*$/m.test(doc.body)) {
+    warnings.push("body: section '## Conflicts, caveats and gaps' is missing – state gaps or say that there are none");
+  }
+  if (!/^##\s+Open questions for the grilling\s*$/m.test(doc.body)) {
+    warnings.push("body: section '## Open questions for the grilling' is missing");
+  }
+
+  const headings = [...doc.body.matchAll(/^###\s+(F\d+)\s*[–-]\s*(.*)$/gm)];
+  if (!headings.length) {
+    errors.push("body: at least one finding ('### F1 – <short claim>') is required");
+  }
+  for (const heading of headings) {
+    const start = (heading.index ?? 0) + heading[0].length;
+    const rest = doc.body.slice(start);
+    const next = rest.search(/^###\s+/m);
+    const block = next === -1 ? rest : rest.slice(0, next);
+    for (const field of FINDING_FIELDS) {
+      const value = new RegExp(`^-\\s*\\*\\*${field}:\\*\\*\\s*(.+)$`, "m").exec(block)?.[1].trim();
+      if (!value) errors.push(`finding ${heading[1]}: field '${field}' is missing or empty`);
+    }
+    const tier = /^-\s*\*\*Tier:\*\*\s*(\S+)/m.exec(block)?.[1];
+    if (tier && !/^[123]$/.test(tier)) errors.push(`finding ${heading[1]}: tier '${tier}' must be 1, 2 or 3`);
+    const confidence = /^-\s*\*\*Confidence:\*\*\s*(\S+)/m.exec(block)?.[1]?.toLowerCase();
+    if (confidence && !/^(high|medium|low)$/.test(confidence)) {
+      errors.push(`finding ${heading[1]}: confidence '${confidence}' must be high, medium or low`);
+    }
+    const retrieved = /^-\s*\*\*Retrieved:\*\*\s*(\S+)/m.exec(block)?.[1];
+    if (retrieved && !isValidDate(retrieved)) {
+      errors.push(`finding ${heading[1]}: retrieved '${retrieved}' must be a valid date (YYYY-MM-DD)`);
+    }
+  }
+
+  return { errors, warnings, doc };
+}
+
+export interface ResearchState {
+  status: ResearchStatus;
+  path: string;
+  relPath: string;
+  topic: string;
+  question: string;
+  retrieved: string;
+  expires: string;
+  errors: string[];
+  warnings: string[];
+}
+
+/** Format and expiry of one research file. Expiry is compared against today, never recomputed from the config. */
+export function researchStatus(path: string, now = today()): ResearchState {
+  const base: ResearchState = {
+    status: "missing",
+    path,
+    relPath: relPath(path),
+    topic: basename(path, ".md"),
+    question: "",
+    retrieved: "",
+    expires: "",
+    errors: [],
+    warnings: [],
+  };
+  if (!existsSync(path)) return base;
+
+  const validation = validateResearchFile(path);
+  const meta = validation.doc?.meta ?? {};
+  const state: ResearchState = {
+    ...base,
+    topic: typeof meta.topic === "string" ? meta.topic : base.topic,
+    question: typeof meta.question === "string" ? meta.question : "",
+    retrieved: typeof meta.retrieved === "string" ? meta.retrieved : "",
+    expires: typeof meta.expires === "string" ? meta.expires : "",
+    errors: validation.errors,
+    warnings: validation.warnings,
+  };
+  if (validation.errors.length) return { ...state, status: "invalid" };
+  if (isValidDate(state.expires) && state.expires < now) return { ...state, status: "expired" };
+  return { ...state, status: "valid" };
+}
+
+/** A local research reference: `docs/research/<topic>.md`, optionally with `#anchor`. */
+export function isLocalResearchRef(ref: string): boolean {
+  return /^docs\/research\/[A-Za-z0-9._-]+\.md(?:#.*)?$/.test(ref.trim());
+}
+
+/** A source is a web URL or a local research file. */
+export function isValidSourceRef(ref: string): boolean {
+  return /^https?:\/\/\S+$/i.test(ref.trim()) || isLocalResearchRef(ref);
+}
+
+/** Absolute path of a local research reference, without the anchor. */
+export function researchPath(ref: string): string {
+  return join(ROOT, ref.trim().split("#", 1)[0]);
+}
+
+/** The `sources:` entries of a story, as written. */
+export function sourceRefs(meta: Obj): string[] {
+  return Array.isArray(meta.sources)
+    ? meta.sources.filter((value): value is string => typeof value === "string" && value.trim() !== "").map((value) => value.trim())
+    : [];
+}
+
+/**
+ * The gate: a story with one of the configured risks or labels needs research evidence before it leaves `review`.
+ * Returns the trigger (`risk 'high'`, `label 'security:oauth'`, or both), or null when the story is not gated.
+ * A label matches exactly or by prefix: `security` matches `security:oauth`.
+ */
+export function researchGateRequired(meta: Obj, cfg: ResearchConfig = loadResearchConfig()): string | null {
+  const triggers: string[] = [];
+  const risk = typeof meta.risk === "string" ? meta.risk.toLowerCase() : "";
+  if (risk && cfg.gate.risk.includes(risk)) triggers.push(`risk '${risk}'`);
+
+  const labels = Array.isArray(meta.labels)
+    ? meta.labels.filter((value): value is string => typeof value === "string").map((value) => value.toLowerCase())
+    : [];
+  const matched = labels.find((label) =>
+    cfg.gate.labels.some((configured) => label === configured || label.startsWith(`${configured}:`)),
+  );
+  if (matched) triggers.push(`label '${matched}'`);
+
+  return triggers.length ? triggers.join(" / ") : null;
+}
+
+/**
+ * Hard-gate errors for the transition to `ready-for-human-review` or `ready`.
+ *
+ * A source counts when it is `https://…` or a local `docs/research/<topic>.md`; a local file must exist. Expiry is
+ * a warning elsewhere, never a gate error: an expired file still records where the evidence came from.
+ */
+export function researchGateErrors(meta: Obj, cfg: ResearchConfig = loadResearchConfig()): string[] {
+  const trigger = researchGateRequired(meta, cfg);
+  if (!trigger) return [];
+
+  const sources = sourceRefs(meta);
+  if (!sources.length) {
+    return [`${trigger} requires at least one 'sources:' entry before ready-for-human-review`];
+  }
+
+  const valid = sources.filter(isValidSourceRef);
+  if (!valid.length) {
+    return [`${trigger} has no resolvable source – use https://… or docs/research/<topic>.md`];
+  }
+  if (valid.some((ref) => /^https?:\/\//i.test(ref))) return [];
+
+  const local = valid.filter(isLocalResearchRef);
+  const missing = local.filter((ref) => !existsSync(researchPath(ref)));
+  if (local.length && missing.length === local.length) {
+    return [`${trigger} has no resolvable source – missing: ${missing.join(", ")}`];
+  }
+  return [];
+}
+
+export interface ExpiredResearchRef {
+  ref: string;
+  path: string;
+  relPath: string;
+  expires: string;
+}
+
+/** Local research references of a story whose expiry has passed. Advisory: verify prints them, the gate does not. */
+export function expiredResearchRefs(meta: Obj, cfg: ResearchConfig = loadResearchConfig(), now = today()): ExpiredResearchRef[] {
+  void cfg;
+  const out: ExpiredResearchRef[] = [];
+  for (const ref of sourceRefs(meta).filter(isLocalResearchRef)) {
+    const state = researchStatus(researchPath(ref), now);
+    if (state.status === "expired") out.push({ ref, path: state.path, relPath: state.relPath, expires: state.expires });
+  }
+  return out;
+}