Fix graph staleness check (HEAD~1) and sync graphify-out for v4.1.0

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: MertCapkin

CHANGELOG.md

@@ -13,14 +13,14 @@ All notable changes to GraphStack are documented here.
 - **`.graphifyignore`** — code-focused graph profile for the GraphStack source repo (reduces markdown noise in `graphify-out/`).
 - **`docs/case-studies/graphstack-self.md`** — honest self-analysis: graph quality on a meta-repo, token savings confidence levels, validation workflow.
 - **README Limitations** section — orchestrator enforcement, token estimates, graph ROI, setup steps.
-- **Pytest** — 5 new tests in `test_validate.py` (28 total in suite).
+- **Pytest** — 6 new tests in `test_validate.py` (29 total in suite).
 
 ### Changed
 - **CI** — `pip install -e .` before tests; `graphstack validate --fail-stale-graph` step; `pyproject.toml` and `validate.py` in required-files manifest.
 - **Installer** — copies `validate.py` into target projects with the Python package.
 
 ### Fixed
-- N/A (quality-of-life / transparency release).
+- **Graph staleness check** — `validate --fail-stale-graph` accepts `HEAD~1` when the graph was built before a dedicated graph-artifacts commit (common release workflow).
 
 ---
 

graphify-out/GRAPH_REPORT.md

@@ -1,16 +1,16 @@
 # Graph Report - graphstack  (2026-05-17)
 
 ## Corpus Check
-- 20 files · ~5,551 words
+- 20 files · ~5,707 words
 - Verdict: corpus is large enough that graph structure adds value.
 
 ## Summary
-- 454 nodes · 560 edges · 29 communities (25 shown, 4 thin omitted)
-- Extraction: 93% EXTRACTED · 7% INFERRED · 0% AMBIGUOUS · INFERRED: 41 edges (avg confidence: 0.8)
+- 459 nodes · 570 edges · 30 communities (26 shown, 4 thin omitted)
+- Extraction: 92% EXTRACTED · 8% INFERRED · 0% AMBIGUOUS · INFERRED: 43 edges (avg confidence: 0.8)
 - Token cost: 0 input · 0 output
 
 ## Graph Freshness
-- Built from commit: `f1365cd9`
+- Built from commit: `68d5e32f`
 - Run `git rev-parse HEAD` and compare to check if the graph is stale.
 - Run `graphify update .` after code changes (no API cost).
 
@@ -38,17 +38,18 @@
 - [[_COMMUNITY_Community 20|Community 20]]
 - [[_COMMUNITY_Community 21|Community 21]]
 - [[_COMMUNITY_Community 22|Community 22]]
-- [[_COMMUNITY_Community 26|Community 26]]
+- [[_COMMUNITY_Community 23|Community 23]]
 - [[_COMMUNITY_Community 27|Community 27]]
+- [[_COMMUNITY_Community 28|Community 28]]
 
 ## God Nodes (most connected - your core abstractions)
 1. `GraphStack 🧠⚡` - 18 edges
 2. `echo()` - 17 edges
-3. `run_checks()` - 16 edges
+3. `run_checks()` - 17 edges
 4. `ORCHESTRATOR` - 12 edges
 5. `Transition Rules` - 12 edges
-6. `Token Optimizer` - 11 edges
-7. `run_git()` - 10 edges
+6. `run_git()` - 11 edges
+7. `Token Optimizer` - 11 edges
 8. `GraphStack v4 — Cursor Prompts & Setup Guide` - 9 edges
 9. `run_hook()` - 8 edges
 10. `install()` - 8 edges
@@ -65,11 +66,11 @@
 - `_do_update()` --calls--> `graphify_available()`  [INFERRED]
   scripts/graphstack/hook.py → scripts/graphstack/platform_utils.py
 
-## Communities (29 total, 4 thin omitted)
+## Communities (30 total, 4 thin omitted)
 
 ### Community 0 - "Community 0"
