U-002: target-project .graphlemon/ scaffold (c_project_create)

Implements c_project_create (03-C §3.0) as a plain function for U-007 to wire up later: idempotent by target_folder_path, creates .graphlemon/ + one init commit in an existing git repo, PATH_NOT_FOUND/PATH_NOT_WRITABLE/ GIT_INIT_DECLINED per contract, never silently `git init`s (02-V §2.1). Also corrects a real SDD-vs-plan conflict found while scoping this Unit: development-plan.md's U-002 line cited architecture doc §7.3's directory tree (.claude/agents/, skills/, top-level runs/) as what to create inside a target project. But §13.1 (a later, confirmed decision) states those are graphlemon's own platform-repo assets (U-003 scope), and 01-M's own graphlemon_subdir_initialized field already points at §13.2, whose target- project tree is only .git/ + .graphlemon/ + the target's pre-existing src/. §7.3 predates the "target project is an independent code space" pivot and was superseded by it. Corrected development-plan.md, unit_matrix.json, CLAUDE.md, and 05-实施约束与依赖.md accordingly (user confirmed, 2026-07-31). 23 stdlib unittest cases (src/test_schema.py + new src/test_project_scaffold.py), all passing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

U-002: target-project .graphlemon/ scaffold (c_project_create)
Implements c_project_create (03-C §3.0) as a plain function for U-007 to wire up later: idempotent by target_folder_path, creates .graphlemon/ + one init commit in an existing git repo, PATH_NOT_FOUND/PATH_NOT_WRITABLE/ GIT_INIT_DECLINED per contract, never silently `git init`s (02-V §2.1). Also corrects a real SDD-vs-plan conflict found while scoping this Unit: development-plan.md's U-002 line cited architecture doc §7.3's directory tree (.claude/agents/, skills/, top-level runs/) as what to create inside a target project. But §13.1 (a later, confirmed decision) states those are graphlemon's own platform-repo assets (U-003 scope), and 01-M's own graphlemon_subdir_initialized field already points at §13.2, whose target- project tree is only .git/ + .graphlemon/ + the target's pre-existing src/. §7.3 predates the "target project is an independent code space" pivot and was superseded by it. Corrected development-plan.md, unit_matrix.json, CLAUDE.md, and 05-实施约束与依赖.md accordingly (user confirmed, 2026-07-31). 23 stdlib unittest cases (src/test_schema.py + new src/test_project_scaffold.py), all passing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
bboonnee
1 parent 1a31a2ad
Showing 6 changed files with 250 additions and 6 deletions
CLAUDE.md
docs/development-plan.md
docs/sdd/05-实施约束与依赖.md
docs/sdd/unit_matrix.json
src/project_scaffold.py
src/test_project_scaffold.py
@@ -115,7 +115,9 @@ directly; anything worth reusing has already been copied and adapted into this r
 - `supervisor/isolation/` — staged utility library (isolate/diff/apply), not yet wired to anything
 - `spikes/` — one-off validation spikes (currently just A-1)
 - `src/` (created by U-001) — graphlemon's own backend source (schema, then U-007+ HTTP/WebSocket server).
