Add reference system status and branch protection audit

fraware · fraware · commit 12dd181aa0c8 · 2026-05-28T10:05:36.000-07:00
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -14,3 +14,11 @@ If this PR touches `conicshield/core/moreau*`, `conicshield/parity/`, `benchmark
 - [ ] **Required (Policy B — repository law):** vendor attestation — green [`vendor-ci-moreau`](https://github.com/fraware/conicshield/actions/workflows/solver-ci.yml) run URL, `workflow_dispatch` link, or `make test-vendor-moreau` log excerpt. **Merge blocked without this.**
 - [ ] Reviewer checklist completed: [`docs/REVIEWER_MERGE_CHECKLIST.md`](docs/REVIEWER_MERGE_CHECKLIST.md)
 - [ ] If published bundles changed: `python scripts/refresh_published_run_index.py` was run and committed
+
+## Host-realistic refresh triggers
+
+If this PR changes `third_party/inter-sim-rl/REVISION`, export scripts, transition-bank generation, or release/governance logic:
+
+- [ ] [`HOST_REALISTIC_CADENCE_POLICY.md`](docs/HOST_REALISTIC_CADENCE_POLICY.md) immediate refresh completed or scheduled
+- [ ] `EXPORT_PROVENANCE.json` / [`REFERENCE_AUTHORITY_LOG.md`](docs/REFERENCE_AUTHORITY_LOG.md) updated
+- [ ] `python scripts/generate_reference_system_status.py` committed
diff --git a/.github/workflows/branch-protection-audit.yml b/.github/workflows/branch-protection-audit.yml
@@ -0,0 +1,25 @@
+name: branch-protection-audit
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 9 * * 1"
+
+permissions:
+  administration: read
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Compare main protection to expected spec
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python scripts/verify_expected_branch_protection.py
+          python scripts/audit_branch_protection_api.py --warn-only
+      - name: Record audit note
+        run: |
+          echo "Attach Settings screenshot to docs/BRANCH_PROTECTION_RECORD.md when protection changes."
diff --git a/.github/workflows/host-realistic-refresh-cadence.yml b/.github/workflows/host-realistic-refresh-cadence.yml
@@ -49,7 +49,10 @@ jobs:
             --notes "Scheduled CI: capture + upstream export; licensed host must run host-realistic-refresh-cycle for bundle publish"
       - name: Cadence staleness check
         run: python scripts/check_reference_refresh_cadence.py --max-days 35
+      - name: Inter-sim REVISION vs provenance
+        run: python scripts/check_inter_sim_revision_cadence.py
+        continue-on-error: true
       - name: Reminder — full cycle on licensed host
         run: |
-          echo "Next: make host-realistic-refresh-cycle --record-refresh --trigger calendar-cadence on licensed WSL"
+          echo "Next: make host-realistic-refresh-cycle-licensed"
           echo "See docs/HOST_REALISTIC_CADENCE_POLICY.md"
diff --git a/.github/workflows/reference-authority.yml b/.github/workflows/reference-authority.yml
@@ -32,6 +32,10 @@ jobs:
         run: python scripts/check_reference_refresh_cadence.py --max-days 35
       - name: Flagship refresh trigger paths
         run: python scripts/check_flagship_refresh_triggers.py --base-ref ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
+      - name: Reference system status artifact
+        run: |
+          python scripts/generate_reference_system_status.py
+          python scripts/generate_reference_system_status.py --check
       - name: verify-reference-system
         run: make verify-reference-system
       - name: Published bundle file profile (all tiers)
diff --git a/.github/workflows/solver-ci.yml b/.github/workflows/solver-ci.yml
@@ -8,6 +8,8 @@ name: vendor-ci-moreau
 
 on:
   workflow_dispatch:
+  schedule:
+    - cron: "0 8 2 * *"
   pull_request:
     paths:
       - "conicshield/core/moreau*.py"
diff --git a/Makefile b/Makefile
@@ -23,7 +23,7 @@ else
   PYTHON ?= python
 endif
 
-.PHONY: test test-reference test-slow test-solver test-vendor-moreau smoke-solver smoke-check env-check reference-correctness perf-benchmark diff-check trust-dashboard parity-native-licensed artifact-validation-report parity-report audit dashboard validate-fixture lint typecheck format format-check cov cov-gates compile-deps verify-extended bootstrap-moreau upgrade-host-realistic-vendor host-realistic-rehearsal export-upstream-rehearsal batch-solve-report check-batch-acceptance check-batch-throughput-advisory validate-published-bundle-profile sync-community-metadata check-reference-refresh-cadence verify-branch-protection-expectations verify-reference-system reference-authority-check reference-authority-snapshot capture-inter-sim-graph refresh-live-upstream-export refresh-live-upstream-export-live host-realistic-refresh-cycle host-realistic-refresh-cycle-licensed host-realistic-refresh-milestone sync-published-readmes
+.PHONY: test test-reference test-slow test-solver test-vendor-moreau smoke-solver smoke-check env-check reference-correctness perf-benchmark diff-check trust-dashboard parity-native-licensed artifact-validation-report parity-report audit dashboard validate-fixture lint typecheck format format-check cov cov-gates compile-deps verify-extended bootstrap-moreau upgrade-host-realistic-vendor host-realistic-rehearsal export-upstream-rehearsal batch-solve-report check-batch-acceptance check-batch-throughput-advisory validate-published-bundle-profile sync-community-metadata check-reference-refresh-cadence verify-branch-protection-expectations verify-reference-system reference-authority-check reference-authority-snapshot reference-system-status reference-system-status-check capture-inter-sim-graph refresh-live-upstream-export refresh-live-upstream-export-live host-realistic-refresh-cycle host-realistic-refresh-cycle-licensed host-realistic-refresh-milestone sync-published-readmes
 
 test:
 	$(PYTHON) -m pytest -q
@@ -98,6 +98,12 @@ upgrade-host-realistic-vendor:
 reference-authority-check:
 	$(PYTHON) scripts/reference_authority_check.py
 
+reference-system-status:
+	$(PYTHON) scripts/generate_reference_system_status.py
+
+reference-system-status-check:
+	$(PYTHON) scripts/generate_reference_system_status.py --check
+
 reference-authority-snapshot:
 	$(PYTHON) scripts/generate_reference_authority_snapshot.py
 
@@ -123,7 +129,7 @@ sync-community-metadata:
 check-reference-refresh-cadence:
 	$(PYTHON) scripts/check_reference_refresh_cadence.py --max-days 35
 
-verify-reference-system: reference-authority-check validate-published-bundle-profile sync-community-metadata
+verify-reference-system: reference-authority-check reference-system-status-check validate-published-bundle-profile sync-community-metadata
 	$(PYTHON) -m pytest \
 		tests/governance/test_published_run_index.py \
 		tests/governance/test_host_realistic_publish_evidence.py \
@@ -138,6 +144,7 @@ verify-reference-system: reference-authority-check validate-published-bundle-pro
 		tests/governance/test_community_metadata.py \
 		tests/governance/test_reference_refresh_cadence.py \
 		tests/governance/test_record_reference_refresh.py \
+		tests/governance/test_reference_system_status.py \
 		tests/governance/test_run_host_realistic_publish.py \
 		tests/governance/test_host_realistic_refresh_cycle.py \
 		tests/governance/test_batch_solve_report.py \
diff --git a/benchmarks/external_evidence/EXPORT_PROVENANCE.json b/benchmarks/external_evidence/EXPORT_PROVENANCE.json
@@ -43,5 +43,6 @@
       "notes": "host-realistic-refresh-cycle host-realistic-20260525"
     }
   ],
-  "last_flagship_refresh_at_utc": "2026-05-28T17:00:56Z"
+  "last_flagship_refresh_at_utc": "2026-05-28T17:00:56Z",
+  "inter_sim_revision_sha": "f1f04ee11d064262f5ee2810abfcb01715260182"
 }
diff --git a/benchmarks/reports/README.md b/benchmarks/reports/README.md
@@ -5,6 +5,7 @@ Optional JSON reports that illustrate public benchmark evidence shapes. They are
 | File | Purpose |
 |------|---------|
 | [`reference_authority_snapshot.json`](reference_authority_snapshot.json) | Committed flagship release alignment (`current_run_id`, gates, provenance); CI `--check` via `reference_authority_check` |
+| [`reference_system_status.json`](reference_system_status.json) | Auditor summary: cadence, batch_story, refresh counts, claim boundaries |
 | [`batch_solve_report.example.json`](batch_solve_report.example.json) | v2 schema: comparisons + `batch_story` (`viability_only` / `throughput_win`) |
 
 Regenerate snapshot after release or flagship bundle changes:
diff --git a/benchmarks/reports/reference_system_status.json b/benchmarks/reports/reference_system_status.json
@@ -0,0 +1,34 @@
+{
+  "schema_version": "conicshield_reference_system_status/v1",
+  "generated_at_utc": "2026-05-28T17:05:22Z",
+  "flagship_run_id": "host-realistic-20260525",
+  "family_id": "conicshield-transition-bank-v1",
+  "reference_authority_aligned": true,
+  "export_kind": "live_upstream_dump",
+  "graph_shape": "host_realistic_fork",
+  "last_flagship_refresh_at_utc": "2026-05-28T17:00:56Z",
+  "refresh_count": 4,
+  "full_cycle_refresh_count": 1,
+  "cadence_age_days": 0.003079939814814815,
+  "cadence_policy_ok": true,
+  "batch_story": "throughput_win",
+  "inter_sim_revision": "f1f04ee11d064262f5ee2810abfcb01715260182",
+  "expected_required_checks": [
+    "quality",
+    "conic-trusted-shape",
+    "governance-audit",
+    "reference-authority",
+    "solver-touch"
+  ],
+  "public_claims": {
+    "batch": "true batch path exists; viability-governed; not universal speedup",
+    "differentiation": "validation only; not public autograd product",
+    "host_realistic_graph": "fork via inter-sim RLEnvironment; not Maps/session navigation"
+  },
+  "docs": [
+    "docs/REFERENCE_SYSTEM.md",
+    "docs/REFERENCE_AUTHORITY.md",
+    "docs/HOST_REALISTIC_CADENCE_POLICY.md",
+    "docs/PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md"
+  ]
+}
diff --git a/docs/BRANCH_PROTECTION_RECORD.md b/docs/BRANCH_PROTECTION_RECORD.md
@@ -38,8 +38,11 @@ make verify-branch-protection-expectations
 ```bash
 python scripts/print_branch_protection_gh_recipe.py   # gh api PUT recipe
 make verify-branch-protection-expectations            # compare after gh auth login
