azcodr 1.0.0

package/.agents/skills/product-analyst/references/backlog_ordering_techniques.md

@@ -0,0 +1,107 @@
+# Product Backlog Ordering & Prioritization Techniques
+
+> **Core Concept:** Prioritizing product backlog items (PBIs) requires disciplined, objective frameworks rather than arbitrary stakeholder pressure. Use this guide to select and apply the right prioritization technique for the product stage.
+
+---
+
+## 1. Prioritization Framework Comparison Matrix
+
+| Framework | Primary Focus | Best Used When... | Key Metric / Input |
+|---|---|---|---|
+| **The Kano Model** | Customer emotional satisfaction vs. investment level | Discovering baseline expectations vs. competitive differentiators | Functional vs. Dysfunctional customer responses |
+| **MoSCoW** | Release scope packaging & non-negotiable boundaries | Planning fixed-date releases or MVP feature gating | Critical path vs. optional enhancements |
+| **RICE Scoring** | Objective algorithmic ranking based on measurable impact | Resolving prioritization disputes across diverse feature requests | $(Reach \times Impact \times Confidence) / Effort$ |
+| **Buy a Feature** | Stakeholder consensus under budget constraints | Engaging cross-functional stakeholders or customer advisory boards | Constrained allocation of currency |
+
+---
+
+## 2. The Kano Model
+
+Categorizes features based on how customer satisfaction correlates with implementation completeness:
+
+```
+Satisfaction (Delighted)
+          ▲
+          │          Attractive (Delighters)
+          │         /
+          │        /    Performance (Linear)
+          │       /    /
+          │      /    /
+          │     /    /
+──────────┼────/────/────────────────────────► Completeness (Invested)
+          │   /    /
+          │  /    /
+          │ /    /   Must-be (Basic Expectations)
+          │/____/
+          ▼
+Dissatisfaction (Frustrated)
+```
+
+### The 5 Kano Categories
+1. **Must-be (Basic / Threshold):** Table stakes. Taken for granted when present, but causes catastrophic dissatisfaction when absent (e.g., database ACID transactions, secure authentication, password resets). *Rule: Must be fully delivered before optimizing performance.*
+2. **Performance (One-Dimensional):** Satisfaction is linearly proportional to execution (e.g., faster page load, higher search speed, larger export limits). *Rule: Optimize strategically where competitive advantage exists.*
+3. **Attractive (Delighters / Excitement):** Unexpected innovations that trigger disproportionate joy and buzz (e.g., instant one-click self-service onboarding, predictive issue alerts). *Rule: Include at least one delighter per major release to drive adoption.*
+4. **Indifferent:** Features that customers do not care about either way. *Rule: Eliminate immediately; do not waste engineering capacity.*
+5. **Reverse:** Features that actively cause frustration if added (e.g., excessive mandatory onboarding modals, invasive popups). *Rule: Avoid or remove.*
+
+---
+
+## 3. MoSCoW Prioritization
+
+Essential for packaging release increments and enforcing negative scope:
+
+- **Must Have (M):**
+  - Non-negotiable core invariants.
+  - Without this, the system cannot operate legally, securely, or fundamentally.
+  - *Example:* "Users must be able to view their pending agreement."
+- **Should Have (S):**
+  - Highly important and valuable, but not critical for launch; a temporary workaround exists.
+  - *Example:* "Automated transactional notifications upon signing" (workaround: manual status check).
+- **Could Have (C):**
+  - Desirable enhancements that provide delight, but are easily deferred if time is constrained.
+  - *Example:* "Downloadable execution certificate with custom styling."
+- **Won't Have This Time (W):**
+  - Explicitly agreed as out-of-scope for the current release. Protects the team from scope creep.
+  - *Example:* "Multi-party commercial co-signer execution flows."
+
+---
+
+## 4. RICE Scoring Framework
+
+When competing stakeholder requests clash, calculate the objective RICE score:
+
+$$\text{RICE Score} = \frac{\text{Reach} \times \text{Impact} \times \text{Confidence}}{\text{Effort}}$$
+
+### Component Definitions & Scoring Scales
+1. **Reach (R):** Number of users or events impacted over a defined timeframe (e.g., per month).
+   - *Example:* 500 active customers signing agreements per quarter $\rightarrow Reach = 500$.
+2. **Impact (I):** Qualitative impact on individual users or conversion:
+   - $3.0$ = Massive impact
+   - $2.0$ = High impact
+   - $1.0$ = Medium impact
+   - $0.5$ = Low impact
+   - $0.25$ = Minimal impact
+3. **Confidence (C):** Percentage reflecting empirical backing vs. speculation:
+   - $100\%$ = High confidence (backed by verified user interviews and analytics)
+   - $80\%$ = Medium confidence (backed by qualitative feedback)
+   - $50\%$ = Low confidence (speculative assumption / gut feeling)
+4. **Effort (E):** Estimated development effort in person-weeks or person-sprints:
+   - *Example:* 1 person-week of engineering $\rightarrow Effort = 1$.
+
+### Example Calculation:
+- **Feature A (Digital Agreement Execution):**
+  - $R = 500$, $I = 3.0$, $C = 100\%$, $E = 1.0 \rightarrow \text{RICE} = \frac{500 \times 3.0 \times 1.0}{1.0} = 1500$
+- **Feature B (Custom Dark Mode Themes):**
+  - $R = 200$, $I = 0.5$, $C = 50\%$, $E = 2.0 \rightarrow \text{RICE} = \frac{200 \times 0.5 \times 0.5}{2.0} = 25$
+- *Conclusion: Feature A takes clear priority.*
+
+---
+
+## 5. Buy a Feature
+
+A collaborative budgeting game ideal for quarterly roadmap planning:
+1. List 10–15 candidate features.
+2. Price each feature proportionally to its engineering effort (e.g., Small = \$50, Medium = \$150, Large = \$400).
+3. Allocate each participant (or group) a constrained budget of fictitious currency equal to roughly 50% of the total cost of all features.
+4. Encourage participants to negotiate and pool their funds to "buy" the features that matter most.
+5. High-priced features that get bought through shared pooling reveal true, undeniable consensus value.

