create-pmos 0.47.0 → 0.48.0

package/workspace/lib/claims.js

@@ -281,8 +281,11 @@ const PAIR_QUESTIONS = {
   delivers: 'The story section does not deliver what the requirement it cites asks for.',
   supports: 'The decision does not support what the document says it decides.',
   sections: 'These two sections of the same document contradict each other.',
+  // status-from-artifacts Run 2 (D83) — asked only when the repository's "read documents for status" switch is on.
+  stub: 'The document is not a complete document for its initiative: it is a stub, an outline or an unfinished draft.',
+  contradicts: 'The note states something that contradicts one of the requirements.',
 };
-const PAIR_CAP = { rubric: 2500, req: 1200, story: 1500, reqs: 1500, sentence: 600, decision: 700, section: 1800 };
+const PAIR_CAP = { rubric: 2500, req: 1200, story: 1500, reqs: 1500, sentence: 600, decision: 700, section: 1800, doc: 2500, note: 1800, intent: 600 };
 // A link keeps its words, not its path.
 const clip = (t, n) => { const s = String(t).replace(/\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/[ \t]+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
 
@@ -367,7 +370,7 @@ function decisionText(root, files, n) {
  * @param {Set<string>} [a.only]  limit to pairs whose own document is in this set (a changed file and its dependents)
  * @returns {{pairs: object[], reads: number}}
  */
-function pairsFor({ root, cacheDir, only = null }) {
+function pairsFor({ root, cacheDir, only = null, statusKinds = false }) {
   const index = readJson(path.join(cacheDir, 'index.json'), null);
   if (!index) return { pairs: [], reads: 0 };
   const files = Object.keys(index).filter((r) => index[r] && index[r].cls);
@@ -441,9 +444,55 @@ function pairsFor({ root, cacheDir, only = null }) {
       }
     }
   }
+  if (statusKinds) statusPairs({ files, index, initiatives, read, typeOf, add, only });
   return { pairs, reads };
 }
 
+/*
+ * status-from-artifacts Run 2 (D83): two questions about the documents TIED to an initiative, so the initiative
+ * detail can say what the documents suggest. Ties are concrete only — the paths the record names, and documents whose
+ * own frontmatter or identity line names the initiative — never "feels related".
+ *   stub         each spec document the record names (PRD, rubric, brief) against the initiative's title and intent
+ *   contradicts  each other document that names the initiative (a meeting note, a report) against the PRD's requirements
+ * The texts are clipped like every other pair. The answer is a suggestion: it changes no step, stage or count.
+ */
+const bodyOf = (t) => String(t || '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+function statusPairs({ files, index, initiatives, read, typeOf, add, only }) {
+  const SPEC_KEYS = ['prd_path', 'rubric_path', 'brief_path'];
+  const SKIP_TYPES = new Set(['Initiative', 'PRD', 'Rubric', 'Story', 'Decision', 'ADR']);
+  const ids = Array.from(initiatives.keys()).sort();
+  for (const iid of ids) {
+    const { rel: recRel, fm } = initiatives.get(iid);
+    const recText = read(recRel);
+    const intent = clip([fm.title || iid, bodyOf(recText || '')].join('\n'), PAIR_CAP.intent);
+    const own = new Set([recRel]);
+    for (const k of SPEC_KEYS) {
+      const p = fm[k] && !isPlaceholder(fm[k]) ? norm(fm[k]) : null;
+      if (!p || !index[p] || !index[p].cls) continue;
+      own.add(p);
+      if (only && !only.has(p) && !only.has(recRel)) continue;
+      const t = read(p); if (t == null) continue;
+      add({ kind: 'stub', doc: p, doc_type: typeOf(p), subject: 'stub:' + iid, a: clip(bodyOf(t), PAIR_CAP.doc), b: intent, a_label: p, partner: recRel, initiative: iid });
+    }
+    const prdRel = fm.prd_path && !isPlaceholder(fm.prd_path) ? norm(fm.prd_path) : null;
+    const prdText = prdRel && typeOf(prdRel) === 'PRD' ? read(prdRel) : null;
+    if (prdText == null) continue;
+    const reqs = Array.from(requirementTexts(prdText).values());
+    if (!reqs.length) continue;
+    const reqText = clip(reqs.join('\n'), PAIR_CAP.reqs);
+    for (const rel of files) {
+      if (own.has(rel)) continue;
+      const e = index[rel]; const t0 = e.cls && e.cls.type;
+      if (!e.cls.classified || SKIP_TYPES.has(t0)) continue;
+      const named = idOf((e.fm || {}).initiative || (e.fm || {}).initiative_id || (e.body || {}).initiative_id);
+      if (named !== iid) continue;
+      if (only && !only.has(rel) && !only.has(prdRel)) continue;
+      const t = read(rel); if (t == null) continue;
+      add({ kind: 'contradicts', doc: rel, doc_type: t0, subject: 'contradicts:' + iid, a: clip(bodyOf(t), PAIR_CAP.note), b: reqText, a_label: rel, partner: prdRel, initiative: iid });
+    }
+  }
+}
+
 /* ── verification ──────────────────────────────────────────────────────────────────────────────── */
 const date = (secs) => new Date(secs * 1000).toISOString().slice(0, 16).replace('T', ' ');
 

package/workspace/lib/doc-category-corrections.js

@@ -0,0 +1,113 @@
+'use strict';
+/* doc-category-corrections.js — the PM's own category for a document, kept per user (jev-doc-categorizer Run 3, C7).
+ *
+ * A correction is the PM saying "this file is a <category>". It is stored OUTSIDE the repository, in the per-user runtime
+ * directory that lib/state-root.js resolves:
+ *
+ *   <stateDir>/doccat/<repoKey>/corrections.json      repoKey = sha1(repository root).slice(0, 12), as the claims cache uses
+ *
+ * The file is a map: repo-relative path → { category, ticket_kind, at }. A correction never edits the document. Writing the
+ * category into the document's frontmatter is a separate press (lib/doc-category-writeback.js).
+ *
+ * The file is written with mode 0600 through a temporary file and a rename, and a symlink at the target is refused, as
+ * lib/typesafe-settings.js does. Pure Node: no network, and nothing here requires the TypeSafe module.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { validCorrection, CATEGORIES, TICKET_KINDS } = require('./doc-category');
+
+const FILE = 'corrections.json';
+const MAX_ENTRIES = 20000;
+const MAX_REL = 1024;
+
+/** The per-repository key: the first 12 hex characters of the sha1 of the repository root. */
+function repoKey(root) { return crypto.createHash('sha1').update(String(root)).digest('hex').slice(0, 12); }
+/** The per-repository directory under the runtime state directory. */
+function repoDir(stateDir, root) { return path.join(stateDir, 'doccat', repoKey(root)); }
+function file(dir) { return path.join(dir, FILE); }
+
+/** A repo-relative Markdown path with forward slashes, or an `{error}` sentence. */
+function checkRel(rel) {
+  if (typeof rel !== 'string' || !rel.trim()) return { error: 'a document path is required' };
+  if (rel.length > MAX_REL || rel.includes('\0')) return { error: 'that document path is not valid' };
+  const r = rel.replace(/\\/g, '/');
+  if (r.startsWith('/') || /^[a-zA-Z]:/.test(r) || path.isAbsolute(rel)) return { error: 'the path must be relative to the repository, not absolute' };
+  if (r.split('/').some((seg) => seg === '..')) return { error: 'the path must not contain ".."' };
+  const n = r.replace(/^(\.\/)+/, '');
+  // one spelling per file: the library lists `a/b.md`, so `a/./b.md` or `a//b.md` would be saved and never apply
+  if (n.split('/').some((seg) => seg === '' || seg === '.')) return { error: 'write the path as the library lists it, with no "./" or "//" inside it' };
+  if (n.split('/').some((seg) => seg.toLowerCase() === '.git')) return { error: 'a file inside .git is not a document' };
+  if (path.posix.extname(n).toLowerCase() !== '.md') return { error: 'only a Markdown (.md) document has a category' };
+  return { rel: n };
+}
+
+function readRaw(dir) {
+  try {
+    const st = fs.lstatSync(file(dir));
+    if (!st.isFile()) return {};
+    const o = JSON.parse(fs.readFileSync(file(dir), 'utf8'));
+    return o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+  } catch { return {}; }
+}
+
+/** Every valid correction for the repository whose directory is `dir`: rel → { category, ticket_kind, at }. */
+function get(dir) {
+  const raw = readRaw(dir);
+  const out = {};
+  for (const [rel, v] of Object.entries(raw)) {
+    if (checkRel(rel).error) continue;
+    const c = validCorrection(v);
+    if (!c) continue;
+    out[rel] = { category: c.category, ticket_kind: c.ticket_kind, at: v && typeof v.at === 'string' ? v.at : null };
+  }
+  return out;
+}
+
+function write(dir, data) {
+  const target = file(dir);
+  try { if (fs.lstatSync(target).isSymbolicLink()) return { ok: false, error: 'the corrections file is a symlink and was not written' }; }
+  catch { /* not there yet */ }
+  const tmp = target + '.' + process.pid + '.tmp';
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 1), { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, target);
+    return { ok: true };
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to clean */ }
+    return { ok: false, error: 'the correction could not be saved (' + String((e && e.code) || 'write failed') + ')' };
+  }
+}
+
+/** Set the PM's category for one document. Returns { ok, rel, correction } or { ok: false, error }. */
+function set(dir, rel, { category, ticket_kind } = {}, now = new Date()) {
+  const p = checkRel(rel);
+  if (p.error) return { ok: false, error: p.error };
+  const c = validCorrection({ category, ticket_kind: ticket_kind === undefined ? null : ticket_kind });
+  if (!c) {
+    const cat = String(category || '').trim().toLowerCase();
+    if (!CATEGORIES.includes(cat)) return { ok: false, error: 'the category must be one of: ' + CATEGORIES.join(', ') };
+    if (cat === 'ticket') return { ok: false, error: 'a ticket needs a ticket kind: ' + TICKET_KINDS.join(', ') };
+    return { ok: false, error: 'only a ticket has a ticket kind' };
+  }
+  const cur = get(dir);
+  if (!cur[p.rel] && Object.keys(cur).length >= MAX_ENTRIES) return { ok: false, error: 'there are too many corrections for this repository (' + MAX_ENTRIES + ')' };
+  const correction = { category: c.category, ticket_kind: c.ticket_kind, at: now.toISOString() };
+  const w = write(dir, { ...cur, [p.rel]: correction });
+  return w.ok ? { ok: true, rel: p.rel, correction } : w;
+}
+
+/** Remove the PM's category for one document. Returns { ok, rel, cleared } or { ok: false, error }. */
+function clear(dir, rel) {
+  const p = checkRel(rel);
+  if (p.error) return { ok: false, error: p.error };
+  const cur = get(dir);
+  if (!cur[p.rel]) return { ok: true, rel: p.rel, cleared: false };
+  delete cur[p.rel];
+  const w = write(dir, cur);
+  return w.ok ? { ok: true, rel: p.rel, cleared: true } : w;
+}
+
+module.exports = { get, set, clear, checkRel, repoKey, repoDir, FILE, MAX_ENTRIES };

