From 26cbf12bc6e5555a0f816d7a0e1f5d13cf453a8d Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Tue, 20 Oct 2026 18:42:43 +0000 Subject: [PATCH] docs: promote reusable AeroSim channel lessons --- SKILL.md | 32 +++++++++----- references/aerosim-lessons-review.md | 35 +++++++++++++++ references/kanban-bootstrap-and-validation.md | 10 ++--- .../recurring-refresh-and-publication.md | 16 +++---- tests/test_contracts.py | 44 +++++++++++++++++++ 5 files changed, 113 insertions(+), 24 deletions(-) create mode 100644 references/aerosim-lessons-review.md create mode 100644 tests/test_contracts.py diff --git a/SKILL.md b/SKILL.md index e7680f6..fec5402 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-kanban -description: "Use when operating or synchronizing a Corp v1 project's Kanban channel. Maintains Board and Focus across Epic, Feature, and task state; correlates all seven same-project channels; and records exact admission before tasks enter the READY_FOR_DELIVERY pickup queue." -version: 1.7.0 +description: "Use when operating or synchronizing a Corp v1 project's Kanban channel. Maintains Board and Focus across Epic, Feature, and task state; correlates all eight same-project channels; and records exact admission before tasks enter the READY_FOR_DELIVERY pickup queue." +version: 1.8.0 author: Hermes Agent license: MIT metadata: @@ -18,7 +18,7 @@ metadata: Whenever a response mentions a Hermes Kanban board, initiative, card, or task, it must include a direct dashboard link in the form `[descriptive board label](/kanban?board=)`. Resolve the dashboard public URL and exact board slug before reporting; never provide only a board name, slug, card count, “visible cards,” or “available in the dashboard.” If no task-specific deep link exists, link the board and include the exact task ID or title in the same statement. Project-adopted skills must replace this generic form with their verified project board URL. -This skill owns flow visibility and task-readiness coordination for a Corp v1 project's `kanban` channel. It monitors the seven same-project channels—`general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, and `releases`—and maintains the project documentation's top-level **Kanban** area. +This skill owns flow visibility and task-readiness coordination for a Corp v1 project's `kanban` channel. It monitors the eight same-project channels—`general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, `uat`, and `releases`—and maintains the project documentation's top-level **Kanban** area. Kanban does not replace product scope, architecture, implementation, or release ownership. Scope owns Roadmap, Ideas, Epics, and Features; Architecture owns requirements, design, task decomposition, dependencies, implementation approval, and version allocation; Kanban exposes flow and records the exact admission that moves an eligible task to Focus `READY_FOR_DELIVERY`; Delivery claims that task and records `IN_PROGRESS`; Releases owns release readiness and controlled release preparation. @@ -75,6 +75,8 @@ This execution boundary was approved by RootAtSkic (`discord:1518725627845283888 ## Approved Information Boundary +Follow the eight-channel topology in `corp-v1-main`, approved by Board message `1552966246591365123`; include UAT between Delivery and Releases. Verify mapped IDs and effective access before reading. + Inspect only: ```text @@ -84,10 +86,11 @@ corp-v1--architecture corp-v1--ui-ux corp-v1--kanban corp-v1--delivery +corp-v1--uat corp-v1--releases ``` -Read enough mapped-channel history to avoid duplicates and only relevant new activity from the other six channels. Never inspect or correlate another project's channels. +Read enough mapped-channel history to avoid duplicates and only relevant new activity from the other seven channels. Never inspect or correlate another project's channels. ## Human Approval Gate @@ -116,7 +119,7 @@ Focus ### Board -Board provides a visual board of all unfinished Epics and Features grouped into these flow columns. `ReadyForDelivery` is the presentation mapping of canonical delivery status `READY_FOR_DELIVERY`; do not create aliases such as `READY` or `QUEUED`: +Board provides a visual board of all unfinished Epics and Features grouped into these flow columns. `ReadyForDelivery` represents the exact-task `READY_FOR_DELIVERY` admission gate, separate from Scope-owned canonical delivery status; do not create aliases such as `READY` or `QUEUED`: 1. `InIdeation` 2. `InBacklog` @@ -134,7 +137,7 @@ Board statuses mean: - `InProgress` — active solution or implementation work exists. - `ToBeReleased` — implementation is complete enough for release readiness; release approval and execution remain separate. -If source lifecycle states are more detailed, maintain an explicit deterministic mapping to these four board states. Never change authoritative approval history merely to simplify Board display. +If source lifecycle states are more detailed, maintain an explicit deterministic mapping to these five board columns. Never change authoritative approval history merely to simplify Board display. ### Focus @@ -186,10 +189,15 @@ Use authoritative ownership: - requirements, architecture, task definitions/dependencies, implementation approval, version allocation → Architecture; - exact `READY_FOR_DELIVERY` Focus admission decision → Kanban human decision; - task execution progress and completion evidence → Delivery; +- frozen-deployment acceptance verdict and defect-return evidence → UAT; - release readiness, released state, and post-release outcome → Releases. When sources conflict, do not choose silently. Mark the card as blocked or inconsistent, link both sources, and route the contradiction to the owning channel. +A healthy deployment without approved scope and exact-task admission is an **execution-to-governance contradiction**, not retroactive readiness. Preserve application source, deployed revision, artifact identity, runtime observations and any template/rendered-source divergence separately. Do not add the unmapped work to Focus or a release candidate; preserve unrelated valid Focus items. Route each missing decision to its owner. See [recurring refresh](references/recurring-refresh-and-publication.md#live-deployment-evidence-without-a-governed-item-mapping). + +Board columns are presentation, not a replacement lifecycle. Keep canonical delivery status, admission, approval, blocking and acceptance verdicts separate. UAT owns the evidence-grounded acceptance verdict for the frozen tested deployment; it does not create another Task status or authorize release. Read only the mapped same-project UAT channel; topology is not mutation authority. + ## Proactive Iteration Requirement Every iteration must materially improve one useful, evidence-based Kanban artifact when possible: reconcile state, remove terminal cards from Board, repair links, expose a blocker, update hierarchy, prepare a task-readiness package, record a human Focus decision, or improve stale ownership/dependency/version evidence. Never create filler or autonomously advance approval-gated state. @@ -202,9 +210,9 @@ For frontend-affecting tasks, Kanban includes the approved UI/UX design-package ## Synchronization Workflow -1. Confirm the exact project code and seven approved channel IDs. -2. Read new messages from the other six channels and enough Kanban history to avoid duplicates. -3. Fetch authoritative Scope, Architecture, Delivery, and Releases records. +1. Confirm the exact project code and eight approved channel IDs. +2. Read new messages from the other seven channels and enough Kanban history to avoid duplicates. +3. Fetch authoritative Scope, Architecture, Delivery, UAT, and Releases records. 4. Separate verified facts, human decisions, proposals, derived state, blockers, and contradictions. 5. Reconcile Board and Focus while preserving ownership and links. 6. Remove terminal Epic/Feature cards from Board and terminal items from Focus without deleting history. @@ -217,7 +225,7 @@ For frontend-affecting tasks, Kanban includes the approved UI/UX design-package May autonomously: -- read and correlate the seven same-project channels; +- read and correlate the eight same-project channels; - maintain Board and Focus from verified authoritative state; - calculate derived aggregate states when labeled; - remove terminal work from active views while preserving history; @@ -257,6 +265,8 @@ Use two-pass channel evidence collection, distinguish substantive messages from When bootstrapping or structurally repairing Kanban documentation, preserve dedicated Board/Focus information architecture, semantic empty states, fail-closed validators, exact-head CI, and authenticated artifact readback. Follow [references/kanban-bootstrap-and-validation.md](references/kanban-bootstrap-and-validation.md). +Source comparison and exclusions: [AeroSim lessons review](references/aerosim-lessons-review.md). + ## Common Pitfalls 1. Treating Kanban as a second source of truth for Scope or Architecture. @@ -273,7 +283,7 @@ When bootstrapping or structurally repairing Kanban documentation, preserve dedi ## Verification Checklist -- [ ] Only the seven same-project channels were inspected. +- [ ] Only the eight same-project channels were inspected. - [ ] The session changed no project implementation repository; project-repository writes were limited to the dedicated Kanban documentation area and its minimum required wiring. - [ ] Any implementation request was represented in planning/Board/Focus and handed to Delivery rather than executed or delegated from Kanban. - [ ] Kanban appears immediately after Architecture and has its own Board/Focus sidebar. diff --git a/references/aerosim-lessons-review.md b/references/aerosim-lessons-review.md new file mode 100644 index 0000000..169184a --- /dev/null +++ b/references/aerosim-lessons-review.md @@ -0,0 +1,35 @@ +# AeroSim lessons review — kanban + +## Evidence boundary + +Source repository: [corp-v1-aerosim-skills-code-agent/corp-v1-channel-kanban-aerosim](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-kanban-aerosim) + +Source commit: `526de6b6e4c331bd7e44794b6485d04d3e006eed` (branch `test`, pinned clone; not the earlier adoption-base SHA). + +Central baseline: `e8507ad71813a7d9ba9e70f69f7e8a7bdf530a7b`. Reviewed the full source package: `SKILL.md`, `ADOPTION.md`, and `references/kanban-bootstrap-and-validation.md`, `references/recurring-refresh-and-publication.md`. All existing source reference files were byte-identical to central at baseline; changes below address omissions or contradictions, not wholesale copying. + +The installed `corp-v1-channel-kanban-aerosim/SKILL.md` was also compared read-only. Runtime SHA-256: `a942940d69fb4c165a1dc33bc301347d4b565e6d88ebe3915091d35515f5e950`. Runtime differs from the pinned repository and has no verified source commit for its local-only changes; it is observation, not remote or Board approval evidence. This delegated review did not change any installed package or AeroSim/other project copy. The coordinating session owns authorized central publication and central runtime refresh. + +Review authority: Board-owner request message `1562171939961966693` authorizes central reference improvement and remote publication; the coordinating session also owns the authorized central runtime refresh. Central source publication must be verified before refreshing its installed package. No project adoption, project permission/authority expansion or naming migration is authorized. + +## Adopted lessons + +- `SKILL.md` → **Overview** (ownership paragraph): an acceptance/UAT verdict belongs to a frozen deployment, separate from Task state and release authority. Keep acceptance separate from flow; UAT topology comes from the already-approved central operating model, not project permission inheritance. +- `references/recurring-refresh-and-publication.md` → **Live deployment evidence without a governed item mapping**, plus `SKILL.md` → **State Reconciliation**: operational health does not retroactively establish scope, admission or release readiness. Expose source/template divergence and exact evidence, preserving unrelated valid Focus work instead of globally clearing the queue. +- `SKILL.md` → **Human Approval Gate**, **Board**, **Focus**, and `ADOPTION.md` → **Semantic synchronization — READY_FOR_DELIVERY pickup gate**: align the older bootstrap/refresh references with the existing exact-task admission gate. Correct four-versus-five columns, restore ReadyForDelivery to bootstrap sections, and remove the stale human-approval requirement for mere InBacklog visibility. Admission is distinct from Scope's canonical delivery vocabulary. + +## Exclusions + +The existing structural/evidence-readiness, publication-lag and concurrent-writer references already contain the reusable detail; do not duplicate them. No named approver, standing merge delegation, runtime-only blocker execution mandate, board URL or broader channel access is imported. Runtime-only **Hermes owns blocker resolution** and **Standing AeroSim PR merge authority** differ from the pinned repository and are not central authority. The prohibition on direct or delegated implementation from Kanban remains unchanged. + +## Central topology authority + +The coordinating review record `GUILD-IMP-20261020-aerosim-reference-lessons` confirms central-only maintenance. `corp-v1-main` v4.5.0, **Board Authority** / **Naming Model** / **Hermes access and Corp project automation policy**, records Board message `1552966246591365123` approving eight lifecycle channels, with UAT between Delivery and Releases. Align ordinary synchronization and references to that existing policy. Historical seven-channel bootstrap overrides are not widened; only separately reauthorized overrides may add UAT. Runtime seven-channel wording is stale, not promoted authority. + +## Remaining authority issue + +`corp-v1-main` v4.5.0 **Documentation Repository** and **Kickoff Definition of Done** still describe four columns and human admission into `InBacklog`, conflicting with the existing central Kanban **Human Approval Gate** / **Focus** exact-task `READY_FOR_DELIVERY` contract and the pinned AeroSim `ADOPTION.md` pickup-gate decision. This review removes that stale wording only inside the owned Kanban package. It does not modify or declare a new approval for `corp-v1-main`; its maintainer must reconcile the cross-skill inconsistency through the Board workflow. + +## Verification + +Run `python3 -B -m unittest discover -s tests -v` from this repository and `git diff --check`. Tests validate normative documentation contracts and linked files offline; they do not claim live workflow, CI, deployment or remote publication verification. diff --git a/references/kanban-bootstrap-and-validation.md b/references/kanban-bootstrap-and-validation.md index acd1e39..09f7102 100644 --- a/references/kanban-bootstrap-and-validation.md +++ b/references/kanban-bootstrap-and-validation.md @@ -9,9 +9,9 @@ Use this when a project documentation site has authoritative Scope and Architect 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. +6. Populate Board from authoritative unfinished Epic and Feature records only. Map detailed lifecycle states deterministically to `InIdeation`, `InBacklog`, `ReadyForDelivery`, `InProgress`, or `ToBeReleased` without changing source state. +7. Populate Focus only from qualifying `InBacklog`, `ReadyForDelivery`, `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 planned task needs a stable canonical ID and parent hierarchy. `ReadyForDelivery` additionally requires Feature implementation approval, satisfied readiness checks, and explicit exact-task human admission; backlog visibility is not executable admission. ## Recommended structural validator @@ -19,10 +19,10 @@ Add a repository validation script and include it in the main validation command - Kanban plugin, search route, and top-level navigation order; - dedicated sidebar containing Board then Focus; -- all four allowed Board columns; +- all five 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 exposes only `InBacklog`, `ReadyForDelivery`, `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`. diff --git a/references/recurring-refresh-and-publication.md b/references/recurring-refresh-and-publication.md index 5596f52..5dce0e4 100644 --- a/references/recurring-refresh-and-publication.md +++ b/references/recurring-refresh-and-publication.md @@ -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=`, 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`. diff --git a/tests/test_contracts.py b/tests/test_contracts.py new file mode 100644 index 0000000..2f75896 --- /dev/null +++ b/tests/test_contracts.py @@ -0,0 +1,44 @@ +"""Offline regression tests for normative skill-package contracts, not runtime behavior.""" +from pathlib import Path +import re +import unittest +ROOT = Path(__file__).resolve().parents[1] +SKILL = (ROOT / 'SKILL.md').read_text() +def ref(name): + return (ROOT / 'references' / name).read_text() +class Contracts(unittest.TestCase): + def test_evidence_and_links(self): + self.assertIn('(references/aerosim-lessons-review.md)', SKILL) + evidence = ref('aerosim-lessons-review.md') + self.assertRegex(evidence, r'Source commit: `[0-9a-f]{40}`') + self.assertIn('## Exclusions', evidence) + for path in re.findall(r'\]\((references/[^)#]+)(?:#[^)]*)?\)', SKILL): + self.assertTrue((ROOT / path).is_file(), path) + def test_admission_not_backlog_gate(self): + refresh = ref('recurring-refresh-and-publication.md') + self.assertNotIn('never admit an exact task to `InBacklog`', refresh) + self.assertIn('never admit an exact task to `ReadyForDelivery`', refresh) + self.assertIn('explicitly approves that exact task', SKILL) + def test_bootstrap_matches_five_columns(self): + bootstrap = ref('kanban-bootstrap-and-validation.md') + self.assertIn('all five allowed Board columns', bootstrap) + self.assertNotIn('all four allowed Board columns', bootstrap) + self.assertIn('`InBacklog`, `ReadyForDelivery`, `InProgress`, and `ToBeReleased` sections', bootstrap) + self.assertNotIn('these four board states', SKILL) + def test_unmapped_execution_does_not_clear_other_work(self): + for text in [SKILL, ref('recurring-refresh-and-publication.md')]: + self.assertIn('preserve unrelated valid Focus items', text) + self.assertIn('does not create another Task status or authorize release', SKILL) + self.assertIn('topology is not mutation authority', SKILL) + def test_execution_boundary_preserved(self): + for term in ['not an implementation session', 'delegated or spawned work', 'implementation approval does not waive it', 'separate from Scope-owned canonical delivery status']: + self.assertIn(term, SKILL) + + def test_eight_channel_boundary(self): + boundary = SKILL.split('## Approved Information Boundary')[1].split('## ', 1)[0] + channels = re.findall(r'^corp-v1--(.+)$', boundary, re.M) + self.assertEqual(channels, ['general', 'scope', 'architecture', 'ui-ux', 'kanban', 'delivery', 'uat', 'releases']) + self.assertIn('1552966246591365123', boundary) + +if __name__ == '__main__': + unittest.main() -- 2.54.0