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

package/dist/engineering-pa-cli/scripts/migrate-doc-paths.mjs

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+// migrate-doc-paths.mjs — one-shot data migration for the repo-relative
+// doc-path contract (Baz ruling 2026-08-06, w-2026-08-06-007).
+//
+// Background:
+//   `pa project doc add <id> --path <p>` used to store <p> verbatim with
+//   no validation. Operators frequently supplied project-relative paths
+//   (`docs/foo.md`, `equity-analysis.md`), which then 404'd in the
+//   workspace viewer because the viewer's file API resolves paths against
+//   the repo root. Ruling: repo-relative wins (see doc-path.mjs header).
+//
+// What this does:
+//   For every entry in projects/*\/project.json:docs (both flat-array and
+//   grouped shape), apply the same normalisation rule as the runtime CLI:
+//     - resolves as-is under repoRoot         -> untouched
+//     - resolves only under projects/<id>/    -> rewrite path to the joined form
+//     - resolves neither way                  -> REPORT only (never rewrite, never delete)
+//
+// Shape preservation:
+//   Entries may carry {label, path}, {label, path, status}, {group, label,
+//   path}, or {title, path, role} (bowmark-legal). This script only ever
+//   rewrites the `path` string on entries where the join rule triggers.
+//   Every other key stays exactly as it was, in its original insertion
+//   order. Docs shape (flat vs grouped) is preserved — the script does not
+//   promote flat arrays to grouped.
+//
+// Idempotence:
+//   After a successful --apply run, a second dry-run reports 0 joins.
+//
+// Usage:
+//   node <script> [--repo <path>] [--apply] [--json]
+//
+//   --repo <path>  Operator repo root. Defaults to $DAVE_REPO_ROOT /
+//                  $PA_REPO_ROOT, else walks upward from cwd for .git.
+//   --apply        Actually write the mutated project.json files. Default
+//                  is dry-run (no writes).
+//   --json         Emit the per-entry report as JSON on stdout instead of
+//                  a human-readable log.
+//
+// Exit codes (tooling-standard §6):
+//   0 ok (regardless of unresolvables — they are reported, not gated).
+//   1 usage error / invalid --repo / project.json parse failure.
+//   2 filesystem write failure.
+
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve, relative, isAbsolute, sep, posix } from 'node:path';
+
+// -- args --------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = { repo: null, apply: false, json: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') out.help = true;
+    else if (a === '--apply') out.apply = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--repo') {
+      out.repo = argv[i + 1];
+      i += 1;
+    } else if (a.startsWith('--repo=')) {
+      out.repo = a.slice('--repo='.length);
+    } else {
+      throw usageError(`unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+const USAGE = `migrate-doc-paths — normalise project.json doc entries to repo-relative paths.
+
+Usage:
+  node migrate-doc-paths.mjs [--repo <path>] [--apply] [--json]
+
+Options:
+  --repo <path>  Operator repo root. Defaults to $DAVE_REPO_ROOT / $PA_REPO_ROOT,
+                 else walks upward from the current directory for a .git marker.
+  --apply        Actually write the changes. Default is dry-run.
+  --json         Emit the per-entry report as JSON on stdout.
+  -h, --help     Show this help.
+
+Behaviour:
+  For every projects/*\/project.json:docs entry, apply the same normalisation
+  rule as \`pa project doc add\`:
+    - path resolves under repoRoot                -> untouched
+    - path resolves only under projects/<id>/     -> rewrite to the joined form
+    - neither resolves                            -> REPORT only (no rewrite, no delete)
+
+  Entry shape is preserved exactly — only the \`path\` string is ever mutated.
+  Docs shape (flat array vs grouped object) is preserved.
+
+Exit codes:
+  0 ok  |  1 usage/invalid input  |  2 filesystem write failure.
+`;
+
+function usageError(msg) {
+  const err = new Error(msg);
+  err.exitCode = 1;
+  return err;
+}
+
+// -- repo root discovery -----------------------------------------------------
+
+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'; }
+}
+
+async function findRepoRoot(start) {
+  let d = start;
+  while (d && d !== dirname(d)) {
+    const k = await pathKind(join(d, '.git'));
+    if (k === 'dir' || k === 'file') return d;
+    d = dirname(d);
+  }
+  return null;
+}
+
+async function resolveRepoRoot(explicit) {
+  if (explicit) {
+    const abs = resolve(explicit);
+    if (!existsSync(abs)) throw usageError(`--repo path does not exist: ${abs}`);
+    return abs;
+  }
+  const env = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
+  if (env) return resolve(env);
+  const found = await findRepoRoot(process.cwd());
+  if (!found) throw usageError(`could not find repo root from ${process.cwd()} (no .git ancestor)`);
+  return found;
+}
+
+// -- normalisation (mirrors packages/cli/src/pa/doc-path.mjs) ---------------
+
+// A tiny in-file re-implementation of the same rule so this script has
+// zero cross-package coupling and stays runnable as a plain node script
+// after install. Keep in lockstep with doc-path.mjs — the migration
+// script's tests pin the equivalence.
+function classify({ repoRoot, projectId, docPath }) {
+  if (!docPath || typeof docPath !== 'string') {
+    return { action: 'report-unresolvable', reason: 'empty or non-string path' };
+  }
+  if (isAbsolute(docPath)) {
+    return { action: 'report-unresolvable', reason: `absolute path: ${docPath}` };
+  }
+  const asIsAbs = resolve(repoRoot, docPath);
+  if (insideRepo(repoRoot, asIsAbs) && existsSync(asIsAbs)) {
+    return { action: 'untouched', absPath: asIsAbs, storedPath: toPosix(docPath) };
+  }
+  const joinedAbs = resolve(repoRoot, 'projects', projectId, docPath);
+  if (insideRepo(repoRoot, joinedAbs) && existsSync(joinedAbs)) {
+    return {
+      action: 'joined',
+      absPath: joinedAbs,
+      storedPath: toPosix(relative(repoRoot, joinedAbs)),
+    };
+  }
+  return {
+    action: 'report-unresolvable',
+    reason: 'not found as-is under repoRoot nor when joined under projects/<id>/',
+    triedAsIs: asIsAbs,
+    triedJoined: joinedAbs,
+  };
+}
+
+function insideRepo(repoRoot, absPath) {
+  const rel = relative(repoRoot, absPath);
+  if (rel.startsWith('..')) return false;
+  return resolve(repoRoot, rel) === absPath;
+}
+
+function toPosix(p) {
+  if (sep === posix.sep) return p;
+  return p.split(sep).join(posix.sep);
+}
+
+// -- walk + rewrite ----------------------------------------------------------
+
+async function listProjectDirs(projectsRoot) {
+  let entries;
+  try { entries = await readdir(projectsRoot, { withFileTypes: true }); }
+  catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+
+// Read + parse a project.json. Returns { manifest, raw } or null when the
+// file is missing / unreadable / unparseable. Parse failure is reported
+// upstream so the operator sees it.
+async function readManifest(manifestPath) {
+  if (!existsSync(manifestPath)) return null;
+  const raw = await readFile(manifestPath, 'utf8');
+  try {
+    return { manifest: JSON.parse(raw), raw };
+  } catch (err) {
+    throw usageError(`failed to parse ${manifestPath}: ${err.message}`);
+  }
+}
+
+// Walk one project's docs and yield per-entry rows. Docs may be a flat
+// array (legacy) or a grouped object. Entries may carry any set of keys —
+// we only reason about `.path`.
+function* iterDocEntries(docs) {
+  if (docs == null) return;
+  if (Array.isArray(docs)) {
+    for (let i = 0; i < docs.length; i++) {
+      yield { group: null, index: i, entry: docs[i] };
+    }
+    return;
+  }
+  if (typeof docs === 'object') {
+    for (const [group, arr] of Object.entries(docs)) {
+      if (!Array.isArray(arr)) continue;
+      for (let i = 0; i < arr.length; i++) {
+        yield { group, index: i, entry: arr[i] };
+      }
+    }
+  }
+}
+
+// Reassign only `.path` on the entry object. All other keys stay in place
+// and in their original insertion order because we mutate rather than
+// spread — `{...entry, path: X}` would re-order path to the end.
+function rewritePathInPlace(entry, newPath) {
+  entry.path = newPath;
+}
+
+// Serialise back to the operator-repo JSON convention (2-space, trailing
+// newline). Matches io.mjs's writeJson.
+function stringifyManifest(manifest) {
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
+async function processProject({ repoRoot, projectId, apply }) {
+  const manifestPath = join(repoRoot, 'projects', projectId, 'project.json');
+  const loaded = await readManifest(manifestPath);
+  if (!loaded) return { projectId, missingManifest: true, rows: [] };
+  const { manifest, raw } = loaded;
+  const rows = [];
+  let dirty = false;
+
+  for (const { group, index, entry } of iterDocEntries(manifest.docs)) {
+    if (!entry || typeof entry !== 'object') {
+      rows.push({ projectId, group, index, entry, action: 'skipped-not-an-object' });
+      continue;
+    }
+    const docPath = entry.path;
+    const cls = classify({ repoRoot, projectId, docPath });
+    const row = { projectId, group, index, path: docPath, entryShape: Object.keys(entry).sort() };
+    if (cls.action === 'untouched') {
+      row.action = 'untouched';
+    } else if (cls.action === 'joined') {
+      row.action = 'joined';
+      row.newPath = cls.storedPath;
+      if (apply) {
+        rewritePathInPlace(entry, cls.storedPath);
+        dirty = true;
+      }
+    } else {
+      row.action = 'report-unresolvable';
+      row.reason = cls.reason;
+      if (cls.triedAsIs) row.triedAsIs = cls.triedAsIs;
+      if (cls.triedJoined) row.triedJoined = cls.triedJoined;
+    }
+    rows.push(row);
+  }
+
+  let wrote = false;
+  if (apply && dirty) {
+    // Preserve the file exactly if nothing changed; only touch on real change.
+    const next = stringifyManifest(manifest);
+    if (next !== raw) {
+      try {
+        await writeFile(manifestPath, next, 'utf8');
+        wrote = true;
+      } catch (err) {
+        const e = new Error(`failed to write ${manifestPath}: ${err.message}`);
+        e.exitCode = 2;
+        throw e;
+      }
+    }
+  }
+  return { projectId, manifestPath, rows, wrote, dirty };
+}
+
+// -- reporting ---------------------------------------------------------------
+
+function summarise(results) {
+  let untouched = 0, joined = 0, unresolvable = 0, skipped = 0;
+  let projectsWritten = 0;
+  const unresolvables = [];
+  const joins = [];
+  for (const r of results) {
+    if (r.wrote) projectsWritten += 1;
+    for (const row of r.rows) {
+      if (row.action === 'untouched') untouched += 1;
+      else if (row.action === 'joined') { joined += 1; joins.push(row); }
+      else if (row.action === 'report-unresolvable') { unresolvable += 1; unresolvables.push(row); }
+      else skipped += 1;
+    }
+  }
+  return { untouched, joined, unresolvable, skipped, projectsWritten, unresolvables, joins };
+}
+
+function renderHumanLog(results, summary, { apply, repoRoot }) {
+  const out = [];
+  out.push(`migrate-doc-paths ${apply ? '(APPLY)' : '(dry-run)'}  repo: ${repoRoot}`);
+  out.push('');
+  for (const r of results) {
+    if (r.missingManifest) continue;
+    if (r.rows.length === 0) continue;
+    out.push(`# ${r.projectId}`);
+    for (const row of r.rows) {
+      if (row.action === 'untouched') {
+        out.push(`  ok       ${formatLocation(row)}  ${row.path}`);
+      } else if (row.action === 'joined') {
+        out.push(`  join     ${formatLocation(row)}  ${row.path}  ->  ${row.newPath}`);
+      } else if (row.action === 'report-unresolvable') {
+        out.push(`  UNRESOLV ${formatLocation(row)}  ${row.path}`);
+        out.push(`             reason: ${row.reason}`);
+        if (row.triedAsIs) out.push(`             tried as-is:  ${row.triedAsIs}`);
+        if (row.triedJoined) out.push(`             tried joined: ${row.triedJoined}`);
+      } else {
+        out.push(`  skip     ${formatLocation(row)}  ${row.action}`);
+      }
+    }
+    if (r.wrote) out.push(`  -> wrote ${r.manifestPath}`);
+    else if (r.dirty && !apply) out.push(`  (dry-run: would write ${r.manifestPath})`);
+    out.push('');
+  }
+  out.push('---');
+  out.push(`untouched:     ${summary.untouched}`);
+  out.push(`joined:        ${summary.joined}${apply ? '' : ' (dry-run — no files written)'}`);
+  out.push(`unresolvable:  ${summary.unresolvable} (report-only; no entries deleted)`);
+  if (summary.skipped) out.push(`skipped:       ${summary.skipped}`);
+  out.push(`projects ${apply ? 'written' : 'that would be written'}: ${summary.projectsWritten}`);
+  return out.join('\n') + '\n';
+}
+
+function formatLocation(row) {
+  const group = row.group == null ? 'flat' : `[${row.group}]`;
+  return `${group}#${row.index}`.padEnd(14, ' ');
+}
+
+// -- main --------------------------------------------------------------------
+
+export async function main(argv) {
+  let args;
+  try { args = parseArgs(argv); }
+  catch (err) {
+    process.stderr.write(err.message + '\n');
+    process.stderr.write(USAGE);
+    return err.exitCode || 1;
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let repoRoot;
+  try { repoRoot = await resolveRepoRoot(args.repo); }
+  catch (err) {
+    process.stderr.write(err.message + '\n');
+    return err.exitCode || 1;
+  }
+  const projectsRoot = join(repoRoot, 'projects');
+  const projectIds = await listProjectDirs(projectsRoot);
+  const results = [];
+  for (const projectId of projectIds) {
+    try {
+      const r = await processProject({ repoRoot, projectId, apply: args.apply });
+      results.push(r);
+    } catch (err) {
+      process.stderr.write(err.message + '\n');
+      return err.exitCode || 2;
+    }
+  }
+  const summary = summarise(results);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      repoRoot,
+      apply: args.apply,
+      summary: {
+        untouched: summary.untouched,
+        joined: summary.joined,
+        unresolvable: summary.unresolvable,
+        skipped: summary.skipped,
+        projectsWritten: summary.projectsWritten,
+      },
+      results,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderHumanLog(results, summary, { apply: args.apply, repoRoot }));
+  }
+  return 0;
+}
+
+// Export the helpers so the test suite can pin per-piece behaviour without
+// spawning a subprocess.
+export { classify, iterDocEntries, processProject, summarise };
+
+// Direct-run entrypoint.
+const isDirectRun =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('/migrate-doc-paths.mjs');
+
+if (isDirectRun) {
+  main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write((err.stack || err.message || String(err)) + '\n');
+      process.exit(err.exitCode || 2);
+    });
+}

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-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.14",
+  "version": "0.1.16",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",