@stravica-ai/digital-operator-pa 0.1.58 → 0.1.60

package/dist/engineering-pa-cli/README.md

@@ -106,8 +106,8 @@ pa work list [--project <id>] [--status ...] [--category ...]
 
 ### `pa knowledge` — query the operator's knowledge graph
 
-Reads `<repo-root>/operator/knowledge/.graph.json` and exposes five verbs
-for querying the operator's knowledge system. Feeds the third leg of the
+Reads `<repo-root>/operator/knowledge/.graph.json` and exposes five query
+verbs for the operator's knowledge system, plus `rebuild` for the graph itself. Feeds the third leg of the
 PA operating model — knowledge retrieval discipline — so agents can
 extract the right snippet at the right size instead of reading whole
 files.
@@ -118,8 +118,31 @@ pa knowledge search  <term> [--full]         # find docs matching a term
 pa knowledge domain  <name>                  # all docs in a domain + internal edges
 pa knowledge orphans [--exclude-stubs]       # docs with no inbound edges
 pa knowledge path    <a> <b>                 # shortest path between two docs
+pa knowledge rebuild [--format json]         # delete and rebuild the graph; prints nodes, edges, ms
 ```
 
+The graph is per-device and untracked. The first query builds it when it
+is absent; nothing schedules a rebuild, so run `pa knowledge rebuild`
+after the knowledge tree changes.
+
+**Scan roots.** The home `operator/knowledge/` and `core/knowledge/`, then
+each clone in `LIBRARY_KNOWLEDGE_EXTRA_ROOTS` (colon-separated clone
+roots). A clone is matched to its registry entry by its `origin` remote
+(normalised against `gitRemote`), else by its directory basename, using
+the company clone's `registry/repos.json` when that clone is among the
+roots, else the clone's own. For every mount whose `to` lies under
+`operator/knowledge/`, `<clone>/<from>` is read as workspace ids under
+`<to>`: hq and company `knowledge/` at `operator/knowledge/`, wsd
+`knowledge/` at `operator/knowledge/wsd/`, operator `voice/` at
+`operator/knowledge/writing/`. The legacy `<clone>/operator/knowledge/`
+form is still read during the path migration. On a colliding id the home
+copy wins, then the mapped copy (higher registry `precedence` first), then
+the legacy copy. Within one clone that holds both forms of an id, the
+legacy copy wins over the mapped one until the migration removes it: every
+writer has written the legacy form since the 2026-08-21 cutover, so it is
+the newer copy. A clone with no registry entry is read in the legacy form
+only.
+
 Global flag: `--format <table|json|mermaid>` (default: `table`). The
 `json` shape is stable-by-convention — `{ "verb": "<name>", ... }` —
 so downstream roles (e.g. `dispatch-briefer`) can pipe query output
@@ -136,7 +159,8 @@ ranking (title exact > title substring > body match, tie-break on
 edge count). Zero-result queries exit `0` — empty is a valid answer.
 
 **Exit codes**: `0` ok, `1` usage, `2` unknown/ambiguous slug or
-unknown domain, `3` IO (graph missing / unreadable).
+unknown domain, `3` IO (graph missing / unreadable, or `rebuild` could
+not write the artefacts).
 
 ### `pa staging-alias` — canonical staging.<site> alias for CF Workers sites
 

package/dist/engineering-pa-cli/src/knowledge/cli.mjs

@@ -1,12 +1,13 @@
 // cli.mjs — argv router for `pa knowledge <verb>`.
 //
-// Verbs (6):
+// Verbs (7):
 //   pa knowledge related <slug> [--in|--out]
 //   pa knowledge search  <term> [--full] [--strict]
 //   pa knowledge domain  <name>
 //   pa knowledge orphans [--exclude-stubs]
 //   pa knowledge path    <a> <b>
 //   pa knowledge eval    [--fixture PATH] [--out DIR] [--full] [--format ...]
+//   pa knowledge rebuild [--format table|json]
 //
 // Global flag:
 //   --format <table|json|mermaid>   default: table
@@ -17,9 +18,12 @@
 //
 // Exit codes (tooling standard §6):
 //   0 ok  |  1 usage  |  2 unknown-slug / ambiguous / unknown-domain
-//   3 IO (graph missing or unreadable)
+//   3 IO (graph missing or unreadable, or the rebuild failed)
 
-import { getRepoRoot, loadGraph, related, search, searchCascade, domain, orphans, path } from './graph.mjs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { BACKLINKS_RELATIVE_PATH, GRAPH_RELATIVE_PATH, getRepoRoot, loadGraph, related, search, searchCascade, domain, orphans, path } from './graph.mjs';
 import { formatRelated, formatSearch, formatDomain, formatOrphans, formatPath } from './formatters.mjs';
 import { loadOrphanPolicy, applyOrphanPolicy } from './orphan-policy.mjs';
 import { appendCallLog } from './call-log.mjs';
@@ -58,6 +62,10 @@ Usage:
                        [--out D]        orphan gauge, delta vs last run);
                        [--full]         persists to
                        [--format ...]   operator/knowledge/_meta/retrieval-eval-runs/
+  pa knowledge rebuild                 Delete and rebuild the per-device graph
+                                       (.graph.json and .backlinks.json) over
+                                       the home tree and every extra scan root,
+                                       then print nodes, edges and milliseconds
   pa knowledge -h, --help              Show this help
 
 Global flags:
@@ -73,9 +81,17 @@ Graph location: <repo-root>/operator/knowledge/.graph.json.
 Repo-root resolution: \$DAVE_REPO_ROOT / \$PA_REPO_ROOT, else walk upward
 from cwd looking for a .git entry.
 
-The graph is a per-device artefact: untracked, and rebuilt locally by
-library-sync-cycle's graph-rebuild leg. If it is absent, the first query
-rebuilds it on demand (one stderr line, then the answer) rather than failing.
+The graph is a per-device artefact: untracked, and built locally. If it is
+absent, the first query builds it on demand (one stderr line, then the
+answer) rather than failing. Run \`pa knowledge rebuild\` to refresh it after
+the knowledge tree changes; nothing schedules a rebuild.
+
+Scan roots: the home operator/knowledge/ and core/knowledge/, then each
+clone in \$LIBRARY_KNOWLEDGE_EXTRA_ROOTS (colon-separated). A clone with a
+registry entry is read through its knowledge mounts (<clone>/<from> composed
+at <to>, for every mount under operator/knowledge/), then in the legacy form
+<clone>/operator/knowledge/. On a colliding id the home copy wins, then the
+mapped copy, then the legacy copy.
 
 JSON output shape (stable-by-convention — consumed by dispatch-briefer):
   { "verb": "<name>", ...verb-specific fields }
@@ -98,6 +114,7 @@ export async function run(argv) {
       case 'domain':   return await doDomain(rest);
       case 'orphans':  return await doOrphans(rest);
       case 'path':     return await doPath(rest);
+      case 'rebuild':  return await doRebuild(rest);
       case 'context': {
         const { runContext } = await import('./context.mjs');
         return await runContext(rest);
@@ -261,4 +278,45 @@ async function doPath(args) {
   return 0;
 }
 
+async function doRebuild(args) {
+  const { positional, flags } = parseFlags(args);
+  const format = resolveFormat(flags);
+  if (positional.length > 0 || format === 'mermaid') {
+    process.stderr.write('usage: pa knowledge rebuild [--format table|json]\n');
+    return 1;
+  }
+  const repoRoot = await getRepoRoot();
+  for (const rel of [GRAPH_RELATIVE_PATH, BACKLINKS_RELATIVE_PATH]) {
+    try {
+      await rm(join(repoRoot, ...rel.split('/')), { force: true });
+    } catch (e) {
+      process.stderr.write(`[pa knowledge] could not delete ${rel}: ${e.message}\n`);
+      return 3;
+    }
+  }
+  // Same path as a first query on a missing graph: loadGraph builds it.
+  let built = null;
+  const silent = { write() { return true; } };
+  await loadGraph({ repoRoot, stderr: silent, onBuilt: (b) => { built = b; } });
+  if (!built) {
+    process.stderr.write('[pa knowledge] rebuild did not run: the graph was recreated by another process\n');
+    return 2;
+  }
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({
+      verb: 'rebuild',
+      graphPath: GRAPH_RELATIVE_PATH,
+      nodeCount: built.nodeCount,
+      edgeCount: built.edgeCount,
+      durationMs: built.durationMs,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(
+      `rebuilt ${GRAPH_RELATIVE_PATH}: ${built.nodeCount} nodes, ${built.edgeCount} edges, ${built.durationMs}ms\n`,
+    );
+  }
+  await logCall({ verb: 'rebuild', query: null, resultCount: built.nodeCount });
+  return 0;
+}
+
 export { USAGE };

package/dist/engineering-pa-cli/src/knowledge/graph.mjs

@@ -26,9 +26,10 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
-import { resolveExtraScanRoots } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
+import { locateScannedFile, resolveExtraScanRoots, scanSourcesFor } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
 
-const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
+export const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
+export const BACKLINKS_RELATIVE_PATH = 'operator/knowledge/.backlinks.json';
 
 // --- loader ---------------------------------------------------------------
 
@@ -55,8 +56,11 @@ const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
 // else, so building would silently answer a different question than the one
 // asked. Those callers keep the exit-3 refusal.
 //
-// Set `autoBuild: false` to opt out entirely.
-export async function loadGraph({ repoRoot, graphPath, autoBuild = true, stderr = process.stderr } = {}) {
+// Set `autoBuild: false` to opt out entirely. `onBuilt` receives the build
+// summary (counts and duration) when this call built the artefact;
+// `pa knowledge rebuild` deletes the artefacts and reads its numbers here,
+// so the explicit rebuild and the self-heal are one code path.
+export async function loadGraph({ repoRoot, graphPath, autoBuild = true, stderr = process.stderr, onBuilt = null } = {}) {
   const path = graphPath ?? join(repoRoot, GRAPH_RELATIVE_PATH);
   if (!existsSync(path)) {
     const canBuild = autoBuild && Boolean(repoRoot) && graphPath == null;
@@ -71,8 +75,9 @@ export async function loadGraph({ repoRoot, graphPath, autoBuild = true, stderr
       stderr.write(
         `[pa knowledge] no graph at ${path} -- built on demand ` +
         `(${built.nodeCount} nodes, ${built.edgeCount} edges, ${built.durationMs}ms); ` +
-        'retrieval artefacts are per-device and normally rebuilt by library-sync-cycle\n',
+        'retrieval artefacts are per-device; `pa knowledge rebuild` refreshes them\n',
       );
+      if (onBuilt) onBuilt(built);
     } catch (e) {
       // Both errors, in one message: "graph missing" alone sends the reader
       // looking for the artefact, when what they need to fix is why it could
@@ -635,6 +640,15 @@ function guidedMissHint(graph, term) {
   return { nearestDomains: ranked.slice(0, 3).map(([d]) => d) };
 }
 
+// `search --full` reads one body per node; resolving the scan list asks git
+// for each clone's remote, so resolve it once per root and env value.
+const scanSourcesCache = new Map();
+function cachedScanSources(repoRoot) {
+  const key = `${repoRoot}\n${process.env.LIBRARY_KNOWLEDGE_EXTRA_ROOTS ?? ''}`;
+  if (!scanSourcesCache.has(key)) scanSourcesCache.set(key, scanSourcesFor(repoRoot));
+  return scanSourcesCache.get(key);
+}
+
 async function readBody(repoRoot, id) {
   // The id is either a path relative to the repo root, or a bare slug.
   // We try repoRoot/<id> first, then repoRoot/operator/knowledge/<id>.
@@ -645,6 +659,16 @@ async function readBody(repoRoot, id) {
   // under the home repoRoot. The extra scan roots — same env var the
   // builders read — are checked in declared order after the home root, so
   // `--full` body search still finds the file.
+  //
+  // Registry mounts (w-2026-10-16-dave-019): the builders' own scan list is
+  // tried first, so a mapped id (`<clone>/knowledge/x.md` composed at
+  // `operator/knowledge/x.md`) opens the same copy the graph indexed.
+  const scanned = locateScannedFile(cachedScanSources(repoRoot), id);
+  if (scanned) {
+    try {
+      return await readFile(scanned, 'utf8');
+    } catch { return null; }
+  }
   const roots = [repoRoot, ...resolveExtraScanRoots()];
   for (const root of roots) {
     const candidates = [

package/dist/engineering-pa-cli/src/operator-attendance/cli.mjs

@@ -181,8 +181,20 @@ export function redactBashCommand(cmd) {
   // user:secret@host URL credential (do this BEFORE the KEY=VALUE pass
   // so the scheme:// does not accidentally feed the key regex).
   out = out.replace(/(https?:\/\/[^:/\s@]+):([^@\s'"`]+)@/gi, '$1:<redacted>@');
