Problem
GRAPH_REPORT.md is a snapshot: current communities, current cohesion scores, current god nodes. It's great for "what does this codebase look like right now," but there's no way to see whether the last month of changes made the architecture healthier or worse — is coupling growing, are new god nodes forming, is a community's cohesion sliding — without manually diffing reports by hand.
Proposal
A lightweight metrics-history mode that, on each rebuild (fits naturally alongside `watch.py`'s incremental rebuild or a git-hook trigger), appends a small record — commit SHA, timestamp, community count, per-community cohesion, god-node count/list, total nodes/edges — to a local history file (e.g. `graphify-out/health_history.jsonl`). A `graphify health` (or `--trend`) command would then read that history and report deltas: which communities gained/lost cohesion, which god nodes are new, whether the graph is trending toward more or less coupling.
`analyze.py`'s `god_nodes()` and the cohesion scores `report.generate()` already consumes are the exact inputs this needs — this is a thin recording + diffing layer on top of data already computed on every rebuild, not a new analysis capability.
Why this fits now
It turns graphify from "a snapshot tool you run when curious" into something that can flag architectural drift proactively — the same shift `graph_diff()` already made possible for two arbitrary graphs, just applied automatically over time instead of on-demand between two manual runs.
Note
This is a proposal, not a commitment to implement — happy to discuss shape/scope first, including whether this belongs in core or as a downstream package consuming the public `analyze`/`report` functions.
Problem
GRAPH_REPORT.md is a snapshot: current communities, current cohesion scores, current god nodes. It's great for "what does this codebase look like right now," but there's no way to see whether the last month of changes made the architecture healthier or worse — is coupling growing, are new god nodes forming, is a community's cohesion sliding — without manually diffing reports by hand.
Proposal
A lightweight metrics-history mode that, on each rebuild (fits naturally alongside `watch.py`'s incremental rebuild or a git-hook trigger), appends a small record — commit SHA, timestamp, community count, per-community cohesion, god-node count/list, total nodes/edges — to a local history file (e.g. `graphify-out/health_history.jsonl`). A `graphify health` (or `--trend`) command would then read that history and report deltas: which communities gained/lost cohesion, which god nodes are new, whether the graph is trending toward more or less coupling.
`analyze.py`'s `god_nodes()` and the cohesion scores `report.generate()` already consumes are the exact inputs this needs — this is a thin recording + diffing layer on top of data already computed on every rebuild, not a new analysis capability.
Why this fits now
It turns graphify from "a snapshot tool you run when curious" into something that can flag architectural drift proactively — the same shift `graph_diff()` already made possible for two arbitrary graphs, just applied automatically over time instead of on-demand between two manual runs.
Note
This is a proposal, not a commitment to implement — happy to discuss shape/scope first, including whether this belongs in core or as a downstream package consuming the public `analyze`/`report` functions.