@stravica-ai/digital-operator-pa 0.1.11 → 0.1.12

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

@@ -21,6 +21,7 @@
 
 import { 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';
 
 const USAGE = `pa knowledge — query the operator's knowledge graph
@@ -41,7 +42,11 @@ Usage:
                        [--strict]      Disable the cascade — restores the
                                        AND-only behaviour for scripted callers
   pa knowledge domain  <name>          All docs in a domain + internal edges
-  pa knowledge orphans                 Docs with no inbound edges
+  pa knowledge orphans                 Docs with no inbound edges. Path classes
+                                       listed in operator/knowledge/
+                                       orphan-policy.json (operator-local doc
+                                       classes) are excluded from the count,
+                                       and the excluded amount is shown.
                        [--exclude-stubs]  Skip null-domain nodes
   pa knowledge path    <a> <b>         Shortest path between two docs
   pa knowledge eval    [--fixture P]   Score the retrieval eval set (hit@1/5,
@@ -218,10 +223,14 @@ async function doOrphans(args) {
   const { flags } = parseFlags(args);
   const format = resolveFormat(flags);
   const includeStubs = !(flags['exclude-stubs'] === true);
-  const { graph } = await loadGraphOrExplain();
-  const results = orphans(graph, { includeStubs });
-  process.stdout.write(formatOrphans(results, format));
-  await logCall({ verb: 'orphans', query: null, resultCount: results.length });
+  const { repoRoot, graph } = await loadGraphOrExplain();
+  // Policy exclusion (w-2026-07-29-003): operator-declared path classes at
+  // operator/knowledge/orphan-policy.json are subtracted from the orphan
+  // list, and the subtraction is rendered — the number never silently shrinks.
+  const policy = await loadOrphanPolicy({ repoRoot });
+  const { kept, exclusion } = applyOrphanPolicy(orphans(graph, { includeStubs }), policy);
+  process.stdout.write(formatOrphans(kept, format, { exclusion }));
+  await logCall({ verb: 'orphans', query: null, resultCount: kept.length });
   return 0;
 }
 

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

@@ -25,7 +25,10 @@
 // Orphan gauge runs in the same pass — total + per-domain, delta vs last
 // run, warnings when growth > 10 or any domain is 100% orphaned. The
 // gauge is a load-bearing hygiene signal, but never fails the run — it
-// tags the summary and boot-context renders the tag.
+// tags the summary and boot-context renders the tag. Path classes listed
+// in operator/knowledge/orphan-policy.json (operator-local doc classes,
+// w-2026-07-29-003) are excluded from the gauge and its alarms; the
+// excluded amount is carried on the gauge and rendered, never silent.
 //
 // Exit codes (tooling standard §6):
 //   0 ok
@@ -38,6 +41,7 @@ import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
 import { getRepoRoot, loadGraph, searchCascade, orphans, uniqueDomains } from './graph.mjs';
+import { loadOrphanPolicy, applyOrphanPolicy, renderExclusionSummary } from './orphan-policy.mjs';
 
 const EVAL_SET_PATH = 'operator/knowledge/_meta/retrieval-evals.json';
 const RUNS_DIR = 'operator/knowledge/_meta/retrieval-eval-runs';
@@ -154,7 +158,18 @@ export async function run(argv) {
   }
 
   const summary = summarise(cases);
-  const orphanGauge = computeOrphanGauge(graph);
+  // Same policy the `orphans` verb honours (w-2026-07-29-003). If the gauge
+  // ignored it, excluded trees would re-alarm forever ("100% orphaned").
+  // A malformed policy file throws here — see orphan-policy.mjs for why
+  // that must be loud.
+  let policy;
+  try {
+    policy = await loadOrphanPolicy({ repoRoot });
+  } catch (err) {
+    process.stderr.write(`pa knowledge eval: ${err.message}\n`);
+    return err.exitCode ?? 1;
+  }
+  const orphanGauge = computeOrphanGauge(graph, policy);
 
   const runId = new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '');
   const generatedAt = new Date().toISOString();
@@ -302,11 +317,17 @@ function pct(n, d) {
 
 // --- orphan gauge ---------------------------------------------------------
 
-function computeOrphanGauge(graph) {
-  const results = orphans(graph, { includeStubs: true });
-  const total = results.length;
+// Policy-excluded path classes (operator/knowledge/orphan-policy.json,
+// w-2026-07-29-003) are subtracted BEFORE totals and per-domain counts,
+// so the growth alarm and the 100%-orphaned-domain alarm judge only the
+// docs that policy says should be graph citizens. The excluded amount is
+// carried on the gauge (`excludedByPolicy`) and rendered on every output
+// surface — the number shrinks visibly, never silently.
+function computeOrphanGauge(graph, policy = null) {
+  const { kept, exclusion } = applyOrphanPolicy(orphans(graph, { includeStubs: true }), policy);
+  const total = kept.length;
   const byDomain = {};
-  for (const r of results) {
+  for (const r of kept) {
     const d = r.domain ?? '<none>';
     byDomain[d] = (byDomain[d] ?? 0) + 1;
   }
@@ -323,7 +344,9 @@ function computeOrphanGauge(graph) {
   if (byDomain['<none>'] != null) {
     perDomain['<none>'] = { orphans: byDomain['<none>'], total: domainTotals['<none>'] ?? 0 };
   }
-  return { total, byDomain: perDomain };
+  const gauge = { total, byDomain: perDomain };
+  if (exclusion != null) gauge.excludedByPolicy = exclusion;
+  return gauge;
 }
 
 // --- delta + alarms -------------------------------------------------------
@@ -373,8 +396,10 @@ function renderWorkStateLine(summary, orphanGauge, delta, alarms) {
   const orphanTag = delta.firstRun
     ? ''
     : ` (${delta.orphanCountDelta > 0 ? '+' : ''}${delta.orphanCountDelta})`;
+  const excluded = orphanGauge.excludedByPolicy?.total ?? 0;
+  const excludedTag = excluded > 0 ? ` [${excluded} excluded by policy]` : '';
   const alarmTag = alarms.length > 0 ? ` ⚠ ${alarms.length} alarm${alarms.length === 1 ? '' : 's'}` : '';
-  return `retrievalEval: hit@5 ${hit5}% ${deltaTag} | orphans ${orphanGauge.total}${orphanTag}${alarmTag}`;
+  return `retrievalEval: hit@5 ${hit5}% ${deltaTag} | orphans ${orphanGauge.total}${orphanTag}${excludedTag}${alarmTag}`;
 }
 
 function emit(runFile, format) {
@@ -399,7 +424,10 @@ function emit(runFile, format) {
     lines.push(`Δhit@5: ${sign}${runFile.delta.hit5PercentagePointsDelta}pp vs last run`);
   }
   lines.push('');
-  lines.push(`Orphans: ${runFile.orphans.total}`);
+  const exclusionSummary = renderExclusionSummary(runFile.orphans.excludedByPolicy);
+  lines.push(exclusionSummary
+    ? `Orphans: ${runFile.orphans.total} (${exclusionSummary})`
+    : `Orphans: ${runFile.orphans.total}`);
   if (runFile.delta && !runFile.delta.firstRun) {
     const sign = runFile.delta.orphanCountDelta > 0 ? '+' : '';
     lines.push(`Δorphans: ${sign}${runFile.delta.orphanCountDelta} vs last run`);

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

@@ -12,6 +12,8 @@
 // pass through the verb result — the CLI-layer wraps in `{verb, ...}`
 // for stability.
 
+import { renderExclusionSummary } from './orphan-policy.mjs';
+
 // --- generic table primitives ---------------------------------------------
 
 const TABLE_MAX_WIDTH = 120;
@@ -229,21 +231,39 @@ function renderDomainMermaid({ domain, nodes, edges }) {
 
 // --- verb: orphans --------------------------------------------------------
 
-export function formatOrphans(results, format) {
-  if (format === 'json') return JSON.stringify({ verb: 'orphans', results }, null, 2) + '\n';
-  if (format === 'mermaid') return renderOrphansMermaid(results);
-  return renderOrphansTable(results);
+// `exclusion` (optional) is the policy-visibility payload from
+// applyOrphanPolicy — { total, byPrefix: [{ pathPrefix, reason, count }] }.
+// When present it is rendered in EVERY format: the ratified design says the
+// orphan number must never silently shrink, so the excluded amount is part
+// of the output, not an implementation detail. When no policy exists
+// (exclusion == null) all three formats are byte-identical to the
+// pre-policy output.
+export function formatOrphans(results, format, { exclusion = null } = {}) {
+  if (format === 'json') {
+    const envelope = { verb: 'orphans', results };
+    if (exclusion != null) envelope.excludedByPolicy = exclusion;
+    return JSON.stringify(envelope, null, 2) + '\n';
+  }
+  if (format === 'mermaid') return renderOrphansMermaid(results, exclusion);
+  return renderOrphansTable(results, exclusion);
+}
+
+function renderExclusionLine(results, exclusion) {
+  const summary = renderExclusionSummary(exclusion);
+  if (summary == null) return null;
+  return `orphans: ${results.length} (${summary})`;
 }
 
-function renderOrphansTable(results) {
-  if (results.length === 0) return '(no orphans)\n';
+function renderOrphansTable(results, exclusion = null) {
+  const footer = renderExclusionLine(results, exclusion);
+  if (results.length === 0) return footer ? `(no orphans)\n${footer}\n` : '(no orphans)\n';
   const rows = results.map((r) => ({
     id: r.id,
     title: r.title ?? '',
     domain: r.domain ?? '',
     outDegree: r.outDegree,
   }));
-  return renderTable(
+  const table = renderTable(
     [
       { key: 'id', label: 'id' },
       { key: 'title', label: 'title' },
@@ -252,13 +272,16 @@ function renderOrphansTable(results) {
     ],
     rows,
   );
+  return footer ? `${table}${footer}\n` : table;
 }
 
-function renderOrphansMermaid(results) {
-  if (results.length === 0) return '%% no orphans\n';
+function renderOrphansMermaid(results, exclusion = null) {
+  const footer = renderExclusionLine(results, exclusion);
+  if (results.length === 0) return footer ? `%% no orphans\n%% ${footer}\n` : '%% no orphans\n';
   const lines = ['graph LR'];
   const idFor = (s) => 'n' + hashSlug(s);
   for (const r of results) lines.push(`  ${idFor(r.id)}["${escapeMermaid(r.title ?? r.id)}"]`);
+  if (footer) lines.push(`  %% ${footer}`);
   return lines.join('\n') + '\n';
 }
 

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

@@ -674,13 +674,24 @@ export function domain(graph, name) {
 // Nodes with zero inbound edges. Excludes null-domain nodes (auto-generated
 // stubs) if `includeStubs` is false. Default is to include everything so
 // operators see the full picture.
+//
+// Index hubs (`type: 'index'`, minted per index.json since core 0.1.10) that
+// link OUT to documents are connectors, not orphans: the root hub has no
+// ancestor to point at it and no authored content can ever link to a .json
+// target (extractLinks drops non-.md markdown links, wiki-links get .md
+// appended, the backlink indexer scans only .md files), so zero inbound is
+// guaranteed by construction — a structural artefact, not a filing gap. A
+// hub with NO outbound links (empty or fully-unresolved index) is still
+// reported, because that genuinely signals a broken hub.
 export function orphans(graph, { includeStubs = true } = {}) {
   const adj = buildAdjacency(graph);
   const results = [];
   for (const node of graph.nodes) {
     if (!includeStubs && node.domain == null) continue;
     if ((adj.in.get(node.id)?.length ?? 0) === 0) {
-      results.push({ id: node.id, title: node.title, domain: node.domain, outDegree: adj.out.get(node.id)?.length ?? 0 });
+      const outDegree = adj.out.get(node.id)?.length ?? 0;
+      if (node.type === 'index' && outDegree > 0) continue;
+      results.push({ id: node.id, title: node.title, domain: node.domain, outDegree });
     }
   }
   results.sort((a, b) => (a.domain ?? '').localeCompare(b.domain ?? '') || a.id.localeCompare(b.id));

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

@@ -0,0 +1,173 @@
+// orphan-policy.mjs — config-driven path-class exclusion for orphan counting.
+//
+// Purpose (w-2026-07-29-003, Baz ruling 2026-07-29): some document classes
+// are operator+agent tier by design — local TODO / memory / note documents
+// that are relevant only to the operator and the agent. A linkless doc in
+// one of those trees is correctly scoped, not an orphan to repair. This
+// module lets the ESTATE declare those path classes in an explicit,
+// human-edited policy file, and every orphan-counting surface (the
+// `orphans` verb, the housekeeping orphanCount that shells it, and the
+// retrieval-eval orphan gauge + alarms) subtracts them consistently.
+//
+// Policy file: `<operator-root>/operator/knowledge/orphan-policy.json` —
+// the same estate tree the knowledge tooling already reads its config
+// from (domains.json, _meta/retrieval-evals.json). Shape:
+//
+//   {
+//     "version": 1,
+//     "excludedPathClasses": [
+//       { "pathPrefix": "operator/knowledge/memory/",
+//         "reason": "<one line: why this class is operator-local>" }
+//     ]
+//   }
+//
+// NAMED TRADE-OFF (ratified with the ruling; do not soften it here): a doc
+// misfiled INTO an excluded tree stops appearing as an orphan. That is why
+// this is a per-path-class config a human reads and edits — never a
+// hardcoded list, never a wildcard/blanket ignore — and why every entry
+// MUST carry a reason string (the file is the audit trail). Validation
+// below enforces both. The exclusion applies to orphan COUNTING only; the
+// librarian's sweep judgement is untouched and still routes genuine
+// knowledge out of excluded trees.
+//
+// Failure posture: a MISSING policy file is normal (empty policy — counts
+// are unfiltered, byte-compatible with the pre-policy world). A MALFORMED
+// policy file throws loudly (exitCode 1): silently ignoring it would snap
+// counts back by the excluded amount and re-fire alarms, and silently
+// misreading it could hide real orphans.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const ORPHAN_POLICY_RELATIVE_PATH = 'operator/knowledge/orphan-policy.json';
+
+// Prefixes that would blanket-ignore the whole tree (or worse). An entry
+// normalising to one of these is a config error, not a policy.
+const BLANKET_PREFIXES = new Set(['/', 'operator/', 'operator/knowledge/']);
+
+export function emptyPolicy() {
+  return { exists: false, path: null, entries: [] };
+}
+
+// Normalise a configured prefix to a plain directory prefix:
+//   - strip a trailing glob (`/**` or `**`) — entries may be written either
+//     as `operator/knowledge/memory/` or `operator/knowledge/memory/**`
+//   - strip a leading `./`
+//   - ensure exactly one trailing `/` so `memory/` never matches `memory-x/`
+function normalisePrefix(raw) {
+  let p = String(raw).trim().replace(/^\.\//, '');
+  p = p.replace(/\*+$/, '');           // drop trailing glob stars
+  p = p.replace(/\/+$/, '');           // drop trailing slashes
+  if (p.includes('*')) return null;    // interior wildcards are not supported — listed prefixes only
+  return p + '/';
+}
+
+function validateEntry(entry, index) {
+  if (!entry || typeof entry !== 'object') {
+    return `excludedPathClasses[${index}] is not an object`;
+  }
+  if (typeof entry.pathPrefix !== 'string' || entry.pathPrefix.trim() === '') {
+    return `excludedPathClasses[${index}].pathPrefix missing or not a non-empty string`;
+  }
+  const prefix = normalisePrefix(entry.pathPrefix);
+  if (prefix == null) {
+    return `excludedPathClasses[${index}].pathPrefix "${entry.pathPrefix}" contains an interior wildcard — only plain path prefixes are allowed`;
+  }
+  if (BLANKET_PREFIXES.has(prefix)) {
+    return `excludedPathClasses[${index}].pathPrefix "${entry.pathPrefix}" is a blanket ignore — the policy requires specific path classes, each with its own reason`;
+  }
+  if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+    return `excludedPathClasses[${index}] ("${entry.pathPrefix}") has no reason — every exclusion must carry a one-line reason; the policy file is the audit trail`;
+  }
+  return null;
+}
+
+// Load + validate the estate policy. Returns
+//   { exists, path, entries: [{ pathPrefix, reason }] }
+// with `pathPrefix` normalised to a trailing-slash directory prefix.
+// Missing file => empty policy. Malformed file => throws (exitCode 1).
+export async function loadOrphanPolicy({ repoRoot, policyPath } = {}) {
+  const path = policyPath ?? (repoRoot ? join(repoRoot, ORPHAN_POLICY_RELATIVE_PATH) : null);
+  if (path == null || !existsSync(path)) return emptyPolicy();
+
+  let json;
+  try {
+    json = JSON.parse(await readFile(path, 'utf8'));
+  } catch (e) {
+    const err = new Error(`orphan policy at ${path} is unreadable or not valid JSON: ${e.message}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  if (!json || typeof json !== 'object' || !Array.isArray(json.excludedPathClasses)) {
+    const err = new Error(`orphan policy at ${path} is malformed: expected { "excludedPathClasses": [...] }`);
+    err.exitCode = 1;
+    throw err;
+  }
+  const entries = [];
+  for (let i = 0; i < json.excludedPathClasses.length; i++) {
+    const problem = validateEntry(json.excludedPathClasses[i], i);
+    if (problem) {
+      const err = new Error(`orphan policy at ${path} is malformed: ${problem}`);
+      err.exitCode = 1;
+      throw err;
+    }
+    entries.push({
+      pathPrefix: normalisePrefix(json.excludedPathClasses[i].pathPrefix),
+      reason: json.excludedPathClasses[i].reason.trim(),
+    });
+  }
+  return { exists: true, path, entries };
+}
+
+// Partition an orphan result list against the policy. Returns
+//   {
+//     kept:     [...],                       // orphans that still count
+//     excluded: [...],                       // policy-excluded results
+//     exclusion: {                           // visibility payload — every
+//       total,                               // output surface renders this
+//       byPrefix: [{ pathPrefix, reason, count }]   // (zero-count entries
+//     }                                      // included: config drift stays visible)
+//   }
+// A null/empty policy keeps everything and returns exclusion: null so
+// callers can preserve the pre-policy output shape exactly.
+export function applyOrphanPolicy(results, policy) {
+  if (!policy || !policy.exists || policy.entries.length === 0) {
+    return { kept: results, excluded: [], exclusion: null };
+  }
+  const counts = new Map(policy.entries.map((e) => [e.pathPrefix, 0]));
+  const kept = [];
+  const excluded = [];
+  for (const r of results) {
+    const match = policy.entries.find((e) => r.id.startsWith(e.pathPrefix));
+    if (match) {
+      counts.set(match.pathPrefix, counts.get(match.pathPrefix) + 1);
+      excluded.push({ ...r, excludedBy: match.pathPrefix });
+    } else {
+      kept.push(r);
+    }
+  }
+  return {
+    kept,
+    excluded,
+    exclusion: {
+      total: excluded.length,
+      byPrefix: policy.entries.map((e) => ({
+        pathPrefix: e.pathPrefix,
+        reason: e.reason,
+        count: counts.get(e.pathPrefix),
+      })),
+    },
+  };
+}
+
+// One-line rendering shared by the orphans table footer, the eval table
+// and the eval workState line, so the excluded amount reads identically
+// everywhere: `87 excluded by policy: operator/knowledge/memory/ 44, ...`.
+export function renderExclusionSummary(exclusion) {
+  if (!exclusion || exclusion.total === 0) return null;
+  const parts = exclusion.byPrefix
+    .filter((p) => p.count > 0)
+    .map((p) => `${p.pathPrefix} ${p.count}`);
+  return `${exclusion.total} excluded by policy: ${parts.join(', ')}`;
+}

package/dist/engineering-pa-core/docs/knowledge-scaffold.md

@@ -127,6 +127,35 @@ npm run reindex
 ```
 
 
+## Orphan policy (path-class exclusions)
+
+`pa knowledge orphans` lists documents with no inbound edges. Some document classes are operator+agent tier by design (local TODO, memory and note documents); a linkless document in one of those trees is correctly scoped, not an orphan to repair. The estate can declare those classes in an explicit policy file:
+
+```
+operator/knowledge/orphan-policy.json
+```
+
+```json
+{
+  "version": 1,
+  "excludedPathClasses": [
+    {
+      "pathPrefix": "operator/knowledge/memory/",
+      "reason": "One line explaining why this class is operator-local."
+    }
+  ]
+}
+```
+
+Every orphan-counting surface honours the same policy: the `orphans` verb, anything that shells it for a count (nightly housekeeping), and the retrieval-eval orphan gauge and its alarms. The rules, all deliberate:
+
+- **Explicit prefixes only.** Each entry is a listed path prefix with a mandatory one-line `reason`. Blanket ignores (the whole knowledge tree, wildcards) are rejected as malformed. The file is the audit trail for the exclusion.
+- **The excluded amount is always rendered** (for example `orphans: 139 (87 excluded by policy: operator/knowledge/memory/ 44, ...)`). The number never silently shrinks.
+- **Named trade-off:** a document misfiled INTO an excluded tree stops appearing as an orphan. That is the price of the exclusion, and it is why the policy is a human-edited config rather than a hardcoded ignore.
+- **Counting only.** The policy does not touch librarian sweep judgement; genuine knowledge is still routed out of excluded trees.
+- A missing policy file means no exclusions. A malformed one fails loudly rather than being ignored, because silently dropping the policy would snap counts back up and re-fire alarms.
+
+
 ## Adding new knowledge
 
 1. Create a domain directory under `operator/knowledge/` if it does not exist.

package/package.json

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