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

package/dist/engineering-pa-core/src/autonomy/envelope.mjs

@@ -0,0 +1,301 @@
+// envelope.mjs — pure functions for autonomy-envelope frontmatter parsing +
+// rendering. Zero IO. All filesystem side effects live in cli.mjs.
+//
+// The envelope is a markdown file with a YAML frontmatter block carrying the
+// machine-readable state. We ship our own minimal YAML reader/writer here
+// (limited to the shape the schema defines) to avoid pulling in a YAML dep
+// for such a narrow surface. Any file whose frontmatter falls outside the
+// documented shape is rejected as invalid.
+
+export const VALID_STATES = ['fullyApproved', 'checkBeforeCommitting', 'needsFullSupervision'];
+
+const STATE_LABELS = {
+  fullyApproved: 'fully approved',
+  checkBeforeCommitting: 'check before committing',
+  needsFullSupervision: 'needs full supervision',
+};
+
+/**
+ * Parse an autonomy-envelope markdown file. Returns
+ *   { frontmatter, body }
+ * where `frontmatter` matches the schema shape and `body` is the markdown
+ * after the closing `---`. Throws on malformed input; the error carries an
+ * `exitCode` for the CLI to propagate.
+ */
+export function parseEnvelope(source) {
+  if (typeof source !== 'string' || source.length === 0) {
+    throwUsage('envelope file is empty');
+  }
+  const lines = source.split(/\r?\n/);
+  if (lines[0].trim() !== '---') {
+    throwParse('envelope must start with YAML frontmatter delimited by ---');
+  }
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx < 0) {
+    throwParse('unterminated YAML frontmatter (missing closing ---)');
+  }
+  const fmLines = lines.slice(1, closeIdx);
+  const bodyLines = lines.slice(closeIdx + 1);
+  const frontmatter = parseFrontmatter(fmLines);
+  return { frontmatter, body: bodyLines.join('\n') };
+}
+
+/**
+ * Parse a limited-shape YAML block. Supports:
+ *   key: value                      (string)
+ *   key:                            (empty list start)
+ *     - key: value                  (list item — object)
+ *       key: value
+ * Numbers, booleans, and nested maps beyond one level are NOT supported —
+ * the schema doesn't need them. Values are always treated as strings.
+ */
+function parseFrontmatter(lines) {
+  const out = {};
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) { i++; continue; }
+    const match = raw.match(/^([a-zA-Z][a-zA-Z0-9]*):(?:\s*(.*))?$/);
+    if (!match) {
+      throwParse(`could not parse frontmatter line ${i + 1}: ${raw}`);
+    }
+    const key = match[1];
+    const value = (match[2] ?? '').trim();
+    if (value === '') {
+      // Expect either a list (starts with "- " at next non-empty indented
+      // line) or an empty value.
+      const listItems = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const peek = lines[j];
+        if (peek.trim() === '' || peek.trim().startsWith('#')) { j++; continue; }
+        if (!/^\s+-\s/.test(peek)) break;
+        const item = readListItem(lines, j);
+        listItems.push(item.value);
+        j = item.next;
+      }
+      out[key] = listItems;
+      i = j;
+    } else {
+      out[key] = stripQuotes(value);
+      i++;
+    }
+  }
+  return out;
+}
+
+function readListItem(lines, start) {
+  const first = lines[start];
+  const indentMatch = first.match(/^(\s+)-\s/);
+  if (!indentMatch) {
+    throwParse(`expected list item at line ${start + 1}: ${first}`);
+  }
+  const itemIndent = indentMatch[1] + '  '; // continuation is deeper than "- "
+  const item = {};
+  // The "- key: value" first line is the first key on the item.
+  const firstBody = first.slice(indentMatch[0].length);
+  const firstMatch = firstBody.match(/^([a-zA-Z][a-zA-Z0-9]*):\s*(.*)$/);
+  if (!firstMatch) {
+    throwParse(`could not parse list item at line ${start + 1}: ${first}`);
+  }
+  item[firstMatch[1]] = stripQuotes(firstMatch[2].trim());
+  let j = start + 1;
+  while (j < lines.length) {
+    const peek = lines[j];
+    if (peek.trim() === '' || peek.trim().startsWith('#')) { j++; continue; }
+    // Terminate when indent doesn't extend the item (either new list item
+    // at the same "- " indent, or dedent back to a top-level key).
+    if (peek.startsWith(itemIndent)) {
+      const bodyLine = peek.slice(itemIndent.length);
+      const m = bodyLine.match(/^([a-zA-Z][a-zA-Z0-9]*):\s*(.*)$/);
+      if (!m) {
+        throwParse(`could not parse list item continuation at line ${j + 1}: ${peek}`);
+      }
+      item[m[1]] = stripQuotes(m[2].trim());
+      j++;
+    } else {
+      break;
+    }
+  }
+  return { value: item, next: j };
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Render an envelope object (frontmatter shape) back to markdown. Body is
+ * regenerated: a current-state table + a history log preserved from prior
+ * body sections. This keeps the file readable + deterministic.
+ */
+export function renderEnvelope(frontmatter, history = []) {
+  const fm = renderFrontmatter(frontmatter);
+  const body = renderBody(frontmatter, history);
+  return `---\n${fm}---\n\n${body}\n`;
+}
+
+function renderFrontmatter(fm) {
+  const lines = [];
+  lines.push(`agent: ${quoteIfNeeded(fm.agent)}`);
+  lines.push(`owner: ${quoteIfNeeded(fm.owner)}`);
+  lines.push(`updated: ${quoteIfNeeded(fm.updated)}`);
+  lines.push('taskTypes:');
+  const items = fm.taskTypes ?? [];
+  for (const item of items) {
+    lines.push(`  - id: ${quoteIfNeeded(item.id)}`);
+    lines.push(`    label: ${quoteIfNeeded(item.label)}`);
+    lines.push(`    state: ${quoteIfNeeded(item.state)}`);
+    if (item.stateSince) lines.push(`    stateSince: ${quoteIfNeeded(item.stateSince)}`);
+    if (item.operatorNote) lines.push(`    operatorNote: ${quoteIfNeeded(item.operatorNote)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function quoteIfNeeded(value) {
+  if (value == null) return '""';
+  const str = String(value);
+  // Quote values that could be misparsed as YAML control sequences.
+  if (/^[\s"'#\-\[\{,&*!|>%@`]/.test(str)) return JSON.stringify(str);
+  if (/[:#]\s/.test(str)) return JSON.stringify(str);
+  if (str.trim() !== str) return JSON.stringify(str);
+  return str;
+}
+
+function renderBody(fm, history) {
+  const lines = [];
+  lines.push(`# Autonomy envelope — ${fm.agent}`);
+  lines.push('');
+  lines.push('## Current state');
+  lines.push('');
+  if (!fm.taskTypes || fm.taskTypes.length === 0) {
+    lines.push('_No task types configured. Use `pa autonomy set <agent> <task-type> <state>` to add one._');
+  } else {
+    lines.push('| Task type | State | Since | Note |');
+    lines.push('|---|---|---|---|');
+    for (const item of fm.taskTypes) {
+      const since = (item.stateSince ?? '').slice(0, 10);
+      const note = (item.operatorNote ?? '—').replace(/\|/g, '\\|');
+      lines.push(`| ${escapeCell(item.label)} | ${STATE_LABELS[item.state] ?? item.state} | ${since || '—'} | ${note} |`);
+    }
+  }
+  lines.push('');
+  lines.push('## History');
+  lines.push('');
+  const entries = [...history].sort((a, b) => (b.at ?? '').localeCompare(a.at ?? ''));
+  if (entries.length === 0) {
+    lines.push('_No history yet._');
+  } else {
+    for (const entry of entries) {
+      lines.push(`### ${entry.at} — ${entry.taskTypeId} → ${entry.state}`);
+      if (entry.note) {
+        lines.push('');
+        lines.push(`Operator note: ${entry.note}`);
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n');
+}
+
+function escapeCell(str) {
+  return String(str).replace(/\|/g, '\\|');
+}
+
+/**
+ * Extract history entries from a rendered body. Returns an array of
+ *   { at, taskTypeId, state, note }
+ * entries. Best-effort — malformed sections are skipped, not raised.
+ */
+export function extractHistory(body) {
+  const entries = [];
+  if (typeof body !== 'string') return entries;
+  const lines = body.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = line.match(/^###\s+(\S+)\s+—\s+([a-z0-9][a-z0-9-]*)\s+→\s+([A-Za-z]+)\s*$/);
+    if (!match) { i++; continue; }
+    const at = match[1];
+    const taskTypeId = match[2];
+    const state = match[3];
+    let note = null;
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === '') j++;
+    if (j < lines.length && lines[j].startsWith('Operator note:')) {
+      note = lines[j].slice('Operator note:'.length).trim();
+    }
+    entries.push({ at, taskTypeId, state, note });
+    i = j + 1;
+  }
+  return entries;
+}
+
+/**
+ * Validate a frontmatter object against the schema. Throws on invalid;
+ * returns nothing on valid.
+ */
+export function validateFrontmatter(fm) {
+  if (!fm || typeof fm !== 'object') throwParse('frontmatter must be an object');
+  requireString(fm, 'agent');
+  requireString(fm, 'owner');
+  requireString(fm, 'updated');
+  if (!Array.isArray(fm.taskTypes)) throwParse('taskTypes must be an array');
+  for (const [i, item] of fm.taskTypes.entries()) {
+    if (!item || typeof item !== 'object') throwParse(`taskTypes[${i}] must be an object`);
+    requireString(item, `taskTypes[${i}].id`, item.id);
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(item.id)) throwParse(`taskTypes[${i}].id '${item.id}' must match ^[a-z0-9][a-z0-9-]*$`);
+    requireString(item, `taskTypes[${i}].label`, item.label);
+    requireString(item, `taskTypes[${i}].state`, item.state);
+    if (!VALID_STATES.includes(item.state)) {
+      throwParse(`taskTypes[${i}].state '${item.state}' must be one of ${VALID_STATES.join(', ')}`);
+    }
+  }
+}
+
+function requireString(obj, field, value) {
+  const v = value ?? obj?.[field];
+  if (typeof v !== 'string' || v.length === 0) {
+    throwParse(`${field} must be a non-empty string`);
+  }
+}
+
+function throwParse(msg) {
+  const err = new Error(msg);
+  err.exitCode = 2;
+  throw err;
+}
+
+function throwUsage(msg) {
+  const err = new Error(msg);
+  err.exitCode = 1;
+  throw err;
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function emptyEnvelope(agent, owner) {
+  return {
+    frontmatter: {
+      agent,
+      owner,
+      updated: nowIso(),
+      taskTypes: [],
+    },
+    history: [],
+  };
+}

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

@@ -10,6 +10,9 @@
   "bin": {
     "pa-init": "bin/pa-init"
   },
+  "dependencies": {
+    "@stravica-ai/engineering-pa-core": "workspace:*"
+  },
   "private": true,
   "license": "MIT",
   "engines": {

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

@@ -11,6 +11,8 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { emptyEnvelope, renderEnvelope } from '../../engineering-pa-core/src/autonomy/envelope.mjs';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 /** Path to the CLAUDE.md template (relative to this module). */
@@ -254,6 +256,25 @@ export function buildJournalMd(config) {
   ].join('\n');
 }
 
+/**
+ * Build the agents/{paName}/autonomy-envelope.md placeholder. The
+ * envelope tracks per-task-type approval state; ships as a stub so the
+ * CLAUDE.md template's reference resolves on day one and the agent
+ * baseline audit (`pa agent audit`) passes on a fresh scaffold.
+ *
+ * Uses the autonomy package's own `emptyEnvelope` + `renderEnvelope`
+ * seeders so the stub always round-trips through `parseEnvelope` — no
+ * risk of `pa autonomy get/set/list` throwing on a fresh scaffold
+ * because the seeder shape drifted from the parser's contract.
+ * `generatedAt` (a fixed ISO from the runner) pins `updated:` so the
+ * scaffold plan is deterministic.
+ */
+export function buildAutonomyEnvelopeMd(config) {
+  const { frontmatter } = emptyEnvelope(config.paName, config.operatorName);
+  frontmatter.updated = config.generatedAt;
+  return renderEnvelope(frontmatter, []);
+}
+
 /** Build the agents/{paName}/next-session.md placeholder. */
 export function buildNextSessionMd(config) {
   return [
@@ -303,6 +324,7 @@ export function buildPlanFromTemplates(config, templates) {
   const profile = buildProfileMd(config);
   const journal = buildJournalMd(config);
   const nextSession = buildNextSessionMd(config);
+  const autonomyEnvelope = buildAutonomyEnvelopeMd(config);
 
   const dirs = [
     'operator',
@@ -339,6 +361,7 @@ export function buildPlanFromTemplates(config, templates) {
   plan.push({ kind: 'file', path: `agents/${paName}/CLAUDE.md`, contents: claudeMd });
   plan.push({ kind: 'file', path: `agents/${paName}/journal.md`, contents: journal });
   plan.push({ kind: 'file', path: `agents/${paName}/next-session.md`, contents: nextSession });
+  plan.push({ kind: 'file', path: `agents/${paName}/autonomy-envelope.md`, contents: autonomyEnvelope });
   plan.push({ kind: 'json', path: `agents/${paName}/spawn-log.json`, contents: spawnLog });
 
   // Empty-directory markers — git won't track empty dirs.

package/dist/engineering-pa-workspace/app/index.html

@@ -339,19 +339,24 @@
       navItems = document.querySelectorAll('.nav-item');
     })
     .then(function() { navigate(pathFromHash()); });
-  // Load dynamic branding from API
+  // Load dynamic branding from API. Subtitle prefers the config-driven role
+  // title (preferences.json → pa.roleTitle, surfaced as data.paRoleTitle) so
+  // each estate can show its PA's role (e.g. "System Architect",
+  // "Forward-Deployed Lead Operator"); absent config falls back to the product
+  // name "Digital Operator", pixel-identical to the pre-config behaviour.
   fetch('/__api/overview').then(function(r) { return r.json(); }).then(function(data) {
     var brandName = document.getElementById('brand-name');
     var brandSub = document.getElementById('brand-subtitle');
+    var subtitle = data.paRoleTitle || 'Digital Operator';
     if (data.paName) {
       var name = data.paName;
       var capName = name.charAt(0).toUpperCase() + name.slice(1);
       brandName.textContent = capName;
-      document.title = capName + ' — Digital Operator';
+      document.title = capName + ' — ' + subtitle;
     } else {
       brandName.textContent = 'Workspace';
     }
-    brandSub.textContent = 'Digital Operator';
+    brandSub.textContent = subtitle;
   }).catch(function() {
     document.getElementById('brand-name').textContent = 'Workspace';
     document.getElementById('brand-subtitle').textContent = 'Digital Operator';

package/dist/engineering-pa-workspace/src/api.mjs

@@ -846,13 +846,22 @@ function buildOverview(projects, work, repoRoot) {
     const status = item.status || 'unknown';
     workByStatus[status] = (workByStatus[status] || 0) + 1;
   }
-  // Read PA name from preferences if available
+  // Read PA name + optional display role title from preferences if available.
+  // paRoleTitle is a NEW, dedicated display field (`pa.roleTitle`) rather than
+  // an alias for the existing `pa.role` category token — `pa.role` defaults to
+  // 'PA' from the scaffold and would silently replace the 'Digital Operator'
+  // subtitle on every existing estate. paRoleTitle is null unless explicitly
+  // configured, so absent config keeps the pre-existing subtitle fallback.
   let paName = null;
+  let paRoleTitle = null;
   try {
     const prefsFile = join(repoRoot, 'operator', 'config', 'preferences.json');
     if (existsSync(prefsFile)) {
       const prefs = JSON.parse(readFileSync(prefsFile, 'utf-8'));
       paName = prefs.paName || null;
+      if (prefs.pa && typeof prefs.pa.roleTitle === 'string' && prefs.pa.roleTitle.length) {
+        paRoleTitle = prefs.pa.roleTitle;
+      }
     }
   } catch (e) { /* non-fatal */ }
   // Read operator name and role from profile
@@ -868,6 +877,7 @@ function buildOverview(projects, work, repoRoot) {
   } catch (e) { /* non-fatal */ }
   return {
     paName: paName,
+    paRoleTitle: paRoleTitle,
     operatorName: operatorName,
     operatorRole: operatorRole,
     projectCount: projectCount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
@@ -53,6 +53,6 @@
   "scripts": {
     "build": "node build.mjs",
     "test": "node --test --test-isolation=none test/*.test.mjs",
-    "dry-publish": "node build.mjs && pnpm publish --dry-run --no-git-checks"
+    "dry-publish": "node build.mjs && node scripts/dry-publish.mjs"
   }
 }