From b2112e55e11029a77c997bf28a1154208383b2d9 Mon Sep 17 00:00:00 2001 From: Movses Aslanyan Date: Fri, 9 Oct 2026 13:19:25 +0330 Subject: [PATCH] Point CLAUDE.md at the roadmap for current phase and completion Replace the hardcoded "Phase 0a" line with an instruction to read docs/roadmap/summary.md first, and add a verify-report-confirm rule for marking a phase Done in the roadmap files. Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e40ca9e..43cfe43 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,9 @@ The full plan lives in `docs/roadmap/`, split one file per phase so an agent working on a given phase doesn't have to load the other ten: `intro.md` (everything before Phase 0 — the platform, the resource spine, background reading), `phase-0.md` through `phase-10.md`, and `summary.md` (a one-page -status/sequencing overview of all of them). Phase 0 is built test-first from +status/sequencing overview of all of them). **Start every session with +`docs/roadmap/summary.md`** to see where the user is — see "Current phase" +below. Phase 0 is built test-first from two specs: `docs/phase-0a-test-suite-spec.md` (the tests) and `docs/phase-0-base-project-spec.md` (the system). @@ -104,15 +106,44 @@ These override helpfulness. Breaking any of them ruins the exercise. and to operate tools they ask you to operate — not to name the culprit. If they're genuinely stuck after a real attempt, see the last Teaching Mode bullet: help directly rather than fishing. -5. Outside Phase 8 these relax. Ask which phase they're in if it's unclear. +5. Outside Phase 8 these relax. Check `docs/roadmap/summary.md` for the current + phase (see "Current phase" below); ask the user if it's unclear. --- ## Current phase -> **Phase: 0a** — writing the integration test suite. -> *(The user updates this line. If it looks stale relative to the conversation, -> ask before assuming.)* +**This file does not track the current phase.** The source of truth is the +roadmap in `docs/roadmap/`. Before acting on anything phase-dependent (the +spoiler rules, Teaching Mode scope, what to build next, or any "where am I / +what's next" question), **read `docs/roadmap/summary.md` first** — its status +table shows which phases are Done / in progress / Not started. Then read only +the `phase-N.md` file for the phase in play (and `intro.md` for platform +background if needed); don't load all eleven. + +- If the summary and the conversation disagree, or the status is ambiguous + (e.g. no phase is marked in progress), ask the user before assuming. +- The "current phase" is the first phase not marked Done, unless the user says + otherwise. +- Don't edit `CLAUDE.md` to record progress. Status changes go in the roadmap + files, following the completion rule below. + +### Marking a phase done + +Never mark a phase Done unilaterally — "Done when" is the user's judgment, and +some criteria (e.g. "can explain out loud what the Resource attributes mean") +can't be verified from the system alone. When a phase's **Done when** criteria +look met: + +1. **Verify against the live system**, per the Verification section — check the + backend and the files, not the user's or your own claim that it works. +2. **Report each criterion** as verified, failed, or unverifiable-by-Claude + (the last kind is the user's to attest). +3. **Ask the user to confirm** the phase is done. +4. **Only after an explicit yes**, update `docs/roadmap/summary.md` (the status + table row) and that phase's `phase-N.md` (the **Status** and **Message** + lines) in the same change, so the two never disagree. Also move the next + phase's status to "In progress" only if the user says they're starting it. Phase reference: **0a** test suite · **0b** implement to green · 1 concepts + first trace · 2 tracing · 3 logs · 4 metrics · 5 dashboards-as-code ·