azcodr 1.1.0 → 1.2.0

package/.agents/skills/lets-build/scripts/bootstrap_workspace.sh

@@ -1,52 +1,84 @@
 #!/usr/bin/env bash
 # ==============================================================================
 # bootstrap_workspace.sh
-# Deterministic Scaffolder for Hexagonal Multi-Tenant Workspaces
+# Topology-Aware Deterministic Scaffolder (Strict YAGNI, Zero Speculative Bloat)
 # ==============================================================================
 
 set -euo pipefail
 
 WORKSPACE_ROOT="${1:-$(pwd)}"
-LANGUAGE="${2:-generic}"
+TOPOLOGY="${2:-backend}"
+LANGUAGE="${3:-generic}"
 
-echo "🚀 Initializing Hexagonal Architecture Workspace in: ${WORKSPACE_ROOT}"
+echo "🚀 Initializing Topology-Aware Workspace in: ${WORKSPACE_ROOT}"
+echo "🏗️ Target Topology: ${TOPOLOGY}"
 echo "📦 Target Language Profile: ${LANGUAGE}"
 echo "--------------------------------------------------------------"
 
-# 1. Create Universal Specification Directories
-echo "1. Scaffolding Contract Specification Directories (specs/)..."
-mkdir -p "${WORKSPACE_ROOT}/specs/protobuf"
-mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
-mkdir -p "${WORKSPACE_ROOT}/specs/schemas"
-mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+case "${TOPOLOGY}" in
+  extension)
+    echo "1. Scaffolding Browser Extension Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/background"
+    mkdir -p "${WORKSPACE_ROOT}/src/content"
+    mkdir -p "${WORKSPACE_ROOT}/src/popup"
+    mkdir -p "${WORKSPACE_ROOT}/src/shared"
+    mkdir -p "${WORKSPACE_ROOT}/public"
+    
+    echo "2. Scaffolding Extension Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/e2e"
+    ;;
 
-# 2. Create Universal Hexagonal Source Directories
-echo "2. Scaffolding Hexagonal Source Tree (src/)..."
-mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
-mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
-mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
-mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
-mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
-mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
-mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+  game|engine)
+    echo "1. Scaffolding Game/Engine Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/core"
+    mkdir -p "${WORKSPACE_ROOT}/src/ecs"
+    mkdir -p "${WORKSPACE_ROOT}/src/renderer"
+    mkdir -p "${WORKSPACE_ROOT}/src/assets"
+    
+    echo "2. Scaffolding Game/Engine Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/benchmarks"
+    ;;
 
-# 3. Create Universal Test Directories
-echo "3. Scaffolding Test Suites (tests/)..."
-mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-mkdir -p "${WORKSPACE_ROOT}/tests/integration"
-mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
-mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+  cli)
+    echo "1. Scaffolding CLI Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/cmd"
+    mkdir -p "${WORKSPACE_ROOT}/src/core"
+    mkdir -p "${WORKSPACE_ROOT}/src/io"
+    
+    echo "2. Scaffolding CLI Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    ;;
 
-# 4. Create Deployment & Infrastructure Directories
-echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
-mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
-mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
-mkdir -p "${WORKSPACE_ROOT}/deploy/k8s"
+  backend|web|saas)
+    echo "1. Scaffolding Backend / Enterprise Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
+    mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
+    mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
+    mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
+    mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
+    mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+    
+    echo "2. Scaffolding Specifications (specs/)..."
+    mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
+    mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+    
+    echo "3. Scaffolding Backend Test Suites (tests/)..."
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
+    mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+    
+    echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
+    mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
+    mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
 
-# 5. Create Default Design Tokens Spec
-TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
-if [[ ! -f "${TOKEN_SPEC}" ]]; then
-  cat << 'EOF' > "${TOKEN_SPEC}"
+    TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
+    if [[ ! -f "${TOKEN_SPEC}" ]]; then
+      cat << 'EOF' > "${TOKEN_SPEC}"
 {
   "color": {
     "brand": {
@@ -62,7 +94,15 @@ if [[ ! -f "${TOKEN_SPEC}" ]]; then
   }
 }
 EOF
-fi
+    fi
+    ;;
+
+  *)
+    echo "1. Scaffolding Generic / Library Source Tree (src/)..."
+    mkdir -p "${WORKSPACE_ROOT}/src"
+    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    ;;
+esac
 
 echo "--------------------------------------------------------------"
-echo "✅ Hexagonal directory tree and contract specifications scaffolded successfully!"
+echo "✅ Topology '${TOPOLOGY}' scaffolded with strict YAGNI (0 speculative folders)!"

package/AGENTS.md

@@ -4,7 +4,7 @@
 > **Rule Zero:** Assume nothing. Every action must be grounded in verified evidence from this workspace or direct instructions from the user.  
 > **Open-Source Mandate:** Always utilize 100% open-source tools, frameworks, libraries, and packages across all architectural domains.  
 > **Atomicity Mandate:** All rules, skills, code units, migrations, and transactions must be strictly atomic (indivisible, self-contained, and composable with full ACID safety).  
