@aisdlc/core 1.5.1 → 1.5.2

package/dist/index.cjs

@@ -12898,12 +12898,6 @@ stages:\r
 \r
 default:\r
   image: node:20\r
-  cache:\r
-    key:\r
-      files:\r
-        - pnpm-lock.yaml\r
-    paths:\r
-      - .pnpm-store\r
 \r
 variables:\r
   PNPM_HOME: "$CI_PROJECT_DIR/.pnpm"\r
@@ -13070,13 +13064,9 @@ var STARTER_TEMPLATES_CI_BITBUCKET_PIPELINES_YML = `# ==========================
 image: node:20\r
 \r
 definitions:\r
-  caches:\r
-    pnpm: $BITBUCKET_CLONE_DIR/.pnpm-store\r
   steps:\r
     - step: &build-and-verify\r
         name: Quality Gates & Verification\r
-        caches:\r
-          - pnpm\r
         script:\r
           - corepack enable\r
           - corepack prepare pnpm@10 --activate\r
@@ -13090,8 +13080,6 @@ definitions:\r
 \r
     - step: &sdd-integrate\r
         name: SDD Canonical Integration\r
-        caches:\r
-          - pnpm\r
         script:\r
           - corepack enable\r
           - corepack prepare pnpm@10 --activate\r
@@ -13123,88 +13111,10 @@ pipelines:\r
       - step: *build-and-verify\r
       - step: *sdd-integrate\r
 `;
-var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_CI_YML = "name: CI - AI-SDLC Quality Gates & Testing\n\non:\n  push:\n    branches: [ main ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  verify-and-test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [ 18.x, 20.x, 22.x ]\n\n    steps:\n      - name: Checkout Code\n        uses: actions/checkout@v4\n\n      - name: Install pnpm\n        uses: pnpm/action-setup@v4\n        with:\n          version: 10\n\n      - name: Setup Node.js ${{ matrix.node-version }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix.node-version }}\n          cache: 'pnpm'\n\n      - name: Install Dependencies\n        run: |\n          pnpm install --frozen-lockfile\n          pnpm approve-builds --all\n\n      - name: Build Packages\n        run: pnpm run build\n\n      - name: Run Vitest Unit & Integration Suites\n        run: pnpm test\n\n      - name: AI-SDLC Quality Gate & Full Verification\n        run: npx @aisdlc/cli verify all\n";
+var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_CI_YML = "name: CI - AI-SDLC Quality Gates & Testing\n\non:\n  push:\n    branches: [ main ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  verify-and-test:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [ 18.x, 20.x, 22.x ]\n\n    steps:\n      - name: Checkout Code\n        uses: actions/checkout@v4\n\n      - name: Install pnpm\n        uses: pnpm/action-setup@v4\n        with:\n          version: 10\n\n      - name: Setup Node.js ${{ matrix.node-version }}\n        uses: actions/setup-node@v4\n        with:\n          node-version: ${{ matrix.node-version }}\n\n      - name: Install Dependencies\n        run: |\n          pnpm install --frozen-lockfile\n          pnpm approve-builds --all\n\n      - name: Build Packages\n        run: pnpm run build\n\n      - name: Run Vitest Unit & Integration Suites\n        run: pnpm test\n\n      - name: AI-SDLC Quality Gate & Full Verification\n        run: npx @aisdlc/cli verify all\n";
 var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_DEPLOY_DASHBOARD_YML = 'name: Deploy AI-SDLC Dashboard to GitHub Pages\n\non:\n  push:\n    branches:\n      - main\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: pages\n  cancel-in-progress: false\n\njobs:\n  deploy-dashboard:\n    name: Build & Publish Interactive Dashboard\n    runs-on: ubuntu-latest\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n\n    steps:\n      - name: Checkout Code\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0 # Full git history required for historical KPIs and telemetry\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: 20\n\n      - name: Generate AI-SDLC Interactive Dashboard\n        run: |\n          mkdir -p reports\n          npx --yes @aisdlc/cli report dashboard --output reports/index.html\n          cp reports/index.html reports/dashboard.html\n          touch reports/.nojekyll\n\n      - name: Setup GitHub Pages\n        uses: actions/configure-pages@v5\n\n      - name: Upload Pages Artifact\n        uses: actions/upload-pages-artifact@v3\n        with:\n          path: reports\n\n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4\n\n      - name: Emit Summary to GitHub Actions\n        if: always() && steps.deployment.outcome == \'success\'\n        run: |\n          echo "### \u{1F310} AI-SDLC Interactive Dashboard Published" >> $GITHUB_STEP_SUMMARY\n          echo "" >> $GITHUB_STEP_SUMMARY\n          echo "The interactive PDaC / RTM graph, Quality Gate telemetry, and release metrics are live at:" >> $GITHUB_STEP_SUMMARY\n          echo "" >> $GITHUB_STEP_SUMMARY\n          echo "\u{1F449} **[Open Live Dashboard](${{ steps.deployment.outputs.page_url }})**" >> $GITHUB_STEP_SUMMARY\n';
