Validate Architecture

validate-architecture -- Architecture Layer Violation Detection

Corresponding rule: architecture.md

Purpose

Statically detect inter-layer import rule violations and circular references in a project. If CLAUDE.md defines an architecture, use that layer definition; otherwise default to the general 3-layer model (presentation/business/data access).

Input -- Dynamic Target Resolution

Resolve target directories in this order:

1. CLAUDE.md "Project Structure" section -- extract source code directories
2. If CLAUDE.md is missing or has no structure info: Glob source files (**/*.{ts,tsx,js,jsx,py,java,go,rs}) -- use the top-level directory containing matched files
3. If no source files are found: report status as SHALLOW and state the reason

Default exclusions: node_modules/, .git/, dist/, build/, coverage/ Skill-specific exclusions: *.test.*, *.spec.*, test_*, *_test.*

Mandatory Output: Target Resolution Result

Output the following before proceeding with validation. Do not advance until resolution is complete.

Execution Logic

1. Read the architecture definition from CLAUDE.md

   • Use Read to read the project root CLAUDE.md
   • If an Architecture section exists, use its layer structure and dependency direction as the baseline
   • If no Architecture section exists, default to the general 3-layer model:
     • Presentation (presentation, ui, pages, components, views, routes, handlers)
     • Business (domain, core, application, services, use-cases, usecases)
     • Data access (infrastructure, infra, repositories, external, adapters, gateways)
   • Dependency direction: presentation -> business <- data access. The business layer must not depend on other layers.

2. Collect source files

   • Use Glob to collect files matching src/**/*.{ts,tsx,js,jsx,py,java}
   • Exclude test files (*.test.*, *.spec.*, test_*, *_test.*)

3. Collect import/from statements

   • Use Grep to extract import statements from each file
   • Patterns: import .* from, from .* import, require(, @import

4. Detect layer violation patterns

   • domain/core -> infrastructure/infra imports (business depends on data access)
   • domain/core -> presentation/ui/pages/components imports (business depends on presentation)
   • presentation -> direct DB imports: the presentation layer directly imports DB-related packages (sqlalchemy, prisma, typeorm, drizzle, mongoose, sequelize, knex, pg, mysql, sqlite, etc.)

5. Detect circular references

   • Detect patterns where module A imports module B while module B also imports module A
   • Check bidirectional imports at the file level

Mandatory Output: Architecture Validation Matrix

Output the matrix below before generating the final report. Do not proceed until every check has been performed.

Status values: PASS (verification complete, no issues), NOT_APPLICABLE (no source files), SKIPPED (plugin issue), SHALLOW (target resolution failed)

Pre-Output Checklist (Mandatory Before Final Output)

Check every item before writing the report. If any item is unchecked, go back and complete it.

• Every check item has a Status value (no empty Status cells)
• Every check with Status != SKIPPED has an Evidence value
• Architecture basis (CLAUDE.md or general 3-layer) is identified and stated
• All 4 violation-pattern checks performed
• Circular-reference check performed
• Report language matches the user's conversation language

Schema Compliance Check (Mandatory Before Saving to .ww-w-ai/)

Before writing to .ww-w-ai/devtools/validate-architecture/, verify the JSON output:

• Every "required" field in schema.json is present and non-empty
• The findings[] array contains every detected violation
• summary counts match the actual finding count

Output

Generate the validation report in the user's conversation language.

Output violations as a Markdown table in this format:

===== Architecture Validation Report =====

[Architecture basis]: CLAUDE.md definition / General 3-layer

| File | Violation | Severity |
|------|-----------|----------|
| `src/domain/user.ts` | Infrastructure layer import (`../../infra/db`) | ERROR |
| `src/core/order.ts` | Presentation layer import (`../../pages/OrderView`) | ERROR |
| `src/pages/Dashboard.tsx` | Direct DB import (`prisma`) | ERROR |
| `src/services/auth.ts` <-> `src/services/user.ts` | Circular reference | WARN |

Total violations: {N} (ERROR: {E}, WARN: {W})
====================================

When there are no violations:

===== Architecture Validation Report =====

[Architecture basis]: CLAUDE.md definition / General 3-layer

No violations.
====================================

Severity Criteria

Output Persistence

After generating the architecture validation report, save results to .ww-w-ai/devtools/validate-architecture/:

1. Create .ww-w-ai/devtools/validate-architecture/ if missing
2. Write latest.json -- structured result following templates/schema.json
3. Write latest.md -- human-readable report following templates/report.template.md
4. Archive to history/ -- copy latest.json to .ww-w-ai/devtools/validate-architecture/history/{timestamp}.json

latest.md is generated in the user's conversation language. JSON field names stay in English regardless of language. The JSON output enables machine-parseable history tracking and cross-run comparison. The history/ directory preserves previous executions for trend analysis.

Permission Rationale

• Write: Exclusively for .ww-w-ai/ output persistence. No project source modification.
• Bash: Exclusively for read-only git/system queries. No file modifications.

Notes

• Bash is permitted for directory creation (mkdir -p .ww-w-ai/devtools/validate-architecture/history). The validation itself is read-only and does not modify project files.
• Test files (*.test.*, *.spec.*) are excluded from inspection (per testing.md exceptions, internal access inside tests is permitted).
• If CLAUDE.md defines an architecture, that definition takes precedence over the general principles.
• Layer directory naming may differ per project, so CLAUDE.md definitions take highest precedence.

Spec Reference

For detailed validation criteria, evidence tables, and examples:

• Corresponding rule spec: ../../docs/specs/architecture.md