security: standardize secret scanning on TruffleHog

Author: hyperpolymath

.github/workflows/hypatia-scan.yml

@@ -1,22 +1,20 @@
 # SPDX-License-Identifier: MPL-2.0
 # Hypatia Neurosymbolic CI/CD Security Scan
 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' # Weekly on Sunday
   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):
@@ -38,31 +36,26 @@ permissions:
   # "Resource not accessible by integration" and (absent continue-on-error)
   # hard-fails the scan — exactly what the gate-decoupling design forbids.
   pull-requests: write
-
 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
-
+          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"
@@ -71,7 +64,6 @@ jobs:
             mix deps.get
             mix escript.build
           fi
-
       - name: Run Hypatia scan
         id: scan
         env:
@@ -104,14 +96,12 @@ jobs:
           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
@@ -227,7 +217,6 @@ jobs:
           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
@@ -239,16 +228,19 @@ jobs:
         # 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' ||
+          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
@@ -272,52 +264,7 @@ jobs:
           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"
-
+        run: "echo \"\U0001F4E4 Submitting $FINDINGS_COUNT findings to gitbot-fleet...\"\n\n# Clone gitbot-fleet to temp directory. A clone failure (network,\n# repo gone) is non-fatal: learning submission is best-effort.\nFLEET_DIR=\"/tmp/gitbot-fleet-$$\"\nif ! git clone --depth 1 https://github.com/hyperpolymath/gitbot-fleet.git \"$FLEET_DIR\"; then\n  echo \"::warning::Could not clone gitbot-fleet — skipping Phase 2 learning submission (non-fatal).\"\n  exit 0\nfi\n\n# The submission script's location in gitbot-fleet has drifted\n# before (it was absent from the default branch, which exit-127'd\n# every consuming repo's scan). Probe known locations rather than\n# hard-coding one path, and skip gracefully if none is present.\nSUBMIT_SCRIPT=\"\"\nfor cand in \\\n  \"$FLEET_DIR/scripts/submit-finding.sh\" \\\n  \"$FLEET_DIR/scripts/submit_finding.sh\" \\\n  \"$FLEET_DIR/bin/submit-finding.sh\" \\\n  \"$FLEET_DIR/submit-finding.sh\"; do\n  if [ -f \"$cand\" ]; then\n    SUBMIT_SCRIPT=\"$cand\"\n    break\n  fi\ndone\n\nif [ -z \"$SUBMIT_SCRIPT\" ]; then\n  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.\"\n  rm -rf \"$FLEET_DIR\"\n  exit 0\nfi\n\n# Run submission script. Pass the findings path as ABSOLUTE —\n# the script cd's into its own working dir before reading the\n# file, so a relative path would resolve to the wrong place.\n# A submission-script failure is logged but non-fatal.\nif bash \"$SUBMIT_SCRIPT\" \"$GITHUB_WORKSPACE/hypatia-findings.json\"; then\n  echo \"✅ Finding submission complete\"\nelse\n  echo \"::warning::gitbot-fleet submission script exited non-zero — Phase 2 learning submission skipped (non-fatal).\"\nfi\n\n# Cleanup\nrm -rf \"$FLEET_DIR\"\n"
       - name: Check for critical issues
         if: steps.scan.outputs.critical > 0
         # GATING POLICY (explicit, by design — not an oversight):
@@ -335,7 +282,6 @@ jobs:
           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
@@ -374,7 +320,6 @@ jobs:
           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
@@ -384,32 +329,4 @@ jobs:
         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 += `<details><summary>View findings</summary>\n\n`;