package/.agents/skills/product-analyst/references/gherkin_patterns.md

@@ -0,0 +1,46 @@
+# Gherkin Scenario Patterns Reference
+
+Reusable Gherkin acceptance criteria patterns for full-stack and API features.
+
+---
+
+## 1. REST API CRUD Pattern
+```gherkin
+Scenario: Successfully creating a tenant resource
+  Given an authenticated user with role "ADMIN" in tenant "tenant-123"
+  When the user sends a "POST" request to "/api/roles" with payload:
+    """
+    {
+      "name": "Editor",
+      "description": "Content editor role"
+    }
+    """
+  Then the response status should be 201
+  And the response body should contain the generated "id"
+  And the role should be persisted in tenant "tenant-123"
+```
+
+---
+
+## 2. Multi-Tenant Isolation Pattern
+```gherkin
+Scenario: Tenant data isolation violation attempt
+  Given an authenticated user in tenant "tenant-A"
+  When the user sends a "GET" request to "/api/members" with header "X-Tenant-ID: tenant-B"
+  Then the response status should be 403
+  And the response code should be "FORBIDDEN_TENANT_ACCESS"
+  And a security audit event should be recorded
+```
+
+---
+
+## 3. UI Interaction & Validation Pattern
+```gherkin
+Scenario: Submitting an invalid email address
+  Given the user is on the login page
+  When the user enters "invalid-email" into the email input
+  And clicks the "Sign In" button
+  Then an alert message "Invalid email address format" should appear
+  And the email input should have "aria-invalid" set to "true"
+  And no network request should be dispatched to the server
+```

package/.agents/skills/product-analyst/references/invest_checklist.md

