create-pmos 0.9.0 → 0.10.1

package/README.md

@@ -333,6 +333,89 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.10.1
+
+**Two fixes found by installing 0.10.0 and using it, rather than by reading the code.**
+
+- **Upgrades will keep reaching you.** The launcher decides whether to reinstall the workspace by
+  comparing the app version it bundles against the one you have. 0.10.0 shipped the *kit* at 0.10.0
+  but the bundled app still labelled **0.9.1** — so the next release would have compared equal,
+  decided you were current, and **silently skipped the upgrade**. Which is precisely the failure
+  0.9.1 existed to fix. The two versions are now checked against each other by the test suite, so it
+  cannot drift again unnoticed.
+- **Alignment no longer offers to edit its own notes.** The change-context digest quotes every change
+  you make, so it matched the "quotes text this change altered" rule on the very first save in any
+  repository — and topped the list of documents to realign. A generated file proposing to realign
+  itself. Machine-written state is now excluded from alignment entirely.
+
+If you installed 0.10.0, run `npx create-pmos@latest workspace` once. Nothing was damaged by either
+bug; the first would have cost you a future upgrade, and the second a confusing first suggestion.
+
+## What's new in 0.10.0
+
+**Editing a document now does something for the rest of them.**
+
+0.8.0 gave you an editor: change a markdown document in the workspace, see the diff as you type, and
+have the change logged. This release adds the two halves that make that log worth keeping.
+
+### After you save, you are offered what your change puts out of step
+
+Not a scan of your repository — a list built from **your change**. A document only appears if it has a
+concrete tie to what you edited:
+
+- it links to the document you changed, or names it in frontmatter (`prd_path`, `rubric_path`, …)
+- it shares that document's `initiative_id`
+- it **quotes text your change altered** — the strongest signal, because it is now asserting something
+  the source no longer says
+
+Each candidate says which of those it is, so you can judge the suggestion before spending anything on
+it. **"Seems related" is deliberately not a rule.** It would widen this to your whole repository and
+put you back in front of a queue of an agent's opinions.
+
+You tick which documents an agent may read. It drafts the edit that brings each back in line, and each
+draft comes back as a diff to apply or skip. Applying uses the same guard as every other write here:
+the text being replaced must appear exactly once, or the write is refused rather than guessed at.
+
+**It never blocks.** The save completed before any of this. Dismiss the offer and nothing is queued,
+nothing badges, nothing waits for you.
+
+### Your change log is now something an agent reads
+
+Every save regenerates `change-context.md` in your repository's own state directory: the documents you
+change most, the recent changes, and — the part that matters — **your own stated reasons**, in your
+words. An agent reading it before working in your repo knows what you keep rewriting and why, so it
+can stop producing the thing that provoked the rewrite.
+
+That is why the editor asks for a reason at all. A reason nobody reads is just friction at save time.
+
+Edits made by applying an alignment record **what they were aligned with**, so the log reads as a
+chain rather than as unexplained changes appearing in files you did not open.
+
+### Also carried: the 0.9.1 upgrade fix
+
+**0.9.1 was never published.** Its fix — `create-pmos workspace` self-upgrading instead of quietly
+launching your old installed app — is in this release. If the workspace has looked unchanged across
+recent versions, that is why; run `npx create-pmos@latest workspace` once and it will self-heal onto
+the current app. Hard-refresh the browser afterwards to drop the cached stylesheet.
+
+## What's new in 0.9.1
+
+**A fix so workspace upgrades actually reach you.** If you activated the Terminal Workspace in an
+earlier version, `npx create-pmos@latest workspace` was quietly launching your *old* installed app —
+so 0.9.0's restyle and whose-turn view never showed up. That was the bug, not a missing feature.
+
+- **`create-pmos workspace` now self-upgrades.** It compares the bundled app's version against what
+  you have installed and **reinstalls when the bundle is newer** (then restarts the persistent server
+  so the new code actually serves). A same-version install still fast-launches — no needless
+  ~20-second native rebuild.
+- **`create-pmos workspace --reinstall`** — force it any time.
+- **`pmos upgrade`** — the same, straight from the installed command.
+- If the UI still looks unchanged right after an upgrade, **hard-refresh the browser**
+  (Cmd/Ctrl+Shift+R) to drop the cached stylesheet.
+
+So if 0.9.0 looked like "not much changed," this is why: the code shipped, but your old install kept
+running. Run `npx create-pmos@latest workspace` once and it will self-heal onto the current app.
+
 ## What's new in 0.9.0
 
 **The Terminal Workspace now tells you whose turn it is.** The optional GUI got this release's real

package/bin/create-pmos.js

@@ -140,24 +140,81 @@ function launchWorkspace(targetDir, viaGlobal) {
     { stdio: 'inherit', env: process.env }).status || 0;
 }
 
