tools: math artifact hypergraph companion (main#579) — organization only, NOT A RESULT

.github/workflows/math-hypergraph.yml

@@ -0,0 +1,70 @@
+name: Math hypergraph (organization only)
+'on':
+  pull_request:
+    paths:
+      - 'tools/hypergraph/**'
+      - '.github/workflows/math-hypergraph.yml'
+      - 'portable/**'
+      - 'src/**'
+      - 'docs/**'
+  push:
+    branches: [main]
+    paths:
+      - 'tools/hypergraph/**'
+      - '.github/workflows/math-hypergraph.yml'
+      - 'portable/**'
+      - 'src/**'
+      - 'docs/**'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  hypergraph:
+    name: math-hypergraph
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # Read-only checkouts of the other public repos (no secrets). If one is private
+      # or unavailable the step is skipped and the builder prints "skip <repo>".
+      - name: Checkout main (public, read-only)
+        continue-on-error: true
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          repository: d6g8k5htny-coder/main
+          path: external/main
+          persist-credentials: false
+      - name: Checkout Math- (public, read-only)
+        continue-on-error: true
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          repository: d6g8k5htny-coder/Math-
+          path: external/Math-
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: tools/hypergraph/requirements.txt
+      - name: Install pinned requirements
+        run: python -m pip install -r tools/hypergraph/requirements.txt
+      - name: Tests
+        run: python -m pytest -q -p no:cacheprovider tools/hypergraph
+      - name: validate (query- artifacts)
+        run: python -m tools.hypergraph.math_hypergraph validate
+      - name: gaps
+        run: python -m tools.hypergraph.math_hypergraph gaps
+      - name: Build all-repo bundle with PNG
+        run: |
+          set -euo pipefail
+          python -m tools.hypergraph.math_hypergraph repos
+          python -m tools.hypergraph.math_hypergraph export "$RUNNER_TEMP/hypergraph" --repos all --png
+          ls -l "$RUNNER_TEMP/hypergraph"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
+        with:
+          name: math-hypergraph
+          path: ${{ runner.temp }}/hypergraph/
+          if-no-files-found: error
+          retention-days: 14

tools/hypergraph/README.md

@@ -0,0 +1,23 @@
+# tools/hypergraph (query- companion) — organization only, NOT A RESULT
+
+credit 0 · OBL OPEN · no flags. Same pinned package as d6g8k5htny-coder/main `tools/hypergraph` (main#579);
+this copy scans **query-** (checkout `.`) and, when present, read-only checkouts of main, Math- under `external/`.
+Vertex keys are `<repo>:<type>:<id>`. Absent/private repos are skipped with a message.
+
+## Run locally (Python 3.11/3.12)
+```
+pip install -r tools/hypergraph/requirements.txt
+pytest tools/hypergraph
+python -m tools.hypergraph.math_hypergraph validate
+python -m tools.hypergraph.math_hypergraph gaps
+python -m tools.hypergraph.math_hypergraph repos
+python -m tools.hypergraph.math_hypergraph export /tmp/hg-bundle --repos all --png
+# optional: git clone --depth 1 https://github.com/d6g8k5htny-coder/<repo> external/<repo>
+```
+Edit `inputs.json` to change which globs count as source / review / formal / impl / spec / test.
+
+## GitHub Actions — `.github/workflows/math-hypergraph.yml`
+Runs on PRs/pushes to `main` touching the tool or query-'s artifacts, and via workflow_dispatch. Checks out the other public
+repos read-only, installs pins on Python 3.12, runs pytest, `validate`, `gaps`, and uploads the all-repo export
+(JSON, PNG, README, MANIFEST) as the `math-hypergraph` artifact. `contents: read`, no secrets, 10-minute timeout, not required.
+The committed-output `build --check` gate lives in main, which owns the ledger.

tools/hypergraph/inputs.json

@@ -0,0 +1,69 @@
+{
+ "note": "Inputs for tools/hypergraph. Paths are relative to this repo's root. Repos whose checkout is absent are skipped with a message. Organization only: credit 0, OBL OPEN. Companion copy in query-: this repo is checkout '.', others are optional read-only checkouts under external/.",
+ "home": "main",
+ "default_repos": [
+  "query-"
+ ],
+ "repos": {
+  "main": {
+   "github": "d6g8k5htny-coder/main",
+   "root_dirs": [".github", "architecture", "audits", "data", "docs", "experiments", "formal", "governance", "history", "incoming", "interface", "records", "reviews", "tests", "tools"],
+   "checkout": "external/main",
+   "ledger": "external/main/data/hypergraph/math_coverage_ledger_20261023.md",
+   "graph": "external/main/docs/site/dependency-source/GRAPH.json",
+   "report": "external/main/data/hypergraph/graph_binding_report_20261023.json"
+  },
+  "Math-": {
+   "github": "d6g8k5htny-coder/Math-",
+   "root_dirs": [".github", "certificates", "claims", "coefficients", "companions", "docs", "formal", "frontiers", "imports", "incoming", "repairs", "reviews", "specifications", "tests", "tools"],
+   "checkout": "external/Math-",
+   "unit_depth": 2,
+   "artifacts_order": "first matching role wins: specific formal/impl globs precede the reviews/* catch-all",
+   "artifacts": {
+    "formal": [
+     "*.lean"
+    ],
+    "impl": [
+     "*.py"
+    ],
+    "review": [
+     "*REVIEW*.md",
+     "reviews/*"
+    ],
+    "source": [
+     "*PROOF*.md",
+     "*LEMMA*.md",
+     "*lemma*.md",
+     "*.tex",
+     "PROOF_INDEX.md"
+    ]
+   }
+  },
+  "query-": {
+   "github": "d6g8k5htny-coder/query-",
+   "root_dirs": [".github", "docs", "portable", "scripts", "src", "tests"],
+   "checkout": ".",
+   "unit_depth": 1,
+   "artifacts": {
+    "test": [
+     "tests/*.py",
+     "test_*.py"
+    ],
+    "spec": [
+     "portable/*.json",
+     "portable/history/*.json"
+    ],
+    "source": [
+     "portable/*.md",
+     "docs/*.md"
+    ],
+    "impl": [
+     "src/*.py",
+     "src/*/*.py",
+     "scripts/*.py",
+     "*.py"
+    ]
+   }
+  }
+ }
+}