@@ -0,0 +1,38 @@
+# INVEST Checklist & Vertical Slicing Reference
+
+Use this checklist to evaluate whether a user story is ready for development, adheres to Bill Wake's original INVEST model, and embodies Ron Jeffries' 3 C's.
+
+---
+
+## 1. The 3 C's Pre-Flight Check
+
+- [ ] **Card:** Does the physical card or issue title capture the essential intent without drowning in premature implementation details?
+- [ ] **Conversation:** Has there been a collaborative discussion between the Product Owner, domain expert, and engineers to co-create details and discover edge cases?
+- [ ] **Confirmation:** Are there concrete, executable acceptance criteria (Gherkin scenarios) that prove whether the story is satisfied?
+
+---
+
+## 2. INVEST Evaluation Matrix
+
+| Criterion | Evaluation Question | Pass / Fail Check |
+|---|---|---|
+| **I - Independent** | Can this story be scheduled, implemented, and released independently of parallel stories? Does it avoid tight coupling or circular dependency? | [ ] No blocking dependencies on concurrent in-flight stories. |
+| **N - Negotiable** | Does the story focus on the user need and business value rather than prescribing rigid code syntax or immutable UI design? | [ ] Leaves implementation discovery and technical details open to the engineering pair. |
+| **V - Valuable** | Is the customer value observable? Does it slice vertically through the "multi-layer cake" (UI, API, Domain, DB)? | [ ] Sliced vertically; delivers usable, working software to the end user. |
+| **E - Estimable** | Is the scope sufficiently bounded and understood by the team to gauge complexity? | [ ] Architectural unknowns isolated; time-boxed spike completed if necessary. |
+| **S - Small** | Is the slice small enough to be completed within 1–2 development days? | [ ] Not a multi-week epic; decomposed into fine-grained vertical increments. |
+| **T - Testable** | Are there unambiguous pass/fail criteria? Are non-functional requirements (NFRs) operationalized as tests? | [ ] Executable Gherkin scenarios defined; verifiable via automated acceptance tests. |
+
+---
+
+## 3. The Multi-Layer Cake Slicing Test
+
+When decomposing epics into stories, visualize a multi-layer cake with presentation, business logic, domain entities, and persistence layers.
+
+### Slicing Violations (Reject immediately)
+- ❌ *"Create database migration and table schema for resources"* (Horizontal layer: Zero customer value).
+- ❌ *"Build UI form components for resource review"* (Horizontal layer: Dummy mock with zero persistence).
+- ❌ *"Write backend REST controller for submitting actions"* (Horizontal layer: Orphaned API endpoint).
+
+### Slicing Success (Accept)
+- ✅ *"Self-service resource review and approval execution"* (Vertical slice: User reviews terms in UI ➔ Submits confirmation ➔ API verifies actor ➔ Domain validates state invariants ➔ Record persisted with audit trail ➔ Transactional confirmation notification dispatched).

package/.agents/skills/product-analyst/references/okr_alignment_guide.md

@@ -0,0 +1,76 @@
+# OKR Alignment & Product Goal Formulation Guide
+
+> **Core Concept:** Connect high-level business strategy to agile sprint execution using the Objectives and Key Results (OKR) framework (pioneered by Andy Grove at Intel, popularized by John Doerr, and standardized by the OKR Institute).
+
+---
+
+## 1. The Strategic Hierarchy
+
+```
+Company Vision & Strategy
+         │
+         ▼
+Strategic OKRs (Annual / Quarterly)
+         │
+         ▼
+    Product Goal (Long-Term Commitment per Scrum Guide)
+         │
+         ▼
+  Product Backlog Items (Kano / MoSCoW / RICE ordered)
+         │
+         ▼
+    Sprint Goal (Tactical Incremental Commitment)
+```
+
+---
+
+## 2. Anatomy of an Effective OKR
+
+### Objective (O)
+- **Definition:** A qualitative, memorable, inspiring, and time-bound statement defining **WHAT** the team wants to achieve.
+- **Criteria:**
+  - Aggressive yet realistic (aiming for 70% achievement on stretch goals).
+  - Concise and easy for anyone on the team to recite.
+  - Concrete and action-oriented.
+  - Free from numeric metrics (numbers belong in Key Results).
+
+### Key Results (KRs)
+- **Definition:** 2 to 5 quantitative, outcome-driven metrics defining **HOW** progress toward the Objective is measured.
+- **Criteria:**
+  - Must measure **Outcomes** (changes in customer behavior, business performance, or operational velocity), **NEVER Activities or Outputs**.
+  - Must be measurable with a clear baseline and target (e.g., *from X to Y*).
+  - Verifiable with objective data.
+
+---
+
+## 3. The OKR vs. Activity Trap
+
+| Faulty Activity Key Result (Anti-Pattern) | Outcome-Driven Key Result (Golden Standard) |
+|---|---|
+| ❌ "Build the digital contract execution feature" | ✅ "Increase contract completion rate from 45% to 85%" |
+| ❌ "Deploy payment integration with Stripe" | ✅ "Reduce overdue invoice settlements by 40% through self-service digital payments" |
+| ❌ "Write 20 user stories for support tickets" | ✅ "Decrease average time-to-first-response on critical incidents from 24h to 2h" |
+| ❌ "Send marketing emails to 5,000 customers" | ✅ "Achieve an 80% self-service portal adoption rate within 30 days of registration" |
+
+---
+
+## 4. OKRs vs. KPIs
+
+| Dimension | Key Performance Indicators (KPIs) | Objectives & Key Results (OKRs) |
+|---|---|---|
+| **Role in Business** | Health monitoring ("Dashboard gauges" / "Vital signs"). | Strategic vehicle for change and transformation. |
+| **Question Answered** | *"Are our ongoing systems and processes running smoothly?"* | *"What critical breakthrough must we achieve next?"* |
+| **Measurement Target** | Maintain within normal operating limits (e.g., 99.9% uptime, latency < 100ms). | Stretch beyond status quo (e.g., expand into 3 new markets, 2x conversion). |
+| **Action on Deficit** | Remedial maintenance / incident response. | Strategic pivot, retrospective root cause analysis. |
+
+---
+
+## 5. Formulating the Product Goal from Strategic OKRs
+
+In Scrum, the **Product Goal** describes a future state of the product which can serve as a target for the Scrum Team to plan against. The Product Goal is in the Product Backlog. The rest of the Product Backlog emerges to define "what" will fulfill the Product Goal.
+
+### Product Goal Formulation Template
+> **"For [target user segment], our product will [core capability / transformation], enabling [measurable business outcome], verified by [primary Key Result]."**
+
+#### Example:
+> *"For enterprise operators and self-service customers, our platform will eliminate manual paper-based onboarding and invoice reconciliation by providing an instant, self-service digital portal, verified by achieving an end-to-end customer activation time of under 24 hours with zero manual administrative overhead."*

