feat: make pons a working tool — CLI, honest messages, non-vacuous e2e, live CI

.github/dependabot.yml

@@ -13,6 +13,7 @@ updates:
       actions:
         patterns:
           - "*"
+    open-pull-requests-limit: 2
 
   # Rust/Cargo
   - package-ecosystem: "cargo"

.github/rulesets/Immutable-Tags.json

@@ -0,0 +1,18 @@
+{
+  "name": "Immutable-Tags",
+  "target": "tag",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["~ALL"],
+      "exclude": []
+    }
+  },
+  "bypass_actors": [],
+  "rules": [
+    {"type": "deletion"},
+    {"type": "non_fast_forward"},
+    {"type": "update"},
+    {"type": "required_signatures"}
+  ]
+}

.github/rulesets/Optimus-Branch.json

@@ -0,0 +1,34 @@
+{
+  "name": "Optimus-Branch",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": ["~DEFAULT_BRANCH"],
+      "exclude": []
+    }
+  },
+  "bypass_actors": [],
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_signatures"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 2,
+        "dismiss_stale_reviews_on_push": true,
+        "require_code_owner_review": true,
+        "require_last_push_approval": true,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": ["squash"]
+      }
+    }
+  ]
+}

.github/workflows/codeql.yml

@@ -16,7 +16,7 @@ permissions:
 
 jobs:
   analyze:
-    name: CodeQL Analysis
+    name: CodeQL Analysis (${{ matrix.language }})
     runs-on: ubuntu-latest
     permissions:
       actions: read
@@ -26,20 +26,33 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # `actions` scans the workflows themselves.
           - language: actions
             build-mode: none
+          # `rust` is the point of this repository. It was never scanned before:
+          # the matrix listed `actions` only, so CodeQL had never once opened
+          # crates/. Rust is public preview from CodeQL 2.22.1; the bundle
+          # carried by codeql-action v4.38.1 is newer, so no experimental
+          # feature flag is needed. build-mode is deliberately omitted — the
+          # upstream Rust check (pr-checks/checks/rust.yml) passes only
+          # `languages: rust`, and an empty input reads as unset.
+          - language: rust
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      # Pinned to the COMMIT this tag dereferences to, not the tag object's own
+      # sha. The previous pin (29b1f65c…) resolved to nothing at all — GitHub
+      # returns 422 for it — which is why every CodeQL run died.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@29b1f65c1f735799893313399435a59f54045865 # v3
+        uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
 
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@29b1f65c1f735799893313399435a59f54045865 # v3
-
+      # No Autobuild step: both matrix entries are buildless. Autobuild under
+      # build-mode `none` is a no-op, and upstream's Rust check omits it.
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@29b1f65c1f735799893313399435a59f54045865 # v3
+        uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/main-estate-audit.yml

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: MPL-2.0
 name: Central Estate CI/CD Audit
 
 on:
@@ -7,6 +8,21 @@ on:
     branches: [ "main" ]
   workflow_call:
 
+permissions:
+  contents: read
+
 jobs:
+  # Was pinned to @feat/cicd-workflow-call, a branch that no longer exists on
+  # cicd-suite. An unresolvable ref is not a failing job — the run dies at
+  # startup with jobs=0, so this audit has been reporting nothing at all.
+  #
+  # Repointed at a full commit SHA on cicd-suite main. That reusable workflow
+  # invokes all 26 estate gates from hyperpolymath/cicd-suite/actions/*, which
+  # is the canonical copy: vendoring those composites into this repo would fork
+  # a snapshot that is already stale (cicd-suite has since replaced
+  # zig-hexadeca-check with zig-unified-api-adapter-check).
+  #
+  # The SHA below is cicd-suite main as of 2026-09-21 and is the head of a
+  # green run of that workflow. Re-pin when the gate set changes.
   call-estate-audit:
-    uses: hyperpolymath/cicd-suite/.github/workflows/main-estate-audit.yml@feat/cicd-workflow-call
+    uses: hyperpolymath/cicd-suite/.github/workflows/main-estate-audit.yml@3b4afafa969103279ee580572626a175ec9dc0d0

.github/workflows/rust-ci.yml

@@ -26,3 +26,14 @@
           RUSTFLAGS: "-D warnings"
       - name: test
         run: cargo test --workspace
+      - name: build
+        run: cargo build --release
+      - name: e2e
+        run: bash tests/e2e.sh
+      - name: e2e non-vacuity (stub binary must fail the suite)
+        run: |
+          if PONS_BIN=/bin/true bash tests/e2e.sh >/dev/null 2>&1; then
+            echo "::error::e2e suite passes against a stub binary — it is vacuous"
+            exit 1
+          fi
+          echo "e2e suite correctly rejects a stub binary"

ARCHITECTURE.adoc

@@ -35,22 +35,23 @@ semantics
 ....
 .
 ├── docs/                  # Architecture Decision Records (ADRs) and planning
