create-pmos 0.47.0 → 0.49.0

package/workspace/guide/proactive-engine.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: Today and the proactive engine"
 description: "What the Today item shows, how the morning brief is made, and how the workspace works out what is waiting for you."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: Today and the proactive engine
@@ -46,7 +46,7 @@ Today learns from you, and only from you. The evidence is your own records on th
 
 - **Weights.** Three adjustments are added to an item's place in the order: one for its trigger (at most 8 points), one for its lane (at most 4) and one for its trigger at this time of day (at most 3). Time of day is morning 05-12, afternoon 12-17, evening 17-22 and night, in your local time. A cell moves only after 5 events, and moves less than the raw average. The total is at most 15, so learning reorders items that are close and cannot turn the stated order upside down. An item shows its adjustment and the counts behind it.
 - **What it never does.** It never lowers or hides what blocks on you: the needs and returned triggers get no negative adjustment and are never narrowed. Items of the morning brief teach no weight, because their order is fixed. Pause learning makes every weight zero and stops the weekly review, the proposals and the narrowing; feedback is still recorded.
-- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review.
+- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review. The review runs from the proactive tick, so while the engine is switched off there is no weekly review either; **run the weekly review now** still works.
 - **The rollup.** For the last 7 days: the hit rate (useful and acted, over useful, acted, not useful, wrong priority and dismissed), the used-as-is rate (accepted over accepted and sent back), corrections per prepared run (sends-back over every session started from a step, reviewed or not), and the items you reported as missed. Every rate shows its count. With fewer than 5 rated items, or 3 runs, it says there is not enough evidence and shows no rate.
 - **The watermelon check.** It looks only when the hit rate is 0.6 or more. It then names any of these: 2 or more items reported as missed, a used-as-is rate under 0.5 over 3 or more reviewed runs, or 0.5 or more corrections per prepared run over 3 or more runs. A good hit rate with one of these under it is not a good week.
 - **Lessons.** The review proposes lessons from four templates: a trigger that was useful under 40% or at least 80% of the time (5 or more ratings), items you reported as missed (2 or more), and a trigger that did badly in one part of the day only. A lesson is a proposal. It is approved, rejected or retired only when you press the button. A rejected lesson is not proposed again for 28 days. At most 10 lessons are approved at once.
@@ -93,6 +93,10 @@ A verdict never changes a status, a lifecycle record or an acceptance. It is rec
 | quiet hours | A start and an end time. No automatic scan runs between them. |
 | pause learning | Stops all learning: weights are zero, and there is no weekly review, no proposal and no narrowing. Feedback is still recorded. |
 
+When you save a setting, Today shows the saved value immediately. A read that started before the save does not replace it.
+
+Text that you type in a setting (the name, the stalled days, the quiet hours) or in the "something was missed" box stays in the box until you save it. A refresh of Today does not clear it, and the box keeps the focus.
+
 ## The commands
 
 - `pmos proactive today` lists the items.

package/workspace/guide/validate-with-typesafe.md

@@ -2,7 +2,7 @@
 type: Guide
 title: "Guide: validate a repository"
 description: "How the validate item checks that a repository agrees with itself, and the optional second check with TypeSafe."
-timestamp: 2026-10-03
+timestamp: 2026-10-04
 ---
 
 # Guide: validate a repository
@@ -61,13 +61,42 @@ Jev's answers are **suspected**, not proven. They appear in their own group, **s
 
 Two rejected keys, or three failed requests in a row, pause automatic checking for that repository. The page says why and shows **resume**. The workspace appends suspected pairs to `claims.jsonl`. Those lines hold a short snippet of the claim. A pair that Jev found fine is not written.
 
+## Read documents for status
+
+A second switch, **read documents for status**, is next to the first one. It is off until you turn it on. It sends texts only when the four conditions above also hold.
+
+When it is on, the workspace asks Jev two more questions about the documents that belong to an initiative:
+
+- **Is it a stub?** Each PRD, rubric and brief that the initiative record names, against the initiative's title and intent.
+- **Does a note contradict a requirement?** Each other document whose frontmatter names the initiative, for example a meeting note, against the requirements of the initiative's PRD.
+
+A document belongs to an initiative only if the record names its path or its own frontmatter names the initiative. Similar words do not make a link.
+
+The first check after you turn this switch on records the documents that exist and sends nothing for them. After that, the workspace sends a document only when it changes. If you turn the switch off, the workspace forgets that starting point. When you turn it on again, it starts again from the documents that exist then. Documents that changed while the switch was off are not sent.
+
+The answers appear in the initiative detail under **What the documents say**, as lines that start with **Documents suggest**. Each line says that it is a suggestion and names the model. A suggestion never changes a phase, a status or a count, and the workspace writes nothing to the document.
+
+## Route prompts with Jev
+
+A third switch, **route prompts with Jev**, is below the consent switch. It is off until you turn it on. When it is off, no prompt is sent.
+
+When the switch is on, a TypeSafe key is saved, and validation is on for the repository, the workspace asks Jev about each prompt that you type in a workspace terminal. Jev answers with a tier: fast, balanced or deep. If the answer names a model that is different from the model of the session, the PMOS cockpit mod changes the model with `/model` and then sends your prompt. A line in the terminal names the new model and the tier.
+
+These prompts are not sent: a slash command, a prompt with an attachment, a prompt that names a file with `@`, and a prompt shorter than 40 characters. A prompt that matches a credential pattern, or that names an excluded path, is not sent. In these cases the model does not change.
+
+If one of the three conditions is missing, the model does not change. The terminal tells you once which condition is missing. A guess from keywords never changes the model.
+
+To stop routing in one terminal, type `/pmos-route off`. To start it again, type `/pmos-route on`.
+
+A change of model starts a new prompt cache, so the next answer can cost more. The workspace does not yet measure if routing saves money.
+
 ## Check with TypeSafe
 
 ## What leaves your machine
 
 Validation is off until you turn it on. Until then, the workspace sends nothing.
 
-When you turn it on, the workspace sends document text to `api.typesafe.ai`. It sends nothing else. It does not send binary files. It does not send a document that you excluded. It does not send a document that matches a credential pattern, such as a private key or a token. It lists that document as withheld.
+When you turn it on, the workspace sends document text to `api.typesafe.ai`. If **route prompts with Jev** is also on, it sends the text of the prompts that you type in a workspace terminal. It sends nothing else. It does not send binary files. It does not send a document that you excluded. It does not send a document that matches a credential pattern, such as a private key or a token. It lists that document as withheld.
 
 The workspace reads the TypeSafe key only on this machine. After you save the key, the screen does not show it again. The workspace does not give the key to a terminal or to an agent.
 

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 };