-  **Not the same `src/` U-002 generates inside a target project's own repo** — those are two different
-  physical repos that can coexist on disk during PH5 self-target. See 05-实施约束与依赖.md §5.7.
+  **Not the same `src/` a target project already has in its own repo** — a target project's `src/` is
+  its own pre-existing source tree; graphlemon does not create or restructure it (see 05-实施约束与依赖.md
+  §5.7 and architecture doc §13.2 — U-002 only creates `.graphlemon/` inside a target project, corrected
+  2026-07-31 after finding development-plan.md's U-002 line had cited the wrong architecture section).
 - Everything else (`.claude/agents/`, `skills/`, `runs/`, per-target-project scaffolding) gets created by
   U-002/U-003 — it doesn't exist yet, and that's expected at this stage.
@@ -48,9 +48,10 @@
   - 覆盖：01-M 全部实体
   - 源码位置：graphlemon 仓库根目录 `src/`（见 05 节 §5.7"源码目录约定"，与 U-002 在目标项目里生成的 `src/` 是两回事）
-- **U-002 [Enabler]** 目标项目 Git 仓库目录骨架初始化逻辑（架构文档 §7.3 目录树：`.claude/agents/`、`.claude/agent-memory/`、`.claude/workflows/`、`skills/`、`runs/`、`src/`）+ `.graphlemon/` 子目录（架构文档 §13.2）
+- **U-002 [Enabler]** 目标项目 Git 仓库目录骨架初始化逻辑：只生成 `.graphlemon/` 子目录（含 `runs/<task_id>/`，架构文档 §13.2——01-M `project.graphlemon_subdir_initialized` 字段本身指向的就是这节，不是 §7.3）
+  - **2026-07-31 订正**：development-plan.md 这行原先误引用了架构文档 §7.3 的旧目录树（`.claude/agents/`、`.claude/agent-memory/`、`.claude/workflows/`、`skills/`、顶层 `runs/`）。但 §13.1（"已确认"决策，晚于 §7.3）明确写着这些是 graphlemon **平台自己仓库**的资产（"graphlemon 平台自己的仓库只保留平台资产：Org/Work Graph 引擎、Skill 库、Agent 人设...不含任何目标项目的业务代码"），属于 U-003 范围，不是目标项目、不是 U-002。§7.3 是"graphlemon 只服务自己开发自己"阶段（自举模式）的旧设计，已被 §13"目标项目是独立代码空间"这个决策取代。目标项目自己的 `src/` 不需要 graphlemon 创建或规定结构（"目标项目自己原有的源码目录，graphlemon 不规定具体结构，尊重目标项目原有约定"）。用户确认，2026-07-31。
   - 依赖：U-001（`project.graphlemon_subdir_initialized` 字段需要有实体支撑）
-  - Done：给定一个空 git 仓库，能生成完整目录骨架并产生一次初始化 commit；非 git 仓库时按 02-V 2.1 节的确认态流程走（不静默 `git init`）
+  - Done：给定一个空 git 仓库，能生成 `.graphlemon/` 子目录骨架并产生一次初始化 commit；非 git 仓库时按 02-V 2.1 节的确认态流程走（不静默 `git init`）
   - 覆盖：01-M `project`；03-C `c_project_create`
 - **U-003 [Enabler]** graphlemon 平台自身的仓库/运行时目录结构（与目标项目仓库物理分离；本地非 Git 的原始日志目录，见架构文档 §13.2）
@@ -68,7 +68,7 @@
 - 前端是本地 Web 应用（浏览器页面），后端用 `http.server`/`socketserver` 等 stdlib 原生能力提供 HTTP API；WebSocket 若 stdlib 支持不足，实施时（U-007）需要验证并可退化为 SSE/长轮询，但仍在 stdlib 范围内解决，不引入第三方包；前端不引入 npm/构建步骤，可以是原生 HTML/CSS/JS 或参考 graphloop `graph.html`/`project.html` 的单文件 no-build 页面模式
 - **例外**：这条约束只针对 graphlemon 平台自身的实现语言，不代表 graphlemon 生成/审查的目标项目代码也必须是 Python——目标项目用什么语言由目标项目自己的技术栈决定
 - **影响**：development-plan.md 的 U-007（本地后端骨架）、U-008（前端骨架）、U-036（Deploy Supervisor 骨架）的 Done 标准隐含"纯 stdlib"这条约束
-- **源码目录约定（2026-07-30 补充）**：graphlemon 平台自身的后端源码（U-001 的 schema 实现、U-007 起的 HTTP/WebSocket 后端）落在 graphlemon 仓库根目录的 `src/`。这与 U-002 在**目标项目**仓库内生成的 `src/` 是两个完全不同的目录（分属两个物理仓库，见架构文档 §13.1"目标项目是独立代码空间"决策）——PH5 self-target 场景下二者会同时存在于同一台机器上，实现时不要混淆，必要时以绝对路径而非相对路径区分
+- **源码目录约定（2026-07-30 补充，2026-07-31 订正）**：graphlemon 平台自身的后端源码（U-001 的 schema 实现、U-007 起的 HTTP/WebSocket 后端）落在 graphlemon 仓库根目录的 `src/`。这与**目标项目**仓库自己已有的 `src/` 是两个完全不同的目录，分属两个物理仓库（见架构文档 §13.1"目标项目是独立代码空间"决策）——PH5 self-target 场景下二者会同时存在于同一台机器上，实现时不要混淆，必要时以绝对路径而非相对路径区分。**订正**：目标项目的 `src/` 不是 U-002 生成的——U-002 只在目标项目里创建 `.graphlemon/` 子目录（架构文档 §13.2），目标项目自己的 `src/` 是其原有源码目录，graphlemon 不创建也不规定其结构；development-plan.md 此前 U-002 那行误引用了架构文档 §7.3 的旧目录树，已于 2026-07-31 订正（§7.3 是"graphlemon 只服务自己开发自己"阶段的旧设计，已被 §13 取代，§7.3 里的 `.claude/agents/`、`skills/`、顶层 `runs/` 实际是 graphlemon 平台自己仓库的资产，属于 U-003 范围）
 ## 5.8 self-target 场景治理规则（`self-development-feasibility.md` 缺口 1/3，2026-07-30 回填）
@@ -12,7 +12,7 @@
   },
   "units": [
     {"id": "U-001", "phase": "PH0", "sub_phase": "PH0-S1", "name": "01-M 全部 15 实体物理 schema", "classification": "Enabler", "depends_on": [], "coverage": {"model": ["project", "org_graph_definition", "task", "work_graph_run", "work_node_execution", "artifact", "bug_record", "skill", "skill_iteration", "agent_profile", "budget_guardrail_config", "org_concurrency_config", "execution_event", "execution_log_file", "log_retention_config"], "view": [], "controller": [], "process": [], "requirement": []}, "done": "15 张表全部建表成功，关键约束（唯一/外键/枚举）有单测覆盖"},
-    {"id": "U-002", "phase": "PH0", "sub_phase": "PH0-S1", "name": "目标项目 Git 仓库目录骨架初始化", "classification": "Enabler", "depends_on": ["U-001"], "coverage": {"model": ["project"], "view": [], "controller": ["c_project_create"], "process": [], "requirement": []}, "done": "给定空 git 仓库，能生成完整目录骨架并产生初始化 commit"},
+    {"id": "U-002", "phase": "PH0", "sub_phase": "PH0-S1", "name": "目标项目 Git 仓库目录骨架初始化（仅 .graphlemon/，见架构文档 §13.2；2026-07-31 订正，此前误引用 §7.3）", "classification": "Enabler", "depends_on": ["U-001"], "coverage": {"model": ["project"], "view": [], "controller": ["c_project_create"], "process": [], "requirement": []}, "done": "给定空 git 仓库，能生成 .graphlemon/ 子目录骨架并产生初始化 commit"},
     {"id": "U-003", "phase": "PH0", "sub_phase": "PH0-S1", "name": "graphlemon 平台自身仓库/运行时目录结构", "classification": "Enabler", "depends_on": [], "coverage": {"model": [], "view": [], "controller": [], "process": [], "requirement": []}, "done": "平台目录与目标项目目录物理分离，互不干扰"},
     {"id": "U-004", "phase": "PH0", "sub_phase": "PH0-S2", "name": "Hermes profile 迁移到 .claude/agents/*.md", "classification": "Risk Gate", "depends_on": ["U-002"], "coverage": {"model": [], "view": [], "controller": [], "process": [], "requirement": [], "assumption": ["A-2"]}, "done": "claude --agent planner -p 可正常启动且系统提示词正确；skills/memory/tools/model frontmatter 配置完整"},
     {"id": "U-004.5", "phase": "PH0", "sub_phase": "PH0-S2", "name": "RUN_REAL_AGENT_E2E 门控测试 harness（2026-07-30 新增）", "classification": "Enabler", "depends_on": ["U-004"], "coverage": {"model": [], "view": [], "controller": [], "process": [], "requirement": []}, "done": "有可复用的 skip_unless_env(\"RUN_REAL_AGENT_E2E\") 装饰器/基类；默认 unittest 跳过真实 claude 子进程调用；显式开启环境变量时至少一个真实往返用例可跑通"},
+"""c_project_create (03-C §3.0): register/scaffold a target project.
+
+U-002 scope: the directory-scaffolding + DB-persistence half of c_project_create --
+no HTTP endpoint yet (that's U-007); this is the plain function U-007 will wire up.
+
+Target-project directory convention is architecture doc §13.2, NOT §7.3 (see
+development-plan.md's 2026-07-31 correction: §7.3 describes graphlemon's own
+platform repo, not a target project). c_project_create only ever creates
+`.graphlemon/` inside the target folder; a target project's own `src/` and
+everything else in it is left untouched.
+"""
+
+import os
+import subprocess
+import uuid
+
+_GIT_IDENTITY = [
+    "-c", "user.name=graphlemon",
+    "-c", "user.email=graphlemon@localhost",
+]
+
+
+class PathNotFoundError(Exception):
+    """PATH_NOT_FOUND -- 03-C §3.0: target_folder_path does not exist."""
+
+
+class PathNotWritableError(Exception):
+    """PATH_NOT_WRITABLE -- 03-C §3.0: no write permission on target_folder_path."""
+
+
+class GitInitDeclinedError(Exception):
+    """GIT_INIT_DECLINED -- 03-C §3.0: not a git repo and caller didn't ask to init one.
+
+    02-V §2.1: the UI must get explicit user confirmation before setting
+    init_git_if_missing=True; this function never silently runs `git init`.
+    """
+
+
+def _run_git(args, cwd):
+    subprocess.run(["git"] + args, cwd=cwd, check=True, capture_output=True, text=True)
+
+
+def create_project(conn, target_folder_path, name=None, init_git_if_missing=False):
+    """Implements c_project_create (03-C §3.0).
+
+    Returns {"project_id", "has_git_repo", "graphlemon_subdir_initialized"}.
+    Idempotent: a second call with the same target_folder_path returns the
+    existing row untouched (01-M 1.0 幂等约束) -- no re-validation, no repeat
+    side effects, matching REQ-11's failure-case wording.
+    """
+    existing = conn.execute(
+        "SELECT project_id, has_git_repo, graphlemon_subdir_initialized "
+        "FROM project WHERE target_folder_path = ?",
+        (target_folder_path,),
+    ).fetchone()
+    if existing is not None:
+        return {
+            "project_id": existing[0],
+            "has_git_repo": bool(existing[1]),
+            "graphlemon_subdir_initialized": bool(existing[2]),
+        }
+
+    if not os.path.isdir(target_folder_path):
+        raise PathNotFoundError(target_folder_path)
+    if not os.access(target_folder_path, os.W_OK):
+        raise PathNotWritableError(target_folder_path)
+
+    has_git_repo = os.path.isdir(os.path.join(target_folder_path, ".git"))
+    if not has_git_repo:
+        if not init_git_if_missing:
+            raise GitInitDeclinedError(target_folder_path)
+        _run_git(["init"], cwd=target_folder_path)
+        has_git_repo = True
+
+    graphlemon_subdir = os.path.join(target_folder_path, ".graphlemon")
+    os.makedirs(graphlemon_subdir, exist_ok=True)
+    # git doesn't track empty directories; this is only so the init commit has
+    # something under .graphlemon/ to record. Real content (runs/<task_id>/...)
+    # arrives once tasks actually execute (01-M 1.5 artifact.file_path).
+    open(os.path.join(graphlemon_subdir, ".gitkeep"), "w").close()
+
+    _run_git(["add", ".graphlemon"], cwd=target_folder_path)
+    _run_git(
+        _GIT_IDENTITY + ["commit", "-m", "graphlemon: initialize .graphlemon/ workspace"],
+        cwd=target_folder_path,
+    )
+
+    project_id = str(uuid.uuid4())
+    project_name = name or os.path.basename(os.path.normpath(target_folder_path))
+    conn.execute(
+        "INSERT INTO project "
+        "(project_id, name, target_folder_path, has_git_repo, graphlemon_subdir_initialized, status) "
+        "VALUES (?, ?, ?, ?, 1, 'active')",
+        (project_id, project_name, target_folder_path, int(has_git_repo)),
+    )
+    conn.commit()
+
+    return {
+        "project_id": project_id,
+        "has_git_repo": has_git_repo,
+        "graphlemon_subdir_initialized": True,
+    }
+"""U-002 tests: c_project_create's directory-scaffolding + DB-persistence logic.
+
+Run: python3 -m unittest src.test_project_scaffold -v
+"""
+
+import os
+import shutil
+import stat
+import subprocess
+import tempfile
+import unittest
+
+from src import project_scaffold, schema
+
+
+def _init_git_repo(path):
+    subprocess.run(["git", "init"], cwd=path, check=True, capture_output=True)
+
+
+class ProjectScaffoldTestBase(unittest.TestCase):
+    def setUp(self):
+        self.conn = schema.connect(":memory:")
+        schema.create_schema(self.conn)
+        self.tmpdir = tempfile.mkdtemp(prefix="graphlemon-u002-")
+
+    def tearDown(self):
+        self.conn.close()
+        shutil.rmtree(self.tmpdir, ignore_errors=True)
+
+
+class HappyPathTest(ProjectScaffoldTestBase):
+    def test_existing_git_repo_gets_graphlemon_subdir_and_init_commit(self):
+        _init_git_repo(self.tmpdir)
+
+        result = project_scaffold.create_project(self.conn, self.tmpdir)
+
+        self.assertTrue(result["has_git_repo"])
+        self.assertTrue(result["graphlemon_subdir_initialized"])
+        self.assertTrue(os.path.isdir(os.path.join(self.tmpdir, ".graphlemon")))
+
+        log = subprocess.run(
+            ["git", "log", "--oneline"], cwd=self.tmpdir, check=True, capture_output=True, text=True
+        )
+        self.assertIn("graphlemon: initialize .graphlemon/ workspace", log.stdout)
+
+        row = self.conn.execute(
+            "SELECT project_id, target_folder_path, has_git_repo, graphlemon_subdir_initialized, status "
+            "FROM project WHERE project_id = ?",
+            (result["project_id"],),
+        ).fetchone()
+        self.assertIsNotNone(row)
+        self.assertEqual(row[1], self.tmpdir)
+        self.assertEqual(row[2], 1)
+        self.assertEqual(row[3], 1)
+        self.assertEqual(row[4], "active")
+
+    def test_project_name_defaults_to_folder_name(self):
+        _init_git_repo(self.tmpdir)
+        result = project_scaffold.create_project(self.conn, self.tmpdir)
+        row = self.conn.execute(
+            "SELECT name FROM project WHERE project_id = ?", (result["project_id"],)
+        ).fetchone()
+        self.assertEqual(row[0], os.path.basename(self.tmpdir))
+
+    def test_explicit_name_used_when_given(self):
+        _init_git_repo(self.tmpdir)
+        result = project_scaffold.create_project(self.conn, self.tmpdir, name="Snake Game")
+        row = self.conn.execute(
+            "SELECT name FROM project WHERE project_id = ?", (result["project_id"],)
+        ).fetchone()
+        self.assertEqual(row[0], "Snake Game")
+
+
+class NonGitRepoConfirmationFlowTest(ProjectScaffoldTestBase):
+    """02-V §2.1 / 03-C §3.0: never silently `git init`."""
+
+    def test_declines_without_confirmation_and_leaves_folder_untouched(self):
+        with self.assertRaises(project_scaffold.GitInitDeclinedError):
+            project_scaffold.create_project(self.conn, self.tmpdir, init_git_if_missing=False)
+
+        self.assertFalse(os.path.isdir(os.path.join(self.tmpdir, ".git")))
+        self.assertFalse(os.path.isdir(os.path.join(self.tmpdir, ".graphlemon")))
+        count = self.conn.execute("SELECT COUNT(*) FROM project").fetchone()[0]
+        self.assertEqual(count, 0)
+
+    def test_initializes_git_when_explicitly_confirmed(self):
+        result = project_scaffold.create_project(self.conn, self.tmpdir, init_git_if_missing=True)
+
+        self.assertTrue(result["has_git_repo"])
+        self.assertTrue(os.path.isdir(os.path.join(self.tmpdir, ".git")))
+        self.assertTrue(os.path.isdir(os.path.join(self.tmpdir, ".graphlemon")))
+
+
+class IdempotentCreationTest(ProjectScaffoldTestBase):
+    def test_second_call_returns_existing_record_without_new_commit(self):
+        _init_git_repo(self.tmpdir)
+        first = project_scaffold.create_project(self.conn, self.tmpdir)
+        second = project_scaffold.create_project(self.conn, self.tmpdir)
+
+        self.assertEqual(first["project_id"], second["project_id"])
+        count = self.conn.execute("SELECT COUNT(*) FROM project").fetchone()[0]
+        self.assertEqual(count, 1)
+
+        log = subprocess.run(
+            ["git", "log", "--oneline"], cwd=self.tmpdir, check=True, capture_output=True, text=True
+        )
+        self.assertEqual(len(log.stdout.strip().splitlines()), 1)
+
+    def test_idempotent_hit_skips_path_validation(self):
+        # REQ-11 failure case: repeat calls on an already-registered path must
+        # return the existing record even if the path itself is no longer
+        # valid, not re-validate and error.
+        _init_git_repo(self.tmpdir)
+        first = project_scaffold.create_project(self.conn, self.tmpdir)
+        shutil.rmtree(self.tmpdir)
+
+        second = project_scaffold.create_project(self.conn, self.tmpdir)
+        self.assertEqual(first["project_id"], second["project_id"])
+
+
+class PathValidationErrorsTest(ProjectScaffoldTestBase):
+    def test_nonexistent_path_raises_path_not_found(self):
+        missing = os.path.join(self.tmpdir, "does-not-exist")
+        with self.assertRaises(project_scaffold.PathNotFoundError):
+            project_scaffold.create_project(self.conn, missing)
+
+    def test_unwritable_path_raises_path_not_writable(self):
+        os.chmod(self.tmpdir, stat.S_IRUSR | stat.S_IXUSR)
+        try:
+            if os.access(self.tmpdir, os.W_OK):
+                self.skipTest("running as a user that bypasses permission bits (e.g. root)")
+            with self.assertRaises(project_scaffold.PathNotWritableError):
+                project_scaffold.create_project(self.conn, self.tmpdir)
+        finally:
+            os.chmod(self.tmpdir, stat.S_IRWXU)
+
+
+if __name__ == "__main__":
+    unittest.main()