azcodr 1.3.0 → 1.5.0

package/memory.md

@@ -17,139 +17,20 @@
 
 | ID | Title | Date | Status | Governing Rule / Skill |
 |---|---|---|---|---|
-| **ADR-001** | 100% Open-Source Tooling & Framework Mandate | 2026-09-16 | ACCEPTED | [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md) |
-| **ADR-002** | Progressive Disclosure Architecture for Agentic Context | 2026-09-16 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md) |
-| **ADR-003** | Dual-Layer Multi-Tenancy Isolation with PostgreSQL RLS | 2026-09-16 | ACCEPTED | [`multitenancy_isolation.md`](./docs/rules/multitenancy_isolation.md) |
-| **ADR-004** | Systemic Atomicity & Pure Single-Responsibility Rule Decomposition | 2026-09-16 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md) |
-| **ADR-005** | Universal Technology, Language, and Stack Agnosticism | 2026-09-18 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md) |
-| **ADR-006** | Mandatory Full Lifecycle CRUD & Relational FK Selector Pattern | 2026-09-18 | ACCEPTED | [`database_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md) |
-| **ADR-007** | Decoupling Project Bootstrapping from Domain Analysis | 2026-09-18 | ACCEPTED | [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md) |
-| **ADR-008** | Non-Negotiable 5-Phase Agile Domain Lifecycle & Outside-In TDD | 2026-09-18 | ACCEPTED | [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`test_isolation.md`](./docs/rules/test_isolation.md) |
-| **ADR-009** | Many-to-Many Skill Composability & Orthogonal Pipelines | 2026-09-18 | ACCEPTED | [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md) |
-| **ADR-011** | Canonical 6 Total Audit Fields Architecture & Modern React Stack | 2026-09-19 | ACCEPTED | [`database_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.md) |
-| **ADR-012** | State Machine Lifecycle Configurability & Ubiquitous Language Contract | 2026-09-19 | ACCEPTED | [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md) |
-| **ADR-013** | Design Architecture Triage, Persistent Shell & Dev Persona Isolation | 2026-09-20 | ACCEPTED | [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md), [`authentication.md`](./docs/rules/authentication.md) |
-| **ADR-014** | Product Ownership, Prioritization Models, SMART Tasks & INVEST Slicing | 2026-09-21 | ACCEPTED | [`product_ownership.md`](./docs/rules/product_ownership.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`project_management.md`](./docs/rules/project_management.md) |
-| **ADR-015** | Problem-First Architecture, Topology Scaffolding, Tipping Points & Nano-TDD | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md) |
-| **ADR-016** | Elimination of Static Markdown Knowledge Graph | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`continuous_learning.md`](./docs/rules/continuous_learning.md) |
-| **ADR-017** | Progressive Rules Consolidation (DDD & GoF Patterns) | 2026-09-25 | ACCEPTED | [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`design_patterns.md`](./docs/rules/design_patterns.md) |
-| **ADR-018** | Elimination of Upstream Changes Ledger and Sync Tooling | 2026-09-25 | ACCEPTED | [`clean_code.md`](./docs/rules/clean_code.md), [`workspace_isolation.md`](./docs/rules/workspace_isolation.md) |
-
+| *(No decisions recorded yet)* | *Record initial architecture decisions during Phase 3 of /lets-build.* | *YYYY-MM-DD* | *ACCEPTED* | *e.g. [`clean_code.md`](./docs/rules/clean_code.md)* |
 
 ---
 
 ### Lightweight Decision Summaries
 
