create-pmos 0.73.0 → 0.75.0

package/workspace/lib/engine/workflow-state.js

@@ -1396,6 +1396,21 @@ function duplicatesArchive(root, L) {
   return path.relative(root, path.join(path.dirname(L.initiatives), 'archive', 'duplicates')).split(path.sep).join('/') + '/';
 }
 function scanRepository(root, L) { return scanDetail(root, L).index; }
+/** The kinds the PM confirmed (S11): `<state>/document-kinds.jsonl`, the latest line for a path. A kind is a role, or `none`. */
+const DOCUMENT_KINDS = ['brief', 'draft', 'review', 'handoff', 'none'];
+function documentKinds(L) {
+  const out = new Map();
+  let text = '';
+  try { text = fs.readFileSync(path.join(path.dirname(L.initiatives), 'document-kinds.jsonl'), 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      if (o && typeof o.path === 'string' && DOCUMENT_KINDS.includes(o.kind)) out.set(o.path, o.kind);
+    } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
 /** The scan's index, and how many initiatives each found document belongs to (`owners`, for the tidy). */
 function scanDetail(root, L) {
   const key = path.resolve(root);
@@ -1403,6 +1418,8 @@ function scanDetail(root, L) {
   if (hit && Date.now() - hit.at < SCAN_TTL_MS) return hit;
   const index = new Map();
   const owners = new Map();
+  const owned = [];     // every document tied to an initiative, with or without a role (the Jev check reads them, S11)
+  const kinds = documentKinds(L);
   const keys = recordKeys(L);
   const idSet = new Set(keys.map((k) => k.id));
   const recDir = path.relative(root, L.initiatives).split(path.sep).join('/') + '/';
@@ -1421,10 +1438,13 @@ function scanDetail(root, L) {
     }
     const owner = documentOwners(rel, fm, idSet, keys);
     if (!owner.ids.length) continue;
-    const role = documentRole(rel, fm.type, owner.key);
-    if (!role) continue;
     // git's index still lists a tracked file that was moved or deleted and not yet staged
     if (!SCAN_TEXT.test(rel) && !fs.existsSync(path.join(root, rel))) continue;
+    const local = documentRole(rel, fm.type, owner.key);
+    const kind = kinds.get(rel) || null;   // a kind the PM confirmed outranks the name (S11)
+    const role = kind ? (kind === 'none' ? null : kind) : local;
+    owned.push({ path: rel, ids: owner.ids, role, local, kind, title: fm.title ? String(fm.title) : null });
+    if (!role) continue;
     owners.set(rel, owner.ids.length);
     for (const id of owner.ids) {
       if (!index.has(id)) index.set(id, { brief: [], draft: [], review: [], handoff: [] });
@@ -1432,7 +1452,7 @@ function scanDetail(root, L) {
     }
   }
   for (const v of index.values()) for (const k of Object.keys(v)) v[k].sort();
-  const out = { at: Date.now(), index, owners };
+  const out = { at: Date.now(), index, owners, owned };
   _scanCache.set(key, out);
   return out;
 }
@@ -1442,6 +1462,27 @@ function documentChangedAt(root, rel) {
   if (t > 0) return t;
   try { return Math.floor(fs.statSync(path.join(root, rel)).mtimeMs / 1000); } catch { return 0; }
 }
+/**
+ * Every document the scan ties to an initiative, for the Jev check (S11): { ok, profile, kinds, documents: [{ path, ids,
+ * role, local, kind, title, text }] }. `local` is the role the name gives, `kind` the one the PM confirmed, `role` the one
+ * the scan uses, and `text` says whether the file is Markdown or text (only those can be read by Jev). Nothing is written.
+ */
+function documentCandidates(root, opts) {
+  const L = layout(root);
+  const profile = profileOf(root);
+  const kinds = path.relative(root, path.join(path.dirname(L.initiatives), 'document-kinds.jsonl')).split(path.sep).join('/');
+  if (profile !== 'pm-artifacts') return { ok: true, profile, kinds, documents: [] };
+  if (opts && opts.fresh) forgetDocumentScan(root);
+  const { owned } = scanDetail(root, L);
+  const titles = {};
+  try {
+    for (const f of fs.readdirSync(L.initiatives)) {
+      if (!f.endsWith('.md') || /^(README|index|log)\.md$/i.test(f)) continue;
+      titles[f.slice(0, -3)] = String((readFrontmatter(path.join(L.initiatives, f)) || {}).title || f.slice(0, -3));
+    }
+  } catch { /* no records */ }
+  return { ok: true, profile, kinds, titles, documents: owned.map((d) => ({ ...d, text: SCAN_TEXT.test(d.path), changed: documentChangedAt(root, d.path) })) };
+}
 /**
  * The duplicates the tidy offers (S10): for each initiative, each role with more than one document. The group keeps the
  * file the record names, else the most recently changed, else the shortest path. A document that belongs to more than one
@@ -1920,7 +1961,7 @@ module.exports = {
   historyRange,
   ENFORCED_FROM,
   lanesFor, laneNames,
-  forgetDocumentScan, documentDuplicates,
+  forgetDocumentScan, documentDuplicates, documentCandidates, DOCUMENT_KINDS,
 };
 
 /*

package/workspace/lib/jev-documents.js

@@ -0,0 +1,224 @@
+'use strict';
+/* jev-documents.js — Jev checks the kind of each initiative document and picks the duplicate to keep (scan-documents S11).
+ *
+ * The bridge between the repository scan (scripts/workflow-state.js documentCandidates) and the one TypeSafe module. Like
+ * lib/jev-categorize.js it opens no client of its own, and no-network.test.js asserts it.
+ *
+ *   plan({ docs, cacheDir, exclude })                         → { documents, requests, fingerprint, cached, withheld_count, excluded, host }
+ *   check({ docs, cacheDir, key, flags, exclude, expectRequests, expectFingerprint, ask, askOpts, now })
+ *                                                            → { ok, sent, failed, kinds: [...], corrections: [...], groups: [...] }
+ *   record(root, kindsFile, corrections, { actor, now })     → { ok, written }   the PM's confirmed corrections, appended
+ *
+ * TWO PASSES. (1) KIND: one Choice question per Markdown or text document the scan ties to an initiative — problem brief,
+ * PRD, evaluation, handoff, or none of these. (2) KEEP: then, by those kinds, one Choice question per group of more than
+ * one document of one kind for one initiative — which one is the most complete and current version. The PM confirms the
+ * number of kind questions before the first pass sends anything; the keep questions follow from the answers.
+ *
+ * WHAT LEAVES THE MACHINE. The D82 snippet of each document (jev-categorize.snippetFor: title, headings and the opening,
+ * at most 3000 characters). Never the path, never the frontmatter, never the whole file. A document under an excluded path,
+ * or whose snippet the secret scan matches, is withheld, and so is every keep group it would be in.
+ *
+ * WHAT A RESULT IS. Advisory (D40). A top option under 0.6, or within 0.1 of the next, is unsure and proposes nothing. A
+ * sure kind that differs from the kind the scan uses now is a CORRECTION; nothing is written until the PM confirms it, and
+ * then only one line per document in `<state>/document-kinds.jsonl`. A keep pick is shown on the tidy sheet; the tidy itself
+ * (lib/tidy-documents.js) moves files. Answers are cached by snippet in the per-user cache directory, so an unchanged
+ * document is never asked twice.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const typesafe = require('./typesafe');
+const scanner = require('./secret-scan');
+const settings = require('./typesafe-settings');
+const JC = require('./jev-categorize');
+
+const UNSURE_BELOW = 0.6;
+const UNSURE_GAP = 0.1;
+const MAX_GROUP = 8;                    // a keep question compares at most this many documents
+const MAX_DOCS = 2000;
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+
+/* The kind question. The option ids are the scan's roles; `none` takes the document out of the scan. */
+const KIND_OPTIONS = {
+  brief: 'A problem brief or idea: the problem, who has it and why it matters, before any solution is specified.',
+  draft: 'A product requirements document (PRD) or specification: the requirements, the scope and how success is judged.',
+  review: 'An evaluation or review of a PRD or of delivered work: scores, a verdict, findings against criteria.',
+  handoff: 'A handoff to delivery: the tickets, epics or work items sent to engineering, or a handover note.',
+  none: 'None of these: meeting notes, a report, research, knowledge, a template or anything else.',
+};
+const KIND_INSTRUCTIONS = 'Which kind of product document is this? Judge from its title, its headings and its opening, given below.';
+const KEEP_INSTRUCTIONS = 'These documents are versions of one kind of document for one initiative. Which one is the most complete and current version, the one to keep?';
+const QUESTION_HASH = sha(JSON.stringify([KIND_INSTRUCTIONS, KIND_OPTIONS, KEEP_INSTRUCTIONS]));
+const LETTERS = 'ABCDEFGH';
+
+const wordsFor = (p) => (p >= 0.85 ? 'very likely' : 'likely');
+
+/** The probabilities of a Choice answer over `ids`, or null when it cannot be read. Pure. */
+function readChoice(ans, ids) {
+  if (!ans || typeof ans !== 'object') return null;
+  const probs = {};
+  const put = (k, v) => { const n = Number(v); if (ids.includes(k) && Number.isFinite(n) && n >= 0 && n <= 1) probs[k] = n; };
+  const raw = ans.probabilities || ans.distribution;
+  if (Array.isArray(raw)) { for (const x of raw) if (x && typeof x === 'object') put(x.option || x.label || x.choice, x.probability != null ? x.probability : x.p); }
+  else if (raw && typeof raw === 'object') { for (const [k, v] of Object.entries(raw)) put(k, v); }
+  if (!Object.keys(probs).length && typeof ans.choice === 'string') put(ans.choice, ans.confidence);
+  if (!Object.keys(probs).length) return null;
+  if (Object.values(probs).reduce((a, b) => a + b, 0) > 1.05) return null;
+  return probs;
+}
+/** The decided option, or unsure with the two leading ones. Pure. */
+function decide(probs) {
+  const ranked = Object.entries(probs || {}).sort((a, b) => b[1] - a[1]);
+  if (!ranked.length) return null;
+  const [top, second] = [ranked[0], ranked[1] || [null, 0]];
+  const leading = [top, second].filter((x) => x[0]).map(([id, p]) => ({ id, p: Math.round(p * 1000) / 1000 }));
+  if (top[1] < UNSURE_BELOW || top[1] - second[1] < UNSURE_GAP) return { decided: false, id: null, p: null, leading };
+  return { decided: true, id: top[0], p: Math.round(top[1] * 1000) / 1000, leading };
+}
+
+/* ── per-user cache ─────────────────────────────────────────────────────────────────────────────── */
+const cacheFile = (cacheDir) => path.join(cacheDir, 'jev-documents-cache.json');
+function readCache(cacheDir) {
+  try { const c = JSON.parse(fs.readFileSync(cacheFile(cacheDir), 'utf8')); return c && typeof c === 'object' && !Array.isArray(c) ? c : {}; } catch { return {}; }
+}
+function writeCache(cacheDir, c) {
+  const keys = Object.keys(c);
+  if (keys.length > 5000) for (const k of keys.slice(0, keys.length - 5000)) delete c[k];
+  try { fs.mkdirSync(cacheDir, { recursive: true }); const tmp = cacheFile(cacheDir) + '.' + process.pid + '.tmp'; fs.writeFileSync(tmp, JSON.stringify(c), { mode: 0o600 }); fs.renameSync(tmp, cacheFile(cacheDir)); } catch { /* the cache is a saving, not a record */ }
+}
+const kindKey = (snip) => sha(['kind', sha(snip), QUESTION_HASH, typesafe.DEFAULT_MODEL].join('\0'));
+const keepKey = (snips) => sha(['keep', ...snips.map(sha), QUESTION_HASH, typesafe.DEFAULT_MODEL].join('\0'));
+
+/* ── which documents ───────────────────────────────────────────────────────────────────────────── */
+/**
+ * `docs` are the scan's documents ({ path, ids, role, text }) with the file text the caller read ({ body, fm }). Only
+ * Markdown and text can be read; each gets its snippet, or is excluded or withheld. Pure.
+ */
+function triage(docs, { exclude = [], cache = {} } = {}) {
+  const out = { items: [], excluded: 0, withheld: [], skipped: 0 };
+  for (const d of (docs || []).slice(0, MAX_DOCS)) {
+    if (!d.text || typeof d.body !== 'string') { out.skipped++; continue; }
+    if (settings.isExcluded(exclude, d.path)) { out.excluded++; continue; }
+    const snip = JC.snippetFor({ fm: d.fm || {}, text: d.body });
+    if (scanner.scan(snip).length) { out.withheld.push(d.path); continue; }
+    const ck = kindKey(snip);
+    out.items.push({ ...d, snip, ck, cached: !!cache[ck] });
+  }
+  return out;
+}
+const fingerprintOf = (items) => sha(Array.from(new Set(items.filter((x) => !x.cached).map((x) => x.ck))).sort().join('\n'));
+
+/** What a check would send for the kind pass. Sends nothing. */
+function plan({ docs, cacheDir, exclude = [] }) {
+  const t = triage(docs, { exclude, cache: readCache(cacheDir) });
+  const ask = new Set(t.items.filter((x) => !x.cached).map((x) => x.ck));
+  return { documents: t.items.length, requests: ask.size, fingerprint: fingerprintOf(t.items), cached: t.items.filter((x) => x.cached).length,
+    withheld_count: t.withheld.length, excluded: t.excluded, skipped: t.skipped, host: typesafe.HOST };
+}
+
+/* ── asking ────────────────────────────────────────────────────────────────────────────────────── */
+async function askOne({ ask, key, askOpts, state, ids, questions, onFail }) {
+  const res = await ask({ key, state, questions, ...askOpts });
+  if (!res.ok) { onFail(res); return null; }
+  return { probs: readChoice(res.answers && res.answers.q, ids), model: res.model || null };
+}
+
+/**
+ * The PM's confirmed check. Refuses unless the gates hold (key, consent, categorize — the D82 switch) and the kind pass has
+ * the number of requests, and the same files, the PM confirmed. Then asks the kind of every document, groups them by kind
+ * and initiative, and asks which one to keep in each group of more than one.
+ */
+async function check({ docs, cacheDir, key, flags, exclude = [], expectRequests, expectFingerprint = null, ask = typesafe.ask, askOpts = {}, now = Date.now() }) {
+  const g = JC.gates({ key: typesafe.validKey(key), consent: !!(flags && flags.consent), categorize: !!(flags && flags.categorize) });
+  if (!g.open) return { ok: false, error: JC.gateSentence(g.missing), missing: g.missing };
+  const cache = readCache(cacheDir);
+  const t = triage(docs, { exclude, cache });
+  const fresh = new Set(t.items.filter((x) => !x.cached).map((x) => x.ck));
+  if (!Number.isInteger(expectRequests) || expectRequests !== fresh.size || (expectFingerprint !== null && expectFingerprint !== fingerprintOf(t.items))) {
+    return { ok: false, conflict: true, error: `the plan changed — it now has ${fresh.size} request(s), not ${expectRequests}. Review it again.` };
+  }
+  let sent = 0, failed = 0, rejected = 0, lastError = null;
+  const at = new Date(now).toISOString();
+  const onFail = (res) => { failed++; lastError = res.reason || 'the request failed'; if (res.status === 401) rejected++; };
+  const stop = () => rejected >= 2 || (failed >= 3 && sent === 0);
+
+  // 1 — the kind of each document
+  const kindIds = Object.keys(KIND_OPTIONS);
+  for (const it of t.items) {
+    if (cache[it.ck] || stop()) continue;
+    const a = await askOne({ ask, key, askOpts, ids: kindIds, state: it.snip, questions: { q: { type: 'choice', instructions: KIND_INSTRUCTIONS, criteria: KIND_OPTIONS } }, onFail });
+    if (!a) continue;
+    sent++;
+    cache[it.ck] = { probs: a.probs, model: a.model, at };
+  }
+  const kinds = [];
+  const corrections = [];
+  const jevRole = new Map();      // path → the role Jev is sure of, or the current one
+  for (const it of t.items) {
+    const hit = cache[it.ck];
+    const d = hit && hit.probs ? decide(hit.probs) : null;
+    const now_ = it.role || 'none';
+    const row = { path: it.path, ids: it.ids, current: now_, kind: d && d.decided ? d.id : null, p: d && d.decided ? d.p : null,
+      unsure: !!(d && !d.decided), leading: d ? d.leading.map((x) => x.id) : [], answered: !!d,
+      words: d && d.decided ? `Jev rates it ${wordsFor(d.p)} that this is ${KIND_WORDS[d.id]}.` : d ? `Jev was unsure: ${d.leading.map((x) => KIND_WORDS[x.id]).join(' or ')}.` : null };
+    kinds.push(row);
+    jevRole.set(it.path, row.kind || now_);
+    // a kind the PM already confirmed is the PM's: Jev proposes no change to it
+    if (row.kind && row.kind !== now_ && !it.kind) corrections.push({ path: it.path, ids: it.ids, was: now_, kind: row.kind, p: row.p, words: row.words });
+  }
+
+  // 2 — which one to keep, per initiative and kind, by Jev's kinds
+  const byGroup = new Map();
+  for (const it of t.items) {
+    const role = jevRole.get(it.path);
+    if (!role || role === 'none' || it.ids.length !== 1) continue;      // a document shared by two initiatives never moves (S10)
+    const k = it.ids[0] + '\0' + role;
+    if (!byGroup.has(k)) byGroup.set(k, { id: it.ids[0], role, docs: [] });
+    byGroup.get(k).docs.push(it);
+  }
+  const groups = [];
+  for (const grp of [...byGroup.values()].sort((a, b) => (a.id + a.role).localeCompare(b.id + b.role))) {
+    if (grp.docs.length < 2) continue;
+    const docs_ = grp.docs.slice(0, MAX_GROUP).sort((a, b) => a.path.localeCompare(b.path));
+    const ids = docs_.map((_, i) => LETTERS[i]);
+    const kk = keepKey(docs_.map((x) => x.snip));
+    if (!cache[kk] && !stop()) {
+      const state = docs_.map((x, i) => `=== DOCUMENT ${LETTERS[i]} ===\n${x.snip}`).join('\n\n').slice(0, typesafe.MAX_STATE_CHARS);
+      const criteria = Object.fromEntries(ids.map((l) => [l, `Document ${l} is the most complete and current version.`]));
+      const a = await askOne({ ask, key, askOpts, ids, state, questions: { q: { type: 'choice', instructions: KEEP_INSTRUCTIONS, criteria } }, onFail });
+      if (a) { sent++; cache[kk] = { probs: a.probs, model: a.model, at }; }
+    }
+    const hit = cache[kk];
+    const d = hit && hit.probs ? decide(hit.probs) : null;
+    const pick = d && d.decided ? docs_[ids.indexOf(d.id)] : null;
+    groups.push({ id: grp.id, role: grp.role, files: docs_.map((x) => x.path), keep: pick ? pick.path : null, p: d && d.decided ? d.p : null,
+      words: pick ? `Jev rates it ${wordsFor(d.p)} that ${pick.path} is the version to keep.` : d ? 'Jev was unsure which version to keep.' : 'Jev did not answer for this group.' });
+  }
+  writeCache(cacheDir, cache);
+  const paused = rejected >= 2 ? 'The service rejected the key twice, so the check stopped.' : (failed >= 3 && sent === 0 ? 'The service could not be reached, so the check stopped.' : null);
+  return { ok: true, sent, failed, error: lastError, paused, kinds, corrections, groups, withheld_count: t.withheld.length, excluded: t.excluded, skipped: t.skipped };
+}
+const KIND_WORDS = { brief: 'a problem brief', draft: 'a PRD', review: 'an evaluation', handoff: 'a handoff', none: 'none of these kinds' };
+
+/**
+ * Append the PM's confirmed corrections to `<state>/document-kinds.jsonl`, one line each. `corrections` is
+ * [{ path, kind, was?, p? }]. A path must be repository-relative and a kind one of KIND_OPTIONS.
+ */
+function record(root, kindsFile, corrections, { actor, now } = {}) {
+  if (!Array.isArray(corrections) || !corrections.length) return { ok: true, written: 0 };
+  if (corrections.length > MAX_DOCS) return { ok: false, status: 400, error: `at most ${MAX_DOCS} corrections at once` };
+  const lines = [];
+  for (const c of corrections) {
+    const p = c && typeof c.path === 'string' ? c.path.replace(/\\/g, '/') : '';
+    if (!p || p.startsWith('/') || p.split('/').includes('..') || p.length > 1024) return { ok: false, status: 400, error: 'each correction names a repository-relative path' };
+    if (!Object.prototype.hasOwnProperty.call(KIND_OPTIONS, c.kind)) return { ok: false, status: 400, error: 'each correction names a kind: ' + Object.keys(KIND_OPTIONS).join(', ') };
+    lines.push(JSON.stringify({ ev: 'kind', path: p, kind: c.kind, was: typeof c.was === 'string' ? c.was : null, p: Number.isFinite(c.p) ? c.p : null,
+      by: (actor && actor.by) || 'pm:unknown', via: 'jev', at: (now || new Date()).toISOString() }));
+  }
+  const file = path.join(root, kindsFile);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, lines.join('\n') + '\n');
+  return { ok: true, written: lines.length };
+}
+
+module.exports = { plan, check, record, triage, readChoice, decide, KIND_OPTIONS, KIND_WORDS, MAX_GROUP, UNSURE_BELOW, UNSURE_GAP };

package/workspace/lib/routes-initiatives.js

@@ -11,8 +11,11 @@
  *                                                    nothing is written: the cached rows go stale and one derivation starts
  *   POST /api/initiatives/duplicates { ws }      → { ok, profile, archive, groups }   documents that share an initiative and a
  *                                                    role (scan-documents S10; requirePagePress; nothing is written)
- *   POST /api/initiatives/tidy { ws, keep: [{ id, role, keep }] } → { ok, archive, moved, skipped }   move every other
- *                                                    document of each named group to the archive (lib/tidy-documents.js)
+ *   POST /api/initiatives/tidy { ws, keep: [{ id, role, keep }], kinds?: [{ path, kind, was, p }] } → { ok, archive, moved,
+ *                                                    skipped, kinds_written }   record the PM's confirmed Jev kinds (S11), then
+ *                                                    move every other document of each named group to the archive
+ *   POST /api/initiatives/jev-check { ws, confirm?, expect_requests?, expect_fingerprint? } → { ok, gates, plan } without
+ *                                                    confirm; { ok, corrections, groups, sent, … } with it (lib/jev-documents.js)
  *   POST /api/placements     { ws, events: [placed | created | adopted | dropped] }
  *                                                    → { ok, written, sig }   fixtures/initiatives-api/post-ok.json
  *   POST /api/measurements   { ws, events: [measured] } → { ok, written, sig }
@@ -51,6 +54,9 @@ const consoleState = require('./console-state');
 const initiativeFiles = require('./initiative-files');
 const jiraTickets = require('./jira-tickets.js');
 const tidy = require('./tidy-documents.js');
+const jevDocs = require('./jev-documents.js');
+const tsSettings = require('./typesafe-settings');
+const docCatCorrections = require('./doc-category-corrections');
 
 const HORIZON_RANK = { now: 0, next: 1, later: 2 };
 const FILE_KEYS = [['brief_path', 'brief', 'Brief'], ['prd_path', 'prd', 'PRD'], ['rubric_path', 'rubric', 'Rubric'], ['doc_path', 'doc', 'Document']];
@@ -445,6 +451,51 @@ function derivedBreakdown(root, rec, lay) {
   return { source, basis, state, items: list, progress: { done: state === 'done' ? n : 0, total: n, proposed: 0, label: `${state === 'done' ? n : 0} of ${n} · from ${source.split(',')[0].split('/').pop()}` } };
 }
 
+// ── the Jev check (scan-documents S11) ───────────────────────────────────────────────────────────
+const JEV_BODY_MAX = 200000;
+/** The scan's documents with the text Jev's snippet is made from (Markdown and text only). */
+function jevDocsOf(engine, root) {
+  const c = engine.documentCandidates(root, { fresh: true });
+  const docs = (c.documents || []).map((d) => {
+    if (!d.text) return d;
+    let text = '';
+    try { text = fs.readFileSync(path.join(root, d.path), 'utf8').slice(0, JEV_BODY_MAX); } catch { return { ...d, text: false }; }
+    const fm = (engine.parseLeadingFrontmatter && engine.parseLeadingFrontmatter(text)) || {};
+    return { ...d, fm, body: text };
+  });
+  return { c, docs };
+}
+async function jevCheck(ctx, w, engine, body) {
+  const flags = tsSettings.getRepo(ctx.runtimeDir, w.root);
+  const present = tsSettings.status(ctx.runtimeDir).present;
+  const gates = { open: !!present && flags.consent && flags.categorize, missing: [] };
+  if (!present) gates.missing.push('key');
+  if (!flags.consent) gates.missing.push('consent');
+  if (!flags.categorize) gates.missing.push('categorize');
+  gates.sentence = gates.open ? null : require('./jev-categorize').gateSentence(gates.missing);
+  const { c, docs } = jevDocsOf(engine, w.root);
+  if (c.profile !== 'pm-artifacts') return { ok: true, profile: c.profile, gates, plan: null };
+  const cacheDir = docCatCorrections.repoDir(ctx.runtimeDir, w.root);
+  if (body.confirm !== true || !gates.open) return { ok: true, profile: c.profile, gates, plan: gates.open ? jevDocs.plan({ docs, cacheDir, exclude: flags.exclude }) : null };
+  const out = await jevDocs.check({ docs, cacheDir, key: tsSettings.getKey(ctx.runtimeDir), flags, exclude: flags.exclude,
+    expectRequests: body.expect_requests, expectFingerprint: typeof body.expect_fingerprint === 'string' ? body.expect_fingerprint : null, askOpts: ctx.jevModelOpts ? ctx.jevModelOpts(w.root) : {} });
+  if (!out.ok) return { ...out, status: out.conflict ? 409 : 403, gates };
+  // the groups in the tidy sheet's shape: the record's own file is kept whatever Jev says (S11), then Jev's pick, then the newest
+  const named = new Map();
+  const dup = engine.documentDuplicates ? engine.documentDuplicates(w.root) : { groups: [] };
+  for (const g of dup.groups || []) if (g.named) named.set(g.id + '\0' + g.role, g.keep);
+  const byPath = new Map(docs.map((d) => [d.path, d]));
+  const groups = out.groups.map((g) => {
+    const files = g.files.map((f) => ({ path: f, changed: (byPath.get(f) || {}).changed || 0 })).sort((a, b) => b.changed - a.changed || a.path.localeCompare(b.path));
+    const pin = named.get(g.id + '\0' + g.role);
+    const keep = pin && g.files.includes(pin) ? pin : (g.keep || files[0].path);
+    return { id: g.id, title: (c.titles || {})[g.id] || g.id, role: g.role, keep, files, shared: [], named: keep === pin, jev: { keep: g.keep, words: g.words } };
+  });
+  const corrections = out.corrections.map((x) => ({ ...x, title: (c.titles || {})[x.ids[0]] || x.ids[0] }));
+  return { ok: true, profile: c.profile, gates, sent: out.sent, failed: out.failed, error: out.error, paused: out.paused, checked: out.kinds.length,
+    unsure: out.kinds.filter((k) => k.unsure).length, corrections, groups, archive: dup.archive || null, withheld_count: out.withheld_count, excluded: out.excluded };
+}
+
 // ── HTTP ─────────────────────────────────────────────────────────────────────────────────────────
 function wsOf(ctx, url) {
   const wsParam = url.searchParams.get('ws');
@@ -559,15 +610,37 @@ async function handle(req, res, url, ctx) {
     ctx.json(res, { ok: true, ws: w.id, started: r.started, running: r.running });
     return true;
   }
+  // Jev checks the kind of each document and picks the duplicate to keep (scan-documents S11). Without `confirm` it
+  // answers the gates and the plan and sends nothing; with it, the PM-confirmed check.
+  if (p === '/api/initiatives/jev-check') {
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) return answer(ctx, res, g), true;
+    const loaded = consoleState.loadEngine();
+    if (!loaded.ok || typeof loaded.engine.documentCandidates !== 'function') { ctx.json(res, { ok: false, status: 501, error: 'this workspace engine cannot list documents; update the kit' }, 501); return true; }
+    const r = await jevCheck(ctx, w, loaded.engine, body);
+    ctx.json(res, { ws: w.id, ...r }, r.ok ? 200 : (r.status || 500));
+    return true;
+  }
   // Tidy duplicates before a scan (scan-documents S10). The list is a POST so its path cannot be read as an initiative id.
   if (p === '/api/initiatives/duplicates' || p === '/api/initiatives/tidy') {
     const g = guard.requirePagePress(req, body);
     if (!g.ok) return answer(ctx, res, g), true;
     const loaded = consoleState.loadEngine();
     if (!loaded.ok) { ctx.json(res, { ok: false, status: 500, error: 'the workflow engine could not be loaded' }, 500); return true; }
+    let kinds = null;
+    if (p === '/api/initiatives/tidy' && Array.isArray(body.kinds) && body.kinds.length) {
+      // the PM's confirmed Jev corrections first (S11), so the duplicates below are grouped by the corrected kinds
+      const c = typeof loaded.engine.documentCandidates === 'function' ? loaded.engine.documentCandidates(w.root) : null;
+      if (!c || !c.kinds) { ctx.json(res, { ok: false, status: 501, error: 'this workspace engine cannot record document kinds; update the kit' }, 501); return true; }
+      kinds = jevDocs.record(w.root, c.kinds, body.kinds, { actor: actorLib.fromUi() });
+      if (!kinds.ok) { ctx.json(res, { ok: false, status: kinds.status || 400, error: kinds.error }, kinds.status || 400); return true; }
+      if (loaded.engine.forgetDocumentScan) loaded.engine.forgetDocumentScan(w.root);
+    }
+    const keep = Array.isArray(body.keep) ? body.keep : [];
     const r = p === '/api/initiatives/duplicates'
       ? tidy.preview(loaded.engine, w.root)
-      : tidy.apply(loaded.engine, w.root, body.keep, { actor: actorLib.fromUi() });
+      : (kinds && !keep.length ? { ok: true, archive: null, moved: [], skipped: [] } : tidy.apply(loaded.engine, w.root, keep, { actor: actorLib.fromUi() }));
+    if (r.ok && kinds) r.kinds_written = kinds.written;
     if (!r.ok) { ctx.json(res, { ok: false, status: r.status || 500, error: r.error }, r.status || 500); return true; }
     // the page scans next (POST /rescan), which drops the cached rows; dropping them here would lose the answer before the tidy
     ctx.json(res, { ws: w.id, ...r });

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/pm/components.css

@@ -3346,6 +3346,40 @@
 .td-day__draftbox { display: grid; gap: 4px; }
 .td-day__draft { margin: 0; max-height: 220px; overflow: auto; padding: 8px 10px; white-space: pre-wrap; font: 12px/1.5 var(--mono); background: var(--muted); color: var(--foreground); }
 .td-day__revise { display: grid; gap: 6px; }
+/* act and prepare (initiative today-act-prepare): a verb first, one sentence, the steps, one button that fits, the marks */
+.td-day__verb { display: inline-block; min-width: 58px; padding: 2px 5px; border: 1px solid currentColor; font: 600 10px/1.3 var(--mono); letter-spacing: 0.05em; text-transform: uppercase; text-align: center; color: var(--foreground); white-space: nowrap; }
+.td-day__verb[data-verb="decide"], .td-day__verb[data-verb="prepare"] { color: var(--warning); }
+.td-day__acth { margin: 0; font-size: 16px; font-weight: 600; line-height: 1.3; text-wrap: balance; }
+.td-day__todo { margin: 0; padding: 7px 10px; border-left: 3px solid var(--foreground); background: var(--muted); font-size: 14px; line-height: 1.45; color: var(--foreground); }
+.td-day__steps2 { list-style: none; margin: 0; padding: 0; display: grid; gap: 4px; }
+.td-day__step2 { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 5px 8px; border: 1px solid var(--border); background: var(--background); }
+.td-day__step2[data-done="true"] .td-day__steprow { text-decoration: line-through; color: var(--muted-foreground); }
+.td-day__marks { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; padding-top: 8px; border-top: 1px solid var(--border); }
+.td-day__grow { flex: 1 1 0; }
+.td-day__mark { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; padding: 6px 10px; border: 1px solid var(--border); background: var(--muted); font-size: 14px; }
+.td-day__mark[data-day-mark-state="done"] { border-color: var(--foreground); }
+.td-day__ready { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 12px; font-size: 12px; }
+.td-day__prep { display: grid; gap: 8px; padding: 10px 12px; border: 1px solid var(--border); background: var(--background); }
+.td-day__fold { border-top: 1px solid var(--border); padding-top: 6px; }
+.td-day__fold > summary { cursor: pointer; font-size: 12px; color: var(--muted-foreground); }
+.td-day__fold[open] > summary { margin-bottom: 6px; }
+.td-day__fold > summary:focus-visible, .td-day__fold[open] > summary:focus-visible, .td-day__ref > summary:focus-visible { outline: 2px solid color-mix(in oklab, var(--ring) 50%, var(--foreground)); outline-offset: 2px; }
+@media (pointer: coarse) { .td-day__fold > summary, .td-day__fold[open] > summary, .td-day__ref > summary { min-height: 44px; } }
+.td-day__fold-head { justify-self: start; }
+.td-day__steprow { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.td-day__step2:has(.td-day__ref), .td-day__step2:has(.td-day__notebox) { flex-direction: column; align-items: stretch; }
+.td-day__ref { display: grid; gap: 4px; padding: 6px 8px; background: var(--muted); font-size: 14px; }
+.td-day__ref > summary { display: flex; justify-content: space-between; gap: 8px; cursor: pointer; font-weight: 600; color: var(--foreground); }
+.td-day__reflines { margin: 0; padding-left: 18px; display: grid; gap: 2px; color: var(--foreground); line-height: 1.45; }
+.td-day__thread { display: grid; gap: 6px; }
+.td-day__msg { display: grid; gap: 2px; padding: 6px 10px; border-left: 2px solid var(--border); }
+.td-day__msg p { margin: 0; font-size: 14px; line-height: 1.45; color: var(--foreground); }
+.td-day__msg--last { border-left-color: var(--foreground); }
+.td-day__compose { display: grid; gap: 6px; padding: 8px 10px; border: 1px solid var(--border); background: var(--background); }
+.td-day__chipsrow { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; }
+.td-day__notebox { display: grid; gap: 4px; }
+.td-day__a--primary { background: var(--primary); color: var(--primary-foreground); border-color: var(--primary); }
+@media (hover: hover) { .td-day__a--primary:hover { color: var(--primary-foreground); opacity: 0.9; } }
 .td-day__log { font-size: 12px; color: var(--muted-foreground); }
 .td-day__ch { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 8px; font-size: 14px; color: var(--foreground); }
 .td-day__slist { display: grid; }

package/workspace/public/pm/initiatives-api.js

@@ -12,7 +12,10 @@
  *   POST /api/initiatives      { ws, title, lane, anchor, intent?, from? }   the New-initiative form and a triage card (one body, no events)
  *   POST /api/initiatives/rescan { ws }                     the Re-scan press: read the repository again now (nothing is written)
  *   POST /api/initiatives/duplicates { ws }                 documents that share an initiative and a role (S10; nothing is written)
- *   POST /api/initiatives/tidy { ws, keep }                 move every other document of each kept group to the archive (S10)
+ *   POST /api/initiatives/tidy { ws, keep, kinds? }         record the kinds the PM confirmed (S11), then move every other
+ *                                                           document of each kept group to the archive (S10)
+ *   POST /api/initiatives/jev-check { ws, confirm?, … }     Jev's plan (nothing sent), or the PM-confirmed check: each
+ *                                                           document's kind and the duplicate to keep (S11)
  *
  * Every GET of /api/initiatives answers 202 { ok: false, pending: true } until the repository's first derivation lands (2C,
  * about 260 ms a record); a read waits and asks again, so a caller sees the answer or a real error, never the 202.
@@ -75,7 +78,10 @@ export async function rescan(ws, opts) {
 
 /** The duplicates a tidy offers (S10), and the tidy itself: `keep` is [{ id, role, keep }] for each group to tidy. */
 export const duplicates = (ws) => pmPost('/api/initiatives/duplicates', { ws });
-export const tidy = (ws, keep) => pmPost('/api/initiatives/tidy', { ws, keep });
+export const tidy = (ws, keep, kinds) => pmPost('/api/initiatives/tidy', kinds && kinds.length ? { ws, keep, kinds } : { ws, keep });
+/** Jev's check (S11). With no `plan` it answers the gates and the plan and sends nothing; with the plan the PM confirmed it asks Jev. */
+export const jevCheck = (ws, plan) => pmPost('/api/initiatives/jev-check', plan
+  ? { ws, confirm: true, expect_requests: plan.requests, expect_fingerprint: plan.fingerprint } : { ws });
 
 export const createInitiative = (ws, fields) => pmPost('/api/initiatives', { ws, ...fields });
 

package/workspace/public/pm/initiatives-copy.js

@@ -22,6 +22,8 @@ export const GLOSSARY = {
   guide: 'initiatives-screen.md',
 };
 
+const KIND = { brief: 'problem brief', draft: 'PRD', review: 'evaluation', handoff: 'handoff', none: 'none of these' };
+
 export const COPY = {
   title: 'Initiatives',
   views: 'Initiatives view',
@@ -56,6 +58,23 @@ export const COPY = {
   tidyNone: 'Nothing to archive: every group is off.',
   tidyArchived: (n) => `Archived ${n} duplicate ${n === 1 ? 'document' : 'documents'}.`,
   tidyFailed: (why) => `Could not tidy: ${why}`,
+  // Jev checks each document's kind and picks the duplicate to keep, before the tidy (scan-documents S11)
+  jevTitle: 'Check documents with Jev',
+  jevPlan: (p) => `Jev reads ${p.documents} ${p.documents === 1 ? 'document' : 'documents'} tied to initiatives and says what kind each one is: problem brief, PRD, evaluation, handoff or none of these. Then it picks the version to keep where an initiative has more than one of a kind. This sends ${p.requests} ${p.requests === 1 ? 'request' : 'requests'} to ${p.host}${p.cached ? `; ${p.cached} ${p.cached === 1 ? 'document was' : 'documents were'} checked before and ${p.cached === 1 ? 'is' : 'are'} not sent again` : ''}. Only each document's title, headings and opening are sent, never its path or the whole file.`,
+  jevWithheld: (n) => `${n} ${n === 1 ? 'document is' : 'documents are'} not sent: ${n === 1 ? 'it is' : 'they are'} in an excluded folder or may contain a secret.`,
+  jevGo: (n) => (n ? `Check with Jev (${n} ${n === 1 ? 'request' : 'requests'})` : 'Check with Jev'),
+  jevSkip: 'Scan without Jev',
+  jevReading: 'Jev is reading the documents…',
+  jevFailed: (why) => `Jev could not check the documents: ${why}`,
+  jevShut: (why) => `Jev did not check the documents: ${why}`,
+  jevPaused: (why) => `${why} The scan uses the answers it has.`,
+  jevClean: (n) => `Jev checked ${n} ${n === 1 ? 'document' : 'documents'}: each kind is right and there are no duplicates.`,
+  jevKindsHead: (n) => `Jev reads ${n} ${n === 1 ? 'document' : 'documents'} as a different kind`,
+  jevKindsBody: 'A changed kind is written to the kinds file in the repository. The scan uses it from now on.',
+  jevKindLine: (c) => `${c.title} · ${c.path}: ${KIND[c.was] || c.was} → ${KIND[c.kind] || c.kind}`,
+  jevKindToggle: 'Use this kind',
+  jevConfirm: (k, n) => [k ? `Change ${k} ${k === 1 ? 'kind' : 'kinds'}` : '', n ? `archive ${n}` : ''].filter(Boolean).join(', ') + ' and scan',
+  jevRecorded: (n) => `Changed the kind of ${n} ${n === 1 ? 'document' : 'documents'}.`,
   rescanDone: (t) => `Read again at ${t}`,
   rescanFailed: (why) => `Could not re-scan: ${why}`,
   rescanSlow: 'The re-scan is still running. The view updates when it ends.',