create-pmos 0.70.1 → 0.71.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.70.1",
+  "version": "0.71.1",
   "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@5a5029e
 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:40:31Z"}
 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:40:31Z"}
 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:40:31Z"}
 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/guide/layout.md

@@ -17,7 +17,7 @@ The top bar has these parts, from left to right:
 - **Branches and sessions** is in ⌘K. It opens a sheet with every branch of the repository (main first) and how many sessions run in each. Press a branch to see its sessions, open one, end one, or start a session there. **＋ branch** makes a branch, and **＋ session** starts one with a branch, an agent and a profile. With All repositories, the sheet lists every repository.
 - **Agenda, Initiatives, Board, Reports, Docs and People** are the six places. Press one to show it. The Agenda count shows how many items need you. Docs shows whether each document is the same as its Google Docs and Confluence copy. People shows the people you work with in the repository ([People](people.md)).
 - **Search or capture ⌘K** opens the command palette. Type to find an initiative, a repository, an open tab or a command.
-- **Sync** shows only when the current repository is not in sync with its remote. Press it to fetch, bring in the work of the other machine, record your changes and push. If the repository has not fetched in the last 10 minutes, Sync also shows, because a push from another machine is not visible until a fetch. When the repository fetched recently and is in sync, Sync is not shown. When two machines add lines to the same ledger (a `.jsonl` file under `pmos/` or `planning/`), Sync keeps the lines from both machines. If Sync stops, the message names the step that stopped. If both machines changed the same lines of another file, the message names the file. Keep the version you want in that file on one machine, sync it, then sync the other machine.
+- **Sync** shows only when the current repository is not in sync with its remote. Press it to fetch, bring in the work of the other machine, record your changes and push. If the repository has not fetched in the last 10 minutes, Sync also shows, because a push from another machine is not visible until a fetch. When the repository fetched recently and is in sync, Sync is not shown. When two machines add lines to the same ledger (a `.jsonl` file under `pmos/` or `planning/`), Sync keeps the lines from both machines. If Sync stops, the message names the step that stopped. If both machines changed the same lines of another file, Sync changes nothing and names the files. Then choose **Push this machine’s version** or **Pull the other machine’s version**. Sync keeps that version of those files, keeps all other changes from both machines, and finishes. It never overwrites the remote history.
 - **Sync on its own.** If you forget to press Sync, the workspace syncs for you. It syncs each repository once when the workspace starts. It also syncs a repository that has records not yet pushed when no record changed for 5 minutes. In a document repository it syncs every changed file on any branch. In a code repository it syncs only on the default branch (for example `main`), and only when every commit not yet pushed changes records and no code. If you close the tab while records are not yet pushed, the browser asks you first. To turn automatic sync off, start the workspace with `PMOS_AUTO_SYNC=0`.
 - **Settings** opens the settings of the workspace.
 

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/sync.js

@@ -118,7 +118,36 @@ async function status(root) {
 }
 
 // The press. Returns { ok, steps:[{step, ok, note}], stopped_at?, message }.
