novahiz 0.1.0

package/src/commands/tokens.ts

@@ -0,0 +1,85 @@
+import { dbPathFor, emit, flagOn, type Parsed } from "./context.ts";
+import { loadSpec, novahizHome } from "../spec.ts";
+import { openDb } from "../db.ts";
+import * as ui from "../render.ts";
+
+const AVG_LINE_BYTES = 80;
+const AVG_TOKENS_PER_LINE = 25;
+
+export function commandTokens(parsed: Parsed): void {
+  const root = novahizHome();
+  const spec = loadSpec(root);
+  const db = openDb(dbPathFor(root, spec));
+
+  const enforcementEvents = (db.prepare("SELECT COUNT(*) AS n FROM enforcement_log").get() as { n: number }).n;
+  const invocationEvents = (db.prepare("SELECT COUNT(*) AS n FROM skill_invocations").get() as { n: number }).n;
+  const roadmapEvents = (db.prepare("SELECT COUNT(*) AS n FROM roadmap_progress").get() as { n: number }).n;
+  const taskEvents = (db.prepare("SELECT COUNT(*) AS n FROM tasks").get() as { n: number }).n;
+  const todoEvents = (db.prepare("SELECT COUNT(*) AS n FROM todos").get() as { n: number }).n;
+
+  const blocked = (db.prepare("SELECT COUNT(*) AS n FROM enforcement_log WHERE decision = 'block'").get() as { n: number }).n;
+  const blockedBytes = blocked * AVG_LINE_BYTES;
+  const blockedTokens = Math.round((blocked * AVG_LINE_BYTES) / AVG_TOKENS_PER_LINE);
+
+  const byTool = db.prepare("SELECT tool, COUNT(*) AS n FROM enforcement_log GROUP BY tool ORDER BY n DESC").all() as { tool: string; n: number }[];
+  const byDecision = db.prepare("SELECT decision, COUNT(*) AS n FROM enforcement_log GROUP BY decision ORDER BY n DESC").all() as { decision: string; n: number }[];
+
+  db.close();
+
+  const events = enforcementEvents + invocationEvents + roadmapEvents + taskEvents + todoEvents;
+
+  const value = {
+    events,
+    enforcement: enforcementEvents,
+    invocations: invocationEvents,
+    roadmap: roadmapEvents,
+    tasks: taskEvents,
+    todos: todoEvents,
+    blocked,
+    estimatedBytesSaved: blockedBytes,
+    estimatedTokensSaved: blockedTokens,
+    byTool,
+    byDecision
+  };
+
+  const calibrate = flagOn(parsed, "calibrate");
+
+  emit(parsed, value, () => {
+    const lines = [
+      ui.heading("Novahiz tokens"),
+      "",
+      ui.kv([
+        ["events:", String(events)],
+        ["enforcement:", String(enforcementEvents)],
+        ["invocations:", String(invocationEvents)],
+        ["roadmap:", String(roadmapEvents)],
+        ["tasks:", String(taskEvents)],
+        ["todos:", String(todoEvents)],
+        ["blocked:", String(blocked)],
+        ["est. bytes saved:", ui.bytes(blockedBytes)],
+        ["est. tokens saved:", String(blockedTokens)]
+      ]),
+      "",
+      ui.heading("By tool"),
+      ui.table(["tool", "n"], byTool.map((row) => [row.tool, String(row.n)])),
+      "",
+      ui.heading("By decision"),
+      ui.table(["decision", "n"], byDecision.map((row) => [row.decision, String(row.n)]))
+    ];
+
+    if (calibrate) {
+      const bytesPerToken = AVG_LINE_BYTES / AVG_TOKENS_PER_LINE;
+      lines.push(
+        "",
+        ui.heading("Calibration"),
+        ui.kv([
+          ["avg line bytes:", String(AVG_LINE_BYTES)],
+          ["avg tokens/line:", String(AVG_TOKENS_PER_LINE)],
+          ["bytes/token:", bytesPerToken.toFixed(1)]
+        ])
+      );
+    }
+
+    return lines.join("\n");
+  });
+}

package/src/content.ts

