feat: three-layer state directory separation

Layer 1: .flow/ (runtime, gitignored) — epics, tasks, specs, pipeline state
Layer 2: .flow-config/ (team config, git-tracked) — project-context.md, invariants.md, config.json
Layer 3: ~/.flow/projects/{slug}/ (global, cross-session) — frecency.json, memory/

New modules:
- paths.rs: FlowPaths struct with resolve(), slug from git remote,
  convenience getters with primary→fallback resolution
- flowctl paths: CLI command showing all resolved paths

Init changes:
- Creates .flow-config/ and ~/.flow/projects/{slug}/memory/
- Migrates existing files to new locations (COPY, not move)
- project-context.md now generated in .flow-config/

Read changes:
- project_context: load_resolved() tries .flow-config/ first
- frecency: load_resolved()/save_resolved() uses global dir
- guard: uses load_resolved() for project-context

Slug: computed from git remote URL (owner-repo format).
Backward compatible: all reads fall back to .flow/ if new paths missing.
381 tests pass. Zero new dependencies.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

bin/flowctl

@@ -0,0 +1,43 @@
+# .flow 状态目录设计分析
+
+> 基于行业最佳实践 + gstack 参考 | 2026-04-09
+
+## 结论
+
+**项目内 `.flow/` 是正确的选择**，符合行业共识（git/.git, cargo/target, nx/.nx）。
+不应移到 `~/.flow/projects/`。
+
+## 当前已有的 CWD 修复（足够）
+
+1. `get_flow_dir()` 向上遍历 — 子目录执行时自动找到根目录的 .flow
+2. `--project-dir` / `-C` — 显式指定项目目录
+3. `FLOW_STATE_DIR` 环境变量 — CI/脚本使用
+
+## 未来可选改进（不紧急）
+
+### 1. 分层存储（gstack 模式）
+
+```
+.flow/              ← 运行时状态（gitignore）
+.flow-config/       ← 团队配置（git 追踪）
+~/.flow/projects/   ← 跨会话记忆（全局）
+```
+
+### 2. Slug 缓存（gstack 的 slug-cache）
+
+用 `git remote get-url origin` 生成项目 slug，缓存到 `~/.flow/slug-cache/`。
+下次找 .flow 时先查缓存，不用遍历。
+
+### 3. Frecency 移到全局
+
+文件频率数据是跨会话积累的，放到 `~/.flow/projects/{slug}/frecency.json`。
+不影响当前功能，只是位置更合理。
+
+## 不做的理由
+
+把 .flow 拆成 3 个位置需要修改 flowctl 所有文件路径解析（~50 个文件引用 .flow）。
+投入产出比不够。当前 3 个 CWD 修复已经解决了 5 轮审计的 #1 问题。
+
+---
+
+*Generated 2026-04-09*

docs/state-directory-analysis.md

@@ -352,8 +352,9 @@ pub fn cmd_guard(json_mode: bool, layer: String) {
     };
 
     // ── Priority chain: project-context → stack config → auto-detection ──
