A five-phase methodology for turning an undocumented codebase into a navigable, provenance-tagged knowledge base using a code graph, structured agent roles, and independent evidence checks.
Repository status: this repository publishes the methodology, interface descriptions, reconstructed agent profiles, and documentation templates. The 36 Python tools described in the toolchain reference and the original MES proof-of- concept artifacts are not included. See Baseline Status before planning an implementation or evaluating the reported results.
Long-lived systems accumulate undocumented dependencies, business rules, screens, and integration behavior. Conventional API documentation and call graphs expose pieces of that structure but rarely produce business-facing documentation that can be traced back to its evidence.
CodeGraph addresses this by requiring factual claims to carry machine-readable citations to source lines, graph relationships, schema definitions, or screen frames. When evidence is insufficient, the method records an explicit SME-review item instead of silently filling the gap.
A resolving citation is not the same as a correct claim. The public specification separates citation resolution, evidence support, extraction accuracy, and business validation; see Measurement.
flowchart TD
SRC["Source codebase"]
subgraph P1["Phase 1 — Source Ingestion"]
GB["Graph Builder"]
DE["Document Extractor"]
end
NEO[("Knowledge Graph\nprovenance on every edge")]
subgraph P2["Phase 2 — Domain Documentation"]
VPA["VP Author Agents"]
DV["Documentation Validator"]
VT["Validation Triad"]
CA["Citation Auditor"]
end
subgraph P3["Phase 3 — Reference Layer"]
RE["Reference Expert Agents"]
RG["Reference Generators"]
end
subgraph P4["Phase 4 — Process Discovery"]
E2E["E2E Discovery Engine"]
SPD["Screen Process Discoverer"]
end
subgraph P5["Phase 5 — Vault Assembly"]
WL["Vault Wikilinker"]
VV["Vault Verifier"]
end
VAULT["Documentation Vault"]
SRC --> P1 --> NEO
NEO --> P2
NEO --> P3
NEO --> P4
P2 --> P3
P2 --> P4
P2 --> P5
P3 --> P4
P3 --> P5
P4 --> P5 --> VAULT
The graph is the shared evidence substrate. Domain documents, the reference layer, and E2E documents are produced and checked by distinct roles. Phase 5 assembles the accepted outputs into a vault. The five named phases are preserved from the origin engagement; several exact re-run and enrichment rules still require PoC recovery.
Living Documentation is omitted from this core pipeline diagram because it remains an unshipped design specification; it is documented separately in Architecture.
The methodology was developed during a real legacy manufacturing-system engagement. The repository reports the following results from that case. It does not include the client artifacts or audit records required to reproduce them independently.
| Metric | Reported result | Public-evidence limitation |
|---|---|---|
| Sprints to complete | 15 | Sprint length and team composition not published |
| Source files analysed | ~3,900 | File-type breakdown not published |
| Validation packages | 19 | Domain-partitioning procedure not recovered |
| Programs documented | 851 (~99%) | Exact program denominator not published |
| Business rules extracted | 572 | Rule-identification procedure not recovered |
| User stories produced | 248 | Counting protocol not published |
| Screens catalogued | 506 | Original catalog not published |
| End-to-end processes discovered | 18 | Stopping criterion not published |
| Compliance gaps surfaced | 5 critical | Absence claims require parser-scope and SME caveats |
| Hallucinations detected on first complete pass | 0 reported | Definition, denominator, and independent audit protocol not published |
| SME review items flagged | 191 | Reported explicit deferrals |
| Documentation lines produced | 165,970 | Original vault not published |
The engagement also reported a pure data-handoff architecture in which modules integrated through staging tables rather than direct calls. This was a valuable PoC finding, but the evidence package needed to reproduce it is not part of this repo.
Provenance at edge creation. Every graph relationship records its detection mechanism, source file, source line, and confidence tier.
Templated graph retrieval. Agents consume predefined Cypher results instead of inventing graph queries. The public seed library contains only the examples already documented in the schema guide.
Producer/verifier separation. Author roles, the Defender–Challenger–Judge triad, and the Citation Auditor have different responsibilities and write permissions.
Honest gaps. Insufficient evidence becomes an
[SME-REVIEW-REQUIRED:ID] item rather than an inferred business fact.
Case-derived process discovery. Status lifecycles, candidate entry points, shared-table access, and screen clustering provide converging signals for candidate E2E processes. Static signals remain bounded by extraction accuracy.
| Label | Meaning |
|---|---|
POC-ORIGINAL |
Demonstrably used in the MES engagement |
RECONSTRUCTED-TESTED |
Recreated and successfully replayed against accepted PoC evidence |
RECONSTRUCTED-UNTESTED |
Derived from repository documentation but not yet replayed |
PROPOSED-EXPERIMENT |
New behavior; not part of the validated baseline |
The profiles and templates shipped here are RECONSTRUCTED-UNTESTED. They make the
documented roles easier to use, but they are not the lost original prompts.
codegraph/
├── AGENTS.md # AI-agent entry point and boundaries
├── CLAUDE.md # Pointer to the shared agent instructions
├── README.md
├── CONTRIBUTING.md
├── RUN_STATE.example.json # Reconstructed resume-state example
├── docs/ # Methodology and interface specifications
├── prompts/ # Reconstructed provider-neutral role profiles
├── templates/ # Reconstructed document and seed Cypher templates
└── scripts/verify_repo.py # Deterministic repository consistency checks
There is currently no tools/ implementation directory and no supported command
that converts a source tree into a graph or vault.
| Language | Public repository status |
|---|---|
| Origin proprietary 4GL | Method and reported results documented; parser not published |
| Python | Non-runnable parser skeleton in the extension guide |
| TypeScript, Java, Go, and others | Design targets only; no implementations published |
AST availability does not by itself make a resolved call graph compiler-verified. Dynamic dispatch, dependency injection, reflection, and incomplete build context can leave relationships unresolved even in modern languages.
| Term | Meaning |
|---|---|
| VP | Validation Package — the evidence-grounded documentation artifact for one supplied business domain |
| E2E | End-to-End — a candidate or validated business process spanning multiple modules or VPs |
| CRUD | Create, Read, Update, Delete data-access operations |
| SME | Subject Matter Expert who reviews operational meaning and unresolved gaps |
| MOC | Map of Content — a navigable index in the documentation vault |
| GraphRAG | Retrieval-Augmented Generation using structured property-graph results as context |
| Confidence tier | Trust assigned to a recorded graph relationship: compiler, schema, regex, or derived |
| Artifact status | Provenance class distinguishing PoC originals, tested/untested reconstructions, and experiments |
| Document | Description |
|---|---|
| Baseline Status | What is present, reconstructed, missing, or blocked on PoC evidence |
| Architecture | System components and design principles |
| Methodology | The five-phase pipeline and current known limits |
| Agent Architecture | Agent roles, validation pattern, and access constraints |
| Graph Schema | Node types, relationships, provenance, and seed queries |
| Toolchain | Specification of 36 unshipped Python tools |
| Provenance System | Citation tags and what their checks do and do not establish |
| Measurement | Metric definitions and evidence requirements |
| Data Governance | Client-code handling and agent safety requirements |
| User Stories | Case-derived personas and scenarios, with status caveats |
| Parser Extension Guide | Proposed parser interface and illustrative Python skeleton |
The supported workflow in this repository is documentation review and agent-profile reconstruction—not a complete source-to-vault run.
git clone https://github.com/your-org/codegraph.git
cd codegraph
# Verify links, profile labels, template shapes, and Cypher examples.
python3 scripts/verify_repo.pyThen:
- Read AGENTS.md for scope and operating rules.
- Read Baseline Status before trusting an artifact as PoC-original.
- Select an existing role from prompts/.
- Provide that role with a bounded evidence package and the matching template.
- Keep the output marked reconstructed until it passes a replay against accepted PoC evidence.
Do not build the 36 tools from prose and treat the result as the original
implementation. Recovered tools should be published as POC-ORIGINAL; new tools
need their own contract tests and evaluation.
- Teams documenting a legacy system before modernisation.
- Engineers designing an evidence-grounded code-understanding pipeline.
- Auditors reviewing how generated documentation traces to source evidence.
- Researchers or practitioners evaluating graph-plus-agent recovery workflows.
Corrections, artifact recovery, replay fixtures, and measured implementations are welcome. Read CONTRIBUTING.md. New method behavior must remain separate from the baseline until its evidence and promotion decision are recorded.
MIT — see LICENSE.
If you reference this repository, use:
CodeGraph: Evidence-Grounded AI Reverse Engineering
https://github.com/your-org/codegraph