-function workspace(targetArg) {
+// Compare two dotted numeric versions. Returns -1 if a<b, 0 if equal, 1 if a>b. Missing/non-numeric
+// segments count as 0, so 'unknown' sorts oldest — the safe default (reinstall rather than run stale).
+function cmpVer(a, b) {
+  const pa = String(a || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+// Version of the workspace app bundled in THIS package. It is kept in lockstep with the create-pmos
+// release version in workspace/package.json, so a newer package means a newer bundled app.
+function bundledWorkspaceVersion() {
+  try { return require(path.join(WORKSPACE, 'package.json')).version || null; }
+  catch { return null; }
+}
+// Version of the globally-installed `pmos-workspace`, or null if absent/unreadable. Read from the
+// npm global root rather than the app's CLI — no dependency on the old binary supporting --version.
+function installedWorkspaceVersion() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const r = spawnSync(npmCmd, ['root', '-g'], { encoding: 'utf8', shell: process.platform === 'win32' });
+  if (r.status !== 0 || !r.stdout) return null;
+  try { return require(path.join(r.stdout.trim(), 'pmos-workspace', 'package.json')).version || null; }
+  catch { return null; }
+}
+function installWorkspaceGlobal() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  return spawnSync(npmCmd, ['install', '-g', WORKSPACE, '--no-audit', '--no-fund'],
+    { stdio: 'inherit', shell: process.platform === 'win32' }).status;
+}
+// A persistent server started by the OLD code keeps serving OLD assets after an upgrade — stop it so
+// the next launch brings the server up on the freshly installed code. Best-effort; ignore failures.
+function stopWorkspaceServer() {
+  try { spawnSync('pmos', ['stop'], { stdio: 'ignore', shell: process.platform === 'win32' }); }
+  catch { /* no server running, or pmos not launchable — nothing to stop */ }
+}
+
+function workspace(targetArg, opts) {
   workspaceOrDie();
   const targetDir = path.resolve(targetArg || '.');
+  const forceReinstall = !!(opts && opts.reinstall);
 
-  // Already activated? Then this is just a launch — fast path, no reinstall.
+  // Already activated? Decide launch-vs-reinstall by VERSION, not merely by presence. The old
+  // behaviour fast-launched whenever `pmos` was on PATH, so every workspace improvement was invisible
+  // to anyone who had activated once — the installed app never advanced. Now: reinstall when forced,
+  // when the installed version can't be read, or when the bundled app is newer; otherwise fast-launch
+  // (no ~20s native rebuild for an already-current install).
   if (onPath('pmos')) {
-    console.log('✅ workspace already activated — launching. (Type `pmos` directly next time.)');
+    const bundled = bundledWorkspaceVersion();
+    const installed = installedWorkspaceVersion();
+    const stale = forceReinstall || installed === null || (bundled != null && cmpVer(installed, bundled) < 0);
+    if (!stale) {
+      console.log(`✅ workspace already current (pmos-workspace ${installed}) — launching. (Type \`pmos\` directly next time.)`);
+      process.exit(launchWorkspace(targetDir, true));
+    }
+    console.log(forceReinstall
+      ? 'Reinstalling the Terminal Workspace app (--reinstall)…'
+      : `Upgrading the Terminal Workspace app (installed ${installed || 'unknown'} → bundled ${bundled})…`);
+    const status = installWorkspaceGlobal();
+    if (status === 0) {
+      stopWorkspaceServer();   // restart the persistent server on the new code
+      console.log(`\n✅ pmos-workspace is now ${bundled}. Launching — if the UI still looks unchanged, hard-refresh the browser (Cmd/Ctrl+Shift+R) to drop the cached stylesheet.`);
+    } else {
+      console.log('\n⚠  Reinstall did not complete cleanly — launching the previously installed copy.');
+    }
     process.exit(launchWorkspace(targetDir, true));
   }
 
+  // First-time activation (pmos not on PATH).
   console.log('Activating the PMOS Terminal Workspace (one-time). Installing node-pty (native) + putting `pmos` on PATH…');
-  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const g = spawnSync(npmCmd, ['install', '-g', WORKSPACE, '--no-audit', '--no-fund'],
-    { stdio: 'inherit', shell: process.platform === 'win32' });
-
-  if (g.status === 0 && onPath('pmos')) {
+  const status = installWorkspaceGlobal();
+  if (status === 0 && onPath('pmos')) {
     console.log('\n✅ `pmos` is now on your PATH. From any repo folder, just type:  pmos');
-    console.log('   pmos status · pmos stop · pmos doctor');
+    console.log('   pmos status · pmos stop · pmos doctor · pmos upgrade');
     process.exit(launchWorkspace(targetDir, true));
   }
 
@@ -177,14 +234,15 @@ if (args.includes('--help') || args.includes('-h')) {
   console.log('usage:');
   console.log('  create-pmos [target-dir]              vendor the file-mode kit into a repo');
   console.log('  create-pmos --update [kit-or-repo]    refresh only the kit kernel');
-  console.log('  create-pmos workspace [repo-dir]      install + launch the Terminal Workspace GUI');
+  console.log('  create-pmos workspace [repo-dir]      install/upgrade + launch the Terminal Workspace GUI');
+  console.log('  create-pmos workspace --reinstall     force-reinstall the workspace app (drop a stale global copy)');
   console.log('  create-pmos --version                 print version + bundled kernel provenance');
 } else if (args.includes('--version') || args.includes('-v')) {
   console.log(`create-pmos ${PKG.version}`);
   console.log(kitVersion());
   console.log(`workspace bundled: ${fs.existsSync(path.join(WORKSPACE, 'bin', 'pmos.js')) ? 'yes' : 'no'}`);
 } else if (positional[0] === 'workspace') {
-  workspace(positional[1]);
+  workspace(positional[1], { reinstall: args.includes('--reinstall') });
 } else if (args.includes('--update')) {
   update(positional[0]);
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.9.0",
+  "version": "0.10.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. `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@bb26298
+kernel-source: pmos@84f5b38
 assembled: 2026-07-28
 mode: vendor

package/workspace/bin/pmos.js

@@ -211,10 +211,17 @@ function doctor() {
   else if (cmd === 'ls' || cmd === 'list') code = await ls();
   else if (cmd === 'stop') code = await stop();
   else if (cmd === 'doctor') code = doctor();
-  else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor]');
+  else if (cmd === 'upgrade') {
+    // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
+    // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
+    const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    code = spawnSync(npx, ['-y', 'create-pmos@latest', 'workspace', '--reinstall', process.cwd()],
+      { stdio: 'inherit', shell: process.platform === 'win32' }).status || 0;
+  } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
+    say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {
     // `pmos open ../other-repo` — the path is the argument AFTER the verb

package/workspace/lib/layout.js

@@ -163,9 +163,25 @@
     return { layouts, currentId: DEFAULT_ID };
   }
 
+  /* What a GET /api/layouts response entitles the client to DO. Split out as a pure function
+     because the original inline condition conflated two very different states — "this workspace
+     has never stored a layout" and "I could not read what it stored" — and answered both by
+     migrating and then WRITING, silently replacing a real stored document whenever a read failed.
+     A read failure must never author a write.
+
+       'migrate' — the server affirmatively says nothing is stored (first run here): R8 applies.
+       'use'     — a stored document came back: adopt it.
+       'keep'    — the answer is unusable (transport error, non-JSON, !ok, or no `stored` flag).
+                   Hold the boot defaults in memory and WRITE NOTHING. */
+  function loadAction(doc) {
+    if (!doc || doc.ok !== true || typeof doc.stored !== 'boolean') return 'keep';
+    return doc.stored ? 'use' : 'migrate';
+  }
+
   return {
     SIDE, READER, SPLIT, FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
     SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, BOTTOM_H,
     isStock, stockLayout, stockLayouts, layout, sanitize, gridFor, hasEscape, migrateLegacy,
+    loadAction,
   };
 });

package/workspace/lib/related-docs.js

@@ -0,0 +1,107 @@
+/* related-docs — which OTHER documents does this change put out of step?
+ * (workspace-doc-editor · R5/R6)
+ *
+ * Pure: takes the changed file, what changed in it, and a list of {path, text} for the repository's
+ * other documents. Returns candidates with a stated reason. No filesystem, no network, so the
+ * scoring rules are unit-testable directly and the endpoint stays a thin caller.
+ *
+ * R6 is the constraint that shapes everything here: **alignment is scoped by the change, not by the
+ * repository.** A pass that re-reads everything is a review by another name — the exact feature this
+ * one replaced, arriving through the back door. So a document only becomes a candidate if it has a
+ * concrete tie to the thing that changed:
+ *
+ *   - it LINKS to the changed file, or names it in frontmatter (prd_path, rubric_path, …)
+ *   - it shares the changed file's initiative_id
+ *   - it QUOTES text the change removed or altered
+ *
+ * "Feels related" is deliberately not a rule. Semantic similarity would widen this to everything and
+ * put the PM back in front of a queue of an agent's opinions, which is what they said they did not
+ * want. If references miss something, that is a known and accepted cost, recorded in the PRD.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.RelatedDocs = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  /** `key: value` from a leading frontmatter block. Tolerates a missing block. */
+  function frontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---/.exec(String(text || ''));
+    if (!m) return {};
+    const out = {};
+    for (const line of m[1].split('\n')) {
+      const i = line.indexOf(':');
+      if (i < 1) continue;
+      out[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+  }
+
+  /* Phrases worth searching other documents for. Short or generic lines match everything and would
+   * turn precision into noise, so a line must be substantial to qualify — and only a few are used,
+   * because each one costs a scan of every document. */
+  function phrasesFrom(removedText, min = 24, max = 4) {
+    return String(removedText || '')
+      .split('\n')
+      .map((l) => l.replace(/^[\s>#*\-+\d.]+/, '').trim())
+      .filter((l) => l.length >= min && /[a-z]{4}/i.test(l))
+      .sort((a, b) => b.length - a.length)
+      .slice(0, max);
+  }
+
+  /**
+   * candidates({ changedPath, changedText, removed, docs })
+   *   changedPath — repo-relative path of the document just saved
+   *   changedText — its full text after the save (for its own frontmatter)
+   *   removed     — the text the save removed or replaced (drives the quote rule)
+   *   docs        — [{ path, text }] for the repository's other markdown documents
+   * → [{ path, reasons: [string], strength }] sorted strongest first. Never throws.
+   */
+  function candidates({ changedPath, changedText, removed, docs } = {}) {
+    const target = String(changedPath || '');
+    if (!target || !Array.isArray(docs)) return [];
+    const base = target.split('/').pop();
+    const mine = frontmatter(changedText);
+    const initiative = mine.initiative_id || mine.id || null;
+    const phrases = phrasesFrom(removed);
+    const out = [];
+
+    for (const d of docs) {
+      if (!d || typeof d.path !== 'string' || d.path === target) continue;
+      const text = String(d.text || '');
+      const reasons = [];
+
+      // 1. links to the changed file — by full repo path or by filename
+      if (text.includes(target) || new RegExp('\\(([^)]*/)?' + esc(base) + '\\)').test(text)) {
+        reasons.push('links to this document');
+      }
+      // 2. frontmatter points at it (prd_path, rubric_path, and anything else path-shaped)
+      const fm = frontmatter(text);
+      for (const [k, v] of Object.entries(fm)) {
+        if (typeof v === 'string' && v && (v === target || v.endsWith('/' + base))) {
+          reasons.push(`its ${k} is this document`);
+        }
+      }
+      // 3. same initiative — the artifacts of one piece of work move together
+      if (initiative && (fm.initiative_id === initiative || fm.id === initiative)) {
+        reasons.push(`same initiative (${initiative})`);
+      }
+      // 4. quotes text this change removed or altered — the strongest signal there is, because the
+      //    other document is now asserting something the source no longer says
+      for (const ph of phrases) {
+        if (text.includes(ph)) { reasons.push(`quotes text this change altered: "${ph.slice(0, 60)}…"`); break; }
+      }
+
+      if (reasons.length) {
+        const quotes = reasons.some((r) => r.startsWith('quotes text'));
+        out.push({ path: d.path, reasons, strength: reasons.length + (quotes ? 2 : 0) });
+      }
+    }
+    return out.sort((a, b) => b.strength - a.strength || a.path.localeCompare(b.path));
+  }
+
+  return { candidates, frontmatter, phrasesFrom };
+});

package/workspace/package.json

@@ -1,17 +1,21 @@
 {
   "name": "pmos-workspace",
-  "version": "0.1.0",
+  "version": "0.10.1",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
-  "bin": { "pmos": "bin/pmos.js" },
+  "bin": {
+    "pmos": "bin/pmos.js"
+  },
   "scripts": {
     "start": "node server.js",
     "test": "node test.js",
     "test:ui": "node ui-test.js",
     "doctor": "node doctor.js"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",

package/workspace/public/app.js

@@ -1059,7 +1059,13 @@ async function loadLayouts() {
     const r = await fetch('/api/layouts?ws=' + encodeURIComponent(state.wsId || ''));
     doc = await r.json();
   } catch { doc = null; }
-  if (!doc || !doc.ok || !Array.isArray(doc.layouts) || !doc.layouts.length) {
+  // A read failure must never author a write. loadAction() is the one place that decides, and it
+  // only says 'migrate' when the SERVER affirmatively reports nothing stored — never because the
+  // answer was unreadable. Anything unusable is 'keep': show the boot defaults, persist nothing,
+  // and leave whatever is on disk exactly as it is until a load succeeds.
+  const act = LAY.loadAction(doc);
+  if (act === 'keep') return;
+  if (act === 'migrate') {
     // R8 — a workspace with nothing stored inherits whatever the PM had already tuned by hand
     // in the pre-feature client, so the upgrade never costs them their rail width.
     const legacy = {};
@@ -2070,10 +2076,12 @@ function edRender() {
   $('edDiff').innerHTML = rows.join('') || '<div class="ed-none">whitespace only</div>';
 }
 
-function edClose(reload) {
+async function edClose(reload) {
   ed.on = false; ed.path = null; ed.base = ''; ed.dirty = false;
   edControls();
-  if (reload && state.docPath) openDoc(state.docPath);
+  // awaited: the reload replaces docBody, so anything that renders into it afterwards (the
+  // alignment offer) must not race the replacement.
+  if (reload && state.docPath) await openDoc(state.docPath);
 }
 
 async function edSave() {
@@ -2098,7 +2106,120 @@ async function edSave() {
     return;
   }
   flash(out.warning ? 'saved — but the change could not be logged' : `saved · +${out.change.added} −${out.change.removed}`);
-  edClose(true);
+  const saved = ed.path;
+  await edClose(true);
+  alOffer(saved);                                          // R7: offered, never blocking — the save is already done
+}
+
+
+// ── alignment (workspace-doc-editor R5–R7) ────────────────────────────────────────────────────
+// Strictly downstream of a save. Nothing here runs until the PM has changed something, and what it
+// looks at is scoped by that change — not the repository. It is offered, never blocking: the save
+// completed before any of this, and ignoring it costs nothing.
+async function alOffer(pth) {
+  if (!pth) return;
+  let out = {};
+  try { out = await (await fetch(`/api/align/candidates?ws=${encodeURIComponent(state.wsId || '')}&path=${encodeURIComponent(pth)}`)).json(); }
+  catch { return; }
+  if (!out.ok || out.empty || !out.candidates || !out.candidates.length) return;
+  state.alCand = out;
+  const n = out.candidates.length;
+  const bar = document.createElement('div');
+  bar.className = 'al-offer';
+  bar.innerHTML = `<span>${n} other document${n === 1 ? '' : 's'} may now be out of step with that change.</span>
+    <button data-al-see>see them</button><button class="q" data-al-no>not now</button>`;
+  const body = $('docBody');
+  body.prepend(bar);
+  bar.querySelector('[data-al-no]').onclick = () => bar.remove();
+  bar.querySelector('[data-al-see]').onclick = () => alShow();
+}
+
+// The candidate list, each with the concrete reason it qualified. The PM chooses which to hand to
+// an agent — so even the drafting step is something they asked for, not something that happened.
+function alShow() {
+  const c = state.alCand; if (!c) return;
+  $('docBody').innerHTML = `<div class="al">
+    <div class="al-lede">Your change to <span class="mono">${esc(c.change.file)}</span> may leave these out of step.</div>
+    <div class="al-sub">Each one has a concrete tie to what you changed — a link, a shared initiative, or text it quotes. Considered ${c.considered} documents.</div>
+    ${c.candidates.map((x, i) => `<label class="al-c">
+        <input type="checkbox" data-al-pick="${i}" checked />
+        <span><span class="al-p mono">${esc(x.path)}</span>
+        <span class="al-why">${x.reasons.map((r) => esc(r)).join(' · ')}</span></span>
+      </label>`).join('')}
+    <div class="al-acts">
+      <button data-al-go>Draft the edits</button>
+      <button class="q" data-al-close>Close</button>
+      <span class="al-note">An agent reads only the documents you tick, and only against this change.</span>
+    </div></div>`;
+  $('docBody').querySelector('[data-al-close]').onclick = () => openDoc(c.change.file);
+  $('docBody').querySelector('[data-al-go]').onclick = async () => {
+    const targets = [...$('docBody').querySelectorAll('[data-al-pick]')]
+      .filter((b) => b.checked).map((b) => c.candidates[Number(b.dataset.alPick)].path);
+    if (!targets.length) { flash('nothing ticked'); return; }
+    let out = {};
+    try {
+      out = await (await fetch('/api/align/start', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ws: state.wsId, path: c.change.file, change: c.change, targets }) })).json();
+    } catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+    if (!out.ok) { flash(out.error || 'could not start'); return; }
+    flash(`drafting against ${targets.length} document${targets.length === 1 ? '' : 's'} — watch the session, then open drafts`);
+    if (out.sessionId) selectSession(out.sessionId);
+  };
+}
+
+// The drafts an agent produced, each an applyable diff. Apply uses the same anchored guard as every
+// other write here: the anchor must appear exactly once or the write is refused.
+async function alDrafts() {
+  let out = {};
+  try { out = await (await fetch(`/api/align/drafts?ws=${encodeURIComponent(state.wsId || '')}`)).json(); }
+  catch { out = { ok: false, error: 'could not reach the workspace server' }; }
+  showRail(); $('paneDoc').hidden = false; foldPane('doc', true);
+  $('crumb').innerHTML = '<bdi>alignment drafts</bdi>';
+  if (!out.ok) { $('docBody').innerHTML = `<div class="al"><div class="al-lede">${esc(out.error || 'could not read the drafts')}</div></div>`; return; }
+  if (out.empty || !out.drafts.length) {
+    $('docBody').innerHTML = `<div class="al"><div class="al-lede">No drafts yet.</div>
+      <div class="al-sub">Edit a document, then ask for the alignment when it offers.</div></div>`;
+    return;
+  }
+  state.alDrafts = out;
+  $('docBody').innerHTML = `<div class="al">
+    <div class="al-lede">${out.drafts.length} edit${out.drafts.length === 1 ? '' : 's'} to bring other documents back in line.</div>
+    <div class="al-sub">Drafted against your change to <span class="mono">${esc(out.source || '')}</span>. Nothing is written until you apply it.</div>
+    ${out.drafts.map((d, i) => `<div class="al-d" data-al-d="${i}">
+      <div class="al-p mono">${esc(d.file)}</div>
+      <div class="al-why">${esc(d.why || '')}</div>
+      <div class="al-code">
+        ${String(d.before || '').split('\n').map((l) => `<div class="ed-l del"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`).join('')}
+        ${String(d.after || '').split('\n').map((l) => `<div class="ed-l add"><span class="g"></span><span class="t">${esc(l) || '&nbsp;'}</span></div>`).join('')}
+      </div>
+      <div class="al-acts"><button data-al-apply="${i}">Apply</button>
+        <button class="q" data-al-skip="${i}">Skip</button></div>
+    </div>`).join('')}</div>`;
+  $('docBody').querySelectorAll('[data-al-skip]').forEach((b) => b.onclick = () => {
+    $('docBody').querySelector(`[data-al-d="${b.dataset.alSkip}"]`).classList.add('done');
+  });
+  $('docBody').querySelectorAll('[data-al-apply]').forEach((b) => b.onclick = async () => {
+    const d = state.alDrafts.drafts[Number(b.dataset.alApply)];
+    b.disabled = true;
+    let r = {};
+    try {
+      r = await (await fetch('/api/align/apply', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ws: state.wsId, file: d.file, before: d.before, after: d.after, why: d.why, source: state.alDrafts.source }) })).json();
+    } catch { r = { ok: false, error: 'could not reach the workspace server' }; }
+    b.disabled = false;
+    const card = $('docBody').querySelector(`[data-al-d="${b.dataset.alApply}"]`);
+    if (!r.ok) {
+      let e = card.querySelector('.al-err');
+      if (!e) { e = document.createElement('div'); e.className = 'al-err'; card.appendChild(e); }
+      e.textContent = r.error === 'stale' ? 'that text is no longer in the file — the draft is out of date'
+        : r.error === 'ambiguous' ? (r.detail || 'that text appears more than once — refusing to guess')
+        : (r.detail || r.error || 'refused');
+      return;
+    }
+    card.classList.add('done');
+    flash('aligned ' + d.file.split('/').pop());
+  });
+  refit();
 }
 
 $('docEdit').onclick = edOpen;
@@ -2602,6 +2723,7 @@ function openPalette() {
   const wss = state.workspaces.filter((w) => w.id !== state.wsId).map((w) => ({ kind: 'workspace', label: w.name, wsid: w.id }));
   // summon a P/D/M/R surface on demand — listed first so "initiatives"/"roadmap"/"okr"/"report" are reachable
   const views = SURFACES.map((v) => ({ kind: 'view', label: v.label, view: v.name }));
+  views.push({ kind: 'align', label: 'alignment drafts' });   // downstream of a save, never resident
   palItems = [...views, ...wss, ...sess, ...inits, ...docs];
   $('palette').style.display = 'grid';
   const inp = $('palInput'); inp.value = ''; renderPalette('');
@@ -2627,6 +2749,7 @@ function choosePalette(n) {
   const it = items[n]; if (!it) return;
   closePalette();
   if (it.kind === 'view') openSurface(it.view);
+  else if (it.kind === 'align') alDrafts();
   else if (it.kind === 'session') selectSession(it.id);
   else if (it.kind === 'workspace') selectWorkspace(it.wsid);
   else if (it.kind === 'initiative') {

package/workspace/public/styles.css

@@ -1279,3 +1279,37 @@ line-height:1.35;cursor:pointer}
 .hist-when i{color:var(--destructive);font-style:normal;font-weight:600}
 .hist-note{margin-top:4px;font-size:var(--text-sm);color:var(--foreground);line-height:1.55}
 .hist-none{font-size:var(--text-sm);color:var(--muted-foreground);line-height:1.6}
+
+/* ── alignment (workspace-doc-editor R5–R7) ──────────────────────────────────────────────────
+   Downstream of a save and offered, never blocking. The offer is one line that can be dismissed;
+   nothing accumulates and nothing badges.
+   Tokens follow the radix-sera port: --brand is the blue for text/borders, --primary is for fills,
+   and --accent is a muted hover surface, not a hue. Radii come from the scale — never a px. */
+.al-offer{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin:12px 14px;padding:10px 12px;
+  border-radius:var(--radius-md);background:var(--brand-wash);border:1px solid var(--brand);
+  font-size:var(--text-sm);line-height:1.5;color:var(--foreground)}
+.al-offer button{font-size:var(--text-sm);color:var(--brand);padding:2px 0}
+.al-offer button:hover{text-decoration:underline}
+.al-offer button.q{color:var(--muted-foreground);margin-left:auto}
+.al{padding:16px 18px 40px;max-width:660px}
+.al-lede{font-size:var(--text-base);line-height:1.5;color:var(--foreground);margin-bottom:5px}
+.al-sub{font-size:var(--text-sm);line-height:1.6;color:var(--muted-foreground);margin-bottom:16px}
+.al-c{display:flex;gap:9px;align-items:flex-start;padding:9px 0;border-top:1px solid var(--border);cursor:pointer}
+.al-c:first-of-type{border-top:0}
+.al-c input{margin-top:3px;accent-color:var(--primary);width:15px;height:15px;flex:none}
+.al-p{font-size:var(--text-sm);color:var(--foreground);display:block;word-break:break-all}
+.al-why{display:block;margin-top:2px;font-size:var(--text-xs);color:var(--muted-foreground);line-height:1.5}
+.al-acts{display:flex;gap:15px;align-items:center;flex-wrap:wrap;margin-top:14px}
+.al-acts button{font-size:var(--text-sm);color:var(--brand);padding:3px 0;min-height:30px}
+.al-acts button:hover{text-decoration:underline}
+.al-acts button.q{color:var(--muted-foreground)}
+.al-acts button:disabled{color:var(--muted-foreground);text-decoration:none;cursor:default}
+.al-note{font-size:var(--text-xs);color:var(--muted-foreground)}
+.al-d{padding:13px 0;border-top:1px solid var(--border)}
+.al-d.done{opacity:.45}
+.al-d.done .al-code,.al-d.done .al-acts{display:none}
+.al-d.done .al-p::after{content:" · settled";color:var(--success);font-family:var(--sans);font-size:var(--text-xs)}
+.al-code{margin-top:9px;font-family:var(--mono);font-size:var(--text-xs);line-height:1.75;
+  border-top:1px solid var(--border);border-bottom:1px solid var(--border);padding:6px 0}
+.al-err{margin-top:9px;padding:8px 11px;border-radius:var(--radius-md);border:1px solid var(--destructive);
+  background:rgba(242,101,95,.08);font-size:var(--text-sm);line-height:1.5;color:var(--foreground)}

package/workspace/server.js

@@ -71,6 +71,7 @@ const consoleState = require('./lib/console-state');   // read-only console surf
 const fmParse = require('./lib/file-mode-parse');      // canonical file-mode parsers, shared with metrics.py (D64 D)
 const gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
 const tmuxControl = require('./lib/tmux-control');     // tmux -CC protocol: the pane's raw stream, so xterm.js keeps its scrollback
+const relatedDocs = require('./lib/related-docs');            // which documents a change puts out of step (R5/R6)
 const applyChange = require('./lib/apply-change');            // anchored + whole-document saves, refuse-on-stale
 const sessionState = require('./lib/session-state');   // the cadence×turn join — validated on BOTH sides
 // The "home" repo this server manages. In PMOS-self the app ships INSIDE its repo
@@ -224,6 +225,9 @@ function wsList() {
   }));
 }
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'vendor', 'target', 'coverage', '.git', 'tmp', 'out']);
+// The directories stateDirFor() resolves to. Their contents are machine-written runtime and curated
+// records — never documents alignment should offer to edit.
+const STATE_DIR_NAMES = new Set(['state', '.pmos']);
 const PLAIN_MAX_DEPTH = 3;      // the curated (knowledge) view stays shallow
 const TREE_MAX_DEPTH = 6;       // the folder lens is a real explorer, but bounded on huge/slow repos
 const TREE_MAX_NODES = 4000;    // …and node-budgeted so a giant repo (or Google Drive) never hangs
