azcodr 1.5.2 → 2.1.0

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

@@ -1,102 +1,102 @@
-# 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
-```
-
----
-
-## Decision Tree 5: User Interface, Experience Duality & Interaction Flows
-
-```mermaid
-flowchart TD
-  Q1["Does the feature introduce or modify a user interface?"]
-  Q1 -->|Yes| Q2["Who is the primary actor and operational persona?"]
-  
-  Q2 -->|Operator / Admin| Q_Op["1. Information Density: Dense tabular grid with filters?\n2. Persistent App Shell: Left collapsible sidebar route?\n3. Actions: Inline row actions or full-page drawer?"]
-  Q2 -->|Consumer / Member| Q_Member["1. Experience Duality: Consumer portal (/portal)?\n2. Touch Ergonomics: Clean cards & mobile drawer?\n3. Simplified self-service actions?"]
-
-  Q_Op --> Q3["Navigation & State Synchronization"]
-  Q_Member --> Q3
-
-  Q3 --> Q_State["1. URL State: Deep-link query params (?tab=, ?q=, ?page=, ?modal=)?\n2. Server Cache: TanStack Query hook with automated invalidation?\n3. Accessibility: Accessible headless dialogs & ARIA live regions?"]
-```
-
----
-
-## 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*
+# 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
+```
+
+---
+
+## Decision Tree 5: User Interface, Experience Duality & Interaction Flows
+
+```mermaid
+flowchart TD
+  Q1["Does the feature introduce or modify a user interface?"]
+  Q1 -->|Yes| Q2["Who is the primary actor and operational persona?"]
+  
+  Q2 -->|Operator / Admin| Q_Op["1. Information Density: Dense tabular grid with filters?\n2. Persistent App Shell: Left collapsible sidebar route?\n3. Actions: Inline row actions or full-page drawer?"]
+  Q2 -->|Consumer / Member| Q_Member["1. Experience Duality: Consumer portal (/portal)?\n2. Touch Ergonomics: Clean cards & mobile drawer?\n3. Simplified self-service actions?"]
+
+  Q_Op --> Q3["Navigation & State Synchronization"]
+  Q_Member --> Q3
+
+  Q3 --> Q_State["1. URL State: Deep-link query params (?tab=, ?q=, ?page=, ?modal=)?\n2. Server Cache: TanStack Query hook with automated invalidation?\n3. Accessibility: Accessible headless dialogs & ARIA live regions?"]
+```
+
+---
+
+## 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/.editorconfig

@@ -1,19 +1,19 @@
-# http://editorconfig.org
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[Makefile]
-indent_style = tab
-
-[*.go]
-indent_style = tab
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab

package/.github/workflows/ci.yml