-Cohesion: 0.05
-Nodes (42): Always prefer:, "Are there tests for this?", Bootstrap Mode Graph Schedule, code:block1 (SESSION BUDGET), code:block10 (read([src/auth/login.ts, src/auth/session.ts])  // one tool ), code:block11 ("Context at ~80% capacity. Summarizing intermediate state to), code:block12 (TRIGGER 1 — Structural change (highest priority)), code:bash (# Force update now (run in Cursor or terminal)) (+34 more)
+Cohesion: 0.1
+Nodes (34): git_available(), graphify_available(), _brief_is_template(), _brief_status(), _build_parser(), check_board_tasks(), check_brief(), check_graph() (+26 more)
 
 ### Community 1 - "Community 1"
 Cohesion: 0.07
@@ -80,12 +81,12 @@ Cohesion: 0.1
 Nodes (35): _build_parser(), cmd_claim(), cmd_complete(), cmd_log(), cmd_new(), cmd_status(), _get(), _git_commit_board() (+27 more)
 
 ### Community 3 - "Community 3"
-Cohesion: 0.12
-Nodes (29): git_available(), graphify_available(), _brief_is_template(), _brief_status(), _build_parser(), check_board_tasks(), check_brief(), check_graph() (+21 more)
+Cohesion: 0.07
+Nodes (29): Activation, Before every file read, ask internally:, code:block1 (1a. Parallel read (once per session — same tool batch if bot), code:block15 (After Cycle 1 Ship:), code:block16 (Is this in Tier 1 or 2?  → Proceed), code:markdown (## [YYYY-MM-DD HH:MM] — [ROLE] → [NEXT_ROLE]), code:bash (# On role claim:), code:bash (python -m graphstack board new <task-id> "<title>") (+21 more)
 
 ### Community 4 - "Community 4"
 Cohesion: 0.07
-Nodes (29): Activation, Before every file read, ask internally:, code:block1 (1a. Parallel read (once per session — same tool batch if bot), code:block15 (After Cycle 1 Ship:), code:block16 (Is this in Tier 1 or 2?  → Proceed), code:markdown (## [YYYY-MM-DD HH:MM] — [ROLE] → [NEXT_ROLE]), code:bash (# On role claim:), code:bash (python -m graphstack board new <task-id> "<title>") (+21 more)
+Nodes (29): Always prefer:, Bootstrap Mode Graph Schedule, code:block1 (SESSION BUDGET), code:block10 (read([src/auth/login.ts, src/auth/session.ts])  // one tool ), code:block11 ("Context at ~80% capacity. Summarizing intermediate state to), code:block12 (TRIGGER 1 — Structural change (highest priority)), code:bash (# Force update now (run in Cursor or terminal)), code:block14 (Cycle 1 → Ship → STOP → "Run /graphify . now" → wait for con) (+21 more)
 
 ### Community 5 - "Community 5"
 Cohesion: 0.07
@@ -124,35 +125,39 @@ Cohesion: 0.19
 Nodes (5): Round-trip tests for the GNAP board lifecycle., _read(), test_full_lifecycle_todo_to_done(), test_new_task_creates_file(), test_unicode_title_is_preserved()
 
 ### Community 14 - "Community 14"
+Cohesion: 0.15
+Nodes (13): "Are there tests for this?", code:block3 (graph.json → node["src/auth/login.ts"].edges.filter(e => e.t), code:block4 (graph.json → nodes.filter(n => n.edges.some(e => e.target ==), code:block5 (GRAPH_REPORT.md → cluster section → find cluster containing ), code:block6 (graph.json → BFS from node X, depth 2, outgoing edges only), code:block7 (graph.json → node["src/auth/login.ts"].edges.filter(e => e.t), code:block8 (GRAPH_REPORT.md → patterns section), Graph Query Patterns (+5 more)
+
+### Community 15 - "Community 15"
 Cohesion: 0.29
 Nodes (5): login(), createSession(), comparePassword(), generateToken(), hashPassword()
 
-### Community 15 - "Community 15"
+### Community 16 - "Community 16"
 Cohesion: 0.22
 Nodes (7): _build_parser(), main(), Top-level CLI dispatcher.  Five sub-commands: - ``board``     — GNAP task boa, Entry point for both ``python -m graphstack`` and unit tests., Entry point for both ``python -m graphstack`` and unit tests., GraphStack — cross-platform Python core.  This package replaces the bash/Power, Allow ``python -m graphstack`` to invoke the CLI.
 
-### Community 16 - "Community 16"
+### Community 17 - "Community 17"
 Cohesion: 0.2
 Nodes (9): Bootstrap Plan: [Project Name], code:block1 ([Project Name]), Cross-Cutting Concerns, Cycle Log, Cycle Sequence, Known Risks, Module Map, Project Summary (+1 more)
 
-### Community 17 - "Community 17"
+### Community 18 - "Community 18"
 Cohesion: 0.2
 Nodes (9): Acceptance Criteria, Brief: [Feature/Change Name], Graph Context, Handoff Note, Implementation Hints, In Scope, Objective, Out of Scope (+1 more)
 
-### Community 19 - "Community 19"
+### Community 20 - "Community 20"
 Cohesion: 0.25
 Nodes (5): Tests for the post-commit graph-update logic., When ``HEAD~1`` cannot be resolved, structural count must be 0., Files inside graphify-out/ or handoff/ never trigger an update by themselves., test_excludes_generated_paths_from_structural_count(), test_no_previous_commit_skips_structural_diff()
 
-### Community 20 - "Community 20"
+### Community 21 - "Community 21"
 Cohesion: 0.33
 Nodes (5): _disable_git_in_tests(), project_root(), Shared pytest fixtures for the graphstack package., Provide an isolated, writable directory and chdir into it.      All board oper, Prevent any board command from creating real git commits during tests.
 
-### Community 21 - "Community 21"
+### Community 22 - "Community 22"
 Cohesion: 0.33
 Nodes (5): code:block1 (board/), GraphStack GNAP Board, How It Works, Task File Format, Why Git?
 
 ## Knowledge Gaps
-- **191 isolated node(s):** `GNAP board manager — pure Python port of ``scripts/board.sh``.  JSON schema is`, `Stage the board directory and commit silently — never fails the command.`, `Top-level CLI dispatcher.  Five sub-commands: - ``board``     — GNAP task boa`, `Entry point for both ``python -m graphstack`` and unit tests.`, `Path and configuration constants used across the package.  Paths are resolved` (+186 more)
+- **193 isolated node(s):** `GNAP board manager — pure Python port of ``scripts/board.sh``.  JSON schema is`, `Stage the board directory and commit silently — never fails the command.`, `Top-level CLI dispatcher.  Five sub-commands: - ``board``     — GNAP task boa`, `Entry point for both ``python -m graphstack`` and unit tests.`, `Path and configuration constants used across the package.  Paths are resolved` (+188 more)
   These have ≤1 connection - possible missing edges or undocumented components.
 - **4 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
 
@@ -161,15 +166,15 @@ _Questions this graph is uniquely positioned to answer:_
 
 - **Why does `GraphStack 🧠⚡` connect `Community 5` to `Community 9`, `Community 10`?**
   _High betweenness centrality (0.017) - this node is a cross-community bridge._
-- **Why does `echo()` connect `Community 2` to `Community 8`, `Community 3`?**
+- **Why does `echo()` connect `Community 2` to `Community 8`, `Community 0`?**
   _High betweenness centrality (0.011) - this node is a cross-community bridge._
 - **Why does `Quick Start` connect `Community 9` to `Community 5`?**
   _High betweenness centrality (0.011) - this node is a cross-community bridge._
 - **Are the 14 inferred relationships involving `echo()` (e.g. with `_print_task()` and `cmd_status()`) actually correct?**
   _`echo()` has 14 INFERRED edges - model-reasoned connections that need verification._
-- **Are the 5 inferred relationships involving `run_checks()` (e.g. with `test_validate_reports_template_brief_as_warning()` and `test_validate_strict_template_brief_is_error()`) actually correct?**
-  _`run_checks()` has 5 INFERRED edges - model-reasoned connections that need verification._
+- **Are the 6 inferred relationships involving `run_checks()` (e.g. with `test_validate_reports_template_brief_as_warning()` and `test_validate_strict_template_brief_is_error()`) actually correct?**
+  _`run_checks()` has 6 INFERRED edges - model-reasoned connections that need verification._
 - **What connects `GNAP board manager — pure Python port of ``scripts/board.sh``.  JSON schema is`, `Stage the board directory and commit silently — never fails the command.`, `Top-level CLI dispatcher.  Five sub-commands: - ``board``     — GNAP task boa` to the rest of the system?**
-  _191 weakly-connected nodes found - possible documentation gaps or missing edges._
+  _193 weakly-connected nodes found - possible documentation gaps or missing edges._
 - **Should `Community 0` be split into smaller, more focused modules?**
-  _Cohesion score 0.05 - nodes in this community are weakly interconnected._
+  _Cohesion score 0.1 - nodes in this community are weakly interconnected._