package/.agents/skills/product-analyst/references/smart_tasks.md

@@ -0,0 +1,59 @@
+# SMART Developer Tasks Reference
+
+> **Core Concept:** While user stories represent customer-facing value (evaluated via the **INVEST** model), engineering execution requires breaking each story down into technical developer tasks. Apply Bill Wake's **SMART** acronym to ensure tasks are clear, bounded, and actionable.
+
+---
+
+## 1. The SMART Developer Task Framework
+
+| Letter | Attribute | Description & Quality Standard | Anti-Pattern to Avoid |
+|---|---|---|---|
+| **S** | **Specific** | The task scope is crystal clear and bounded. Everyone on the team understands exactly what needs to be created or modified. | Vague tasks like *"Fix auth issues"* or *"Refactor backend"*. |
+| **M** | **Measurable** | Answers: *"Can we objectively mark it as done?"* Completion requires working behavior, automated tests passing, clean code, and zero lint/type errors. | Tasks marked "done" when code is written but tests are unwritten or failing. |
+| **A** | **Achievable** | The developer or pair has the capability, permissions, and tools to complete it. Team norm: anyone can ask for help immediately without stigma. | Assigning a complex cryptographic or database optimization task without necessary context or pairing support. |
+| **R** | **Relevant** | The task directly contributes to delivering the parent user story. Every developer task must be justifiable to the customer's value proposition. | Building gold-plated utility libraries, speculative abstractions, or unrequested features. |
+| **T** | **Time-Boxed** | The task has an explicit bounded duration expectation (typically 2–4 hours, never exceeding 1 working day). Exceeding the time-box triggers a pause, task splitting, or pairing. | Open-ended tasks that span multiple days without intermediate commits or observable progress. |
+
+---
+
+## 2. Example: Decomposing an INVEST Story into SMART Tasks
+
+### Parent Story: Customer Digital Agreement Execution
+- **Story Description:** *As an approved prospective customer, I want to review my agreement terms and digitally execute the contract in the portal, so that my subscription becomes active immediately.*
+
+### Decomposed SMART Tasks:
+
+#### Task 1: Domain Entity Invariants & Digital Signature Value Object
+- **Specific:** Add `Signature` value interface to `Agreement` entity; validate signer name presence and actor ID consistency in `Agreement.sign()`.
+- **Measurable:** 100% unit test coverage in `agreement_domain.test.ts` testing valid signatures, empty signer name throws, and unauthorized actor rejection.
+- **Achievable:** Developer familiar with TypeScript domain models and Vitest.
+- **Relevant:** Core business invariant required to make digital execution legally defensible.
+- **Time-Boxed:** 2 hours.
+
+#### Task 2: Persistence Schema Evolution & Repository Implementation
+- **Specific:** Add `termsJson` and `signatureJson` to persistence schema; update repository to serialize/deserialize signature JSON.
+- **Measurable:** Database schema sync clean; repository integration tests pass; round-trip serialization verified.
+- **Achievable:** Standard persistence repository workflow in monorepo.
+- **Relevant:** Persists the legal audit trail in the primary database.
+- **Time-Boxed:** 2 hours.
+
+#### Task 3: Use Case State Transition & Async Event Notification
+- **Specific:** Add `signAgreement()` to `AgreementUseCase`; enqueue `agreement.signed` on `JobQueuePort`; register event handler in `EventNotificationDispatcher` to send confirmation notification.
+- **Measurable:** Integration test verifies confirmation notification delivery to customer upon signing; tests green.
+- **Achievable:** Uses existing `JobQueuePort` and notification adapters.
+- **Relevant:** Provides transactional transparency to both customer and operator.
+- **Time-Boxed:** 3 hours.
+
+#### Task 4: REST API Endpoint & Error Handling
+- **Specific:** Add `POST /api/v1/agreements/:id/sign` route to HTTP controller; validate request body; return RFC 7807 problem details on failure.
+- **Measurable:** API acceptance tests pass; covers 200, 400 (validation), 404 (not found).
+- **Achievable:** Standard HTTP controller pattern.
+- **Relevant:** Exposes digital signing capability to web clients.
+- **Time-Boxed:** 2 hours.
+
+#### Task 5: Consumer Portal UI Integration & Document Download
+- **Specific:** Connect `CustomerAgreementPage.tsx` to TanStack `useMutation`; build terms review section, legal acknowledgment checkbox, typed signature modal, and receipt download.
+- **Measurable:** Component builds without TypeScript errors; visual smoke test verifies interactive signing workflow.
+- **Achievable:** Uses existing design system and UI primitives.
+- **Relevant:** Final customer-facing touchpoint closing the satisfaction gap.
+- **Time-Boxed:** 3 hours.

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

