@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/src/desk/team-scope.mjs

@@ -0,0 +1,142 @@
+// team-scope.mjs — shared project-visibility scoping for every read surface
+// that enumerates projects/*/project.json (desk overview/today/projects,
+// `pa project list`, `pa status`'s in-process `desk overview`).
+//
+// Why this exists: the operator repo's projects/ directory is materialised
+// from multiple teams via a library-sync transport (see work item
+// w-2026-07-14-008). Without scoping, one team's read surfaces show every
+// other team's projects with no way to tell them apart at a glance.
+//
+// Scoping key: project.executor, falling back to project.assignee. This is
+// deliberate — `owner` is a human name (e.g. "Barry") that can be shared
+// across teams working for the same person under different agent
+// identities, so it cannot discriminate. `executor`/`assignee` carry the
+// *agent* identity that actually does the work, which is unique per team.
+//
+// Own-team is a SET, not a single name: in real estates `assignee` carries
+// a mix of agent names ("dave") and role names ("system-architect") on
+// projects that belong to the same team. Matching against paName alone
+// would silently hide the role-assigned projects. The effective set is
+// `preferences.json:teamIdentities` (string[]) when present, else
+// `[paName]` — and paName is ALWAYS a member even if teamIdentities omits
+// it (belt-and-braces: the local agent must never scope out its own
+// directly-assigned projects through a config oversight).
+//
+// Fail-open: a project with neither `executor` nor `assignee` set is
+// unclassifiable. It is always shown in the default scoped view — hiding
+// unowned work silently is a worse failure than a little noise.
+//
+// Backward compatibility: scoping only activates when the operator repo
+// opts in via `operator/config/preferences.json:scopeProjectsToTeam = true`.
+// With no config and no flags, behaviour is unchanged from pre-scoping
+// desk/pa (show everything). This is load-bearing — existing installs must
+// not silently start hiding projects on a package bump.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Resolve the agent identity a project is scoped to, or null if the
+ * project carries no identity field at all (unclassifiable -> fail open).
+ */
+export function resolveProjectIdentity(project) {
+  if (!project) return null;
+  return project.executor || project.assignee || null;
+}
+
+/**
+ * True if `project` belongs to the local team under the default scoped
+ * view. `selfIdentities` is the team-identity set (Set or array of
+ * strings — mixed agent names and role names; see header note).
+ * Unclassifiable projects (no executor/assignee) count as "own" for the
+ * purposes of the default view — see fail-open note above.
+ */
+export function isOwnProject(project, selfIdentities) {
+  const identity = resolveProjectIdentity(project);
+  if (identity == null) return true;
+  const set = selfIdentities instanceof Set ? selfIdentities : new Set(selfIdentities || []);
+  return set.has(identity);
+}
+
+/**
+ * Filter a project list per the team-scoping rules.
+ *
+ * Precedence:
+ *   1. `team` explicit filter (--team <identity>) — strict: only projects
+ *      whose resolved identity matches exactly. Unclassifiable projects are
+ *      NOT included here; the fail-open guarantee applies to the default
+ *      view, not to a narrow explicit query for one specific team.
+ *   2. `allTeams` (--all-teams) — bypass scoping entirely, return input
+ *      unchanged.
+ *   3. `scopeEnabled` false (no config opt-in) — bypass scoping entirely,
+ *      return input unchanged (backward compatibility).
+ *   4. Default scoped view — own projects + unclassifiable (fail open).
+ *
+ * @param {object[]} projects
+ * @param {object} opts
+ * @param {string[]|Set<string>} opts.selfIdentities - local team-identity
+ *   set (effective set from readTeamScopeConfig: teamIdentities ∪ {paName})
+ * @param {boolean} opts.scopeEnabled - config opt-in state
+ * @param {boolean} [opts.allTeams] - explicit bypass
+ * @param {string|null} [opts.team] - explicit single-identity filter
+ */
+export function filterProjectsByTeam(projects, opts = {}) {
+  const { selfIdentities = [], scopeEnabled = false, allTeams = false, team = null } = opts;
+
+  if (team) {
+    return projects.filter((p) => resolveProjectIdentity(p) === team);
+  }
+  if (allTeams) return projects;
+  if (!scopeEnabled) return projects;
+
+  const set = selfIdentities instanceof Set ? selfIdentities : new Set(selfIdentities);
+  return projects.filter((p) => isOwnProject(p, set));
+}
+
+/**
+ * Read the team-scoping config out of operator/config/preferences.json.
+ * Falls back to disabled scoping + no identity if the file is missing or
+ * malformed — same fail-open posture as the filter itself.
+ *
+ * `teamIdentities` in the returned object is the EFFECTIVE set, already
+ * resolved: `preferences.teamIdentities` (string[], non-string entries
+ * dropped) when present, else `[paName]` — with paName always unioned in
+ * even when the configured list omits it (documented belt-and-braces: the
+ * local agent can never scope out its own directly-assigned projects).
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<{ paName: string, teamIdentities: string[], scopeEnabled: boolean }>}
+ */
+export async function readTeamScopeConfig(repoRoot) {
+  let paName = 'pa';
+  let configured = null;
+  let scopeEnabled = false;
+  try {
+    const raw = await readFile(join(repoRoot, 'operator', 'config', 'preferences.json'), 'utf8');
+    const config = JSON.parse(raw);
+    paName = config.paName || config.agentName || 'pa';
+    scopeEnabled = config.scopeProjectsToTeam === true;
+    if (Array.isArray(config.teamIdentities)) {
+      configured = config.teamIdentities.filter((x) => typeof x === 'string' && x.length > 0);
+    }
+  } catch {
+    // Missing/malformed file -> defaults above (scoping disabled).
+  }
+  const teamIdentities = [...new Set([paName, ...(configured || [])])];
+  return { paName, teamIdentities, scopeEnabled };
+}
+
+/**
+ * Parse the two team-scope flags out of an argv-style array. Does not
+ * consume/mutate the input; callers that also parse other flags should
+ * run this in addition to their own parsing (or fold it in — see
+ * commands.mjs `parseFilters`).
+ */
+export function parseTeamScopeFlags(args) {
+  const out = { allTeams: false, team: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--all-teams') out.allTeams = true;
+    else if (args[i] === '--team') out.team = args[++i] ?? null;
+  }
+  return out;
+}

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

