Add v1 release note, make onboard, and CI lock quick gate

fraware · fraware · commit 4bc89ef038c7 · 2026-05-28T11:46:05.000-07:00
V1_REFERENCE_RELEASE doc, print_v1_status script, reference-authority verify-v1-lock-quick, PR public-claims checkbox.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -5,6 +5,7 @@
 ## Testing
 
 - [ ] Default CI (`quality`, `conic-trusted-shape`, `governance-audit`, `reference-authority`) is green or pending
+- [ ] If `docs/`, `examples/`, or published bundle READMEs changed public claims: cited [`docs/PUBLIC_CLAIMS.md`](docs/PUBLIC_CLAIMS.md) (or related stance doc) and `python scripts/check_public_claim_phrases.py` passes
 
 ## Solver / parity / published runs
 
diff --git a/.github/workflows/reference-authority.yml b/.github/workflows/reference-authority.yml
@@ -40,6 +40,8 @@ jobs:
         run: make verify-reference-system
       - name: Community dataset smoke (API, CLI, flagship example)
         run: make community-verify
+      - name: v1 lock quick (auditor entrypoint)
+        run: make verify-v1-lock-quick
       - name: Published bundle file profile (all tiers)
         run: python scripts/validate_published_bundle_profile.py
       - name: Committed batch acceptance report (viability — required)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Reference system (host-realistic flagship)
 
+### 2026-05-28 — v1 release note, onboard target, and CI lock quick gate
+
+- [`docs/V1_REFERENCE_RELEASE.md`](docs/V1_REFERENCE_RELEASE.md), `make onboard`, `scripts/print_v1_status.py`.
+- `reference-authority` runs `verify-v1-lock-quick`; PR template public-claims checkbox.
+
 ### 2026-05-28 — Community front door and frozen published-runs v1 API
 
 - README **Start here** block; [COMMUNITY_LAYER.md](docs/COMMUNITY_LAYER.md) as default public map.
diff --git a/Makefile b/Makefile
@@ -26,7 +26,7 @@ else
   endif
 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 sync-published-run-readmes sync-published-readmes finalize-community-dataset community-verify check-reference-refresh-cadence check-flagship-full-refresh-cadence verify-v1-lock verify-v1-lock-quick 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
+.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 sync-published-run-readmes sync-published-readmes finalize-community-dataset community-verify check-reference-refresh-cadence check-flagship-full-refresh-cadence verify-v1-lock verify-v1-lock-quick v1-status onboard 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
@@ -129,6 +129,13 @@ verify-v1-lock: verify-reference-system community-verify reference-system-status
 verify-v1-lock-quick:
 	$(PYTHON) scripts/verify_v1_lock.py
 
+v1-status:
+	$(PYTHON) scripts/print_v1_status.py
+
+onboard: community-verify v1-status
+	@echo ""
+	@echo "Community onboarding OK. Next: docs/COMMUNITY_LAYER.md"
+
 sync-community-metadata:
 	$(PYTHON) scripts/sync_community_metadata.py
 
diff --git a/README.md b/README.md
@@ -79,7 +79,7 @@ Refresh: `make host-realistic-refresh-cycle-licensed` — [`docs/HOST_REALISTIC_
 
 **Batch:** governed; viability-tested — not universal speedup ([`docs/SOLVER_PATHS_AND_BATCHING.md`](docs/SOLVER_PATHS_AND_BATCHING.md)). **Differentiation:** validation-only ([`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](docs/DIFFERENTIATION_PUBLIC_STANCE.md)).
 
-Published-run API: [`docs/PUBLISHED_RUNS_API.md`](docs/PUBLISHED_RUNS_API.md) · Claims: [`docs/PUBLIC_CLAIMS.md`](docs/PUBLIC_CLAIMS.md)
+v1 release: [`docs/V1_REFERENCE_RELEASE.md`](docs/V1_REFERENCE_RELEASE.md) · API: [`docs/PUBLISHED_RUNS_API.md`](docs/PUBLISHED_RUNS_API.md) · Claims: [`docs/PUBLIC_CLAIMS.md`](docs/PUBLIC_CLAIMS.md)
 
 ## Installation
 
