Wire free production readiness stack

.github/workflows/free-production-readiness.yml

@@ -0,0 +1,104 @@
+name: Free Production Readiness
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  business-contracts:
+    name: Business contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run low-gray business contracts
+        run: npm run verify:business
+
+      - name: Run advisory source-shape contracts
+        run: npm run test:business:advisory
+        continue-on-error: true
+
+  route-hygiene:
+    name: Route Hygiene P0/P1
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check route hygiene
+        run: npm run routes:check
+
+      - name: Upload route hygiene reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: route-hygiene-reports
+          path: docs/operations/generated/
+          if-no-files-found: ignore
+          retention-days: 14
+
+  static-radar:
+    name: Static radar advisory
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Semgrep CE
+        run: python -m pip install semgrep
+
+      - name: Run Semgrep Helm rules
+        run: npm run analyze:semgrep
+
+      - name: Run dependency-cruiser
+        run: npm run analyze:deps
+
+      - name: Run duplicate-code radar
+        run: npm run analyze:duplicates
+
+      - name: Run Helm auditor
+        if: always()
+        run: npm run auditor:all
+
+      - name: Upload static radar reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: static-radar-reports
+          path: |
+            docs/operations/generated/
+            docs/operations/revealed-bugs/production-readiness/
+          if-no-files-found: ignore
+          retention-days: 14

.gitignore

@@ -139,6 +139,10 @@ scripts/rotate-demo-passwords.mjs
 /test-results/
 /playwright-report/
 
+# Production-readiness generated reports.
+/docs/operations/generated/
+/.stryker-tmp/
+
 # Large generated showcase binaries (repo already ignores GolfHelm-Prospect-Deck.pptx).
 GolfHelm-CoachHelm-Showcase.pdf
 GolfHelm-Fairway-Guide.pdf

.semgrep/helm-rules.yml

@@ -0,0 +1,89 @@
+rules:
+  - id: helm-service-role-in-client-code
+    severity: ERROR
+    languages: [typescript, javascript]
+    message: Service-role/admin Supabase client must not be imported from client-facing code.
+    paths:
+      include:
+        - /src/**/*.ts
+        - /src/**/*.tsx
+      exclude:
+        - /src/lib/supabase/admin.ts
+        - /src/**/*.test.ts
+        - /src/**/*.test.tsx
+        - /src/contracts/**
+    patterns:
+      - pattern-either:
+          - pattern: import $X from '@/lib/supabase/admin'
+          - pattern: import { $X } from '@/lib/supabase/admin'
+          - pattern: createAdminClient(...)
+      - pattern-not-inside: |
+          "use server";
+          ...
+
+  - id: helm-golf-file-links-baseball-auth-or-dashboard
+    severity: ERROR
+    languages: [typescript]
+    message: Golf files must not link or redirect to Baseball auth/dashboard routes.
+    patterns:
+      - pattern-either:
+          - pattern: '"/baseball/$PATH"'
+          - pattern: "'/baseball/$PATH'"
+    paths:
+      include:
+        - /src/app/golf/**/*.ts
+        - /src/app/golf/**/*.tsx
+
+  - id: helm-baseball-file-links-golf-auth-or-dashboard
+    severity: ERROR
+    languages: [typescript]
+    message: Baseball files must not link or redirect to Golf auth/dashboard routes.
+    patterns:
+      - pattern-either:
+          - pattern: '"/golf/$PATH"'
+          - pattern: "'/golf/$PATH'"
+      - metavariable-regex:
+          metavariable: $PATH
+          regex: ^(login|signup|dashboard).*
+    paths:
+      include:
+        - /src/app/baseball/**/*.ts
+        - /src/app/baseball/**/*.tsx
+
+  - id: helm-success-true-inside-catch
+    severity: ERROR
+    languages: [typescript, javascript]
+    message: Catch blocks must not return success:true.
+    pattern: |
+      catch ($ERR) {
+        ...
+        return { ..., success: true, ... };
+      }
+
+  - id: helm-llm-call-in-client-component
+    severity: ERROR
+    languages: [typescript]
+    message: LLM generation must stay server-side.
+    patterns:
+      - pattern-either:
+          - pattern: generateText(...)
+          - pattern: streamText(...)
+      - pattern-inside: |
+          "use client";
+          ...
+
+  - id: helm-catch-collapses-error-to-empty
+    severity: WARNING
+    languages: [typescript, javascript]
+    message: Catch block collapses a failure to []/null; prefer an explicit error state.
+    pattern-either:
+      - pattern: |
+          catch ($ERR) {
+            ...
+            return [];
+          }
+      - pattern: |
+          catch ($ERR) {
+            ...
+            return null;
+          }

