create-pmos 0.41.0 → 0.42.0

package/package.json

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

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ddb2c06
-assembled: 2026-10-03
+kernel-source: pmos@e99d9d4
+assembled: 2026-10-04
 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-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T01:33:06Z"}
 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-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T01:33:06Z"}
 status: stable
 ---
 

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-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T01:33:06Z"}
 status: stable
 ---
 

package/payload/state/log.md

@@ -2,6 +2,6 @@
 
 Newest first, ISO dates.
 
-## 2026-10-03
+## 2026-10-04
 
 - Adopted OKF v0.2 (D73).

package/workspace/README.md

@@ -82,6 +82,10 @@ After the session ends, `GET /api/next-step/summary` returns the files the branc
 
 The top of Today is a brief: a greeting, the day's calendar, ranked priorities and a worth-asking list. The server does not build it. The built-in skill `skills/morning-brief.skill` runs in an agent session, reads the sources the settings allow (calendar, wispr, mail, jira, confluence; mail is off by default) and the derived list (`pmos proactive today`), and submits one brief with `pmos proactive brief submit --file`. `POST /api/proactive/brief` checks it with `lib/brief.js` and stores `briefs/<date>.json` in the runtime state folder, replacing any earlier brief for the same day; `GET` returns the newest one with a `stale` flag when its date is not today. The check refuses, with the reason and without storing, a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, an over-long field, an item that rests on a source not reported as read, a source reported as read that the settings switched off, and a claim of typed scoring when that setting is off. The bucket is derived: under 0.5 confidence is "worth asking". The order is fixed: confidence, then PM-owned, then title. `POST /api/schedules/seed` with `set: "brief"` (one press in Today, or `pmos proactive brief schedule`) makes the daily 06:45 schedule once; as with every schedule, one made after its time of day runs once within a minute. The routes make no model or network call and write only the brief file. Typed scoring is a standing opt-in setting that is off by default. Tests: `proactive.test.js` G, H, I and `pm-r22-test.js` B1-B11. The guide page is `guide/proactive-engine.md`.
 
+## Find knowledge without reading whole files (`knowledge-graph`, slice K1)
+
+`pmos kg find|card|neighbors|section|why|stats` builds a map of the repository's tracked Markdown files from relations they already write down (links, frontmatter paths, `D<nn>` citations, `initiative_id`, `parent_kr`) and answers from it, so an agent reads one card or one section and not a 130 KB file. `lib/kg.js` is pure; `lib/kg-cli.js` reads the files, keeps the map in the runtime state directory (rebuilt when HEAD or an uncommitted `.md` changes) and writes nothing in the repository. A link to a missing file is listed as dangling and is never an edge; `lib/kg-dangling-rules.json` says which dangling links are history by design. It does not guess, use embeddings, or call a model or the network. `node scripts/kg-bench.js` replays two written strategies over the fixed questions in `planning/evals/knowledge-graph-questions.md`; it is a simulation, and says "NOT REPORTABLE" until three of the questions are the PM's. Guide page: `guide/knowledge-graph.md`. Tests: `kg.test.js`.
+
 ## Scheduled tasks from the terminal (`schedule-cli`)
 
 `pmos schedule` and `pmos skill` talk to the running workspace server, so the terminal and the workspace share one schedule store and one validator. Every change is saved the moment the command succeeds. A refused value names what is allowed and changes nothing. With no server running the command says so and exits 1.

package/workspace/bin/pmos.js

@@ -402,6 +402,10 @@ function doctor() {
     code = await require('../lib/proactive-cli').run(process.argv.slice(2), {
       say, call: async (m, p, b) => (port ? api(port, m, p, b) : null) });
   }
+  else if (cmd === 'kg') {
+    // Reads tracked .md files straight from disk (lib/kg-cli.js); needs no running server.
+    code = require('../lib/kg-cli').run(process.argv.slice(2), { say });
+  }
   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.
@@ -413,12 +417,13 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive]');
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive|kg]');
     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 schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
     say('  pmos skill …     list, read, create and edit skills');
     say('  pmos proactive … what is waiting for you, feedback, settings (pmos proactive --help)');
