docs: promote reusable AeroSim channel lessons

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)

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.

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.

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.

references/status-and-reporting.md

@@ -6,7 +6,7 @@ Recommended update:
 
 ```markdown
 ## UAT result — <VERDICT>
-- Run: <run ID>
+- Run: <run ID and exact E2E commit>
 - Environment: <name and base URL>
 - Deployment: app <commit>; images <digests>; GitOps <commit>; Argo CD <sync/health>
 - Journeys: <passed>/<failed>/<skipped>; <browser matrix>
@@ -15,4 +15,6 @@ Recommended update:
 - Next action: <one owner and 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.

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()