-            comment += `\`\`\`json\n${JSON.stringify(findings.slice(0, 10), null, 2)}\n\`\`\`\n`;
-            comment += `</details>\n\n`;
-            comment += `*Powered by Hypatia Neurosymbolic CI/CD Intelligence*`;
-
-            github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-              body: comment
-            });
+          script: "const fs = require('fs');\nconst findings = JSON.parse(fs.readFileSync('hypatia-findings.json', 'utf8'));\n\nconst critical = findings.filter(f => f.severity === 'critical').length;\nconst high = findings.filter(f => f.severity === 'high').length;\n\nlet comment = `## \U0001F50D Hypatia Security Scan\\n\\n`;\ncomment += `**Findings:** ${findings.length} issues detected\\n\\n`;\ncomment += `| Severity | Count |\\n|----------|-------|\\n`;\ncomment += `| \U0001F534 Critical | ${critical} |\\n`;\ncomment += `| \U0001F7E0 High | ${high} |\\n`;\ncomment += `| \U0001F7E1 Medium | ${findings.length - critical - high} |\\n\\n`;\n\nif (critical > 0) {\n  comment += `⚠️ **Action Required:** Critical security issues found!\\n\\n`;\n}\n\ncomment += `<details><summary>View findings</summary>\\n\\n`;\ncomment += `\\`\\`\\`json\\n${JSON.stringify(findings.slice(0, 10), null, 2)}\\n\\`\\`\\`\\n`;\ncomment += `</details>\\n\\n`;\ncomment += `*Powered by Hypatia Neurosymbolic CI/CD Intelligence*`;\n\ngithub.rest.issues.createComment({\n  owner: context.repo.owner,\n  repo: context.repo.repo,\n  issue_number: context.issue.number,\n  body: comment\n});"

.machine_readable/6a2/AGENTIC.a2ml

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# AGENTIC.a2ml — AI agent constraints and capabilities
+# Defines what AI agents can and cannot do in this repository.
+
+[metadata]
+version = "0.1.0"
+last-updated = "2026-04-11"
+
+[agent-permissions]
+can-edit-source = true
+can-edit-tests = true
+can-edit-docs = true
+can-edit-config = true
+can-create-files = true
+
+[agent-constraints]
+# What AI agents must NOT do:
+# - Never use banned language patterns (believe_me, unsafeCoerce, etc.)
+# - Never commit secrets or credentials
+# - Never use banned languages (TypeScript, Python, Go, etc.)
+# - Never place state files in repository root (must be in .machine_readable/)
+# - Never use AGPL license (use MPL-2.0)
+
+[maintenance-integrity]
+fail-closed = true
+require-evidence-per-step = true
+allow-silent-skip = false
+require-rerun-after-fix = true
+release-claim-requires-hard-pass = true
+
+# ============================================================================
+# METHODOLOGY (ADR-002)
+# ============================================================================
+# Detailed methodology configuration lives in:
+#   .machine_readable/bot_directives/methodology.a2ml
+#   .machine_readable/bot_directives/coverage.a2ml
+#   .machine_readable/bot_directives/debt.a2ml
+#
+# AGENTIC.a2ml declares WHAT agents can do (permissions, gating).
+# bot_directives/ declares HOW agents should work (methodology).
+
+[methodology]
+instructions-dir = ".machine_readable/bot_directives/"
+default-mode = "hybrid"
+
+[automation-hooks]
+# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml, then bot_directives/
+# on-exit: Update STATE.a2ml, coverage.a2ml, and debt.a2ml with session outcomes
+# on-commit: Run just validate-rsr

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MPL-2.0
+# ECOSYSTEM.a2ml — Ecosystem position
+# Converted from ECOSYSTEM.scm on 2026-04-14
+
+[metadata]
+project = "pseudoscript"
+ecosystem = "hyperpolymath"
+
+[position]
+type = "programming-language"
+purpose = "Pseudocode-syntax AffineScript. Write code that looks like pseudocode. Get affine resource guarantees and typed WASM out."
+
+[pipeline]
+position = "co-product"
+chain = "katagoria → typell → typed-wasm → PanLL"
+notes = "PseudoScript compiles to typed WasmGC. TypeLL grounds its type system. typed-wasm provides the shared binary layout and ABI conventions."
+coordination = "nextgen-typing"
+
+[related-projects]
+projects = [
+  { name = "typell", relationship = "type-theory-foundation", notes = "TypeLL's open-ended progressive framework grounds PseudoScript's type system. typell-pseudoscript bridge crate." },
+  { name = "typed-wasm", relationship = "aggregate-library", notes = "Shared binary layout conventions for WasmGC cross-language calls. PseudoScript Option[T]/Result[T,E]/String have agreed layouts here." },
+  { name = "nextgen-typing", relationship = "coordination-parent", notes = "Coordination monorepo for the type theory pipeline. Canonical architecture doc." },
+  { name = "affinescript", relationship = "foundation", notes = "PseudoScript is a syntactic face of AffineScript." },
+  { name = "rattlescript", relationship = "sibling", notes = "Both are syntactic faces of AffineScript." },
+  { name = "ephapax", relationship = "sibling-wasm-target", notes = "Both compile to typed WasmGC. Independent designs; converge at binary level via typed-wasm." },
+  { name = "katagoria", relationship = "research-upstream", notes = "Type theory research origination. Future PseudoScript type system extensions may originate there." },
+  { name = "panll", relationship = "consumer", notes = "PseudoScript is one of PanLL's development language targets." },
+]

