azcodr 1.0.1 → 1.2.0

package/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh

@@ -45,21 +45,37 @@ if [[ -L "${CLAUDE_FILE}" ]]; then
   else
     log_fail "CLAUDE.md points to '${TARGET}' instead of 'AGENTS.md'."
   fi
+elif [[ -f "${CLAUDE_FILE}" ]] && [[ "$(< "${CLAUDE_FILE}")" == "AGENTS.md" ]]; then
+  log_pass "CLAUDE.md is a text pointer to AGENTS.md (symlink fallback)."
 else
   log_fail "CLAUDE.md is not a symbolic link."
 fi
 
-# Check agents.md symlink
+# Check agents.md symlink (case-insensitive filesystem aware)
 AGENTS_LOWER="${WORKSPACE_ROOT}/agents.md"
-if [[ -L "${AGENTS_LOWER}" ]]; then
-  TARGET=$(readlink "${AGENTS_LOWER}")
-  if [[ "${TARGET}" == "AGENTS.md" ]]; then
-    log_pass "agents.md is a valid symlink to AGENTS.md."
+IS_CASE_INSENSITIVE=false
+if [[ "$(uname -s)" == "Darwin" ]] || [[ "$(uname -s)" =~ (MINGW|MSYS|CYGWIN) ]]; then
+  IS_CASE_INSENSITIVE=true
+elif [[ -f "${AGENTS_FILE}" ]] && [[ -f "${AGENTS_LOWER}" ]] && [[ ! -L "${AGENTS_LOWER}" ]]; then
+  IS_CASE_INSENSITIVE=true
+fi
+
+if [[ "${IS_CASE_INSENSITIVE}" == "true" ]]; then
+  log_pass "agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem)."
+else
+  if [[ ! -L "${AGENTS_LOWER}" ]] && [[ ! -e "${AGENTS_LOWER}" ]] && [[ -f "${AGENTS_FILE}" ]]; then
+    ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+  fi
+  if [[ -L "${AGENTS_LOWER}" ]]; then
+    TARGET=$(readlink "${AGENTS_LOWER}")
+    if [[ "${TARGET}" == "AGENTS.md" ]]; then
+      log_pass "agents.md is a valid symlink to AGENTS.md."
+    else
+      log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    fi
   else
-    log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    log_fail "agents.md is not a symbolic link."
   fi
-else
-  log_fail "agents.md is not a symbolic link."
 fi
 
 # 2. Checking Progressive Disclosure Rules (docs/rules)

package/.agents/skills/lets-build/SKILL.md

@@ -3,9 +3,9 @@ name: lets-build
 description: Use when initializing or bootstrapping a new project from this template workspace, or when the user invokes '/lets-build' to conduct deep research and relentless questioning across language, stack, frameworks, package managers, databases, and architectural layers, followed by scaffolding the finalized project. Do not use for routine bug fixing, editing existing code features, or auditing already bootstrapped projects.
 ---
 
-# Let's Build: Interactive Architecture Research & Project Bootstrapper
+# Let's Build: Problem-First Architecture Research & Project Bootstrapper
 
-> **Core Purpose:** Conduct an exhaustive, relentless architectural interview across all 18 systemic dimensions to finalize technical choices (language, runtime, frameworks, package managers, databases, tenancy, auth, workflows, observability, CI/CD) with zero assumptions, synthesize an approved ADR, and bootstrap the project following strict Hexagonal architecture.
+> **Core Purpose:** Conduct an exhaustive, problem-first architectural interview across domain essence, physical constraints, and system topology to derive technical choices (language, runtime, frameworks, build tools, architectural style) with zero assumptions, synthesize an approved ADR, and bootstrap a lean, strictly YAGNI project foundation.
 
 ---
 
@@ -27,50 +27,53 @@ description: Use when initializing or bootstrapping a new project from this temp
 Progress through five mandatory stages:
 
 ```
-1. DISCOVER (Toolchain & Root) ──► 2. INTERROGATE (Relentless Interview) ──► 3. SYNTHESIZE (ADR & Blueprint) ──► 4. BOOTSTRAP (Scaffold Code) ──► 5. VERIFY (Prove Health)
+1. DISCOVER (Toolchain & Root) ──► 2. INTERROGATE (Problem-First Interview) ──► 3. SYNTHESIZE (ADR & Blueprint) ──► 4. BOOTSTRAP (Topology Scaffolding) ──► 5. VERIFY (Prove Health)
 ```
 
 ---
 
 ### Phase 1: Discover (Toolchain & Workspace Inspection)
 1. Inspect the workspace root: confirm whether this is a fresh copy or an existing codebase.
-2. Check for pre-installed development runtimes and CLI tools (`go`, `rustc`/`cargo`, `python3`/`uv`, `node`/`pnpm`, `docker`, `atlas`, `semgrep`).
+2. Check for pre-installed development runtimes and CLI tools (`go`, `rustc`/`cargo`, `python3`/`uv`, `node`/`pnpm`, `docker`, `semgrep`).
 3. Verify that `AGENTS.md`, `memory.md`, and `docs/rules/` exist and remain intact.
 
 ---
 
