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

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/agent/cli.mjs

@@ -29,6 +29,7 @@ import { hostname as osHostname } from 'node:os';
 import { dirname, join } from 'node:path';
 
 import { loadBundledManifestSync } from '../../../engineering-pa-core/src/agent-baseline/manifest.mjs';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 
 import { auditManifest } from './audit.mjs';
 import { getRepoRoot } from '../pa/repo-root.mjs';
@@ -201,12 +202,9 @@ function isStale(cache, stalenessMinutes) {
 
 function readStalenessMinutes(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      const value = prefs?.agentAudit?.cacheStalenessMinutes;
-      if (typeof value === 'number' && value > 0) return value;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    const value = prefs?.agentAudit?.cacheStalenessMinutes;
+    if (typeof value === 'number' && value > 0) return value;
   } catch {
     // fall through
   }
@@ -215,11 +213,8 @@ function readStalenessMinutes(repoRoot) {
 
 function readPaName(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.paName === 'string' && prefs.paName.length > 0) return prefs.paName;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.paName === 'string' && prefs.paName.length > 0) return prefs.paName;
   } catch {
     // fall through
   }

package/dist/engineering-pa-cli/src/coordinator-hook/self.mjs

@@ -11,15 +11,15 @@
 //
 // Returns a string paName, or null when unresolved.
 
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readPreferences } from '../../../engineering-pa-core/src/preferences.mjs';
 
 export async function resolveSelfAgent(repoRoot, env = process.env) {
   if (env.PA_SELF_AGENT) return env.PA_SELF_AGENT;
   if (!repoRoot) return null;
   try {
-    const raw = await readFile(join(repoRoot, 'operator', 'config', 'preferences.json'), 'utf8');
-    const config = JSON.parse(raw);
+    // Overlay-aware: preferences.local.json shallow-merges OVER the shared
+    // preferences.json so a device-local paName wins for the coordinator hook.
+    const config = await readPreferences(repoRoot);
     if (config && typeof config.paName === 'string' && config.paName.trim()) {
       return config.paName.trim();
     }

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

@@ -22,6 +22,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getRepoRoot } from '../pa/repo-root.mjs';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import {
   probePlatform,
   probeRuntimes,
@@ -252,12 +253,9 @@ function isStale(cache, stalenessMinutes) {
 
 function readStalenessMinutes(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      const value = prefs?.environment?.cacheStalenessMinutes;
-      if (typeof value === 'number' && value > 0) return value;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    const value = prefs?.environment?.cacheStalenessMinutes;
+    if (typeof value === 'number' && value > 0) return value;
   } catch {
     // fall through
   }

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

@@ -10,6 +10,7 @@ import { arch, platform, release, homedir } from 'node:os';
 import { basename, join, resolve, dirname } from 'node:path';
 import { resolve4 } from 'node:dns/promises';
 import { fileURLToPath } from 'node:url';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 
 const execFileP = promisify(execFile);
 
@@ -234,11 +235,8 @@ export async function probeWorkspace(repoRoot) {
 
 function readWorkspacePort(repoRoot) {
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.workspacePort === 'number') return prefs.workspacePort;
   } catch {
     // fall through
   }

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

@@ -10,6 +10,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { run as runDesk } from '../../../engineering-pa-core/src/desk/cli.mjs';
 import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
+import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -198,11 +199,8 @@ async function doStatus(opts = {}) {
 function resolveWorkspacePort(repoRoot, opts = {}) {
   if (opts.workspacePort) return opts.workspacePort;
   try {
-    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
-    if (existsSync(prefsPath)) {
-      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
-      if (typeof prefs.workspacePort === 'number') return prefs.workspacePort;
-    }
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.workspacePort === 'number') return prefs.workspacePort;
   } catch { /* fall through to default */ }
   return 4200;
 }

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;
+}