docs: add worked example - Epochs of Empire (Unity / C# RTS)

[victorsilvaolav-commits]

Worked example: Epochs of Empire (Unity / C# RTS prototype)

Adds worked/epochs-of-empire/ — a graphify dry-run against a small, cleanly-layered
single-language Unity codebase, a project type not covered by the existing worked
examples.

Corpus: ~20 tracked .cs files, ~5,500 LOC, root namespace EoE.*, one concern per
top-level folder (Core/ AI/ Units/ Buildings/ Player/ World/ UI/ Data/ Editor/), no test
suite, identifiers and comments in Spanish. Two Unity Package Manager files
(Packages/manifest.json, Packages/packages-lock.json) are tracked, as Unity recommends.

Run: graphify extract . --code-only → graphify cluster-only . --no-label. AST-only,
no API key, $0. Communities left as Community N.

Counts: 869 nodes · 1589 edges · 68 communities · 97% EXTRACTED / 3% INFERRED.

What the review covers

Works well

• God nodes are accurate — all top 15 are real core abstractions (Unit, AIPlayer,
  PlayerController, Building, Faction, …). No test-factory noise because there is no
  test suite; degree centrality points straight at the domain model.
• Spanish / non-ASCII identifiers parse cleanly (AIPlanEstado, ReservaBloqueante,
  SinRecursos, IsPointerOverUi).
• No false import cycles — correct; the architecture is acyclic by design.

Doesn't

• Unity package manifests dominate the graph. Packages/packages-lock.json +
  Packages/manifest.json are 39% of nodes and 72% of communities (49/68), and
  dependencies is the highest-betweenness node in the whole graph (0.119, above Unit
  at 0.118). --code-only does not skip them — json_config classifies *.json as code.
  Every Unity project commits these two files.
• Community cohesion is uniformly low (0.05–0.16) and does not recover the on-disk folder
  structure.
• ~40% of nodes reported "isolated", inflated by enum members accessed as
  ResourceType.Food and by boolean properties.
• query and explain underperform on a graph this small with no semantic layer
  (explain "Faction" ambiguity matches explain: silently returns one arbitrary match when a symbol name is ambiguous (no warning, no match count, no way to qualify) #3176).

review.md has the detail, with GRAPH_REPORT.md quoted verbatim for each finding, plus
5 suggested follow-ups (Unity/UPM ignore recipe, --code-only + JSON config, enum-member
edges, type-as-field node identity, small-graph guidance).

Note on reproducibility

The source repo is private, so the run can't be reproduced byte-for-byte. The committed
artifacts and review.md are self-contained — review.md describes the codebase structure
in enough detail to follow every finding, and each finding quotes GRAPH_REPORT.md. Happy
to adjust if a public corpus is required.

[graphify-labs]

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 1 advisory finding(s) below merit a look before merge.

---

Graphify review — findings

Adds a worked case study of running graphify against a Unity C# RTS prototype (EpochsOfEmpire), committing the generated GRAPH_REPORT.md, per-file manifest cache entries, and a README write-up. Documents five review findings where the tool underperforms on this codebase — community detection fragments packages-lock.json metadata into ~20 near-identical dependency clusters and splits a single type across its field occurrences, folder architecture isn't recovered by clustering, and query/explain miss conceptual questions on the small graph.

Worth a look

• Raw graph tooltip HTML reaches vis-network title sink — worked/epochs-of-empire/graph.html · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 198 functions depend on the 198 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 198 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 198 function(s) in the blast radius were not formally verified this run