stylegallery 0.1.0

package/scripts/validate-governance.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { componentStateWorkflowFailures } from "./component-state-workflow-contract.mjs";
+import { consumerEvidenceGovernanceFailures } from "./consumer-evidence-governance-contract.mjs";
+import { referenceOwnershipFailures } from "./governance-matrix-contract.mjs";
+import { immutableActionPins, requiredCodeowners, sentinelProvenanceClauses } from "./governance-policy-contract.mjs";
+import { promotionGovernanceFailures } from "./promotion-governance-contract.mjs";
+import { workflowActionFailures } from "./workflow-action-contract.mjs";
+
+const json = new Set(process.argv.slice(2)).has("--json");
+const root = process.cwd();
+const failures = [];
+const warnings = [];
+function read(relative) {
+  const target = path.join(root, relative);
+  if (!fs.existsSync(target)) {
+    failures.push(`${relative}: missing file`);
+    return "";
+  }
+  return fs.readFileSync(target, "utf8");
+}
+
+function requireIncludes(relative, text) {
+  if (!read(relative).includes(text)) failures.push(`${relative}: missing ${text}`);
+}
+
+function recommendIncludes(relative, text, label = `recommended wording missing ${text}`) {
+  if (!read(relative).includes(text)) warnings.push(`${relative}: ${label}`);
+}
+
+function requirePattern(relative, pattern, label) {
+  if (!pattern.test(read(relative))) failures.push(`${relative}: missing ${label}`);
+}
+
+function requireGeneratedWarning(relative) {
+  requirePattern(relative, /Generated from `scripts\/generate-patterns\.mjs` and `scripts\/pattern-data\.mjs`\. Do not hand-edit/, "generated warning");
+}
+
+function requireGeneratedPatternMetadata(relative) {
+  requireIncludes(relative, "lifecycle: generated");
+  requireIncludes(relative, "generated_from: scripts/generate-patterns.mjs, scripts/pattern-data.mjs");
+}
+
+function requireGovernanceMatrix() {
+  const families = [
+    "Root repository guide",
+    "OKF bundle map",
+    "Agent editing rules",
+    "Planning guides",
+    "Layout recipes",
+    "Quality gates and evidence",
+    "Consumer reference contract",
+    "Governed local reference profiles",
+    "Component-state evidence matrices",
+    "Consumer migration conformance",
+    "Consumer page-evidence lifecycle",
+    "Explicit evidence freshness schedule",
+    "Deterministic consumer browser conformance",
+    "Shared promotion policy",
+    "Proposed Chromium sentinel",
+    "Domain manifest and scope decision",
+    "Layout domain hub",
+    "Motion domain guidance",
+    "Design Engineering domain guidance",
+    "Game UI domain guidance",
+    "Platform Guides domain guidance",
+    "Pattern data and examples",
+    "Pattern generator",
+    "Validation scripts",
+    "CI workflow",
+  ];
+  for (const family of families) requireIncludes("GOVERNANCE.md", family);
+  requireIncludes("GOVERNANCE.md", "| Doc family | Source of truth | Generator | Generated artifacts | Lifecycle state | Stale trigger | Validator | Review owner |");
+  requireIncludes("GOVERNANCE.md", "`scripts/pattern-data.mjs`");
+  requireIncludes("GOVERNANCE.md", "`scripts/generate-patterns.mjs`");
+  requireIncludes("GOVERNANCE.md", "`scripts/validate-patterns.mjs`, `scripts/validate-catalog.mjs`, `scripts/validate-governance.mjs`");
+  requireIncludes("GOVERNANCE.md", "Source-lineage URL changes, generated drift, category changes, or pattern count changes.");
+  requireIncludes("GOVERNANCE.md", "Generated structure changes, generated-warning changes, or generated metadata changes.");
+  requireIncludes("GOVERNANCE.md", "`scripts/generate-consumer-reference-evidence.mjs`");
+  requireIncludes("GOVERNANCE.md", "Browser state evidence begins with `scripts/create-component-state-session.mjs`");
+  requireIncludes("GOVERNANCE.md", "Receipt creation rejects dirty relevant sources.");
+  requireIncludes("GOVERNANCE.md", "browser-authored visual sidecars bind the same session, scenario, capture time, source digest, PNG bytes, dimensions, and hash");
+  requireIncludes("GOVERNANCE.md", "exactly 30 channel passes over the closed 40-file runtime set");
+  requireIncludes("GOVERNANCE.md", "Validation uses the receipt and completed manifest interval, not a wall-clock maximum age");
+  for (const profile of ["editorial", "terminal"]) {
+    for (const artifact of ["state-matrix.md", "keyboard-matrix.md", "evidence-coverage.md"]) {
+      requireIncludes("GOVERNANCE.md", `design-engineering/reference-profiles/governed-local/${profile}/generated/${artifact}`);
+    }
+  }
+}
+
+function requireLifecycleStates() {
+  for (const state of ["`draft`", "`stable`", "`deprecated`", "`experimental`", "`generated`"]) {
+    requireIncludes("GOVERNANCE.md", state);
+  }
+}
+
+function requireOwnership() {
+  for (const ownerRule of requiredCodeowners) {
+    requireIncludes(".github/CODEOWNERS", ownerRule);
+  }
+  requireIncludes("GOVERNANCE.md", "Review Ownership");
+  requireIncludes("GOVERNANCE.md", "CODEOWNERS");
+}
+
+function requireStalenessDecision() {
+  requireIncludes("GOVERNANCE.md", "Audit trigger:");
+  requireIncludes("GOVERNANCE.md", "node scripts/validate-links.mjs --json");
+}
+
+function requireCiwiring() {
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/component-state-workflow-contract.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/validate-governance.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/test-validate-governance.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-governance.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-governance.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/validate-domains.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/test-validate-domains.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-domains.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-domains.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-webpage-workflow.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-webpage-workflow.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/validate-consumer-reference.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/test-validate-consumer-reference.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/consumer-reference-case-runner.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/governed-profile-registry.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/promotion-attestation-contract.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/validate-promotion-rfc.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/test-validate-promotion-rfc.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-consumer-reference.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-consumer-reference.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-promotion-rfc.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-promotion-rfc.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "consumer-reference/schema/promotion-rfc.schema.json");
+  requireIncludes(".github/workflows/validate.yml", "consumer-reference/policies/shared-experimental.json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-consumer-reference-sentinel.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/baseline-schema-parity.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node -c scripts/test-component-state-source-contract.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-component-state-source-contract.mjs");
+  requireIncludes(".github/workflows/validate.yml", "consumer-reference/schema/visual-evidence.schema.json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/create-component-state-session.mjs");
+  requireIncludes(".github/workflows/validate.yml", "STATE_SESSION_RECEIPT=");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/finalize-component-state-evidence.mjs");
+  requireIncludes(".github/workflows/validate.yml", "--runtime-manifest");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-baseline-manifest.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-validate-baseline-manifest.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/test-summarize-sentinel-calibration.mjs");
+  requireIncludes(".github/workflows/validate.yml", "node scripts/validate-renderer-purity.mjs --json");
+  requireIncludes(".github/workflows/validate.yml", "checkout_sha=\"$(git -c safe.directory=\"$GITHUB_WORKSPACE\" rev-parse HEAD)\"");
+  requireIncludes(".github/workflows/validate.yml", "--repository \"changeroa/StyleGallery\" \\");
+  requireIncludes(".github/workflows/validate.yml", "--execution-repository \"$GITHUB_REPOSITORY\" \\");
+  requireIncludes(".github/workflows/validate.yml", "\"repository\":\"%s\",\"execution_repository\":\"%s\"");
+  requireIncludes(".github/workflows/validate.yml", "\"changeroa/StyleGallery\" \"$GITHUB_REPOSITORY\" \"$GITHUB_RUN_ID\"");
+  if (/safe\.directory(?:=|\s+)["']?\*["']?/.test(read(".github/workflows/validate.yml"))) {
+    failures.push(".github/workflows/validate.yml: broad Git safe.directory wildcard is forbidden");
+  }
+  requireIncludes(".github/workflows/validate.yml", "permissions:");
+  requireIncludes(".github/workflows/validate.yml", "contents: read");
+}
+
+function requireComponentStateCiIsolation() {
+  const relative = ".github/workflows/validate.yml";
+  for (const failure of componentStateWorkflowFailures(read(relative))) failures.push(`${relative}: ${failure}`);
+}
+
+function requireImmutableActions() {
+  const relative = ".github/workflows/validate.yml";
+  const workflow = read(relative);
+  for (const pin of immutableActionPins) if (!workflow.includes(pin)) failures.push(`${relative}: missing immutable action pin ${pin}`);
+  failures.push(...workflowActionFailures(workflow, relative));
+}
+
+function requireRootLinks() {
+  for (const relative of ["README.md", "index.md", "AGENTS.md"]) {
+    requirePattern(relative, /\[[^\]]+\]\(GOVERNANCE\.md\)/, "link target GOVERNANCE.md");
+  }
+  recommendIncludes("README.md", "[Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md)", "recommended link label missing [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md)");
+  recommendIncludes("index.md", "[Governance, lifecycle, and docs-as-code](GOVERNANCE.md)", "recommended link label missing [Governance, lifecycle, and docs-as-code](GOVERNANCE.md)");
+  recommendIncludes("AGENTS.md", "[Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md)", "recommended link label missing [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md)");
+  requireIncludes("README.md", "(DOMAINS.md)");
+  requireIncludes("index.md", "(DOMAINS.md)");
+  requireIncludes("AGENTS.md", "(DOMAINS.md)");
+}
+
+function requireEvidenceMap() {
+  requireIncludes("quality/evidence/executable-evidence.md", "scripts/validate-governance.mjs");
+  requireIncludes("quality/evidence/executable-evidence.md", "scripts/test-validate-governance.mjs");
+  recommendIncludes("quality/evidence/executable-evidence.md", "generated warnings, generated metadata, root link targets");
+  requireIncludes("quality/evidence/executable-evidence.md", "Missing governance file, generated warning, generated metadata, CODEOWNERS coverage, or stale policy fixtures must fail.");
+  requireIncludes("quality/evidence/executable-evidence.md", "Domain metadata, immutable provenance, scope boundaries, and root-route fixtures must fail.");
+  requireIncludes("quality/evidence/executable-evidence.md", "Consumer-reference handoffs, schema/runtime parity");
+  requireIncludes("quality/evidence/executable-evidence.md", "repository handoff omissions must fail");
+  requireIncludes("quality/evidence/executable-evidence.md", "The proposed Chromium sentinel preserves canonical card-grid geometry and truth-derived calibration evidence.");
+  requireIncludes("quality/evidence/executable-evidence.md", "Governed-local button states retain source-bound visual, DOM, and accessibility-tree evidence across both example profiles.");
+  requireIncludes("quality/evidence/executable-evidence.md", "one clean capture session binds the browser artifacts to the governed source inventory");
+  requireIncludes("quality/evidence/executable-evidence.md", "It does not prove product suitability, independent adoption, full accessibility, cross-browser behavior, or owner approval");
+  requireIncludes("GOVERNANCE.md", "node scripts/test-consumer-reference-sentinel.mjs");
+  requireIncludes("GOVERNANCE.md", "owner.enforcement: \"placeholder\"");
+  requireIncludes("GOVERNANCE.md", "review_independence: \"single_account\"");
+}
+
+function requireSentinelProvenanceBoundary() {
+  for (const relative of ["consumer-reference/contract.md", "quality/evidence/executable-evidence.md", "GOVERNANCE.md"]) {
+    for (const clause of sentinelProvenanceClauses) requireIncludes(relative, clause);
+  }
+}
+
+requireGovernanceMatrix();
+failures.push(...referenceOwnershipFailures(read("GOVERNANCE.md")));
+requireLifecycleStates();
+requireOwnership();
+requireStalenessDecision();
+requireCiwiring();
+failures.push(...consumerEvidenceGovernanceFailures({
+  evidence: read("quality/evidence/executable-evidence.md"),
+  freshnessWorkflow: read(".github/workflows/evidence-freshness.yml"),
+  governance: read("GOVERNANCE.md"),
+  validationWorkflow: read(".github/workflows/validate.yml"),
+}));
+requireComponentStateCiIsolation();
+requireImmutableActions();
+requireRootLinks();
+requireEvidenceMap();
+requireSentinelProvenanceBoundary();
+failures.push(...promotionGovernanceFailures(read));
+requireGeneratedWarning("CATALOG.md");
+requireGeneratedWarning("patterns/index.md");
+requireGeneratedWarning("patterns/stacking/index.md");
+requireGeneratedWarning("patterns/stacking/stack.md");
+requireGeneratedPatternMetadata("patterns/stacking/stack.md");
+
+const result = {
+  failures,
+  ok: failures.length === 0,
+  warnings,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: governance policy (${warnings.length} warnings)`);
+} else {
+  console.error(result.failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;

package/scripts/validate-ia.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { stripFencedCodeBlocks } from "./markdown-structure.mjs";
+
+const args = new Set(process.argv.slice(2));
+const json = args.has("--json");
+const root = process.cwd();
+const failures = [];
+
+const rootRoles = [
+  ["README.md", "Primary role: repository guide"],
+  ["index.md", "Primary role: OKF bundle map"],
+  ["GUIDE.md", "Primary role: planning workflow"],
+  ["CATALOG.md", "Primary role: pattern lookup"],
+];
+const domainRoutes = [
+  ["Layout", "layout/index.md"],
+  ["Motion", "motion/index.md"],
+  ["Design Engineering", "design-engineering/index.md"],
+  ["Platform Guides", "platform-guides/index.md"],
+];
+const leafDirectories = ["patterns", "recipes", "quality", "motion", "design-engineering", "platform-guides", "consumer-reference"];
+const nestedIndexes = [
+  "design-engineering/reference-profiles/index.md",
+  "design-engineering/reference-profiles/governed-local/index.md",
+  "design-engineering/reference-profiles/external-adaptation/index.md",
+];
+const governedProfileLinks = [
+  "[Editorial profile](editorial/profile.json)",
+  "[Editorial state matrix](editorial/generated/state-matrix.md)",
+  "[Editorial keyboard matrix](editorial/generated/keyboard-matrix.md)",
+  "[Editorial evidence coverage](editorial/generated/evidence-coverage.md)",
+  "[Terminal profile](terminal/profile.json)",
+  "[Terminal state matrix](terminal/generated/state-matrix.md)",
+  "[Terminal keyboard matrix](terminal/generated/keyboard-matrix.md)",
+  "[Terminal evidence coverage](terminal/generated/evidence-coverage.md)",
+];
+const migrationRoutes = [
+  ["README.md", "[Consumer Migration Readiness](design-engineering/consumer-migration-readiness.md)"],
+  ["index.md", "[Consumer migration readiness](design-engineering/consumer-migration-readiness.md)"],
+  ["design-engineering/index.md", "[Consumer Migration Readiness](consumer-migration-readiness.md)"],
+  ["consumer-reference/index.md", "[Consumer Migration Readiness](../design-engineering/consumer-migration-readiness.md)"],
+  ["quality/index.md", "[Consumer migration evidence gate](gates/consumer-migration-evidence.md)"],
+  ["quality/gates/index.md", "[Consumer migration evidence gate](consumer-migration-evidence.md)"],
+  ["quality/evidence/index.md", "[Consumer migration evidence](consumer-migration.md)"],
+];
+
+function read(relative) {
+  const target = path.join(root, relative);
+  if (!fs.existsSync(target)) {
+    failures.push(`${relative}: missing file`);
+    return "";
+  }
+  return fs.readFileSync(target, "utf8");
+}
+
+function walk(dir) {
+  const absolute = path.join(root, dir);
+  if (!fs.existsSync(absolute)) return [];
+  return fs.readdirSync(absolute, { withFileTypes: true }).flatMap((entry) => {
+    const next = path.join(absolute, entry.name);
+    if (entry.isDirectory()) return walk(path.relative(root, next));
+    if (!entry.isFile() || !entry.name.endsWith(".md") || entry.name === "index.md") return [];
+    return [path.relative(root, next)];
+  });
+}
+
+function requireIncludes(relative, text) {
+  if (!stripFencedCodeBlocks(read(relative)).includes(text)) failures.push(`${relative}: missing ${text}`);
+}
+
+function requireRootRoles() {
+  for (const [relative, role] of rootRoles) {
+    requireIncludes(relative, role);
+  }
+  requireIncludes("README.md", "## Repository Entry Roles");
+  requireIncludes("README.md", "## Task Routes");
+  requireIncludes("README.md", "## Link Policy");
+  requireIncludes("README.md", "Navigation links");
+  requireIncludes("README.md", "Citation links");
+  requireIncludes("README.md", "Dependency links");
+  requireIncludes("quality/index.md", "## Tree-Test Findability QA");
+  requireIncludes("README.md", "[Consumer Reference](consumer-reference/index.md)");
+  requireIncludes("index.md", "[Consumer reference](consumer-reference/index.md)");
+  requireIncludes("design-engineering/index.md", "[Reference Profiles](reference-profiles/index.md)");
+  requireIncludes("design-engineering/reference-profiles/index.md", "[External Adaptation](external-adaptation/index.md)");
+  requireIncludes("design-engineering/reference-profiles/index.md", "[Governed Local Profiles](governed-local/index.md)");
+  for (const link of governedProfileLinks) {
+    requireIncludes("design-engineering/reference-profiles/governed-local/index.md", link);
+  }
+  for (const [relative, link] of migrationRoutes) requireIncludes(relative, link);
+}
+
+function requireTaskRoutes() {
+  const content = stripFencedCodeBlocks(read("README.md"));
+  const section = content.split("## Task Routes")[1]?.split("\n## ")[0] ?? "";
+  const routeRows = section.split("\n").filter((line) => /^\| `[^`]+` \| \[[^\]]+\]\([^)]+\) \|/.test(line));
+  if (routeRows.length < 10) failures.push(`README.md: expected at least 10 task route rows, found ${routeRows.length}`);
+}
+
+function requireDomainRoutes() {
+  for (const relative of ["README.md", "index.md"]) {
+    for (const [label, target] of domainRoutes) requireIncludes(relative, `[${label}](${target})`);
+  }
+}
+
+function requireLeafNavigation() {
+  for (const file of [...leafDirectories.flatMap(walk), ...nestedIndexes]) {
+    const content = stripFencedCodeBlocks(read(file));
+    if (!/^Parent: \[[^\]]+\]\([^)]+\)/m.test(content)) failures.push(`${file}: missing Parent navigation link`);
+    if (!/^Next: \[[^\]]+\]\([^)]+\)/m.test(content)) failures.push(`${file}: missing Next navigation link`);
+  }
+}
+
+requireRootRoles();
+requireTaskRoutes();
+requireDomainRoutes();
+requireLeafNavigation();
+
+const result = {
+  checkedLeafFiles: leafDirectories.flatMap(walk).length + nestedIndexes.length,
+  failures,
+  ok: failures.length === 0,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: ${result.checkedLeafFiles} IA leaf files`);
+} else {
+  console.error(result.failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;

package/scripts/validate-links.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = new Set(process.argv.slice(2));
+const json = args.has("--json");
+const root = process.cwd();
+const failures = [];
+
+function walk(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === ".git" || entry.name === ".omo" || entry.name === "node_modules") return [];
+    const next = path.join(dir, entry.name);
+    if (entry.isDirectory()) return walk(next);
+    if (!entry.isFile() || !entry.name.endsWith(".md")) return [];
+    return [next];
+  });
+}
+
+function stripFencedCodeBlocks(content) {
+  return content.replace(/```[\s\S]*?```/g, "");
+}
+
+function localTarget(rawTarget) {
+  const target = rawTarget.trim();
+  if (!target || target.startsWith("#")) return null;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) return null;
+  return target.split("#")[0].split("?")[0];
+}
+
+function checkLink(file, target) {
+  const local = localTarget(target);
+  if (!local) return;
+  const decoded = decodeURIComponent(local);
+  const absolute = path.resolve(path.dirname(file), decoded);
+  if (!absolute.startsWith(root)) {
+    failures.push(`${path.relative(root, file)}: link escapes repository: ${target}`);
+    return;
+  }
+  if (!fs.existsSync(absolute)) failures.push(`${path.relative(root, file)}: missing link target: ${target}`);
+}
+
+const files = walk(root);
+for (const file of files) {
+  const content = stripFencedCodeBlocks(fs.readFileSync(file, "utf8"));
+  for (const match of content.matchAll(/(?<!!)\[[^\]]+\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+    checkLink(file, match[1]);
+  }
+}
+
+const result = {
+  checkedFiles: files.length,
+  failures,
+  ok: failures.length === 0,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: ${files.length} markdown files`);
+} else {
+  console.error(result.failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;

package/scripts/validate-okf.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = new Set(process.argv.slice(2));
+const json = args.has("--json");
+const root = process.cwd();
+const ignoredDirs = new Set([".git", ".omo", "node_modules"]);
+const failures = [];
+
+function walk(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (ignoredDirs.has(entry.name)) return [];
+    const next = path.join(dir, entry.name);
+    if (entry.isDirectory()) return walk(next);
+    return entry.isFile() && entry.name.endsWith(".md") ? [next] : [];
+  });
+}
+
+function frontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const metadata = {};
+  for (const line of match[1].split("\n")) {
+    const index = line.indexOf(":");
+    if (index === -1) continue;
+    metadata[line.slice(0, index).trim()] = line.slice(index + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return metadata;
+}
+
+function hasRootOnlyOkfFrontmatter(file, metadata) {
+  return file === "index.md" && metadata && Object.keys(metadata).every((key) => key === "okf_version");
+}
+
+function checkIndex(file, content) {
+  const metadata = frontmatter(content);
+  if (metadata && !hasRootOnlyOkfFrontmatter(file, metadata)) {
+    failures.push(`${file}: index.md must not contain concept frontmatter`);
+  }
+  if (!content.match(/^#\s+\S/m)) failures.push(`${file}: index.md must contain at least one heading`);
+  if (!content.match(/\[[^\]]+\]\([^)]+\)/)) failures.push(`${file}: index.md must list at least one markdown link`);
+}
+
+function checkLog(file, content) {
+  if (frontmatter(content)) failures.push(`${file}: log.md must not contain frontmatter`);
+  if (!content.match(/^#\s+\S/m)) failures.push(`${file}: log.md must contain a title heading`);
+  const dateHeadings = [...content.matchAll(/^##\s+(.+)$/gm)].map((match) => match[1].trim());
+  for (const heading of dateHeadings) {
+    if (!heading.match(/^\d{4}-\d{2}-\d{2}$/)) failures.push(`${file}: log.md date heading must be YYYY-MM-DD: ${heading}`);
+  }
+}
+
+function checkConcept(file, content) {
+  const metadata = frontmatter(content);
+  if (!metadata) {
+    failures.push(`${file}: missing OKF frontmatter`);
+    return;
+  }
+  if (!metadata.type) failures.push(`${file}: missing required OKF type`);
+}
+
+const files = walk(root);
+let conceptCount = 0;
+let indexCount = 0;
+let logCount = 0;
+
+for (const absolute of files) {
+  const file = path.relative(root, absolute);
+  const content = fs.readFileSync(absolute, "utf8");
+  const basename = path.basename(file);
+  if (basename === "index.md") {
+    indexCount += 1;
+    checkIndex(file, content);
+  } else if (basename === "log.md") {
+    logCount += 1;
+    checkLog(file, content);
+  } else {
+    conceptCount += 1;
+    checkConcept(file, content);
+  }
+}
+
+if (!files.includes(path.join(root, "index.md"))) failures.push("missing root index.md");
+if (!files.includes(path.join(root, "log.md"))) failures.push("missing root log.md");
+
+const result = {
+  ok: failures.length === 0,
+  conceptCount,
+  indexCount,
+  logCount,
+  failures,
+};
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`ok: ${conceptCount} concepts, ${indexCount} indexes, ${logCount} logs`);
+} else {
+  console.error(failures.join("\n"));
+}
+
+process.exitCode = result.ok ? 0 : 1;