Epic: structure as identity -- architecture fingerprints you can trust and compare (lessons from DOOM's DNA and agent-habits)

Open
  • Is something wrong?
#7,533 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
8/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
python
Domain
devtools

Research direction

This is a tracking epic, not a single task, so pick one unchecked child rather than the whole list. The most self-contained is #7504, where several functions on one line lose all but the first; start from the function-splitting logic it refers to and reproduce with a one-line, multi-function Python file. Other children touch traceability.json (#7532) and the sfs 3-line function floor, and need design decisions first. Done for a child means its acceptance point in the list is met and the change is covered by a test.

Written by the indexing model from the issue text.

Description

enhancement epic roadmap

The finding this epic acts on

Three studies point the same way:

  • DOOM's DNA: GitGalaxy's structural signal recovered lineage across 43 descendants and showed which translations kept the original blueprint, against chance and negative controls.
  • agent-habits (https://github.com/squid-protocol/agent-habits): structure alone identified which AI model wrote a program 83 % of the time (chance 27 %, permutation p < 0.001; exploratory, registered for replication as round 3). Each model's structure is stable across independent runs: distance 0.32 within a model against 0.62 between models.
  • temporal crucible: structure did not predict defects beyond file size ("history predicts, structure describes").

So GitGalaxy's structural signal is strongest at describing and comparing code (identity, lineage, translation fidelity, drift) and weakest as a risk predictor. This epic points the architecture work at comparison, and fixes what the studies showed breaks it.

Child work

1. Make formatting irrelevant (the measurements must survive how code is laid out)
  • #7501 / #7503: dense hand-written code is no longer excluded as minified (merged)
  • #7504: several functions on one line lose all but the first
  • Measure on statements and tokens, not physical lines, wherever a metric divides by lines (comment ratio, per-function size). An audit of every line-based metric.
  • sfs's 3-line function floor drops one-line functions, which hides dense authors. Review it, or measure on a canonical form.
2. Calibrated fingerprints with a built-in noise floor
  • An engine-level architecture fingerprint per repo and per module, with the distance scale it should be read against. agent-habits gives the first calibration: same author ≈ 0.32, different author ≈ 0.62, different language ≈ 1.0.
  • An architecture drift signal: did a change move a module's fingerprint beyond its own noise floor?
3. Report style and architecture as separate layers
  • Comments, naming and keywords are habit; decomposition, call graph and module shape are architecture. In agent-habits, different model pairs separate on different layers (Haiku against Sonnet on comments; Sonnet against Codex on structure). Today's exposures blend them.
4. Cross-language blueprint fidelity
  • #7532: paragraph-to-method fidelity along traceability.json. Global fingerprints can't trace a mechanical det-port to its source: 1-3 of 124, chance 0.8 %.
  • A translation-invariant representation for whole-program comparison across languages; the portable lens is not invariant to a systematic translation style.
5. Provenance as a report, with honest confidence
  • Lineage (forks, vendored copies) and author attribution (human or which model), with sample sizes and confidence stated; style can shift between model versions.
6. Validate continuously against AI-written code
  • Add the agent-habits programs, and future rounds, to a crucible corpus, with a standing GitGalaxy / tree-sitter / ctags agreement check per author.
  • Tooling lesson: ctags' default COBOL parser assumes fixed format and silently mismatches free-format code. The comparison tooling should choose the parser from the source format.
7. Agents as an architecture lab (the bigger lever)
  • Coding agents make controlled variation possible: many independent implementations of one spec. Use it, pre-registered as in agent-habits, to tie structure to outcomes: which architectural shapes go with stronger chess engines, faster solvers, or code that absorbs a spec change. This is the "better or worse" study held back for now, plus fault injection.

Not in scope here

Evidence-level work on the burned estates (cases, proofs, ladder) is melek's lane. Item 4 measures translations; it adds no evidence records.

Dominant language
Python
Stars
57
Forks
11
Avg merge
1h 35m
Merged PRs (30d)
975

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from squid-protocol/gitgalaxy

All issues in squid-protocol/gitgalaxy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.