azcodr 1.3.0 → 1.4.0

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

@@ -15,66 +15,75 @@ echo "🏗️ Target Topology: ${TOPOLOGY}"
 echo "📦 Target Language Profile: ${LANGUAGE}"
 echo "--------------------------------------------------------------"
 
+# Helper to create leaf directory with .gitkeep to ensure Git tracks empty structures
+create_leaf() {
+  local dir="$1"
+  mkdir -p "${dir}"
+  if [[ -z "$(ls -A "${dir}" 2>/dev/null)" ]]; then
+    touch "${dir}/.gitkeep"
+  fi
+}
+
 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"
+    create_leaf "${WORKSPACE_ROOT}/src/background"
+    create_leaf "${WORKSPACE_ROOT}/src/content"
+    create_leaf "${WORKSPACE_ROOT}/src/popup"
+    create_leaf "${WORKSPACE_ROOT}/src/shared"
+    create_leaf "${WORKSPACE_ROOT}/public"
     
     echo "2. Scaffolding Extension Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/e2e"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/e2e"
     ;;
 
   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"
+    create_leaf "${WORKSPACE_ROOT}/src/core"
+    create_leaf "${WORKSPACE_ROOT}/src/ecs"
+    create_leaf "${WORKSPACE_ROOT}/src/renderer"
+    create_leaf "${WORKSPACE_ROOT}/src/assets"
     
     echo "2. Scaffolding Game/Engine Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/benchmarks"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/benchmarks"
     ;;
 
   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"
+    create_leaf "${WORKSPACE_ROOT}/src/cmd"
+    create_leaf "${WORKSPACE_ROOT}/src/core"
+    create_leaf "${WORKSPACE_ROOT}/src/io"
     
     echo "2. Scaffolding CLI Test Suites (tests/)..."
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
-    mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/integration"
     ;;
 
   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"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/entities"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/value_objects"
+    create_leaf "${WORKSPACE_ROOT}/src/domain/services"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/ports/secondary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/primary"
+    create_leaf "${WORKSPACE_ROOT}/src/adapters/secondary"
     
     echo "2. Scaffolding Specifications (specs/)..."
-    mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
-    mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+    create_leaf "${WORKSPACE_ROOT}/specs/openapi"
+    create_leaf "${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"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/tests/integration"
+    create_leaf "${WORKSPACE_ROOT}/tests/contracts"
+    create_leaf "${WORKSPACE_ROOT}/tests/acceptance"
     
     echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
-    mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
-    mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
+    create_leaf "${WORKSPACE_ROOT}/deploy/docker"
+    create_leaf "${WORKSPACE_ROOT}/deploy/compose"
 
     TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
     if [[ ! -f "${TOKEN_SPEC}" ]]; then
@@ -99,10 +108,29 @@ EOF
 
   *)
     echo "1. Scaffolding Generic / Library Source Tree (src/)..."
-    mkdir -p "${WORKSPACE_ROOT}/src"
-    mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+    create_leaf "${WORKSPACE_ROOT}/src"
+    create_leaf "${WORKSPACE_ROOT}/tests/unit"
     ;;
 esac
 
+# Deterministically generate boundary verification smoke test script (Phase 5 requirement)
+SMOKE_TEST="${WORKSPACE_ROOT}/scripts/smoke_test.sh"
+if [[ ! -f "${SMOKE_TEST}" ]]; then
+  echo "5. Generating boundary smoke test verification script (scripts/smoke_test.sh)..."
+  mkdir -p "${WORKSPACE_ROOT}/scripts"
+  cat << 'EOF' > "${SMOKE_TEST}"
+#!/usr/bin/env bash
+# ==============================================================================
+# Boundary Verification Smoke Test (Phase 5 Verification Gate)
+# ==============================================================================
+set -euo pipefail
+
+echo "Running boundary smoke verification..."
+# Extend with project-specific runtime health checks (e.g. ping health endpoint, CLI --help)
+echo "✅ Boundary smoke verification passed!"
+EOF
+  chmod +x "${SMOKE_TEST}"
+fi
+
 echo "--------------------------------------------------------------"
 echo "✅ Topology '${TOPOLOGY}' scaffolded with strict YAGNI (0 speculative folders)!"

package/.agents/skills/relentless-questioner/SKILL.md

@@ -58,10 +58,10 @@ Do NOT dump a massive 20-question static checklist. Execute the interview in **d
 ---
 
 ### Phase 3: Architectural Friction & Rule Reconciliation
-Check the user's proposed answers against the **47 Atomic Domain Rules** in `docs/rules/`:
-- If the user proposes writing to the database and publishing an event sequentially ➔ **Flag the dual-write anti-pattern** and mandate the Transactional Outbox pattern ([`database_transactions.md`](../../../docs/rules/database_transactions.md)).
-- If the user proposes storing tenant data without an isolation mechanism ➔ **Flag the tenant leak risk** and mandate an isolation model ([`multitenancy_isolation.md`](../../../docs/rules/multitenancy_isolation.md)).
-- If the user proposes arbitrary untrusted script execution ➔ **Flag the host security vulnerability** and mandate Wasm sandboxing ([`tenant_pluggable_logic.md`](../../../docs/rules/tenant_pluggable_logic.md)).
+Check the user's proposed answers against the **28 Cohesive Domain Rules** in `docs/rules/`:
+- If the user proposes writing to the database and publishing an event sequentially ➔ **Flag the dual-write anti-pattern** and mandate the Transactional Outbox pattern ([`database_design.md`](../../../docs/rules/database_design.md)).
+- If the user proposes storing tenant data without an isolation mechanism ➔ **Flag the tenant leak risk** and mandate an isolation model ([`multitenancy_architecture.md`](../../../docs/rules/multitenancy_architecture.md)).
+- If the user proposes arbitrary untrusted script execution ➔ **Flag the host security vulnerability** and mandate Wasm sandboxing ([`multitenancy_architecture.md`](../../../docs/rules/multitenancy_architecture.md)).
 - Reconcile the conflict collaboratively before proceeding.
 
 ---
