hypomnema 1.3.4 → 1.4.0

package/scripts/check-versions.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// check-versions.mjs — assert every version-carrying file in the repo agrees, and
+// (with --tag) that they all match the release tag. This makes the release pipeline
+// OWN the plugin channel: a forgotten plugin.json / marketplace.json / hypo-config /
+// lockfile bump hard-fails the release instead of publishing a split-version plugin.
+//
+// The set mirrors scripts/bump-version.mjs (package.json, .claude-plugin/plugin.json,
+// .claude-plugin/marketplace.json, templates/hypo-config.md) PLUS package-lock.json,
+// which npm — not bump-version — manages, so it can lag a bump and silently break
+// `npm ci`. README/CHANGELOG carry prose version HISTORY (every past vX.Y.Z), not a
+// single release authority, so they are intentionally excluded (covered by the
+// bilingual + README-reconcile checklist instead).
+//
+// Usage:
+//   node scripts/check-versions.mjs               # assert all files agree
+//   node scripts/check-versions.mjs --tag v1.4.0  # also assert they equal the tag
+//   node scripts/check-versions.mjs --root <dir>  # point at a fixture (tests)
+//   node scripts/check-versions.mjs --json
+//
+// Exit 0 = consistent (and, with --tag, matches). Exit 1 = drift / unreadable / mismatch.
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseArgs(argv) {
+  const args = { root: null, tag: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--root=')) args.root = a.slice(7);
+    else if (a === '--root') args.root = argv[++i];
+    else if (a.startsWith('--tag=')) args.tag = a.slice(6);
+    else if (a === '--tag') args.tag = argv[++i];
+    else if (a === '--json') args.json = true;
+  }
+  return args;
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function readJson(abs) {
+  return JSON.parse(readFileSync(abs, 'utf-8'));
+}
+
+// Collect {label, version} for every authoritative location. A location that
+// cannot be read or whose field is missing becomes {label, version: null, error}.
+function collectVersions(root) {
+  const sources = [];
+  const push = (label, fn) => {
+    try {
+      const v = fn();
+      if (typeof v !== 'string' || v.length === 0) {
+        sources.push({ label, version: null, error: 'version field missing or empty' });
+      } else {
+        sources.push({ label, version: v });
+      }
+    } catch (err) {
+      sources.push({ label, version: null, error: err?.message ?? String(err) });
+    }
+  };
+
+  push('package.json', () => readJson(join(root, 'package.json')).version);
+
+  // package-lock.json carries the version in TWO top-level spots (lockfileVersion 3):
+  // the root `.version` and `.packages[""].version`. Dependency versions deeper in
+  // the tree are NOT release authorities and must not be read.
+  push('package-lock.json (root)', () => readJson(join(root, 'package-lock.json')).version);
+  push('package-lock.json (packages[""])', () => {
+    const lock = readJson(join(root, 'package-lock.json'));
+    return lock.packages && lock.packages[''] ? lock.packages[''].version : undefined;
+  });
+
+  const pluginName = (() => {
+    try {
+      return readJson(join(root, '.claude-plugin', 'plugin.json')).name;
+    } catch {
+      return null;
+    }
+  })();
+
+  push(
+    '.claude-plugin/plugin.json',
+    () => readJson(join(root, '.claude-plugin', 'plugin.json')).version,
+  );
+
+  // Select the marketplace entry BY NAME (matching plugin.json), not by position:
+  // Claude Code's runtime resolves plugins by name (hooks/version-check.mjs), and a
+  // future second marketplace entry would make plugins[0] the wrong authority.
+  push('.claude-plugin/marketplace.json (entry: ' + (pluginName ?? '?') + ')', () => {
+    const mp = readJson(join(root, '.claude-plugin', 'marketplace.json'));
+    const plugins = Array.isArray(mp.plugins) ? mp.plugins : [];
+    if (!pluginName)
+      throw new Error('plugin.json name unreadable — cannot match marketplace entry');
+    const matches = plugins.filter((p) => p && p.name === pluginName);
+    if (matches.length !== 1) {
+      throw new Error(
+        `expected exactly one marketplace entry named "${pluginName}", found ${matches.length}`,
+      );
+    }
+    return matches[0].version;
+  });
+
+  // hypo-config.md frontmatter: version: "X.Y.Z"
+  push('templates/hypo-config.md', () => {
+    const text = readFileSync(join(root, 'templates', 'hypo-config.md'), 'utf-8');
+    const m = text.match(/^version:\s*"?([^"\n]+)"?/m);
+    return m ? m[1].trim() : undefined;
+  });
+
+  return sources;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || REPO_ROOT;
+  const sources = collectVersions(root);
+
+  const errored = sources.filter((s) => s.error);
+  const versions = [...new Set(sources.filter((s) => s.version).map((s) => s.version))];
+
+  // Normalize the tag by stripping exactly one leading `v` (release tags are vX.Y.Z,
+  // file versions are X.Y.Z). Track tag PRESENCE separately from the normalized
+  // value: a bare `v` (or any tag that normalizes to empty / non-semver) must HARD
+  // FAIL, not be mistaken for "no tag supplied" — otherwise a `git tag v` push would
+  // bypass the release gate. This preserves the old "Validate tag matches package
+  // version" guarantee while widening it to every channel.
+  const hasTag = args.tag != null;
+  const tagVersion = hasTag ? args.tag.replace(/^v/, '') : null;
+  const tagValid = hasTag && /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(tagVersion);
+
+  const consistent = errored.length === 0 && versions.length === 1;
+  const tagOk = !hasTag || (tagValid && consistent && versions[0] === tagVersion);
+  const ok = consistent && tagOk;
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { ok, consistent, hasTag, tagVersion, tagValid, distinctVersions: versions, sources },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const width = Math.max(...sources.map((s) => s.label.length));
+    for (const s of sources) {
+      const val = s.error ? `ERROR: ${s.error}` : s.version;
+      console.log(`  ${s.label.padEnd(width)}  ${val}`);
+    }
+    if (errored.length) {
+      console.error(`\n✗ ${errored.length} version source(s) unreadable.`);
+    } else if (!consistent) {
+      console.error(
+        `\n✗ version drift — ${versions.length} distinct versions: ${versions.join(', ')}`,
+      );
+    } else if (hasTag && !tagValid) {
+      console.error(`\n✗ tag "${args.tag}" does not normalize to a valid semver version`);
+    } else if (!tagOk) {
+      console.error(
+        `\n✗ tag ${args.tag} (→ ${tagVersion}) does not match the file version ${versions[0]}`,
+      );
+    } else {
+      console.log(
+        `\n✓ all version-carrying files agree on ${versions[0]}${tagVersion ? ` (matches tag ${args.tag})` : ''}`,
+      );
+    }
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+main();

package/scripts/crystallize.mjs

@@ -60,20 +60,14 @@
  *     hard-fails regardless of scope.
  */
 
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-  writeFileSync,
-  mkdirSync,
-  renameSync,
-} from 'fs';
-import { join, relative, extname, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'fs';
+import { join, dirname } from 'path';
+import { hostname } from 'os';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
-import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
+import { collectPagesCrystallize, extractWikilinks } from './lib/wikilink.mjs';
 import {
   sessionCloseFileStatus,
   sessionCloseGlobalStatus,
@@ -756,9 +750,21 @@ function applySessionClose(args) {
       // otherwise mistake it for the evidence file. The dated `## [date] ...`
       // heading lives inside the entry, so freshness / derive / design-history
       // are unchanged.
+      // PRAC-17 audit fields. The shard frontmatter is git-tracked and synced, so
+      // `device` is an INTENTIONAL synced multi-machine identifier (privacy note:
+      // docs/ARCHITECTURE.md). It is a CREATOR-only stamp — only the session/
+      // machine that first seeds the daily shard is recorded; later same-day
+      // appends do not touch it. The per-session-accurate store is the LOCAL
+      // (.cache/, gitignored) index.jsonl written by hypo-session-record.mjs.
+      // `session_id` is honest naming: the value is the Claude session UUID, and
+      // it is present only on the Stop-chain close path that passes --session-id.
+      const device = String(hostname() || 'unknown').replace(/[\r\n]/g, '');
+      const auditFm =
+        (args.sessionId ? `session_id: ${String(args.sessionId).replace(/[\r\n]/g, '')}\n` : '') +
+        `device: ${device}\n`;
       const header =
         `---\ntitle: Session Log ${date} (${project})\n` +
-        `type: session-log\nupdated: ${date}\n---\n\n` +
+        `type: session-log\nupdated: ${date}\n${auditFm}---\n\n` +
         `# Session Log ${date} (${project})\n`;
       const entry = payload.sessionLog.entry;
       const body = entry.endsWith('\n') ? entry : `${entry}\n`;
@@ -944,21 +950,6 @@ function applySessionClose(args) {
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
-function collectPages(dir, root, acc = [], ignorePatterns = []) {
-  if (!existsSync(dir)) return acc;
-  for (const entry of readdirSync(dir)) {
-    if (entry.startsWith('.')) continue;
-    const full = join(dir, entry);
-    if (isScanIgnored(full, root, ignorePatterns)) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) collectPages(full, root, acc, ignorePatterns);
-    else if (extname(entry) === '.md') {
-      acc.push({ path: full, rel: relative(root, full) });
-    }
-  }
-  return acc;
-}
-
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
@@ -983,10 +974,6 @@ function parseTags(fm) {
     .filter(Boolean);
 }
 
-function extractWikilinks(content) {
-  return [...content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)].map((m) => m[1].trim());
-}
-
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -1005,7 +992,7 @@ if (args.checkSessionClose) {
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const pagesDir = join(args.hypoDir, 'pages');
-const pages = collectPages(pagesDir, args.hypoDir, [], ignorePatterns);
+const pages = collectPagesCrystallize(pagesDir, args.hypoDir, ignorePatterns);
 
 const tagGroups = {}; // tag → [{ slug, title }]
 const unlinked = []; // pages with no outbound wikilinks

package/scripts/doctor.mjs

@@ -528,10 +528,19 @@ function checkSyncState(hypoDir) {
     pass('Sync state', 'No unresolved sync failures');
   } else {
     const last = entries[entries.length - 1];
-    warn(
-      'Sync state',
-      `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.`,
-    );
+    // A merge conflict needs a real manual merge, not a plain push/pull — give
+    // the same explicit guidance session-start does instead of the generic hint.
+    if (String(last.op || '').startsWith('conflict')) {
+      warn(
+        'Sync state',
+        `${entries.length} unresolved sync issue(s) — last: remote diverged (merge conflict). Your local work is committed; the other machine's version is on the remote. Resolve with \`git pull --no-rebase\`, fix conflicts, then push.`,
+      );
+    } else {
+      warn(
+        'Sync state',
+        `${entries.length} unresolved failure(s) — last: ${last.op || '?'} at ${last.timestamp || '?'}. Inspect .cache/sync-state.json or push/pull manually to clear.`,
+      );
+    }
   }
 }
 

package/scripts/feedback.mjs

@@ -48,6 +48,8 @@ import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
+import { FAILURE_TYPE_ENUM } from './lib/failure-type.mjs';
+import { parseFrontmatter } from './lib/frontmatter.mjs';
 
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 
@@ -69,6 +71,7 @@ function parseArgs(argv) {
     promoteToGlobal: false,
     reason: null,
     source: null,
+    failureType: null,
     behavior: null,
     claudeHome: null,
     projectId: null,
@@ -91,6 +94,7 @@ function parseArgs(argv) {
     else if (arg === '--promote-to-global') args.promoteToGlobal = true;
     else if (arg.startsWith('--reason=')) args.reason = arg.slice(9);
     else if (arg.startsWith('--source=')) args.source = arg.slice(9);
+    else if (arg.startsWith('--failure-type=')) args.failureType = arg.slice(15);
     else if (arg.startsWith('--behavior=')) args.behavior = arg.slice(11);
     else if (arg.startsWith('--claude-home=')) args.claudeHome = expandHome(arg.slice(14));
     else if (arg.startsWith('--project-id=')) args.projectId = arg.slice(13);
@@ -132,6 +136,16 @@ function parseTargets(raw) {
     .filter(Boolean);
 }
 
+// FEAT-1: `failure_type` is OPTIONAL — an unset value is always fine. A set value
+// must be one of the eight enum members (same vocabulary lint enforces). Returns
+// an error string or null. Shared by create (validateClassification) and append.
+function failureTypeError(value) {
+  if (!value) return null;
+  if (!FAILURE_TYPE_ENUM.includes(value))
+    return `--failure-type invalid: "${value}" (allowed: ${FAILURE_TYPE_ENUM.join(', ')})`;
+  return null;
+}
+
 // Validate the create-mode classification. Returns an array of error strings.
 function validateClassification(args, targets) {
   const errs = [];
@@ -151,6 +165,8 @@ function validateClassification(args, targets) {
     errs.push(`--priority must be an integer 1-5 (got "${args.priority}")`);
   if (!args.memorySummary) errs.push('--memory-summary is required');
   if (!args.reason) errs.push('--reason is required');
+  const ftErr = failureTypeError(args.failureType);
+  if (ftErr) errs.push(ftErr);
 
   // CLAUDE.md projection candidates must be global + L1 (ADR 0031 §6 filter), and
   // carry the two conditional fields (lint #8). Enforce here so we never write a
@@ -201,6 +217,7 @@ function renderPage(args, targets, today) {
   }
   lines.push(`reason: ${oneLine(args.reason)}`);
   lines.push(`source: ${oneLine(args.source || `session:${today}`)}`);
+  if (args.failureType) lines.push(`failure_type: ${args.failureType}`);
   lines.push(`corrected_at: ${today}`);
   lines.push(`updated: ${today}`);
   lines.push(`created: ${today}`);
@@ -233,6 +250,24 @@ function bumpUpdated(content, today) {
   return content.replace(m[0], `---\n${bumped}\n---`);
 }
 
+// Set `failure_type: <value>` in the leading frontmatter block. Scoped to the
+// first `---` fence (like bumpUpdated) so a body line starting "failure_type:" is
+// never touched; the `^` anchor keeps it top-level (an indented/nested key starts
+// with whitespace and won't match). CRLF-aware (the shared parser accepts CRLF,
+// so this must too — an LF-only match would silently skip a CRLF page) and it
+// REPLACES an existing empty `failure_type:` line rather than leaving it blank.
+// The caller only invokes this when the page has no real value (absent or empty),
+// so a populated top-level key never reaches here.
+function addFailureType(content, value) {
+  const m = content.match(/^---(\r?\n)([\s\S]*?)\r?\n---/);
+  if (!m) return content; // no frontmatter fence to host the field
+  const nl = m[1];
+  const fm = /^failure_type:\s*.*$/m.test(m[2])
+    ? m[2].replace(/^failure_type:\s*.*$/m, `failure_type: ${value}`)
+    : `${m[2]}${nl}failure_type: ${value}`;
+  return content.replace(m[0], `---${nl}${fm}${nl}---`);
+}
+
 function writeFeedback(args, today) {
   const feedbackDir = join(args.hypoDir, 'pages', 'feedback');
   const filePath = join(feedbackDir, `${args.topic}.md`);
@@ -244,7 +279,39 @@ function writeFeedback(args, today) {
     // Append a dated entry; preserve existing frontmatter classification.
     mode = 'append';
     const existing = readFileSync(filePath, 'utf-8');
-    const appended = existing.trimEnd() + `\n\n## ${today}\n\n${args.entry}\n`;
+    // FEAT-1: failure_type is a per-page classification property. On append,
+    // set it if the page has none, error if it conflicts with an existing value,
+    // no-op if it matches. Without the flag, append is byte-for-byte unchanged.
+    const existingFt = (parseFrontmatter(existing) || {}).failure_type || null;
+    if (args.failureType) {
+      const ftErr = failureTypeError(args.failureType);
+      if (ftErr) {
+        console.error(`Error: ${ftErr}`);
+        process.exit(1);
+      }
+      if (existingFt && existingFt !== args.failureType) {
+        console.error(
+          `Error: failure_type mismatch on append: page has "${existingFt}", ` +
+            `--failure-type=${args.failureType}. A feedback page carries a single ` +
+            `failure_type; use a separate topic for a different failure type.`,
+        );
+        process.exit(1);
+      }
+    }
+    let appended = existing.trimEnd() + `\n\n## ${today}\n\n${args.entry}\n`;
+    if (args.failureType && !existingFt) {
+      appended = addFailureType(appended, args.failureType);
+      // Fail loud rather than silently appending without the field: if the page's
+      // frontmatter is too malformed to host failure_type (no fence at all), the
+      // set-if-absent contract could not be honored.
+      if ((parseFrontmatter(appended) || {}).failure_type !== args.failureType) {
+        console.error(
+          `Error: could not set failure_type on "${args.topic}" — its frontmatter ` +
+            `is malformed (no parseable --- block). Fix the page, then retry.`,
+        );
+        process.exit(1);
+      }
+    }
     content = bumpUpdated(appended, today);
   } else {
     mode = 'create';

package/scripts/graph.mjs

@@ -14,10 +14,11 @@
  *   --min-edges=<n>     Only include nodes with at least N edges (default: 0)
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { join, relative, extname, basename } from 'path';
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
-import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
+import { collectPagesGraph, extractWikilinks } from './lib/wikilink.mjs';
 
 // ── arg parsing ───────────────────────────────────────────────────────────────
 
@@ -32,24 +33,6 @@ function parseArgs(argv) {
   return args;
 }
 
-// ── page collector ────────────────────────────────────────────────────────────
-
-function collectPages(dir, root, pages = [], ignorePatterns = []) {
-  if (!existsSync(dir)) return pages;
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    if (isScanIgnored(full, root, ignorePatterns)) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      collectPages(full, root, pages, ignorePatterns);
-    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
-      const slug = relative(root, full).replace(/\.md$/, '').replace(/\\/g, '/');
-      pages.push({ path: full, slug, bare: basename(full, '.md') });
-    }
-  }
-  return pages;
-}
-
 // ── slug resolver ─────────────────────────────────────────────────────────────
 
 function buildSlugIndex(pages) {
@@ -61,16 +44,6 @@ function buildSlugIndex(pages) {
   return index;
 }
 
-// ── wikilink extractor ────────────────────────────────────────────────────────
-
-function extractWikilinks(content) {
-  const links = [];
-  for (const m of content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)) {
-    links.push(m[1].trim());
-  }
-  return links;
-}
-
 // ── graph builder ─────────────────────────────────────────────────────────────
 
 function buildGraph(pages, slugIndex) {
@@ -180,7 +153,7 @@ const args = parseArgs(process.argv);
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const scanDirs = ['pages', 'projects'].map((d) => join(args.hypoDir, d));
-const pages = scanDirs.flatMap((d) => collectPages(d, args.hypoDir, [], ignorePatterns));
+const pages = scanDirs.flatMap((d) => collectPagesGraph(d, args.hypoDir, ignorePatterns));
 const slugIndex = buildSlugIndex(pages);
 const graph = buildGraph(pages, slugIndex);
 

package/scripts/init.mjs

@@ -46,6 +46,7 @@ import {
   readFileIfRegular,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
+import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
@@ -477,7 +478,7 @@ function writePkgJson(dryRun, extraFields = {}) {
     ...existing,
     pkgRoot: PKG_ROOT,
     pkgVersion: PKG_VERSION,
-    schemaVersion: '2.0',
+    schemaVersion: templateSchemaVersion(PKG_ROOT) ?? '2.1',
     ...extraFields,
   };
   if (!dryRun) {

package/scripts/lib/failure-type.mjs

@@ -0,0 +1,33 @@
+// Feedback page `failure_type:` field vocabulary — shared single source of truth.
+//
+// Consumed by:
+//   - scripts/lint.mjs      (lint-time enum validation of feedback frontmatter)
+//   - scripts/feedback.mjs  (create/append-time --failure-type validation)
+// Keep this the ONLY definition; both consumers import it so the two validators
+// never drift (mirrors feedback-scope.mjs / ADR 0034). stats.mjs aggregates by
+// plain string and does not validate, so it is intentionally not a consumer.
+//
+// `failure_type` is an OPTIONAL field: it classifies feedback that came from a
+// real failure incident. Pure preferences / new conventions ("always do X")
+// omit it. Order below is the precedence used when classifying — most specific
+// first (a failure that matches several is labeled by the earliest match):
+//   hallucination       fabricated a fact / API / path
+//   false-completion    declared "done" without running the required gate/test
+//   process-stall       stopped instead of asking / continuing when it should
+//   over-caution        re-asked / re-gated despite standing authority
+//   overreach           acted beyond the requested scope
+//   incompleteness      started correctly but omitted a required step / scope
+//   instruction-miss    ignored an explicit this-session instruction
+//   convention-violation broke a standing documented convention (not restated)
+// The runtime does NOT enforce the precedence tree — it only validates that a
+// supplied value is one of these eight; classification is a human judgement.
+export const FAILURE_TYPE_ENUM = [
+  'hallucination',
+  'false-completion',
+  'process-stall',
+  'over-caution',
+  'overreach',
+  'incompleteness',
+  'instruction-miss',
+  'convention-violation',
+];

package/scripts/lib/frontmatter.mjs

@@ -1,14 +1,35 @@
+// A YAML block sequence entry: `-` followed by whitespace or end-of-line.
+// Narrower than `startsWith('-')` so a (nonstandard) plain key like `-key:` is
+// still read rather than mistaken for a list item.
+export const SEQUENCE_ENTRY_RE = /^-(\s|$)/;
+
+// Lenient, top-level-only frontmatter field extractor (NOT a YAML parser).
+// Reads only unindented `key: value` lines, skipping indented lines and list
+// items, so a nested mapping (e.g. a `type:` inside a `relations:` list) cannot
+// clobber the page's real top-level field. Without this a `learning` page
+// carrying a relations block was mis-read as `type: depends_on` and silently
+// dropped by type-routed consumers (doctor's verify-freshness scan, lint's
+// type check). First-wins on a repeated top-level key. Assumes the Hypomnema
+// convention of unindented root fields (templates/SCHEMA.md §3). scripts/lint.mjs
+// imports this and adds a separate W9 pass for invalid-YAML classes a real
+// parser would reject.
 export function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
   const fm = {};
   for (const line of m[1].split(/\r?\n/)) {
+    if (/^\s/.test(line) || SEQUENCE_ENTRY_RE.test(line)) continue; // nested / list item
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line
+    const key = line.slice(0, idx).trim();
+    if (!key || Object.hasOwn(fm, key)) continue; // first-wins
+    fm[key] = line
       .slice(idx + 1)
       .trim()
-      .replace(/\s*#.*$/, '')
+      // strip a trailing YAML comment: `#` must follow whitespace to start one,
+      // so `concept#bad` stays literal (and still trips lint's unknown-type W2)
+      // while `concept # note` loses the comment.
+      .replace(/\s+#.*$/, '')
       .replace(/^["']|["']$/g, '');
   }
   return fm;

package/scripts/lib/schema-vocab.mjs

@@ -94,3 +94,38 @@ export function parseSchemaPageDirs(hypoDir) {
   }
   return dirs;
 }
+
+// Type-token shape: lowercase identifier (a-z, digits, hyphen). Excludes
+// memory-layer rows whose first cell is a filename (`hot.md`, `log.md`) — those
+// carry a `.` and never match — so only real type names survive.
+const TYPE_TOKEN_RE = /^[a-z][a-z0-9-]+$/;
+
+// Derive the set of valid page `type` values from the SCHEMA "Page Type
+// Taxonomy" table — the FIRST backticked cell of each table row (the type
+// column). Single source of truth, mirroring parseSchemaPageDirs: adding a type
+// row to a vault's SCHEMA automatically widens the accepted types, so a
+// vault-local extension (e.g. working-doc / draft / qa-run) stops tripping the
+// W2 unknown-type warning without editing lint. Returns an empty Set when
+// SCHEMA.md or the table is absent — callers union this with a hardcoded core so
+// the core types never depend on a present/complete SCHEMA.
+export function parseSchemaTypes(hypoDir) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return new Set();
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = TYPE_TAXONOMY_HEADER_RE.exec(content);
+  if (!headerMatch) return new Set();
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const section = nextH2 ? rest.slice(0, nextH2.index) : rest;
+
+  const types = new Set();
+  for (const rawLine of section.split('\n')) {
+    if (!rawLine.trimStart().startsWith('|')) continue;
+    const m = rawLine.match(/`([^`]+)`/); // first backtick token = type column
+    if (m && TYPE_TOKEN_RE.test(m[1].trim())) types.add(m[1].trim());
+  }
+  return types;
+}

package/scripts/lib/template-schema-version.mjs

@@ -0,0 +1,21 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// The SCHEMA version this package ships, read from templates/SCHEMA.md
+// frontmatter. init.mjs / upgrade.mjs stamp it into hypo-pkg.json metadata;
+// deriving it here (rather than hardcoding a literal at each write site) keeps
+// the stamped value from going stale on a schema bump — the failure mode that
+// FEAT-1's 2.0 → 2.1 bump would otherwise have introduced. Returns null only if
+// the template is missing/unreadable (a broken package), in which case callers
+// keep their prior literal default.
+export function templateSchemaVersion(pkgRoot) {
+  const p = join(pkgRoot, 'templates', 'SCHEMA.md');
+  if (!existsSync(p)) return null;
+  try {
+    const v = (parseFrontmatter(readFileSync(p, 'utf-8')) || {}).version;
+    return v ? String(v) : null;
+  } catch {
+    return null;
+  }
+}