Rewrite CLAUDE.md to reflect current repo state, not PH0-era scaffolding

The original CLAUDE.md described a pre-scaffolding repo with no commits and open questions about A-2/critical path -- stale since PH0. Updates it to point at git log as the actual status record, document the two independent unittest discover roots (src/ and supervisor/), the real backend_server.py CLI, the .graphlemon-worktrees/ isolation mechanism and its three real incident notes, and a full repo layout reflecting what's actually there. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Rewrite CLAUDE.md to reflect current repo state, not PH0-era scaffolding
The original CLAUDE.md described a pre-scaffolding repo with no commits and open questions about A-2/critical path -- stale since PH0. Updates it to point at git log as the actual status record, document the two independent unittest discover roots (src/ and supervisor/), the real backend_server.py CLI, the .graphlemon-worktrees/ isolation mechanism and its three real incident notes, and a full repo layout reflecting what's actually there. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
bboonnee
1 parent 5098fbe4
Showing 1 changed file with 134 additions and 63 deletions
CLAUDE.md
 # CLAUDE.md
-This file orients Claude Code when working in this repository. Read this first, then follow the
-pointers below — do not start writing code before reading `docs/development-plan.md` and the
-current Unit's coverage references in `docs/sdd/`.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Read this first, then follow the pointers below — do not start writing code before reading
+`docs/development-plan.md` and the current Unit's coverage references in `docs/sdd/`.
 ## What this is