@@ -1,78 +1,167 @@
-name: CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  test:
-    name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ ubuntu-24.04, macos-latest, windows-latest ]
-        node-version: [ 18.x, 20.x, 22.x, 24.x ]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v7
-
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v7
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Verify Environment
-        run: |
-          node --version
-          npm --version
-
-      - name: Run Syntax & Lint Checks
-        run: npm run lint
-
-      - name: Validate Agentic Architecture
-        run: npm run validate
-
-      - name: Run Test Suite
-        run: npm test
-
-  coverage:
-    name: 100.00% Coverage Gate (Node 24)
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v7
-
-      - name: Setup Node.js 24.x
-        uses: actions/setup-node@v7
-        with:
-          node-version: 24.x
-
-      # Native 100% threshold flags require Node >=22.8.0 (see scripts/test_coverage.js),
-      # so the coverage gate runs once on the newest runtime instead of every matrix cell.
-      - name: Verify 100.00% Test Coverage Gates
-        run: npm run test:coverage
-
-  security:
-    name: Secret & Vulnerability Scans
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v7
-
-      - name: Secret Scan (Gitleaks)
-        uses: gitleaks/gitleaks-action@v2
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Filesystem Vulnerability Scan (Trivy)
-        uses: aquasecurity/trivy-action@v0.36.0
-        with:
-          scan-type: fs
-          scan-ref: .
-          scanners: vuln
-          severity: HIGH,CRITICAL
-          exit-code: '1'
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  merge_group:
+    branches: [ main ]
+
+# Least privilege by default. Every job here only needs to read the repository.
+# A write-capable token executing `node --test` over PR-controlled content is a
+# supply-chain exposure; grant write scopes only where a job genuinely needs them.
+permissions:
+  contents: read
+
+# Cancel superseded runs. Without this, five pushes to a PR queue five full
+# matrix runs; with a publish workflow it also prevents two release runs racing
+# the same version.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-24.04, macos-latest, windows-latest ]
+        # Node 18 (EOL 2025-04-30) and 20 (EOL 2026-04-30) are no longer
+        # patched. Half the matrix was verifying unpatched runtimes. Supported
+        # lines as of Oct 2026: 24 (Active LTS), 22 (Maintenance), 26 (Current).
+        node-version: [ 22.x, 24.x, 26.x ]
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      # The repo has zero runtime dependencies, but contributor tooling
+      # (ESLint, ADR-012) is a devDependency and must be installed.
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify Environment
+        run: |
+          node --version
+          npm --version
+
+      - name: Run Syntax & Lint Checks
+        run: npm run lint
+
+      - name: Validate Agentic Architecture
+        run: npm run validate
+
+      - name: Run Test Suite
+        run: npm test
+
+  coverage:
+    name: Coverage Gate (Node 24)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js 24.x
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24.x
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Native threshold flags require Node >=22.8.0 (see scripts/test_coverage.js),
+      # so the coverage gate runs once on the newest runtime instead of every matrix cell.
+      - name: Verify Coverage Gates
+        run: npm run test:coverage
+
+  shell-syntax:
+    name: Shell Script Syntax (shipped hooks)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      # The .sh files ship to every scaffolded project and auto-run as agent
+      # hooks. `bash -n` catches a CRLF checkout or a syntax slip that the
+      # Node-only lint is blind to.
+      - name: Parse every shipped shell script
+        run: |
+          set -euo pipefail
+          failed=0
+          while IFS= read -r script; do
+            if bash -n "$script"; then
+              echo "ok: $script"
+            else
+              echo "FAIL: $script"
+              failed=1
+            fi
+          done < <(find .agents -name '*.sh' -not -path './node_modules/*')
+          exit $failed
+
+      - name: Verify hooks use LF line endings
+        run: |
+          set -euo pipefail
+          bad=0
+          while IFS= read -r script; do
+            if grep -qU $'\r' "$script"; then
+              echo "CRLF found (breaks shebang + 'set -euo pipefail'): $script"
+              bad=1
+            fi
+          done < <(find .agents -name '*.sh' -not -path './node_modules/*')
+          [ "$bad" -eq 0 ] && echo "all hook scripts are LF"
+
+  security:
+    name: Secret & Vulnerability Scans
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      # gitleaks-action comments on PRs when it finds a leak; without these it
+      # degrades gracefully to scan-only.
+      pull-requests: write
+    steps:
+      - name: Checkout Repository (full history for secret scanning)
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      # gitleaks-action v2 runs on the Node 20 action runtime, which GitHub
+      # removed from hosted runners on 2026-09-16 -- the job was failing for
+      # every PR. v3 targets Node 24.
+      - name: Secret Scan (Gitleaks)
+        uses: gitleaks/gitleaks-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Filesystem Vulnerability Scan (Trivy)
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln
+          severity: HIGH,CRITICAL
+          exit-code: '1'
+
+      - name: Software Bill of Materials (CycloneDX)
+        uses: anchore/sbom-action@v0
+        with:
+          format: cyclonedx-json
+          output-file: sbom.cdx.json
+          artifact-name: sbom.cdx.json
+
+      - name: Dependency Review
+        if: github.event_name == 'pull_request'
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high