-#### ADR-001: 100% Open-Source Tooling & Framework Mandate
-- **Date:** 2026-09-16 | **Status:** ACCEPTED
-- **Context:** Proprietary SaaS dependencies introduce vendor lock-in, recurring operational costs, and black-box security risks.
-- **Decision:** Standardize exclusively on open-source solutions across all architectural domains (PostgreSQL, Redis, Trivy, Semgrep, Gitleaks, OpenTelemetry, Vitest, Playwright, Radix UI).
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`compliance.md`](./docs/rules/compliance.md), [`devsecops.md`](./docs/rules/devsecops.md).
-
-#### ADR-002: Progressive Disclosure Architecture for Agentic Context
-- **Date:** 2026-09-16 | **Status:** ACCEPTED
-- **Context:** Injecting large monolithic documentation files on every AI prompt exhausts token windows and degrades model attention.
-- **Decision:** Keep root `AGENTS.md` lean (≤ 120 lines), decoupling specialized engineering manuals into modular files under `docs/rules/` and skills under `.agents/skills/`.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md).
-
-#### ADR-003: Dual-Layer Multi-Tenancy Isolation with PostgreSQL RLS
-- **Date:** 2026-09-16 | **Status:** ACCEPTED
-- **Context:** Application-level `where: { tenantId }` filtering is prone to human error, risking catastrophic cross-tenant data leaks.
-- **Decision:** Combine application middleware context resolution with database-level PostgreSQL Row-Level Security (RLS) policies as an immutable backstop.
-- **Enforced In:** [`multitenancy_isolation.md`](./docs/rules/multitenancy_isolation.md).
-
-#### ADR-004: Systemic Atomicity & Pure Single-Responsibility Rule Decomposition
-- **Date:** 2026-09-16 | **Status:** ACCEPTED
-- **Context:** Composite rules with conjunction names (`this_and_that.md`) mix disparate technical concerns, creating documentation bloat and ambiguity.
-- **Decision:** Decompose all rules into strictly atomic, single-topic rule files with zero conjunction names, enforcing Single Responsibility Principle across skills, rules, and database operations.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`agentic_configuration.md`](./docs/rules/agentic_configuration.md).
-
-#### ADR-005: Universal Technology, Language, and Stack Agnosticism
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Coupling architecture rules to a single programming language or database creates technical lock-in and prevents polyglot implementation.
-- **Decision:** Adopt a Two-Tier Hexagonal / Ports-and-Adapters model across the entire system: Tier 1 mandates 100% technology-, language-, and stack-agnostic invariant domain capabilities and open standard specifications; Tier 2 encapsulates interchangeable polyglot adapters.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md).
-
-#### ADR-006: Mandatory Full Lifecycle CRUD & Relational Foreign Key Selector Pattern
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Prototypes often provide partial CRUD, leaving entities un-editable or undeletable. Exposing foreign keys as raw text inputs causes severe relational errors.
-- **Decision:** Every feature must implement complete lifecycle CRUD (Create, Read/Detail, Update/Transition, Delete/Archive) with 100.00% test coverage. Foreign keys must never be exposed as raw string inputs; they must be resolved via accessible relational dropdown selectors displaying contextual business metadata.
-- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`rest_api_conventions.md`](./docs/rules/rest_api_conventions.md), [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md).
-
-#### ADR-007: Strict Decoupling of Project Bootstrapping from Domain Analysis
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Agents running `/lets-build` frequently fabricate domain entities on sheer assumptions during technical bootstrapping, skipping requirements discovery.
-- **Decision:** Project bootstrapping terminates strictly after technical skeleton creation and health probe verification (`Phase 5`). A mandatory Handover Gate halts coding and directs the agent to initiate Domain Analysis via `product-analyst` and `relentless-questioner` before domain models or schemas are authored.
-- **Enforced In:** [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md).
-
-#### ADR-008: Non-Negotiable 5-Phase Agile Domain Lifecycle & Outside-In TDD Invariant
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Writing production code before tests or domain understanding leads to brittle code, regressions, and "toy prototypes."
-- **Decision:** Enforce an immutable 5-Phase Agile Domain Lifecycle across all tasks (Requirements ➔ Domain Analysis ➔ Outer Acceptance RED ➔ Inner Unit TDD RED-GREEN-REFACTOR ➔ Outer GREEN & DoD). Writing production code without a failing test is strictly prohibited.
-- **Enforced In:** Root [`AGENTS.md`](./AGENTS.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`test_isolation.md`](./docs/rules/test_isolation.md).
-
-#### ADR-009: Many-to-Many Skill Composability & Orthogonal Pipeline Architecture
-- **Date:** 2026-09-18 | **Status:** ACCEPTED
-- **Context:** Complex engineering tasks require multiple orthogonal skills; coupling skills into monolithic bundles causes context bloat and cross-contamination.
-- **Decision:** Codify Many-to-Many skill composability via three formal patterns: Sequential Pipeline Chaining, Dynamic Skill Stacking, and Multi-Agent Subagent Delegation, with standardized output contracts, pure function semantics, and zero cross-contamination.
-- **Enforced In:** [`agentic_configuration.md`](./docs/rules/agentic_configuration.md), [`agentic-architect`](./.agents/skills/agentic-architect/SKILL.md).
-
-#### ADR-011: The Canonical 6 Total Audit Fields Architecture & Modern React Stack
-- **Date:** 2026-09-19 | **Status:** ACCEPTED
-- **Context:** Inconsistent audit tracking risks SOC 2 / ISO 27001 non-compliance. Frontend `useEffect` fetch loops cause stale states and race conditions.
-- **Decision:** Every mutable stateful table must implement the Canonical 6 Total Audit Fields (`createdAt`, `createdBy`, `updatedAt`, `updatedBy`, `deletedAt`, `deletedBy`), with append-only ledgers omitting update/delete fields. Standardize frontend on TanStack Query, React Hook Form + Zod, and headless Radix primitives.
-- **Enforced In:** [`database_integrity.md`](./docs/rules/database_integrity.md), [`react.md`](./docs/rules/react.md).
-
-#### ADR-012: State Machine Lifecycle Configurability & Living Ubiquitous Language Contract
-- **Date:** 2026-09-19 | **Status:** ACCEPTED
-- **Context:** Unconstrained state configurability causes the "Inner Platform Effect." Linguistic drift between business terms and code identifiers breaks domain models.
-- **Decision:** Bifurcate state into Core Invariant States (Hard FSM in compiled aggregate roots) and Operational Workflow Stages (Soft FSM in declarative JSON state transition matrices evaluated via CEL/Temporal). Maintain a living, single-name Ubiquitous Language Glossary contract.
-- **Enforced In:** [`workflow_state_machines.md`](./docs/rules/workflow_state_machines.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`ubiquitous_language.md`](./docs/knowledge/ubiquitous_language.md).
-
-#### ADR-013: Design Architecture Triage Framework, Persistent Shell & Dev Persona Isolation
-- **Date:** 2026-09-20 | **Status:** ACCEPTED
-- **Context:** Conflating developer demo personas with production auth creates toy-like prototypes. Untriaged UI produces layout shifts and broken navigation.
-- **Decision:** Mandate the 7-Pillar Design Architecture Triage Gate before writing UI code; separate Enterprise Operator Workspace (`/`) from Consumer Portal (`/portal`); standardize on a persistent shell with 64px collapsible icon rail and bidirectional URL state sync; strictly isolate developer demo personas into a dev-only floating toolbar (`import.meta.env.DEV`).
-- **Enforced In:** [`ui_ux_architecture.md`](./docs/rules/ui_ux_architecture.md), [`authentication.md`](./docs/rules/authentication.md), [`ui_navigation.md`](./docs/rules/ui_navigation.md).
-
-#### ADR-014: Product Ownership, Backlog Prioritization Models, SMART Developer Tasks & INVEST Slicing
-- **Date:** 2026-09-21 | **Status:** ACCEPTED
-- **Context:** Teams frequently measure output (lines of code, story points) rather than outcome (customer value), leading to the "Feature Factory" anti-pattern.
-- **Decision:** Ground backlog ordering in quantitative prioritization (Kano, MoSCoW, RICE) aligned with OKRs; decompose epics into vertically sliced INVEST user stories; decompose user stories into bounded SMART developer tasks (2–4 hours).
-- **Enforced In:** [`product_ownership.md`](./docs/rules/product_ownership.md), [`requirements_engineering.md`](./docs/rules/requirements_engineering.md), [`project_management.md`](./docs/rules/project_management.md), [`product-analyst`](./.agents/skills/product-analyst/SKILL.md).
-
-#### ADR-015: Problem-First Architecture, Topology Scaffolding, Evolutionary Tipping Points & Incremental Nano-Cycle TDD
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Tool-first planning (asking for languages, databases, and microservices upfront) creates accidental complexity and forces non-backend projects (such as Chrome extensions, game engines, or CLIs) into heavy enterprise templates (as observed in `force-dark-light`). Furthermore, AI assistants naturally accelerate architectural drift by appending code without structural evolution, and fake TDD by batch-generating 15 tests and implementations at once.
-- **Decision:**
-  1. Enforce **Problem-First Architecture**: Strictly separate Problem Space from Solution Space (Evans, Vernon, Brooks). Derive tools and runtimes from problem constraints (latency budget, GC tolerance, memory, execution target).
-  2. Implement **Topology-Aware Scaffolding**: Eliminate universal templates. Match architectural styles to system topologies (Platform Scripting for extensions, Data-Oriented Design for game engines, Command Pipeline for CLIs, Hexagonal for enterprise backends).
-  3. Codify **Evolutionary Architecture & Architectural Tipping Points**: Enforce Kent Beck's "Refactor-Before-Add" protocol and 5 explicit tipping points to halt AI-generated code rot.
-  4. Mandate **True Incremental TDD & Nano-Cycles**: Prohibit batch-test dumps ("Test-First Waterfall"); enforce Uncle Bob's Three Laws (especially Law #2) and Ping-Pong pair programming with verified RED failure proofs.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`test_driven_development.md`](./docs/rules/test_driven_development.md), [`lets-build`](./.agents/skills/lets-build/SKILL.md), [`architecture_interview_matrix.md`](./.agents/skills/lets-build/references/architecture_interview_matrix.md).
-
-#### ADR-016: Elimination of Static Markdown Knowledge Graph in Favor of Code-as-Truth & Living Glossary
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Template repositories often maintain static markdown files containing Mermaid diagrams, ERDs, and component topologies (`docs/knowledge/knowledge_graph.md`). In practice, these static artifacts suffer from rapid maintenance drift, violate the Problem-First mandate by pre-fabricating multi-tenant web backend models before the user defines their project, duplicate existing domain rules and memory records, and become stale tokens consumed on every context load.
-- **Decision:** Permanently delete `docs/knowledge/knowledge_graph.md`. Treat executable code, strict type definitions, and versioned database migrations as the sole source of truth for architectural topologies. Retain `docs/knowledge/ubiquitous_language.md` as the lightweight, living domain vocabulary contract.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`clean_code.md`](./docs/rules/clean_code.md), [`continuous_learning.md`](./docs/rules/continuous_learning.md), [`memory.md`](./memory.md).
-
-#### ADR-017: Progressive Rules Consolidation (DDD & GoF Design Patterns)
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Multiple domain rules exhibited redundant overlaps: `domain_expertise.md` duplicated strategic capability mapping and tactical aggregate invariants already governed by `domain_driven_design.md`, while `gof_design_patterns_reference.md` artificially fragmented design patterns into a separate satellite file from `design_patterns.md`. This fragmentation caused token bloat in `AGENTS.md` and scattered domain invariants.
-- **Decision:**
-  1. Merge business capability tiering (Core/Supporting/Generic) and the Aggregate Root Gatekeeper invariant example into [`domain_driven_design.md`](./docs/rules/domain_driven_design.md). Delete redundant `domain_expertise.md`.
-  2. Consolidate the 23 Gang of Four patterns catalog directly into [`design_patterns.md`](./docs/rules/design_patterns.md). Delete redundant `gof_design_patterns_reference.md`.
-  3. Streamline rule catalog across `AGENTS.md` and `README.md` to 45 lean, single-responsibility, non-overlapping rules.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), [`domain_driven_design.md`](./docs/rules/domain_driven_design.md), [`design_patterns.md`](./docs/rules/design_patterns.md).
-
-#### ADR-018: Elimination of Upstream Changes Ledger and Upstream Sync Tooling
-- **Date:** 2026-09-25 | **Status:** ACCEPTED
-- **Context:** Maintaining a manual `changes.md` ledger duplicated state already captured across Git commit history and formal ADR records in `memory.md`. Furthermore, scaffolding `changes.md` into downstream derived projects contaminated them with meta-tooling baggage about the upstream template, violating Problem-First Architecture and Workspace Sovereignty. Accompanying CLI subcommands (`npx azcodr change`) and rule files (`upstream_synchronization.md`) added over 200 lines of accidental maintenance complexity.
-- **Decision:**
-  1. Permanently delete `changes.md` and retire `docs/rules/upstream_synchronization.md`.
-  2. Remove `changes.md` from scaffolded `TEMPLATE_ITEMS` and package manifests.
-  3. Purge `logChange` functions, types, and CLI subcommands, restoring `azcodr` CLI as a clean, single-purpose project bootstrapper.
-  4. Standardize exclusively on Git commits for historical revision logs and `memory.md` for architectural decision records.
-- **Enforced In:** [`AGENTS.md`](./AGENTS.md), [`README.md`](./README.md), [`lib/scaffold.js`](./lib/scaffold.js), [`bin/azcodr.js`](./bin/azcodr.js), [`memory.md`](./memory.md).
-
+<!--
+Record project Architectural Decision Records (ADRs) below as decisions are finalized.
+Format:
+
+#### ADR-001: [Imperative Title]
+- **Date:** YYYY-MM-DD | **Status:** ACCEPTED
+- **Context:** Problem space, constraints, and operational context requiring a decision.
+- **Decision:** Chosen architecture, invariants, and implementation patterns.
+- **Consequences:** Positive benefits and deliberate trade-offs accepted.
+- **Enforced In:** Relevant rule files in docs/rules/ or code paths.
+-->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azcodr",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Enterprise Architecture & Agentic Engineering Starter Template",
   "bin": {
     "azcodr": "bin/azcodr.js"
@@ -54,6 +54,6 @@
     "test:coverage": "node scripts/test_coverage.js",
     "lint": "node --check bin/azcodr.js lib/index.js lib/scaffold.js tests/cli.test.js tests/scaffold.test.js scripts/test_coverage.js",
     "validate": "bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh",
-    "prepublishOnly": "npm run test:coverage && npm run validate"
+    "prepublishOnly": "npm run lint && npm run test:coverage && npm run validate"
   }
 }

