create-pmos 0.65.2 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.65.2",
+  "version": "0.66.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@cc06cf0
+kernel-source: pmos@c6198fe
 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:20:37Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T01:43:50Z"}
 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:20:37Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T01:43:50Z"}
 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:20:37Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T01:43:50Z"}
 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/guide/layout.md

@@ -119,7 +119,7 @@ Every row has a visible ⋯ button. Every control is at least 44 pixels high. No
 
 You can have the same session open on your phone and your computer. A session has one size, so the screen you type in or tap last sets it. The other screen keeps showing the session and takes the size back as soon as you type in it.
 
-On an iPhone or an iPad, the terminal gets smaller when the keyboard opens, so the agent's prompt stays above the keyboard. Tapping the terminal does not zoom the page, and dragging at its top or bottom does not pull or reload the page. A swipe from the left edge of the screen is Safari's Back gesture and leaves the workspace. To avoid that, add the workspace to your Home Screen and open it from there.
+On an iPhone or an iPad, the terminal gets smaller when the keyboard opens, so the agent's prompt stays above the keyboard. Tapping the terminal does not zoom the page, and dragging at its top or bottom does not pull or reload the page. Swipe up or down on the terminal to scroll it, also inside Claude Code or any other program that uses the mouse. A swipe from the left edge of the screen is Safari's Back gesture and leaves the workspace. To avoid that, add the workspace to your Home Screen and open it from there.
 
 ## The older layout
 

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.2",
+  "version": "0.66.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.65.2",
+  "version": "0.66.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/public/pm/tab-term.js

@@ -915,9 +915,78 @@ function buildReal(tab) {
     rec.ro = new ResizeObserver(() => refitVisible());
     try { rec.ro.observe(host); } catch { /* ignore */ }
   }
+  touchScroll(rec);
   return rec;
 }
 
+/* ── a swipe scrolls ───────────────────────────────────────────────────────────────────────────
+ * xterm scrolls on a touch drag only while no program has asked for the mouse. A program that has
+ * (Claude Code, tmux, an editor) gets nothing from a swipe, because xterm ignores touch then and a
+ * touch is not a wheel. On an iPhone or iPad a swipe was therefore dead in exactly the sessions
+ * that matter. A vertical drag on the pane is turned into wheel events instead, and xterm does with
+ * them what it does with a mouse wheel: it scrolls its own scrollback, or it reports the wheel to
+ * the program that asked for the mouse, or it sends arrow keys in a full-screen program that did
+ * not. The finger's speed carries on for a moment after it lifts, as a native scroll does. A tap
+ * is left alone, so it still focuses the terminal and raises the keyboard. */
+const TOUCH_SLOP = 6;          // px a finger moves before a touch is a swipe rather than a tap
+const MOMENTUM_DECAY = 0.95;   // the carried speed kept per frame after the finger lifts
+
+function touchScroll(rec) {
+  const { host, term } = rec;
+  let t = null;        // the swipe in progress: { x, y, lastY, lastT, v, swiping }
+  let glide = 0;       // the momentum frame, if one is queued
+
+  const wheel = (dy, x, y) => {
+    const target = (term.element && term.element.querySelector('.xterm-screen')) || term.element;
+    if (!target || !dy) return;
+    target.dispatchEvent(new WheelEvent('wheel', {
+      deltaY: dy, deltaMode: 0, clientX: x, clientY: y, bubbles: true, cancelable: true,
+    }));
+  };
+  const stopGlide = () => { if (glide) { cancelAnimationFrame(glide); glide = 0; } };
+
+  host.addEventListener('touchstart', (e) => {
+    stopGlide();
+    if (e.touches.length !== 1) { t = null; return; }
+    const p = e.touches[0];
+    t = { x: p.clientX, y: p.clientY, lastY: p.clientY, lastT: e.timeStamp, v: 0, swiping: false };
+  }, { capture: true, passive: true });
+
+  host.addEventListener('touchmove', (e) => {
+    if (!t || e.touches.length !== 1) return;
+    const p = e.touches[0];
+    if (!t.swiping) {
+      const dx = p.clientX - t.x, dy = p.clientY - t.y;
+      if (Math.abs(dy) < TOUCH_SLOP || Math.abs(dy) < Math.abs(dx)) return;
+      t.swiping = true;
+    }
+    // Ours from here: xterm's own touch handling and the page's scroll do not also see it.
+    e.preventDefault();
+    e.stopPropagation();
+    const dy = t.lastY - p.clientY;   // finger up = content up = wheel down
+    const dt = Math.max(1, e.timeStamp - t.lastT);
+    t.v = 0.8 * (dy / dt) + 0.2 * t.v;
+    t.lastY = p.clientY; t.lastT = e.timeStamp;
+    wheel(dy, p.clientX, p.clientY);
+  }, { capture: true, passive: false });
+
+  const end = () => {
+    if (!t || !t.swiping) { t = null; return; }
+    let v = t.v * 16;                  // px per frame
+    const x = t.x, y = t.lastY;
+    t = null;
+    const step = () => {
+      v *= MOMENTUM_DECAY;
+      if (Math.abs(v) < 0.5) { glide = 0; return; }
+      wheel(v, x, y);
+      glide = requestAnimationFrame(step);
+    };
+    if (Math.abs(v) >= 0.5) glide = requestAnimationFrame(step);
+  };
+  host.addEventListener('touchend', end, { capture: true, passive: true });
+  host.addEventListener('touchcancel', end, { capture: true, passive: true });
+}
+
 /* ── the exported surface ──────────────────────────────────────────────────────────────────── */
 
 /**

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