@brainervirus/workit-core 0.6.0 → 0.7.0

package/src/core/config.ts

@@ -1,6 +1,24 @@
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} 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";
 
@@ -12,16 +30,41 @@ export type ToolkitConfig = {
 };
 
 export const PRESETS: Record<BranchPreset, { allowed: string[]; protected: string[] }> = {
-  gitflow: { allowed: ["feature/*", "bugfix/*", "hotfix/*", "release/*"], protected: ["main", "develop", "master", "prod", "production"] },
+  gitflow: {
+    allowed: ["feature/*", "bugfix/*", "hotfix/*", "release/*"],
+    protected: ["main", "develop", "master", "prod", "production"],
+  },
   "github-flow": { allowed: ["*"], protected: ["main"] },
   "trunk-based": { allowed: ["*"], protected: ["main"] },
   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
-  ?? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "workit");
+  process.env.WORKFLOW_TOOLKIT_CONFIG ??
+  process.env.WORKFLOW_TOOLKIT_CONFIG_DIR ??
+  path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "workit");
 
 // One-time lazy migration from the legacy ~/.config/workflow-toolkit dir.
 // migratedDir remembers the resolved dir already checked: configDir() is on
@@ -41,7 +84,10 @@ export const ensureConfigDir = (dir: string = resolveConfigDir()): string => {
     migratedDir = dir;
     return dir;
   }
-  const legacy = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "workflow-toolkit");
+  const legacy = path.join(
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"),
+    "workflow-toolkit",
+  );
   if (!existsSync(legacy)) {
     migratedDir = dir;
     return dir;
@@ -52,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);
@@ -61,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;
@@ -76,45 +128,188 @@ const DEFAULTS: ToolkitConfig = {
   locale: "en",
   localeOptions: ["en", "es-CL", "es-MX", "es-AR", "pt-BR"],
   timezone: "America/Santiago",
-  branchPolicy: { preset: "gitflow", allowed: [...PRESETS.gitflow.allowed], protected: [...PRESETS.gitflow.protected] },
+  branchPolicy: {
+    preset: "gitflow",
+    allowed: [...PRESETS.gitflow.allowed],
+    protected: [...PRESETS.gitflow.protected],
+  },
 };
 
 const readSafe = (p: string): string | null => {
-  try { return readFileSync(p, "utf8"); } catch { return null; }
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return 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");
 };
 
-export const resolveBranchPolicy = (config: ToolkitConfig): { allowed: RegExp[]; protected: Set<string> } => {
-  const allowed = config.branchPolicy.allowed.map((p) =>
-    new RegExp(`^${p.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`, "i"));
-  return { allowed, protected: new Set(config.branchPolicy.protected.map((p) => p.toLowerCase())) };
+// 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,
+  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 {
+    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/detector.ts

@@ -5,8 +5,7 @@ import { parseTasksFromPlan } from "./docs-validate";
 
 export type Detection = { choices: string[]; pattern: "alpha" | "numeric" } | null;
 
-export const detectConfigGapError = (text: string): boolean =>
-  text.includes(CONFIG_GAP_MARKER);
+export const detectConfigGapError = (text: string): boolean => text.includes(CONFIG_GAP_MARKER);
 
 // Enforcement-rail detectors: case-insensitive word-boundary heuristics.
 // Conservative bias (D-03): require 1+ signal word AND 0 evidence words;
@@ -86,20 +85,27 @@ export const detectInstructionOption = (questions: unknown): boolean => {
 // Labeled blocks are stripped first so their plain closing fence (```) can't match.
 export const detectRawDocDelivery = (text: string): boolean =>
   /^```\s*$/m.test(text.replace(/```\S[^\n]*\r?\n[\s\S]*?```/g, "")) &&
-  (text.includes("# Spec") || text.includes("# Plan") ||
-    text.includes("**Spec:**") || text.includes("**Branch:**"));
+  (text.includes("# Spec") ||
+    text.includes("# Plan") ||
+    text.includes("**Spec:**") ||
+    text.includes("**Branch:**"));
 
 // Interrogative gate: a literal question mark OR explicit interrogative phrases.
 // Plain "I want to confirm..." or "the script which runs" must NOT match.
-const INTERROGATIVE = /[?¿]|which\s+one|choose\s+(?:one|between|among)|do\s+you\s+(?:want|prefer)|want\s+me\s+to/i;
+const INTERROGATIVE =
+  /[?¿]|which\s+one|choose\s+(?:one|between|among)|do\s+you\s+(?:want|prefer)|want\s+me\s+to/i;
 
 export const detectProseChoices = (text: string): Detection => {
   if (!INTERROGATIVE.test(text)) return null;
 
-  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  const lines = text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
 
-  const alphaAll = [...text.matchAll(/([a-dA-D])[.)]\s+([^\n]*?)(?=\s+[a-dA-D][.)]\s|$)/g)]
-    .map((m) => ({ letter: m[1].toLowerCase(), choice: m[2].trim() }));
+  const alphaAll = [...text.matchAll(/([a-dA-D])[.)]\s+([^\n]*?)(?=\s+[a-dA-D][.)]\s|$)/g)].map(
+    (m) => ({ letter: m[1].toLowerCase(), choice: m[2].trim() }),
+  );
   const alphaLines = lines
     .map((l) => /^([a-dA-D])[.)]\s+(.+)$/.exec(l))
     .filter((m): m is RegExpExecArray => Boolean(m))
@@ -114,8 +120,10 @@ export const detectProseChoices = (text: string): Detection => {
     }
   }
 
-  const numericAll = [...text.matchAll(/(\d+)[.)]\s+([^\n]*?)(?=\s+\d+[.)]\s|$)/g)]
-    .map((m) => ({ num: Number(m[1]), choice: m[2].trim() }));
+  const numericAll = [...text.matchAll(/(\d+)[.)]\s+([^\n]*?)(?=\s+\d+[.)]\s|$)/g)].map((m) => ({
+    num: Number(m[1]),
+    choice: m[2].trim(),
+  }));
   const numericLines = lines
     .map((l) => /^(\d+)[.)]\s+(.+)$/.exec(l))
     .filter((m): m is RegExpExecArray => Boolean(m))
@@ -137,7 +145,10 @@ const stripFences = (text: string): string => {
   const out: string[] = [];
   let inFence = false;
   for (const line of lines) {
-    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
     if (!inFence) out.push(line);
   }
   return out.join("\n");

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