-> **Agnostic Mandate:** Decouple domain core from transient technologies, languages, and stacks (Hexagonal Ports & Adapters; zero language bias).
+> **Architecture Mandate:** Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero tool/platform bias). Match architectural style to problem topology (Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Game Loop for canvas games). Never force premature abstractions or universal templates.
 
 ---
 
@@ -14,10 +14,12 @@
 2. **Ground Truth Only:** A statement is only true if proven by a workspace file, verified command output, or direct user instruction.
 3. **Unknown Until Verified:** If something is not explicitly written in the workspace or stated by the user, treat it as unknown.
 4. **Strict Open Standards:** Standardize on open-source solutions and open specs (Semgrep, Trivy, Gitleaks, OpenTelemetry, OPA, OCI, Wasm, CloudEvents).
-5. **Universal Agnosticism:** Core business rules are technology-, language-, and stack-agnostic; runtimes connect via swappable adapters with zero language bias.
-6. **Systemic Atomicity:** Every skill, rule, database transaction, and refactoring step must be atomic (Single Responsibility, zero side-effects, full rollback).
-7. **Workspace Sovereignty:** Total containment within the local workspace root (`./`). Zero interference from global configs, tools, or sibling projects.
-8. **Continuous Learning:** Log all defects, DO's/DONT's, and lessons into `docs/knowledge/` and `memory.md`, dynamically updating atomic rules.
+5. **Problem-First & Topology Alignment:** Problem domain and operational constraints (latency budget, GC tolerance, memory, execution environment) strictly dictate the architectural style and toolchain. Never select tools before defining the problem space.
+6. **Evolutionary Architecture & Refactor-Before-Add:** As complexity grows, code must graduate across explicit architectural tipping points. Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
+7. **True Incremental TDD & Nano-Cycles:** Never dump test suites in batches ("Test-First Waterfall"). Follow Uncle Bob's Three Laws: write one micro-assertion at a time, verify RED failure output, write minimal code to turn GREEN, and refactor under green.
+8. **Systemic Atomicity:** Every skill, rule, database transaction, and refactoring step must be atomic (Single Responsibility, zero side-effects, full rollback).
+9. **Workspace Sovereignty:** Total containment within the local workspace root (`./`). Zero interference from global configs, tools, or sibling projects.
+10. **Continuous Learning:** Ingest all verified defects, lessons, and architectural invariants directly into domain rules and `memory.md`.
 
 ### The 5 Core Branch Questions
 Before acting on any decision branch, answer:
@@ -40,10 +42,10 @@ Before acting on any decision branch, answer:
 
 Progress all tasks systematically through the unified **Agent Cognitive & Agile Domain Lifecycle**, seamlessly interlocking the 5 agent operational disciplines with the 5-phase domain engineering pipeline:
 ```
-1. DISCOVER / REQUIREMENTS   ──► Read-only inspection; INVEST user stories & executable Gherkin scenarios.
-2. INTERROGATE / DOMAIN     ──► Relentless questioning; Ubiquitous Language & domain invariants.
+1. DISCOVER / REQUIREMENTS   ──► Read-only inspection; Problem Space & operational constraints; INVEST stories & Gherkin.
+2. INTERROGATE / DOMAIN     ──► Relentless questioning; Ubiquitous Language, Aggregate invariants & state machines.
 3. PLAN / OUTER TDD         ──► Minimal blast radius; failing Outer Acceptance Test (UI/API RED).
-4. EXECUTE / INNER TDD      ──► Surgical edits; Inner TDD collaborator discovery (RED-GREEN-REFACTOR).
+4. EXECUTE / INNER TDD      ──► Incremental nano-cycles (Uncle Bob's 3 Laws: 1 micro-assertion RED ➔ MINIMAL pass GREEN ➔ REFACTOR).
 5. VERIFY / DoD & PROOF     ──► Outer test turns GREEN; boundary smoke tests & 100.00% test coverage.
 ```
 ---
