diff --git a/.archon/workflows/dev-pipeline-diagram.html b/.archon/workflows/dev-pipeline-diagram.html index 08b0cbf..7c38960 100644 --- a/.archon/workflows/dev-pipeline-diagram.html +++ b/.archon/workflows/dev-pipeline-diagram.html @@ -11,14 +11,13 @@ table { border-collapse: collapse; width: 100%; margin: 20px 0; } th, td { border: 1px solid #30363d; padding: 8px 12px; text-align: left; } th { background: #161b22; color: #58a6ff; } - tr:nth-child(even) { background: #161b2211; } code { background: #161b22; padding: 2px 6px; border-radius: 4px; color: #79c0ff; } -

Dev Pipeline Workflow

-

Run with: archon workflow run dev-pipeline "implement issue #N"

+

Dev Pipeline Workflow (v2 — split nodes)

+

archon workflow run dev-pipeline --from hotfix --branch feat/issue-N-slug "implement issue #N"

flowchart TD @@ -28,114 +27,96 @@

Dev Pipeline Workflow

PF -->|"exit 0"| R PF -->|"exit 1"| STOP(["WORKFLOW STOPS"]) - R["1-2. RESEARCH
gh issue view
codegraph queries
nlm CLI / context7"] + R["1-2. RESEARCH
gh issue view
codegraph queries (MANDATORY)
nlm CLI / context7"] R --> P P["3. PLAN
Read plan_local template
Write plan file"] - P --> DC + P --> I - subgraph LOOP1 ["dev-cycle — loop node (max 10 iters, 10min idle timeout)"] - direction TB - I["4. IMPLEMENT
Execute plan tasks
pytest after each change"] - I --> RV + I["4. IMPLEMENT
Execute plan tasks
pytest after each change"] + I --> RV - RV["5. REVIEW
feature-dev:code-reviewer
codegraph arch-check"] - RV -->|"issues"| FX["FIX issues"] - FX --> RV - RV -->|"0 issues"| CM + RV["5. REVIEW
feature-dev:code-reviewer
codegraph arch-check
MANDATORY — separate node"] + RV --> CM - CM["6. COMMIT
feat/fix/...(scope): why
Co-Authored-By"] - CM --> CR + CM["6. COMMIT
feat/fix/...(scope): why
Co-Authored-By"] + CM --> CR - CR["7. CRITIQUE
Check acceptance criteria
codegraph structural verify"] - CR -->|"FAIL"| I - end + CR["7. CRITIQUE
output_format: JSON
verdict: pass/fail + gaps"] + CR -->|"verdict: pass"| FG + CR -->|"verdict: fail"| IF - DC --> LOOP1 - LOOP1 -->|"CYCLE_COMPLETE +
until_bash: pytest=0"| RM + IF["7b. IMPLEMENT-FIX
loop max 5 iters
Fix gaps + review + commit"] + IF --> FG + + FG["FINAL GATE
bash: pytest + compileall
trigger_rule: one_success"] + FG --> RM RM["8. ROADMAP
Update ROADMAP.md"] - RM --> PK + RM --> RMV + + RMV["8b. ROADMAP VERIFY
loop max 3 — self-heals
Commits if agent forgot"] + RMV --> PK PK["9. PACKAGE
Bump 0.1.X+1
python -m build
twine upload"] PK --> TC - subgraph LOOP2 ["test-cycle — loop node (max 10 iters, 10min idle timeout)"] - direction TB - T1["Unit tests + compileall"] - T1 --> T2["Install test (fresh venv)"] - T2 --> T3["Self-index (dogfood)"] - T3 --> T4["Leytongo (real-world TS)"] - T4 --> T5["Arch check"] - T5 -->|"fail"| TF["Fix + re-package"] - TF --> T1 - end - - TC --> LOOP2 - LOOP2 -->|"TESTS_PASS +
until_bash: pytest=0"| FI + TC["10. TEST CYCLE
loop max 10 iters
unit + install + self-index
+ leytongo + arch-check"] + TC --> FI FI["11. FILE ISSUES
gh issue create
for discoveries"] FI --> PR - PR["12. CREATE PR
feature to hotfix
+ PyPI version link"] + PR["12. CREATE PR
feature to hotfix
Closes #N + issue comment"] PR --> DONE(["DONE"]) style PF fill:#1a472a,color:#fff,stroke:#2ea043 style STOP fill:#6e1212,color:#fff,stroke:#da3633 style DONE fill:#1a472a,color:#fff,stroke:#2ea043 - style LOOP1 fill:#0d1b2a22,stroke:#1f6feb,stroke-width:2px,color:#c9d1d9 - style LOOP2 fill:#0d1b2a22,stroke:#1f6feb,stroke-width:2px,color:#c9d1d9 + style RV fill:#1a1a3d,color:#fff,stroke:#8957e5 style CR fill:#3d2200,color:#fff,stroke:#d29922 - style T5 fill:#3d2200,color:#fff,stroke:#d29922 + style IF fill:#3d2200,color:#fff,stroke:#d29922 + style FG fill:#1a472a,color:#fff,stroke:#2ea043 + style RMV fill:#3d2200,color:#fff,stroke:#d29922 style I fill:#1a1a3d,color:#fff,stroke:#8957e5 - style RV fill:#1a1a3d,color:#fff,stroke:#8957e5 style CM fill:#1a1a3d,color:#fff,stroke:#8957e5
-

Safety Mechanisms

+

Key Improvements (v2)

-
-flowchart LR - subgraph "Each loop exits when ANY of these fire" - A["Agent signals
promise COMPLETE"] - B["until_bash
pytest exit 0"] - C["max_iterations: 10"] - D["idle_timeout: 10min"] - end - A & B --> AND{"BOTH
required"} - AND --> EXIT["Loop exits"] - C --> EXIT - D --> EXIT - - style AND fill:#3d2200,color:#fff,stroke:#d29922 - style EXIT fill:#1a472a,color:#fff,stroke:#2ea043 -
+ + + + + + + +
Issuev1 (broken)v2 (fixed)
Code reviewerInstruction inside loop prompt — agent skipped itSeparate review node — cannot be skipped
CritiqueBuried in loop, no structured outputSeparate node with output_format JSON — verdict drives routing
ROADMAP commitAgent edited but didn't commitroadmap-verify loop self-heals — commits if forgotten
Package pathsHardcoded to main checkout$(git rev-parse --show-toplevel) — works in worktrees
Critique failLoop re-iterated entire cycleConditional implement-fix node with specific gaps

Node Details

- + - - - - - - - - + + + + + + + + + + + + + +
StepNode IDTypeModelKey Tools
StepNode IDTypeModelKey Feature
0preflightbash-docker, pytest, codegraph
1-2researchpromptopusgh, codegraph CLI, nlm CLI, context7
3planpromptopusRead, Write (plan file)
4-7dev-cycleloopworkflow defaultAll tools, code-reviewer agent
8roadmappromptworkflow defaultRead, Edit
9packagepromptworkflow defaultbuild, twine, curl
10test-cycleloopworkflow defaultpytest, codegraph, pip
11file-issuespromptworkflow defaultgh issue create
12create-prpromptworkflow defaultgh pr create
1-2researchpromptopusMANDATORY codegraph queries
3planpromptopusWrites plan to repo, not ~/
4implementpromptopusPostToolUse hooks for validation
5reviewpromptopusMANDATORY code-reviewer + arch-check
6commitpromptsonnetFresh context, conventional format
7critiquepromptopusoutput_format: {verdict, gaps}
7bimplement-fixloopinheritConditional on verdict==fail, max 5
-final-gatebash-Independent test verification
8roadmappromptinheritMANDATORY edit + commit
8broadmap-verifyloopinheritSelf-heals if commit missing
9packagepromptinheritDynamic paths, commit on branch
10test-cycleloopopus5-stage validation, max 10 iters
11file-issuespromptsonnetgh issue create for discoveries
12create-prpromptinheritCloses #N, issue comment, PR to hotfix
-

How to Run

-

archon workflow run dev-pipeline "implement issue #12 — expose queries.md as @mcp.prompt() templates"

- diff --git a/.archon/workflows/dev-pipeline-diagram.md b/.archon/workflows/dev-pipeline-diagram.md index 0e35efb..0b16d2a 100644 --- a/.archon/workflows/dev-pipeline-diagram.md +++ b/.archon/workflows/dev-pipeline-diagram.md @@ -4,7 +4,7 @@ ```mermaid flowchart TD - START([Start: archon workflow run dev-pipeline]) --> PF + START([archon workflow run dev-pipeline]) --> PF PF["/preflight
bash node"] PF -->|PASS| R @@ -14,93 +14,50 @@ flowchart TD R --> P P["/plan
Read plan_local template
Write plan file directly"] - P --> DC - - subgraph IMPL_LOOP ["Implementation Loop (max 10 iterations)"] - direction TB - I["Step 4: IMPLEMENT
Execute plan tasks
Validate after each change"] - I --> RV - RV["Step 5: REVIEW
code-reviewer agent
+ codegraph arch-check
+ dead-code check"] - RV -->|issues found| FIX["Fix issues"] - FIX --> RV - RV -->|clean| C - C["Step 6: COMMIT
Conventional commit
+ Co-Authored-By"] - C --> CR - CR["Step 7: CRITIQUE
Verify acceptance criteria
+ codegraph structural checks"] - CR -->|FAIL: gaps found| I - end - - DC{dev-cycle
loop node} --> IMPL_LOOP - IMPL_LOOP -->|"CYCLE_COMPLETE
+ until_bash passes"| RM + P --> I + + I["IMPLEMENT
Execute plan tasks
Validate after each change"] + I --> RV + + RV["REVIEW
feature-dev:code-reviewer
+ codegraph arch-check
MANDATORY separate node"] + RV --> CM + + CM["COMMIT
Conventional commit
+ Co-Authored-By"] + CM --> CR + + CR["CRITIQUE
output_format: verdict + gaps
Structured JSON"] + CR -->|"verdict: pass"| FG + CR -->|"verdict: fail"| IF + + IF["IMPLEMENT-FIX
loop max 5
Fix gaps + review + commit"] + IF --> FG + + FG["FINAL-GATE
bash: pytest + compileall
trigger_rule: one_success"] + FG --> RM RM["/roadmap
Update ROADMAP.md"] - RM --> PK + RM --> RMV + + RMV["ROADMAP-VERIFY
loop max 3
Self-heals if not committed"] + RMV --> PK PK["/package
Bump version + build + PyPI"] PK --> TC - subgraph TEST_LOOP ["Test Loop (max 10 iterations)"] - direction TB - T1["Stage 1: Unit tests
pytest + compileall"] - T1 --> T2 - T2["Stage 2: Install test
Fresh venv + pip install"] - T2 --> T3 - T3["Stage 3: Self-index
codegraph index on itself"] - T3 --> T4 - T4["Stage 4: Leytongo
Real-world TS project"] - T4 --> T5 - T5["Stage 5: Arch check
codegraph arch-check"] - T5 -->|any failure| TFIX["Fix + re-package"] - TFIX --> T1 - end - - TC{test-cycle
loop node} --> TEST_LOOP - TEST_LOOP -->|"TESTS_PASS
+ until_bash passes"| FI - - FI["/file-issues
Create GitHub issues for
out-of-scope discoveries"] + TC["TEST-CYCLE
loop max 10
unit + install + self-index
+ leytongo + arch-check"] + TC --> FI + + FI["/file-issues
gh issue create
for discoveries"] FI --> PR - PR["/create-pr
feature → hotfix
with PyPI version link"] + PR["/create-pr
feature to hotfix
Closes #N + issue comment"] PR --> DONE([Done]) - style PF fill:#2d5016,color:#fff - style STOP fill:#8b0000,color:#fff - style DONE fill:#2d5016,color:#fff - style DC fill:#1a3a5c,color:#fff - style TC fill:#1a3a5c,color:#fff - style CR fill:#5c3a1a,color:#fff - style T5 fill:#5c3a1a,color:#fff - style IMPL_LOOP fill:#0d1b2a11,stroke:#1a3a5c,stroke-width:2px - style TEST_LOOP fill:#0d1b2a11,stroke:#1a3a5c,stroke-width:2px -``` - -## Safety Mechanisms - -```mermaid -flowchart LR - subgraph "Loop Exit Conditions" - A["Agent signals
<promise>COMPLETE</promise>"] - B["until_bash
pytest exit code 0"] - C["max_iterations: 10
failsafe"] - D["idle_timeout: 10min
hang detection"] - end - - A --> EXIT{Exit loop} - B --> EXIT - C --> EXIT - D --> EXIT + style PF fill:#1a472a,color:#fff + style STOP fill:#6e1212,color:#fff + style DONE fill:#1a472a,color:#fff + style RV fill:#1a1a3d,color:#fff + style CR fill:#3d2200,color:#fff + style IF fill:#3d2200,color:#fff + style FG fill:#1a472a,color:#fff ``` - -## Node Details - -| Step | Node ID | Type | Model | Key Tools | -|------|---------|------|-------|-----------| -| 0 | `preflight` | bash | - | docker, pytest, codegraph | -| 1-2 | `research` | prompt | opus | gh, codegraph CLI, nlm CLI, context7 | -| 3 | `plan` | prompt | opus | Read, Write (plan file) | -| 4-7 | `dev-cycle` | loop | opus | All tools, code-reviewer agent | -| 8 | `roadmap` | prompt | sonnet | Read, Edit | -| 9 | `package` | prompt | sonnet | build, twine, curl | -| 10 | `test-cycle` | loop | opus | pytest, codegraph, pip | -| 11 | `file-issues` | prompt | sonnet | gh issue create | -| 12 | `create-pr` | prompt | sonnet | gh pr create | diff --git a/.archon/workflows/dev-pipeline.yaml b/.archon/workflows/dev-pipeline.yaml index ac3fb00..a6d6811 100644 --- a/.archon/workflows/dev-pipeline.yaml +++ b/.archon/workflows/dev-pipeline.yaml @@ -2,7 +2,7 @@ name: dev-pipeline description: | Use when: implementing a feature, fixing a bug, or working on a GitHub issue for codegraph. Triggers: "start workflow", "implement issue", "dev pipeline", "work on issue" - Does: preflight -> research -> plan -> implement/review/commit/critique loop -> roadmap -> package -> test -> file-issues -> create-pr + Does: preflight -> research -> plan -> implement -> review -> commit -> critique -> roadmap -> package -> test -> file-issues -> create-pr NOT for: quick one-off fixes, documentation-only changes, manual exploration Run with: @@ -28,7 +28,8 @@ nodes: - id: preflight bash: | set -e - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" PASS=true echo "=== Pre-flight Checks ===" @@ -101,7 +102,9 @@ nodes: effort: high prompt: | You are researching a codegraph issue/feature before planning implementation. - Working directory: /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph + + Find the repo root with: REPO=$(git rev-parse --show-toplevel) + The codegraph package is at: $REPO/codegraph User request: $USER_MESSAGE @@ -114,12 +117,14 @@ nodes: ``` ### 2. Query the codegraph (MANDATORY — do NOT skip this) - The codegraph CLI is at `.venv/bin/codegraph`. You MUST run at least 3 codegraph - queries below before proceeding. Do NOT substitute with Read/Grep — the graph + The codegraph CLI is at `$REPO/codegraph/.venv/bin/codegraph`. You MUST run at least 3 + codegraph queries below before proceeding. Do NOT substitute with Read/Grep — the graph has cross-file relationships that file reading cannot reveal. Find affected symbols: ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" .venv/bin/codegraph query "MATCH (c:Class) WHERE c.name CONTAINS '' RETURN c.name, c.file" .venv/bin/codegraph query "MATCH (f:Function) WHERE f.name CONTAINS '' RETURN f.name, f.file" ``` @@ -149,10 +154,10 @@ nodes: **NotebookLM CLI** (for deep research with sources): ```bash - nlm notebook list # list existing notebooks - nlm notebook query "" # query a notebook - nlm source add --url "" # add a source to research - nlm research start "" # start a new research session + nlm notebook list + nlm notebook query "" + nlm source add --url "" + nlm research start "" ``` **Context7 MCP** (for library documentation): @@ -181,14 +186,14 @@ nodes: Create an implementation plan based on the research. Do NOT enter plan mode. Do NOT use /plan or any interactive planning mode. Just write a plan file directly. - Working directory: /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph + Find the repo with: REPO=$(git rev-parse --show-toplevel) Research findings: $research.output ## Instructions - Read the file `.claude/commands/plan_local.md` for the full plan template and follow + Read the file `$REPO/.claude/commands/plan_local.md` for the full plan template and follow its structure exactly. Write the plan directly to a file — do NOT invoke any skills or slash commands. @@ -205,94 +210,261 @@ nodes: - Include expected test counts - NO vague criteria like "tests pass" or "feature works" - Save the plan to `codegraph/.claude/plans/` with a descriptive kebab-case name. + Save the plan to `$REPO/.claude/plans/` with a descriptive kebab-case name. Use the FULL path from the working directory, not ~/.claude/plans/. The plan MUST be inside the repo, not in your home directory. Output the plan file path when done. # ═══════════════════════════════════════════════════════════════ - # Steps 4-7: Implementation cycle (implement → review → commit → critique) - # Loops until critique passes + # Step 4: Implement # ═══════════════════════════════════════════════════════════════ - - id: dev-cycle + - id: implement depends_on: [plan] model: opus effort: high idle_timeout: 600000 - loop: - prompt: | - You are in the implementation cycle for codegraph. + prompt: | + Read the plan and implement ALL tasks. + + Plan: $plan.output + User request: $USER_MESSAGE + + ## Instructions + + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` + + For each task in the plan, in order: + 1. Read the Mirror/context files referenced in the task + 2. Implement the change + 3. Validate immediately after EVERY file change: + ```bash + python -m compileall codegraph/ -q + .venv/bin/python -m pytest tests/ -q + ``` + 4. Fix any failures before moving to the next task + + After ALL tasks are done, output a summary of what was implemented. + hooks: + PostToolUse: + - matcher: "Write|Edit" + response: + systemMessage: "Run byte-compile and tests NOW to catch errors early." - Plan from previous step: - $plan.output + # ═══════════════════════════════════════════════════════════════ + # Step 5: Review (MANDATORY — separate node guarantees it runs) + # ═══════════════════════════════════════════════════════════════ + + - id: review + depends_on: [implement] + model: opus + effort: high + idle_timeout: 300000 + prompt: | + You MUST run a code review on all changed files. This is a mandatory step. + + Implementation summary: $implement.output - User's original request: - $USER_MESSAGE + ## Instructions + + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` - ## Cycle: Implement → Review → Commit → Critique + ### 1. Get the list of changed files + ```bash + git diff --name-only HEAD + git diff --cached --name-only + ``` - ### Step 4: IMPLEMENT + ### 2. Spawn the code reviewer (MANDATORY) + Use the built-in `feature-dev:code-reviewer` agent to review all changed files. + Focus on: logic bugs, edge cases, security, inconsistencies with codebase patterns. + Only report issues with >80% confidence. - Read the plan file. For each task not yet completed: - 1. Read the Mirror/context files referenced in the task - 2. Implement the change - 3. Validate immediately: - ```bash - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph - python -m compileall codegraph/ -q - .venv/bin/python -m pytest tests/ -q - ``` - 4. Fix any failures before moving to next task + ### 3. Run architecture check + ```bash + .venv/bin/codegraph arch-check + ``` - ### Step 5: REVIEW + ### 4. Run tests + ```bash + .venv/bin/python -m pytest tests/ -q + ``` - After all tasks are implemented: - 1. Spawn the built-in `feature-dev:code-reviewer` agent on changed files - - Only report issues with >80% confidence - 2. Run architecture check: - ```bash - .venv/bin/codegraph arch-check - ``` - 3. If issues found: fix them and re-run the reviewer - 4. Repeat until reviewer finds 0 issues AND arch-check passes AND tests pass + ### 5. Fix and re-review + If the code reviewer found issues: + - Fix each issue + - Re-run the code reviewer on the fixed files + - Repeat until 0 issues remain - ### Step 6: COMMIT + If arch-check found violations: + - Fix them + - Re-run arch-check - Once review is clean: - ```bash - git add - git commit -m "$(cat <<'COMMITEOF' - (): + ### 6. Exit condition + Only finish when ALL of these are true: + - Code reviewer reports 0 high-confidence issues + - arch-check passes (exit 0) + - All tests pass - + Output: list of files reviewed, issues found, issues fixed, final status. - Co-Authored-By: Claude Opus 4.6 (1M context) - COMMITEOF - )" - ``` + # ═══════════════════════════════════════════════════════════════ + # Step 6: Commit + # ═══════════════════════════════════════════════════════════════ + + - id: commit + depends_on: [review] + model: sonnet + context: fresh + prompt: | + Commit all changes with a conventional commit message. + + Review summary: $review.output + + ## Instructions + + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` + + 1. Stage the changed files (NOT .claude/ local files, NOT .env): + ```bash + git add + ``` + + 2. Commit with conventional format and Co-Authored-By: + ```bash + git commit -m "$(cat <<'EOF' + (): + + + + Co-Authored-By: Claude Opus 4.6 (1M context) + EOF + )" + ``` + + 3. Verify: + ```bash + git log --oneline -1 + git branch --show-current # must be feature branch, NOT main/hotfix/dev + ``` + + Output the commit SHA and message. + + # ═══════════════════════════════════════════════════════════════ + # Step 7: Critique (structured output for routing) + # ═══════════════════════════════════════════════════════════════ + + - id: critique + depends_on: [commit] + model: opus + effort: high + context: fresh + output_format: + type: object + properties: + verdict: + type: string + enum: ["pass", "fail"] + criteria_results: + type: array + items: + type: object + properties: + criterion: + type: string + met: + type: boolean + evidence: + type: string + required: [criterion, met, evidence] + gaps: + type: array + items: + type: string + required: [verdict, criteria_results, gaps] + prompt: | + Verify the plan's acceptance criteria are ALL met. + + Plan: $plan.output + Commit: $commit.output + + ## Instructions + + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` - ### Step 7: CRITIQUE + 1. Read the plan file and extract every acceptance criterion + 2. For each criterion: + - Check if it's met by examining code, tests, or running verification commands + - Use codegraph queries for structural verification where specified + - Record evidence (test output, query results, file contents) + 3. Run the full test suite: + ```bash + .venv/bin/python -m pytest tests/ -q + ``` + 4. Return JSON: + - verdict: "pass" if ALL criteria met, "fail" if ANY are not + - criteria_results: array of {criterion, met, evidence} for each + - gaps: array of strings describing what's missing (empty if pass) + + # ═══════════════════════════════════════════════════════════════ + # Step 7b: Fix gaps if critique failed (conditional) + # ═══════════════════════════════════════════════════════════════ + + - id: implement-fix + depends_on: [critique] + when: "$critique.output.verdict == 'fail'" + model: opus + effort: high + idle_timeout: 600000 + loop: + prompt: | + The critique found gaps in the implementation. Fix them. + + Gaps to address: + $critique.output.gaps + + Full critique results: + $critique.output.criteria_results - Read the plan's acceptance criteria. For each criterion: - - Verify it's met by checking code, tests, or running verification commands - - Use codegraph queries for structural verification if specified + Plan: $plan.output + User request: $USER_MESSAGE + + ## Instructions - Run the full test suite one more time: ```bash - .venv/bin/python -m pytest tests/ -q + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" ``` - **If ALL criteria pass**: Signal completion with CYCLE_COMPLETE + For each gap: + 1. Implement the fix + 2. Run tests: `.venv/bin/python -m pytest tests/ -q` + 3. Spawn the `feature-dev:code-reviewer` agent on changed files + 4. Run arch-check: `.venv/bin/codegraph arch-check` + 5. Commit the fix with conventional format + Co-Authored-By - **If ANY criteria fail**: List the gaps, then loop back to implement the fixes. - Do NOT signal completion until all acceptance criteria are met. + Re-verify ALL acceptance criteria from the plan. + If ALL criteria now pass: FIXES_COMPLETE + If gaps remain: list them and continue fixing. - until: CYCLE_COMPLETE - max_iterations: 10 + until: FIXES_COMPLETE + max_iterations: 5 until_bash: | - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" python -m compileall codegraph/ -q 2>&1 && .venv/bin/python -m pytest tests/ -q 2>&1 hooks: PostToolUse: @@ -300,26 +472,48 @@ nodes: response: systemMessage: "Run byte-compile and tests NOW to catch errors early." + # ═══════════════════════════════════════════════════════════════ + # Final gate — independent verification (fan-in from both paths) + # ═══════════════════════════════════════════════════════════════ + + - id: final-gate + depends_on: [critique, implement-fix] + trigger_rule: one_success + bash: | + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + echo "=== Final Gate ===" + python -m compileall codegraph/ -q 2>&1 && echo "PASS: byte-compile" || exit 1 + .venv/bin/python -m pytest tests/ -q 2>&1 && echo "PASS: tests" || exit 1 + echo "FINAL_GATE_PASS" + timeout: 120000 + # ═══════════════════════════════════════════════════════════════ # Step 8: Update ROADMAP.md # ═══════════════════════════════════════════════════════════════ - id: roadmap - depends_on: [dev-cycle] + depends_on: [final-gate] context: fresh prompt: | Update ROADMAP.md at the repo root to reflect what was just implemented. + This step is MANDATORY — you MUST edit and commit the ROADMAP.md file. - Implementation summary: - $dev-cycle.output + Implementation summary: $implement.output + Review summary: $review.output ## Instructions + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO" + ``` + 1. Read the current ROADMAP.md 2. Run `git log --oneline -10` to see recent commits 3. Update these sections: - "TL;DR — where we are" — branch state, test count, package version - - "Shipped since the last roadmap update" — add new commits + - "Shipped since the last roadmap update" — add new commits grouped by theme - "Repository state" — update table - "What's next (ranked)" — move completed items, re-rank remaining - "Known open questions" — remove resolved, add new @@ -327,38 +521,121 @@ nodes: Do NOT rewrite sections that haven't changed. + 5. COMMIT the ROADMAP update (MANDATORY): + ```bash + git add ROADMAP.md + git commit -m "$(cat <<'EOF' + docs(roadmap): update session handoff + + Co-Authored-By: Claude Opus 4.6 (1M context) + EOF + )" + ``` + + 6. Verify: + ```bash + git log --oneline -1 + ``` + + # ═══════════════════════════════════════════════════════════════ + # Step 8b: Verify ROADMAP was committed (self-healing) + # ═══════════════════════════════════════════════════════════════ + + - id: roadmap-verify + depends_on: [roadmap] + loop: + prompt: | + Verify that ROADMAP.md was committed. If it was NOT committed, commit it now. + + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO" + ``` + + Check if ROADMAP.md appears in the last 2 commits: + ```bash + git log --oneline -2 -- ROADMAP.md + ``` + + If no recent commit touches ROADMAP.md: + ```bash + git add ROADMAP.md + git commit -m "docs(roadmap): update session handoff + + Co-Authored-By: Claude Opus 4.6 (1M context) " + ``` + + Once verified or committed: ROADMAP_COMMITTED + until: ROADMAP_COMMITTED + max_iterations: 3 + until_bash: | + REPO=$(git rev-parse --show-toplevel) + cd "$REPO" + git log --oneline -3 --diff-filter=M -- ROADMAP.md | grep -qi roadmap + # ═══════════════════════════════════════════════════════════════ # Step 9: Package and publish # ═══════════════════════════════════════════════════════════════ - id: package - depends_on: [roadmap] + depends_on: [roadmap-verify] context: fresh prompt: | Bump the version, build, and publish to PyPI. ## Instructions - 1. Read current version: `grep '^version' pyproject.toml` - 2. Bump patch: 0.1.X → 0.1.X+1 - 3. Edit pyproject.toml with the new version - 4. Commit the version bump: + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` + + 1. Read current version: + ```bash + grep '^version' pyproject.toml + ``` + + 2. Bump patch: 0.1.X → 0.1.X+1. Edit pyproject.toml with the new version. + + 3. COMMIT the version bump (MANDATORY — must be on the feature branch): ```bash - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph git add pyproject.toml - git commit -m "chore: bump version to 0.1.X + git commit -m "$(cat <<'EOF' + chore: bump version to 0.1.X + + Co-Authored-By: Claude Opus 4.6 (1M context) + EOF + )" + ``` + + 4. Verify the commit is on the feature branch: + ```bash + git log --oneline -1 + git branch --show-current # must NOT be main/hotfix/dev + ``` + + 5. Build: + ```bash + rm -f dist/* + .venv/bin/python -m build + ls dist/ + ``` - Co-Authored-By: Claude Opus 4.6 (1M context) " + 6. Upload: + ```bash + .venv/bin/twine upload dist/* + ``` + + 7. Verify on PyPI: + ```bash + sleep 5 + curl -s https://pypi.org/pypi/cognitx-codegraph/json | python3 -c "import sys,json; print('Published:', json.load(sys.stdin)['info']['version'])" ``` - 5. Build: `rm -f dist/* && .venv/bin/python -m build` - 6. Upload: `.venv/bin/twine upload dist/*` - 7. Verify: check PyPI JSON API for the new version Output the version number and PyPI URL. # ═══════════════════════════════════════════════════════════════ # Step 10: Test (unit + real-world) - # Loops until all tests pass # ═══════════════════════════════════════════════════════════════ - id: test-cycle @@ -374,9 +651,13 @@ nodes: ## Test Stages + ```bash + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" + ``` + ### Stage 1: Unit tests ```bash - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph .venv/bin/python -m pytest tests/ -q python -m compileall codegraph/ -q ``` @@ -419,8 +700,8 @@ nodes: If ANY stage fails: 1. Diagnose the failure - 2. Fix the code (implement the fix, run code review, commit) - 3. Re-package if code changed (`python -m build && twine upload dist/*`) + 2. Fix the code, run code review, commit + 3. Re-package if code changed 4. Re-run all test stages Do NOT signal completion until all stages pass. @@ -428,7 +709,8 @@ nodes: until: TESTS_PASS max_iterations: 10 until_bash: | - cd /home/edouard-gouilliard/Obsidian/SecondBrain/Personal/projects/graphrag-code/codegraph + REPO=$(git rev-parse --show-toplevel) + cd "$REPO/codegraph" .venv/bin/python -m pytest tests/ -q 2>&1 && python -m compileall codegraph/ -q 2>&1 # ═══════════════════════════════════════════════════════════════ @@ -443,7 +725,8 @@ nodes: Review the implementation and testing for any enhancement ideas, bugs in unrelated code, or technical debt worth tracking. - Implementation output: $dev-cycle.output + Implementation output: $implement.output + Review output: $review.output Test output: $test-cycle.output ## Instructions @@ -500,13 +783,12 @@ nodes: curl -s https://pypi.org/pypi/cognitx-codegraph/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])" ``` - 4. If the input mentioned an issue number, add a comment to the issue - explaining what was implemented: + 4. MANDATORY — if the user's original request mentioned an issue number, + you MUST comment on the issue. Extract the issue number from: $USER_MESSAGE ```bash gh issue comment --body "$(cat <<'EOF' ## Implementation Complete - **PR:** **Package:** cognitx-codegraph=={version} ### What was done @@ -522,10 +804,12 @@ nodes: EOF )" ``` + Verify: + ```bash + gh issue view --json comments --jq '.comments | length' + ``` - 5. Create the PR. If an issue number was mentioned, include `Closes #N` - in the PR body — GitHub will auto-close the issue when the PR is merged. - Do NOT manually close the issue — let GitHub handle it via the PR merge. + 5. Create the PR with `Closes #N` in the body: ```bash BRANCH=$(git branch --show-current) gh pr create --base hotfix --head "$BRANCH" --title ": " --body "$(cat <<'EOF' diff --git a/codegraph/pyproject.toml b/codegraph/pyproject.toml index 78f53d3..e0dd2c0 100644 --- a/codegraph/pyproject.toml +++ b/codegraph/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "cognitx-codegraph" -version = "0.1.0" +version = "0.1.2" description = "Code knowledge graph for Claude Code & AI coding agents — index TypeScript, Python, NestJS, FastAPI, React into Neo4j and query architecture in Cypher. Note: v0.2.0 is deprecated, use 0.1.x." readme = "README.md" requires-python = ">=3.10"