feat: mine reusable AeroSim channel lessons
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: corp-v1-channel-releases
|
||||
description: "Use when operating or synchronizing a Corp v1 project's releases channel. Assesses release readiness and, only when the team requests a release, updates the Gondor v1 template source, renders it, pushes a separate branch to Gondor v1, and opens a pull request requiring team approval before deployment."
|
||||
version: 1.5.1
|
||||
version: 1.6.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
@@ -206,6 +206,19 @@ Requires separate approval for:
|
||||
- changing secrets, permissions, costs, or unrelated infrastructure;
|
||||
- destructive or irreversible operations.
|
||||
|
||||
|
||||
## Mined Project-Adoption Improvements
|
||||
|
||||
## Dedicated Project Channel Workspace
|
||||
|
||||
Every project adoption must bind this channel to a dedicated local workspace under the active working root. Keep clones, worktrees, plans, reports, screenshots, generated artifacts, retained logs, and channel inputs inside that channel root. Use run-unique or task-specific children under `workspace/`; keep durable project truth in approved repositories. A local folder boundary organizes execution only—it neither broadens authority nor replaces remote evidence. Delivery adoptions should additionally use a channel-level `cache/` for reusable pinned toolchains and dependencies, while keeping Task evidence isolated by Task.
|
||||
|
||||
## Project-Adoption Release Lessons
|
||||
|
||||
Releases—not Delivery—owns the final `TO_BE_RELEASED → DONE` transition. Apply it only after the approved release/deployment is promoted and verified. Record the actual version, immutable artifact/digest where applicable, deployment revision, runtime health, acceptance evidence, actor/time, and append-only history linkage. The exit gate is remote documentation showing `DONE` after the release-specific checks pass; merged code, green integration CI, or a published image alone is insufficient.
|
||||
|
||||
Recurring readiness work must refresh mutable owner PR heads and the latest exact-head CI tasks, prevent self-stale references to the readiness PR's own head, guard against concurrent writers, replace stale open/pending wording after merges, and verify exact remote artifact bytes before reporting. Follow [references/recurring-readiness-pr-refresh.md](references/recurring-readiness-pr-refresh.md).
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. Treating green CI as a release request.
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# Recurring release-readiness PR refresh
|
||||
|
||||
Use this procedure when an existing release-readiness PR consolidates mutable evidence from Scope, Architecture, Kanban, Delivery, or another readiness source. It prevents a successful update from publishing evidence that was already stale when committed.
|
||||
|
||||
## 1. Discover rather than hard-code
|
||||
|
||||
1. Read new activity from all six allowed project channels and enough Releases history to identify the last reported evidence window. Use a stored or artifact-derived high-watermark and paginate until that boundary is reached; a fixed latest-N sample can be filled by recurring bot reports and cannot prove that no human release request or approval occurred. Record author type and distinguish human authorization from bot summaries.
|
||||
- If no separate synchronization-state file exists, derive each channel's boundary from the last verified releases report or from the readiness artifact's channel evidence links. Do not use one global timestamp when exact per-channel message IDs are available.
|
||||
- Keep authorization coverage separate from display truncation. A collector may emit only the newest few messages for review, but its human-message count, newest-message ID, and high-watermark-reached assertion must be computed over **every fetched page**, not only the shortened digest. Record per channel: fetched oldest/newest IDs, boundary ID, whether the boundary was reached, and every human-authored message since that boundary. Refuse to claim that no human request or approval exists when any channel has not reached its verified boundary.
|
||||
- Treat a helper that only prints the newest messages as a display digest, not an authorization collector. Before relying on an existing helper, inspect its channel map and output contract: it must include General, Scope, Architecture, Kanban, Delivery, and Releases and must emit the boundary/coverage fields above. Replace or parameterize helpers that hard-code one run's PR numbers, SHAs, task IDs, or message IDs.
|
||||
2. Discover the readiness PR by purpose, changed artifact, and source branch—not by title alone.
|
||||
- If it is open and owns the same readiness page and purpose, fetch its exact remote source ref, fast-forward the clean worktree to that head, and refresh it in place.
|
||||
- If it is closed or merged, preserve it as historical evidence and create a successor branch from the freshly fetched default branch. Never revive or append commits to the old review branch merely because that ref still exists remotely.
|
||||
- Open Scope, Architecture, Kanban, or Delivery PRs remain independent evidence sources. Do not stack the readiness artifact onto one of those branches unless that PR already owns the readiness page and purpose.
|
||||
3. Resolve every cited PR from the Gitea API. Record its state, merged flag, head/base refs, full head/base SHAs, merge commit when applicable, and URL. Treat a closed PR's source-head CI as historical source validation; use the final default-branch SHA and exact-SHA task as the current merged baseline.
|
||||
4. Query Actions tasks and select the latest task for each exact head SHA by numeric task ID or creation time. Require terminal `success` before citing it.
|
||||
5. Read the current authoritative artifacts from the exact cited SHAs—for example Scope approval records and Kanban Board/Focus—not only from channel summaries.
|
||||
|
||||
Do not bake current PR numbers, SHAs, or task IDs into a reusable collector or verifier. Pass them through a run-specific evidence map or generated snapshot so the helper remains reusable.
|
||||
|
||||
## 2. Build a replacement map
|
||||
|
||||
Before editing, construct two explicit sets:
|
||||
|
||||
- **Required current markers:** every new full head SHA, task ID/run, and substantive decision or blocker that the refreshed page must contain.
|
||||
- **Superseded markers:** every prior SHA/task pair that must be absent after the update.
|
||||
|
||||
Replace every occurrence of an obsolete pair, including summary tables, narrative sections, dependency maps, and approval packets. Search separately for stale boundary language and old channel counts.
|
||||
|
||||
For the readiness PR itself, do not place its mutable current head SHA or exact-head task inside the artifact it owns. Report that pair externally after publication.
|
||||
|
||||
## 3. Validate and apply the pre-commit race guard
|
||||
|
||||
1. Run the repository-native full validation and `git diff --check`.
|
||||
2. Immediately before committing, re-read every cited PR and its latest exact-head task.
|
||||
3. Compare the fresh snapshot with the replacement map used in the artifact.
|
||||
4. If any head or latest task changed, update every occurrence, rerun affected validation, and repeat the guard.
|
||||
5. Confirm the local readiness branch still equals the exact remote branch head before committing; never overwrite a concurrent writer.
|
||||
|
||||
A passing build does not satisfy this guard. The guard is about evidence freshness, not syntax.
|
||||
|
||||
## 4. Publish and verify
|
||||
|
||||
1. Commit only the intended readiness artifact and push the existing review branch without force.
|
||||
2. Verify local/remote ref equality.
|
||||
3. Poll Actions for the new full readiness head and require the latest matching task to succeed.
|
||||
4. Read the artifact back through the authenticated raw API at the exact pushed SHA.
|
||||
5. Assert programmatically that every required current marker is present and every superseded marker is absent.
|
||||
6. Re-read the PR and task list once more immediately before reporting; retries can create a newer task for the same SHA.
|
||||
7. Re-scan all six allowed channels before the final report so a newly posted human release request or approval is not missed while CI was running.
|
||||
|
||||
## 5. Report the gate accurately
|
||||
|
||||
Report:
|
||||
|
||||
- no release was initiated unless an explicit human request was found;
|
||||
- current Scope lifecycle and exact Kanban `ToBeReleased`/Focus state;
|
||||
- readiness PR URL, branch, full head/base SHAs, state, merge status, and latest exact-head task;
|
||||
- validation and authenticated readback results;
|
||||
- remaining human review sequence;
|
||||
- explicit confirmation that no merge, Gondor change, release, migration, or deployment occurred.
|
||||
|
||||
Green documentation CI is planning evidence only. It is never a release request, candidate artifact, `ToBeReleased` admission, deployment approval, or proof of deployment.
|
||||
Reference in New Issue
Block a user