diff --git a/.github/CICD-CHANGES-2026-06-04.md b/.github/CICD-CHANGES-2026-06-04.md
index 672a8a74..8a21131e 100644
--- a/.github/CICD-CHANGES-2026-06-04.md
+++ b/.github/CICD-CHANGES-2026-06-04.md
@@ -1,3 +1,8 @@
+
+
# CI/CD Changes — 2026-06-04
**Date:** 2026-06-04
@@ -22,7 +27,7 @@ All 18 workflows in this repository have been updated to include `timeout-minute
| Workflow | timeout-minutes | Concurrency Added | Notes |
|----------|-----------------|------------------|-------|
| `abi-drift.yml` | 15 | | ABI manifest + FFI verification |
-| `codeql.yml` | 15 | ✓ | Includes C++ support (has C/C++ headers) |
+| `codeql.yml` | 15 | ✓ | JavaScript/TypeScript CodeQL only; Zig FFI is covered by Zig workflows |
| `container-publish.yml` | 30 | | Container build & push |
| `dogfood-gate.yml` | 5-15 | ✓ | 6 jobs: a2ml(5), k9(5), empty-lint(15), groove(5), eclexiaiser(5), summary(5) |
| `e2e.yml` | 15 | ✓ | MCP bridge input fuzz tests |
@@ -54,8 +59,13 @@ All 18 workflows in this repository have been updated to include `timeout-minute
## CodeQL Configuration
-**Languages:** `javascript-typescript` + `cpp`
-**Reason:** This repository contains C/C++ headers in the FFI layer.
+**Languages:** `javascript-typescript`
+
+**Reason:** The FFI implementation is Zig. The tracked C ABI file is a generated
+header-only surface (`generated/abi/boj_catalogue.h`), not a C/C++ translation
+unit; enabling CodeQL `cpp` for headers alone makes extraction fail before
+analysis. Re-add `cpp` only when tracked `.c`, `.cc`, `.cpp`, or `.cxx` sources
+exist.
---
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index 4cb86bb3..ee97c746 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -33,8 +33,10 @@ jobs:
include:
- language: javascript-typescript
build-mode: none
- - language: cpp
- build-mode: none
+ # C/C++ CodeQL is intentionally not enabled for the generated
+ # header-only ABI surface. The FFI implementation is Zig and is
+ # covered by the Zig workflows; re-add cpp only when tracked
+ # .c/.cc/.cpp/.cxx translation units exist.
steps:
- name: Checkout
diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml
index 76d824db..d18476e8 100644
--- a/.github/workflows/dogfood-gate.yml
+++ b/.github/workflows/dogfood-gate.yml
@@ -165,6 +165,9 @@ jobs:
echo "::warning file=${REL_PATH}::Invisible Unicode characters detected (zero-width space, BOM, NBSP, etc.)"
done < /tmp/empty-lint-results.txt
+ - name: Check shebang placement
+ run: bash scripts/check-shebang-first.sh
+
- name: Write summary
run: |
if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then
@@ -374,4 +377,3 @@ jobs:
*Generated by the [Dogfood Gate](https://github.com/hyperpolymath/rsr-template-repo) workflow.*
*Dogfooding is guinea pig fooding — we test our tools on ourselves.*
EOF
-
diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml
index 1b4e269a..8161ec24 100644
--- a/.github/workflows/governance.yml
+++ b/.github/workflows/governance.yml
@@ -1,35 +1,16 @@
-# SPDX-License-Identifier: MPL-2.0
-# governance.yml — single wrapper calling the shared estate governance bundle
-# in hyperpolymath/standards instead of carrying per-repo copies.
-#
-# Replaces the per-repo governance scaffolding removed in the same commit:
-# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml,
-# security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml,
-# workflow-linter.yml
-#
-# Load-bearing build/security workflows stay standalone in the repo
-# (rust-ci, codeql, dependabot, release, scan/mirror/pages plumbing).
-
+# SPDX-License-Identifier: PMPL-1.0-or-later
name: Governance
on:
push:
branches: [main, master]
pull_request:
+ branches: [main, master]
workflow_dispatch:
-# Estate guardrail: cancel superseded runs so re-pushes / rebased PR
-# updates do not pile up queued runs against the shared account-wide
-# Actions concurrency pool. Applied only to read-only check workflows
-# (no publish/mutation), so cancelling a superseded run is always safe.
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
-
permissions:
contents: read
jobs:
governance:
- uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@861b5e911d9e5dcfb3c0ab3dd2a9a3c8fd0a1613
- timeout-minutes: 10
+ uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@5a93d9d57cc04de4002d6d0ecd336fc7a8698910
diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml
index 127905d2..e7158485 100644
--- a/.github/workflows/hypatia-scan.yml
+++ b/.github/workflows/hypatia-scan.yml
@@ -1,415 +1,19 @@
-# SPDX-License-Identifier: MPL-2.0
-# Hypatia Neurosymbolic CI/CD Security Scan
+# SPDX-License-Identifier: PMPL-1.0-or-later
name: Hypatia Security Scan
on:
push:
- branches: [ main, master, develop ]
+ branches: [main, master, develop]
pull_request:
- branches: [ main, master ]
+ branches: [main, master]
schedule:
- - cron: '0 0 * * 0' # Weekly on Sunday
+ - cron: '0 0 * * 0'
workflow_dispatch:
-# Estate guardrail: cancel superseded runs so re-pushes don't pile up
-# queued runs across the estate. Safe here because this workflow only
-# performs read-only checks/lint/test/scan with no publish or mutation.
-concurrency:
- group: ${{ github.workflow }}-${{ github.ref }}
- cancel-in-progress: true
permissions:
contents: read
- # security-events: write serves two purposes (write implies read):
- # 1. read — lets the built-in GITHUB_TOKEN query this repo's own
- # Dependabot alerts via the Hypatia DependabotAlerts rule
- # (DA001-DA004). Without read, `scan_from_path` gets HTTP 403
- # and the rule silently returns no findings.
- # See 007-lang/audits/audit-dependabot-automation-gap-2026-04-17.md.
- # 2. write — lets the "Upload SARIF to code scanning" step publish
- # Hypatia findings to the Security → Code scanning page so they
- # are triaged/deduplicated like CodeQL alerts instead of living
- # only in a build artifact nobody is required to look at.
- # See hyperpolymath/burble#35 (SARIF integration).
- # This is a single-job workflow, so job-level scoping would not
- # narrow the grant further; it stays workflow-level and documented.
- security-events: write
- # pull-requests: write lets the advisory "Comment on PR with findings"
- # step post its summary. Without it the built-in GITHUB_TOKEN gets
- # "Resource not accessible by integration" and (absent continue-on-error)
- # hard-fails the scan — exactly what the gate-decoupling design forbids.
- pull-requests: write
+ security-events: read
jobs:
scan:
- name: Hypatia Neurosymbolic Analysis
- runs-on: ubuntu-latest
- timeout-minutes: 15
-
- steps:
- - name: Checkout repository
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- with:
- fetch-depth: 0 # Full history for better pattern analysis
-
- - name: Setup Elixir for Hypatia scanner
- uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.18.2
- with:
- elixir-version: '1.18'
- otp-version: '27'
-
- - name: Clone Hypatia
- run: |
- if [ ! -d "$HOME/hypatia" ]; then
- git clone https://github.com/hyperpolymath/hypatia.git "$HOME/hypatia"
- fi
-
- - name: Build Hypatia scanner (if needed)
- run: |
- cd "$HOME/hypatia"
- if [ ! -f hypatia ]; then
- echo "Building hypatia scanner..."
- mix deps.get
- mix escript.build
- fi
-
- - name: Run Hypatia scan
- id: scan
- env:
- # Pass the built-in Actions token through to Hypatia so the
- # DependabotAlerts rule can query this repo's own alerts.
- # For cross-repo scanning (fleet-coordinator scan-supervised),
- # a PAT with `security_events` scope is required instead.
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- echo "Scanning repository: ${{ github.repository }}"
-
- # Run scanner (exits non-zero when findings exist — suppress to continue)
- HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json || true
-
- # Count findings
- FINDING_COUNT=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0)
- echo "findings_count=$FINDING_COUNT" >> $GITHUB_OUTPUT
-
- # Extract severity counts
- CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json)
- HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json)
- MEDIUM=$(jq '[.[] | select(.severity == "medium")] | length' hypatia-findings.json)
-
- echo "critical=$CRITICAL" >> $GITHUB_OUTPUT
- echo "high=$HIGH" >> $GITHUB_OUTPUT
- echo "medium=$MEDIUM" >> $GITHUB_OUTPUT
-
- echo "## Hypatia Scan Results" >> $GITHUB_STEP_SUMMARY
- echo "- Total findings: $FINDING_COUNT" >> $GITHUB_STEP_SUMMARY
- echo "- Critical: $CRITICAL" >> $GITHUB_STEP_SUMMARY
- echo "- High: $HIGH" >> $GITHUB_STEP_SUMMARY
- echo "- Medium: $MEDIUM" >> $GITHUB_STEP_SUMMARY
-
- - name: Upload findings artifact
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
- with:
- name: hypatia-findings
- path: hypatia-findings.json
- retention-days: 90
-
- - name: Convert Hypatia findings to SARIF
- # Always runs (no findings_count guard): an EMPTY SARIF run is
- # valid and intentional — uploading it clears stale Hypatia
- # alerts from the code-scanning page when a repo goes clean.
- # The converter is dependency-free Node (Node ships on
- # ubuntu-latest; no npm install — estate npm ban respected) and
- # is hardened against the heterogeneous Hypatia JSON schema:
- # most findings are {rule_module,severity,type,file,reason,
- # action}; only some carry an integer `line`; `file` may be
- # empty or absolute. See lib/hypatia/cli.ex (collect_findings).
- run: |
- cat > "$RUNNER_TEMP/hypatia-sarif.cjs" <<'CJS'
- const fs = require('fs');
- const path = require('path');
- const crypto = require('crypto');
-
- const ws = process.env.GITHUB_WORKSPACE || process.cwd();
-
- let findings = [];
- try {
- const parsed = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
- if (Array.isArray(parsed)) findings = parsed;
- } catch (_) {
- // Scanner unavailable / empty / malformed -> empty SARIF.
- // Intentionally clears stale alerts rather than erroring.
- findings = [];
- }
-
- // Mirrors Hypatia's own "github" annotation mapping
- // (lib/hypatia/cli.ex output/2): critical|high -> error,
- // medium -> warning, everything else -> note.
- const levelFor = (sev) => {
- switch (String(sev || '').toLowerCase()) {
- case 'critical':
- case 'high': return 'error';
- case 'medium': return 'warning';
- default: return 'note';
- }
- };
-
- // SARIF artifactLocation.uri must be a repo-relative POSIX
- // path. Hypatia may emit absolute paths (scanned under
- // $GITHUB_WORKSPACE) or "" / "." for repo-level findings.
- const relUri = (file) => {
- if (!file) return '.';
- let f = String(file);
- if (path.isAbsolute(f)) {
- const rel = path.relative(ws, f);
- f = (rel && !rel.startsWith('..')) ? rel : path.basename(f);
- }
- f = f.replace(/\\/g, '/').replace(/^\.\//, '');
- return f || '.';
- };
-
- const rules = new Map();
- const results = findings.map((f) => {
- const mod = String(f.rule_module || 'hypatia');
- const type = String(f.type || 'finding');
- const ruleId = `hypatia/${mod}/${type}`;
- const level = levelFor(f.severity);
- if (!rules.has(ruleId)) {
- rules.set(ruleId, {
- id: ruleId,
- name: `${mod}.${type}`,
- shortDescription: { text: `Hypatia ${mod}: ${type}` },
- defaultConfiguration: { level }
- });
- }
- const uri = relUri(f.file);
- const msg = String(f.reason || f.type || 'Hypatia finding');
- const startLine =
- Number.isInteger(f.line) && f.line > 0 ? f.line : 1;
- // Stable cross-run fingerprint for dedupe (no line, so a
- // moved finding in the same file/rule stays one alert).
- const fp = crypto
- .createHash('sha256')
- .update([ruleId, uri, type, msg].join('|'))
- .digest('hex');
- return {
- ruleId,
- level,
- message: { text: msg },
- locations: [
- {
- physicalLocation: {
- artifactLocation: { uri },
- region: { startLine }
- }
- }
- ],
- partialFingerprints: { 'hypatiaFindingHash/v1': fp }
- };
- });
-
- const sarif = {
- $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
- version: '2.1.0',
- runs: [
- {
- tool: {
- driver: {
- name: 'Hypatia',
- informationUri: 'https://github.com/hyperpolymath/hypatia',
- rules: Array.from(rules.values())
- }
- },
- results
- }
- ]
- };
-
- fs.writeFileSync('hypatia.sarif', JSON.stringify(sarif, null, 2));
- console.log(`hypatia.sarif written: ${results.length} result(s).`);
- CJS
- node "$RUNNER_TEMP/hypatia-sarif.cjs"
-
- - name: Upload SARIF to GitHub code scanning
- # Fork PRs get a read-only GITHUB_TOKEN, so security-events:write
- # is unavailable and upload-sarif cannot publish — skip there
- # rather than hard-fail (the push/schedule run on the default
- # branch is the authoritative upload). Same-repo PRs and pushes
- # do upload. This step is deliberately NOT continue-on-error:
- # if the security-surface integration breaks we want a loud red,
- # not a silently-ungated scanner (the exact failure mode #35
- # exists to end). The empty-SARIF "clear stale alerts" path is
- # handled in the converter above and does not error here.
- if: >-
- always() &&
- (github.event_name != 'pull_request' ||
- github.event.pull_request.head.repo.fork != true)
- uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.28.1
- with:
- sarif_file: hypatia.sarif
- # Distinct category so Hypatia results coexist with CodeQL's
- # (codeql.yml) instead of overwriting them on the same surface.
- category: hypatia
-
- - name: Submit findings to gitbot-fleet (Phase 2)
- if: steps.scan.outputs.findings_count > 0
- # Phase 2 is the collaborative LEARNING side-channel ("bots share
- # findings via gitbot-fleet"), not the security gate. The gate is
- # the baseline-aware "Check for critical or high-severity issues"
- # step below. A fleet-side regression (e.g. the submit script being
- # moved/removed) must NEVER hard-fail every consuming repo's scan.
- # Same reasoning as the "Comment on PR with findings" step.
- # See hyperpolymath/hypatia#213 (gate decoupling) and the exit-127
- # estate-wide breakage when gitbot-fleet/scripts/submit-finding.sh
- # no longer existed on the default branch.
- continue-on-error: true
- env:
- # All GitHub context values surface as env vars so the run
- # block never interpolates `${{ … }}` inline (closes the
- # workflow_audit/unsafe_curl_payload + actions_expression_injection
- # findings).
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- FLEET_PUSH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
- FLEET_DISPATCH_TOKEN: ${{ secrets.HYPATIA_DISPATCH_PAT }}
- GITHUB_REPOSITORY: ${{ github.repository }}
- GITHUB_SHA: ${{ github.sha }}
- FINDINGS_COUNT: ${{ steps.scan.outputs.findings_count }}
- run: |
- echo "📤 Submitting $FINDINGS_COUNT findings to gitbot-fleet..."
-
- # Clone gitbot-fleet to temp directory. A clone failure (network,
- # repo gone) is non-fatal: learning submission is best-effort.
- FLEET_DIR="/tmp/gitbot-fleet-$$"
- if ! git clone --depth 1 https://github.com/hyperpolymath/gitbot-fleet.git "$FLEET_DIR"; then
- echo "::warning::Could not clone gitbot-fleet — skipping Phase 2 learning submission (non-fatal)."
- exit 0
- fi
-
- # The submission script's location in gitbot-fleet has drifted
- # before (it was absent from the default branch, which exit-127'd
- # every consuming repo's scan). Probe known locations rather than
- # hard-coding one path, and skip gracefully if none is present.
- SUBMIT_SCRIPT=""
- for cand in \
- "$FLEET_DIR/scripts/submit-finding.sh" \
- "$FLEET_DIR/scripts/submit_finding.sh" \
- "$FLEET_DIR/bin/submit-finding.sh" \
- "$FLEET_DIR/submit-finding.sh"; do
- if [ -f "$cand" ]; then
- SUBMIT_SCRIPT="$cand"
- break
- fi
- done
-
- if [ -z "$SUBMIT_SCRIPT" ]; then
- echo "::warning::gitbot-fleet submit-finding script not found at any known path — skipping Phase 2 learning submission (non-fatal). Findings are still uploaded as an artifact and gated below."
- rm -rf "$FLEET_DIR"
- exit 0
- fi
-
- # Run submission script. Pass the findings path as ABSOLUTE —
- # the script cd's into its own working dir before reading the
- # file, so a relative path would resolve to the wrong place.
- # A submission-script failure is logged but non-fatal.
- if bash "$SUBMIT_SCRIPT" "$GITHUB_WORKSPACE/hypatia-findings.json"; then
- echo "✅ Finding submission complete"
- else
- echo "::warning::gitbot-fleet submission script exited non-zero — Phase 2 learning submission skipped (non-fatal)."
- fi
-
- # Cleanup
- rm -rf "$FLEET_DIR"
-
- - name: Check for critical issues
- if: steps.scan.outputs.critical > 0
- # GATING POLICY (explicit, by design — not an oversight):
- # Hypatia is ADVISORY here. Critical findings are surfaced
- # (step annotation + SARIF alert on the code-scanning page +
- # PR comment) but do NOT fail this check. Enforcement is
- # delegated to the code-scanning surface: tighten by adding a
- # branch-protection "required" status on the `hypatia` SARIF
- # category, not by reintroducing an `exit 1` here. This keeps
- # the gate decision in one auditable place (hypatia#213 gate
- # decoupling) and lets a repo opt into fail-on-critical without
- # editing this canonical workflow. To change the policy, change
- # branch protection — deliberately no commented-out `exit 1`.
- run: |
- echo "::warning::Hypatia found critical security issue(s) — advisory."
- echo "See the Security → Code scanning page (category: hypatia)"
- echo "and the hypatia-findings.json artifact for details."
-
- - name: Generate scan report
- run: |
- cat << EOF > hypatia-report.md
- # Hypatia Security Scan Report
-
- **Repository:** ${{ github.repository }}
- **Scan Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
- **Commit:** ${{ github.sha }}
-
- ## Summary
-
- | Severity | Count |
- |----------|-------|
- | Critical | ${{ steps.scan.outputs.critical }} |
- | High | ${{ steps.scan.outputs.high }} |
- | Medium | ${{ steps.scan.outputs.medium }} |
- | **Total**| ${{ steps.scan.outputs.findings_count }} |
-
- ## Next Steps
-
- 1. Triage findings on the **Security → Code scanning** page
- (SARIF category \`hypatia\`) — dismiss/track them there like
- CodeQL alerts.
- 2. The full finding set is also attached as the
- \`hypatia-findings.json\` build artifact for offline review.
- 3. Findings are **advisory** today (surfaced, not gated); the
- gating policy is documented in the workflow's "Check for
- critical issues" step.
-
- ## Learning
-
- These findings feed Hypatia's learning engine to improve future rules.
-
- ---
- *Powered by [Hypatia](https://github.com/hyperpolymath/hypatia) - Neurosymbolic CI/CD Intelligence*
- EOF
-
- cat hypatia-report.md >> $GITHUB_STEP_SUMMARY
-
- - name: Comment on PR with findings
- if: github.event_name == 'pull_request' && steps.scan.outputs.findings_count > 0
- # Advisory only — posting findings as a PR comment must never gate
- # the scan (hypatia#213 gate decoupling). Belt-and-braces alongside
- # the pull-requests: write permission above: a token/API hiccup or
- # a fork PR (read-only token) skips the comment, not the check.
- continue-on-error: true
- uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v7
- with:
- script: |
- const fs = require('fs');
- const findings = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));
-
- const critical = findings.filter(f => f.severity === 'critical').length;
- const high = findings.filter(f => f.severity === 'high').length;
-
- let comment = `## 🔍 Hypatia Security Scan\n\n`;
- comment += `**Findings:** ${findings.length} issues detected\n\n`;
- comment += `| Severity | Count |\n|----------|-------|\n`;
- comment += `| 🔴 Critical | ${critical} |\n`;
- comment += `| 🟠 High | ${high} |\n`;
- comment += `| 🟡 Medium | ${findings.length - critical - high} |\n\n`;
-
- if (critical > 0) {
- comment += `⚠️ **Action Required:** Critical security issues found!\n\n`;
- }
-
- comment += `View findings
\n\n`;
- comment += `\`\`\`json\n${JSON.stringify(findings.slice(0, 10), null, 2)}\n\`\`\`\n`;
- comment += `