-var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_PR_KPI_SUMMARY_YML = "name: AI-SDLC PR KPI Aggregator\n\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  aggregate-kpis:\n    name: Aggregate PR KPIs & Telemetry\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout Repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: Install pnpm\n        uses: pnpm/action-setup@v4\n        with:\n          version: 10\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: 20\n          cache: 'pnpm'\n\n      - name: Install Dependencies\n        run: |\n          pnpm install --frozen-lockfile\n\n      - name: Calculate and Emit PR KPIs\n        id: kpi\n        run: |\n          npx @aisdlc/cli kpi pr --base origin/${{ github.base_ref }} --head HEAD >> $GITHUB_STEP_SUMMARY\n";
-var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_SDD_INTEGRATE_ON_MERGE_YML = `name: SDD Canonical Integration on Merge\r
-\r
-on:\r
-  pull_request:\r
-    types: [closed]\r
-    branches:\r
-      - main\r
-      - 'release/**'\r
-  workflow_dispatch:\r
-    inputs:\r
-      change_id:\r
-        description: 'SDD change ID to integrate manually (e.g. chg-001-telemetry)'\r
-        required: false\r
-        type: string\r
-\r
-permissions:\r
-  contents: write\r
-  pull-requests: read\r
-\r
-concurrency:\r
-  group: sdd-integrate-\${{ github.ref }}\r
-  cancel-in-progress: false\r
-\r
-jobs:\r
-  integrate-sdd:\r
-    name: SDD Canonical Integration\r
-    if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'\r
-    runs-on: ubuntu-latest\r
-\r
-    steps:\r
-      - name: Checkout Repository\r
-        uses: actions/checkout@v4\r
-        with:\r
-          ref: \${{ github.event.pull_request.base.ref || github.ref_name }}\r
-          fetch-depth: 0\r
-          token: \${{ secrets.GITHUB_TOKEN }}\r
-\r
-      - name: Install pnpm\r
-        uses: pnpm/action-setup@v4\r
-        with:\r
-          version: 10\r
-\r
-      - name: Setup Node.js\r
-        uses: actions/setup-node@v4\r
-        with:\r
-          node-version: 20\r
-          cache: 'pnpm'\r
-\r
-      - name: Install Dependencies\r
-        run: |\r
-          pnpm install --frozen-lockfile\r
-          pnpm approve-builds --all\r
-\r
-      - name: Build Packages\r
-        run: pnpm run build\r
-\r
-      - name: Detect and Integrate SDD Change\r
-        id: integrate\r
-        env:\r
-          PR_HEAD_REF: \${{ github.event.pull_request.head.ref }}\r
-          PR_TITLE: \${{ github.event.pull_request.title }}\r
-          PR_BODY: \${{ github.event.pull_request.body }}\r
-          MANUAL_CHANGE_ID: \${{ github.event.inputs.change_id }}\r
-        run: |\r
-          npx @aisdlc/cli sdd integrate --auto || true\r
-\r
-      - name: Commit and Push Canonical Baseline Changes\r
-        run: |\r
-          git config user.name "github-actions[bot]"\r
-          git config user.email "github-actions[bot]@users.noreply.github.com"\r
-          git add -A\r
-          if ! git diff --cached --quiet; then\r
-            git commit -m "chore(sdd): integrate changes into canonical baseline [skip ci]"\r
-            git push\r
-            echo "\u2714 Canonical integration committed and synchronized to repository."\r
-          else\r
-            echo "\u2139 No pending changes generated in working tree."\r
-          fi\r
-`;
+var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_PR_KPI_SUMMARY_YML = "name: AI-SDLC PR KPI Aggregator\n\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  aggregate-kpis:\n    name: Aggregate PR KPIs & Telemetry\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout Repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: Install pnpm\n        uses: pnpm/action-setup@v4\n        with:\n          version: 10\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: 20\n\n      - name: Install Dependencies\n        run: |\n          pnpm install --frozen-lockfile\n\n      - name: Calculate and Emit PR KPIs\n        id: kpi\n        run: |\n          npx @aisdlc/cli kpi pr --base origin/${{ github.base_ref }} --head HEAD >> $GITHUB_STEP_SUMMARY\n";
+var STARTER_TEMPLATES_CI_GITHUB_WORKFLOWS_SDD_INTEGRATE_ON_MERGE_YML = 'name: SDD Canonical Integration on Merge\r\n\r\non:\r\n  pull_request:\r\n    types: [closed]\r\n    branches:\r\n      - main\r\n      - \'release/**\'\r\n  workflow_dispatch:\r\n    inputs:\r\n      change_id:\r\n        description: \'SDD change ID to integrate manually (e.g. chg-001-telemetry)\'\r\n        required: false\r\n        type: string\r\n\r\npermissions:\r\n  contents: write\r\n  pull-requests: read\r\n\r\nconcurrency:\r\n  group: sdd-integrate-${{ github.ref }}\r\n  cancel-in-progress: false\r\n\r\njobs:\r\n  integrate-sdd:\r\n    name: SDD Canonical Integration\r\n    if: github.event.pull_request.merged == true || github.event_name == \'workflow_dispatch\'\r\n    runs-on: ubuntu-latest\r\n\r\n    steps:\r\n      - name: Checkout Repository\r\n        uses: actions/checkout@v4\r\n        with:\r\n          ref: ${{ github.event.pull_request.base.ref || github.ref_name }}\r\n          fetch-depth: 0\r\n          token: ${{ secrets.GITHUB_TOKEN }}\r\n\r\n      - name: Install pnpm\r\n        uses: pnpm/action-setup@v4\r\n        with:\r\n          version: 10\r\n\r\n      - name: Setup Node.js\r\n        uses: actions/setup-node@v4\r\n        with:\r\n          node-version: 20\r\n\r\n      - name: Install Dependencies\r\n        run: |\r\n          pnpm install --frozen-lockfile\r\n          pnpm approve-builds --all\r\n\r\n      - name: Build Packages\r\n        run: pnpm run build\r\n\r\n      - name: Detect and Integrate SDD Change\r\n        id: integrate\r\n        env:\r\n          PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}\r\n          PR_TITLE: ${{ github.event.pull_request.title }}\r\n          PR_BODY: ${{ github.event.pull_request.body }}\r\n          MANUAL_CHANGE_ID: ${{ github.event.inputs.change_id }}\r\n        run: |\r\n          npx @aisdlc/cli sdd integrate --auto || true\r\n\r\n      - name: Commit and Push Canonical Baseline Changes\r\n        run: |\r\n          git config user.name "github-actions[bot]"\r\n          git config user.email "github-actions[bot]@users.noreply.github.com"\r\n          git add -A\r\n          if ! git diff --cached --quiet; then\r\n            git commit -m "chore(sdd): integrate changes into canonical baseline [skip ci]"\r\n            git push\r\n            echo "\u2714 Canonical integration committed and synchronized to repository."\r\n          else\r\n            echo "\u2139 No pending changes generated in working tree."\r\n          fi\r\n';
 var STARTER_TEMPLATES_COMPLIANCE_COMMERCIAL_ACQUISITION_REQUEST_TEMPLATE_MD = '---\r\nid: REQ-LIC-ACQUISITION-001\r\ntype: license-acquisition-request\r\ntitle: Commercial License Acquisition Request for [Library]\r\nstatus: pending-approval # pending-approval, approved, rejected\r\nrequested-package: "@vendor/commercial-package"\r\nspdx-license: "BSL-1.1" # or Commercial, SSPL-1.0\r\nlicense-category: commercial_acquisition_required\r\nestimated-cost: "$1,200 / year"\r\nbusiness-justification: "Accelerates critical telemetry module development avoiding 4 months of in-house implementation."\r\n---\r\n\r\n# Commercial License Acquisition Request\r\n\r\n## 1. Package and Vendor\r\n- **Package**: `@vendor/commercial-package`\r\n- **Version**: `2.4.0`\r\n- **License Type**: BSL 1.1 / Commercial\r\n- **Official Website**: `https://vendor.example.com`\r\n\r\n## 2. Technical Justification and Evaluated Alternatives\r\n- **Why a permissive alternative (MIT/Apache 2.0) is not used**:\r\n  - Open-source alternatives lack required hardware encryption protocol support.\r\n- **Impact of not acquiring the license**:\r\n  - 4-month delay on product delivery milestone.\r\n\r\n## 3. Human Authorization Signatures\r\n- [ ] Tech Lead: Technical approval\r\n- [ ] Legal / IP Counsel: EULA clauses validation\r\n- [ ] Procurement / Budget Owner: Payment authorization\r\n';
 var STARTER_TEMPLATES_MANUALS_PRODUCTION_MANUAL_TEMPLATE_MD = '---\r\nid: MAN-PROD-001\r\ntype: production-manual\r\ntitle: "Production & Operations Manual: Application Name"\r\nstatus: draft\r\nversion: "1.0.0"\r\nschema-version: "1.0"\r\napplies-to-version: "v1.0.0"\r\ntarget-audience:\r\n  - devops-engineer\r\n  - sre-engineer\r\n  - release-manager\r\n  - secops\r\ncomponents-covered:\r\n  - CMP-NAME-001\r\nenclaves-involved:\r\n  - SEC-ENC-DMZ-001\r\nsupersedes: null\r\nsuperseded-by: null\r\n---\r\n\r\n# MAN-PROD-001: Production & Operations Manual - Application Name\r\n\r\n## 1. Deterministic Release Regeneration (Reproducible Builds)\r\n\r\nThis section contains the specifications and directives required to deterministically reproduce identical bit-by-bit application artifacts or releases from their Git tag.\r\n\r\n### 1.1 Source Code Baseline\r\n\r\n- **Canonical Repository**: `https://github.com/organization/repo-name.git`\r\n- **Immutable Git Release Tag**: `v1.0.0`\r\n- **Commit SHA-256 / SHA-1**: `[VERIFIED_HEXADECIMAL_COMMIT_SHA]`\r\n- **Clean Checkout Command**:\r\n  ```bash\r\n  git clone --recurse-submodules https://github.com/organization/repo-name.git\r\n  cd repo-name\r\n  git checkout tags/v1.0.0\r\n  git submodule update --init --recursive\r\n  ```\r\n\r\n### 1.2 Frozen Toolchains and Build Tool Matrix\r\n\r\nTo prevent discrepancies in binary or package generation, strict usage of pinned versions of the following utilities is enforced:\r\n\r\n| Tool / Runtime | Exact Version | Toolchain Checksum / Digest | Purpose |\r\n| :--- | :--- | :--- | :--- |\r\n| **Node.js LTS** | `v22.12.0` | `sha256:node-v22.12.0-linux-x64.tar.xz` | Execution and transpilation runtime |\r\n| **pnpm** | `9.15.0` | `sha256:pnpm-v9.15.0` | Deterministic monorepo package manager |\r\n| **TypeScript (tsc)** | `5.7.2` | Pinned in `devDependencies` | Strict ECMAScript compiler |\r\n| **Docker BuildKit** | `v0.18.0` | `moby/buildkit:v0.18.0` | Hermetic OCI packaging engine |\r\n\r\n### 1.3 Libraries, Dependencies, and Vertex Graph\r\n\r\n- **Immutable Lockfile**: `pnpm-lock.yaml` (or `Cargo.lock`, `go.sum`, `requirements.lock`). Installations with open resolution are forbidden (`pnpm install --frozen-lockfile` mandatory).\r\n- **SBOM (Software Bill of Materials) Inventory**:\r\n  - Format: CycloneDX JSON v1.5 / SPDX v2.3.\r\n  - Compiled SBOM path: `reports/sbom-cyclonedx.json`.\r\n- **OSS License Governance**:\r\n  - Binding policy: `license-policy.yaml`.\r\n  - Library vertex pre-verification:\r\n    ```bash\r\n    pnpm verify:licenses\r\n    ```\r\n\r\n### 1.4 Step-by-Step Deterministic Build Procedure\r\n\r\n1. **Step 1: Hermetic Dependency Installation**\r\n   ```bash\r\n   pnpm install --frozen-lockfile --ignore-scripts\r\n   ```\r\n\r\n2. **Step 2: Integrity and Strict Type Checking**\r\n   ```bash\r\n   pnpm typecheck\r\n   ```\r\n\r\n3. **Step 3: Artifact Compilation**\r\n   ```bash\r\n   export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)\r\n   pnpm build\r\n   ```\r\n\r\n4. **Step 4: Cryptographic Verification of Generated Artifact**\r\n   ```bash\r\n   sha256sum dist/app.bundle.js\r\n   # Compare against the canonical checksum registered in official release:\r\n   # Expected: [CANONICAL_SHA256_CHECKSUM]\r\n   ```\r\n\r\n---\r\n\r\n## 2. Version, Infrastructure, and Migration Compatibility Matrix\r\n\r\nThis section defines technical interoperability boundaries between the release version and the deployment ecosystem, ensuring safe Zero-Downtime transitions.\r\n\r\n### 2.1 Platform and Execution Runtime Compatibility\r\n\r\n| Infrastructure Component | Approved Version Range | Recommended Version | Support Status |\r\n| :--- | :--- | :--- | :---: |\r\n| **Kubernetes Cluster (K8s)** | `>= 1.28` and `<= 1.31` | `1.30.2` | \u2705 Certified |\r\n| **Container Runtime (CRI)** | containerd `>= 1.7` / CRI-O `>= 1.28` | containerd `1.7.15` | \u2705 Certified |\r\n| **Base Operating System (Host)** | Ubuntu 22.04 LTS / RHEL 9.2+ | Ubuntu 22.04 LTS (Kernel 6.x) | \u2705 Homologated |\r\n| **Language Runtime (Production)** | Node.js `>= 20.x` and `<= 22.x` | `v22.12.0 LTS` | \u2705 Hermetic |\r\n\r\n### 2.2 Data Schema and Migration Compatibility (N-1 Support)\r\n\r\nTo enable Canary or Blue-Green continuous deployments without transaction loss:\r\n\r\n| Release Version | DB Schema Version | Compatible with $N-1$ Code | Schema Migration Status |\r\n| :---: | :---: | :---: | :--- |\r\n| **`v1.0.0`** (Current) | `SCHEMA-v1.0` | \u2705 Yes (supports `v0.9.x` code) | Non-destructive additive migration (no column renaming). |\r\n| **`v0.9.x`** | `SCHEMA-v0.9` | \u2705 Previous baseline | Fully compatible during Canary drain period. |\r\n\r\n### 2.3 Interoperability Between Architecture Components (`CMP-*`)\r\n\r\n| Dependent Component | Consumed Component | Minimum Compatible Versions | Binding Protocol / Contract |\r\n| :--- | :--- | :---: | :--- |\r\n| `CMP-NAME-001` (Gateway) | `CMP-NAME-002` (Backend) | `>= v1.0.0` | gRPC / Protobuf v3 (`contract_spec.proto`) |\r\n| `CMP-NAME-001` (Gateway) | Messaging Bus / Kafka | `>= 3.5.0` | Kafka v2 Protocol with TLS mTLS |\r\n\r\n### 2.4 Homologated Upgrade & Rollback Paths\r\n\r\n| Source Version | Direct Jump to `v1.0.0` | Intermediate Migration Required | Direct Rollback Procedure |\r\n| :---: | :---: | :---: | :---: |\r\n| **`v0.9.1`** | \u2705 Allowed | \u274C Not required | `kubectl rollout undo` without data loss. |\r\n| **`v0.9.0`** | \u2705 Allowed | \u274C Not required | `kubectl rollout undo` without data loss. |\r\n| **`< v0.9.0`** | \u274C Blocked | \u2705 Must upgrade to `v0.9.1` first | Requires restore from backup snapshot. |\r\n\r\n---\r\n\r\n## 3. CI/CD Architecture and Pipelines\r\n\r\n### 3.1 Hierarchical Branching Model and Integration Triggers\r\n\r\nFollowing the AI-SDLC 4-tier standard:\r\n\r\n```text\r\nTIER 1: main (Production)\r\n  \u25B2\r\n  \u2514\u2500\u2500 PR Release Gate (Manual Tech Lead / Release Manager Approval)\r\n        \u2502\r\nTIER 2: release/v1.0.0 (Open Version Branch)\r\n  \u25B2\r\n  \u2514\u2500\u2500 PR Feature Gate (Lint + Tests + Quality Gate + SAST + SBOM)\r\n        \u2502\r\nTIER 3: feat/CHG-001-* (Feature / Bug)\r\n```\r\n\r\n- **Pull Request Trigger**: Executes linters, full test battery, and governance verifications without deployment.\r\n- **Release Tag Trigger (`v*.*.*`)**: Executes the full hermetic build pipeline, image signing, and continuous deployment.\r\n\r\n### 3.2 CI/CD Pipeline Flowchart\r\n\r\n```mermaid\r\nflowchart LR\r\n    A["Git Push / Tag v1.0.0"] --> B["Hermetic Checkout"]\r\n    B --> C["Linters & Typecheck"]\r\n    C --> D["Vitest: Unit & BDD"]\r\n    D --> E["Quality Gate: CC & MI"]\r\n    E --> F["SAST & Secret Scan"]\r\n    F --> G["SBOM & License Gate"]\r\n    G --> H["Deterministic Build"]\r\n    H --> I["Cosign / SLSA Signing"]\r\n    I --> J["Push to OCI Registry"]\r\n    J --> K["Deploy to DMZ Enclave"]\r\n```\r\n\r\n### 3.3 Release Gate Contracts and Thresholds\r\n\r\n| Quality Gate | Tool / Command | Required Threshold | Action on Non-Compliance |\r\n| :--- | :--- | :--- | :--- |\r\n| **Lint & Typecheck** | `pnpm typecheck` | Zero errors, zero `any` | **Immediate failure** |\r\n| **Automated Tests** | `pnpm test:all` | 100% passed, Coverage >= 85% | **Immediate failure** |\r\n| **Cyclomatic Complexity** | `aisdlc verify quality` | CC <= 10 per function | **Release blocked** |\r\n| **Maintainability Index** | `aisdlc verify quality` | MI >= 50.0 / 100 | **Release blocked** |\r\n| **360\xB0 Traceability** | `aisdlc verify traceability` | 100% of requirements linked | **Release blocked** |\r\n| **OSS Licenses** | `aisdlc verify licenses` | Zero forbidden/viral licenses | **Release blocked** |\r\n| **Cryptographic Signature** | `cosign verify` | Valid signature from Corporate CA | **Deployment rejected** |\r\n\r\n---\r\n\r\n## 4. Production Deployment Strategy and Procedure\r\n\r\n### 4.1 Infrastructure Prerequisites and Network Enclaves\r\n\r\n- **Target Enclave**: `SEC-ENC-DMZ-001` (Strict segmentation without direct uncontrolled outbound internet access).\r\n- **Enabled Network Ports**:\r\n  - Port `8443/TCP`: Secure WebSocket ingestion with mutual TLS (mTLS) authentication.\r\n  - Port `9090/TCP`: Prometheus metrics (internal management network only).\r\n- **Secrets and Certificate Management**:\r\n  - Server TLS and client root CA certificates mounted via immutable secret at `/etc/pki/tls/`.\r\n  - Embedding cryptographic keys in environment variables or images is strictly forbidden.\r\n\r\n### 4.2 Rollout Strategy\r\n\r\nA **Canary strategy with progressive telemetry metrics analysis** is utilized:\r\n1. 10% of traffic is routed to the new version for 15 minutes.\r\n2. If the 5xx error rate is `<= 0.01%` and p99 latency is `<= 50ms`, traffic is promoted to 100%.\r\n\r\n### 4.3 Step-by-Step Deployment Procedure\r\n\r\n1. **Step 1: Pre-deployment and State Snapshot**\r\n   ```bash\r\n   # Check cluster health and record baseline\r\n   kubectl get pods -n production -l app=system\r\n   kubectl exec -it system-db-0 -- /backup/create-snapshot.sh\r\n   ```\r\n\r\n2. **Step 2: Deployment Manifest Application**\r\n   ```bash\r\n   kubectl apply -f deploy/production/canary-deployment.yaml\r\n   kubectl rollout status deployment/system-service -n production --timeout=180s\r\n   ```\r\n\r\n3. **Step 3: Health Verification and Smoke Tests**\r\n   ```bash\r\n   curl -f --cacert /etc/pki/tls/ca.crt https://127.0.0.1:8443/healthz\r\n   curl -f --cacert /etc/pki/tls/ca.crt https://127.0.0.1:8443/readyz\r\n   pnpm test:example\r\n   ```\r\n\r\n### 4.4 Rollback Plan (Immediate Rollback)\r\n\r\n- **Objective Rollback Activation Criteria**:\r\n  - mTLS handshake failure rate `> 1.0%`.\r\n  - Ingestion p99 latency `> 100ms` for 2 continuous minutes.\r\n  - Critical `CrashLoopBackOff` alert on more than 20% of instances.\r\n- **Rollback Execution Command**:\r\n  ```bash\r\n  kubectl rollout undo deployment/system-service -n production\r\n  kubectl rollout status deployment/system-service -n production\r\n  ```\r\n\r\n---\r\n\r\n## 5. Likely Errors Resolution and Troubleshooting (Runbooks)\r\n\r\nThis section documents the most frequent runtime and deployment failures along with diagnosis and immediate mitigation procedures.\r\n\r\n### 5.1 Frequent Incidents and Solutions Matrix\r\n\r\n#### Incident 1: Dependency Vertex Inconsistency or Drift (Build Failure)\r\n- **Symptom**: `pnpm install --frozen-lockfile` command fails in CI with error `ERR_PNPM_LOCKFILE_OUTDATED`.\r\n- **Root Cause**: `package.json` was modified without updating `pnpm-lock.yaml`.\r\n- **Diagnosis**:\r\n  ```bash\r\n  git diff HEAD^ package.json pnpm-lock.yaml\r\n  ```\r\n- **Mitigation**:\r\n  1. On the feature branch, run `pnpm install` locally to regenerate the deterministic lockfile.\r\n  2. Verify no restricted-license dependencies were introduced via `pnpm verify:licenses`.\r\n  3. Commit both files together in an atomic commit.\r\n\r\n---\r\n\r\n#### Incident 2: mTLS Handshake Failure or Enclave Certificate Rejected\r\n- **Symptom**: Clients receive error `ERR_TLS_CERT_ALTNAME_INVALID` or connection closed with TLS alert `certificate_unknown (46)`.\r\n- **Root Cause**: Internal root CA mounted on server does not match the client certificate issuer CA, or certificate expired.\r\n- **Diagnosis**:\r\n  ```bash\r\n  openssl s_client -connect 127.0.0.1:8443 -CAfile /etc/pki/tls/ca.crt -cert /etc/pki/tls/client.crt -key /etc/pki/tls/client.key\r\n  openssl x509 -in /etc/pki/tls/ca.crt -noout -dates -issuer -subject\r\n  ```\r\n- **Mitigation**:\r\n  1. Verify expiration date of certificate mounted in cluster Secret.\r\n  2. If expired, rotate the certificate by injecting the new pair from HSM / Vault storage.\r\n  3. Orderly restart pods with `kubectl rollout restart deployment/system-service`.\r\n\r\n---\r\n\r\n#### Incident 3: Release Gate Rejection in CI/CD Due to Quality Metrics\r\n- **Symptom**: Pipeline aborts with verdict `Quality Gate REJECTED` (Cyclomatic Complexity > 10 or Maintainability < 50).\r\n- **Root Cause**: Introduction of complex nested logic (multiple `if/else`, extensive `switch`, or branching loops).\r\n- **Diagnosis**:\r\n  ```bash\r\n  pnpm verify:quality\r\n  ```\r\n- **Mitigation**:\r\n  1. Inspect the violation report in `reports/QUALITY_GATE_REPORT.md` to identify the offending function.\r\n  2. Decompose function into cohesive private helper methods following the rule of maximum 40 lines per function.\r\n  3. Re-run `pnpm verify:quality` until green verdict is confirmed. Adding suppression comments (`// @ts-ignore`) is forbidden.\r\n\r\n---\r\n\r\n#### Incident 4: CrashLoopBackOff Due to Memory Leak or Connection Limit\r\n- **Symptom**: Pod is terminated with exit code `ExitCode: 137` (`OOMKilled`) after a load spike.\r\n- **Root Cause**: Undrained socket buffer accumulation during high-frequency bursts.\r\n- **Diagnosis**:\r\n  ```bash\r\n  kubectl describe pod system-service-xxx -n production | grep -i oom\r\n  kubectl logs system-service-xxx -n production --previous\r\n  ```\r\n- **Mitigation**:\r\n  1. Temporarily adjust memory limits in Kubernetes manifest (`resources.limits.memory`) if the load burst is legitimate.\r\n  2. Apply backpressure or discard expired packets in accordance with business rules (`BR-*`).\r\n  3. Run local benchmark with `pnpm test:all` to audit memory consumption.\r\n\r\n---\r\n\r\n### 5.2 Escalation Protocol and Critical Incident Management\r\n\r\n| Severity Level | Impact Criterion | Maximum Response Time | Roles Involved |\r\n| :--- | :--- | :---: | :--- |\r\n| **SEV-1 (Critical)** | Complete service outage or security breach in enclave. | 15 minutes | On-call SRE + Lead Architect + SecOps |\r\n| **SEV-2 (Major)** | Severe service degradation, massive retries without outage. | 1 hour | On-call SRE + Tech Lead |\r\n| **SEV-3 (Minor)** | Isolated node incident without global SLA impact. | 4 hours | Support Engineer / DevOps |\r\n\r\n---\r\n\r\n## 6. Revision History and Version Control\r\n\r\n| Version | Date | Author / Agent | Change Description | Change Reference (Change/PR) |\r\n| :--- | :--- | :--- | :--- | :--- |\r\n| **1.0.0** | 2026-09-15 | Operations & DevOps Team | Initial Production Manual generation | CHG-009 |\r\n';
 var STARTER_TEMPLATES_MANUALS_USER_MANUAL_TEMPLATE_MD = '---\r\nid: MAN-USER-001\r\ntype: user-manual\r\ntitle: "User Manual: Application Name"\r\nstatus: draft\r\nversion: "1.0.0"\r\nschema-version: "1.0"\r\napplies-to-version: "v1.0.0"\r\ntarget-audience:\r\n  - ACT-ROLE-USER-001\r\n  - ACT-OPERATOR-002\r\nallowed-roles:\r\n  - ACT-ROLE-USER-001\r\n  - ACT-OPERATOR-002\r\njourneys-covered:\r\n  - JRN-JOURNEY-001\r\nuse-cases-covered:\r\n  - UC-ACTION-001\r\nsupersedes: null\r\nsuperseded-by: null\r\n---\r\n\r\n# MAN-USER-001: User Manual - Application Name\r\n\r\n## 1. System Purpose and Audience\r\n\r\nConcisely describes the software\'s purpose, the operational value it delivers to end users, and the general context in which it operates.\r\n\r\n- **Application / System**: `[System Name or Bounded Context]`\r\n- **Software Version**: `v1.0.0`\r\n- **Target Audience**: `[Functional roles and user profiles addressed]`\r\n\r\n---\r\n\r\n## 2. User Role Catalog and Permissions Matrix (RBAC)\r\n\r\nThis section formally defines the roles authorized to access and operate the application, as well as the privileges assigned to each.\r\n\r\n### 2.1 Authorized Role Catalog\r\n\r\n| Role Identifier | Role Name | Associated Actor | Description & Responsibility | Enclave / Access Level |\r\n| :--- | :--- | :--- | :--- | :--- |\r\n| **`ROLE_USER`** | Standard User | `ACT-ROLE-USER-001` | Data queries and nominal business flow execution. | Corporate Network / Web UI |\r\n| **`ROLE_OPERATOR`** | System Operator | `ACT-OPERATOR-002` | Streaming supervision, alert management, and command control. | DMZ Enclave / Operational Console |\r\n\r\n### 2.2 Access and Capabilities Matrix by Role\r\n\r\n| Application Capability / Module | `ROLE_USER` | `ROLE_OPERATOR` | Authentication Mode |\r\n| :--- | :---: | :---: | :--- |\r\n| Status Query and Dashboard Visualizations | \u2705 Allowed | \u2705 Allowed | Bearer Token (OIDC/JWT) |\r\n| Business Journey Execution (`JRN-JOURNEY-001`) | \u2705 Allowed | \u2705 Allowed | Bearer Token (OIDC/JWT) |\r\n| Real-Time Streaming and Operational Control | \u274C Denied | \u2705 Allowed | mTLS + Device X.509 Certificate |\r\n| Global Parameters Configuration & Connectivity | \u274C Denied | \u2705 Allowed | Administrator Credential |\r\n\r\n---\r\n\r\n## 3. Version and User Platform Compatibility Matrix\r\n\r\nThis section specifies cross-compatibility between the current application version and user environments, clients, and formats.\r\n\r\n### 3.1 Client-Server Compatibility (APIs and SDKs)\r\n\r\n| Application Version (Backend) | Compatible CLI Version | Compatible SDK Version | Compatibility Status | Migration Notes |\r\n| :---: | :---: | :---: | :---: | :--- |\r\n| **`v1.0.0`** (Current) | `>= v1.0.0` | `>= v1.0.0` | \u2705 Fully Supported | Active canonical version. |\r\n| **`v1.0.0`** (Current) | `v0.9.x` | `v0.9.x` | \u26A0\uFE0F Degraded Mode | Requires upgrade before next minor. |\r\n| **`v1.0.0`** (Current) | `< v0.9.0` | `< v0.9.0` | \u274C Incompatible / Deprecated | Legacy endpoints decommissioned. |\r\n\r\n### 3.2 Homologated Browsers and Client Platforms\r\n\r\n| Platform / Environment | Minimum Supported Versions | Support Level | Known Constraints |\r\n| :--- | :--- | :---: | :--- |\r\n| **Google Chrome / Chromium** | Version `>= 120` | Tier 1 (Official) | Optimal WebSockets and WebGL performance. |\r\n| **Mozilla Firefox** | Version `>= 115 ESR` | Tier 1 (Official) | Full client certificate support. |\r\n| **Safari / WebKit** | Version `>= 17.0` | Tier 2 (Functional) | Requires explicit mTLS enablement in macOS Keychain. |\r\n| **Terminal / CLI (Linux / macOS / Windows)** | Node.js `>= 18` or Bash `>= 5.0` | Tier 1 (Official) | Full support on PowerShell 7+ and bash. |\r\n\r\n### 3.3 Configuration Files and Data Formats Compatibility\r\n\r\n| Format / Artifact | Source Version Supported | Automatic Conversion | User Action Required |\r\n| :--- | :---: | :---: | :--- |\r\n| **`config.yaml`** | `v0.9.x` | \u2705 Yes | None. Application migrates deprecated keys on startup. |\r\n| **Export Profiles (`.json`)** | `v0.9.x` | \u2705 Yes | 100% backward compatible. |\r\n\r\n---\r\n\r\n## 4. Application Installation, Access, and Configuration\r\n\r\n### 4.1 Access Channels and Prerequisites\r\n\r\n- **Web Portal / UI**: Access URL (e.g., `https://app.system.internal`).\r\n- **Command Line (CLI)**: Executable binary or package (e.g., `npx system-cli` or `./system-client`).\r\n- **Supported Browsers or Platforms**: Chrome >= 120, Firefox >= 120, Linux/macOS/Windows terminal.\r\n\r\n### 4.2 Client Configuration and Environment Variables\r\n\r\nThe application allows parameterizing its behavior via environment variables or local configuration files:\r\n\r\n| Parameter / Variable | Type | Default Value | Required | Description |\r\n| :--- | :--- | :--- | :---: | :--- |\r\n| `API_ENDPOINT` | URL | `https://api.system.internal/v1` | Yes | Base backend API endpoint. |\r\n| `WS_STREAM_URL` | WSS URL | `wss://stream.system.internal/telemetry` | No | Real-time telemetry or notifications socket. |\r\n| `CLIENT_TIMEOUT_MS` | Integer | `5000` | No | Network response timeout in milliseconds. |\r\n| `AUTH_PROFILE` | String | `production` | No | Active authentication profile (`development`, `staging`, `production`). |\r\n\r\n### 4.3 Local Configuration File (`config.yaml` / `.env`)\r\n\r\nExample recommended configuration for operator workstations:\r\n\r\n```yaml\r\n# Client configuration file: config.yaml\r\nprofile: production\r\nnetwork:\r\n  api_endpoint: "https://api.system.internal/v1"\r\n  stream_url: "wss://stream.system.internal/telemetry"\r\n  timeout_ms: 5000\r\n  retry_attempts: 3\r\n\r\nsecurity:\r\n  tls_verify: true\r\n  client_cert_path: "/etc/pki/client/operator.crt"\r\n  client_key_path: "/etc/pki/client/operator.key"\r\n\r\nui:\r\n  theme: "dark"\r\n  refresh_interval_sec: 1\r\n```\r\n\r\n---\r\n\r\n## 5. Step-by-Step Journey Execution Guide (`JRN-*`)\r\n\r\nEach subsection documents an end-to-end Journey, specifying authorized execution roles, starting conditions, and the step-by-step operating procedure.\r\n\r\n### 5.1 `JRN-JOURNEY-001`: User Journey Name\r\n\r\n- **Linked Use Case**: `UC-ACTION-001`\r\n- **Primary Actor**: `ACT-ROLE-USER-001`\r\n- **Authorized Roles**: `ROLE_USER`, `ROLE_OPERATOR`\r\n- **Required Execution Enclave**: Corporate Intranet or VPN access\r\n\r\n#### A. Preconditions\r\n1. User must have an active and authenticated session with their authorized role.\r\n2. The base entity or resource must be in `ACTIVE` state.\r\n\r\n#### B. Step-by-Step Procedure\r\n\r\n1. **Step 1: Operation Initiation**\r\n   - **Action**: User navigates to the execution section or invokes the corresponding command:\r\n     ```bash\r\n     system-cli execute --journey JRN-JOURNEY-001 --input payload.json\r\n     ```\r\n   - **Required Input**: Resource identifier and validated parameters.\r\n   - **Expected On-Screen Response**: System displays confirmation dialog with operation summary.\r\n\r\n2. **Step 2: Validation and Submission**\r\n   - **Action**: User reviews parameters and confirms execution.\r\n   - **System Behavior**: Client locally validates data schema and transmits signed request.\r\n\r\n3. **Step 3: Observable Outcome Verification**\r\n   - **Success Outcome**: Console / interface displays success message `MSG-SUCCESS-001` with generated unique transaction ID.\r\n   - **Final State**: Resource transitions to `PROCESSED` state.\r\n\r\n#### C. Alternative Flows and Exception Handling\r\n- **Unauthorized Access**: If an unauthorized role attempts to invoke the journey, the system blocks the action, outputs code `MSG-ERR-AUTH-403`, and records the access attempt in the audit trail.\r\n- **Connection Loss in Transit**: If connection is lost during step 2, client retries with exponential backoff up to 3 times before notifying user.\r\n\r\n---\r\n\r\n## 6. System Messages Catalog and Response Codes\r\n\r\nStructured matrix of key informational, warning, and error messages emitted by the application during its operational lifecycle:\r\n\r\n| Code | Severity | Literal Screen Message | Trigger / Context | Meaning for User | Recommended Corrective Action |\r\n| :--- | :--- | :--- | :--- | :--- | :--- |\r\n| **`MSG-SYS-100`** | `INFO` | `"Connection established successfully with server"` | Successful network handshake upon initializing session. | Application is online and ready to process commands. | None. Normal operation. |\r\n| **`MSG-SYS-200`** | `INFO` | `"Operation completed successfully. Transaction ID: [TX-ID]"` | Successful completion of a Journey or Use Case. | Transaction was persisted and acknowledged by backend. | Save `TX-ID` for tracking if required. |\r\n| **`MSG-WARN-301`** | `WARN` | `"High link latency (>500ms). Degraded mode active"` | Response metric exceeds real-time threshold. | Screen data may experience slight refresh delays. | Check network connection quality or bandwidth. |\r\n| **`MSG-WARN-302`** | `WARN` | `"Session expiring in 5 minutes"` | Authentication token approaching TTL expiry. | User will be logged out unless credential is refreshed. | Renew session by clicking alert or re-authenticating. |\r\n| **`MSG-ERR-401`** | `ERR-USER` | `"Invalid credentials or expired token. Access denied"` | Login authentication failure or expired token. | User identity could not be validated. | Re-enter credentials or request a new token. |\r\n| **`MSG-ERR-403`** | `ERR-USER` | `"Unauthorized action for assigned role [ROLE]"` | Attempted execution of Journey or command outside RBAC. | User role lacks permissions for this resource. | Contact administrator to request permission expansion. |\r\n| **`MSG-ERR-422`** | `ERR-USER` | `"Invalid payload: field [FIELD] does not match schema"` | Syntactic validation or business rule (`BR-*`) failure. | User-supplied data is invalid. | Correct indicated fields according to business rule. |\r\n| **`MSG-ERR-503`** | `ERR-SYS` | `"Service temporarily unavailable. Retrying..."` | Backend gateway unreachable or under scheduled maintenance. | Central server is not responding to requests. | Await automatic retries or check system status page. |\r\n\r\n---\r\n\r\n## 7. Frequently Asked Questions (FAQ) and Support\r\n\r\n- **What should I do if I lose connectivity while executing a Journey?**  \r\n  The application implements idempotency mechanisms. Once network connectivity is restored, verify resource status before retrying to prevent duplicate transactions.\r\n- **How do I request a user role change?**  \r\n  Contact the Security Administrator (`SecOps`) referencing your user ID and operational justification for the role change.\r\n\r\n---\r\n\r\n## 8. Revision History and Version Control\r\n\r\n| Version | Date | Author / Agent | Change Description | Change Reference (Change/PR) |\r\n| :--- | :--- | :--- | :--- | :--- |\r\n| **1.0.0** | 2026-09-15 | Documentation & Product Team | Initial User Manual generation | CHG-009 |\r\n';
