@brainervirus/workit-core 0.6.1 → 0.7.1

package/src/core/branch.ts

@@ -3,13 +3,23 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { gitContext } from "./git";
 import { readConfig, resolveBranchPolicy } from "./config";
+import { resolveWorkspace } from "./workspaces";
 import { vcsConfig } from "./vcs-config";
 
-const policy = () => resolveBranchPolicy(readConfig());
-const allowedBranch = (name: string) => policy().allowed.some((r) => r.test(name));
-const isProtected = (name: string) => policy().protected.has(name.toLowerCase());
-const baseBranch = (cwd: string) =>
-  String(vcsConfig("resolve", cwd).defaultTargetBranch ?? "develop");
+/** CA-09: the one policy resolver every consumer calls. */
+export const resolveBranchPolicyFor = (workspaceRoot: string) =>
+  resolveBranchPolicy(readConfig(), resolveWorkspace(workspaceRoot));
+
+const policy = (root: string) => resolveBranchPolicyFor(root);
+const allowedBranch = (root: string, name: string) =>
+  policy(root).allowed.some((r) => r.test(name));
+const isProtected = (root: string, name: string) => policy(root).protected.has(name.toLowerCase());
+// RL-01: malformed vcs.json blocks branch resolution with an exact-path error.
+const baseBranch = (cwd: string): { base: string } | { error: string } => {
+  const resolved = vcsConfig("resolve", cwd);
+  if (resolved.ok === false) return { error: String(resolved.error) };
+  return { base: String(resolved.defaultTargetBranch ?? "develop") };
+};
 const DECLARE_RE = /^\s*\*+Branch:\*+\s*`?([^`\s|]+)`?\s*$/gim;
 const USE_CURRENT_RE = /^\s*\*+Branch:\*+\s*use-current\s*$/im;
 const readSafe = (p: string): string | null => {
@@ -20,10 +30,10 @@ const readSafe = (p: string): string | null => {
   }
 };
 
-const normalizeBranch = (name: string): string | null => {
+const normalizeBranch = (root: string, name: string): string | null => {
   const n = name.trim().replace(/`/g, "").replace(/\.+$/, "");
-  if (isProtected(n)) return null;
-  if (!allowedBranch(n)) return null;
+  if (isProtected(root, n)) return null;
+  if (!allowedBranch(root, n)) return null;
   const parts = n
     .toLowerCase()
     .split("/")
