azcodr 1.2.0 → 1.2.1

package/README.md

@@ -1,23 +1,25 @@
-# azcodr: Enterprise Multi-Tenant Architecture & Agentic Engineering
+# azcodr: Enterprise Architecture & Agentic Engineering Starter Template
 
-> **Production-ready, battle-tested multi-tenant enterprise architecture governed by strict systemic atomicity, 100% open-source standards, universal technology and language agnosticism, progressive disclosure agentic directives, and zero-downtime database patterns.**
+> **Production-ready, battle-tested software architecture governed by problem-first topology alignment, strict systemic atomicity, evolutionary architecture tipping points, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.**
 
 ---
 
 ## 🌟 Architectural Pillars
 
-1. **Systemic Atomicity**: Every rule, skill, database transaction, and code unit adheres to the Single Responsibility Principle (SRP)—indivisible, self-contained, orthogonal, and composable with zero conjunction naming.
-2. **Universal Technology & Stack Agnosticism**: Core business capabilities adhere strictly to Hexagonal (Ports & Adapters) architecture with zero runtime, language, or vendor lock-in. Runtimes, databases, and transports connect via interchangeable polyglot adapters with zero primary language bias.
-3. **100% Open-Source & Open Standards**: Standardized exclusively on open-source solutions and vendor-neutral specifications (OpenTelemetry, OPA, OpenFGA, Protocol Buffers, OpenAPI 3.1, JSON Schema Draft 2020-12, CloudEvents, Semgrep, Trivy, Gitleaks, Cosign).
-4. **Zero-Assumption Framework**: Ground truth is established solely through workspace configurations, code evidence, or direct user confirmation.
-5. **Hardened Multi-Tenancy**: 4 interchangeable isolation models (AST query interceptor filtering, schema-per-tenant, database-per-tenant, transparent storage proxy) backed by transaction-scoped session context.
-6. **Dynamic Extensibility Without Code Branching**:
+1. **Problem-First & Topology Alignment**: Architecture emerges strictly from problem constraints and execution targets (Problem-First; zero preemptive tool bias). Architectural styles match the problem topology: Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, and Game Loop for canvas games.
+2. **Systemic Atomicity**: Every rule, skill, database transaction, and code unit adheres to the Single Responsibility Principle (SRP)—indivisible, self-contained, orthogonal, and composable with zero conjunction naming.
+3. **Evolutionary Architecture & Refactor-Before-Add**: To eliminate AI-accelerated architectural drift, code graduates across 5 deterministic tipping points. Refactor structure first under existing green tests before implementing new features. Never append code into rotting files.
+4. **True Incremental TDD & Nano-Cycles**: Prohibit batch-test dumps ("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 with Ping-Pong pair programming.
+5. **100% Open-Source & Open Standards**: Standardized exclusively on open-source solutions and vendor-neutral specifications (OpenTelemetry, OPA, OpenFGA, Protocol Buffers, OpenAPI 3.1, JSON Schema Draft 2020-12, CloudEvents, Semgrep, Trivy, Gitleaks, Cosign).
+6. **Zero-Assumption Framework**: Ground truth is established solely through workspace configurations, code evidence, or direct user confirmation.
+7. **Hardened Multi-Tenancy (When Applicable)**: 4 interchangeable isolation models (AST query interceptor filtering, schema-per-tenant, database-per-tenant, transparent storage proxy) backed by transaction-scoped session context.
+8. **Dynamic Extensibility Without Code Branching**:
    - Custom tables and columns via hybrid core relational/document models and validated JSON Schema.
    - Pluggable business logic via Common Expression Language (CEL), GoF Strategy registries, and WebAssembly (Wasm) micro-sandboxes.
    - Tenant lifecycles via durable workflows (Temporal / BPMN 2.0 / statecharts).
    - Server-Driven UI (SDUI) component registries and W3C Design Tokens Community Group (DTCG) theming.
-7. **Resilient Database Architecture**: Full ACID atomicity, Transactional Outbox pattern eliminating dual-writes, declarative expand-contract zero-downtime migrations, and continuous Point-In-Time Recovery (PITR).
-8. **Workspace Knowledge Hub & Token Economy**: In-workspace system knowledge graphs, defect post-mortems, and Lightweight Architectural Decision Records (ADRs) to eliminate repetitive token-expensive discovery loops.
+9. **Resilient Database Architecture**: Full ACID atomicity, Transactional Outbox pattern eliminating dual-writes, declarative expand-contract zero-downtime migrations, and continuous Point-In-Time Recovery (PITR).
+10. **Workspace Knowledge Hub & Token Economy**: In-workspace system knowledge graphs and Lightweight Architectural Decision Records (ADRs) to eliminate repetitive token-expensive discovery loops.
 
 ---
 
@@ -54,9 +56,9 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 
 | Domain | Rule Reference File | Key Focus & Invariants |
 |---|---|---|
-| **TDD Double Loop** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Outside-In TDD (London School), collaborator discovery, mock ownership. |
+| **TDD Double Loop** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Uncle Bob's 3 Laws, nano-cycles, Ping-Pong pairing, outside-in double loop. |
 | **Test Coverage & Isolation** | [`test_isolation.md`](./docs/rules/test_isolation.md) | 100.00% full-stack coverage, status codes, transactional DB rollback. |
-| **Clean Code** | [`clean_code.md`](./docs/rules/clean_code.md) | Naming, small functions (< 30 lines), CQS, SLAP, DRY, DbC, zero side-effects. |
+| **Clean Code** | [`clean_code.md`](./docs/rules/clean_code.md) | 5 evolutionary tipping points, Refactor-Before-Add, CQS, SLAP, DRY, fitness functions. |
 | **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Facade, Strategy, and Result `<T, E>` pattern. |
 | **GoF Design Patterns** | [`gof_design_patterns_reference.md`](./docs/rules/gof_design_patterns_reference.md) | Complete reference of all 23 GoF patterns across OOP and functional paradigms. |
 | **Type Safety** | [`typescript.md`](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
@@ -91,7 +93,7 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 | **React & Frontend** | [`react.md`](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
 | **Requirements Engineering** | [`requirements_engineering.md`](./docs/rules/requirements_engineering.md) | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. |
 | **Product Ownership** | [`product_ownership.md`](./docs/rules/product_ownership.md) | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. |
-| **Domain-Driven Design** | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Value Objects, Aggregates. |
+| **Domain-Driven Design** | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) | Problem Space vs Solution Space, Ubiquitous Language, Bounded Contexts, Aggregates. |
 | **Workflow State Machines** | [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs. |
 | **Cloud-Native 12-Factor** | [`cloud_native.md`](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Agentic Config & Skills** | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) | Progressive disclosure architecture, skill inquiry branches, refinement loop. |
@@ -99,7 +101,7 @@ The architecture enforces 47 atomic, single-responsibility domain rules. Read on
 | **Domain Modeling** | [`domain_expertise.md`](./docs/rules/domain_expertise.md) | Business capabilities, Aggregate Root invariants, Ubiquitous Language. |
 | **Relentless Questioning** | [`relentless_questioning.md`](./docs/rules/relentless_questioning.md) | Dynamic context-aware interrogation loops, adaptive decision trees. |
 | **Workspace Isolation** | [`workspace_isolation.md`](./docs/rules/workspace_isolation.md) | Strict workspace sovereignty, zero global contamination, local ground truth. |
-| **Continuous Learning** | [`continuous_learning.md`](./docs/rules/continuous_learning.md) | Automated defect post-mortems, DO's/DONT's logging, dynamic rule updates. |
+| **Continuous Learning** | [`continuous_learning.md`](./docs/rules/continuous_learning.md) | Direct 4-step rule ingestion, root-cause analysis, dynamic invariant updates. |
 | **Upstream Sync** | [`upstream_synchronization.md`](./docs/rules/upstream_synchronization.md) | Logging generic architecture improvements to changes.md; zero baseline pollution. |
 
 ---
@@ -134,40 +136,33 @@ In your AI coding assistant (Google Antigravity, Claude Code, Cursor, or OpenHan
 ```
 *(Or simply prompt: "Let's build a new project from this template.")*
 
-### Step 3: The Relentless Architectural Interview
-The agent will execute a deep research loop and systematically interrogate you across all **18 systemic dimensions** (with zero assumptions) to lock in your desired technical stack:
-
-1. **Domain, Scale & Performance**: Problem domain, p95/p99 latency budgets, peak throughput (RPS), and regulatory standards (SOC 2, ISO 27001, GDPR).
-2. **Language & Runtime**: Go, Rust, Python, TypeScript, Java/Kotlin, C# (.NET), Elixir, or Polyglot microservices.
-3. **Package Manager & Toolchain**: `go modules`, `cargo`, `uv`/`poetry`, `pnpm`, `gradle`, or `dotnet CLI`.
-4. **Transport & Network**: REST (OpenAPI 3.1), gRPC (Protobuf v3 via `buf`), GraphQL, or Event-Driven.
-5. **Transport Framework**: Gin, Axum, FastAPI, Fastify, Spring Boot, or ASP.NET Core.
-6. **Database Engine**: PostgreSQL, MySQL, SQLite, CockroachDB, MongoDB, or Hybrid.
-7. **Database Migrations**: Declarative schema migrations (**Atlas**) vs versioned SQL (**Flyway**, **Goose**).
-8. **Multi-Tenancy Isolation**: AST query interceptor, Database RLS, Schema-per-tenant, or DB-per-tenant.
-9. **Dynamic Schemas**: Universal **JSON Schema Draft 2020-12** in semi-structured columns vs EAV.
-10. **Pluggable Logic & Workflows**: Common Expression Language (CEL), WebAssembly (Extism) sandboxing, and Temporal.io / BPMN 2.0.
-11. **Authentication & Identity**: OIDC, OAuth 2.1, Passkeys (FIDO2/WebAuthn), PASETO, or JWT JWKS.
-12. **Authorization Engine**: Open Policy Agent (OPA Rego via HTTP/Wasm), OpenFGA (Zanzibar ReBAC), or Cerbos.
-13. **Frontend / Client**: Web (React, Vue, Svelte), 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 (100% coverage gates).
-18. **Deployment Target**: Minimal OCI Distroless/Scratch, Docker Compose, Kubernetes, and OpenTofu IaC.
+### Step 3: The Problem-First Architectural Interview
+The agent will execute a deep research loop and systematically derive your technical stack strictly from problem constraints (with zero preemptive tool bias) across 5 tiered dimensions:
+
+1. **Problem Space & Topology Classification**: What real-world problem is being solved? What data moves and transforms? Classifies the system topology:
+   - *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: Systems / Embedded / Cryptographic Library*
+2. **Physical & Operational Constraints**: Latency budget (hard real-time <16.6ms frame loop vs interactive low-latency vs batch), memory model & GC tolerance (zero-GC pause tolerance vs managed throughput GC vs single-threaded event loop), and concurrency topology.
+3. **Architectural Style Derivation**: Matches style strictly to topology (Hexagonal for enterprise backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Game Loop for canvas games, Command Pipeline for CLIs).
+4. **Emergent Stack & Toolchain**: Derives the optimal language (C, Rust, TypeScript, Go, Java, C#, Python), package manager, and build system strictly from the verified constraints.
+5. **Targeted Invariants (Strictly Topology-Scoped)**: Inquires *only* into the dimensions relevant to the selected topology (e.g. database migrations for web backends, content script isolation for extensions, CLI flags for CLIs; zero Docker, Kubernetes, or OpenAPI bloat for non-backend projects).
 
 ### Step 4: Blueprint Synthesis & Explicit Approval
 The agent consolidates all your choices into a formal **Architectural Specification & Technology Blueprint** and records a formal ADR in [`memory.md`](./memory.md).  
 **The agent will stop and ask for your explicit confirmation before generating any code.**
 
-### Step 5: Deterministic Project Bootstrapping
+### Step 5: Deterministic Topology Scaffolding (Strict YAGNI)
 Once confirmed, the agent automatically executes:
-1. Directory scaffolding following **Hexagonal Architecture** (`src/domain/`, `src/ports/`, `src/adapters/`, `specs/`, `tests/`, `deploy/`).
-2. Canonical contract generation (`specs/openapi/`, `specs/protobuf/`, `specs/schemas/`, `specs/tokens/`).
-3. Build manifests, strict linter/formatter configurations, multi-stage Dockerfiles, and Compose environments.
-4. Domain entities, primary/secondary port interfaces, and initial adapter stubs.
-5. **Project-Specific README Generation**: Completely replaces the starter template `README.md` with clean, project-specific documentation (mission, stack highlights, quickstart setup, build/test commands, and directory structure), preserving links to `docs/rules/`.
-6. Deterministic validation via `validate_agentic_configs.sh` and initial compiler/test suite execution.
+1. Topology-aware directory scaffolding via `bootstrap_workspace.sh . <topology> <language>`, generating **0 speculative folders** (e.g. extensions get no Kubernetes or OpenAPI specs; CLIs get no Dockerfiles).
+2. Targeted contract and entrypoint generation matching the derived topology.
+3. Build manifests, strict linter/formatter configurations, and boundary smoke test (`scripts/smoke_test.sh`).
+4. **Project-Specific README Generation**: Completely replaces the starter template `README.md` with clean, project-specific documentation (mission, stack highlights, quickstart setup, build/test commands, and directory structure), preserving links to `docs/rules/`.
+5. Deterministic validation via `validate_agentic_configs.sh` and initial smoke test execution.
+6. **Handover Gate to Domain Analysis**: Halts technical scaffolding and instructs the user to invoke `product-analyst` and `relentless-questioner` for domain modeling.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azcodr",
-  "version": "1.2.0",
-  "description": "Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template",
+  "version": "1.2.1",
+  "description": "Enterprise Architecture & Agentic Engineering Starter Template",
   "bin": {
     "azcodr": "bin/azcodr.js"
   },