+    say('  pmos kg …       find a card, a section or a decision\'s citers without reading whole files (pmos kg --help)');
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {

package/workspace/guide/index.md

@@ -38,3 +38,4 @@ The workspace has three columns. [Layout](layout.md) explains where things open.
 - [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
 - [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
 - [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.
+- [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.

package/workspace/guide/knowledge-graph.md

@@ -0,0 +1,63 @@
+---
+type: Guide
+title: "Guide: find knowledge without reading whole files"
+timestamp: 2026-10-03
+---
+
+# Guide: find knowledge without reading whole files
+
+`pmos kg` reads the Markdown files of a repository and builds a map of how they point at each other. You use the map to find one card, one section or one decision's readers. You do not need to open a long file.
+
+## What it is, and what it is not
+
+A **card** is a short summary of one file: its title, its type, its `description` (or its first paragraph) and its size in tokens. A **section** is the lines under one heading.
+
+The map has an **edge** only where a file states a relation:
+
+| Edge | What states it |
+|---|---|
+| link | A Markdown link to a tracked file. |
+| frontmatter | A path in `prd_path`, `rubric_path`, `explainer_path` or `sources`. |
+| supersedes, amended_by, cites | A document that chooses to carry one of these keys. |
+| initiative | An `initiative_id` that names an initiative record. |
+| anchor | A `parent_kr` of `health:<id>` or a KR id. |
+| cites (mention) | A `D<nn>` in the text, such as `D65`, with two or more digits. |
+
+A link that points at a missing file is **dangling**. It is listed and never becomes an edge. A link, a `D<nn>` or a heading inside a code block or a code span is not read.
+
+It does not guess. A file that talks about a topic without a link, a path or a `D<nn>` is not connected to it. It does not use embeddings or a model, and it does not use the network.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pmos kg find <term>` | Lists cards whose id, title, headings or card contain the term, with the token size of each file. |
+| `pmos kg card <id>` | Prints one card and the headings of the file with their line ranges. |
+| `pmos kg neighbors <id> [--type T] [--depth 1\|2]` | Lists the files that link to this file or that it links to, with the type and the basis of each edge. |
+| `pmos kg section <path>#<heading>` | Prints only that section. `pmos kg section <path> <from>-<to>` prints a line range. |
+| `pmos kg why <D-id>` | Prints the decision's ADR view, its line in the amendment log of `DECISIONS.md`, and the files that cite it, grouped by kind. |
+| `pmos kg stats` | Prints counts: files, edges by type, written and derived cards, files with no incoming link, and the dangling links. |
+
+Add `--max-tokens N` to stop printing at a result boundary. The command then says how many results it did not show.
+
+An unknown file, heading or decision stops with a message that says what was not found. The exit code is 1.
+
+## What the numbers mean
+
+- A token count is the number of characters divided by four. It is an estimate.
+- `stats` splits dangling links into **history by design** and **needs a decision**. The rules are in `workspace/lib/kg-dangling-rules.json`. Read the file and change it if you disagree. A link in `okf/log.md` or in a decision about a removed document is history.
+- A file with no incoming link is not an error. It means no other file links to it.
+- A **derived** card comes from the first paragraph of a file that has no `description`.
+
+## Where the map is kept
+
+The command reads the tracked `.md` files of the Git repository you run it in. It keeps the map in the runtime state directory of the workspace, never in the repository. It builds the map again when the Git HEAD changes or when you edit a tracked `.md` file that is not yet committed. It does not use the cache for any other change.
+
+The command does not edit a file in the repository.
+
+## Limits
+
+- It finds only relations that are written in the files.
+- It reads Markdown files. It does not read the ledgers in `pmos/state/`, a connector, or a session.
+- `find` matches the words you type. It does not know that two different words mean the same thing.
+- The benchmark in `scripts/kg-bench.js` replays two written strategies over fixed questions. It is a simulation. It does not measure the tokens of a real agent session.

package/workspace/lib/kg-cli.js

@@ -0,0 +1,146 @@
+'use strict';
+/* kg-cli.js — `pmos kg …`: query the repository's knowledge graph from the terminal (knowledge-graph K1).
+ *
+ *   pmos kg find <term>                          cards whose id, title, headings or card match, with their token cost
+ *   pmos kg card <id>                            one card
+ *   pmos kg neighbors <id> [--type T] [--depth 1|2]
+ *   pmos kg section <path>#<heading>             the lines of one section
+ *   pmos kg section <path> <from>-<to>           a line range
+ *   pmos kg why <D-id>                           the decision's ADR view, its amendment-log line, and the files citing it
+ *   pmos kg stats                                counts, not claims
+ *   --max-tokens N                               stop at a card boundary and say how many results were not shown
+ *
+ * Reads the repository's tracked .md files straight from disk — no server, no model, no network. The graph is cached in
+ * the runtime state directory (never in the repository), keyed by git HEAD plus the modification times of uncommitted
+ * .md files, so a stale graph is rebuilt and a pull request never carries a graph diff. The only write is that cache.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const Kg = require('./kg');
+const { defaultRoot } = require('./state-root');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = ['find', 'card', 'neighbors', 'section', 'why', 'stats'];
+const RULES_FILE = path.join(__dirname, 'kg-dangling-rules.json');
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+
+function repoRoot(cwd) { return git(cwd, ['rev-parse', '--show-toplevel']).trim(); }
+
+function loadFiles(root) {
+  const out = []; const unreadable = [];
+  for (const rel of git(root, ['ls-files', '-z', '*.md']).split('\0').filter(Boolean)) {
+    try { out.push({ path: rel, text: fs.readFileSync(path.join(root, rel), 'utf8') }); }
+    catch (e) { unreadable.push({ path: rel, error: e.code || e.message }); }
+  }
+  return { files: out, unreadable };
+}
+
+function cacheKey(root) {
+  const head = git(root, ['rev-parse', 'HEAD']).trim();
+  const dirty = git(root, ['status', '--porcelain', '-z', '--untracked-files=no']).split('\0').filter(Boolean)
+    .map((l) => l.slice(3)).filter((p) => /\.md$/.test(p)).sort()
+    .map((p) => { try { return p + ':' + fs.statSync(path.join(root, p)).mtimeMs; } catch { return p + ':gone'; } });
+  return crypto.createHash('sha1').update(head + '\n' + dirty.join('\n')).digest('hex');
+}
+
+function graphFor(root, { stateDir = defaultRoot() } = {}) {
+  const dir = path.join(stateDir, 'kg');
+  const file = path.join(dir, crypto.createHash('sha1').update(root).digest('hex').slice(0, 12) + '.json');
+  const key = cacheKey(root);
+  try { const c = JSON.parse(fs.readFileSync(file, 'utf8')); if (c.key === key) return { graph: c.graph, unreadable: c.unreadable, cached: true }; } catch { /* rebuild */ }
+  const { files, unreadable } = loadFiles(root);
+  const graph = Kg.build(files);
+  try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify({ key, graph, unreadable })); } catch { /* the cache is an optimisation, never required */ }
+  return { graph, unreadable, cached: false };
+}
+
+function run(argv, { say, cwd = process.cwd(), stateDir } = {}) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  const fail = (m) => { say('✗ ' + m); return 1; };
+  if (group !== 'kg' || !verb || flags.help || verb === 'help') { say(`usage: pmos kg <${COMMANDS.join('|')}> …  [--max-tokens N]`); return verb ? 0 : 1; }
+  if (!COMMANDS.includes(verb)) return fail(`unknown command "${verb}" — use ${COMMANDS.join(', ')}`);
+  let root;
+  try { root = repoRoot(cwd); } catch { return fail('this is not a git repository, so there are no tracked files to read'); }
+  const { graph, unreadable, cached } = graphFor(root, { stateDir });
+  const budget = flags['max-tokens'] === undefined ? Infinity : Number(flags['max-tokens']);
+  if (!(budget > 0)) return fail('--max-tokens takes a positive number');
+  for (const u of unreadable || []) say(`not read — ${u.path}: ${u.error}`);
+
+  /* print blocks until the budget is spent, stopping at a block boundary; say how many were not shown */
+  const emit = (blocks) => {
+    let used = 0; let shown = 0;
+    for (const b of blocks) {
+      const cost = Kg.estTokens(b);
+      if (shown && used + cost > budget) break;
+      say(b); used += cost; shown++;
+    }
+    if (shown < blocks.length) say(`… ${blocks.length - shown} more result(s) not shown (--max-tokens ${budget}). ~${used} tokens printed.`);
+    else if (budget !== Infinity) say(`~${used} tokens printed.`);
+  };
+
+  if (verb === 'find') {
+    if (!pos[0]) return fail('find needs a term');
+    const hits = Kg.find(graph, pos.join(' '), { limit: 50 });
+    if (!hits.length) { say(`nothing matches "${pos.join(' ')}"`); return 0; }
+    emit(hits.map((h) => `${Kg.cardText(h.node)}\n    matched: ${h.where.join(', ')} · linked from ${h.indegree} file(s)`));
+    return 0;
+  }
+  if (verb === 'card') {
+    const n = Kg.nodeById(graph, pos[0]);
+    if (!n) return fail(`no file "${pos[0] || ''}" in the graph`);
+    say(Kg.cardText(n));
+    for (const h of n.headings) say(`${'  '.repeat(h.level - 1)}${h.text}  (lines ${h.start}-${h.end})`);
+    return 0;
+  }
+  if (verb === 'neighbors') {
+    const depth = flags.depth === undefined ? 1 : Number(flags.depth);
+    if (![1, 2].includes(depth)) return fail('--depth takes 1 or 2');
+    const rows = Kg.neighbors(graph, pos[0], { type: flags.type || null, depth });
+    if (!rows) return fail(`no file "${pos[0] || ''}" in the graph`);
+    if (!rows.length) { say('no neighbours' + (flags.type ? ` of type ${flags.type}` : '')); return 0; }
+    emit(rows.map((r) => `${r.direction === 'out' ? '→' : '←'} ${r.via} (${r.basis}${r.depth > 1 ? ', depth ' + r.depth : ''})  ${Kg.cardText(Kg.nodeById(graph, r.id))}`));
+    return 0;
+  }
+  if (verb === 'section') {
+    let id = pos[0] || ''; let spec = pos[1] || '';
+    const hash = id.indexOf('#');
+    if (hash > 0) { spec = id.slice(hash); id = id.slice(0, hash); }
+    const n = Kg.nodeById(graph, id);
+    if (!n) return fail(`no file "${id}" in the graph`);
+    if (!spec) return fail('section needs #heading or from-to');
+    const s = Kg.section(n, fs.readFileSync(path.join(root, id), 'utf8'), spec);
+    if (!s) return fail(`no section "${spec}" in ${id} — run: pmos kg card ${id}`);
+    say(`${id} lines ${s.from}-${s.to} (~${Kg.estTokens(s.text)} tokens of ${n.tokens_est})`);
+    say(s.text);
+    return 0;
+  }
+  if (verb === 'why') {
+    const w = Kg.why(graph, pos[0]);
+    if (!w) return fail(`no decision "${pos[0] || ''}" — the ADR views are okf/products/pmos/adr/dNN-*.md`);
+    say(Kg.cardText(w.adr));
+    say(w.amendmentLog ? `amendment log: ${w.amendmentLog.path} line ${w.amendmentLog.line}` : 'amendment log: no "Added **D…**" line found');
+    const blocks = [];
+    for (const [kind, rows] of Object.entries(w.citedBy).sort()) blocks.push(`${kind} (${rows.length}):\n` + rows.map((r) => `  ${r.id}  [${r.via.join('+')}, ${r.basis}]`).join('\n'));
+    emit(blocks.length ? blocks : ['no file cites this decision']);
+    return 0;
+  }
+  if (verb === 'stats') {
+    const rules = JSON.parse(fs.readFileSync(RULES_FILE, 'utf8'));
+    const s = Kg.stats(graph, rules);
+    say(`${s.nodes} files, ${s.edges} edges (${s.byBasis.stated} stated, ${s.byBasis.mention} mention) — graph ${cached ? 'from cache' : 'rebuilt'}`);
+    say('edges by type: ' + Object.entries(s.byType).sort().map(([k, v]) => `${k} ${v}`).join(', '));
+    say(`cards: ${s.cardsWritten} written (description), ${s.cardsDerived} derived from the first paragraph, ${s.noCard} none`);
+    say(`${s.noType} file(s) have no type · ${s.noIncoming} have no incoming link (index and log files excluded)`);
+    say(`dangling links: ${s.dangling} — ${s.danglingHistory} history by design (${path.relative(root, RULES_FILE) || RULES_FILE}), ${s.danglingNeedsDecision} need a decision`);
+    for (const d of s.needsDecision) say(`  ${d.from} → ${d.to}`);
+    say('Only relations written in the files are found. Token counts are characters ÷ 4, an estimate.');
+    return 0;
+  }
+  return 0;
+}
+
+module.exports = { run, graphFor, loadFiles, cacheKey, COMMANDS };

