feat: mine reusable AeroSim channel lessons
This commit is contained in:
@@ -0,0 +1,62 @@
|
||||
# Kanban documentation bootstrap and validation
|
||||
|
||||
Use this when a project documentation site has authoritative Scope and Architecture records but no dedicated Kanban area yet.
|
||||
|
||||
## Bootstrap sequence
|
||||
|
||||
1. Start from a clean clone of the current documentation integration branch. Do not reuse a worktree with unrelated modifications.
|
||||
2. Read current Scope records plus Architecture, Delivery, Releases, and enough Kanban-channel history to establish approval and execution evidence.
|
||||
3. Add a dedicated Docusaurus docs plugin for `kanban/`, with its own `sidebarsKanban.ts`.
|
||||
4. Place the top-level Kanban navigation item immediately after Architecture and add `/kanban` to documentation search indexing.
|
||||
5. Add exactly two sidebar entries in this order: Board, Focus.
|
||||
6. Populate Board from authoritative unfinished Epic and Feature records only. Map detailed lifecycle states deterministically to `InIdeation`, `InBacklog`, `InProgress`, or `ToBeReleased` without changing source state.
|
||||
7. Populate Focus only from qualifying `InBacklog`, `InProgress`, or `ToBeReleased` evidence. An empty Focus is correct when no item qualifies; state the exact missing approval, dependency, task-definition, or execution evidence.
|
||||
8. Never create placeholder tasks to make Focus appear populated. A task needs a stable Architecture-owned ID, parent hierarchy, Feature implementation approval, and explicit exact-task human Focus admission.
|
||||
|
||||
## Recommended structural validator
|
||||
|
||||
Add a repository validation script and include it in the main validation command. Check at least:
|
||||
|
||||
- Kanban plugin, search route, and top-level navigation order;
|
||||
- dedicated sidebar containing Board then Focus;
|
||||
- all four allowed Board columns;
|
||||
- all known unfinished Epic/Feature IDs appear exactly as intended;
|
||||
- no card has a terminal authoritative source status;
|
||||
- Focus exposes only `InBacklog`, `InProgress`, and `ToBeReleased` sections;
|
||||
- Focus preserves the exact-task human admission rule.
|
||||
|
||||
Avoid naïve substring checks when explanatory prose names excluded states. Validate headings or structured fields instead—for example, reject an `## InIdeation` Focus section rather than rejecting every occurrence of the word `InIdeation`.
|
||||
|
||||
## Verification and publication
|
||||
|
||||
1. Run existing Scope and Architecture validators, the Kanban validator, TypeScript checks, the strict-link Docusaurus production build, and `git diff --check`.
|
||||
2. Push a review branch; do not merge autonomously.
|
||||
3. Open or update the existing PR against the integration branch; do not create a duplicate PR for the same review branch.
|
||||
4. Fetch the remote, verify the local and remote branch SHAs match, and confirm the worktree is clean.
|
||||
5. Read Board, Focus, sidebar, and config back from the exact remote commit. A deterministic local/remote comparison is:
|
||||
- `git show origin/<BRANCH>:kanban/board.md | sha256sum` versus `sha256sum kanban/board.md`;
|
||||
- repeat for `kanban/focus.md` and any changed structural files.
|
||||
6. Read the PR remotely and confirm `state`, `merged`, `mergeable`, `head.sha`, and `base.sha`. Private Gitea repositories may return `404` to unauthenticated API requests; use an already configured runtime credential in memory without printing, exporting, or placing it on the command line. Treat a credentialed read as verification, not permission to merge.
|
||||
7. Wait for an Actions run whose `head_sha` exactly matches the PR head and require `status=completed` plus `conclusion=success`; do not transfer CI results from another SHA.
|
||||
8. Report paths, PR, commit, exact-head run ID, source message IDs, admission decisions, and unresolved gates.
|
||||
|
||||
### Safe private-Gitea read pattern
|
||||
|
||||
For a private repository, resolve the active profile environment path, load only the configured Gitea token inside a short-lived process, and send it in an in-memory authorization header. Output only non-secret fields. Query:
|
||||
|
||||
- `/api/v1/repos/<OWNER>/<REPO>/pulls/<NUMBER>` for PR state and exact head/base SHAs;
|
||||
- `/api/v1/repos/<OWNER>/<REPO>/actions/runs?limit=<N>` for recent run IDs, head SHAs, status, conclusion, and event.
|
||||
|
||||
Never print the token, headers, environment file contents, exception request objects, or response bodies that may echo credentials. An unauthenticated `404` followed by a successful credentialed read means the repository is private; it is not evidence that the endpoint is absent.
|
||||
|
||||
## Evidence pattern for an empty Focus
|
||||
|
||||
Record each ownership boundary explicitly:
|
||||
|
||||
- Scope: Epic/Feature state remains Proposed or otherwise outside active Focus.
|
||||
- Architecture: no stable implementation task and/or no Approved-for-Implementation evidence.
|
||||
- Kanban: no explicit human admission for an exact task.
|
||||
- Delivery: no verified execution evidence.
|
||||
- Releases: no verified release handoff.
|
||||
|
||||
This turns an empty Focus into a useful gate report rather than filler.
|
||||
@@ -0,0 +1,215 @@
|
||||
# Recurring Kanban refresh and publication
|
||||
|
||||
Use this runbook when an existing Board/Focus review branch must absorb newer same-project evidence without changing approval-gated state.
|
||||
|
||||
## 1. Discover substantive deltas
|
||||
|
||||
1. Fetch a compact recent digest from only the seven 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.
|
||||
|
||||
## 2. Verify mutable repository evidence
|
||||
|
||||
Before editing, query every cited open PR and Actions task through the authenticated API. Record state, merged flag, mergeability, head/base SHA, and the latest task matching each exact head SHA. Also re-read every mutable issue, comment, or incident record whose open/closed status or resolution is asserted by Board or Focus; a channel report is provenance for the transition, not a substitute for current repository state.
|
||||
|
||||
Fetch all relevant branch refs explicitly. For the Kanban branch, require zero local/remote divergence before editing. For other owning branches, inspect the material change between the previously cited and current heads; do not merely replace a SHA when the newer commit changes the approval package, dependency conditions, stable approval identity, gate ownership, or review sequence.
|
||||
|
||||
Keep merged owning records authoritative. Describe open Scope or Architecture changes as pending review evidence, even when exact-head CI succeeds.
|
||||
|
||||
### Repository head advances before its channel report
|
||||
|
||||
Concurrent scheduled writers can push an owning PR and complete exact-head CI before their substantive channel summary is delivered. Handle this publication lag explicitly:
|
||||
|
||||
1. Re-read the owning channel briefly or perform a bounded poll; do not wait indefinitely for a report.
|
||||
2. If no new substantive message appears, inspect the exact intervening commits and diff from the previously cited head to the verified current PR head.
|
||||
3. Record the material change as **repository-verified pending review evidence**, not as an owning-channel decision or authoritative merged state.
|
||||
4. Preserve the latest substantive owning-channel message as channel provenance for the unchanged lifecycle/gate facts; do not claim that it explains the newer commit.
|
||||
5. Say that channel and mutable repository evidence were refreshed separately when their evidence times differ.
|
||||
6. Recheck the owning head and exact-head task immediately before committing. If either changed, reconcile again rather than publishing a stale pair.
|
||||
|
||||
This pattern is especially important when a pending correction changes stable item IDs or separates lifecycle gates: surface the ambiguity it resolves, but never infer approval from a clean diff, successful CI, or the absence of a channel report.
|
||||
|
||||
### An owning-channel writer is active but has not published a review
|
||||
|
||||
A human-triggered Scope, Architecture, Delivery, or Releases interaction can remain visibly in progress while Kanban needs to reconcile already-merged evidence. Progress messages are a concurrency signal, not authoritative project state.
|
||||
|
||||
1. Perform a bounded wait and re-read the owning channel plus the repository's open PR list.
|
||||
2. If the writer publishes a review, verify its exact head and classify it as pending review evidence under the normal owning-source rules.
|
||||
3. If no review appears within the bound, continue from the verified default-branch baseline when useful Kanban maintenance is independently safe; do not wait indefinitely or invent the unpublished artifact.
|
||||
4. You may record an explicit human authorization for documentation work only when it materially explains the boundary, but label it as documentation authorization—not lifecycle, implementation, task-admission, release, or merge approval.
|
||||
5. Avoid durable claims such as “no PR exists” because the writer may publish immediately after the commit. Describe only the authoritative baseline and the approval boundary in Board/Focus; keep transient writer state in the synchronization report.
|
||||
6. In the final report, state that the owning review was not yet published at the final read. If it later shares the same base, require owning-review-first assessment and revalidate or rebase the dependent Kanban review against the resulting default-branch head.
|
||||
|
||||
This allows Kanban to remove independently false evidence without racing an unpublished owning artifact or treating interactive progress as project provenance.
|
||||
|
||||
A failed or truncated owning-channel cron report may claim that an improvement was completed locally while omitting the material diff, commit, publication state, or verification. Treat that message as a concurrency/high-watermark signal only. Re-read the owning PR and remote branch; if neither advanced, do not cite the unpublished local result or update durable Kanban state from its truncated summary. Preserve the current authenticated repository evidence and note the publication gap in the synchronization report when material.
|
||||
|
||||
### An owning channel explicitly withholds publication
|
||||
|
||||
An owning-channel job may fully validate a useful local patch but explicitly withhold commit or push because a required independent review, approval, or fail-closed publication gate was unavailable. Validation success does not make that patch repository evidence.
|
||||
|
||||
1. Re-read the complete substantive report and any later follow-up that states the final publication outcome; prefer the final explicit `not committed`, `not pushed`, or `publication withheld` message over an earlier progress summary.
|
||||
2. Query the authoritative PR and remote source ref after that follow-up. If they did not advance, retain their verified remote head and exact-head CI as current evidence.
|
||||
3. Record the local work only as a **publication gap** when it materially clarifies missing reconciliation; do not copy its proposed records, statuses, IDs, or acceptance claims into Board or Focus.
|
||||
4. Link the final withholding message as provenance for the gap, while using repository readback—not the message—for the unchanged PR head and CI facts.
|
||||
5. Keep all product, implementation, Focus-admission, and release states unchanged. A locally passing build or frozen diff hash satisfies none of those gates.
|
||||
6. Route the owning artifact through a later reviewed publication cycle. If it eventually advances, inspect the intervening diff and refresh both Board and Focus under the normal pending-review rules.
|
||||
7. When that later publication closes the gap, remove every stale current-state phrase that still says the refinement is local, uncommitted, unpushed, withheld, or blocked on reviewer availability. Replace it in both artifacts with the substantive owner-channel publication report, verified current PR head, and latest exact-head task; preserve the earlier withholding message only as clearly labeled history when it still explains the review sequence.
|
||||
8. Treat publication-gap closure as a material evidence change even when lifecycle and Focus remain unchanged. Verify exact-commit readback contains the published head/task and no longer contains the superseded current-state wording.
|
||||
|
||||
This distinction prevents well-validated but unpublished Scope or Architecture work from silently becoming Kanban truth, and prevents a later successful publication from leaving Board and Focus falsely blocked on a gap that no longer exists.
|
||||
|
||||
### Another Kanban writer is already active
|
||||
|
||||
A recurring run can overlap a human-triggered Kanban readiness repair. Use this adoption sequence rather than racing it:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Do not treat interactive progress/tool messages as project evidence. A human request to check or repair documentation authorizes the reviewable documentation repair, not lifecycle approval, Focus admission, merge, release, or deployment.
|
||||
|
||||
### The Kanban review merges while the recurring run is active
|
||||
|
||||
A human may merge the Kanban review—and related owning reviews—after exact-head verification but before the recurring run reports. Treat the final repository read as a new synchronization boundary, not a ceremonial check:
|
||||
|
||||
1. Re-read the Kanban PR, every cited owning PR, the default-branch ref, and exact-head task list after CI and immediately before reporting.
|
||||
2. If the Kanban PR merged, stop writing to its source branch. Fetch the new default branch and inspect the first-parent merge sequence plus the combined artifact diff.
|
||||
3. If Board or Focus now contains stale `open`, `pending review`, old-base, or review-order language, create one new follow-up branch from the verified final integration head. Do not amend or revive the merged source branch.
|
||||
4. Record the merge commits in order and require successful CI for the exact final integration head; source-branch CI alone does not validate the merge chain.
|
||||
5. Refresh Board and Focus together, preserve lifecycle and task-admission gates, and label repository facts separately when owning-channel completion reports have not yet appeared.
|
||||
6. Perform another final PR/default-branch read before reporting in case the follow-up also merged.
|
||||
|
||||
This bounded repair is warranted even when no product state changed: removing already-false pending-review evidence is a material Kanban maintenance improvement.
|
||||
|
||||
### Reconciling a stale Kanban branch after an owning merge
|
||||
|
||||
When an owning merge introduces a newer data model, generated renderer, validator, or file format while the Kanban branch still contains hand-maintained Board/Focus content, resolve the integration semantically rather than selecting the old Kanban side wholesale:
|
||||
|
||||
1. Fetch and assert the exact remote Kanban parent and new default head before starting the merge.
|
||||
2. Merge the new default into the existing Kanban review without rebasing or force-pushing.
|
||||
3. For conflicted Board/Focus files, begin from the integrated default version so canonical components, generated data, renamed files, and strengthened validators are preserved; then reapply only the still-valid Kanban reconciliation and gate evidence.
|
||||
4. Do not restore a manual card table when the owning merge replaced it with a validated data-backed renderer. Keep mutable lifecycle state canonical and limit Markdown to mapping, gate explanation, provenance, and dated reconciliation evidence.
|
||||
5. Expect the merge commit to stage all incoming owning changes. Review the Kanban diff against the integrated default separately from the full staged merge diff so inherited owning changes are not mistaken for new Kanban authorship.
|
||||
6. If the merge adds dependencies or changes the lockfile, install from that exact lockfile before validation, then run the complete data, test, Scope, Architecture, Kanban, type, strict-build, and diff checks.
|
||||
7. Immediately before commit, re-read channel high-watermarks, owning PR heads, the default head, and the remote Kanban parent. Abort if either parent advanced.
|
||||
8. After the normal push, require a new exact-head task for the merge commit and authenticated readback proving the canonical renderer remains present and stale pre-merge phrases are absent.
|
||||
|
||||
Also preserve per-channel authority when reports straddle the merge boundary. For example, a Releases message published before an owning merge can still prove that no release was requested, but its transient statement that no PR merged must not be repeated after repository readback proves otherwise.
|
||||
|
||||
### High-watermarks that are not project evidence
|
||||
|
||||
Newer messages can be channel-skill synchronization requests, governance notices, job-management text, tool traces, or self-improvement reports. Keep their IDs as polling high-watermarks if needed, but retain the newest substantive project message as provenance. These notices do not refresh an artifact's evidence date unless they contain a genuine project fact or explicit authorized human decision.
|
||||
|
||||
### Cross-channel reports disagree about mutable evidence
|
||||
|
||||
A later report in a non-owning channel can still contain an older PR head, task, or review state than the owning channel and authenticated repository. Do not choose evidence by Discord message time alone.
|
||||
|
||||
1. Resolve mutable PR state, head SHA, base SHA, merge status, and exact-head task from fresh authenticated repository readback.
|
||||
2. Use the newest substantive owning-channel message that matches that repository state as provenance when available.
|
||||
3. Keep a non-owning report only for facts that channel owns—for example, Releases may still establish that no release was requested even when its embedded Scope PR head is stale.
|
||||
4. Do not copy, cite as current, or preserve the stale mutable head/task pair merely because the non-owning report is useful for another fact.
|
||||
5. When artifacts previously embedded the stale pair, update Board and Focus together and verify exact-commit readback contains the replacement pair while the superseded current-state pair is absent.
|
||||
6. If repository state advanced beyond every channel report, apply the repository-verified pending-review procedure rather than attributing the newer commit to an older message.
|
||||
|
||||
This prevents a fresh release, delivery, or steering summary from rolling back newer Scope or Architecture evidence while preserving each channel's authoritative lifecycle facts.
|
||||
|
||||
### A substantive owning-channel report lands during validation
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 3. Update active views
|
||||
|
||||
Refresh Board and Focus together when evidence affects both:
|
||||
|
||||
- advance the evidence date only to the newest substantive evidence actually represented;
|
||||
- summarize the material gate change, not just the new mutable SHA/task pair;
|
||||
- preserve Scope-owned lifecycle and dependencies until owning changes merge;
|
||||
- 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;
|
||||
- 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.
|
||||
|
||||
Do not embed the Kanban PR's own head as a durable current-head claim. Report it only after publication.
|
||||
|
||||
### Owner reviews advance without changing flow state
|
||||
|
||||
A General, Scope, Architecture, Delivery, or Releases review may advance after the latest Kanban publication while preserving every lifecycle and admission gate. Treat this as material evidence maintenance when Board or Focus still names the superseded head, task, or substantive channel report:
|
||||
|
||||
1. Re-read the new owner report and its continuation companion at full length, then verify the current PR head and latest exact-head task independently.
|
||||
2. Inspect the intervening diff from the head currently cited by Kanban. Summarize the actual evidence change—such as a refreshed runtime checkpoint, resolved publication gap, or revised review order—instead of performing a SHA-only replacement.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### An owning proposal receives a newer cross-domain exact-head review
|
||||
|
||||
A materially advanced owning PR may be followed by a substantive report from another owning channel that independently validates its exact head and explains the impact on that channel's domain. Preserve both roles instead of collapsing them into one provenance claim:
|
||||
|
||||
1. Cite the originating owner-channel publication for what the proposal changes and for its lifecycle boundary.
|
||||
2. Cite the cross-domain review only for the independent exact-head validation and domain-specific impact it actually assessed.
|
||||
3. Resolve the mutable head, PR state, and latest exact-head task from authenticated repository readback rather than either message.
|
||||
4. Advance the Board and Focus evidence-through time to the newer cross-domain report only when its findings are represented in both artifacts.
|
||||
5. Keep the proposal pending review and preserve all approval gates; an independent review, successful CI, or cross-domain compatibility finding is not merge, lifecycle approval, implementation approval, or Focus admission.
|
||||
6. In post-push readback, require both the new owner head/task pair and the cross-domain substantive message marker, and forbid the superseded current-state head/task pair in both Board and Focus.
|
||||
|
||||
This three-part attribution—originating owner, independent domain reviewer, authenticated repository—keeps proposal authorship, impact assessment, and mutable state distinct while allowing Kanban evidence to converge promptly.
|
||||
|
||||
### Live deployment evidence without a governed item mapping
|
||||
|
||||
A live, healthy service can be materially newer than the approved product hierarchy. When this happens, improve Board and Focus by recording the real operational boundary without fabricating flow state:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
This pattern makes verified execution visible while preventing an already-running deployment from retroactively manufacturing product approval, task admission, or release state.
|
||||
|
||||
## 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.
|
||||
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`.
|
||||
- The Actions task-list response may be an object whose records are under `workflow_runs`, not a top-level list or `entries`/`data`. Inspect response keys before concluding that no tasks exist.
|
||||
- Distinguish the task-list `id` and `run_number` from workflow-run IDs or build/job IDs quoted in channel reports. Resolve current CI fields from authenticated API readback and do not copy a mismatched channel label into Board or Focus.
|
||||
- A repository token can be present in the live process environment even when it is absent from the active profile environment file. Check key presence without printing values, then use the narrowly scoped credential in memory. Do not infer API unavailability from the profile file alone or attempt to extract an API token from an SSH remote URL.
|
||||
6. Perform one final API/readback check after CI to detect a concurrent update.
|
||||
7. Any short-lived authenticated helper must parse credentials in memory, print only non-secret evidence, and be removed after verification. Never discover credential names with a content search over `.env` files because match output can expose the full assignment; check key presence in a trusted process instead. If bulk cleanup is blocked by a safety guard, remove helpers individually or leave them non-secret and report the cleanup exception rather than requesting destructive bypass.
|
||||
|
||||
## 5. Report
|
||||
|
||||
The synchronization result should include:
|
||||
|
||||
- changed documentation paths;
|
||||
- unchanged flow/admission state or the exact human decision that changed it;
|
||||
- newest substantive channel evidence IDs;
|
||||
- current heads and exact-head CI for other relevant open PRs;
|
||||
- Kanban pushed commit, PR state, remote artifact readback, and exact-head task/run;
|
||||
- unresolved gates and human review order.
|
||||
|
||||
For scheduled delivery, return the report directly. Use `[SILENT]` only when there is no substantive delta and no useful maintenance action.
|
||||
Reference in New Issue
Block a user