@@ -0,0 +1,112 @@
+// distill — CLI.
+//
+// Arg parsing (node:util.parseArgs, strict:true), verb routing,
+// exit-code translation per §5–§6 of the tooling standard.
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { defaultRepoRoot } from './prereqs.mjs';
+import { runDistill } from './run.mjs';
+import { defaultRunner } from './runner.mjs';
+
+const USAGE = `distill — librarian distillation sweep runner
+
+Usage:
+  distill run                Run a real distillation sweep
+  distill run --dry-run      Print what would run, don't invoke claude
+  distill -h, --help         Show this help
+
+Exit codes:
+  0  ok
+  1  usage error
+  2  prerequisite missing / operational failure
+  3  claude / git transport failure
+
+Source of truth for behaviour: @stravica-ai/engineering-pa-core/docs/tools/distill.md
+`;
+
+// Best-effort runs.jsonl write for the CLI-bootstrap failure path.
+//
+// runDistill() writes its own audit records on every documented exit
+// branch via writeAudit() in run.mjs. This handler covers the residual
+// gap: a *synchronous* throw before/around runDistill (a parseArgs
+// strict-mode TypeError, an import surfaced as a runtime crash, a
+// destructuring failure on a malformed argv, etc) — without it, the
+// catch in main() would report to stderr and exit non-zero with no
+// runs.jsonl entry, leaving a hole in the always-log invariant the
+// freshness monitor depends on.
+//
+// Defensive on every step: best-effort path resolution, mkdir -p the
+// logs dir, append. Any failure here is swallowed with a stderr note —
+// losing the audit line is less bad than masking the real exit code.
+async function writeBootstrapAudit({ err, exitCode, stderr }) {
+  try {
+    const repoRoot = await defaultRepoRoot();
+    if (!repoRoot) {
+      stderr.write(`[distill] warning: no repo root resolved; skipping bootstrap audit\n`);
+      return;
+    }
+    const logDir = join(repoRoot, '.cache/distill/logs');
+    const runsLog = join(logDir, 'runs.jsonl');
+    await mkdir(logDir, { recursive: true });
+    const record = {
+      ts: new Date().toISOString(),
+      status: 'fail-cli-bootstrap',
+      exitCode,
+      durationSec: 0,
+      stagingCount: null,
+      log: null,
+      reason: `cli bootstrap failure: ${err?.message || err}`,
+    };
+    await appendFile(runsLog, JSON.stringify(record) + '\n');
+  } catch (auditErr) {
+    stderr.write(`[distill] warning: failed to append bootstrap audit record: ${auditErr.message}\n`);
+  }
+}
+
+export async function main(
+  argv,
+  { stderr = process.stderr, exit = process.exit, audit = writeBootstrapAudit } = {},
+) {
+  try {
+    return await route(argv);
+  } catch (err) {
+    const code = err?.distillExitCode ?? 2;
+    stderr.write(`[distill] ${err.message || err}\n`);
+    await audit({ err, exitCode: code, stderr });
+    exit(code);
+  }
+}
+
+async function route(argv) {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  const verb = argv[0];
+  const rest = argv.slice(1);
+
+  if (verb === 'run') {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        'dry-run': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+    if (values.help) {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    const code = await runDistill({ dryRun: values['dry-run'], runner: defaultRunner });
+    process.exit(code ?? 0);
+  }
+
+  process.stderr.write(`[distill] unknown command: ${verb}\n`);
+  process.stderr.write(USAGE);
+  process.exit(1);
+}

package/dist/engineering-pa-core/src/distill/prereqs.mjs

@@ -0,0 +1,171 @@
+// distill — prerequisite resolution.
+//
+// Locates the operator repo root, reads the PA name from preferences, validates
+// the librarian role definition and the claude binary exist. Throws errors
+// carrying `distillExitCode` so the CLI maps to the correct exit code (§6 of
+// the tooling standard: 1 usage, 2 operational).
+//
+// In v2 the platform is installed as the `@stravica-ai/engineering-pa-core`
+// package inside the operator repo. The librarian definition is bundled with
+// the package (this same module's tree), and the log directory lives inside
+// the operator repo at `.cache/distill/` (gitignored — §16 of the standard).
+//
+// Repo-root discovery (in order):
+//   1. opts.repoRoot — explicit caller override (used by tests).
+//   2. process.env.DAVE_REPO_ROOT / PA_REPO_ROOT — operator override.
+//   3. `.git`-walk upwards from process.cwd().
+
+import { access, readFile, mkdir, stat } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// The package's bundled librarian definition. From this module
+// (`packages/core/src/distill/prereqs.mjs`) the file lives at
+// `../../roles/librarian/definition.md` — i.e. inside the same package tree.
+export const BUNDLED_LIBRARIAN_DEF = resolve(__dirname, '..', '..', 'roles', 'librarian', 'definition.md');
+
+async function pathKind(p) {
+  try {
+    const s = await stat(p);
+    if (s.isDirectory()) return 'dir';
+    if (s.isFile()) return 'file';
+    return 'other';
+  } catch {
+    return 'missing';
+  }
+}
+
+export async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const kind = await pathKind(join(d, '.git'));
+    if (kind === 'dir' || kind === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+/**
+ * Best-effort repo-root discovery. Returns null if nothing is found; callers
+ * decide whether that is a usage error or an operational error.
+ */
+export async function defaultRepoRoot() {
+  const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (envRoot) return resolve(envRoot);
+  return await findRepoRoot(process.cwd());
+}
+
+export async function exists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function opError(msg) {
+  const err = new Error(msg);
+  err.distillExitCode = 2;
+  return err;
+}
+
+export async function resolvePrereqs({
+  repoRoot,
+  librarianDef,
+  which = defaultWhich,
+} = {}) {
+  const root = repoRoot || (await defaultRepoRoot());
+  if (!root) {
+    throw opError('could not find repo root (no .git ancestor; set DAVE_REPO_ROOT or PA_REPO_ROOT)');
+  }
+  if (!(await exists(join(root, '.git')))) {
+    throw opError(`could not find repo root at ${root}`);
+  }
+
+  const prefsFile = join(root, 'operator/config/preferences.json');
+  if (!(await exists(prefsFile))) {
+    throw opError(`missing preferences at ${prefsFile}`);
+  }
+
+  let prefs;
+  try {
+    prefs = JSON.parse(await readFile(prefsFile, 'utf8'));
+  } catch (err) {
+    throw opError(`failed to parse preferences at ${prefsFile}: ${err.message}`);
+  }
+
+  const paName = prefs.paName;
+  if (!paName || typeof paName !== 'string') {
+    throw opError(`no paName configured in ${prefsFile}`);
+  }
+
+  // Librarian definition resolution (highest precedence first):
+  //   1. explicit opts.librarianDef (tests pass a fixture path here) —
+  //      the caller controls the whole prompt; no supplement is applied;
+  //   2. full operator override at
+  //      operator/extensions/roles/librarian/definition.md — the operator
+  //      has taken ownership of the whole prompt; no supplement is applied
+  //      even if overrides.md also exists (back-compat with pre-supplement
+  //      operator repos is byte-for-byte);
+  //   3. bundled definition + operator supplement at
+  //      operator/extensions/roles/librarian/overrides.md — run.mjs appends
+  //      the supplement after the bundled definition with an explicit
+  //      operator-wins precedence statement;
+  //   4. bundled definition alone (BUNDLED_LIBRARIAN_DEF).
+  //
+  // This module resolves *paths* only; reading and composing the content
+  // is run.mjs's job. `librarianSupplement` is null for outcomes 1, 2, 4.
+  let resolvedLibrarianDef;
+  let resolvedLibrarianSupplement = null;
+  if (librarianDef) {
+    resolvedLibrarianDef = librarianDef;
+  } else {
+    const operatorOverride = join(root, 'operator/extensions/roles/librarian/definition.md');
+    if (await exists(operatorOverride)) {
+      resolvedLibrarianDef = operatorOverride;
+    } else {
+      resolvedLibrarianDef = BUNDLED_LIBRARIAN_DEF;
+      const operatorSupplement = join(root, 'operator/extensions/roles/librarian/overrides.md');
+      if (await exists(operatorSupplement)) {
+        resolvedLibrarianSupplement = operatorSupplement;
+      }
+    }
+  }
+  if (!(await exists(resolvedLibrarianDef))) {
+    throw opError(`missing librarian definition at ${resolvedLibrarianDef}`);
+  }
+
+  // Log directory in the operator repo, gitignored per the tooling standard §16.
+  const logDir = join(root, '.cache/distill/logs');
+  await mkdir(logDir, { recursive: true });
+
+  if (!(await which('claude'))) {
+    throw opError('claude binary not on PATH');
+  }
+
+  return {
+    repoRoot: root,
+    paName,
+    librarianDef: resolvedLibrarianDef,
+    librarianSupplement: resolvedLibrarianSupplement,
+    logDir,
+    runsLog: join(logDir, 'runs.jsonl'),
+  };
+}
+
+async function defaultWhich(binary) {
+  const PATH = process.env.PATH || '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      if (await exists(join(dir, binary + ext))) return true;
+    }
+  }
+  return false;
+}