package/workspace/lib/kg-dangling-rules.json

@@ -0,0 +1,6 @@
+[
+  { "from": "^okf/log\\.md$", "why": "the OKF log records references to documents that were removed on purpose" },
+  { "from": "^okf/products/pmos/", "to": "(mcp-tools|data-model|references/metrics/v_)", "why": "D66 deleted the hosted-backend reference documents; the text that cites them is history" },
+  { "from": "/blind-plants/", "why": "a blind-plant specimen is planted with broken references on purpose" },
+  { "to": "^/planning/prd/x\\.md$", "why": "an example path in an explainer, not a reference" }
+]

package/workspace/lib/kg.js

@@ -0,0 +1,266 @@
+'use strict';
+/* kg.js — the repository's knowledge graph, derived from what its files already state (knowledge-graph K1).
+ *
+ * Pure: takes [{path, text}] for the tracked Markdown files and returns nodes, edges and the dangling links.
+ * No filesystem, no git, no network, no model. Same input → byte-identical output.
+ *
+ * WHAT IS A NODE. One tracked .md file. It carries a CARD (the frontmatter `description`, else the first paragraph,
+ * cut at 240 characters), a token estimate (characters ÷ 4 — an estimate, not a measurement), and its headings with
+ * line ranges so a caller can read ONE section and not the file.
+ *
+ * WHAT IS AN EDGE. Only a relation a file writes down:
+ *   link         a Markdown link to a tracked file                                  basis stated
+ *   frontmatter  a path in prd_path / rubric_path / explainer_path / sources        basis stated
+ *   supersedes · amended_by · cites   (typed keys a document opts into)             basis stated
+ *   initiative   initiative_id (frontmatter or an identity bullet) → its record     basis stated
+ *   anchor       parent_kr / parent_KR `health:<id>` or a KR id → the file naming it basis stated
+ *   cites        a `D<nn>` mention in prose → that decision's ADR view              basis mention
+ * A link to a file that does not exist is a DANGLING item, never an edge. A link-like string inside a code fence or
+ * an inline code span is not a relation and makes no edge. Nothing is inferred by similarity; workspace/lib/
+ * related-docs.js took the same position for alignment, for the same reason.
+ *
+ * `D<nn>` needs two or more digits on purpose: slice labels such as "D1" and "D3" in the proactive-engine documents
+ * would otherwise cite decisions D01 and D03 that they never mention.
+ */
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.Kg = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const CARD_MAX = 240;
+  const ADR_DIR = 'okf/products/pmos/adr/';
+  const PATH_KEYS = ['prd_path', 'rubric_path', 'explainer_path', 'sources'];
+  const TYPED_KEYS = ['supersedes', 'amended_by', 'cites'];
+  const estTokens = (s) => Math.ceil(String(s || '').length / 4);
+
+  /* Replace fenced code blocks and inline code spans with spaces of the same length, keeping every newline, so line
+   * numbers stay true and nothing inside code is read as a link, a citation or a heading. */
+  function stripCode(text) {
+    const blank = (s) => s.replace(/[^\n]/g, ' ');
+    let out = '';
+    let fence = null;
+    for (const line of String(text || '').split('\n')) {
+      const m = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+      if (fence) { out += blank(line) + '\n'; if (m && m[1][0] === fence[0] && m[1].length >= fence.length) fence = null; continue; }
+      if (m) { fence = m[1]; out += blank(line) + '\n'; continue; }
+      out += line.replace(/(`+)[^`\n]*?\1/g, (s) => blank(s)) + '\n';
+    }
+    return out.slice(0, -1);
+  }
+
+  /* Frontmatter values come from the reader workspace/lib/related-docs.js already ships (one-line `key: value`);
+   * the body start line is the only thing computed here. */
+  const readFm = (typeof require === 'function') ? require('./related-docs').frontmatter : null;
+  function frontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(String(text || ''));
+    if (!m) return { fm: {}, bodyStart: 1 };
+    return { fm: readFm ? readFm(text) : {}, bodyStart: m[0].split('\n').length };
+  }
+
+  function headingsOf(stripped, bodyStart) {
+    const lines = stripped.split('\n');
+    const found = [];
+    for (let i = bodyStart - 1; i < lines.length; i++) {
+      const m = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(lines[i]);
+      if (m) found.push({ level: m[1].length, text: m[2].trim(), start: i + 1 });
+    }
+    for (let k = 0; k < found.length; k++) {
+      let end = lines.length;
+      for (let j = k + 1; j < found.length; j++) if (found[j].level <= found[k].level) { end = found[j].start - 1; break; }
+      found[k].end = end;
+    }
+    return found;
+  }
+
+  function cardOf(fm, stripped, bodyStart) {
+    if (fm.description) return fm.description.slice(0, CARD_MAX);
+    const lines = stripped.split('\n').slice(bodyStart - 1);
+    const para = [];
+    for (const raw of lines) {
+      const l = raw.trim();
+      if (!l) { if (para.length) break; continue; }
+      if (/^(#|\||>|---|[-*]\s|\d+\.\s|<)/.test(l)) { if (para.length) break; continue; }
+      para.push(l);
+    }
+    return para.join(' ').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').slice(0, CARD_MAX);
+  }
+
+  const norm = (from, target) => {
+    const t = target.replace(/^<|>$/g, '');
+    const parts = (t.startsWith('/') ? t.slice(1) : from.replace(/[^/]*$/, '') + t).split('/');
+    const out = [];
+    for (const p of parts) { if (p === '.' || p === '') continue; if (p === '..') out.pop(); else out.push(p); }
+    return out.join('/');
+  };
+
+  const pathsIn = (value) => [...String(value || '').matchAll(/[\w@./-]+\.md\b/g)].map((m) => m[0].replace(/^\//, ''));
+
+  function build(files) {
+    const list = (files || []).filter((f) => f && typeof f.path === 'string').sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const have = new Set(list.map((f) => f.path));
+    const adrFor = new Map();
+    for (const p of have) { const m = /^okf\/products\/pmos\/adr\/d(\d{2,3})-/.exec(p); if (m) adrFor.set('D' + m[1], p); }
+    const krFile = new Map();
+    for (const f of list) if (f.path.startsWith('planning/okrs/')) for (const m of f.text.matchAll(/\bO\d+\.KR\d+\b/g)) if (!krFile.has(m[0])) krFile.set(m[0], f.path);
+    const budgets = have.has('planning/okrs/health-budgets.md') ? 'planning/okrs/health-budgets.md' : null;
+
+    const nodes = [];
+    const edges = new Map();
+    const dangling = [];
+    const meta = { decisionLines: {} };
+    const addEdge = (from, to, type, basis) => {
+      if (from === to || !have.has(to)) return;
+      const key = from + '\u0000' + to + '\u0000' + type;
+      const cur = edges.get(key);
+      if (!cur) edges.set(key, { from, to, type, basis });
+      else if (cur.basis === 'mention' && basis === 'stated') cur.basis = 'stated';
+    };
+
+    for (const f of list) {
+      const text = String(f.text || '');
+      const { fm, bodyStart } = frontmatter(text);
+      const stripped = stripCode(text);
+      const body = stripped;
+      const heads = headingsOf(stripped, bodyStart);
+      const title = fm.title || (heads.find((h) => h.level === 1) || {}).text || f.path;
+      nodes.push({
+        id: f.path, title, type: fm.type || null, card: cardOf(fm, stripped, bodyStart),
+        described: !!fm.description, tokens_est: estTokens(text), lines: text.split('\n').length,
+        headings: heads.map((h) => ({ level: h.level, text: h.text, start: h.start, end: h.end })),
+        status: fm.status || null, stale_after: fm.stale_after || null,
+      });
+
+      for (const m of body.matchAll(/\]\(([^)\s]+?)(?:#[^)]*)?\)/g)) {
+        const raw = m[1];
+        if (/^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('#')) continue;
+        if (!/\.md$/i.test(raw)) continue;
+        const to = norm(f.path, raw);
+        if (have.has(to)) addEdge(f.path, to, 'link', 'stated');
+        else dangling.push({ from: f.path, to: raw });
+      }
+      for (const m of body.matchAll(/\bD(\d{2,3})\b/g)) {
+        const to = adrFor.get('D' + m[1]);
+        if (to) addEdge(f.path, to, 'cites', 'mention');
+      }
+      for (const k of PATH_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, 'frontmatter', 'stated');
+      for (const k of TYPED_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, k, 'stated');
+      const ini = fm.initiative_id || ((/^[-*]?\s*initiative_id:\s*([\w.-]+)/m.exec(body) || [])[1]);
+      if (ini) addEdge(f.path, 'planning/initiatives/' + ini + '.md', 'initiative', 'stated');
+      const anchor = fm.parent_kr || fm.parent_KR || ((/^[-*]?\s*parent_kr:\s*([\w:.-]+)/im.exec(body) || [])[1]);
+      if (anchor) {
+        if (/^health:/.test(anchor) && budgets) addEdge(f.path, budgets, 'anchor', 'stated');
+        else if (krFile.has(anchor)) addEdge(f.path, krFile.get(anchor), 'anchor', 'stated');
+      }
+      if (f.path === 'DECISIONS.md') {
+        const lines = body.split('\n');
+        for (let i = 0; i < lines.length; i++) { const m = /\bAdded \*\*(D\d{2,3})\*\*/.exec(lines[i]); if (m && !(m[1] in meta.decisionLines)) meta.decisionLines[m[1]] = i + 1; }
+      }
+    }
+    const e = [...edges.values()].sort((a, b) => (a.from + a.to + a.type < b.from + b.to + b.type ? -1 : 1));
+    dangling.sort((a, b) => (a.from + a.to < b.from + b.to ? -1 : a.from + a.to > b.from + b.to ? 1 : 0));
+    return { nodes, edges: e, dangling, meta };
+  }
+
+  /* Split dangling links into "history by design" and "needs a decision" by a readable rule list:
+   * [{from?: regex, to?: regex, why: string}] — a rule matches when every field it names matches. */
+  function splitDangling(graph, rules) {
+    const compiled = (rules || []).map((r) => ({ from: r.from ? new RegExp(r.from) : null, to: r.to ? new RegExp(r.to) : null, why: r.why || '' }));
+    const history = []; const needs = [];
+    for (const d of graph.dangling) {
+      const r = compiled.find((x) => (x.from || x.to) && (!x.from || x.from.test(d.from)) && (!x.to || x.to.test(d.to)));
+      if (r) history.push({ ...d, why: r.why }); else needs.push(d);
+    }
+    return { history, needs };
+  }
+
+  function stats(graph, rules) {
+    const byType = {}; const byBasis = { stated: 0, mention: 0 };
+    for (const e of graph.edges) { byType[e.type] = (byType[e.type] || 0) + 1; byBasis[e.basis]++; }
+    const inbound = new Set(graph.edges.map((e) => e.to));
+    const orphans = graph.nodes.filter((n) => !inbound.has(n.id) && !/(^|\/)(index|log)\.md$/.test(n.id)).length;
+    const split = splitDangling(graph, rules);
+    return {
+      nodes: graph.nodes.length, edges: graph.edges.length, byType, byBasis,
+      cardsWritten: graph.nodes.filter((n) => n.described).length,
+      cardsDerived: graph.nodes.filter((n) => !n.described && n.card).length,
+      noCard: graph.nodes.filter((n) => !n.card).length,
+      noType: graph.nodes.filter((n) => !n.type).length,
+      noIncoming: orphans, dangling: graph.dangling.length,
+      danglingHistory: split.history.length, danglingNeedsDecision: split.needs.length, needsDecision: split.needs,
+    };
+  }
+
+  const nodeById = (graph, id) => graph.nodes.find((n) => n.id === id) || null;
+  const cardText = (n) => `${n.id} [${n.type || 'untyped'}] ${n.title}${n.card ? ' — ' + n.card : ''} (file ~${n.tokens_est} tokens)`;
+
+  /* Rank: where the term matches (id 3, title 3, heading 2, card 1), then how many files link to the node. */
+  function find(graph, term, { limit = 20 } = {}) {
+    const t = String(term || '').toLowerCase().trim();
+    if (!t) return [];
+    const indeg = new Map();
+    for (const e of graph.edges) indeg.set(e.to, (indeg.get(e.to) || 0) + 1);
+    const out = [];
+    for (const n of graph.nodes) {
+      let score = 0; const where = [];
+      if (n.id.toLowerCase().includes(t)) { score += 3; where.push('id'); }
+      if (n.title.toLowerCase().includes(t)) { score += 3; where.push('title'); }
+      const h = n.headings.find((x) => x.text.toLowerCase().includes(t));
+      if (h) { score += 2; where.push('heading "' + h.text + '"'); }
+      if ((n.card || '').toLowerCase().includes(t)) { score += 1; where.push('card'); }
+      if (score) out.push({ node: n, score, where, indegree: indeg.get(n.id) || 0 });
+    }
+    return out.sort((a, b) => b.score - a.score || b.indegree - a.indegree || (a.node.id < b.node.id ? -1 : 1)).slice(0, limit);
+  }
+
+  function neighbors(graph, id, { type = null, depth = 1 } = {}) {
+    if (!nodeById(graph, id)) return null;
+    const seen = new Map([[id, 0]]); const rows = [];
+    let frontier = [id];
+    for (let d = 1; d <= depth; d++) {
+      const next = [];
+      for (const e of graph.edges) {
+        if (type && e.type !== type) continue;
+        for (const [a, b, dir] of [[e.from, e.to, 'out'], [e.to, e.from, 'in']]) {
+          if (!frontier.includes(a) || seen.has(b)) continue;
+          seen.set(b, d); next.push(b); rows.push({ id: b, via: e.type, basis: e.basis, direction: dir, depth: d, from: a });
+        }
+      }
+      frontier = next;
+    }
+    return rows;
+  }
+
+  /* why("D65"): the ADR view, the amendment-log line in DECISIONS.md, and every file that cites the ADR, by kind. */
+  function why(graph, dId) {
+    const id = String(dId || '').toUpperCase().replace(/^D(\d)$/, 'D0$1');
+    const adr = graph.nodes.find((n) => n.id.startsWith(ADR_DIR + id.toLowerCase() + '-'));
+    if (!adr) return null;
+    const groups = {};
+    const byFrom = new Map();
+    for (const e of graph.edges) if (e.to === adr.id) {
+      const cur = byFrom.get(e.from) || { id: e.from, via: [], basis: 'mention' };
+      if (!cur.via.includes(e.type)) cur.via.push(e.type);
+      if (e.basis === 'stated') cur.basis = 'stated';
+      byFrom.set(e.from, cur);
+    }
+    for (const r of byFrom.values()) { const n = nodeById(graph, r.id); const k = (n && n.type) || 'untyped'; r.via.sort(); (groups[k] = groups[k] || []).push(r); }
+    for (const k of Object.keys(groups)) groups[k].sort((a, b) => (a.id < b.id ? -1 : 1));
+    const line = graph.meta && graph.meta.decisionLines ? graph.meta.decisionLines[id] || null : null;
+    return { decision: id, adr, amendmentLog: line ? { path: 'DECISIONS.md', line } : null, citedBy: groups };
+  }
+
+  /* section(node, text, spec): spec is "#heading words" or "from-to". Returns {from,to,text} or null. */
+  function section(node, text, spec) {
+    const lines = String(text || '').split('\n');
+    const m = /^(\d+)-(\d+)$/.exec(spec || '');
+    if (m) { const from = Math.max(1, +m[1]); const to = Math.min(lines.length, +m[2]); if (from > to) return null; return { from, to, text: lines.slice(from - 1, to).join('\n') }; }
+    const want = String(spec || '').replace(/^#/, '').trim().toLowerCase();
+    if (!want || !node) return null;
+    const h = node.headings.find((x) => x.text.toLowerCase() === want) || node.headings.find((x) => x.text.toLowerCase().includes(want));
+    if (!h) return null;
+    return { from: h.start, to: h.end, heading: h.text, text: lines.slice(h.start - 1, h.end).join('\n') };
+  }
+
+  return { build, stats, splitDangling, find, neighbors, why, section, nodeById, cardText, stripCode, frontmatter, estTokens, ADR_DIR };
+});

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js",
+    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",