@@ -94,14 +104,14 @@ export const resolveBranch = ({
     const text = readSafe(file);
     if (!text) continue;
     if (USE_CURRENT_RE.test(text)) {
-      if (!current || !allowedBranch(current) || isProtected(current)) {
+      if (!current || !allowedBranch(cwd, current) || isProtected(cwd, current)) {
         return { error: `use-current but HEAD ${current} is not an allowed branch` };
       }
       return finish(current, "use-current");
     }
   }
 
-  if (current && allowedBranch(current) && !isProtected(current))
+  if (current && allowedBranch(cwd, current) && !isProtected(cwd, current))
     return finish(current, "keep-current");
 
   let declaredButInvalid: string | null = null;
@@ -109,7 +119,7 @@ export const resolveBranch = ({
     const text = readSafe(file);
     if (!text) continue;
     for (const match of text.matchAll(DECLARE_RE)) {
-      const normalized = normalizeBranch(match[1]);
+      const normalized = normalizeBranch(cwd, match[1]);
       if (normalized) return finish(normalized, file === spec ? "spec" : "plan");
       declaredButInvalid ??= match[1];
     }
@@ -140,7 +150,9 @@ export const docsBranch = ({
   const git = gitContext(cwd);
   const current = git.branch;
   const kindArg = (kind ?? "feature").toLowerCase();
-  const base = baseBranch(cwd);
+  const baseResolved = baseBranch(cwd);
+  if ("error" in baseResolved) return { error: baseResolved.error };
+  const base = baseResolved.base;
 
   if (current === base || current === "main" || current === "master" || current === "develop") {
     let slug = "";
@@ -162,7 +174,7 @@ export const docsBranch = ({
       dirty: Boolean(git.status_short.trim()),
     };
   }
-  if (current && allowedBranch(current) && !isProtected(current)) {
+  if (current && allowedBranch(cwd, current) && !isProtected(cwd, current)) {
     return {
       branch: current,
       action: "keep",
@@ -280,8 +292,8 @@ export const branchSetup = ({
 
   const target = target_branch ?? "";
   if (!target) return { error: "target branch required" };
-  if (isProtected(target)) return { error: `protected branch ${target}` };
-  if (!allowedBranch(target))
+  if (isProtected(cwd, target)) return { error: `protected branch ${target}` };
+  if (!allowedBranch(cwd, target))
     return { error: `target branch ${target} is not allowed by the branch policy` };
 
   let stash_ref: string | undefined;
@@ -311,7 +323,9 @@ export const branchSetup = ({
         };
       }
       try {
-        const baseResult = ensureBaseBranch(cwd, baseBranch(cwd));
+        const baseResolved = baseBranch(cwd);
+        if ("error" in baseResolved) return { error: baseResolved.error };
+        const baseResult = ensureBaseBranch(cwd, baseResolved.base);
         if (!baseResult.ok) return { error: baseResult.error };
         exec(["checkout", "-b", target]);
       } catch (createError) {

package/src/core/config.ts

@@ -9,6 +9,16 @@ import {
 } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import type { Logger } from "./logger";
+import { EVENT, errorDetail } from "./boundary";
+
+// Optional diagnostic seam: adapters install their host logger so config
+// migration and provenance events land in the same sanitized log stream.
+let diagnosticLogger: Logger | undefined;
+export const setDiagnosticLogger = (logger: Logger | undefined): void => {
+  diagnosticLogger = logger;
+};
+export const getDiagnosticLogger = (): Logger | undefined => diagnosticLogger;
 
 export type BranchPreset = "gitflow" | "github-flow" | "trunk-based" | "custom";
 
@@ -29,6 +39,28 @@ export const PRESETS: Record<BranchPreset, { allowed: string[]; protected: strin
   custom: { allowed: [], protected: [] },
 };
 
+// RL-02: one shared preset merge helper. Changing the preset resets every
+// derived policy field from PRESETS; only `custom` carries explicit values
+// (falling back to the current policy when none are given).
+export const mergePreset = (
+  preset: BranchPreset,
+  input: { allowed?: string[]; protectedNames?: string[] } = {},
+  current: { branchPolicy: ToolkitConfig["branchPolicy"] } = {
+    branchPolicy: { preset, allowed: [], protected: [] },
+  },
+): ToolkitConfig["branchPolicy"] => {
+  const defs = PRESETS[preset];
+  return {
+    preset,
+    allowed:
+      preset === "custom" ? (input.allowed ?? current.branchPolicy.allowed) : [...defs.allowed],
+    protected:
+      preset === "custom"
+        ? (input.protectedNames ?? current.branchPolicy.protected)
+        : [...defs.protected],
+  };
+};
+
 export const resolveConfigDir = (): string =>
   process.env.WORKFLOW_TOOLKIT_CONFIG ??
   process.env.WORKFLOW_TOOLKIT_CONFIG_DIR ??
@@ -66,6 +98,7 @@ export const ensureConfigDir = (dir: string = resolveConfigDir()): string => {
   }
   migrationFailed = false;
   mkdirSync(dir, { recursive: true });
+  diagnosticLogger?.info(EVENT.migration, { from: legacy, to: dir });
   for (const entry of readdirSync(legacy, { withFileTypes: true })) {
     const src = path.join(legacy, entry.name);
     const dest = path.join(dir, entry.name);
@@ -75,7 +108,12 @@ export const ensureConfigDir = (dir: string = resolveConfigDir()): string => {
       else if (entry.isFile()) copyFileSync(src, dest);
     } catch (err) {
       migrationFailed = true;
-      console.warn(`[workit] config migration: failed to copy ${src}: ${(err as Error).message}`);
+      diagnosticLogger?.warn(EVENT.migration, { from: src, ok: false, ...errorDetail(err) });
+      // Task 10 advisory: never leak the raw legacy source path to the terminal —
+      // the structured warn above carries it through the sanitized logger.
+      console.warn(
+        `[workit] config migration: a file could not be copied to ${dir}; it will be retried on the next run`,
+      );
     }
   }
   if (!migrationFailed) migratedDir = dir;
@@ -105,49 +143,173 @@ const readSafe = (p: string): string | null => {
   }
 };
 
-export const readConfig = (): ToolkitConfig => {
-  const raw = readSafe(path.join(configDir(), "config.json"));
-  if (!raw) return DEFAULTS;
+// RL-01: typed reader contract. Every config reader distinguishes missing from
+// valid from malformed and reports the exact file path; risky consumers stop on
+// malformed instead of silently falling back to defaults.
+export type ReaderStatus = "missing" | "valid" | "malformed";
+
+export type ReaderResult<T> = {
+  status: ReaderStatus;
+  path: string;
+  config?: T;
+  error?: string;
+};
+
+// AR-07/CA-37: the one shared fail-closed shape rule for every object-config
+// reader (config, setup-state, workspaces, doctor). A parseable non-object
+// (null, scalar, array) is malformed, never defaults.
+export const isConfigObject = (value: unknown): boolean =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const parseConfigResult = (raw: string | null, file: string): ReaderResult<ToolkitConfig> => {
+  if (raw === null) return { status: "missing", path: file };
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(raw) as Partial<ToolkitConfig>;
-    const locale = LOCALE_RE.test(String(parsed.locale ?? ""))
-      ? (parsed.locale as string)
-      : DEFAULTS.locale;
-    const preset = (parsed.branchPolicy?.preset ?? "gitflow") as BranchPreset;
-    const presetOk = Object.hasOwn(PRESETS, preset) ? preset : "gitflow";
-    const presetDefs = PRESETS[presetOk];
-    return {
-      locale,
-      localeOptions: Array.isArray(parsed.localeOptions)
-        ? parsed.localeOptions
-        : DEFAULTS.localeOptions,
-      timezone: parsed.timezone ?? DEFAULTS.timezone,
-      branchPolicy: {
-        preset: presetOk,
-        allowed: Array.isArray(parsed.branchPolicy?.allowed)
-          ? parsed.branchPolicy.allowed
-          : presetDefs.allowed,
-        protected: Array.isArray(parsed.branchPolicy?.protected)
-          ? parsed.branchPolicy.protected
-          : presetDefs.protected,
-      },
-    };
+    parsed = JSON.parse(raw);
   } catch {
-    return DEFAULTS;
+    return { status: "malformed", path: file, error: `${file} is not valid JSON` };
   }
+  if (!isConfigObject(parsed)) {
+    return { status: "malformed", path: file, error: `${file} is not a JSON object` };
+  }
+  const input = parsed as Partial<ToolkitConfig>;
+  const locale = LOCALE_RE.test(String(input.locale ?? ""))
+    ? (input.locale as string)
+    : DEFAULTS.locale;
+  const preset = (
+    Object.hasOwn(PRESETS, input.branchPolicy?.preset as string)
+      ? input.branchPolicy?.preset
+      : "gitflow"
+  ) as BranchPreset;
+  return {
+    status: "valid",
+    path: file,
+    config: {
+      locale,
+      localeOptions: Array.isArray(input.localeOptions)
+        ? input.localeOptions
+        : DEFAULTS.localeOptions,
+      timezone: input.timezone ?? DEFAULTS.timezone,
+      // RL-02/CA-23: the persisted preset is authoritative; derived allowed /
+      // protected fields always reset from PRESETS via the one shared merge.
+      branchPolicy: mergePreset(
+        preset,
+        {
+          allowed: Array.isArray(input.branchPolicy?.allowed)
+            ? input.branchPolicy.allowed
+            : undefined,
+          protectedNames: Array.isArray(input.branchPolicy?.protected)
+            ? input.branchPolicy.protected
+            : undefined,
+        },
+        DEFAULTS,
+      ),
+    },
+  };
+};
+
+export const readConfigTyped = (dir?: string): ReaderResult<ToolkitConfig> => {
+  const file = path.join(dir ?? configDir(), "config.json");
+  return parseConfigResult(readSafe(file), file);
+};
+
+// RL-01: no silent fallback on malformed config — every consumer gets an
+// exact-path diagnostic instead of defaults. Missing config still defaults.
+export const readConfig = (): ToolkitConfig => {
+  const result = readConfigTyped();
+  if (result.status === "malformed") throw new Error(result.error);
+  return result.config ?? DEFAULTS;
+};
+
+export const readConfigFromDir = (dir: string): ToolkitConfig => {
+  const result = readConfigTyped(dir);
+  if (result.status === "malformed") throw new Error(result.error);
+  return result.config ?? DEFAULTS;
+};
+
+export type ConfigInput = {
+  locale?: string;
+  localeOptions?: string[];
+  timezone?: string;
+  preset?: BranchPreset;
+  allowed?: string[];
+  protectedNames?: string[];
 };
 
+// RL-02: the single authoritative ToolkitConfig merge. CLI, OpenCode, and Cursor
+// adapters all route their `config` writes through this so a preset switch
+// resets every derived policy field identically everywhere.
+export const mergeConfigValues = (input: ConfigInput, current: ToolkitConfig): ToolkitConfig => ({
+  locale: input.locale ?? current.locale,
+  localeOptions: input.localeOptions ?? current.localeOptions,
+  timezone: input.timezone ?? current.timezone,
+  branchPolicy: mergePreset(input.preset ?? current.branchPolicy.preset, input, current),
+});
+
 export const writeConfig = (config: ToolkitConfig): void => {
   const dir = configDir();
   mkdirSync(dir, { recursive: true });
   writeFileSync(path.join(dir, "config.json"), JSON.stringify(config, null, 2) + "\n", "utf8");
 };
 
+// Configuration provenance for startup diagnostics: where config.json came from
+// and whether it parsed. Only paths + a malformed flag — never the file body.
+export const describeConfigSource = (
+  dir: string = resolveConfigDir(),
+): { source: string; config_dir: string; malformed: boolean } => {
+  const file = path.join(dir, "config.json");
+  if (!existsSync(file)) return { source: "defaults", config_dir: dir, malformed: false };
+  const raw = readSafe(file);
+  if (raw === null) return { source: "unreadable", config_dir: dir, malformed: true };
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isConfigObject(parsed)) {
+      return { source: "defaults", config_dir: dir, malformed: true };
+    }
+    return { source: "file", config_dir: dir, malformed: false };
+  } catch {
+    return { source: "defaults", config_dir: dir, malformed: true };
+  }
+};
+
 export const resolveBranchPolicy = (
   config: ToolkitConfig,
-): { allowed: RegExp[]; protected: Set<string> } => {
-  const allowed = config.branchPolicy.allowed.map(
+  workspace?: { branchPolicy?: Record<string, any> } | null,
+): {
+  preset: BranchPreset;
+  allowed: RegExp[];
+  protected: Set<string>;
+  integration: "pr" | "merge";
+  defaultTargetBranch: string;
+} => {
+  const wp = (workspace?.branchPolicy ?? {}) as Record<string, any>;
+  // An invalid workspace preset (e.g. a typo) falls back to the global preset,
+  // preserving resolution order workspace > global > preset, instead of
+  // crashing on PRESETS[preset] (mirrors parseConfigResult's Object.hasOwn).
+  const preset = (
+    Object.hasOwn(PRESETS, wp.preset) ? wp.preset : (config.branchPolicy?.preset ?? "gitflow")
+  ) as BranchPreset;
+  // RL-02: the preset is authoritative — allowed/protected re-derive from the
+  // workspace's own values or the preset table, never the global config's, and
+  // the current config remains the `custom` fallback when no values are given.
+  const merged = mergePreset(
+    preset,
+    {
+      allowed: wp.allowed,
+      protectedNames: wp.protected,
+    },
+    config,
+  );
+  const allowed = merged.allowed.map(
     (p) => new RegExp(`^${p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`, "i"),
   );
-  return { allowed, protected: new Set(config.branchPolicy.protected.map((p) => p.toLowerCase())) };
+  return {
+    preset,
+    allowed,
+    protected: new Set(merged.protected.map((p) => p.toLowerCase())),
+    integration: wp.integration === "merge" ? "merge" : "pr",
+    // CA-05: preset-aware default target when vcs.defaultTargetBranch is unset.
+    defaultTargetBranch:
+      preset === "github-flow" ? "main" : preset === "trunk-based" ? "master" : "develop",
+  };
 };

package/src/core/docs-layout.ts

@@ -0,0 +1,251 @@
+import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+// One canonical document path contract (DC-01, DC-02, DC-04, DC-14): workspace
+// root, slug, and spec/plan pair resolution all funnel through here so every
+// document/flow/SDD consumer on both hosts enforces the same containment rules.
+
+export type CanonicalLayout = {
+  /** Canonical (realpath) workspace root. */
+  workspace: string;
+  /** Validated slug. */
+  slug: string;
+  /** Canonical path of docs/. */
+  docs: string;
+  /** Canonical path of docs/<slug>/. */
+  dir: string;
+  /** Canonical path of docs/<slug>/spec.md. */
+  spec: string;
+  /** Canonical path of docs/<slug>/plan.md. */
+  plan: string;
+  /** Canonical path of docs/<slug>/sdd/. */
+  sdd: string;
+};
+
+export type LayoutResult = { ok: true; layout: CanonicalLayout } | { ok: false; error: string };
+
+export type LegacyProbe = {
+  /** `.superpowers/sdd` exists. */
+  legacy_sdd: boolean;
+  /** `docs/superpowers/` exists. */
+  superpowers_dir: boolean;
+};
+
+export type PrepareResult =
+  | { ok: true; layout: CanonicalLayout; created: string[]; legacy: LegacyProbe }
+  | { ok: false; error: string };
+
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Reserved legacy root (DC-05): never resolve or prepare a slug under it. */
+const LEGACY_SLUG = "superpowers";
+
+const posix = (p: string) => p.split(path.sep).join("/");
+
+// Realpath the nearest existing ancestor of `candidate` and reject the result
+// when it escapes `base` (base must already be canonical). The returned path is
+// canonical where it exists and joined for the non-existent tail.
+const canonicalize = (base: string, candidate: string): string => {
+  const abs = path.resolve(base, candidate);
+  let ancestor = abs;
+  while (!existsSync(ancestor)) ancestor = path.dirname(ancestor);
+  const real = realpathSync(ancestor);
+  if (real !== base && !real.startsWith(base + path.sep)) {
+    throw new Error(`path must stay inside repository root: ${candidate}`);
+  }
+  return path.join(real, path.relative(ancestor, abs));
+};
+
+const buildLayout = (workspace: string, slug: string): CanonicalLayout => {
+  const docs = canonicalize(workspace, "docs");
+  const dir = canonicalize(workspace, path.join(docs, slug));
+  return {
+    workspace,
+    slug,
+    docs,
+    dir,
+    spec: path.join(dir, "spec.md"),
+    plan: path.join(dir, "plan.md"),
+    sdd: path.join(dir, "sdd"),
+  };
+};
+
+/** Read-only legacy detection (DC-04): never mutates legacy state. */
+export const probeLegacyDocs = (workspace: string): LegacyProbe => ({
+  legacy_sdd: existsSync(path.join(workspace, ".superpowers", "sdd")),
+  superpowers_dir: existsSync(path.join(workspace, "docs", LEGACY_SLUG)),
+});
+
+/**
+ * The one canonical workspace/slug/pair resolver. Given a slug or any spec/plan
+ * pair path, returns canonical paths for the pair. Rejects absolute paths,
+ * traversal, symlink escapes, cross-slug pairs, wrong basenames, and arbitrary
+ * or legacy locations (DC-01, DC-02). Creates nothing.
+ */
+export const resolveCanonicalLayout = (input: {
+  workspace_root: string;
+  slug?: string;
+  spec_path?: string;
+  plan_path?: string;
+}): LayoutResult => {
+  const { workspace_root, slug, spec_path, plan_path } = input;
+  if (!workspace_root) return { ok: false, error: "workspace_root required" };
+  let workspace: string;
+  try {
+    workspace = realpathSync(path.resolve(workspace_root));
+  } catch {
+    return { ok: false, error: `workspace root not found: ${workspace_root}` };
+  }
+
+  let derived: string | null = null;
+  for (const [candidate, kind] of [
+    [spec_path, "spec"],
+    [plan_path, "plan"],
+  ] as const) {
+    if (!candidate) continue;
+    if (path.isAbsolute(candidate)) {
+      return { ok: false, error: `absolute path not allowed: ${candidate}` };
+    }
+    let abs: string;
+    try {
+      abs = canonicalize(workspace, candidate);
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    const rel = posix(path.relative(workspace, abs));
+    const match = rel.match(/^docs\/([^/]+)\/(spec|plan)\.md$/);
+    if (!match) {
+      return {
+        ok: false,
+        error: `path must be docs/<slug>/(spec|plan).md inside workspace_root: ${candidate}`,
+      };
+    }
+    const pathSlug = match[1];
+    if (pathSlug === LEGACY_SLUG) {
+      return { ok: false, error: `legacy path not allowed: ${candidate}` };
+    }
+    if (!SLUG_RE.test(pathSlug)) {
+      return { ok: false, error: `invalid slug derived from path: ${JSON.stringify(pathSlug)}` };
+    }
+    if (match[2] !== kind) {
+      return {
+        ok: false,
+        error: `wrong basename for ${kind}: expected ${kind}.md, got ${path.basename(candidate)}`,
+      };
+    }
+    if (derived && derived !== pathSlug) {
+      return {
+        ok: false,
+        error: "cross-slug pair: spec_path and plan_path must share the same docs/<slug>/",
+      };
+    }
+    derived = pathSlug;
+  }
+
+  let resolvedSlug = slug;
+  if (resolvedSlug !== undefined) {
+    if (!SLUG_RE.test(resolvedSlug)) {
+      return { ok: false, error: `invalid slug: ${JSON.stringify(resolvedSlug)}` };
+    }
+    if (resolvedSlug === LEGACY_SLUG) {
+      return { ok: false, error: `reserved slug: ${LEGACY_SLUG}` };
+    }
+    if (derived && derived !== resolvedSlug) {
+      return {
+        ok: false,
+        error: `slug ${JSON.stringify(resolvedSlug)} does not match docs path ${JSON.stringify(derived)}`,
+      };
+    }
+  } else if (derived) {
+    resolvedSlug = derived;
+  } else {
+    return { ok: false, error: "slug or spec_path/plan_path required" };
+  }
+
+  try {
+    return { ok: true, layout: buildLayout(workspace, resolvedSlug) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/**
+ * Prepare the canonical layout (DC-04): create only missing `docs/` and
+ * `docs/<slug>/`, return canonical (realpath) paths, and probe legacy state
+ * read-only. Never creates sdd/, spec.md, or plan.md.
+ */
+export const prepareDocsLayout = (input: {
+  workspace_root: string;
+  slug?: string;
+  spec_path?: string;
+  plan_path?: string;
+}): PrepareResult => {
+  const resolved = resolveCanonicalLayout(input);
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+  const { layout } = resolved;
+  const created: string[] = [];
+  const ensure = (dir: string) => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      const rel = posix(path.relative(layout.workspace, dir));
+      created.push(rel || ".");
+    } else if (!statSync(dir).isDirectory()) {
+      throw new Error(
+        `path exists but is not a directory: ${posix(path.relative(layout.workspace, dir))}`,
+      );
+    }
+  };
+  try {
+    ensure(layout.docs);
+    ensure(layout.dir);
+    // Re-canonicalize after creation so a symlinked docs/<slug> that escapes
+    // the workspace is rejected, not silently accepted (DC-02).
+    const docs = canonicalize(layout.workspace, "docs");
+    const dir = canonicalize(layout.workspace, path.join(docs, layout.slug));
+    return {
+      ok: true,
+      layout: { ...layout, docs, dir },
+      created,
+      legacy: probeLegacyDocs(layout.workspace),
+    };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/**
+ * Containment check for paths that must live inside the workspace docs tree
+ * (sdd dirs, progress files, plan links). Rejects absolute paths, escapes, and
+ * the reserved legacy root `docs/superpowers/`.
+ */
+export const resolveDocsPath = (input: {
+  workspace_root: string;
+  path: string;
+}): { ok: true; path: string; relative: string; base: string } | { ok: false; error: string } => {
+  if (path.isAbsolute(input.path)) {
+    return { ok: false, error: `absolute path not allowed: ${input.path}` };
+  }
+  let workspace: string;
+  try {
+    workspace = realpathSync(path.resolve(input.workspace_root));
+  } catch {
+    return { ok: false, error: `workspace root not found: ${input.workspace_root}` };
+  }
+  try {
+    const abs = canonicalize(workspace, input.path);
+    const relative = posix(path.relative(workspace, abs));
+    if (
+      !relative.startsWith("docs/") ||
+      relative === `docs/${LEGACY_SLUG}` ||
+      relative.startsWith(`docs/${LEGACY_SLUG}/`)
+    ) {
+      return {
+        ok: false,
+        error: `path must live under docs/ and not under docs/${LEGACY_SLUG}/: ${input.path}`,
+      };
+    }
+    return { ok: true, path: abs, relative, base: workspace };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+};