@accelerationguy/accel 1.0.0

package/modules/radar/src/core/workflows/session-handoff.md

@@ -0,0 +1,152 @@
+<purpose>
+Manages the transfer of context between agent sessions — persisting findings, disagreements, and state after each session completes, and assembling the input context for the next session to begin.
+</purpose>
+
+<phase_context>
+Phase: Utility — invoked at every session boundary across all Radar Core phases (0-5)
+Prior phase output: Varies by phase — each agent session produces findings, disagreements, and updated state
+Agents invoked: None directly — this workflow is invoked BY phase orchestration workflows after each agent session completes
+Output: Validated session artifacts in .radar/, updated .radar/STATE.md, assembled context bundle for next session
+</phase_context>
+
+<required_input>
+@.radar/STATE.md
+@.radar/MANIFEST.md
+@~/.claude/radar/schemas/finding.md
+@~/.claude/radar/schemas/disagreement.md
+@~/.claude/radar/schemas/confidence.md
+@~/.claude/radar/schemas/signal.md
+@~/.claude/radar/core/agents/{agent-id}.md (the agent that just completed)
+</required_input>
+
+<process>
+
+<step name="capture_session_output" priority="first">
+1. Identify the agent that just completed its session from .radar/STATE.md current_agent field.
+2. Collect all output artifacts from the completed session:
+   a. Finding files — structured per src/schemas/finding.md
+   b. Disagreement records — structured per src/schemas/disagreement.md
+   c. Any partial report sections (Phase 5 only) — per src/schemas/report-section.md
+3. Assign unique IDs to any findings or disagreements that lack them:
+   - Findings: F-{DD}-{NNN} where DD is the domain number and NNN is sequential
+   - Disagreements: D-{NNN} where NNN is sequential across the audit
+4. Tag each artifact with session metadata:
+   - agent_id: which agent produced it
+   - phase: which Radar phase this was produced in
+   - timestamp: session completion time
+</step>
+
+<step name="validate_against_schemas" priority="blocking">
+1. For each finding produced:
+   a. Validate all 7 epistemic layers are present per src/schemas/finding.md
+   b. Validate confidence vector has all 4 dimensions per src/schemas/confidence.md
+   c. Verify severity rating is justified by evidence (not asserted without support)
+   d. Check that domain_id matches one of the producing agent's declared domains
+2. For each disagreement record:
+   a. Validate structure per src/schemas/disagreement.md
+   b. Verify both positions reference valid finding IDs
+   c. Verify root_cause_taxonomy uses valid categories
+3. Record validation results:
+   - VALID: artifact passes all checks
+   - INVALID: artifact fails — log specific field-level errors
+4. For INVALID artifacts:
+   a. If the originating session is still available: return to agent with errors for correction
+   b. If the originating session has ended: flag as "unvalidated" in .radar/STATE.md and mark for manual review
+   c. Do not write invalid artifacts to the canonical .radar/ directory
+</step>
+
+<step name="persist_to_radar_directory" priority="blocking">
+1. Write validated findings to .radar/findings/{agent-id}.md:
+   - One file per agent containing all findings from that session
+   - Append to existing file if agent has run in multiple phases
+   - Preserve finding IDs for cross-reference stability
+2. Write disagreement records to .radar/disagreements/{disagreement-id}.md:
+   - One file per disagreement for independent tracking
+3. Update .radar/signals/ if the session produced normalized signal data (Phase 1 only):
+   - One file per tool: .radar/signals/{tool-id}.md
+4. Verify all writes completed:
+   - Confirm file existence
+   - Confirm file is non-empty
+   - Confirm no write errors
+</step>
+
+<step name="update_state" priority="blocking">
+1. Update .radar/STATE.md with:
+   a. Session completion record:
+      - agent_id, phase, timestamp, status (complete/partial/failed)
+   b. Artifact counts:
+      - findings_produced: N
+      - findings_validated: N
+      - findings_invalid: N
+      - disagreements_produced: N
+   c. Phase progress:
+      - agents_completed: N of M for current phase
+      - agents_remaining: list of agent IDs not yet run in this phase
+   d. Next session:
+      - next_agent_id (or "phase_complete" if all agents in phase have run)
+2. If all agents in the current phase have completed:
+   a. Mark phase as complete in .radar/STATE.md
+   b. Set phase_status to "complete"
+   c. Record phase-level metrics (total findings, total disagreements, domain coverage)
+</step>
+
+<step name="assemble_next_context" priority="blocking">
+1. If next_agent_id is set (another agent runs in this phase or next phase):
+   a. Read the next agent's manifest from src/core/agents/{next-agent-id}.md
+   b. Resolve component references:
+      - Load persona from src/core/personas/{persona-id}.md
+      - Load domains from src/domains/{DD}-*.md for each domain in the manifest
+      - Load schemas from src/schemas/{schema-id}.md for each declared schema
+      - Load rules from src/rules/{rule-id}.md for each declared rule
+   c. Collect input signals:
+      - For Phase 2+ agents: load .radar/signals/{tool-id}.md for each tool in the manifest
+      - For Phase 3+ agents: load .radar/findings/ from prior phases for declared domains
+      - For Phase 4 (Devil's Advocate): load ALL .radar/findings/ and .radar/disagreements/
+      - For Phase 5 (Principal Engineer): load complete .radar/ analytical record
+   d. Include session context from the agent manifest's "Session Context" section
+   e. Include .radar/STATE.md for audit position awareness
+2. Bundle into a context package:
+   - Ordered by priority: persona first, then rules, then domains, then signals/findings
+   - Include a context manifest listing all loaded files and their roles
+3. Verify context fits within session budget:
+   - Estimate token count of assembled context
+   - If exceeding budget: prioritize by agent manifest's declared dependencies
+   - Log any context that was trimmed due to budget constraints
+</step>
+
+<step name="handle_interrupted_session" priority="optional">
+1. If a session ended without producing complete output:
+   a. Check for partial artifacts (incomplete findings, draft disagreements)
+   b. If partial artifacts exist:
+      - Validate whatever is complete
+      - Mark incomplete fields in .radar/STATE.md
+      - Flag session as "interrupted" with resume point
+   c. If no artifacts exist:
+      - Mark session as "failed" in .radar/STATE.md
+      - Do not block phase progression — record the gap
+2. To resume an interrupted session:
+   a. Reload the same context bundle that was prepared for the original session
+   b. Include .radar/STATE.md showing the interruption point
+   c. Include any partial artifacts that were saved
+   d. Set resume_from field so the agent knows where to continue
+</step>
+
+</process>
+
+<output>
+Artifacts created or updated per invocation:
+- .radar/findings/{agent-id}.md — Validated finding set from completed session
+- .radar/disagreements/{disagreement-id}.md — Disagreement records (if any)
+- .radar/signals/{tool-id}.md — Normalized signals (Phase 1 sessions only)
+- .radar/STATE.md — Updated with session completion, metrics, and next agent
+- Context bundle — Assembled input for the next agent session (in-memory, not persisted as a file)
+</output>
+
+<error_handling>
+- **Session timeout (no output):** Mark session as "failed" in .radar/STATE.md. Record which agent and phase. Allow phase to continue with remaining agents but log coverage gap. Do not retry automatically — present to user for decision.
+- **Partial output (some findings valid, some invalid):** Accept valid findings. Quarantine invalid findings in .radar/quarantine/{agent-id}-{timestamp}.md with validation errors. Update STATE.md with partial completion status. Allow phase to continue.
+- **Schema validation failure (all output invalid):** Do not persist any artifacts. Mark session as "validation-failed" in STATE.md. Return full error report to user. Agent must re-run with corrected output before phase can complete.
+- **State file corruption (.radar/STATE.md unreadable):** Halt workflow. Attempt reconstruction from .radar/findings/ and .radar/disagreements/ file timestamps. Present reconstructed state to user for confirmation before proceeding.
+- **Context budget exceeded (next session too large):** Log which components were trimmed. Prioritize: persona > rules > primary domain > signals > prior findings > secondary domains. Never trim persona or rules — these are non-negotiable. If persona + rules alone exceed budget, the audit configuration must be revised.
+- **Write failure (disk/permission error):** Halt immediately. Do not proceed to next session. Present error with full path and permission details. Session artifacts exist only in memory until successfully written.
+</error_handling>

package/modules/radar/src/domains/00-context.md

@@ -0,0 +1,201 @@
+---
+id: domain-00
+number: "00"
+name: Context & Intent
+owner_agents: [principal-engineer]
+---
+
+## Overview
+
+Covers the foundational understanding of what the system is, why it exists, who uses it, and under what constraints it operates. Context & Intent must come first in every audit — without establishing what the system is supposed to do, every other domain is partially blind. Findings in architecture, security, or performance have no severity anchor without knowing the system's business criticality, deployment model, and operational expectations.
+
+Scope: system purpose, stakeholder expectations, deployment context, architectural intent, regulatory environment, data sensitivity classification, and operational constraints. Does NOT cover implementation details — those belong to domains 01-12. Does NOT produce technical findings — it produces the lens through which all other findings are interpreted.
+
+## Audit Questions
+
+- What problem is this system solving, and for whom?
+- Who are the primary users, and what are their expectations for reliability and performance?
+- What is the business criticality of this system (revenue-generating, cost-saving, compliance-required, internal tooling)?
+- What is the deployment model (cloud, on-premise, hybrid, edge)?
+- What regulatory or compliance requirements apply (GDPR, HIPAA, SOC 2, PCI-DSS, none)?
+- What are the expected load patterns (steady, bursty, seasonal, event-driven)?
+- What data does the system handle, and what is its sensitivity classification?
+- What are the known integration points with external systems?
+- What is explicitly out of scope for this system?
+- Are there documented architectural decisions, and do they reflect current reality?
+- What is the team size and composition maintaining this system?
+- What are the known constraints (budget, timeline, team expertise, legacy dependencies)?
+
+## Failure Patterns
+
+### Missing System Context
+
+- **Description:** No documentation exists describing what the system does, why it exists, or who it serves. Engineers must reverse-engineer purpose from code.
+- **Indicators:**
+  - No README or README contains only setup instructions without purpose statement
+  - No architecture decision records (ADRs) or design documents
+  - Onboarding requires synchronous knowledge transfer from specific individuals
+  - Git history is the only source of "why" information
+- **Severity Tendency:** high
+
+### Intent-Implementation Drift
+
+- **Description:** The system's actual behavior has diverged significantly from its documented or originally intended purpose, creating a gap between what stakeholders believe the system does and what it actually does.
+- **Indicators:**
+  - Documentation describes features or behaviors that no longer exist
+  - Significant code paths that serve no current business purpose
+  - Stakeholders describe the system differently than the code implements
+  - Feature flags or configuration permanently set to non-default values
+- **Severity Tendency:** high
+
+### Undocumented Assumptions
+
+- **Description:** Critical assumptions about the operating environment, data characteristics, or user behavior are embedded in code without explicit documentation, creating hidden failure modes when assumptions are violated.
+- **Indicators:**
+  - Hardcoded values without explanatory comments (magic numbers, URLs, thresholds)
+  - Environment-specific behavior without configuration abstraction
+  - Error handling that assumes specific input shapes without validation
+  - Code comments like "this should never happen" or "temporary fix"
+- **Severity Tendency:** medium
+
+### Missing Threat Model
+
+- **Description:** No documented analysis of what could go wrong, who might attack the system, or what the consequences of various failure modes would be.
+- **Indicators:**
+  - No threat modeling artifacts (STRIDE, attack trees, data flow diagrams)
+  - Security controls implemented reactively rather than by design
+  - No classification of data sensitivity levels
+  - No documented trust boundaries between components
+- **Severity Tendency:** high
+
+### Stakeholder Blindness
+
+- **Description:** The system's design does not account for all relevant stakeholders, leading to misaligned priorities and missing requirements.
+- **Indicators:**
+  - No documented stakeholder map or user personas
+  - Operations team not consulted during design (missing observability, deployment concerns)
+  - Compliance requirements discovered late in development
+  - End-user feedback loop absent from development process
+- **Severity Tendency:** medium
+
+### Scope Creep Without Context Update
+
+- **Description:** The system has grown beyond its original scope, but the contextual documentation, constraints, and architectural boundaries have not been updated to reflect the expanded responsibilities.
+- **Indicators:**
+  - System handles concerns far outside its original domain
+  - Multiple teams depend on the system for different, sometimes conflicting purposes
+  - No clear boundary between "core" functionality and "accreted" functionality
+  - Resource allocation still reflects original, smaller scope
+- **Severity Tendency:** medium
+
+## Best Practice Patterns
+
+### System Context Documentation
+
+- **Replaces Failure Pattern:** Missing System Context
+- **Abstract Pattern:** Every system should have a living document that describes its purpose, stakeholders, constraints, and operational context — maintained as a first-class artifact alongside code.
+- **Framework Mappings:**
+  - Arc42: Section 1 (Introduction and Goals) + Section 3 (Context and Scope)
+  - C4 Model: System Context Diagram as the entry point for all architectural understanding
+  - ADR (Architecture Decision Records): Lightweight decision logs capturing "why" alongside "what"
+- **Language Patterns:**
+  - Any: `README.md` with structured sections (Purpose, Users, Deployment, Constraints, Non-Goals)
+  - Any: `docs/architecture/` directory with ADRs using the Nygard format (Title, Status, Context, Decision, Consequences)
+
+### Living Architecture Decision Records
+
+- **Replaces Failure Pattern:** Intent-Implementation Drift
+- **Abstract Pattern:** Architectural decisions are recorded when made and updated when the system evolves, creating a traceable chain from intent to implementation that surfaces drift early.
+- **Framework Mappings:**
+  - MADR (Markdown ADR): Structured decision records with status tracking (proposed, accepted, deprecated, superseded)
+  - Log4brains: ADR tooling that integrates decision records into CI/CD and makes them searchable
+  - Lightweight ADR: Simple markdown files in `docs/decisions/` with sequential numbering
+- **Language Patterns:**
+  - Any: ADR files with explicit "Status" field that gets updated when decisions change
+  - Any: Git commit messages that reference ADR numbers when implementing decisions
+
+### Explicit Assumption Register
+
+- **Replaces Failure Pattern:** Undocumented Assumptions
+- **Abstract Pattern:** Assumptions about the operating environment, data characteristics, and user behavior are captured in an explicit register — each assumption has an owner, a validation method, and a consequence-if-violated statement.
+- **Framework Mappings:**
+  - TOGAF: Architecture Requirements Specification includes explicit assumption documentation
+  - Risk Management (ISO 31000): Assumptions as risk inputs with monitoring criteria
+  - Lean Architecture: Validated assumptions through hypothesis testing
+- **Language Patterns:**
+  - Any: `ASSUMPTIONS.md` or structured section in architecture docs listing each assumption with validation criteria
+  - Any: Code comments using a structured format: `// ASSUMPTION: [statement] | VALIDATED BY: [method] | IF WRONG: [consequence]`
+
+### Threat Model as Code
+
+- **Replaces Failure Pattern:** Missing Threat Model
+- **Abstract Pattern:** Threat modeling is treated as an ongoing, version-controlled activity that evolves with the system, not a one-time exercise.
+- **Framework Mappings:**
+  - STRIDE: Systematic threat categorization (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege)
+  - OWASP Threat Dragon: Visual threat modeling tool that produces version-controllable output
+  - pytm (Python Threat Modeling): Threat models defined as code, producing data flow diagrams and threat lists
+- **Language Patterns:**
+  - Python: `pytm` library for defining system components and data flows as code
+  - Any: YAML/JSON threat model definitions stored alongside architecture docs
+
+### Stakeholder Map
+
+- **Replaces Failure Pattern:** Stakeholder Blindness
+- **Abstract Pattern:** All stakeholders (users, operators, maintainers, compliance, business owners) are explicitly identified with their needs, communication channels, and influence on system design.
+- **Framework Mappings:**
+  - Impact Mapping: Goal → Actors → Impacts → Deliverables tree connecting stakeholders to system features
+  - Wardley Mapping: Value chain positioning that reveals stakeholder dependencies
+  - User Story Mapping: Backbone → Walking Skeleton approach that ensures all user types are represented
+- **Language Patterns:**
+  - Any: `STAKEHOLDERS.md` with categorized stakeholder list (primary users, secondary users, operators, business owners)
+  - Any: User persona documents with specific needs, access patterns, and quality expectations
+
+### Scope Governance
+
+- **Replaces Failure Pattern:** Scope Creep Without Context Update
+- **Abstract Pattern:** System scope is explicitly defined and bounded, with a formal process for expanding scope that requires updating context documentation, resource allocation, and architectural boundaries.
+- **Framework Mappings:**
+  - DDD (Domain-Driven Design): Bounded Contexts with explicit context maps showing relationships between domains
+  - Team Topologies: Stream-aligned teams with clear ownership boundaries that prevent uncontrolled scope expansion
+  - TOGAF: Architecture governance including change management for scope modifications
+- **Language Patterns:**
+  - Any: `SCOPE.md` or scope section in architecture docs with explicit "In Scope" and "Out of Scope" lists
+  - Any: Module boundary enforcement through package visibility, dependency rules, or architectural fitness functions
+
+## Red Flags
+
+- No README, or README contains only "how to install" without "what this is"
+- No architecture documentation of any kind
+- Onboarding requires specific people ("ask Sarah, she knows how it works")
+- No ADRs and no design documents
+- Comments in code that say "I don't know why this is here" or "legacy — don't touch"
+- System handles data types not mentioned in any documentation
+- Multiple conflicting descriptions of the system's purpose from different team members
+- No deployment documentation or runbooks
+- Configuration values that no one can explain the origin of
+- Missing or outdated dependency on external systems not documented anywhere
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| git-history | Commit patterns, authorship concentration, and change frequency reveal implicit intent and knowledge distribution | contextual |
+| sonarqube | Complexity metrics and code smell density hint at areas where intent may be misaligned with implementation | contextual |
+
+## Standards & Frameworks
+
+- ISO 25010 — Software product quality model (defines quality characteristics that context establishes priorities for)
+- TOGAF — Enterprise architecture framework with structured context documentation requirements
+- C4 Model — Hierarchical architecture diagramming (System Context as the outermost view)
+- Arc42 — Architecture documentation template with explicit context and scope sections
+- ISO 31000 — Risk management framework (assumptions as risk inputs)
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| README completeness score | Presence of purpose, users, deployment, constraints, and non-goals sections | 5/5 sections present |
+| ADR count | Number of architecture decision records | ≥1 per major architectural choice |
+| Documentation freshness | Time since last update to architecture/context docs | <6 months |
+| Stakeholder coverage | Number of identified stakeholder types with documented needs | ≥3 stakeholder types |
+| Assumption register size | Number of explicitly documented assumptions | ≥5 for non-trivial systems |

package/modules/radar/src/domains/01-architecture.md

@@ -0,0 +1,248 @@
+---
+id: domain-01
+number: "01"
+name: Architecture & System Design
+owner_agents: [architect]
+---
+
+## Overview
+
+Covers structural patterns, module boundaries, dependency direction, coupling, cohesion, layering, and whether the architecture can support the system's actual requirements. Architecture determines how easy bugs are to introduce, how expensive changes are, and whether scale is possible without rewrites. A well-designed architecture makes the right things easy and the wrong things hard; a poorly designed one does the opposite.
+
+Scope: module responsibilities and boundaries, dependency graphs, layering consistency, coupling and cohesion metrics, API surface design, extensibility points, and adherence to stated architectural patterns. Does NOT cover data model design (domain 02), security boundaries (domain 04), or deployment architecture (domain 10).
+
+## Audit Questions
+
+- Is there a stated architectural pattern (layered, hexagonal, microservices, modular monolith), and does the code follow it?
+- Are module boundaries clearly defined and enforced, or do modules reach into each other's internals?
+- Does dependency direction follow a consistent rule (e.g., inward toward domain, downward through layers)?
+- Are there circular dependencies between modules or packages?
+- Are there "god modules" — modules that know about everything and are imported everywhere?
+- Is domain logic separated from infrastructure concerns (database, HTTP, messaging)?
+- Are API surfaces (internal and external) well-defined with clear contracts?
+- Is there evidence of the "wrong abstraction" — shared code that is harder to understand than duplication would be?
+- Are extensibility points (plugins, hooks, event systems) intentional or accidental?
+- What is the ratio of concrete to abstract dependencies?
+- Are there modules that change together but are structurally separate (hidden coupling)?
+- Is the system's decomposition aligned with its domain boundaries?
+- How deep is the dependency tree, and are there concerning chains?
+
+## Failure Patterns
+
+### Big Ball of Mud
+
+- **Description:** The system lacks discernible architecture. Modules, layers, and boundaries are absent or unenforced, resulting in code where everything depends on everything.
+- **Indicators:**
+  - No clear directory structure reflecting architectural intent
+  - Import graphs show dense, bidirectional connections between most modules
+  - Any change requires touching files across many directories
+  - No team member can draw the system's architecture from memory
+- **Severity Tendency:** critical
+
+### Leaky Abstractions
+
+- **Description:** Module boundaries exist in name but not in practice. Internal implementation details leak through interfaces, creating hidden coupling between components.
+- **Indicators:**
+  - Callers make assumptions about implementation details (database schemas, internal state, ordering)
+  - Interface changes propagate transitively through multiple layers
+  - "Convenience" methods that bypass the intended API surface
+  - Error types from lower layers surface unchanged through upper layers
+- **Severity Tendency:** high
+
+### Circular Dependencies
+
+- **Description:** Two or more modules depend on each other, creating cycles in the dependency graph that prevent independent testing, deployment, and reasoning about each module.
+- **Indicators:**
+  - Import analysis reveals cycles (A imports B, B imports A)
+  - Build order is fragile or requires special configuration
+  - Extracting a module requires bringing its "dependencies" along
+  - Initialization order bugs (module A needs B initialized first, but B needs A)
+- **Severity Tendency:** high
+
+### God Objects / God Modules
+
+- **Description:** A single class, module, or package has accumulated responsibility for too many concerns, becoming a central point of coupling that everything depends on.
+- **Indicators:**
+  - One module with significantly more lines of code than any other
+  - A single file or class imported by >50% of other modules
+  - Module name is generic ("utils", "helpers", "common", "core", "shared")
+  - Changes to this module have high blast radius
+- **Severity Tendency:** high
+
+### Layer Violations
+
+- **Description:** The system has an intended layering (e.g., presentation → business → data), but code routinely bypasses layers, creating shortcuts that undermine the architecture's guarantees.
+- **Indicators:**
+  - UI/controller code directly accessing database queries
+  - Business logic importing HTTP request/response types
+  - Data access layer containing business rules
+  - Configuration or environment variables read deep inside business logic
+- **Severity Tendency:** medium
+
+### Distributed Monolith
+
+- **Description:** The system is deployed as multiple services but exhibits the coupling characteristics of a monolith — services cannot be deployed, tested, or reasoned about independently.
+- **Indicators:**
+  - Services share a database or schema
+  - Deploying one service requires coordinated deployment of others
+  - Shared libraries contain business logic, not just utilities
+  - Synchronous call chains span 3+ services for common operations
+- **Severity Tendency:** high
+
+### Wrong Abstraction Level
+
+- **Description:** Code has been prematurely or incorrectly abstracted — shared modules, base classes, or generic frameworks that make the code harder to understand than simple duplication would.
+- **Indicators:**
+  - Abstract base classes with only one concrete implementation
+  - Generic frameworks used for a single use case
+  - Utility functions with boolean parameters that switch between unrelated behaviors
+  - Code that requires understanding the abstraction layer to understand any concrete use case
+- **Severity Tendency:** medium
+
+### Feature Envy
+
+- **Description:** Modules or classes that primarily operate on another module's data rather than their own, indicating misplaced responsibility and a domain modeling failure.
+- **Indicators:**
+  - Methods that take an object and call multiple getters/accessors on it
+  - Modules that import data structures from another module more than their own
+  - Transformation logic located far from the data it transforms
+  - "Manager" or "Service" classes that orchestrate another module's internal operations
+- **Severity Tendency:** medium
+
+## Best Practice Patterns
+
+### Clean Architecture / Hexagonal Architecture
+
+- **Replaces Failure Pattern:** Big Ball of Mud
+- **Abstract Pattern:** Structure the system with a clear dependency direction — outer layers depend on inner layers, never the reverse. Domain logic sits at the center with no dependencies on infrastructure. All external concerns (database, HTTP, messaging) are behind interfaces defined by the domain.
+- **Framework Mappings:**
+  - Spring Boot: Domain layer as plain POJOs, repository interfaces defined in domain, implementations in infrastructure module
+  - NestJS: Modules with clear imports, domain services with no framework decorators, repository pattern for data access
+  - Laravel: Domain directory separate from app/, repository interfaces in domain, Eloquent implementations in infrastructure
+- **Language Patterns:**
+  - Java/Kotlin: Package-by-feature with domain packages having zero framework imports
+  - TypeScript: Barrel exports per module, no cross-module deep imports, dependency injection for infrastructure
+
+### Interface Segregation
+
+- **Replaces Failure Pattern:** Leaky Abstractions
+- **Abstract Pattern:** Expose narrow, purpose-specific interfaces rather than broad, implementation-revealing ones. Each consumer should depend only on the methods it uses, not the entire capability of the provider.
+- **Framework Mappings:**
+  - Go: Small interfaces defined at the consumer site, not the provider (io.Reader, io.Writer as exemplars)
+  - Spring Boot: Separate query and command interfaces for repositories (CQRS-lite)
+  - Express/NestJS: Route-specific DTOs rather than exposing domain entities directly
+- **Language Patterns:**
+  - TypeScript: Interface per use case (`UserReader`, `UserWriter`) rather than one fat `UserRepository`
+  - Python: Protocol classes (PEP 544) for structural typing, ABC for small capability interfaces
+
+### Acyclic Dependencies Principle
+
+- **Replaces Failure Pattern:** Circular Dependencies
+- **Abstract Pattern:** The dependency graph between modules must be a directed acyclic graph (DAG). Break cycles through dependency inversion — introduce an interface owned by the higher-level module that the lower-level module implements.
+- **Framework Mappings:**
+  - Spring Boot: Event-driven communication between modules via ApplicationEventPublisher to break synchronous cycles
+  - NestJS: forwardRef() as a temporary fix, but proper solution is extracting shared interfaces into a separate module
+  - Django: Signal system for decoupled module communication
+- **Language Patterns:**
+  - Java: Dependency inversion with interfaces — module A defines the interface, module B implements it
+  - TypeScript: Shared types/interfaces package that both modules depend on, breaking the direct cycle
+
+### Module Cohesion
+
+- **Replaces Failure Pattern:** God Objects / God Modules
+- **Abstract Pattern:** Each module should have a single, well-defined responsibility. If a module's name requires "and" to describe, it should be split. Utility grab-bags should be decomposed into purpose-specific modules.
+- **Framework Mappings:**
+  - DDD: Aggregate roots as natural module boundaries — each aggregate is a cohesion unit
+  - Spring Boot: One @Service per bounded context operation, packages named by domain concept
+  - Rails: Concerns and service objects to extract responsibilities from fat models/controllers
+- **Language Patterns:**
+  - Any: Replace `utils/` with purpose-named modules (`formatting`, `validation`, `date-helpers`)
+  - Go: Package per domain concept with short, focused packages preferred over large "everything" packages
+
+### Strict Layering
+
+- **Replaces Failure Pattern:** Layer Violations
+- **Abstract Pattern:** Each layer may only depend on the layer immediately below it. Skip-layer access is forbidden. Layer boundaries are enforced through module visibility, dependency rules, or architectural fitness functions.
+- **Framework Mappings:**
+  - Spring Boot: ArchUnit tests enforcing layer dependencies (controller → service → repository, never controller → repository)
+  - .NET: Project references enforcing layer separation (API project references Domain, not Infrastructure)
+  - NestJS: Module imports enforcing dependency direction with strict mode
+- **Language Patterns:**
+  - Java: Package-private visibility for implementation classes, public only for interfaces
+  - TypeScript: `index.ts` barrel exports controlling module surface, eslint-plugin-import rules preventing deep imports
+
+### Service Autonomy
+
+- **Replaces Failure Pattern:** Distributed Monolith
+- **Abstract Pattern:** Each service owns its data, can be deployed independently, and communicates through well-defined asynchronous contracts. Shared databases are replaced with API contracts or event-driven integration.
+- **Framework Mappings:**
+  - Kafka/RabbitMQ: Event-driven integration replacing synchronous call chains
+  - gRPC: Strongly-typed service contracts with independent schema evolution
+  - API Gateway: Centralized routing with independent service deployments behind it
+- **Language Patterns:**
+  - Any: Database-per-service with API or event-based data sharing
+  - Any: Consumer-driven contract tests (Pact) to validate integration without coupling
+
+### Justified Abstraction
+
+- **Replaces Failure Pattern:** Wrong Abstraction Level
+- **Abstract Pattern:** Prefer duplication over the wrong abstraction. Introduce abstractions only when three or more concrete cases exist and the shared pattern is stable and well-understood. Every abstraction should earn its keep.
+- **Framework Mappings:**
+  - Rule of Three: Wait for three instances before extracting a shared abstraction
+  - Martin Fowler's Refactoring: Extract only when duplication is proven harmful, not merely present
+  - Sandi Metz: "Prefer duplication over the wrong abstraction" — wrong abstractions are more expensive than duplicated code
+- **Language Patterns:**
+  - Any: Inline implementation for single-use patterns; extract only after multiple proven uses
+  - Any: Composition over inheritance — small, focused functions combined rather than class hierarchies
+
+### Responsibility Alignment
+
+- **Replaces Failure Pattern:** Feature Envy
+- **Abstract Pattern:** Operations should live with the data they operate on. If a function primarily uses another module's data, it belongs in that module. Domain modeling should align code boundaries with data ownership.
+- **Framework Mappings:**
+  - DDD: Rich domain models where behavior lives with the entity it operates on
+  - Tell, Don't Ask: Objects expose behavior (tell), not data for external computation (ask)
+  - CQRS: Separate read/write models to avoid cross-module data access for queries
+- **Language Patterns:**
+  - Java/Kotlin: Methods on the domain object itself rather than in external "service" classes
+  - Python: Instance methods for operations on instance data; module-level functions for operations on module's data types
+
+## Red Flags
+
+- Directory named `utils/`, `helpers/`, `common/`, or `misc/` with >500 lines
+- A single file imported by more than half the codebase
+- Import statements that reach 3+ levels deep into another module's directory structure
+- Module names that require "and" to describe their purpose
+- Business logic in controller/handler files
+- Database queries in UI component files
+- Circular import warnings from build tools
+- "Shared" library containing business logic, not just utilities
+- God class with >1000 lines and >20 methods
+- Service-to-service calls requiring synchronized deployments
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| sonarqube | Cyclomatic complexity, cognitive complexity, coupling between modules, duplication density | primary |
+| semgrep | Custom rules to detect layer violations, forbidden imports, architectural pattern violations | supporting |
+| git-history | Change coupling analysis — files that always change together reveal hidden architectural dependencies | supporting |
+
+## Standards & Frameworks
+
+- SOLID Principles — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
+- Clean Architecture (Robert C. Martin) — Dependency rule, entity/use-case/interface-adapter/framework layers
+- Hexagonal Architecture (Alistair Cockburn) — Ports and adapters separating domain from infrastructure
+- Domain-Driven Design (Eric Evans) — Bounded contexts, aggregates, ubiquitous language
+- Package Principles (Robert C. Martin) — Reuse-Release, Common-Closure, Common-Reuse, Acyclic Dependencies, Stable Dependencies, Stable Abstractions
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| Coupling between modules | Number of inter-module dependencies relative to total modules | <0.3 (normalized, lower is better) |
+| Average cyclomatic complexity | Average decision complexity per function | <10 per function |
+| Dependency depth | Longest chain in the module dependency graph | <5 levels |
+| File size distribution (P90) | 90th percentile file size in lines of code | <400 lines |
+| Circular dependency count | Number of cycles in the module dependency graph | 0 |
+| Afferent/efferent coupling ratio | Balance between incoming and outgoing dependencies per module | Varies — instability index (Ce/(Ca+Ce)) should be 0 or 1, not middle |