-### Phase 2: Interrogate (The Relentless Architecture Interview)
+### Phase 2: Interrogate (The Problem-First Architecture Interview)
 Do NOT guess or assume any technology or stack choice. Execute the relentless interrogation using [references/architecture_interview_matrix.md](./references/architecture_interview_matrix.md). Group questions logically into digestible batches:
 
-#### Batch 1: Domain, Performance & Language
-1. **Domain & Problem Statement:** What is the business problem, expected scale (RPS, active tenants), and compliance requirements (SOC 2, ISO 27001, GDPR)?
-2. **Primary Programming Language & Runtime:** Go, Rust, Python, TypeScript, Java/Kotlin, C#, or Polyglot microservices?
-3. **Package Manager & Toolchain:** Specific package manager (e.g. `uv` vs `poetry`, `cargo`, `pnpm`, `go modules`) and task runner?
-
-#### Batch 2: Transports, Protocols & Persistence
-4. **Transport & Network:** REST (OpenAPI 3.1), gRPC (Protobuf v3 via `buf`), GraphQL, or Event-Driven? Which web/transport framework?
-5. **Database & Storage Engine:** Relational (PostgreSQL, MySQL, CockroachDB, SQLite) vs Document (MongoDB) vs Hybrid? ORM vs Query Builder vs raw SQL? Canonical 6 Total Audit Fields?
-6. **Database Migration Tooling:** Declarative migrations (**Atlas**) vs versioned SQL (**Flyway**, **Liquibase**, **Goose**)?
-7. **Multi-Tenancy Isolation Model:** AST query interceptor, Database RLS, Schema-per-tenant, or Database-per-tenant?
-8. **Dynamic Schemas & Extensibility:** Universal **JSON Schema Draft 2020-12** in semi-structured columns, EAV, or virtual columns?
-
-#### Batch 3: Pluggable Logic, Security & Identity
-9. **Dynamic Business Logic:** Common Expression Language (CEL), GoF Strategy registries, or WebAssembly (Extism) sandboxes?
-10. **Workflow Orchestration:** Temporal.io durable execution vs Camunda/Zeebe (BPMN 2.0) vs statecharts?
-11. **Authentication & Identity:** OIDC, OAuth 2.1 with PKCE, Passkeys (FIDO2/WebAuthn), PASETO, or JWT with JWKS rotation?
-12. **Authorization Engine:** Open Policy Agent (OPA Rego via HTTP/Wasm), OpenFGA (Zanzibar ReBAC), or Cerbos?
-
-#### Batch 4: Presentation, Infrastructure & Quality
-13. **Frontend & Presentation:** Web (React/Vue/Svelte/Web Components), Mobile (Flutter/Native), Server-Driven UI (SDUI), and W3C DTCG Design Tokens?
-14. **Caching & Locks:** Redis, Valkey, Dragonfly, Memcached, or local LRU with XFetch stampede defense?
-15. **Event Streaming:** Apache Kafka, NATS JetStream, RabbitMQ, SQS, with Transactional Outbox?
-16. **Observability:** OpenTelemetry OTLP traces/metrics/logs over gRPC/HTTP with W3C trace context?
-17. **DevSecOps & Verification:** Semgrep SAST, Gitleaks, Trivy scanning, CycloneDX SBOM, Cosign, and Outside-In TDD (London School) with 100% coverage gates?
-18. **Containerization & Deployment:** Minimal OCI Distroless/Scratch, Docker Compose, Kubernetes, and OpenTofu IaC?
-
-#### Batch 5: Lifecycles, State Machines & Ubiquitous Language
-19. **State Invariant Separation:** Core Invariant States (Hard FSM in Aggregate Root) vs Tenant-Configurable Operational Workflow Stages (Soft FSM via transition matrices and CEL guards)?
-20. **Ubiquitous Language Agreement:** Living glossary contract (`ubiquitous_language.md`) with AST linter denylists and branded nominal types?
+#### Batch 1: Problem Space & System Topology
+1. **Domain & Problem Statement:** What real-world problem or capability does this system solve? What data moves, and what transformations occur?
+2. **System Topology Classification:** Which topology best matches the execution target?
+   - Topology A: Web SaaS / Cloud Microservices
+   - Topology B: Browser Extension (Manifest V3)
+   - Topology C: Game Engine / High-Performance Simulator (Bare metal, GPU)
+   - Topology D: Browser / Canvas Game (HTML5 Canvas / WebGL / WebGPU)
+   - Topology E: Desktop Application / CLI Utility (Native POSIX/Windows)
+   - Topology F: Embedded / Systems Library
+
+#### Batch 2: Operational & Physical Constraints (The Machine Reality)
+3. **Latency & Time Budget:** Hard real-time (<16.6ms / <7ms frame loop), interactive low-latency (<10ms keystroke), soft service API (<200ms p99), or batch?
+4. **Memory Management & GC Tolerance:** Zero-GC pause tolerance (demands C/C++/Rust/Zig), managed throughput GC (Go, Java 21+, C# .NET 9), or single-threaded event loop (JS/TS)?
+5. **Concurrency & Execution Model:** Single-threaded event loop, multi-threaded worker pools with work stealing, SIMD compute shaders, or distributed actors?
+6. **Persistence & Connectivity:** Zero persistence (in-memory only), local flat/binary files, embedded SQLite, client-side browser storage, or enterprise RDBMS (Postgres)? Zero network, WebSockets, UDP, or HTTP/REST/gRPC?
+
+#### Batch 3: Architectural Style & Emergent Toolchain
+7. **Architectural Style Derivation:**
+   - Web SaaS ➔ Modular Monolith / Hexagonal (Ports & Adapters)
+   - Browser Extension ➔ Platform Scripting (`background`, `content`, `popup`, `storage`)
+   - Game Engine ➔ Data-Oriented Design (DOD / ECS / Cache-friendly contiguous memory)
+   - Canvas Game ➔ Game Loop (`Input ➔ Update ➔ Render`)
+   - Desktop CLI ➔ Command Pipeline (`Arg Parser ➔ Handler ➔ Stream I/O`)
+8. **Primary Programming Language & Runtime:** Derived strictly from the constraints above (C, Rust, TypeScript, Go, Java, C#, Python).
+9. **Package Manager & Toolchain:** Specific package manager (`cargo`, `pnpm`, `uv`, `go modules`) and build task runner.
+
+#### Batch 4: Targeted Invariants (Topology-Scoped, 100% YAGNI)
+Inquire *only* into the dimensions relevant to the selected topology:
+- *If Web SaaS / Backend:* API protocol (REST/gRPC), DB migration engine (Atlas/Flyway), tenancy isolation model, authentication, and OCI distroless containers.
+- *If Browser Extension:* MV3 content script isolation (IIFE bundle), `chrome.storage.sync` flow, permissions. (Zero Docker/K8s/OpenAPI!).
+- *If Game Engine:* Graphics backend (Vulkan/DirectX/wgpu), memory allocators (arena/frame), ECS archetype model. (Zero Docker/SQL!).
+- *If CLI:* Arg parsing library, POSIX exit codes, streaming I/O, `--json` formatting. (Zero Docker/SQL!).
 
 ---
 
@@ -81,23 +84,20 @@ Do NOT guess or assume any technology or stack choice. Execute the relentless in
 
 ---
 
-### Phase 4: Bootstrap (Deterministic Technical Scaffolding)
+### Phase 4: Bootstrap (Deterministic Topology Scaffolding)
 Upon user confirmation:
-1. Run the deterministic workspace initialization script:
+1. Run the topology-aware workspace initialization script:
    ```bash
-   bash .agents/skills/lets-build/scripts/bootstrap_workspace.sh . <language>
+   bash .agents/skills/lets-build/scripts/bootstrap_workspace.sh . <topology> <language>
    ```
-2. Generate base infrastructure and open specification foundations in `specs/`:
-   - `specs/openapi/v1/openapi.yaml` (minimal health probe and API versioning metadata)
-   - `specs/tokens/tokens.json` (W3C DTCG design tokens baseline)
-3. Scaffold initial Hexagonal application technical skeleton following [references/hexagonal_bootstrap_scaffolds.md](./references/hexagonal_bootstrap_scaffolds.md):
-   - Pure architecture ports and adapters layout (`src/domain/`, `src/ports/`, `src/adapters/`).
-   - Minimal system health probes (`/healthz`, `/readyz`).
-   - Strict isolation: **Do NOT scaffold application business features or fabricate domain entities yet.**
-4. Generate build manifests (`go.mod`, `Cargo.toml`, `pyproject.toml`, or `package.json`), linter/formatter configurations, minimal multi-stage `Dockerfile`, and `docker-compose.yml`.
-5. Scaffold initial test runner and boundary verification smoke test (`scripts/smoke_test.sh`).
-6. **Replace Starter README with Project-Specific README**:
-   Generate a clean, project-specific `README.md` using [references/project_readme_template.md](./references/project_readme_template.md), completely replacing the starter/meta-template content with the project's actual name, mission, stack highlights, quickstart commands, directory tree, and links to `docs/rules/`.
+2. Generate base infrastructure strictly for the selected topology (zero speculative bloat):
+   - *Backend:* `specs/openapi/v1/openapi.yaml`, `specs/tokens/tokens.json`, `deploy/docker`, `deploy/compose`.
+   - *Extension:* `manifest.json`, `src/background/index.ts`, `src/content/index.ts`, `src/popup/index.html`.
+   - *Game / Engine:* `src/core/`, `src/ecs/`, asset manifest, frame loop entrypoint.
+   - *CLI:* `src/cmd/`, `src/core/`, CLI entrypoint with exit code handling.
+3. Generate build manifests (`Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`), linter configurations, and boundary smoke test (`scripts/smoke_test.sh`).
+4. **Replace Starter README with Project-Specific README**:
+   Generate a clean, project-specific `README.md` completely replacing meta-template content with the project's actual name, mission, stack highlights, quickstart commands, and directory tree.
 
 ---
 
@@ -106,9 +106,9 @@ Upon user confirmation:
    ```bash
    bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh
    ```
-2. Execute toolchain dependency checks, build commands, and health probe tests:
+2. Execute toolchain dependency checks, build commands, and health/smoke tests:
    - Compile code and verify zero compiler or lint errors.
-   - Verify direct backend and reverse proxy health probes (`/healthz`).
+   - Verify boundary verification smoke test (`scripts/smoke_test.sh`).
 3. **Mandatory Handover to Domain Analysis (STOP & PIVOT):**
    - **`lets-build` IS NOW COMPLETE.** Do NOT proceed to write domain business entities, repositories, or application features.
    - Present the bootstrapped technical skeleton to the user.
@@ -120,11 +120,11 @@ Upon user confirmation:
 
 - **MAJOR DONT: DO NOT invent, assume, or scaffold application domain entities, business logic, or feature pages during `/lets-build`.** The `lets-build` skill is strictly an infrastructure and technical stack bootstrapper. Fabricating business domain features without dedicated domain analysis and relentless questioning of the user is a fatal architectural defect.
 - **DO NOT** assume the stack. Never start writing Go, Rust, Python, or TypeScript before asking the user.
-- **DO NOT** scaffold all options at once. Follow the user's chosen stack strictly.
-- **DO NOT** couple domain entities to ORMs, database libraries, or HTTP frameworks. The domain core must remain pure.
+- **DO NOT** scaffold universal web boilerplate (Docker, Kubernetes, OpenAPI, Postgres migrations) for non-backend projects (Browser Extensions, CLIs, Game Engines, Desktop apps).
+- **DO NOT** force Hexagonal Architecture onto platforms where the application IS the platform integration (e.g. Browser Extensions). Match architecture to topology.
 - **DO NOT** proceed to code generation without presenting the blueprint and receiving explicit user approval.
-- **DO NOT** skip or delete the 41 atomic domain rules in `docs/rules/` during bootstrapping. The rules govern the ongoing lifecycle of the newly bootstrapped project.
-- **DO NOT** create monolithic files (> 300 lines) or large functions (> 30 lines). Maintain strict Clean Code standards.
+- **DO NOT** skip or delete the atomic domain rules in `docs/rules/` during bootstrapping. The rules govern the ongoing lifecycle of the newly bootstrapped project.
+- **DO NOT** create monolithic files (> 250 lines) or large functions (> 30 lines). Maintain strict Clean Code standards.
 
 ---
 
@@ -134,31 +134,24 @@ Upon user confirmation:
 ```markdown
 # Architectural Specification & Technology Blueprint
 
-## 1. Core Profile
+## 1. Problem Space & Topology
 - **Project Domain:** <domain>
+- **System Topology:** <Web SaaS / Browser Extension / Game Engine / Canvas Game / CLI / Library>
+- **Architectural Style:** <Hexagonal / Platform Scripting / Data-Oriented Design / Game Loop / Command Pipeline>
+
+## 2. Core Profile & Constraints
 - **Primary Language & Runtime:** <language / version>
 - **Package Manager & Build Tool:** <tool>
-
-## 2. Interface & Transport
-- **Protocols:** <REST / gRPC / CloudEvents>
-- **Transport Framework:** <framework>
-- **Contracts:** <specs/openapi / specs/protobuf>
-
-## 3. Persistence & Isolation
-- **Storage Engine:** <engine & version>
-- **Migration Engine:** <Atlas / Flyway / Goose>
-- **Tenancy Isolation:** <Model A / B / C / D>
-- **Dynamic Schemas:** <JSON Schema Draft 2020-12>
-
-## 4. Logic, Workflows & Identity
-- **Dynamic Logic:** <Common Expression Language / Wasm Extism>
-- **Workflows:** <Temporal / Camunda / Statecharts>
-- **Authentication:** <OIDC / WebAuthn Passkeys / PASETO>
-- **Authorization:** <OPA Rego / OpenFGA ReBAC>
-
-## 5. Operations & Quality
-- **Caching & Streams:** <Cache Engine / Broker>
-- **Observability:** <OpenTelemetry OTLP>
-- **DevSecOps:** <Semgrep / Trivy / Gitleaks / Syft>
-- **Testing:** Outside-In TDD (100.00% coverage gate)
+- **Latency / Performance Target:** <Hard real-time / Interactive / Service / Batch>
+- **Memory & Concurrency Model:** <Zero GC / Managed GC / Single-threaded event loop>
+
+## 3. Interfaces & Storage
+- **Protocols / Transports:** <REST / gRPC / WebSockets / CLI stdin-stdout / None>
+- **Storage / Persistence:** <PostgreSQL / SQLite / chrome.storage / Flat file / In-memory>
+- **Specifications:** <OpenAPI 3.1 / Manifest V3 / Protobuf / None>
+
+## 4. Quality & Verification
+- **Testing Strategy:** Outside-In TDD with Nano-Cycles (Uncle Bob's 3 Laws)
+- **Code Health Gates:** 100.00% test coverage gate, zero lint errors
+- **DevSecOps:** <Semgrep / Trivy / Gitleaks / None>
 ```

package/.agents/skills/lets-build/references/architecture_interview_matrix.md

@@ -1,188 +1,109 @@
-# Comprehensive Architecture Interview Matrix
+# Problem-First Architecture Interview Matrix
 
-> **Source of Truth:** Exhaustive taxonomy across 20 architectural dimensions to interrogate before bootstrapping any enterprise project.
+> **Core Philosophy:** Software architecture must be derived from problem constraints, domain invariants, and execution targets—never from preemptive tool selection. Tools, runtimes, and databases are emergent outputs of the Problem Space.
 
 ---
 
-## Dimension 1: Architectural Paradigm & Monolith-to-Service Boundary
-- **System Topology:** Modular Monolith (Modulith), Event-Driven Architecture (EDA), Service-Oriented (SOA), or Microservices?
-- **Domain Decoupling:** Hexagonal Ports & Adapters, Clean Architecture, Onion Architecture, or Pragmatic Layered?
-- **Language Bias:** Zero language bias; pure business domain core decoupled from infrastructure adapters.
+## Tier 1: Problem Space Definition & System Topology
 
----
-
-## Dimension 2: Core Programming Languages & Runtimes
-- **Primary Languages:**
-  - Systems / High-Performance: Rust, Go, or C++23
-  - Enterprise / JVM: Java 21+ (Loom virtual threads) or Kotlin
-  - Web / Full-Stack: TypeScript (Node.js / Bun)
-  - Data / ML / Scripting: Python 3.12+ or Elixir (BEAM concurrency)
-- **Language Invariants:** Strict static sound typing; zero unhandled exceptions at domain boundaries.
-
----
-
-## Dimension 3: Package Managers, Workspaces & Monorepo Tooling
-- **Package Manager:**
-  - Node/TS: `pnpm` (with strict isolated node_modules), `bun`, or `yarn` (Berry)
-  - Rust: `cargo` (with cargo workspaces)
-  - Go: Go Modules (with multi-module workspaces)
-  - Python: `uv`, `poetry`, or `pixi`
-- **Monorepo Build Orchestration:** Turborepo, Nx, or Bazel/Buck2 with remote caching?
-
----
-
-## Dimension 4: Containerization, Base OS & Cloud-Native Runtime
-- **Container Strategy:**
-  - Zero-cve distroless (`gcr.io/distroless/*`) or `scratch` base images?
-  - Rootless container execution (`USER nonroot:nonroot`)?
-  - Multi-stage Dockerfiles with build caching?
-- **Cloud-Native Invariants:** 12-Factor (2026 Edition); stateless runtime isolates; graceful `SIGTERM` draining.
-
----
-
-## Dimension 5: API Protocols, Transports & Network Contracts
-- **Primary Transport:**
-  - RESTful HTTP/JSON (RFC 7807 problem details + OpenAPI 3.1)
-  - gRPC / Protocol Buffers (v3 / Buf CLI)
-  - GraphQL (Apollo / GraphQL-Yoga with code-first or schema-first SDL)
-  - WebSockets / Server-Sent Events (SSE) for real-time push
-- **API Versioning Strategy:** URI Path (`/v1/`), Request Header, or Media Type negotiation?
-
----
-
-## Dimension 6: Database & Persistence Engine
-- **Primary Storage Engine:**
-  - Relational: PostgreSQL, MySQL / MariaDB, SQLite, CockroachDB, or TiDB
-  - Document / NoSQL: MongoDB, DynamoDB, or Cassandra
-  - Multi-Model / Hybrid: Relational core with document extension
-- **Persistence Pattern:** Repository Pattern with raw SQL / query builders (e.g. `sqlx`, `pgx`, `Kysely`, `jOOQ`) vs ORM (e.g. Prisma, SQLAlchemy, GORM, Hibernate)?
-- **Mandatory Universal Audit Columns:**
-  - Standardize on **The Canonical 6 Total Audit Fields** (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`) across all mutable relational entities?
-  - Strictly immutable append-only ledgers (`createdAt`, `createdBy` only; updates/deletions prohibited)?
-
----
+### Dimension 1: The Core Problem & Domain Essence
+- **Problem Statement:** What real-world problem or capability does this system address? What data moves, and what transformations occur?
+- **Domain Invariants:** What core business, legal, mathematical, or physical rules must never be violated?
+- **Domain Subdivisions:** Identify subdomains:
+  - *Core Subdomain:* The unique differentiator (e.g. proprietary physics simulation, smart filter inversion, bidding algorithm).
+  - *Supporting Subdomain:* Necessary domain-specific capabilities (e.g. user preferences, level editor).
+  - *Generic Subdomain:* Solved industry utilities (e.g. authentication, logging).
 
-## Dimension 7: Database Migration & Schema Evolution
-- **Migration Engine:** Declarative schema management (**Atlas**), versioned SQL migrations (**Flyway**, **Liquibase**, **Goose**, or **Bytebase**)?
-- **Zero-Downtime Expand-Contract:** Does the project commit to the 5-phase expand-contract deployment lifecycle?
+### Dimension 2: System Topology Classification
+Classify the system into its primary operational topology:
+1. **Topology A — Web SaaS / Cloud Microservices:** Network-facing HTTP/gRPC services with multi-tenant data persistence and web/mobile clients.
+2. **Topology B — Browser Extension:** Client-side sandboxed extension (Chrome/Firefox MV3) orchestrating content scripts, background service workers, and popup UI.
+3. **Topology C — Game Engine / High-Performance Simulator:** Low-level, frame-budgeted application directly interfacing with GPU APIs (Vulkan, DirectX, Metal) and system memory.
+4. **Topology D — Browser / Canvas Game:** Sandboxed web game running inside the browser DOM/Canvas via Canvas2D, WebGL, or WebGPU.
+5. **Topology E — Desktop Application / CLI Utility:** Standalone OS binary (POSIX/Windows) executed locally via terminal arguments or native desktop UI.
+6. **Topology F — Systems / Embedded / Cryptographic Library:** Headless shared library or crate compiled for specific hardware targets or WASM runtimes.
 
 ---
 
-## Dimension 8: Multi-Tenancy Data Isolation Model
-- **Isolation Strategy:**
-  1. **Model A: Universal AST Query Interceptor** (Tenant column + automatic SQL/query AST rewriting)
-  2. **Model B: Database Row-Level Security (RLS)** (Session-scoped `set_config` / session variables)
-  3. **Model C: Schema-per-Tenant** (Dedicated database schema namespace per tenant)
-  4. **Model D: Database-per-Tenant** (Physical instance routing via connection pool manager)
-  5. **Model E: Storage Proxy** (Envoy / ProxySQL / Vitess)
+## Tier 2: Physical & Operational Constraints
 
----
+### Dimension 3: Latency & Time Budgets
+- **Hard Real-Time:** Frame budget enforced (e.g. 16.6ms for 60 FPS, 6.94ms for 144 FPS). Any jitter causes dropped frames.
+- **Interactive Low-Latency:** Sub-10ms response for user inputs (e.g. keystrokes in a code editor, real-time audio DSP).
+- **Service Request-Response:** Soft latency (e.g. p99 < 200ms for web APIs; p95 < 50ms for internal RPC).
+- **Asynchronous / Batch:** Throughput-optimized batch or event stream processing (seconds to minutes).
 
-## Dimension 9: Dynamic Schemas & Extensible Entities
-- **Dynamic Field Storage:** Semi-structured JSON column with **JSON Schema Draft 2020-12** validation vs Entity-Attribute-Value (EAV) vs Virtual Column projection?
-- **Meta-Schema Virtual Entities:** Will tenants define completely custom entities at runtime without code deployments?
+### Dimension 4: Memory Management & Garbage Collection Tolerance
+- **Zero GC Pause Tolerance:** Latency spikes or unpredictable GC pauses are unacceptable. Demands deterministic, manual, or compile-time memory management (C, C++, Rust, Zig).
+- **High-Throughput Managed GC:** GC pauses (< 10ms) are completely imperceptible within network I/O latency. Managed runtimes maximize developer velocity (Go, Java 21+ with Loom, C# .NET 9).
+- **Single-Threaded Event Loop:** JavaScript / TypeScript runtime in browser sandbox or Node/Bun.
 
----
+### Dimension 5: Concurrency & Execution Topology
+- **Single-Threaded Cooperative:** Event loop with non-blocking async I/O (browser JS, Node.js).
+- **Multi-Threaded Work-Stealing:** Parallel pipelines across CPU cores (physics, rendering, audio) requiring data-race safety.
+- **Data-Parallel / SIMD:** Vectorized computation over contiguous arrays or GPU compute shaders.
+- **Distributed Shared-Nothing:** Clustered actor nodes or horizontal stateless containers.
 
-## Dimension 10: Pluggable Business Logic & Workflows
-- **Dynamic Rules:** Google's **Common Expression Language (CEL)** vs JSON Logic vs Strategy Registries?
-- **Workflow Orchestration:** **Temporal.io** durable execution vs **Camunda 8 / Zeebe (BPMN 2.0)** vs state machine libraries?
-- **Sandboxed Scripting:** **WebAssembly (Extism / Wasmtime)** micro-sandboxes vs isolated interpreters?
+### Dimension 6: Persistence & Connectivity Demands
+- **Zero Persistence:** In-memory state only (e.g. real-time canvas game, transient CLI filter).
+- **Local Embedded / Flat Storage:** Local binary files, JSON configuration, or embedded SQLite.
+- **Client-Side Platform Storage:** Browser `chrome.storage.local` / `sync`, `localStorage`, or IndexedDB.
+- **Enterprise Relational / Document RDBMS:** PostgreSQL, MySQL, MongoDB, CockroachDB with ACID transactions.
+- **Network Interface:** Pure local IPC/pipes (zero network), WebSockets, UDP packets, or HTTP/REST/gRPC.
 
 ---
 
-## Dimension 11: Authentication & Identity
-- **Protocols:** OpenID Connect (OIDC), OAuth 2.1 with PKCE, SAML 2.0 federation, or local credentials?
-- **Passkeys / Passwordless:** W3C / FIDO2 WebAuthn passkey support?
-- **Token Format:** PASETO (Platform-Agnostic Security Tokens) vs RFC 7519 JWT with JWKS asymmetric key rotation?
-- **Token Rotation:** Cryptographic Refresh Token Rotation (RTR) with family invalidation on replay detection?
+## Tier 3: Architectural Style Derivation (Topology Alignment)
 
----
+Match the architectural style strictly to the system topology:
 
-## Dimension 12: Authorization & Policy-as-Code
-- **Policy Engine:**
-  - **Open Policy Agent (OPA)** (Rego language via REST/gRPC or embedded `.wasm` module)
-  - **OpenFGA** (Google Zanzibar Relationship-Based Access Control - ReBAC)
-  - **Cerbos** (Stateless policy-as-code)
-  - Application-level RBAC / ABAC guard wrappers
+| Topology | Mandatory Architectural Style | Rationale | Anti-Pattern to Ban |
+|---|---|---|---|
+| **Web SaaS / Backend** | **Hexagonal (Ports & Adapters) / Clean** | Decouples business rules from databases, HTTP frameworks, and external APIs. | Fat controllers with inline SQL; leaky abstractions. |
+| **Browser Extension** | **Platform Scripting Architecture** | Direct, lean coordination of `background`, `content`, `popup`, and browser storage APIs. | Forcing Hexagonal ports, use-case classes, or `/healthz` probes. |
+| **Game Engine** | **Data-Oriented Design (DOD / ECS)** | Cache-friendly contiguous memory layout (dense component arrays) for SIMD vectorization. | Deep OOP inheritance hierarchies; GC-managed wrappers. |
+| **Canvas Game** | **Game Loop Architecture** | Structured `Input ➔ Update ➔ Render` loop driven by `requestAnimationFrame`. | Enterprise repository and layered CRUD ceremony. |
+| **Desktop CLI** | **Command Pipeline Architecture** | Streamlined `Arg Parser ➔ Command Handler ➔ Stream I/O`. | Embedding REST servers, microservices, or Docker containers. |
 
 ---
 
-## Dimension 13: Presentation, Client & Server-Driven UI (SDUI)
-- **Frontend Framework & Architecture:**
-  - Web: React, Vue, Svelte, Solid, Angular, or Web Components?
-  - Mobile: Flutter, React Native, iOS SwiftUI, or Android Jetpack Compose?
-  - Hypermedia / SSR: HTMX / HTML-over-the-wire?
-  - Server-Driven UI (SDUI): Declarative JSON layout schemas rendered by client registries?
-- **UI Component Primitives & Styling:**
-  - Standardize on `shadcn/ui` with `@radix-ui` headless primitives + Tailwind CSS?
-  - Accessible dialogs, focus trapping, and zero native alerts per `accessibility.md`?
-- **Server-State Caching & Data Synchronization:**
-  - **TanStack Query (`@tanstack/react-query`)** with query keys, stale-while-revalidate, and automatic mutation invalidation vs SWR vs raw fetch?
-- **Form State Management & Validation:**
-  - **React Hook Form (`react-hook-form` + `@hookform/resolvers/zod`)** or **TanStack Form (`@tanstack/react-form`)** with **Zod** schema contracts?
-- **Data Grids & Table Virtualization:**
-  - **TanStack Table (`@tanstack/react-table`)** for headless sorting, filtering, and pagination?
-- **Client Stores & Global State:**
-  - **Zustand** vs Jotai vs Redux Toolkit for shared client-only state?
-- **Design Tokens:** W3C Design Tokens Community Group (DTCG) `tokens.json` processed via Style Dictionary?
+## Tier 4: Emergent Toolchain & Language Derivation
 
----
+Derive the programming language, runtime, and package manager strictly from the constraints established above:
 
-## Dimension 14: Caching, Distributed Locks & Session State
-- **Caching Engine:** Redis, Valkey, Dragonfly, KeyDB, Memcached, or local in-memory LRU?
-- **Cache Pattern:** Cache-Aside with jittered TTLs, XFetch probabilistic stampede defense, and event-driven invalidation?
-- **Distributed Locks:** Redis Redlock / atomic SETNX with bounded TTLs?
+| Language Profile | Optimal Fit | Primary Trade-Off |
+|---|---|---|
+| **C (C99 / C11)** | Game engines, embedded systems, OS kernels. | Raw pointer control, instant compile times; manual memory management. |
+| **Rust** | Game engines, code editors, CLI tools, systems services. | Zero GC, compile-time memory safety, fearless concurrency; steeper learning curve, slower builds. |
+| **TypeScript / JS** | Browser extensions, canvas games, web frontends, fullstack apps. | Instant browser compatibility, rich UI ecosystem; single-threaded event loop, runtime typing. |
+| **Go** | Cloud microservices, CLI tools, network proxies. | Fast startup, simple concurrency (goroutines); basic GC, limited generics. |
+| **Java 21+ / C# (.NET 9)** | Enterprise transaction platforms, high-throughput microservices. | Massive enterprise ecosystem, virtual threads; higher memory footprint. |
+| **Python** | Data analysis, ML pipelines, quick automation scripts. | Expressive syntax, unmatched ML libraries; slower execution, GIL constraints. |
 
 ---
 
-## Dimension 15: Distributed Messaging & Event Streaming
-- **Message Broker:** Apache Kafka / Redpanda, NATS JetStream, RabbitMQ, AWS SQS, or Redis Streams?
-- **Event Specification:** CNCF CloudEvents v1.0.2 format?
-- **Transactional Outbox:** Polling relay (`FOR UPDATE SKIP LOCKED`) or Change Data Capture (CDC via Debezium)?
-
----
+## Tier 5: Targeted Invariants (Strictly Topology-Scoped, 100% YAGNI)
 
-## Dimension 16: Observability, Telemetry & Logging
-- **Standard:** 100% CNCF OpenTelemetry (OTel) with OTLP export over gRPC/HTTP?
-- **Tracing:** W3C Trace Context (`traceparent`, `tracestate`)?
-- **Logging Format:** Structured JSON conforming to Elastic Common Schema (ECS) or OpenTelemetry Resource Schema?
+Inquire *only* into the dimensions relevant to the selected topology. **Never ask non-backend projects about databases, containers, or API versioning!**
 
----
+### For Web SaaS & Enterprise Backends ONLY:
+- **API Protocols:** REST (OpenAPI 3.1) vs gRPC (Protobuf v3 via Buf) vs GraphQL.
+- **Database Migrations:** Declarative (Atlas) vs Versioned SQL (Flyway, Goose).
+- **Multi-Tenancy Isolation:** AST Query Interceptor vs Database RLS vs Schema-per-tenant.
+- **Authentication & AuthZ:** OIDC, OAuth 2.1, PASETO, OPA Rego, or OpenFGA ReBAC.
+- **Container Infrastructure:** Minimal Distroless/Scratch OCI containers and Docker Compose.
 
-## Dimension 17: DevSecOps, Supply Chain & Security
-- **SAST:** Polyglot Semgrep rules for security and code quality?
-- **Secret Detection:** Pre-commit Gitleaks or Secretlint hooks?
-- **Vulnerability Scanning:** Trivy container and lockfile scanning in CI?
-- **SBOM & Provenance:** Syft CycloneDX 1.6 SBOM generation and Cosign artifact signing?
+### For Browser Extensions ONLY:
+- **Manifest Version:** Chrome/Firefox Manifest V3.
+- **Script Isolation & Bundling:** Self-contained IIFE for content scripts (zero external ES module chunk imports).
+- **State Synchronization:** `chrome.storage.sync` with local fallback and unidirectional event application.
+- **Permissions:** Principle of least privilege for `manifest.json`.
 
----
-
-## Dimension 18: Testing & Verification Strategy
-- **TDD Methodology:** Outside-In TDD (London School) double loop?
-- **BDD Acceptance:** Executable Cucumber / Gherkin `.feature` criteria?
-- **Contract Testing:** Consumer-Driven Contract testing via Pact?
-- **Property-Based Testing:** Schemathesis OpenAPI / GraphQL automated fuzzing?
-- **Coverage Gate:** Mandatory 100.00% coverage thresholds across all suites?
-
----
-
-## Dimension 19: State Machines, Workflows & Lifecycle Configurability
-- **State Taxonomy & Invariant Separation:**
-  - **Core Invariant States (Hard FSM):** Enforced strictly inside compiled Domain Aggregate Roots? (Financial/legal integrity states like `SETTLED`, `CANCELLED` cannot be user-rewritten).
-  - **Operational Workflow Stages (Soft FSM):** Tenant-configurable review funnels, approval tiers, or sub-statuses managed via Declarative State Transition Matrices?
-- **Transition Guards & Rule Evaluation:**
-  - Standardize on Common Expression Language (CEL) or embedded Wasm sandboxing for tenant-defined guards?
-- **Workflow Orchestration:**
-  - Durable workflow engine (Temporal.io, Camunda 8 / Zeebe BPMN 2.0) for multi-step distributed sagas?
-- **Transition Audit Trail:**
-  - Mandatory append-only state transition log (`transitionId`, `entityType`, `entityId`, `fromState`, `toState`, `event`, `actorId`, `createdAt`)?
-
----
+### For Game Engines & High-Performance Simulators ONLY:
+- **Graphics Backend:** Native Vulkan, DirectX 12, Metal, or portable `wgpu`.
+- **Memory Allocation Strategy:** Linear allocators, frame allocators, arena allocators, or pool allocators.
+- **Entity Model:** Archetype ECS (e.g. `bevy_ecs`, `hecs`, `EnTT`) vs dense component arrays.
 
-## Dimension 20: Ubiquitous Language & Domain-Code Agreement
-- **Living Glossary:** Authoritative `docs/knowledge/ubiquitous_language.md` mapping domain terms, business definitions, and exact code identifiers?
-- **Linguistic Drift Defenses:**
-  - Mechanical AST / Linter rules (ESLint `id-denylist`) prohibiting banned synonyms?
-  - Branded nominal types (`type UserId = string & { readonly __brand: unique symbol }`) preventing primitive obsession and cross-domain identifier confusion?
-- **Anti-Corruption Layer (ACL):** Adapters at system perimeters converting external vendor terminology into the canonical Ubiquitous Language?
+### For Desktop CLIs ONLY:
+- **CLI Framework:** Zero-dependency argument parser vs battle-tested CLI library (e.g. `clap` for Rust, `cobra` for Go).
+- **I/O Protocols:** Standard POSIX streams (`stdin`, `stdout`, `stderr`), exit codes (0 for success, non-zero for error), JSON output flags (`--json`).