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

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

@@ -1,301 +1,20 @@
-// envelope.mjs — pure functions for autonomy-envelope frontmatter parsing +
-// rendering. Zero IO. All filesystem side effects live in cli.mjs.
+// envelope.mjs — re-export shim.
 //
-// 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: [],
-  };
-}
+// The envelope parse/render/seed logic lives in
+// `@stravica-ai/engineering-pa-core/src/autonomy/envelope.mjs` — pure, no
+// CLI coupling, so scaffold can seed a round-trippable stub without an
+// inverted package dependency (scaffold → core, not scaffold → cli).
+//
+// This shim exists so anything that historically imported from
+// `packages/cli/src/autonomy/envelope.mjs` (tests, internal callers)
+// keeps working. New callers should import from core directly.
+
+export {
+  VALID_STATES,
+  parseEnvelope,
+  renderEnvelope,
+  extractHistory,
+  validateFrontmatter,
+  nowIso,
+  emptyEnvelope,
+} from '../../../engineering-pa-core/src/autonomy/envelope.mjs';

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

@@ -27,6 +27,7 @@ Usage:
   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)
+  pa agent <verb>             Agent baseline audit (audit | audit refresh)
   pa staging-alias <verb>     Canonical staging.<site> alias for CF Workers sites (set | unset | status | list)
   pa lint <verb>              Lint operator text against voice rules (linkedin)
   pa migrate-inspect [options]  Host inspection for migration planning
