create-pmos 0.65.3 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.65.3",
+  "version": "0.67.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@bc7453c
+kernel-source: pmos@5233c8c
 assembled: 2026-10-07
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-07T01:27:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T02:01:39Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-07T01:27:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T02:01:39Z"}
 status: stable
 ---
 

package/payload/scripts/workflow-state.js

@@ -1274,6 +1274,129 @@ function computeWorkflowDerived(id, opts) {
   };
 }
 
+// ── The document scan (scan-documents S1–S4) — what the repository holds for each initiative ─────
+// A pm-artifacts record often names none of its documents: the PRD, the evaluation and the Jira
+// tickets sit in the repository and the record was never told. The ladder used to read the record
+// only, so that work read as not started. This reads the repository once per root (tracked and
+// untracked, not ignored), joins each document to an initiative by its frontmatter or by the id in
+// its path, and gives it a role from its name. It is evidence a named path outranks, never a
+// blocker, and nothing is written back. The cache holds SCAN_TTL_MS; `forgetDocumentScan` (the
+// workspace's Scan repository) drops it at once.
+const SCAN_TTL_MS = 30000;
+const SCAN_MAX_FILES = 20000;
+const SCAN_EXT = /\.(md|markdown|mdx|txt|docx|pdf|html?)$/i;
+const SCAN_TEXT = /\.(md|markdown|mdx|txt)$/i;
+const SCAN_ROLES = [   // first match wins, in this order (S2)
+  ['review', ['eval', 'evals', 'evaluation', 'evaluations', 'review', 'reviews', 'verdict', 'scorecard']],
+  ['handoff', ['handoff', 'handover', 'hand-off']],
+  ['brief', ['brief', 'briefs', 'problem', 'idea', 'ideas', 'intake', 'one-pager', 'onepager', 'bug-report']],
+  ['draft', ['prd', 'prds', 'spec', 'specs', 'specification', 'requirements', 'findings', 'plan', 'strategy', 'report', 'decision']],
+];
+const SCAN_NOT_EVIDENCE = ['rubric', 'rubrics', 'template', 'templates'];
+const JIRA_KEY = /^[A-Z][A-Z0-9_]+-\d+$/;
+const _scanCache = new Map();   // root -> { at, index: Map(id -> { brief:[], draft:[], review:[], handoff:[] }) }
+function forgetDocumentScan(root) { if (root) _scanCache.delete(path.resolve(root)); else _scanCache.clear(); }
+
+function scanWords(s) {
+  const lower = String(s || '').toLowerCase();
+  const words = lower.split(/[^a-z0-9]+/).filter(Boolean);
+  // The hyphenated role words are matched as joined pairs too: "hand-off", "one-pager", "bug-report".
+  const n = words.length;
+  for (let i = 0; i + 1 < n; i++) words.push(`${words[i]}-${words[i + 1]}`);
+  return words;
+}
+function roleOfWords(words, extra) {
+  const set = new Set(words);
+  for (const [role, list] of SCAN_ROLES) {
+    if (list.some((w) => set.has(w))) return role;
+    if (role === 'draft' && extra && extra.some((w) => set.has(w))) return role;
+  }
+  return null;
+}
+/** The role of a found document: its file name, then its frontmatter `type:`, then its folders (S2). */
+function documentRole(rel, type, ids) {
+  const parts = rel.split('/');
+  const base = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+  // The id is not a role word: "problem-reporting-prd" is a PRD of the initiative problem-reporting.
+  const strip = (s) => { let out = s.toLowerCase(); for (const id of ids || []) out = out.split(id.toLowerCase()).join(' '); return out; };
+  // A rubric or a template says what good looks like; it is not evidence that the work was judged or done.
+  if (scanWords(base).some((x) => SCAN_NOT_EVIDENCE.includes(x))) return null;
+  return roleOfWords(scanWords(strip(base))) || roleOfWords(scanWords(type))
+    || roleOfWords(scanWords(strip(parts.slice(0, -1).join('/'))));
+}
+/** The initiatives a document belongs to (S1): its frontmatter names them, else the longest id that is a folder or leads the file name. */
+function documentOwners(rel, fm, idSet, byLength) {
+  const named = [fm.initiative, fm.initiative_id, fm.initiatives].filter(Boolean)
+    .flatMap((v) => String(v).replace(/^\[|\]$/g, '').split(',')).map((s) => s.trim().replace(/^["']|["']$/g, ''))
+    .filter((s) => idSet.has(s));
+  if (named.length) return [...new Set(named)];
+  const parts = rel.toLowerCase().split('/');
+  const base = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+  const dirs = parts.slice(0, -1);
+  for (const id of byLength) {
+    if (id.length < 3) break;
+    const low = id.toLowerCase();
+    if (dirs.includes(low)) return [id];
+    if (base === low || base.startsWith(low + '-') || base.startsWith(low + '_') || base.startsWith(low + '.')) return [id];
+  }
+  return [];
+}
+/** Every record id, read from the records folder (the scan needs them all to pick the longest owner). */
+function recordIds(L) {
+  try { return fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)).map((f) => f.slice(0, -3)); }
+  catch { return []; }
+}
+function scanRepository(root, ids, L) {
+  const key = path.resolve(root);
+  const hit = _scanCache.get(key);
+  if (hit && Date.now() - hit.at < SCAN_TTL_MS && ids.every((id) => hit.ids.has(id))) return hit.index;
+  const index = new Map();
+  const idSet = new Set(ids);
+  const byLength = ids.slice().sort((a, b) => b.length - a.length);
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  const files = out == null ? [] : [...new Set(out.split('\0').filter(Boolean))].slice(0, SCAN_MAX_FILES);
+  const recDir = path.relative(root, L.initiatives).split(path.sep).join('/') + '/';
+  for (const rel of files) {
+    if (!SCAN_EXT.test(rel) || rel.startsWith(recDir) || /(^|\/)(node_modules|\.git)\//.test(rel)) continue;
+    let fm = {};
+    if (SCAN_TEXT.test(rel)) {
+      try {
+        const fd = fs.openSync(path.join(root, rel), 'r');
+        const buf = Buffer.alloc(4096);
+        const n = fs.readSync(fd, buf, 0, 4096, 0);
+        fs.closeSync(fd);
+        fm = parseLeadingFrontmatter(buf.slice(0, n).toString('utf8')) || {};
+      } catch { continue; }
+    }
+    const owners = documentOwners(rel, fm, idSet, byLength);
+    if (!owners.length) continue;
+    const role = documentRole(rel, fm.type, owners);
+    if (!role) continue;
+    for (const id of owners) {
+      if (!index.has(id)) index.set(id, { brief: [], draft: [], review: [], handoff: [] });
+      index.get(id)[role].push(rel);
+    }
+  }
+  for (const v of index.values()) for (const k of Object.keys(v)) v[k].sort();
+  _scanCache.set(key, { at: Date.now(), ids: idSet, index });
+  return index;
+}
+/** Jira keys the repository holds for an initiative (S4): the Jira tab's draft, then the record's own keys. */
+function jiraKeysOf(root, L, id, fm) {
+  const keys = [];
+  const draft = path.join(path.dirname(L.initiatives), 'tracker', 'jira', `${id}-tickets.md`);
+  try {
+    for (const line of fs.readFileSync(draft, 'utf8').split('\n')) {
+      const m = /^- jira:\s*(\S+)\s*$/.exec(line);
+      if (m && JIRA_KEY.test(m[1].toUpperCase())) keys.push(m[1].toUpperCase());
+    }
+  } catch { /* no draft */ }
+  for (const k of ['jira', 'jira_key', 'jira_keys', 'jira_epic']) {
+    for (const m of String(fm[k] || '').toUpperCase().matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+  }
+  return [...new Set(keys)];
+}
+
 /**
  * D68 — the pm-artifacts ladder: route → anchor → brief → draft → review → approved → handed off.
  *
@@ -1286,6 +1409,9 @@ function computeWorkflowDerived(id, opts) {
  *   review   — an evals.jsonl verdict for this id, or a named `reviewed_by:` (a rubric, an agent, a human)
  *   approved — the PM's acceptance in acceptances.jsonl (D12, never automatic)
  *   handoff  — `handed_off:` names where it went; n/a for decision records, reports and chores
+ * When the record names no file for brief, draft or review, or names one that does not exist, a
+ * document the repository scan found for the id completes the step (scan-documents S3); Jira keys
+ * in the repository complete the handoff (S4). Found evidence never blocks and never fails CI.
  * Track: `light` (guidance — only route and anchor can fail CI) or `governed` (brief and draft
  * existence and their order fail CI for a non-legacy record). Review, approval and handoff are never
  * CI-blocking in either track: none can be true before the PR exists.
@@ -1307,12 +1433,17 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     : step('route', 'route', 'done', `unknown lane '${lane}' — treated as a governed prd, the profile's strictest (D68)`,
       `set lane: to one of ${laneNames('pm-artifacts').join(', ')}`);
 
+  const found = (opts && opts.scan === false) ? null : (scanRepository(root, recordIds(L).concat(id), L).get(id) || null);
+  const foundOf = (role) => (found && found[role].length ? found[role][0] : null);
   const briefPath = String(fm.brief_path || fm.prd_path || '').trim();
   const docPath = String(fm.doc_path || '').trim();
+  const foundBrief = exists(briefPath) ? null : foundOf('brief');
+  const foundDraft = exists(docPath) ? null : foundOf('draft');
   const briefIdx = briefPath ? firstAppearance(root, range, briefPath) : null;
   const docIdx = docPath ? firstAppearance(root, range, docPath) : null;
 
   if (!flows('brief')) steps.push(skipped('brief', def.brief_label));
+  else if (foundBrief) steps.push(step('brief', def.brief_label, 'done', `${foundBrief} — found by the repository scan`));
   else if (exists(briefPath)) steps.push(step('brief', def.brief_label, 'done', `${briefPath} present`));
   else steps.push(step('brief', def.brief_label, enforce ? 'blocked' : 'pending',
     briefPath ? `brief_path '${briefPath}' does not exist` : `no ${def.brief_label} yet`,
@@ -1320,6 +1451,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     { blocking: enforce, rule: 'P1' }));
 
   if (!flows('draft')) steps.push(skipped('draft', def.draft_label));
+  else if (foundDraft) steps.push(step('draft', def.draft_label, 'done', `${foundDraft} — found by the repository scan`));
   else if (exists(docPath)) {
     const inOrder = briefIdx == null || docIdx == null ? null : docIdx >= briefIdx;
     if (enforce && inOrder === false) {
@@ -1335,6 +1467,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (!flows('review')) steps.push(skipped('review', 'review'));
   else if (evals.length) steps.push(step('review', 'review', 'done', `${evals[evals.length - 1].verdict || 'verdict'} recorded in evals.jsonl`));
   else if (reviewer) steps.push(step('review', 'review', 'done', `reviewed by ${reviewer}`));
+  else if (foundOf('review')) steps.push(step('review', 'review', 'done', `${foundOf('review')} — evaluation found by the repository scan`));
   else steps.push(step('review', 'review', 'pending', 'not reviewed yet',
     'name the reviewer in reviewed_by: (a person, an agent, or a rubric verdict in evals.jsonl)'));
 
@@ -1359,7 +1492,10 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));
   else {
     const to = String(fm.handed_off || '').trim();
+    const keys = to ? [] : jiraKeysOf(root, L, id, fm);
     steps.push(to ? step('handoff', 'handed off', 'done', `handed off — ${to}`)
+      : keys.length ? step('handoff', 'handed off', 'done', `handed off to Jira — ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ` and ${keys.length - 5} more` : ''}`)
+      : foundOf('handoff') ? step('handoff', 'handed off', 'done', `${foundOf('handoff')} — handoff found by the repository scan`)
       : step('handoff', 'handed off', 'pending', 'not handed off yet',
         'record where it went in handed_off: (a tracker link, the team, or "accepted as the deliverable")'));
   }
@@ -1370,6 +1506,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (by.brief.status === 'done') stage = 'brief';
   if (by.draft.status === 'done') stage = 'draft';
   if (by.review.status === 'done') stage = 'review';
+  if (by.handoff && by.handoff.status === 'done') stage = 'handoff';
   if (accepted.length) stage = 'accepted';
   const blockers = steps.filter((x) => x.status === 'blocked');
   const gateFailures = blockers.filter((x) => x.blocking);
@@ -1382,6 +1519,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
     last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
     title: fm.title || id, anchor: fm.parent_kr || null, profile: 'pm-artifacts', track,
+    found: found ? { brief: found.brief.slice(), draft: found.draft.slice(), review: found.review.slice(), handoff: found.handoff.slice() } : null,
     ...facts,
     steps, blockers: blockers.map((x) => x.key), gate_failures: gateFailures.map((x) => x.rule || x.key),
     next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
@@ -1673,6 +1811,7 @@ module.exports = {
   historyRange,
   ENFORCED_FROM,
   lanesFor, laneNames,
+  forgetDocumentScan,
 };
 
 /*

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-07T01:27:56Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T02:01:39Z"}
 status: stable
 ---
 

package/workspace/guide/initiatives-screen.md

@@ -11,11 +11,30 @@ The Initiatives place shows every initiative of the selected repository. Each in
 
 Press **Roadmap** or **List** at the top to change the view. The workspace keeps your choice in this browser.
 
-### Re-scan
+### Scan repository
 
-The workspace reads the stage, the files and the breakdown of each initiative from the repository. It reads them again when an initiative record changes, and at the latest after ten minutes. A change that does not touch a record, for example a pull request merged on the trunk, can show late.
+The workspace reads the stage, the files and the breakdown of each initiative from the repository. It reads them again when an initiative record changes, and at the latest after ten minutes. A change that does not touch a record, for example a new PRD or a pull request merged on the trunk, can show late.
 
-To read the repository again now, use **Re-scan the repository**. It is in the **⋯** menu of an initiative sheet, and in the command menu (⌘K). A toast shows **Re-scanning…**, and another shows the time when the read ends. Then the view updates. Re-scan writes nothing. It works the same on PMOS itself and on a tenant repository.
+To read the repository again now, press **Scan repository** at the top of the screen. The same action is in the **⋯** menu of an initiative sheet, and in the command menu (⌘K). A toast shows **Scanning the repository…**. When the scan ends, a toast tells you how many initiatives it checked and how many moved, by stage, for example "Checked 42 initiatives. 9 moved: 4 to PRD, 3 to Evaluate, 2 to Handoff." Then the view updates. The scan writes nothing. It works the same on PMOS itself and on a tenant repository.
+
+### What the scan finds in a document repository
+
+In a document repository (`.pmos-profile` is `pm-artifacts`), the scan reads every document in the repository: Markdown, text, Word, PDF and HTML files that git does not ignore, whether git tracks them yet or not. A document belongs to an initiative when:
+
+- its frontmatter names the initiative in `initiative:`, `initiative_id:` or `initiatives:`, or
+- a folder in its path is the initiative's id, for example `docs/checkout/problem-brief.md`, or
+- its file name starts with the initiative's id, for example `checkout-prd.md`. When two ids match, the longer id wins.
+
+The file name, then the `type:` in the frontmatter, then the folder names give the document its role:
+
+| Role | Words | Step it completes |
+|---|---|---|
+| Evaluation | `eval`, `evaluation`, `review`, `verdict`, `scorecard` | review |
+| Handoff | `handoff`, `hand-off`, `handover` | handed off |
+| Brief | `brief`, `problem`, `idea`, `intake`, `one-pager`, `bug-report` | the brief, for example Problem brief |
+| Draft | `prd`, `spec`, `specification`, `requirements`, `findings`, `plan`, `strategy`, `report`, `decision` | the draft, for example PRD |
+
+A rubric or a template is not evidence. Jira keys also complete the handoff: the keys the Jira tab recorded when it pushed the tickets, and a `jira:`, `jira_key:` or `jira_epic:` key in the record. A path that the record names always comes before a found document. A found document never fails a gate. Acceptance is always yours: the scan never records it.
 
 ## The Roadmap
 

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

@@ -1274,6 +1274,129 @@ function computeWorkflowDerived(id, opts) {
   };
 }
 
+// ── The document scan (scan-documents S1–S4) — what the repository holds for each initiative ─────
+// A pm-artifacts record often names none of its documents: the PRD, the evaluation and the Jira
+// tickets sit in the repository and the record was never told. The ladder used to read the record
+// only, so that work read as not started. This reads the repository once per root (tracked and
+// untracked, not ignored), joins each document to an initiative by its frontmatter or by the id in
+// its path, and gives it a role from its name. It is evidence a named path outranks, never a
+// blocker, and nothing is written back. The cache holds SCAN_TTL_MS; `forgetDocumentScan` (the
+// workspace's Scan repository) drops it at once.
+const SCAN_TTL_MS = 30000;
+const SCAN_MAX_FILES = 20000;
+const SCAN_EXT = /\.(md|markdown|mdx|txt|docx|pdf|html?)$/i;
+const SCAN_TEXT = /\.(md|markdown|mdx|txt)$/i;
+const SCAN_ROLES = [   // first match wins, in this order (S2)
+  ['review', ['eval', 'evals', 'evaluation', 'evaluations', 'review', 'reviews', 'verdict', 'scorecard']],
+  ['handoff', ['handoff', 'handover', 'hand-off']],
+  ['brief', ['brief', 'briefs', 'problem', 'idea', 'ideas', 'intake', 'one-pager', 'onepager', 'bug-report']],
+  ['draft', ['prd', 'prds', 'spec', 'specs', 'specification', 'requirements', 'findings', 'plan', 'strategy', 'report', 'decision']],
+];
+const SCAN_NOT_EVIDENCE = ['rubric', 'rubrics', 'template', 'templates'];
+const JIRA_KEY = /^[A-Z][A-Z0-9_]+-\d+$/;
+const _scanCache = new Map();   // root -> { at, index: Map(id -> { brief:[], draft:[], review:[], handoff:[] }) }
+function forgetDocumentScan(root) { if (root) _scanCache.delete(path.resolve(root)); else _scanCache.clear(); }
+
+function scanWords(s) {
+  const lower = String(s || '').toLowerCase();
+  const words = lower.split(/[^a-z0-9]+/).filter(Boolean);
+  // The hyphenated role words are matched as joined pairs too: "hand-off", "one-pager", "bug-report".
+  const n = words.length;
+  for (let i = 0; i + 1 < n; i++) words.push(`${words[i]}-${words[i + 1]}`);
+  return words;
+}
+function roleOfWords(words, extra) {
+  const set = new Set(words);
+  for (const [role, list] of SCAN_ROLES) {
+    if (list.some((w) => set.has(w))) return role;
+    if (role === 'draft' && extra && extra.some((w) => set.has(w))) return role;
+  }
+  return null;
+}
+/** The role of a found document: its file name, then its frontmatter `type:`, then its folders (S2). */
+function documentRole(rel, type, ids) {
+  const parts = rel.split('/');
+  const base = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+  // The id is not a role word: "problem-reporting-prd" is a PRD of the initiative problem-reporting.
+  const strip = (s) => { let out = s.toLowerCase(); for (const id of ids || []) out = out.split(id.toLowerCase()).join(' '); return out; };
+  // A rubric or a template says what good looks like; it is not evidence that the work was judged or done.
+  if (scanWords(base).some((x) => SCAN_NOT_EVIDENCE.includes(x))) return null;
+  return roleOfWords(scanWords(strip(base))) || roleOfWords(scanWords(type))
+    || roleOfWords(scanWords(strip(parts.slice(0, -1).join('/'))));
+}
+/** The initiatives a document belongs to (S1): its frontmatter names them, else the longest id that is a folder or leads the file name. */
+function documentOwners(rel, fm, idSet, byLength) {
+  const named = [fm.initiative, fm.initiative_id, fm.initiatives].filter(Boolean)
+    .flatMap((v) => String(v).replace(/^\[|\]$/g, '').split(',')).map((s) => s.trim().replace(/^["']|["']$/g, ''))
+    .filter((s) => idSet.has(s));
+  if (named.length) return [...new Set(named)];
+  const parts = rel.toLowerCase().split('/');
+  const base = parts[parts.length - 1].replace(/\.[^.]+$/, '');
+  const dirs = parts.slice(0, -1);
+  for (const id of byLength) {
+    if (id.length < 3) break;
+    const low = id.toLowerCase();
+    if (dirs.includes(low)) return [id];
+    if (base === low || base.startsWith(low + '-') || base.startsWith(low + '_') || base.startsWith(low + '.')) return [id];
+  }
+  return [];
+}
+/** Every record id, read from the records folder (the scan needs them all to pick the longest owner). */
+function recordIds(L) {
+  try { return fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)).map((f) => f.slice(0, -3)); }
+  catch { return []; }
+}
+function scanRepository(root, ids, L) {
+  const key = path.resolve(root);
+  const hit = _scanCache.get(key);
+  if (hit && Date.now() - hit.at < SCAN_TTL_MS && ids.every((id) => hit.ids.has(id))) return hit.index;
+  const index = new Map();
+  const idSet = new Set(ids);
+  const byLength = ids.slice().sort((a, b) => b.length - a.length);
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  const files = out == null ? [] : [...new Set(out.split('\0').filter(Boolean))].slice(0, SCAN_MAX_FILES);
+  const recDir = path.relative(root, L.initiatives).split(path.sep).join('/') + '/';
+  for (const rel of files) {
+    if (!SCAN_EXT.test(rel) || rel.startsWith(recDir) || /(^|\/)(node_modules|\.git)\//.test(rel)) continue;
+    let fm = {};
+    if (SCAN_TEXT.test(rel)) {
+      try {
+        const fd = fs.openSync(path.join(root, rel), 'r');
+        const buf = Buffer.alloc(4096);
+        const n = fs.readSync(fd, buf, 0, 4096, 0);
+        fs.closeSync(fd);
+        fm = parseLeadingFrontmatter(buf.slice(0, n).toString('utf8')) || {};
+      } catch { continue; }
+    }
+    const owners = documentOwners(rel, fm, idSet, byLength);
+    if (!owners.length) continue;
+    const role = documentRole(rel, fm.type, owners);
+    if (!role) continue;
+    for (const id of owners) {
+      if (!index.has(id)) index.set(id, { brief: [], draft: [], review: [], handoff: [] });
+      index.get(id)[role].push(rel);
+    }
+  }
+  for (const v of index.values()) for (const k of Object.keys(v)) v[k].sort();
+  _scanCache.set(key, { at: Date.now(), ids: idSet, index });
+  return index;
+}
+/** Jira keys the repository holds for an initiative (S4): the Jira tab's draft, then the record's own keys. */
+function jiraKeysOf(root, L, id, fm) {
+  const keys = [];
+  const draft = path.join(path.dirname(L.initiatives), 'tracker', 'jira', `${id}-tickets.md`);
+  try {
+    for (const line of fs.readFileSync(draft, 'utf8').split('\n')) {
+      const m = /^- jira:\s*(\S+)\s*$/.exec(line);
+      if (m && JIRA_KEY.test(m[1].toUpperCase())) keys.push(m[1].toUpperCase());
+    }
+  } catch { /* no draft */ }
+  for (const k of ['jira', 'jira_key', 'jira_keys', 'jira_epic']) {
+    for (const m of String(fm[k] || '').toUpperCase().matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+  }
+  return [...new Set(keys)];
+}
+
 /**
  * D68 — the pm-artifacts ladder: route → anchor → brief → draft → review → approved → handed off.
  *
@@ -1286,6 +1409,9 @@ function computeWorkflowDerived(id, opts) {
  *   review   — an evals.jsonl verdict for this id, or a named `reviewed_by:` (a rubric, an agent, a human)
  *   approved — the PM's acceptance in acceptances.jsonl (D12, never automatic)
  *   handoff  — `handed_off:` names where it went; n/a for decision records, reports and chores
+ * When the record names no file for brief, draft or review, or names one that does not exist, a
+ * document the repository scan found for the id completes the step (scan-documents S3); Jira keys
+ * in the repository complete the handoff (S4). Found evidence never blocks and never fails CI.
  * Track: `light` (guidance — only route and anchor can fail CI) or `governed` (brief and draft
  * existence and their order fail CI for a non-legacy record). Review, approval and handoff are never
  * CI-blocking in either track: none can be true before the PR exists.
@@ -1307,12 +1433,17 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     : step('route', 'route', 'done', `unknown lane '${lane}' — treated as a governed prd, the profile's strictest (D68)`,
       `set lane: to one of ${laneNames('pm-artifacts').join(', ')}`);
 
+  const found = (opts && opts.scan === false) ? null : (scanRepository(root, recordIds(L).concat(id), L).get(id) || null);
+  const foundOf = (role) => (found && found[role].length ? found[role][0] : null);
   const briefPath = String(fm.brief_path || fm.prd_path || '').trim();
   const docPath = String(fm.doc_path || '').trim();
+  const foundBrief = exists(briefPath) ? null : foundOf('brief');
+  const foundDraft = exists(docPath) ? null : foundOf('draft');
   const briefIdx = briefPath ? firstAppearance(root, range, briefPath) : null;
   const docIdx = docPath ? firstAppearance(root, range, docPath) : null;
 
   if (!flows('brief')) steps.push(skipped('brief', def.brief_label));
+  else if (foundBrief) steps.push(step('brief', def.brief_label, 'done', `${foundBrief} — found by the repository scan`));
   else if (exists(briefPath)) steps.push(step('brief', def.brief_label, 'done', `${briefPath} present`));
   else steps.push(step('brief', def.brief_label, enforce ? 'blocked' : 'pending',
     briefPath ? `brief_path '${briefPath}' does not exist` : `no ${def.brief_label} yet`,
@@ -1320,6 +1451,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     { blocking: enforce, rule: 'P1' }));
 
   if (!flows('draft')) steps.push(skipped('draft', def.draft_label));
+  else if (foundDraft) steps.push(step('draft', def.draft_label, 'done', `${foundDraft} — found by the repository scan`));
   else if (exists(docPath)) {
     const inOrder = briefIdx == null || docIdx == null ? null : docIdx >= briefIdx;
     if (enforce && inOrder === false) {
@@ -1335,6 +1467,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (!flows('review')) steps.push(skipped('review', 'review'));
   else if (evals.length) steps.push(step('review', 'review', 'done', `${evals[evals.length - 1].verdict || 'verdict'} recorded in evals.jsonl`));
   else if (reviewer) steps.push(step('review', 'review', 'done', `reviewed by ${reviewer}`));
+  else if (foundOf('review')) steps.push(step('review', 'review', 'done', `${foundOf('review')} — evaluation found by the repository scan`));
   else steps.push(step('review', 'review', 'pending', 'not reviewed yet',
     'name the reviewer in reviewed_by: (a person, an agent, or a rubric verdict in evals.jsonl)'));
 
@@ -1359,7 +1492,10 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (!flows('handoff')) steps.push(step('handoff', 'handed off', 'na', `${effLane} — nothing to hand off`));
   else {
     const to = String(fm.handed_off || '').trim();
+    const keys = to ? [] : jiraKeysOf(root, L, id, fm);
     steps.push(to ? step('handoff', 'handed off', 'done', `handed off — ${to}`)
+      : keys.length ? step('handoff', 'handed off', 'done', `handed off to Jira — ${keys.slice(0, 5).join(', ')}${keys.length > 5 ? ` and ${keys.length - 5} more` : ''}`)
+      : foundOf('handoff') ? step('handoff', 'handed off', 'done', `${foundOf('handoff')} — handoff found by the repository scan`)
       : step('handoff', 'handed off', 'pending', 'not handed off yet',
         'record where it went in handed_off: (a tracker link, the team, or "accepted as the deliverable")'));
   }
@@ -1370,6 +1506,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
   if (by.brief.status === 'done') stage = 'brief';
   if (by.draft.status === 'done') stage = 'draft';
   if (by.review.status === 'done') stage = 'review';
+  if (by.handoff && by.handoff.status === 'done') stage = 'handoff';
   if (accepted.length) stage = 'accepted';
   const blockers = steps.filter((x) => x.status === 'blocked');
   const gateFailures = blockers.filter((x) => x.blocking);
@@ -1382,6 +1519,7 @@ function pmLadder({ id, fm, lane, effLane, knownLane, legacy, steps, root, L, re
     ok: true, id, lane, laneKnown: knownLane, legacy, in_change: inChange,
     last_activity: lastActivity, accepted: accepted.length > 0, stage, record: recRel,
     title: fm.title || id, anchor: fm.parent_kr || null, profile: 'pm-artifacts', track,
+    found: found ? { brief: found.brief.slice(), draft: found.draft.slice(), review: found.review.slice(), handoff: found.handoff.slice() } : null,
     ...facts,
     steps, blockers: blockers.map((x) => x.key), gate_failures: gateFailures.map((x) => x.rule || x.key),
     next: next ? { step: next.key, why: next.evidence, action: next.next || next.evidence } : null,
@@ -1673,6 +1811,7 @@ module.exports = {
   historyRange,
   ENFORCED_FROM,
   lanesFor, laneNames,
+  forgetDocumentScan,
 };
 
 /*

package/workspace/lib/initiative-rows.js

@@ -73,6 +73,8 @@ function narrow(root, raw) {
     last_activity: iso(r.last_activity), profile: r.profile || null, record: r.record || null, next: r.next || null,
     // key and status of each ladder step, so a row's stage is read by the same rule as the sheet's stepper
     steps: Array.isArray(r.steps) ? r.steps.filter(Boolean).map((x) => ({ key: x.key, status: x.status })) : null,
+    // the documents the repository scan found for it, by role (scan-documents S1–S3); null in a code repository
+    found: r.found && typeof r.found === 'object' ? r.found : null,
   } : { ok: false, id: r && r.id, error: (r && r.error) || 'the row could not be derived' }));
 }
 

package/workspace/lib/routes-initiatives.js

@@ -278,8 +278,10 @@ function sheetOf(w, F, rec, opts = {}) {
     const file = planTree.recordPath(root, rec.id);
     if (loaded.ok && file) fm = loaded.engine.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {};
   } catch { fm = {}; }
-  const files = filesOf(root, rec, fm, opts);
-  const derived = derivedBreakdown(root, rec, lay);
+  // the sheet's own ladder is fresher than the row cache: its scan finds a document written since the rows were read
+  const recF = lad && lad.ok && lad.found ? { ...rec, found: lad.found } : rec;
+  const files = filesOf(root, recF, fm, opts);
+  const derived = derivedBreakdown(root, recF, lay);
   const verb = { now: 'Moved to Now', next: 'Moved to Next', later: 'Moved to Later' };
   const history = F.placed.moves.filter((m) => m.init === rec.id)
     .map((m) => ({ at: m.at, by: actorLib.pageName(m.by), text: m.from === null && m.to === 'later' ? 'Added to Later' : verb[m.to] }))
@@ -295,6 +297,7 @@ function sheetOf(w, F, rec, opts = {}) {
  *   git             the files the commits for it changed (lib/initiative-files.js: its branch, and trunk commits naming it)
  * A path is listed once, under its first source. A git read that fails is a `{ kind: 'note' }` row, never an empty list.
  */
+const FOUND_ROLES = [['brief', 'Brief'], ['draft', 'Draft'], ['review', 'Evaluation'], ['handoff', 'Handoff']];
 function filesOf(root, rec, fm, opts) {
   const out = [];
   const seen = new Set();
@@ -316,6 +319,8 @@ function filesOf(root, rec, fm, opts) {
     push({ kind, label: cap(kind.replace(/_/g, ' ')), path: v.trim(), source: 'record' });
   }
   if (rec.record) push({ kind: 'record', label: 'Record', path: String(rec.record), source: 'record' });
+  // The documents the repository scan tied to it (scan-documents S1–S3), when the record names none of them.
+  for (const [role, label] of FOUND_ROLES) for (const rel of (rec.found && rec.found[role]) || []) push({ kind: role, label, path: String(rel), source: 'scan' });
   let groups = [];
   try { groups = opts && opts.initiativeIndex ? (opts.initiativeIndex(root).initiatives || []) : []; } catch { groups = []; }
   const g = groups.find((x) => x && x.id === rec.id);
@@ -397,8 +402,11 @@ function derivedBreakdown(root, rec, lay) {
     if (st && st.ok && st.items.length) { items = st.items.map((x) => ({ ref: x.id, title: firstSentence(x.title) })); source = st.sources.join(', '); }
   } catch { items = []; }
   if (!items.length) {
-    for (const k of ['prd_path', 'doc_path', 'brief_path']) {
-      const rel = typeof rfm[k] === 'string' ? rfm[k].trim() : '';
+    // the paths the record names, then the documents the repository scan found (scan-documents S6)
+    const found = rec.found || {};
+    const cands = ['prd_path', 'doc_path', 'brief_path'].map((k) => rfm[k]).concat(found.draft || [], found.brief || []);
+    for (const c of cands) {
+      const rel = typeof c === 'string' ? c.trim() : '';
       if (!rel) continue;
       let text = null;
       try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { text = null; }
@@ -526,6 +534,7 @@ async function handle(req, res, url, ctx) {
     const g = guard.requirePagePress(req, body);
     if (!g.ok) return answer(ctx, res, g), true;
     initiativeFiles.forget(w.root);
+    try { const loaded = consoleState.loadEngine(); if (loaded.ok && loaded.engine.forgetDocumentScan) loaded.engine.forgetDocumentScan(w.root); } catch { /* an older engine has no scan cache */ }
     const r = rowsLib.rescan(w.root);
     if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id);
     ctx.json(res, { ok: true, ws: w.id, started: r.started, running: r.running });

package/workspace/package-lock.json

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

package/workspace/package.json

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

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

@@ -108,6 +108,8 @@ function draw(host, r, ctx, repo, ws) {
   const head = el('div', { class: 'in-head' },
     el('h2', { class: 'in-head__title' }, COPY.title),
     tabs({ variant: 'segmented', role: 'tablist', ariaLabel: COPY.views, items: views, value: r.view, attrs: { 'data-in-views': '' }, onChange: (id) => { r.view = id; saveView(id); r.draw(r.ctx); } }),
+    // Scan repository (scan-documents S7): the visible form of the sheet menu's and ⌘K's re-scan. It needs a workspace.
+    ws ? button({ label: COPY.rescan, icon: 'refresh-cw', attrs: { 'data-in-scan': '', title: COPY.rescanHint }, onClick: () => rescanRepo(ws) }) : null,
     button({ label: COPY.newInitiative, icon: 'plus', variant: 'primary', attrs: { 'data-in-new': '' }, onClick: () => r.openNew() }));
   r.body = el('div', { class: 'in-body', 'data-in-body': r.view });
   r.root.replaceChildren(head, r.body);

package/workspace/public/pm/initiative-sheet.js

@@ -272,9 +272,10 @@ export function openSheet(repo, slug) {
     if (tab === 'people') { panel.replaceChildren(initiativePeople(ws, slug, { onOpen: () => s.close() })); return; }
     if (tab === 'files') {
       const files = data.files || [];
-      // Grouped by where the tie came from (scan-consistency R3): the record's own paths, the documents the library's
+      // Grouped by where the tie came from (scan-consistency R3, scan-documents S3): the record's own paths, the documents
+      // the repository scan found, the documents the library's
       // index links to it, and the files git changed for it. A `note` row is a fact about the list, not a file.
-      const order = ['record', 'knowledge-graph', 'git'];
+      const order = ['record', 'scan', 'knowledge-graph', 'git'];
       const groups = order.map((src) => [src, files.filter((f) => (f.source || 'record') === src)]).filter(([, list]) => list.length);
       const fileRow = (f) => (f.kind === 'note' ? el('p', { class: 'in-note', 'data-in-file-note': '' }, f.label) : row({
         title: f.label, meta: [f.path, f.commits ? COPY.sheet.commits(f.commits) : null, f.shared ? COPY.sheet.shared : null], openLabel: COPY.aria.open(f.label),

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

@@ -51,13 +51,16 @@ export const drop = (ws, proposal) => pmPost('/api/placements', { ws, events: [{
 /** Read the repository again now. Answers when the new derivation has landed (the records part of the sig stops reading
  *  `~stale`), or { ok: true, slow: true } when it is still running after about three minutes. */
 export async function rescan(ws) {
+  const roadmap = () => pmGet('/api/initiatives?ws=' + enc(ws) + '&view=roadmap');
+  // the answer before the scan, so the caller can say what moved (scan-documents S7)
+  const before = await roadmap();
   const a = await pmPost('/api/initiatives/rescan', { ws });
   if (!a || !a.ok) return a || { ok: false, error: 'no answer' };
   for (let k = 0; k < 120; k++) {
     await sleep(1500);
-    const r = await pmGet('/api/initiatives?ws=' + enc(ws) + '&view=roadmap');
+    const r = await roadmap();
     const rec = r && r.sig ? String(r.sig.records || '') : '';
-    if (r && r.ok && rec && !rec.endsWith('~stale')) return { ok: true };
+    if (r && r.ok && rec && !rec.endsWith('~stale')) return { ok: true, before: before && before.ok ? before : null, after: r };
   }
   return { ok: true, slow: true };
 }

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

@@ -28,9 +28,16 @@ export const COPY = {
   roadmap: 'Roadmap',
   list: 'List',
   newInitiative: 'New initiative',
-  rescan: 'Re-scan the repository',
-  rescanning: 'Re-scanning…',
-  rescanHint: 'Read stage, files and breakdown again now',
+  rescan: 'Scan repository',
+  rescanning: 'Scanning the repository…',
+  rescanHint: 'Check every initiative against the repository and move it to its real stage',
+  // scan-documents S7: what the scan found, in one sentence — "Checked 42 initiatives. 9 moved: 4 to PRD, 3 to Evaluate."
+  rescanResult: (checked, moves) => {
+    const n = moves.reduce((a, m) => a + m.count, 0);
+    const head = `Checked ${checked} initiative${checked === 1 ? '' : 's'}.`;
+    if (!n) return `${head} None moved.`;
+    return `${head} ${n} moved: ${moves.map((m) => `${m.count} to ${m.label}`).join(', ')}.`;
+  },
   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.',
@@ -142,7 +149,7 @@ export const COPY = {
     graphReading: 'Reading the links…',
     graphError: 'The links could not be read. The list is below.',
     graphPhone: 'On a small screen the files show as a list.',
-    fileSource: { record: 'Named by the record', 'knowledge-graph': 'Linked documents', git: 'Changed for it in git' },
+    fileSource: { record: 'Named by the record', scan: 'Found by the repository scan', 'knowledge-graph': 'Linked documents', git: 'Changed for it in git' },
     commits: (n) => (n === 1 ? '1 commit' : `${n} commits`),
     shared: 'shared',
     skippedStep: (noun) => `Skipped: ${noun} is still open`,

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

@@ -26,14 +26,38 @@ export function healthSignal(health) {
   return signal({ text: top.text || COPY.healthUnknown, tone, title: top.source || null, attrs: { 'data-health': health.level } });
 }
 
+/** The rows of a roadmap answer: every horizon, and the dormant ones. */
+const rowsOf = (answer) => (answer && answer.horizons
+  ? [...(answer.horizons.now || []), ...(answer.horizons.next || []), ...(answer.horizons.later || []), ...(answer.dormant || [])] : []);
+/**
+ * What a scan changed (scan-documents S7): how many initiatives the answer after the scan holds, and how many now read a
+ * different stage than before, grouped by the stage they moved to, largest group first. null when there is no answer
+ * from before to compare with.
+ */
+export function scanMoves(before, after) {
+  if (!before) return null;
+  const was = new Map(rowsOf(before).filter((r) => r && r.ok !== false).map((r) => [r.id, (r.stage && r.stage.label) || null]));
+  const rows = rowsOf(after).filter((r) => r && r.ok !== false);
+  const by = new Map();
+  for (const r of rows) {
+    const now = (r.stage && r.stage.label) || null;
+    if (!now || !was.has(r.id) || was.get(r.id) === now) continue;
+    by.set(now, (by.get(now) || 0) + 1);
+  }
+  const moves = [...by].map(([label, count]) => ({ label, count })).sort((x, y) => y.count - x.count || x.label.localeCompare(y.label));
+  return { checked: rows.length, moves };
+}
+
 /** Re-scan: read the repository again now. A toast says it started and another says how it ended. Answers the rescan
  *  answer; the caller reloads what it shows when `ok`. */
 export async function rescanRepo(ws) {
   toast({ text: COPY.rescanning, timeout: 4000 });
   const a = await rescan(ws);
   const t = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  const moved = a && a.ok && a.after ? scanMoves(a.before, a.after) : null;
   if (!a || !a.ok) toast({ text: COPY.rescanFailed((a && a.error) || 'no answer'), tone: 'error', timeout: 8000 });
-  else toast({ text: a.slow ? COPY.rescanSlow : COPY.rescanDone(t), timeout: 6000 });
+  else if (a.slow) toast({ text: COPY.rescanSlow, timeout: 6000 });
+  else toast({ text: moved ? COPY.rescanResult(moved.checked, moved.moves) : COPY.rescanDone(t), timeout: 10000 });
   try { if (a && a.ok) window.dispatchEvent(new CustomEvent('pmos:initiatives-changed')); } catch { /* no window */ }
   return a || { ok: false };
 }

package/workspace/run-tests.js

@@ -2,8 +2,9 @@
 'use strict';
 /* run-tests.js — run the workspace suites side by side.
  *
- *   node run-tests.js <group> [--jobs=N] [--shard=I/N] [--changed[=REF]] [--list] [--verbose]
+ *   node run-tests.js <group> [--jobs=N] [--shard=I/N] [--changed[=REF]] [--timings-out=FILE] [--list] [--verbose]
  *   node run-tests.js --check
+ *   node run-tests.js --merge-timings=DIR
  *
  * Groups come from test-files.json: unit (test.js + modules), modules, panels, ui, browser
  * (panels + ui), all. The npm scripts call this file, so `npm test` and CI run the same lists.
@@ -31,6 +32,14 @@
  * test-files.json, plus `helpers` (a -test.js file that is a helper, not a suite, with the reason, as
  * in ELSEWHERE). This file merges every fragment into the lists before it does anything else, so
  * --check, --shard and every group see one list. A fragment that is not valid fails every command.
+ *
+ * Timings. --shard balances the shards by each suite's time, and the shards only finish together when
+ * those times are the CI runner's. test-timings.json holds times measured on CI; the `seconds` keys in
+ * test-files.json and the fragments are the fallback for a suite it does not name yet, and a suite in
+ * neither counts as 10. The `seconds` numbers were measured on a 4-CPU sandbox and were off by up to
+ * 4x on the 2-CPU runners, which left one shard running 280s while two others finished in 130s.
+ * Every CI job writes its times with --timings-out and uploads them; --merge-timings=DIR folds a
+ * downloaded set into test-timings.json. A stale time never skips a suite: it only moves it.
  */
 const fs = require('fs');
 const os = require('os');
@@ -98,7 +107,10 @@ const args = process.argv.slice(2);
 const flag = (name) => { const a = args.find((x) => x === `--${name}` || x.startsWith(`--${name}=`)); return a === undefined ? undefined : (a.includes('=') ? a.slice(a.indexOf('=') + 1) : true); };
 const group = args.find((a) => !a.startsWith('--'));
 
-const secs = (f) => Number((FILES.seconds || {})[f]) || 10;
+const TIMINGS_FILE = path.join(DIR, 'test-timings.json');
+let TIMINGS = {};
+try { TIMINGS = JSON.parse(fs.readFileSync(TIMINGS_FILE, 'utf8')).seconds || {}; } catch { /* no CI timings yet: the seconds keys decide */ }
+const secs = (f) => Number(TIMINGS[f]) || Number((FILES.seconds || {})[f]) || 10;
 // Slowest first, so a long suite never starts last and holds the run open on its own.
 const bySlowest = (list) => list.map((f, k) => ({ f, k })).sort((a, b) => secs(b.f) - secs(a.f) || a.k - b.k).map((x) => x.f);
 
@@ -155,6 +167,7 @@ function changedSuites(list, ref) {
   for (const f of files) {
     if (source.has(f)) { picked.add(f); continue; }
     if (/^(guide|docs)\/|\.md$/.test(f)) continue; // prose: no suite asserts on it except guide.test.js, a unit suite
+    if (f === 'test-timings.json') continue; // run order only: no suite reads it
     const stem = path.basename(f).replace(/\.[^.]+$/, '');
     const key = stem.replace(/^(panel|view|tab)-/, '');
     const hits = list.filter((s) => source.get(s).includes(stem) || s.includes(`-${key}-`) || s.includes(`-${key}.`));
@@ -207,8 +220,30 @@ function runOne(file, verbose) {
   });
 }
 
+// Fold the --timings-out files a CI run uploaded (one per job, in DIR) into test-timings.json. A suite
+// the run did not reach keeps its old time; a time under one second is recorded as one.
+function mergeTimings(dir) {
+  const old = fs.existsSync(TIMINGS_FILE) ? JSON.parse(fs.readFileSync(TIMINGS_FILE, 'utf8')) : {};
+  const seconds = { ...(old.seconds || {}) };
+  let n = 0;
+  for (const name of fs.readdirSync(dir, { recursive: true }).filter((x) => String(x).endsWith('.json'))) {
+    for (const [f, v] of Object.entries(JSON.parse(fs.readFileSync(path.join(dir, String(name)), 'utf8')))) {
+      if (typeof v === 'number' && GROUPS.all.includes(f)) { seconds[f] = Math.max(1, Math.round(v)); n++; }
+    }
+  }
+  const sorted = Object.fromEntries(Object.keys(seconds).filter((f) => GROUPS.all.includes(f)).sort().map((f) => [f, seconds[f]]));
+  const out = {
+    _comment: old._comment || 'Wall time of each suite on the Workspace CI runners, in seconds. run-tests.js --shard balances the shards with these numbers. Refresh: download the timings-* artifacts of a green Workspace CI run into one directory, then run `node run-tests.js --merge-timings=DIR`.',
+    measured: new Date().toISOString().slice(0, 10),
+    seconds: sorted,
+  };
+  fs.writeFileSync(TIMINGS_FILE, `${JSON.stringify(out, null, 2)}\n`);
+  console.log(`run-tests: ${n} times merged into test-timings.json (${Object.keys(sorted).length} suites).`);
+}
+
 async function main() {
   if (flag('check')) return check();
+  if (flag('merge-timings')) return mergeTimings(flag('merge-timings'));
   if (fragProblems.length) { for (const p of fragProblems) console.error(`✗ ${p}`); process.exitCode = 2; return; }
   if (!group || !GROUPS[group]) {
     console.error(`usage: node run-tests.js <${Object.keys(GROUPS).join('|')}> [--jobs=N] [--shard=I/N] [--list] [--verbose]\n       node run-tests.js --check`);
@@ -250,6 +285,8 @@ async function main() {
 
   const failed = results.filter((r) => !r.ok);
   const slowest = [...results].sort((a, b) => b.secs - a.secs).slice(0, 5).map((r) => `${r.file} ${r.secs}s`).join(', ');
+  const timingsOut = flag('timings-out');
+  if (timingsOut && timingsOut !== true) fs.writeFileSync(timingsOut, JSON.stringify(Object.fromEntries(results.map((r) => [r.file, r.secs])), null, 2));
   console.log(`\nrun-tests: ${results.length - failed.length}/${results.length} suites passed in ${((Date.now() - t0) / 1000).toFixed(1)}s wall. Slowest: ${slowest}.`);
   // exitCode, never process.exit(): stdout to a pipe is asynchronous, and exiting here cut the CI log
   // off mid-suite, before the summary that names what failed.

package/workspace/test-lists/scan-documents.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "scan-documents: a document repository's initiatives read their stage from the documents and Jira keys the repository holds.",
+  "modules": ["scan-documents.test.js"],
+  "seconds": { "scan-documents.test.js": 5 }
+}

package/workspace/test-timings.json

@@ -0,0 +1,172 @@
+{
+  "_comment": "Wall time of each suite on the Workspace CI runners, in seconds. run-tests.js --shard balances the shards with these numbers. Refresh: download the timings-* artifacts of a green Workspace CI run into one directory, then run `node run-tests.js --merge-timings=DIR`.",
+  "measured": "2026-10-07",
+  "seconds": {
+    "agenda.test.js": 1,
+    "auto-sync.test.js": 2,
+    "board-cli.test.js": 3,
+    "capture.test.js": 1,
+    "claims.test.js": 2,
+    "cuts.test.js": 1,
+    "d86-seams.test.js": 1,
+    "day-run.test.js": 21,
+    "doc-category-corrections.test.js": 1,
+    "doc-category.test.js": 1,
+    "doc-library.test.js": 1,
+    "doc-sync.test.js": 1,
+    "docs-cli.test.js": 5,
+    "external-linking.test.js": 1,
+    "factory-join.test.js": 1,
+    "first-paint-board.test.js": 8,
+    "first-paint-count.test.js": 23,
+    "first-paint-initiatives.test.js": 12,
+    "first-paint-reports.test.js": 8,
+    "first-paint-today.test.js": 26,
+    "fixture-parity.test.mjs": 1,
+    "focus.test.js": 1,
+    "glossary.test.js": 1,
+    "goals.test.js": 1,
+    "grant-mint.test.js": 1,
+    "guide.test.js": 1,
+    "handoff.test.js": 1,
+    "health.test.js": 1,
+    "initiative-cli.test.js": 8,
+    "initiative-needs.test.js": 2,
+    "initiative-surface.test.js": 3,
+    "initiative-writer.test.js": 1,
+    "issues.test.js": 1,
+    "item-cli.test.js": 7,
+    "item-spans.test.js": 1,
+    "jev-categorize.test.js": 1,
+    "jev-claims.test.js": 1,
+    "jev-route.test.js": 1,
+    "jev-status.test.js": 1,
+    "jira-wbs.test.js": 1,
+    "kg.test.js": 2,
+    "kit-update.test.js": 1,
+    "launcher.test.js": 1,
+    "learn.test.js": 4,
+    "live-notes.test.js": 5,
+    "markdown.test.mjs": 1,
+    "measurements.test.js": 1,
+    "next-step-actions.test.js": 11,
+    "no-network.test.js": 1,
+    "notes-listen.test.js": 2,
+    "notes.test.js": 5,
+    "online-mode.test.js": 1,
+    "people.test.js": 2,
+    "phone-access.test.js": 1,
+    "phone-command.test.js": 4,
+    "placements.test.js": 1,
+    "plan-items-stage-parity.test.js": 1,
+    "plan-items.test.js": 1,
+    "plan-routes.test.js": 11,
+    "plan-tree.test.js": 6,
+    "pm-board-dest-phone-test.js": 14,
+    "pm-board-dest-test.js": 27,
+    "pm-breakdown-phone-test.js": 33,
+    "pm-breakdown-test.js": 68,
+    "pm-breakdown-timeline-test.js": 25,
+    "pm-cuts-test.js": 16,
+    "pm-detail-test.js": 18,
+    "pm-doc-category-test.js": 6,
+    "pm-docs-test.js": 37,
+    "pm-frame-phone-test.js": 14,
+    "pm-frame-test.js": 21,
+    "pm-initiatives-dest-phone-test.js": 9,
+    "pm-initiatives-dest-test.js": 28,
+    "pm-initiatives-test.js": 19,
+    "pm-initiatives-timeline-test.js": 39,
+    "pm-jira-test.js": 6,
+    "pm-lines-needs.test.js": 1,
+    "pm-live-notes-test.js": 25,
+    "pm-modes-test.js": 11,
+    "pm-nonce-test.js": 14,
+    "pm-notes-test.js": 40,
+    "pm-palette-test.js": 29,
+    "pm-people-test.js": 12,
+    "pm-r1-test.js": 10,
+    "pm-r10-test.js": 1,
+    "pm-r11-test.js": 2,
+    "pm-r12-test.js": 17,
+    "pm-r13-test.js": 12,
+    "pm-r14-test.js": 7,
+    "pm-r15-test.js": 7,
+    "pm-r16-test.js": 16,
+    "pm-r17-test.js": 7,
+    "pm-r18-test.js": 11,
+    "pm-r19-test.js": 20,
+    "pm-r2-test.js": 7,
+    "pm-r20-test.js": 19,
+    "pm-r21-test.js": 29,
+    "pm-r22-test.js": 2,
+    "pm-r23-test.js": 17,
+    "pm-r24-test.js": 15,
+    "pm-r25-test.js": 1,
+    "pm-r26-test.js": 1,
+    "pm-r27-test.js": 26,
+    "pm-r28-test.js": 1,
+    "pm-r29-filespad-test.js": 1,
+    "pm-r29-knowledge-test.js": 1,
+    "pm-r29-memory-test.js": 1,
+    "pm-r29-newsession-alignment-test.js": 1,
+    "pm-r29-portfolio-test.js": 1,
+    "pm-r29-reports-addrepo-test.js": 1,
+    "pm-r29-skills-scheduled-test.js": 1,
+    "pm-r29-today-test.js": 12,
+    "pm-r29-validate-guide-test.js": 1,
+    "pm-r3-test.js": 11,
+    "pm-r30-test.js": 13,
+    "pm-r4-test.js": 4,
+    "pm-r5-test.js": 6,
+    "pm-r6-test.js": 5,
+    "pm-r7-test.js": 1,
+    "pm-r8-test.js": 1,
+    "pm-r9-test.js": 10,
+    "pm-report-slides-test.js": 6,
+    "pm-reports-phone-test.js": 9,
+    "pm-reports-test.js": 20,
+    "pm-repos-test.js": 10,
+    "pm-seams-test.js": 16,
+    "pm-shell-test.js": 6,
+    "pm-tabs-test.js": 55,
+    "pm-term-test.js": 38,
+    "pm-today-goals-test.js": 30,
+    "pm-today-phone-test.js": 27,
+    "pm-today-test.js": 60,
+    "pm-updates-test.js": 16,
+    "proactive-prepare.test.js": 12,
+    "proactive.test.js": 17,
+    "profiles.test.js": 1,
+    "public-host.test.js": 1,
+    "r25-guards.test.js": 9,
+    "r3-display.test.js": 4,
+    "replaced-tests.test.js": 17,
+    "repo-scan.test.js": 1,
+    "repo-watch.test.js": 1,
+    "report-cli.test.js": 2,
+    "report-draft.test.js": 4,
+    "report-needs.test.js": 1,
+    "report-slides-data.test.js": 1,
+    "routes-board.test.js": 1,
+    "routes-capture.test.js": 1,
+    "routes-initiatives.test.js": 3,
+    "routes-reports.test.js": 1,
+    "routes-timeline.test.js": 1,
+    "routes-today.test.js": 6,
+    "scan-consistency.test.js": 1,
+    "schedule-cli.test.js": 3,
+    "session-flag.test.js": 1,
+    "start-policy.test.js": 1,
+    "state-isolation.test.js": 37,
+    "status-facts-panel.test.js": 1,
+    "story-artifacts.test.js": 1,
+    "sync.test.js": 4,
+    "test.js": 65,
+    "today.test.js": 5,
+    "tracker-refresh.test.js": 1,
+    "typesafe-validation.test.js": 1,
+    "ui-test.js": 43,
+    "work-check-needs.test.js": 1
+  }
+}