@@ -0,0 +1,70 @@
+export function changeText(tool: string, args: unknown): string {
+  const record = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+  const parts: string[] = [];
+  for (const key of ["newString", "new_string", "content", "patchText", "patch", "command", "newText"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.length > 0) parts.push(value);
+  }
+  const edits = record.edits;
+  if (Array.isArray(edits)) {
+    for (const edit of edits) {
+      if (!edit || typeof edit !== "object") continue;
+      const entry = edit as Record<string, unknown>;
+      for (const key of ["newString", "new_string", "content", "newText"]) {
+        const value = entry[key];
+        if (typeof value === "string" && value.length > 0) parts.push(value);
+      }
+    }
+  }
+  return parts.join("\n");
+}
+
+const STYLE_SIGNALS = [
+  /(^|\n)\s*[.#][\w-]+(\s*[:>+~]\s*[.#\w:-]+)*\s*[,{]/,
+  /className\s*=/i,
+  /style\s*[=:]\s*[{"]/i,
+  /styled\./,
+  /\bcss`/,
+  /\b(gap-\d|p[xy]?-\d|m[xy]?-\d|text-\w+-\d|bg-\w+-\d)\b/i
+];
+
+const PROSE_SIGNALS = [
+  /(^|\n)\s*(\/\/|#|\*)\s+[A-Za-z][A-Za-z ,.'()-]{12,}/,
+  /\/\*\*?[\s\S]*?[A-Za-z][A-Za-z ,.'()-]{12,}[\s\S]*?\*\//,
+  /"[^"\n]{15,}[ ][^"\n]{10,}"/,
+  /'[^'\n]{15,}[ ][^'\n]{10,}'/,
+  /`[^`\n]{15,}[ ][^`\n]{10,}`/,
+  /(^|\n)\s{0,3}\S[^\n]*\s\S+\s[^\n]*[.!?](\s|$)/
+];
+
+export function hasStyle(text: string): boolean {
+  if (text.length === 0) return false;
+  return STYLE_SIGNALS.some((pattern) => pattern.test(text));
+}
+
+export function hasProse(text: string): boolean {
+  if (text.length === 0) return false;
+  return PROSE_SIGNALS.some((pattern) => pattern.test(text));
+}
+
+export function isTrivial(text: string, minChange = 0): boolean {
+  if (minChange <= 0) return text.trim().length === 0;
+  return text.replace(/\s+/g, " ").trim().length < minChange;
+}
+
+const PLACEHOLDER_PATTERNS = [
+  /\b(TODO|FIXME|XXX|HACK)\b/,
+  /\bnot implemented\b/i,
+  /\bcoming soon\b/i,
+  /<placeholder/i,
+  /<your[_ ]code/i,
+  /\blorem ipsum\b/i,
+  /\.\.\.\s*rest of\b/i,
+  /\bimplement me\b/i,
+  /\.\.\.\s*existing\b/i
+];
+
+export function hasPlaceholder(text: string): boolean {
+  if (text.length === 0) return false;
+  return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text));
+}

package/src/db.ts

@@ -0,0 +1,143 @@
+import { DatabaseSync } from "node:sqlite";
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export { DatabaseSync };
+
+export function openDb(dbPath: string): DatabaseSync {
+  const absolute = resolve(dbPath);
+  mkdirSync(dirname(absolute), { recursive: true });
+  const db = new DatabaseSync(absolute);
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(absolute, 0o600);
+    } catch {
+      // best effort, the umask may forbid it
+    }
+  }
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec("PRAGMA busy_timeout = 5000;");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    );
+    CREATE TABLE IF NOT EXISTS skills (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      description TEXT,
+      source_path TEXT,
+      power INTEGER NOT NULL DEFAULT 3,
+      stars INTEGER,
+      tags TEXT NOT NULL DEFAULT '[]',
+      categories TEXT NOT NULL DEFAULT '[]',
+      scanned_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS categories (
+      id TEXT PRIMARY KEY,
+      label TEXT,
+      priority INTEGER NOT NULL DEFAULT 0,
+      keywords TEXT NOT NULL DEFAULT '[]',
+      default_skills TEXT NOT NULL DEFAULT '[]'
+    );
+    CREATE TABLE IF NOT EXISTS rules (
+      id TEXT PRIMARY KEY,
+      json TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      agent TEXT,
+      categories TEXT NOT NULL DEFAULT '[]',
+      required_skills TEXT NOT NULL DEFAULT '[]',
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS skill_invocations (
+      session_id TEXT NOT NULL,
+      skill TEXT NOT NULL,
+      invoked_at TEXT NOT NULL,
+      PRIMARY KEY (session_id, skill)
+    );
+    CREATE TABLE IF NOT EXISTS roadmap_progress (
+      session_id TEXT NOT NULL,
+      step_id TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'done',
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (session_id, step_id)
+    );
+    CREATE TABLE IF NOT EXISTS enforcement_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT,
+      tool TEXT,
+      file_path TEXT,
+      file_class TEXT,
+      decision TEXT,
+      missing TEXT NOT NULL DEFAULT '[]',
+      matched_rules TEXT NOT NULL DEFAULT '[]',
+      logged_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS tasks (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      session_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      revision INTEGER NOT NULL DEFAULT 0,
+      reviewed_at TEXT,
+      edits_since_review INTEGER NOT NULL DEFAULT 0,
+      todos_since_review INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE TABLE IF NOT EXISTS todos (
+      id TEXT PRIMARY KEY,
+      task_id TEXT NOT NULL,
+      seq INTEGER NOT NULL DEFAULT 0,
+      label TEXT NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'edit',
+      status TEXT NOT NULL DEFAULT 'pending',
+      acceptance TEXT,
+      proof TEXT,
+      owner TEXT,
+      depends_on TEXT NOT NULL DEFAULT '[]',
+      iterations INTEGER NOT NULL DEFAULT 0,
+      max_iterations INTEGER,
+      updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS enforcement_log_logged_at ON enforcement_log(logged_at);
+    CREATE INDEX IF NOT EXISTS enforcement_log_session ON enforcement_log(session_id);
+  `);
+  migrate(db);
+  return db;
+}
+
+// Table and column names are interpolated here, unlike every other query in the
+// project, because SQLite does not parameterize identifiers. The values come from
+// the fixed strings below and from migrate(), never from external input. Keep it
+// that way: this is the only place where SQL is assembled from strings.
+function tableColumns(db: DatabaseSync, table: string): Set<string> {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+  return new Set(rows.map((row) => row.name));
+}
+
+function ensureColumn(db: DatabaseSync, table: string, column: string, definition: string): void {
+  if (tableColumns(db, table).has(column)) return;
+  db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition};`);
+}
+
+export const SCHEMA_VERSION = 1;
+
+function migrate(db: DatabaseSync): void {
+  ensureColumn(db, "tasks", "revision", "INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "tasks", "reviewed_at", "TEXT");
+  ensureColumn(db, "tasks", "edits_since_review", "INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "tasks", "todos_since_review", "INTEGER NOT NULL DEFAULT 0");
+  db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+}
+
+export function setMeta(db: DatabaseSync, key: string, value: string): void {
+  db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+
+export function getMeta(db: DatabaseSync, key: string): string | null {
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value?: string } | undefined;
+  return row?.value ?? null;
+}

package/src/deps.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+import type { Provider, Spec } from "./spec.ts";
+
+export function commandExists(command: string): boolean {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(probe, [command], { encoding: "utf8", shell: false });
+  return result.status === 0;
+}
+
+type DependencyStatus = {
+  id: string;
+  kind: string;
+  requires: string[];
+  missing: string[];
+  ok: boolean;
+};
+
+export function checkDependencies(spec: Spec): DependencyStatus[] {
+  return spec.providers.map((provider) => {
+    const requires = provider.requires ?? [];
+    const missing = requires.filter((command) => !commandExists(command));
+    return { id: provider.id, kind: provider.kind, requires, missing, ok: missing.length === 0 };
+  });
+}
+
+export function bootstrapFor(provider: Provider, platform: string = process.platform): string[] | null {
+  const bootstrap = provider.bootstrap;
+  if (!bootstrap) return null;
+  return bootstrap[platform] ?? bootstrap.default ?? null;
+}
+
+export function missingPrerequisites(spec: Spec): { provider: Provider; missing: string[] }[] {
+  return spec.providers
+    .map((provider) => ({ provider, missing: (provider.requires ?? []).filter((command) => !commandExists(command)) }))
+    .filter((entry) => entry.missing.length > 0);
+}

package/src/exec.ts

@@ -0,0 +1,85 @@
+import { spawnSync } from "node:child_process";
+
+// Allowed characters for a single argument. It excludes every character a shell
+// can reinterpret: whitespace, & | < > ^ % ! ( ) " ' ` ; $ * ? and newlines.
+// The Windows branch below joins tokens with spaces and hands the result to
+// cmd.exe, so widening this set would re-open command injection on that path.
+const SAFE_TOKEN = /^[A-Za-z0-9@._+,/:=~-]+$/;
+
+type CommandResult = {
+  ok: boolean;
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: string;
+};
+
+function resultFrom(status: number | null, stdout: string, stderr: string, error?: string): CommandResult {
+  return { ok: status === 0, status, stdout, stderr, error };
+}
+
+function refused(token: string): CommandResult {
+  return { ok: false, status: null, stdout: "", stderr: "", error: `refused unsafe token: ${token}` };
+}
+
+export function unsafeToken(tokens: string[]): string | null {
+  for (const token of tokens) {
+    if (token.length === 0) return "";
+    if (!SAFE_TOKEN.test(token)) return token;
+  }
+  return null;
+}
+
+export function runCommand(bin: string, args: string[]): CommandResult {
+  const bad = unsafeToken([bin, ...args]);
+  if (bad !== null) return refused(bad);
+  const [command, spawnArgs] = resolveSpawn(bin, args);
+  const result = spawnSync(command, spawnArgs, { encoding: "utf8", windowsHide: true, shell: false });
+  return resultFrom(result.status, result.stdout ?? "", result.stderr ?? "", result.error?.message);
+}
+
+function resolveSpawn(bin: string, args: string[]): [string, string[]] {
+  if (process.platform !== "win32") return [bin, args];
+  // The shell is taken from the environment. Whoever can set ComSpec can already
+  // run code locally, so the token allowlist above is what actually contains the
+  // arguments; this is noted for completeness, not treated as a boundary.
+  const shell = process.env.ComSpec ?? "cmd.exe";
+  return [shell, ["/d", "/s", "/c", [bin, ...args].join(" ")]];
+}
+
+// Bootstrap may only start a known interpreter or packager. Arguments stay
+// unvalidated on purpose (a legitimate argument is sometimes a whole shell
+// command line), so the binary itself is what gets bounded here.
+const SAFE_BOOTSTRAP_BINS = new Set([
+  "node", "npm", "npx", "uv", "uvx", "sh", "bash", "pwsh", "powershell", "cmd", "cmd.exe", "python", "py"
+]);
+
+function normalizeBin(bin: string): string {
+  const base = bin.replace(/\\/g, "/").split("/").pop() ?? bin;
+  return base.toLowerCase();
+}
+
+function bootstrapBinAllowed(bin: string): boolean {
+  const name = normalizeBin(bin);
+  const withoutExt = name.replace(/\.(exe|cmd|bat)$/i, "");
+  return SAFE_BOOTSTRAP_BINS.has(name) || SAFE_BOOTSTRAP_BINS.has(withoutExt);
+}
+
+function refusedBootstrap(bin: string): CommandResult {
+  return { ok: false, status: null, stdout: "", stderr: "", error: `refused disallowed bootstrap binary: ${bin}` };
+}
+
+// Bootstrap argv is trusted: it comes from catalog/providers.json, which ships
+// inside the repository. Arguments stay unvalidated on purpose, because a
+// legitimate argument can be a whole shell command line (for example
+// `sh -c "curl ... | sh"`) that must reach its interpreter as one unparsed
+// token. The binary itself is bounded to SAFE_BOOTSTRAP_BINS, so editing the
+// registry to point `bin` at an arbitrary executable is refused.
+export function runScript(argv: string[]): CommandResult {
+  if (argv.length === 0) return refused("");
+  const [bin, ...args] = argv;
+  if (!SAFE_TOKEN.test(bin)) return refused(bin);
+  if (!bootstrapBinAllowed(bin)) return refusedBootstrap(bin);
+  const result = spawnSync(bin, args, { encoding: "utf8", windowsHide: true, shell: false });
+  return resultFrom(result.status, result.stdout ?? "", result.stderr ?? "", result.error?.message);
+}

package/src/gate.ts

@@ -0,0 +1,261 @@
+import type { Rule, Spec } from "./spec.ts";
+import { hasPlaceholder, hasProse, hasStyle, isTrivial } from "./content.ts";
+
+type FileClass = "code" | "text" | "design" | "data" | "config" | "other";
+
+const CLASS_BY_EXTENSION: Record<string, FileClass> = {
+  css: "design",
+  scss: "design",
+  sass: "design",
+  less: "design",
+  styl: "design",
+  html: "design",
+  htm: "design",
+  vue: "design",
+  svelte: "design",
+  astro: "design",
+  jsx: "design",
+  tsx: "design",
+  md: "text",
+  mdx: "text",
+  markdown: "text",
+  txt: "text",
+  rst: "text",
+  adoc: "text",
+  json: "data",
+  jsonc: "data",
+  yaml: "data",
+  yml: "data",
+  toml: "data",
+  csv: "data",
+  tsv: "data",
+  xml: "data",
+  env: "config",
+  ini: "config",
+  cfg: "config",
+  conf: "config",
+  gitignore: "config",
+  gitattributes: "config",
+  js: "code",
+  mjs: "code",
+  cjs: "code",
+  ts: "code",
+  mts: "code",
+  cts: "code",
+  py: "code",
+  rb: "code",
+  go: "code",
+  rs: "code",
+  java: "code",
+  kt: "code",
+  kts: "code",
+  swift: "code",
+  c: "code",
+  cc: "code",
+  cpp: "code",
+  h: "code",
+  hpp: "code",
+  cs: "code",
+  php: "code",
+  sh: "code",
+  bash: "code",
+  zsh: "code",
+  ps1: "code",
+  sql: "code",
+  lua: "code",
+  dart: "code",
+  ex: "code",
+  exs: "code",
+  erl: "code",
+  clj: "code",
+  scala: "code"
+};
+
+export function fileClass(filePath: string): FileClass {
+  const normalized = filePath.replace(/\\/g, "/");
+  const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+  if (base.length === 0) return "other";
+
+  if (base.startsWith(".")) {
+    const rest = base.replace(/^\.+/, "").toLowerCase();
+    if (rest.length === 0) return "other";
+    const direct = CLASS_BY_EXTENSION[rest];
+    if (direct) return direct;
+    const lastDot = rest.lastIndexOf(".");
+    if (lastDot !== -1) {
+      const ext = rest.slice(lastDot + 1);
+      return CLASS_BY_EXTENSION[ext] ?? "config";
+    }
+    return "config";
+  }
+
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return "other";
+  const ext = base.slice(dot + 1).toLowerCase();
+  return CLASS_BY_EXTENSION[ext] ?? "other";
+}
+
+export function globToRegExp(glob: string): RegExp {
+  const source = glob.replace(/\\/g, "/");
+  let output = "";
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "*") {
+      if (source[index + 1] === "*") {
+        index += 1;
+        if (source[index + 1] === "/") {
+          index += 1;
+          output += "(?:.*/)?";
+        } else {
+          output += ".*";
+        }
+      } else {
+        output += "[^/]*";
+      }
+    } else if (char === "?") {
+      output += "[^/]";
+    } else if (".+^${}()|[]\\".includes(char)) {
+      output += `\\${char}`;
+    } else {
+      output += char;
+    }
+  }
+  return new RegExp(`^${output}$`, "i");
+}
+
+export function contentSatisfies(content: string, patterns: string[]): boolean {
+  if (content.length === 0) return false;
+  return patterns.some((pattern) => {
+    if (pattern === "prose") return hasProse(content);
+    if (pattern === "style") return hasStyle(content);
+    if (pattern.length > 1000) return false;
+    try {
+      return new RegExp(pattern, "i").test(content);
+    } catch {
+      return false;
+    }
+  });
+}
+
+function selectorMatches(rule: Rule, classification: FileClass, path: string, categories: string[]): boolean {
+  const when = rule.when;
+  const checks: boolean[] = [];
+  if (when.fileClasses && when.fileClasses.length > 0) checks.push(when.fileClasses.includes(classification));
+  if (when.pathGlobs && when.pathGlobs.length > 0) checks.push(when.pathGlobs.some((glob) => globToRegExp(glob).test(path)));
+  if (when.promptCategories && when.promptCategories.length > 0) {
+    checks.push(when.promptCategories.some((category) => categories.includes(category)));
+  }
+  if (checks.length === 0) return true;
+  return when.match === "all" ? checks.every(Boolean) : checks.some(Boolean);
+}
+
+type GateInput = {
+  tool: string;
+  filePath: string;
+  content?: string;
+  categories?: string[];
+  loadedSkills?: string[];
+  installedSkills?: ReadonlySet<string> | null;
+  installedIndexAvailable?: boolean;
+  spec: Spec;
+};
+
+type GateResult = {
+  allow: boolean;
+  ignored: boolean;
+  fileClass: FileClass;
+  roadmap: string | null;
+  requiredSkills: string[];
+  missingSkills: string[];
+  unmatchedRequired: string[];
+  matchedRules: string[];
+  indexMissing: boolean;
+  placeholder: boolean;
+  reasons: string[];
+};
+
+export function evaluateGate(input: GateInput): GateResult {
+  const classification = fileClass(input.filePath);
+  const categories = input.categories ?? [];
+  const path = input.filePath.replace(/\\/g, "/");
+  const content = input.content ?? "";
+
+  const ignored = input.spec.config.gate.ignoreFiles.some((glob) => globToRegExp(glob).test(path));
+  if (ignored) {
+    return {
+      allow: true,
+      ignored: true,
+      fileClass: classification,
+      roadmap: null,
+      requiredSkills: [],
+      missingSkills: [],
+      unmatchedRequired: [],
+      matchedRules: [],
+      indexMissing: false,
+      placeholder: false,
+      reasons: []
+    };
+  }
+
+  const requiredSkills: string[] = [];
+  const matchedRules: string[] = [];
+
+  for (const rule of input.spec.rules) {
+    if (!selectorMatches(rule, classification, path, categories)) continue;
+    if (rule.when.minChange && isTrivial(content, rule.when.minChange)) continue;
+    if (rule.when.contentExcludes && contentSatisfies(content, rule.when.contentExcludes)) continue;
+    if (rule.when.contentMatches && !contentSatisfies(content, rule.when.contentMatches)) continue;
+    matchedRules.push(rule.id);
+    for (const skill of rule.require) {
+      if (!requiredSkills.includes(skill)) requiredSkills.push(skill);
+    }
+  }
+
+  const primary = categories[0];
+  let roadmap: string | null = null;
+  if (primary) {
+    const category = input.spec.categories.find((entry) => entry.id === primary);
+    if (category?.roadmap) {
+      roadmap = category.roadmap.id;
+      for (const step of category.roadmap.steps) {
+        if (step.kind !== "skill" || step.optional) continue;
+        for (const skill of step.requireSkills ?? []) {
+          if (!requiredSkills.includes(skill)) requiredSkills.push(skill);
+        }
+      }
+    }
+  }
+
+  const installed = input.installedSkills ?? null;
+  const indexAvailable = input.installedIndexAvailable !== false;
+  const effective: string[] = [];
+  const unmatchedRequired: string[] = [];
+  for (const skill of requiredSkills) {
+    if (indexAvailable && installed && !installed.has(skill)) unmatchedRequired.push(skill);
+    else effective.push(skill);
+  }
+
+  const loaded = new Set(input.loadedSkills ?? []);
+  const missingSkills = effective.filter((skill) => !loaded.has(skill));
+
+  const placeholderEligible = input.spec.config.gate.placeholders && (classification === "code" || classification === "design");
+  const placeholder = placeholderEligible && hasPlaceholder(content);
+
+  const reasons: string[] = [];
+  for (const skill of missingSkills) reasons.push(`missing skill: ${skill}`);
+  if (placeholder) reasons.push("placeholder marker found in content");
+
+  return {
+    allow: missingSkills.length === 0 && !placeholder,
+    ignored: false,
+    fileClass: classification,
+    roadmap,
+    requiredSkills: effective,
+    missingSkills,
+    unmatchedRequired,
+    matchedRules,
+    indexMissing: input.installedIndexAvailable === false,
+    placeholder,
+    reasons
+  };
+}