-    // Try project-context.md first (highest priority).
-    let pc = ProjectContext::load(&flow_dir);
+    // Try three-layer resolution first (.flow-config/ then .flow/), fall back to direct load.
+    let pc = ProjectContext::load_resolved()
+        .or_else(|| ProjectContext::load(&flow_dir));
     let pc_commands = pc.as_ref().map(|ctx| {
         let gc = &ctx.guard_commands;
         let mut cmds: Vec<(String, String, String)> = Vec::new();

flowctl/crates/flowctl-cli/src/commands/admin/guard.rs

@@ -89,17 +89,93 @@ pub fn cmd_init(json: bool) {
         eprintln!("warning: failed to ensure store dirs: {e}");
     }
 
+    // ── Layer 2: .flow-config/ (team config, git-tracked) ──────────────
+    let config_dir = cwd.join(".flow-config");
+    if !config_dir.exists() {
+        if let Err(e) = fs::create_dir_all(&config_dir) {
+            eprintln!("warning: failed to create .flow-config/: {e}");
+        } else {
+            actions.push("created .flow-config/".to_string());
+        }
+    }
+
+    // ── Layer 3: global project directory ──────────────────────────────
+    if let Some(paths) = flowctl_core::paths::FlowPaths::resolve() {
+        let global_dir = &paths.global_project_dir;
+        if !global_dir.exists() {
+            if let Err(e) = fs::create_dir_all(global_dir.join("memory")) {
+                eprintln!("warning: failed to create global project dir: {e}");
+            } else {
+                actions.push(format!("created {}", global_dir.display()));
+            }
+        }
+    }
+
+    // ── Migrate existing files to new locations (copy, not move) ───────
+
+    // config.json → .flow-config/config.json
+    let old_config = flow_dir.join("config.json");
+    let new_config = config_dir.join("config.json");
+    if old_config.exists() && !new_config.exists() {
+        if fs::copy(&old_config, &new_config).is_ok() {
+            actions.push("migrated config.json → .flow-config/".to_string());
+        }
+    }
+
+    // project-context.md → .flow-config/project-context.md
+    let old_pc = flow_dir.join("project-context.md");
+    let new_pc = config_dir.join("project-context.md");
+    if old_pc.exists() && !new_pc.exists() {
+        if fs::copy(&old_pc, &new_pc).is_ok() {
+            actions.push("migrated project-context.md → .flow-config/".to_string());
+        }
+    }
+
+    // invariants.md → .flow-config/invariants.md
+    let old_inv = flow_dir.join("invariants.md");
+    let new_inv = config_dir.join("invariants.md");
+    if old_inv.exists() && !new_inv.exists() {
+        if fs::copy(&old_inv, &new_inv).is_ok() {
+            actions.push("migrated invariants.md → .flow-config/".to_string());
+        }
+    }
+
+    // frecency.json + memory/ → global project dir
+    if let Some(paths) = flowctl_core::paths::FlowPaths::resolve() {
+        let old_frec = flow_dir.join("frecency.json");
+        let new_frec = paths.global_project_dir.join("frecency.json");
+        if old_frec.exists() && !new_frec.exists() {
+            if fs::copy(&old_frec, &new_frec).is_ok() {
+                actions.push("migrated frecency.json → global".to_string());
+            }
+        }
+
+        let old_mem = flow_dir.join("memory");
+        let new_mem = paths.global_project_dir.join("memory");
+        if old_mem.is_dir() && !new_mem.exists() {
+            if fs::create_dir_all(&new_mem).is_ok() {
+                for entry in fs::read_dir(&old_mem).into_iter().flatten().flatten() {
+                    let dest = new_mem.join(entry.file_name());
+                    fs::copy(entry.path(), &dest).ok();
+                }
+                actions.push("migrated memory/ → global".to_string());
+            }
+        }
+    }
+
     // Create project-context.md with auto-detected stack info if missing
-    let project_context_path = flow_dir.join("project-context.md");
-    if !project_context_path.exists() {
+    // Write to .flow-config/ (primary location) instead of .flow/
+    let project_context_path = config_dir.join("project-context.md");
+    let fallback_context_path = flow_dir.join("project-context.md");
+    if !project_context_path.exists() && !fallback_context_path.exists() {
         let content = generate_project_context(&cwd);
         if let Err(e) = fs::write(&project_context_path, content) {
             eprintln!("warning: failed to create project-context.md: {e}");
         } else {
             actions.push("created project-context.md (auto-detected stack)".to_string());
         }
     }
-    let has_project_context = project_context_path.exists();
+    let has_project_context = project_context_path.exists() || fallback_context_path.exists();
 
     // Build output
     let message = if actions.is_empty() {
@@ -114,13 +190,13 @@ pub fn cmd_init(json: bool) {
             "path": flow_dir.to_string_lossy(),
             "actions": actions,
             "hint": if has_project_context { serde_json::Value::Null } else {
-                serde_json::Value::String("Tip: copy templates/project-context.md to .flow/project-context.md to share technical standards with all worker agents".to_string())
+                serde_json::Value::String("Tip: copy templates/project-context.md to .flow-config/project-context.md to share technical standards with all worker agents".to_string())
             },
         }));
     } else {
         println!("{}", message);
         if !has_project_context {
-            println!("Tip: copy templates/project-context.md to .flow/project-context.md to share technical standards with all worker agents");
+            println!("Tip: copy templates/project-context.md to .flow-config/project-context.md to share technical standards with all worker agents");
         }
     }
 }

flowctl/crates/flowctl-cli/src/commands/admin/init.rs

