create-pmos 0.70.1 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.70.1",
+  "version": "0.71.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@9413354
+kernel-source: pmos@c87956b
 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-07T04:11:36Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T04:24:34Z"}
 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-07T04:11:36Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T04:24:34Z"}
 status: stable
 ---
 

package/payload/scripts/workflow-state.js

@@ -1313,51 +1313,102 @@ function roleOfWords(words, extra) {
   }
   return null;
 }
-/** The role of a found document: its file name, then its frontmatter `type:`, then its folders (S2). */
-function documentRole(rel, type, ids) {
+/** A name as a slug: lower case, every run of other characters one dash. "Checkout Redesign PRD.docx" → "checkout-redesign-prd-docx". */
+const scanSlug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+/**
+ * Does the slug `name` carry the key? Equal, or the key leads it ("checkout-prd"). A key of two words or more, or of
+ * six characters or more, may also stand anywhere between dashes ("prd-checkout-redesign-v2"): a short one-word key
+ * such as "app" would otherwise claim every file with that word in it.
+ */
+function slugHasKey(name, key) {
+  if (!name || !key) return false;
+  if (name === key || name.startsWith(key + '-')) return true;
+  if (!key.includes('-') && key.length < 6) return false;
+  return name.endsWith('-' + key) || name.includes('-' + key + '-');
+}
+/**
+ * The initiatives a document belongs to (S1): its frontmatter names them; else the record whose key — its id, or its
+ * title as a slug — is a folder in the path, leads or stands in the file name, or stands in the document's own title.
+ * The longest key wins, so "checkout-redesign" takes a file that "checkout" would also match.
+ */
+function documentOwners(rel, fm, idSet, keys) {
+  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 { ids: [...new Set(named)], key: null };
+  const parts = rel.split('/');
+  const base = scanSlug(parts[parts.length - 1].replace(/\.[^.]+$/, ''));
+  const dirs = parts.slice(0, -1).map(scanSlug);
+  const title = scanSlug(fm.title);
+  for (const { id, key } of keys) {
+    if (dirs.includes(key) || slugHasKey(base, key) || slugHasKey(title, key)) return { ids: [id], key };
+  }
+  return { ids: [], key: null };
+}
+/** The role of a found document (S2): its file name, then its frontmatter `type:`, then its folders. */
+function documentRole(rel, type, key) {
   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;
+  // The initiative's own name is not a role word: "problem-reporting-prd" is the PRD of the initiative problem-reporting.
+  const strip = (s) => { const slug = scanSlug(s); return key ? slug.split(key).join('-') : slug; };
   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];
+/** Every record: its id and the keys a document may carry — the id, and the title as a slug when it is not too short. */
+function recordKeys(L) {
+  let files = [];
+  try { files = fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)); }
+  catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const id = f.slice(0, -3);
+    const fm = readFrontmatter(path.join(L.initiatives, f)) || {};
+    const keys = new Set([scanSlug(id)]);
+    const t = scanSlug(fm.title);
+    if (t && (t.includes('-') || t.length >= 6)) keys.add(t);
+    for (const key of keys) if (key.length >= 3) out.push({ id, key });
   }
-  return [];
+  return out.sort((a, b) => b.key.length - a.key.length);
 }
-/** 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 []; }
+/** The repository's files: git's list (tracked, and untracked but not ignored); a walk of the folder when it is not a git repository. */
+function scanFiles(root) {
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  if (out != null) return [...new Set(out.split('\0').filter(Boolean))].slice(0, SCAN_MAX_FILES);
+  const files = [];
+  const walk = (dir, rel) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (files.length >= SCAN_MAX_FILES) return;
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.isFile()) files.push(r);
+    }
+  };
+  walk(root, '');
+  return files;
+}
+/** Where the tidy (S10) moves a duplicate, repository-relative: `<state>/archive/duplicates/`. The scan does not read it. */
+function duplicatesArchive(root, L) {
+  return path.relative(root, path.join(path.dirname(L.initiatives), 'archive', 'duplicates')).split(path.sep).join('/') + '/';
 }