@@ -18,80 +19,125 @@ the MVCP (Model/View/Controller/Process) methodology from `docs/graphlemon_archi
 equivalent input that produced the SDD. When they conflict, the SDD wins (it's newer and more
 detailed); if a conflict looks unresolved, stop and ask rather than picking one silently.
+## Status: all 43 planned Units (U-001~U-043, PH0~PH5) are implemented and committed
+
+`docs/development-plan.md` and `docs/sdd/unit_matrix.json` describe the plan as it read at
+inception (2026-07-29) — they were **not** kept updated with "done" checkmarks as work landed, so
+don't treat their prose as a live status board. `git log --oneline` is the actual record: every
+Unit from U-001 through U-043 has a matching commit, plus many `U-0XX fix:`/`U-0XX follow-up:`
+commits for bugs found during real (not mocked) runs, plus a long tail of `graphlemon: <artifact
+type> for task <uuid>` / `graphlemon: auto-commit uncommitted changes for <id>` / `graphlemon:
+merge <id>` commits — those are graphlemon **actually self-hosting**: running its own
+Planner→Coder→Validator loop against its own repo (`target_folder_path` == this checkout,
+`src/paths.is_self_target()`), with the Deploy Supervisor (`supervisor/`) staging, health-checking,
+and cutting over its own code changes. PH5 (self-modification / auto-rollback) is real and running,
+not future work — see "Two things named Supervisor" below and `supervisor/self_hosting_e2e.py`.
+
+When a `development-plan.md` line and the actual code disagree about what's done, trust the code
+and `git log`, and — if it matters to the task at hand — flag the doc as stale rather than
+silently trusting either source. `development-plan.md`'s per-Unit "实现补充"/"真实 bug" notes
+(inline, added after-the-fact) are still valuable: they're a real incident log of bugs found
+during self-hosting runs and how they were fixed (e.g. worktree commits being silently dropped,
+`memory: project` writes landing on the wrong checkout) — read them before touching
+`supervisor/isolation/`, `src/work_node_run.py`, or anything worktree-related.
+
 ## Where to start
-1. Read `docs/development-plan.md` — Phase → Sub-phase → Unit breakdown (`docs/sdd/unit_matrix.json`
-   is the machine-readable mirror). Work is organized as Development Units, each classified
-   Value Path / Risk Gate / Enabler, each with explicit `depends_on` and a `done` criterion that
-   references a specific REQ in `docs/sdd/06-验收与测试锚点.md`.
-2. The critical path starts at **U-001** (01-M schema) → U-002 → U-004 → ... Follow
-   `development-plan.md` §3 "关键路径" — do not skip ahead to later Units even if they look more
-   interesting; most have real `depends_on` edges.
-3. **U-004 (A-2 assumption) is the next unvalidated risk on the critical path.** A-1 (dynamic
-   workflow programmatic invocation) was already spike-validated (`spikes/a1-dynamic-workflows/`,
-   confirmed 2026-07-29). A-2 (Hermes profile SOUL.md/AGENTS.md migrating cleanly into
-   `.claude/agents/*.md` without major rewrites) is not yet tested. Validate it early with a
-   minimal spike (per `development-plan.md`'s explicit recommendation) rather than discovering
-   problems after U-010/U-011 are fully built on top of it.
+1. Read `docs/development-plan.md` for the Phase → Sub-phase → Unit breakdown and the *design*
+   rationale behind each piece — but see Status above before trusting any "done"/"depends_on"
+   framing as current. `docs/sdd/unit_matrix.json` is its machine-readable mirror (also static).
+2. `docs/sdd/06-验收与测试锚点.md` has REQ-01 through REQ-15, the acceptance anchors every Unit's
+   Done criterion cites. REQ-15 (PH5, Deploy Supervisor blue-green + auto-rollback) was added
+   2026-07-30 after the original REQ-01~14 set.
+3. For any specific behavior, prefer reading the actual module in `src/`/`supervisor/`/`agents/`
+   over the plan doc — the plan doc records intent at write-time and known deviations, the code is
+   truth.
 ## Commands
-No build, lint, or test tooling exists yet — the repo is pre-scaffolding (PH0, no commits made
-yet). `supervisor/isolation/` has no test suite of its own (that's U-036); `docs/` and `spikes/`
-aren't packages. The one real executable entry point today:
+Two independent `unittest discover` roots — there is no single top-level `discover` that covers
+both (deliberately: `supervisor/` was added later as PH5 landed, see
+`development-plan.md`'s U-036 note):
 ```bash
-# A-1 spike: verify Claude Code dynamic workflows can be invoked headlessly (already validated,
-# kept here for re-running / reference — see spikes/a1-dynamic-workflows/RESULTS.md)
-./spikes/a1-dynamic-workflows/run-spike.sh /path/to/some/git/repo
+# graphlemon's own backend/schema/agent-orchestration code (441 tests as of U-043)
+python3 -m unittest discover -s src
+
+# Deploy Supervisor + the isolate/diff/apply library it depends on
+# (this also picks up supervisor/isolation/test_*.py — no separate invocation needed)
+python3 -m unittest discover -s supervisor -p "test_*.py"
+
+# single test
+python3 -m unittest src.test_work_graph_execute.SomeTestClass.test_method
+```
+
+Both suites skip real-`claude`-subprocess tests by default (`skip_unless_env`, `src/test_support.py`)
+— those need `RUN_REAL_AGENT_E2E=1` and real API spend, e.g.:
+
+```bash
+RUN_REAL_AGENT_E2E=1 python3 -m unittest src.test_agent_e2e
 ```
-Once U-002/U-003 scaffold `src/`, tests run via stdlib `unittest` only (see Testing below) — there
-is no repo convention yet for a single-test invocation beyond the standard
-`python3 -m unittest path.to.test_module.TestClass.test_method`; don't invent a different pattern.
+`supervisor/self_hosting_e2e.py`'s own real end-to-end scenario (`run_self_hosting_closed_loop`,
+the literal 9-step self-development-feasibility.md walkthrough) is gated the same way in
+`supervisor/test_self_hosting_e2e.py` — do not invoke it casually; it does a real self-targeted
+Planner→Coder→Validator→stage→cutover→monitor run against **this repo**.
+
+No build step, no lint config, no package manager — pure stdlib Python, nothing to install.
+
+```bash
+# A-1 spike (already validated 2026-07-29, kept for reference/re-running)
+./spikes/a1-dynamic-workflows/run-spike.sh /path/to/some/git/repo
+
+# local console (U-007/U-008): backend serves the API, frontend is static no-build HTML/JS
+python3 -m src.backend_server --port 8000   # default --port 0 means OS-assigned (fine for tests, not for browsing)
+```
 ## Hard constraints (do not relitigate these — they're settled decisions)
 - **Execution backend**: Claude Code ACP only (`claude -p ... --output-format json --json-schema
   <schema> --permission-mode auto`, no `--bare`, no `--dangerously-skip-permissions`). See
-  05 §5.3, §5.3.1, §5.4.
+  05 §5.3, §5.3.1, §5.4. One documented gotcha: `--agent` + `--json-schema` together silently drop
+  `structured_output` — see 05 §5.4.1.1 and `src/work_graph_plan.py`'s ```` ```json ```` fence
+  parsing workaround.
 - **Implementation language**: graphlemon's own backend/frontend/Deploy Supervisor are **pure
   stdlib Python** — no Flask/FastAPI/Express/Node.js, no npm build step. This mirrors the
   predecessor project graphloop's convention. See 05 §5.7. (This constraint is on graphlemon's
   own implementation only — it does NOT apply to the code graphlemon generates for target
   projects, which follows whatever stack that target project uses.)
 - **Testing**: stdlib `unittest` only, no pytest/fixtures. Mock the `subprocess`/`claude -p`
-  boundary in normal tests; real end-to-end tests that actually shell out to `claude` should be
-  gated behind an explicit env var and skipped by default (mirror graphloop's
-  `RUN_REAL_AGENT_E2E=1` pattern) — this project doesn't have that harness yet, build it as part
-  of the relevant Unit rather than improvising a different pattern per test file.
-- **Isolation**: parallel coding nodes must use `git_worktree_ref`. If `target_folder_path` is
-  graphlemon's own repo (self-hosting/self-modification, PH5 only), worktree is **unconditionally
-  mandatory** even for serial single-node changes — see 05 §5.8.
+  boundary in normal tests; real end-to-end tests that actually shell out to `claude` are gated
+  behind `RUN_REAL_AGENT_E2E=1` (`src/test_support.py:skip_unless_env`, mirrors graphloop's
+  precedent) — reuse that helper, don't invent a per-file variant.
+- **Isolation**: parallel coding nodes must use `git_worktree_ref` (`src/work_node_run.py`). If
+  `target_folder_path` is graphlemon's own repo (self-hosting/self-modification), worktree is
+  **unconditionally mandatory** even for serial single-node changes — see 05 §5.8,
+  `src/paths.is_self_target()`. Worktree checkouts live at `.graphlemon-worktrees/<node_exec_id>/`
+  **inside** the main repo's working tree while a node runs (gitignored — never let `git add -A`
+  on `repo_path` pick one up mid-run). Before touching this code, read the three `U-013` incident
+  notes in `development-plan.md` (uncommitted worktree changes silently dropped on merge, `memory:
+  project` writes landing on the main checkout instead of the worktree, and the pathspec-vs-gitignore
+  conflict that fixing the second one introduced) — `work_node_run.ensure_worktree_committed()` is
+  the fix for all three; don't re-solve the same problem a fourth way.
 ## Two things named "Supervisor" — do not confuse them
 1. **"Supervisor（调度子 Agent）"** — an in-process monitoring node inside the Coder Work Graph
    (architecture doc, existing concept). Watches Work Node execution, triggers reflection/
    rescheduling. Part of the Graph Engine itself.
-2. **"Deploy Supervisor"** — an independent OS process, entirely outside the Graph Engine, that
-   handles blue-green deployment and automatic rollback when graphlemon modifies its own code
-   (PH5 only). See `docs/supervisor-auto-rollback-design.md` for the full design and the
-   disambiguation note at the top of that file.
+2. **"Deploy Supervisor"** (`supervisor/`) — an independent OS process (`python3 -m
+   supervisor.deploy_supervisor`), entirely outside the Graph Engine, that handles blue-green
+   deployment and automatic rollback when graphlemon modifies its own code. Fully implemented
+   (U-034~U-043): `deploy_stage.py` (stage a candidate), `deploy_health_check.py` (poll for
+   startup readiness, not one-shot — see U-038 fix), `deploy_cutover.py`, `deploy_monitor.py`,
+   `deploy_rollback.py`. Fail-closed, never-auto-restart philosophy adapted (not imported) from
+   graphloop's `hermes_watchdog.py`. See `docs/supervisor-auto-rollback-design.md` for the full
+   design and the disambiguation note at the top of that file.
 These are unrelated components that happen to share a root word in casual English. Identifiers
 for #2 are always prefixed `c_deploy_supervisor_*` / `deploy_health_signal` — never abbreviate to
 just "supervisor" in code or docs.
-## PH5 (Deploy Supervisor / self-hosting) is not in scope yet
-
-`docs/development-plan.md` PH5 (Units U-034~U-043) depends on PH4 closing first — self-modification
-safety only makes sense once the base system has passed full regression. Don't build any of
-U-034~U-043 before PH0-PH4 are done, even though the design (`docs/supervisor-auto-rollback-design.md`)
-and its four reusable isolation modules (`supervisor/isolation/`) are already staged. Those modules
-were adapted from graphloop and have had exactly one manual smoke test — they still need a real
-`unittest` suite (U-036) before anyone should trust them in a real rollback path.
-
 ## Prior art worth reading, not worth copying wholesale
 `/Users/yibo/Documents/lemonAI/graphloop` is an earlier, unmaintained attempt at this same
@@ -104,20 +150,45 @@ worth reading for the &quot;fail-closed, deterministic, never-auto-restart&quot; supervisi
 (graphlemon's Deploy Supervisor deliberately extends this into auto-rollback rather than just
 auto-halt — see `docs/supervisor-design-comparison.md` for why). Do not import graphloop code
 directly; anything worth reusing has already been copied and adapted into this repo
-(`supervisor/isolation/`).
-
-## Repo layout (as of PH0, before scaffolding exists)
-
-- `docs/` — architecture, SDD, development plan (see above)
-- `docs/wireframes/` — static no-build HTML prototypes for the PH3 console views (`v_*.html`), referenced
-  per-page from `docs/sdd/02-V-界面与交互.md` §2.1-2.13 — implementation starting point once PH3 begins,
-  DOM/class names map 1:1 to that doc's field lists.
-- `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/` 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.
+(`supervisor/isolation/`, adapted verbatim per the U-036 note in `development-plan.md`).
+
+## Repo layout
+
+- `docs/` — architecture doc, SDD (`docs/sdd/`), development plan, self-hosting design docs. See
+  Status above for how stale the plan/unit-matrix "done" framing is relative to the real code.
+- `docs/wireframes/` — static no-build HTML prototypes for the PH3 console views (`v_*.html`),
+  referenced per-page from `docs/sdd/02-V-界面与交互.md` §2.1-2.13; DOM/class names map 1:1 to
+  that doc's field lists.
+- `src/` — graphlemon's own backend: `schema.py` (17-table SQLite schema — the original 01-M 15
+  entities plus PH5's `deployment`/`deploy_health_signal`), `backend_server.py` (stdlib
+  `http.server` HTTP API + WebSocket-ish log/event streaming, no third-party deps), the Org Graph
+  layer (`org_node_trigger.py`, `org_node_lifecycle.py`, `org_loop_route.py`, `org_level_loop.py`),
+  the Work Graph layer (`work_graph_plan.py`, `work_graph_execute.py`, `work_graph_orchestrate.py`,
+  `work_node_run.py`), root-cause tracing (`root_cause_trace.py`), skills (`skill_update.py`,
+  `skill_query.py`), budget/scheduling (`budget_guardrail.py`, `scheduler.py`), and `paths.py`
+  (graphlemon's own runtime home — `~/.graphlemon` by default, override via `GRAPHLEMON_HOME`,
+  deliberately outside this repo checkout so logs/db never enter this repo's own git history).
+  **This is not the same kind of `src/` a target project has in its own repo** — a target
+  project's own `src/` is its pre-existing source tree; graphlemon doesn't create or restructure
+  it (05 §5.7, architecture doc §13.2). Each `src/x.py` has a same-directory `src/test_x.py` (and
+  sometimes `src/test_x_e2e.py` for the gated real-agent variant) — that pairing is the repo
+  convention, keep it when adding modules.
+- `supervisor/` — Deploy Supervisor process + its isolation library (`supervisor/isolation/`:
+  `isolated_workspace.py`, `change_manifest.py`, `selective_apply.py`, `workspace_security.py`,
+  adapted from graphloop). `supervisor/self_hosting_e2e.py` is the acceptance-scenario glue that
+  wires Graph Engine scheduling + Deploy Supervisor into one real self-targeted run.
+- `agents/{coder,planner,validator}/SOUL.md` — original Hermes-profile identity docs, migrated
+  2026-07-31 (A-2 assumption, "部分成立" — Coder's needed real rewriting to drop a hardcoded
+  Feishu API token and a `--dangerously-skip-permissions` self-invocation; Planner/Validator were
+  near-verbatim). These are the source-of-truth prose; `.claude/agents/*.md` is the actual
+  Claude-Code-discoverable wrapper (frontmatter: `skills:`/`memory: project`/`tools:`/`model:`)
+  that Claude Code loads — if you change agent behavior, both need to move together, and the
+  `.claude/agents/*.md` frontmatter comment block records exactly what changed between them.
+- `frontend/` — the PH3 console: static `index.html`/`app.js`/`style.css`, no build step, no npm.
+- `spikes/` — one-off validation spikes (`a1-dynamic-workflows/`, confirmed 2026-07-29).
+- `.claude/agent-memory/{coder,planner,validator}/` — per-agent `memory: project` files, tracked
+  in git on purpose (architecture doc §8 decision: memory must leave a git trail, not be silently
+  mutable local state).
+- `.graphlemon/runs/<task_id>/` — real Artifacts (brd/prd/sdd/benchmark/code_diff/test_report)
+  from actual self-hosting runs against this repo. `.graphlemon-worktrees/` (gitignored, see
+  Isolation above) is the transient per-node worktree checkout directory, not persistent state.