Skip to content

Commit 2418e5a

Browse files
xiaojiou176xiaojiou176
committed
fix: align front door proof and local gates
1 parent 40d227a commit 2418e5a

9 files changed

Lines changed: 117 additions & 32 deletions

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,15 @@ If review-first cleanup is the workflow you keep wishing existed, star the repo
243243
Delivery-complete truth for the current snapshot still depends on fresh gate evidence, not on static prose.
244244
Treat `bash tooling/gates/quality_gate.sh` as the delivery-complete receipt for the current snapshot, and treat repository docs as guidance rather than a live platform dashboard.
245245

246+
## Minimal Truth Routes
247+
248+
If you only want the shortest honest map of what is true right now, follow these four routes:
249+
250+
- **Public proof map**: [docs/public_proof.md](docs/public_proof.md)
251+
- **Current release and platform boundary**: [docs/open_source_runbook.md](docs/open_source_runbook.md)
252+
- **Detailed operator route**: [docs/usage.md](docs/usage.md)
253+
- **System wiring and contracts**: [docs/architecture.md](docs/architecture.md)
254+
246255
Public readiness gates:
247256

248257
- `bash tooling/gates/public_readiness_gate.sh repo`

‎contracts/docs/docs_nav_registry.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@ docs:
5151
layer: human-authored
5252
scope: strict
5353
command_smoke: false
54+
- path: docs/public_proof.md
55+
layer: human-authored
56+
scope: strict
57+
command_smoke: false
5458
- path: docs/brand_positioning.md
5559
layer: human-authored
5660
scope: strict

