azcodr 1.3.0 → 1.5.0

package/docs/rules/test_driven_development.md

@@ -1,6 +1,6 @@
-# Test-Driven Development (London School TDD) & Agile Domain Lifecycle
+# Test-Driven Development (London School TDD) & Test Isolation Standards
 
-> **Core Mandate:** Drive all features through the non-negotiable 5-Phase Agile Domain Lifecycle: Requirements ➔ Domain Analysis ➔ Outer Acceptance Test (RED) ➔ Inner Unit Test (RED-GREEN-REFACTOR) ➔ Outer Verification (GREEN). Never deviate from this sequence.
+> **Core Mandate:** Drive all features through the non-negotiable 5-Phase Agile Domain Lifecycle (Outside-In Double-Loop TDD, Uncle Bob's 3 Laws), enforcing transactional database rollback per test, zero-sleep determinism, and non-negotiable 100.00% statement, branch, and function coverage gates.
 
 ---
 
@@ -8,57 +8,42 @@
 
 Every functional increment, feature, or architectural modification must traverse this unbroken sequence. Writing code out of order (e.g. coding before tests, or testing before domain analysis) is strictly prohibited.
 
-```
-┌────────────────────────────────────────────────────────────────────────────────────────┐
-│                        THE NON-NEGOTIABLE AGILE DOMAIN LIFECYCLE                       │
-└────────────────────────────────────────────────────────────────────────────────────────┘
-
-  [Phase 1: Requirements Engineering]
-     │  - Decompose user prompt into INVEST user stories.
-     │  - Author executable Gherkin Given-When-Then criteria.
-     │  - Define Out-of-Scope non-goals and edge case status code matrix.
-     ▼
-  [Phase 2: Tactical Domain Analysis]
-     │  - Discover and enforce Ubiquitous Language terms.
-     │  - Map Bounded Contexts, Aggregate Roots, and Value Objects.
-     │  - Codify explicit business invariants that state mutations must protect.
-     ▼
-  [Phase 3: Outer-Loop Acceptance Test (RED)]
-     │  - Write failing end-to-end acceptance or contract test:
-     │      * Frontend: Component/UI user interaction assertion (Playwright / testing library).
-     │      * Backend: Black-box HTTP API contract test (Supertest/OpenAPI).
-     │  - Verify the test FAILS for the expected reason (RED proof).
-     ▼
-  [Phase 4: Inner-Loop TDD & Collaborator Discovery (RED-GREEN-REFACTOR)]
-     │  - Outer test discovers required collaborators (Use Cases, Ports, Domain Entities).
-     │  - For each collaborator:
-     │      1. RED: Write failing unit test asserting domain invariants.
-     │      2. GREEN: Write minimal production code to pass.
-     │      3. REFACTOR: Eliminate duplication, enforce SLAP, CQS, Clean Code.
-     ▼
-  [Phase 5: Outer Acceptance Resolution & Definition of Done]
-        - Run outer acceptance test: verifies GREEN without altering the test assertion.
-        - Run cross-package boundary smoke tests (reverse proxy, sockets, LAN interfaces).
-        - Verify 100.00% test coverage gate across all packages.
-        - Pass Definition of Done (DoD) checklist.
+```mermaid
+flowchart TD
+    P1["Phase 1: Requirements Engineering<br/>• INVEST stories & Gherkin criteria<br/>• Out-of-scope non-goals & status matrix"]
+    P2["Phase 2: Tactical Domain Analysis<br/>• Ubiquitous Language & Bounded Contexts<br/>• Aggregate Roots & Business Invariants"]
+    P3["Phase 3: Outer Acceptance Test (RED)<br/>• Failing UI component or API route test<br/>• Verifies failure for expected reason"]
+    P4["Phase 4: Inner TDD & Collaborator Discovery (RED-GREEN-REFACTOR)<br/>• Discovers Use Cases & Ports<br/>• Nano-cycles with Uncle Bob's 3 Laws"]
+    P5["Phase 5: Outer Verification & Proof (GREEN)<br/>• Outer test passes with zero regressions<br/>• 100.00% coverage & boundary smoke verification"]
+
+    P1 --> P2 --> P3 --> P4 --> P5
 ```
 
 ---
 
-## 2. Outside-In TDD (London School) Double Loop
+## 2. The London School Double-Loop TDD Workflow
 
 Drive all user-facing features from the outermost interface inward:
 
-```
-[Outer Loop: Acceptance / Contract Test (RED)]
-       │
-       ▼
-[Inner Loop: Unit Test Collaborator (RED)] ──► [Implement Minimal Code (GREEN)] ──► [Refactor (REFACTOR)]
-       │                                                                                   │
-       └──────────────────────── Repeat Inner Loop until Done ◄────────────────────────────┘
-       │
-       ▼
-[Outer Loop: Acceptance / Contract Test (GREEN)] ──► [Outer Refactor]
+```mermaid
+flowchart TD
+    subgraph OuterLoop ["Outer Loop (Acceptance / Contract Test)"]
+        O_RED["Outer Acceptance Test (RED)"]
+        O_GREEN["Outer Acceptance Test (GREEN)"]
+        O_REF["Outer Refactor & Proof"]
+    end
+
+    subgraph InnerLoop ["Inner Loop (Unit Test & Collaborator TDD)"]
+        I_RED["Unit Test Collaborator (RED)"]
+        I_GREEN["Implement Minimal Code (GREEN)"]
+        I_REF["Refactor under Green (REFACTOR)"]
+        
+        I_RED --> I_GREEN --> I_REF
+        I_REF -.->|"Next Micro-Assertion"| I_RED
+    end
+
+    O_RED --> I_RED
+    I_REF --> O_GREEN --> O_REF
 ```
 
 1. **Outer Acceptance / Contract Test First**: Every feature begins with a failing outer acceptance test:
@@ -81,13 +66,9 @@ Deviating from this lifecycle introduces catastrophic defects and architectural
 | **Skipping Domain Analysis** | Hallucinated entities, missing business invariants, wrong data models. | "The Toy Prototype Blunder": Foreign key string inputs, unvalidated states, costly migrations. |
 | **Writing Code Before Tests** | Untested edge cases, unfalsifiable code, confirmation bias in test design. | Hidden bugs in production, regressions during refactoring, brittle codebases. |
 | **Skipping Outer Acceptance Tests** | In-memory unit tests pass, but user interactions and network routing fail. | "The In-Memory Supertest Illusion": App says "Offline/Connecting" while 100% unit tests pass. |
+| **Dropping the UI in Fullstack TDD** | Developer plunges into internal domain units, leaving the application headless with no web UI. | "The Headless Fallacy": User requests a fullstack web app but receives pure headless backend libraries. |
 | **Skipping the Refactor Phase** | Technical debt accumulates immediately behind green tests. | Code rot, duplicated logic, bloated monolithic functions (> 30 lines), violated DRY/SLAP. |
 
-### The Immutable Three Laws of TDD (Uncle Bob & Kent Beck):
-1. **First Law:** You are not allowed to write any production code unless it is to make a single failing unit or acceptance test pass.
-2. **Second Law (Strict Incremental Boundary):** You are not allowed to write any more of a unit test than is sufficient to fail; and compilation failures are failures.
-3. **Third Law (Minimal Production Code):** You are not allowed to write any more production code than is sufficient to pass the one currently failing test.
-
 ---
 
 ## 4. The Batch-Test Anti-Pattern & The Incremental Nano-Cycle
@@ -111,18 +92,94 @@ Every collaborator discovered in Phase 4 must progress through micro-cycles of o
 ## 5. Ping-Pong Pair Programming Protocol with AI
 
 When pairing with the human developer, operate in true **Ping-Pong TDD**:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor A as Partner A (Driver/Human)
+    participant S as Test Runner
+    actor B as Partner B (Navigator/AI)
+    
+    A->>S: Writes 1 micro-test assertion (RED)
+    S-->>A: Displays verified failure output
+    B->>S: Writes minimal code to pass (GREEN)
+    S-->>B: Displays verified pass
+    Note over A,B: Both refactor under green (REFACTOR)
+    Note over A,B: Roles swap; repeat for next behavior
 ```
-  ┌─────────────────────────────────────────────────────────────┐
-  │                 PING-PONG PAIR PROGRAMMING                  │
-  │                                                             │
-  │  Turn 1 [Partner A]: Writes ONE micro-test assertion (RED)  │
-  │  Turn 2 [System]:    Runs test & displays verified failure  │
-  │  Turn 3 [Partner B]: Writes MINIMAL code to pass (GREEN)    │
-  │  Turn 4 [System]:    Runs test & displays verified pass     │
-  │  Turn 5 [Both]:      Refactors under green (REFACTOR)       │
-  │  Turn 6:             Roles swap; repeat for next behavior   │
-  └─────────────────────────────────────────────────────────────┘
-```
+
 - **Collaborative Steering**: The human developer can write the test while the AI writes the minimal pass, or the AI can present each micro-test and await confirmation before implementing.
 - **Continuous Alignment**: Design and data structures emerge organically through mutual feedback rather than monolithic code dumps.
 
+---
+
+## 6. Test Isolation & Determinism
+
+- **Transactional Rollback per Integration Test**:
+  - Every integration test that interacts with persistence must execute within a scoped transaction that is rolled back upon test completion (`afterEach` rollback) or use ephemeral, disposable database isolates. Never leave mutated rows that pollute subsequent tests.
+- **Deterministic Test Data Factories**:
+  - Utilize strongly-typed test data factories (`buildUser()`, `buildOrder()`) with randomized unique identifiers rather than hardcoded magic strings or fixed database IDs.
+- **Zero Sleep / Flakiness Elimination**:
+  - Strictly forbid arbitrary `sleep()` or timeout pauses in tests.
+  - Rely exclusively on deterministic condition polling (`waitFor(condition)`) or reactive event promises to eliminate test flakiness.
+
+---
+
+## 7. Mandatory 100.00% Test Coverage Thresholds
+
+- **Strict Coverage Thresholds**: Maintain line, function, branch, and statement test coverage at **100.00%** across all backend domain logic, adapters, contracts, and frontend suites. Strictly enforce 100% threshold failure gates in CI pipelines (`scripts/test_coverage.js`).
+- **Exhaustive Status Codes & Error Branches**: Explicitly test all HTTP/gRPC response codes:
+  - Success: `200 OK`, `201 Created`, `204 No Content`
+  - Client Errors: `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`, `422 Unprocessable Entity`, `429 Too Many Requests`
+  - Server Failures: `500 Internal Server Error`, `503 Service Unavailable`
+- **UI Interaction States & Edge Cases**: Fully assert all presentation states (loading spinners, disabled controls, error banners, success feedback, empty states) across suites.
+
+---
+
+## 8. Headless UI Testing Architecture for Autonomous Agents
+
+Autonomous AI coding agents operate without human eyesight. To verify user interfaces deterministically without manual browser clicking, projects with UI interfaces must enforce the **4-Tier Headless UI Testing Pyramid**:
+
+```mermaid
+flowchart TD
+    T4["Tier 4: Headless Playwright E2E<br/>(Full multi-page browser journeys, Chromium CLI)"]
+    T3["Tier 3: Automated A11y Gates (axe-core)<br/>(WCAG 2.2 AA audits with zero human eyesight)"]
+    T2["Tier 2: Network Isolation via MSW<br/>(Deterministic HTTP mocking: loading, error, empty, success)"]
+    T1["Tier 1: Behavioral Component Testing (@testing-library)<br/>(Accessible role queries, user-event keyboard/mouse)"]
+
+    T4 --> T3 --> T2 --> T1
+```
+
+### 8.1. Behavioral Component Testing (@testing-library + jsdom/happy-dom)
+- **Test Behavior, Not Implementation**: Never assert component internal state, hook variables, or private methods. Assert what the user experiences.
+- **Strict Accessible Role-Based Queries**:
+  - *Mandatory:* `screen.getByRole('button', { name: /submit/i })`, `screen.getByRole('heading', { level: 1 })`, `screen.getByLabelText(/email/i)`.
+  - *Prohibited:* `container.querySelector('.btn-primary')`, `getByTestId('submit-btn')` (data-testid is a banned crutch for poor semantic accessibility).
+- **Realistic User Events**: Always use `@testing-library/user-event` rather than synthetic `fireEvent` to accurately simulate browser focus, keypress, typing, and click sequences.
+
+### 8.2. Network Isolation via Mock Service Worker (MSW)
+- Never mock client fetch/HTTP clients with ad-hoc mock objects (`vi.fn()`).
+- Intercept requests at the network layer using **MSW**:
+  ```typescript
+  // Deterministic network boundary simulation
+  http.get('/api/v1/orders', () => HttpResponse.json(mockOrders))
+  ```
+- **The 4 Universal UI Presentation States**: Component tests must explicitly assert:
+  1. *Loading State:* Accessible spinner / skeleton is rendered while request is in flight.
+  2. *Success State:* Data grid / list renders items with correct semantic markup.
+  3. *Error State:* RFC 7807 error banner renders with retry button when API returns `500` or `422`.
+  4. *Empty State:* Meaningful empty-state message and CTA when API returns `[]`.
+
+### 8.3. Automated Headless Accessibility Gates (axe-core)
+- Every component test suite must execute automated accessibility checks using `axe-core` (`vitest-axe` or `@axe-core/playwright`):
+  ```typescript
+  const { container } = render(<OrderDetailsModal orderId="ord_123" />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+  ```
+- Fails the test automatically on missing ARIA labels, invalid heading hierarchies, contrast defects, or unlinked form labels without requiring human eyesight.
+
+### 8.4. End-to-End Headless Browser Automation (Playwright)
+- For critical user journeys (authentication, checkout, resource creation):
+  - Run headless Chromium in CLI/CI: `npx playwright test`.
+  - Configure automated forensic captures on failure: screenshots, trace files, and videos saved to `test-results/` for immediate agent inspection.

package/docs/rules/type_safety.md

@@ -0,0 +1,65 @@
+# Static Type Safety & Sound Type Systems
+
+> **Core Mandate:** Enforce maximum compiler strictness, branded nominal typing for domain identifiers, strict prohibition of untyped escape hatches, and automated pre-commit quality guardrails across polyglot implementations.
+
+---
+
+## 1. The YAGNI Gate: Sound Types vs. Type-Level Acrobatics
+
+Type systems exist to prove program correctness and eliminate entire classes of runtime errors. **Never compromise static type safety with `any` escape hatches, but avoid premature type-level metaprogramming acrobatics that obscure domain intent.**
+
+```mermaid
+flowchart TD
+    subgraph TypeSafetyGate["Type Safety YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Strict compiler flags enabled with zero compilation warnings<br/>• Concrete interfaces, records, dataclasses, and structs<br/>• Zero any, Any, or raw Object escape hatches"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Bypassing the compiler via any, as unknown as T, or casts<br/>• Deep recursive type-gymnastics where a simple interface solves it<br/>• Primitive Obsession: passing raw string for all domain IDs"]
+        B3["3. The Tipping Point (Graduation)<br/>• Domain Identifiers: Use Branded/Nominal types when multiple entity IDs risk mix-ups<br/>• System Boundaries: Use fail-fast schema validation (Zod, Serde, Pydantic) on untrusted inputs"]
+        B1 -->|Forbidden if compiler bypassed| B2
+        B1 -->|Triggered by domain safety & boundary parsing| B3
+    end
+```
+
+---
+
+## 2. Maximum Compiler Strictness Across Polyglot Stacks
+
+Regardless of the execution language chosen for an adapter, service, or CLI, enforce maximum compiler rigor to eliminate runtime null pointer exceptions, unhandled type cases, and memory errors at compile time:
+
+- **TypeScript**: Enable all strict compiler flags (`strict: true`, `noImplicitAny: true`, `strictNullChecks: true`, `noUncheckedIndexedAccess: true`).
+- **Python**: Enforce strict type checking (`mypy --strict` or `pyright` in strict mode).
+- **Rust**: Enable `#![deny(clippy::all)]` and `#![deny(missing_docs)]` with zero `unsafe` blocks.
+- **Go**: Enable comprehensive static analysis (`golangci-lint` with `errcheck`, `govet`, `staticcheck`).
+- **Java**: Enable `-Werror -Xlint:all`, enforce `@NonNull` contracts or the Checker Framework.
+- **C#**: Enable `<Nullable>enable</Nullable>` and `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`.
+
+---
+
+## 3. Branded Nominal Typing & Primitive Obsession Elimination
+
+Prevent accidental mixing of raw primitive identifiers (e.g. passing an arbitrary `string` representing a `TenantId` where a `UserId` is expected) by enforcing nominal types across all supported languages:
+
+```mermaid
+classDiagram
+    class NominalIdentifierPattern {
+        <<Polyglot Implementations>>
+    }
+    note for NominalIdentifierPattern "Rust: struct TenantId(String); struct UserId(String);<br/>Go: type TenantId string; type UserId string<br/>TypeScript: type TenantId = Brand<string, 'TenantId'>;<br/>Python: TenantId = NewType('TenantId', str)<br/>Java: record TenantId(String value) {}<br/>C#: readonly record struct TenantId(string Value);"
+```
+
+Domain functions must accept and return branded types rather than raw primitive strings or integers.
+
+---
+
+## 4. Strict Prohibition of Untyped Escape Hatches
+
+- **Zero Tolerance for Unsound Types**: Strictly prohibit `any` in TypeScript, raw `interface{}` / `any` without type assertion checks in Go, raw `Any` in Python, or unchecked casts in Java/Rust/C#.
+- **Runtime Validation at Boundaries**: External payloads (network requests, message queues, disk files) must be parsed and narrowed into strongly-typed domain structures before passing to application services (e.g. via Zod in TS, Pydantic in Python, Serde in Rust, Jackson/Record validation in Java).
+- **Commit Guardrails**: Enforce Conventional Commits via commit linters. Never bypass pre-commit hooks running static type checking, formatting, and linters.
+
+---
+
+## 5. Clean Import Hygiene & Relative Traversal Elimination
+
+- **Path Alias Mandate**: In languages supporting path aliases (TypeScript, Python packages, Go modules), configure root module resolution (e.g. `@/*` mapped to `./src/*`) to prevent brittle relative coupling.
+- **Strict Prohibition of Deep Relative Traversal**: Never use deep relative traversals (`../../../..`, `../../..`, `../..`) across layers or contexts. Deep relative paths create fragile coupling, impair refactoring, and obscure domain layer boundaries.
+- **Scope of Sibling Imports**: Local relative imports (`./file`) are permitted only for immediate siblings within the identical directory. Any import traversing up a directory hierarchy or crossing architectural boundaries (domain, ports, adapters, components, context) MUST resolve via root package paths or aliases.

package/docs/rules/ui_ux_architecture.md

@@ -10,14 +10,16 @@ A catastrophic software defect occurs when design architecture is not triaged up
 
 Before a single UI component or view is built, every interface increment must pass the **7-Pillar Design Architecture Triage Gate**:
 
-```
-1. ROLE & IDENTITY TRIAGE      ──► Who is the user? What is their exact operational domain and boundary?
-2. INFORMATION ARCHITECTURE    ──► What is the hierarchy? Persistent Shell vs. Dynamic Canvas?
-3. EXPERIENCE DUALITY          ──► Operator Enterprise Workspace (dense) vs. Member Consumer Portal (simple)?
-4. NAVIGATION & WAYFINDING     ──► Collapsible sidebar, breadcrumbs, command palette (Cmd+K), mobile drawer?
-5. STATE & URL SYNCHRONIZATION ──► Deep-linkable search params (?tab=, ?q=, ?page=, ?modal=)?
-6. ACCESS & ROUTE PROTECTION   ──► Strict route guards (<ProtectedRoute>), role redirection, 403 handling?
-7. ACCESSIBILITY & FEEDBACK    ──► WCAG 2.2 AA, focus trapping, ARIA live regions, zero browser-native alerts?
+```mermaid
+flowchart TD
+    P1["1. Role & Identity Triage<br/>Who is the user? Operational domain & boundary"]
+    P2["2. Information Architecture<br/>Hierarchy: Persistent Shell vs. Dynamic Canvas"]
+    P3["3. Experience Duality<br/>Operator Enterprise Workspace (dense) vs. Member Consumer Portal (simple)"]
+    P4["4. Navigation & Wayfinding<br/>Collapsible sidebar, breadcrumbs, command palette Cmd+K, mobile drawer"]
+    P5["5. State & URL Synchronization<br/>Deep-linkable search params (?tab=, ?q=, ?page=, ?modal=)"]
+    P6["6. Access & Route Protection<br/>Route guards, role redirection, 403 handling"]
+    P7["7. Accessibility & Feedback<br/>WCAG 2.2 AA, focus trapping, ARIA live regions, zero native alerts"]
+    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
 ```
 
 ---
@@ -26,27 +28,28 @@ Before a single UI component or view is built, every interface increment must pa
 
 The application interface is strictly divided into two distinct anatomical zones:
 
-```
-+----------------------------------------------------------------------------------------------------+
-| PERSISTENT GLOBAL HEADER                                                                           |
-| [Brand / Logo] | [Organization Context Switcher] | [Command Palette Cmd+K] | [Alerts] | [User Menu]|
-+------------------------------------+---------------------------------------------------------------+
-| PERSISTENT OPERATOR SIDEBAR        | DYNAMIC VIEWPORT CANVAS                                       |
-| (Collapsible to 64px Icon Rail)    |                                                               |
-|                                    | 1. CONTEXTUAL BREADCRUMBS                                     |
-| - Overview (Dashboard)             |    Home > Resources > Resource Alpha > Details                |
-| - Operations (Catalogs, Resources) | ------------------------------------------------------------- |
-| - Transactions (Orders, Invoices)  | 2. PAGE HEADER & PRIMARY ACTION CTA                           |
-| - Financials (Ledger, Settlements) |    [Page Title]               [Filter] [+ Primary Action CTA] |
-| - Services (Requests, Tickets)     | ------------------------------------------------------------- |
-| - Settings (Team, Roles, Org)      | 3. URL-SYNCHRONIZED TABS & SEARCH BAR                         |
-| ---------------------------------- |    [Active (12)] [Draft (2)] [Archived (0)]  [Search...]      |
-| [System Health Badge]              | ------------------------------------------------------------- |
-| [Collapse / Expand Toggle Button]  | 4. DATA PRESENTATION CANVAS                                   |
-|                                    |    (Data Tables, Metric Grids, Detail Drawers, Dialogs)       |
-+------------------------------------+---------------------------------------------------------------+
-| PERSISTENT STATUS / FOOTER (System Context, Active Role Indicator, Accessible Live Regions)         |
-+----------------------------------------------------------------------------------------------------+
+```mermaid
+flowchart TD
+    subgraph PersistentAppShell["Persistent Application Shell"]
+        Header["Persistent Global Header<br/>[Brand / Logo] | [Org Switcher] | [Command Palette Cmd+K] | [Alerts] | [User Profile]"]
+        
+        subgraph BodyLayout["Viewport Split"]
+            Sidebar["Persistent Operator Sidebar<br/>(Collapsible to 64px Icon Rail)<br/>• Overview (Dashboard)<br/>• Operations (Catalogs, Resources)<br/>• Transactions (Orders, Invoices)<br/>• Financials (Ledger, Settlements)<br/>• Services (Requests, Tickets)<br/>• Settings (Team, Roles, Org)<br/>• Collapse / Expand Toggle"]
+            
+            subgraph DynamicCanvas["Dynamic Viewport Canvas"]
+                Breadcrumb["1. Contextual Breadcrumbs<br/>Home > Resources > Details"]
+                PageHeader["2. Page Header & Primary Action CTA<br/>[Page Title] [Filter] [+ Primary Action CTA]"]
+                Tabs["3. URL-Synchronized Tabs & Search Bar<br/>[Active (12)] [Draft (2)] [Archived (0)] [Search...]"]
+                Content["4. Data Presentation Canvas<br/>(Data Tables, Metric Grids, Detail Drawers, Dialogs)"]
+                Breadcrumb --> PageHeader --> Tabs --> Content
+            end
+            Sidebar ~~~ DynamicCanvas
+        end
+        
+        Footer["Persistent Status / Footer (System Context, Active Role Indicator, Accessible Live Regions)"]
+        
+        Header --> BodyLayout --> Footer
+    end
 ```
 
 ### 2.1. The Persistent Shell (Never Re-rendered Across Page Navigations)
@@ -132,7 +135,7 @@ To prevent confusing operators with consumer simplicity and overwhelming consume
 
 ## 6. Bidirectional URL State Synchronization
 
-Per [`docs/rules/ui_navigation.md`](./ui_navigation.md), all view state that represents navigation, active tab, filtering, sorting, pagination, or search query must synchronize bidirectionally with URL search parameters (`useSearchParams`):
+Per [`docs/rules/frontend_architecture.md`](./frontend_architecture.md), all view state that represents navigation, active tab, filtering, sorting, pagination, or search query must synchronize bidirectionally with URL search parameters (`useSearchParams`):
 1. **Tabs**: `?tab=active`, `?tab=draft`, `?tab=archived`
 2. **Filters**: `?status=ACTIVE&category=cloud`
 3. **Search Queries**: `?q=alpha`

package/docs/rules/workflow_state_machines.md

@@ -4,7 +4,24 @@
 
 ---
 
-## 1. The Fallacy of Universal Configurability
+## 1. The YAGNI Gate: Simple Enums vs. State Machines
+
+State machine libraries, declarative transition matrices, and workflow orchestration engines introduce significant cognitive and operational weight. **Never build a state machine when a simple enum or boolean flag suffices.**
+
+```mermaid
+flowchart TD
+    subgraph StateMachineGate["State Machine YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Discriminated union or enum column (status: 'PENDING' | 'DONE')<br/>• Simple guard clause in aggregate method (if (status !== 'A'))<br/>• Zero external state-machine libraries (no XState, Temporal, BPMN)"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Binary lifecycle flags (is_active, is_verified, archived)<br/>• Strict linear forward-only progressions without branching/rollback<br/>• Synchronous single-table mutations within one ACID transaction"]
+        B3["3. The Tipping Point (Graduation)<br/>• Entity has 3+ non-linear states with branching transitions, cancellations, or conditional rollbacks<br/>• Transitions require multi-step side-effects (emitting domain events, releasing authorizations)<br/>• Business/regulatory rules mandate an immutable transition audit<br/>• Durable orchestration (Temporal) justified ONLY when transitions depend on asynchronous multi-day callbacks"]
+        B1 -->|Forbidden if linear or binary| B2
+        B1 -->|Triggered by multi-step or non-linear branches| B3
+    end
+```
+
+---
+
+## 2. The Fallacy of Universal Configurability
 
 A common architectural anti-pattern is the **"Universal Workflow Fallacy"** (a variant of the *Inner Platform Effect*), which presumes that *every* status and state transition in a system should be dynamically configurable by end-users or tenants.
 
@@ -25,7 +42,7 @@ A common architectural anti-pattern is the **"Universal Workflow Fallacy"** (a v
 
 ---
 
-## 2. State Machine Architectural Patterns
+## 3. State Machine Architectural Patterns
 
 ### Pattern A: In-Aggregate State Machine (Hard Invariants)
 Model states as **Discriminated Unions** or the GoF **State Pattern** encapsulated inside the domain entity. Public mutations must be explicit domain actions:
@@ -82,7 +99,7 @@ When a state transition requires coordination across multiple aggregates or asyn
 
 ---
 
-## 3. Mandatory State Transition Audit Trail
+## 4. Mandatory State Transition Audit Trail
 
 Every state change across any entity or workflow MUST be immutably recorded in a transition log:
 

package/lib/scaffold.js

@@ -11,7 +11,8 @@ const TEMPLATE_ITEMS = [
   'docs',
   '.agents',
   '.gitignore',
-  '.editorconfig'
+  '.editorconfig',
+  'LICENSE'
 ];
 
 /**
@@ -93,7 +94,7 @@ function ensureSymlink(targetDir, linkName, targetFileName, dryRun = false) {
     return true;
   } catch {
     // Fallback if environment (e.g., certain Windows configs) prevents symlink creation
-    const sourceFile = path.join(targetDir, targetFileName);
+    const sourceFile = path.resolve(targetDir, targetFileName);
     if (fs.existsSync(sourceFile)) {
       fs.copyFileSync(sourceFile, linkPath);
     }
@@ -102,10 +103,29 @@ function ensureSymlink(targetDir, linkName, targetFileName, dryRun = false) {
 }
 
 /**
- * Ensures all bash scripts in skill directories have executable permissions (0o755).
+ * Ensures all bash scripts in agent and skill directories have executable permissions (0o755).
  */
 function makeScriptsExecutable(targetDir, dryRun = false) {
   const modified = [];
+
+  const agentScriptsDir = path.join(targetDir, '.agents', 'scripts');
+  if (fs.existsSync(agentScriptsDir) && fs.statSync(agentScriptsDir).isDirectory()) {
+    const files = fs.readdirSync(agentScriptsDir);
+    for (const file of files) {
+      if (file.endsWith('.sh')) {
+        const filePath = path.join(agentScriptsDir, file);
+        modified.push(filePath);
+        if (!dryRun) {
+          try {
+            fs.chmodSync(filePath, 0o755);
+          } catch {
+            // Non-critical if filesystem does not support POSIX permissions
+          }
+        }
+      }
+    }
+  }
+
   const skillsDir = path.join(targetDir, '.agents', 'skills');
   if (!fs.existsSync(skillsDir)) return modified;
 
@@ -146,7 +166,13 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   }
 
   for (const item of TEMPLATE_ITEMS) {
-    const srcPath = path.join(resolvedTemplate, item);
+    let srcPath = path.join(resolvedTemplate, item);
+    if (item === '.gitignore' && !fs.existsSync(srcPath)) {
+      const npmIgnorePath = path.join(resolvedTemplate, '.npmignore');
+      if (fs.existsSync(npmIgnorePath)) {
+        srcPath = npmIgnorePath;
+      }
+    }
     if (!fs.existsSync(srcPath)) continue;
 
     const destPath = path.join(resolvedTarget, item);
@@ -164,6 +190,45 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   actions.push(`symlink: agents.md -> AGENTS.md`);
   ensureSymlink(resolvedTarget, 'agents.md', 'AGENTS.md', dryRun);
 
+  actions.push(`symlink: GEMINI.md -> AGENTS.md`);
+  ensureSymlink(resolvedTarget, 'GEMINI.md', 'AGENTS.md', dryRun);
+
+  actions.push(`symlink: .cursorrules -> AGENTS.md`);
+  ensureSymlink(resolvedTarget, '.cursorrules', 'AGENTS.md', dryRun);
+
+  actions.push(`symlink: .windsurfrules -> AGENTS.md`);
+  ensureSymlink(resolvedTarget, '.windsurfrules', 'AGENTS.md', dryRun);
+
+  // GitHub Copilot harness parity
+  const githubDir = path.join(resolvedTarget, '.github');
+  if (!dryRun && !fs.existsSync(githubDir)) {
+    fs.mkdirSync(githubDir, { recursive: true });
+  }
+  actions.push(`symlink: .github/copilot-instructions.md -> ../AGENTS.md`);
+  ensureSymlink(githubDir, 'copilot-instructions.md', '../AGENTS.md', dryRun);
+
+  // Starter package.json for project scripts validation
+  const pkgJsonPath = path.join(resolvedTarget, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) {
+    actions.push('create: package.json');
+    if (!dryRun) {
+      const projectName = path.basename(resolvedTarget) || 'my-project';
+      const starterPkg = {
+        name: projectName,
+        version: '0.1.0',
+        private: true,
+        description: 'Scaffolded with azcodr enterprise architecture template',
+        scripts: {
+          test: 'node --test',
+          'test:coverage': 'node --test --experimental-test-coverage',
+          lint: 'echo "No linter configured yet. Run /lets-build to configure toolchain."',
+          validate: 'bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh'
+        }
+      };
+      fs.writeFileSync(pkgJsonPath, JSON.stringify(starterPkg, null, 2) + '\n', 'utf-8');
+    }
+  }
+
   // Ensure scripts are executable
   const inspectDir = dryRun ? resolvedTemplate : resolvedTarget;
   const scripts = makeScriptsExecutable(inspectDir, dryRun);
@@ -174,6 +239,23 @@ function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
   return actions;
 }
 
+/**
+ * Detects whether targetDir is already inside an existing Git worktree.
+ */
+function isInsideGitWorkTree(targetDir) {
+  try {
+    const checkDir = fs.existsSync(targetDir) ? targetDir : path.dirname(targetDir);
+    const out = cp.execSync('git rev-parse --is-inside-work-tree', {
+      cwd: checkDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8'
+    });
+    return out.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Initializes a git repository in the target directory if not already inside one.
  */
@@ -184,12 +266,41 @@ function initGit(targetDir, options = {}) {
   const gitDir = path.join(targetDir, '.git');
   if (fs.existsSync(gitDir)) return false;
 
+  if (isInsideGitWorkTree(targetDir)) return false;
+
   if (dryRun) {
     return true;
   }
 
   try {
-    cp.execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+    try {
+      cp.execSync('git init -b main -q', { cwd: targetDir, stdio: 'ignore' });
+    } catch {
+      cp.execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+      try {
+        cp.execSync('git branch -m main', { cwd: targetDir, stdio: 'ignore' });
+      } catch {
+        // Non-critical if branch rename fails
+      }
+    }
+
+    try {
+      cp.execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+      try {
+        cp.execSync('git commit -q -m "chore: initial scaffold from azcodr template"', {
+          cwd: targetDir,
+          stdio: 'ignore'
+        });
+      } catch {
+        cp.execSync('git -c user.name="azcodr" -c user.email="azcodr@local" commit -q -m "chore: initial scaffold from azcodr template"', {
+          cwd: targetDir,
+          stdio: 'ignore'
+        });
+      }
+    } catch {
+      // Non-critical if initial commit fails
+    }
+
     return true;
   } catch {
     return false;
@@ -233,6 +344,7 @@ module.exports = {
   ensureSymlink,
   isSameCaseInsensitiveFile,
   makeScriptsExecutable,
+  isInsideGitWorkTree,
   initGit,
   getTemplateDir,
   TEMPLATE_ITEMS