feat: mine reusable AeroSim channel lessons

2026-09-10 11:41:25 +00:00
parent fad0703294
commit 31088a5ed8
11 changed files with 670 additions and 2 deletions
@@ -0,0 +1,39 @@
+# Gitea Actions evidence triage
+
+Use this when a documentation PR or default-branch Action is marked failed but repository validation succeeds locally. The goal is to distinguish code/content failure from runner infrastructure failure without weakening the exact-head gate.
+
+## Evidence sequence
+
+1. Record the remote default branch SHA and, for a PR, its exact remote head/base SHAs. Do not validate an unpushed local commit as though it were the PR artifact.
+2. Query the repository Action tasks and identify the entry whose `head_sha` exactly matches the commit under review. Preserve task ID, run number, status, and run URL. Treat the tasks endpoint as paginated: a small `limit` can omit an older still-valid exact-head task after other branches produce newer runs. Increase the limit or paginate before declaring that exact-head CI is absent; if a prior report preserved a run ID, query that immutable run directly.
+3. Immediately preserve the numeric `run_id` from the matching task's run URL. Poll `/actions/runs/{run_id}` for `status` and `conclusion`, then query its jobs. Do not depend on repeatedly rediscovering the task by SHA: completed tasks may disappear from the tasks listing or be displaced by later activity even though the run remains available by ID. Gitea commonly exposes these paths:
+   - `/api/v1/repos/{owner}/{repo}/actions/tasks?limit=...`
+   - `/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}`
+   - `/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs`
+   - `/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
+4. Confirm the terminal run and every relevant job still report the exact expected `head_sha`; preserve run ID, job ID, conclusion, timestamps, and step conclusions. If a tasks-list poll returns empty after previously finding the match, query the preserved run ID before concluding that CI evidence is missing.
+5. Determine the earliest failed phase:
+   - checkout or later command output with a repository error: content/build evidence;
+   - image pull/container creation/runner startup with no checkout or repository command: infrastructure evidence;
+   - timeout/cancellation: report the last completed phase and do not infer repository failure.
+6. Independently validate the exact remote commit in a clean detached checkout/worktree using the repository's frozen-lockfile install, full validator/test/typecheck/build command, and `git diff --check`.
+7. Report remote CI and local validation separately. A local pass does not turn remote exact-head CI green; an infrastructure failure does not prove the repository content failed.
+8. Keep the verdict `partially in sync` when required remote build/render evidence is unavailable or failed, unless project policy explicitly allows a different disposition. State the smallest remediation: rerun exact-head CI or repair runner infrastructure, then re-read the remote terminal result.
+
+## Concurrent-branch safety
+
+If another channel worker is actively correcting the same PR branch:
+
+- do not create a competing Architecture PR;
+- compare the remote PR head with local work before making claims;
+- describe unpushed commits or working-tree fixes as ongoing local work, never as delivered remediation;
+- wait for the corrected remote head and its own exact-head CI before completion.
+
+## Reporting checklist
+
+- default branch and SHA;
+- PR URL, head/base SHA, mergeability, and remote changed-file scope;
+- exact task/run/job IDs and failure phase;
+- clean exact-commit local command results;
+- browser/render checks performed or explicitly not rerun;
+- approval gate under the active authority contract unchanged by CI, review, merge, or local validation; treat it as human-only only when the invocation explicitly narrows authority.