@@ -0,0 +1,120 @@
+---
+name: relentless-questioner
+description: Use when initiating a new feature, complex user story, architectural mutation, or ambiguous task to execute a context-aware relentless questioning loop that dynamically adapts subsequent questions based on user answers before planning or coding. Do not use for routine bug fixes with obvious solutions, minor typo corrections, or running tests.
+---
+
+# Relentless Questioner: Context-Aware Dynamic Interrogation Skill
+
+> **Core Purpose:** Eliminate ambiguity, hidden assumptions, and premature coding by executing an interactive, context-aware interrogation loop where every subsequent question directly adapts to the user's previous answers, producing an unambiguous Feature Alignment Specification (FAS) before implementation begins.
+
+---
+
+## 1. When to Use This Skill
+
+- When starting any non-trivial feature, API endpoint, or database modification.
+- When user requirements are high-level, ambiguous, or open-ended (e.g. *"add webhook support"*, *"create billing integration"*, *"allow users to export reports"*).
+- When a task involves conflicting architectural trade-offs (consistency vs latency, synchronous vs asynchronous).
+- When explicitly triggered via slash command `/grill-me`, `/interrogate`, or `/relentless-questioning`.
+- **Do NOT use for**:
+  - Routine typo fixes, dependency version bumps, or minor formatting changes.
+  - Trivial bugs where the defect, root cause, and fix are already verified and obvious.
+  - Routine test execution or build script maintenance.
+
+---
+
+## 2. Step-by-Step Execution Workflow
+
+```
+1. CLASSIFY (Detect Archetype) ──► 2. ADAPTIVE DRILL-DOWN (Chained Questions) ──► 3. RECONCILE (Rule Invariants) ──► 4. CONVERGE (Signed-Off FAS)
+```
+
+---
+
+### Phase 1: Intent & Technical Archetype Classification
+Upon receiving a user task or feature prompt, classify the functional archetype into one or more categories using [references/adaptive_question_trees.md](./references/adaptive_question_trees.md):
+- **Archetype A: State Mutations & Financials** (balances, orders, payments, inventories)
+- **Archetype B: Multi-Tenancy & Authorization** (tenant boundaries, custom fields, permissions)
+- **Archetype C: Asynchronous & Event Streaming** (background jobs, webhooks, queues, pub/sub)
+- **Archetype D: 3rd-Party & External Integrations** (external APIs, payment gateways, mailers)
+- **Archetype E: Read Performance & Search** (dashboards, aggregations, high-scale read traffic)
+
+---
+
+### Phase 2: Context-Aware Dynamic Interrogation
+Do NOT dump a massive 20-question static checklist. Execute the interview in **dynamic batches of 2–3 questions**:
+
+1. **Initial Archetype Branch**: Ask the foundational branching questions for the detected archetype.
+2. **Contextual Chaining (The Adaptive Rule)**:
+   - Carefully parse the user's response.
+   - **Every subsequent question MUST build on the previous answer**:
+     `"Because you specified [Choice A], how should we handle [Specific Consequence / Failure Mode B]?"`
+   - If the user selects a synchronous API integration, branch into timeouts and circuit breakers; do NOT ask about background queue retries.
+   - If the user selects an asynchronous queue, branch into at-least-once delivery, idempotency, and dead-letter queues.
+3. **Negative Scope Interrogation**:
+   - Always ask: *"What is explicitly OUT OF SCOPE for this initial increment (Non-Goals)?"*
+4. **Error Matrix Interrogation**:
+   - Always ask: *"What are the expected client and server error states and corresponding status codes?"*
+
+---
+
+### 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)).
+- Reconcile the conflict collaboratively before proceeding.
+
+---
+
+### Phase 4: Convergence & Feature Alignment Specification (FAS)
+Synthesize the answers into an unambiguous **Feature Alignment Specification (FAS)** using the template in Section 4.
+**STOP AND ASK FOR CONFIRMATION**: Present the FAS to the user and obtain explicit sign-off before writing any production code or plans.
+
+---
+
+## 3. Gotchas & What NOT to Do
+
+- **DO NOT** use static checklists that ignore user responses. Every question turn must reflect the user's prior answers.
+- **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.
+
+---
+
+## 4. Structured Output Templates
+
+### Feature Alignment Specification (FAS) Template
+```markdown
+# Feature Alignment Specification (FAS): [Feature Name]
+
+## 1. Domain Purpose & Value
+- **User Story:** As a [role], I want [capability], so that [benefit].
+- **Core Invariant:** [Immutable business rule that must never be violated].
+
+## 2. Technical Decisions & Boundaries
+- **Interaction Archetype:** [Mutating / Read-Only / Async Event / 3rd-Party]
+- **Tenant Isolation Model:** [AST Interceptor / DB RLS / Schema / Instance]
+- **Transaction Boundary:** [Isolation level, timeouts, Outbox requirements]
+- **Port/Adapter Boundary:** [Project-owned interface for any external dependency]
+
+## 3. Negative Scope (Non-Goals)
+- [Explicitly excluded feature 1]
+- [Explicitly excluded feature 2]
+
+## 4. Error & Edge Case Matrix
+| Scenario | Error Code | HTTP / RPC Status | Recovery Action |
+|---|---|---|---|
+| [Scenario 1] | `RESOURCE_CONFLICT` | 409 Conflict | Return latest version |
+| [Scenario 2] | `TENANT_NOT_FOUND` | 404 Not Found | Terminate request |
+
+## 5. Verification & Acceptance Criteria
+- **Outside-In Acceptance Scenario (Gherkin):**
+  ```gherkin
+  Scenario: [Name]
+    Given [Precondition]
+    When [Action]
+    Then [Observable Outcome]
+  ```
+- **Test Strategy:** [Contract / Integration / Unit tests required for 100% coverage]
+```