-│   └── adr/               # ADR-0001 through ADR-0004
+│   └── adr/               # ADR-0001 through ADR-0005
 │   ├── 0001-substrate.adoc
 │   ├── 0002-t1-language-and-cfg.adoc
 │   ├── 0003-protocol-spec-and-typestate.adoc
-│   └── 0004-companion-to-panic-attack.adoc
+│   ├── 0004-companion-to-panic-attack.adoc
+│   └── 0005-cli-exit-code-contract.adoc
 ├── docs/PLAN.adoc          # Milestone-by-milestone implementation plan
 ├── docs/pons-kickoff.adoc  # Mission, species, decidability wall, evidence tiers
 ├── .machine_readable/      # RSR compliance infrastructure
 │   ├── contractiles/      # Machine-readable contracts
 │   ├── descriptiles/      # Machine-readable descriptions
 │   └── scripts/           # Verification and lifecycle scripts
-├── tests/                 # Test suites (planning phase)
+├── tests/                 # Shell test suites (e2e runs in CI)
 │   ├── e2e.sh             # End-to-end validation of artefacts
 │   ├── aspect_tests.sh    # Cross-cutting architectural invariants
 │   └── workflows/         # CI workflow validation
-├── benches/               # Benchmarks (planning phase)
+├── benches/               # Benchmarks (not yet wired into CI)
 │   └── pons_bench.sh      # Performance benchmarks
 ├── LICENSE                # MPL-2.0 for source code
 ├── LICENSE.adoc           # Licence documentation
@@ -65,38 +66,50 @@ semantics
 
 === Component Architecture
 
-==== Planned Implementation (Post-Planning Phase)
-
-Once implementation begins (post-v0.1.0 planning), the architecture will
-include:
+Components marked *built* exist on `main` and are exercised by the test suite.
+Components marked *planned* carry the milestone that delivers them; see
+`docs/PLAN.adoc`.
 
 [arabic]
-. *Parser Layer*
-* tree-sitter grammars for Python, JavaScript/TypeScript, Rust
-* Grammar version pinning via workspace dependencies
-* Exact grammar crate versions pinned (PLAN Appendix F)
-. *CFG + Dataflow Engine*
-* Per-language CFG extraction (Python first, per ADR-0002)
-* Reaching definitions for `+read-before-init+`
-* Liveness analysis for `+dead-store+`
-* Typestate semantics (ADR-0003)
-. *Rule Engine*
-* Evidence classes: PROTOCOL, DATAFLOW, HEURISTIC, SPECULATIVE
-* Negative corpus for each rule (falsification testing)
-* Automatic demotion/removal of rules firing on negative corpus
+. *Parser Layer* — *built*
+* tree-sitter grammars for Python, JavaScript, TypeScript, TSX and Rust
+* Grammar crate versions pinned exactly (PLAN Appendix F)
+* `.jsx` maps to the JavaScript grammar; `.tsx` to the TSX grammar
+. *CFG + Dataflow Engine* — *planned (M4, ADR-0002)*
+* Per-language CFG extraction, Python first
+* Forward may-be-unbound analysis for `+read-before-init+`
+* Backward live-variables analysis for `+dead-store+`
+* The OPAQUE hatch: no T1 finding is reported for a function that can
+  rewrite its own scope (`exec`, `eval`, `locals`, wildcard import)
+. *Typestate Engine* — *planned (M5, ADR-0003)*
+* Forward per-path may-analysis over the CFG, one instance key at a time
+. *Rule Engine* — *built (T0 catalogue; higher tiers planned)*
+* Evidence class is fixed by tier and cannot be overridden per finding
+* Negative corpus for every rule (falsification testing)
+* A rule that fires anywhere in its own negative corpus is falsified, and is
+  demoted or removed
 . *Reporter*
-* Evidence class visualization
-* SPECULATIVE findings visually demoted
-* Multiple output formats (JSON, SARIF, human-readable)
+* Human-readable output with SPECULATIVE visually demoted — *built*
+* JSON and SARIF output — *planned (M3)*
 
 === Evidence Classes
 
-The core architectural invariant is the evidence class taxonomy:
-
-* *PROTOCOL*: Findings with mathematical certainty
-* *DATAFLOW*: Findings from dataflow analysis
-* *HEURISTIC*: Pattern-based findings
-* *SPECULATIVE*: Weakest evidence, visually demoted
+The core architectural invariant is the evidence class taxonomy. Evidence class
+is a function of the analysis tier that produced the finding, and is never set
+per finding:
+
+* *PROTOCOL* (T2): the typestate analysis found a path on which the protocol is
+  violated. This is a *may* result over an approximation of the real control
+  flow — it means "a violating path exists in the model", not "this will
+  happen". It is the strongest class pons emits, and it is still not a proof.
+* *DATAFLOW* (T1): supported by an intraprocedural dataflow analysis over a
+  real CFG, within that analysis's disclosed limits.
+* *HEURISTIC* (T0): a syntactic pattern match. No flow analysis stands behind it.
+* *SPECULATIVE* (T3): the underlying question is undecidable or the signal is
+  weak. Always visually demoted, never counted toward a `--fail-on` threshold.
+
+*Never dress a heuristic up as a proof.* No class above claims certainty,
+because no analysis in pons delivers certainty.
 
 Every finding carries its evidence class, and the reporter enforces
 visual distinction between classes, especially demoting SPECULATIVE

