Repair Replit-agent drift: restore module doctrine, metadata contracts, and GitHub-first change discipline

[erinepshovel-code]

hmmm

Replit agent is no longer the primary driver of a0 change. Treat Replit/a0p as runtime and preview surface only. GitHub is source of truth. Repair changes that appear hallucinated, under-specified, or mechanically inconsistent with module doctrine.

Goal

Stabilize a0 after Replit-agent drift by auditing and repairing the module metadata substrate, route registration, annotation parser, and doctrine compliance without broad rewrites.

Prime doctrine

• No breakage.
• No retreat.
• Changes inevitable.
• Welcome refinement.
• Runtime is not authority.
• Deployment is not authorship.
• The running instrument may reveal pressure.
• The repository records decision.

Required context files

Read before editing:

1. .agents/skills/a0p-module-doctrine/SKILL.md
2. README.md
3. python/routes/__init__.py
4. scripts/annotate.py
5. python/tests/contracts/route_gating.py
6. python/tests/contracts/gating.py

Main repair areas

1. Annotation parser drift

Doctrine says first AND last line of every .py, .ts, .tsx file must be annotation comments carrying three metric pairs:

# N:M C:D I:O
// N:M C:D I:O

But collect_doc_meta() appears to parse only the older/simple first-line form. Repair parser logic so it accepts full three-pair annotations and exposes all six values where docs metadata is returned:

• code_lines
• comment_lines
• consumed_count
• declared_count
• fan_in
• fan_out

Do not break old two-number annotations during transition; parse both.

2. Role metadata adoption

Doctrine now requires:

# DOC role: route

Audit route files and add appropriate roles from the allowed list:

• route
• api
• service
• engine
• orchestrator
• schema
• component
• page
• test
• contract
• doctrine
• config
• script
• adapter
• hot_swap
• module

For existing route files, likely defaults:

• {name}.py self-contained routes -> route
• {name}_api.py thin delegates -> api
• docs/contracts/gating tests -> contract where applicable

Do not invent new roles without updating the skill doctrine first.

3. Module metadata contract tests

Add or extend tests to verify:

• every registered route file has a # DOC block
• every # DOC block has module, label, description, tier, role
• role is in the allowed list
• UI_META.tab_id matches # DOC module when UI_META exists
• DATA_SCHEMA.endpoints do not contradict # DOC endpoint entries
• modules in ALL_ROUTERS are represented in collect_doc_meta() where appropriate
• modules with UI_META are represented in collect_ui_meta()
• first-line and last-line annotations both exist for .py, .ts, .tsx files, at least for files touched by this repair

4. Four-place registration drift

Current doctrine requires new route modules be registered in four places in python/routes/__init__.py:

1. import
2. ALL_ROUTERS
3. collect_doc_meta() file list
4. collect_ui_meta() module list, if it has UI_META

Audit for drift. Fix missing registrations. Do not rewrite to full auto-discovery unless small and safe. Prefer contract coverage first.

5. Replit hallucination audit

Search for signs of brittle or hallucinated edits:

• dead UI_META entries
• empty or contradictory DATA_SCHEMA
• route files mounted but undocumented
• docs metadata claiming endpoints that do not exist
• endpoints that exist but are absent from DOC block
• modules with tier/client gating mismatch
• files exceeding 400 code-line budget after annotation
• placeholder logic that returns fake success
• runtime-only assumptions that should be config/env driven

Do not perform cosmetic rewrites. Repair only clear contradictions or add issues/TODOs where behavior is ambiguous.

Constraints

• Preserve current public behavior unless a clear bug is found.
• No broad architecture rewrites.
• No Replit-specific runtime state as authority.
• Keep changes small and reviewable.
• Run annotator after edits.
• Tests must pass.

Validation commands

Run, at minimum:

python scripts/annotate.py
python3 -m pytest python/tests/contracts/route_gating.py python/tests/contracts/gating.py -v
python3 -m pytest python/tests/contracts -v || true
npm run check

If full contract suite needs live services/Postgres and cannot run, state that clearly in PR notes.

Deliverables

1. Small PR or commit series titled around module doctrine repair.
2. Summary of each drift found and fixed.
3. List of remaining hmmm items that need human decision.
4. No runtime deploy claim unless deployment actually happened.

GPT generated; context, prompt Erin Spencer.