gachi-retrofit — Non-Destructive Codebase Retrofitting & Diagnostic Repository Inspector

gachi-retrofit is the codebase migration, diagnostic inspection, and non-destructive skeleton overlay engine of the Gachi ecosystem framework. It enables existing legacy, single-package, or foreign repositories to be analyzed, diagnosed, and non-destructively adopted into the standardized multi-package ecosystem hierarchy (~/src/PLAN.md §1.A, Phase 4).

1. Architectural Overview

Per Note [Non-Destructive Skeleton Overlay] [ref:note-nondestructive-retrofit], retrofitting operations must never delete, overwrite, or mutate domain logic source files (src/, app/, lib/, test/). The engine executes through a two-phase architecture:

1. Milestone 4.1: Diagnostic Repository Inspector: Conducts rigorous, read-only static analysis across six dimensions (languages, build manifests, test suites, documentation gaps, Git governance, verification gates) and computes quantitative readiness scores.
2. Milestone 4.2: Non-Destructive Skeleton Overlay: Computes an explicit OverlayPlan categorizing missing standardized assets as ActionCreate and pre-existing files as ActionPreserve. In live mode, materializes missing documentation, agent rules, Git hooks, and verification runners (bin/*-verify) with executable bits, and configures Git governance without touching domain code.
3. Milestone 4.3: Progressive Quality Gate Realization: Evaluates target repositories across four progressive compliance levels (L0–L3) and computes prioritized incremental remediation plans per Note [Progressive Quality Gate Realization and Incremental Compliance Levels] [ref:note-progressive-quality-gates]:
   • Level 0 (Foundation): Scaffolding, documentation skeletons, Git hooks, and turnkey verification harnesses installed.
   • Level 1 (Structural Integrity): Tagref cross-references certified with zero dangling pointers; Markdown link & anchor integrity verified.
   • Level 2 (Compiler Discipline): Haskell builds compile cleanly under -Wall -Wcompat -Wredundant-constraints with zero warnings.
   • Level 3 (Static Analysis Purity): HLint reports zero hints under .hlint.yaml; in-code comment density satisfies the 25.0% threshold (50.0%+ target on src/); full test suites pass cleanly.

Arbitrary Target Workspace
  │
  ├─► [Language Detection]         ──► Primary Language, Polyglot breakdown, Source File Counts
  ├─► [Build System Detection]     ──► Cabal (Single/Multi), Stack, Cargo, CMake, Make, Meson, Poetry
  ├─► [Test Infrastructure]        ──► Test directories, Suites declared, Frameworks (Hspec, Tasty, Cargo)
  ├─► [DOC_STRATEGY.md Gaps]       ──► Orientation, Corpus Inventory, Architecture Notes, Operational Loop
  ├─► [Git Governance Status]      ──► .githooks, commit-msg (RFC 2822 Assisted-by:), pre-commit, .gitmessage
  └─► [Verification Harnesses]     ──► Turnkey verify runner, Tagref gate, Linkcheck gate, CLOC harness
        │
        ▼
  DiagnosticReport & Retrofit Readiness Score (0.0% – 100.0%)
        │
        ▼
  Non-Destructive Overlay Plan (Milestone 4.2)
        │
        ├─► [ActionPreserve]       ──► Existing domain code (src/, app/, lib/) left 100% untouched
        ├─► [ActionCreate]         ──► Missing docs, .agents/rules, .githooks, and bin/*-verify
        └─► [GitGovernanceAction]  ──► core.hooksPath = .githooks, commit.template = .gitmessage
        │
        ▼
  Progressive Quality Gate Realization (Milestone 4.3)
        │
        ├─► Level 0: Foundation (Harnesses, Scaffolding, Documentation)
        ├─► Level 1: Structural Integrity (Tagref zero dangling, Linkcheck clean)
        ├─► Level 2: Compiler Discipline (-Wall clean build, zero warnings)
        └─► Level 3: Static Analysis Purity (Zero HLint hints, CLOC density, Tests pass)

2. Six Diagnostic Dimensions & Overlay Categories

The diagnostic and overlay pipeline covers six orthogonal dimensions:

1. Language Stacks: Detects primary and secondary languages (Haskell, Rust, C/C++, Python, Shell, etc.), measuring file counts and distribution percentages.
2. Build Systems & Layout: Identifies build manifests (cabal.project, *.cabal, stack.yaml, Cargo.toml, CMakeLists.txt, Makefile, pyproject.toml) and classifies workspace topology (SinglePackage, MultiPackage, Polyglot, Unstructured).
3. Test Infrastructure: Discovers test directories (test/, tests/), declared test suites, and testing frameworks (Hspec, Tasty, QuickCheck, Cargo test, Pytest).
4. Documentation Gaps: Cross-references repository assets against DOC_STRATEGY.md requirements (README.md, docs/INDEX.md, docs/notes/*_DESIGN.md, PLAN.md, STATE.md, AGENTS.md, CLAUDE.md, .agents/rules/).
5. Git Governance & Attribution: Audits and configures .git, core.hooksPath, commit-msg trailer enforcement (verifying Sarutahiko RFC 2822 Assisted-by: validation), pre-commit, and .gitmessage template configuration.
6. Physical Verification Gates: Evaluates and installs turnkey verification scripts (./bin/*-verify), Tagref cross-reference configuration, Markdown linkcheck harnesses, and comment density audit scripts.

3. Module Hierarchy

• Gachi.Retrofit.Types: Comprehensive algebraic data models representing diagnostic findings, language statistics, build systems, test suites, documentation gaps, and report structures.
• Gachi.Retrofit.Diagnostic: Pure classification combinators, filesystem exploration routines, heuristic scoring, and remediation plan calculation.
• Gachi.Retrofit.Overlay: Non-destructive skeleton overlay engine, candidate asset synthesis, plan computation (computeOverlayPlan), and materialization (executeOverlayPlan).
• Gachi.Retrofit.QualityGate: Progressive quality gate evaluation engine, 4-level monotonic compliance tracker (L0–L3), and prioritized remediation planner.
• Gachi.Retrofit.Report: Rich terminal dashboard pretty-printing (aligned ASCII tables, progress bars) and GFM Markdown serialization.
• Gachi.Retrofit: Root facade re-exporting the complete public API.

4. Usage Example

import Gachi.Retrofit

main :: IO ()
main = do
  report <- scanRepository "/path/to/legacy-repo"
  putStrLn (formatDiagnosticReport report)

  -- Preview non-destructive overlay plan
  plan <- computeOverlayPlan "/path/to/legacy-repo" report
  putStrLn (formatOverlayPlan plan)

  -- Execute non-destructive overlay (materializes missing assets, preserves domain code)
  res <- executeOverlayPlan plan
  putStrLn (formatOverlayResult res)

  -- Evaluate progressive quality gates (L0–L3) and inspect compliance report
  qgReport <- evaluateQualityGates "/path/to/legacy-repo"
  putStrLn (formatQualityGateReport qgReport)