@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-requirements/skills/workflow-wayfinder/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: workflow-wayfinder
+description: "Use when a requirement is too large or foggy for one clarification session before baseline. Builds a decision map with destination, frontier, fog, out-of-scope, and small Research/Prototype/Grilling/Task tickets that can be resolved one at a time before entering requirement baseline."
+---
+
+# Workflow: Wayfinder（需求探索地图）
+
+本技能是需求主链的固定第二步。无论需求表面上是否简单，都先建立探索地图；目标不是写 baseline，而是把目标、已知事实、边界、迷雾和可逐个解决的 ticket 显式化。
+
+## Outputs
+
+Always create or update:
+
+- `.planning/requirements/{功能名}/决策地图.md`
+- `.planning/requirements/{功能名}/决策地图.meta.json`
+- `.planning/requirements/{功能名}/wayfinder/WF-xxx.md` for each ticket
+
+`决策地图.meta.json` minimum fields:
+
+```json
+{
+  "feature_name": "",
+  "status": "mapping | tickets_open | ready_for_baseline | blocked",
+  "destination": "",
+  "open_ticket_count": 0,
+  "resolved_ticket_count": 0,
+  "frontier_ticket_ids": [],
+  "next_ticket_id": "",
+  "blocking_reason": "",
+  "ready_for_baseline": false
+}
+```
+
+Each ticket file has YAML front matter:
+
+```yaml
+id: WF-001
+status: open # open | claimed | resolved | blocked | out_of_scope
+type: research # research | prototype | grilling | task
+blocked_by: []
+claimed_by:
+claimed_at:
+decision_level: L1
+resolved_at:
+```
+
+## Map Vocabulary
+
+| Section | Meaning |
+|---------|---------|
+| Destination | 最终要抵达的业务目标，用一句话描述，不写实现方案 |
+| Known Land | 已确认事实、项目现状、用户已拍板决策 |
+| Frontier | 当前可推进的最外层问题，不依赖其他未解决问题 |
+| Fog | 依赖 Frontier 答案才能定义的问题 |
+| Out of Scope | 明确不做、暂缓、或历史拒绝的范围 |
+
+The map is an index, not the source of full ticket truth:
+
+- `决策地图.md` keeps Destination, Known Land, Decisions so far, Not yet specified, Out of Scope, and Ticket index.
+- Ticket details, evidence, answers, prototypes, and discussion summaries live in `wayfinder/WF-xxx.md`.
+- Do not duplicate full ticket answers into the map. Add only one-line decision gists with links to the ticket file.
+
+## Ticket Types
+
+| Type | Use when | Output |
+|------|----------|--------|
+| Research | Need docs, code reading, external API/library confirmation, or primary-source investigation | Cited Markdown finding or code evidence notes |
+| Prototype | Need runnable proof to compare logic, UX, state machine, parsing, or integration feasibility | Throwaway prototype and result summary |
+| Grilling | Need user/business decision; cannot be discovered from code or docs | One-question-at-a-time decision record |
+| Task | Need a small local artifact update that clarifies the map, such as glossary cleanup or source indexing | Updated artifact with completion note |
+
+Do not merge `Grilling` and `Task`: a question to the user and a local artifact update have different completion gates.
+
+## Phase 1 — Chart The First Map
+
+1. Read `.planning/requirements/{功能名}/入口分诊.md`.
+2. Read the raw user input and only the project context needed to understand the uncertainty.
+3. Run the **Source Coherence Gate** below before declaring Fog or creating any Grilling ticket.
+4. Write:
+   - Destination
+   - Known Land
+   - Frontier
+   - Fog
+   - Out of Scope
+5. If there is no meaningful Fog after charting, mark `ready_for_baseline: true`; do not bypass the mandatory `workflow-domain-modeling` and `requirement-feasibility-review` steps.
+
+### Source Coherence Gate
+
+Do not treat each paragraph as an isolated requirement. Build one coherent behavior model from the entire source first:
+
+1. Classify statements as `background/problem`, `normative rule`, `trigger/process`, `example/mock`, or `exception/history`.
+2. Join statements that describe different stages of the same behavior. A risk stated in the background is not a separate feature when a later process already supplies the confirmation, validation, or recovery mechanism.
+3. Resolve apparent conflicts in this order:
+   - confirmed user decision;
+   - explicit normative rule (`must`, limit, formula, state/result);
+   - explicit trigger/process;
+   - scoped exception or historical rule;
+   - example, mock data, OCR text, or background motivation.
+4. Prefer an interpretation that preserves all higher-authority statements without inventing another dialog, threshold, state, field, or API.
+5. Record a lower-authority conflicting example as non-normative evidence; do not promote it into a question when the formal rule already determines behavior.
+
+A Grilling ticket is allowed only when at least two coherent interpretations remain after this gate and they would change a user-visible outcome, money rule, state transition, permission, data ownership, API contract, or acceptance result. The ticket must list those interpretations and the exact consequence of each. If one interpretation is supported by the full source, choose it confidently and record the reasoning in Known Land or Decisions so far.
+
+## Phase 2 — Create Tickets
+
+Ticket rules:
+
+- Each ticket must fit one agent session.
+- Every ticket has a clear done condition.
+- Every ticket declares dependencies by ticket ID.
+- Frontier tickets have no unresolved dependencies.
+- L1/L2 decisions generally outrank L3/L4 details unless a lower-level fact blocks them.
+- Do not create a Grilling ticket merely because a detail is not repeated in every section. First prove that the Source Coherence Gate cannot resolve it.
+
+Ticket template:
+
+```markdown
+---
+id: WF-{序号}
+status: open
+type: research | prototype | grilling | task
+blocked_by: []
+claimed_by:
+claimed_at:
+decision_level: L1 | L2 | L3 | L4 | N/A
+resolved_at:
+---
+
+## WF-{序号}: {ticket title}
+
+### Question
+{one thing this ticket must answer}
+
+### Done Condition
+{what must be true for this ticket to resolve}
+
+### Findings / Answer
+{filled after resolution}
+
+### Map Update
+{Known Land / Frontier / Fog / Out of Scope changes}
+```
+
+## Phase 3 — Resolve One Frontier Ticket
+
+Pick exactly one ticket:
+
+1. Prefer unresolved Frontier tickets.
+2. Within Frontier, use L1 → L2 → L3 → L4.
+3. Claim it before work by setting `status=claimed`, `claimed_by={agent/session identifier}`, and `claimed_at={ISO time}` in the ticket front matter.
+4. Re-read the map and ticket immediately after claiming. If another claim appeared first, stop and choose another Frontier ticket.
+5. If a ticket is `Grilling`, ask exactly one question and wait for the answer.
+6. If a ticket is `Research`, use high-trust sources first; for code facts, cite file paths and line numbers.
+7. If a ticket is `Prototype`, keep it throwaway and record only the decision result.
+8. If a ticket is `Task`, update only the artifact named in the ticket.
+
+Before asking a Grilling question, re-read the raw source around every cited statement and write into the ticket:
+
+- the two or more surviving interpretations;
+- why background + formal rules + process cannot reconcile them;
+- the different acceptance or data consequences.
+
+If this evidence cannot be written, reclassify the ticket as Research/Task or resolve it from the source; do not ask the user.
+
+After resolution, update the map immediately. Do not solve hidden Fog tickets before their dependencies clear.
+
+## Phase 4 — Exit Criteria
+
+Exit this step to `workflow-domain-modeling` only when:
+
+- Destination is still valid.
+- All L1/L2 blocking decisions are resolved.
+- Remaining L3/L4 questions are either resolved or explicitly non-blocking.
+- Out-of-scope items are recorded.
+- There is enough Known Land to decompose FP/BR/BC without inventing business rules.
+
+If open tickets remain but are not needed for the active slice, record them as deferred exploration with re-entry conditions.
+
+When exit criteria pass:
+
+1. Set `决策地图.meta.json.status = ready_for_baseline`.
+2. Set `决策地图.meta.json.ready_for_baseline = true`.
+3. Let the orchestrator advance to `workflow-domain-modeling`. Do not update the triage route and do not enter baseline directly.