package/docs/rules/accessibility.md

@@ -1,31 +0,0 @@
-# Accessibility (A11y) & WCAG 2.2 Standards
-
-> **Core Mandate:** Enforce WCAG 2.2 Level AA compliance, accessible Radix UI primitives, keyboard focus management, visible focus rings, and ARIA live regions across all user interfaces.
-
----
-
-## 1. Accessible UI Primitives & Radix UI
-
-- **Prohibited Native Alerts**: Strictly prohibit browser-native `window.confirm()` or `window.alert()`. Use accessible Radix UI dialogs (`@radix-ui/react-dialog`, `@radix-ui/react-alert-dialog`).
-- **Focus Management & Trapping**:
-  - Modal dialogs must trap keyboard focus within the dialog container while open.
-  - Closing a dialog must return keyboard focus deterministically to the triggering element.
-- **Visible Focus Indicators**: Never remove default outline rings (`outline: none`) without providing an explicit, high-contrast replacement (`focus-visible:ring-2 focus-visible:ring-offset-2`).
-
----
-
-## 2. Form & Feedback Accessibility
-
-- **Form Input Wiring**:
-  - Every form input must have an associated `<label>` using `htmlFor` or nested wrapping.
-  - Validation errors must be programmatically linked to their inputs via `aria-invalid="true"` and `aria-describedby="<error-message-id>"`.
-- **Dynamic Content & Status Feedback (ARIA Live Regions)**:
-  - Asynchronous notifications, toast alerts, and status updates must use `role="status"` or `aria-live="polite"` so screen readers announce changes without interrupting the user.
-  - Critical error alerts must use `role="alert"` or `aria-live="assertive"`.
-
----
-
-## 3. Visual & Contrast Baselines
-
-- **Color Contrast**: Maintain a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text / UI controls against their background.
-- **Semantic Landmark Markup**: Use semantic landmark elements (`<main>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<section>`) rather than unsemantic `<div>` structures.

