hypomnema 1.4.0 → 1.4.2

package/scripts/lib/changelog-classify.mjs

@@ -0,0 +1,216 @@
+/**
+ * lib/changelog-classify.mjs — pure classifier + surface sanitizer for the
+ * section-model CHANGELOG (changelog-pr-guide, format.md §3 / §5).
+ *
+ * Two responsibilities, both pure (no fs/git/process) so tests/runner.mjs can
+ * exercise them on synthetic strings:
+ *
+ *   1. classifyChange(commitTitle) -> { section, basis }
+ *      Decide which of the three migrated sections a change belongs to.
+ *      Precedence (format.md §3): tracker ID first, Conventional-Commit type
+ *      second, the legacy heading hint third, a safe Chores fallback last.
+ *        - tracker:  FEAT-* -> New Features, ISSUE-* -> Bug Fixes,
+ *                    IMPR-* / PRAC-* -> Chores.  Tracker wins over type, so a
+ *                    `feat(...)` commit tagged IMPR-N lands in Chores, and a
+ *                    `docs(...)` commit tagged ISSUE-N lands in Bug Fixes.
+ *                    (IDs in this comment use an `N` placeholder, not a real
+ *                    digit, so check-tracker-ids does not flag this file.)
+ *        - type:     feat -> New Features, fix -> Bug Fixes, and the
+ *                    non-user-visible types (chore/refactor/docs/ci/perf/...) ->
+ *                    Chores.
+ *        - heading:  an ID-less, type-less pre-convention item maps by the
+ *                    legacy heading it sits under (Added -> New Features,
+ *                    Fixed -> Bug Fixes, Changed/Internal/... -> Chores), passed
+ *                    via opts.legacyHeading.
+ *        - fallback: nothing resolves -> Chores (basis tells the caller it was a
+ *                    guess, so a human can re-check).
+ *
+ *   2. sanitizeTrackerIds(text) -> text
+ *      Strip every wiki tracker ID (FEAT-/IMPR-/ISSUE-/PRAC-N) from public
+ *      surface, leaving the PR number (`#N`) as the only identifier
+ *      (format.md §5, "표면 ID 0"). It also cleans the `(FEAT-N)` parens the ID
+ *      left empty. NOTE: `fix #N` (the wiki fix-tracker) is NOT handled here —
+ *      that pattern is the domain of check-tracker-ids; the classifier output
+ *      never produces it. ADR anchors (`ADR NNNN`, `decisions/NNNN`) are left
+ *      intact: CHANGELOG history keeps them (format.md §10).
+ *
+ * Section keys are stable machine strings; the human heading text
+ * (`New Features` etc.) is mapped by SECTION_TITLE for callers that render.
+ */
+
+// Stable section keys. Order is the canonical render order (format.md §1).
+export const SECTION = {
+  NEW_FEATURES: 'new-features',
+  BUG_FIXES: 'bug-fixes',
+  CHORES: 'chores',
+};
+
+export const SECTION_TITLE = {
+  'new-features': 'New Features',
+  'bug-fixes': 'Bug Fixes',
+  'chores': 'Chores',
+};
+
+// Tracker-ID -> section, in precedence order. A change carries one tracker in
+// practice; if two ever co-occur, the earlier rule wins (FEAT > ISSUE > IMPR >
+// PRAC), so a feature-with-cleanup is surfaced as a feature.
+export const TRACKER_RULES = [
+  { prefix: 'FEAT', re: /\bFEAT-\d+\b/i, section: SECTION.NEW_FEATURES },
+  { prefix: 'ISSUE', re: /\bISSUE-\d+\b/i, section: SECTION.BUG_FIXES },
+  { prefix: 'IMPR', re: /\bIMPR-\d+\b/i, section: SECTION.CHORES },
+  { prefix: 'PRAC', re: /\bPRAC-\d+\b/i, section: SECTION.CHORES },
+];
+
+// Conventional-Commit type -> section (secondary signal). feat/fix are the two
+// user-facing buckets; everything else is internal -> Chores (format.md §4:
+// Chores is defined by KIND, not by visibility).
+export const TYPE_SECTION = {
+  feat: SECTION.NEW_FEATURES,
+  fix: SECTION.BUG_FIXES,
+  chore: SECTION.CHORES,
+  refactor: SECTION.CHORES,
+  docs: SECTION.CHORES,
+  ci: SECTION.CHORES,
+  perf: SECTION.CHORES,
+  build: SECTION.CHORES,
+  test: SECTION.CHORES,
+  style: SECTION.CHORES,
+};
+
+// Legacy CHANGELOG heading -> section (format.md §6, the section-bound rows
+// only). The hint used when neither a tracker ID nor a Conventional-Commit type
+// resolves a change (a pre-convention prose item under an old `### Added` etc.).
+// Headings that map to NON-section blocks (Highlights, Breaking, Upgrading,
+// Known Issues, Notes) are deliberately absent: they are structural, not one of
+// the three sections this function returns, so the caller routes them (§6/§8).
+export const HEADING_SECTION = {
+  added: SECTION.NEW_FEATURES,
+  fixed: SECTION.BUG_FIXES,
+  changed: SECTION.CHORES,
+  internal: SECTION.CHORES,
+  maintenance: SECTION.CHORES,
+  documentation: SECTION.CHORES,
+};
+
+// Normalize a legacy heading to its HEADING_SECTION key: drop a leading `###`,
+// the `⚠ ` warning glyph, and a trailing ` (한글)` variant marker, then
+// lowercase. `### Fixed (한글)` and `⚠ Breaking` both reduce cleanly.
+function normalizeHeading(heading) {
+  return String(heading == null ? '' : heading)
+    .replace(/^#+\s*/, '')
+    .replace(/^[⚠️\s]+/, '')
+    .replace(/\s*\(한글\)\s*$/, '')
+    .trim()
+    .toLowerCase();
+}
+
+// All four wiki tracker prefixes, as one alternation. Used by both the
+// classifier (read) and the sanitizer (strip). Kept here as the single source
+// so the two never drift.
+export const TRACKER_ID_RE = /\b(?:FEAT|IMPR|ISSUE|PRAC)-\d+\b/gi;
+
+// Internal labels that are NOT tracker IDs but must also leave the public
+// surface (format.md §10): `Track A`, `Track A-sot`, `OQ-34`. These are NOT
+// stripped by sanitizeTrackerIds — removing `Track A` cleanly needs a PR-number
+// substitution, which is a human migration call (T5), not a regex. detect them
+// so the migration can flag and replace them by hand rather than miss them.
+export const INTERNAL_LABEL_RE = /\bTrack [A-Z](?:-[a-z]+)?\b|\bOQ-\d+\b/g;
+
+// Parse the `type` out of a Conventional-Commit subject: `type(scope)!: rest`.
+// Returns the lowercased type or null. The scope and the breaking-change `!`
+// are optional.
+function commitType(text) {
+  const m = /^([a-zA-Z]+)(?:\([^)]*\))?!?:/.exec(String(text).trim());
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * Classify one change into a section, following format.md §3 precedence:
+ * tracker ID first, Conventional-Commit type second, the legacy heading hint
+ * third (for pre-convention prose items that carry neither), and a Chores
+ * fallback last. Returns { section, basis } where basis is
+ * 'tracker' | 'type' | 'heading' | 'fallback' — the basis is for the snapshot
+ * fixture / human audit, not public surface.
+ *
+ * @param {string} text  commit subject / changelog line to classify
+ * @param {{legacyHeading?: string}} [opts]  the `### Added` etc. the item sits
+ *   under, used only when text alone is ambiguous (an ID-less, type-less line).
+ * @returns {{section: string, basis: 'tracker'|'type'|'heading'|'fallback'}}
+ */
+export function classifyChange(text, opts = {}) {
+  const s = String(text == null ? '' : text);
+  // 1. tracker ID wins.
+  for (const rule of TRACKER_RULES) {
+    if (rule.re.test(s)) return { section: rule.section, basis: 'tracker' };
+  }
+  // 2. Conventional-Commit type.
+  const type = commitType(s);
+  if (type && TYPE_SECTION[type]) {
+    return { section: TYPE_SECTION[type], basis: 'type' };
+  }
+  // 3. legacy heading hint (format.md §3 step 3 / §6) — an old `### Added` item
+  //    with no conventional prefix maps by its heading, not the Chores default.
+  if (opts && opts.legacyHeading != null) {
+    const key = normalizeHeading(opts.legacyHeading);
+    if (key in HEADING_SECTION) return { section: HEADING_SECTION[key], basis: 'heading' };
+  }
+  // 4. safe default — surfaced as a guess so a human can re-check.
+  return { section: SECTION.CHORES, basis: 'fallback' };
+}
+
+/**
+ * Remove every wiki tracker ID from `text`, leaving `#N` PR numbers untouched.
+ * Cleans up the parens / stray whitespace the removed ID leaves behind so
+ * `... (FEAT-N) (#N)` becomes `... (#N)`, not `... () (#N)`.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitizeTrackerIds(text) {
+  if (text == null) return '';
+  let s = String(text);
+  // 1. drop the tracker IDs themselves.
+  s = s.replace(TRACKER_ID_RE, '');
+  // 2. parens the ID emptied: `()` or `(  )` -> gone.
+  s = s.replace(/\(\s*\)/g, '');
+  // 3. tidy whitespace the removal left: collapse runs, drop space hugging
+  //    brackets/punctuation, strip per-line trailing space.
+  s = s.replace(/[ \t]{2,}/g, ' ');
+  s = s.replace(/([([])[ \t]+/g, '$1');
+  s = s.replace(/[ \t]+([)\].,;:])/g, '$1');
+  // a removed leading label leaves orphaned punctuation at the start of a line
+  // (e.g. `ISSUE-N: foo` -> `: foo`); drop it. NOTE: a tracker ID glued to other
+  // text by a non-paren separator (`ISSUE-N/foo`) is not a CHANGELOG form and is
+  // left minimally cleaned.
+  s = s.replace(/^[ \t]*[:;,][ \t]*/gm, '');
+  s = s.replace(/[ \t]+$/gm, '');
+  return s.trim();
+}
+
+/**
+ * Find internal labels (`Track A`, `OQ-NN`) that format.md §10 wants off the
+ * public surface but that sanitizeTrackerIds intentionally does NOT auto-strip
+ * (they need a PR-number substitution, a human call). Returns the matches so the
+ * migration (T5) can flag and replace them rather than silently ship them.
+ *
+ * @param {string} text
+ * @returns {string[]}  matched labels (empty if none)
+ */
+export function detectInternalLabels(text) {
+  INTERNAL_LABEL_RE.lastIndex = 0;
+  const out = String(text == null ? '' : text).match(INTERNAL_LABEL_RE);
+  return out ? out : [];
+}
+
+/**
+ * Does `text` still carry any wiki tracker ID? A cheap predicate for the
+ * regression gate ("surface ID 0") — distinct from check-tracker-ids, which
+ * only blocks ISSUE-/fix #. This sees all four prefixes.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function hasTrackerId(text) {
+  TRACKER_ID_RE.lastIndex = 0;
+  return TRACKER_ID_RE.test(String(text == null ? '' : text));
+}

package/scripts/lib/check-bilingual.mjs

@@ -34,20 +34,99 @@ export function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// Section model (changelog-pr-guide format.md §1/§2). A version block carries
+// gated sections, each split into "#### English" / "#### 한국어" sub-blocks at
+// and after the Korean cutoff. Highlights is gated too (it has a curated Korean
+// half); Changelog and the migration callout are NOT gated (language-neutral).
+export const GATED_HEADINGS = ['Highlights', 'New Features', 'Bug Fixes', 'Chores'];
+
+// Korean-summary cutoff: 1.2.0 is the first release that shipped a Korean half
+// (empirically the first "### 한글 요약" in CHANGELOG.md). 1.0.0–1.1.0 are
+// English-only; we never fabricate a Korean half for them (format.md §9).
+export const KOREAN_CUTOFF = [1, 2, 0];
+
+// Parse "major.minor.patch" (ignoring any prerelease/build suffix) into a number
+// triple, or null if it does not look like semver.
+export function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v == null ? '' : v).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// Is `version` at or past the Korean cutoff (>= 1.2.0)? A prerelease of a
+// cutoff version (1.2.0-rc.1) counts as in-era. Unparseable → treated as not
+// meeting the cutoff (the gate then only checks English presence).
+export function meetsKoreanCutoff(version) {
+  const s = parseSemver(version);
+  if (!s) return false;
+  for (let i = 0; i < 3; i++) {
+    if (s[i] !== KOREAN_CUTOFF[i]) return s[i] > KOREAN_CUTOFF[i];
+  }
+  return true;
+}
+
+// Split `lines` into the sections introduced by a heading of exactly `hashes`
+// '#'. A section ends at the next same-level heading OR any higher-level (fewer
+// '#') heading; a deeper heading (more '#') stays inside the section body. So
+// slicing a version block at level 3 keeps each "### Section" with its nested
+// "#### English/한국어" lines, and re-slicing a section at level 4 yields those
+// sub-blocks. Returns [{ title, body: string[] }].
+function sliceSections(lines, hashes) {
+  const headRe = new RegExp(`^#{${hashes}} (.+?)\\s*$`);
+  const sameOrHigherRe = new RegExp(`^#{1,${hashes}} `);
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    const m = headRe.exec(line);
+    if (m) {
+      if (cur) out.push(cur);
+      cur = { title: m[1].trim(), body: [] };
+      continue;
+    }
+    if (cur) {
+      // a same-or-higher level heading (that is not our own level) closes the
+      // open section without opening a tracked one.
+      if (sameOrHigherRe.test(line)) {
+        out.push(cur);
+        cur = null;
+        continue;
+      }
+      cur.body.push(line);
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+// List the versions a CHANGELOG documents, in file order (skips "Unreleased").
+export function listChangelogVersions(content) {
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+  const re = /^## \[([^\]]+)\](\s.*)?$/;
+  const out = [];
+  for (const l of lines) {
+    const m = re.exec(l);
+    if (m && m[1] !== 'Unreleased') out.push(m[1]);
+  }
+  return out;
+}
+
 /**
- * Validate that CHANGELOG.md content has a "## [<version>]" section containing
- * a "### 한글 요약" sub-section with >= HANGUL_BODY_THRESHOLD Hangul chars.
+ * Validate one CHANGELOG version block against the section model.
+ *
+ * At/after the Korean cutoff (>= 1.2.0): the block must carry at least one gated
+ * section, and EVERY gated section present must hold both a "#### English" and a
+ * "#### 한국어" sub-block, the Korean one non-empty, with the version's total
+ * Korean >= HANGUL_BODY_THRESHOLD. Before the cutoff (1.0.0–1.1.0): English-only
+ * era — the block need only carry content; no Korean is required or fabricated.
  *
  * @param {string} content  CHANGELOG.md raw content (CRLF tolerated).
  * @param {string} version  Semver string to look up (e.g. "1.2.1").
- * @returns {{ok: true, hangulCount: number} | {ok: false, reason: string}}
+ * @returns {{ok: true, hangulCount: number, koreanExempt?: boolean} | {ok: false, reason: string}}
  */
 export function validateChangelog(content, version) {
   if (!version) return { ok: false, reason: 'no version supplied' };
   const lines = content.replace(/\r\n/g, '\n').split('\n');
   const versionEsc = escapeRegex(version);
   // Anchor closing bracket so 1.2.1 does NOT match the prefix of 1.2.10.
-  // Allow trailing " - YYYY-MM-DD" or nothing.
   const sectionRe = new RegExp(`^## \\[${versionEsc}\\](\\s.*)?$`);
 
   const startIndices = [];
@@ -72,34 +151,58 @@ export function validateChangelog(content, version) {
       break;
     }
   }