@@ -78,7 +78,7 @@ Synthesize the answers into an unambiguous **Feature Alignment Specification (FA
 - **DO NOT** ask 10+ questions at once. Keep batches small (2–3 questions) to maintain a collaborative conversation.
 - **DO NOT** start coding or planning in parallel while the interrogation is in progress.
 - **DO NOT** let the user bypass critical failure branches (e.g. *"we'll handle errors later"*). Insist on defining failure states.
-- **DO NOT** compromise on the 41 atomic rules. If a user request introduces an architectural violation, surface it immediately.
+- **DO NOT** compromise on the 28 cohesive domain rules. If a user request introduces an architectural violation, surface it immediately.
 
 ---
 
@@ -118,3 +118,8 @@ Synthesize the answers into an unambiguous **Feature Alignment Specification (FA
   ```
 - **Test Strategy:** [Contract / Integration / Unit tests required for 100% coverage]
 ```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/adaptive_question_trees.md](./references/adaptive_question_trees.md): Contextual branching trees for state mutations, multi-tenancy, integrations, and caching.

package/AGENTS.md

@@ -1,10 +1,11 @@
 # AGENTS.md
 
-> **Operating Framework & Agent Directives**  
+> **azcodr: Enterprise Architecture & Agentic Engineering Starter Template**  
+> **Workspace Mission:** Problem-first, topology-aligned production architectures governed by strict systemic atomicity, 100% open-source standards, true incremental TDD nano-cycles, and zero speculative bloat.  
+> **Runtime & Tools:** Node.js (`>=18.0.0`), npm (`>=10.0.0`) | `npm test` (test runner), `npm run test:coverage` (100% gate), `npm run lint`, `npm run validate`.  
 > **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).  
-> **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.
+> **Atomicity Mandate:** All rules, skills, code units, migrations, and transactions must be strictly atomic (indivisible, self-contained, composable with full ACID safety).  
+> **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 backends, Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Game Loop for canvas games).
 
 ---
 
@@ -56,50 +57,34 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
 
 | Domain | Rule Reference File | When to Consult |
 |---|---|---|
