From 575a7c40cb6b3541c602c9bda69c390e0fd99291 Mon Sep 17 00:00:00 2001 From: Krill Date: Sat, 18 Jul 2026 02:49:56 -0500 Subject: [PATCH 1/3] Fail site publication closed on matrix failures --- .github/workflows/site-data-publish.yml | 100 ++++++++++++++++++++++-- 1 file changed, 95 insertions(+), 5 deletions(-) diff --git a/.github/workflows/site-data-publish.yml b/.github/workflows/site-data-publish.yml index 722b9c513..3975d32ea 100644 --- a/.github/workflows/site-data-publish.yml +++ b/.github/workflows/site-data-publish.yml @@ -16,8 +16,9 @@ permissions: env: SOURCE_COMMIT: ${{ github.event.workflow_run.head_sha }} SOURCE_BRANCH: ${{ github.event.workflow_run.head_branch }} - EVIDENCE_CONCLUSION: ${{ github.event.workflow_run.conclusion }} + REPORTED_EVIDENCE_CONCLUSION: ${{ github.event.workflow_run.conclusion }} EVIDENCE_RUN_ID: ${{ github.event.workflow_run.id }} + EVIDENCE_RUN_ATTEMPT: ${{ github.event.workflow_run.run_attempt }} jobs: site-data-prepare: @@ -25,10 +26,92 @@ jobs: runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: + actions: read contents: read outputs: publish: ${{ steps.final-head.outputs.publish }} + evidence_conclusion: ${{ steps.normalize_evidence.outputs.conclusion }} steps: + - name: Normalize evidence across every build job + id: normalize_evidence + env: + GITHUB_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + JOBS_FILE="$RUNNER_TEMP/build-evidence-jobs.tsv" + NON_PASSING_FILE="$RUNNER_TEMP/build-evidence-non-passing.tsv" + : > "$JOBS_FILE" + case "$EVIDENCE_RUN_ATTEMPT" in + ''|*[!0-9]*) echo "Invalid workflow attempt: $EVIDENCE_RUN_ATTEMPT" >&2; exit 1 ;; + esac + test "$EVIDENCE_RUN_ATTEMPT" -ge 1 + + PAGE=1 + EXPECTED_JOB_COUNT="" + while true; do + PAGE_FILE="$RUNNER_TEMP/build-evidence-jobs-${PAGE}.json" + curl --fail-with-body --silent --show-error \ + --retry 3 \ + --retry-all-errors \ + --header "Accept: application/vnd.github+json" \ + --header "Authorization: Bearer ${GITHUB_TOKEN}" \ + --header "X-GitHub-Api-Version: 2022-11-28" \ + "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/actions/runs/${EVIDENCE_RUN_ID}/attempts/${EVIDENCE_RUN_ATTEMPT}/jobs?per_page=100&page=${PAGE}" \ + --output "$PAGE_FILE" + + PAGE_METADATA="$(python3 -I -c 'import json, os, sys; payload = json.load(open(sys.argv[1], encoding="utf-8")); jobs = payload.get("jobs"); total = payload.get("total_count"); assert isinstance(jobs, list) and isinstance(total, int) and total > 0; expected_run = int(os.environ["EVIDENCE_RUN_ID"]); expected_sha = os.environ["SOURCE_COMMIT"]; assert all(isinstance(job, dict) and isinstance(job.get("id"), int) and job["id"] > 0 and job.get("run_id") == expected_run and job.get("head_sha") == expected_sha and isinstance(job.get("name"), str) and job["name"] for job in jobs); print(f"{total}\t{len(jobs)}")' \ + "$PAGE_FILE")" + PAGE_TOTAL_COUNT="${PAGE_METADATA%%$'\t'*}" + PAGE_JOB_COUNT="${PAGE_METADATA#*$'\t'}" + if test "$PAGE" -eq 1; then + EXPECTED_JOB_COUNT="$PAGE_TOTAL_COUNT" + else + test "$PAGE_TOTAL_COUNT" -eq "$EXPECTED_JOB_COUNT" + fi + + if test "$PAGE_JOB_COUNT" -eq 0; then + break + fi + + python3 -I -c 'import json, sys; field = lambda value: str(value or "").replace("\\", "\\\\").replace("\t", "\\t").replace("\r", "\\r").replace("\n", "\\n"); payload = json.load(open(sys.argv[1], encoding="utf-8")); [print("\t".join(field(job.get(key)) for key in ("id", "name", "status", "conclusion"))) for job in payload["jobs"]]' \ + "$PAGE_FILE" >> "$JOBS_FILE" + + if test "$PAGE_JOB_COUNT" -lt 100; then + break + fi + PAGE="$((PAGE + 1))" + test "$PAGE" -le 100 + done + + test -s "$JOBS_FILE" + JOB_COUNT="$(wc -l < "$JOBS_FILE" | tr -d '[:space:]')" + UNIQUE_JOB_COUNT="$(cut -f 1 "$JOBS_FILE" | LC_ALL=C sort -u | wc -l | tr -d '[:space:]')" + test "$JOB_COUNT" -eq "$EXPECTED_JOB_COUNT" + test "$UNIQUE_JOB_COUNT" -eq "$JOB_COUNT" + awk -F '\t' \ + '$3 != "completed" || ($4 != "success" && $4 != "skipped") { print }' \ + "$JOBS_FILE" > "$NON_PASSING_FILE" + + NORMALIZED_CONCLUSION="failure" + if test "$EVIDENCE_RUN_ATTEMPT" -eq 1 \ + && test "$REPORTED_EVIDENCE_CONCLUSION" = "success" \ + && test ! -s "$NON_PASSING_FILE"; then + NORMALIZED_CONCLUSION="success" + else + echo "::warning::The build evidence is not fully passing (workflow=${REPORTED_EVIDENCE_CONCLUSION})." + if test "$EVIDENCE_RUN_ATTEMPT" -ne 1; then + echo "::warning::A rerun cannot promote site evidence because a partial rerun does not prove the complete job roster. Push a new commit for a full run." + fi + while IFS=$'\t' read -r JOB_ID JOB_NAME JOB_STATUS JOB_CONCLUSION; do + printf 'Non-passing job %s: %s (%s/%s)\n' \ + "$JOB_ID" "$JOB_NAME" "$JOB_STATUS" "${JOB_CONCLUSION:-missing}" + done < "$NON_PASSING_FILE" + fi + + printf 'Evaluated %s jobs; normalized conclusion: %s\n' \ + "$JOB_COUNT" "$NORMALIZED_CONCLUSION" + printf 'conclusion=%s\n' "$NORMALIZED_CONCLUSION" >> "$GITHUB_OUTPUT" + - name: Checkout the evaluated source commit without persisted credentials uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: @@ -50,6 +133,8 @@ jobs: - name: Repeat the complete repository proof if: steps.initial-head.outputs.publish == 'true' + env: + NORMALIZED_EVIDENCE_CONCLUSION: ${{ steps.normalize_evidence.outputs.conclusion }} run: | set -euo pipefail test "$(git rev-parse HEAD)" = "$SOURCE_COMMIT" @@ -66,8 +151,8 @@ jobs: --source-branch "$SOURCE_BRANCH" \ --committed-at "$COMMITTED_AT" \ --evidence-commit "$SOURCE_COMMIT" \ - --ci-conclusion "$EVIDENCE_CONCLUSION" \ - --workflow-url "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${EVIDENCE_RUN_ID}" + --ci-conclusion "$NORMALIZED_EVIDENCE_CONCLUSION" \ + --workflow-url "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${EVIDENCE_RUN_ID}/attempts/${EVIDENCE_RUN_ATTEMPT}" python3 tools/site-data/validate.py --published "$OUTPUT" done diff --recursive --brief \ @@ -89,6 +174,7 @@ jobs: - name: Generate and validate the retained publication payload if: steps.initial-head.outputs.publish == 'true' env: + NORMALIZED_EVIDENCE_CONCLUSION: ${{ steps.normalize_evidence.outputs.conclusion }} PUBLISH_DIR: ${{ runner.temp }}/sparkengine-site-data-payload run: | set -euo pipefail @@ -101,8 +187,8 @@ jobs: --source-branch "$SOURCE_BRANCH" \ --committed-at "$COMMITTED_AT" \ --evidence-commit "$SOURCE_COMMIT" \ - --ci-conclusion "$EVIDENCE_CONCLUSION" \ - --workflow-url "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${EVIDENCE_RUN_ID}" + --ci-conclusion "$NORMALIZED_EVIDENCE_CONCLUSION" \ + --workflow-url "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${EVIDENCE_RUN_ID}/attempts/${EVIDENCE_RUN_ATTEMPT}" python3 tools/site-data/validate.py --published "$PUBLISH_DIR" - name: Recheck Working immediately before handing off the payload @@ -136,6 +222,8 @@ jobs: timeout-minutes: 5 permissions: contents: write + env: + EVIDENCE_CONCLUSION: ${{ needs.site-data-prepare.outputs.evidence_conclusion }} steps: - name: Download the proven publication payload uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 @@ -153,6 +241,8 @@ jobs: test -f "$PAYLOAD_DIR/latest.json" test -d "$PAYLOAD_DIR/snapshots/$SOURCE_COMMIT" test ! -e "$PAYLOAD_DIR/.git" + python3 -I -c 'import json, sys; payload = json.load(open(sys.argv[1], encoding="utf-8")); conclusion = sys.argv[2]; assert payload["publication"]["conclusion"] == conclusion; assert payload["publication"]["state"] == ("current" if conclusion == "success" else "blocked")' \ + "$PAYLOAD_DIR/latest.json" "$EVIDENCE_CONCLUSION" git init "$PUBLISH_REPO" git -C "$PUBLISH_REPO" remote add origin "https://github.com/${GITHUB_REPOSITORY}.git" From 1341a2342d687120370b083f37f3acbed390c251 Mon Sep 17 00:00:00 2001 From: Krill Date: Sat, 18 Jul 2026 02:54:18 -0500 Subject: [PATCH 2/3] Close delivered truth and site sync work --- docs/readiness/ENGINE_READINESS_HANDOFF.md | 45 +++++++++---------- .../work-items/00-truth-ci-release.json | 4 +- .../40-installer-governance-docs.json | 6 +-- docs/site/readiness.json | 6 +-- 4 files changed, 30 insertions(+), 31 deletions(-) diff --git a/docs/readiness/ENGINE_READINESS_HANDOFF.md b/docs/readiness/ENGINE_READINESS_HANDOFF.md index c81c7b90e..81767d30a 100644 --- a/docs/readiness/ENGINE_READINESS_HANDOFF.md +++ b/docs/readiness/ENGINE_READINESS_HANDOFF.md @@ -10,8 +10,8 @@ - Capabilities tracked: **22** - Blocking release gates: **18** - Gate states: **0 passing**, **0 at risk**, **18 blocked**, **0 not evaluated** -- Work items: **55 total**, **46 unfinished release blockers** -- First unblocked item: **`RDY-000` — Establish the release profiles and capability ledger** +- Work items: **55 total**, **44 unfinished release blockers** +- First unblocked item: **`CI-100` — Repair fail-closed required CI** ### Release means all of the following @@ -35,28 +35,27 @@ ## Start the next code session here -Open **`RDY-000` — Establish the release profiles and capability ledger**. Its dependencies are satisfied under the current ledger. Do not skip ahead to a dependent item or weaken a gate to manufacture a pass. +Open **`CI-100` — Repair fail-closed required CI**. Its dependencies are satisfied under the current ledger. Do not skip ahead to a dependent item or weaken a gate to manufacture a pass. ### Session entry points -- `docs/site/readiness.json` -- `docs/site/content.json` -- `docs/readiness/work-items` +- `.github/workflows/build.yml` +- `.github/workflows/codeql.yml` ### Session acceptance -1. No public capability or numeric claim exists without a validated contract entry -2. Every referenced path, gate, work item, metric, and capability exists -3. A capability cannot be ready while a blocker or required gate is open -4. Two clean generations produce byte-identical content except declared timestamps +1. Controlled test, sanitizer, format, threshold, registration, and validation failures each make CI red +2. Every Working commit receives a gate summary, including docs-only changes +3. MinGW/Wine is either executable and labeled experimental or removed from claims +4. Required-check policy is documented and externally verified ### Session verification ```bash -python3 tools/site-data/validate.py -python3 tools/site-data/generate.py --output .site-data -python3 tools/site-data/render_handoff.py --check -git diff --exit-code +bash tools/validate-all.sh +bash Tools/check-test-registration.sh +gh workflow run build.yml +gh api repos/Krilliac/SparkEngine/branches/Working/protection ``` Before ending the session, update the item status/evidence and regenerate this file. If new work is discovered, give it a stable ID, owner, dependencies, acceptance criteria, tests, documentation impact, and public-wording impact. @@ -65,7 +64,7 @@ Before ending the session, update the item status/evidence and regenerate this f | Gate | Area | State | Blocking | What must become true | Blocking work | |---|---|---|:---:|---|---| -| `G00` Source-of-truth integrity | governance | **blocked** | yes | One validated readiness contract owns public status; All numeric claims are generated; Documentation health is current; Regeneration is deterministic and clean | `RDY-000`, `DOC-410` | +| `G00` Source-of-truth integrity | governance | **blocked** | yes | One validated readiness contract owns public status; All numeric claims are generated; Documentation health is current; Regeneration is deterministic and clean | `DOC-410` | | `G01` Fail-closed CI evidence | ci | **blocked** | yes | Required commands propagate failure; Every Working commit receives normalized evidence; Advisory lanes are not represented as support gates; JUnit and gate summaries attach to the exact SHA | `CI-100`, `CI-110` | | `G02` Supported build matrix | build | **blocked** | yes | Declared host/compiler configurations configure and build from clean checkout; Every shipped target and real module library is built; Shipping configuration exists and is distinct from Debug/Release; Submodule/toolchain inputs are pinned | `CI-120`, `BLD-100` | | `G03` Production-source test coverage | tests | **blocked** | yes | Every real module library loads and executes in tests; No mirror-only or tautological test satisfies release; Coverage thresholds are explicit and enforced; Sanitizer and concurrency lanes fail closed | `RDY-010`, `CI-110` | @@ -80,7 +79,7 @@ Before ending the session, update the item status/evidence and regenerate this f | `G12` Production multiplayer and services | networking | **blocked** | yes | Dedicated server plus two independent clients pass authoritative gameplay; Protocol compatibility and hostile-client suites pass; Transactional persistence and restart/migration recovery pass; Load, telemetry, alerts, backups, and incident drills meet budgets | `NET-100`, `NET-110`, `DATA-120`, `TF-110`, `TF-120`, `OPS-110` | | `G13` Game-module release profiles | modules | **blocked** | yes | Every discovered module has a validated manifest and declared N/A dimensions; Applicable lifecycle/gameplay/assets/persistence/AI/editor/tests reach score 3; Modules are packaged and smoke-tested; Prototype/template labels are generated from the contract | `MOD-290`, `MOD-300`, `MOD-310`, `MOD-320`, `MOD-330`, `MOD-340`, `MOD-350`, `MOD-360`, `MOD-370`, `MOD-380`, `MOD-390` | | `G14` Performance, reliability, and operations | operations | **blocked** | yes | Representative CPU/GPU/memory/load budgets are versioned; Long soaks show bounded memory and tick/frame percentiles; Crashes produce symbolized actionable reports; Backups, restore, rollback, and incident drills pass | `PERF-100`, `OPS-100`, `OPS-110` | -| `G15` Documentation, legal, and support truth | governance | **blocked** | yes | Docs health is current and every link resolves; License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release; Quick starts run from clean machines; Website wording is generated from the tested contract | `DOC-410`, `GOV-400`, `DOC-400` | +| `G15` Documentation, legal, and support truth | governance | **blocked** | yes | Docs health is current and every link resolves; License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release; Quick starts run from clean machines; Website wording is generated from the tested contract | `DOC-410`, `GOV-400` | | `G16` Compatibility and migration | compatibility | **blocked** | yes | Version contracts exist for SDK, modules, assets, saves, scenes, protocols, and scripts; N-1 upgrade and rollback fixtures pass; Breaking changes fail with actionable diagnostics; Release notes enumerate migrations | `SDK-240`, `SAVE-230`, `NET-100`, `REL-200` | | `G17` Release rehearsal and sign-off | release | **blocked** | yes | A release candidate tag passes all blocking gates; Artifacts are installed and upgraded on clean supported hosts; Rollback and recovery drills pass; Owners sign the evidence ledger before the final tag | `REL-200` | @@ -128,7 +127,7 @@ Establish the only source of readiness truth and make CI report reality. | Work item | Priority | Status | Depends on | Safe parallel work | |---|---|---|---|---| -| [`RDY-000`](#rdy-000--establish-the-release-profiles-and-capability-ledger) Establish the release profiles and capability ledger | P0 | **in-progress** | — | `CI-100`, `SEC-100`, `OPS-100` | +| [`RDY-000`](#rdy-000--establish-the-release-profiles-and-capability-ledger) Establish the release profiles and capability ledger | P0 | **done** | — | `CI-100`, `SEC-100`, `OPS-100` | | [`RDY-010`](#rdy-010--make-real-module-and-production-source-tests-the-readiness-evidence) Make real module and production-source tests the readiness evidence | P0 | **open** | `RDY-000`, `CI-100` | `RDY-020`, `CI-110`, `CI-120` | | [`RDY-020`](#rdy-020--establish-asset-and-package-integrity-manifests) Establish asset and package integrity manifests | P0 | **open** | `RDY-000` | `RDY-010`, `CI-110`, `CI-120` | | [`CI-100`](#ci-100--repair-fail-closed-required-ci) Repair fail-closed required CI | P0 | **open** | — | `RDY-000`, `SEC-100`, `OPS-100` | @@ -223,7 +222,7 @@ Finish governance, publish the live bundle, rehearse every gate, and cut the fir | Work item | Priority | Status | Depends on | Safe parallel work | |---|---|---|---|---| | [`GOV-400`](#gov-400--resolve-licensing-third-party-notices-trademark-contribution-security-and-support-policy) Resolve licensing, third-party notices, trademark, contribution, security, and support policy | P0 | **open** | `RDY-000`, `SEC-110`, `REL-100` | `DOC-400` | -| [`DOC-400`](#doc-400--publish-the-repository-synchronized-site-data-bundle-and-complete-public-framing) Publish the repository-synchronized site-data bundle and complete public framing | P0 | **in-progress** | `RDY-000` | `DOC-410`, `CI-100`, `GOV-400` | +| [`DOC-400`](#doc-400--publish-the-repository-synchronized-site-data-bundle-and-complete-public-framing) Publish the repository-synchronized site-data bundle and complete public framing | P0 | **done** | `RDY-000` | `DOC-410`, `CI-100`, `GOV-400` | | [`REL-200`](#rel-200--rehearse-sign-off-and-publish-the-first-fully-gated-release) Rehearse, sign off, and publish the first fully gated release | P0 | **blocked** | `REL-100`, `REL-110`, `PLT-200`, `RHI-210`, `HEAD-220`, `EDT-210`, `SDK-240`, `PERF-100`, `OPS-100`, `GOV-400`, `DOC-400` | — | ## Game-module parity baseline @@ -250,9 +249,9 @@ Scores are evidence pointers, not percentages: `0` absent/dead, `1` data-model/m ### RDY-000 — Establish the release profiles and capability ledger -**Priority:** P0 · **Status:** in-progress · **Wave:** 0 · **Area:** governance · **Owner:** unassigned · **Release-blocking:** yes +**Priority:** P0 · **Status:** done · **Wave:** 0 · **Area:** governance · **Owner:** unassigned · **Release-blocking:** yes -Status documents, roadmap entries, test counts, module counts, website copy, and source reality currently disagree. One validated repository contract must own every public claim. +Status documents, roadmap entries, test counts, module counts, website copy, and source reality previously disagreed. The validated repository contract now owns every public claim while unresolved implementation work remains explicitly blocked. **Dependency contract** @@ -4276,9 +4275,9 @@ python3 tools/site-data/generate.py --output .site-data ### DOC-400 — Publish the repository-synchronized site-data bundle and complete public framing -**Priority:** P0 · **Status:** in-progress · **Wave:** 6 · **Area:** website · **Owner:** unassigned · **Release-blocking:** yes +**Priority:** P0 · **Status:** done · **Wave:** 6 · **Area:** website · **Owner:** unassigned · **Release-blocking:** yes -The existing site checks in a 22 MB generated snapshot and hardcodes capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that can drift after Working moves. +The previous site checked in a large generated snapshot and hardcoded capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that could drift after Working moved. The deployed runtime now consumes the validated exact-SHA repository publication and labels any fallback honestly. **Dependency contract** @@ -4308,7 +4307,7 @@ The existing site checks in a 22 MB generated snapshot and hardcodes capabilitie - Validate schema/hash/size at site runtime - Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable - Move all mutable site wording and claims into repository data -- Remove checked-in generated corpus after live parity +- Replace the checked-in full corpus with an exact generated fallback while live repository data remains authoritative **Acceptance criteria** diff --git a/docs/readiness/work-items/00-truth-ci-release.json b/docs/readiness/work-items/00-truth-ci-release.json index 31e1f7172..7cddfc7e5 100644 --- a/docs/readiness/work-items/00-truth-ci-release.json +++ b/docs/readiness/work-items/00-truth-ci-release.json @@ -5,12 +5,12 @@ "id": "RDY-000", "title": "Establish the release profiles and capability ledger", "priority": "P0", - "status": "in-progress", + "status": "done", "blocking": true, "wave": 0, "area": "governance", "owner": "unassigned", - "rationale": "Status documents, roadmap entries, test counts, module counts, website copy, and source reality currently disagree. One validated repository contract must own every public claim.", + "rationale": "Status documents, roadmap entries, test counts, module counts, website copy, and source reality previously disagreed. The validated repository contract now owns every public claim while unresolved implementation work remains explicitly blocked.", "dependencies": [], "parallelWith": ["CI-100", "SEC-100", "OPS-100"], "sourceContext": ["docs/status/PROJECT_STATUS.md", "docs/plans/FEATURE_ROADMAP.md", "wiki/advanced/SparkGame-Module-Status.md", "GameModules/README.md", "README.md"], diff --git a/docs/readiness/work-items/40-installer-governance-docs.json b/docs/readiness/work-items/40-installer-governance-docs.json index 5dcaa07a8..5ae3eafa7 100644 --- a/docs/readiness/work-items/40-installer-governance-docs.json +++ b/docs/readiness/work-items/40-installer-governance-docs.json @@ -58,12 +58,12 @@ { "id": "DOC-400", "title": "Publish the repository-synchronized site-data bundle and complete public framing", - "priority": "P0", "status": "in-progress", "blocking": true, "wave": 6, "area": "website", "owner": "unassigned", - "rationale": "The existing site checks in a 22 MB generated snapshot and hardcodes capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that can drift after Working moves.", + "priority": "P0", "status": "done", "blocking": true, "wave": 6, "area": "website", "owner": "unassigned", + "rationale": "The previous site checked in a large generated snapshot and hardcoded capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that could drift after Working moved. The deployed runtime now consumes the validated exact-SHA repository publication and labels any fallback honestly.", "dependencies": ["RDY-000"], "parallelWith": ["DOC-410", "CI-100", "GOV-400"], "sourceContext": ["docs/site", "docs/readiness", "tools/site-data", ".github/workflows/site-data.yml"], "entryPoints": ["tools/site-data/generate.py", ".github/workflows/site-data.yml", "docs/site/content.json"], - "implementationScope": ["Generate exact-SHA content/readiness/metrics/handoff/docs/search/page bundle", "Publish to dedicated site-data branch after exact tested Working SHA", "Publish blocked state after failed CI instead of leaving previous commit current", "Use hash-addressed snapshots and switch latest last", "Retain current plus two previous snapshots", "Validate schema/hash/size at site runtime", "Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable", "Move all mutable site wording and claims into repository data", "Remove checked-in generated corpus after live parity"], + "implementationScope": ["Generate exact-SHA content/readiness/metrics/handoff/docs/search/page bundle", "Publish to dedicated site-data branch after exact tested Working SHA", "Publish blocked state after failed CI instead of leaving previous commit current", "Use hash-addressed snapshots and switch latest last", "Retain current plus two previous snapshots", "Validate schema/hash/size at site runtime", "Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable", "Move all mutable site wording and claims into repository data", "Replace the checked-in full corpus with an exact generated fallback while live repository data remains authoritative"], "acceptanceCriteria": ["Repository-only wording/status/doc change appears on existing site without Sites checkpoint", "Displayed SHA equals the bundle/evidence SHA", "Failed same-commit CI changes site to blocked", "Every mutable metric/capability/quick-start/learning/readiness/roadmap claim comes from bundle", "Malformed/oversize/hash-invalid bundles are rejected", "Fallback is visibly stale/unavailable", "All docs routes/search/source links resolve"], "commands": ["python3 tools/site-data/validate.py", "python3 tools/site-data/generate.py --output .site-data", "python3 tools/site-data/render_handoff.py --check", "npm test"], "testSelectors": ["site-data-contract", "runtime-bundle-validation", "live-docs-parity", "no-hardcoded-claims"], "requiredCiJobs": ["site-data-validate", "site-data-publish", "site-runtime-contract"], diff --git a/docs/site/readiness.json b/docs/site/readiness.json index c664f72a6..0340b379c 100644 --- a/docs/site/readiness.json +++ b/docs/site/readiness.json @@ -436,7 +436,7 @@ } ], "gates": [ - {"id": "G00", "name": "Source-of-truth integrity", "area": "governance", "state": "blocked", "blocking": true, "summary": "Status, roadmap, module counts, test counts, and generated documentation contradict or trail the repository.", "acceptanceCriteria": ["One validated readiness contract owns public status", "All numeric claims are generated", "Documentation health is current", "Regeneration is deterministic and clean"], "evidence": [{"type": "document", "path": "docs/status/PROJECT_STATUS.md", "label": "Stale status snapshot"}, {"type": "document", "path": "docs/plans/FEATURE_ROADMAP.md", "label": "Roadmap snapshot"}], "blockingWorkItemIds": ["RDY-000", "DOC-410"]}, + {"id": "G00", "name": "Source-of-truth integrity", "area": "governance", "state": "blocked", "blocking": true, "summary": "The validated readiness contract now owns public status and metrics, while stale repository documentation generators still prevent this gate from passing.", "acceptanceCriteria": ["One validated readiness contract owns public status", "All numeric claims are generated", "Documentation health is current", "Regeneration is deterministic and clean"], "evidence": [{"type": "document", "path": "docs/status/PROJECT_STATUS.md", "label": "Stale status snapshot"}, {"type": "document", "path": "docs/plans/FEATURE_ROADMAP.md", "label": "Roadmap snapshot"}], "blockingWorkItemIds": ["DOC-410"]}, {"id": "G01", "name": "Fail-closed CI evidence", "area": "ci", "state": "blocked", "blocking": true, "summary": "Required jobs can mask failures or remain advisory; docs-only changes can bypass the engine evidence path.", "acceptanceCriteria": ["Required commands propagate failure", "Every Working commit receives normalized evidence", "Advisory lanes are not represented as support gates", "JUnit and gate summaries attach to the exact SHA"], "evidence": [{"type": "workflow", "path": ".github/workflows/build.yml", "label": "Build workflow"}], "blockingWorkItemIds": ["CI-100", "CI-110"]}, {"id": "G02", "name": "Supported build matrix", "area": "build", "state": "blocked", "blocking": true, "summary": "The intended configurations and module/tool targets are not all built as required, reproducible gates.", "acceptanceCriteria": ["Declared host/compiler configurations configure and build from clean checkout", "Every shipped target and real module library is built", "Shipping configuration exists and is distinct from Debug/Release", "Submodule/toolchain inputs are pinned"], "evidence": [{"type": "workflow", "path": ".github/workflows/build.yml", "label": "Build matrix"}, {"type": "source", "path": "CMakePresets.json", "label": "CMake presets"}], "blockingWorkItemIds": ["CI-120", "BLD-100"]}, {"id": "G03", "name": "Production-source test coverage", "area": "tests", "state": "blocked", "blocking": true, "summary": "Many module tests compile subsets or mirrored logic rather than packaged production implementations; coverage thresholds are nonblocking.", "acceptanceCriteria": ["Every real module library loads and executes in tests", "No mirror-only or tautological test satisfies release", "Coverage thresholds are explicit and enforced", "Sanitizer and concurrency lanes fail closed"], "evidence": [{"type": "source", "path": "Tests/CMakeLists.txt", "label": "Test target composition"}, {"type": "workflow", "path": ".github/workflows/build.yml", "label": "Test lanes"}], "blockingWorkItemIds": ["RDY-010", "CI-110"]}, @@ -451,7 +451,7 @@ {"id": "G12", "name": "Production multiplayer and services", "area": "networking", "state": "blocked", "blocking": true, "summary": "True independent-client, secure transport, compatibility, persistence, scale, recovery, and operations gates are missing.", "acceptanceCriteria": ["Dedicated server plus two independent clients pass authoritative gameplay", "Protocol compatibility and hostile-client suites pass", "Transactional persistence and restart/migration recovery pass", "Load, telemetry, alerts, backups, and incident drills meet budgets"], "evidence": [{"type": "source", "path": "GameModules/SparkGameMMOFPS", "label": "MMOFPS vertical slice"}], "blockingWorkItemIds": ["NET-100", "NET-110", "DATA-120", "TF-110", "TF-120", "OPS-110"]}, {"id": "G13", "name": "Game-module release profiles", "area": "modules", "state": "blocked", "blocking": true, "summary": "Only MMOFPS approaches a deep vertical slice; FPS is local-playable and the remaining modules are prototypes/templates with uneven real-source tests and assets.", "acceptanceCriteria": ["Every discovered module has a validated manifest and declared N/A dimensions", "Applicable lifecycle/gameplay/assets/persistence/AI/editor/tests reach score 3", "Modules are packaged and smoke-tested", "Prototype/template labels are generated from the contract"], "evidence": [{"type": "source", "path": "GameModules", "label": "Eleven module directories"}, {"type": "document", "path": "wiki/advanced/SparkGame-Module-Status.md", "label": "Module audit"}], "blockingWorkItemIds": ["MOD-290", "MOD-300", "MOD-310", "MOD-320", "MOD-330", "MOD-340", "MOD-350", "MOD-360", "MOD-370", "MOD-380", "MOD-390"]}, {"id": "G14", "name": "Performance, reliability, and operations", "area": "operations", "state": "blocked", "blocking": true, "summary": "Profilers exist, while representative budgets, long soaks, leak limits, crash symbolization, service telemetry, alerting, backups, and recovery drills are not release gates.", "acceptanceCriteria": ["Representative CPU/GPU/memory/load budgets are versioned", "Long soaks show bounded memory and tick/frame percentiles", "Crashes produce symbolized actionable reports", "Backups, restore, rollback, and incident drills pass"], "evidence": [{"type": "document", "path": "wiki/advanced/Performance-Profiling-Guide.md", "label": "Profiling guide"}, {"type": "source", "path": "SparkCrashReporter", "label": "Crash reporter"}], "blockingWorkItemIds": ["PERF-100", "OPS-100", "OPS-110"]}, - {"id": "G15", "name": "Documentation, legal, and support truth", "area": "governance", "state": "blocked", "blocking": true, "summary": "Documentation generators are stale, release/security wording assumes a version line with no tag, and support/trademark/attribution decisions need a release review.", "acceptanceCriteria": ["Docs health is current and every link resolves", "License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release", "Quick starts run from clean machines", "Website wording is generated from the tested contract"], "evidence": [{"type": "document", "path": "LICENSE", "label": "License"}, {"type": "document", "path": "SECURITY.md", "label": "Security policy"}, {"type": "document", "path": "docs/README.md", "label": "Docs tooling"}], "blockingWorkItemIds": ["DOC-410", "GOV-400", "DOC-400"]}, + {"id": "G15", "name": "Documentation, legal, and support truth", "area": "governance", "state": "blocked", "blocking": true, "summary": "Website wording is generated from the tested contract, while documentation generators, clean-machine quick starts, and release legal/support review remain incomplete.", "acceptanceCriteria": ["Docs health is current and every link resolves", "License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release", "Quick starts run from clean machines", "Website wording is generated from the tested contract"], "evidence": [{"type": "document", "path": "LICENSE", "label": "License"}, {"type": "document", "path": "SECURITY.md", "label": "Security policy"}, {"type": "document", "path": "docs/README.md", "label": "Docs tooling"}], "blockingWorkItemIds": ["DOC-410", "GOV-400"]}, {"id": "G16", "name": "Compatibility and migration", "area": "compatibility", "state": "blocked", "blocking": true, "summary": "SDK ABI, module, save, asset, protocol, and editor-data compatibility policies and migration tests are incomplete.", "acceptanceCriteria": ["Version contracts exist for SDK, modules, assets, saves, scenes, protocols, and scripts", "N-1 upgrade and rollback fixtures pass", "Breaking changes fail with actionable diagnostics", "Release notes enumerate migrations"], "evidence": [{"type": "source", "path": "SparkSDK", "label": "Public SDK"}, {"type": "source", "path": "SparkEngine/Source/Engine/SaveSystem/SaveSystem.h", "label": "Serialization surface"}], "blockingWorkItemIds": ["SDK-240", "SAVE-230", "NET-100", "REL-200"]}, {"id": "G17", "name": "Release rehearsal and sign-off", "area": "release", "state": "blocked", "blocking": true, "summary": "No tagged release has rehearsed every blocking gate, artifact, install, migration, rollback, documentation, and support step at one commit.", "acceptanceCriteria": ["A release candidate tag passes all blocking gates", "Artifacts are installed and upgraded on clean supported hosts", "Rollback and recovery drills pass", "Owners sign the evidence ledger before the final tag"], "evidence": [{"type": "workflow", "path": ".github/workflows/release.yml", "label": "Release workflow"}], "blockingWorkItemIds": ["REL-200"]} ], @@ -473,6 +473,6 @@ {"id": 5, "name": "Portable and modern backends", "objective": "Certify or explicitly bound Linux, macOS, D3D12, Vulkan, OpenGL, Metal, mobile, VR, and console work.", "workItemIds": ["PLT-210", "PLT-220", "PLT-230", "PLT-240", "PLT-250", "RHI-220", "RHI-225", "RHI-230", "RHI-240", "ENG-220"]}, {"id": 6, "name": "Public truth and release", "objective": "Finish governance, publish the live bundle, rehearse every gate, and cut the first evidence-backed release.", "workItemIds": ["GOV-400", "DOC-400", "REL-200"]} ], - "firstUnblockedWorkItemId": "RDY-000" + "firstUnblockedWorkItemId": "CI-100" } } From 5062894e195ec5303f9882e73730790adae908ee Mon Sep 17 00:00:00 2001 From: Krill Date: Sat, 18 Jul 2026 02:59:50 -0500 Subject: [PATCH 3/3] Keep readiness closeout evidence-bound --- docs/readiness/ENGINE_READINESS_HANDOFF.md | 45 ++++++++++--------- .../work-items/00-truth-ci-release.json | 4 +- .../40-installer-governance-docs.json | 6 +-- docs/site/readiness.json | 6 +-- 4 files changed, 31 insertions(+), 30 deletions(-) diff --git a/docs/readiness/ENGINE_READINESS_HANDOFF.md b/docs/readiness/ENGINE_READINESS_HANDOFF.md index 81767d30a..c81c7b90e 100644 --- a/docs/readiness/ENGINE_READINESS_HANDOFF.md +++ b/docs/readiness/ENGINE_READINESS_HANDOFF.md @@ -10,8 +10,8 @@ - Capabilities tracked: **22** - Blocking release gates: **18** - Gate states: **0 passing**, **0 at risk**, **18 blocked**, **0 not evaluated** -- Work items: **55 total**, **44 unfinished release blockers** -- First unblocked item: **`CI-100` — Repair fail-closed required CI** +- Work items: **55 total**, **46 unfinished release blockers** +- First unblocked item: **`RDY-000` — Establish the release profiles and capability ledger** ### Release means all of the following @@ -35,27 +35,28 @@ ## Start the next code session here -Open **`CI-100` — Repair fail-closed required CI**. Its dependencies are satisfied under the current ledger. Do not skip ahead to a dependent item or weaken a gate to manufacture a pass. +Open **`RDY-000` — Establish the release profiles and capability ledger**. Its dependencies are satisfied under the current ledger. Do not skip ahead to a dependent item or weaken a gate to manufacture a pass. ### Session entry points -- `.github/workflows/build.yml` -- `.github/workflows/codeql.yml` +- `docs/site/readiness.json` +- `docs/site/content.json` +- `docs/readiness/work-items` ### Session acceptance -1. Controlled test, sanitizer, format, threshold, registration, and validation failures each make CI red -2. Every Working commit receives a gate summary, including docs-only changes -3. MinGW/Wine is either executable and labeled experimental or removed from claims -4. Required-check policy is documented and externally verified +1. No public capability or numeric claim exists without a validated contract entry +2. Every referenced path, gate, work item, metric, and capability exists +3. A capability cannot be ready while a blocker or required gate is open +4. Two clean generations produce byte-identical content except declared timestamps ### Session verification ```bash -bash tools/validate-all.sh -bash Tools/check-test-registration.sh -gh workflow run build.yml -gh api repos/Krilliac/SparkEngine/branches/Working/protection +python3 tools/site-data/validate.py +python3 tools/site-data/generate.py --output .site-data +python3 tools/site-data/render_handoff.py --check +git diff --exit-code ``` Before ending the session, update the item status/evidence and regenerate this file. If new work is discovered, give it a stable ID, owner, dependencies, acceptance criteria, tests, documentation impact, and public-wording impact. @@ -64,7 +65,7 @@ Before ending the session, update the item status/evidence and regenerate this f | Gate | Area | State | Blocking | What must become true | Blocking work | |---|---|---|:---:|---|---| -| `G00` Source-of-truth integrity | governance | **blocked** | yes | One validated readiness contract owns public status; All numeric claims are generated; Documentation health is current; Regeneration is deterministic and clean | `DOC-410` | +| `G00` Source-of-truth integrity | governance | **blocked** | yes | One validated readiness contract owns public status; All numeric claims are generated; Documentation health is current; Regeneration is deterministic and clean | `RDY-000`, `DOC-410` | | `G01` Fail-closed CI evidence | ci | **blocked** | yes | Required commands propagate failure; Every Working commit receives normalized evidence; Advisory lanes are not represented as support gates; JUnit and gate summaries attach to the exact SHA | `CI-100`, `CI-110` | | `G02` Supported build matrix | build | **blocked** | yes | Declared host/compiler configurations configure and build from clean checkout; Every shipped target and real module library is built; Shipping configuration exists and is distinct from Debug/Release; Submodule/toolchain inputs are pinned | `CI-120`, `BLD-100` | | `G03` Production-source test coverage | tests | **blocked** | yes | Every real module library loads and executes in tests; No mirror-only or tautological test satisfies release; Coverage thresholds are explicit and enforced; Sanitizer and concurrency lanes fail closed | `RDY-010`, `CI-110` | @@ -79,7 +80,7 @@ Before ending the session, update the item status/evidence and regenerate this f | `G12` Production multiplayer and services | networking | **blocked** | yes | Dedicated server plus two independent clients pass authoritative gameplay; Protocol compatibility and hostile-client suites pass; Transactional persistence and restart/migration recovery pass; Load, telemetry, alerts, backups, and incident drills meet budgets | `NET-100`, `NET-110`, `DATA-120`, `TF-110`, `TF-120`, `OPS-110` | | `G13` Game-module release profiles | modules | **blocked** | yes | Every discovered module has a validated manifest and declared N/A dimensions; Applicable lifecycle/gameplay/assets/persistence/AI/editor/tests reach score 3; Modules are packaged and smoke-tested; Prototype/template labels are generated from the contract | `MOD-290`, `MOD-300`, `MOD-310`, `MOD-320`, `MOD-330`, `MOD-340`, `MOD-350`, `MOD-360`, `MOD-370`, `MOD-380`, `MOD-390` | | `G14` Performance, reliability, and operations | operations | **blocked** | yes | Representative CPU/GPU/memory/load budgets are versioned; Long soaks show bounded memory and tick/frame percentiles; Crashes produce symbolized actionable reports; Backups, restore, rollback, and incident drills pass | `PERF-100`, `OPS-100`, `OPS-110` | -| `G15` Documentation, legal, and support truth | governance | **blocked** | yes | Docs health is current and every link resolves; License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release; Quick starts run from clean machines; Website wording is generated from the tested contract | `DOC-410`, `GOV-400` | +| `G15` Documentation, legal, and support truth | governance | **blocked** | yes | Docs health is current and every link resolves; License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release; Quick starts run from clean machines; Website wording is generated from the tested contract | `DOC-410`, `GOV-400`, `DOC-400` | | `G16` Compatibility and migration | compatibility | **blocked** | yes | Version contracts exist for SDK, modules, assets, saves, scenes, protocols, and scripts; N-1 upgrade and rollback fixtures pass; Breaking changes fail with actionable diagnostics; Release notes enumerate migrations | `SDK-240`, `SAVE-230`, `NET-100`, `REL-200` | | `G17` Release rehearsal and sign-off | release | **blocked** | yes | A release candidate tag passes all blocking gates; Artifacts are installed and upgraded on clean supported hosts; Rollback and recovery drills pass; Owners sign the evidence ledger before the final tag | `REL-200` | @@ -127,7 +128,7 @@ Establish the only source of readiness truth and make CI report reality. | Work item | Priority | Status | Depends on | Safe parallel work | |---|---|---|---|---| -| [`RDY-000`](#rdy-000--establish-the-release-profiles-and-capability-ledger) Establish the release profiles and capability ledger | P0 | **done** | — | `CI-100`, `SEC-100`, `OPS-100` | +| [`RDY-000`](#rdy-000--establish-the-release-profiles-and-capability-ledger) Establish the release profiles and capability ledger | P0 | **in-progress** | — | `CI-100`, `SEC-100`, `OPS-100` | | [`RDY-010`](#rdy-010--make-real-module-and-production-source-tests-the-readiness-evidence) Make real module and production-source tests the readiness evidence | P0 | **open** | `RDY-000`, `CI-100` | `RDY-020`, `CI-110`, `CI-120` | | [`RDY-020`](#rdy-020--establish-asset-and-package-integrity-manifests) Establish asset and package integrity manifests | P0 | **open** | `RDY-000` | `RDY-010`, `CI-110`, `CI-120` | | [`CI-100`](#ci-100--repair-fail-closed-required-ci) Repair fail-closed required CI | P0 | **open** | — | `RDY-000`, `SEC-100`, `OPS-100` | @@ -222,7 +223,7 @@ Finish governance, publish the live bundle, rehearse every gate, and cut the fir | Work item | Priority | Status | Depends on | Safe parallel work | |---|---|---|---|---| | [`GOV-400`](#gov-400--resolve-licensing-third-party-notices-trademark-contribution-security-and-support-policy) Resolve licensing, third-party notices, trademark, contribution, security, and support policy | P0 | **open** | `RDY-000`, `SEC-110`, `REL-100` | `DOC-400` | -| [`DOC-400`](#doc-400--publish-the-repository-synchronized-site-data-bundle-and-complete-public-framing) Publish the repository-synchronized site-data bundle and complete public framing | P0 | **done** | `RDY-000` | `DOC-410`, `CI-100`, `GOV-400` | +| [`DOC-400`](#doc-400--publish-the-repository-synchronized-site-data-bundle-and-complete-public-framing) Publish the repository-synchronized site-data bundle and complete public framing | P0 | **in-progress** | `RDY-000` | `DOC-410`, `CI-100`, `GOV-400` | | [`REL-200`](#rel-200--rehearse-sign-off-and-publish-the-first-fully-gated-release) Rehearse, sign off, and publish the first fully gated release | P0 | **blocked** | `REL-100`, `REL-110`, `PLT-200`, `RHI-210`, `HEAD-220`, `EDT-210`, `SDK-240`, `PERF-100`, `OPS-100`, `GOV-400`, `DOC-400` | — | ## Game-module parity baseline @@ -249,9 +250,9 @@ Scores are evidence pointers, not percentages: `0` absent/dead, `1` data-model/m ### RDY-000 — Establish the release profiles and capability ledger -**Priority:** P0 · **Status:** done · **Wave:** 0 · **Area:** governance · **Owner:** unassigned · **Release-blocking:** yes +**Priority:** P0 · **Status:** in-progress · **Wave:** 0 · **Area:** governance · **Owner:** unassigned · **Release-blocking:** yes -Status documents, roadmap entries, test counts, module counts, website copy, and source reality previously disagreed. The validated repository contract now owns every public claim while unresolved implementation work remains explicitly blocked. +Status documents, roadmap entries, test counts, module counts, website copy, and source reality currently disagree. One validated repository contract must own every public claim. **Dependency contract** @@ -4275,9 +4276,9 @@ python3 tools/site-data/generate.py --output .site-data ### DOC-400 — Publish the repository-synchronized site-data bundle and complete public framing -**Priority:** P0 · **Status:** done · **Wave:** 6 · **Area:** website · **Owner:** unassigned · **Release-blocking:** yes +**Priority:** P0 · **Status:** in-progress · **Wave:** 6 · **Area:** website · **Owner:** unassigned · **Release-blocking:** yes -The previous site checked in a large generated snapshot and hardcoded capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that could drift after Working moved. The deployed runtime now consumes the validated exact-SHA repository publication and labels any fallback honestly. +The existing site checks in a 22 MB generated snapshot and hardcodes capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that can drift after Working moves. **Dependency contract** @@ -4307,7 +4308,7 @@ The previous site checked in a large generated snapshot and hardcoded capabiliti - Validate schema/hash/size at site runtime - Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable - Move all mutable site wording and claims into repository data -- Replace the checked-in full corpus with an exact generated fallback while live repository data remains authoritative +- Remove checked-in generated corpus after live parity **Acceptance criteria** diff --git a/docs/readiness/work-items/00-truth-ci-release.json b/docs/readiness/work-items/00-truth-ci-release.json index 7cddfc7e5..31e1f7172 100644 --- a/docs/readiness/work-items/00-truth-ci-release.json +++ b/docs/readiness/work-items/00-truth-ci-release.json @@ -5,12 +5,12 @@ "id": "RDY-000", "title": "Establish the release profiles and capability ledger", "priority": "P0", - "status": "done", + "status": "in-progress", "blocking": true, "wave": 0, "area": "governance", "owner": "unassigned", - "rationale": "Status documents, roadmap entries, test counts, module counts, website copy, and source reality previously disagreed. The validated repository contract now owns every public claim while unresolved implementation work remains explicitly blocked.", + "rationale": "Status documents, roadmap entries, test counts, module counts, website copy, and source reality currently disagree. One validated repository contract must own every public claim.", "dependencies": [], "parallelWith": ["CI-100", "SEC-100", "OPS-100"], "sourceContext": ["docs/status/PROJECT_STATUS.md", "docs/plans/FEATURE_ROADMAP.md", "wiki/advanced/SparkGame-Module-Status.md", "GameModules/README.md", "README.md"], diff --git a/docs/readiness/work-items/40-installer-governance-docs.json b/docs/readiness/work-items/40-installer-governance-docs.json index 5ae3eafa7..5dcaa07a8 100644 --- a/docs/readiness/work-items/40-installer-governance-docs.json +++ b/docs/readiness/work-items/40-installer-governance-docs.json @@ -58,12 +58,12 @@ { "id": "DOC-400", "title": "Publish the repository-synchronized site-data bundle and complete public framing", - "priority": "P0", "status": "done", "blocking": true, "wave": 6, "area": "website", "owner": "unassigned", - "rationale": "The previous site checked in a large generated snapshot and hardcoded capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that could drift after Working moved. The deployed runtime now consumes the validated exact-SHA repository publication and labels any fallback honestly.", + "priority": "P0", "status": "in-progress", "blocking": true, "wave": 6, "area": "website", "owner": "unassigned", + "rationale": "The existing site checks in a 22 MB generated snapshot and hardcodes capabilities, counts, paths, CI runs, maturity rules, learning tracks, community status, and wording that can drift after Working moves.", "dependencies": ["RDY-000"], "parallelWith": ["DOC-410", "CI-100", "GOV-400"], "sourceContext": ["docs/site", "docs/readiness", "tools/site-data", ".github/workflows/site-data.yml"], "entryPoints": ["tools/site-data/generate.py", ".github/workflows/site-data.yml", "docs/site/content.json"], - "implementationScope": ["Generate exact-SHA content/readiness/metrics/handoff/docs/search/page bundle", "Publish to dedicated site-data branch after exact tested Working SHA", "Publish blocked state after failed CI instead of leaving previous commit current", "Use hash-addressed snapshots and switch latest last", "Retain current plus two previous snapshots", "Validate schema/hash/size at site runtime", "Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable", "Move all mutable site wording and claims into repository data", "Replace the checked-in full corpus with an exact generated fallback while live repository data remains authoritative"], + "implementationScope": ["Generate exact-SHA content/readiness/metrics/handoff/docs/search/page bundle", "Publish to dedicated site-data branch after exact tested Working SHA", "Publish blocked state after failed CI instead of leaving previous commit current", "Use hash-addressed snapshots and switch latest last", "Retain current plus two previous snapshots", "Validate schema/hash/size at site runtime", "Cache five minutes with stale-while-revalidate and label current/syncing/blocked/stale/unavailable", "Move all mutable site wording and claims into repository data", "Remove checked-in generated corpus after live parity"], "acceptanceCriteria": ["Repository-only wording/status/doc change appears on existing site without Sites checkpoint", "Displayed SHA equals the bundle/evidence SHA", "Failed same-commit CI changes site to blocked", "Every mutable metric/capability/quick-start/learning/readiness/roadmap claim comes from bundle", "Malformed/oversize/hash-invalid bundles are rejected", "Fallback is visibly stale/unavailable", "All docs routes/search/source links resolve"], "commands": ["python3 tools/site-data/validate.py", "python3 tools/site-data/generate.py --output .site-data", "python3 tools/site-data/render_handoff.py --check", "npm test"], "testSelectors": ["site-data-contract", "runtime-bundle-validation", "live-docs-parity", "no-hardcoded-claims"], "requiredCiJobs": ["site-data-validate", "site-data-publish", "site-runtime-contract"], diff --git a/docs/site/readiness.json b/docs/site/readiness.json index 0340b379c..c664f72a6 100644 --- a/docs/site/readiness.json +++ b/docs/site/readiness.json @@ -436,7 +436,7 @@ } ], "gates": [ - {"id": "G00", "name": "Source-of-truth integrity", "area": "governance", "state": "blocked", "blocking": true, "summary": "The validated readiness contract now owns public status and metrics, while stale repository documentation generators still prevent this gate from passing.", "acceptanceCriteria": ["One validated readiness contract owns public status", "All numeric claims are generated", "Documentation health is current", "Regeneration is deterministic and clean"], "evidence": [{"type": "document", "path": "docs/status/PROJECT_STATUS.md", "label": "Stale status snapshot"}, {"type": "document", "path": "docs/plans/FEATURE_ROADMAP.md", "label": "Roadmap snapshot"}], "blockingWorkItemIds": ["DOC-410"]}, + {"id": "G00", "name": "Source-of-truth integrity", "area": "governance", "state": "blocked", "blocking": true, "summary": "Status, roadmap, module counts, test counts, and generated documentation contradict or trail the repository.", "acceptanceCriteria": ["One validated readiness contract owns public status", "All numeric claims are generated", "Documentation health is current", "Regeneration is deterministic and clean"], "evidence": [{"type": "document", "path": "docs/status/PROJECT_STATUS.md", "label": "Stale status snapshot"}, {"type": "document", "path": "docs/plans/FEATURE_ROADMAP.md", "label": "Roadmap snapshot"}], "blockingWorkItemIds": ["RDY-000", "DOC-410"]}, {"id": "G01", "name": "Fail-closed CI evidence", "area": "ci", "state": "blocked", "blocking": true, "summary": "Required jobs can mask failures or remain advisory; docs-only changes can bypass the engine evidence path.", "acceptanceCriteria": ["Required commands propagate failure", "Every Working commit receives normalized evidence", "Advisory lanes are not represented as support gates", "JUnit and gate summaries attach to the exact SHA"], "evidence": [{"type": "workflow", "path": ".github/workflows/build.yml", "label": "Build workflow"}], "blockingWorkItemIds": ["CI-100", "CI-110"]}, {"id": "G02", "name": "Supported build matrix", "area": "build", "state": "blocked", "blocking": true, "summary": "The intended configurations and module/tool targets are not all built as required, reproducible gates.", "acceptanceCriteria": ["Declared host/compiler configurations configure and build from clean checkout", "Every shipped target and real module library is built", "Shipping configuration exists and is distinct from Debug/Release", "Submodule/toolchain inputs are pinned"], "evidence": [{"type": "workflow", "path": ".github/workflows/build.yml", "label": "Build matrix"}, {"type": "source", "path": "CMakePresets.json", "label": "CMake presets"}], "blockingWorkItemIds": ["CI-120", "BLD-100"]}, {"id": "G03", "name": "Production-source test coverage", "area": "tests", "state": "blocked", "blocking": true, "summary": "Many module tests compile subsets or mirrored logic rather than packaged production implementations; coverage thresholds are nonblocking.", "acceptanceCriteria": ["Every real module library loads and executes in tests", "No mirror-only or tautological test satisfies release", "Coverage thresholds are explicit and enforced", "Sanitizer and concurrency lanes fail closed"], "evidence": [{"type": "source", "path": "Tests/CMakeLists.txt", "label": "Test target composition"}, {"type": "workflow", "path": ".github/workflows/build.yml", "label": "Test lanes"}], "blockingWorkItemIds": ["RDY-010", "CI-110"]}, @@ -451,7 +451,7 @@ {"id": "G12", "name": "Production multiplayer and services", "area": "networking", "state": "blocked", "blocking": true, "summary": "True independent-client, secure transport, compatibility, persistence, scale, recovery, and operations gates are missing.", "acceptanceCriteria": ["Dedicated server plus two independent clients pass authoritative gameplay", "Protocol compatibility and hostile-client suites pass", "Transactional persistence and restart/migration recovery pass", "Load, telemetry, alerts, backups, and incident drills meet budgets"], "evidence": [{"type": "source", "path": "GameModules/SparkGameMMOFPS", "label": "MMOFPS vertical slice"}], "blockingWorkItemIds": ["NET-100", "NET-110", "DATA-120", "TF-110", "TF-120", "OPS-110"]}, {"id": "G13", "name": "Game-module release profiles", "area": "modules", "state": "blocked", "blocking": true, "summary": "Only MMOFPS approaches a deep vertical slice; FPS is local-playable and the remaining modules are prototypes/templates with uneven real-source tests and assets.", "acceptanceCriteria": ["Every discovered module has a validated manifest and declared N/A dimensions", "Applicable lifecycle/gameplay/assets/persistence/AI/editor/tests reach score 3", "Modules are packaged and smoke-tested", "Prototype/template labels are generated from the contract"], "evidence": [{"type": "source", "path": "GameModules", "label": "Eleven module directories"}, {"type": "document", "path": "wiki/advanced/SparkGame-Module-Status.md", "label": "Module audit"}], "blockingWorkItemIds": ["MOD-290", "MOD-300", "MOD-310", "MOD-320", "MOD-330", "MOD-340", "MOD-350", "MOD-360", "MOD-370", "MOD-380", "MOD-390"]}, {"id": "G14", "name": "Performance, reliability, and operations", "area": "operations", "state": "blocked", "blocking": true, "summary": "Profilers exist, while representative budgets, long soaks, leak limits, crash symbolization, service telemetry, alerting, backups, and recovery drills are not release gates.", "acceptanceCriteria": ["Representative CPU/GPU/memory/load budgets are versioned", "Long soaks show bounded memory and tick/frame percentiles", "Crashes produce symbolized actionable reports", "Backups, restore, rollback, and incident drills pass"], "evidence": [{"type": "document", "path": "wiki/advanced/Performance-Profiling-Guide.md", "label": "Profiling guide"}, {"type": "source", "path": "SparkCrashReporter", "label": "Crash reporter"}], "blockingWorkItemIds": ["PERF-100", "OPS-100", "OPS-110"]}, - {"id": "G15", "name": "Documentation, legal, and support truth", "area": "governance", "state": "blocked", "blocking": true, "summary": "Website wording is generated from the tested contract, while documentation generators, clean-machine quick starts, and release legal/support review remain incomplete.", "acceptanceCriteria": ["Docs health is current and every link resolves", "License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release", "Quick starts run from clean machines", "Website wording is generated from the tested contract"], "evidence": [{"type": "document", "path": "LICENSE", "label": "License"}, {"type": "document", "path": "SECURITY.md", "label": "Security policy"}, {"type": "document", "path": "docs/README.md", "label": "Docs tooling"}], "blockingWorkItemIds": ["DOC-410", "GOV-400"]}, + {"id": "G15", "name": "Documentation, legal, and support truth", "area": "governance", "state": "blocked", "blocking": true, "summary": "Documentation generators are stale, release/security wording assumes a version line with no tag, and support/trademark/attribution decisions need a release review.", "acceptanceCriteria": ["Docs health is current and every link resolves", "License, attribution, trademark, privacy, security, support, and contribution text is reviewed for the release", "Quick starts run from clean machines", "Website wording is generated from the tested contract"], "evidence": [{"type": "document", "path": "LICENSE", "label": "License"}, {"type": "document", "path": "SECURITY.md", "label": "Security policy"}, {"type": "document", "path": "docs/README.md", "label": "Docs tooling"}], "blockingWorkItemIds": ["DOC-410", "GOV-400", "DOC-400"]}, {"id": "G16", "name": "Compatibility and migration", "area": "compatibility", "state": "blocked", "blocking": true, "summary": "SDK ABI, module, save, asset, protocol, and editor-data compatibility policies and migration tests are incomplete.", "acceptanceCriteria": ["Version contracts exist for SDK, modules, assets, saves, scenes, protocols, and scripts", "N-1 upgrade and rollback fixtures pass", "Breaking changes fail with actionable diagnostics", "Release notes enumerate migrations"], "evidence": [{"type": "source", "path": "SparkSDK", "label": "Public SDK"}, {"type": "source", "path": "SparkEngine/Source/Engine/SaveSystem/SaveSystem.h", "label": "Serialization surface"}], "blockingWorkItemIds": ["SDK-240", "SAVE-230", "NET-100", "REL-200"]}, {"id": "G17", "name": "Release rehearsal and sign-off", "area": "release", "state": "blocked", "blocking": true, "summary": "No tagged release has rehearsed every blocking gate, artifact, install, migration, rollback, documentation, and support step at one commit.", "acceptanceCriteria": ["A release candidate tag passes all blocking gates", "Artifacts are installed and upgraded on clean supported hosts", "Rollback and recovery drills pass", "Owners sign the evidence ledger before the final tag"], "evidence": [{"type": "workflow", "path": ".github/workflows/release.yml", "label": "Release workflow"}], "blockingWorkItemIds": ["REL-200"]} ], @@ -473,6 +473,6 @@ {"id": 5, "name": "Portable and modern backends", "objective": "Certify or explicitly bound Linux, macOS, D3D12, Vulkan, OpenGL, Metal, mobile, VR, and console work.", "workItemIds": ["PLT-210", "PLT-220", "PLT-230", "PLT-240", "PLT-250", "RHI-220", "RHI-225", "RHI-230", "RHI-240", "ENG-220"]}, {"id": 6, "name": "Public truth and release", "objective": "Finish governance, publish the live bundle, rehearse every gate, and cut the first evidence-backed release.", "workItemIds": ["GOV-400", "DOC-400", "REL-200"]} ], - "firstUnblockedWorkItemId": "CI-100" + "firstUnblockedWorkItemId": "RDY-000" } }