@stravica-ai/digital-operator-pa 0.1.13 → 0.1.16

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

@@ -0,0 +1,66 @@
+# scaffold — baseline manifest + scaffold seeds
+
+Machine-readable baselines that shape every fresh PA and every audit against a running one.
+
+## `agent-baseline.json`
+
+The list of capabilities every operator PA is expected to carry. Each entry is a mechanical presence-probe: `pa agent audit` (packages/cli/src/agent/) diffs an agent estate against this file and reports gaps.
+
+Two failure classes it covers, in priority order:
+
+1. **Drift** — the platform grows a capability, existing agents never adopt. This is the motivating case. Boot-slice shipped in core 0.1.7, one estate adopted, another never noticed for months. The audit turns adoption into a generated to-do instead of a memory test.
+2. **Creation-time gaps** — a new agent scaffolded by `pa-init` boots missing standard kit. `packages/scaffold/test/manifest-coverage.test.mjs` runs the manifest against the pa-init plan and fails the build if any agents-local capability with a static-path probe is uncovered.
+
+### Version-coupling convention
+
+Every capability entry carries a `sinceVersion` (the `@stravica-ai/engineering-pa-core` release that introduced it) and the manifest as a whole carries a `manifestVersion` integer.
+
+**When a new capability lands:**
+
+1. Add the entry to `agent-baseline.json`.
+2. Bump `manifestVersion` by 1.
+3. Set the entry's `sinceVersion` to the core version the change ships in.
+4. Note the manifest bump in `CHANGELOG.md` under the release (line pattern: `agent-baseline: added <capability-id> at manifestVersion N`).
+
+**When a capability is removed** (rare — retired platform feature): bump `manifestVersion` and note the removal in the changelog. Never rename an `id` — retire and add.
+
+### Probe types (v1)
+
+Each probe carries a `type` and its own required fields (see `agent-baseline.schema.json`):
+
+| Type | Purpose |
+|---|---|
+| `file-exists` | File at `path` exists. `{paName}` token substituted. |
+| `directory-exists` | Directory at `path` exists (must be a dir, not a file). |
+| `knowledge-doc-exists` | Semantic alias for `file-exists` on `operator/knowledge/**/*.md`. Kept as its own type so future extensions (graph presence, non-orphan) can enrich the check. |
+| `staging-recent-write` | Directory exists AND has a non-hidden entry younger than `maxAgeDays`. Fails only if the newest entry is older than the window. Use with `severity: warn` — a quiet week is not a broken agent. |
+| `schedule-defined` | A JSON file under `path` (typically `schedules/`) whose `command` includes ALL of `commandIncludes` and (if given) AT LEAST ONE of `commandIncludesAny`, and is not `enabled: false`. Host-pinned schedules produce `unverified-here` when the audited host doesn't match. Use with `hostDependent: true`. |
+| `json-field-includes` | Open a JSON file at `path`, check that top-level `field` is an array containing `expectedValue` (token-substituted). Optional `requiredTool` gates the probe: absent tool = `unverified-here`. |
+
+### Outcome ladder
+
+| Rendered status | When |
+|---|---|
+| `pass` | Probe matched. |
+| `warn` | Probe failed AND capability has `severity: warn` — informational, never gates `--strict`. |
+| `fail` | Probe failed AND capability has `severity: fail` (default). Gates `--strict`. |
+| `unverified-here` | Mechanically indeterminate on this host — host-pinned capability declared for another host, required tool absent from the estate, probe threw. Never a false pass, never a false fail. |
+
+### Named defaults (ratified with the operator on approval)
+
+- `pa agent audit` exit code default = 0 (informational tool). `--strict` opts into CI-gating exit 2 on any `fail`.
+- `staging-recent-write` window = 7 days, severity `warn` (quiet-week tolerance).
+- Host-dependent probes report `unverified-here`, never `fail`. Precision over noise.
+- Manifest ships in `packages/core/knowledge/scaffold/` (single-bundled via `packages/engineering-pa/build.mjs`), not a separate schema package.
+- Cache path `.session/agent-audit.json`, mirroring `pa environment`'s `.session/environment.json`.
+- `sinceVersion` is the `@stravica-ai/engineering-pa-core` version, not the platform tarball version (manifest lives in core).
+
+### Consumers
+
+- **`pa agent audit`** — session-boot drift detection. Reads the cache; auto-refreshes on stale.
+- **`pa-init`** (via `manifest-coverage.test.mjs`) — creation-time coverage guard. New capabilities that CAN be scaffolded MUST be scaffolded, or the test fails and forces the scaffold plan update at the same time as the manifest bump.
+- **Future: `boot-context`** — the session-boot hook can surface a one-liner (`3/11 capabilities need adoption`) into the injected workState block.
+
+## `domains.json`
+
+The base set of knowledge domains seeded into every fresh PA — unchanged by this pass.