package/workspace/lib/doc-category-writeback.js

@@ -0,0 +1,110 @@
+'use strict';
+/* doc-category-writeback.js — write the PM's category into a document's own frontmatter (jev-doc-categorizer Run 3, C7).
+ *
+ * A correction lives outside the repository and never edits a file. When the PM wants the category IN the file, as an author
+ * `category:` key, that is this separate press, and it has two steps:
+ *
+ *   1. plan(text, correction)   returns the diff, the sha1 of the text the PM saw and the sha1 of the text it would write.
+ *      Nothing is written.
+ *   2. apply(current, correction, expectSha, expectNextSha)   refuses when the file changed after the PM saw the diff, or
+ *      when the change is not the one the PM saw; otherwise returns the same plan, and the caller writes `next`.
+ *
+ * The change is as small as it can be: ONE `category:` line (and ONE `ticket_kind:` line for a ticket) is set or replaced in
+ * the LEADING frontmatter block. No other byte of the file changes, line endings and a byte-order mark included. A file with
+ * no leading frontmatter block is refused: this module does not add a block. Pure: it reads and writes no file.
+ */
+const crypto = require('crypto');
+const { validCorrection, CATEGORIES, TICKET_KINDS } = require('./doc-category');
+
+const sha1 = (text) => crypto.createHash('sha1').update(String(text), 'utf8').digest('hex');
+const lines = (text) => String(text).match(/[^\n]*\n|[^\n]+$/g) || [];
+const bare = (line) => line.replace(/\r?\n$/, '');
+const eolOf = (line) => (/\r\n$/.test(line) ? '\r\n' : (/\n$/.test(line) ? '\n' : ''));
+
+/* The leading frontmatter block: the first line is `---` (after an optional byte-order mark) and a later line is `---`.
+ * Returns the index of the closing line, or an error sentence. */
+function block(ls) {
+  if (!ls.length || bare(ls[0]).replace(/^/, '').trimEnd() !== '---') {
+    return { error: 'This file has no frontmatter block at the top, so the category was not written. Add a frontmatter block first, or keep the correction only.' };
+  }
+  for (let i = 1; i < ls.length; i++) if (bare(ls[i]).trimEnd() === '---') return { close: i };
+  return { error: 'The frontmatter block at the top of this file has no closing --- line, so the category was not written.' };
+}
+
+/* Set `key: value` on one top-level line inside the block. More than one such line is refused, because the writer cannot
+ * know which one the reader uses. */
+function setKey(ls, close, key, value, eol, changes) {
+  const re = new RegExp('^' + key + '\\s*:');
+  const at = [];
+  for (let i = 1; i < close; i++) if (re.test(ls[i])) at.push(i);
+  if (at.length > 1) return { error: 'The frontmatter has more than one ' + key + ': line, so the category was not written. Remove the extra line first.' };
+  const want = key + ': ' + value;
+  if (at.length === 1) {
+    const i = at[0];
+    // a value that goes on below the key (a block scalar, a list, a map) is more than one line; replacing the key line alone
+    // would leave broken YAML, so it is refused
+    if (/^[^:]*:\s*[|>][-+0-9]*\s*(#.*)?$/.test(bare(ls[i])) || (i + 1 < close && /^[ \t]/.test(ls[i + 1]))) {
+      return { error: 'The ' + key + ': value in the frontmatter goes on below its line, so the category was not written. Make it one line first.' };
+    }
+    if (bare(ls[i]) === want) return { close };
+    changes.push({ line: i + 1, before: bare(ls[i]), after: want });
+    ls[i] = want + eolOf(ls[i]);
+    return { close };
+  }
+  changes.push({ line: close + 1, before: null, after: want });
+  ls.splice(close, 0, want + eol);
+  return { close: close + 1 };
+}
+
+function diffOf(changes) {
+  return changes.map((c) => c.before === null
+    ? '@@ line ' + c.line + ' (added) @@\n+' + c.after
+    : '@@ line ' + c.line + ' @@\n-' + c.before + '\n+' + c.after).join('\n');
+}
+
+/**
+ * Plan the write. Pure.
+ * @returns {{ok:true, next:string, diff:string, changes:Array, sha:string, next_sha:string, unchanged:boolean} | {ok:false, error:string, sha?:string}}
+ */
+function plan(text, { category, ticket_kind } = {}) {
+  const t = String(text == null ? '' : text);
+  const sha = sha1(t);
+  const c = validCorrection({ category, ticket_kind: ticket_kind === undefined ? null : ticket_kind });
+  if (!c) {
+    const cat = String(category || '').trim().toLowerCase();
+    if (!CATEGORIES.includes(cat)) return { ok: false, sha, error: 'The category must be one of: ' + CATEGORIES.join(', ') + '.' };
+    if (cat === 'ticket') return { ok: false, sha, error: 'A ticket needs a ticket kind: ' + TICKET_KINDS.join(', ') + '.' };
+    return { ok: false, sha, error: 'Only a ticket has a ticket kind.' };
+  }
+  const ls = lines(t);
+  const b = block(ls);
+  if (b.error) return { ok: false, sha, error: b.error };
+  const eol = eolOf(ls[0]) || '\n';
+  const changes = [];
+  let r = setKey(ls, b.close, 'category', c.category, eol, changes);
+  if (r.error) return { ok: false, sha, error: r.error };
+  if (c.category === 'ticket') {
+    r = setKey(ls, r.close, 'ticket_kind', c.ticket_kind, eol, changes);
+    if (r.error) return { ok: false, sha, error: r.error };
+  }
+  const next = ls.join('');
+  return { ok: true, next, diff: diffOf(changes), changes, sha, next_sha: sha1(next), unchanged: next === t };
+}
+
+/**
+ * The confirmed step: refuse when the file is no longer the text the PM saw, or when the change is not the one the PM saw
+ * (`expectNextSha` is the plan's `next_sha`); otherwise the plan, whose `next` the caller writes.
+ */
+function apply(current, correction, expectSha, expectNextSha) {
+  const sha = sha1(current);
+  if (typeof expectSha !== 'string' || expectSha !== sha) {
+    return { ok: false, stale: true, sha, error: 'The file changed after you saw the diff, so nothing was written. Look at the new diff and press again.' };
+  }
+  const p = plan(current, correction);
+  if (p.ok && (typeof expectNextSha !== 'string' || expectNextSha !== p.next_sha)) {
+    return { ok: false, stale: true, sha, error: 'This is not the change you were shown, so nothing was written. Look at the diff again and press apply.' };
+  }
+  return p;
+}
+
+module.exports = { plan, apply, sha1 };

package/workspace/lib/doc-category.js

@@ -0,0 +1,225 @@
+'use strict';
+/* doc-category.js — what KIND of document is this, in the PM's words? (jev-doc-categorizer Run 1)
+ *
+ * `doc-profiles.js` answers a narrower question for the claims ledger: which documents is this one compared with.
+ * This module answers the PM's: is it a PRD, meeting notes, a report, a ticket, knowledge or something else. The category is
+ * DERIVED data kept beside the frontmatter `type`. It never replaces `type`, adds nothing to the registry, and is never
+ * written into a document.
+ *
+ * Run 1 has NO network and NO model. It is pure: it reads no file and requires nothing outside Node. Evidence, strongest first,
+ * and the FIRST basis that decides wins:
+ *   1. author key      a `category:` line the author wrote (and `ticket_kind:` for a ticket)
+ *   2. frontmatter type  a `type` that maps to a category (TYPE_TO_CATEGORY). `Reference` and `Research` map to nothing,
+ *                      because each is a bucket, and fall through to the next basis.
+ *   3. named by initiative  an initiative record that names the file as its prd_path or rubric_path
+ *   4. file name       a file-name suffix or a folder name
+ *   5. headings        a heading signature
+ * A correction the PM set (Run 3, C7) is stronger than all five. The caller reads it from the per-user store
+ * (lib/doc-category-corrections.js) and passes it in as `correction`, so this module still reads no file. A valid correction
+ * decides with basis `pm correction`; an invalid one is ignored and the five bases decide as before.
+ * A file no basis decides is `undetermined` with `decided: false`. It is not rounded to `other`: `other` is an answer
+ * ("this is none of the kinds"), `undetermined` is the absence of one. Later bases that disagree with the winner are listed
+ * in `disagrees`, so the PM can see the conflict and the winner is never silently chosen.
+ */
+const path = require('path');
+
+const CATEGORIES = ['prd', 'meeting-notes', 'report', 'ticket', 'knowledge', 'spec-artifact', 'other'];
+const TICKET_KINDS = ['design', 'engineering', 'other'];
+const UNDETERMINED = 'undetermined';
+/* Every basis name a result can carry. `pm correction` is the strongest. The next five are the local bases in their order.
+ * `jev` is reserved for the measured Jev pass of a later run, which sets its place in the order. */
+const BASES = ['pm correction', 'author key', 'frontmatter type', 'named by initiative', 'file name', 'headings', 'jev'];
+
+/** A correction is valid when its category is in the vocabulary, and its ticket kind is a known kind for a ticket and null
+ * (or absent) for every other category. Returns the normalized correction or null. */
+function validCorrection(c) {
+  if (!c || typeof c !== 'object') return null;
+  const category = typeof c.category === 'string' ? c.category.trim().toLowerCase() : '';
+  if (!CATEGORIES.includes(category)) return null;
+  const k = c.ticket_kind === null || c.ticket_kind === undefined ? null : String(c.ticket_kind).trim().toLowerCase();
+  if (category === 'ticket') return TICKET_KINDS.includes(k) ? { category, ticket_kind: k } : null;
+  return k === null || k === '' ? { category, ticket_kind: null } : null;
+}
+
+/* Every type in scripts/frontmatter_registry.txt has a row here (a test enforces it). `null` means the type alone does not
+ * decide: it is a bucket, and a sharper basis may. Rows are the vocabulary's one editable decision; change one with a reason. */
+const TYPE_TO_CATEGORY = {
+  Concept: 'knowledge', ADR: 'spec-artifact', Template: 'other', Playbook: 'knowledge', Reference: null,
+  Initiative: 'spec-artifact', PRD: 'prd', Story: 'spec-artifact', Rubric: 'spec-artifact', OKR: 'spec-artifact',
+  Radar: 'report', Checklist: 'other', Calibration: 'report', Research: null, Design: 'spec-artifact',
+  Prototype: 'other', Handover: 'report',
+  Decision: 'spec-artifact', Principle: 'knowledge', Debt: 'report', Discovery: 'report', Guide: 'knowledge',
+};
+
+/* A tenant repository is not bound to PMOS's registry, so a few spellings a PM would write for the same kinds are read too. */
+const norm = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+const TYPE_ALIASES = {
+  prd: ['prd', 'productrequirements', 'productrequirementsdocument'],
+  'meeting-notes': ['meetingnotes', 'meetingnote', 'meeting', 'minutes', 'meetingminutes'],
+  report: ['report', 'statusreport', 'postmortem'],
+  ticket: ['ticket', 'issue', 'bug', 'task'],
+  knowledge: ['knowledge', 'article', 'kb', 'howto'],
+  'spec-artifact': [],
+  other: ['other'],
+};
+const ALIAS = new Map();
+for (const [cat, list] of Object.entries(TYPE_ALIASES)) for (const a of list) ALIAS.set(a, cat);
+ALIAS.set('designticket', ['ticket', 'design']);
+ALIAS.set('engineeringticket', ['ticket', 'engineering']);
+ALIAS.set('engticket', ['ticket', 'engineering']);
+
+const ROLE_CATEGORY = { prd_path: 'prd', rubric_path: 'spec-artifact' };
+
+const RESERVED = /(^|\/)(index|log)\.md$/i;
+const TEMPLATE = /(^|\/)templates?\//i;
+
+function typeDecision(fmType) {
+  const t = String(fmType || '').trim();
+  if (!t) return null;
+  if (Object.prototype.hasOwnProperty.call(TYPE_TO_CATEGORY, t)) {
+    const c = TYPE_TO_CATEGORY[t];
+    return c ? { category: c } : null;
+  }
+  const a = ALIAS.get(norm(t));
+  if (!a) return null;
+  return Array.isArray(a) ? { category: a[0], ticket_kind: a[1] } : { category: a };
+}
+
+function ticketKindFrom(text) {
+  const s = String(text || '').toLowerCase();
+  if (/(^|[^a-z])(design|ux|ui|figma|mockup|wireframe)([^a-z]|$)/.test(s)) return 'design';
+  if (/(^|[^a-z])(eng|engineering|bug|backend|frontend|api|steps to reproduce|regression)([^a-z]|$)/.test(s)) return 'engineering';
+  return 'other';
+}
+
+/* File-name and folder evidence. Suffixes the repository already uses come first because they are the strongest. */
+const NAME_RULES = [
+  [/-eval-rubric\.md$/i, 'spec-artifact'],
+  [/-prd\.md$/i, 'prd'],
+  [/-user-stor(?:y|ies)\.md$/i, 'spec-artifact'],
+  [/-surface-explainer\.md$/i, 'knowledge'],
+  [/(^|\/)d\d{1,3}-[^/]+\.md$/i, 'spec-artifact'],
+  [/(^|\/)(meetings?|minutes|standups?)\//i, 'meeting-notes'],
+  [/(^|[-_/ ])(meeting|minutes|standup|1[-_ ]?on[-_ ]?1)([-_. ]|notes|\.md$)/i, 'meeting-notes'],
+  [/(^|\/)(initiatives|adr)\//i, 'spec-artifact'],
+  [/(^|\/)(explainers|guide|guides|playbooks|concepts)\//i, 'knowledge'],
+  [/(^|\/)readme\.md$/i, 'knowledge'],
+  [/(^|\/)(tickets?|issues?|bugs?)\//i, 'ticket'],
+  // a tracker key such as PROJ-123, but not a date: `sync-2026-09-12.md` is a dated note, not ticket SYNC-2026
+  [/(^|\/)[a-z][a-z0-9]{1,9}-\d{1,6}(?!-\d)([-_.][^/]*)?\.md$/i, 'ticket'],
+  [/(^|[-_/ ])ticket([-_. ]|\.md$)/i, 'ticket'],
+  [/(^|\/)reports?\//i, 'report'],
+  [/(^|[-_/ ])(report|postmortem|post-mortem|status-update)([-_. ]|\.md$)/i, 'report'],
+];
+
+function headings(text) {
+  const out = [];
+  for (const m of String(text).matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) out.push(m[1].toLowerCase());
+  return out;
+}
+
+function fileNameDecision(rel) {
+  if (TEMPLATE.test(rel) || /-template\.md$/i.test(rel)) return { category: 'other', via: 'a template path' };
+  for (const [re, category] of NAME_RULES) {
+    if (re.test(rel)) return { category, via: 'the name or folder matches ' + String(re) };
+  }
+  return null;
+}
+
+function headingsDecision(text) {
+  const h = headings(text);
+  const has = (s) => h.some((x) => x.includes(s));
+  if (has('requirements') && has('identity')) return { category: 'prd', via: 'headings: requirements and identity' };
+  if (has('dimensions') && has('sprint contract')) return { category: 'spec-artifact', via: 'headings: dimensions and sprint contract' };
+  if ((has('attendees') || has('agenda')) && (has('action items') || has('decisions') || has('notes') || has('discussion'))) {
+    return { category: 'meeting-notes', via: 'headings: attendees or agenda with notes, decisions or action items' };
+  }
+  if (has('acceptance criteria') && (has('steps to reproduce') || has('expected') || has('description') || has('actual'))) {
+    return { category: 'ticket', via: 'headings: acceptance criteria with a description or reproduction steps' };
+  }
+  if ((has('executive summary') || has('summary')) && (has('findings') || has('results') || has('recommendations') || has('metrics'))) {
+    return { category: 'report', via: 'headings: a summary with findings, results, recommendations or metrics' };
+  }
+  return null;
+}
+
+/**
+ * Categorize one file. Pure: no file is read, no network is used, nothing is written.
+ * @param {object} a
+ * @param {string} a.rel      repo-relative path with forward slashes
+ * @param {object} [a.fm]     parsed frontmatter ({} when none)
+ * @param {string} [a.text]   file text
+ * @param {Map}    [a.named]  path → [{role, id, lane}] from initiative records
+ * @param {object} [a.correction]  the PM's stored correction {category, ticket_kind}; wins over every basis when valid
+ * @returns {{category:string, ticket_kind:string|null, basis:string|null, via:string, decided:boolean, disagrees:Array}}
+ */
+function categorize({ rel, fm = {}, text = '', named = new Map(), correction = null }) {
+  const r = String(rel || '').replace(/\\/g, '/');
+  if (path.posix.extname(r).toLowerCase() !== '.md') {
+    return { category: UNDETERMINED, ticket_kind: null, basis: null, via: 'not a Markdown document', decided: false, disagrees: [] };
+  }
+  const found = []; // every basis that has something to say, in order
+  const push = (basis, via, d) => { if (d && d.category) found.push({ basis, via, category: d.category, kind: d.ticket_kind || null, }); };
+
+  const corr = validCorrection(correction);
+  if (corr) push('pm correction', 'a correction the PM set', corr);
+  // index.md and log.md are reserved by OKF: they are directory listings and histories, not documents of a kind.
+  if (RESERVED.test(r)) push('file name', 'a reserved index or log file', { category: 'other' });
+  else collect(r, fm, text, named, push);
+  return decide(found, r, fm, text);
+}
+
+function collect(r, fm, text, named, push) {
+  const authorCat = String(fm.category || '').trim().toLowerCase();
+  if (CATEGORIES.includes(authorCat)) {
+    const k = String(fm.ticket_kind || '').trim().toLowerCase();
+    push('author key', 'a category line the author wrote', { category: authorCat, ticket_kind: TICKET_KINDS.includes(k) ? k : null });
+  }
+  const t = typeDecision(fm.type);
+  if (t) push('frontmatter type', 'type: ' + String(fm.type).trim(), t);
+  const roles = named.get(r);
+  if (roles && roles.length) {
+    // In every lane but `feature` the prd_path holds that lane's brief (a spike brief, an intent), not a PRD.
+    const lane = roles[0].lane;
+    const c = roles[0].role === 'prd_path' && lane && lane !== 'feature' ? 'spec-artifact' : ROLE_CATEGORY[roles[0].role];
+    if (c) push('named by initiative', 'named by initiative ' + roles[0].id, { category: c });
+  }
+  const n = fileNameDecision(r);
+  if (n) push('file name', n.via, n);
+  const h = headingsDecision(text);
+  if (h) push('headings', h.via, h);
+}
+
+function decide(found, r, fm, text) {
+  if (!found.length) {
+    return { category: UNDETERMINED, ticket_kind: null, basis: null, via: 'no evidence', decided: false, disagrees: [] };
+  }
+  const win = found[0];
+  let kind = null;
+  if (win.category === 'ticket') kind = win.kind || ticketKindFrom(String(fm.title || '') + ' ' + r + ' ' + headings(text).join(' '));
+  return {
+    category: win.category, ticket_kind: kind, basis: win.basis, via: win.via, decided: true,
+    disagrees: found.slice(1).filter((f) => f.category !== win.category).map((f) => ({ basis: f.basis, category: f.category })),
+  };
+}
+
+/**
+ * Build the `named` map from initiative records: path → [{role, id, lane}]. Pure; the caller supplies each record's path and
+ * parsed frontmatter, so no file is read here.
+ * @param {Array<{rel:string, fm:object}>} records
+ */
+function namedFromRecords(records) {
+  const named = new Map();
+  for (const { rel, fm } of records || []) {
+    if (!/(^|\/)initiatives\//.test(String(rel || '').replace(/\\/g, '/')) || !fm) continue;
+    for (const role of Object.keys(ROLE_CATEGORY)) {
+      if (!fm[role]) continue;
+      const k = String(fm[role]).replace(/^\//, '');
+      if (!named.has(k)) named.set(k, []);
+      named.get(k).push({ role, id: fm.id || path.posix.basename(String(rel), '.md'), lane: fm.lane || null });
+    }
+  }
+  return named;
+}
+
+module.exports = { namedFromRecords, categorize, validCorrection, CATEGORIES, TICKET_KINDS, UNDETERMINED, BASES, TYPE_TO_CATEGORY, ROLE_CATEGORY };