@stravica-ai/digital-operator-pa 0.1.22 → 0.1.25

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

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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,248 @@
+// 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 `agents/dave/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, returns the printable / JSON-emittable shape.
+ *
+ * @param {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}} config
+ * @returns {{
+ *   verb: 'context',
+ *   libraryMode: 'simple'|'remote',
+ *   libraryVariant: 'simple'|'remote',
+ *   remoteEndpoint: string|null,
+ *   ruleVariants: Array<{bucket:number, ruleNumber:number, ruleTitle:string, effective:string, mode:'simple'|'remote'}>,
+ *   specReference: string,
+ * }}
+ */
+export function buildContextEnvelope(config) {
+  const variant = getLibraryVariant(config);
+  return {
+    verb: 'context',
+    libraryMode: config.mode,
+    libraryVariant: variant,
+    remoteEndpoint: config.mode === 'remote' ? config.remoteEndpoint : null,
+    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 (agents/dave/CLAUDE.md, 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;
+  }
+
+  const envelope = buildContextEnvelope(config);
+  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/io.mjs

@@ -24,6 +24,24 @@ export async function writeJson(path, value) {
   await writeFile(path, body, 'utf8');
 }
 
+/**
+ * Write a JSON file with O_CREAT|O_EXCL semantics. Refuses to overwrite
+ * an existing file (throws a Node error with `code === 'EEXIST'`).
+ *
+ * Same shape rules as `writeJson`: 2-space indent, trailing newline,
+ * parent directories created on demand. Callers that follow an
+ * allocate-then-write pattern use this to turn a same-author write race
+ * into an EEXIST they can retry at NNN+1, rather than the plain flag
+ * `'w'` behaviour where the second write silently clobbered the first.
+ * Same primitive `escalate.mjs` in `librarian-pr-intake` uses for the
+ * librarian's own allocator — the two writers now share one race model.
+ */
+export async function writeJsonExclusive(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const body = JSON.stringify(value, null, 2) + '\n';
+  await writeFile(path, body, { encoding: 'utf8', flag: 'wx' });
+}
+
 /**
  * Ensure a directory exists. Returns the absolute path.
  */

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-cli/src/pa/work.mjs

@@ -26,7 +26,22 @@ import {
 } from '../../../engineering-pa-core/src/workItemId/index.mjs';
 
 import { getRepoRoot } from './repo-root.mjs';
-import { readJson, writeJson, ensureDir, listJsonFiles, today } from './io.mjs';
+import {
+  readJson,
+  writeJson,
+  writeJsonExclusive,
+  ensureDir,
+  listJsonFiles,
+  today,
+} from './io.mjs';
+
+// Upper bound on the O_CREAT|O_EXCL retry loop in `createWork`. Same
+// value the librarian-pr-intake allocator uses (`escalate.mjs`); both
+// close the same class of same-author race between allocator scan and
+// exclusive write. 99 is comfortably above any realistic burst — 999 is
+// the per-author-per-day NNN ceiling so a runaway loop still terminates
+// well below it.
+const MAX_ALLOCATE_RETRIES = 99;
 
 const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
 
@@ -63,29 +78,22 @@ function validatePriority(priority) {
 }
 
 /**
- * Highest NNN already allocated for `dateStr` in THIS author's per-day
- * sequence. Legacy items (`w-YYYY-MM-DD-NNN` with no author segment)
- * do not count toward any author's sequence — each writer starts from
- * 001 on the day writer-scoping takes effect and existing legacy items
- * simply occupy a separate, older space.
+ * Highest NNN currently visible on disk for `dateStr` in THIS author's
+ * per-day sequence. Legacy items (`w-YYYY-MM-DD-NNN` with no author
+ * segment) do not count toward any author's sequence — each writer
+ * starts from 001 on the day writer-scoping takes effect and existing
+ * legacy items simply occupy a separate, older space.
  *
- * If 999 is already taken, throws — callers should treat as an
- * operational failure and report. In practice this is unreachable
- * because NNN is per-author-per-day, not shared.
+ * The value is a starting point for `createWork`'s allocate-write-retry
+ * loop, not a final answer: between the scan and the exclusive write,
+ * another same-author `pa work create` may have landed a same-NNN file
+ * (same-author write race, structurally possible when two operator
+ * sessions run concurrently on shared work/). The O_CREAT|O_EXCL retry
+ * in `createWork` is what closes that residual race.
  */
-async function nextWorkNumber(repoRoot, dateStr, author) {
-  const dir = join(repoRoot, 'work');
-  const files = await listJsonFiles(dir);
-  const max = maxNForAuthorOnDate(files, dateStr, author);
-  const next = max + 1;
-  if (next > 999) {
-    const err = new Error(
-      `no free work-item slot for ${dateStr} in author=${author} sequence (NNN exhausted)`,
-    );
-    err.exitCode = 2;
-    throw err;
-  }
-  return next;
+async function scanMaxNInWorkDir(workDir, dateStr, author) {
+  const files = await listJsonFiles(workDir);
+  return maxNForAuthorOnDate(files, dateStr, author);
 }
 
 /**
@@ -101,6 +109,15 @@ async function nextWorkNumber(repoRoot, dateStr, author) {
  * with an actionable message naming all three sources — a mint with no
  * author identity is the exact defect R1 exists to close, so we refuse
  * to fall back to any hard-coded default.
+ *
+ * Write is O_CREAT|O_EXCL via `writeJsonExclusive`. If two same-author
+ * `createWork` invocations race (same estate, same day, two operator
+ * sessions), the allocator scan may hand both callers the same base
+ * NNN; the first exclusive write lands and the second gets EEXIST,
+ * which the retry loop below resolves by trying NNN+1, NNN+2, ... up
+ * to `MAX_ALLOCATE_RETRIES`. Cross-writer collisions (different author
+ * tokens) are already structurally impossible after R1
+ * (w-2026-08-12-001) — this closes the residual same-author window.
  */
 export async function createWork(opts) {
   if (!opts.title) {
@@ -127,28 +144,48 @@ export async function createWork(opts) {
   await ensureDir(workDir);
 
   const dateStr = today();
-  const nnn = await nextWorkNumber(repoRoot, dateStr, author);
-  const id = buildWorkItemId({ date: dateStr, author, nnn });
-  const path = join(workDir, `${id}.json`);
-
-  const item = {
-    id,
-    projectId: opts.projectId || null,
-    title: opts.title,
-    category: opts.category || 'chore',
-    status: 'draft',
-    priority: opts.priority == null ? 2 : opts.priority,
-    owner: opts.owner || 'system-architect',
-    assignee: opts.assignee || opts.owner || 'system-architect',
-    created: dateStr,
-    updated: dateStr,
-    completedAt: null,
-    summary: opts.summary || '',
-    blocked: null,
-    links: [],
-  };
-  await writeJson(path, item);
-  return { id, path };
+  const baseN = await scanMaxNInWorkDir(workDir, dateStr, author);
+
+  for (let offset = 1; offset <= MAX_ALLOCATE_RETRIES; offset += 1) {
+    const nnn = baseN + offset;
+    if (nnn > 999) {
+      const err = new Error(
+        `no free work-item slot for ${dateStr} in author=${author} sequence (NNN exhausted)`,
+      );
+      err.exitCode = 2;
+      throw err;
+    }
+    const id = buildWorkItemId({ date: dateStr, author, nnn });
+    const path = join(workDir, `${id}.json`);
+    const item = {
+      id,
+      projectId: opts.projectId || null,
+      title: opts.title,
+      category: opts.category || 'chore',
+      status: 'draft',
+      priority: opts.priority == null ? 2 : opts.priority,
+      owner: opts.owner || 'system-architect',
+      assignee: opts.assignee || opts.owner || 'system-architect',
+      created: dateStr,
+      updated: dateStr,
+      completedAt: null,
+      summary: opts.summary || '',
+      blocked: null,
+      links: [],
+    };
+    try {
+      await writeJsonExclusive(path, item);
+      return { id, path };
+    } catch (e) {
+      if (e && e.code === 'EEXIST') continue;
+      throw e;
+    }
+  }
+  const err = new Error(
+    `pa work create: gave up after ${MAX_ALLOCATE_RETRIES} EEXIST retries from base NNN ${baseN + 1} in ${dateStr} author=${author}`,
+  );
+  err.exitCode = 2;
+  throw err;
 }
 
 /**

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.22",
+  "version": "0.1.25",
   "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",