@@ -302,6 +306,32 @@ function libraryTree(root) {
   if (loose.length) roots.push({ name: '(root)', path: '', dirs: [], docs: loose });
   return roots;
 }
+// Every markdown document under the root, as repo-relative paths. Used by alignment to decide which
+// documents a change might affect (R6) — it needs a flat list, and libraryTree returns a nested shape
+// for the library lens. Bounded: a repository is not an excuse to read forever.
+function markdownDocs(root, limit = 800) {
+  const out = [];
+  const walk = (dir, rel, depth) => {
+    if (out.length >= limit || depth > 8) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (out.length >= limit) return;
+      if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const r = rel ? rel + '/' + e.name : e.name;
+      // Machine-written state is not a document the PM maintains, and alignment must never propose
+      // realigning it. change-context.md in particular QUOTES every change, so it matches the
+      // quoted-text rule on the first save in any repository and would top the candidate list —
+      // a generated file suggesting itself, found by installing the published artifact and using it.
+      if (STATE_DIR_NAMES.has(e.name)) continue;
+      if (e.isDirectory()) walk(full, r, depth + 1);
+      else if (preview.previewKind(e.name) === 'markdown') out.push(r);
+    }
+  };
+  walk(root, '', 0);
+  return out;
+}
 // every top-level file (md + non-md), so the folder lens shows the real root, not a curated subset
 function looseFiles(root) {
   let ents = [];
@@ -1488,11 +1518,17 @@ const LAYOUT_MAX = 40_000;
 function layoutPath(w) { return w ? path.join(LAYOUT_DIR, w.id + '.json') : null; }
 // Always returns a usable document: an absent, empty, truncated or hand-mangled file yields the
 // four stock layouts rather than an error, because the alternative is a window the PM cannot use.
+// `stored` is the client's ONLY safe signal that R8's one-time migration should run. sanitize()
+// always yields the four stock layouts, so the response body alone cannot distinguish "this
+// workspace has never stored anything" from "I could not read what it stored" — and the client
+// answers those two cases very differently (one writes, one must not). A file that exists but is
+// corrupt still counts as stored: this workspace has been through the layout system, so replaying
+// the pre-feature localStorage over it would be a second loss, not a recovery.
 function readLayouts(w) {
   const f = layoutPath(w);
   let raw = null;
   if (f) { try { raw = fs.readFileSync(f, 'utf8'); } catch { raw = null; } }
-  return layoutModel.sanitize(raw);
+  return Object.assign(layoutModel.sanitize(raw), { stored: raw !== null });
 }
 function writeLayouts(w, doc) {
   const f = layoutPath(w);
@@ -1850,6 +1886,7 @@ async function handleRequest(req, res) {
   // a directory route — a <script src> for a file missing from this list 404s silently, and the
   // client feature that depends on it fails in a way no server-side test can see.
   if (p === '/lib/apply-change.js') return serveFile(res, path.join(__dirname, 'lib', 'apply-change.js'));
+  if (p === '/lib/related-docs.js') return serveFile(res, path.join(__dirname, 'lib', 'related-docs.js'));
   if (p === '/styles.css') return serveFile(res, path.join(PUB, 'styles.css'));
   // xterm assets straight from node_modules (offline; no CDN)
   if (p === '/vendor/xterm.js') return serveFile(res, path.join(XROOT, 'xterm', 'lib', 'xterm.js'));
@@ -2099,7 +2136,7 @@ async function handleRequest(req, res) {
     const w = getWs(url.searchParams.get('ws'));
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
     const doc = readLayouts(w);
-    return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId });
+    return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId, stored: doc.stored });
   }
   if (p === '/api/doc') {
     const w = getWs(url.searchParams.get('ws'));
@@ -2247,12 +2284,156 @@ async function handleRequest(req, res) {
       const sink = path.join(dir, 'doc-changes.jsonl');
       try { fs.mkdirSync(dir, { recursive: true }); fs.appendFileSync(sink, JSON.stringify(rec) + '\n'); logged = sink; }
       catch (e) { warnWriteFail('doc-changes.jsonl (the change log)', e); }
+      writeChangeContext(dir);                              // R8 — keep the agent-readable digest current
     }
     // The document IS saved at this point. A failed log is reported honestly rather than as success,
     // but it must not read as "your edit was lost".
     return json(res, { ok: true, saved: body.path, logged, change: { added: rec.added, removed: rec.removed, at_line: rec.at_line },
       warning: logged ? undefined : 'the document was saved but the change could not be logged' });
   }