package/docs/rules/advanced_api_patterns.md

@@ -1,104 +0,0 @@
-# Advanced REST API Patterns & Capability Architecture
-
-> **Core Mandate:** Enrich API responses with capability metadata (Allowed Actions), ensure safe mutations via idempotency keys, enforce cursor pagination, and prevent race conditions with optimistic concurrency.
-
----
-
-## 1. Allowed Actions & Capability Metadata (HATEOAS-Lite)
-
-Clients must not duplicate server-side business and authorization rules to decide whether an action (edit, delete, approve, cancel) is 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 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" }
-  }
-}
-```
-
-### UI Benefits
-- Frontend buttons and menus simply bind to `resource._actions.canDelete`.
-- When business logic evolves (e.g. orders over $1,000 require manager approval), only the backend logic changes—zero frontend redeployment required.
-
----
-
-## 2. Safe Mutations via Idempotency Keys (IETF Draft)
-
-To prevent duplicate processing (double charging, duplicate resource creation) caused by network retries:
-
-### Protocol
-- Clients generating mutating requests (`POST`, `PATCH`) must supply a unique `Idempotency-Key: <uuid-v4>` header.
-- **Server Lifecycle**:
-  1. Check distributed idempotency store 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 status code, headers, and response payload without re-executing.
-  4. If not found: Acquire distributed lock, process mutation atomically, cache response with a 24-hour TTL, and release lock.
-
----
-
-## 3. 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.
-
-### Specification
-- 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 cursor token for `nextCursor`.
-
----
-
-## 4. Optimistic Concurrency Control (OCC)
-
-Prevent lost-update anomalies during concurrent edits without pessimistic database row locking:
-
-### Protocol
-- Every mutable entity contains an incrementing integer `version` column.
-- Server returns the current version in the `ETag` response header: `ETag: W/"v4"`.
-- Clients submitting updates (`PUT`, `PATCH`) must include `If-Match: W/"v4"`.
-- **Conflict Handling**:
-  - Atomic update: `UPDATE table SET ..., version = version + 1 WHERE id = :id AND version = :expectedVersion`.
-  - If 0 rows updated: Return **`409 Conflict`** with error code `CONCURRENCY_CONFLICT` and the latest entity representation.
-
----
-
-## 5. Asynchronous Processing (`202 Accepted`)
-
-For tasks taking > 1.5 seconds (video rendering, large PDF export, batch imports):
-- Do NOT block synchronous client requests.
-- Dispatch task to an asynchronous worker queue or workflow engine.
-- Return **`202 Accepted`** immediately with:
-  - Header: `Location: /api/v1/tasks/:taskId`
-  - Body: `{ "taskId": "tsk_123", "status": "QUEUED", "pollIntervalMs": 2000 }`

package/docs/rules/api_versioning.md

@@ -1,113 +0,0 @@
-# API Versioning, SemVer Lifecycle & Swagger Multi-Version Architecture
-
-> **Core Mandate:** Enforce URI path major versioning (`/api/v1/`), SemVer 2.0.0 contract specifications, RFC 8594 Sunset/Deprecation headers, a 90-day retirement window, and multi-version Swagger UI exploration.
-
----
-
-## 1. Semantic Versioning (SemVer 2.0.0) in Web APIs
-
-Semantic Versioning maps to Web APIs according to contract stability and backward compatibility:
-
-$$\text{Version Format: } \mathbf{MAJOR.MINOR.PATCH}$$
-
-| SemVer Component | Scope & Impact | Exposure Channel | Example |
-|---|---|---|---|
-| **MAJOR** | Breaking, backwards-incompatible contract modifications. Requires client code/URL changes. | URI Path (`/api/v1/`, `/api/v2/`) & OpenAPI `info.version` | `2.0.0` |
-| **MINOR** | Backwards-compatible additive functionality, new endpoints, or optional attributes. | OpenAPI `info.version`, `API-Version` response header | `1.1.0` |
-| **PATCH** | Backwards-compatible bug fixes, performance optimizations, and documentation fixes. | OpenAPI `info.version`, release tags, telemetry metadata | `1.0.1` |
-
-> [!IMPORTANT]
-> **Why URI Path Exposes MAJOR Only:**
-> Exposing minor or patch versions in the URL path (e.g. `/api/v1.2.3/`) is a severe anti-pattern. Minor additions and bug fixes must not break client routing. Clients bind to the stable major version (`/api/v1/`) while consuming backward-compatible updates transparently.
-
----
-
-## 2. SemVer Trigger Matrix: What Triggers a Version Update?
-
-### A. MAJOR Bump (`1.x.x` ➔ `2.0.0`) — Breaking Changes
-A MAJOR version bump and a new URI prefix (`/api/v2/`) are triggered whenever existing clients would fail without code modifications:
-
-1. **Endpoint Alterations:**
-   - Deleting an existing endpoint or HTTP method.
-   - Renaming an existing URL path or subresource route.
-2. **Request Contract Breaking Changes:**
-   - Removing an existing request parameter (header, query, or body field).
-   - Renaming a request field.
-   - Changing the data type or format of a request field (e.g., string integer to number, date format change).
-   - Adding a new **mandatory / required** field to an existing request payload without a default value.
-   - Tightening input validation constraints (e.g., reducing max string length, narrowing allowed enum values).
-3. **Response Contract Breaking Changes:**
-   - Removing an existing field from a response payload.
-   - Changing the data type or structure of a response field (e.g., object converted to array, integer cents converted to float string).
-   - Changing the semantic business meaning of a field.
-4. **Behavioral & Protocol Breaking Changes:**
-   - Altering the standard HTTP status code for successful execution (e.g., changing `200 OK` to `204 No Content` or `201 Created`).
-   - Changing the error envelope schema away from RFC 7807 problem details.
-   - Changing authentication or authorization requirements (e.g. requiring a new OAuth scope or mTLS).
-
-### B. MINOR Bump (`1.0.x` ➔ `1.1.0`) — Additive, Backward-Compatible
-A MINOR version bump preserves the `/api/v1/` URI path and updates the contract specification:
-
-1. Adding completely new endpoints or resources (e.g., adding `POST /api/v1/documents/:id/signatures`).
-2. Adding new optional query parameters, headers, or request body fields.
-3. Adding new fields to response payloads (clients must follow Postel's Law / Tolerant Reader pattern).
-4. Adding new enum values to input requests if the service handles them gracefully without breaking old clients.
-5. Relaxing validation constraints (e.g., increasing maximum allowed file upload size or string length).
-6. Introducing deprecation notices on endpoints (via RFC 8594 headers) while maintaining functionality.
-
-### C. PATCH Bump (`1.0.0` ➔ `1.0.1`) — Bug Fixes & Non-Contractual Changes
-A PATCH version bump preserves contract schemas and updates release metadata:
-
-1. Internal bug fixes in domain logic that do not alter the contractual request/response schema or status codes.
-2. Performance enhancements, caching optimization, and database indexing.
-3. Security patches in dependencies and runtime frameworks.
-4. Clarifications, typo corrections, and formatting updates in OpenAPI descriptions.
-
----
-
-## 3. RFC 8594 Sunset & Deprecation Lifecycle
-
-When an older major version or endpoint is scheduled for retirement, inject standardized RFC 8594 headers:
-
-```http
-Deprecation: @1773619200
-Sunset: Wed, 16 Sep 2026 23:59:59 GMT
-Link: <https://api.domain.com/docs/migration/v2>; rel="sunset"
-```
-
-- **Mandatory 90-Day Migration Window:** Retain deprecated API versions for a minimum of 90 days following formal deprecation notification before decommissioning.
-- **Access Telemetry:** Track consumer traffic on deprecated routes via OpenTelemetry attributes (`api.deprecated=true`, `http.route`) to coordinate client migration.
-
----
-
-## 4. Swagger UI Multi-Version Selector Architecture
-
-Swagger UI must provide an interactive version dropdown selector enabling consumers and developers to inspect both active and upcoming API specifications.
-
-### Multi-Spec Configuration in Express / Swagger UI:
-```ts
-app.use(
-  '/docs',
-  swaggerUi.serve,
-  swaggerUi.setup(undefined, {
-    swaggerOptions: {
-      urls: [
-        { url: '/specs/v1/openapi.yaml', name: 'v1.0.0 (Current Stable)' },
-        { url: '/specs/v2/openapi.yaml', name: 'v2.0.0-draft (Next Major Preview)' }
-      ],
-      'urls.primaryName': 'v1.0.0 (Current Stable)'
-    }
-  })
-);
-```
-
-### Filesystem Specification Hierarchy:
-```
-specs/
-├── openapi/
-│   ├── v1/
-│   │   └── openapi.yaml
-│   └── v2/
-│       └── openapi.yaml
-```
-

package/docs/rules/application_security.md

@@ -1,23 +0,0 @@
-# Application Security & OWASP Top 10 Defenses
-
-> **Core Mandate:** Enforce proactive defenses against the OWASP Top 10 vulnerabilities, cryptographic rigor, and token-bucket rate limiting across all layers.
-
----
-
-## 1. OWASP Top 10 Defenses
-
-- **A01: Broken Access Control**: Verify permissions server-side on every request using Policy Enforcement Points (PEPs). Enforce immutable multi-tenancy data isolation (AST interceptors, database RLS, or schema namespaces).
-- **A02: Cryptographic Failures**: Passwords must be hashed using **Argon2id** with memory-hard parameters. Encrypt sensitive data at rest using authenticated ciphers (**AES-256-GCM** or **ChaCha20-Poly1305**).
-- **A03: Injection (SQL / NoSQL / Command)**: Strictly prohibit raw query string interpolation or dynamic execution. All database interactions must use parameterized prepared statements.
-- **A07: Identification and Authentication Failures**: Enforce rate limiting on auth endpoints, FIDO2/WebAuthn passkeys, and Refresh Token Rotation (RTR) with family invalidation on replay detection.
-- **A10: Server-Side Request Forgery (SSRF)**: Validate and restrict outbound network requests to an explicit allowlist of domains. Block requests targeting RFC 1918 private IP ranges, loopback addresses (`127.0.0.1`), and cloud metadata endpoints (`169.254.169.254`).
-
----
-
-## 2. Distributed API Rate Limiting
-
-- Utilize token-bucket or sliding-window rate limiters backed by a distributed in-memory cache port.
-- Enforce tiered rate limits:
-  - Authentication routes: Max 5 requests / minute per IP.
-  - Standard API routes: Max 100 requests / minute per tenant/user.
-- Return **`429 Too Many Requests`** with standard `Retry-After` and `RateLimit-*` IETF headers when limits are exceeded.

package/docs/rules/architecture_decision_records.md

@@ -1,42 +0,0 @@
-# Architecture Decision Records (ADR)
-
-> **Core Mandate:** Log all technical, architectural, and operational trade-offs in `memory.md` using the standardized Lightweight ADR format.
-
----
-
-## 1. When to Author an ADR
-
-An Architectural Decision Record must be authored whenever a team member or agent:
-- Introduces or removes an external dependency or library.
-- Modifies database schema architecture, transaction boundaries, or migration strategies.
-- Selects an architectural pattern (e.g. Server-Driven UI, Event-Driven Outbox, OpenFeature).
-- Defines security boundaries, cryptographic standards, or compliance exceptions.
-
----
-
-## 2. Lightweight ADR Format
-
-Log decisions in `memory.md` adhering to this structure:
-
-```markdown
-### ADR-[Number]: [Concise Title]
-
-- **Date:** [YYYY-MM-DD]
-- **Status:** [PROPOSED | ACCEPTED | SUPERSEDED]
-
-#### 1. Context & Problem Statement
-What business requirement, technical bottleneck, or security mandate necessitated this architectural decision?
-
-#### 2. Decision Drivers
-- [Driver 1: e.g. Zero-downtime database deployment]
-- [Driver 2: e.g. SOC 2 Type II tamper-evident logging compliance]
-
-#### 3. Considered Options
-- **Option A:** [Description and evaluation]
-- **Option B:** [Description and evaluation]
-
-#### 4. Decision Outcome & Consequences
-- **Chosen Option:** [Selected approach and core rationale]
-- **Positive Consequences:** [What improves]
-- **Negative Consequences / Trade-offs:** [What operational or code overhead is accepted]
-```

package/docs/rules/compliance.md

@@ -1,25 +0,0 @@
-# Regulatory Compliance: SOC 2, ISO 27001 & GDPR
-
-> **Core Mandate:** Enforce SOC 2 Type II Trust Services Criteria, ISO/IEC 27001 ISMS technical controls, and GDPR data subject privacy rights using open-source architectures.
-
----
-
-## 1. SOC 2 Type II Trust Services Criteria
-
-- **Access Controls (CC6.1)**: Enforce least-privilege RBAC/ABAC on all API endpoints. System-defined roles must be protected from unauthorized mutation.
-- **Tamper-Evident Audit Trails (CC7.2)**:
-  - All state mutations must create write-only, immutable audit log records:
-    `{ timestamp, actorId, tenantId, action, entityType, entityId, ipAddress, userAgent, changes: { before, after } }`.
-  - Audit logs must be retained for at least 365 days in append-only storage.
-
----
-
-## 2. ISO/IEC 27001 ISMS Technical Controls
-
-- **Annex A Cryptographic Controls (A.10.1)**: Enforce TLS 1.3 for data in transit and AES-256-GCM for sensitive data at rest. Passwords must be hashed using Argon2id or bcrypt.
-
----
-
-## 3. GDPR Data Subject Rights
-
-- **Right to Erasure (Article 17)**: Deleting a tenant or user must cascade delete or pseudonymize all associated personal identifiable information (PII) across active databases and backups.

package/docs/rules/container_infrastructure.md

@@ -1,32 +0,0 @@
-# Container Infrastructure & Local Parity
-
-> **Core Mandate:** Enforce production parity through containerized reverse proxy routing, explicit OCI service healthchecks, non-root security boundaries, and minimal distroless base images.
-
----
-
-## 1. Gateway Routing & Local Parity
-
-- **Unified Gateway Routing**: Route all local development and production services through an edge reverse proxy gateway (such as **Envoy** or **Nginx**) on standard HTTP ports to eliminate CORS discrepancies and simulate production multi-service topologies uniformly.
-- **Internal Network Isolation**: Isolate internal services and datastores on a private bridge or overlay network, exposing only the hardened gateway entrypoint to public interfaces.
-
----
-
-## 2. OCI Healthchecks & Deterministic Dependency Ordering
-
-- **Explicit Service Healthchecks**: Every database, cache, message broker, and application service in container configurations (`docker-compose.yml` or Kubernetes manifests) must define an explicit healthcheck command and interval.
-- **Strict Dependency Ordering**: Dependent application services must wait for upstream database and cache readiness, never launching before health verification:
-  ```yaml
-  depends_on:
-    database:
-      condition: service_healthy
-    cache:
-      condition: service_healthy
-  ```
-
----
-
-## 3. Container Security & Build Performance
-
-- **Non-Root Execution**: Run all application containers strictly as unprivileged users (UID >= 10001) with read-only root filesystems and dropped Linux capabilities (`cap_drop: ALL`).
-- **Minimal OCI Base Images**: Standardize on **Distroless** (Google Container Tools) or **Scratch** base images across all polyglot microservices, eliminating package managers, debug shells, and OS vulnerabilities.
-- **Multi-Stage Build Optimization**: Utilize multi-stage OCI builds with cache mounts across dependency steps to minimize image sizes and maximize layer cache reuse.

package/docs/rules/continuous_deployment.md

@@ -1,24 +0,0 @@
-# Continuous Deployment (CD) & Release Engineering
-
-> **Core Mandate:** Enforce zero-downtime deployment rollouts, cryptographic container signing with Cosign, and minimal attack surface container baselines.
-
----
-
-## 1. Zero-Downtime Deployment Strategies
-
-- **Blue-Green / Rolling Deployments**: Deploy new application versions alongside active instances, verify readiness healthchecks, and shift traffic seamlessly without dropping connections.
-- **Rollback Automation**: If error rates or latency spike beyond thresholds immediately post-deployment, automate an instant rollback to the previous stable release.
-
----
-
-## 2. Container Signing & Provenance (Cosign)
-
-- Utilize open-source **Cosign** (Sigstore) to cryptographically sign all release container images in the deployment pipeline.
-- Production Kubernetes / Docker hosts must verify Cosign image signatures and provenance attestations before pulling and launching containers.
-
----
-
-## 3. Container Minimization
-
-- Standardize on minimal container base images (`node:24-alpine` or distroless images).
-- Purge all devDependencies, compilers, and package managers from the final production container layer.

package/docs/rules/continuous_integration.md

@@ -1,20 +0,0 @@
-# Continuous Integration (CI) & Quality Gates
-
-> **Core Mandate:** Enforce shift-left automated quality gates, trunk-based development with short-lived branches, and mandatory green pipeline verification before merge.
-
----
-
-## 1. Shift-Left Automated Quality Gates
-
-Every pull request pipeline must execute automated checks in strict dependency stages:
-1. **Security & Secrets**: Open-source secret scanning (`secretlint`) and SAST analysis (`semgrep`).
-2. **Static Analysis**: ESLint (`npm run lint`) and TypeScript typecheck (`npm run typecheck`).
-3. **Full-Stack Test Coverage**: Unit and acceptance tests verifying **100.00%** coverage (`npm run coverage`).
-4. **Supply Chain Audit**: Vulnerability scan of dependencies and SBOM generation (`syft` + `grype`).
-
----
-
-## 2. Trunk-Based Development
-
-- **Short-Lived Branches**: Feature branches must live less than 24–48 hours before merging to the main trunk.
-- **Fast Build Times**: Docker build layers and npm packages must be cached in CI runners to maintain pipeline execution times under 5 minutes.

package/docs/rules/continuous_learning.md

@@ -1,29 +0,0 @@
-# Continuous Learning & Automated Rule Ingestion
-
-> **Core Mandate:** Automatically capture development defects, analyze root causes, and directly update domain rules or skills to permanently prevent recurrence without intermediate bloat.
-
----
-
-## 1. The 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).
-   - If it unlocks a new domain, author a new atomic rule file and index it in [`AGENTS.md`](../../AGENTS.md).
-   - Run verification (`npm test && npm run validate`) to ensure 100% integrity.
-
----
-
-## 2. Institutional Memory Maintenance
-
-- **Lightweight ADR Ledger**: Major technical decisions and invariant shifts are logged in [`memory.md`](../../memory.md) linking directly to the governing rule or skill.
-- **Living Glossary**: Keep [`docs/knowledge/ubiquitous_language.md`](../knowledge/ubiquitous_language.md) updated with canonical domain terminology and forbidden synonyms.