create-pmos 0.131.0 → 0.133.0

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

@@ -0,0 +1,227 @@
+'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']);
+
+// What a record's path key says about the file it names. scan-consistency R3 adds the keys records use for their other
+// artifacts, so an explainer or a design a record names is categorized by that tie, not left to its file name.
+const ROLE_CATEGORY = { prd_path: 'prd', rubric_path: 'spec-artifact', brief_path: 'spec-artifact', design_path: 'spec-artifact', explainer_path: 'knowledge' };
+
+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 };

package/workspace/lib/vendor/workspace/lib/factory-join.js

@@ -0,0 +1,158 @@
+'use strict';
+/* factory-join.js — THE ONE JOIN of the factory graph's work items onto plan items and initiatives (pm-os-absorb Run 4,
+ * PRD R6, R7, R8, R19; D65, D86 point 1).
+ *
+ *   joinFactory(root, { initiative, fold } = {}) → {
+ *     ok: true,
+ *     byInit: {
+ *       [initiativeId]: {
+ *         items:   [{ id, plan_item, state, pr, integrated, integrated_at }],
+ *                    id = work-item id; plan_item = plan item id | null; state = the work item's folded state
+ *                    (scripts/work-item.js deriveItems: declared, claimed, verified, failed, integrated, shipped,
+ *                    withdrawn); pr = a pull-request reference from its evidence | null; integrated = true once
+ *                    `pmos verify-work` saw its trailer on the default branch; integrated_at = that line's time | null
+ *         batches: [{ id, ready, items: [<work-item id>] }],     a D65 Release batch; ready = every item passed its checks
+ *       }
+ *     },
+ *     flags: [{ kind, id, why }],                                a dangling plan_item, an unreadable line, a missing engine
+ *     unreadable?: why                                           only when the ledger EXISTS but cannot be read or folded
+ *   }
+ *   factoryOf(join, id) → that initiative's entry, or null; when the join is `unreadable`, { items: [], batches: [],
+ *                         unreadable: why } for every id, so a health rule says Unknown (R8) and never "on track"
+ *
+ * `initiative` narrows byInit to that one id. `fold` is an optional lib/plan-items.js fold the caller already holds
+ * (lib/plan-tree.js layout passes its own), so the dangling check does not read the plan-items ledger twice. Readers
+ * never throw; a bad line is a flag.
+ *
+ * THE FOLD IS D65's, NOT A COPY. Work-item state comes from scripts/work-item.js deriveItems, the fold the writer and
+ * the CI checker (scripts/check-work-items.js) use, so this join cannot call an item verified that the gate calls
+ * failed. That module lives in scripts/ and is not vendored into a published workspace (its sink guard requires a
+ * directory the vendoring walk refuses). In an install without it, a repository that HAS a factory ledger gets the
+ * flag `engine-missing` and an empty join; one without a ledger gets an empty join and no flag. Only PMOS-self runs a
+ * factory today.
+ *
+ * WHERE THE LEDGER IS. `planning/work-items.jsonl` of the MAIN working tree of `root`, the same tree the plan-items
+ * ledger resolves to (lib/plan-items.js ledgerRoot), so the two halves of the join are read from one tree.
+ *
+ * A BATCH (D65 Release, D86 point 2) is the work items one materialization declared: one Commit covers the whole batch
+ * (R14), and the materialization writes their `declared` lines with ONE `at`. The ledger has no batch field (D86 point
+ * 1 adds `plan_item` and nothing else), so the batch is that shared `at`. Only materialized items (a `plan_item`) form
+ * batches; a withdrawn or shipped item has left its batch. The batch is keyed on that `at` as an INSTANT, and its id is
+ * `b<UTC digits of that at>` — 14 digits to the second, and the 3 millisecond digits after them when they are not
+ * 000 — so two materializations in one second have two ids, and one Release grant names `<initiative>:<batch id>`. `ready` = every item in it is verified or integrated, and none failed.
+ *
+ * Consumers (all read through this module, never work-items.jsonl directly):
+ *   - health ctx.factory = factoryOf(joinFactory(root), id)   (lib/health-rules-factory.js reads it; 2C's routes and
+ *     5A's drafter assemble it);
+ *   - lib/plan-tree.js layout (a materialized item reads Done once integrated, R7);
+ *   - 4D's Board and work-check-needs (Review and Release rows);
+ *   - 5A's blocks (factory progress when present).
+ *
+ * Nothing is cached (D33). No network, no git.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const WORK_ITEM_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'work-item.js')];
+const READY = new Set(['verified', 'integrated']);
+const PR_RE = /^(?:https?:\/\/\S+\/pull\/\d+\S*|pr:#?\d+)$/i;
+
+function loadWorkItem() {
+  for (const p of WORK_ITEM_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return { ok: true, mod: require(p) }; }
+    catch (e) { return { ok: false, error: `scripts/work-item.js is present but failed to load — ${String((e && e.message) || e).slice(0, 160)}` }; }
+  }
+  return { ok: false, error: 'the work-item fold (scripts/work-item.js) is not in this install, so factory work cannot be read here' };
+}
+
+function mainTreeOf(root) {
+  try { return require('./plan-tree.js').mainTree(path.resolve(String(root))); } catch { return path.resolve(String(root)); }
+}
+
+/** Per work item, from the raw lines: the `at` of its declaration, its last integrated time and its last PR evidence. */
+function lineFacts(text) {
+  const facts = new Map();
+  for (const raw of String(text).split('\n')) {
+    if (!raw.trim()) continue;
+    let r;
+    try { r = JSON.parse(raw); } catch { continue; }
+    if (!r || typeof r !== 'object' || typeof r.item_id !== 'string') continue;
+    const f = facts.get(r.item_id) || { declaredAt: null, integratedAt: null, pr: null };
+    if (r.event === 'declared' && !f.declaredAt && typeof r.at === 'string') f.declaredAt = r.at;
+    if (r.event === 'integrated' && typeof r.at === 'string') f.integratedAt = r.at;
+    if (typeof r.evidence === 'string' && PR_RE.test(r.evidence.trim())) f.pr = r.evidence.trim();
+    facts.set(r.item_id, f);
+  }
+  return facts;
+}
+
+/** The batch id of one declared instant: b + 14 digits, + the milliseconds when they are not 000. Unique per instant. */
+function batchId(at) {
+  const t = Date.parse(at);
+  if (!Number.isFinite(t)) return `b${String(at).replace(/\D/g, '')}`;
+  const digits = new Date(t).toISOString().replace(/\D/g, '');   // YYYYMMDDHHMMSSmmm
+  return `b${digits.endsWith('000') ? digits.slice(0, 14) : digits}`;
+}
+
+function joinFactory(root, { initiative, fold } = {}) {
+  const out = { ok: true, byInit: {}, flags: [] };
+  const unreadable = (kind, why) => { out.flags.push({ kind, id: null, why }); out.unreadable = why; return out; };
+  const file = path.join(mainTreeOf(root), 'planning', 'work-items.jsonl');
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) {
+    if (!(e && e.code === 'ENOENT')) return unreadable('unreadable', `planning/work-items.jsonl cannot be read (${(e && e.code) || e})`);
+    return out;
+  }
+  if (!text.trim()) return out;
+  const W = loadWorkItem();
+  if (!W.ok) return unreadable('engine-missing', W.error);
+
+  let derived;
+  try { derived = W.mod.deriveItems(text, { now: new Date().toISOString() }); }
+  catch (e) { return unreadable('unreadable', `the work-item fold failed: ${String((e && e.message) || e).slice(0, 160)}`); }
+  for (const d of derived.defects) out.flags.push({ kind: d.kind, id: d.item_id || null, why: `line ${d.line}: ${d.detail}` });
+
+  let planFold = fold || null;
+  if (!planFold && derived.items.some((it) => typeof it.plan_item === 'string')) {
+    try { planFold = require('./plan-items.js').readFold(root); }
+    catch (e) { out.flags.push({ kind: 'plan-items-unreadable', id: null, why: `the plan-items ledger cannot be read, so no plan_item is checked: ${String((e && e.message) || e).slice(0, 160)}` }); }
+  }
+  const known = planFold ? new Set([...Object.keys(planFold.items || {}), ...(planFold.withdrawnIds || [])]) : null;
+
+  const facts = lineFacts(text);
+  const batchesOf = new Map();
+  for (const it of derived.items) {
+    if (initiative && it.initiative_id !== initiative) continue;
+    const id = it.item_id;
+    const f = facts.get(id) || {};
+    const planItem = typeof it.plan_item === 'string' ? it.plan_item : null;
+    if (planItem && known && !known.has(planItem)) {
+      out.flags.push({ kind: 'dangling-plan-item', id, why: `plan_item ${planItem} names no plan item` });
+    }
+    const integrated = (it.history || []).includes('integrated');
+    const entry = out.byInit[it.initiative_id] || (out.byInit[it.initiative_id] = { items: [], batches: [] });
+    entry.items.push({ id, plan_item: planItem, state: it.state, pr: f.pr || null, integrated, integrated_at: integrated ? f.integratedAt || null : null });
+    if (planItem && it.state !== 'withdrawn' && it.state !== 'shipped' && f.declaredAt) {
+      const t = Date.parse(f.declaredAt);
+      const key = `${it.initiative_id}\u0000${Number.isFinite(t) ? t : f.declaredAt}`;
+      if (!batchesOf.has(key)) batchesOf.set(key, { init: it.initiative_id, at: f.declaredAt, items: [], states: [] });
+      const b = batchesOf.get(key);
+      b.items.push(id); b.states.push(it.state);
+    }
+  }
+  for (const b of batchesOf.values()) {
+    out.byInit[b.init].batches.push({ id: batchId(b.at), ready: b.states.every((s) => READY.has(s)), items: b.items.slice().sort() });
+  }
+  for (const e of Object.values(out.byInit)) e.batches.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+/** The health ctx.factory value for one initiative: its join entry, or null. */
+function factoryOf(join, id) {
+  if (join && typeof join.unreadable === 'string') return { items: [], batches: [], unreadable: join.unreadable };
+  return (join && join.byInit && Object.prototype.hasOwnProperty.call(join.byInit, id)) ? join.byInit[id] : null;
+}
+
+module.exports = { joinFactory, factoryOf };