package/dist/engineering-pa-core/knowledge/scaffold/agent-baseline.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "./agent-baseline.schema.json",
+  "schemaVersion": "1.0",
+  "manifestVersion": 1,
+  "description": "Baseline capabilities every operator PA agent is expected to carry. Each entry is a mechanical presence-probe: `pa agent audit` diffs an agent estate against this manifest and reports gaps. New capabilities land here at the same time as the platform release that ships them, so drift becomes a generated to-do instead of a memory test. Version-coupling convention: bump `manifestVersion` whenever a new capability entry lands; set the capability's `sinceVersion` to the @stravica-ai/engineering-pa-core release that introduced it. Host-dependent probes MUST carry `hostDependent:true` so a mismatched host is reported as `unverified-here`, not a false fail.",
+  "capabilities": [
+    {
+      "id": "spawn-log",
+      "label": "Spawn-log JSON present",
+      "sinceVersion": "0.1.0",
+      "rationale": "Every dispatch must leave a trail; the spawn-log is the machine-readable record the librarian sweeps.",
+      "probe": {
+        "type": "file-exists",
+        "path": "agents/{paName}/spawn-log.json"
+      }
+    },
+    {
+      "id": "journal",
+      "label": "Self-improvement journal present",
+      "sinceVersion": "0.1.0",
+      "rationale": "Every PA keeps a journal — the substrate for the librarian's distillation pass.",
+      "probe": {
+        "type": "file-exists",
+        "path": "agents/{paName}/journal.md"
+      }
+    },
+    {
+      "id": "next-session",
+      "label": "Next-session handover file present",
+      "sinceVersion": "0.1.0",
+      "rationale": "Session-boundary continuity — the top of the file is operator-facing.",
+      "probe": {
+        "type": "file-exists",
+        "path": "agents/{paName}/next-session.md"
+      }
+    },
+    {
+      "id": "autonomy-envelope",
+      "label": "Autonomy-envelope file present",
+      "sinceVersion": "0.1.0",
+      "rationale": "Per-task-type approval state — the durable record the PA checks when the reflex is unclear.",
+      "probe": {
+        "type": "file-exists",
+        "path": "agents/{paName}/autonomy-envelope.md"
+      }
+    },
+    {
+      "id": "staging-dir",
+      "label": "Staging directory present",
+      "sinceVersion": "0.1.0",
+      "rationale": "Real-time observation staging — the librarian's inbox. Absent staging dir means the PA has no place to write in-session observations.",
+      "probe": {
+        "type": "directory-exists",
+        "path": "agents/{paName}/staging"
+      }
+    },
+    {
+      "id": "staging-recent-write",
+      "label": "Staging directory has a recent write",
+      "sinceVersion": "0.1.0",
+      "rationale": "Warns (never fails) if the staging dir has been quiet for longer than the tolerated window — a signal that real-time staging discipline has drifted, but tolerant of legitimate quiet weeks.",
+      "severity": "warn",
+      "probe": {
+        "type": "staging-recent-write",
+        "path": "agents/{paName}/staging",
+        "maxAgeDays": 7
+      }
+    },
+    {
+      "id": "session-end-sop-overlay",
+      "label": "Session-boot-and-end SOP overlay present",
+      "sinceVersion": "0.1.0",
+      "rationale": "The estate-side SOP that layers over the core session-end routine — its absence means the PA is running on the core baseline only, with no estate customisation applied.",
+      "probe": {
+        "type": "knowledge-doc-exists",
+        "path": "operator/knowledge/operator-interface/session-boot-and-end.md"
+      }
+    },
+    {
+      "id": "boot-slice-job",
+      "label": "Boot-slice schedule + output file",
+      "sinceVersion": "0.1.7",
+      "rationale": "The lightweight boot slice is what the PA loads on every session boot instead of the full profile. Its regeneration is scheduled on a profile-bearing host; the output file must exist somewhere in the estate.",
+      "hostDependent": true,
+      "probe": {
+        "type": "schedule-defined",
+        "path": "schedules",
+        "commandIncludes": ["slice generate"],
+        "outputPathHints": ["operator/profile/slices/"]
+      }
+    },
+    {
+      "id": "library-sync-up",
+      "label": "Library-sync up-path scheduled",
+      "sinceVersion": "0.1.5",
+      "rationale": "Fresh estate content must reach canonical on every device that authors it; a missing up-path is the mechanism that produced the 2026-07-14 stale-clobber family.",
+      "hostDependent": true,
+      "probe": {
+        "type": "schedule-defined",
+        "path": "schedules",
+        "commandIncludes": ["library-sync"],
+        "commandIncludesAny": ["--up", "library-sync-cycle"]
+      }
+    },
+    {
+      "id": "library-sync-down",
+      "label": "Library-sync down-path scheduled",
+      "sinceVersion": "0.1.5",
+      "rationale": "Every device must materialise the freshest canonical content. On devices that use the cycle orchestrator the down leg is embedded; standalone down-only schedules also satisfy this probe.",
+      "hostDependent": true,
+      "probe": {
+        "type": "schedule-defined",
+        "path": "schedules",
+        "commandIncludes": ["library-sync"],
+        "commandIncludesAny": ["--down", "library-sync-cycle", "library-sync-refresh"]
+      }
+    },
+    {
+      "id": "relay-agent-registration",
+      "label": "Agent id registered in claude-relay config",
+      "sinceVersion": "0.1.0",
+      "rationale": "Cross-agent transport requires the agent id to appear in `operator/extensions/tools/claude-relay/config.json:agents`; absence means no cross-machine relay traffic can address this PA.",
+      "probe": {
+        "type": "json-field-includes",
+        "path": "operator/extensions/tools/claude-relay/config.json",
+        "field": "agents",
+        "expectedValue": "{paName}",
+        "requiredTool": "claude-relay"
+      }
+    }
+  ]
+}

