From 5a09d92abd4793ecf13e8989dd184587573ed91c Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Tue, 20 Oct 2026 18:42:45 +0000 Subject: [PATCH] docs: promote reusable AeroSim channel lessons --- SKILL.md | 37 ++++++++++++------ references/aerosim-lessons-review.md | 32 +++++++++++++++ references/channel-handoff.md | 2 +- references/feature-set-completeness.md | 54 +++++--------------------- tests/test_contracts.py | 42 ++++++++++++++++++++ 5 files changed, 109 insertions(+), 58 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 86d2ef7..32b5bc4 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-scope -description: "Use when operating or synchronizing a Corp v1 project's Scope channel. Owns Roadmap, Epics, Features, and Ideas; correlates all seven same-project channels; proactively improves evidence-based product scope; and records human approval before work enters Architecture solution design." -version: 1.7.0 +description: "Use when operating or synchronizing a Corp v1 project's Scope channel. Owns Roadmap, Epics, Features, and Ideas; correlates all eight same-project channels; proactively improves evidence-based product scope; and records human approval before work enters Architecture solution design." +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 product discovery and durable scope for a Corp v1 project's `scope` 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 **Scope** area. +This skill owns product discovery and durable scope for a Corp v1 project's `scope` 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 **Scope** area. Scope owns Overview, Roadmap, Epics, Features, canonical Task records/reader pages, Ideas, and Questions. General coordinates overall project awareness but does not duplicate Scope records. Architecture performs solution work only for Features explicitly approved for solution by a human team member and remains semantic owner of requirement/task derivation, dependencies, and readiness. Hermes participates proactively by proposing and refining useful scope, but never approves its own proposals. @@ -53,6 +53,8 @@ Do not use it to design architecture, approve solution entry, approve implementa ## 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 @@ -62,10 +64,11 @@ corp-v1--architecture corp-v1--ui-ux corp-v1--kanban corp-v1--delivery +corp-v1--uat corp-v1--releases ``` -Read enough Scope history to avoid duplicates and only relevant new activity from the other six channels. Never inspect or correlate another project's channels. +Read enough Scope 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 @@ -113,9 +116,11 @@ Maintain a dedicated **Overview** page at canonical route `/scope/overview/` as Generate the matrix from the same validated canonical data and status selector used by Roadmap and Board views. Include every item, including `DONE` and `CANCELLED`, with at least: ```text -ID | type | title | direct parent/resulting scope | delivery status | EXACT/DERIVED | blocked flag/reason | owner | approval gates | required children | dependencies | release/deployment evidence | last evidenced transition | canonical record link +ID | type | title | direct parent/resulting scope | delivery status | Status basis | blocked flag/reason | owner | approval gates | required children | dependencies | release/deployment evidence | last evidenced transition | canonical record link ``` +Keep `status_source: EXACT`/`DERIVED` internal; render **Status basis** as `Exact item evidence`/`Required-child roll-up`, separate from the unchanged canonical status. + Provide type/status totals and filters. Render exactly one semantic matrix table: it initially contains every governed record, and search/type/status controls narrow that same table. Do not add a second “complete unfiltered” disclosure or duplicate table. Keep the current table usable for print, accessibility, and no-JavaScript output. Sort deterministically by hierarchy and stable ID. Link every row to its canonical record and every relationship to the resolved target record. Fail validation when any canonical item is absent or duplicated; a required relationship is dangling, one-sided, or double-counted; a status is invalid for the item type; `status_source` is missing or wrong; a derived status disagrees with the unified roll-up algorithm; a blocked item lacks a reason; or a transition/evidence link is not durable. The page must expose stale or contradictory states rather than silently filtering them out. @@ -265,14 +270,20 @@ Acceptance requires canonical-YAML validation, graph/table parity where a semant Every Scope iteration must add or materially improve at least one evidence-based scope artifact when a safe path exists: a grounded Idea, Epic, or Feature; clearer value or acceptance outcomes; dependency/risk evidence; deduplication; Roadmap reconciliation; cross-links; or a concrete unanswered product question. Never create filler to satisfy cadence. -Use evidence from all seven same-project channels. Delivery and release outcomes may expose new Ideas or required scope corrections; Architecture may expose infeasible assumptions; Kanban may expose flow or dependency problems. Preserve authority boundaries while incorporating that evidence. +Use evidence from all eight same-project channels. Delivery and release outcomes may expose new Ideas or required scope corrections; Architecture may expose infeasible assumptions; Kanban may expose flow or dependency problems. Preserve authority boundaries while incorporating that evidence. + +### Acceptance-gap discovery + +When verified implementation or deployment precedes item-specific approval, record an acceptance gap, not retroactive approval. Attribute channel reports as reports unless independently verified. For each canonical outcome classify only `demonstrated`, `contradicted`, or `not demonstrated by the cited evidence`; missing evidence does not prove an outcome was untested. Bind coverage to the immutable Scope revision defining the outcome set and the distinct tested application revision; require one row per outcome and all capture fields before calling coverage complete. Re-evaluate completeness when Scope changes. Follow the packet contract in [data-backed Scope integrity](references/data-backed-scope-integrity.md#reproducible-acceptance-evidence-packet-consistency). + +Keep newest published source and actually deployed/tested source distinct. Never transfer runtime observations to a newer unobserved revision. Discovery, capture completion, healthy deployment and documentation merge do not grant acceptance, admission, release approval or lifecycle transitions. ## Handoffs - **Scope → Architecture:** only human-approved Features with stable ID, parent Epic, value, scope, acceptance outcomes, dependencies, risks, and approval evidence. - **Architecture → Scope:** feasibility constraints, requirement implications, dependencies, and proposed scope clarifications; Architecture does not silently rewrite product scope. - **Scope → Kanban:** stable Idea/Epic/Feature identities, required-child relationships, approval gates, and unified delivery status for Board/Focus reconciliation. -- **Delivery/Releases → Scope:** verified outcomes, regressions, user feedback, and follow-up opportunities that may alter the Roadmap or create Ideas. +- **Delivery/UAT/Releases → Scope:** verified outcomes, regressions, user feedback, and follow-up opportunities that may alter the Roadmap or create Ideas. - **Scope → General:** concise overall implications, decisions requiring visibility, owners, and cross-channel blockers. ## UI/UX Coordination @@ -281,15 +292,15 @@ Scope supplies UI/UX with stable Feature identity, user problems, value, accepta ## Synchronization Workflow -1. Confirm the exact project code and seven approved channel IDs. -2. Read new activity from the other six channels and enough Scope history to avoid duplication. +1. Confirm the exact project code and eight approved channel IDs. +2. Read new activity from the other seven channels and enough Scope history to avoid duplication. 3. Separate verified facts, human decisions, proposals, forecasts, and unresolved questions. 4. Inspect Overview, Roadmap, Ideas, the exact Epics → Epic → Questions → Question and Epics → Epic → Features → Feature → Tasks hierarchies, every separate Question and Task reader page, links, IDs, unified delivery statuses, required-child roll-ups, and approval evidence. 5. Reconcile architecture feasibility, Kanban flow, delivery progress, and release outcomes against scope. 6. Add or materially improve at least one useful evidence-based artifact, or document the exact evidence/approval blocker. 7. Load `documentation-docusaurus` and the project CI/CD skill. Run only fast, dependency-free local preflight checks such as schema/parity scripts, targeted tests already available, `git diff --check`, and secret scanning. Do not spend the working session installing dependencies or repeatedly running the full documentation build locally when PR-triggered Gitea Actions can provide the authoritative environment. -8. Push the smallest coherent reviewable branch early and open or refresh its PR. The PR workflow must install dependencies and run the complete canonical-data validation, tests, typecheck, strict production build, and built-site assertions without publishing. Wait for the run attached to the exact pushed SHA; inspect failed job steps and logs, fix only evidenced defects, push, and repeat until that exact head is green. -9. Review the exact CI-green head, merge through the repository workflow, then require default-head CI/publication success and deployed remote readback before reporting completion. Never treat a local build, a stale run, or CI for another SHA as acceptance evidence. +8. Satisfy any required pre-publication review before push; the early-PR workflow does not waive the independent review required for data-backed migrations. If a required pre-publication channel record cannot be delivered in this execution context, keep the candidate local and report that precise publication block. Push the smallest coherent reviewable branch early and open or refresh its PR. The PR workflow must install dependencies and run the complete canonical-data validation, tests, typecheck, strict production build, and built-site assertions without publishing. Wait for the run attached to the exact pushed SHA; inspect failed job steps and logs, fix only evidenced defects, push, and repeat until that exact head is green. +9. Review the complete candidate diff against its verified base, including older committed changes and untracked candidate files. Keep a claim ledger for dynamic source, PR, CI and runtime assertions; evidence-through times must cover every cited source within their stated boundary. Fix actual artifact defects, but correct missing ledger evidence without churning already-correct prose. Preserve the required review type: self-review is not a substitute for independent review. Merge only with applicable authorization, then require default-head CI/publication success and deployed page-body readback. A redirect to an identity-provider login page with HTTP 200 is not content verification; report that boundary rather than claiming publication verified. Never transfer a review to a changed base merely because the patch hash is unchanged. 10. Post a concise Scope update. When verification is successful and the human did not ask for delivery evidence, report only the substantive changes and the reader-facing documentation link; omit routine test, build, CI, audit, PR, run, commit, and SHA details. Internal validation and immutable evidence remain mandatory. Include technical evidence only when requested or when a failure, blocker, or unresolved publication state makes it actionable. Handoff packets retain their explicit evidence contract. Prefer the most specific verified documentation route, and include the portal landing page when several pages changed. If default-head publication or page-body verification is still pending, say so instead of presenting the route as published, then provide the documentation link in the completion follow-up. Stay silent when no substantive result exists. ## Authority and Escalation @@ -327,6 +338,8 @@ When a human asks whether an Epic contains all Features required for its outcome Refine experiential requests into observable loops: entry/start, continuous user control, meaningful state change, visible feedback, outcome/failure, and replay/recovery. Keep feasibility research separate from solution selection. For Epic-wide constraints, create one canonical cross-cutting question, link it reciprocally to every affected Feature, validate both directions, and search for stale count/range assertions. Use [references/roadmap-multidimensional-state.md](references/roadmap-multidimensional-state.md) and [references/react-flow-governed-state.md](references/react-flow-governed-state.md) when the project uses data-backed readers or graphs. +Source comparison and exclusions: [AeroSim lessons review](references/aerosim-lessons-review.md). + ## Common Pitfalls 1. Treating General as the authoritative owner of Scope records. @@ -355,7 +368,7 @@ Refine experiential requests into observable loops: entry/start, continuous user ## Verification Checklist -- [ ] Only the seven same-project channels were inspected. +- [ ] Only the eight same-project channels were inspected. - [ ] Scope appears immediately before Architecture with its own sidebar. - [ ] Sidebar order is Overview, Roadmap, Ideas with child pages, then Epics; every Epic contains explicit Questions and Features groups. - [ ] Ways of Working starts with a separate Scope page explaining the ticket hierarchy and governed statuses. diff --git a/references/aerosim-lessons-review.md b/references/aerosim-lessons-review.md new file mode 100644 index 0000000..4fe6ba5 --- /dev/null +++ b/references/aerosim-lessons-review.md @@ -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. diff --git a/references/channel-handoff.md b/references/channel-handoff.md index 4c71b04..9277fc7 100644 --- a/references/channel-handoff.md +++ b/references/channel-handoff.md @@ -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. diff --git a/references/feature-set-completeness.md b/references/feature-set-completeness.md index 3466ea3..1518811 100644 --- a/references/feature-set-completeness.md +++ b/references/feature-set-completeness.md @@ -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 | |---|---|---| -| `` | [``]() | `` | -``` +| `` | `` | `` | -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](). 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. diff --git a/tests/test_contracts.py b/tests/test_contracts.py new file mode 100644 index 0000000..dcd76a1 --- /dev/null +++ b/tests/test_contracts.py @@ -0,0 +1,42 @@ +"""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_capture_is_not_acceptance(self): + block = SKILL.split('### Acceptance-gap discovery')[1].split('## Handoffs')[0] + for term in ['not retroactive approval', 'missing evidence does not prove', 'immutable Scope revision', 'distinct tested application revision', 'one row per outcome', 'Re-evaluate completeness', 'Never transfer runtime observations', 'do not grant acceptance']: + self.assertIn(term, block) + def test_review_identity_and_content_readback(self): + for term in ['complete candidate diff', 'untracked candidate files', 'claim ledger', 'changed base', 'HTTP 200 is not content verification', 'self-review is not a substitute for independent review']: + self.assertIn(term, SKILL) + def test_reader_contract_consistency(self): + self.assertIn('delivery status | Status basis |', SKILL) + self.assertNotIn('delivery status | EXACT/DERIVED |', SKILL) + review = ref('feature-set-completeness.md') + self.assertIn('governed review artifact', review) + self.assertNotIn('## Epic-page pattern', review) + self.assertNotIn('## Canonical product questions', review) + def test_review_precedes_push(self): + workflow = SKILL.split('## Synchronization Workflow')[1].split('## Authority')[0] + self.assertLess(workflow.index('required pre-publication review'), workflow.index('Push the smallest')) + + 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