package/.agents/skills/relentless-questioner/references/adaptive_question_trees.md

@@ -0,0 +1,84 @@
+# Adaptive Questioning Trees & Contextual Branching Matrices
+
+> **Core Purpose:** Detailed decision trees for the `relentless-questioner` skill, demonstrating how subsequent questions adapt dynamically based on previous user responses.
+
+---
+
+## Decision Tree 1: Mutating Operations & State Changes
+
+```mermaid
+flowchart TD
+  Q1["Does the operation mutate database state?"]
+  Q1 -->|Yes| Q2["Does it involve multiple tables, monetary balances, or inventory?"]
+  Q1 -->|No / Read Only| Q_Read["Branch: Read Performance & Consistency"]
+
+  Q2 -->|Yes: Financial / Inventory| Q_Acid["1. Transaction Isolation: REPEATABLE READ or SERIALIZABLE?\n2. Lock Ordering: How to prevent deadlocks?\n3. Concurrency: Optimistic Concurrency Control (version) or pessimistic locking?"]
+  Q2 -->|No: Standard Entity CRUD| Q_Crud["1. Soft delete or hard delete?\n2. Unique constraints across tenant?\n3. Cascading relations?"]
+
+  Q_Acid --> Q3["Does the mutation emit domain events or notify external systems?"]
+  Q_Crud --> Q3
+
+  Q3 -->|Yes| Q_Outbox["How is the dual-write avoided?\n(Enforce Transactional Outbox pattern before broker publish)"]
+  Q3 -->|No| Q4["Idempotency: Is an Idempotency-Key header required to guard against network retries?"]
+```
+
+---
+
+## Decision Tree 2: Multi-Tenancy & Authorization Boundaries
+
+```mermaid
+flowchart TD
+  Q1["Who executes this action and across which boundary?"]
+  Q1 -->|End User via Web/API| Q_Auth["1. What roles are permitted (ADMIN, MEMBER, CUSTOMER)?\n2. Are dynamic ABAC attributes involved (e.g. order value threshold)?\n3. Can a user act across multiple tenants (switch tenant)?"]
+  Q1 -->|System / Background Job| Q_Worker["1. How is tenant context established without an HTTP session?\n2. What service principal / token credentials are used?"]
+
+  Q_Auth --> Q2["What happens if an unauthorized tenant accesses this resource ID?"]
+  Q2 --> Q_Sec["1. Return 404 Not Found (enumeration masking) or 403 Forbidden?\n2. Is isolation enforced at the DB layer (RLS / AST interceptor)?"]
+```
+
+---
+
+## Decision Tree 3: External Integrations & 3rd-Party APIs
+
+```mermaid
+flowchart TD
+  Q1["Does the feature integrate with an external SaaS or network endpoint?"]
+  Q1 -->|Yes| Q2["What is the failure tolerance of the integration?"]
+  
+  Q2 -->|Synchronous / Critical| Q_Sync["1. What is the strict HTTP timeout (e.g. 3000ms)?\n2. What is the circuit breaker threshold before fast-failing?\n3. What fallback response is served if the 3rd-party is down?"]
+  Q2 -->|Asynchronous / Event-Driven| Q_Async["1. Does the external system provide webhooks?\n2. How are webhook signatures cryptographically verified?\n3. What is the retry backoff and dead-letter queue (DLQ) policy?"]
+
+  Q_Sync --> Q_Port["How is the external SDK isolated?\n(Enforce application-owned Port interface so domain never imports SDK)"]
+  Q_Async --> Q_Port
+```
+
+---
+
+## Decision Tree 4: Read Performance, Caching & Search
+
+```mermaid
+flowchart TD
+  Q1["What is the expected read volume and latency requirement?"]
+  Q1 -->|High Volume / Sub-50ms Latency| Q2["Is stale data acceptable for seconds/minutes?"]
+  
+  Q2 -->|Yes| Q_Cache["1. What is the cache TTL and jitter window?\n2. What domain events trigger cache eviction?\n3. Is probabilistic early expiration (XFetch) needed?"]
+  Q2 -->|No: Strict Read-After-Write Consistency| Q_Consistent["1. Read from primary database instance for 2s after mutation\n2. Bypass read replicas during write session"]
+
+  Q_Cache --> Q_Page["Pagination Strategy: Enforce keyset/cursor pagination over OFFSET"]
+  Q_Consistent --> Q_Page
+```
+
+---
+
+## Contextual Follow-Up Patterns
+
+When conducting the interview, use this exact syntax pattern to chain questions adaptively:
+
+1. **Acknowledge and Pin Previous Answer**:
+   `"Understood, you specified [Option A] for [Requirement X]."`
+2. **Surface Immediate Architectural Implication**:
+   `"Because of [Option A], [Potential Failure / Edge Case Y] becomes the primary risk."`
+3. **Ask Context-Dependent Question**:
+   `"How should the system behave when [Condition Y] occurs? Specifically:"`
+   - *Sub-question 1*
+   - *Sub-question 2*

package/.gitignore

@@ -0,0 +1,20 @@
+# Node dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Test coverage
+coverage/
+
+# Pack tarballs
+*.tgz
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Local environment
+.env
+.env.local
+.env.*.local