@guanlin4924/devflow-pi 0.1.93 → 0.1.94

package/src/project-layout.ts

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { access, cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const DEVFLOW_DIRECTORY = ".devflow";
+export const DEVFLOW_MANIFEST = ".devflow/project.json";
+export const PLANNING_DIRECTORY = ".devflow/planning";
+export const CONTEXT_DIRECTORY = ".devflow/context";
+export const LEGACY_PLANNING_DIRECTORY = ".planning";
+export const LEGACY_CONTEXT_DIRECTORY = ".context";
+export const LAYOUT_MIGRATION_MARKER = ".devflow/layout-migration.json";
+export const LEGACY_PLANNING_MARKERS = [
+  "STATE.md", "PROJECT.md", ".devflow.lock", "navigation/INDEX.md", "code-index/INDEX.md",
+  "workflows", "contracts", "evidence", "review-runs", "requirements", "features",
+  "handoffs", "artifacts", "phase-ownership.yaml",
+] as const;
+export const LEGACY_CONTEXT_MARKERS = ["spec/index.md", "index.md", "project/index.md", "knowledge/index.md"] as const;
+export const ACTIVE_LEGACY_CONTROL_PATHS = [
+  "STATE.md", "workflows", "contracts", "evidence", "review-runs", "requirements",
+  "features", "handoffs", "artifacts", "phase-ownership.yaml",
+] as const;
+
+export const DEVFLOW_SCAN_EXCLUDES = [
+  ".git/**",
+  ".devflow/**",
+  ".planning/**",
+  ".context/**",
+] as const;
+
+export type ProjectLayout = {
+  devflowRoot: string;
+  manifestPath: string;
+  planningRoot: string;
+  contextRoot: string;
+};
+
+export function projectLayout(root: string): ProjectLayout {
+  const projectRoot = path.resolve(root);
+  const devflowRoot = path.join(projectRoot, DEVFLOW_DIRECTORY);
+  return {
+    devflowRoot,
+    manifestPath: path.join(projectRoot, DEVFLOW_MANIFEST),
+    planningRoot: path.join(projectRoot, PLANNING_DIRECTORY),
+    contextRoot: path.join(projectRoot, CONTEXT_DIRECTORY),
+  };
+}
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function containsLegacyMarker(root: string, kind: "planning" | "context"): Promise<boolean> {
+  const markers = kind === "planning" ? LEGACY_PLANNING_MARKERS : LEGACY_CONTEXT_MARKERS;
+  return (await Promise.all(markers.map(marker => exists(path.join(root, marker))))).some(Boolean);
+}
+
+async function containsActiveLegacyControl(root: string): Promise<string | null> {
+  for (const relative of ACTIVE_LEGACY_CONTROL_PATHS) {
+    if (await exists(path.join(root, relative))) return relative;
+  }
+  return null;
+}
+
+async function readValidProjectManifest(manifestPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const value = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
+    const valid = Object.getPrototypeOf(value) === Object.prototype
+      && value.schemaVersion === 1
+      && typeof value.name === "string" && value.name.trim().length > 0
+      && typeof value.createdAt === "string" && Number.isFinite(Date.parse(value.createdAt))
+      && typeof value.projectId === "string"
+      && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value.projectId)
+      && (value.layoutVersion === undefined || value.layoutVersion === 1 || value.layoutVersion === 2);
+    return valid ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function validMigrationMarker(root: string): Promise<boolean> {
+  try {
+    const value = JSON.parse(await readFile(path.join(root, LAYOUT_MIGRATION_MARKER), "utf8")) as Record<string, unknown>;
+    return value.schemaVersion === 1 && value.status === "complete" && Array.isArray(value.migrated);
+  } catch {
+    return false;
+  }
+}
+
+async function rewriteLegacyReferences(directory: string): Promise<void> {
+  const textExtensions = new Set([".md", ".json", ".jsonl", ".yaml", ".yml", ".txt"]);
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`DEVFLOW_LAYOUT_SYMLINK: ${target}`);
+    if (entry.isDirectory()) {
+      await rewriteLegacyReferences(target);
+      continue;
+    }
+    if (!entry.isFile() || !textExtensions.has(path.extname(entry.name).toLowerCase())) continue;
+    const original = await readFile(target, "utf8");
+    const rewritten = original
+      .replaceAll(".planning/", ".devflow/planning/")
+      .replaceAll(".context/", ".devflow/context/");
+    if (rewritten !== original) await writeFile(target, rewritten, "utf8");
+  }
+}
+
+/**
+ * Copies an old Devflow layout into the namespaced layout. Legacy paths stay
+ * read-only and are never selected as new write targets. Migration is only
+ * permitted for a directory next to an existing project manifest and only
+ * when a Devflow-owned marker is present. A same-named business directory is
+ * therefore never treated as control state based on its name alone.
+ */
+export type LayoutMigrationHooks = {
+  beforeCandidatePublish?: (kind: "planning" | "context") => void | Promise<void>;
+  beforeMarkerPublish?: () => void | Promise<void>;
+  allowActive?: boolean;
+  allowUnmanifested?: boolean;
+};
+
+export async function migrateLegacyProjectLayout(root: string, hooks: LayoutMigrationHooks = {}): Promise<string[]> {
+  const projectRoot = path.resolve(root);
+  const layout = projectLayout(projectRoot);
+  const candidates = [
+    { kind: "planning" as const, legacy: path.join(projectRoot, LEGACY_PLANNING_DIRECTORY), canonical: layout.planningRoot },
+    { kind: "context" as const, legacy: path.join(projectRoot, LEGACY_CONTEXT_DIRECTORY), canonical: layout.contextRoot },
+  ];
+  const markedCandidates: typeof candidates = [];
+  for (const candidate of candidates) {
+    const legacyStat = await lstat(candidate.legacy).catch(() => null);
+    if (!legacyStat?.isDirectory() || legacyStat.isSymbolicLink()) continue;
+    if (await containsLegacyMarker(candidate.legacy, candidate.kind)) markedCandidates.push(candidate);
+  }
+  if (!markedCandidates.length) return [];
+  let manifest = await readValidProjectManifest(layout.manifestPath);
+  if (!manifest && hooks.allowUnmanifested) {
+    manifest = {
+      schemaVersion: 1,
+      layoutVersion: 1,
+      projectId: randomUUID(),
+      name: path.basename(projectRoot),
+      createdAt: new Date().toISOString(),
+    };
+    await mkdir(layout.devflowRoot, { recursive: true });
+    await writeFile(layout.manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  }
+  if (!manifest) {
+    throw new Error("DEVFLOW_LEGACY_LAYOUT_CONFIRMATION_REQUIRED: legacy Devflow directories exist without a valid project manifest; initialize or confirm migration explicitly");
+  }
+  const markerValid = await validMigrationMarker(projectRoot);
+  const active = await containsActiveLegacyControl(path.join(projectRoot, LEGACY_PLANNING_DIRECTORY));
+  if (active && !hooks.allowActive && !markerValid) {
+    throw new Error(`DEVFLOW_ACTIVE_LEGACY_LAYOUT: .planning/${active} requires a dedicated control-plane migration before this project can run`);
+  }
+
+  await mkdir(layout.devflowRoot, { recursive: true });
+  const canonicalExists = await exists(layout.planningRoot) || await exists(layout.contextRoot);
+  // A completed v2 migration is immutable. Legacy directories are retained
+  // only as read-only history; never re-import them on a later startup.
+  if (manifest.layoutVersion === 2 && markerValid) {
+    for (const candidate of markedCandidates) {
+      if (!(await exists(candidate.canonical))) {
+        throw new Error(`DEVFLOW_LEGACY_REINTRODUCTION: v2 project will not backfill ${candidate.kind} from a legacy directory`);
+      }
+    }
+    return [];
+  }
+  if (manifest.layoutVersion === 2 && !markerValid) {
+    throw new Error("DEVFLOW_LEGACY_REINTRODUCTION: a v2 project cannot import newly introduced .planning/.context content");
+  }
+  if (canonicalExists && !markerValid) {
+    throw new Error("DEVFLOW_LAYOUT_CONFLICT: a partial canonical layout coexists with legacy Devflow content without a completed migration marker");
+  }
+  const migrated: string[] = [];
+  const committed: string[] = [];
+  for (const candidate of candidates) {
+    const legacyStat = await lstat(candidate.legacy).catch(() => null);
+    if (!legacyStat?.isDirectory() || legacyStat.isSymbolicLink()) continue;
+    if (!(await containsLegacyMarker(candidate.legacy, candidate.kind))) continue;
+    if (await exists(candidate.canonical)) {
+      if (markerValid) continue;
+      throw new Error(`DEVFLOW_LAYOUT_CONFLICT: both ${path.relative(projectRoot, candidate.legacy)} and ${path.relative(projectRoot, candidate.canonical)} exist without a completed migration marker`);
+    }
+    const staging = `${candidate.canonical}.migration-${randomUUID()}`;
+    try {
+      await cp(candidate.legacy, staging, { recursive: true, errorOnExist: true, force: false });
+      await rewriteLegacyReferences(staging);
+      await hooks.beforeCandidatePublish?.(candidate.kind);
+      await rename(staging, candidate.canonical);
+      committed.push(candidate.canonical);
+    } catch (error) {
+      await rm(staging, { recursive: true, force: true }).catch(() => {});
+      await Promise.all(committed.map(target => rm(target, { recursive: true, force: true }).catch(() => {})));
+      throw error;
+    }
+    migrated.push(path.relative(projectRoot, candidate.canonical).replaceAll("\\", "/"));
+  }
+  if (migrated.length) {
+    const marker = path.join(projectRoot, LAYOUT_MIGRATION_MARKER);
+    const temporary = `${marker}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify({ schemaVersion: 1, status: "complete", migrated, legacyReadOnly: true, migratedAt: new Date().toISOString() }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+      await hooks.beforeMarkerPublish?.();
+      await rename(temporary, marker);
+    } catch (error) {
+      await rm(temporary, { force: true }).catch(() => {});
+      await Promise.all(committed.map(target => rm(target, { recursive: true, force: true }).catch(() => {})));
+      throw error;
+    }
+  }
+  return migrated;
+}

package/src/runtime.ts

@@ -21,7 +21,7 @@ export interface RuntimeOptions {
 const TOOL_CALL_SAFETY_PROMPT = `Devflow tool-call rules:
 - Read always requires a non-empty string path; never call Read with {} or omit path.
 - skill:// URLs identify one exact packaged resource. Never use Glob or Grep with a skill:// URL or wildcard; choose an exact resource and use Read.
-- A generated project path such as .context/spec/frontend/index.md is not automatically a packaged skill template path.
+- A generated project path such as .devflow/context/spec/frontend/index.md is not automatically a packaged skill template path.
 - The project-context validator is a final gate. Do not run project-context-validate while files are still being planned or written.`;
 
 const MANAGED_SETTINGS: Record<string, unknown> = {
@@ -212,7 +212,7 @@ export async function runInteractiveRuntime(project: ProjectContext, options: Ru
     if (rolloverConsumptionInFlight || interactiveSubmissionInFlight || runtime.session.isStreaming) return;
     rolloverConsumptionInFlight = true;
     try {
-    const requestPath = path.join(project.root, ".planning", "rollover-request.json");
+    const requestPath = path.join(project.root, ".devflow/planning", "rollover-request.json");
     let request: { schema_version?: number; rollover_id?: string; source_session_id?: string };
     let originalRequest: string;
     try {
@@ -279,7 +279,7 @@ export async function runInteractiveRuntime(project: ProjectContext, options: Ru
     }, delay);
   };
   const waitForControlledRollover = async (): Promise<void> => {
-    const requestPath = path.join(project.root, ".planning", "rollover-request.json");
+    const requestPath = path.join(project.root, ".devflow/planning", "rollover-request.json");
     let requestObserved = false;
     // The input hook may finish its async state transition just after
     // submitInteractiveInput resolves. Wait briefly for that durable request

package/templates/commands/start.md

@@ -39,7 +39,7 @@
 
 **关键约定**：当用户要求进入下一个 workflow 步骤时（说"继续"、"下一步"、或直接调用 workflow skill），在执行新 skill 之前先做两件事：
 
-1. 写入 `.planning/.next-intent`：
+1. 写入 `.devflow/planning/.next-intent`：
    - 继续下一步：`{"action": "continue"}`
    - 调用指定 skill：`{"action": "skill", "skill": "workflow-run-acceptance-tests", "args": "..."}`
 2. 执行 `/clear`
@@ -53,6 +53,6 @@
 - workflow skill 使用 `skill://<name>` 按需读取（如 `skill://workflow-run-acceptance-tests`）。
 - 上下文管理：你觉得需要时就 `/clear`，不要等 compaction。`/clear` 后 hook 会自动恢复 pipeline 状态和索引入口。
 - 优先读取最新的规则、规范和导航索引；索引缺失或过期时回退到 LSP、搜索和源码事实，并显式报告降级状态
-- 读 `.context/lessons/README.md`，避免已知陷阱
-- 每个步骤完成后更新 `.planning/STATE.md`
-- 遇到不确定的情况，在 `.context/lessons/` 中记录
+- 读 `.devflow/context/lessons/README.md`，避免已知陷阱
+- 每个步骤完成后更新 `.devflow/planning/STATE.md`
+- 遇到不确定的情况，在 `.devflow/context/lessons/` 中记录

package/templates/omp/AGENTS.md

@@ -10,7 +10,7 @@ This repository uses an OMP-native, project-scoped software delivery runtime.
 - Mutate checkpoints and steps only with `devflow_transition`.
 - To abandon an active feature, use the runtime-confirmed `devflow_transition`
   `cancel-feature` operation or `/devflow abandon`; never edit control files.
-- Never directly edit `.planning/STATE.md`, `.planning/.next-intent`, `.planning/workflows/`, or `.planning/artifacts/index.yaml`.
+- Never directly edit `.devflow/planning/STATE.md`, `.devflow/planning/.next-intent`, `.devflow/planning/workflows/`, or `.devflow/planning/artifacts/index.yaml`.
 - The parent session is the only workflow-state writer. Task agents return evidence or patches and never advance state.
 
 ## Evidence order

package/templates/omp/hook-config.json

@@ -1,14 +1,14 @@
 {
   "sources": {
-    "state": ".planning/STATE.md",
-    "workflow": ".context/workflow.md",
+    "state": ".devflow/planning/STATE.md",
+    "workflow": ".devflow/context/workflow.md",
     "indexes": [
-      ".planning/rules/INDEX.md",
-      ".context/spec/index.md",
-      ".planning/navigation/INDEX.md",
-      ".planning/code-index/INDEX.md"
+      ".devflow/planning/rules/INDEX.md",
+      ".devflow/context/spec/index.md",
+      ".devflow/planning/navigation/INDEX.md",
+      ".devflow/planning/code-index/INDEX.md"
     ],
-    "lessons": ".context/lessons/README.md"
+    "lessons": ".devflow/context/lessons/README.md"
   },
   "gates": {
     "index_first": {

package/templates/omp/index-policy.json

@@ -3,19 +3,19 @@
   "mode": "advisory",
   "protected_roots": [],
   "required_evidence": [
-    ".planning/rules/INDEX.md",
-    ".context/spec/index.md",
-    ".planning/navigation/INDEX.md"
+    ".devflow/planning/rules/INDEX.md",
+    ".devflow/context/spec/index.md",
+    ".devflow/planning/navigation/INDEX.md"
   ],
   "optional_evidence": [
-    ".planning/code-index/INDEX.md"
+    ".devflow/planning/code-index/INDEX.md"
   ],
   "allowed_before_gate": [
     "AGENTS.md",
     "README.md",
     ".omp/**",
-    ".planning/**",
-    ".context/**",
+    ".devflow/planning/**",
+    ".devflow/context/**",
     ".agent-gates/**",
     ".skills/**"
   ],
@@ -26,8 +26,8 @@
     "full_file_threshold": 30,
     "ignore": [
       ".omp/**",
-      ".planning/**",
-      ".context/**",
+      ".devflow/planning/**",
+      ".devflow/context/**",
       ".agent-gates/**",
       ".skills/**"
     ],