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

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

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-cli",
-  "version": "0.2.4",
+  "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/context.mjs

@@ -29,18 +29,19 @@
 // §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 { LibraryConfigError, getLibraryVariant, resolveLibraryConfigWithRefs } 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.
+// 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,
@@ -83,25 +84,41 @@ Exit codes (tooling standard §6):
 
 /**
  * Build the envelope for the resolved library variant. Pure: takes an
- * already-resolved config, returns the printable / JSON-emittable shape.
+ * 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) {
+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,
@@ -126,7 +143,7 @@ export function formatContextTable(envelope) {
     lines.push(`remoteEndpoint: ${envelope.remoteEndpoint}`);
   }
   lines.push('');
-  lines.push('Effective CLAUDE.md rule variants (agents/dave/CLAUDE.md, Bucket 4):');
+  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}]`);
@@ -226,7 +243,7 @@ export async function runContext(argv, seam = {}) {
 
   let config;
   try {
-    config = resolveLibraryConfig(prefs);
+    config = resolveLibraryConfigWithRefs(prefs, { repoRoot });
   } catch (err) {
     if (err instanceof LibraryConfigError) {
       stderr.write(`[pa knowledge context] ${err.message}\n`);
@@ -236,7 +253,16 @@ export async function runContext(argv, seam = {}) {
     return 2;
   }
 
-  const envelope = buildContextEnvelope(config);
+  // 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 {

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

@@ -25,7 +25,7 @@ import { mergePreferences } from '../../../engineering-pa-core/src/preferences.m
 import {
   LibraryConfigError,
   getLibraryVariant,
-  resolveLibraryConfig,
+  resolveLibraryConfigWithRefs,
 } from '../../../engineering-pa-core/src/library-config.mjs';
 
 /**
@@ -178,16 +178,17 @@ export async function buildSessionPlan(repoRoot, seam = {}) {
   }
 
   // Item 14: resolve the `library.*` block and select the CLAUDE.md
-  // rule-variant token. `resolveLibraryConfig` throws
+  // rule-variant token. `resolveLibraryConfigWithRefs` 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.
+  // SIMPLE), and additionally resolves a `library.remoteKey` carrying
+  // the full-scope vault reference form (`<scope>/<KEY_NAME>`) into
+  // its underlying literal via the `secrets` CLI. Item 15 consumes
+  // `libraryVariant` when it renders the effective CLAUDE.md and when
+  // `pa knowledge context` prints the resolved wording.
   let libraryConfig;
   try {
-    libraryConfig = resolveLibraryConfig(merged);
+    libraryConfig = resolveLibraryConfigWithRefs(merged, { repoRoot });
   } catch (err) {
     if (err instanceof LibraryConfigError) {
       throw new SessionError(

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

@@ -16,10 +16,31 @@
 // 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` /
+// `resolveLibraryConfig` 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.
+//
+// `resolveRemoteKeyRef` sits alongside it as an OPT-IN vault-fetching
+// resolver: `library.remoteKey` values that look like the full-scope
+// reference form (`<scope>/<KEY_NAME>` per Baz's w-2026-07-15-023
+// ruling) resolve to their vaulted literal via the `secrets` CLI so
+// canonical stravica-operator-barry never has to carry a literal
+// subkey in a git-tracked file. Literal values pass through untouched.
+// The wrapper `resolveLibraryConfigWithRefs(preferences, {repoRoot})`
+// composes the two so callers get one call: read → ref-resolve →
+// validate, refuse-boot on any failure.
+//
+// Written into the platform in w-2026-08-21-005 after the 2026-08-21T11:05Z
+// library-sync-cycle wipe: the canonical file had no library block, a
+// materialisation tick clobbered HQ's local plaintext block, and the
+// options collapsed to (a) put a literal secret in canonical (rejected
+// by policy — git history is forever), (b) hold sync-cycle indefinitely,
+// or (c) ship this resolver. The estate picked (c).
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
 
 /**
  * Default when `library.mode` is absent from preferences.
@@ -120,3 +141,134 @@ export function getLibraryVariant(config) {
   const mode = config?.mode ?? DEFAULT_LIBRARY_MODE;
   return mode === 'remote' ? 'remote' : 'simple';
 }
+
+/**
+ * Full-scope vault reference form for `library.remoteKey`, per Baz's
+ * ruling on w-2026-07-15-023: `<scope>/<KEY_NAME>` (e.g.
+ * `hq-estate/REMOTE_LIBRARY_SUBKEY_DAVE`). Distinct from the literal-
+ * subkey shape (`<subkeyId>:<secret>`) so the shape validator downstream
+ * still refuses garbage. Any value that neither matches this ref shape
+ * nor the literal shape is passed through and refused by the shape
+ * validator.
+ */
+export const REMOTE_KEY_REF_RE = /^([a-z0-9-]+)\/([A-Z][A-Z0-9_]*)$/;
+
+/**
+ * Resolve a `library.remoteKey` value that carries the full-scope vault
+ * reference form (`<scope>/<KEY_NAME>`) into the underlying literal
+ * `<subkeyId>:<secret>` by calling the estate `secrets` CLI. Literal
+ * values (containing a colon) and anything else pass through untouched;
+ * the shape validator in `resolveLibraryConfig` is authoritative on shape.
+ *
+ * Canonical stravica-operator-barry cannot carry the literal subkey (a
+ * sync-cycle materialisation would round-trip a plaintext secret through
+ * a git-tracked file). The reference lives in canonical; the vault holds
+ * the value; this function is the bridge. See w-2026-08-21-005 for the
+ * incident that made this the durable pattern.
+ *
+ * @param {string} refOrLiteral        the raw remoteKey value from preferences
+ * @param {object} opts
+ * @param {string} opts.repoRoot       repo root; used to locate the secrets bin
+ * @param {(args:{scope:string,key:string,repoRoot:string})=>string} [opts.secretsGet]
+ *                                     injectable resolver (tests)
+ * @returns {string}                   the resolved literal (never printed)
+ */
+export function resolveRemoteKeyRef(refOrLiteral, { repoRoot, secretsGet } = {}) {
+  if (typeof refOrLiteral !== 'string') return refOrLiteral;
+  const m = REMOTE_KEY_REF_RE.exec(refOrLiteral);
+  if (!m) return refOrLiteral;
+  const [, scope, key] = m;
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" cannot be resolved: ` +
+        `no repoRoot supplied. Callers must pass repoRoot when preferences carry a scope/KEY ref.`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  const fetcher = secretsGet || defaultSecretsGet;
+  let resolved;
+  try {
+    resolved = fetcher({ scope, key, repoRoot });
+  } catch (err) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" failed to resolve ` +
+        `(scope=${scope} key=${key}): ${err && err.message ? err.message : err}. ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  if (typeof resolved !== 'string' || resolved.length === 0) {
+    throw new LibraryConfigError(
+      `library.remoteKey vault reference "${refOrLiteral}" resolved to empty value ` +
+        `(scope=${scope} key=${key}). ` +
+        `Fix: pnpm exec secrets set ${key} --scope ${scope} <value>`,
+      'remote-key-ref-unresolved',
+    );
+  }
+  // secrets get can leave a trailing newline depending on subshell; strip
+  // trailing whitespace once at the boundary so the shape validator sees
+  // the clean payload.
+  return resolved.replace(/\s+$/, '');
+}
+
+/**
+ * Read + ref-resolve + validate in one call. Wraps `resolveLibraryConfig`
+ * with `resolveRemoteKeyRef` so callers get: (1) full-scope vault refs
+ * automatically resolved via the injected `secretsGet` (or the built-in
+ * `secrets` CLI); (2) the same shape/refuse-boot guarantees on the
+ * resolved literal. Preserves the pure `resolveLibraryConfig` for
+ * caller sites that never see refs.
+ *
+ * @param {object|null} preferences   merged preferences (base + overlay)
+ * @param {object} opts
+ * @param {string} opts.repoRoot      required when preferences may carry a
+ *                                    scope/KEY ref; ignored otherwise
+ * @param {(args:{scope:string,key:string,repoRoot:string})=>string} [opts.secretsGet]
+ * @returns {{mode: 'simple'|'remote', remoteEndpoint?: string, remoteKey?: string}}
+ */
+export function resolveLibraryConfigWithRefs(preferences, opts = {}) {
+  if (
+    preferences &&
+    typeof preferences === 'object' &&
+    !Array.isArray(preferences) &&
+    preferences.library &&
+    typeof preferences.library === 'object' &&
+    !Array.isArray(preferences.library) &&
+    preferences.library.mode === 'remote' &&
+    typeof preferences.library.remoteKey === 'string'
+  ) {
+    const original = preferences.library.remoteKey;
+    const resolved = resolveRemoteKeyRef(original, opts);
+    if (resolved !== original) {
+      preferences = {
+        ...preferences,
+        library: { ...preferences.library, remoteKey: resolved },
+      };
+    }
+  }
+  return resolveLibraryConfig(preferences);
+}
+
+/**
+ * Default vault fetcher: invokes the `secrets` bin from the installed
+ * `@stravica-ai/digital-operator-pa` package under `repoRoot`. Uses
+ * direct `node <bin>` invocation (not `pnpm exec`) to sidestep the
+ * pnpm-11 stdout footgun that has bitten sam-tasks and others. Value
+ * is never logged.
+ */
+function defaultSecretsGet({ scope, key, repoRoot }) {
+  const secretsBin = join(
+    repoRoot,
+    'node_modules',
+    '@stravica-ai',
+    'digital-operator-pa',
+    'bin',
+    'secrets',
+  );
+  const out = execFileSync('node', [secretsBin, 'get', key, '--scope', scope], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return out;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.25",
-  "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
+  "version": "0.1.27",
+  "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -49,11 +49,10 @@
   "engines": {
     "node": ">=24"
   },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie.",
   "scripts": {
     "build": "node build.mjs",
-    "prepack": "node build.mjs",
     "test": "node --test --test-isolation=none test/*.test.mjs",
     "dry-publish": "node build.mjs && node scripts/dry-publish.mjs"
-  },
-  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper \u2014 see packages/cli/test/secrets. Counts must never lie."
-}
+  }
+}