package/dist/engineering-pa-core/knowledge/scaffold/agent-baseline.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Baseline Manifest",
+  "description": "Machine-readable baseline of capabilities every operator PA is expected to carry. Consumed by `pa agent audit` and by `pa-init` at scaffold time.",
+  "type": "object",
+  "required": ["schemaVersion", "manifestVersion", "capabilities"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "type": "string", "const": "1.0" },
+    "manifestVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic manifest version. Bump on every capability addition/removal so an audit can detect its own manifest is behind."
+    },
+    "description": { "type": "string" },
+    "capabilities": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/capability" }
+    }
+  },
+  "definitions": {
+    "capability": {
+      "type": "object",
+      "required": ["id", "label", "sinceVersion", "rationale", "probe"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+          "description": "Stable capability id — kebab-case, referenced in audit output. Never renamed once shipped."
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-facing one-liner rendered in audit summaries."
+        },
+        "sinceVersion": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "@stravica-ai/engineering-pa-core version that introduced this capability."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Why this capability exists in the baseline. Renders in --verbose audit output."
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["fail", "warn"],
+          "default": "fail",
+          "description": "How a missing/failing probe is reported. `warn` never contributes to a non-zero --strict exit."
+        },
+        "hostDependent": {
+          "type": "boolean",
+          "default": false,
+          "description": "Declares the capability lives on a specific host or subset of hosts. The audit's fail-vs-unverified-here treatment is probe-specific: only `schedule-defined` currently reads host-shape (via each schedule's `host` field) and upgrades a matching-schedule-on-wrong-host outcome to `unverified-here`. For all other probe types, `hostDependent:true` is documentary metadata only — a mechanical fail (missing file, missing directory, missing field) is reported as `fail`, because a missing artefact is missing on every host, not just this one. The upgrade is deliberately kept probe-local: a generic 'hostDependent+fail → unverified-here' fold would silence genuine estate-wide gaps that no host has."
+        },
+        "probe": {
+          "oneOf": [
+            { "$ref": "#/definitions/probeFileExists" },
+            { "$ref": "#/definitions/probeDirectoryExists" },
+            { "$ref": "#/definitions/probeStagingRecentWrite" },
+            { "$ref": "#/definitions/probeKnowledgeDocExists" },
+            { "$ref": "#/definitions/probeScheduleDefined" },
+            { "$ref": "#/definitions/probeJsonFieldIncludes" }
+          ]
+        }
+      }
+    },
+    "probeFileExists": {
+      "type": "object",
+      "required": ["type", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "file-exists" },
+        "path": { "type": "string", "description": "Path relative to repo root. Tokens: {paName}." }
+      }
+    },
+    "probeDirectoryExists": {
+      "type": "object",
+      "required": ["type", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "directory-exists" },
+        "path": { "type": "string" }
+      }
+    },
+    "probeKnowledgeDocExists": {
+      "type": "object",
+      "required": ["type", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "knowledge-doc-exists" },
+        "path": { "type": "string" }
+      }
+    },
+    "probeStagingRecentWrite": {
+      "type": "object",
+      "required": ["type", "path", "maxAgeDays"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "staging-recent-write" },
+        "path": { "type": "string" },
+        "maxAgeDays": { "type": "number", "minimum": 1 }
+      }
+    },
+    "probeScheduleDefined": {
+      "type": "object",
+      "required": ["type", "path", "commandIncludes"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "schedule-defined" },
+        "path": { "type": "string", "description": "Directory containing schedule JSON files (typically `schedules`)." },
+        "commandIncludes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "description": "Substrings that MUST all appear (AND) in a schedule's `command` field."
+        },
+        "commandIncludesAny": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Substrings where AT LEAST ONE (OR) must appear in the same schedule's command."
+        },
+        "outputPathHints": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Optional path substrings that, if present in the estate, corroborate the schedule's declared output."
+        }
+      }
+    },
+    "probeJsonFieldIncludes": {
+      "type": "object",
+      "required": ["type", "path", "field", "expectedValue"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "json-field-includes" },
+        "path": { "type": "string" },
+        "field": { "type": "string", "description": "Top-level JSON field name (dot-path not supported in v1)." },
+        "expectedValue": { "type": "string", "description": "Value expected in the field's array. Tokens: {paName}." },
+        "requiredTool": {
+          "type": "string",
+          "description": "If set, the probe is skipped (unverified-here) when the named tool directory is absent under operator/extensions/tools/."
+        }
+      }
+    }
+  }
+}

