feat(catalog): shared OKF conformance checker + wire as cross-plugin acceptance gate

Lift okr's reference okf-check.mjs into the catalog as the single cross-plugin
acceptance gate for the OKF-compatible second-brain form (spec §3):

- scripts/okf-check.mjs (+ vendored okf-frontmatter.mjs): verdict logic
  byte-identical to okr's reference impl, English output, zero deps, self-contained.
- scripts/okf-check.test.mjs: 5 self-contained tests (temp-dir bundles).
- spec §7 + §14: the shared checker now lives here; only TS/mjs reconciliation
  remains Stage-3, not required for the gate. log.md protocol §6: conformance is
  verified by the gate, not asserted — a plugin moves to 🟢 only after passing it.

Verified: 33/33 catalog tests green (canonical glob form); verdict parity with
okr's checker on okr fixtures (positive + negative missing-type); a scaffolded
linkedin-studio brain/ validates clean (exit 0).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012GqEHp4uDiivfrAUjw4BdE

scripts/okf-check.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// okf-check.mjs — shared OKF-compatible second-brain conformance checker.
+//
+// The single cross-plugin acceptance gate for the convention in
+// docs/okf-second-brain/spec.md. Validates one bundle root against the minimal
+// contract (spec §3):
+//   - every concept file (.md except index.md) MUST carry `type:` in frontmatter;
+//     >= 1 file without type -> exit 1, count + names the files; 0 -> exit 0.
+//   - recommended fields (resource/title/description/timestamp) -> WARNING, not error.
+//   - the bundle-root index.md's `okf_version` is echoed for human comparison
+//     (no auto-fetch — offline by design).
+//
+// Lifted faithfully from okr/scripts/okf-check.mjs (the de-facto reference
+// implementation; spec §7), with English output + a vendored frontmatter reader so
+// the catalog copy is self-contained. Verdict logic is byte-identical, so a bundle's
+// pass/fail is the same here as under okr's checker. Run per bundle root.
+// Zero npm dependencies (node: builtins).
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatter } from './okf-frontmatter.mjs';
+
+const RECOMMENDED = ['resource', 'title', 'description', 'timestamp'];
+
+// All concept files (.md except index.md) under root, recursively.
+function walkConcepts(root) {
+  const out = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'index.md') out.push(p);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// Read the root's okf_version (markdown text in index.md, not frontmatter). null if absent.
+function rootOkfVersion(root) {
+  const idx = join(root, 'index.md');
+  if (!existsSync(idx)) return null;
+  const m = readFileSync(idx, 'utf8').match(/^okf_version:\s*(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+export function checkBundle(root) {
+  const concepts = walkConcepts(root);
+  const missingType = [];
+  const warnings = [];
+  for (const f of concepts) {
+    const { get } = parseFrontmatter(readFileSync(f, 'utf8'));
+    const rel = relative(root, f);
+    if (!get('type')) {
+      missingType.push(rel);
+      continue;
+    }
+    for (const field of RECOMMENDED) {
+      if (!get(field)) warnings.push(`${rel}: missing recommended field "${field}"`);
+    }
+  }
+  return {
+    scanned: concepts.length,
+    missingType,
+    warnings,
+    okfVersion: rootOkfVersion(root),
+  };
+}
+
+// --- CLI ---
+const isMain = process.argv[1]
+  && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+  const root = process.argv[2];
+  if (!root) {
+    process.stderr.write('Usage: node okf-check.mjs <bundle-root>\n');
+    process.exit(2);
+  }
+  if (!existsSync(root)) {
+    process.stderr.write(`Bundle root does not exist: ${root}\n`);
+    process.exit(2);
+  }
+  const r = checkBundle(root);
+  const out = [];
+  out.push(`OKF check: ${root}`);
+  out.push(`  Concept files scanned: ${r.scanned}`);
+  out.push(`  ${r.missingType.length} files without type:`);
+  for (const f of r.missingType) out.push(`    - ${f}`);
+  out.push(`  okf_version: ${r.okfVersion || 'MISSING (root index without okf_version)'}`);
+  out.push(`  Warnings (recommended fields): ${r.warnings.length}`);
+  for (const w of r.warnings) out.push(`    ! ${w}`);
+  out.push(r.missingType.length === 0 ? 'OK: valid OKF bundle' : `FAIL: ${r.missingType.length} file(s) missing type:`);
+  process.stdout.write(`${out.join('\n')}\n`);
+  process.exit(r.missingType.length === 0 ? 0 : 1);
+}

scripts/okf-check.test.mjs

@@ -0,0 +1,104 @@
+// Tests for the shared OKF conformance checker (the cross-plugin acceptance gate).
+// Self-contained: builds tiny bundles in a temp dir, so the test has no dependency
+// on any sibling repo's fixtures. okf-check is run as a subprocess to capture the
+// exit code (the contract). Zero npm deps. Style mirrors check-versions.test.mjs.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkBundle } from './okf-check.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CHECK = join(HERE, 'okf-check.mjs');
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), 'okf-catalog-'));
+}
+
+// Run okf-check as a subprocess; capture non-zero exit (execFileSync throws then).
+function runCheck(root) {
+  try {
+    const stdout = execFileSync('node', [CHECK, root], { encoding: 'utf8' });
+    return { status: 0, stdout };
+  } catch (e) {
+    return { status: e.status ?? 1, stdout: `${e.stdout || ''}${e.stderr || ''}` };
+  }
+}
+
+// A minimal conforming bundle: root index.md with okf_version + one fully-typed concept.
+function writeValidBundle(dir) {
+  writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n\n# Bundle\n');
+  writeFileSync(
+    join(dir, 'profile.md'),
+    '---\ntype: Profile\ntitle: User profile\ndescription: The user.\nresource: about\ntimestamp: 2026-06-29\n---\n# Profile\n',
+  );
+}
+
+test('valid bundle (every concept has type:) -> exit 0, "0 files without type:"', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    const { status, stdout } = runCheck(dir);
+    assert.equal(status, 0, 'a valid bundle should exit 0');
+    assert.match(stdout, /0 files without type:/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('concept file without type: -> exit != 0 + count > 0 + names the file', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    writeFileSync(
+      join(dir, 'no-type.md'),
+      '---\ntitle: Untyped\ndescription: A concept file missing the required type.\n---\n# Untyped\n',
+    );
+    const { status, stdout } = runCheck(dir);
+    assert.notEqual(status, 0, 'a type-less file should exit != 0');
+    assert.match(stdout, /[1-9]\d* files without type:/);
+    assert.match(stdout, /no-type\.md/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('echoes okf_version from the root index.md', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    const { stdout } = runCheck(dir);
+    assert.match(stdout, /okf_version:\s*0\.1/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('index.md is exempt from the type requirement (sub-levels included)', () => {
+  const dir = tmpRoot();
+  try {
+    writeValidBundle(dir);
+    mkdirSync(join(dir, 'journal'));
+    writeFileSync(join(dir, 'journal', 'index.md'), '# Journal\n'); // no frontmatter, must not fail
+    const { status } = runCheck(dir);
+    assert.equal(status, 0, 'index.md must not be treated as a concept file');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('checkBundle(): recommended-field gaps are warnings, not failures', () => {
+  const dir = tmpRoot();
+  try {
+    writeFileSync(join(dir, 'index.md'), 'okf_version: 0.1\n');
+    writeFileSync(join(dir, 'bare.md'), '---\ntype: Note\n---\n# Bare\n'); // type only
+    const r = checkBundle(dir);
+    assert.equal(r.missingType.length, 0, 'type present -> not a failure');
+    assert.ok(r.warnings.length >= 1, 'missing recommended fields -> warnings');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

scripts/okf-frontmatter.mjs

@@ -0,0 +1,32 @@
+// okf-frontmatter.mjs
+// Minimal flat-frontmatter reader for the shared OKF conformance checker.
+// Vendored from okr's lib/frontmatter.mjs (the reference implementation) so the
+// catalog-hosted checker is self-contained — zero npm dependencies, no cross-repo
+// import. The checker only reads (never writes), so only parseFrontmatter().get is
+// vendored. Parsing logic is kept byte-identical to okr's so verdicts stay in parity.
+
+const FM_RE = /^---\n([\s\S]*?)\n---/;
+
+export function parseFrontmatter(content) {
+  const match = String(content).match(FM_RE);
+  const raw = match ? match[1] : null;
+
+  const get = (key) => {
+    if (raw === null) return null;
+    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(.*)$`, 'm'));
+    if (!m) return null;
+    let v = m[1].trim();
+    if (v === '') return null;
+    const q = v[0];
+    if (q === '"' || q === "'") {
+      const end = v.indexOf(q, 1);
+      if (end !== -1) return v.slice(1, end); // internal '#' preserved
+      v = v.slice(1); // unterminated quote: fall back to the rest
+    } else {
+      v = v.replace(/\s+#.*$/, '').trim(); // unquoted: strip trailing comment
+    }
+    return v === '' ? null : v;
+  };
+
+  return { raw, get };
+}