+  if (p === '/api/align/candidates') {
+    // Which documents does the last change to THIS document put out of step? Scoped by the change
+    // (R6): a document qualifies only by a concrete tie — it links here, its frontmatter points
+    // here, it shares the initiative, or it quotes text the change altered. "Feels related" is not a
+    // rule, because that is how this becomes a review queue again.
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(url.searchParams.get('path') || '');
+    const full = path.resolve(w.root, rel);
+    if (!rel || !insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+
+    const dir = stateDirFor(w);
+    let last = null;
+    try {
+      const sink = dir ? path.join(dir, 'doc-changes.jsonl') : null;
+      if (sink && fs.existsSync(sink)) {
+        const rows = fs.readFileSync(sink, 'utf8').split('\n').filter(Boolean)
+          .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+          .filter((r) => r && r.file === rel);
+        last = rows[rows.length - 1] || null;
+      }
+    } catch {}
+    if (!last) return json(res, { ok: true, empty: true, reason: 'no recorded change to this document yet' });
+
+    let changedText = '';
+    try { changedText = fs.readFileSync(full, 'utf8'); } catch {}
+    const docs = [];
+    for (const f of markdownDocs(w.root)) {
+      if (f === rel) continue;
+      const fp = path.resolve(w.root, f);
+      if (!insideRoot(w.root, fp)) continue;
+      try { docs.push({ path: f, text: fs.readFileSync(fp, 'utf8') }); } catch {}
+    }
+    const cands = relatedDocs.candidates({ changedPath: rel, changedText, removed: last.before, docs });
+    return json(res, { ok: true, change: last, candidates: cands.slice(0, 12), considered: docs.length, total: cands.length });
+  }
+  if (p === '/api/align/start' && req.method === 'POST') {
+    // Hand the change and its candidates to an agent, which DRAFTS the realigning edits (R5). The
+    // prompt is assembled here so the absolute paths are facts, not guesses — a tenant product repo
+    // has no workspace/ folder, and the agent must never invent one.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(body.path || '');
+    if (!rel || !insideRoot(w.root, path.resolve(w.root, rel))) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    const targets = (Array.isArray(body.targets) ? body.targets : []).filter((t) => typeof t === 'string').slice(0, 12);
+    if (!targets.length) return json(res, { ok: false, error: 'no documents named to align' }, 400);
+
+    const dir = stateDirFor(w, { create: true });
+    if (!dir) return json(res, { ok: false, error: 'this workspace has no state directory to file drafts into' }, 500);
+    const adir = path.join(dir, 'alignments');
+    try { fs.mkdirSync(adir, { recursive: true }); }
+    catch (e) { warnWriteFail('alignments directory', e); return json(res, { ok: false, error: 'could not create the alignments directory' }, 500); }
+
+    const c = body.change || {};
+    const prompt = [
+      'A document in this repository was just changed by the PM. Your job is to bring the documents',
+      'listed below back into line with that change — nothing else.',
+      '',
+      `CHANGED: ${rel} (from line ${c.at_line || '?'})`,
+      '',
+      'It used to say:', '```', String(c.before || '').slice(0, 4000), '```',
+      'It now says:', '```', String(c.after || '').slice(0, 4000), '```',
+      c.note ? `The PM's reason: ${c.note}` : '',
+      '',
+      'BRING THESE INTO LINE — read each, and only these:',
+      ...targets.map((t) => `  - ${t}`),
+      '',
+      'For each document that genuinely contradicts the change, produce the edit that fixes it.',
+      'A document that does not actually contradict it gets NO draft — say so and move on. Do not',
+      'improve, tidy, or critique anything: the only warrant you have is the change above.',
+      '',
+      `Write your drafts as JSON to: ${path.join(adir, 'draft-' + Date.now() + '.json')}`,
+      'Shape:',
+      '{"source":"' + rel + '","at":"<ISO 8601>","drafts":[',
+      '  {"file":"<path>","why":"<what in this document contradicts the change>",',
+      '   "before":"<verbatim text from that file, appearing EXACTLY once>","after":"<replacement>"}',
+      ']}',
+      '',
+      '`before` must be copied verbatim and must occur exactly once in its file — the apply path',
+      'refuses a stale or ambiguous anchor rather than guessing. An empty drafts array is a correct',
+      'and useful answer.',
+    ].filter((l) => l !== '').join('\n');
+
+    const s = spawnSession({ name: 'align: ' + path.basename(rel), agent: 'claude', ws: w.id,
+      origin: 'align:' + rel, initialInput: prompt + '\r' });
+    const started = !!(s && s.pty);
+    return json(res, { ok: started, sessionId: s && s.id, targets, sink: adir,
+      error: started ? undefined : ((s && s.note) || 'could not start the session') });
+  }
+  if (p === '/api/align/drafts') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const dir = stateDirFor(w);
+    const adir = dir ? path.join(dir, 'alignments') : null;
+    let files = [];
+    try { files = adir ? fs.readdirSync(adir).filter((f) => f.endsWith('.json')).sort() : []; } catch {}
+    if (!files.length) return json(res, { ok: true, empty: true });
+    const pick = files[files.length - 1];
+    let doc;
+    try { doc = JSON.parse(fs.readFileSync(path.join(adir, pick), 'utf8')); }
+    catch { return json(res, { ok: false, error: `the draft file '${pick}' is unreadable or not valid JSON` }, 500); }
+    const drafts = Array.isArray(doc.drafts) ? doc.drafts.filter((d) => d && typeof d.file === 'string') : [];
+    return json(res, { ok: true, id: pick.replace(/\.json$/, ''), source: doc.source || null, at: doc.at || null, drafts });
+  }
+  if (p === '/api/align/apply' && req.method === 'POST') {
+    // Apply ONE drafted realignment. Same anchored guard as everything else that writes here: the
+    // anchor must appear exactly once, or the write is refused rather than guessed at.
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
+    const rel = String(body.file || '');
+    const full = path.resolve(w.root, rel);
+    if (!rel || !insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    if (preview.previewKind(path.basename(full)) !== 'markdown') return json(res, { ok: false, error: 'only markdown documents are editable here' }, 400);
+    let current;
+    try { current = fs.readFileSync(full, 'utf8'); }
+    catch { return json(res, { ok: false, error: 'could not read the document' }, 404); }
+
+    const r = applyChange.applyChange(current, { before: body.before, after: body.after });
+    if (!r.ok) return json(res, { ok: false, error: r.reason, detail: r.detail || null }, 409);
+    try { fs.writeFileSync(full, r.text); }
+    catch (e) { warnWriteFail('alignment apply (' + rel + ')', e); return json(res, { ok: false, error: 'could not write the document' }, 500); }
+
+    // An aligning edit is a change to that document too, and belongs in its log — attributed to the
+    // change that caused it, so the log reads as a chain rather than as unexplained edits.
+    const region = applyChange.changedRegion(body.before, body.after);
+    const dir = stateDirFor(w, { create: true });
+    if (dir) {
+      const rec = { file: rel, at: nowISO(), pm: body.pm || 'wawan',
+        note: 'aligned with ' + (body.source || 'an earlier change') + (body.why ? ' — ' + String(body.why).slice(0, 200) : ''),
+        at_line: region.at_line, added: region.added, removed: region.removed,
+        before: region.before, after: region.after, aligned_from: body.source || null };
+      try { fs.appendFileSync(path.join(dir, 'doc-changes.jsonl'), JSON.stringify(rec) + '\n'); }
+      catch (e) { warnWriteFail('doc-changes.jsonl (alignment)', e); }
+      writeChangeContext(dir);
+    }
+    return json(res, { ok: true, wrote: rel });
+  }
   if (p === '/api/doc/changes') {
     // The change log, read back (R8 — this is what an agent reads before working here).
     const w = getWs(url.searchParams.get('ws'));
@@ -2273,6 +2454,67 @@ async function handleRequest(req, res) {
   res.writeHead(404); res.end('not found');
 }
 
+// ── R8: the change log, written for an agent to read before it works here ──────────────────────
+// The jsonl is the record; this is the same material shaped so a coding agent picks it up without
+// being handed a parser. Regenerated on every save — cheap, and it means the file is never stale.
+// What makes it worth reading is the PM's own reasons: an agent that knows WHY a line kept getting
+// rewritten will stop writing the thing that provoked it.
+function writeChangeContext(dir) {
+  if (!dir) return null;
+  const sink = path.join(dir, 'doc-changes.jsonl');
+  let rows = [];
+  try {
+    if (!fs.existsSync(sink)) return null;
+    rows = fs.readFileSync(sink, 'utf8').split('\n').filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return null; }
+  if (!rows.length) return null;
+
+  const byFile = new Map();
+  for (const r of rows) byFile.set(r.file, (byFile.get(r.file) || 0) + 1);
+  const hot = [...byFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
+  const withReasons = rows.filter((r) => r.note).slice(-20).reverse();
+  const recent = rows.slice(-12).reverse();
+
+  const out = [
+    '---', 'type: Reference',
+    'title: "Change context — what the PM has been editing here, and why"',
+    'timestamp: ' + nowISO().slice(0, 10), '---', '',
+    '# Change context',
+    '',
+    '**Read this before writing documents in this repository.** It is generated from the PM\'s own',
+    'edits in the workspace — not a summary of the repo, and not a style guide someone wrote once.',
+    'If a line below shows the PM rewriting the same kind of thing repeatedly, that is a correction',
+    'you can avoid provoking again.',
+    '',
+    `Generated ${nowISO()} from ${rows.length} recorded change${rows.length === 1 ? '' : 's'}.`,
+    '',
+    '## Documents changed most often', '',
+    ...hot.map(([f, n]) => `- \`${f}\` — ${n} change${n === 1 ? '' : 's'}`),
+    '',
+  ];
+  if (withReasons.length) {
+    out.push('## Why the PM changed things, in their words', '');
+    for (const r of withReasons) {
+      out.push(`- **${r.file}** — ${r.note}`);
+      if (r.before && r.after) {
+        out.push('  ```', '  - ' + String(r.before).split('\n')[0].slice(0, 160),
+                 '  + ' + String(r.after).split('\n')[0].slice(0, 160), '  ```');
+      }
+    }
+    out.push('');
+  }
+  out.push('## Most recent changes', '');
+  for (const r of recent) {
+    out.push(`- \`${r.file}\` · +${r.added} −${r.removed} at line ${r.at_line} · ${String(r.at).slice(0, 16).replace('T', ' ')}` +
+             (r.aligned_from ? ` · aligned with a change to \`${r.aligned_from}\`` : ''));
+  }
+  out.push('');
+  const target = path.join(dir, 'change-context.md');
+  try { fs.writeFileSync(target, out.join('\n')); return target; }
+  catch { return null; }
+}
+
 // ── Access guard (D62): loopback is token-free; every non-loopback peer needs the bearer token. ──
 // Peer-based: what matters is where the request came FROM, not which listener accepted it. With the
 // remote flag off there is no non-loopback listener, so this is transparent for local dev. Headers