migrate.audit

Custom agent imported from Rakurai/legacy-evennia (.github/agents/migrate.audit.agent.md). Copyright stays with the author.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Audit implemented code across multiple specs for cross-system consistency problems that only appear when looking at separately-developed subsystems together.

Context

Read these to understand the system architecture and coding standards:

• docs/architecture/ARCHITECTURE.md -- structural invariants, handler rules, boundaries
• docs/architecture/DESIGN_PRINCIPLES.md -- design reasoning and principles
• docs/architecture/PATTERNS.md -- approved patterns and antipatterns
• docs/architecture/CODE_SHAPING_RULES.md -- implementation shape rules
• docs/CURRENT_DEVIATIONS.md -- known tolerated violations (do not re-flag these)
• docs/evennia_guides/EVENNIA_MODEL.md -- framework conceptual architecture
• docs/evennia_guides/EVENNIA_CODING.md -- framework implementation patterns

This command performs adversarial architectural conformance testing, not descriptive review. Your job is to find violations, not describe what was built. Every finding must cite a specific architectural rule and provide file:line evidence.

Procedure

1. If the user specified subsystems in their input, scope the audit to those. Otherwise, audit all implemented specs.

2. Check if migration/audits/cross-audit.md exists. If it does, load it to see what was previously audited and at what git revision.

3. Identify which specs have implementation changes since the last audit (compare current git revisions of implementation branches).

4. If no specs have changed since the last audit, report that and stop.

5. For each changed spec, load its requirements document from migration/requirements/{subsystem}.md and scan the implementation code in legacy/.

6. Run the automated conformance script first:

   bash scripts/dev/conformance_check.sh

   Record whether it passes or fails. If it fails, include the output.

7. Audit across subsystem boundaries for:

   • Interface mismatches -- implementations don't match prescribed interface contracts from requirements documents
   • Naming inconsistencies -- same concept named differently across subsystems
   • Data flow conflicts -- incompatible Attribute key formats, Tag conventions, or handler protocols between subsystems
   • Import violations -- domain logic leaking into integration layer or vice versa
   • Communication pattern violations -- custom event buses instead of direct calls / hooks / signals

8. Adversarial architectural conformance checks -- for each, answer with file:line evidence and explicit PASS/FAIL:

   a. Handler namespace ownership (ARCHITECTURE.md §4): Does every handler use its own attr_category? Does any code write Attributes outside the owning handler's namespace?

   b. Layer boundary (CODE_SHAPING_RULES.md §6): Does any game/ file (excluding messages.py) call msg() or game_act()? Are commands and hooks thin orchestrators?

   c. Single canonical write point (CODE_SHAPING_RULES.md §10): Does any piece of persistent state have more than one write path?

   d. Stat pipeline (ARCHITECTURE.md §8.1): Are all modifier-eligible stats read through stats.get()?

   e. Wait state (ARCHITECTURE.md §7.4): Is ndb.wait_until the only command wait mechanism?

   f. Stub discipline (CODE_SHAPING_RULES.md §4): Are all stubs properly marked? Has the stub count changed? Are any correctness-affecting?

9. Append findings to migration/audits/cross-audit.md using this format:

   ## Audit: [DATE]
   
   ### Specs Audited
   - [spec-name] at [git rev]
   
   ### Findings
   
   #### [SHORT TITLE]
   - **Type:** interface-mismatch | naming | data-flow | import | protocol
   - **Severity:** critical | warning
   - **Files:** [file1:line], [file2:line]
   - **Detail:** [exact description with code quotes]
   - **Recommendation:** [what should change]

   If no issues found, record "No cross-system issues found."

   Include a Conformance Summary table:

   ### Conformance Summary
   
   | Check | Result | Violations |
   |-------|--------|------------|
   | Handler namespace | PASS/FAIL | N |
   | Layer boundary | PASS/FAIL | N |
   | Single write point | PASS/FAIL | N |
   | Stat pipeline | PASS/FAIL | N |
   | Wait state | PASS/FAIL | N |
   | Stub discipline | PASS/FAIL | N |

10. Summarize findings:

• Number of issues (critical vs. warning)
• Which subsystem boundaries have problems
• Recommended remediation priority

11. If critical issues were found, ask the user whether to address them now or track them for later.

12. Check for doc-code drift: spot-check 3 examples from ARCHITECTURE.md and PATTERNS.md against the actual codebase. Report any doc examples that no longer match reality.