@@ -99,7 +101,7 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 | **Domain Modeling** | [docs/rules/domain_expertise.md](./docs/rules/domain_expertise.md) | Business capabilities, Aggregate Root invariants, Ubiquitous Language. |
 | **Relentless Questioning** | [docs/rules/relentless_questioning.md](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [docs/rules/workspace_isolation.md](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
-| **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Automated defect post-mortems, DO's/DONT's logging, dynamic rule updates. |
+| **Continuous Learning** | [docs/rules/continuous_learning.md](./docs/rules/continuous_learning.md) | Direct rule ingestion, root-cause analysis, dynamic invariant updates. |
 | **Upstream Sync** | [docs/rules/upstream_synchronization.md](./docs/rules/upstream_synchronization.md) | Logging generic architecture improvements to changes.md; zero baseline pollution. |
 ---
 
@@ -114,5 +116,5 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`lets-build`](.agents/skills/lets-build/SKILL.md): Conducting architecture interviews to finalize stack, frameworks, package managers, and bootstrapping projects.
   - [`relentless-questioner`](.agents/skills/relentless-questioner/SKILL.md): Dynamic context-aware interrogation loops before planning and coding.
 - **Relentless Skill Architecture Inquiry:** Never author or update skills on assumptions. Interrogate all 7 inquiry branches (placement, trigger intent, domain truth, gotchas/anti-patterns, determinism, progressive bloat, verification loop) defined in [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) before writing `SKILL.md`.
-- **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/`](./docs/knowledge/knowledge_graph.md) for system topologies, issue logs, and DO's/DONT's.
+- **Workspace Memory & Knowledge Hub:** Consult [`memory.md`](./memory.md) for ADRs, and [`docs/knowledge/`](./docs/knowledge/knowledge_graph.md) for system topologies and domain glossaries.
 - **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, and `agents.md` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.

package/README.md

@@ -34,11 +34,8 @@
 │       ├── product-analyst/          # INVEST user stories & Gherkin criteria
 │       └── relentless-questioner/    # Context-aware dynamic interrogation loop
 ├── docs/
-│   ├── knowledge/                    # Institutional knowledge & token economy
-│   │   ├── dos_and_donts.md          # Consolidated DO's and DONT's directory
-│   │   ├── issue_log.md              # Defect post-mortems & preventing rules
+│   ├── knowledge/                    # Institutional knowledge & domain contracts
 │   │   ├── knowledge_graph.md        # Visual topologies & fast-lookup matrices
-│   │   ├── lessons_learned.md        # Strategic architectural takeaways
 │   │   └── ubiquitous_language.md    # Living Ubiquitous Language glossary template
 │   └── rules/                        # 47 atomic single-responsibility domain rules
 ├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
@@ -177,8 +174,6 @@ Once confirmed, the agent automatically executes:
 ## 🏛️ Workspace Memory & Knowledge Hub
 
 - 🗺️ **[System Knowledge Graph](./docs/knowledge/knowledge_graph.md)**: Visual subsystem topologies and entity-relationship models.
-- 📋 **[Consolidated DO's & DONT's](./docs/knowledge/dos_and_donts.md)**: High-impact engineering invariants and anti-patterns to avoid.
-- 🐛 **[Coding Issue Log](./docs/knowledge/issue_log.md)**: Defect post-mortems and preventative rules.
-- 💡 **[Institutional Lessons Learned](./docs/knowledge/lessons_learned.md)**: Strategic engineering insights.
-- 📜 **[Lightweight ADR Ledger](./memory.md)**: Formal Architectural Decision Records.
+- 📖 **[Living Ubiquitous Language Glossary](./docs/knowledge/ubiquitous_language.md)**: Authoritative domain vocabulary contract.
+- 📜 **[Lightweight ADR Ledger](./memory.md)**: Formal Architectural Decision Records and governing rules.
 - 📝 **[Upstream Changes Ledger](./changes.md)**: Record candidate improvements and generic patterns for the upstream azcodr template.

package/changes.md

@@ -48,3 +48,15 @@ When an AI agent or engineer discovers a generic architectural improvement, bug
 - **Rationale:** Ensure flawless cross-platform and multi-version Node execution across macOS, Windows, and Linux on Node 18, 20, 22, 24.
 - **Description:** Untracked agents.md from Git to prevent cyclic symlink overwrite on case-insensitive filesystems; hardened ensureSymlink with isSameCaseInsensitiveFile check; added cross-version test coverage runner script; updated npm test runner to use native discovery.
 - **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+
+### [2026-09-25] Problem-First Architecture, Evolutionary Tipping Points, and Incremental Nano-Cycle TDD
+- **Category:** Architecture, Rule & Skill
+- **Target File(s):** `AGENTS.md`, `docs/rules/clean_code.md`, `docs/rules/domain_driven_design.md`, `docs/rules/test_driven_development.md`, `.agents/skills/lets-build/SKILL.md`, `.agents/skills/lets-build/references/architecture_interview_matrix.md`, `.agents/skills/lets-build/scripts/bootstrap_workspace.sh`, `memory.md`
+- **Rationale:** Eliminate tool-first bias ("Solution-in-Search-of-a-Problem"), stop accidental complexity (as seen in `force-dark-light` where Chrome extension received Kubernetes and OpenAPI specs), prevent AI-accelerated architectural drift, and halt the "Test-First Waterfall" batch-test anti-pattern.
+- **Description:** 
+  1. Enforced Problem Space vs Solution Space decoupling with zero tool bias.
+  2. Made scaffolding strictly topology-aware (Web SaaS, Browser Extension, Game/Engine, CLI, Library) with zero speculative bloat.
+  3. Codified Evolutionary Architecture, the 5 Architectural Tipping Points, and Kent Beck's "Refactor-Before-Add" protocol.
+  4. Codified Uncle Bob's Three Laws of TDD, banned batch-test dumps, and introduced the Incremental Nano-Cycle and Ping-Pong Pair Programming protocol.
+- **Domain Filter Verification:** Verified 100% generic; applicable across any language, stack, and project topology.
+

package/docs/rules/api_versioning.md

@@ -111,18 +111,3 @@ specs/
 │       └── openapi.yaml
 ```
 
----
-
-## 5. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Prefix all public REST endpoints with major version identifiers (`/api/v1/`, `/api/v2/`).
-- **DO:** Bump MAJOR and cut a new `/api/v2/` prefix whenever request or response breaking changes occur.
-- **DO:** Inject RFC 8594 `Sunset` and `Deprecation` headers on all retired endpoints and provide a 90-day grace period.
-- **DO:** Organize specs into versioned folders (`specs/openapi/v1/`, `v2/`) with an interactive Swagger selector.
-
-### DONT's:
-- **DONT:** Never expose minor or patch numbers in the URL path (e.g. `/api/v1.2/`).
-- **DONT:** Never introduce breaking schema or status code changes within an existing major version.
-- **DONT:** Never delete an active endpoint without a formal deprecation lifecycle.
-

package/docs/rules/clean_code.md

@@ -23,3 +23,40 @@
 - **Orthogonality**: Eliminate coupling between unrelated modules. Changing one component must not cascade unexpected side effects into another.
 - **Broken Windows Theory**: Never leave bad code, failing lint checks, or out-of-date documentation unfixed. Fix defects immediately before entropy normalizes.
 - **Design by Contract (DbC)**: Define explicit preconditions (runtime boundary validation), postconditions (guaranteed response envelopes), and domain invariants.
+
+---
+
+## 3. Evolutionary Architecture & Architectural Tipping Points (Ford, Parsons & Fowler)
+
+Architecture is not a static Day 1 monument; it evolves incrementally as complexity grows. AI coding tools naturally take the path of least resistance (local token minimization), repeatedly appending code to simple files until they rot into a Big Ball of Mud. To eliminate **AI-Accelerated Architectural Drift**, the agent must pause and execute an architectural upgrade whenever code hits a **Deterministic Tipping Point**:
+
+| Simple Baseline (Day 1) | Tipping Point / Mutation Trigger | Required Architectural Upgrade |
+|---|---|---|
+| **Flat Script / Single File** | File exceeds **250 lines**, or coordinates **>2 distinct I/O resources**, or is imported by **>3 distinct callers**. | **Extract Modular Subsystems:** Decouple domain logic from platform I/O; split into dedicated, focused submodules. |
+| **Inline `if/else` or `switch` Cascades** | **Rule of Three:** The 3rd branching variant, payment provider, or protocol format is introduced. | **Strategy Pattern / Registry:** Replace conditional branching with a polymorphic Strategy interface or handler registry; update `memory.md`. |
+| **In-Memory Store / Global State** | State requires **concurrent mutations**, **persistence across process restarts**, or **transactional rollback**. | **Repository Pattern & Persistence Port:** Introduce an explicit storage port contract; swap in-memory mock for a persistent database adapter. |
+| **Direct Platform / Third-Party Calls** | External SDK or platform API is called from **>2 places**, or SDK throws untyped exceptions across boundaries. | **Adapter Pattern (Anti-Corruption Layer):** Wrap external SDK inside an application-owned port interface; mock only the owned interface in tests. |
+| **Monolithic Domain Model** | The same business noun represents divergent lifecycles or definitions across workflows (e.g. `User` in Auth vs `User` in Billing). | **Bounded Context Split:** Separate into isolated domain contexts with explicit DTO / Anti-Corruption translation between them. |
+
+---
+
+## 4. The "Refactor-Before-Add" Protocol (Kent Beck's Rule)
+
+> *"Make the change easy (warning: this may be hard), then make the easy change."* — Kent Beck
+
+Before writing production code for any new feature or user story, the agent must execute the **Refactor-Before-Add Check**:
+1. **Assess Tipping Points**: Will adding this requirement cause any module, function, or data structure to cross an architectural tipping point?
+2. **Phase A — Structural Refactoring (Under Green)**: If yes, refactor the existing architecture *first* while existing test suites remain 100% green. Zero behavioral changes; purely structural evolution.
+3. **Phase B — ADR Mutation**: When an architectural tipping point is crossed, log a Lightweight Architectural Decision Record in `memory.md` summarizing the new structural boundary and trade-off.
+4. **Phase C — Feature Implementation (Inner TDD)**: Only once the architecture cleanly accommodates the new capability, write the failing micro-test and implement the feature.
+
+---
+
+## 5. Architectural Fitness Functions (Automated Tripwires)
+
+Prevent AI-generated code rot using automated fitness functions integrated into linting and continuous verification:
+- **File Length Gates**: Maximum 250–300 lines per file (ESLint `max-lines`).
+- **Function Length Gates**: Maximum 20–30 lines per function (ESLint `max-lines-per-function`).
+- **Dependency Direction Gates**: Enforce unidirectional import rules (e.g. `import/no-restricted-paths`, `dependency-cruiser`, `ArchUnit`) ensuring domain core never imports infrastructure or transport adapters.
+- **Complexity Budgets**: Enforce cyclomatic complexity limits (maximum 10 per function).
+If an AI attempt to add code violates any fitness function, the build fails immediately, blocking completion until the architecture is refactored.

package/docs/rules/continuous_learning.md

@@ -1,29 +1,30 @@
 # Continuous Learning & Automated Rule Ingestion
 
-> **Core Mandate:** Automatically log development defects, post-mortems, and lessons learned into workspace memory, dynamically updating or generating atomic rules to permanently prevent recurrence.
+> **Core Mandate:** Automatically capture development defects, analyze root causes, and directly update domain rules or skills to permanently prevent recurrence without intermediate bloat.
 
 ---
 
-## 1. The Automated Rule Ingestion Loop
+## 1. The Direct Rule Ingestion Loop
 
-Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 5-step loop:
+Whenever an error, test failure, build friction, or architectural anti-pattern occurs during development, immediately execute the 4-step loop:
 
 ```
-1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Log Post-Mortem ──► 4. Synthesize Rule ──► 5. Update Rulebase
+1. Capture Defect ──► 2. Root Cause Analysis ──► 3. Synthesize Invariant ──► 4. Update Rule / Skill
 ```
 
-1. **Capture Defect**: Record the failure symptoms and stack trace.
+1. **Capture Defect**: Record the failure symptoms, stack trace, and failing test case.
 2. **Root Cause Analysis**: Identify the fundamental architectural or operational gap (not just the surface symptom).
-3. **Log Post-Mortem**: Append an entry to [`docs/knowledge/issue_log.md`](../knowledge/issue_log.md) documenting Symptom, Root Cause, Anti-Pattern, and Resolution.
-4. **Synthesize Rule**: Formulate the preventative DO and DONT directives and add them to [`docs/knowledge/dos_and_donts.md`](../knowledge/dos_and_donts.md).
-5. **Update Rulebase**:
-   - If the issue falls under an existing domain rule in `docs/rules/<domain>.md`, update that rule immediately.
-   - If it represents a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
-   - Run the configuration validation script to ensure integrity.
+3. **Synthesize Invariant**: Formulate a concrete, positive architectural invariant and code example showing the correct implementation.
+4. **Update Rule / Skill**:
+   - Update the governing domain rule in `docs/rules/<domain>.md` or specialized skill in `.agents/skills/` directly.
+   - If the lesson introduces an architectural trade-off or paradigm shift, record a lightweight ADR in [`memory.md`](../../memory.md).
+   - If it unlocks a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
+   - Run verification (`npm test && npm run validate`) to ensure 100% integrity.
 
 ---
 
 ## 2. Institutional Memory Maintenance
 
-- **ADR Synchronization**: Major technical decisions must be logged in [`memory.md`](../../memory.md) before or immediately upon implementation.
-- **Knowledge Graph Updates**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, database models, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.
+- **Lightweight ADR Ledger**: Major technical decisions and invariant shifts are logged in [`memory.md`](../../memory.md) linking directly to the governing rule or skill.
+- **System Knowledge Graph**: Keep [`docs/knowledge/knowledge_graph.md`](../knowledge/knowledge_graph.md) synchronized with new services, ports, or adapters to avoid repetitive token-expensive codebase discovery in future sessions.
+- **Living Glossary**: Keep [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md) updated with canonical domain terminology and forbidden synonyms.

package/docs/rules/database_integrity.md

@@ -69,20 +69,12 @@ Pure financial ledgers (e.g. `PaymentLedgerEntry`, `JournalEntry`) and event out
 
 ---
 
-## 6. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Include the canonical total audit fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`) on every mutable entity model.
-- **DO:** Populate `createdBy`, `updatedBy`, and `deletedBy` from the verified session actor (`req.user.id`), falling back explicitly to `'SYSTEM'` only for background daemons or public bootstrap.
-- **DO:** Default foreign keys to `RESTRICT` for root aggregates and financial ledgers to prevent accidental cascading data loss.
-- **DO:** Enforce foreign key validation in use cases before persistence, returning RFC 7807 problem details if referenced records do not exist.
-- **DO:** Render foreign key associations using relational selectors (`shadcn/ui` `<Select>`) showing human-readable business metadata (names, labels, numbers, emails).
-- **DO:** Ensure every entity/feature implements full lifecycle CRUD (Create, Read/Detail, Update/Status Transition, Delete/Archive) before considering it complete.
-- **DO:** Filter active records with `WHERE deleted_at IS NULL` and pair uniqueness with partial indexes (`WHERE deleted_at IS NULL`).
-
-### DONT's:
-- **DONT:** Never create a database table or entity without `createdAt` and `createdBy`.
-- **DONT:** Never omit `updatedBy` or `deletedBy` on mutable tables. Every mutation and deletion must have an accountable actor.
-- **DONT:** Never expose raw string text inputs for foreign key identifiers in the user interface.
-- **DONT:** Never consider a feature complete if it only implements creation or listing without update, transition, or deletion capabilities.
-- **DONT:** Never allow cascading deletes on master entities with dependent transactional history.
+## 6. Semi-Structured Evolution & Cryptographic Audit Trails
+
+- **Non-Destructive Schema Evolution via JSON**: For contractual covenants, dynamic conditions, or variable metadata subject to rapid domain iteration, employ semi-structured JSON fields (`termsJson`, `metadataJson`) validated against JSON Schema rather than premature table migrations.
+- **Cryptographic Electronic Signatures & Execution Auditing**: Legal agreements and execution records require defensible evidence beyond a boolean `isSigned` flag. All executed agreements must capture:
+  1. Typed signer legal name and designated role.
+  2. ISO 8601 UTC execution timestamp.
+  3. Authenticated actor ID (`userId`).
+  4. Client network IP address and User-Agent string.
+  5. Deterministic cryptographic checksum / hash of the executed terms.

package/docs/rules/design_patterns.md

@@ -10,6 +10,7 @@
 - **Factory Method**: Encapsulate complex collaborator instantiation (e.g. tenant-specific payment gateways or notification dispatchers) behind factory functions.
 - **Facade Pattern**: Expose a unified, simplified interface to complex underlying multi-service subsystems.
 - **Decorator / Middleware**: Compose cross-cutting concerns (observability, authentication, tenant context resolution, rate limiting) via middleware pipelines.
+- **Dependency Injection & Composition Hygiene**: Application factories (`createApp(deps)`) must accept an explicit composite container (`AppDependencies`). Never provide silent default fallback instances inside factories that instantiate disconnected repositories or services when partial dependencies are passed (the Split-Brain Anti-Pattern). Assemble the full dependency graph explicitly at the composition root.
 
 ---
 

package/docs/rules/domain_driven_design.md

@@ -1,10 +1,35 @@
 # Domain-Driven Design (DDD) & Ubiquitous Language
 
-> **Core Mandate:** Establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement across all architectural layers, and separate Value Objects, Entities, and Aggregates.
+> **Core Mandate:** Separate Problem Space from Solution Space, establish unambiguous Ubiquitous Language definitions, isolate Bounded Contexts, guarantee Domain-Code Language Agreement, and protect Aggregate invariants.
 
 ---
 
-## 1. Domain-Code Language Agreement
+## 1. Problem Space vs. Solution Space (Evans & Vernon)
+
+Software engineering fails when teams jump directly into the **Solution Space** (choosing languages, frameworks, databases, and microservices) before fully defining the **Problem Space**.
+
+```
+  ┌────────────────────────────────────────────────────────────────────────┐
+  │                           THE PROBLEM SPACE                            │
+  │  Business Problem ➔ Subdomains (Core/Supporting/Generic) ➔ Invariants  │
+  │  Operational Constraints: Execution target, Latency budget, GC limits  │
+  └───────────────────────────────────┬────────────────────────────────────┘
+                                      │ Shapes & Dictates
+                                      ▼
+  ┌────────────────────────────────────────────────────────────────────────┐
+  │                           THE SOLUTION SPACE                           │
+  │  Bounded Contexts ➔ Architectural Style (DOD, Hexagonal, Pipeline)      │
+  │  Emergent Toolchain: Programming Language, Runtime, Persistence        │
+  └────────────────────────────────────────────────────────────────────────┘
+```
+
+- **The Problem Space (The Essence - Fred Brooks):** Concerns *what* problem is being solved, the entities, state transitions, and operational constraints (e.g. 16.6ms frame budget for games, zero-install browser sandbox for extensions, or ACID compliance for banking). **Zero technology, stack, or database choices are permitted in the Problem Space.**
+- **The Solution Space (The Accidents):** Concerns *how* the system is realized. Runtimes, programming languages (C, Rust, TS, Go, Java), and storage engines are **emergent outputs** derived strictly from Problem Space constraints.
+- **The Golden Hammer Anti-Pattern:** Selecting tools (e.g., "Let's use Next.js and PostgreSQL") before mapping problem constraints forces the domain to fit the tool, creating massive accidental complexity.
+
+---
+
+## 2. Domain-Code Language Agreement
 
 The fundamental premise of Domain-Driven Design (Eric Evans) is that **the code is the model, and the model is the code**. Any divergence between the mental model of domain experts and the source code is called **Linguistic Drift**.
 
@@ -16,7 +41,7 @@ The fundamental premise of Domain-Driven Design (Eric Evans) is that **the code
 
 ---
 
-## 2. Living Ubiquitous Language Glossary
+## 3. Living Ubiquitous Language Glossary
 
 Every project must maintain an authoritative, version-controlled **Living Ubiquitous Language Glossary** at [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md).
 
@@ -30,7 +55,7 @@ Each entry must define:
 
 ---
 
-## 3. Automated Enforcement & Linters
+## 4. Automated Enforcement & Linters
 
 To prevent linguistic drift over time, teams must employ mechanical enforcement:
 
@@ -60,25 +85,10 @@ Acceptance criteria must be written strictly in Ubiquitous Language, serving as
 
 ---
 
-## 4. Tactical Patterns & Invariants
+## 5. Tactical Patterns & Invariants
 
 1. **Entities**: Objects defined by identity that persists across state changes (e.g. `User`, `Order`, `Invoice`).
 2. **Value Objects**: Immutable objects defined strictly by their attributes with no identity (e.g. `Money`, `DateRange`, `EmailAddress`).
 3. **Aggregates & Aggregate Roots**: Clusters of domain objects treated as a single transactional consistency boundary. All mutations must pass through explicit methods on the Aggregate Root.
 4. **Anti-Corruption Layer (ACL)**: When integrating with third-party APIs or legacy systems that use different terminology, translate external payloads into the internal Ubiquitous Language at the boundary adapter before they enter the domain core.
-
----
-
-## 5. Invariants (DO's & DONT's)
-
-### DO
-- **DO** use identical terminology in domain conversations, PRDs, code, database schemas, and user interfaces.
-- **DO** maintain an authoritative `ubiquitous_language.md` and treat it as a binding architectural contract.
-- **DO** use branded nominal types for IDs to catch cross-entity domain mixups at compile time.
-- **DO** translate foreign data structures at the perimeter using an Anti-Corruption Layer (ACL).
-
-### DONT
-- **DONT** use technical jargon (`dto`, `entity_row`, `table_item`) in domain business logic.
-- **DONT** allow competing synonyms for the same concept within the same Bounded Context.
-- **DONT** overload words with dual meanings across technical architecture and business domain.
-- **DONT** rename domain terms in code without updating the living glossary and recording an ADR.
+5. **Cross-Aggregate Coordination in Use Cases**: While an Aggregate Root guards its own internal invariants, business operations frequently span multiple aggregates (e.g. reserving an inventory item for an agreement). Application use cases or orchestrators must coordinate aggregate transitions atomically: asserting resource availability prior to state change, transitioning the constrained entity (e.g. `ALLOCATED`), and restoring state (`AVAILABLE`) upon cancellation, avoiding double-allocation race conditions without coupling aggregates directly.

package/docs/rules/error_handling.md

@@ -1,6 +1,6 @@
 # Error Handling, Request Tracing & Schema Validation
 
-> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, and standardized RFC 7807 / REST error envelopes.
+> **Core Mandate:** Enforce fail-fast schema validation at startup, structured OpenTelemetry/JSON request tracing, standardized RFC 7807 problem details, and an explicit canonical DomainError hierarchy.
 
 ---
 
@@ -37,3 +37,16 @@ Enforce a uniform error envelope across all external HTTP/REST endpoints conform
 ```
 
 - **Production Masking Invariant**: Strictly mask internal database error codes, raw SQL queries, file system paths, and stack traces from external client responses in non-local environments.
+
+---
+
+## 4. Canonical Domain Error Hierarchy & Type-Safe Narrowing
+
+- **Canonical DomainError Hierarchy**: Model operational domain failures using an explicit `DomainError` base class with canonical subclasses:
+  - `ValidationError` (maps to HTTP 400 / 422)
+  - `UnauthorizedError` (maps to HTTP 401)
+  - `ForbiddenError` (maps to HTTP 403)
+  - `NotFoundError` (maps to HTTP 404)
+  - `ConflictError` (maps to HTTP 409)
+  - `ExpiredError` (maps to HTTP 410)
+- **Eliminate Untyped Error Monkey-Patching**: Strictly prohibit monkey-patching arbitrary properties onto error objects at catch sites (e.g. `(err as any).statusCode = 404`). Use clean `instanceof` narrowing in HTTP error middleware to map domain errors deterministically to RFC 7807 status codes with full compiler type safety.

package/docs/rules/multitenancy_isolation.md

@@ -14,6 +14,8 @@ Resolve tenant identity dynamically in an inbound gateway or middleware pipeline
 
 *Validation:* If the resolved tenant does not exist or is in `SUSPENDED` status, immediately return **`403 Forbidden`** (`TENANT_SUSPENDED` or `TENANT_INVALID`). Propagate `TenantContext` across service calls using standard W3C Baggage headers or request contexts.
 
+- **Fail-Closed Multi-Tenancy Invariant**: Never trust client-supplied tenant headers (`X-Tenant-ID`) without cryptographically verifying that the authenticated session actor actually belongs to the requested tenant organization/workspace. Mismatched tenant headers must immediately fail closed with HTTP 403 `FORBIDDEN_TENANT_ACCESS`.
+
 ---
 
 ## 2. Four Universal Data Isolation Models

package/docs/rules/product_ownership.md

@@ -130,21 +130,3 @@ Following Gunther Verheyen's backlog topology, the Product Backlog serves as an
 1. **Single & Ordered:** Exactly one backlog exists per product.
 2. **Dynamic Splitting:** As coarse items approach the top of the backlog, they must be split into fine, sprintable INVEST slices.
 3. **Continuous Pruning:** Items may be reordered, added, split, or permanently deleted at any time based on empirical learning. If an item lingers at the bottom of the backlog for months without business justification, remove it.
-
----
-
-## 6. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Formulate a clear, inspiring Product Goal that guides all backlog prioritization.
-- **DO:** Ground prioritization in quantitative models (RICE, Kano, MoSCoW) rather than executive opinion.
-- **DO:** Measure outcomes (satisfaction gap closure, conversion, retention) instead of pure output (story points, lines of code).
-- **DO:** Explicitly state what will NOT be done (Won't Have this time) to preserve engineering focus.
-- **DO:** Ensure every sprint increment complies 100% with the Definition of Done.
-
-### DONT's:
-- **DONT:** Never confuse output (features shipped) with outcome (value realized).
-- **DONT:** Never treat OKRs as a task checklist; Key Results must be measurable outcomes.
-- **DONT:** Never prioritize speculative features when core "Must-be" baseline capabilities are unfulfilled.
-- **DONT:** Never maintain separate, disconnected backlogs for the same product.
-- **DONT:** Never deliver "un-done" work carrying forward technical debt.

package/docs/rules/project_management.md

@@ -47,20 +47,3 @@ A user story or task is only marked `DONE` when all of the following verifiable
 
 - If a blocker or ambiguity arises, immediately transition the task to `BLOCKED`, halt execution, and interrogate the root cause.
 - Never guess or write speculative code to bypass an unresolved requirement.
-
----
-
-## 5. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Maintain strict WIP = 1 limit. Never work on multiple active tasks concurrently.
-- **DO:** Deliver features in vertical slices (UI ➔ API ➔ Domain ➔ DB) rather than isolated horizontal stubs.
-- **DO:** Apply SMART criteria to developer tasks, time-boxing them to under 4 hours.
-- **DO:** Halt and transition to `BLOCKED` whenever assumptions are required.
-- **DO:** Satisfy all 7 criteria of the Definition of Done before declaring any increment complete.
-
-### DONT's:
-- **DONT:** Never mark a task `DONE` with skipped, failing, or unwritten tests.
-- **DONT:** Never bypass the 5-Phase Agile Domain Lifecycle provenance gate.
-- **DONT:** Never create untracked, open-ended developer tasks without measurable completion tests.
-- **DONT:** Never leave unresolved blockers or silent errors in working branches.

package/docs/rules/react.md

@@ -72,17 +72,7 @@
 
 ---
 
-## 5. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Use `shadcn/ui` components backed by `@radix-ui` primitives for all interactive elements.
-- **DO:** Use `@tanstack/react-query` (`useQuery`, `useMutation`) for all server data fetching, caching, and mutation invalidation.
-- **DO:** Validate all form inputs using formal Zod schemas and `react-hook-form` / `tanstack-form`.
-- **DO:** Display user feedback and errors using accessible ARIA live regions (`role="alert"` for errors, `role="status"` for confirmations) and `<ConfirmDialog>`.
-- **DO:** Synchronize pagination, active tabs, and search filters into URL search parameters.
-
-### DONT's:
-- **DONT:** Never use `window.alert()` or `window.confirm()`.
-- **DONT:** Never fetch data in raw `useEffect` hooks with manual `loading` / `error` boolean state.
-- **DONT:** Never manage multi-field forms using raw `useState` and manual imperative string validations.
-- **DONT:** Never use unstyled raw HTML select or dialog elements when `shadcn/ui` components exist.
+## 5. Theme Architecture & Design Token Completeness
+
+- **Symmetric Design Tokens**: Ensure foundational CSS variables (`--background`, `--foreground`, `--card`, `--border`, `--popover`) are symmetrically declared across `:root` and `.dark`. Omitted root tokens in `.dark` result in unstyled backgrounds and illegible text when switching themes.
+- **System Preference Detection & Reactive Synchronization**: `ThemeProvider` implementations must listen to `window.matchMedia('(prefers-color-scheme: dark)')` with dynamic event listeners so OS appearance toggles seamlessly propagate in real-time, and synchronize `document.documentElement.style.colorScheme = resolvedTheme` to ensure browser-native elements (scrollbars, input widgets) match the active theme.

package/docs/rules/requirements_engineering.md

@@ -94,20 +94,3 @@ Scenario: Successful Digital Agreement Execution
   - `422 Unprocessable Entity`: Semantic domain invariant violations.
   - `429 Too Many Requests`: Rate limiter token exhaustion.
   - `500 Internal Server Error`: Unhandled upstream infrastructure failures.
-
----
-
-## 5. Invariants, DO's & DONT's
-
-### DO's:
-- **DO:** Embody Ron Jeffries' 3 C's (Card, Conversation, Confirmation) for all user-facing stories.
-- **DO:** Slice user stories vertically through all layers (UI ➔ API ➔ Domain ➔ DB).
-- **DO:** Model technical constraints, invariants, and spikes as explicit non-story requirements.
-- **DO:** Write Gherkin scenarios with active voice covering happy and unhappy paths.
-- **DO:** Map edge cases to standard HTTP status codes and RFC 7807 problem details.
-
-### DONT's:
-- **DONT:** Never write horizontal technical stories that lack end-user observable value.
-- **DONT:** Never treat user stories as complete formal specification documents.
-- **DONT:** Never omit negative scope (out-of-scope / non-goals) in requirements.
-- **DONT:** Never skip edge cases or map errors to ambiguous status codes.