package/src/cli.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env bun
+
+import path from "node:path";
+
+import { formatDoctor, runHostDoctor } from "./doctor.ts";
+import { initializeProject, loadProjectContext, resolveProjectRoot } from "./project-context.ts";
+import { aggregateUsage, renderUsage } from "./usage-stats.ts";
+import { projectSessionDir } from "./paths.ts";
+
+function usage(): string {
+  return [
+    "Usage:",
+    "  devflow-pi init [project]",
+    "  devflow-pi doctor [project]",
+    "  devflow-pi usage [project]",
+    "  devflow-pi [project] [--resume [session-id]] [--prompt <text>] [--mcp]",
+  ].join("\n");
+}
+
+function option(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function optionalOption(args: string[], name: string): boolean | string | undefined {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  return value && !value.startsWith("-") ? value : true;
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  if (command === "--help" || command === "-h" || command === "help") {
+    console.log(usage());
+    return;
+  }
+  if (command === "init") {
+    const requested = args[1] ? path.resolve(args[1]) : process.cwd();
+    const root = await resolveProjectRoot(requested, { explicit: requested, allowUninitialized: true });
+    const { context, created } = await initializeProject(root);
+    console.log(`${created ? "Initialized" : "Already initialized"}: ${context.root}`);
+    console.log(`projectId: ${context.manifest.projectId}`);
+    console.log(`planning: ${context.planningRoot}`);
+    return;
+  }
+  const positionalProject = command && !["doctor", "usage"].includes(command) && !command.startsWith("-") ? command : undefined;
+  const requestedProject = ["doctor", "usage"].includes(command || "") ? args[1] : positionalProject;
+  const root = await resolveProjectRoot(process.cwd(), { explicit: requestedProject });
+  const project = await loadProjectContext(root);
+  if (command === "doctor") {
+    const report = await runHostDoctor(project);
+    console.log(formatDoctor(report));
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+  if (command === "usage") {
+    console.log(renderUsage(await aggregateUsage(projectSessionDir(project.manifest.projectId))));
+    return;
+  }
+  const originalOmpAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const { runInteractiveRuntime } = await import("./runtime.ts");
+  await runInteractiveRuntime(project, {
+    initialPrompt: option(args, "--prompt"),
+    originalOmpAgentDir,
+    resume: optionalOption(args, "--resume"),
+    enableMCP: args.includes("--mcp"),
+  });
+}
+
+main().catch(error => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Devflow Pi failed: ${message}`);
+  process.exitCode = 1;
+});

package/src/constants.ts

@@ -0,0 +1,15 @@
+export const PRODUCT_NAME = "Devflow Pi";
+export const PRODUCT_VERSION = "0.1.0";
+export const PROJECT_SCHEMA_VERSION = 1;
+export const OMP_RUNTIME_VERSION = "17.2.7";
+
+export const DEVFLOW_PLUGIN_NAMES = [
+  "devflow-core",
+  "devflow-intel",
+  "devflow-requirements",
+  "devflow-design",
+  "devflow-implementation",
+  "devflow-quality",
+] as const;
+
+export const REQUIRED_MODEL_ROLES = ["@smol", "@task", "@slow"] as const;

package/src/doctor.ts

@@ -0,0 +1,66 @@
+import { access, lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { DEVFLOW_PLUGIN_NAMES, OMP_RUNTIME_VERSION, PRODUCT_VERSION } from "./constants.ts";
+import { devflowAgentDir, devflowHome, ompSdkManifestPath, pluginRoots, projectSessionDir } from "./paths.ts";
+import type { ProjectContext } from "./project-context.ts";
+
+export interface DoctorCheck {
+  id: string;
+  ok: boolean;
+  message: string;
+}
+
+export interface HostDoctorReport {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function bunVersionOk(version: string): boolean {
+  const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+  return major > 1 || (major === 1 && (minor > 3 || (minor === 3 && patch >= 14)));
+}
+
+export async function runHostDoctor(project: ProjectContext): Promise<HostDoctorReport> {
+  const checks: DoctorCheck[] = [];
+  const add = (id: string, ok: boolean, message: string) => checks.push({ id, ok, message });
+  add("branch-runtime", true, `devflow-pi ${PRODUCT_VERSION}; OMP SDK ${OMP_RUNTIME_VERSION}`);
+  add("bun", bunVersionOk(Bun.version), bunVersionOk(Bun.version) ? Bun.version : `${Bun.version}; requires >=1.3.14`);
+  add("project-root", path.isAbsolute(project.root), project.root);
+  add("project-id", Boolean(project.manifest.projectId), project.manifest.projectId);
+  const planningStat = await lstat(project.planningRoot).catch(() => null);
+  add("planning-root", Boolean(planningStat?.isDirectory() && !planningStat.isSymbolicLink()), project.planningRoot);
+  const roots = pluginRoots();
+  for (let index = 0; index < DEVFLOW_PLUGIN_NAMES.length; index += 1) {
+    const plugin = DEVFLOW_PLUGIN_NAMES[index];
+    const root = roots[index];
+    add(`plugin:${plugin}`, await exists(path.join(root, "skills")), root);
+  }
+  const sdkManifest = ompSdkManifestPath();
+  let installedVersion = "missing";
+  if (await exists(sdkManifest)) {
+    const parsed = JSON.parse(await readFile(sdkManifest, "utf8")) as { version?: string };
+    installedVersion = parsed.version || "unknown";
+  }
+  add("omp-sdk", installedVersion === OMP_RUNTIME_VERSION, installedVersion);
+  add("agent-dir", true, devflowAgentDir());
+  add("session-isolation", true, projectSessionDir(project.manifest.projectId));
+  add("devflow-home", true, devflowHome());
+  return { ok: checks.every(check => check.ok), checks };
+}
+
+export function formatDoctor(report: HostDoctorReport): string {
+  return [
+    `Devflow Pi doctor: ${report.ok ? "PASS" : "FAIL"}`,
+    ...report.checks.map(check => ` [${check.ok ? "PASS" : "FAIL"}] ${check.id}: ${check.message}`),
+  ].join("\n");
+}

package/src/paths.ts

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { DEVFLOW_PLUGIN_NAMES } from "./constants.ts";
+
+export function packageRoot(): string {
+  return path.resolve(import.meta.dir, "..");
+}
+
+export function devflowHome(): string {
+  return path.resolve(process.env.DEVFLOW_HOME || path.join(os.homedir(), ".devflow-pi"));
+}
+
+export function devflowAgentDir(): string {
+  return path.join(devflowHome(), "agent");
+}
+
+export function sharedOmpAgentDir(originalAgentDir?: string): string {
+  return path.resolve(
+    process.env.DEVFLOW_SHARED_OMP_AGENT_DIR ||
+      originalAgentDir ||
+      path.join(os.homedir(), ".omp", "agent"),
+  );
+}
+
+export function pluginRoots(root = packageRoot()): string[] {
+  return DEVFLOW_PLUGIN_NAMES.map(name => path.join(root, "plugins", name));
+}
+
+export function projectSessionDir(projectId: string): string {
+  return path.join(devflowHome(), "sessions", projectId);
+}
+
+export function ompSdkManifestPath(): string {
+  return fileURLToPath(import.meta.resolve("@oh-my-pi/pi-coding-agent/package.json"));
+}

package/src/platform-extension.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+import { aggregateUsage, renderUsage } from "./usage-stats.ts";
+
+export interface PlatformExtensionOptions {
+  sessionRoot: string;
+  projectId: string;
+}
+
+export function createPlatformExtension(options: PlatformExtensionOptions) {
+  return function devflowPlatform(pi: ExtensionAPI) {
+    const { z } = pi.zod;
+    pi.setLabel("Devflow Platform Runtime");
+    pi.registerTool({
+      name: "devflow_usage_stats",
+      label: "Devflow Usage Stats",
+      description: "Read token and cost totals from this Devflow project's isolated session store.",
+      parameters: z.object({
+        from: z.string().optional(),
+        to: z.string().optional(),
+        format: z.enum(["table", "json"]).default("table"),
+      }),
+      approval: "read",
+      async execute(_id, params) {
+        const input = params as { from?: string; to?: string; format: "table" | "json" };
+        const totals = await aggregateUsage(options.sessionRoot, { from: input.from, to: input.to });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: input.format === "json" ? JSON.stringify({ projectId: options.projectId, ...totals }) : renderUsage(totals),
+            },
+          ],
+          details: { projectId: options.projectId, totals },
+        };
+      },
+    });
+    pi.registerCommand("devflow-usage", {
+      description: "Show project-scoped Devflow token and cost totals",
+      handler: async (_args, ctx) => {
+        const totals = await aggregateUsage(options.sessionRoot);
+        ctx.ui.notify(renderUsage(totals), "info");
+      },
+    });
+  };
+}

package/src/project-context.ts

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { access, lstat, mkdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { PROJECT_SCHEMA_VERSION } from "./constants.ts";
+
+export interface ProjectManifest {
+  schemaVersion: number;
+  projectId: string;
+  name: string;
+  createdAt: string;
+}
+
+export interface ProjectContext {
+  root: string;
+  manifestPath: string;
+  manifest: ProjectManifest;
+  planningRoot: string;
+}
+
+const PROJECT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTROL_BOUNDARY_PATHS = [
+  ".planning/STATE.md",
+  ".planning/.devflow.lock",
+  ".planning/workflows",
+  ".planning/artifacts",
+];
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function canonicalDirectory(candidate: string): Promise<string> {
+  const resolved = path.resolve(candidate);
+  const stat = await lstat(resolved).catch(() => null);
+  if (!stat?.isDirectory()) throw new Error(`Project directory does not exist: ${resolved}`);
+  return realpath(resolved);
+}
+
+async function nearestManifest(start: string): Promise<string | null> {
+  let current = await canonicalDirectory(start);
+  while (true) {
+    const manifest = path.join(current, ".devflow", "project.json");
+    if (await exists(manifest)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+async function gitRoot(start: string): Promise<string | null> {
+  const processHandle = Bun.spawn(["git", "-C", start, "rev-parse", "--show-toplevel"], {
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  if ((await processHandle.exited) !== 0) return null;
+  const output = (await new Response(processHandle.stdout).text()).trim();
+  return output ? canonicalDirectory(output) : null;
+}
+
+export async function resolveProjectRoot(
+  start = process.cwd(),
+  options: { explicit?: string; allowUninitialized?: boolean } = {},
+): Promise<string> {
+  if (options.explicit) return canonicalDirectory(options.explicit);
+  const manifestRoot = await nearestManifest(start);
+  if (manifestRoot) return manifestRoot;
+  const repositoryRoot = await gitRoot(await canonicalDirectory(start));
+  if (repositoryRoot) return repositoryRoot;
+  if (options.allowUninitialized) return canonicalDirectory(start);
+  throw new Error("No Devflow project found. Run `devflow-pi init` from the project root first.");
+}
+
+function validateManifest(value: unknown, manifestPath: string): ProjectManifest {
+  if (!value || typeof value !== "object") throw new Error(`Invalid project manifest: ${manifestPath}`);
+  const record = value as Record<string, unknown>;
+  if (record.schemaVersion !== PROJECT_SCHEMA_VERSION) {
+    throw new Error(`Unsupported project schema in ${manifestPath}: ${String(record.schemaVersion)}`);
+  }
+  if (typeof record.projectId !== "string" || !PROJECT_ID_PATTERN.test(record.projectId)) {
+    throw new Error(`Invalid projectId in ${manifestPath}`);
+  }
+  if (typeof record.name !== "string" || !record.name || typeof record.createdAt !== "string") {
+    throw new Error(`Incomplete project manifest: ${manifestPath}`);
+  }
+  return record as unknown as ProjectManifest;
+}
+
+export async function assertPlanningBoundary(root: string): Promise<string> {
+  const canonicalRoot = await canonicalDirectory(root);
+  const planningRoot = path.join(canonicalRoot, ".planning");
+  const stat = await lstat(planningRoot).catch(() => null);
+  if (stat?.isSymbolicLink()) throw new Error(`Refusing symlinked planning root: ${planningRoot}`);
+  if (stat && !stat.isDirectory()) throw new Error(`Planning root is not a directory: ${planningRoot}`);
+  if (stat) {
+    const canonicalPlanning = await realpath(planningRoot);
+    if (!canonicalPlanning.startsWith(`${canonicalRoot}${path.sep}`)) {
+      throw new Error(`Planning root escapes project boundary: ${canonicalPlanning}`);
+    }
+  }
+  for (const relative of CONTROL_BOUNDARY_PATHS) {
+    const target = path.join(canonicalRoot, relative);
+    const targetStat = await lstat(target).catch(() => null);
+    if (targetStat?.isSymbolicLink()) throw new Error(`Refusing symlinked Devflow control path: ${target}`);
+    if (targetStat) {
+      const canonicalTarget = await realpath(target);
+      if (!canonicalTarget.startsWith(`${canonicalRoot}${path.sep}`)) {
+        throw new Error(`Devflow control path escapes project boundary: ${canonicalTarget}`);
+      }
+    }
+  }
+  return planningRoot;
+}
+
+export async function loadProjectContext(root: string): Promise<ProjectContext> {
+  const canonicalRoot = await canonicalDirectory(root);
+  const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
+  const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
+  const planningRoot = await assertPlanningBoundary(canonicalRoot);
+  return { root: canonicalRoot, manifestPath, manifest, planningRoot };
+}
+
+async function atomicWriteJson(target: string, value: unknown): Promise<void> {
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  await rename(temporary, target);
+}
+
+export async function initializeProject(root: string): Promise<{ context: ProjectContext; created: boolean }> {
+  const canonicalRoot = await canonicalDirectory(root);
+  const devflowDir = path.join(canonicalRoot, ".devflow");
+  const planningRoot = path.join(canonicalRoot, ".planning");
+  await assertPlanningBoundary(canonicalRoot);
+  await mkdir(devflowDir, { recursive: true });
+  await mkdir(planningRoot, { recursive: true });
+  const manifestPath = path.join(devflowDir, "project.json");
+  if (await exists(manifestPath)) {
+    return { context: await loadProjectContext(canonicalRoot), created: false };
+  }
+  const manifest: ProjectManifest = {
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    projectId: randomUUID(),
+    name: path.basename(canonicalRoot),
+    createdAt: new Date().toISOString(),
+  };
+  await atomicWriteJson(manifestPath, manifest);
+  return {
+    context: { root: canonicalRoot, manifestPath, manifest, planningRoot },
+    created: true,
+  };
+}
+
+export function assertContainedPath(root: string, target: string, label = "path"): string {
+  const canonicalRoot = path.resolve(root);
+  const resolved = path.resolve(canonicalRoot, target);
+  if (resolved !== canonicalRoot && !resolved.startsWith(`${canonicalRoot}${path.sep}`)) {
+    throw new Error(`${label} escapes project boundary: ${target}`);
+  }
+  return resolved;
+}