-  // Authorization header value (quoted or unquoted, Bearer or raw).
-  out = out.replace(/(Authorization\s*:\s*)(?:Bearer\s+)?([^\s'"`,;)]+)/gi, '$1<redacted>');
+  // Authorization header value (any scheme: Bearer, token, Basic,
+  // Digest, or an unknown word; and the raw-value no-scheme form). Three
+  // passes handle the single-quoted, double-quoted, and unquoted header
+  // forms. The quoted passes consume up to the closing quote so secrets
+  // that contain whitespace or inner punctuation (token schemes, Basic
+  // base64, Digest comma-separated field lists with inner "quoted"
+  // fields) never leak past the scheme word. 0.1.58 only redacted the
+  // scheme word for non-Bearer schemes, so `Authorization: token <x>`
+  // landed in the log as `Authorization: <redacted> <x>` (Dex's 0.1.58
+  // verification). 0.1.59 extends the redaction to the full header
+  // value.
+  out = out.replace(/'([^'\n]*?Authorization\s*:\s*)[^'\n]+(?=')/gi, (_m, pre) => `'${pre}<redacted>`);
+  out = out.replace(/"([^"\n]*?Authorization\s*:\s*)[^"\n]+(?=")/gi, (_m, pre) => `"${pre}<redacted>`);
+  out = out.replace(/(Authorization\s*:\s*)[^\s'"`,;)]+(?:\s+[^\s'"`,;)]+)?/gi, '$1<redacted>');
   // --token / --token=  and  token=
   out = out.replace(/(--?token[\s=]+)([^\s'"`;)]+)/gi, '$1<redacted>');
   // NAME=value (env-style). Match a word boundary that is not preceded

package/dist/engineering-pa-core/knowledge/platform-tooling/pa-cli-reference.md

@@ -17,7 +17,7 @@ The `pa` bin is the operator-facing top-level CLI. Every verb here is a subcomma
 | `pa workspace <verb>` | Workspace server lifecycle (start / stop / status / restart / open). |
 | `pa project <verb>` | Project state writes (create / status / doc add/rm/status / list). |
 | `pa work <verb>` | Work-item state writes (create / status / list). |
-| `pa knowledge <verb>` | Query the operator's knowledge graph (related / search / domain / orphans / path). |
+| `pa knowledge <verb>` | Query the operator's knowledge graph (related / search / domain / orphans / path); `rebuild` deletes and rebuilds the per-device graph. |
 | `pa autonomy <verb>` | Autonomy envelope get / set / list / init. |
 | `pa environment [verb]` | Environment cache read / refresh / extended. |
 | `pa lint <verb>` | Lint operator text against voice rules. |

package/dist/engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs

@@ -25,9 +25,9 @@
 
 import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
-import { join, resolve, dirname, relative } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildFileIndex, extractLinks, scanSourcesFor, toPosix, walkFiles } from './links.mjs';
+import { buildFileIndex, collectScannedFiles, extractLinks, scanSourcesFor } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
 import { findRepoRootSync } from '../../instance-root/find.mjs';
 
@@ -74,22 +74,13 @@ export async function buildBacklinkIndex({ root, coverage = null, extraRoots })
   // files exist, so the whole tree is collected before any link is read.
   //
   // Sources: home root first, then env-supplied extra scan roots (Wave H,
-  // w-2026-08-24-dave-033). Files are relativised against THEIR source root
-  // so ids are shape-compatible across the flat namespace. Home-wins on
-  // collision.
+  // w-2026-08-24-dave-033), each in its registry-mapped form and then its
+  // legacy form (w-2026-10-16-dave-019). Each scan names the id prefix its
+  // files take, so ids are shape-compatible across the flat namespace. First
+  // in wins on collision: home, then mapped, then legacy, except that a
+  // clone's legacy copy beats its own mapped copy (`legacySupersedes`).
   const sources = scanSourcesFor(root, { extraRoots });
-  const fileEntries = [];
-  const seenIds = new Set();
-  for (const { sourceRoot, scanDirs } of sources) {
-    for (const dir of scanDirs) {
-      for (const abs of await walkFiles(dir)) {
-        const id = toPosix(relative(sourceRoot, abs));
-        if (seenIds.has(id)) continue;
-        seenIds.add(id);
-        fileEntries.push({ abs, id });
-      }
-    }
-  }
+  const fileEntries = await collectScannedFiles(sources);
   const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));
 
   // Pass 2 — build backlinks map: target -> [sources]

package/dist/engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs

@@ -16,16 +16,17 @@
 
 import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
-import { join, resolve, dirname, relative } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   buildFileIndex,
   buildIndexHubs,
+  collectScannedFiles,
   deriveDomain,
   extractLinks,
   isIndexJson,
+  scanIdFor,
   scanSourcesFor,
-  toPosix,
   walkFiles,
 } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
@@ -94,33 +95,26 @@ function reportUnresolved(label, entries) {
  */
 export async function buildKnowledgeGraph({ root, coverage = null, extraRoots }) {
   // Sources: home root first, then each extra scan root (env-supplied by
-  // default). Files from an extra root are relativised against THEIR root,
-  // so their ids are still shaped `operator/knowledge/…` and merge into the
-  // same flat namespace as home. Home wins on collision (first-in policy).
+  // default) in its registry-mapped form, then in its legacy form. Each scan
+  // names the id prefix its files take, so ids are still shaped
+  // `operator/knowledge/...` and merge into the same flat namespace as home.
+  // First in wins on collision: home, then mapped, then legacy, except that a
+  // clone's legacy copy beats its own mapped copy (`legacySupersedes`).
   const sources = scanSourcesFor(root, { extraRoots });
 
   // ── Pass 1: enumerate the tree ────────────────────────────────────────
   // Resolution needs the whole file set before any link is interpreted —
   // `[[slug]]` cannot be resolved without knowing which files exist.
   //
-  // Each entry pairs the on-disk path with the source root it belongs to,
-  // so pass 2 can read the file from disk while emitting a source-relative
-  // id. Ids that collide keep the first occurrence (home-wins).
-  const fileEntries = [];
+  // Each entry pairs the on-disk path with its workspace id, so pass 2 can
+  // read the file from disk while emitting the id. Ids that collide keep the
+  // first occurrence (home, then mapped, then legacy), except that a clone's
+  // legacy copy replaces its own mapped copy (see collectScannedFiles).
+  const fileEntries = await collectScannedFiles(sources);
   const indexEntries = [];
-  const seenIds = new Set();
-  for (const { sourceRoot, scanDirs } of sources) {
-    for (const dir of scanDirs) {
-      for (const abs of await walkFiles(dir)) {
-        const id = toPosix(relative(sourceRoot, abs));
-        if (seenIds.has(id)) continue;
-        seenIds.add(id);
-        fileEntries.push({ abs, id });
-      }
-      for (const abs of await walkFiles(dir, isIndexJson)) {
-        const id = toPosix(relative(sourceRoot, abs));
-        indexEntries.push({ abs, id });
-      }
+  for (const scan of sources) {
+    for (const abs of await walkFiles(scan.dir, isIndexJson)) {
+      indexEntries.push({ abs, id: scanIdFor(scan, abs) });
     }
   }
   const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));

package/dist/engineering-pa-core/src/knowledge/retrieval/links.mjs

@@ -33,8 +33,11 @@
 // nowhere does not describe the estate — it inflates it, and every orphan
 // statistic computed over it is wrong in both directions.
 
+import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
-import { join, normalize, posix } from 'node:path';
+import { join, normalize, posix, relative } from 'node:path';
+
+import { resolveTierMounts } from './mounts.mjs';
 
 // Knowledge trees the builders scan, repo-root-relative.
 export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
@@ -57,6 +60,15 @@ export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
 // matches the retirement's repatriation rule ("HOME-REPO copy wins for
 // estate-native classes"); the intent is that canonical docs only ever live
 // on ONE side, and any collision is a symptom that needs resolving upstream.
+//
+// Registry mounts (w-2026-10-16-dave-019): an extra root that is a tier clone
+// is also read through its registry knowledge mounts, so `<clone>/knowledge/`
+// composes at `operator/knowledge/` (or `operator/knowledge/wsd/`, and
+// `<clone>/voice/` at `operator/knowledge/writing/`) exactly as the registry
+// says. Across clones a mapped copy beats a legacy one; within one clone the
+// legacy `<clone>/operator/knowledge/` copy beats the mapped copy during the
+// migration bridge (`legacySupersedes`); home still beats both. See
+// `scanSourcesFor` and mounts.mjs.
 export const EXTRA_SCAN_ROOTS_ENV = 'LIBRARY_KNOWLEDGE_EXTRA_ROOTS';
 
 /**
@@ -165,28 +177,164 @@ export function scanDirsFor(root) {
 }
 
 /**
- * Full scan-source list: the home workspace root first, then every extra
- * scan root from the environment. Each entry pairs a source root with the
- * scan dirs it contributes, so callers relativise ids against the SOURCE
- * root (yielding `operator/knowledge/…` shaped ids regardless of where on
- * disk the file lives).
+ * Full scan list, in collision-precedence order. Each entry names one
+ * directory to walk and the workspace-id prefix its files take, so every
+ * caller derives ids the same way (`scanIdFor`) and they stay shaped
+ * `operator/knowledge/...` regardless of where on disk the file lives.
  *
- * Home comes first so the first-wins collision policy resolves in favour
- * of the home workspace copy.
+ * Order (first wins on a colliding id):
+ *   1. the home workspace root (`operator/knowledge/`, `core/knowledge/`);
+ *   2. the MAPPED form of every extra root that resolves to a registry entry:
+ *      `<clone>/<from>` read as `<to>` for each mount whose `to` lies under
+ *      `operator/knowledge/` (see mounts.mjs). Higher registry `precedence`
+ *      first, declared order on a tie;
+ *   3. the LEGACY form of every extra root, `<clone>/operator/knowledge/` and
+ *      `<clone>/core/knowledge/`, in declared order. Home and legacy ids are
+ *      exactly the ids this function produced before mounts were read.
+ *
+ * So the home copy beats both forms, and a mapped copy beats another clone's
+ * legacy copy of the same id. Within ONE clone the legacy copy beats the
+ * mapped one; the order cannot say that, so the collision step applies it
+ * (`legacySupersedes`, `collectScannedFiles`). A clone with no registry entry
+ * contributes its legacy form only.
  *
  * @param {string} root the home workspace root
  * @param {object} [opts]
  * @param {NodeJS.ProcessEnv} [opts.env] defaults to process.env
  * @param {string[]} [opts.extraRoots] override the env-resolved list (tests)
- * @returns {{ sourceRoot: string, scanDirs: string[] }[]}
+ * @param {(root: string) => string|null} [opts.remoteOf] override the git
+ *   remote lookup (tests)
+ * @returns {{ sourceRoot: string, dir: string, idPrefix: string,
+ *   form: 'home'|'mapped'|'legacy', repo: string|null }[]}
  */
 export function scanSourcesFor(root, opts = {}) {
   const extras = opts.extraRoots ?? resolveExtraScanRoots(opts.env);
-  const sources = [{ sourceRoot: root, scanDirs: scanDirsFor(root) }];
-  for (const extra of extras) {
-    sources.push({ sourceRoot: extra, scanDirs: scanDirsFor(extra) });
+  const legacyScans = (sourceRoot, form, repo = null) => KNOWLEDGE_SCAN_DIRS.map((rel) => ({
+    sourceRoot,
+    dir: join(sourceRoot, ...rel.split('/')),
+    idPrefix: `${rel}/`,
+    form,
+    repo,
+  }));
+
+  const scans = legacyScans(root, 'home');
+  const tiers = extras.length ? resolveTierMounts(extras, { remoteOf: opts.remoteOf }) : [];
+
+  const mapped = tiers
+    .map((tier, order) => ({ tier, order }))
+    .filter(({ tier }) => tier.mounts.length > 0)
+    .sort((a, b) => (b.tier.precedence - a.tier.precedence) || (a.order - b.order));
+  for (const { tier } of mapped) {
+    for (const { from, to } of tier.mounts) {
+      scans.push({
+        sourceRoot: tier.root,
+        dir: join(tier.root, ...from.split('/').filter(Boolean)),
+        idPrefix: to,
+        form: 'mapped',
+        repo: tier.repo,
+      });
+    }
+  }
+
+  // slice 3 removes: the legacy `<clone>/operator/knowledge/` scan is the
+  // migration bridge for docs written at the workspace path (811 rows in the
+  // w-2026-10-16-dave-019 sizing). Drop it once those rows are re-put.
+  for (const tier of tiers) scans.push(...legacyScans(tier.root, 'legacy', tier.repo));
+
+  // An identity mount `operator/knowledge/ -> operator/knowledge/` would
+  // repeat its legacy scan; keep the first (mapped) occurrence only.
+  const seen = new Set();
+  return scans.filter((s) => {
+    const key = `${s.dir}\0${s.idPrefix}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Workspace id of a file found under `scan.dir`. */
+export function scanIdFor(scan, abs) {
+  return scan.idPrefix + toPosix(relative(scan.dir, abs));
+}
+
+// slice 3 removes: the within-tier bridge rule. The scan order cannot carry
+// it, because "legacy first within a clone" and "mapped first across clones"
+// are not one order: with copies in A legacy, A mapped and B mapped (A of
+// higher precedence) the two rules cycle. So the order picks the winning
+// TIER (first occurrence: home, mapped by precedence, legacy), and this rule
+// then swaps a mapped winner for the same clone's legacy copy. Every writer
+// wrote the legacy form after the 2026-08-21 cutover, so where one clone
+// holds both, the legacy copy is the newer (all 25 hq merge rows).
+/**
+ * True when `candidate` (met later in scan order) should replace `winner`,
+ * the scan that first claimed the same id.
+ *
+ * @param {ReturnType<typeof scanSourcesFor>[number]} winner
+ * @param {ReturnType<typeof scanSourcesFor>[number]} candidate
+ */
+export function legacySupersedes(winner, candidate) {
+  return winner.form === 'mapped' && candidate.form === 'legacy'
+    && winner.sourceRoot === candidate.sourceRoot;
+}
+
+/**
+ * Walk every scan and keep one file per workspace id: the first occurrence,
+ * except that a clone's legacy copy replaces that clone's mapped copy
+ * (`legacySupersedes`). A replaced entry keeps its position, so the entry
+ * order is still scan order of first occurrence.
+ *
+ * @param {ReturnType<typeof scanSourcesFor>} scans
+ * @returns {Promise<{ abs: string, id: string, scan: object }[]>}
+ */
+export async function collectScannedFiles(scans) {
+  const entries = [];
+  const byId = new Map();
+  for (const scan of scans) {
+    for (const abs of await walkFiles(scan.dir)) {
+      const id = scanIdFor(scan, abs);
+      const existing = byId.get(id);
+      if (!existing) {
+        const entry = { abs, id, scan };
+        byId.set(id, entry);
+        entries.push(entry);
+      } else if (legacySupersedes(existing.scan, scan)) {
+        existing.abs = abs;
+        existing.scan = scan;
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * The on-disk file that backs a workspace id, under the same precedence the
+ * builders apply (including `legacySupersedes`), or null. Lets body readers (`pa knowledge search --full`)
+ * open the copy the graph actually indexed.
+ *
+ * @param {ReturnType<typeof scanSourcesFor>} scans
+ * @param {string} id
+ * @returns {string|null}
+ */
+export function locateScannedFile(scans, id) {
+  const posixId = toPosix(id);
+  const fileIn = (scan) => {
+    if (!posixId.startsWith(scan.idPrefix)) return null;
+    const rest = posixId.slice(scan.idPrefix.length);
+    if (!rest || escapesRoot(posix.normalize(rest))) return null;
+    const candidate = join(scan.dir, ...rest.split('/'));
+    return existsSync(candidate) ? candidate : null;
+  };
+  for (const [i, scan] of scans.entries()) {
+    const found = fileIn(scan);
+    if (!found) continue;
+    for (const later of scans.slice(i + 1)) {
+      if (!legacySupersedes(scan, later)) continue;
+      const legacy = fileIn(later);
+      if (legacy) return legacy;
+    }
+    return found;
   }
-  return sources;
+  return null;
 }
 
 // ── File index ──────────────────────────────────────────────────────────────

package/dist/engineering-pa-core/src/knowledge/retrieval/mounts.mjs

@@ -0,0 +1,184 @@
+// mounts.mjs: registry knowledge mounts for the extra scan roots.
+//
+// Each tier clone named in LIBRARY_KNOWLEDGE_EXTRA_ROOTS is a library repo
+// whose registry entry (`registry/repos.json`, `repos.<name>.mounts[]`) says
+// which of its directories compose where in the workspace. The reader used to
+// ignore that and scan only `<clone>/operator/knowledge/`, so the correctly
+// mounted trees (`knowledge/ -> operator/knowledge/`,
+// `knowledge/ -> operator/knowledge/wsd/`, `voice/ -> operator/knowledge/writing/`)
+// were invisible while the mis-pathed legacy copies were visible
+// (w-2026-10-16-dave-019 sizing).
+//
+// This module resolves each clone to its registry entry and returns the
+// knowledge mounts the reader must apply: every mount whose `to` lies under
+// `operator/knowledge/`. Mounts that target anything else are ignored.
+//
+// Resolution order for a clone:
+//   1. its `origin` remote, normalised, against each entry's `gitRemote`;
+//   2. else the clone directory basename against the repo key.
+// Registry source order:
+//   1. the company clone's `registry/repos.json`, when the company clone is
+//      among the extra roots (it is the clone whose own entry mounts
+//      `registry/`, the registry source of truth);
+//   2. else the clone's own `registry/repos.json`;
+//   3. else no registry: the clone is scanned in the legacy form only.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+
+export const KNOWLEDGE_MOUNT_PREFIX = 'operator/knowledge/';
+export const REGISTRY_RELATIVE_PATH = 'registry/repos.json';
+
+/**
+ * Normalise a git remote URL to `host/owner/repo` (lowercase, no `.git`), so
+ * `git@github.com:Stravica/x.git`, `ssh://git@github.com/Stravica/x` and
+ * `https://github.com/Stravica/x.git` compare equal.
+ *
+ * @param {string|null|undefined} url
+ * @returns {string|null}
+ */
+export function normaliseRemote(url) {
+  if (typeof url !== 'string') return null;
+  let s = url.trim();
+  if (!s) return null;
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  s = s.replace(/^[^@/]+@/, '');
+  // scp-like `host:owner/repo`; a Windows drive letter is not a host.
+  s = s.replace(/^([^/:]{2,}):(?!\/)/, '$1/');
+  s = s.replace(/\/+$/, '').replace(/\.git$/i, '');
+  return s.toLowerCase();
+}
+
+/** Read the clone's `origin` URL, or null when it is not a git clone root. */
+export function gitRemoteOf(root) {
+  // A directory below some other repo would report that repo's remote, so
+  // only ask git when the root itself carries the `.git` entry.
+  if (!existsSync(join(root, '.git'))) return null;
+  try {
+    return execFileSync('git', ['-C', root, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Parse `<root>/registry/repos.json`; null when absent or unreadable. */
+export function readRegistry(root) {
+  const path = join(root, ...REGISTRY_RELATIVE_PATH.split('/'));
+  if (!existsSync(path)) return null;
+  try {
+    const json = JSON.parse(readFileSync(path, 'utf8'));
+    if (!json || typeof json.repos !== 'object' || json.repos === null) return null;
+    return json;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the registry entry for a clone: remote first, basename second.
+ *
+ * @returns {{ name: string, entry: object, via: 'remote'|'basename' } | null}
+ */
+export function resolveRepoEntry(registry, root, { remoteOf = gitRemoteOf } = {}) {
+  if (!registry || !registry.repos) return null;
+  const remote = normaliseRemote(remoteOf(root));
+  if (remote) {
+    for (const [name, entry] of Object.entries(registry.repos)) {
+      if (normaliseRemote(entry?.gitRemote) === remote) return { name, entry, via: 'remote' };
+    }
+  }
+  const base = basename(resolve(root));
+  const entry = registry.repos[base];
+  if (entry && typeof entry === 'object') return { name: base, entry, via: 'basename' };
+  return null;
+}
+
+const withSlash = (p) => (p.endsWith('/') ? p : `${p}/`);
+
+function isSafeRelative(p) {
+  return !p.startsWith('/') && !p.split('/').includes('..');
+}
+
+/**
+ * The mounts the knowledge reader applies: `to` under `operator/knowledge/`,
+ * `from` a safe clone-relative directory. Both come back with a trailing `/`.
+ *
+ * @param {object} entry a `repos.<name>` registry entry
+ * @returns {{ from: string, to: string }[]}
+ */
+export function knowledgeMounts(entry) {
+  const out = [];
+  for (const m of Array.isArray(entry?.mounts) ? entry.mounts : []) {
+    if (typeof m?.from !== 'string' || typeof m?.to !== 'string') continue;
+    const from = withSlash(m.from.replace(/^\.\//, ''));
+    const to = withSlash(m.to.replace(/^\.\//, ''));
+    if (!to.startsWith(KNOWLEDGE_MOUNT_PREFIX)) continue;
+    if (!isSafeRelative(from) || !isSafeRelative(to)) continue;
+    out.push({ from, to });
+  }
+  return out;
+}
+
+function mountsRegistry(entry) {
+  return (Array.isArray(entry?.mounts) ? entry.mounts : [])
+    .some((m) => typeof m?.from === 'string' && withSlash(m.from) === 'registry/');
+}
+
+/**
+ * Resolve every extra root to its tier and knowledge mounts.
+ *
+ * @param {string[]} extraRoots
+ * @param {object} [opts]
+ * @param {(root: string) => string|null} [opts.remoteOf] injectable for tests
+ * @returns {{
+ *   root: string,
+ *   repo: string|null,
+ *   via: 'remote'|'basename'|null,
+ *   registrySource: 'company'|'own'|null,
+ *   precedence: number,
+ *   mounts: { from: string, to: string }[],
+ * }[]}
+ */
+export function resolveTierMounts(extraRoots, { remoteOf = gitRemoteOf } = {}) {
+  const own = new Map();
+  for (const root of extraRoots) own.set(root, readRegistry(root));
+
+  // The company clone is the registry's own source: its entry mounts
+  // `registry/`. Prefer its copy over each clone's (possibly drifted) one.
+  let company = null;
+  for (const root of extraRoots) {
+    const registry = own.get(root);
+    const self = resolveRepoEntry(registry, root, { remoteOf });
+    if (self && mountsRegistry(self.entry)) { company = registry; break; }
+  }
+
+  return extraRoots.map((root) => {
+    let hit = null;
+    let registrySource = null;
+    if (company) {
+      hit = resolveRepoEntry(company, root, { remoteOf });
+      if (hit) registrySource = 'company';
+    }
+    if (!hit && own.get(root)) {
+      hit = resolveRepoEntry(own.get(root), root, { remoteOf });
+      if (hit) registrySource = 'own';
+    }
+    if (!hit) {
+      return { root, repo: null, via: null, registrySource: null, precedence: 0, mounts: [] };
+    }
+    const precedence = Number.isFinite(hit.entry.precedence) ? hit.entry.precedence : 0;
+    return {
+      root,
+      repo: hit.name,
+      via: hit.via,
+      registrySource,
+      precedence,
+      mounts: knowledgeMounts(hit.entry),
+    };
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "description": "Digital Operator PA: single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",