@@ -76,6 +77,8 @@ export async function main(argv) {
       return await doAutonomy(rest);
     case 'environment':
       return await doEnvironment(rest);
+    case 'agent':
+      return await doAgent(rest);
     case 'lint':
       return await doLint(rest);
     case 'staging-alias':
@@ -276,6 +279,11 @@ async function doEnvironment(rest) {
   return await run(rest);
 }
 
+async function doAgent(rest) {
+  const { run } = await import('../agent/cli.mjs');
+  return await run(rest);
+}
+
 async function doStagingAlias(rest) {
   const { main } = await import('../staging-alias/cli.mjs');
   return await main(rest);

package/dist/engineering-pa-cli/src/pa/doc-path.mjs

@@ -0,0 +1,125 @@
+// doc-path.mjs — normalisation for project.json doc `path` entries.
+//
+// The contract (Baz ruling 2026-08-06 under the PA-stack domain):
+//   Doc paths stored in project.json:docs[*].path are REPO-relative.
+//
+// This matches the workspace viewer's file API (packages/workspace/src/api.mjs)
+// which resolves the `?file=` parameter against the operator repo root and
+// applies a traversal guard. Storing repo-relative paths keeps the CLI, the
+// stored data, and the viewer link on the same contract. Repo-relative also
+// expresses legitimate out-of-project references (operator/notes/*, cross-
+// project links) that project-relative cannot.
+//
+// The historical bug: `pa project doc add <id> --path <p>` stored `<p>`
+// verbatim. Operators frequently invoked it with a project-relative path
+// (e.g. `docs/foo.md`) because that reads naturally when their cwd is the
+// project dir. The resulting entry then 404'd in the workspace viewer.
+//
+// This module's normalisation resolves the three input cases at write time:
+//
+//   1. `<p>` resolves against repoRoot and exists         -> untouched
+//   2. `<p>` resolves against `projects/<id>/` and exists -> joined (with notice)
+//   3. neither resolves                                    -> refused
+//
+// Case 1 covers everything already correct (~96% of the estate) plus any
+// deliberate out-of-project reference. Case 2 is the failing case — the
+// input is auto-corrected to `projects/<id>/<p>`. Case 3 refuses to create
+// a dangling entry, matching the file API's own 404 contract.
+//
+// The normaliser is a pure function of (repoRoot, projectId, docPath) plus
+// filesystem existence — no state, no I/O beyond stat.
+
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve, relative, sep, posix } from 'node:path';
+
+/**
+ * Normalise a doc path against a project's location under the operator repo.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot   Absolute path to the operator repo root.
+ * @param {string} opts.projectId  Project id (matches the projects/<id>/ dir).
+ * @param {string} opts.docPath    The `--path` value as supplied by the caller.
+ *
+ * @returns {{ path: string, action: 'as-is'|'joined',
+ *             absPath: string, joinedFrom?: string }}
+ *          `path` is the value that should be stored (repo-relative, forward
+ *          slashes on any platform). `action` reports how it was resolved.
+ *          `absPath` is the resolved absolute path that DOES exist on disk.
+ *          When `action === 'joined'`, `joinedFrom` carries the original
+ *          input so callers can print a "normalised: X -> Y" notice.
+ *
+ * @throws {Error & {exitCode:1}} when the input resolves neither way, when
+ *          the input is absolute, or when the input escapes the repo root.
+ *          The message names the two candidate absolute paths that were
+ *          tried so the operator can diagnose immediately.
+ */
+export function normaliseDocPath({ repoRoot, projectId, docPath }) {
+  if (!repoRoot) throw makeError('normaliseDocPath: repoRoot is required');
+  if (!projectId) throw makeError('normaliseDocPath: projectId is required');
+  if (!docPath || typeof docPath !== 'string') {
+    throw makeError('normaliseDocPath: docPath must be a non-empty string');
+  }
+
+  // Absolute paths are refused outright — the contract is repo-relative,
+  // and an absolute path (a) breaks portability across machines and (b)
+  // will fail the workspace viewer's traversal guard even if we tried to
+  // rewrite it. Operator diagnosis is more useful when we say why.
+  if (isAbsolute(docPath)) {
+    throw makeError(
+      `path must be repo-relative, got absolute path: ${docPath}\n` +
+      `  the doc-path contract is repo-relative (see packages/workspace/src/api.mjs)`,
+    );
+  }
+
+  const asIsAbs = resolve(repoRoot, docPath);
+  const asIsInside = insideRepo(repoRoot, asIsAbs);
+  if (asIsInside && existsSync(asIsAbs)) {
+    return {
+      path: toPosix(docPath),
+      action: 'as-is',
+      absPath: asIsAbs,
+    };
+  }
+
+  const joinedAbs = resolve(repoRoot, 'projects', projectId, docPath);
+  const joinedInside = insideRepo(repoRoot, joinedAbs);
+  if (joinedInside && existsSync(joinedAbs)) {
+    const joinedRel = toPosix(relative(repoRoot, joinedAbs));
+    return {
+      path: joinedRel,
+      action: 'joined',
+      absPath: joinedAbs,
+      joinedFrom: docPath,
+    };
+  }
+
+  // Neither resolves — refuse with both candidates so the operator can see
+  // which one they meant to hit.
+  const asIsCandidate = asIsInside ? asIsAbs : `${asIsAbs} (outside repo root)`;
+  const joinedCandidate = joinedInside ? joinedAbs : `${joinedAbs} (outside repo root)`;
+  throw makeError(
+    `doc path does not resolve: ${docPath}\n` +
+    `  tried as-is:  ${asIsCandidate}\n` +
+    `  tried joined: ${joinedCandidate}\n` +
+    `  the doc-path contract is repo-relative — create the file first, or use --path <existing repo-relative path>`,
+  );
+}
+
+function insideRepo(repoRoot, absPath) {
+  const rel = relative(repoRoot, absPath);
+  if (rel.startsWith('..')) return false;
+  // Cross-platform: `path.resolve` uses OS-native separators. The api.mjs
+  // traversal guard does the same round-trip we do here.
+  return resolve(repoRoot, rel) === absPath;
+}
+
+function toPosix(p) {
+  if (sep === posix.sep) return p;
+  return p.split(sep).join(posix.sep);
+}
+
+function makeError(message) {
+  const err = new Error(message);
+  err.exitCode = 1;
+  return err;
+}

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

@@ -174,6 +174,7 @@ async function doDocAdd(args) {
       path: typeof flags.path === 'string' ? flags.path : null,
       status: typeof flags.status === 'string' ? flags.status : null,
     });