package/dist/engineering-pa-core/src/distill/prompt.mjs

@@ -0,0 +1,74 @@
+// distill — prompt assembly. Pure string building; no I/O.
+//
+// The DISTILL_PROMPT instructs the librarian session to rebuild retrieval
+// indexes after promoting observations. In v2 the retrieval tools ship inside
+// the `@stravica-ai/engineering-pa-core` package, not at `core/knowledge/retrieval/`
+// in the operator repo. Concrete absolute paths are computed at runtime so
+// Claude invokes the correct binaries from inside its session.
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Absolute paths to the bundled retrieval tools. From this module
+// (`packages/core/src/distill/prompt.mjs`) the retrieval tools live at
+// `../knowledge/retrieval/`.
+export const RETRIEVAL_INDEX_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'index-builder.mjs');
+export const RETRIEVAL_BACKLINK_INDEXER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'backlink-indexer.mjs');
+export const RETRIEVAL_GRAPH_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'graph-builder.mjs');
+
+/**
+ * Build the distillation prompt text. Absolute paths are interpolated for the
+ * retrieval-tool invocations so Claude doesn't have to guess at install
+ * locations.
+ */
+export function buildDistillPrompt({
+  indexBuilder = RETRIEVAL_INDEX_BUILDER,
+  backlinkIndexer = RETRIEVAL_BACKLINK_INDEXER,
+  graphBuilder = RETRIEVAL_GRAPH_BUILDER,
+} = {}) {
+  return `You are operating as the Librarian. Run a full distillation sweep now.
+
+## Instructions
+
+1. **Scan all staging areas.** Process every markdown file in agents/*/staging/ (skip _archived/).
+
+2. **Extract durable knowledge.** For each observation:
+   - If it reveals something about the operator: update operator/profile/operator.json
+   - If it belongs in a knowledge domain: file it into operator/knowledge/ under the appropriate domain
+   - If it captures a reusable pattern or decision: ensure it is recorded
+
+3. **Synthesise the operator profile narrative.** After updating operator/profile/operator.json, regenerate operator/profile/profile.md as a human-readable markdown narrative derived from the JSON plus the body of accumulated observations. This is the file the workspace and PA read first; it must always exist and reflect current state. Replace it in full each run — it is a derived artefact, not an append log.
+
+4. **Rebuild indexes.** After all content changes, run these in order:
+   - node ${indexBuilder}
+   - node ${backlinkIndexer}
+   - node ${graphBuilder}
+
+5. **Library hygiene check.** Per your role definition — verify JSON camelCase, cross-reference integrity, index completeness, and lastUpdated freshness. Fix violations in place.
+
+6. **Archive processed observations.** Move each processed staging file to agents/{agent}/staging/_archived/ (create the directory if needed).
+
+7. **Report.** Summarise what was processed, what was promoted, what was archived, and any hygiene findings.`;
+}
+
+/**
+ * Back-compat constant: the prompt assembled with default (bundled) paths.
+ * Existing consumers that import DISTILL_PROMPT keep working; new callers
+ * should use buildDistillPrompt() with explicit overrides where needed.
+ */
+export const DISTILL_PROMPT = buildDistillPrompt();
+
+export function claudeArgs({ sessionName, librarianDef, prompt = DISTILL_PROMPT }) {
+  // Positional prompt last. No shell interpolation — this array is
+  // handed directly to child_process.spawn.
+  return [
+    '--print',
+    '--permission-mode', 'bypassPermissions',
+    '--no-session-persistence',
+    '--name', sessionName,
+    '--append-system-prompt', librarianDef,
+    prompt,
+  ];
+}