dependency-cruiser.config.cjs

@@ -0,0 +1,65 @@
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: 'golf-app-must-not-import-baseball-app',
+      severity: 'error',
+      from: { path: '^src/app/golf/' },
+      to: { path: '^src/app/baseball/' },
+    },
+    {
+      name: 'baseball-app-must-not-import-golf-app',
+      severity: 'error',
+      from: { path: '^src/app/baseball/' },
+      to: { path: '^src/app/golf/' },
+    },
+    {
+      name: 'golf-lib-must-not-import-baseball-lib',
+      severity: 'error',
+      from: { path: '^src/lib/golf/' },
+      to: { path: '^src/lib/baseball/' },
+    },
+    {
+      name: 'baseball-lib-must-not-import-golf-lib',
+      severity: 'error',
+      from: { path: '^src/lib/baseball/' },
+      to: { path: '^src/lib/golf/' },
+    },
+    {
+      name: 'lib-must-not-import-app',
+      severity: 'error',
+      from: { path: '^src/lib/' },
+      to: { path: '^src/app/' },
+    },
+    {
+      name: 'coachhelm-core-must-not-import-ui-pages',
+      severity: 'error',
+      from: { path: '^src/lib/coachhelm/' },
+      to: { path: '^src/(app|components)/' },
+    },
+    {
+      name: 'stats-helpers-must-not-import-react-ui',
+      severity: 'error',
+      from: { path: '^src/lib/.*/(stats|stat|calculator|formulas)' },
+      to: { dependencyTypes: ['npm'], path: '^(react|react-dom|next)' },
+    },
+    {
+      name: 'no-circular-coachhelm-or-stats',
+      severity: 'error',
+      from: { path: '^src/lib/(coachhelm|.*stats.*|.*golf.*)' },
+      to: { circular: true },
+    }
+  ],
+  options: {
+    doNotFollow: { path: 'node_modules' },
+    tsPreCompilationDeps: true,
+    tsConfig: { fileName: 'tsconfig.json' },
+    enhancedResolveOptions: {
+      exportsFields: ['exports'],
+      conditionNames: ['import', 'require', 'node', 'default'],
+    },
+    reporterOptions: {
+      dot: { collapsePattern: 'node_modules/[^/]+' },
+    },
+  },
+};

docs/operations/BRANCH_PROTECTION.md

@@ -13,6 +13,8 @@ Required checks for `main` should match the hard blockers in `docs/operations/GA
 - `Unit tests`
 - `Next build`
 - `Supabase lint + RLS tests`
+- `Business contracts`
+- `Route Hygiene P0/P1`
 - `Playwright Smoke / Smoke checks`
 - `Review Gate / all`
 - `CodeRabbit`
@@ -22,10 +24,14 @@ Required checks for `main` should match the hard blockers in `docs/operations/GA
 Do not require these until they are stable enough to block everyday work:
 
 - `Playwright E2E Advisory`
-- `Business contracts`
+- `Business contracts advisory`
 - `Course picker screenshots`
 - CircleCI weekly radar jobs
 - Lighthouse preview jobs
+- `Knip`
+- `jscpd`
+- `Stryker`
+- `k6 staging load`
 
 ## Change Rule
 

docs/operations/FREE_PRODUCTION_READINESS_STACK.md