+    printNormalisationNotice(res.normalisation);
     if (res.changed) {
       let msg = `added "${res.label}" -> workstream [${res.workstream}] in ${id}`;
       if (res.status) msg += ` (status: ${res.status})`;
@@ -191,6 +192,7 @@ async function doDocAdd(args) {
     group: typeof flags.group === 'string' ? flags.group : null,
     status: typeof flags.status === 'string' ? flags.status : null,
   });
+  printNormalisationNotice(res.normalisation);
   if (res.changed) {
     let msg = `added "${res.label}" -> [${res.group}] in ${id}`;
     if (res.status) msg += ` (status: ${res.status})`;
@@ -201,6 +203,16 @@ async function doDocAdd(args) {
   return 0;
 }
 
+// Emit a one-line notice when the path was auto-joined under projects/<id>/.
+// Silent on `action === 'as-is'` — the vast majority of calls are already
+// correctly repo-relative and shouldn't be spammed.
+function printNormalisationNotice(normalisation) {
+  if (!normalisation || normalisation.action !== 'joined') return;
+  process.stdout.write(
+    `notice: path normalised to repo-relative — ${normalisation.inputPath} -> ${normalisation.storedPath}\n`,
+  );
+}
+
 async function doDocRm(args) {
   const { positional, flags } = parseFlags(args);
   if (positional.length === 0) {

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

@@ -19,6 +19,7 @@ import { join } from 'node:path';
 import { getRepoRoot } from './repo-root.mjs';
 import { readJson, writeJson, ensureDir, listSubdirs, today } from './io.mjs';
 import { addDoc, removeDocByPath, setDocStatus, DEFAULT_GROUP, VALID_DOC_STATUSES } from './doc-groups.mjs';
+import { normaliseDocPath } from './doc-path.mjs';
 import { filterProjectsByTeam, readTeamScopeConfig } from '../../../engineering-pa-core/src/desk/team-scope.mjs';
 
 const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
@@ -190,6 +191,11 @@ export async function setProjectStatus(id, status) {
 /**
  * Append a doc entry to a group. Migrates a legacy flat-array shape to
  * grouped in the same write. Idempotent on {label,path} match.
+ *
+ * The `--path` value is normalised against the repo-relative contract via
+ * `normaliseDocPath` before storage — an input that only resolves under
+ * `projects/<id>/` is auto-joined; an input that resolves neither way is
+ * refused. See `./doc-path.mjs` for the full contract.
  */
 export async function addProjectDoc(id, { label, path: docPath, group, status }) {
   validateId(id);
@@ -217,9 +223,11 @@ export async function addProjectDoc(id, { label, path: docPath, group, status })
     err.exitCode = 1;
     throw err;
   }
+  const normalised = normaliseDocPath({ repoRoot, projectId: id, docPath });
+  const storedPath = normalised.path;
   const manifest = await readJson(manifestPath);
   const before = JSON.stringify(manifest.docs);
-  const entry = { label, path: docPath };
+  const entry = { label, path: storedPath };
   if (status) entry.status = status;
   manifest.docs = addDoc(manifest.docs, group, entry);
   const after = JSON.stringify(manifest.docs);
@@ -231,10 +239,15 @@ export async function addProjectDoc(id, { label, path: docPath, group, status })
     id,
     group: group || DEFAULT_GROUP,
     label,
-    path: docPath,
+    path: storedPath,
     status: status || null,
     changed: before !== after,
     manifestPath,
+    normalisation: {
+      action: normalised.action,
+      inputPath: docPath,
+      storedPath,
+    },
   };
 }
 

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

@@ -21,6 +21,7 @@ import { join } from 'node:path';
 import { getRepoRoot } from './repo-root.mjs';
 import { readJson, writeJson, today } from './io.mjs';
 import { VALID_DOC_STATUSES } from './doc-groups.mjs';
+import { normaliseDocPath } from './doc-path.mjs';
 
 const STATUSES = new Set(['draft', 'planned', 'in-progress', 'blocked', 'done', 'archived']);
 
@@ -171,6 +172,11 @@ export async function removeWorkstream(projectId, { id: wsId }) {
 /**
  * Add a doc entry to a specific workstream's docs array.
  * Idempotent on {label, path} match within the workstream.
+ *
+ * The `--path` value is normalised against the repo-relative contract via
+ * `normaliseDocPath` before storage, mirroring `addProjectDoc` — inputs
+ * that only resolve under `projects/<id>/` are auto-joined, unresolvables
+ * are refused. See `./doc-path.mjs`.
  */
 export async function addDocToWorkstream(projectId, wsId, { label, path: docPath, status }) {
   validateWsId(wsId);
@@ -180,6 +186,10 @@ export async function addDocToWorkstream(projectId, wsId, { label, path: docPath
     fail(`invalid doc status: ${status} (expected one of: ${[...VALID_DOC_STATUSES].join(', ')})`);
   }
 
+  const repoRoot = await getRepoRoot();
+  const normalised = normaliseDocPath({ repoRoot, projectId, docPath });
+  const storedPath = normalised.path;
+
   const { manifest, path } = await loadProject(projectId);
   const workstreams = ensureWorkstreams(manifest);
   const ws = findWorkstream(workstreams, wsId);
@@ -187,15 +197,23 @@ export async function addDocToWorkstream(projectId, wsId, { label, path: docPath
 
   if (!Array.isArray(ws.docs)) ws.docs = [];
 
-  const dup = ws.docs.find((d) => d.path === docPath && d.label === label);
+  const dup = ws.docs.find((d) => d.path === storedPath && d.label === label);
   if (dup) {
-    return { projectId, workstream: wsId, label, path: docPath, status: status || null, changed: false, manifestPath: path };
+    return {
+      projectId, workstream: wsId, label, path: storedPath,
+      status: status || null, changed: false, manifestPath: path,
+      normalisation: { action: normalised.action, inputPath: docPath, storedPath },
+    };
   }
 
-  const entry = { label, path: docPath };
+  const entry = { label, path: storedPath };
   if (status) entry.status = status;
   ws.docs.push(entry);
 
   await saveProject(path, manifest);
-  return { projectId, workstream: wsId, label, path: docPath, status: status || null, changed: true, manifestPath: path };
+  return {
+    projectId, workstream: wsId, label, path: storedPath,
+    status: status || null, changed: true, manifestPath: path,
+    normalisation: { action: normalised.action, inputPath: docPath, storedPath },
+  };
 }

package/dist/engineering-pa-core/index.mjs

@@ -19,3 +19,16 @@ export { acquireLock, DEFAULT_STALE_AFTER_MS } from './src/lock/lock.mjs';
 // Distill prereqs / prompt — also useful as a library entry point.
 export { resolvePrereqs, defaultRepoRoot as distillDefaultRepoRoot, BUNDLED_LIBRARIAN_DEF } from './src/distill/prereqs.mjs';
 export { buildDistillPrompt, DISTILL_PROMPT, claudeArgs } from './src/distill/prompt.mjs';
+
+// Agent baseline manifest — machine-readable list of capabilities every
+// operator PA must carry. Consumed by `pa agent audit` (drift detection)
+// and by `pa-init` (creation-time coverage check). Docs:
+// packages/core/knowledge/scaffold/README.md.
+export {
+  bundledManifestPath,
+  loadBundledManifest,
+  loadBundledManifestSync,
+  parseManifest,
+  expandTemplate,
+  capabilitySeverity,
+} from './src/agent-baseline/manifest.mjs';