Drive Corps — Repo Organization Audit

Compared against PressRaven, Peregrine, NoteSparrow, VentureRaven, CodeRaven · 27 July 2026

The mess is real, and it's mostly two things: commit style and root clutter. The structural decisions I made (ignoring the generated .xcodeproj, tracking generated assets) actually match house style — I checked rather than assumed. What doesn't match is that an entire multi-hour session landed as two commits in a foreign format, and that ten loose files are sitting at the repo root where your other projects have three.

How the neighbors work

Project	Commits	Branch	Tracked	Commit format
CodeRaven	795	master	1,962	feat(experts):
Peregrine	154	main	901	feat(vigilance):
NoteSparrow	75	main	824	feat(mobile):
VentureRaven	40	master	1,607	fix(commands):
PressRaven	24	master	101	feat(export):
Drive Corps	2	main	123	Initial commit:

Every one of the five uses Conventional Commits. Drive Corps is the only project that doesn't.

What I got right

	Decision	Evidence it matches
match	`.xcodeproj` ignored, `project.yml` is truth	Peregrine is the only other XcodeGen project and tracks 0 pbxproj files
match	Generated `Data/` and `signs/` tracked	Peregrine tracks `pipeline/generated/` — 11 files, same rationale
match	`.gitignore` with commented sections explaining why	Peregrine's is written the same way, down to the prose rationale
match	Python venv excluded	Peregrine ignores `pipeline/.venv/`

What doesn't match

deviation 1. Commit format and granularity

House style is a Conventional Commit subject followed by a short bullet body:

feat(vigilance): add Launch Deck, actionable clock, and device-local telemetry

- Add LaunchDeckView + LaunchDeckOrder session-ordering logic with unit and UI tests
- Add ActionableClock component and wire the two-tempo clock through game views
- Add PeregrineCore Telemetry — unattributed, device-local only, no network path

Mine used Initial commit: … with multi-paragraph prose under section headings. Worse, the granularity is off by two orders of magnitude: the asset pipeline, design system, data layer, two complete games, a font migration and an abort flow are all in one commit. Peregrine would have made roughly fifteen.

deviation 2. Ten loose files at the repo root

Drive Corps root today

Drive-Corps-App-Icon-1024.jpg
Intercept-Background.jpg
Recon-Sweep-Background.jpg
Transmission-Complete.png
Transmission-Lost.png
warning-signs.pdf
regulatory-signs.pdf
dmv_practice_test.json
drive-corps-handoff-v1.md
project.yml
README.md

Peregrine root

docs/
Image-Assets/
pipeline/
Peregrine/
PeregrineCore/
PeregrineUITests/
project.yml
README.md

Art masters, source PDFs, the question bank and the spec are all dumped at top level. Peregrine and NoteSparrow both keep art in a named directory (Image-Assets/, Image-Files/) and pipeline inputs inside the pipeline.

deviation 3. No `docs/` directory

All three iOS peers have one. Peregrine's holds flowmaps/ meetings/ mockups/ playtests/ reviews/ plus every spec markdown file. Drive Corps has no docs/ at all, and drive-corps-handoff-v1.md — the document the whole app was built from — sits loose at the root.

This audit is the first file in the new docs/reviews/, matching the convention your global instructions already assume exists.

deviation 4. Pipeline layout and missing `requirements.txt`

Peregrine keeps everything pipeline-related together — pipeline/scripts/, pipeline/pdfs/, pipeline/generated/, its own README.md, and a requirements.txt. Drive Corps splits this: tools/ at root, .venv/ at root, and the dependency list written as prose inside the main README rather than a file pip install -r can read.

Proposed target structure

Drive Corps/
  README.md
  project.yml
  docs/
    drive-corps-handoff-v1.md      ← moved from root
    reviews/                       ← this audit lives here
  Image-Assets/                    ← the 5 art masters, moved from root
  pipeline/
    README.md                      ← new: how to regenerate
    requirements.txt               ← new: pillow, numpy, scipy, fonttools
    .venv/                         (ignored)
    pdfs/                          ← the 2 sign PDFs, moved from root
    scripts/                       ← the 5 .py files, moved from tools/
    sign_manifest.json
    dmv_practice_test.json         ← moved from root
  Sources/  Tests/
  Data/  signs/  Resources/        (generated, tracked)

Root goes from eleven loose files to two.

One thing worth NOT copying

Peregrine does not track pipeline/pdfs/. I'd keep tracking ours: the two NCDMV PDFs are 144 KB combined and are the literal source of truth for all 54 signs — losing them breaks reproducibility for a rounding error of repo size. Peregrine's are presumably far larger. Worth a deliberate divergence rather than cargo-culting.

What this doesn't fix

Reorganizing files is cosmetic next to the real gap: there is still no pre-commit hook enforcing that Data/ and signs/ match their sources. A hand-edit to Data/signs.json would commit cleanly today while silently diverging from sign_manifest.json. That invariant is documented, not enforced — and it's the one that actually protects the corpus.