azcodr 1.3.0 → 1.5.0

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

@@ -97,6 +97,9 @@ async function runCli(rawArgs = process.argv.slice(2), io = {}) {
       return exit(1);
     } else if (!targetDir) {
       targetDir = arg;
+    } else {
+      err(`❌ Error: Unexpected argument '${arg}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
     }
   }
 
@@ -181,18 +184,20 @@ 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, .github/copilot-instructions.md)');
+      out('  ✅ Project configuration initialized (package.json)');
       if (result.gitInitialized) {
         out('  ✅ Git repository initialized');
       }
 
       out('\n🎉 azcodr initialized successfully!\n');
       out('Next steps:');
+      let step = 1;
       if (targetDir !== '.' && targetDir !== './') {
-        out(`  1. cd ${targetDir}`);
+        out(`  ${step++}. cd ${targetDir}`);
       }
-      out('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
-      out('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
+      out(`  ${step++}. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)`);
+      out(`  ${step++}. Run /lets-build to start the architectural interview and scaffold your application stack!\n`);
     }
     return exit(0);
   } catch (error) {

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,28 @@ 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`
+- GitHub Copilot: `.github/copilot-instructions.md`
 
 **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
+mkdir -p .github && ln -sf ../AGENTS.md .github/copilot-instructions.md
 ```
 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 +85,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 +150,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 +200,60 @@ 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.
+- **Fresh Project Baseline (ADR Clean Slate):** When starting or bootstrapping a new project from this starter template, the memory ledger in [`memory.md`](../../memory.md) must be a clean slate with zero prior decisions recorded. The initial technical foundation derived during `/lets-build` must always be recorded as **`ADR-001`**. Template development history from `azcodr` must never bleed into downstream project memory ledgers.
+

package/docs/rules/api_architecture.md

@@ -0,0 +1,179 @@
+# API Architecture, Protocols & Communication Standards
+
+> **Core Mandate:** Enforce standard HTTP semantics, synchronous vs. asynchronous processing (`202 Accepted`), capability metadata (`_actions`), safe mutations via idempotency keys, keyset cursor pagination, optimistic concurrency control (OCC), and RFC 8594 lifecycle versioning.
+
+---
+
+## 1. Standard HTTP Semantics & Status Codes
+
+APIs must adhere strictly to standard HTTP semantics. Never return `200 OK` for error envelopes:
+
+| Status Code | Semantic Purpose | When to Return |
+|---|---|---|
+| **`200 OK`** | Successful read or synchronous update | Standard `GET`, `PATCH`, `PUT` queries that return payloads. |
+| **`201 Created`** | Successful resource creation | Synchronous `POST` with `Location: /api/v1/resources/:id` header. |
+| **`202 Accepted`** | Asynchronous task accepted | Tasks exceeding latency budgets (> 1.5s) delegated to background queues. |
+| **`204 No Content`** | Successful action with zero payload | Standard `DELETE` or empty mutation responses. |
+| **`400 Bad Request`** | Malformed syntax or protocol violation | Unparseable JSON, invalid query parameters. |
+| **`401 Unauthorized`** | Missing or invalid authentication | Missing, expired, or tampered JWT / API token. |
+| **`403 Forbidden`** | Authenticated but insufficient permission | Role, tenant boundary, or policy guard denial. |
+| **`404 Not Found`** | Resource does not exist | Unknown entity identifier (or masked tenant resource). |
+| **`409 Conflict`** | State conflict or race condition | Concurrency mismatch (`If-Match`), unique constraint, or in-flight idempotency. |
+| **`422 Unprocessable`** | Semantic validation failure | Schema constraint violation (RFC 7807 problem details). |
+| **`500 Internal Error`** | Unhandled server exception | Unexpected server failure; never leak internal stack traces. |
+
+### Subresource URL Conventions
+- Express relational hierarchy cleanly: `/api/v1/organizations/:orgId/projects/:projectId/members`.
+- Limit URL nesting to a maximum of 2 subresource levels; for deeper resources, access directly via canonical ID (`/api/v1/tasks/:taskId`).
+
+### Enumeration Masking
+- Authentication and recovery endpoints must never reveal user existence (e.g. return `"If an account exists, a recovery link has been sent"` with identical timing).
+
+---
+
+## 2. Synchronous vs. Asynchronous Processing (`202 Accepted`)
+
+Operations with unpredictable or long execution durations (> 1.5 seconds, such as video rendering, large PDF exports, batch imports, or complex report generation) must never block synchronous HTTP request threads:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Client
+    participant Gateway as API Gateway
+    participant Queue as Task Queue / Worker
+    
+    Client->>Gateway: POST /reports/export (Long-running > 1.5s)
+    Gateway->>Queue: Dispatch background job
+    Gateway-->>Client: 202 Accepted (Location: /api/v1/tasks/tsk_123)
+    Note over Client,Gateway: Client polls GET /api/v1/tasks/tsk_123 until complete
+```
+
+### Protocol Standards:
+1. Dispatch the payload to a persistent worker queue (e.g., BullMQ, Temporal, Celery).
+2. Respond immediately with **`202 Accepted`** containing:
+   - Header: `Location: /api/v1/tasks/:taskId`
+   - Envelope:
+     ```json
+     {
+       "taskId": "tsk_123",
+       "status": "QUEUED",
+       "pollIntervalMs": 2000,
+       "_links": {
+         "status": { "href": "/api/v1/tasks/tsk_123", "method": "GET" },
+         "cancel": { "href": "/api/v1/tasks/tsk_123", "method": "DELETE" }
+       }
+     }
+     ```
+3. Polling endpoint (`GET /api/v1/tasks/:taskId`) returns:
+   - In-progress: `200 OK` with status `PROCESSING` and progress percentage.
+   - Finished: `303 See Other` with `Location: /api/v1/reports/rep_789` or `200 OK` with `status: "COMPLETED"` and the final artifact URI.
+
+---
+
+## 3. Allowed Actions & Capability Metadata (`_actions` Envelope)
+
+Clients must not duplicate complex server-side business and authorization rules to decide whether UI actions (edit, delete, approve, cancel, refund) are permitted. **The server is the authoritative source of truth.**
+
+### Pattern: `_actions` and `_links` Envelope
+Every resource response must embed an `_actions` boolean map and optional `_links` hypermedia block indicating what the requesting caller is permitted to do based on their role, tenant boundaries, and the entity's current lifecycle state:
+
+```json
+{
+  "id": "ord_9876",
+  "status": "SHIPPED",
+  "totalAmount": 149.99,
+  "currency": "USD",
+  "_actions": {
+    "canEdit": false,
+    "canCancel": false,
+    "canTrack": true,
+    "canRequestRefund": true
+  },
+  "_links": {
+    "self": { "href": "/api/v1/orders/ord_9876", "method": "GET" },
+    "track": { "href": "/api/v1/orders/ord_9876/tracking", "method": "GET" },
+    "refund": { "href": "/api/v1/orders/ord_9876/refunds", "method": "POST" }
+  }
+}
+```
+
+### Frontend Binding:
+- UI action buttons directly bind visibility or disabled state to `resource._actions.canCancel`.
+- When business logic evolves (e.g. orders over $1,000 require manager approval), only backend policy changes—zero frontend redeployment required.
+
+---
+
+## 4. Safe Mutations via Idempotency Keys (IETF Draft)
+
+To prevent duplicate execution (double charging, duplicate orders) caused by network retries or transient connection drops:
+
+### Protocol Standards:
+- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
+- **Server Execution Lifecycle**:
+  1. Check distributed idempotency cache for key `idemp:<tenantId>:<idempotencyKey>`.
+  2. If found with status `IN_FLIGHT`: return **`409 Conflict`** (`IDEMPOTENT_OPERATION_IN_PROGRESS`).
+  3. If found with status `COMPLETED`: return the cached HTTP status code, headers, and response payload without re-executing.
+  4. If not found: Acquire distributed lock, execute mutation within an atomic database transaction, cache the response envelope with a 24-hour TTL, and release the lock.
+
+---
+
+## 5. High-Scale Keyset / Cursor-Based Pagination
+
+Never use offset pagination (`OFFSET 10000 LIMIT 20`) on large tables. Offsets degrade linearly ($O(N)$) and suffer from page-drift anomalies as rows are inserted or deleted.
+
+### Specification & Envelope:
+- Query Parameters: `?cursor=<opaque_base64>&limit=20` (default limit 20, max 100).
+- Response Envelope:
+  ```json
+  {
+    "data": [...],
+    "pagination": {
+      "nextCursor": "ZXlKaWRI...==",
+      "hasMore": true,
+      "limit": 20
+    }
+  }
+  ```
+- **Agnostic Keyset Query Pattern**:
+  ```sql
+  SELECT * FROM orders
+  WHERE tenant_id = :tenantId
+    AND (created_at, id) < (:cursorCreatedAt, :cursorId)
+  ORDER BY created_at DESC, id DESC
+  LIMIT :limit + 1;
+  ```
+  If `results.length > limit`, slice the extra item and encode its composite values (`created_at`, `id`) into the base64 `nextCursor`.
+
+---
+
+## 6. Optimistic Concurrency Control (OCC)
+
+Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
+
+### Protocol Standards:
+- Every mutable entity contains an incrementing integer `version` column.
+- The server returns the current entity version in the `ETag` response header: `ETag: W/"v4"`.
+- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
+- **Atomic Concurrency Handling**:
+  ```sql
+  UPDATE orders 
+  SET status = :status, version = version + 1 
+  WHERE id = :id AND version = :expectedVersion;
+  ```
+  - If `rows_affected == 0`: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
+
+---
+
+## 7. API Versioning & RFC 8594 Lifecycle Deprecation
+
+### URI Versioning Standard
+- Standardize on explicit path versioning: `/v1/`, `/v2/`.
+- Never introduce breaking changes within an active major version:
+  - *Non-Breaking (Permitted in `/v1/`):* Adding optional fields, adding new endpoints, adding new enum variants.
+  - *Breaking (Demands `/v2/`):* Renaming/removing fields, changing validation constraints, altering status codes.
+
+### RFC 8594 Sunset & Deprecation Headers
+When deprecating an endpoint, provide clients with a minimum 90-day grace period:
+- `Deprecation: @<unix-timestamp>`: Date when the endpoint was deprecated.
+- `Sunset: <HTTP-date>`: Absolute date when the endpoint will return `410 Gone`.
+- `Link: </api/v2/docs>; rel="sunset"`: Link to migration documentation.

package/docs/rules/caching.md

@@ -4,20 +4,37 @@
 
 ---
 
-## 1. Abstract Cache Port & Cache-Aside Pattern
+## 1. The YAGNI Gate: Database First, Caching Second
 
-Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+Caching introduces state duplication, cache invalidation race conditions, and memory overhead. **Caching is never a substitute for missing database indexes or poorly structured SQL queries.**
 
+```mermaid
+flowchart TD
+    subgraph CachingGate["Caching YAGNI Gate"]
+        B1["1. Simple Baseline (Day 1)<br/>• Relational queries with composite indexes<br/>• Request-scoped in-memory DataLoader batching to eliminate N+1<br/>• Zero distributed cache infrastructure (no Redis / Memcached)"]
+        B2["2. Anti-Triggers (Forbidden)<br/>• Queries that are slow due to missing indexes or sequential scans<br/>• High-write / high-churn entities (write-heavy mutation streams)<br/>• Low-traffic administrative or internal operational queries"]
+        B3["3. The Tipping Point (Graduation)<br/>• Query has been optimized with EXPLAIN ANALYZE, but p99 latency still exceeds SLA (> 100ms)<br/>• Read-to-write asymmetry on the entity exceeds 20:1<br/>• Downstream external API rate limits or third-party egress costs demand response caching"]
+        B1 -->|Forbidden if missing indexes| B2
+        B1 -->|Triggered by high read/write ratio| B3
+    end
 ```
-┌────────────────────────────────────────────────────────┐
-│ Cache Port Interface (Agnostic Contract)               │
-├────────────────────────────────────────────────────────┤
-│ get(key): Optional<String>                             │
-│ set(key, value, ttlSeconds): void                      │
-│ delete(key): void                                      │
-│ deletePattern(pattern): void                           │
-│ acquireLock(lockKey, ttlMs): boolean                   │
-└────────────────────────────────────────────────────────┘
+
+---
+
+## 2. Abstract Cache Port & Cache-Aside Pattern
+
+Application services interact with caching infrastructure through a swappable **Cache Port**, supporting any backend (Redis, Valkey, Dragonfly, KeyDB, Memcached, or in-memory LRU):
+
+```mermaid
+classDiagram
+    class CachePort {
+        <<interface>>
+        +get(key: string) Optional~string~
+        +set(key: string, value: string, ttlSeconds: number) void
+        +delete(key: string) void
+        +deletePattern(pattern: string) void
+        +acquireLock(lockKey: string, ttlMs: number) boolean
+    }
 ```
 
 ### Cache-Aside Implementation & Stampede Defense
@@ -38,7 +55,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 2. Key Namespacing & Event-Driven Invalidation
+## 3. Key Namespacing & Event-Driven Invalidation
 
 - **Universal Key Hierarchy**: Structure all keys hierarchically:
   `tenant:{tenantId}:{entity}:{entityId}` (e.g. `tenant:123:order:987`)
@@ -46,7 +63,7 @@ For high-throughput cache regeneration, employ the **XFetch algorithm** (probabi
 
 ---
 
-## 3. HTTP Conditional Caching (ETags)
+## 4. HTTP Conditional Caching (ETags)
 
 - Generate strong cryptographic `ETag` hashes (e.g. SHA-256 of representation or resource version) for cacheable `GET` endpoints.
 - Return **`304 Not Modified`** with zero payload body when inbound requests present matching `If-None-Match` headers, preserving bandwidth and client CPU.

package/docs/rules/cloud_native.md

@@ -28,16 +28,14 @@ All application processes and containers must handle graceful termination:
 - Drain active, in-flight connections within a bounded timeout window (e.g. 10 seconds).
 - Gracefully flush telemetry buffers, terminate background workers, and close database/cache connection pools cleanly before exiting with code 0:
 
-```
-┌────────────────────────────────────────────────────────┐
-│ Graceful Shutdown Flow (Universal / Agnostic)          │
-├────────────────────────────────────────────────────────┤
-│ onSignal(SIGTERM | SIGINT):                            │
-│   1. Set health check probe to UNHEALTHY (drain LB)    │
-│   2. Stop server listening for new connections         │
-│   3. Wait for in-flight requests (timeout: 10s)        │
-│   4. Close database and cache connection pools         │
-│   5. Flush OpenTelemetry trace & log buffers           │
-│   6. Terminate process with exit code 0                │
-└────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    subgraph GracefulShutdown["Graceful Shutdown Flow (Universal / Agnostic)"]
+        Sig["onSignal (SIGTERM | SIGINT)"] --> S1["1. Set health check probe to UNHEALTHY (drain LB)"]
+        S1 --> S2["2. Stop server listening for new connections"]
+        S2 --> S3["3. Wait for in-flight requests (timeout: 10s)"]
+        S3 --> S4["4. Close database and cache connection pools"]
+        S4 --> S5["5. Flush OpenTelemetry trace & log buffers"]
+        S5 --> S6["6. Terminate process with exit code 0"]
+    end
 ```