review-architecture-boundaries

name	review-architecture-boundaries
description	Review code and contracts for clean architecture boundary violations. Use when Codex needs a structured boundary review and, only when explicit gate inputs are provided, a gate decision about dependency direction, layer leakage, port-adapter separation, DTO leakage, framework leakage, or forbidden imports after implementation or refactoring. Do not use to design the architecture from scratch.

Review Architecture Boundaries

Goal

Evaluate whether the current code and contracts still respect clean architecture boundaries and dependency rules.

Read Shared Contract Reference before reviewing scope.

Trigger boundary

• Use to review existing code, contracts, or diffs against an existing architecture baseline.
• Do not use to invent the architecture or redesign modules from scratch.

Required input

• Required: architecture rules or clean architecture baseline
• Required: relevant code diff, codebase area, or module map
• Optional: relevant contracts when they influence boundary placement
• Optional gate inputs: acceptance_criteria, blocking_rules, required_invariants, expected_layer_model, forbidden_dependencies, review_scope

Refusal and blocked policy

• Focus on structural violations, not style preferences.
• Cite file, module, or dependency evidence for every violation.
• Review both direct leakage and indirect boundary erosion.
• Prefer actionable fixes over vague warnings.
• Return BLOCKED in gate mode when the architecture baseline or required gate inputs are missing.
• If gate inputs are absent, produce a structured review report and do not invent PASS | WARN | FAIL.

Workflow

1. Identify the expected layer model and dependency direction.
2. Inspect code, contracts, and module relationships against that model.
3. Find framework leakage into domain or use-case layers.
4. Find inverted dependencies, adapter misuse, DTO leakage, and forbidden imports.
5. Classify issues as blocking or non-blocking and state required fixes.
6. Produce a gate-style decision only when explicit gate inputs are provided.

Output contract

Use one of these output modes.

Review mode

Write architecture-boundary-review.md or return equivalent Markdown when explicit gate inputs are absent:

# Architecture Boundary Review

## Artifact Metadata
- artifact_id:
- artifact_type: review
- artifact_status: current | superseded
- approval_status: pending_review | approved | changes_required | rejected
- approved_by_gate_profile: none
- gate_report_ref: none | <ref>
- upstream_artifact_refs:

## Reviewed Scope
- ...

## Blocking Violations
- issue_id: ISSUE-*
- rule_id: RULE-*
- category: dependency_inversion | framework_leakage | dto_leakage | adapter_misuse | forbidden_dependency
- location:
- evidence_source:
- evidence_excerpt_or_reference:
- impact:
- required_fix:

## Non-Blocking Issues
- issue_id: ISSUE-*
- rule_id: RULE-*
- category:
- location:
- evidence_source:
- evidence_excerpt_or_reference:
- impact:

## Recommendation
- boundary_safe_to_merge: yes | no
- next_action:

Gate mode

Write architecture-boundary-review.yaml or return equivalent YAML only when explicit gate inputs are present:

artifact_metadata:
  artifact_id: ""
  artifact_type: gate-report
  artifact_status: current | superseded
  approval_status: approved | changes_required | rejected | pending_review
  approved_by_gate_profile: architecture-boundaries
  gate_report_ref: self
  upstream_artifact_refs:
    - ""
stage: review-architecture-boundaries
gate_profile: architecture-boundaries
decision: PASS | WARN | FAIL | BLOCKED
decision_rationale: ""
summary: ""
blocking_violations:
  - issue_id: ""
    rule_id: ""
    category: ""
    location: ""
    evidence_source: ""
    evidence_excerpt_or_reference: ""
    impact: ""
non_blocking_issues:
  - issue_id: ""
    rule_id: ""
    category: ""
    location: ""
    issue: ""
    evidence_source: ""
    evidence_excerpt_or_reference: ""
    impact: ""
required_fixes:
  - ""
approved_artifacts:
  - ""
artifact_metadata_updates:
  - artifact_ref: ""
    artifact_status: current | superseded
    approval_status: approved | changes_required | rejected | pending_review
    approved_by_gate_profile: ""
    gate_report_ref: ""
next_step_allowed: true

Quality bar

• Use FAIL for violations that break dependency direction or leak infrastructure into the core.
• Keep evidence concrete enough for a developer to reproduce the finding quickly.
• Avoid broad rewrite advice unless the violation truly spans the design.
• Leave PASS only when the reviewed scope is structurally sound.
• Never emit gate decisions without explicit gate inputs and a known baseline.
• Keep review and gate artifacts on the same metadata contract as the rest of the system.