@@ -13477,12 +13387,6 @@ stages:
 
 default:
   image: node:20
-  cache:
-    key:
-      files:
-        - pnpm-lock.yaml
-    paths:
-      - .pnpm-store
 
 variables:
   PNPM_HOME: "$CI_PROJECT_DIR/.pnpm"
@@ -13632,13 +13536,9 @@ var STARTER_BITBUCKET_PIPELINES = `# ===========================================
 image: node:20
 
 definitions:
-  caches:
-    pnpm: $BITBUCKET_CLONE_DIR/.pnpm-store
   steps:
     - step: &build-and-verify
         name: Quality Gates & Verification
-        caches:
-          - pnpm
         script:
           - corepack enable
           - corepack prepare pnpm@10 --activate
@@ -13652,8 +13552,6 @@ definitions:
 
     - step: &sdd-integrate
         name: SDD Canonical Integration
-        caches:
-          - pnpm
         script:
           - corepack enable
           - corepack prepare pnpm@10 --activate
@@ -13712,7 +13610,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: \${{ matrix.node-version }}
-          cache: 'pnpm'
 
       - name: Install Dependencies
         run: |
@@ -13758,7 +13655,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: 'pnpm'
 
       - name: Install Dependencies
         run: |
@@ -13879,7 +13775,6 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: 'pnpm'
 
       - name: Install Dependencies
         run: |