-function scanRepository(root, ids, L) {
+function scanRepository(root, L) { return scanDetail(root, L).index; }
+/** The scan's index, and how many initiatives each found document belongs to (`owners`, for the tidy). */
+function scanDetail(root, L) {
   const key = path.resolve(root);
   const hit = _scanCache.get(key);
-  if (hit && Date.now() - hit.at < SCAN_TTL_MS && ids.every((id) => hit.ids.has(id))) return hit.index;
+  if (hit && Date.now() - hit.at < SCAN_TTL_MS) return hit;
   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 owners = new Map();
+  const keys = recordKeys(L);
+  const idSet = new Set(keys.map((k) => k.id));
   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;
+  const archDir = duplicatesArchive(root, L);
+  for (const rel of scanFiles(root)) {
+    if (!SCAN_EXT.test(rel) || rel.startsWith(recDir) || rel.startsWith(archDir) || /(^|\/)(node_modules|\.git)\//.test(rel)) continue;
     let fm = {};
     if (SCAN_TEXT.test(rel)) {
       try {
@@ -1368,21 +1419,67 @@ function scanRepository(root, ids, L) {
         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);
+    const owner = documentOwners(rel, fm, idSet, keys);
+    if (!owner.ids.length) continue;
+    const role = documentRole(rel, fm.type, owner.key);
     if (!role) continue;
-    for (const id of owners) {
+    // git's index still lists a tracked file that was moved or deleted and not yet staged
+    if (!SCAN_TEXT.test(rel) && !fs.existsSync(path.join(root, rel))) continue;
+    owners.set(rel, owner.ids.length);
+    for (const id of owner.ids) {
       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;
+  const out = { at: Date.now(), index, owners };
+  _scanCache.set(key, out);
+  return out;
+}
+/** When a document last changed, in seconds: its last commit, else the file's own time. */
+function documentChangedAt(root, rel) {
+  const t = Number(String(git(root, ['log', '-1', '--format=%ct', '--', rel]) || '').trim());
+  if (t > 0) return t;
+  try { return Math.floor(fs.statSync(path.join(root, rel)).mtimeMs / 1000); } catch { return 0; }
+}
+/**
+ * The duplicates the tidy offers (S10): for each initiative, each role with more than one document. The group keeps the
+ * file the record names, else the most recently changed, else the shortest path. A document that belongs to more than one
+ * initiative is listed as `shared` and is never one to move. Only a pm-artifacts repository has groups. Nothing is written.
+ *   { ok, profile, archive, groups: [{ id, title, role, keep, files: [{ path, changed }], shared: [path] }] }
+ */
+function documentDuplicates(root, opts) {
+  const L = layout(root);
+  const profile = profileOf(root);
+  const archive = duplicatesArchive(root, L);
+  if (profile !== 'pm-artifacts') return { ok: true, profile, archive, groups: [] };
+  if (opts && opts.fresh) forgetDocumentScan(root);
+  const { index, owners } = scanDetail(root, L);
+  const norm = (p) => { const v = String(p || '').trim(); return v ? path.relative(root, path.resolve(root, v)).split(path.sep).join('/') : ''; };
+  const groups = [];
+  for (const [id, roles] of [...index].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const fm = readFrontmatter(path.join(L.initiatives, `${id}.md`)) || {};
+    const named = { brief: norm(fm.brief_path || fm.prd_path), draft: norm(fm.doc_path) };
+    for (const role of ['brief', 'draft', 'review', 'handoff']) {
+      const own = roles[role].filter((f) => (owners.get(f) || 0) <= 1);
+      const shared = roles[role].filter((f) => (owners.get(f) || 0) > 1);
+      const pin = named[role] && fs.existsSync(path.join(root, named[role])) ? named[role] : '';
+      if (pin && !own.includes(pin) && !shared.includes(pin)) own.push(pin);
+      if (own.length < 2) continue;
+      const files = own.map((f) => ({ path: f, changed: documentChangedAt(root, f) }));
+      files.sort((a, b) => (b.path === pin) - (a.path === pin) || b.changed - a.changed
+        || a.path.length - b.path.length || a.path.localeCompare(b.path));
+      groups.push({ id, title: fm.title || id, role, keep: files[0].path, files, shared, named: !!pin && files[0].path === pin });
+    }
+  }
+  return { ok: true, profile, archive, groups };
 }
-/** 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) {
+/**
+ * Jira keys the repository holds for an initiative (S4): the Jira tab's draft; the record's `jira:` keys; in the
+ * record's text, a Jira link (`…/browse/KEY`) or a key on a line that says Jira; and a Jira link in its found
+ * documents. A bare key elsewhere is not read: "UTF-8" and "ISO-8601" have the same shape.
+ */
+function jiraKeysOf(root, L, id, fm, found) {
   const keys = [];
   const draft = path.join(path.dirname(L.initiatives), 'tracker', 'jira', `${id}-tickets.md`);
   try {
@@ -1394,6 +1491,18 @@ function jiraKeysOf(root, L, id, fm) {
   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]);
   }
+  const fromText = (text, lines) => {
+    for (const m of String(text).matchAll(/\/browse\/([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    if (lines) for (const line of String(text).split('\n')) {
+      if (!/jira/i.test(line)) continue;
+      for (const m of line.matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    }
+  };
+  try { fromText(fs.readFileSync(path.join(L.initiatives, `${id}.md`), 'utf8'), true); } catch { /* no record text */ }
+  for (const rel of found ? [].concat(found.brief, found.draft, found.review, found.handoff) : []) {
+    if (!SCAN_TEXT.test(rel)) continue;
+    try { fromText(fs.readFileSync(path.join(root, rel), 'utf8').slice(0, 200000), false); } catch { /* unreadable */ }
+  }
   return [...new Set(keys)];
 }
 
@@ -1433,7 +1542,7 @@ 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 found = (opts && opts.scan === false) ? null : (scanRepository(root, 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();
@@ -1492,7 +1601,7 @@ 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);
+    const keys = to ? [] : jiraKeysOf(root, L, id, fm, found);
     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`)
@@ -1811,7 +1920,7 @@ module.exports = {
   historyRange,
   ENFORCED_FROM,
   lanesFor, laneNames,
-  forgetDocumentScan,
+  forgetDocumentScan, documentDuplicates,
 };
 
 /*

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-07T04:11:36Z"}
+generated: {by: process:create-pmos, at: "2026-10-07T04:24:34Z"}
 status: stable
 ---
 

package/workspace/fixtures/initiatives-api/roadmap.json

@@ -217,5 +217,10 @@
         }
       ]
     }
-  ]
+  ],
+  "scan": {
+    "initiatives": 6,
+    "with_documents": 0,
+    "profile": "product-code"
+  }
 }

package/workspace/guide/initiatives-screen.md

@@ -15,15 +15,15 @@ Press **Roadmap** or **List** at the top to change the view. The workspace keeps
 
 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, 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.
+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. Documents or Jira keys found for 30 of them." When it found nothing for any initiative, the toast says so. Then the view updates. The scan writes nothing, except the tidy you confirm (below). 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:
+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 folder that is not a git repository is read the same way. Each initiative has two names the scan looks for: its id (the record's file name) and its title. Spaces, capitals, underscores and punctuation do not matter, so the title "Guest Checkout" matches `guest-checkout`, `Guest Checkout` and `guest_checkout`. 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.
+- a folder in its path has the initiative's name, for example `Product/Guest Checkout/PRD.md`, or
+- its file name or its own `title:` carries the initiative's name, for example `PRD - Guest Checkout v2.md`. A one-word name shorter than six letters must start the file name. When two initiatives match, the longer name wins.
 
 The file name, then the `type:` in the frontmatter, then the folder names give the document its role:
 
@@ -34,7 +34,19 @@ The file name, then the `type:` in the frontmatter, then the folder names give t
 | 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.
+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, a `jira:`, `jira_key:` or `jira_epic:` key in the record, a Jira link or a line that says Jira in the record, and a Jira link in one of its documents. 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.
+
+### Tidy duplicate documents
+
+An initiative has one document of each kind: one brief, one PRD, one evaluation and one handoff. When a document repository holds more than one of a kind for an initiative, for example `checkout-prd.md` and `checkout-prd-v2.md`, **Scan repository** first opens the **Tidy duplicate documents** sheet. It lists each group and selects the document to keep:
+
+1. the file the record names (`doc_path:` or `brief_path:`), else
+2. the most recently changed file (its last git commit, else the file's own time), else
+3. the shortest path.
+
+Select another file to keep a different one. Clear a group's check box to leave that group as it is. Then press **Archive N and scan**. Every other document of each checked group moves to `pmos/state/archive/duplicates/`, under its original path. Nothing is deleted. A file that git tracks moves with `git mv`, so it shows as a rename when you next commit. Each move is one line in `moves.jsonl` in the same folder, so you can move a file back by hand. A document that belongs to more than one initiative never moves. The scan does not read the archive. The scan then runs, and its toast starts with how many documents were archived.
+
+Press **Scan without tidying** to scan with every document in place. Press **Cancel** or Escape to do neither. The tidy writes no initiative record.
 
 ## The Roadmap
 

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

@@ -1313,51 +1313,102 @@ function roleOfWords(words, extra) {
   }
   return null;
 }
-/** The role of a found document: its file name, then its frontmatter `type:`, then its folders (S2). */
-function documentRole(rel, type, ids) {
+/** A name as a slug: lower case, every run of other characters one dash. "Checkout Redesign PRD.docx" → "checkout-redesign-prd-docx". */
+const scanSlug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+/**
+ * Does the slug `name` carry the key? Equal, or the key leads it ("checkout-prd"). A key of two words or more, or of
+ * six characters or more, may also stand anywhere between dashes ("prd-checkout-redesign-v2"): a short one-word key
+ * such as "app" would otherwise claim every file with that word in it.
+ */
+function slugHasKey(name, key) {
+  if (!name || !key) return false;
+  if (name === key || name.startsWith(key + '-')) return true;
+  if (!key.includes('-') && key.length < 6) return false;
+  return name.endsWith('-' + key) || name.includes('-' + key + '-');
+}
+/**
+ * The initiatives a document belongs to (S1): its frontmatter names them; else the record whose key — its id, or its
+ * title as a slug — is a folder in the path, leads or stands in the file name, or stands in the document's own title.
+ * The longest key wins, so "checkout-redesign" takes a file that "checkout" would also match.
+ */
+function documentOwners(rel, fm, idSet, keys) {
+  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 { ids: [...new Set(named)], key: null };
+  const parts = rel.split('/');
+  const base = scanSlug(parts[parts.length - 1].replace(/\.[^.]+$/, ''));
+  const dirs = parts.slice(0, -1).map(scanSlug);
+  const title = scanSlug(fm.title);
+  for (const { id, key } of keys) {
+    if (dirs.includes(key) || slugHasKey(base, key) || slugHasKey(title, key)) return { ids: [id], key };
+  }
+  return { ids: [], key: null };
+}
+/** The role of a found document (S2): its file name, then its frontmatter `type:`, then its folders. */
+function documentRole(rel, type, key) {
   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;
+  // The initiative's own name is not a role word: "problem-reporting-prd" is the PRD of the initiative problem-reporting.
+  const strip = (s) => { const slug = scanSlug(s); return key ? slug.split(key).join('-') : slug; };
   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];
+/** Every record: its id and the keys a document may carry — the id, and the title as a slug when it is not too short. */
+function recordKeys(L) {
+  let files = [];
+  try { files = fs.readdirSync(L.initiatives).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)); }
+  catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const id = f.slice(0, -3);
+    const fm = readFrontmatter(path.join(L.initiatives, f)) || {};
+    const keys = new Set([scanSlug(id)]);
+    const t = scanSlug(fm.title);
+    if (t && (t.includes('-') || t.length >= 6)) keys.add(t);
+    for (const key of keys) if (key.length >= 3) out.push({ id, key });
   }
-  return [];
+  return out.sort((a, b) => b.key.length - a.key.length);
 }
-/** 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 []; }
+/** The repository's files: git's list (tracked, and untracked but not ignored); a walk of the folder when it is not a git repository. */
+function scanFiles(root) {
+  const out = git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  if (out != null) return [...new Set(out.split('\0').filter(Boolean))].slice(0, SCAN_MAX_FILES);
+  const files = [];
+  const walk = (dir, rel) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (files.length >= SCAN_MAX_FILES) return;
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.isFile()) files.push(r);
+    }
+  };
+  walk(root, '');
+  return files;
+}
+/** Where the tidy (S10) moves a duplicate, repository-relative: `<state>/archive/duplicates/`. The scan does not read it. */
+function duplicatesArchive(root, L) {
+  return path.relative(root, path.join(path.dirname(L.initiatives), 'archive', 'duplicates')).split(path.sep).join('/') + '/';
 }
-function scanRepository(root, ids, L) {
+function scanRepository(root, L) { return scanDetail(root, L).index; }
+/** The scan's index, and how many initiatives each found document belongs to (`owners`, for the tidy). */
+function scanDetail(root, L) {
   const key = path.resolve(root);
   const hit = _scanCache.get(key);
-  if (hit && Date.now() - hit.at < SCAN_TTL_MS && ids.every((id) => hit.ids.has(id))) return hit.index;
+  if (hit && Date.now() - hit.at < SCAN_TTL_MS) return hit;
   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 owners = new Map();
+  const keys = recordKeys(L);
+  const idSet = new Set(keys.map((k) => k.id));
   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;
+  const archDir = duplicatesArchive(root, L);
+  for (const rel of scanFiles(root)) {
+    if (!SCAN_EXT.test(rel) || rel.startsWith(recDir) || rel.startsWith(archDir) || /(^|\/)(node_modules|\.git)\//.test(rel)) continue;
     let fm = {};
     if (SCAN_TEXT.test(rel)) {
       try {
@@ -1368,21 +1419,67 @@ function scanRepository(root, ids, L) {
         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);
+    const owner = documentOwners(rel, fm, idSet, keys);
+    if (!owner.ids.length) continue;
+    const role = documentRole(rel, fm.type, owner.key);
     if (!role) continue;
-    for (const id of owners) {
+    // git's index still lists a tracked file that was moved or deleted and not yet staged
+    if (!SCAN_TEXT.test(rel) && !fs.existsSync(path.join(root, rel))) continue;
+    owners.set(rel, owner.ids.length);
+    for (const id of owner.ids) {
       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;
+  const out = { at: Date.now(), index, owners };
+  _scanCache.set(key, out);
+  return out;
+}
+/** When a document last changed, in seconds: its last commit, else the file's own time. */
+function documentChangedAt(root, rel) {
+  const t = Number(String(git(root, ['log', '-1', '--format=%ct', '--', rel]) || '').trim());
+  if (t > 0) return t;
+  try { return Math.floor(fs.statSync(path.join(root, rel)).mtimeMs / 1000); } catch { return 0; }
+}
+/**
+ * The duplicates the tidy offers (S10): for each initiative, each role with more than one document. The group keeps the
+ * file the record names, else the most recently changed, else the shortest path. A document that belongs to more than one
+ * initiative is listed as `shared` and is never one to move. Only a pm-artifacts repository has groups. Nothing is written.
+ *   { ok, profile, archive, groups: [{ id, title, role, keep, files: [{ path, changed }], shared: [path] }] }
+ */
+function documentDuplicates(root, opts) {
+  const L = layout(root);
+  const profile = profileOf(root);
+  const archive = duplicatesArchive(root, L);
+  if (profile !== 'pm-artifacts') return { ok: true, profile, archive, groups: [] };
+  if (opts && opts.fresh) forgetDocumentScan(root);
+  const { index, owners } = scanDetail(root, L);
+  const norm = (p) => { const v = String(p || '').trim(); return v ? path.relative(root, path.resolve(root, v)).split(path.sep).join('/') : ''; };
+  const groups = [];
+  for (const [id, roles] of [...index].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const fm = readFrontmatter(path.join(L.initiatives, `${id}.md`)) || {};
+    const named = { brief: norm(fm.brief_path || fm.prd_path), draft: norm(fm.doc_path) };
+    for (const role of ['brief', 'draft', 'review', 'handoff']) {
+      const own = roles[role].filter((f) => (owners.get(f) || 0) <= 1);
+      const shared = roles[role].filter((f) => (owners.get(f) || 0) > 1);
+      const pin = named[role] && fs.existsSync(path.join(root, named[role])) ? named[role] : '';
+      if (pin && !own.includes(pin) && !shared.includes(pin)) own.push(pin);
+      if (own.length < 2) continue;
+      const files = own.map((f) => ({ path: f, changed: documentChangedAt(root, f) }));
+      files.sort((a, b) => (b.path === pin) - (a.path === pin) || b.changed - a.changed
+        || a.path.length - b.path.length || a.path.localeCompare(b.path));
+      groups.push({ id, title: fm.title || id, role, keep: files[0].path, files, shared, named: !!pin && files[0].path === pin });
+    }
+  }
+  return { ok: true, profile, archive, groups };
 }
-/** 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) {
+/**
+ * Jira keys the repository holds for an initiative (S4): the Jira tab's draft; the record's `jira:` keys; in the
+ * record's text, a Jira link (`…/browse/KEY`) or a key on a line that says Jira; and a Jira link in its found
+ * documents. A bare key elsewhere is not read: "UTF-8" and "ISO-8601" have the same shape.
+ */
+function jiraKeysOf(root, L, id, fm, found) {
   const keys = [];
   const draft = path.join(path.dirname(L.initiatives), 'tracker', 'jira', `${id}-tickets.md`);
   try {
@@ -1394,6 +1491,18 @@ function jiraKeysOf(root, L, id, fm) {
   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]);
   }
+  const fromText = (text, lines) => {
+    for (const m of String(text).matchAll(/\/browse\/([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    if (lines) for (const line of String(text).split('\n')) {
+      if (!/jira/i.test(line)) continue;
+      for (const m of line.matchAll(/\b([A-Z][A-Z0-9_]+-\d+)\b/g)) keys.push(m[1]);
+    }
+  };
+  try { fromText(fs.readFileSync(path.join(L.initiatives, `${id}.md`), 'utf8'), true); } catch { /* no record text */ }
+  for (const rel of found ? [].concat(found.brief, found.draft, found.review, found.handoff) : []) {
+    if (!SCAN_TEXT.test(rel)) continue;
+    try { fromText(fs.readFileSync(path.join(root, rel), 'utf8').slice(0, 200000), false); } catch { /* unreadable */ }
+  }
   return [...new Set(keys)];
 }
 
@@ -1433,7 +1542,7 @@ 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 found = (opts && opts.scan === false) ? null : (scanRepository(root, 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();
@@ -1492,7 +1601,7 @@ 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);
+    const keys = to ? [] : jiraKeysOf(root, L, id, fm, found);
     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`)
@@ -1811,7 +1920,7 @@ module.exports = {
   historyRange,
   ENFORCED_FROM,
   lanesFor, laneNames,
-  forgetDocumentScan,
+  forgetDocumentScan, documentDuplicates,
 };
 
 /*

package/workspace/lib/routes-initiatives.js

@@ -9,6 +9,10 @@
  *                                                    → { ok, id, path, written, sig }   New initiative (requirePagePress)
  *   POST /api/initiatives/rescan { ws }          → { ok, started, running }   read the repository again now (requirePagePress);
  *                                                    nothing is written: the cached rows go stale and one derivation starts
+ *   POST /api/initiatives/duplicates { ws }      → { ok, profile, archive, groups }   documents that share an initiative and a
+ *                                                    role (scan-documents S10; requirePagePress; nothing is written)
+ *   POST /api/initiatives/tidy { ws, keep: [{ id, role, keep }] } → { ok, archive, moved, skipped }   move every other
+ *                                                    document of each named group to the archive (lib/tidy-documents.js)
  *   POST /api/placements     { ws, events: [placed | created | adopted | dropped] }
  *                                                    → { ok, written, sig }   fixtures/initiatives-api/post-ok.json
  *   POST /api/measurements   { ws, events: [measured] } → { ok, written, sig }
@@ -46,6 +50,7 @@ const breakdownExport = require('./breakdown-export.js');
 const consoleState = require('./console-state');
 const initiativeFiles = require('./initiative-files');
 const jiraTickets = require('./jira-tickets.js');
+const tidy = require('./tidy-documents.js');
 
 const HORIZON_RANK = { now: 0, next: 1, later: 2 };
 const FILE_KEYS = [['brief_path', 'brief', 'Brief'], ['prd_path', 'prd', 'PRD'], ['rubric_path', 'rubric', 'Rubric'], ['doc_path', 'doc', 'Document']];
@@ -190,9 +195,23 @@ function roadmapOf(w, F) {
     dormant,
     proposals: F.placed.proposals.map((p) => ({ eid: p.eid, initiative: p.init, title: title(p.init), horizon: p.horizon, after: p.after, by: actorLib.pageName(p.by), at: p.at })),
     flags: flagsOf(F),
+    scan: scanSummary(F),
   };
 }
 
+/**
+ * What the document scan found across the repository (scan-documents S7): how many initiatives it read, how many it
+ * found a document or a Jira key for, and the repository's profile — the scan reads documents in a `pm-artifacts`
+ * repository only, and the Scan repository toast says so instead of a bare "None moved".
+ */
+function scanSummary(F) {
+  const recs = [...F.byId.values()];
+  const hasAny = (f) => !!f && ['brief', 'draft', 'review', 'handoff'].some((k) => Array.isArray(f[k]) && f[k].length);
+  const handedToJira = (r) => Array.isArray(r.steps) && r.steps.some((s) => s.key === 'handoff' && s.status === 'done');
+  const profile = recs.find((r) => r.profile) ? recs.find((r) => r.profile).profile : null;
+  return { initiatives: recs.length, with_documents: recs.filter((r) => hasAny(r.found) || handedToJira(r)).length, profile };
+}
+
 /**
  * The units the library groups as an initiative (a PRD, a rubric, a prototype folder) with no record behind them. The
  * panel lists them under "no record"; without this the Roadmap and the List hid them, so a PRD-only initiative was
@@ -540,6 +559,20 @@ async function handle(req, res, url, ctx) {
     ctx.json(res, { ok: true, ws: w.id, started: r.started, running: r.running });
     return true;
   }
+  // Tidy duplicates before a scan (scan-documents S10). The list is a POST so its path cannot be read as an initiative id.
+  if (p === '/api/initiatives/duplicates' || p === '/api/initiatives/tidy') {
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) return answer(ctx, res, g), true;
+    const loaded = consoleState.loadEngine();
+    if (!loaded.ok) { ctx.json(res, { ok: false, status: 500, error: 'the workflow engine could not be loaded' }, 500); return true; }
+    const r = p === '/api/initiatives/duplicates'
+      ? tidy.preview(loaded.engine, w.root)
+      : tidy.apply(loaded.engine, w.root, body.keep, { actor: actorLib.fromUi() });
+    if (!r.ok) { ctx.json(res, { ok: false, status: r.status || 500, error: r.error }, r.status || 500); return true; }
+    // the page scans next (POST /rescan), which drops the cached rows; dropping them here would lose the answer before the tidy
+    ctx.json(res, { ws: w.id, ...r });
+    return true;
+  }
   if (p === '/api/initiatives') {
     const g = guard.requirePagePress(req, body);
     if (!g.ok) return answer(ctx, res, g), true;

package/workspace/lib/tidy-documents.js

@@ -0,0 +1,86 @@
+'use strict';
+/* tidy-documents.js — move duplicate documents out of the way before a scan (scan-documents S10).
+ *
+ *   preview(engine, root)                         → { ok, profile, archive, groups }   the engine's documentDuplicates, fresh
+ *   apply(engine, root, keep, { actor, now })     → { ok, moved: [{ from, to, id, role }], skipped: [{ id, role, why }] }
+ *                                                   | { ok: false, status, error }
+ *
+ * `keep` is [{ id, role, keep }]: one entry for each group the PM tidies, naming the document to keep. A group that is
+ * not named stays as it is. The server reads the duplicates again and moves only files its own fresh list holds, so a
+ * page cannot name a file to move. Every other document of a named group moves to `<state>/archive/duplicates/` under
+ * its original path, with `git mv` when git tracks it (the move shows as a rename) and a plain rename otherwise.
+ * Nothing is deleted and no record is written. Each move is one line in `<archive>/moves.jsonl`.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROLES = ['brief', 'draft', 'review', 'handoff'];
+const MAX_GROUPS = 500;
+
+function preview(engine, root) {
+  if (!engine || typeof engine.documentDuplicates !== 'function') return { ok: false, status: 501, error: 'this workspace engine cannot list duplicates; update the kit' };
+  return engine.documentDuplicates(root, { fresh: true });
+}
+
+/** A free path under the archive for `rel`: the same path, or `name.2.ext`, `name.3.ext`, … when one is already there. */
+function freeTarget(root, archive, rel) {
+  const base = archive + rel;
+  if (!fs.existsSync(path.join(root, base))) return base;
+  const ext = path.posix.extname(base);
+  const stem = base.slice(0, base.length - ext.length);
+  for (let n = 2; n < 1000; n++) {
+    const t = `${stem}.${n}${ext}`;
+    if (!fs.existsSync(path.join(root, t))) return t;
+  }
+  return null;
+}
+
+function tracked(root, rel) {
+  try { execFileSync('git', ['-C', root, 'ls-files', '--error-unmatch', '--', rel], { stdio: 'ignore' }); return true; } catch { return false; }
+}
+
+function move(root, from, to) {
+  fs.mkdirSync(path.dirname(path.join(root, to)), { recursive: true });
+  if (tracked(root, from)) {
+    try { execFileSync('git', ['-C', root, 'mv', '--', from, to], { stdio: 'ignore' }); return; } catch { /* fall back to a rename */ }
+  }
+  fs.renameSync(path.join(root, from), path.join(root, to));
+}
+
+function apply(engine, root, keep, { actor, now } = {}) {
+  if (!Array.isArray(keep) || !keep.length) return { ok: false, status: 400, error: 'send { keep: [{ id, role, keep }] } for at least one group' };
+  if (keep.length > MAX_GROUPS) return { ok: false, status: 400, error: `at most ${MAX_GROUPS} groups at once` };
+  for (const k of keep) {
+    if (!k || typeof k.id !== 'string' || !ROLES.includes(k.role) || typeof k.keep !== 'string') {
+      return { ok: false, status: 400, error: 'each entry is { id, role, keep } with role one of ' + ROLES.join(', ') };
+    }
+  }
+  const p = preview(engine, root);
+  if (!p.ok) return p;
+  const at = (now || new Date()).toISOString();
+  const by = (actor && actor.by) || 'pm:unknown';
+  const moved = [];
+  const skipped = [];
+  for (const k of keep) {
+    const g = p.groups.find((x) => x.id === k.id && x.role === k.role);
+    if (!g) { skipped.push({ id: k.id, role: k.role, why: 'no longer has duplicates' }); continue; }
+    if (!g.files.some((f) => f.path === k.keep)) { skipped.push({ id: k.id, role: k.role, why: `${k.keep} is not one of its documents` }); continue; }
+    for (const f of g.files) {
+      if (f.path === k.keep) continue;
+      const to = freeTarget(root, p.archive, f.path);
+      if (!to) { skipped.push({ id: k.id, role: k.role, why: `no free place in the archive for ${f.path}` }); continue; }
+      try { move(root, f.path, to); } catch (e) { skipped.push({ id: k.id, role: k.role, why: `${f.path} could not be moved: ${String((e && e.message) || e).slice(0, 120)}` }); continue; }
+      moved.push({ from: f.path, to, id: k.id, role: k.role });
+    }
+  }
+  if (moved.length) {
+    const log = path.join(root, p.archive, 'moves.jsonl');
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    fs.appendFileSync(log, moved.map((m) => JSON.stringify({ ev: 'archived', from: m.from, to: m.to, initiative: m.id, role: m.role, at, by })).join('\n') + '\n');
+    if (engine.forgetDocumentScan) engine.forgetDocumentScan(root);
+  }
+  return { ok: true, archive: p.archive, moved, skipped };
+}
+
+module.exports = { preview, apply, ROLES };

package/workspace/package-lock.json

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

package/workspace/package.json

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

package/workspace/public/pm/components.css

@@ -1570,6 +1570,65 @@
   color: var(--destructive);
 }
 
+/* the tidy sheet (scan-documents S10): one group per initiative and kind of document */
+.in-tidy {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.in-tidy__group {
+  margin: 0;
+  padding: 8px 12px;
+  border: 1px solid var(--border);
+  min-width: 0;
+}
+.in-tidy__head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+  color: var(--foreground);
+}
+.in-tidy__file {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 4px 0 4px 24px;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--foreground);
+  overflow-wrap: anywhere;
+}
+.in-tidy__file input {
+  margin-top: 2px;
+  flex: none;
+}
+.in-tidy__file input:focus-visible,
+.in-tidy__head input:focus-visible {
+  outline: 2px solid color-mix(in oklab, var(--ring) 50%, var(--foreground));
+  outline-offset: 2px;
+}
+@media (pointer: coarse) {
+  .in-tidy__file input,
+  .in-tidy__head input {
+    min-height: 44px;
+    min-width: 44px;
+    margin-top: 0;
+  }
+  .in-tidy__file {
+    min-height: 48px;
+    align-items: center;
+  }
+}
+.in-tidy__path {
+  font-family: var(--mono);
+}
+.in-tidy__group[data-off] .in-tidy__file {
+  color: var(--muted-foreground);
+}
+
 /* the Roadmap */
 .in-roadmap {
   display: flex;

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

@@ -11,6 +11,8 @@
  *   POST /api/placements       { ws, events: [placed…] }       every move, reorder and check-by
  *   POST /api/initiatives      { ws, title, lane, anchor, intent?, from? }   the New-initiative form and a triage card (one body, no events)
  *   POST /api/initiatives/rescan { ws }                     the Re-scan press: read the repository again now (nothing is written)
+ *   POST /api/initiatives/duplicates { ws }                 documents that share an initiative and a role (S10; nothing is written)
+ *   POST /api/initiatives/tidy { ws, keep }                 move every other document of each kept group to the archive (S10)
  *
  * Every GET of /api/initiatives answers 202 { ok: false, pending: true } until the repository's first derivation lands (2C,
  * about 260 ms a record); a read waits and asks again, so a caller sees the answer or a real error, never the 202.
@@ -50,21 +52,31 @@ export const drop = (ws, proposal) => pmPost('/api/placements', { ws, events: [{
 /** A new initiative: from the form, or from a triaged capture (`from` is the capture's id). It lands in Later. */
 /** 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) {
+export async function rescan(ws, opts) {
   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();
+  // a step between that answer and the scan: the tidy (S10), so its moves count as the scan's
+  let tidied = null;
+  if (opts && typeof opts.first === 'function') {
+    tidied = await opts.first();
+    if (!tidied || !tidied.ok) return tidied || { ok: false, error: 'no answer' };
+  }
   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 roadmap();
     const rec = r && r.sig ? String(r.sig.records || '') : '';
-    if (r && r.ok && rec && !rec.endsWith('~stale')) return { ok: true, before: before && before.ok ? before : null, after: r };
+    if (r && r.ok && rec && !rec.endsWith('~stale')) return { ok: true, before: before && before.ok ? before : null, after: r, tidied };
   }
-  return { ok: true, slow: true };
+  return { ok: true, slow: true, tidied };
 }
 
+/** The duplicates a tidy offers (S10), and the tidy itself: `keep` is [{ id, role, keep }] for each group to tidy. */
+export const duplicates = (ws) => pmPost('/api/initiatives/duplicates', { ws });
+export const tidy = (ws, keep) => pmPost('/api/initiatives/tidy', { ws, keep });
+
 export const createInitiative = (ws, fields) => pmPost('/api/initiatives', { ws, ...fields });
 
 export const setLifecycle = (ws, id, state, reason) => pmPost('/api/lifecycle', { ws, initiative_id: id, state, reason: reason || '' });

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

@@ -32,12 +32,30 @@ export const COPY = {
   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) => {
+  // `scan` is the roadmap's summary ({ initiatives, with_documents, profile }): it says why nothing moved.
+  rescanResult: (checked, moves, scan) => {
     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(', ')}.`;
+    const body = n ? `${n} moved: ${moves.map((m) => `${m.count} to ${m.label}`).join(', ')}.` : 'None moved.';
+    if (!scan) return `${head} ${body}`;
+    if (scan.profile && scan.profile !== 'pm-artifacts') return `${head} ${body} This repository is set up for code, so the scan reads builds, not documents.`;
+    const w = scan.with_documents || 0;
+    if (!w) return `${head} ${body} No document or Jira key matched an initiative. The guide says how files are matched.`;
+    return `${head} ${body} Documents or Jira keys found for ${w} of them.`;
   },
+  // the tidy before a scan (scan-documents S10)
+  tidyTitle: 'Tidy duplicate documents',
+  tidyBody: (groups, inits, archive) => `${inits} ${inits === 1 ? 'initiative has' : 'initiatives have'} more than one document of one kind (${groups} ${groups === 1 ? 'group' : 'groups'}). Pick the document to keep in each group. The others move to ${archive}. Nothing is deleted, and the move is logged there.`,
+  tidyRole: { brief: 'Brief', draft: 'PRD or draft', review: 'Evaluation', handoff: 'Handoff' },
+  tidyGroupToggle: 'Tidy this group',
+  tidyNamed: 'named in the record',
+  tidyShared: (p) => `${p} also belongs to another initiative and stays`,
+  tidyChanged: (d) => `changed ${d}`,
+  tidyConfirm: (n) => `Archive ${n} and scan`,
+  tidySkip: 'Scan without tidying',
+  tidyNone: 'Nothing to archive: every group is off.',
+  tidyArchived: (n) => `Archived ${n} duplicate ${n === 1 ? 'document' : 'documents'}.`,
+  tidyFailed: (why) => `Could not tidy: ${why}`,
   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.',

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

@@ -6,14 +6,16 @@
  *   confirmSheet({…})               a sheet that asks for one press (a PM-only act): an optional choice, a reason, Cancel, Confirm
  *   checkBySheet({…})               a sheet with a date and Save or Clear
  *   say(out, ok)                    a toast for the answer of a write: the success text, or the server's refusal
- *   rescanRepo(ws)                  read the repository again now, with a toast at the start and at the end (scan-consistency R6)
+ *   rescanRepo(ws)                  read the repository again now, with a toast at the start and at the end (scan-consistency R6);
+ *                                   the tidy sheet first when a document repository has duplicates (scan-documents S10)
+ *   tidySheet(duplicates)           the groups of duplicate documents, the one to keep in each, and Cancel, Skip or Archive
  * No native dialog is used anywhere here. Every control is a primitive (primitives.js).
  */
 
 import { el } from './dom.js';
 import { button, field, signal, sheet, tabs, toast } from './primitives.js';
 import { COPY } from './initiatives-copy.js';
-import { rescan } from './initiatives-api.js';
+import { rescan, duplicates, tidy } from './initiatives-api.js';
 
 export const horizonLabel = (h) => COPY.horizons[h] || h;
 export const progressText = (row) => (row && row.progress && row.progress.label) || '';
@@ -48,16 +50,77 @@ export function scanMoves(before, after) {
   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`. */
+/**
+ * The tidy sheet (scan-documents S10): each group of documents that share an initiative and a role, with the one to keep
+ * chosen, a switch to leave the group as it is, and three answers. Resolves { keep: [{ id, role, keep }] } on the confirm,
+ * 'skip' on Scan without tidying, and null on Cancel, Escape or the backdrop.
+ */
+export function tidySheet(d) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v) => { if (settled) return; settled = true; resolve(v); };
+    const state = d.groups.map((g) => ({ g, on: true, keep: g.keep }));
+    const count = () => state.reduce((n, x) => n + (x.on ? x.g.files.length - 1 : 0), 0);
+    const day = (t) => (t ? new Date(t * 1000).toISOString().slice(0, 10) : '');
+    const err = el('p', { class: 'in-error', role: 'alert', 'data-in-error': '' });
+    err.hidden = true;
+    const groups = state.map((x, gi) => {
+      const box = el('fieldset', { class: 'in-tidy__group', 'data-in-tidy-group': x.g.id + ':' + x.g.role });
+      const toggle = el('input', { type: 'checkbox', checked: true, 'aria-label': COPY.tidyGroupToggle, 'data-in-tidy-on': '' });
+      toggle.addEventListener('change', () => { x.on = toggle.checked; if (x.on) box.removeAttribute('data-off'); else box.setAttribute('data-off', ''); go.textContent = COPY.tidyConfirm(count()); });
+      const head = el('legend', { class: 'in-tidy__head' }, toggle, `${x.g.title} · ${COPY.tidyRole[x.g.role] || x.g.role}`);
+      const files = x.g.files.map((f) => {
+        const radio = el('input', { type: 'radio', name: 'in-tidy-' + gi, value: f.path, checked: f.path === x.keep, 'data-in-tidy-keep': f.path });
+        radio.addEventListener('change', () => { if (radio.checked) x.keep = f.path; });
+        const meta = [f.changed ? COPY.tidyChanged(day(f.changed)) : '', x.g.named && f.path === x.g.keep ? COPY.tidyNamed : ''].filter(Boolean).join(' · ');
+        return el('label', { class: 'in-tidy__file' }, radio, el('span', null, el('span', { class: 'in-tidy__path' }, f.path), meta ? el('span', { class: 'in-note' }, ' · ' + meta) : null));
+      });
+      const shared = (x.g.shared || []).map((p) => el('p', { class: 'in-note in-tidy__file' }, COPY.tidyShared(p)));
+      box.replaceChildren(head, ...files, ...shared);
+      return box;
+    });
+    const inits = new Set(d.groups.map((g) => g.id)).size;
+    const go = button({
+      label: COPY.tidyConfirm(count()), variant: 'primary', attrs: { 'data-in-tidy-confirm': '' },
+      onClick: () => {
+        const keep = state.filter((x) => x.on).map((x) => ({ id: x.g.id, role: x.g.role, keep: x.keep }));
+        if (!keep.length) { err.textContent = COPY.tidyNone; err.hidden = false; return; }
+        finish({ keep }); s.close();
+      },
+    });
+    const s = sheet({
+      mode: 'auto', title: COPY.tidyTitle,
+      body: [el('p', { class: 'in-note' }, COPY.tidyBody(d.groups.length, inits, d.archive)), el('div', { class: 'in-tidy' }, groups), err],
+      attrs: { 'data-in-sheet': 'tidy' },
+      onClose: () => finish(null),
+      actions: [
+        button({ label: COPY.cancel, variant: 'outline', onClick: () => s.close(), attrs: { 'data-in-cancel': '' } }),
+        button({ label: COPY.tidySkip, variant: 'outline', onClick: () => { finish('skip'); s.close(); }, attrs: { 'data-in-tidy-skip': '' } }),
+        go,
+      ],
+    });
+  });
+}
+
+/** Re-scan: read the repository again now. In a document repository with duplicates, the tidy sheet comes first (S10).
+ *  A toast says the scan started and another says how it ended. Answers the rescan answer; the caller reloads what it
+ *  shows when `ok`. */
 export async function rescanRepo(ws) {
+  let first = null;
+  const d = await duplicates(ws);
+  if (d && d.ok && Array.isArray(d.groups) && d.groups.length) {
+    const pick = await tidySheet(d);
+    if (!pick) return { ok: false, cancelled: true };
+    if (pick !== 'skip') first = () => tidy(ws, pick.keep);
+  }
   toast({ text: COPY.rescanning, timeout: 4000 });
-  const a = await rescan(ws);
+  const a = await rescan(ws, first ? { first } : null);
   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 if (a.slow) toast({ text: COPY.rescanSlow, timeout: 6000 });
-  else toast({ text: moved ? COPY.rescanResult(moved.checked, moved.moves) : COPY.rescanDone(t), timeout: 10000 });
+  const archived = a && a.tidied && Array.isArray(a.tidied.moved) && a.tidied.moved.length ? COPY.tidyArchived(a.tidied.moved.length) + ' ' : '';
+  if (!a || !a.ok) toast({ text: first && a && !a.after && !a.slow ? COPY.tidyFailed((a && a.error) || 'no answer') : COPY.rescanFailed((a && a.error) || 'no answer'), tone: 'error', timeout: 8000 });
+  else if (a.slow) toast({ text: archived + COPY.rescanSlow, timeout: 6000 });
+  else toast({ text: archived + (moved ? COPY.rescanResult(moved.checked, moved.moves, (a.after && a.after.scan) || null) : COPY.rescanDone(t)), timeout: 10000 });
   try { if (a && a.ok) window.dispatchEvent(new CustomEvent('pmos:initiatives-changed')); } catch { /* no window */ }
   return a || { ok: false };
 }