azcodr 1.5.1 → 2.0.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,56 +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-latest, macos-latest, windows-latest ]
-        node-version: [ 18.x, 20.x, 22.x, 24.x ]
-
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        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: Secret Scan (Gitleaks)
-        uses: gitleaks/gitleaks-action@v2
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Filesystem Vulnerability Scan (Trivy)
-        uses: aquasecurity/trivy-action@0.28.0
-        with:
-          scan-type: fs
-          scan-ref: .
-          severity: HIGH,CRITICAL
-          exit-code: '1'
-
-      - name: Run Test Suite
-        run: npm test
-
-      - name: Verify 100.00% Test Coverage Gates
-        run: npm run test:coverage
+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

package/.github/workflows/publish.yml

@@ -0,0 +1,200 @@
+name: Publish
+
+on:
+  release:
+    types: [ published ]
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Verify the publishable tarball without uploading"
+        type: boolean
+        default: true
+
+# Least privilege: read the repo, write only the npm registry.
+permissions:
+  contents: read
+  id-token: write # npm trusted publishing / provenance attestation
+
+# Never let two release runs race the same version.
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify Release Before Publishing
+    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
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify Environment
+        run: |
+          node --version
+          npm --version
+
+      # Re-run the full gate on the exact release tag. prepublishOnly also runs
+      # on `npm publish`, but failing fast here avoids building a tarball at all.
+      - name: Run Syntax & Lint Checks
+        run: npm run lint
+
+      - name: Run Test Suite
+        run: npm test
+
+      - name: Verify Coverage Gates
+        run: npm run test:coverage
+
+      - name: Validate Agentic Architecture
+        run: npm run validate
+
+      - name: Verify version matches the release tag
+        if: github.event_name == 'release'
+        run: |
+          set -euo pipefail
+          pkg_version="$(node -p "require('./package.json').version")"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$pkg_version" != "$tag_version" ]; then
+            echo "::error::package.json version ($pkg_version) does not match release tag ($GITHUB_REF_NAME)"
+            exit 1
+          fi
+          echo "version $pkg_version matches tag $GITHUB_REF_NAME"
+
+      - name: Inspect the publishable tarball
+        run: |
+          set -euo pipefail
+          npm pack --dry-run
+          # Prove the tarball actually carries the files the package promises,
+          # rather than trusting the files[] allowlist to be correct.
+          # npm writes UTF-16LE on Windows, so parse it as text, not via require.
+          npm pack --json > pack.json
+          node -e '
+            const fs = require("fs");
+            let raw = fs.readFileSync("pack.json", "utf-8");
+            if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            // npm writes UTF-16LE on Windows, so utf-8 decoding yields NUL
+            // padding. Detect it and re-read. Use an escape, never a literal
+            // NUL byte: an embedded 0x00 makes git classify this file as
+            // binary, which breaks the workflow.
+            if (raw.indexOf(String.fromCharCode(0)) !== -1) {
+              raw = fs.readFileSync("pack.json", "utf16le");
+              if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+            }
+            const meta = JSON.parse(raw)[0];
+            const files = new Set(meta.files.map((f) => f.path));
+            const required = [
+              "package.json", "README.md", "LICENSE",
+              "bin/azcodr.js", "lib/index.js", "lib/index.d.ts", "lib/scaffold.js",
+              "scripts/validate.js", "scripts/validate-cli.js"
+            ];
+            const missing = required.filter((f) => !files.has(f));
+            if (missing.length) {
+              console.error("::error::missing from tarball: " + missing.join(", "));
+              process.exit(1);
+            }
+            console.log("tarball contains all " + required.length + " required paths");
+          '
+
+      - name: Install the packed tarball and smoke-test the CLI
+        run: |
+          set -euo pipefail
+          # The highest-value missing check: the published artifact must be
+          # runnable, not just constructible.
+          npm pack > /dev/null
+          mkdir -p /tmp/smoke && cd /tmp/smoke
+          npm init -y > /dev/null 2>&1
+          npm install "$GITHUB_WORKSPACE"/*.tgz --no-audit --no-fund
+          npx azcodr --version
+          npx azcodr --help > /dev/null
+          node -e '
+            const api = require("azcodr");
+            const required = ["scaffold", "copyTemplate", "validateTarget", "ERROR_CODES", "ScaffoldError"];
+            const missing = required.filter((k) => !(k in api));
+            if (missing.length) { console.error("missing exports: " + missing.join(", ")); process.exit(1); }
+            if (api.ERROR_CODES.E_GIT_BLOCKED !== "Blocked git subcommand") {
+              console.error("error-code contract changed unexpectedly");
+              process.exit(1);
+            }
+            console.log("programmatic API surface verified");
+          '
+
+      - name: Scaffold a real project from the packed tarball
+        run: |
+          set -euo pipefail
+          cd /tmp/smoke
+          npx azcodr ./generated --force --no-git
+          cd ./generated
+          npm run validate
+
+  publish-npm:
+    name: Publish to npm
+    needs: verify
+    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
+          registry-url: https://registry.npmjs.org
+
+      - name: Verify the working tree is clean
+        run: |
+          set -euo pipefail
+          # Publishing from a dirty tree ships files that are not in any tag and
+          # cannot be reproduced later.
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "::error::working tree is dirty; refusing to publish"
+            git status --porcelain
+            exit 1
+          fi
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Re-run the publish gate
+        # prepublishOnly fires on npm publish: lint -> coverage -> validate.
+        run: npm run lint && npm run test:coverage && npm run validate
+
+      - name: Dry run (no upload)
+        if: inputs.dry-run == true
+        run: npm publish --dry-run --access public
+
+      - name: Publish to npm
+        if: inputs.dry-run != true
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-jsr:
+    name: Publish to JSR
+    needs: verify
+    # Requires a native ESM entrypoint. The npm package is CommonJS, which JSR
+    # explicitly forbids ("You cannot publish CommonJS modules"). Disabled with
+    # a stated reason rather than failing every release.
+    if: false
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Publish to JSR
+        run: npx jsr publish