‎docs/_generated/render_state.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@
7676
"source_hashes": {
7777
"contracts/api/web_api.openapi.yaml": "c97830844b65fd8f76cd23688187ca8648835d787d1819045882dea01e1d7b64"
7878
},
79-
"output_hash": "ffb36e9c2b3fa2651083ac92db5bf8b3d825345632c09ca8a1f4256c896a408c"
79+
"output_hash": "560ad547242b0c1b25a236d2f2ad7028b0fb644bb243027844d8e1731d36a0da"
8080
},
8181
{
8282
"id": "root-runtime-topology",
@@ -91,7 +91,7 @@
9191
"package.json": "19ed161b16378601fc42d4baa05b7225fc57a47cfdee28a64131fd57d3cd1efc",
9292
".env.example": "32a60792624cd36eb5992b34d9c67c6e6e2a0971a45f3a48370f3b0b720b0aa8"
9393
},
94-
"output_hash": "ffb36e9c2b3fa2651083ac92db5bf8b3d825345632c09ca8a1f4256c896a408c"
94+
"output_hash": "560ad547242b0c1b25a236d2f2ad7028b0fb644bb243027844d8e1731d36a0da"
9595
},
9696
{
9797
"id": "root-ci-governance-summary",
@@ -106,7 +106,7 @@
106106
"contracts/governance/required_checks_policy.yaml": "51f9e8cb17df93c3912ae719a6ba95b74f2c666b6b11c79e1728f7002fb3e3b3",
107107
"package.json": "19ed161b16378601fc42d4baa05b7225fc57a47cfdee28a64131fd57d3cd1efc"
108108
},
109-
"output_hash": "ffb36e9c2b3fa2651083ac92db5bf8b3d825345632c09ca8a1f4256c896a408c"
109+
"output_hash": "560ad547242b0c1b25a236d2f2ad7028b0fb644bb243027844d8e1731d36a0da"
110110
},
111111
{
112112
"id": "root-release-identity",
@@ -117,7 +117,7 @@
117117
"source_hashes": {
118118
"pyproject.toml": "d12c2c415c3900d81c888e91d3a8ec1af88af96a701c6de801c37a1e52b4a495"
119119
},
120-
"output_hash": "ffb36e9c2b3fa2651083ac92db5bf8b3d825345632c09ca8a1f4256c896a408c"
120+
"output_hash": "560ad547242b0c1b25a236d2f2ad7028b0fb644bb243027844d8e1731d36a0da"
121121
},
122122
{
123123
"id": "script-readme-web-api-routes",

‎tests/unit/test_governance_closeout_contracts.py‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,89 @@ def test_gate_log_correlation_gate_validates_summary_and_artifacts(tmp_path: Pat
283283
assert proc.returncode == 0, proc.stdout + proc.stderr
284284

285285

286+
def test_gate_log_correlation_can_skip_missing_optional_gate_summaries(tmp_path: Path) -> None:
287+
repo = tmp_path / "repo"
288+
(repo / "contracts" / "runtime").mkdir(parents=True)
289+
(repo / ".runtime-cache" / "logs" / "quality-gate").mkdir(parents=True)
290+
(repo / "contracts" / "runtime" / "gate_log_schema.yaml").write_text(
291+
"\n".join(
292+
[
293+
"version: 1",
294+
"required_gates:",
295+
" - gate_name: quality-gate",
296+
" summary_path: .runtime-cache/logs/quality-gate/summary.json",
297+
" bridge_log_step_name: logging-contract",
298+
" bridge_required_event_fields:",
299+
" - gate_run_id",
300+
" - gate_name",
301+
" - gate_name: platform-alignment",
302+
" summary_path: .runtime-cache/logs/platform-alignment/summary.json",
303+
"required_top_level_fields:",
304+
" - gate_run_id",
305+
" - gate_name",
306+
" - status",
307+
" - started_at",
308+
" - ended_at",
309+
" - duration_ms",
310+
" - steps",
311+
"required_step_fields:",
312+
" - step_name",
313+
" - status",
314+
" - started_at",
315+
" - ended_at",
316+
" - duration_ms",
317+
" - artifact_log_path",
318+
]
319+
)
320+
+ "\n",
321+
encoding="utf-8",
322+
)
323+
(repo / ".runtime-cache" / "logs" / "quality-gate" / "step.log").write_text(
324+
"\n".join(
325+
[
326+
'{"event":"report.generate.start","gate_run_id":"quality-gate-1","gate_name":"quality-gate"}',
327+
'{"event":"report.generate.fail","gate_run_id":"quality-gate-1","gate_name":"quality-gate"}',
328+
]
329+
)
330+
+ "\n",
331+
encoding="utf-8",
332+
)
333+
(repo / ".runtime-cache" / "logs" / "quality-gate" / "summary.json").write_text(
334+
"{\n"
335+
' "gate_run_id": "quality-gate-1",\n'
336+
' "gate_name": "quality-gate",\n'
337+
' "status": "pass",\n'
338+
' "started_at": "2026-03-16T13:00:00Z",\n'
339+
' "ended_at": "2026-03-16T13:00:01Z",\n'
340+
' "duration_ms": 1000,\n'
341+
' "steps": [\n'
342+
" {\n"
343+
' "step_name": "logging-contract",\n'
344+
' "status": "pass",\n'
345+
' "started_at": "2026-03-16T13:00:00Z",\n'
346+
' "ended_at": "2026-03-16T13:00:01Z",\n'
347+
' "duration_ms": 1000,\n'
348+
' "artifact_log_path": ".runtime-cache/logs/quality-gate/step.log"\n'
349+
" }\n"
350+
" ]\n"
351+
"}\n",
352+
encoding="utf-8",
353+
)
354+
355+
proc = _run(
356+
[
357+
sys.executable,
358+
str(REPO_ROOT / "tooling" / "scripts" / "check_gate_log_correlation.py"),
359+
"--root",
360+
str(repo),
361+
"--allow-missing-gate",
362+
"platform-alignment",
363+
],
364+
repo,
365+
)
366+
assert proc.returncode == 0, proc.stdout + proc.stderr
367+
368+
286369
def test_gate_log_correlation_can_target_single_gate_with_custom_summary_path(tmp_path: Path) -> None:
287370
repo = tmp_path / "repo"
288371
(repo / "contracts" / "runtime").mkdir(parents=True)

‎tests/unit/test_governance_completion_gates.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ def test_governance_wiring_includes_cold_start_and_root_change_control_gates() -
175175
assert "check_snapshot_scope_labels.py" in quality
176176
assert "check_gate_log_correlation.py" in verify
177177
assert "check_gate_log_correlation.py" in score
178-
assert "check_gate_log_correlation.py" in local_quality
178+
assert "check_gate_log_correlation.py" not in local_quality
179179
assert "check_gate_log_correlation.py" in quality
180180
assert "check_positioning_claims.py" in verify
181181
assert "check_positioning_claims.py" in score

‎tests/unit/test_test_system_round2_audit.py‎

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -459,21 +459,9 @@ def test_local_fast_and_standard_prepush_align_with_ci_core_gates() -> None:
459459
'step fast-lane bash "$ROOT/gates/local_quality_gate.sh" fast',
460460
"pre-push strict fast lane",
461461
)
462-
_assert_contains(
463-
local_quality_gate,
464-
"check_upstream_verification_freshness.py",
465-
"local upstream freshness guard",
466-
)
467-
_assert_contains(
468-
local_quality_gate,
469-
"check_upstream_receipts.py",
470-
"local upstream receipts guard",
471-
)
472-
_assert_contains(
473-
local_quality_gate,
474-
"check_gate_log_correlation.py",
475-
"local gate log correlation guard",
476-
)
462+
assert "check_upstream_verification_freshness.py" not in local_quality_gate
463+
assert "check_upstream_receipts.py" not in local_quality_gate
464+
assert "check_gate_log_correlation.py" not in local_quality_gate
477465

478466

479467
def test_local_fast_skips_unrelated_python_and_frontend_work() -> None:

‎tooling/gates/local_quality_gate.sh‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@ set -euo pipefail
1515
# - Runs targeted checks on changed files only
1616
# - Falls back to full check if detection fails
1717
#
18-
# Summary-dependent receipt synthesis still belongs to tooling/gates/quality_gate.sh.
19-
# The local lanes keep the cheaper closeout guards that validate upstream freshness,
20-
# upstream receipts, and gate-log correlation without forcing the full quality-gate
21-
# summary pipeline on every routine local run.
18+
# Summary-dependent receipt synthesis and gate-summary correlation belong to
19+
# tooling/gates/quality_gate.sh after it has written the gate envelopes.
20+
# Keeping them out of fast/prepush-lite preserves the advertised local-burn
21+
# envelope and avoids false reds on clean local clones.
2222

2323
DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
2424
ROOT="$(dirname "$DIR")"
@@ -347,14 +347,11 @@ run_fast() {
347347
run_parallel_step upstream-drift "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_drift.py" --root "$REPO_ROOT"
348348
run_parallel_step upstream-registry "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_registry_completeness.py" --root "$REPO_ROOT"
349349
run_parallel_step upstream-compat "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_compat_matrix.py" --root "$REPO_ROOT"
350-
run_parallel_step upstream-freshness "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_verification_freshness.py" --root "$REPO_ROOT"
351-
run_parallel_step upstream-receipts "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_receipts.py" --root "$REPO_ROOT"
352350
run_parallel_step upstream-host-capabilities "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_host_capabilities.py" --root "$REPO_ROOT"
353351
run_parallel_step upstream-fetch "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_fetch_surfaces.py" --root "$REPO_ROOT"
354352
run_parallel_step private-upstream-coupling "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_no_private_upstream_coupling.py" --root "$REPO_ROOT"
355353
run_parallel_step dependency-boundaries "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_dependency_boundaries.py" --root "$REPO_ROOT"
356354
run_parallel_step logging-contract "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_logging_contract.py" --root "$REPO_ROOT"
357-
run_parallel_step gate-log-correlation "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_gate_log_correlation.py" --root "$REPO_ROOT"
358355
run_parallel_step run-bundle-contract "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_run_bundle_contract.py" --root "$REPO_ROOT"
359356
run_parallel_step test-quality bash "$ROOT/gates/test_quality_gate.sh"
360357

@@ -475,14 +472,11 @@ run_prepush_lite() {
475472
run_parallel_step upstream-drift "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_drift.py" --root "$REPO_ROOT"
476473
run_parallel_step upstream-registry "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_registry_completeness.py" --root "$REPO_ROOT"
477474
run_parallel_step upstream-compat "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_compat_matrix.py" --root "$REPO_ROOT"
478-
run_parallel_step upstream-freshness "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_verification_freshness.py" --root "$REPO_ROOT"
479-
run_parallel_step upstream-receipts "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_receipts.py" --root "$REPO_ROOT"
480475
run_parallel_step upstream-host-capabilities "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_host_capabilities.py" --root "$REPO_ROOT"
481476
run_parallel_step upstream-fetch "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_upstream_fetch_surfaces.py" --root "$REPO_ROOT"
482477
run_parallel_step private-upstream-coupling "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_no_private_upstream_coupling.py" --root "$REPO_ROOT"
483478
run_parallel_step dependency-boundaries "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_dependency_boundaries.py" --root "$REPO_ROOT"
484479
run_parallel_step logging-contract "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_logging_contract.py" --root "$REPO_ROOT"
485-
run_parallel_step gate-log-correlation "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_gate_log_correlation.py" --root "$REPO_ROOT"
486480
run_parallel_step run-bundle-contract "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_run_bundle_contract.py" --root "$REPO_ROOT"
487481
wait_parallel_steps
488482
run_step runtime-layout "$VENV/bin/python" "$REPO_ROOT/tooling/scripts/check_runtime_layout.py" --root "$REPO_ROOT"

‎tooling/scripts/check_ci_governance_regressions.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,8 +87,6 @@ def main() -> int:
8787
failures.append("local_quality_gate.sh must keep docs fragment completeness gate")
8888
if "check_snapshot_scope_labels.py" not in local_quality:
8989
failures.append("local_quality_gate.sh must keep snapshot scope labels gate")
90-
if "check_gate_log_correlation.py" not in local_quality:
91-
failures.append("local_quality_gate.sh must keep gate log correlation gate")
9290
if "check_hotspot_budget.py" not in local_quality:
9391
failures.append("local_quality_gate.sh must keep hotspot budget gate")
9492
if "check_mcp_surface.py" not in local_quality:

‎tooling/scripts/check_gate_log_correlation.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@ def main() -> int:
3535
parser.add_argument("--root", default=".")
3636
parser.add_argument("--contract", default="contracts/runtime/gate_log_schema.yaml")
3737
parser.add_argument("--gate", action="append", default=[], help="Only validate the named gate(s) from the contract")
38+
parser.add_argument(
39+
"--allow-missing-gate",
40+
action="append",
41+
default=[],
42+
help="Gate name(s) that may be skipped when their summary file does not exist",
43+
)
3844
parser.add_argument("--summary-path", help="Override the summary path when validating a single gate")
3945
args = parser.parse_args()
4046

@@ -52,6 +58,7 @@ def main() -> int:
5258
missing = selected_gates.difference(str(gate.get("gate_name", "")).strip() for gate in gates if isinstance(gate, dict))
5359
if missing:
5460
raise SystemExit(f"unknown gate(s) requested: {', '.join(sorted(missing))}")
61+
allow_missing_gates = {item.strip() for item in args.allow_missing_gate if item and item.strip()}
5562
if args.summary_path and len(gates) != 1:
5663
raise SystemExit("--summary-path requires exactly one selected gate")
5764

@@ -67,6 +74,8 @@ def main() -> int:
6774
issues.append(f"invalid required_gates entry: {gate!r}")
6875
continue
6976
if not summary_path.exists():
77+
if gate_name in allow_missing_gates:
78+
continue
7079
issues.append(f"{gate_name}: missing summary file: {summary_path.relative_to(root)}")
7180
continue
7281
try:

0 commit comments

Comments
 (0)