docs: promote reusable AeroSim channel lessons

This commit is contained in:
jarvis-at-skic committed 2026-10-20 18:42:43 +00:00
1 parent e8507ad718
commit 26cbf12bc6
5 files changed
+113 -24

No files matched your search

@@ -4,7 +4,7 @@ Use this runbook when an existing Board/Focus review branch must absorb newer sa
## 1. Discover substantive deltas
1. Fetch a compact recent digest from only the seven authorized project channels.
1. Fetch a compact recent digest from only the eight authorized project channels.
2. Compare substantive message IDs—not delivery footers or continuation-only messages—with the evidence already cited by Board and Focus.
3. Re-read at full length any advanced substantive message and required companion. If a compact digest truncates a decision or gate explanation, do not edit from the truncated text. A direct Discord message read may itself contain a literal truncation marker when the original scheduled report exceeded the delivery boundary; treat that record as incomplete, read its numbered continuation companions, and use authenticated repository state or the exact intervening diff for facts omitted from the delivered text. Never reconstruct missing claims from the visible prefix.
4. Classify each delta as authoritative state, pending review evidence, human decision, blocker, contradiction, or boilerplate.
@@ -67,7 +67,7 @@ A recurring run can overlap a human-triggered Kanban readiness repair. Use this
1. If Kanban history shows a recent human request followed by working/progress messages, poll the Kanban channel and open-PR list for a bounded interval.
2. When a same-purpose Kanban PR appears, fetch its exact source ref and inspect its diff; do not create a second branch or PR.
3. Wait for the substantive completion message when practical, then independently verify the claimed head, PR state, remote Board/Focus bytes, and exact-head task.
4. Re-read the other six owning channels and their open PRs after the writer finishes. The first writer may have reconciled the original stale state while missing newer owning-channel follow-ups published during its run.
4. Re-read the other seven owning channels and their open PRs after the writer finishes. The first writer may have reconciled the original stale state while missing newer owning-channel follow-ups published during its run.
5. If a material omission remains, extend the existing Kanban branch only after confirming its remote ref still equals the locally verified parent. Re-run the full validation suite before committing.
6. Repeat the remote-ref equality check immediately before push. After pushing, wait for CI matched to the new head and report only that replacement head/task pair.
@@ -122,13 +122,13 @@ This prevents a fresh release, delivery, or steering summary from rolling back n
Validation can overlap another scheduled owning-channel run. A pre-edit digest is therefore not sufficient protection against publishing stale provenance.
1. After the full local validation suite and immediately before commit, perform one compact seven-channel high-watermark refresh plus authenticated repository readback.
1. After the full local validation suite and immediately before commit, perform one compact eight-channel high-watermark refresh plus authenticated repository readback.
2. If only boilerplate advanced, preserve it as a polling watermark and continue without changing the artifact evidence date.
3. If a substantive owning-channel report advanced, read the complete message and required continuation before committing. Reconcile Board and Focus again when it materially improves gate explanation, blocker classification, review sequence, or provenance.
4. If the owning PR head advanced during validation but its completion report has not arrived, inspect the exact intervening commits and material diff immediately, refresh the matching exact-head task, and apply the **repository-verified pending review evidence** boundary. Perform one short bounded channel re-read before finalizing. When the owner report then arrives, replace the temporary publication-lag wording with exact owner-report provenance; preserve an independent reviewer message only for the earlier head it actually reviewed.
5. When the new report explains a PR head that was previously classified as **repository-verified pending review evidence**, converge the label as well as the link: replace publication-lag wording with owning-channel provenance, advance the evidence-through time to the substantive report, and retain the proposal's pending-human-review status. Do not leave text claiming the head is newer than its channel report after that report has arrived.
6. Re-run the complete validation suite and production build after this reconciliation, even when only provenance labels, evidence timestamps, or mutable head/task pairs changed. Do not rely on validation performed against the superseded text.
7. Repeat both the seven-channel high-watermark check and remote-ref race assertion immediately before commit and push.
7. Repeat both the eight-channel high-watermark check and remote-ref race assertion immediately before commit and push.
This late refresh is particularly important when a newer report classifies a failed CI run. Distinguish a repository validation failure from a runner failure before Checkout or repository setup. A successful local exact-commit validation may establish that repository checks pass locally, but it does not turn a failed or absent exact-head CI task into successful CI; record both facts separately and preserve the remediation gate.
@@ -142,7 +142,7 @@ Refresh Board and Focus together when evidence affects both:
- preserve ownership qualifiers exactly: `proposed`, `not accepted`, `unassigned`, and confirmed ownership are materially different states; never shorten “proposed; not accepted” to a presentation that could imply acceptance;
- include newly opened owner-specific coordination reviews when they materially affect Board or Focus evidence—for example, a Releases review that confirms empty `ToBeReleased` and preserves release blockers—even when the flow state itself is unchanged;
- keep `InIdeation` and terminal work out of Focus;
- never admit an exact task to `InBacklog` without explicit human approval;
- never admit an exact task to `ReadyForDelivery` without explicit human approval; planned `InBacklog` visibility is not executable admission;
- preserve review ordering for prerequisite owning corrections and dependent Kanban artifacts;
- when several open reviews share the same base, record that the first merge invalidates old-base integration evidence for the remaining reviews: reconcile them to the new base and require fresh exact-head CI before dependent review or merge.
@@ -157,7 +157,7 @@ A General, Scope, Architecture, Delivery, or Releases review may advance after t
3. Refresh Board and Focus together, including their evidence-through timestamp and substantive provenance links, while leaving Board columns and Focus admission unchanged unless authoritative approval evidence independently supports a transition.
4. Replace superseded mutable head/task pairs in both artifacts. Preserve old SHAs only when clearly labeled as immutable history rather than current evidence.
5. Keep the Kanban review's own mutable head out of the artifacts; report its new head and exact-head CI only after the update is pushed.
6. Before committing, repeat the compact seven-channel scan, owner-PR readback, and remote Kanban-parent equality check. After pushing, require authenticated exact-commit readback that proves the new pairs are present and the superseded current-state pairs are absent.
6. Before committing, repeat the compact eight-channel scan, owner-PR readback, and remote Kanban-parent equality check. After pushing, require authenticated exact-commit readback that proves the new pairs are present and the superseded current-state pairs are absent.
This maintenance is substantive even when all work remains `InIdeation` and Focus stays empty: stale mutable evidence can otherwise misroute human review or imply that a newer owner reconciliation has not happened.
@@ -181,7 +181,7 @@ A live, healthy service can be materially newer than the approved product hierar
1. Build one independently verified execution packet containing the application integration SHA, exact-head build/publish/validation tasks, immutable artifact digests when available, rendered GitOps integration revision, Argo reconciliation state, workload readiness/restarts, public route checks, and runtime image IDs.
2. Verify source-of-truth alignment separately. If rendered GitOps is merged and live while its authoritative template-source review is still open or lacks exact-head CI, expose that divergence as an unresolved blocker; do not hide it behind successful runtime checks.
3. Update Board and Focus together and label the result an **execution-to-governance contradiction** when no approved Feature and stable Architecture-owned task map the deployment into the governed hierarchy.
4. Keep Scope-owned Epic/Feature state unchanged, keep Focus empty, and keep `ToBeReleased` empty unless their normal human approval and handoff evidence exists. Operationally deployed, release-ready, governed release candidate, and released are distinct claims.
4. Keep Scope-owned Epic/Feature state unchanged for the unmapped execution; do not add it to Focus or `ToBeReleased` without normal human approval and handoff evidence, and preserve unrelated valid Focus items. Operationally deployed, release-ready, governed release candidate, and released are distinct claims.
5. Preserve broad human deployment authority as operational provenance only. It is not item-specific **Approved for Implementation**, exact-task Focus admission, version allocation, candidate selection, or release authorization.
6. Record remaining governance and release-packet gates precisely—for example approved scope, exact item mapping, version allocation, candidate selection, digest pinning, changelog, migration assessment, rollback ownership, and source-template review—rather than saying only that “governance remains.”
7. After publication, repeat public health checks and authenticated repository/PR readback, but report the Kanban PR's own exact head and CI only in the synchronization result.
@@ -191,7 +191,7 @@ This pattern makes verified execution visible while preventing an already-runnin
## 4. Validate and publish safely
1. Run Scope, Architecture, and Kanban validators, TypeScript checks, the strict-link production build, and `git diff --check`.
2. Refresh the seven channel high-watermarks and authenticated repository state as described above, then fetch the intended Kanban source ref immediately before commit; abort or reconcile if any substantive evidence or remote ref advanced.
2. Refresh the eight channel high-watermarks and authenticated repository state as described above, then fetch the intended Kanban source ref immediately before commit; abort or reconcile if any substantive evidence or remote ref advanced.
3. Prefer adopting and extending an existing same-purpose Kanban review branch. If no same-purpose branch or PR exists after a bounded Kanban-history and open-PR check, create exactly one review branch from the verified default head, push it, and open one PR. Never create a competing or duplicate review.
4. Verify local HEAD equals the remote source ref and read Board/Focus back from that exact commit. Prefer an authenticated contents-API read at `ref=<exact pushed SHA>`, decode the returned bytes, require byte equality with both local artifacts, and report their hashes. Do not rely on `git status` alone: when a local branch tracks a fetched alias rather than the actual PR source ref, a successful push can leave that alias stale and misleadingly report the branch as `ahead 1`. Resolve equality from the exact source ref via authenticated PR readback or `ls-remote`, then explicitly refresh any local alias if it is still needed.
5. Re-query the PR and Actions tasks after pushing. Wait for a terminal task whose `head_sha` equals the pushed commit; never reuse CI from the preceding head. On Gitea/Forgejo, treat the task's terminal `status` (`success`, `failure`, `cancelled`, or `skipped`) as authoritative when `conclusion` is absent or null; always report the exact task ID, run number, and matched `head_sha`.