docs: promote reusable AeroSim channel lessons

This commit is contained in:
jarvis-at-skic committed 2026-10-20 18:42:45 +00:00
1 parent 602b1a0afd
commit 5a09d92abd
5 files changed
+109 -58

No files matched your search

+32
View File
@@ -0,0 +1,32 @@
# AeroSim lessons review — scope
## Evidence boundary
Source repository: [corp-v1-aerosim-skills-code-agent/corp-v1-channel-scope-aerosim](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-scope-aerosim)
Source commit: `3eb7a2a530d63e4ad20f7bff36cf435dc98eb7d6` (branch `test`, pinned clone; not the earlier adoption-base SHA).
Central baseline: `602b1a0afdac56f4b8a10def4bd241b53495c3e3`. Reviewed the full source package: `SKILL.md`, `ADOPTION.md`, and `references/data-backed-scope-integrity.md`, `references/decision-readiness.md`, `references/feature-set-completeness.md`, `references/react-flow-governed-state.md`, `references/roadmap-multidimensional-state.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-scope-aerosim/SKILL.md` was also compared read-only. Runtime SHA-256: `78d2e5c1a192184cf2edd6d056182631297a9f1cb97e18cffbc402399c215b47`. 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` → **Proactive Iteration Requirement**, acceptance-gap paragraphs: distinguish observed outcomes from missing evidence; bind exhaustive coverage to Scope and tested-application revisions; never transfer observations to newer source or manufacture retroactive approval. Existing `references/data-backed-scope-integrity.md` → **Reproducible acceptance-evidence packet consistency** remains the detailed contract.
- `SKILL.md` → **Synchronization Workflow**, step 8 and its review-ledger, temporal-consistency and continuation bullets; step 9: review the complete candidate with a dynamic claim ledger, invalidate review after base drift, distinguish a login-page HTTP 200 from deployed-content verification. Retain central independent review, not AeroSim self-review substitution. Resolve central early-push wording against the existing pre-publication migration review gate.
- `SKILL.md` → **Overview** (under Documentation Contract), **Roadmap**, and **React Flow visualization contract**: use plain-language Status basis rather than internal EXACT/DERIVED reader labels, matching the already-shared roadmap reference.
- `SKILL.md` → **Epics, Features, and Tasks** forbids duplicate completeness sections, while **Human Decision Readiness** and `references/feature-set-completeness.md` still prescribe them. Resolve the central contradiction by retaining the review mechanics in a linked governed review artifact, not restoring forbidden reader sections or a global Question bucket.
## Exclusions
No Jira mandate, API recovery operations, release-instance migration, cumulative release schema, named owners, org-wide PR sweep, standing merge authority, self-review downgrade, dispatcher path/credentials or additional channel authorization is adopted. Runtime-only **Documentation Contract** changes to a release-first sidebar were inspected and excluded; runtime also has seven/eight-channel and UAT-route inconsistencies. Central navigation, stable identities, human decisions and independent review remain authoritative. No release-first adoption or naming migration is authorized by this review.
## 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.
## 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.
+1 -1
View File
@@ -18,6 +18,6 @@ Use this packet only after the source channel has completed and verified its own
The destination scans for packets addressed to it, searches its own history for the exact Handoff ID, and processes each ID at most once. Before acting, it verifies the packet evidence and every destination entry gate. A valid packet is acknowledged and continued in the destination's authority boundary. An incomplete or invalid packet is returned as `BLOCKED` or `RETURNED` under the same Handoff ID with the missing condition and correct owner. A notification is never lifecycle approval.
The normal forward path is `general → scope → architecture → ui-ux when applicable → kanban → delivery → releases → general`. Route directly to the actual owner when work begins later, and route backward for defects, contradictions, or missing evidence. General receives final outcomes and cross-cutting exceptions, not every routine transition. Continuations name the parent Handoff ID; never duplicate an already acknowledged transition or copy whole conversations.
The normal forward path is `general → scope → architecture → ui-ux when applicable → kanban → delivery → uat → releases → general`. Route directly to the actual owner when work begins later, and route backward for defects, contradictions, or missing evidence. General receives final outcomes and cross-cutting exceptions, not every routine transition. Continuations name the parent Handoff ID; never duplicate an already acknowledged transition or copy whole conversations.
A project may add an event-driven dispatcher only through a separately approved project-local authorization and credential contract. The central packet contract does not authorize webhook creation, secret access, scheduler jobs, or automated destination mutation.
+9 -45
View File
@@ -1,57 +1,21 @@
# Epic feature-set completeness review
Use this pattern when a human asks whether an Epic includes every Feature needed for its stated outcome, or whether its unresolved questions are documented.
Use when a human asks whether an Epic covers its outcome or its product questions are documented.
## Evidence boundary
Assess completeness against the Epic's current intended outcome, user journey, explicit exclusions, and cited human request. Do not invent a Feature to satisfy cadence. Label the result as a Scope assessment or proposal, never approval.
Assess the current intended outcome, full user journey, explicit exclusions and cited request. Label the result a proposal, never approval. Shared technical capabilities belong in existing acceptance outcomes unless independently valuable Features are evidenced. Epic approval never approves child Features.
## Epic-page pattern
## Review artifact, not duplicate reader sections
Add a durable section at the point of review:
Keep the assessment in a governed review artifact linked from the canonical Epic record, not a second mutable completeness table or Canonical product questions section on the concise Epic reader. Record the canonical Scope revision and a journey-to-Feature coverage table:
```md
## Feature-set completeness review
The proposed Features form the minimum complete set for the current Epic outcome. This is a Scope assessment, not approval.
| User journey outcome | Owning Feature | Why it is required |
| User journey outcome | Canonical Feature link | Coverage or gap |
|---|---|---|
| `<OUTCOME>` | [`<FEATURE-ID>`](<LINK>) | `<UNIQUE VALUE OR COVERAGE>` |
```
| `<OUTCOME>` | `<RESOLVED-RECORD-URL>` | `<EVIDENCE-BOUNDED ASSESSMENT>` |
Then state:
State shared acceptance expectations, excluded outcomes, any supported new Feature proposal, and the exact human decision needed. Link the Epic-owned canonical Question records; do not introduce a global question register or duplicate question bodies. Conditional approval must retain exact unresolved questions or equivalent conditions as Architecture risks.
- which shared capabilities are acceptance expectations inside existing Features rather than standalone Features;
- which adjacent outcomes remain explicitly outside the Epic;
- whether evidence supports another Feature;
- that expanding an excluded outcome requires a new or revised Scope proposal;
- that Epic approval does not approve child Features.
## Validation and publication
A completeness review should detect both gaps and duplication. Do not create separate Features for shared technical components or cross-cutting behavior unless they independently deliver user value within the Epic outcome.
## Canonical-question confirmation
Answer “are the questions documented?” at the decision point, not only in an aggregate registry:
```md
## Canonical product questions
The unresolved product questions are recorded in the [question register](<REGISTER-LINK>). It records each stable question ID, affected items, owner, destination, status, blocker, and evidence.
```
Link the dependency-ordered resolution sequence when one exists. Reiterate that question resolution and lifecycle approval are separate records, and that conditional approval must name every unresolved question or equivalent scope condition carried into Architecture as an unresolved risk.
## Validation
When the repository has structural validators, add a RED-first assertion for:
- the completeness-review heading;
- the journey-to-Feature coverage table;
- the canonical-question heading and register link.
Run the targeted validator and observe the expected missing-marker failure before adding content. Then run the targeted validator, full documentation validator, type checking, link/build checks, and production build. This prevents a later edit from silently removing the human decision package while leaving the site build green.
## Publication evidence
Refresh the existing authoritative Scope PR rather than opening a competing change. After pushing, verify branch equality, PR head equality, authenticated artifact readback, and the newest exact-head CI task. Re-read only the authorized project channels at the end to ensure no human decision arrived during publication.
Test the review's outcome coverage, canonical links, preserved exclusions and proposal label. Test that the Epic reader retains its mandated card and Questions/Features groups without duplicate review sections. Run targeted checks, the required full validation/build and review workflow; never manufacture a Feature to satisfy cadence. Reuse the existing authoritative Scope review when applicable, verify exact-head CI and remote readback, and re-read only approved channels for late substantive decisions.