-async function sync(root, { label } = {}) {
+// While a replay stops on a conflict, the PM's choice settles each conflicted file whole. In a rebase, stage 2 (`--ours`)
+// is the remote's side being built on, and stage 3 (`--theirs`) is this machine's commit being replayed. A side that
+// deleted the file is honoured by removing it. A commit left with nothing of its own is skipped. Bounded: each round
+// replays one commit, so the loop ends after at most one round per unpushed commit plus one.
+async function settleReplay(root, prefer, rounds) {
+  for (let i = 0; i <= rounds; i++) {
+    const rp = await run(root, ['rev-parse', '--git-path', 'rebase-merge']);
+    if (!rp.ok || !fs.existsSync(path.resolve(root, rp.out))) return { ok: true };
+    const u = await run(root, ['diff', '--name-only', '--diff-filter=U']);
+    const files = u.ok && u.out ? u.out.split('\n').filter(Boolean) : [];
+    if (!files.length) return { ok: false, err: 'the replay stopped with no conflicted file' };
+    const stage = prefer === 'mine' ? '3' : '2';
+    for (const f of files) {
+      const has = await run(root, ['cat-file', '-e', `:${stage}:${f}`]);
+      const r = has.ok ? await run(root, ['checkout', prefer === 'mine' ? '--theirs' : '--ours', '--', f]) : await run(root, ['rm', '-q', '--', f]);
+      if (!r.ok) return { ok: false, err: r.err };
+      if (has.ok) { const a = await run(root, ['add', '--', f]); if (!a.ok) return { ok: false, err: a.err }; }
+    }
+    const empty = (await run(root, ['diff', '--cached', '--quiet'])).ok;
+    const next = await run(root, ['-c', 'core.editor=true', 'rebase', empty ? '--skip' : '--continue']);
+    if (next.ok) return { ok: true };
+  }
+  return { ok: false, err: 'the replay did not finish' };
+}
+
+// `prefer` is the PM's answer after a stop on a conflict, and only the press passes it (never auto-sync): 'mine' keeps
+// this machine's version of each file both machines changed, 'theirs' keeps the other machine's. Every other change
+// from both machines is kept either way. Still a rebase of this machine's own commits: no force, no merge commit.
+async function sync(root, { label, prefer } = {}) {
+  if (prefer !== undefined && prefer !== 'mine' && prefer !== 'theirs') prefer = undefined;
   const steps = [];
   const stop = (step, message) => { steps.push({ step, ok: false, note: message }); return { ok: false, steps, stopped_at: step, message }; };
   const done = (step, note) => steps.push({ step, ok: true, note });
@@ -157,20 +186,26 @@ async function sync(root, { label } = {}) {
   if (s2.behind) {
     // Fast-forward when we have nothing of our own; otherwise replay OUR unpushed commits on top.
     const attrs = s2.ahead ? unionAttributesFor(root) : null;
-    const verb = s2.ahead ? [...(attrs ? ['-c', `core.attributesFile=${attrs}`] : []), 'rebase', '--autostash', s2.upstream]
+    // With the PM's choice, a conflicted hunk takes that side (-X); in a rebase `theirs` is this machine's commit.
+    const side = prefer && s2.ahead ? ['-X', prefer === 'mine' ? 'theirs' : 'ours'] : [];
+    const verb = s2.ahead ? [...(attrs ? ['-c', `core.attributesFile=${attrs}`] : []), 'rebase', '--autostash', ...side, s2.upstream]
       : ['merge', '--ff-only', s2.upstream];
-    const r = await run(root, verb);
+    let r = await run(root, verb);
+    if (!r.ok && prefer && s2.ahead) r = await settleReplay(root, prefer, s2.ahead);
     if (!r.ok) {
       if (!s2.ahead) return stop('integrate', `cannot fast-forward — ${r.err.split('\n')[0] || 'see git'}`);
       // Name the files before the abort clears them: the PM has to open these, and "the same lines" alone says not where.
       const u = await run(root, ['diff', '--name-only', '--diff-filter=U']);
       const files = u.ok && u.out ? u.out.split('\n').filter(Boolean) : [];
       await run(root, ['rebase', '--abort']);
-      return stop('integrate', files.length
-        ? `both machines changed ${files.join(', ')} — rebase aborted, nothing changed; keep the version you want in each file on one machine, sync it, then sync the other`
-        : `the two machines changed the same lines — rebase aborted, nothing changed — ${r.err.split('\n')[0] || 'see git'}`);
+      const out = stop('integrate', files.length
+        ? `both machines changed ${files.join(', ')} — rebase aborted, nothing changed; choose which machine's version to keep`
+        : `the two machines changed the same lines — rebase aborted, nothing changed — ${(r.err || '').split('\n')[0] || 'see git'}`);
+      // The surface offers the choice only for a conflict it can settle, and never again once one was made.
+      if (!prefer) out.conflict = { files };
+      return out;
     }
-    done('integrate', s2.ahead ? `replayed ${s2.ahead} local commit(s) on the remote` : `fast-forwarded ${s2.behind} commit(s)`);
+    done('integrate', s2.ahead ? `replayed ${s2.ahead} local commit(s) on the remote${prefer ? `, keeping ${prefer === 'mine' ? 'this' : 'the other'} machine's version where both changed a file` : ''}` : `fast-forwarded ${s2.behind} commit(s)`);
   } else done('integrate', 'nothing to bring in');
 
   const s3 = await status(root);

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.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

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

package/workspace/public/pm/app.js

@@ -39,7 +39,7 @@ import { isMobile, mountMobile, applyMobile } from './mobile.js';
 /* The frame's parts (Run 3, slice 3A). Small modules with no effect at import: a fixture page loads them and calls none. */
 import { createTopbar, unsyncedOf } from './topbar.js';
 import { createDockRail } from './dock.js';
-import { SEL, ensureComponentsCss, iconButton, menu, toast } from './primitives.js';
+import { SEL, ensureComponentsCss, iconButton, menu, toast, sheet, button } from './primitives.js';
 import { ensureSprite } from './icons.js';
 import { COPY as FC } from './frame-copy.js';
 import { registerCommand } from './registry.js';
@@ -512,17 +512,34 @@ function syncReading(repo) {
   }
   return syncSeen.get(repo).st;
 }
-async function runSync() {
+async function runSync(prefer) {
   const repo = fr.scope === 'all' ? null : activeRepo();
   if (!repo || fr.syncing || !mods.data || typeof mods.data.syncRepository !== 'function') return;
   fr.syncing = true;
   setState({});
   let res;
-  try { res = await mods.data.syncRepository(repo); } catch (e) { res = { ok: false, message: String((e && e.message) || e) }; }
+  const opts = prefer === 'mine' || prefer === 'theirs' ? { prefer } : undefined;
+  try { res = await mods.data.syncRepository(repo, opts); } catch (e) { res = { ok: false, message: String((e && e.message) || e) }; }
   fr.syncing = false;
   syncSeen.delete(repo);
-  toast({ text: res && res.ok ? FC.sync.done : FC.sync.stopped((res && (res.stopped_at || res.step)) || FC.sync.label, (res && (res.message || res.error)) || '') });
   setState({});
+  // Both machines changed the same lines and nothing changed: the PM chooses which version to keep (D70 amended
+  // 2026-10-07). The server offers the choice only once per press, so a choice that still stops ends in the toast.
+  if (res && !res.ok && res.conflict) return chooseSyncSide(res.conflict.files || []);
+  toast({ text: res && res.ok ? FC.sync.done : FC.sync.stopped((res && (res.stopped_at || res.step)) || FC.sync.label, (res && (res.message || res.error)) || '') });
+}
+function chooseSyncSide(files) {
+  const C = FC.sync.conflict;
+  let s = null;
+  const pick = (side) => () => { s.close(); runSync(side); };
+  s = sheet({
+    title: C.title, sub: C.sub(files), body: [el('p', {}, C.body)], attrs: { 'data-sync-conflict': '' },
+    actions: [
+      button({ label: C.push, variant: 'primary', onClick: pick('mine'), attrs: { 'data-sync-prefer': 'mine' } }),
+      button({ label: C.pull, onClick: pick('theirs'), attrs: { 'data-sync-prefer': 'theirs' } }),
+      button({ label: C.cancel, variant: 'ghost', onClick: () => s.close() }),
+    ],
+  });
 }
 
 /* Closing the tab with work that is not yet pushed asks first (D70 as amended 2026-10-06): idle auto-sync waits for a

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/data.js

@@ -1559,11 +1559,12 @@ export async function syncStatusOf(name) {
   return getJson('/api/sync/status', { ws });
 }
 
-export async function syncRepository(name) {
+// prefer: 'mine' | 'theirs' — the PM's answer after Sync stopped on a conflict (D70 as amended 2026-10-07).
+export async function syncRepository(name, { prefer } = {}) {
   if (FIXTURE) return { ok: false, message: 'fixture mode — nothing to sync' };
   const ws = wsOf(name);
   if (!ws) return { ok: false, message: 'unknown repository' };
-  const res = await postJson('/api/sync', { ws });
+  const res = await postJson('/api/sync', prefer ? { ws, prefer } : { ws });
   const p = products.get(name);
   if (res && res.ok && p) { p.board = null; await loadBoard(p); publishBoards(); }
   return res || { ok: false, message: 'the workspace server did not answer' };

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

@@ -41,6 +41,15 @@ export const COPY = {
     title: 'Sync this repository: fetch, bring in the work of the other machine, record your changes, push.',
     done: 'The repository is in sync.',
     stopped: (step, why) => 'Sync stopped at ' + step + ': ' + why,
+    /** Sync stopped because both machines changed the same lines. The PM chooses which version to keep. */
+    conflict: {
+      title: 'Both machines changed the same files',
+      sub: (files) => (files.length ? files.join(', ') : 'Git did not name the files.'),
+      body: 'Nothing changed. Choose which version to keep in these files. All other changes from both machines are kept.',
+      push: 'Push this machine’s version',
+      pull: 'Pull the other machine’s version',
+      cancel: 'Not now',
+    },
   },
   settings: 'Settings',
   dock: {

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

package/workspace/server.js

@@ -7095,7 +7095,9 @@ async function handleRequest(req, res) {
     if (syncing.has(w.root)) return json(res, { ok: false, error: 'a sync is already running for this repository' }, 409);
     syncing.add(w.root);
     try {
-      const out = await syncLib.sync(w.root, { label: os.hostname() });
+      // After a stop on a conflict the PM may answer which machine's version to keep; only this press passes it.
+      const prefer = body.prefer === 'mine' || body.prefer === 'theirs' ? body.prefer : undefined;
+      const out = await syncLib.sync(w.root, { label: os.hostname(), prefer });
       boardCache.invalidate(w.root);
       return json(res, { ws: w.id, name: w.name, ...out });
     } finally { syncing.delete(w.root); }