EXPLAINME.adoc

@@ -7,9 +7,15 @@
 pons (after the _pons asinorum_ / Euclid I.5, the "bridge of asses") is a lightweight, 
 multi-language static scanner that flags three categories of critical code issues:
 
-* **Dead work** — Code that does nothing, is unreachable, or produces no effect
-* **Self-contradiction** — Inconsistent logic or state that cannot be reconciled
-* **Missing escape hatches** — Error paths that don't properly handle failures
+* **Wasted work** — the program computes something it then discards. Dead
+  stores, a loop whose result is never read, accidental super-linear cost.
+  "Labour for nothing."
+* **Contradiction** — the program asserts two incompatible things at once.
+  Divide by zero asserts `a/0` is defined. Suppress-output-then-prompt asserts
+  both "stay silent" and "speak". An empty-effect loop asserts "this iteration
+  matters" while producing nothing.
+* **Missing escape hatches** — a third, smaller shape: a long operation with no
+  way to interrupt it. Not waste, not contradiction, but a real defect.
 
 == Design Philosophy
 
@@ -24,32 +30,51 @@ pons is the depth companion to link:https://github.com/hyperpolymath/panic-attac
 
 Every finding carries an explicit evidence class:
 
-* `PROTOCOL` — Mathematically certain, based on formal specifications
-* `DATAFLOW` — High confidence, based on concrete dataflow analysis
-* `HEURISTIC` — Moderate confidence, based on pattern matching
-* `SPECULATIVE` — Low confidence, visually demoted in all output formats
+* `PROTOCOL` (T2) — a typestate analysis found a path on which the protocol is
+  violated. A *may* result over an approximation of the real control flow: it
+  says "a violating path exists in the model", not "this will happen". The
+  strongest class pons emits, and still not a proof.
+* `DATAFLOW` (T1) — supported by an intraprocedural dataflow analysis over a
+  real control-flow graph, within that analysis's disclosed limits.
+* `HEURISTIC` (T0) — a syntactic pattern match. No flow analysis stands behind it.
+* `SPECULATIVE` (T3) — the underlying question is undecidable, or the signal is
+  weak. Visually demoted in every output format and never counted toward a
+  `--fail-on` threshold.
+
+Evidence class is fixed by the tier that produced the finding. A rule cannot
+choose its own class, and no class claims certainty — because no analysis in
+pons delivers certainty.
 
 **Key principle:** Never dress a heuristic up as a proof.
 
 == Current Status
 
-*Planning complete; implementation not started.* This repository contains the ratified v0.1.0 plan.
+*Implementation in progress toward v0.1.0.* Milestones M0-M2 are merged: the
+Rust workspace, the scanning engine, five tree-sitter grammars, the eight-rule
+T0 catalogue and the falsifier gate all build, test and run. `pons scan <path>`
+works today.
+
+Milestones M3-M8 remain: JSON and SARIF output, the Python CFG and dataflow
+engine (T1), typestate and protocols (T2), speculative rules (T3), suppression,
+and the v0.1.0 acceptance sweep. Until a tier ships, no finding carries its
+evidence class: every rule on `main` today is T0/`HEURISTIC`.
 
 == Repository Structure
 
-include::docs/structure.adoc[]
+See link:ARCHITECTURE.adoc[ARCHITECTURE.adoc] for the directory layout and the
+component breakdown.
 
 == Quick Start
 
 See link:.github/CONTRIBUTING.md[CONTRIBUTING.md] for development setup.
 
 == License
 
-Code: MPL-2.0-or-later (see LICENSE)
+Code: MPL-2.0 (see LICENSE)
 Docs: CC-BY-SA-4.0
 
 == Contact
 
-* Issues: https://github.com/hyperpolymath/pons/issues
-* Discussions: https://github.com/hyperpolymath/pons/discussions
+* Issues: https://github.com/hyperpolymath/pons-asinorum/issues
+* Discussions: https://github.com/hyperpolymath/pons-asinorum/discussions
 * Email: j.d.a.jewell@open.ac.uk

Justfile

@@ -15,4 +15,19 @@ lint:
 falsify:
     cargo test -p pons-rules --test falsifier
 
-check: fmt lint test
+# End-to-end: builds the binary first, because tests/e2e.sh executes it and
+# deliberately FAILS rather than skips when it is absent.
+e2e:
+    cargo build --release
+    bash tests/e2e.sh
+
+# Proves the e2e suite is not vacuous: against a stub binary it must go red.
+e2e-mutant:
+    #!/usr/bin/env bash
+    if PONS_BIN=/bin/true bash tests/e2e.sh >/dev/null 2>&1; then
+        echo "e2e suite passed against a STUB binary — it is vacuous"; exit 1
+    else
+        echo "e2e suite correctly rejects a stub binary"
+    fi
+
+check: fmt lint test e2e