From 6e71bfd202a225319359629743dd0f9bce816f10 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Tue, 20 Oct 2026 18:42:48 +0000 Subject: [PATCH] docs: promote reusable AeroSim channel lessons --- SKILL.md | 4 +- references/aerosim-lessons-review.md | 34 ++++++++++++ references/deployment-evidence-contract.md | 6 ++- references/journey-repository-contract.md | 2 + references/status-and-reporting.md | 4 +- tests/test_aerosim_lessons_contract.py | 60 ++++++++++++++++++++++ 6 files changed, 106 insertions(+), 4 deletions(-) create mode 100644 references/aerosim-lessons-review.md create mode 100644 tests/test_aerosim_lessons_contract.py diff --git a/SKILL.md b/SKILL.md index ec47d38..e93f2be 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-uat description: Use when validating a deployed Corp v1 environment through UAT journeys. -version: 1.3.0 +version: 1.4.0 author: Hermes Agent license: MIT metadata: @@ -127,6 +127,8 @@ UAT must not modify product requirements, application behavior, deployment desir ## References +Review provenance and exclusions: [AeroSim lessons review](references/aerosim-lessons-review.md). + - [Journey repository contract](references/journey-repository-contract.md) - [Deployment evidence contract](references/deployment-evidence-contract.md) - [Defect and retest workflow](references/defect-and-retest-workflow.md) diff --git a/references/aerosim-lessons-review.md b/references/aerosim-lessons-review.md new file mode 100644 index 0000000..d5cad53 --- /dev/null +++ b/references/aerosim-lessons-review.md @@ -0,0 +1,34 @@ +# AeroSim lessons review — UAT + +## Immutable sources + +AeroSim UAT source SHA: `f07f457bf6debeb16cdf79ab10dac193d0f6d69c`. Central baseline: `8e6547659cd7019a445c8b4b061e61a3a7b79b8b`. +- [SKILL.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-uat-aerosim/src/commit/f07f457bf6debeb16cdf79ab10dac193d0f6d69c/SKILL.md) +- [references/exact-deployment-evidence.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-uat-aerosim/src/commit/f07f457bf6debeb16cdf79ab10dac193d0f6d69c/references/exact-deployment-evidence.md) +- [references/journey-repository-and-execution.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-uat-aerosim/src/commit/f07f457bf6debeb16cdf79ab10dac193d0f6d69c/references/journey-repository-and-execution.md) +- [references/defect-return-and-retest.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-uat-aerosim/src/commit/f07f457bf6debeb16cdf79ab10dac193d0f6d69c/references/defect-return-and-retest.md) +- [references/reporting-and-release-handoff.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-uat-aerosim/src/commit/f07f457bf6debeb16cdf79ab10dac193d0f6d69c/references/reporting-and-release-handoff.md) + +Read the full source skill and all four references against the central skill and its four references. Relevant sections: **Entry gate from Delivery**, **E2E Gitea Actions contract**, **Handoff packet**, **Exact deployment evidence**, and **Defect return and retest**. + +## Promoted lessons + +- A template commit is provenance, not proof of the rendered deployment. Require timestamped pre/post live identity and health; distinguish root/runtime sources and invalidate mixed-deployment results. +- Reconcile the complete required journey/browser matrix rather than accepting a partial run; keep E2E revision and verified receipt in reporting. +- Accept only ordinary-user-path evidence, with meaningful runtime outcomes. Infrastructure health and bypass-assisted navigation cannot prove product acceptance. +- Existing two-workflow, secret-handling, retest, and lifecycle separation contracts already cover the source; preserve rather than duplicate them. + +## Runtime drift reviewed + +Installed UAT `SKILL.md` SHA-256: `0167e17bf5f254c359ea311b21b0b94a8a24db9d33b0635afa3e6a2b0b311d9b`; installed `references/journey-repository-and-execution.md` SHA-256: `0fef75fdd1d6eaa861f40810fbcbe1f0a3e75d16e7c76d1ad91da8f8e556e291`. Runtime board reassignment and standing authority are local overlays, not central defaults. The runtime journey reference omits artifact-validation exclusions present in Git; preserve the newer source boundary. + +Ordinary-interaction acceptance is a cross-channel lesson from installed AeroSim Releases **Post-Approval and Deployment Evidence**, SHA-256 `feac09e2515486abc35a5b127525ec3a13ca97d47f12b32cf68e434c50df9ece`. This supplementary local content is not attributed to the pinned source; the related immutable Releases baseline is: +- [SKILL.md](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-releases-aerosim/src/commit/3c4b4788915bae3d89303959c46a8854c9a141bc/SKILL.md) + +## Exclusions + +No project rollout, runtime overwrite, owner reassignment, branch naming change, Jira mandate, standing merge/deploy delegation, account recovery, board/channel IDs, endpoint, scheduler cadence, or deployment configuration is promoted. Central authority and project overlays remain unchanged. The newer central functional-non-unit versus build-time artifact-validation split is retained; runtime references that send Helm artifact validation to UAT are stale and are not imported. + +## Verification + +Run `python3 -B -m unittest discover -s tests -v` from this repository, plus `git diff --check`. Tests validate the published documentation contract and links offline; they do not prove a deployment or live acceptance run. diff --git a/references/deployment-evidence-contract.md b/references/deployment-evidence-contract.md index 969e931..851cafe 100644 --- a/references/deployment-evidence-contract.md +++ b/references/deployment-evidence-contract.md @@ -12,7 +12,9 @@ cluster_environment base_url ``` -Before execution, assert that the Argo CD application is synchronized to the declared GitOps commit and healthy. Where the environment exposes a version endpoint, compare its source/image identity with the handoff. +The template commit is provenance, not the deployed revision. Resolve the rendered desired-state repository and environment from the handoff; a production revision cannot substitute for the declared non-production deployment. + +Read live identity and health before and after execution, retaining both timestamped snapshots. For app-of-apps or multi-source deployments, record root and runtime controller identities separately: compare the root to the rendered Git revision and each child/source to its declared chart version or source revision, not blindly to the same Git SHA. Require synchronized, healthy state and compare pod image IDs plus exposed source/chart annotations or version endpoints to the immutable artifacts in the handoff. Reject the handoff when: @@ -22,4 +24,4 @@ Reject the handoff when: - the base URL resolves to a different environment; - a newer synchronization occurs after the run begins. -If deployment identity changes during execution, end the run as invalidated and start a new run after the new identity is frozen. +If deployment identity changes during execution, end the run as invalidated and start a new run after the new identity is frozen; never combine results across deployment tuples. Missing post-run identity or health evidence blocks a release-facing pass. diff --git a/references/journey-repository-contract.md b/references/journey-repository-contract.md index 29bf14a..a6bc321 100644 --- a/references/journey-repository-contract.md +++ b/references/journey-repository-contract.md @@ -23,6 +23,8 @@ A smaller standalone repository may keep `journeys/`, `fixtures/`, `helpers/`, a ## Journey rules - Stable journey IDs appear in test titles and evidence. +- Declare the required journey/browser matrix before execution and reconcile every cell with the final report. Missing, skipped, interrupted, or artifact-less required cells cannot support `UAT_PASSED`. +- Use visible controls and ordinary user interactions for acceptance. Forced clicks, hidden controls, direct state/DOM mutation, or API bypasses are diagnosis, not acceptance evidence. Assert the meaningful runtime outcome over a requirement-appropriate observation period, not only route loading or a clean console; a blocking warning or unusable state fails the journey. - `UAT_BASE_URL` is required; no production-looking default is embedded. - Authentication is loaded from runtime secrets and never persisted in committed storage-state files. - Retries are explicit and low; a retry cannot turn a flaky first failure into an undisclosed pass. diff --git a/references/status-and-reporting.md b/references/status-and-reporting.md index 0e925a0..793b8a9 100644 --- a/references/status-and-reporting.md +++ b/references/status-and-reporting.md @@ -6,7 +6,7 @@ Recommended update: ```markdown ## UAT result — -- Run: +- Run: - Environment: - Deployment: app ; images ; GitOps ; Argo CD - Journeys: //; @@ -15,4 +15,6 @@ Recommended update: - Next action: ``` +Retain the mapped destination and verified handoff receipt; reuse the existing handoff identity on retry rather than duplicating work. A summary in the source channel alone does not prove receipt. + Never say “released,” “production-ready,” or “DONE” from a UAT pass alone. Releases owns promotion and final release status. diff --git a/tests/test_aerosim_lessons_contract.py b/tests/test_aerosim_lessons_contract.py new file mode 100644 index 0000000..929daaa --- /dev/null +++ b/tests/test_aerosim_lessons_contract.py @@ -0,0 +1,60 @@ +"""Offline regression tests for the channel's published prose contract.""" +from pathlib import Path +import re +import unittest + +ROOT = Path(__file__).resolve().parents[1] + +class LessonsContract(unittest.TestCase): + def test_review_provenance_and_link(self): + review = ROOT / "references/aerosim-lessons-review.md" + self.assertTrue(review.is_file()) + text = review.read_text() + self.assertRegex(text, r"/src/commit/[0-9a-f]{40}/") + self.assertIn("## Exclusions", text) + self.assertIn("aerosim-lessons-review.md", (ROOT / "SKILL.md").read_text()) + + def test_local_markdown_links_resolve(self): + for path in [ROOT / "SKILL.md", *ROOT.glob("references/*.md")]: + for target in re.findall(r"\]\(([^)]+)\)", path.read_text()): + if "://" not in target and not target.startswith(("#", "<")): + self.assertTrue((path.parent / target.split("#")[0]).is_file(), (path, target)) + + def test_no_project_authority_transplant(self): + for path in [ROOT / "SKILL.md", *ROOT.glob("references/*.md")]: + if path.name == "aerosim-lessons-review.md": + continue + text = path.read_text() + for forbidden in ("jarvis-at-skic", "aerosim-dev.apps", "AEROSIM_STANDING", "1537388451501056081"): + self.assertNotIn(forbidden, text) + + def test_contract_0(self): + text = (ROOT / 'references/deployment-evidence-contract.md').read_text() + self.assertIn('template commit is provenance', text) + self.assertIn('before and after', text) + self.assertIn('root and runtime', text) + self.assertIn('never combine results', text) + + def test_contract_1(self): + text = (ROOT / 'references/journey-repository-contract.md').read_text() + self.assertIn('ordinary user interactions', text) + self.assertIn('diagnosis, not acceptance', text) + self.assertIn('required journey/browser matrix', text) + + def test_contract_2(self): + text = (ROOT / 'SKILL.md').read_text() + self.assertIn('version: 1.4.0', text) + + def test_preserved_ownership_and_invalidation(self): + repo = (ROOT / "references/journey-repository-contract.md").read_text() + evidence = (ROOT / "references/deployment-evidence-contract.md").read_text() + reporting = (ROOT / "references/status-and-reporting.md").read_text() + self.assertIn("Helm installation/rendering", repo) + self.assertIn("cannot support `UAT_PASSED`", repo) + self.assertIn("Missing post-run identity or health evidence blocks", evidence) + self.assertIn("verified handoff receipt", reporting) + self.assertIn("exact E2E commit", reporting) + + +if __name__ == "__main__": + unittest.main() -- 2.54.0