+python scripts/audit_branch_protection_api.py         # GITHUB_TOKEN / gh with admin read
 ```
 
+Weekly GitHub Action: [`.github/workflows/branch-protection-audit.yml`](../.github/workflows/branch-protection-audit.yml) (`workflow_dispatch` + Mondays 09:00 UTC).
+
 ### Screenshot / export (attach in PR or paste link)
 
 <!-- Required: quality, conic-trusted-shape, governance-audit, reference-authority, solver-touch -->
diff --git a/docs/README.md b/docs/README.md
@@ -6,6 +6,7 @@ Start here after the repository [`README.md`](../README.md).
 
 | Document | Use when |
 |----------|----------|
+| [REFERENCE_SYSTEM.md](REFERENCE_SYSTEM.md) | Auditor one-page map + status JSON |
 | [REFERENCE_AUTHORITY.md](REFERENCE_AUTHORITY.md) | Flagship `host-realistic-20260525`, gates, closed loop |
 | [HOST_REALISTIC_CADENCE_POLICY.md](HOST_REALISTIC_CADENCE_POLICY.md) | Monthly + immediate refresh triggers |
 | [REFERENCE_AUTHORITY_LOG.md](REFERENCE_AUTHORITY_LOG.md) | Durable refresh log |
diff --git a/docs/REFERENCE_SYSTEM.md b/docs/REFERENCE_SYSTEM.md
@@ -0,0 +1,53 @@
+# Reference system (v1)
+
+Single-page map for auditors and external consumers. Machine summary: [`benchmarks/reports/reference_system_status.json`](../benchmarks/reports/reference_system_status.json).
+
+## Flagship
+
+| Field | Value |
+|-------|--------|
+| Family | `conicshield-transition-bank-v1` |
+| `current_run_id` | `host-realistic-20260525` |
+| Tier | `vendor_native`, `real_projector` |
+| Export | `live_upstream_dump`, graph `host_realistic_fork` |
+
+## Closed loop
+
+```text
+capture inter-sim graph → upstream export JSON → transition bank → publish → parity → release → index
+```
+
+Licensed command: `make host-realistic-refresh-cycle-licensed`
+
+## Evidence and logs
+
+| Artifact | Role |
+|----------|------|
+| [`REFERENCE_AUTHORITY_LOG.md`](REFERENCE_AUTHORITY_LOG.md) | Human refresh cadence log |
+| [`EXPORT_PROVENANCE.json`](../benchmarks/external_evidence/EXPORT_PROVENANCE.json) | Export + `refresh_history` |
+| [`reference_authority_snapshot.json`](../benchmarks/reports/reference_authority_snapshot.json) | CI alignment gate |
+| [`PUBLISHED_RUN_INDEX.json`](../benchmarks/PUBLISHED_RUN_INDEX.json) | Per-file SHA-256 integrity |
+| [`COMMUNITY_METADATA.json`](../benchmarks/published_runs/host-realistic-20260525/COMMUNITY_METADATA.json) | External scope per bundle |
+
+## CI merge gates
+
+`quality`, `conic-trusted-shape`, `governance-audit`, `reference-authority`, `solver-touch` — see [`CI_MERGE_GATES.md`](CI_MERGE_GATES.md). `vendor-ci-moreau` is Policy B attestation, not a required check.
+
+## Public claim boundaries
+
+| Topic | Allowed | Not allowed |
+|-------|---------|-------------|
+| Batch | True batched solve exists; viability tested | Universal speedup on all scenarios |
+| Differentiation | FD / validation (Layer F) | Production autograd product |
+| Graph | Fork validated via inter-sim API | Full Maps/session navigation graph |
+
+## Verification
+
+```bash
+make verify-reference-system
+make reference-authority-check
+python scripts/generate_reference_system_status.py --check
+python scripts/check_reference_refresh_cadence.py --max-days 35
+```
+
+Branch protection (admin token): `python scripts/audit_branch_protection_api.py`
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -1,6 +1,6 @@
 # Roadmap
 
-Operational commands: [`MAINTAINER_RUNBOOK.md`](MAINTAINER_RUNBOOK.md). Flagship refresh: [`REFERENCE_REFRESH_LOG.md`](REFERENCE_REFRESH_LOG.md).
+Operational commands: [`MAINTAINER_RUNBOOK.md`](MAINTAINER_RUNBOOK.md). System map: [`REFERENCE_SYSTEM.md`](REFERENCE_SYSTEM.md).
 
 ## Current flagship
 
@@ -36,6 +36,9 @@ Auditable in Git; do not re-open without a new milestone:
 | Native batch API | `NATIVE_MOREAU_BATCH`; viability + throughput-advisory policy |
 | CI merge | `reference-authority`, Policy B attestation, bundle profile validator |
 | inter-sim pin | `third_party/inter-sim-rl/REVISION`; capture via `make capture-inter-sim-graph` |
+| Refresh cadence | `HOST_REALISTIC_CADENCE_POLICY.md`, monthly workflows, `REFERENCE_AUTHORITY_LOG.md` |
+| Community bundles | `COMMUNITY_METADATA.json`, `PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md` |
+| System status | `reference_system_status.json`, `generate_reference_system_status.py` |
 
 ## Open backlog
 
diff --git a/scripts/audit_branch_protection_api.py b/scripts/audit_branch_protection_api.py
@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Compare GitHub branch protection on main with expected-branch-protection-main.json."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _github_repo() -> tuple[str, str]:
+    env = os.environ.get("GITHUB_REPOSITORY", "")
+    if "/" in env:
+        owner, repo = env.split("/", 1)
+        return owner, repo
+    return "", ""
+
+
+def _fetch_protection(*, owner: str, repo: str, token: str) -> dict[str, Any] | None:
+    url = f"https://api.github.com/repos/{owner}/{repo}/branches/main/protection"
+    req = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return None
+        body = exc.read().decode("utf-8", errors="replace")
+        print(f"GitHub API {exc.code}: {body}", file=sys.stderr)
+        return None
+
+
+def _required_contexts(protection: dict[str, Any]) -> set[str]:
+    checks = protection.get("required_status_checks") or {}
+    contexts = checks.get("contexts")
+    if isinstance(contexts, list) and contexts:
+        if isinstance(contexts[0], dict):
+            return {str(c.get("context", c.get("name", ""))) for c in contexts}
+        return {str(c) for c in contexts}
+    return set()
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument(
+        "--token",
+        default=os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN"),
+        help="GitHub token with administration:read (Actions GITHUB_TOKEN on same repo).",
+    )
+    p.add_argument(
+        "--warn-only",
+        action="store_true",
+        help="Print mismatches but exit 0 (for fork PRs without admin token).",
+    )
+    args = p.parse_args()
+
+    root = _repo_root()
+    spec = json.loads(
+        (root / ".github" / "expected-branch-protection-main.json").read_text(encoding="utf-8")
+    )
+    expected = set(spec["required_status_checks"])
+    forbidden = set(spec.get("not_required_status_checks") or [])
+
+    if not args.token:
+        print("No GITHUB_TOKEN; skipping remote branch protection audit.", file=sys.stderr)
+        return 0
+
+    owner, repo = _github_repo()
+    if not owner:
+        print("GITHUB_REPOSITORY not set; skipping remote audit.", file=sys.stderr)
+        return 0
+
+    protection = _fetch_protection(owner=owner, repo=repo, token=args.token)
+    if protection is None:
+        print("Branch protection not configured or token lacks access.", file=sys.stderr)
+        return 0 if args.warn_only else 2
+
+    remote = _required_contexts(protection)
+    missing = expected - remote
+    extra = remote - expected
+    wrongly = forbidden & remote
+    errors: list[str] = []
+    if missing:
+        errors.append(f"missing required checks: {sorted(missing)}")
+    if extra:
+        errors.append(f"unexpected required checks: {sorted(extra)}")
+    if wrongly:
+        errors.append(f"forbidden checks enabled: {sorted(wrongly)}")
+
+    print("Remote required contexts:", ", ".join(sorted(remote)) or "(none)")
+    if errors:
+        for e in errors:
+            print(f"ERROR: {e}", file=sys.stderr)
+        return 0 if args.warn_only else 1
+    print("Branch protection matches expected required checks.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/check_inter_sim_revision_cadence.py b/scripts/check_inter_sim_revision_cadence.py
diff --git a/scripts/generate_reference_system_status.py b/scripts/generate_reference_system_status.py
diff --git a/scripts/record_reference_refresh.py b/scripts/record_reference_refresh.py
diff --git a/tests/governance/test_reference_system_status.py b/tests/governance/test_reference_system_status.py

Original file line number	Diff line number	Diff line change
`@@ -43,5 +43,6 @@`
`43`	`43`	`"notes": "host-realistic-refresh-cycle host-realistic-20260525"`
`44`	`44`	`}`
`45`	`45`	`],`
`46`		`- "last_flagship_refresh_at_utc": "2026-05-28T17:00:56Z"`
	`46`	`+ "last_flagship_refresh_at_utc": "2026-05-28T17:00:56Z",`
	`47`	`+ "inter_sim_revision_sha": "f1f04ee11d064262f5ee2810abfcb01715260182"`
`47`	`48`	`}`