@@ -19,6 +19,7 @@ pub mod log;
 pub mod memory;
 pub mod outputs;
 pub mod patch;
+pub mod paths;
 pub mod project_context;
 pub mod query;
 pub mod ralph;

flowctl/crates/flowctl-cli/src/commands/mod.rs

@@ -0,0 +1,38 @@
+//! `flowctl paths` — show all resolved state directory paths.
+
+use flowctl_core::FlowPaths;
+use serde_json::json;
+
+use crate::output::{error_exit, json_output};
+
+/// Show all resolved state directory paths.
+pub fn cmd_paths(json: bool) {
+    match FlowPaths::resolve() {
+        Some(paths) => {
+            if json {
+                json_output(json!({
+                    "project_root": paths.project_root,
+                    "slug": paths.slug,
+                    "runtime_dir": paths.runtime_dir,
+                    "config_dir": paths.config_dir,
+                    "global_project_dir": paths.global_project_dir,
+                    "config_json": paths.config_json(),
+                    "project_context": paths.project_context(),
+                    "invariants": paths.invariants(),
+                    "frecency": paths.frecency(),
+                    "memory_dir": paths.memory_dir(),
+                }));
+            } else {
+                println!(
+                    "Project: {} ({})",
+                    paths.slug,
+                    paths.project_root.display()
+                );
+                println!("Runtime:  {}", paths.runtime_dir.display());
+                println!("Config:   {}", paths.config_dir.display());
+                println!("Global:   {}", paths.global_project_dir.display());
+            }
+        }
+        None => error_exit("Cannot resolve project paths. Run flowctl init first."),
+    }
+}

flowctl/crates/flowctl-cli/src/commands/paths.rs

@@ -98,6 +98,8 @@ enum Commands {
         #[arg(long)]
         all: bool,
     },
+    /// Show all resolved state directory paths (three-layer resolution).
+    Paths,
     /// Show resolved state directory path.
     StatePath {
         /// Task ID to show state file path for.
@@ -645,6 +647,7 @@ fn main() {
     match cli.command {
         // Admin / top-level
         Commands::Init => admin::cmd_init(json),
+        Commands::Paths => commands::paths::cmd_paths(json),
         Commands::Detect => admin::cmd_detect(json),
         Commands::Status { interrupted, dag, epic, progress } => {
             if dag {

flowctl/crates/flowctl-cli/src/main.rs

@@ -48,6 +48,34 @@ impl FrecencyStore {
         }
     }
 
+    /// Load from three-layer resolution (tries ~/.flow/projects/{slug}/ first, then .flow/).
+    pub fn load_resolved() -> Self {
+        if let Some(paths) = crate::paths::FlowPaths::resolve() {
+            let path = paths.frecency();
+            if path.exists() {
+                if let Ok(content) = std::fs::read_to_string(&path) {
+                    if let Ok(entries) = serde_json::from_str(&content) {
+                        return Self { entries };
+                    }
+                }
+            }
+        }
+        Self::default()
+    }
+
+    /// Persist to global project dir via three-layer resolution.
+    pub fn save_resolved(&self) {
+        if let Some(paths) = crate::paths::FlowPaths::resolve() {
+            let path = paths.global_project_dir.join("frecency.json");
+            if let Some(parent) = path.parent() {
+                std::fs::create_dir_all(parent).ok();
+            }
+            if let Ok(content) = serde_json::to_string_pretty(&self.entries) {
+                std::fs::write(&path, content).ok();
+            }
+        }
+    }
+
     /// Record an access with the given weight. Applies decay before adding.
     pub fn record_access(&mut self, path: &str, weight: f64) {
         let now = Utc::now();

flowctl/crates/flowctl-core/src/frecency.rs

@@ -25,6 +25,7 @@ pub mod lifecycle;
 pub mod ngram_index;
 pub mod outputs;
 pub mod patch;
+pub mod paths;
 pub mod pipeline;
 pub mod project_context;
 pub mod repo_map;
@@ -42,3 +43,4 @@ pub use pipeline::PipelinePhase;
 pub use state_machine::{Status, Transition, TransitionError};
 pub use types::{Epic, Evidence, Phase, Task, TaskSize};
 pub use approvals::FileApprovalStore;
+pub use paths::FlowPaths;