-| **TDD Double Loop** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD (London School), collaborator discovery, mock ownership. |
-| **Test Coverage & Isolation** | [docs/rules/test_isolation.md](./docs/rules/test_isolation.md) | 100.00% full-stack coverage, status codes, transactional DB rollback. |
+| **TDD & Isolation** | [docs/rules/test_driven_development.md](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. |
 | **Clean Code** | [docs/rules/clean_code.md](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
-| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and complete 23 GoF catalog. |
-| **Type Safety** | [docs/rules/typescript.md](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
-| **ADRs** | [docs/rules/architecture_decision_records.md](./docs/rules/architecture_decision_records.md) | Authoring Lightweight Architectural Decision Records in `memory.md`. |
+| **Design Patterns** | [docs/rules/design_patterns.md](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and GoF pattern catalog. |
+| **Type Safety** | [docs/rules/type_safety.md](./docs/rules/type_safety.md) | Compiler strictness, branded nominal types, type discriminators across polyglot languages. |
 | **Authentication** | [docs/rules/authentication.md](./docs/rules/authentication.md) | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. |
 | **Authorization** | [docs/rules/authorization.md](./docs/rules/authorization.md) | CASL, OPA Rego policy engines, OpenFGA ReBAC, server guards. |
-| **Multi-Tenancy Isolation** | [docs/rules/multitenancy_isolation.md](./docs/rules/multitenancy_isolation.md) | Tenant context resolution, 4 universal data isolation models, RLS/interceptor safety. |
-| **REST API Conventions** | [docs/rules/rest_api_conventions.md](./docs/rules/rest_api_conventions.md) | Standard HTTP status codes, enumeration masking, subresource endpoints. |
-| **Advanced API Patterns** | [docs/rules/advanced_api_patterns.md](./docs/rules/advanced_api_patterns.md) | Allowed Actions (`_actions`), Idempotency keys, cursor pagination, OCC. |
-| **API Versioning** | [docs/rules/api_versioning.md](./docs/rules/api_versioning.md) | URI versioning (`/v1/`), RFC 8594 Sunset/Deprecation headers, 90-day window. |
-| **Tenant Dynamic Schemas** | [docs/rules/tenant_dynamic_schemas.md](./docs/rules/tenant_dynamic_schemas.md) | Hybrid core + JSON/document storage, JSON Schema Draft 2020-12, meta-schemas. |
-| **Tenant Pluggable Logic** | [docs/rules/tenant_pluggable_logic.md](./docs/rules/tenant_pluggable_logic.md) | Common Expression Language (CEL), Wasm sandboxing, durable workflows (Temporal/BPMN). |
-| **Server-Driven UI** | [docs/rules/server_driven_ui.md](./docs/rules/server_driven_ui.md) | Client-agnostic layout schemas, multi-renderer component registries, DTCG tokens. |
-| **Database Transactions** | [docs/rules/database_transactions.md](./docs/rules/database_transactions.md) | ACID atomicity, isolation levels, defensive timeouts, transactional outbox. |
-| **Database Migrations** | [docs/rules/database_migrations.md](./docs/rules/database_migrations.md) | Declarative/versioned migrations (Atlas/Flyway), zero-downtime expand-contract. |
-| **Database Integrity** | [docs/rules/database_integrity.md](./docs/rules/database_integrity.md) | Foreign keys, domain CHECK constraints, interval EXCLUDE, soft-delete indexes. |
-| **Database Operations** | [docs/rules/database_operations.md](./docs/rules/database_operations.md) | Continuous PITR, autovacuum/defrag tuning, connection pooling, role separation. |
-| **Database Performance** | [docs/rules/database_performance.md](./docs/rules/database_performance.md) | Eliminating N+1 queries, DataLoader batching, composite tenant indexes. |
-| **Caching** | [docs/rules/caching.md](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense. |
-| **Application Security** | [docs/rules/application_security.md](./docs/rules/application_security.md) | OWASP Top 10 defenses, cryptographic rigor, token bucket rate limiting. |
-| **Regulatory Compliance** | [docs/rules/compliance.md](./docs/rules/compliance.md) | SOC 2 Type II controls, ISO/IEC 27001 ISMS, GDPR data erasure rights. |
-| **DevSecOps** | [docs/rules/devsecops.md](./docs/rules/devsecops.md) | Secretlint pre-commit gating, CycloneDX SBOM generation, Trivy/Grype scanning. |
+| **Multi-Tenancy** | [docs/rules/multitenancy_architecture.md](./docs/rules/multitenancy_architecture.md) | Tenant context, 4 isolation models, RLS, dynamic schemas, pluggable logic & YAGNI gates. |
+| **API Architecture** | [docs/rules/api_architecture.md](./docs/rules/api_architecture.md) | HTTP status codes, sync vs async (202), `_actions`, idempotency keys, cursor pagination, OCC, versioning. |
+| **Server-Driven UI** | [docs/rules/server_driven_ui.md](./docs/rules/server_driven_ui.md) | Backend-driven layout schemas, multi-renderer component registries, DTCG tokens & YAGNI gate. |
+| **Database Design** | [docs/rules/database_design.md](./docs/rules/database_design.md) | Relational integrity, FKs, CHECK constraints, Canonical 6 audit fields, ACID transactions, Outbox CDC. |
+| **Database Operations** | [docs/rules/database_operations.md](./docs/rules/database_operations.md) | Zero-downtime expand-contract migrations, N+1 elimination, DataLoader, indexing, pooling, PITR. |
+| **Caching** | [docs/rules/caching.md](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense & YAGNI gate. |
+| **Security & Compliance** | [docs/rules/security_compliance.md](./docs/rules/security_compliance.md) | OWASP Top 10 defenses, rate limiting, crypto, SOC 2 Type II, ISO 27001, GDPR data erasure. |
+| **DevOps & CI/CD** | [docs/rules/devops_ci_cd.md](./docs/rules/devops_ci_cd.md) | Shift-left trunk-based CI, OCI distroless containers, Secretlint/Trivy DevSecOps, zero-downtime CD. |
+| **Cloud-Native 12-Factor** | [docs/rules/cloud_native.md](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Error Architecture** | [docs/rules/error_handling.md](./docs/rules/error_handling.md) | Fail-fast schema validation, structured OTel/Pino tracing, RFC 7807 envelopes. |
-| **Feature Flags** | [docs/rules/feature_flags.md](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches. |
-| **Continuous Integration** | [docs/rules/continuous_integration.md](./docs/rules/continuous_integration.md) | Shift-left automated pipelines, trunk-based development, build caching. |
-| **Continuous Deployment** | [docs/rules/continuous_deployment.md](./docs/rules/continuous_deployment.md) | Zero-downtime rollouts, Cosign container signing, container minimization. |
-| **Container Infrastructure** | [docs/rules/container_infrastructure.md](./docs/rules/container_infrastructure.md) | Unified gateway, minimal OCI distroless/scratch containers, non-root user security. |
+| **Feature Flags** | [docs/rules/feature_flags.md](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches & YAGNI gate. |
 | **Transactional Email** | [docs/rules/transactional_email.md](./docs/rules/transactional_email.md) | Declarative templates (MJML/JSON), safe interpolation, SMTP integration testing. |
-| **Accessibility** | [docs/rules/accessibility.md](./docs/rules/accessibility.md) | WCAG 2.2 AA compliance, accessible primitives, focus trapping, ARIA live regions. |
-| **UI Navigation** | [docs/rules/ui_navigation.md](./docs/rules/ui_navigation.md) | Bidirectional URL state synchronization, deep linking, search params. |
-| **UI/UX Architecture** | [docs/rules/ui_ux_architecture.md](./docs/rules/ui_ux_architecture.md) | Design triage, persistent app shell, collapsible sidebar, dual-experience portals. |
-| **React & Frontend** | [docs/rules/react.md](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
+| **UI/UX Architecture** | [docs/rules/ui_ux_architecture.md](./docs/rules/ui_ux_architecture.md) | Design triage gate, persistent app shell, collapsible sidebar, dual-experience portals, dev persona. |
+| **Frontend Architecture** | [docs/rules/frontend_architecture.md](./docs/rules/frontend_architecture.md) | Accessible headless primitives, WCAG 2.2 AA, server cache sync, form validation, 5-tier state, URL navigation. |
 | **Requirements Engineering** | [docs/rules/requirements_engineering.md](./docs/rules/requirements_engineering.md) | User stories vs requirements, 3 C's, INVEST vertical cake slicing, Gherkin. |
 | **Product Ownership** | [docs/rules/product_ownership.md](./docs/rules/product_ownership.md) | Product Backlog Management, OKRs, Kano/MoSCoW/RICE, Product Value, empiricism. |
-| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
-| **Workflow State Machines** | [docs/rules/workflow_state_machines.md](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs. |
-| **Cloud-Native 12-Factor** | [docs/rules/cloud_native.md](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
-| **Agentic Config & Skills** | [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) | Progressive disclosure architecture, skill inquiry branches, refinement loop. |
 | **Project Management** | [docs/rules/project_management.md](./docs/rules/project_management.md) | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. |
+| **Domain-Driven Design** | [docs/rules/domain_driven_design.md](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
+| **CQRS & Projections** | [docs/rules/cqrs.md](./docs/rules/cqrs.md) | Evolutionary CQRS spectrum, YAGNI defense, read projections, outbox CDC. |
+| **Workflow State Machines** | [docs/rules/workflow_state_machines.md](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs & YAGNI gate. |
+| **Agentic Governance** | [docs/rules/agentic_configuration.md](./docs/rules/agentic_configuration.md) | Progressive disclosure, ADR ledger, workspace sovereignty, continuous learning, YAGNI gate triad. |
 | **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) | Direct rule ingestion, root-cause analysis, dynamic invariant updates. |
 ---
 
 ## 4. Agent Configuration & Workspace Architecture
@@ -114,4 +99,4 @@ To prevent context bloat and keep prompt overhead minimal, detailed engineering
   - [`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/ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md) for 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.
+- **Harness Parity & Symlinks:** `AGENTS.md`, `CLAUDE.md`, `agents.md`, `GEMINI.md`, `.cursorrules`, and `.windsurfrules` must remain identical via filesystem symbolic links to eliminate configuration divergence across different agent harnesses.

package/README.md

@@ -38,10 +38,13 @@
 ├── docs/
 │   ├── knowledge/                    # Institutional knowledge & domain contracts
 │   │   └── ubiquitous_language.md    # Living Ubiquitous Language glossary template
-│   └── rules/                        # 44 atomic single-responsibility domain rules
+│   └── rules/                        # 28 cohesive single-responsibility domain rules
 ├── AGENTS.md                         # Lean root agentic configuration (< 120 lines)
-├── CLAUDE.md -> AGENTS.md            # Filesystem symlink for harness parity
-├── agents.md -> AGENTS.md            # Filesystem symlink for harness parity
+├── CLAUDE.md -> AGENTS.md            # Filesystem symlink for harness parity (Claude Code)
+├── agents.md -> AGENTS.md            # Filesystem symlink for harness parity (Codex / Standard)
+├── GEMINI.md -> AGENTS.md            # Filesystem symlink for harness parity (Antigravity / Gemini)
+├── .cursorrules -> AGENTS.md         # Filesystem symlink for harness parity (Cursor)
+├── .windsurfrules -> AGENTS.md       # Filesystem symlink for harness parity (Windsurf)
 ├── memory.md                         # Master memory hub & Lightweight ADR ledger
 └── README.md                         # Project documentation
 ```
@@ -50,54 +53,38 @@
 
 ## 📋 Progressive Disclosure Rules Catalog (`docs/rules/`)
 
-The architecture enforces 44 atomic, single-responsibility domain rules. Read on demand to prevent prompt context bloat:
+The architecture enforces 28 cohesive, single-responsibility domain rules. Read on demand to prevent prompt context bloat:
 
 | Domain | Rule Reference File | Key Focus & Invariants |
 |---|---|---|
-| **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) | 5 evolutionary tipping points, Refactor-Before-Add, CQS, SLAP, DRY, fitness functions. |
-| **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and complete 23 GoF catalog. |
-| **Type Safety** | [`typescript.md`](./docs/rules/typescript.md) | Compiler strictness, branded nominal types, type safety, static sound invariants. |
-| **ADRs** | [`architecture_decision_records.md`](./docs/rules/architecture_decision_records.md) | Authoring Lightweight Architectural Decision Records in `memory.md`. |
+| **TDD & Isolation** | [`test_driven_development.md`](./docs/rules/test_driven_development.md) | Outside-In TDD, Uncle Bob's 3 Laws, 100% coverage, test isolation & DB rollback. |
+| **Clean Code** | [`clean_code.md`](./docs/rules/clean_code.md) | Naming, small functions, CQS, SLAP, DRY, DbC, zero side-effects. |
+| **Design Patterns** | [`design_patterns.md`](./docs/rules/design_patterns.md) | Adapter, Factory, Strategy, Result `<T, E>`, and GoF pattern catalog. |
+| **Type Safety** | [`type_safety.md`](./docs/rules/type_safety.md) | Compiler strictness, branded nominal types, type discriminators across polyglot languages. |
 | **Authentication** | [`authentication.md`](./docs/rules/authentication.md) | In-memory access tokens, refresh token rotation (RTR), WebAuthn passkeys. |
 | **Authorization** | [`authorization.md`](./docs/rules/authorization.md) | CASL, OPA Rego policy engines, OpenFGA ReBAC, server guards. |
-| **Multi-Tenancy Isolation** | [`multitenancy_isolation.md`](./docs/rules/multitenancy_isolation.md) | Tenant context resolution, 4 universal data isolation models, RLS/interceptor safety. |
-| **REST API Conventions** | [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md) | Standard HTTP status codes, enumeration masking, subresource endpoints. |
-| **Advanced API Patterns** | [`advanced_api_patterns.md`](./docs/rules/advanced_api_patterns.md) | Allowed Actions (`_actions`), Idempotency keys, cursor pagination, OCC. |
-| **API Versioning** | [`api_versioning.md`](./docs/rules/api_versioning.md) | URI versioning (`/v1/`), RFC 8594 Sunset/Deprecation headers, 90-day window. |
-| **Tenant Dynamic Schemas** | [`tenant_dynamic_schemas.md`](./docs/rules/tenant_dynamic_schemas.md) | Hybrid core + JSON/document storage, JSON Schema Draft 2020-12, meta-schemas. |
-| **Tenant Pluggable Logic** | [`tenant_pluggable_logic.md`](./docs/rules/tenant_pluggable_logic.md) | Common Expression Language (CEL), Wasm sandboxing, durable workflows (Temporal/BPMN). |
-| **Server-Driven UI** | [`server_driven_ui.md`](./docs/rules/server_driven_ui.md) | Client-agnostic layout schemas, multi-renderer component registries, DTCG tokens. |
-| **Database Transactions** | [`database_transactions.md`](./docs/rules/database_transactions.md) | ACID atomicity, isolation levels, defensive timeouts, transactional outbox. |
-| **Database Migrations** | [`database_migrations.md`](./docs/rules/database_migrations.md) | Declarative/versioned migrations (Atlas/Flyway), zero-downtime expand-contract. |
-| **Database Integrity** | [`database_integrity.md`](./docs/rules/database_integrity.md) | Foreign keys, domain CHECK constraints, interval EXCLUDE, soft-delete indexes. |
-| **Database Operations** | [`database_operations.md`](./docs/rules/database_operations.md) | Continuous PITR, autovacuum/defrag tuning, connection pooling, role separation. |
-| **Database Performance** | [`database_performance.md`](./docs/rules/database_performance.md) | Eliminating N+1 queries, DataLoader batching, composite tenant indexes. |
-| **Caching** | [`caching.md`](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense. |
-| **Application Security** | [`application_security.md`](./docs/rules/application_security.md) | OWASP Top 10 defenses, cryptographic rigor, token bucket rate limiting. |
-| **Regulatory Compliance** | [`compliance.md`](./docs/rules/compliance.md) | SOC 2 Type II controls, ISO/IEC 27001 ISMS, GDPR data erasure rights. |
-| **DevSecOps** | [`devsecops.md`](./docs/rules/devsecops.md) | Secretlint pre-commit gating, CycloneDX SBOM generation, Trivy/Grype scanning. |
+| **Multi-Tenancy** | [`multitenancy_architecture.md`](./docs/rules/multitenancy_architecture.md) | Tenant context, 4 isolation models, RLS, dynamic schemas, pluggable logic & YAGNI gates. |
+| **API Architecture** | [`api_architecture.md`](./docs/rules/api_architecture.md) | HTTP status codes, sync vs async (202), `_actions`, idempotency keys, cursor pagination, OCC, versioning. |
+| **Server-Driven UI** | [`server_driven_ui.md`](./docs/rules/server_driven_ui.md) | Backend-driven layout schemas, multi-renderer component registries, DTCG tokens & YAGNI gate. |
+| **Database Design** | [`database_design.md`](./docs/rules/database_design.md) | Relational integrity, FKs, CHECK constraints, Canonical 6 audit fields, ACID transactions, Outbox CDC. |
+| **Database Operations** | [`database_operations.md`](./docs/rules/database_operations.md) | Zero-downtime expand-contract migrations, N+1 elimination, DataLoader, indexing, pooling, PITR. |
+| **Caching** | [`caching.md`](./docs/rules/caching.md) | Cache Port semantics, Cache-Aside, jittered TTLs, XFetch stampede defense & YAGNI gate. |
+| **Security & Compliance** | [`security_compliance.md`](./docs/rules/security_compliance.md) | OWASP Top 10 defenses, rate limiting, crypto, SOC 2 Type II, ISO 27001, GDPR data erasure. |
+| **DevOps & CI/CD** | [`devops_ci_cd.md`](./docs/rules/devops_ci_cd.md) | Shift-left trunk-based CI, OCI distroless containers, Secretlint/Trivy DevSecOps, zero-downtime CD. |
+| **Cloud-Native 12-Factor** | [`cloud_native.md`](./docs/rules/cloud_native.md) | 12-Factor (2026 Edition), OpenTelemetry (OTel), stateless isolates. |
 | **Error Architecture** | [`error_handling.md`](./docs/rules/error_handling.md) | Fail-fast schema validation, structured OTel/Pino tracing, RFC 7807 envelopes. |
-| **Feature Flags** | [`feature_flags.md`](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches. |
-| **Continuous Integration** | [`continuous_integration.md`](./docs/rules/continuous_integration.md) | Shift-left automated pipelines, trunk-based development, build caching. |
-| **Continuous Deployment** | [`continuous_deployment.md`](./docs/rules/continuous_deployment.md) | Zero-downtime rollouts, Cosign container signing, container minimization. |
-| **Container Infrastructure** | [`container_infrastructure.md`](./docs/rules/container_infrastructure.md) | Unified gateway, minimal OCI distroless/scratch containers, non-root user security. |
+| **Feature Flags** | [`feature_flags.md`](./docs/rules/feature_flags.md) | OpenFeature standard, Flipt/Unleash backends, targeting, kill switches & YAGNI gate. |
 | **Transactional Email** | [`transactional_email.md`](./docs/rules/transactional_email.md) | Declarative templates (MJML/JSON), safe interpolation, SMTP integration testing. |
-| **Accessibility** | [`accessibility.md`](./docs/rules/accessibility.md) | WCAG 2.2 AA compliance, accessible primitives, focus trapping, ARIA live regions. |
-| **UI Navigation** | [`ui_navigation.md`](./docs/rules/ui_navigation.md) | Bidirectional URL state synchronization, deep linking, search params. |
-| **UI/UX Architecture** | [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) | Design triage, persistent app shell, collapsible sidebar, dual-experience portals. |
-| **React & Frontend** | [`react.md`](./docs/rules/react.md) | Modern React, shadcn/ui, TanStack Query, React Hook Form, and Zod validation. |
+| **UI/UX Architecture** | [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) | Design triage gate, persistent app shell, collapsible sidebar, dual-experience portals, dev persona. |
+| **Frontend Architecture** | [`frontend_architecture.md`](./docs/rules/frontend_architecture.md) | Accessible headless primitives, WCAG 2.2 AA, server cache sync, form validation, 5-tier state, URL navigation. |
 | **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) | Problem vs Solution Space, Ubiquitous Language, Aggregates, Capability Mapping. |
-| **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. |
 | **Project Management** | [`project_management.md`](./docs/rules/project_management.md) | Work-In-Progress limits (WIP = 1), SMART developer tasks, Definition of Done. |
+| **Domain-Driven Design** | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) | Ubiquitous Language, Bounded Contexts, Aggregates, Capability Mapping. |
+| **CQRS & Projections** | [`cqrs.md`](./docs/rules/cqrs.md) | Evolutionary CQRS spectrum, YAGNI defense, read projections, outbox CDC. |
+| **Workflow State Machines** | [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md) | Configurable workflows, in-aggregate invariant FSMs, transition guards & audit logs & YAGNI gate. |
+| **Agentic Governance** | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) | Progressive disclosure, ADR ledger, workspace sovereignty, continuous learning, YAGNI gate triad. |
 | **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) | Direct 4-step rule ingestion, root-cause analysis, dynamic invariant updates. |
 
 ---
 

package/bin/azcodr.js

@@ -181,7 +181,7 @@ async function runCli(rawArgs = process.argv.slice(2), io = {}) {
       out('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
       out('  ✅ Specialized agentic skills copied (.agents/skills/)');
       out('  ✅ Editor formatting standards initialized (.editorconfig)');
-      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md)');
+      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md, GEMINI.md, .cursorrules, .windsurfrules)');
       if (result.gitInitialized) {
         out('  ✅ Git repository initialized');
       }

package/docs/rules/agentic_configuration.md

@@ -1,6 +1,6 @@
-# Agentic Configuration, Skills & Harness Standards
+# Agentic Configuration, Governance & Harness Standards
 
-> **Core Mandate:** Maintain lean agent entrypoints via progressive disclosure, modular documentation, strict skill front matter standards, harness symlink parity, and relentless questioning during skill architecture.
+> **Core Mandate:** Enforce progressive disclosure across agent entrypoints, strict skill front matter standards, workspace sovereignty, continuous learning via the direct rule ingestion loop, and immutable Architectural Decision Records (ADRs).
 
 ---
 
@@ -37,14 +37,26 @@ Different AI agents and IDE harnesses look for different configuration filenames
 - Standard: `AGENTS.md`
 - Lowercase: `agents.md`
 - Anthropic Claude Code: `CLAUDE.md`
+- Google Antigravity & Gemini CLI: `GEMINI.md`
+- Cursor: `.cursorrules`
+- Windsurf: `.windsurfrules`
 
 **Standard:** Maintain identical configuration across all harnesses by establishing filesystem symbolic links:
 ```bash
 ln -sf AGENTS.md agents.md
 ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md GEMINI.md
+ln -sf AGENTS.md .cursorrules
+ln -sf AGENTS.md .windsurfrules
 ```
 Never duplicate content into separate files.
 
+### Context Budget & Token Economy Directives
+To prevent LLM context exhaustion, attention dilution, and model degradation:
+- **Per-File Rule Size Cap (24 KB / 24,000 bytes):** Every rule file in `docs/rules/` must strictly stay under 24,000 bytes. Files exceeding this ceiling risk truncation across agent runtimes.
+- **Aggregate Rules Token Budget (20,000 tokens):** Continuous and directory-scoped rules share an aggregate budget. Over-budget rules are demoted to file-pointer references. Always use concise, actionable directives rather than prose tutorials.
+- **Progressive Offloading:** Offload deep specifications, schemas, or large lookup matrices to dedicated reference files loaded on demand.
+
 ---
 
 ## 4. Skills Architecture (`.agents/skills/<skill-name>/`)
@@ -71,9 +83,34 @@ description: <Imperative trigger description under 1024 characters. MUST start w
 - Include structured response templates and self-validation checklists for deterministic output.
 
 ### Progressive Disclosure Subdirectories
-- `references/`: Detailed sub-domain markdown files loaded on demand by the skill.
+Adhere strictly to the standard agent skills folder taxonomy:
 - `scripts/`: Deterministic executable scripts (bash, node, python) for tasks where LLMs produce non-deterministic drift.
-- `assets/`: Static data, lookup tables, schemas, or boilerplate templates.
+- `references/`: Detailed sub-domain markdown manuals loaded on demand by the skill.
+- `resources/`: Static templates, lookup tables, JSON schemas, or mock artifacts.
+- `examples/`: Reference implementations and concrete code patterns.
+
+### Deterministic Lifecycle Hooks (`.agents/hooks.json`)
+To enforce non-negotiable safety guardrails and automated verification without stochastic agent failure:
+- **`PreToolUse`**: Intercept destructive or dangerous CLI commands (`rm -rf`, DROP DATABASE, git push --force) and force explicit confirmation (`decision: ask`).
+- **`PostToolUse`**: Automatically trigger fast linters (`npm run lint`), formatters, or unit test verification after tool runs.
+- **`Stop`**: Intercept premature agent termination when background tasks are running or tests remain failing (`decision: continue`).
+
+### Model Context Protocol (MCP) Integration (`.agents/mcp_config.json`)
+When external tool capabilities are required (database introspectors, cloud telemetry, documentation search):
+- Standardize on vendor-neutral **Model Context Protocol (MCP)** specifications.
+- Declare local or containerized MCP tool servers in `.agents/mcp_config.json`.
+- Treat MCP tools as secondary adapter driving ports, keeping domain logic decoupled from proprietary platform APIs.
+
+### Explicit Prohibition: The "Library-as-a-Skill" Anti-Pattern
+Never author or dynamically generate skills for commodity open-source packages or libraries (e.g. `react`, `tanstack`, `shadcn`, `zustand`, `testing-library`, `vitest`):
+- **Prompt Bloat & Re-Explanation Tax:** Skill descriptions are continuously loaded into the agent's `<skills>` context. Proliferating skills for every library in a stack floods the prompt with thousands of redundant tokens and degrades model reasoning.
+- **Parametric Redundancy:** Frontier LLMs already possess extensive parametric knowledge of open-source library APIs. Re-explaining basic imports and function signatures in a skill wastes context and creates documentation rot.
+- **Trigger Collision & Agent Paralysis:** When a prompt touches UI, form validation, and data fetching, having 5 library skills triggers semantic collision, causing the agent to waste execution turns resolving which sub-skill to run.
+- **The 4-Layer Resolution Standard:** Always resolve library stack knowledge through the **4-Layer Resolution Model**:
+  1. *Layer 1 (Manifest Ground Truth):* Read `package.json`, `components.json`, or `tsconfig.json`.
+  2. *Layer 2 (Stack Contract in `AGENTS.md`):* 3–5 line declaration in project entrypoint stamped by `/lets-build`.
+  3. *Layer 3 (Universal Domain Rules):* Enforce architectural invariants (`frontend_architecture.md`, `test_driven_development.md`) rather than library syntax.
+  4. *Layer 4 (Tool & CLI Execution):* Direct execution of official CLIs (`npx shadcn@latest add ...`) or local component inspection.
 
 ---
 
@@ -111,38 +148,40 @@ Coding tasks and agentic skills exhibit an explicit **Many-to-Many ($M:N$) Relat
 - **Zero Cross-Contamination:** No skill may write code or modify files outside its declared functional boundary.
 - **Pure Function Semantics:** Analysis skills must remain read-only and side-effect free.
 
+## 6. The Mandatory YAGNI Gate Triad (Rules & Skills)
+
+LLM coding agents have a natural statistical bias toward **Instruction Creep** and **Eager Pattern Application**: when provided with a rule explaining an advanced pattern, agents reflexively apply it everywhere, causing severe architectural bloat.
+
+To prevent premature abstraction, every architectural pattern rule and skill must enforce the **YAGNI Gate Triad**:
+
+1. **The Simple Baseline (Day 1 Default):**
+   - The zero-overhead, default implementation that solves the immediate requirement without indirection (e.g. single database model before CQRS, relational indexes before Redis, standard React components before Server-Driven UI).
+2. **The Anti-Triggers (Strictly Forbidden Scenarios):**
+   - Explicit, negative conditions where applying the pattern or skill is forbidden as premature over-engineering (e.g. no caching for low-throughput queries, no state machines for 2-state boolean flags, no skills for routine typo fixes).
+3. **The Empirical Tipping Point (Graduation Threshold):**
+   - Measurable, verified criteria that MUST be breached before graduating to the pattern (e.g. p99 latency > 200ms after indexing, 3+ non-linear lifecycle states with transition guards, untrusted third-party user scripts).
+
+### Foundational Leverage vs. Speculative Over-Engineering
+A common misunderstanding is that YAGNI forbids using external libraries. **This is completely false**:
+- **YAGNI Attacks:** Speculative custom code, home-grown frameworks, custom wheel reinvention, and premature multi-tier distributed architectures.
+- **YAGNI Mandates:** Adopting battle-tested, open-source building blocks (`shadcn/ui`, `Tailwind CSS`, `Zod`, `TanStack Query`, `Lombok`) to solve concrete, present requirements with the minimum amount of custom code (preventing Not-Invented-Here / NIH syndrome).
+
 ---
 
-## 6. The Relentless Skill Architecture Inquiry
+## 7. The Relentless Skill Architecture Inquiry
 
 Never architect or modify a skill based on assumptions. Before authoring any `SKILL.md`, run the **7 Core Skill Inquiry Branches**:
 
-```
-[New Skill / Rule Request]
-       │
-       ▼
-[Branch 1: Placement] ────────── Should this be AGENTS.md, a Rule, or a Skill?
-       │
-       ▼
-[Branch 2: Trigger Boundaries] ── Exact 'Use when...' and explicit 'Do NOT use for...'?
-       │
-       ▼
-[Branch 3: Domain Ground Truth] ─ Have generic textbook tutorials been purged?
-       │
-       ▼
-[Branch 4: Gotchas & Anti-Patterns] What specific AI mistakes MUST be forbidden?
-       │
-       ▼
-[Branch 5: Determinism vs LLM] ── Should deterministic steps be scripts in scripts/?
-       │
-       ▼
-[Branch 6: Progressive Bloat] ─── Is SKILL.md < 500 lines with sub-docs in references/?
-       │
-       ▼
-[Branch 7: Verification Loop] ─── Are there output templates and self-checklists?
-       │
-       ▼
-[Ready to Author / Update Skill]
+```mermaid
+flowchart TD
+    Req["New Skill / Rule Request"] --> B1["Branch 1: Placement<br/>AGENTS.md, Rule, or Skill?"]
+    B1 --> B2["Branch 2: Trigger Boundaries<br/>Exact 'Use when...' & 'Do NOT use for...'?"]
+    B2 --> B3["Branch 3: Domain Ground Truth<br/>Generic textbook tutorials purged?"]
+    B3 --> B4["Branch 4: Gotchas & Anti-Patterns<br/>What AI mistakes MUST be forbidden?"]
+    B4 --> B5["Branch 5: Determinism vs LLM<br/>Deterministic steps scripted in scripts/?"]
+    B5 --> B6["Branch 6: Progressive Bloat<br/>SKILL.md < 500 lines with sub-docs in references/?"]
+    B6 --> B7["Branch 7: Verification Loop<br/>Output templates & self-checklists present?"]
+    B7 --> Ready["Ready to Author / Update Skill"]
 ```
 
 ### The 7 Core Inquiry Branches
@@ -159,10 +198,59 @@ Never architect or modify a skill based on assumptions. Before authoring any `SK
 
 ---
 
-## 7. The Continuous Refinement Loop
+## 8. The Continuous Refinement Loop
 
 When an AI produces suboptimal code or documentation:
 1. Preserve the original AI output draft.
 2. Make manual corrections to produce the desired gold-standard output.
 3. Diff the original draft against the corrected version to identify specific gaps.
 4. Update the relevant skill's "What NOT to do" or guideline section to prevent repeating that mistake.
+
+---
+
+## 9. Workspace Sovereignty & Zero Global Interference
+
+Enforce strict workspace containment within the workspace root (`./`):
+- **Ground Truth Boundary**: Only files, dependencies, configuration files (`package.json`, `tsconfig.json`, `docker-compose.yml`), and verified command executions within the local workspace (`./`) constitute project truth.
+- **Zero Global Contamination**: Never import, execute, or assume tools, environment variables, or conventions from global system directories (e.g. `~/.config`, `/tmp`, `~/.gemini/antigravity-cli`, or parent directories) unless explicitly defined within local workspace configuration.
+- **Sibling Project Isolation**: Strictly ignore external or legacy projects. Do not read from or write to directories outside the local repository (`./`).
+- **Subagent Context Sandboxing**: When spawning subagents or executing commands, ensure working directories are anchored strictly to `./`.
+
+---
+
+## 10. Continuous Learning & The Direct Rule Ingestion 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. Synthesize Invariant ──► 4. Update Rule / Skill
+```
+
+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. **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).
+   - Run verification (`npm test && npm run validate`) to ensure 100% integrity.
+
+---
+
+## 11. Architectural Decision Records (ADR) Standards
+
+Significant architectural, technical stack, or invariant decisions must be captured in [`memory.md`](../../memory.md):
+
+### Required ADR Envelope:
+```markdown
+#### ADR-XXX: <Imperative Action-Oriented Title>
+- **Date:** YYYY-MM-DD | **Status:** PROPOSED | ACCEPTED | SUPERSEDED | DEPRECATED
+- **Context:** The specific operational or technical problem, constraint, or trade-off requiring a decision.
+- **Decision:** Concrete, unambiguous architecture choice and positive invariants.
+- **Consequences:** Direct benefits and deliberate operational trade-offs accepted.
+- **Enforced In:** Links to specific rule files in `docs/rules/` or code paths.
+```
+
+### Numbering & Immutability:
+- ADR numbers are monotonically increasing (`ADR-001`, `ADR-002`, ...).
+- ADR entries are **immutable history**. Never edit past accepted ADRs to represent new decisions; author a new ADR that explicitly supersedes the former.
+