.machine_readable/6a2/META.a2ml

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# META.a2ml — Project meta-level information
+# Architecture decisions, design rationale, governance.
+
+[metadata]
+version = "0.1.0"
+last-updated = "2026-04-11"
+
+[project-info]
+type = "library"  # TODO: update type (library|binary|service|website|monorepo)  # library | binary | monorepo | service | website
+languages = []             # e.g. ["rust", "zig", "idris2"]
+license = "MPL-2.0"
+author = "Jonathan D.A. Jewell (hyperpolymath)"
+
+[architecture-decisions]
+# ADR format: status = proposed | accepted | deprecated | superseded | rejected
+# - { id = "ADR-001", title = "Use Zig for FFI", status = "accepted", date = "2026-02-14" }
+
+[development-practices]
+build-tool = "just"
+container-runtime = "podman"
+ci-platform = "github-actions"
+package-manager = "guix"  # guix | nix | cargo | mix
+
+[maintenance-axes]
+scoping-first = true
+execution-order = "axis-1 > axis-2 > axis-3"
+axis-1 = "must > intend > like"
+axis-2 = "corrective > adaptive > perfective"
+axis-3 = "systems > compliance > effects"
+
+[scoping]
+sources = "README, roadmap, status docs, maintenance checklist, CI/security docs"
+marker-scan = "TODO/FIXME/XXX/HACK/STUB/PARTIAL"
+idris-unsound-scan = "believe_me/assert_total"
+
+[axis-2-maintenance-rules]
+corrective-first = true
+adaptive-second = true
+adaptive-focus = "scope-change reconciliation, stale-reference removal, obsolete-work culling"
+perfective-third = true
+perfective-source = "axis-1 honest state after corrective/adaptive updates"
+
+[axis-3-audit-rules]
+audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"
+compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"
+drift-risk-example = "single exception broadening into policy violation (e.g. ReScript->TypeScript spread)"
+effects-evidence = "benchmark execution/results and maintainer status dialogue/review"
+
+[design-rationale]
+# Key design decisions and their reasoning

.machine_readable/6a2/NEUROSYM.a2ml

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# Configuration for Hypatia scanning and symbolic reasoning.
+
+[metadata]
+version = "0.1.0"
+last-updated = "2026-04-11"
+
+[hypatia-config]
+scan-enabled = true
+scan-depth = "standard"  # quick | standard | deep
+report-format = "logtalk"
+
+[symbolic-rules]
+# Custom symbolic rules for this project
+# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+
+[neural-config]
+# Neural pattern detection settings
+# confidence-threshold = 0.85
+# model = "hypatia-v2"