-  const sectionLines = lines.slice(start, sectionEnd);
+  const blockLines = lines.slice(start + 1, sectionEnd);
+  const sections = sliceSections(blockLines, 3);
+  const gated = sections.filter((s) => GATED_HEADINGS.includes(s.title));
 
-  const koreanHeadIdx = sectionLines.findIndex((l) => l.trim() === '### 한글 요약');
-  if (koreanHeadIdx === -1) {
-    return { ok: false, reason: `section [${version}] missing "### 한글 요약" sub-section` };
+  if (!meetsKoreanCutoff(version)) {
+    // Pre-cutoff English-only era: require content (a non-heading body line),
+    // never a Korean half.
+    const hasContent = blockLines.some((l) => l.trim() && !/^#/.test(l));
+    if (!hasContent) {
+      return { ok: false, reason: `section [${version}] has no content` };
+    }
+    return { ok: true, hangulCount: 0, koreanExempt: true };
   }
 
-  // Bound the Korean block: stop at the next H2 OR H3. CHANGELOG.md has
-  // sibling H3s like "### Internal", "### Fixed" — Hangul in those sections
-  // does not count toward the "### 한글 요약" requirement.
-  let koreanEnd = sectionLines.length;
-  for (let i = koreanHeadIdx + 1; i < sectionLines.length; i++) {
-    if (/^(##|###) /.test(sectionLines[i])) {
-      koreanEnd = i;
-      break;
+  // Cutoff+: enforce the per-section bilingual structure.
+  if (gated.length === 0) {
+    return {
+      ok: false,
+      reason:
+        `section [${version}] has no gated section ` +
+        `(one of ${GATED_HEADINGS.join(' / ')} is required at >= 1.2.0)`,
+    };
+  }
+  let total = 0;
+  for (const sec of gated) {
+    const subs = sliceSections(sec.body, 4);
+    const hasEnglish = subs.some((s) => s.title === 'English');
+    const korean = subs.find((s) => s.title === '한국어');
+    if (!hasEnglish) {
+      return { ok: false, reason: `[${version}] "${sec.title}" missing "#### English" sub-block` };
+    }
+    if (!korean) {
+      return { ok: false, reason: `[${version}] "${sec.title}" missing "#### 한국어" sub-block` };
     }
+    const koCount = countHangul(korean.body.join('\n'));
+    if (koCount < 1) {
+      return {
+        ok: false,
+        reason: `[${version}] "${sec.title}" "#### 한국어" has no Korean text (heading alone does not count)`,
+      };
+    }
+    total += koCount;
   }
-  const body = sectionLines.slice(koreanHeadIdx + 1, koreanEnd).join('\n');
-  const count = countHangul(body);
-  if (count < HANGUL_BODY_THRESHOLD) {
+  if (total < HANGUL_BODY_THRESHOLD) {
     return {
       ok: false,
       reason:
-        `section [${version}] "### 한글 요약" body has ${count} Hangul chars ` +
-        `(threshold: ${HANGUL_BODY_THRESHOLD}). Heading alone does not count — write real Korean summary.`,
+        `section [${version}] total Korean is ${total} Hangul chars ` +
+        `(threshold: ${HANGUL_BODY_THRESHOLD}). Write real Korean summaries in the "#### 한국어" sub-blocks.`,
     };
   }
-  return { ok: true, hangulCount: count };
+  return { ok: true, hangulCount: total };
 }
 
 /**

package/scripts/lib/check-tracker-ids.mjs

@@ -61,6 +61,25 @@ export const BLOCKED_PATTERNS = [
   },
 ];
 
+// The remaining wiki tracker prefixes (FEAT-/IMPR-/PRAC-). These are NOT in
+// BLOCKED_PATTERNS because shipped CODE COMMENTS legitimately cite them for
+// maintainer context (e.g. `// FEAT-17 hardening`), exactly like ADR anchors —
+// blocking them everywhere would flag ~20 real in-code references. They ARE
+// blocked on the PUBLIC RELEASE SURFACE that carries no code: the annotated tag
+// body (the source of the GitHub Release via --notes-from-tag). The CLI applies
+// [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS] only in --tag mode. The
+// CHANGELOG's own surface-ID-0 is held by the section migration + a grep
+// regression test, not by widening this file-scan set (changelog-pr-guide §5).
+// Examples below use `N`, not a real digit, so this file scans clean.
+export const SURFACE_TRACKER_PATTERNS = [
+  { name: 'FEAT-N', label: 'wiki feature-tracker id', re: /\bFEAT-\d+\b/gi },
+  { name: 'IMPR-N', label: 'wiki improvement-tracker id', re: /\bIMPR-\d+\b/gi },
+  { name: 'PRAC-N', label: 'wiki practice-tracker id', re: /\bPRAC-\d+\b/gi },
+];
+
+// The full tracker-ID set for a no-code public surface (the annotated tag body).
+export const TAG_BODY_PATTERNS = [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS];
+
 /**
  * Scan a blob of text against `patterns` (default BLOCKED_PATTERNS). Returns hits:
  *   { pattern, label, match, line, col, lineText }

package/scripts/lib/project-create.mjs

@@ -90,13 +90,31 @@ export function insertHotRow(content, name, today) {
  * @param {{hypoDir: string, name: string, workingDir: string, started?: string, today?: string}} opts
  * @returns {{created: string[], skipped: string[], warnings: string[], projectDir: string}}
  */
+/**
+ * A project name must be a SINGLE path segment with at least one alnum. The
+ * charset alone is not enough: `.`, `..`, `...` all pass `[A-Za-z0-9._-]+` yet
+ * would resolve `projects/<name>` to the wiki root or `projects/` itself (codex
+ * review 2026-05-22, both workers) — so dot-only names are rejected and ≥1 alnum
+ * required. The leading `typeof` guard lets non-CLI callers (e.g. a JSON payload
+ * where the value could be a number) reuse this without a JS regex coercing a
+ * non-string into a "valid" name. Shared so the apply path (crystallize.mjs B-3)
+ * accepts exactly the namespace createProject can scaffold — no wider, no narrower.
+ *
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+export function isValidProjectName(name) {
+  return (
+    typeof name === 'string' &&
+    /^[A-Za-z0-9._-]+$/.test(name) &&
+    !/^\.+$/.test(name) &&
+    /[A-Za-z0-9]/.test(name)
+  );
+}
+
 export function createProject(opts) {
   const { name, workingDir } = opts;
-  // Name must be a single path segment with at least one alnum. The charset
-  // alone is not enough: `.`, `..`, `...` all pass `[A-Za-z0-9._-]+` yet would
-  // resolve `projects/<name>` to the wiki root or `projects/` itself (codex
-  // review 2026-05-22, both workers). Reject dot-only names and require alnum.
-  if (!name || !/^[A-Za-z0-9._-]+$/.test(name) || /^\.+$/.test(name) || !/[A-Za-z0-9]/.test(name)) {
+  if (!isValidProjectName(name)) {
     throw new Error(
       `invalid project name: ${JSON.stringify(name)} (need a single segment with ≥1 alnum, charset A-Za-z0-9._-, not "."/"..")`,
     );

package/scripts/lib/schema-vocab.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
 const VOCAB_HEADER_RE = /^##\s+(?:\d+\.\s+)?Tag\s+(?:Vocabulary|Taxonomy)\s*$/m;
@@ -66,6 +66,110 @@ export function parseSchemaVocab(hypoDir) {
   return vocab;
 }
 
+// Prose seeded into a freshly-created `### Pending` block. It carries NO
+// backtick tokens, so parseSchemaVocab's vocabLineTokens never mistakes it for a
+// vocabulary line — only the `**Pending**:` data line below it contributes tags.
+const PENDING_HEADING = '### Pending (auto-registered)';
+const PENDING_PROSE =
+  'Tags auto-registered by a crystallize close because they were not yet in the ' +
+  'vocabulary above. Review periodically: promote each into a category and delete ' +
+  'it here, or drop the tag from the page.';
+const PENDING_HEADING_RE = /^###[ \t]+Pending\b.*$/im; // prefix/word match
+const PENDING_DATA_RE = /^\*\*Pending[^*]*\*\*:.*$/im;
+const NEXT_H3_RE = /^###[ \t]+/m;
+const FORBIDDEN_HEADING_RE = /^###[ \t]+Forbidden\b/im;
+
+function backtickList(tags) {
+  return tags.map((t) => `\`${t}\``).join(', ');
+}
+
+// Auto-register unknown (non-forbidden) tags into the vault SCHEMA.md `### Pending`
+// section so a close never stalls on a vocabulary gap and the next lint sees them
+// as known (B-4). Pending lives INSIDE the "## Tag Vocabulary" H2 section because
+// parseSchemaVocab is H2-bounded — placing it elsewhere would not widen the vocab.
+// No-ops (returns []) when SCHEMA.md or the Tag Vocabulary header is absent, when
+// every tag is already in the vocabulary, or when a tag is forbidden — registering
+// a forbidden pattern is pointless (lint errors on it before the vocab check) and
+// would only pollute Pending. Idempotent: re-running with the same tags writes
+// nothing (they are already in the parsed vocabulary on the second call).
+export function appendPendingTags(hypoDir, tags) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return [];
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = VOCAB_HEADER_RE.exec(content);
+  if (!headerMatch) return [];
+
+  const current = parseSchemaVocab(hypoDir);
+  const seen = new Set();
+  const newTags = [];
+  for (const raw of tags || []) {
+    const t = typeof raw === 'string' ? raw.trim() : '';
+    // A literal backtick cannot be serialized inside the backtick-delimited
+    // `**Pending**:` line — it would close the token early and make
+    // parseSchemaVocab mis-tokenize (or blank) the whole line, taking valid
+    // sibling tags down with it (codex stage-2 CONCERN). Skip it: the tag stays a
+    // non-blocking unknown-tag warn the author can rename. (A `"` is safe — it
+    // round-trips between backticks — so only the backtick is rejected.)
+    if (!t || t.includes('`') || seen.has(t) || current.has(t) || checkForbidden(t)) continue;
+    seen.add(t);
+    newTags.push(t);
+  }
+  if (newTags.length === 0) return [];
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const sectionEnd = nextH2 ? sectionStart + nextH2.index : content.length;
+  const section = content.slice(sectionStart, sectionEnd);
+
+  let newSection;
+  const heading = PENDING_HEADING_RE.exec(section);
+  if (heading) {
+    // Pending subsection exists — bound it (heading → next H3 or section end) and
+    // either extend its `**Pending**:` data line or seed one if the block is empty
+    // (the template ships heading + prose with no tags yet).
+    const subStart = heading.index;
+    const after = section.slice(heading.index + heading[0].length);
+    const nextH3 = NEXT_H3_RE.exec(after);
+    const subEnd = nextH3 ? heading.index + heading[0].length + nextH3.index : section.length;
+    const sub = section.slice(subStart, subEnd);
+
+    const dataMatch = PENDING_DATA_RE.exec(sub);
+    let newSub;
+    if (dataMatch) {
+      const existing = [];
+      for (const m of dataMatch[0].matchAll(BACKTICK_TOKEN_RE)) {
+        const t = m[1].trim();
+        if (t && !t.includes(' ')) existing.push(t);
+      }
+      const merged = [...existing, ...newTags];
+      const dataLine = `**Pending**: ${backtickList(merged)}`;
+      newSub =
+        sub.slice(0, dataMatch.index) + dataLine + sub.slice(dataMatch.index + dataMatch[0].length);
+    } else {
+      const dataLine = `**Pending**: ${backtickList(newTags)}`;
+      newSub = `${sub.replace(/\s*$/, '')}\n\n${dataLine}\n`;
+    }
+    newSection = section.slice(0, subStart) + newSub + section.slice(subEnd);
+  } else {
+    // No Pending block yet — build one and place it before "### Forbidden patterns"
+    // if present (Pending is vocabulary; Forbidden is a separate concern), else at
+    // the end of the Tag Vocabulary section.
+    const block = `${PENDING_HEADING}\n\n${PENDING_PROSE}\n\n**Pending**: ${backtickList(newTags)}\n`;
+    const forbidden = FORBIDDEN_HEADING_RE.exec(section);
+    if (forbidden) {
+      newSection =
+        section.slice(0, forbidden.index) + `${block}\n` + section.slice(forbidden.index);
+    } else {
+      newSection = `${section.replace(/\s*$/, '')}\n\n${block}\n`;
+    }
+  }
+
+  writeFileSync(path, content.slice(0, sectionStart) + newSection + content.slice(sectionEnd));
+  return newTags;
+}
+
 // Derive the set of valid immediate subdirectories under pages/ from the
 // SCHEMA "Page Type Taxonomy" table (e.g. learnings, feedback, people). Single
 // source of truth — adding a type+dir row to SCHEMA automatically widens the

package/scripts/lint.mjs

@@ -426,7 +426,15 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
         continue;
       }
       if (!tagVocab.has(tag)) {
-        issue('error', rel, `Unknown tag: "${tag}" (not in SCHEMA.md Tag Vocabulary)`);
+        // W10 (B-4): an unknown but non-forbidden tag is a WARNING, not a hard
+        // error — a session close must never stall on a vocabulary gap. The
+        // crystallize apply path parses these warns (by this exact message
+        // string — load-bearing, see scripts/crystallize.mjs auto-register block)
+        // and registers them into SCHEMA.md's `### Pending` section, so the next
+        // lint sees them as known. W10 is intentionally NOT in STRICT_PROMOTE_IDS:
+        // an unregistered tag is a vocabulary lag, not a content defect, so even
+        // `--strict` keeps it a warning (it only surfaces the id in --json output).
+        issue('warn', rel, `Unknown tag: "${tag}" (not in SCHEMA.md Tag Vocabulary)`, null, 'W10');
       }
     }
   }

package/scripts/weekly-report.mjs

@@ -123,7 +123,7 @@ export function buildReport(
   return { week: weekLabel, count: weekResults.length, counts, score, results: weekResults };
 }
 
-function renderMarkdown(report) {
+function renderMarkdown(report, hypoDir) {
   const { week, count, counts, score, results } = report;
   const today = new Date().toISOString().slice(0, 10);
   const lines = [];
@@ -138,8 +138,14 @@ function renderMarkdown(report) {
   lines.push('');
   lines.push(`# Observability — Week ${week}`);
   lines.push('');
+  // Only emit the wikilink when its target page exists, so a fresh vault
+  // (or a deleted _index) does not stamp a broken link into every weekly.
+  const indexExists = !!hypoDir && existsSync(join(hypoDir, 'pages', 'observability', '_index.md'));
+  const heuristicRef = indexExists
+    ? '[[pages/observability/_index]]'
+    : '`pages/observability/_index.md` (not present in this vault)';
   lines.push(
-    `> Generated by \`scripts/weekly-report.mjs\`. Heuristic definition: [[pages/observability/_index]].`,
+    `> Generated by \`scripts/weekly-report.mjs\`. Heuristic definition: ${heuristicRef}.`,
   );
   lines.push('');
   lines.push(`## Autonomy score (heuristic v0): **${score}%**`);
@@ -196,7 +202,7 @@ if (isMain()) {
     process.exit(0);
   }
 
-  const md = renderMarkdown(report);
+  const md = renderMarkdown(report, args.hypoDir);
 
   if (args.write) {
     const dir = join(args.hypoDir, 'journal', 'weekly');