@stravica-ai/digital-operator-pa 0.1.31 → 0.1.32

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

@@ -26,6 +26,7 @@
 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';
 
 const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
 
@@ -637,15 +638,25 @@ function guidedMissHint(graph, term) {
 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>.
-  const candidates = [
-    resolve(repoRoot, id),
-    resolve(repoRoot, 'operator', 'knowledge', id),
-  ];
-  for (const path of candidates) {
-    if (existsSync(path)) {
-      try {
-        return await readFile(path, 'utf8');
-      } catch { return null; }
+  //
+  // Extra scan roots (Wave H, w-2026-08-24-dave-033): a doc merged into the
+  // graph from a pull-clone at `~/stravica-library-clones/<tier>/` has an id
+  // shaped `operator/knowledge/<domain>/<file>.md` but is not resolvable
+  // 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.
+  const roots = [repoRoot, ...resolveExtraScanRoots()];
+  for (const root of roots) {
+    const candidates = [
+      resolve(root, id),
+      resolve(root, 'operator', 'knowledge', id),
+    ];
+    for (const path of candidates) {
+      if (existsSync(path)) {
+        try {
+          return await readFile(path, 'utf8');
+        } catch { return null; }
+      }
     }
   }
   return null;

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

@@ -27,7 +27,7 @@ import { readFile } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildFileIndex, extractLinks, scanDirsFor, toPosix, walkFiles } from './links.mjs';
+import { buildFileIndex, extractLinks, scanSourcesFor, toPosix, walkFiles } from './links.mjs';
 import { writeJsonAtomic } from './write-atomic.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -64,23 +64,35 @@ Output: operator/knowledge/.backlinks.json
  *   writes a minimal one. Readers treat it as optional either way.
  * @returns {Promise<{outPath:string, targetCount:number, unresolved:object[]}>}
  */
-export async function buildBacklinkIndex({ root, coverage = null }) {
+export async function buildBacklinkIndex({ root, coverage = null, extraRoots }) {
   // Pass 1 — enumerate. `[[slug]]` cannot be resolved without knowing which
   // files exist, so the whole tree is collected before any link is read.
-  const allFiles = [];
-  for (const dir of scanDirsFor(root)) {
-    allFiles.push(...await walkFiles(dir));
+  //
+  // 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.
+  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 fileIds = allFiles.map((f) => toPosix(relative(root, f)));
-  const fileIndex = buildFileIndex(fileIds);
+  const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));
 
   // Pass 2 — build backlinks map: target -> [sources]
   const backlinks = {};
   const unresolved = [];
 
-  for (let i = 0; i < allFiles.length; i++) {
-    const content = await readFile(allFiles[i], 'utf8');
-    const relSource = fileIds[i];
+  for (const { abs, id: relSource } of fileEntries) {
+    const content = await readFile(abs, 'utf8');
     const result = extractLinks(content, relSource, fileIndex);
     unresolved.push(...result.unresolved);
 

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

@@ -24,7 +24,7 @@ import {
   deriveDomain,
   extractLinks,
   isIndexJson,
-  scanDirsFor,
+  scanSourcesFor,
   toPosix,
   walkFiles,
 } from './links.mjs';
@@ -87,20 +87,38 @@ function reportUnresolved(label, entries) {
  * @returns {Promise<object>}  outPath, counts, diagnostics and the unresolved
  *   entries the CLI reports
  */
-export async function buildKnowledgeGraph({ root, coverage = null }) {
-  const scanDirs = scanDirsFor(root);
+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).
+  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.
-  const allFiles = [];
-  const indexPaths = [];
-  for (const dir of scanDirs) {
-    allFiles.push(...await walkFiles(dir));
-    indexPaths.push(...await walkFiles(dir, isIndexJson));
+  //
+  // 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 = [];
+  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 });
+      }
+    }
   }
-  const fileIds = allFiles.map((f) => toPosix(relative(root, f)));
-  const fileIndex = buildFileIndex(fileIds);
+  const fileIndex = buildFileIndex(fileEntries.map((e) => e.id));
 
   // ── Pass 2: nodes + forward edges ─────────────────────────────────────
   const nodesMap = new Map();
@@ -115,10 +133,8 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
     edges.push({ from, to, type });
   };
 
-  for (let i = 0; i < allFiles.length; i++) {
-    const filePath = allFiles[i];
-    const relPath = fileIds[i];
-    const content = await readFile(filePath, 'utf8');
+  for (const { abs, id: relPath } of fileEntries) {
+    const content = await readFile(abs, 'utf8');
     const title = extractTitle(content) || relPath.split('/').pop().replace('.md', '');
 
     nodesMap.set(relPath, { id: relPath, title, domain: deriveDomain(relPath) });
@@ -130,8 +146,7 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
 
   // ── index.json hubs ───────────────────────────────────────────────────
   const indexFiles = [];
-  for (const indexPath of indexPaths) {
-    const id = toPosix(relative(root, indexPath));
+  for (const { abs: indexPath, id } of indexEntries) {
     let data;
     try {
       data = JSON.parse(await readFile(indexPath, 'utf8'));
@@ -180,7 +195,7 @@ export async function buildKnowledgeGraph({ root, coverage = null }) {
     version: '1.0',
     generatedAt: new Date().toISOString(),
     diagnostics: {
-      markdownFiles: allFiles.length,
+      markdownFiles: fileEntries.length,
       indexHubs: {
         files: indexFiles.length,
         entries: hubs.entryCount,

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

@@ -39,6 +39,50 @@ import { join, normalize, posix } from 'node:path';
 // Knowledge trees the builders scan, repo-root-relative.
 export const KNOWLEDGE_SCAN_DIRS = ['operator/knowledge', 'core/knowledge'];
 
+// Environment variable that names ADDITIONAL scan roots beyond the workspace
+// root. Colon-separated absolute paths, each pointing at a directory shaped
+// like a workspace root (i.e. containing an `operator/knowledge/` subtree).
+//
+// Motivation (Wave H, w-2026-08-24-dave-033): the REMOTE-mode read path is
+// `~/stravica-library-clones/<tier>/`. Each tier repo carries its own
+// `operator/knowledge/**` tree, and canonical knowledge lives in those tier
+// repos — not in the home workspace. Without extra scan roots, `pa knowledge`
+// on an operator host misses every canonical doc. Extra roots let the builders
+// merge tier-repo content into the SAME graph the home tree produces, so node
+// ids are still `operator/knowledge/<domain>/<file>.md` regardless of which
+// root supplied the file.
+//
+// Collision policy: FIRST WINS. The home workspace root is scanned first, so
+// a doc present in both home and a tier clone keeps the home copy. This
+// 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.
+export const EXTRA_SCAN_ROOTS_ENV = 'LIBRARY_KNOWLEDGE_EXTRA_ROOTS';
+
+/**
+ * Read + normalise the extra scan roots from the environment. Returns an
+ * array of absolute paths (deduped, in declared order). Missing / empty
+ * entries are silently skipped so a stray colon never manufactures a bogus
+ * root.
+ *
+ * @param {NodeJS.ProcessEnv} [env] defaults to process.env
+ * @returns {string[]}
+ */
+export function resolveExtraScanRoots(env = process.env) {
+  const raw = env[EXTRA_SCAN_ROOTS_ENV];
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+  const seen = new Set();
+  const out = [];
+  for (const part of raw.split(':')) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
 const WIKI_RE = /\[\[([^\]]+)\]\]/g;
 const MD_LINK_RE = /\[([^\]]*)\]\(([^)]+)\)/g;
 const EXTERNAL_RE = /^(?:https?:\/\/|mailto:|#)/;
@@ -120,6 +164,31 @@ export function scanDirsFor(root) {
   return KNOWLEDGE_SCAN_DIRS.map((rel) => join(root, ...rel.split('/')));
 }
 
+/**
+ * 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).
+ *
+ * Home comes first so the first-wins collision policy resolves in favour
+ * of the home workspace copy.
+ *
+ * @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[] }[]}
+ */
+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) });
+  }
+  return sources;
+}
+
 // ── File index ──────────────────────────────────────────────────────────────
 
 function pushInto(map, key, value) {

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

@@ -18,6 +18,7 @@ import { runFlush } from './verbs/flush.mjs';
 import { runGet } from './verbs/get.mjs';
 import { runSearch } from './verbs/search.mjs';
 import { runStatus } from './verbs/status.mjs';
+import { runRefreshClones } from './verbs/refresh-clones.mjs';
 
 const USAGE = `library — REMOTE-mode client for the remote-library service.
 
@@ -27,6 +28,7 @@ Usage:
   library get <path>
   library search <query> [--files-only]
   library status [--json]
+  library refresh-clones [--json] [--timeout-ms <n>] [--tier <name>]...
   library -h | --help
 
 Reads config from operator/config/preferences.json (+ preferences.local.json overlay).
@@ -86,6 +88,7 @@ export async function main(argv, seams = {}) {
       case 'get':      return await runGet({ ...ctx, args: parseGet(rest) });
       case 'search':   return await runSearch({ ...ctx, args: parseSearch(rest) });
       case 'status':   return await runStatus({ ...ctx, args: parseStatus(rest) });
+      case 'refresh-clones': return await runRefreshClones({ ...ctx, args: parseRefreshClones(rest) });
       default:
         err(`[library] unknown verb: ${verb}`);
         log(USAGE);
@@ -140,3 +143,17 @@ function parseStatus(argv) {
   });
   return { json: values.json };
 }
+function parseRefreshClones(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    allowPositionals: false,
+    options: {
+      json:         { type: 'boolean', default: false },
+      'timeout-ms': { type: 'string' },
+      tier:         { type: 'string', multiple: true },
+    },
+  });
+  const timeoutMs = values['timeout-ms'] ? parseInt(values['timeout-ms'], 10) : undefined;
+  return { json: values.json, timeoutMs, tiers: values.tier };
+}

package/dist/engineering-pa-library-cli/src/verbs/refresh-clones.mjs

@@ -0,0 +1,153 @@
+// verbs/refresh-clones.mjs — `library refresh-clones`
+//
+// REMOTE-mode session-boot verb: refreshes every tier clone under the
+// pull-clones root by running `git fetch --quiet origin` then
+// `git pull --ff-only --quiet origin main` for each. Called from the
+// session-boot hook (Wave H, w-2026-08-24-dave-033) so `pa knowledge`
+// reads the freshest projection of the tier repos.
+//
+// Design notes:
+//   - Q4 boot-only refresh: this verb is meant to be invoked from the
+//     session-boot path (Claude Code SessionStart hook, `pa environment`
+//     adjacency). It is NOT a cron / launchd job — the retirement plan
+//     is boot-only refresh v1.
+//   - Parallel per tier. Total wall time is dominated by the slowest
+//     tier's fetch; per-tier timeout keeps a wedged remote from
+//     blocking session start.
+//   - Refuses to touch a tier clone with uncommitted local changes
+//     (`git status --porcelain` non-empty) — pull-clones are a
+//     read-only projection per spec §3.3 and any local edit is a
+//     corruption signal, not a merge target.
+//   - Exit code 0 iff every tier refreshed successfully. Any per-tier
+//     failure surfaces on stderr and produces a non-zero exit so the
+//     session-boot hook logs it.
+
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { pullClonesRootExists, resolvePullClonesRoot } from '../pull-clones.mjs';
+
+const DEFAULT_TIER_TIMEOUT_MS = 20_000;
+
+/**
+ * @param {object} ctx
+ * @param {object} ctx.config
+ * @param {object} [ctx.args]                 { json?, timeoutMs?, tiers? }
+ * @param {(...m:unknown[])=>void} [ctx.log]
+ * @param {(...m:unknown[])=>void} [ctx.err]
+ * @param {(args:string[], cwd:string, opts?:object)=>Promise<{code:number, stdout:string, stderr:string}>} [ctx.git]
+ * @returns {Promise<number>}
+ */
+export async function runRefreshClones({
+  config,
+  args = {},
+  log = defaultLog,
+  err = defaultErr,
+  git = runGit,
+}) {
+  const root = resolvePullClonesRoot({ preferences: config.preferences });
+  const timeoutMs = args.timeoutMs ?? DEFAULT_TIER_TIMEOUT_MS;
+
+  if (!pullClonesRootExists(root)) {
+    const payload = { root, tiers: [], error: 'pull-clones root not found' };
+    if (args.json) log(JSON.stringify(payload, null, 2));
+    else err(`[library refresh-clones] pull-clones root not found: ${root}`);
+    return 2;
+  }
+
+  const tiers = await enumerateTiers(root, args.tiers);
+  const results = await Promise.all(
+    tiers.map((tier) => refreshOne({ tier, git, timeoutMs })),
+  );
+
+  const failures = results.filter((r) => r.status !== 'ok');
+  const payload = { root, tiers: results, ok: failures.length === 0 };
+
+  if (args.json) {
+    log(JSON.stringify(payload, null, 2));
+  } else {
+    log(`pull-clones root: ${root} (${results.length} tier${results.length === 1 ? '' : 's'})`);
+    for (const r of results) {
+      const line = r.status === 'ok'
+        ? `  ${r.name.padEnd(32)} ok (${r.newCommits} new commit${r.newCommits === 1 ? '' : 's'})`
+        : `  ${r.name.padEnd(32)} ${r.status}${r.error ? ` (${r.error})` : ''}`;
+      log(line);
+    }
+    if (failures.length > 0) {
+      err(`[library refresh-clones] ${failures.length} tier${failures.length === 1 ? '' : 's'} failed`);
+    }
+  }
+  return failures.length === 0 ? 0 : 2;
+}
+
+async function enumerateTiers(root, only) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch { return []; }
+  const filter = only && only.length ? new Set(only) : null;
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    if (filter && !filter.has(entry.name)) continue;
+    const full = join(root, entry.name);
+    const s = await stat(join(full, '.git')).catch(() => null);
+    if (!s) continue;
+    out.push({ name: entry.name, path: full });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function refreshOne({ tier, git, timeoutMs }) {
+  const cwd = tier.path;
+
+  // Dirty check — refuse rather than clobber. Pull-clones are read-only
+  // projections; any local edit is a corruption signal that should be
+  // investigated, not merged over.
+  const dirty = await git(['status', '--porcelain'], cwd, { timeoutMs });
+  if (dirty.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git status: ${(dirty.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+  if (dirty.stdout.trim() !== '') {
+    return { name: tier.name, status: 'dirty', error: 'uncommitted local changes; refusing to refresh' };
+  }
+
+  const fetched = await git(['fetch', '--quiet', 'origin'], cwd, { timeoutMs });
+  if (fetched.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git fetch: ${(fetched.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+
+  const count = await git(['rev-list', 'HEAD..origin/main', '--count'], cwd, { timeoutMs });
+  const newCommits = count.code === 0 ? parseInt(count.stdout.trim(), 10) || 0 : 0;
+
+  if (newCommits === 0) {
+    return { name: tier.name, status: 'ok', newCommits: 0 };
+  }
+
+  const pulled = await git(['merge', '--ff-only', '--quiet', 'origin/main'], cwd, { timeoutMs });
+  if (pulled.code !== 0) {
+    return { name: tier.name, status: 'error', error: `git merge --ff-only: ${(pulled.stderr || 'nonzero exit').slice(0, 160)}` };
+  }
+  return { name: tier.name, status: 'ok', newCommits };
+}
+
+function runGit(argsArr, cwd, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIER_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    const proc = spawn('git', argsArr, { cwd });
+    let stdout = '';
+    let stderr = '';
+    const killer = setTimeout(() => {
+      stderr += `\n[timeout after ${timeoutMs}ms]`;
+      try { proc.kill('SIGTERM'); } catch { /* ignore */ }
+    }, timeoutMs);
+    proc.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    proc.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    proc.on('error', (e) => { clearTimeout(killer); resolve({ code: -1, stdout, stderr: e.message }); });
+    proc.on('close', (code) => { clearTimeout(killer); resolve({ code: code ?? -1, stdout, stderr }); });
+  });
+}
+
+function defaultLog(...m) { process.stdout.write(m.join(' ') + '\n'); }
+function defaultErr(...m) { process.stderr.write(m.join(' ') + '\n'); }

package/package.json

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