P36.2 (#12)

Sellafield · claude · web-flow · commit d7746da439d7 · 2026-05-23T17:09:27.000+05:00
* Add IMPROVEMENT-021 Phase 1 design spec: graphify-dotnet integration

Covers Directory.Build.targets pre-build hook, dotnet-tools.json registration,
docs/graph/ committed output, and .claude/knowledge/ Claude consumption artifact.
Phase 2 (.NET 10 migration) deferred as independent workstream.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* Add graphify-dotnet integration implementation plan

5-task plan: tool registration, Directory.Build.targets, artifact verification,
Claude knowledge file, and docs/backlog updates.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* chore: register graphify-dotnet 0.7.0 local tool

* chore: add graphify pre-build target and graph output directory

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* chore: switch graphify output to wiki format, gitignore generated artifacts

* chore: switch graphify output to report format

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* docs: add Claude orientation file for codebase graph

* docs: fix codebase-graph.md accuracy (god nodes, .NET version, community count)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* ci: add GitHub Wiki publishing job for codebase graph report

* chore: add graphify-out to gitignore, harden CI SHA interpolation

* docs: update ARCHITECTURE.md and backlog for graphify integration (IMPROVEMENT-021)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

* docs: final review fixes (heading hierarchy, hardcoded counts, CI path)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.claude/knowledge/codebase-graph.md b/.claude/knowledge/codebase-graph.md
@@ -0,0 +1,35 @@
+# Codebase Dependency Graph
+
+Generated by graphify-dotnet from the `src/` directory. Regenerates automatically before
+each build of `Perpetuum.Server` (requires .NET 10 SDK for the graphify tool — `dotnet tool restore` from the
+solution root).
+
+## Artifacts
+
+- **`docs/graph/graph.json`** — machine-readable graph; gitignored,
+  present after any local `Perpetuum.Server` build
+- **`docs/graph/GRAPH_REPORT.md`** — Markdown architecture report; gitignored, same condition
+- **GitHub Wiki** — latest report published by CI:
+  `https://github.com/OpenPerpetuum/PerpetuumServer2/wiki/Codebase-Graph`
+
+## Graph Structure
+
+Nodes represent C# classes, methods, and namespaces (type: `Entity` or `File`).
+Edges represent inheritance, composition, and namespace imports.
+Communities (Louvain clustering, clusters) group related symbols.
+
+## How to Use
+
+**Impact analysis** — when a type is modified, query `graph.json` for edges pointing to that
+node's `id` to find all dependents before assessing blast radius.
+
+**God-node awareness** — the top 10 most-connected symbols are listed in `GRAPH_REPORT.md`
+under "God Nodes". These are the highest-risk symbols to change: `RelocateItems`,
+`LootItemRepository`, `PackItems`, `ChangeAmmo`, `UnstackAmount`, `EquipModule`,
+`ListContainer`, `IWeatherService`, `SetItemName`, `ILootItemRepository` — see `GRAPH_REPORT.md` for the full list.
+
+**Subsystem navigation** — look up a class node in `graph.json` to find its `community` ID,
+then find other nodes with the same `community` to discover related types in the same cluster.
+
+**Dependency verification** — check for edge paths between two namespaces to confirm whether
+an unintended cross-subsystem dependency would be introduced by a change.
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "graphify-dotnet": {
+      "version": "0.7.0",
+      "commands": [
+        "graphify"
+      ]
+    }
+  }
+}
diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml
@@ -57,3 +57,46 @@ jobs:
         name: Perpetuum-AdminTool-Installer-${{ github.sha }}
         path: ${{ env.Workspace }}/src/Perpetuum.AdminToolInstaller/bin/x64/Release/en-US/*.msi
       if: ${{ github.event_name == 'push' }}
+
+  publish-wiki:
+
+    runs-on: windows-latest
+    needs: build
+    if: github.event_name == 'push'
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup .NET 10 (graphify tool requirement)
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 10.0.x
+
+    - name: Restore dotnet tools
+      run: dotnet tool restore
+
+    - name: Generate codebase report
+      working-directory: ${{ github.workspace }}
+      run: dotnet tool run graphify run src -o graphify-out -f report
+
+    - name: Publish report to GitHub Wiki
+      shell: pwsh
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        COMMIT_SHA: ${{ github.sha }}
+      run: |
+        git clone "https://x-access-token:$env:GH_TOKEN@github.com/OpenPerpetuum/PerpetuumServer2.wiki.git" wiki-repo
+        Copy-Item "graphify-out/GRAPH_REPORT.md" -Destination "wiki-repo/Codebase-Graph.md" -Force
+        Set-Location wiki-repo
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+        git add "Codebase-Graph.md"
+        $changes = git status --porcelain
+        if ($changes) {
+          git commit -m "Update codebase graph report [$env:COMMIT_SHA]"
+          git push
+        } else {
+          Write-Host "No wiki changes to publish"
+        }
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,7 @@ Releases/
 .planning/
 *.log
 *_wpftmp.csproj
+
+# graphify-dotnet generated output (regenerates on build)
+docs/graph/
+graphify-out/
diff --git a/Directory.Build.targets b/Directory.Build.targets
@@ -0,0 +1,8 @@
+<Project>
+  <Target Name="GenerateCodeGraph" BeforeTargets="Build"
+          Condition="'$(MSBuildProjectName)' == 'Perpetuum.Server'">
+    <Exec Command="dotnet tool run graphify run &quot;$(MSBuildThisFileDirectory)src&quot; -o &quot;$(MSBuildThisFileDirectory)docs\graph&quot; -f json,report"
+          ContinueOnError="true"
+          WorkingDirectory="$(MSBuildThisFileDirectory)" />
+  </Target>
+</Project>
diff --git a/docs/backlog/improvements.md b/docs/backlog/improvements.md
@@ -499,41 +499,32 @@ Installer output should be a single executable or package that operators can dis
 
 ---
 
-## IMPROVEMENT-021 - Upgrade to .NET 10 and Integrate Graphify
+## IMPROVEMENT-021 - Graphify Codebase Graph Integration
 
-Status: TODO
+Status: DONE
 Priority: HIGH
 Area: Infrastructure / Tooling / AI
+Spec: docs/superpowers/specs/2026-05-23-improvement-021-graphify-integration-design.md
 
 ### Description
-Plan and execute a careful migration of the entire solution from .NET 8 to .NET 10, then integrate the [Graphify](https://github.com/willibrandon/graphify) package (a .NET 10 dependency) to generate a structural graph of the codebase and wire it to Claude for enhanced code understanding and navigation.
-
-### Impact
-.NET 10 (LTS) brings performance improvements, new C# language features, and long-term support beyond .NET 8. The Graphify integration would give Claude (and operators) a machine-readable dependency/call graph of the server codebase, enabling more accurate impact analysis, smarter navigation, and reduced hallucination risk when reasoning about unfamiliar subsystems.
+Integrated `graphify-dotnet` (https://github.com/elbruno/graphify-dotnet) as a local dotnet
+tool. Generates a structural JSON graph and Markdown architecture report before every
+`Perpetuum.Server` build. CI publishes the report to the GitHub Wiki on each push to `develop`.
 
-### Proposed Implementation
-
-**Phase 1 — .NET 10 upgrade**
-- Audit current NuGet dependencies for .NET 10 compatibility; flag any packages with no .NET 10 target or known breaking changes.
-- Update all `<TargetFramework>` entries in `.csproj` files from `net8.0` to `net10.0`.
-- Address any breaking API changes surfaced by the build (`dotnet build`): BCL changes, removed APIs, updated semantics.
-- Update the CI workflow (`.github/workflows/dotnet.yml`) to use the .NET 10 SDK.
-- Validate a full Release build and a local server run before proceeding to Phase 2.
-- Update `docs/STACK.md` to reflect the new runtime version.
-
-**Phase 2 — Graphify integration**
-- Add the Graphify NuGet package to the solution (targeting the appropriate project — likely a standalone tooling project or the AdminTool).
-- Configure Graphify to analyze the `PerpetuumServer2` solution and output a dependency/call graph in a Claude-consumable format (JSON, Markdown, or Graphify's native output).
-- Define what graph artifacts are most useful for Claude: namespace dependency graph, class hierarchy, inter-module call graph, or a combination.
-- Automate graph regeneration (e.g. as a pre-build step or CI artifact) so the graph stays current as the codebase evolves.
-- Document how Claude should load and interpret the graph output — update `.claude/knowledge/architecture.md` with a pointer to the graph artifact and a brief explanation of its structure.
+### Implementation
+- `.config/dotnet-tools.json` registers `graphify-dotnet@0.7.0` (command: `graphify`)
+- `Directory.Build.targets` (solution root) fires `GenerateCodeGraph` before `Perpetuum.Server`
+  builds; `ContinueOnError="true"` soft-fails on machines without .NET 10 SDK
+- `-f json,report` produces `docs/graph/graph.json` and `docs/graph/GRAPH_REPORT.md` (gitignored)
+- `.github/workflows/dotnet.yml` `publish-wiki` job pushes `GRAPH_REPORT.md` to GitHub Wiki as
+  `Codebase-Graph.md` on each push to `develop`
+- `.claude/knowledge/codebase-graph.md` added for Claude orientation
 
 ### Notes
-.NET 10 is on the STS/LTS release train; verify its LTS status and release date before committing to the upgrade timeline.
-Graphify requires .NET 10 — Phase 1 must be complete and stable before Phase 2 begins.
-The upgrade should be done on a dedicated branch with a full build + manual smoke test before merging.
-Pay special attention to any use of reflection, source generators, or runtime behaviour that changed between .NET 8 and .NET 10.
-Autofac and other DI/serialization libraries should be verified for .NET 10 compatibility early — these are common sources of upgrade friction.
+Phase 2 (.NET 8 → .NET 10 project TFM migration) is deferred as an independent workstream.
+The graphify tool requires .NET 10 SDK but the project TFMs remain at net8.0.
+Run `dotnet tool restore` once after cloning to enable graph regeneration.
+GitHub Wiki must have at least one page initialized before the CI publish job can push.
 
 ---
 
diff --git a/docs/codebase/ARCHITECTURE.md b/docs/codebase/ARCHITECTURE.md
@@ -339,3 +339,15 @@ Post-commit hooks via `Transaction.Current.OnCommited(...)` (`src/Perpetuum/Data
 ---
 
 *Architecture analysis: 2026-05-11*
+
+## Graph Artifact
+
+A structural graph of this codebase is generated by graphify-dotnet on every `Perpetuum.Server`
+build (requires .NET 10 SDK and `dotnet tool restore`):
+
+- `docs/graph/graph.json` — machine-readable nodes/edges (gitignored, regenerates on build)
+- `docs/graph/GRAPH_REPORT.md` — Markdown architecture report (gitignored, regenerates on build)
+- GitHub Wiki — latest report published by CI on each push to `develop`:
+  `https://github.com/OpenPerpetuum/PerpetuumServer2/wiki/Codebase-Graph`
+
+See `.claude/knowledge/codebase-graph.md` for how Claude uses these artifacts.
diff --git a/docs/superpowers/plans/2026-05-23-graphify-integration.md b/docs/superpowers/plans/2026-05-23-graphify-integration.md
diff --git a/docs/superpowers/specs/2026-05-23-improvement-021-graphify-integration-design.md b/docs/superpowers/specs/2026-05-23-improvement-021-graphify-integration-design.md