@@ -0,0 +1,59 @@
+# Free Production Readiness Stack
+
+This branch wires the free/open-source production-readiness foundation for Helm without changing product behavior.
+
+## Installed Tools
+
+Repo dev dependencies:
+
+- `fast-check`
+- `@stryker-mutator/core`
+- `@stryker-mutator/vitest-runner`
+- `dependency-cruiser`
+- `jscpd`
+- `knip`
+- `@axe-core/playwright`
+- `@lhci/cli`
+
+Machine CLIs verified on this workstation:
+
+- `semgrep`
+- `gitleaks`
+- `osv-scanner`
+- `k6`
+
+## New Lanes
+
+- `npm run test:business`: low-gray Vitest business contracts.
+- `npm run test:business:advisory`: source-shape advisory contracts.
+- `npm run routes:check`: route inventory plus duplicate/stale/boundary/coverage/dead-route checks.
+- `npm run analyze:semgrep`: Helm Semgrep CE rules.
+- `npm run analyze:deps`: dependency-cruiser architecture report.
+- `npm run analyze:duplicates`: jscpd duplicate-code report.
+- `npm run prod:audit:db`: SELECT-only DB audit; skips safely without `PROD_AUDIT_DATABASE_URL`.
+- `npm run auditor:all`: aggregates generated reports into issue drafts.
+
+Generated reports go under `docs/operations/generated/` and are ignored by git.
+
+## Gate Posture
+
+Immediate hard candidates:
+
+- Business contracts
+- Route Hygiene P0/P1
+- Existing CI hard gates
+- Existing Review Gate / gitleaks / semgrep / CodeQL checks
+
+Advisory first:
+
+- Business source-shape advisory
+- Stryker mutation pilots
+- Knip
+- jscpd
+- dependency-cruiser lower-severity findings
+- k6 staging load
+- Lighthouse public route budgets
+
+## Gray-Test Cleanup
+
+Source-sniffing contracts were moved to `*.advisory.contract.test.ts`. The low-gray path now includes pure product-trust state mappers and property contracts for GolfHelm stats.

docs/operations/GATE_MATRIX.md

@@ -19,17 +19,23 @@ This file is the current map of hard merge blockers versus advisory checks.
 | Review Gate / ast-grep | `review-gate.yml` | project-specific banned patterns |
 | Review Gate / semgrep | `review-gate.yml` | security and static-analysis risks |
 | Review Gate / gitleaks | `review-gate.yml` | leaked secrets |
+| Business Contracts | `npm run verify:business` / `Business contracts` | low-gray product-truth regressions in stats, CoachHelm evidence, and product trust mappers |
+| Route Hygiene P0/P1 | `npm run routes:check` | missing or duplicate critical routes and Golf/Baseball route-boundary leaks |
 
 ## Advisory Checks
 
 | Check | Why Advisory |
 |---|---|
 | Playwright E2E Advisory | full suite is still stabilizing |
-| Business Contracts | advisory product-truth radar for GolfHelm stats, CoachHelm evidence, access boundaries, and product trust states |
+| Business Contracts Advisory | source-shape radar for contracts that still need behavior-test replacements |
 | Course picker screenshots | visual evidence artifact, not a merge blocker |
 | Lighthouse | performance and accessibility visibility |
 | Knip | dead-code discovery |
 | Stryker | mutation-test signal |
+| jscpd | duplicate-code radar |
+| dependency-cruiser P2/P3 | architecture smell radar after P0/P1 boundaries are clean |
+| OSV Scanner | vulnerability triage report until reachability policy is finalized |
+| k6 staging load | staging reliability signal |
 | Promptfoo | AI output drift signal |
 | npm audit | dependency-risk triage |
 | full sqlfluff | SQL style and risk signal |

docs/operations/revealed-bugs/production-readiness/gitleaks-81-redacted-findings.md

@@ -0,0 +1,13 @@
+# Gitleaks reported 81 redacted secret findings
+
+Severity: P0
+Confidence: high
+Source: gitleaks.json
+
+## Evidence
+
+- See ignored generated gitleaks report locally; do not commit raw secret output.
+
+## Suggested Fix
+
+Investigate and fix the production-readiness finding.