diff --git a/benchmarks/reports/reference_system_status.json b/benchmarks/reports/reference_system_status.json
@@ -1,6 +1,6 @@
 {
   "schema_version": "conicshield_reference_system_status/v1",
-  "generated_at_utc": "2026-05-28T18:32:31Z",
+  "generated_at_utc": "2026-05-28T18:45:41Z",
   "flagship_run_id": "host-realistic-20260525",
   "family_id": "conicshield-transition-bank-v1",
   "reference_authority_aligned": true,
@@ -10,7 +10,7 @@
   "refresh_count": 4,
   "full_cycle_refresh_count": 1,
   "last_full_refresh_at_utc": "2026-05-28T17:00:56Z",
-  "cadence_age_days": 0.06360137756944444,
+  "cadence_age_days": 0.07274463219907408,
   "cadence_policy_ok": true,
   "full_refresh_cadence_ok": true,
   "batch_story": "throughput_win",
@@ -23,7 +23,8 @@
     "verify_make_target": "community-verify",
     "finalize_script": "scripts/finalize_community_dataset.py",
     "onboarding_doc": "docs/COMMUNITY_LAYER.md",
-    "api_doc": "docs/PUBLISHED_RUNS_API.md"
+    "api_doc": "docs/PUBLISHED_RUNS_API.md",
+    "v1_release_doc": "docs/V1_REFERENCE_RELEASE.md"
   },
   "inter_sim_revision": "f1f04ee11d064262f5ee2810abfcb01715260182",
   "ci_merge_checks": [
diff --git a/docs/COMMUNITY_LAYER.md b/docs/COMMUNITY_LAYER.md
@@ -2,7 +2,11 @@
 
 **Start here** if you are new to the repository. This page is the default map for researchers, integrators, and anyone citing published benchmarks.
 
-Maintainer depth (cadence, governance graph, refresh scripts) lives in [`docs/README.md`](README.md) — not required for consumption.
+v1 release summary: [`V1_REFERENCE_RELEASE.md`](V1_REFERENCE_RELEASE.md). Maintainer depth (cadence, governance graph, refresh scripts) lives in [`docs/README.md`](README.md) — not required for consumption.
+
+```bash
+make onboard   # community-verify + status snapshot (recommended first run)
+```
 
 ## Choose your path (< 10 minutes)
 
diff --git a/docs/README.md b/docs/README.md
@@ -19,6 +19,7 @@ Public claim boundaries: [PUBLIC_CLAIMS.md](PUBLIC_CLAIMS.md). Examples: [exampl
 | Document | Use when |
 |----------|----------|
 | [REFERENCE_SYSTEM.md](REFERENCE_SYSTEM.md) | Auditor one-page map + status JSON |
+| [V1_REFERENCE_RELEASE.md](V1_REFERENCE_RELEASE.md) | v1 public release summary |
 | [V1_LOCK_CHECKLIST.md](V1_LOCK_CHECKLIST.md) | Pre-lock verification (`make verify-v1-lock`) |
 | [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 |
diff --git a/docs/V1_LOCK_CHECKLIST.md b/docs/V1_LOCK_CHECKLIST.md
@@ -40,9 +40,19 @@ Licensed full refresh: `make host-realistic-refresh-cycle-licensed` ([procedure]
 
 After push, confirm green: `quality`, `conic-trusted-shape`, `governance-audit`, `reference-authority`, `solver-touch` (when paths match). See [`CI_MERGE_GATES.md`](CI_MERGE_GATES.md).
 
+## Machine status (committed)
+
+```bash
+python scripts/print_v1_status.py
+python scripts/verify_v1_lock.py --json
+```
+
+Reads [`benchmarks/reports/reference_system_status.json`](../benchmarks/reports/reference_system_status.json). Expect `reference_authority_aligned: true`, `full_refresh_cadence_ok: true`, `cadence_policy_ok: true`.
+
 ## v1 complete when
 
 - [ ] `make verify-v1-lock` passes locally
+- [ ] `make onboard` passes (community smoke + status)
 - [ ] `reference-authority` green on `main`
 - [ ] At least one `live-export-full` refresh with `authority_ok` within 35 days
 
diff --git a/docs/V1_REFERENCE_RELEASE.md b/docs/V1_REFERENCE_RELEASE.md
@@ -0,0 +1,45 @@
+# ConicShield v1 reference release
+
+Public name for the governed **host-realistic flagship** reference system shipped in this repository.
+
+## What v1 is
+
+| Item | Value |
+|------|--------|
+| Family | `conicshield-transition-bank-v1` |
+| Flagship `run_id` | `host-realistic-20260525` |
+| Evidence tier | `vendor_native`, `real_projector` |
+| Export | `live_upstream_dump` (inter-sim fork topology) |
+| Public API | `conicshield.published_runs` v1 (frozen) |
+| Integrity catalog | `benchmarks/PUBLISHED_RUN_INDEX.json` schema v2 |
+
+## What v1 is for
+
+- Reproducible, hash-verified benchmark bundles for external researchers
+- Library integration via reference CVXPY and (with license) native Moreau paths
+- A closed maintainer loop: export → bank → publish → parity → index
+
+## What v1 is not
+
+See [PUBLIC_CLAIMS.md](PUBLIC_CLAIMS.md): no production autograd product, no universal batch speedup claim, no Maps/session navigation graph, no second-family authority.
+
+## How to consume (start here)
+
+1. [COMMUNITY_LAYER.md](COMMUNITY_LAYER.md)
+2. `python examples/verify_published_run_index.py`
+3. [CITING_CONICSHIELD_ARTIFACTS.md](CITING_CONICSHIELD_ARTIFACTS.md)
+
+## How to verify coherence
+
+```bash
+make verify-v1-lock-quick
+python scripts/print_v1_status.py
+```
+
+Machine snapshot: [`benchmarks/reports/reference_system_status.json`](../benchmarks/reports/reference_system_status.json).
+
+## Maintainer operations
+
+- Refresh: [HOST_REALISTIC_REFRESH_PROCEDURE.md](HOST_REALISTIC_REFRESH_PROCEDURE.md)
+- Lock gate: [V1_LOCK_CHECKLIST.md](V1_LOCK_CHECKLIST.md)
+- Strategy: [V2_STRATEGY.md](V2_STRATEGY.md) (Option A active; B/C deferred)
diff --git a/examples/load_flagship_run.py b/examples/load_flagship_run.py
@@ -1,5 +1,12 @@
 #!/usr/bin/env python3
-"""Load flagship bundle via published_runs API (typed, no governance deep-dive)."""
+"""Short published_runs API demo on the flagship bundle.
+
+Audience: researcher needing a minimal API sample (see load_published_runs_api.py for full tour).
+Prerequisites: ``pip install -e .`` from repo root.
+Proves: ``verify_run``, ``get_current_run``, ``load_summary``, ``load_provenance``.
+Does not prove: governance internals or scientific claims beyond bundle metadata.
+Expected: integrity OK line; path, tier, arm/episode counts.
+"""
 
 from __future__ import annotations
 
diff --git a/examples/native_compiled_projection.py b/examples/native_compiled_projection.py
@@ -1,13 +1,20 @@
 #!/usr/bin/env python3
-"""One native compiled sequential projection (requires vendor Moreau)."""
+"""One native compiled sequential projection (requires vendor Moreau).
 
-from __future__ import annotations
+Audience: integrator evaluating sequential native compiled path.
+Prerequisites: vendor Moreau installed and licensed; ``pip install -e ".[solver]"`` or project .venv.
+Proves: ``create_projector(..., Backend.NATIVE_MOREAU)`` returns a corrected action vector.
+Does not prove: batched throughput wins or parity against reference without separate parity run.
+Expected: prints proposed/corrected vectors, or exits 0 with Skip if Moreau unavailable.
+"""
 
-import numpy as np
+from __future__ import annotations
 
 import sys
 from pathlib import Path
 
+import numpy as np
+
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import minimal_spec  # noqa: E402
 
@@ -37,7 +44,8 @@ def main() -> int:
             print("Skip: Moreau license not available.", exc)
             return 0
         raise
-    print("corrected_action:", result.corrected_action)
+    print("proposed:", proposed)
+    print("corrected:", result)
     return 0
 
 
diff --git a/scripts/generate_reference_system_status.py b/scripts/generate_reference_system_status.py
@@ -98,6 +98,7 @@ def build_reference_system_status(*, repo_root: Path) -> dict[str, Any]:
             "finalize_script": "scripts/finalize_community_dataset.py",
             "onboarding_doc": "docs/COMMUNITY_LAYER.md",
             "api_doc": "docs/PUBLISHED_RUNS_API.md",
+            "v1_release_doc": "docs/V1_REFERENCE_RELEASE.md",
         },
         "inter_sim_revision": _inter_sim_revision(root),
         "ci_merge_checks": [
diff --git a/scripts/print_v1_status.py b/scripts/print_v1_status.py
@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Print human-readable v1 reference system status from committed artifacts."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def main() -> int:
+    root = _repo_root()
+    path = root / "benchmarks" / "reports" / "reference_system_status.json"
+    if not path.is_file():
+        print(f"Missing {path}; run: python scripts/generate_reference_system_status.py", file=sys.stderr)
+        return 2
+    status = json.loads(path.read_text(encoding="utf-8"))
+    community = status.get("community_dataset") or {}
+
+    print("ConicShield v1 reference system status")
+    print("=" * 40)
+    print("flagship_run_id:", status.get("flagship_run_id"))
+    print("family_id:", status.get("family_id"))
+    print("reference_authority_aligned:", status.get("reference_authority_aligned"))
+    print("export_kind:", status.get("export_kind"))
+    print("graph_shape:", status.get("graph_shape"))
+    print("cadence_policy_ok:", status.get("cadence_policy_ok"))
+    print("full_refresh_cadence_ok:", status.get("full_refresh_cadence_ok"))
+    print("batch_public_narrative:", status.get("batch_public_narrative"))
+    print("published_run_count:", community.get("published_run_count"))
+    print("onboarding:", community.get("onboarding_doc"))
+    print("api_doc:", community.get("api_doc"))
+    print()
+    print("Public entry:", "docs/COMMUNITY_LAYER.md")
+    print("Release note:", "docs/V1_REFERENCE_RELEASE.md")
+    print("Auditor checks: make verify-v1-lock-quick")
+    print("Full lock gate: make verify-v1-lock")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/governance/test_reference_system_status.py b/tests/governance/test_reference_system_status.py
@@ -30,6 +30,7 @@ def test_reference_system_status_builds() -> None:
     assert community.get("api_module") == "conicshield.published_runs"
     assert community.get("published_run_count", 0) >= 1
     assert community.get("onboarding_doc") == "docs/COMMUNITY_LAYER.md"
+    assert community.get("v1_release_doc") == "docs/V1_REFERENCE_RELEASE.md"
     assert "reference-authority" in (payload.get("ci_merge_checks") or [])
 
 
diff --git a/tests/scripts/test_print_v1_status.py b/tests/scripts/test_print_v1_status.py
@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_print_v1_status_exits_zero() -> None:
+    root = Path(__file__).resolve().parents[2]
+    proc = subprocess.run(
+        [sys.executable, str(root / "scripts" / "print_v1_status.py")],
+        cwd=str(root),
+        capture_output=True,
+        text=True,
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert "host-realistic-20260525" in proc.stdout
+    assert "COMMUNITY_LAYER" in proc.stdout
