@stravica-ai/digital-operator-pa 0.1.23 → 0.1.26

package/dist/engineering-pa-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-cli",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Operator-facing CLIs — pa, secrets, scheduler, sync, smoke, launch.",
   "type": "module",
   "main": "./index.mjs",

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

@@ -49,6 +49,11 @@ Usage:
                                        and the excluded amount is shown.
                        [--exclude-stubs]  Skip null-domain nodes
   pa knowledge path    <a> <b>         Shortest path between two docs
+  pa knowledge context                 Print the effective CLAUDE.md rule
+                       [--json]         variants selected by \`library.mode\`
+                                        (remote-library spec §5.1, §5.2).
+                                        Refuses cleanly on structurally
+                                        invalid REMOTE config.
   pa knowledge eval    [--fixture P]   Score the retrieval eval set (hit@1/5,
                        [--out D]        orphan gauge, delta vs last run);
                        [--full]         persists to
@@ -93,6 +98,10 @@ export async function run(argv) {
       case 'domain':   return await doDomain(rest);
       case 'orphans':  return await doOrphans(rest);
       case 'path':     return await doPath(rest);
+      case 'context': {
+        const { runContext } = await import('./context.mjs');
+        return await runContext(rest);
+      }
       case 'eval': {
         const { run: runEval } = await import('./eval.mjs');
         return await runEval(rest);

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

@@ -0,0 +1,274 @@
+// context.mjs — `pa knowledge context` verb.
+//
+// Prints the CLAUDE.md rule variants that are LIVE for this session,
+// selected by `library.mode` in the merged operator preferences.
+//
+// The two-mode switch is specified in the `@stravica-ai/remote-library`
+// spec §5.1 and §5.2 (build items 14 + 15). Item 14 landed the wiring —
+// `resolveLibraryConfig` + `getLibraryVariant` in `packages/core/src/
+// library-config.mjs` — and the `plan.libraryVariant` seam on
+// `buildSessionPlan`. Item 15 (this file, plus stravica-pa's CLAUDE.md
+// variant markers) closes the loop: agents read the CLAUDE.md variants
+// on boot and invoke `pa knowledge context` to know WHICH is live.
+//
+// Rule-variant TEXT is duplicated between this module and the operator
+// repo's CLAUDE.md. Both sources cite spec §5.2 verbatim. The
+// duplication is a feature: each stands alone; if one drifts, running
+// `pa knowledge context` alongside CLAUDE.md flags the drift visually.
+//
+// Refuse-boot semantics (spec §5.1): a structurally invalid REMOTE
+// config (mode="remote" with missing endpoint/key, or malformed key
+// shape) surfaces the underlying `LibraryConfigError` on stderr and
+// exits 1. `pa knowledge context` is deliberately usable as a
+// diagnostic when the boot path itself is refusing to open — an
+// operator can invoke it AFTER the `pa session` refusal to inspect
+// exactly what the mode-resolver saw.
+//
+// Runtime unreachability of the remote endpoint is NOT surfaced here:
+// this verb never performs a network call. That is deliberate — spec
+// §5.1 rules runtime unreachability non-fatal at boot; probing here
+// would drag the boot doctrine sideways.
+
+import { LibraryConfigError, getLibraryVariant, resolveLibraryConfig } from '../../../engineering-pa-core/src/library-config.mjs';
+import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
+
+import { getRepoRoot } from '../pa/repo-root.mjs';
+
+// --- rule-variant text (spec §5.2 verbatim) ------------------------------
+//
+// Every entry mirrors an existing rule in the operator's
+// `agents/<paName>/CLAUDE.md` under Bucket 4 (Knowledge & memory).
+// `bucket` + `ruleNumber` + `ruleTitle` let the JSON envelope be indexed
+// against the CLAUDE.md file without string-matching the file body.
+// `simple` is the historic wording; the REMOTE deltas come from
+// remote-library spec §5.2.
+export const RULE_VARIANTS = [
+  {
+    bucket: 4,
+    ruleNumber: 2,
+    ruleTitle: 'Repo is single source of truth',
+    simple: 'Markdown for human-readable, JSON for machine-readable indexes.',
+    remote: 'The write path is `library put`. The pulled repo is a read-only projection of the event log. Never edit files inside library repos directly; write via `library put`.',
+  },
+  {
+    bucket: 4,
+    ruleNumber: 7,
+    ruleTitle: 'The Librarian sweeps staging during distillation',
+    simple: 'Each agent stages to its own staging dir; the Librarian routes observations to canonical destinations. Don\'t route observations directly.',
+    remote: '`library flush` sweeps local staging into the event log. The service applies the events to the git projection.',
+  },
+];
+
+const USAGE = `pa knowledge context — print the effective CLAUDE.md rule variants for this session
+
+Usage:
+  pa knowledge context                 Print the live rule variants (human-readable)
+  pa knowledge context --format json   Emit the same envelope as JSON
+
+The variant is selected by \`library.mode\` in the merged operator preferences
+(base file + preferences.local.json overlay). Absent field defaults to "simple"
+per spec §5.1.
+
+A structurally invalid REMOTE config (mode="remote" with missing endpoint or
+key, or a malformed key shape) is REFUSED here with the same message the
+\`pa session\` boot path uses — this verb is safe to run as a diagnostic when
+\`pa session\` itself is refusing to open.
+
+Runtime endpoint unreachability is not probed here (spec §5.1: runtime
+unreachability is non-fatal at boot; individual \`library\` verbs fail closed
+and alert).
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage/config error | 2 unexpected internal failure
+`;
+
+/**
+ * Build the envelope for the resolved library variant. Pure: takes an
+ * already-resolved config plus the resolved paName, returns the
+ * printable / JSON-emittable shape.
+ *
+ * `paName` is the boot-resolved operator name (from merged preferences,
+ * same source `buildSessionPlan` uses). When null (diagnostic call with
+ * absent preferences), the rendered path degrades to the `<paName>`
+ * placeholder so the diagnostic still emits without lying about which
+ * operator's file the variants target.
+ *
+ * @param {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}} config
+ * @param {{paName?: string|null}} [opts]
+ * @returns {{
+ *   verb: 'context',
+ *   libraryMode: 'simple'|'remote',
+ *   libraryVariant: 'simple'|'remote',
+ *   remoteEndpoint: string|null,
+ *   paName: string|null,
+ *   agentClaudePath: string,
+ *   ruleVariants: Array<{bucket:number, ruleNumber:number, ruleTitle:string, effective:string, mode:'simple'|'remote'}>,
+ *   specReference: string,
+ * }}
+ */
+export function buildContextEnvelope(config, opts = {}) {
+  const variant = getLibraryVariant(config);
+  const paName = typeof opts.paName === 'string' && opts.paName.length > 0
+    ? opts.paName
+    : null;
+  const agentClaudePath = `agents/${paName ?? '<paName>'}/CLAUDE.md`;
+  return {
+    verb: 'context',
+    libraryMode: config.mode,
+    libraryVariant: variant,
+    remoteEndpoint: config.mode === 'remote' ? config.remoteEndpoint : null,
+    paName,
+    agentClaudePath,
+    ruleVariants: RULE_VARIANTS.map((r) => ({
+      bucket: r.bucket,
+      ruleNumber: r.ruleNumber,
+      ruleTitle: r.ruleTitle,
+      effective: variant === 'remote' ? r.remote : r.simple,
+      mode: variant,
+    })),
+    specReference: '@stravica-ai/remote-library spec §5.1 (mode switch), §5.2 (rule variants)',
+  };
+}
+
+/**
+ * Human-readable renderer. Emits one block per rule variant so an
+ * operator can eyeball which text is live.
+ * @param {ReturnType<typeof buildContextEnvelope>} envelope
+ * @returns {string}
+ */
+export function formatContextTable(envelope) {
+  const lines = [];
+  lines.push(`library.mode = ${envelope.libraryMode}  (variant token: ${envelope.libraryVariant})`);
+  if (envelope.libraryMode === 'remote') {
+    lines.push(`remoteEndpoint: ${envelope.remoteEndpoint}`);
+  }
+  lines.push('');
+  lines.push(`Effective CLAUDE.md rule variants (${envelope.agentClaudePath}, Bucket 4):`);
+  lines.push('');
+  for (const r of envelope.ruleVariants) {
+    lines.push(`  Rule ${r.bucket}.${r.ruleNumber} — ${r.ruleTitle}  [${r.mode}]`);
+    lines.push(`    ${r.effective}`);
+    lines.push('');
+  }
+  lines.push(`Spec: ${envelope.specReference}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// --- verb entry ---------------------------------------------------------
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === '-h' || a === '--help') { flags.help = true; continue; }
+    if (a === '--json') { flags.format = 'json'; continue; }
+    if (a === '--format') {
+      const peek = args[i + 1];
+      if (peek == null || peek.startsWith('--')) {
+        const err = new Error('--format requires an argument (table|json)');
+        err.exitCode = 1;
+        throw err;
+      }
+      flags.format = peek;
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--format=')) {
+      flags.format = a.slice('--format='.length);
+      continue;
+    }
+    positional.push(a);
+  }
+  if (positional.length > 0) {
+    const err = new Error(`unexpected argument: ${positional[0]}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  if (flags.format != null && flags.format !== 'table' && flags.format !== 'json') {
+    const err = new Error(`unknown --format: ${flags.format} (expected table | json)`);
+    err.exitCode = 1;
+    throw err;
+  }
+  return flags;
+}
+
+/**
+ * Verb entrypoint. Seams allow tests to inject a fake preferences reader,
+ * fake repo-root resolver, and capture streams.
+ *
+ * @param {string[]} argv         args after `context`
+ * @param {object}   [seam]
+ * @param {() => Promise<string>} [seam.getRepoRoot]
+ * @param {(root:string) => Promise<object|null>} [seam.readPreferences]
+ * @param {NodeJS.WritableStream} [seam.stdout]
+ * @param {NodeJS.WritableStream} [seam.stderr]
+ */
+export async function runContext(argv, seam = {}) {
+  const stdout = seam.stdout ?? process.stdout;
+  const stderr = seam.stderr ?? process.stderr;
+  const getRoot = seam.getRepoRoot ?? getRepoRoot;
+  const readPrefs = seam.readPreferences ?? readPreferences;
+
+  let flags;
+  try {
+    flags = parseFlags(argv);
+  } catch (err) {
+    stderr.write(`[pa knowledge context] ${err.message}\n`);
+    stderr.write(USAGE);
+    return err.exitCode ?? 1;
+  }
+
+  if (flags.help) {
+    stdout.write(USAGE);
+    return 0;
+  }
+
+  let repoRoot;
+  try {
+    repoRoot = await getRoot();
+  } catch (err) {
+    stderr.write(`[pa knowledge context] ${err.message ?? err}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  let prefs;
+  try {
+    prefs = await readPrefs(repoRoot);
+  } catch (err) {
+    stderr.write(`[pa knowledge context] failed to read preferences at ${repoRoot}: ${err.message ?? err}\n`);
+    return 2;
+  }
+
+  let config;
+  try {
+    config = resolveLibraryConfig(prefs);
+  } catch (err) {
+    if (err instanceof LibraryConfigError) {
+      stderr.write(`[pa knowledge context] ${err.message}\n`);
+      return err.exitCode ?? 1;
+    }
+    stderr.write(`[pa knowledge context] ${err.message ?? err}\n`);
+    return 2;
+  }
+
+  // paName is the boot-resolved operator name. Sourced from the same
+  // merged preferences `buildSessionPlan` consumes — no new config, no
+  // second read. Absent prefs (readPreferences === null) keeps paName
+  // null and the envelope renders the `<paName>` placeholder so the
+  // diagnostic remains usable when the boot path itself is refusing.
+  const paName = (prefs && typeof prefs.paName === 'string' && prefs.paName.length > 0)
+    ? prefs.paName
+    : null;
+
+  const envelope = buildContextEnvelope(config, { paName });
+  if (flags.format === 'json') {
+    stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+  } else {
+    stdout.write(formatContextTable(envelope));
+  }
+  return 0;
+}
+
+export { USAGE };

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

@@ -24,7 +24,7 @@ Usage:
   pa project <verb>           Project state writes (create | status | doc add/rm | list)
   pa work <verb>              Work-item state writes (create | status | list)
   pa gsc <verb>               Google Search Console automation (add-property | verify-via-cf-dns | submit-sitemap | sitemap-status | pull-analytics | list-properties)
-  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 | context)
   pa research <verb>          Deep-research session store (run | list | show | gates | prune | mark | paths)
   pa autonomy <verb>          Per-agent per-task-type approval state (init | get | set | list)
   pa environment [verb]       Session-boot environment cache (default | refresh | extended)

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

@@ -22,6 +22,11 @@ import { spawn } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 
 import { mergePreferences } from '../../../engineering-pa-core/src/preferences.mjs';
+import {
+  LibraryConfigError,
+  getLibraryVariant,
+  resolveLibraryConfig,
+} from '../../../engineering-pa-core/src/library-config.mjs';
 
 /**
  * Resolve the operator repo root with the priority documented in the brief:
@@ -172,6 +177,28 @@ export async function buildSessionPlan(repoRoot, seam = {}) {
     );
   }
 
+  // Item 14: resolve the `library.*` block and select the CLAUDE.md
+  // rule-variant token. `resolveLibraryConfig` throws
+  // LibraryConfigError on mode=remote misconfiguration (spec §5.1 —
+  // refuse to boot the library subsystem, no silent fallback to
+  // SIMPLE). Item 15 will consume `libraryVariant` when it renders the
+  // effective CLAUDE.md and when `pa knowledge context` prints the
+  // resolved wording; the plan carries the token forward so item 15
+  // slots content in without changing the wiring here.
+  let libraryConfig;
+  try {
+    libraryConfig = resolveLibraryConfig(merged);
+  } catch (err) {
+    if (err instanceof LibraryConfigError) {
+      throw new SessionError(
+        `${err.message} (preferences at ${preferencesPath})`,
+        err.exitCode ?? 1,
+      );
+    }
+    throw err;
+  }
+  const libraryVariant = getLibraryVariant(libraryConfig);
+
   return {
     repoRoot,
     preferencesPath,
@@ -179,6 +206,8 @@ export async function buildSessionPlan(repoRoot, seam = {}) {
     agentDir,
     command: 'claude',
     args: ['--dangerously-skip-permissions'],
+    libraryConfig,
+    libraryVariant,
   };
 }
 

package/dist/engineering-pa-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Type-agnostic platform spine — desk CLI, distill, memory-sync, schemas, briefing-contract framework, knowledge engine, scheduler primitives.",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-core/src/library-config.mjs

@@ -0,0 +1,122 @@
+// library-config.mjs — resolve + validate the `library.*` block in
+// operator preferences.
+//
+// This module supplies the READ + REFUSE-BOOT half of the two-mode
+// switch specified in `@stravica-ai/remote-library` spec §5.1:
+//
+//   - `library.mode` is EXPLICIT (`"simple"` | `"remote"`); never auto-
+//     detected. Absent defaults to `"simple"`.
+//   - `mode="remote"` with missing/empty `remoteEndpoint` or `remoteKey`
+//     REFUSES to boot the library subsystem — no silent fallback to
+//     SIMPLE (falling back is a data-loss path).
+//
+// This lands as a token-selection module for build item 14 (see the
+// spec's work-item breakdown §11). The CLAUDE.md variant CONTENT and
+// the `pa knowledge context` verb both key off `getLibraryVariant`
+// and will land in item 15; the wiring here is stable so item 15 slots
+// content into the existing shape without changing this file.
+//
+// The reader is DELIBERATELY pure — it consumes an already-merged
+// preferences object. Callers pair it with `readPreferences` /
+// `readPreferencesSync` from ./preferences.mjs so the overlay-aware
+// path stays a single implementation.
+
+/**
+ * Default when `library.mode` is absent from preferences.
+ * @type {"simple"|"remote"}
+ */
+export const DEFAULT_LIBRARY_MODE = 'simple';
+
+/**
+ * Set of accepted `library.mode` values (spec §5.1).
+ */
+const VALID_MODES = new Set(['simple', 'remote']);
+
+/**
+ * Sentinel raised on invalid `library.*` configuration. Carries a
+ * `code` for machine-consumer disambiguation and an `exitCode` so
+ * CLI wrappers can surface it without a switch.
+ */
+export class LibraryConfigError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} code   e.g. 'invalid-mode' | 'remote-config-missing' | 'remote-key-shape'
+   * @param {number} [exitCode]  defaults to 1 (usage / configuration error)
+   */
+  constructor(message, code, exitCode = 1) {
+    super(message);
+    this.name = 'LibraryConfigError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Resolve the `library` block from a merged preferences object.
+ * Returns `{ mode }` for SIMPLE mode and
+ * `{ mode: 'remote', remoteEndpoint, remoteKey }` for REMOTE mode.
+ * Throws {@link LibraryConfigError} on invalid shape or on REMOTE
+ * mode with missing required fields.
+ *
+ * @param {object|null} preferences  merged preferences (base + overlay)
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}}
+ */
+export function resolveLibraryConfig(preferences) {
+  const raw =
+    preferences && typeof preferences === 'object' && !Array.isArray(preferences)
+      ? preferences.library
+      : null;
+  const block = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+
+  const mode = block.mode ?? DEFAULT_LIBRARY_MODE;
+
+  if (!VALID_MODES.has(mode)) {
+    throw new LibraryConfigError(
+      `library.mode must be "simple" or "remote", got ${JSON.stringify(mode)}`,
+      'invalid-mode',
+    );
+  }
+
+  if (mode === 'simple') {
+    return { mode };
+  }
+
+  // REMOTE mode — validate required fields (spec §5.1 refuse-boot).
+  const missing = [];
+  const endpoint = block.remoteEndpoint;
+  const key = block.remoteKey;
+  if (typeof endpoint !== 'string' || endpoint.trim() === '') missing.push('library.remoteEndpoint');
+  if (typeof key !== 'string' || key.trim() === '') missing.push('library.remoteKey');
+  if (missing.length > 0) {
+    throw new LibraryConfigError(
+      `library.mode="remote" but required field(s) missing/empty: ${missing.join(', ')}. ` +
+        `Refusing to boot the library subsystem (spec §5.1: no silent fallback to SIMPLE).`,
+      'remote-config-missing',
+    );
+  }
+
+  // Cheap shape check on remoteKey (`<subkeyId>:<secret>`). The server
+  // does the authoritative check; catching a paste error early spares a
+  // network round-trip and a generic 401.
+  if (!/^[^:\s]+:[^\s]+$/.test(key)) {
+    throw new LibraryConfigError(
+      'library.remoteKey must be of shape "<subkeyId>:<secret>" (no whitespace, colon separator).',
+      'remote-key-shape',
+    );
+  }
+
+  return { mode, remoteEndpoint: endpoint, remoteKey: key };
+}
+
+/**
+ * Return the CLAUDE.md rule-variant token for a resolved library config.
+ * Item 15 keys off this string when composing the effective CLAUDE.md
+ * and when `pa knowledge context` prints the resolved wording.
+ *
+ * @param {{mode: 'simple'|'remote'}} config  the value returned by resolveLibraryConfig
+ * @returns {'simple'|'remote'}
+ */
+export function getLibraryVariant(config) {
+  const mode = config?.mode ?? DEFAULT_LIBRARY_MODE;
+  return mode === 'remote' ? 'remote' : 'simple';
+}

package/dist/engineering-pa-scaffold/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-scaffold",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "pa-init scaffolder + onboarding flows (solo, lead, member).",
   "type": "module",
   "main": "./index.mjs",

package/dist/engineering-pa-scaffold/src/generator.mjs

@@ -184,6 +184,13 @@ export function buildPreferencesJson(config) {
     pa: { name: capitalise(config.paName), role: 'PA' },
     communicationStyle: config.communicationStyle,
     workspacePort: 4200,
+    // `@stravica-ai/remote-library` spec §5.1 — mode is EXPLICIT, never
+    // auto-detected. Fresh installs land on SIMPLE (single-operator, one
+    // local librarian sweep). Flipping to `"remote"` also requires
+    // `remoteEndpoint` and `remoteKey` (see spec §5.1); the `pa session`
+    // boot path refuses to launch when `mode="remote"` and either field
+    // is missing.
+    library: { mode: 'simple' },
     generatedAt: config.generatedAt,
   };
 }

package/package.json

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