From eb4b98ff031fcffc01762a8d8acaea03dfa8f56b Mon Sep 17 00:00:00 2001 From: Giorgi Chomakhashvili <133794518+kaikisegfault@users.noreply.github.com> Date: Fri, 24 Jul 2026 22:49:28 +0200 Subject: [PATCH] chore: move heavy verification to GitHub Make GitHub-hosted runners the default for resource-heavy gates, prevent superseded workflow duplication, and require bounded monitoring plus phase-boundary process and artifact cleanup. Add a narrow idempotent local cleanup command and persist the policy in project instructions and skills. --- .agents/skills/proceed-project/SKILL.md | 20 +++++++++------ .agents/skills/verify-project/SKILL.md | 21 ++++++++++----- .github/workflows/verify.yml | 5 ++++ AGENTS.md | 27 ++++++++++++++------ docs/engineering/build-toolchain.md | 19 +++++++++++++- docs/engineering/continuation.md | 34 +++++++++++++++---------- docs/engineering/verification.md | 23 ++++++++++++++--- docs/project/current-state.md | 7 ++--- tools/clean-local.sh | 29 +++++++++++++++++++++ 9 files changed, 142 insertions(+), 43 deletions(-) create mode 100755 tools/clean-local.sh diff --git a/.agents/skills/proceed-project/SKILL.md b/.agents/skills/proceed-project/SKILL.md index 20927a9..d7c1505 100644 --- a/.agents/skills/proceed-project/SKILL.md +++ b/.agents/skills/proceed-project/SKILL.md @@ -18,14 +18,15 @@ description: Continue autonomous work in protocol-stack when the owner says "pro 6. For consensus, tokenomics, encoding, cryptography, authority, or compatibility work, invoke `change-protocol`, research alternatives, record the autonomous decision, and specify behavior first. -7. Implement the slice, run the relevant `verify-project` gates, inspect the - full diff, and update affected documentation. -8. Commit and push each independently complete, verified chunk under the +7. Implement the slice, use focused local checks, inspect the full diff, and + update affected documentation plus `current-state.md`. +8. Commit and push each clean, independently complete candidate under the configured owner identity. Do not wait for the session to end. -9. Update `current-state.md` with verified facts, evidence, blockers, and one - exact next action. -10. While execution capacity remains, repeat from step 5 with another bounded - slice. A completed slice is not a reason to yield. +9. Require the heavy `verify-project` gates on GitHub-hosted runners for that + exact commit before merge or completion. Record the results in the pull + request and repair any failure. +10. Merge and clean the completed phase, then repeat from step 5 while + execution capacity remains. A completed slice is not a reason to yield. Use meaningful issues, focused branches, and evidence-bearing PRs as defined in `AGENTS.md`. Do not manufacture activity with empty commits or vanity issues. @@ -38,4 +39,7 @@ review, or resolution of conflicting unexplained user work. Complete all other unblocked work before reporting such a blocker. Never use chat history as the authoritative handoff. Never claim continuous -background execution after the current Codex run ends. +background execution after the current Codex run ends. Never leave detached +local work running. At each phase boundary, cancel obsolete GitHub runs, audit +local processes, and remove reproducible artifacts with +`tools/clean-local.sh`. diff --git a/.agents/skills/verify-project/SKILL.md b/.agents/skills/verify-project/SKILL.md index 7d9ce63..5947279 100644 --- a/.agents/skills/verify-project/SKILL.md +++ b/.agents/skills/verify-project/SKILL.md @@ -8,19 +8,28 @@ description: Run and evaluate protocol-stack quality gates before completion, co 1. Read `docs/engineering/verification.md` and inspect the complete change. 2. Classify affected surfaces: documentation, build, kernel, protocol, persistence, adapter, network, Python model, or operations. -3. Run every available required check for those surfaces in the current working - state. Do not substitute a narrower test merely because it is faster. +3. Run lightweight and focused checks locally when they provide prompt + feedback. Push a clean candidate, then use the required GitHub-hosted + workflow jobs on that exact commit for full builds, compiler and sanitizer + matrices, fuzzing, simulations, packaging, and other heavy gates. Do not + duplicate heavy remote work locally by default. 4. For consensus-visible changes, require fixed vectors, negative and boundary cases, property invariants, and differential evidence from an independent model. 5. For untrusted bytes, require a fuzz target or a documented reason it does not apply. -6. For C/C++, require the configured compiler matrix and sanitizers when the - build bootstrap provides them. +6. For C/C++, require the configured compiler matrix and sanitizers. GitHub + Actions on the exact commit is the default evidence. Run the full matrix + locally only if the workflow is unavailable or under change, or local + reproduction is needed; record the reason. 7. Inspect the full diff, Git status, generated artifacts, documentation, and dependency changes. -8. Report exact commands and results. Distinguish passed, failed, and - unavailable checks. +8. Report exact local commands and exact GitHub check results. Distinguish + passed, failed, and unavailable checks. +9. At every phase boundary, use bounded status queries, cancel obsolete remote + runs, audit for repository build/test/watch/server processes, and remove + reproducible local artifacts with `tools/clean-local.sh`. Preserve and + investigate anything unexplained. Do not claim completion when a required check fails or cannot run. Record the gap and next action in `docs/project/current-state.md`. diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index b151bee..9a611ba 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -9,10 +9,15 @@ on: permissions: contents: read +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + jobs: linux: name: Linux x86_64 / ${{ matrix.preset }} runs-on: ubuntu-24.04 + timeout-minutes: 20 strategy: fail-fast: false matrix: diff --git a/AGENTS.md b/AGENTS.md index c22b10a..5bae0a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,8 @@ the source of truth. relevant to the next action. 4. Verify GitHub authentication, fetch and prune `origin`, then reconcile the current branch, recent commits, working tree, local and remote branches, - worktrees, active issues, and pull requests before editing. + worktrees, active issues, pull requests, GitHub Actions runs, repository + processes, and generated directories before editing. 5. Prove every retained local branch has an upstream and identify any divergence or uncommitted work. Do not assume a VS Code branch list or a previous handoff is current. @@ -65,13 +66,23 @@ test evidence, then repair the state document. - Prioritize implementation and integration over process artifacts. Add only the design record and risk-proportionate tests needed to make behavior auditable and safe. -- During implementation, iterate with the smallest relevant build and focused - tests. Run the complete required compiler/sanitizer matrix once the slice is - ready to commit or merge rather than repeatedly rebuilding every environment. - Required completion gates remain mandatory. -- Remove redundant generated build trees and caches after their evidence has - been recorded. Report handoffs as: what works now, the nearest actual - outcome, and the remaining gap. +- During implementation, use only lightweight or focused local checks needed + for prompt feedback. Push a clean candidate and use GitHub-hosted Actions on + that exact commit as the default execution site for full builds, compiler and + sanitizer matrices, fuzzing, simulations, packaging, and other heavy work. + Run a heavy gate locally only when the workflow is unavailable or under + change, or when reproducing a failure requires it; record why. Do not + duplicate the full remote matrix locally by default. Required completion + gates remain mandatory. +- Never launch repository work as a detached or unattended local process. + Prefer bounded GitHub status queries over persistent local watchers. Before + each phase boundary and handoff, prove no repository build, test, monitor, + server, or helper process remains; cancel obsolete remote runs; and remove + reproducible build trees, caches, temporary files, merged branches, and stale + worktrees. Use `tools/clean-local.sh` after preserving required evidence and + inspect anything outside its narrow known-path scope rather than deleting it + blindly. Report handoffs as: what works now, the nearest actual outcome, and + the remaining gap. ## Architectural constraints diff --git a/docs/engineering/build-toolchain.md b/docs/engineering/build-toolchain.md index 4ec9264..a30e770 100644 --- a/docs/engineering/build-toolchain.md +++ b/docs/engineering/build-toolchain.md @@ -32,7 +32,10 @@ PROTOCOL_STACK_PRESET=clang-debug tools/verify.sh PROTOCOL_STACK_PRESET=clang-sanitizers tools/verify.sh ``` -CI runs all four presets. +CI runs all four presets. This GitHub-hosted matrix is the normal completion +path. Avoid rebuilding all four presets locally by default; use a focused +local target only when it materially improves iteration, and reserve a local +full matrix for workflow changes, unavailable CI, or failure reproduction. ## What the command does @@ -71,6 +74,20 @@ differ. CMake and Ninja wheel downloads may be served from pip's normal user download cache, but their contents are still checked against the committed hashes. +After a phase's evidence is recorded and no local verification process is +running, remove the known reproducible repository artifacts: + +```sh +tools/clean-local.sh +``` + +The command deletes only the four committed preset trees, the isolated +repository toolchain, and Python bytecode caches under `tools/` and `tests/`. +It does not kill processes or delete unexplained files. Audit and resolve those +separately. GitHub-hosted runners are ephemeral; obsolete or superseded runs +must still be cancelled, and workflow concurrency should prevent duplicate +runs for the same branch or pull request. + ## Dependency inventory ADR 0005 records the build-tool and cryptographic dependency inventory. ADR diff --git a/docs/engineering/continuation.md b/docs/engineering/continuation.md index a9d0c72..f14825a 100644 --- a/docs/engineering/continuation.md +++ b/docs/engineering/continuation.md @@ -30,15 +30,18 @@ When the owner says `proceed`, the session should: 4. Select the nearest runnable vertical outcome that materially advances the first operational goal. 5. Write or update a specification before consensus-critical code. -6. Implement using focused checks, then inspect and document the slice. -7. Run the required completion matrix once the slice is coherent. -8. Commit and immediately push each atomic verified chunk or tightly coupled - pair. -9. Update `current-state.md` with what works, the remaining gap, and the exact +6. Implement using focused local checks, then inspect and document the slice. +7. Update `current-state.md` with what works, the remaining gap, and the exact next outcome. -10. Open and merge reviewable PRs when their evidence gates pass, update local - `main`, then remove merged or obsolete local/remote branches, worktrees, - stale refs, and generated build copies after proving that no required +8. Commit and immediately push each clean atomic candidate or tightly coupled + pair. +9. Run the required heavy completion matrix on GitHub-hosted Actions for that + exact commit, record its terminal results in the pull request, and repair + any failure. +10. Merge reviewable PRs when their evidence gates pass, update local `main`, + cancel obsolete remote runs, audit local repository processes, then remove + merged or obsolete local/remote branches, worktrees, stale refs, temporary + files, caches, and generated build copies after proving that no required unique work remains. 11. Continue with another bounded slice while time, context, and tools remain. @@ -74,11 +77,16 @@ outcome. Prefer production code and runnable integration over speculative frameworks, redundant test environments, or documentation that does not clarify implemented behavior. -Use the smallest relevant build and test while iterating. The repository's -compiler and sanitizer matrix remains a completion gate, but it should run -after a slice is coherent rather than after every small edit. Once evidence is -recorded, remove redundant build trees and dependency caches that can be -reproduced by `tools/verify.sh`. +Use the smallest relevant local check while iterating. The repository's +compiler and sanitizer matrix remains a completion gate, but GitHub-hosted +Actions on the exact candidate commit are its default execution site. Do not +duplicate the heavy matrix locally without a concrete workflow or diagnostic +reason. + +Never detach repository work or leave a local watcher, server, build, test, or +helper running across a phase boundary. Once evidence is recorded, use bounded +status checks, cancel obsolete GitHub runs, audit local processes, and run +`tools/clean-local.sh`. Resolve unexplained artifacts individually. A finished branch is not durable project state. Merge it when its evidence gates pass, then delete local and remote branch references and any linked diff --git a/docs/engineering/verification.md b/docs/engineering/verification.md index 4680459..9b3d0b1 100644 --- a/docs/engineering/verification.md +++ b/docs/engineering/verification.md @@ -31,6 +31,21 @@ UndefinedBehaviorSanitizer builds. The current suite includes unit and boundary tests, deterministic properties, 10,000 seeded differential sequences, and bounded libFuzzer smoke under the Clang sanitizer preset. +## Execution policy + +GitHub-hosted Actions on the exact pushed commit are the default completion +site for full builds, compiler and sanitizer matrices, fuzzing, simulations, +packaging, and other resource-heavy gates. Locally, run only the lightweight +or focused checks needed for prompt feedback. Do not duplicate a green remote +matrix locally unless the workflow is unavailable or under change, or a remote +failure must be reproduced; document that exception. + +Do not detach local repository commands or leave persistent check watchers, +servers, or helpers. Use bounded GitHub status queries. At every completed +phase, confirm the exact remote jobs are terminal, cancel obsolete runs, audit +local processes, preserve evidence, and run `tools/clean-local.sh`. Inspect +unexplained processes or files individually rather than deleting them. + As production surfaces are added, this same entry point will expand to orchestrate: @@ -44,7 +59,7 @@ documented. ## Evidence rule -Do not claim a check passed without running it in the current working state. -Record the exact command and concise result in the relevant PR or -`current-state.md`. If a required check cannot run, describe why and do not -silently downgrade the definition of done. +Do not claim a check passed without exact local output or a terminal GitHub +check on the current commit. Record the exact command or check and concise +result in the relevant PR or `current-state.md`. If a required check cannot +run, describe why and do not silently downgrade the definition of done. diff --git a/docs/project/current-state.md b/docs/project/current-state.md index e97b34c..4c2318a 100644 --- a/docs/project/current-state.md +++ b/docs/project/current-state.md @@ -186,9 +186,10 @@ the active roadmap slice. exactly with materialized state and metadata. Snapshot rows remain refused. - The owner prefers one active delivery branch, cleanup of obsolete branches/worktrees/build trees at phase boundaries, focused checks while - iterating, one required completion matrix, and runnable vertical outcomes - over speculative process work. `AGENTS.md` and the continuation guide record - that durable workflow. + iterating, GitHub-hosted execution for heavy gates, no detached local work, + process and remote-run audits, and removal of reproducible local artifacts + after every completed phase. `AGENTS.md`, the project skills, and the + engineering guides record that durable workflow. - GitHub is the strict durable publication boundary: every retained branch must be clean and equal to its upstream at handoff; completed PRs must be merged and pruned; local `main` must equal `origin/main`; and only `main` plus one diff --git a/tools/clean-local.sh b/tools/clean-local.sh new file mode 100755 index 0000000..04bb670 --- /dev/null +++ b/tools/clean-local.sh @@ -0,0 +1,29 @@ +#!/bin/sh +set -eu + +repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd) + +clean_tree() { + target=$1 + if [ -e "$target" ]; then + find "$target" -depth -delete + fi +} + +clean_tree "$repo_root/out/build/gcc-debug" +clean_tree "$repo_root/out/build/gcc-sanitizers" +clean_tree "$repo_root/out/build/clang-debug" +clean_tree "$repo_root/out/build/clang-sanitizers" +clean_tree "$repo_root/.cache/toolchain-linux-x86_64" + +for python_root in "$repo_root/tools" "$repo_root/tests"; do + find "$python_root" -type f \ + \( -name '*.pyc' -o -name '*.pyo' \) -delete + find "$python_root" -depth -type d -name __pycache__ -empty -delete +done + +rmdir "$repo_root/out/build" 2>/dev/null || true +rmdir "$repo_root/out" 2>/dev/null || true +rmdir "$repo_root/.cache" 2>/dev/null || true + +printf '%s\n' "Removed known reproducible local artifacts."