package/dist/engineering-pa-core/src/agent-baseline/manifest.mjs

@@ -0,0 +1,139 @@
+// manifest.mjs — loader for the agent baseline manifest.
+//
+// The manifest itself lives at
+//   packages/core/knowledge/scaffold/agent-baseline.json
+// and is shipped inside the core package (single-bundled by
+// packages/engineering-pa/build.mjs at publish time). Downstream code
+// resolves the on-disk path via `bundledManifestPath()` — no hard-coded
+// consumer paths.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the manifest shipped inside this package. Resolves both
+ * in the dev workspace (packages/core/knowledge/scaffold/agent-baseline.json)
+ * and in the published tarball (dist/engineering-pa-core/knowledge/scaffold/agent-baseline.json).
+ */
+export function bundledManifestPath() {
+  return resolve(__dirname, '..', '..', 'knowledge', 'scaffold', 'agent-baseline.json');
+}
+
+/**
+ * Load the bundled manifest synchronously. Throws with a clear diagnostic
+ * if the file is missing or malformed — callers surface that via exit
+ * code 2 (unresolvable state).
+ */
+export function loadBundledManifestSync() {
+  const path = bundledManifestPath();
+  if (!existsSync(path)) {
+    const err = new Error(`agent baseline manifest missing at ${path}`);
+    err.exitCode = 2;
+    throw err;
+  }
+  const raw = readFileSync(path, 'utf8');
+  return parseManifest(raw, path);
+}
+
+/**
+ * Async loader for the bundled manifest. Same contract as the sync form.
+ */
+export async function loadBundledManifest() {
+  const path = bundledManifestPath();
+  const raw = await readFile(path, 'utf8');
+  return parseManifest(raw, path);
+}
+
+/**
+ * Parse + shape-validate a raw manifest string. Rejects obvious structural
+ * corruption (missing capabilities array, empty ids, unknown probe types)
+ * — a false PASS at boot time would be worse than a loud crash.
+ */
+export function parseManifest(raw, sourcePath = '<manifest>') {
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    const wrapped = new Error(`agent baseline manifest at ${sourcePath} is not valid JSON: ${err.message}`);
+    wrapped.exitCode = 2;
+    throw wrapped;
+  }
+  if (!doc || typeof doc !== 'object') {
+    throw shapeError(`manifest ${sourcePath}: not an object`);
+  }
+  if (doc.schemaVersion !== '1.0') {
+    throw shapeError(`manifest ${sourcePath}: schemaVersion must be "1.0" (got ${JSON.stringify(doc.schemaVersion)})`);
+  }
+  if (typeof doc.manifestVersion !== 'number' || !Number.isInteger(doc.manifestVersion) || doc.manifestVersion < 1) {
+    throw shapeError(`manifest ${sourcePath}: manifestVersion must be a positive integer`);
+  }
+  if (!Array.isArray(doc.capabilities)) {
+    throw shapeError(`manifest ${sourcePath}: capabilities must be an array`);
+  }
+  const seen = new Set();
+  for (const cap of doc.capabilities) {
+    validateCapability(cap, sourcePath, seen);
+  }
+  return doc;
+}
+
+function validateCapability(cap, sourcePath, seen) {
+  if (!cap || typeof cap !== 'object') {
+    throw shapeError(`manifest ${sourcePath}: capability entry is not an object`);
+  }
+  for (const field of ['id', 'label', 'sinceVersion', 'rationale']) {
+    if (typeof cap[field] !== 'string' || cap[field].length === 0) {
+      throw shapeError(`manifest ${sourcePath}: capability missing required string field '${field}'`);
+    }
+  }
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(cap.id)) {
+    throw shapeError(`manifest ${sourcePath}: capability id ${JSON.stringify(cap.id)} is not kebab-case`);
+  }
+  if (seen.has(cap.id)) {
+    throw shapeError(`manifest ${sourcePath}: duplicate capability id ${JSON.stringify(cap.id)}`);
+  }
+  seen.add(cap.id);
+  if (cap.severity && cap.severity !== 'fail' && cap.severity !== 'warn') {
+    throw shapeError(`manifest ${sourcePath}: capability ${cap.id} has invalid severity ${JSON.stringify(cap.severity)}`);
+  }
+  if (!cap.probe || typeof cap.probe !== 'object' || typeof cap.probe.type !== 'string') {
+    throw shapeError(`manifest ${sourcePath}: capability ${cap.id} has no probe.type`);
+  }
+  const supported = new Set([
+    'file-exists',
+    'directory-exists',
+    'staging-recent-write',
+    'knowledge-doc-exists',
+    'schedule-defined',
+    'json-field-includes',
+  ]);
+  if (!supported.has(cap.probe.type)) {
+    throw shapeError(`manifest ${sourcePath}: capability ${cap.id} declares unknown probe.type ${JSON.stringify(cap.probe.type)}`);
+  }
+}
+
+function shapeError(msg) {
+  const err = new Error(msg);
+  err.exitCode = 2;
+  return err;
+}
+
+/**
+ * Substitute {paName} tokens in a path template. Extend here if new tokens
+ * land — kept small on purpose (path templates are configuration, not code).
+ */
+export function expandTemplate(str, tokens) {
+  if (typeof str !== 'string') return str;
+  return str.replaceAll('{paName}', tokens.paName);
+}
+
+/**
+ * Derive the effective severity of a capability (default: fail).
+ */
+export function capabilitySeverity(cap) {
+  return cap.severity ?? 'fail';
+}