hypomnema 1.3.4 → 1.4.1

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`;
@@ -913,8 +919,36 @@ function applySessionClose(args) {
     for (const a of applied) console.log(`  ✓ wrote ${a}`);
     for (const s of skipped) console.log(`  · skipped ${s} (already current)`);
     if (ok) {
-      console.log('\n✓ session-close verified — all 5 mandatory files fresh, lint clean.');
-    } else {
+      // When the marker was withheld, qualify the success line so a reader scanning
+      // stdout alone cannot mistake "verified" for "fully closed". markerSkipReason
+      // is non-null exactly when args.sessionId is set and the marker did not land.
+      if (markerSkipReason) {
+        console.log(
+          '\n✓ session-close files verified (all 5 mandatory files fresh, lint clean).' +
+            '\n  session NOT fully closed: the Stop-chain marker was not written (see warning below).',
+        );
+      } else {
+        console.log('\n✓ session-close verified — all 5 mandatory files fresh, lint clean.');
+      }
+    }
+    // When ok:true but the session-close marker was NOT written, the Stop-chain
+    // still sees an open session and will re-prompt at the next Stop. Surface this
+    // loudly so neither the human nor a skill-following model reads "ok:true" as
+    // "session fully closed". Gate on markerSkipReason (non-null exactly when
+    // args.sessionId is present and the marker was withheld).
+    if (markerSkipReason) {
+      process.stderr.write(
+        `\n⚠️  session-close marker NOT written (reason: ${markerSkipReason})\n` +
+          `    The 5 mandatory files were applied and verified (ok:true), but the\n` +
+          `    per-session Stop-chain marker was withheld. The session is NOT fully\n` +
+          `    closed: the Stop hook will re-prompt until the marker is present.\n` +
+          `    To fix: re-run with the correct main-conversation --session-id (NOT\n` +
+          `    a background task or Agent UUID from a /tmp/... path).\n` +
+          `    Example: crystallize.mjs --apply-session-close --payload=<path>\n` +
+          `             --session-id=<main-conversation-id> --hypo-dir=<path>\n`,
+      );
+    }
+    if (!ok) {
       if (!verification.ok) {
         const bad = [
           ...verification.missing.map((f) => `${f} (missing)`),
@@ -944,21 +978,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 +1002,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 +1020,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/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));
+}