Ln 56 Architecture Auditor

3. Audit Contracts and Dependencies

• Inspect public API, service, event, command, and persistence boundaries for stable input/output models plus explicit error, nullability, idempotency, and compatibility contracts.
• Check whether shared entity or framework types, missing boundary models, boolean modes, excessive parameters, unstable serialization, or naming drift create coupling or contract ambiguity; do not demand DTOs where a shared model is an intentional stable contract.
• Build module or package dependency direction using resolved internal edges; account for aliases, re-exports, generated code, reflection, registries, plugins, and runtime loading before declaring an edge absent.
• Apply configured forbidden/allowed dependency rules first; if rules are only inferred, report the inferred model and confidence instead of presenting it as policy.
• Identify forbidden imports, cycles, unstable dependency direction, excessive fan-in/fan-out, and isolated islands; use structural metrics to locate candidates, then apply the consequence check below.
• Trace cycle and coupling findings to concrete effects on change radius, initialization, testing, deployment, ownership, or failure propagation.
• Check that producers and consumers agree on event names, schemas, versions, delivery semantics, ordering, and registration.
• Check physical structure for domain cohesion, framework placement, junk drawers, duplicate module roots, orphan packages, and files whose location hides ownership.
• Check configuration boundaries for typed settings, composition-root ownership, precedence and override semantics, startup validation, scattered environment reads, secret ownership, and leakage into domain behavior.
• Verify runtime discovery: routes, handlers, jobs, commands, plugins, middleware, serializers, and dependency bindings must be registered and reachable.

4. Evaluate Evolution and Alternatives

• Identify current architecture pain using repository evidence: repeated change sets, fragile tests, broad blast radius, duplicate mechanisms, release coupling, or incident-prone ownership.
• If a system-design baseline exists, verify its source and freshness, then compare confirmed constraints with actual behavior.
• If a prior audit baseline exists, compare new, resolved, and retained findings; continue to report accepted or retained risks when their impact remains material.
• Research external pattern or framework behavior only when it can confirm a capability, limitation, lifecycle rule, or supported simplification.
• Compare the current shape with the simplest credible alternative, including migration risk, compatibility, rollback, team impact, and operational cost.
• Prefer incremental boundary repair when a rewrite or new pattern would create more transitional complexity than it removes.
• Reject recommendations that require speculative scale, unsupported future variants, or replacement of working conventions without a demonstrated defect.
• Include a migration sequence only when the recommendation cannot be applied safely as one bounded change.

5. Validate Findings and Report

• Verify structural findings through at least one dependency path, call path, registration path, public contract, or reproducible analysis result.
• Filter generated code, framework conventions, deliberate adapters, test-only architecture, and documented exceptions before confirming a violation.
• Apply the materiality gate: require concrete correctness, security, ownership, deployment, change amplification, or recurring maintenance impact at evidenced scale. Reject taste, theoretical purity, generic practice, hypothetical scale, and reasonable alternatives; require the outcome or constraint, not a preferred implementation.
• External correction evidence: Ground external corrections in version-matched official contracts, using primary engineering sources for unresolved tradeoffs. Cite the supported mechanism; local evidence suffices for local defects.
• Link each accepted boundary finding to the violated driver or contract and the smallest independently verifiable remediation scope; distinguish architectural proposals from accepted decisions.
• Classify findings as P0-P3 based on correctness, security, change amplification, deployment coupling, and recurring maintenance cost.
• Order recommendations by prerequisite and risk reduction, separating immediate correctness fixes from optional evolution.
• Use BLOCKED when required runtime wiring, boundary evidence, or an authoritative contract cannot be verified without a credible fallback; use FAIL for an evidenced unresolved correctness or security boundary defect, unsafe ownership ambiguity, or P0/P1 structural risk; use CONCERNS only for material non-blocking change amplification, and PASS only when no evidenced architecture defect creates material cost or risk.

Self-Check

• Reconcile before returning. Check item-level evidence, requirement coverage, contradictions, scope, verdict, and applicable cleanup. Correct the report or authorized artifacts. Reuse valid evidence; do not automatically rescan the repository or rerun successful commands. Repeat checks only for relevant changes, failures, or unresolved evidence. Disclose remaining gaps.

Output Contract

Report in the user's language, in this order; label all five fields and state each fact once. Use controlled plain language: one fact per sentence, usually under 20 words, active voice, and one term per concept, with no synonyms for verdicts, IDs, or states. Small results may use one line per field; omit empty tables and do not copy linked artifacts:

1. Result: The exact skill-specific verdict token first, then the supported outcome.
2. Scope: Reviewed/changed scope, exclusions, baseline, and material assumptions.
3. Evidence: Skill-specific fields below; distinguish facts, inferences, and unverified claims. Link artifacts; use tables when useful.
4. Verification: Checks/results, unavailable evidence, and applicable cleanup/external state.
5. Completion: Checklist: X/Y complete; Incomplete: None or each UNPROVEN item's reason, outcome impact, and exact next action; residual risks and required decisions.

Skill-specific evidence: Actual modules, boundaries, wiring, dependencies, configuration, and critical flows; distinguish current, target, transition, and drift. Findings need priority, affected boundary, evidence, consequence at current scale, unacceptable tradeoff, migration risk, and smallest safe next step; allow equivalent target shapes. Order evolution by prerequisites and preserve accepted exceptions.