diff --git a/SKILL.md b/SKILL.md index 1078cdf..d3b90bc 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: corp-v1-channel-architecture -description: "Use when operating or synchronizing a Corp v1 project's architecture channel. Maintains C4-based architecture documentation, Draw.io diagrams, architecture decisions, and requirements while correlating verified activity across the project's seven channels." -version: 1.9.0 +description: "Use when operating or synchronizing a Corp v1 project's architecture channel. Maintains C4-based architecture documentation, Draw.io diagrams, architecture decisions, and requirements while correlating verified activity across the project's eight channels." +version: 1.10.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 the solution phase and architecture coherence for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, and `releases` channels, transforms human-approved Features into requirements and solution artifacts, breaks them into dependency-aware implementation tasks, assigns approved Features to versions, and maintains the Architecture section of the project documentation. +This skill owns the solution phase and architecture coherence for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, `uat`, and `releases` channels, transforms human-approved Features into requirements and solution artifacts, breaks them into dependency-aware implementation tasks, assigns approved Features to versions, and maintains the Architecture section of the project documentation. The default architecture model is C4. Architecture diagrams must be authored and validated using the global `diagrams-drawio` skill from: @@ -82,10 +82,11 @@ corp-v1--architecture corp-v1--ui-ux corp-v1--kanban corp-v1--delivery +corp-v1--uat corp-v1--releases ``` -Use mapped-channel history to avoid duplicate work and new relevant activity from the other six channels. Never inspect another project's channels. +Use mapped-channel history to avoid duplicate work and new relevant activity from the other seven channels. Never inspect another project's channels. ## Architecture Documentation Contract @@ -132,7 +133,7 @@ Documentation and diagrams must reflect approved/current truth. Proposed designs For each human-approved Feature from canonical Scope: 1. verify its stable ID, parent Epic, scope, value, acceptance outcomes, status, and human approval evidence; -2. set solution status to `In Solution` without changing product approval history; +2. use the canonical repository schema for solution status without changing product approval history; do not invent an intermediate state absent from that schema; 3. derive traceable FRs and NFRs; 4. update C4 views and draft/maintain ADRs as needed; 5. break the Feature into implementation tasks with dependencies and acceptance evidence; @@ -252,7 +253,7 @@ After human Feature implementation approval, Architecture applies the `READY_FOR ## Proactive Iteration Requirement -Every architecture iteration must add or materially improve a useful project-documentation artifact for an eligible human-approved Feature: FR/NFR traceability, C4/ADR content, task decomposition, dependency mapping, risk analysis, version proposal, or review package. Prefer improving existing artifacts over creating duplicates. If no Feature is approved for solution, document the exact waiting gate or actionable clarification instead of advancing unapproved work. +When eligible work or material drift exists, an architecture iteration must add or materially improve a useful project-documentation artifact for an eligible human-approved Feature: FR/NFR traceability, C4/ADR content, task decomposition, dependency mapping, risk analysis, version proposal, or review package. Prefer improving existing artifacts over creating duplicates. If no Feature is approved for solution, document the exact waiting gate or actionable clarification instead of advancing unapproved work. When that durable gate is already accurate and no material evidence changed, verify and report unchanged status only as needed; do not manufacture an edit to satisfy iteration activity. ## UI/UX Coordination @@ -264,7 +265,7 @@ Architecture supplies UI/UX with system boundaries, interfaces, data availabilit 2. Inspect documented Epics/Features and verify human `Approved for Solution` evidence before selecting work. 3. Identify changed assumptions, requirements, interfaces, constraints, infrastructure, deployment topology, or runtime behavior. 4. Compare evidence with the required Architecture information architecture, C4 views, ADRs, FR/NFR registries and pages, Scope-hosted task records, dependencies, readiness, and version evidence. -5. Add or materially improve at least one useful solution artifact for an eligible Feature. +5. Apply the Proactive Iteration Requirement: improve eligible artifacts or maintain the exact waiting gate; avoid edits for unchanged evidence. 6. Use `diagrams-drawio` for every diagram change and `documentation-docusaurus` for every documentation, navigation, MDX, plugin, or embedding change. 7. Validate the exact Architecture sidebar, FR/NFR registries and reader pages, absence of Architecture Feature/task navigation, reciprocal Scope traceability, links, Draw.io source embedding, Docusaurus build, and browser rendering; then perform remote readback. 8. Post a concise update with changed artifacts, implications, unresolved decisions, approval gate, and exact evidence. @@ -299,6 +300,8 @@ Every project adoption must bind this channel to a dedicated local workspace und ## Project-Adoption Architecture Lessons +Apply [references/aerosim-lessons-review.md](references/aerosim-lessons-review.md) for pre-approval intake, scope-to-board coverage, accepted-output evidence, source-of-truth changes and no-churn synchronization. It records pinned sources and exclusions without replacing project tools or approval authority. + Resolve authority from the active project authorization contract at invocation time; broad delegation never replaces exact-item evidence, safety boundaries, or a later narrower owner decision. Use [references/authority-precedence-and-concurrent-evidence.md](references/authority-precedence-and-concurrent-evidence.md). For cross-channel handoffs, emit a stable verified packet and let the destination re-check its own entry gates. Process each handoff ID once and return incomplete work without fabricating a lifecycle transition. Follow [references/channel-handoff.md](references/channel-handoff.md). @@ -331,7 +334,7 @@ Use RED-first repository contracts for delegated solution packages and task iden ## Verification Checklist -- [ ] Only the seven same-project channels were inspected. +- [ ] Only the eight same-project channels were inspected. - [ ] Architecture documentation reflects verified status. - [ ] C4 scope and level are appropriate. - [ ] `diagrams-drawio` governed every diagram change. diff --git a/references/aerosim-lessons-review.md b/references/aerosim-lessons-review.md new file mode 100644 index 0000000..a4f7e98 --- /dev/null +++ b/references/aerosim-lessons-review.md @@ -0,0 +1,48 @@ +# AeroSim lessons review — Architecture + +## Sources and scope + +- Complete pinned [Architecture package](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-architecture-aerosim/src/commit/d7900acfa923d8c7bb32f6e8e269048f5d4b8d4f/SKILL.md), immutable SHA `d7900acfa923d8c7bb32f6e8e269048f5d4b8d4f`: **Epic and Feature Transition**, **Capability-safe partial remediation**, **Current-gate freshness audit**, **Human requirement intake before solution approval**, **Architecture Structure Synchronization Audit**, all eight references, adoption record, tests and validation workflow. +- Supplemental read-only `/opt/data/skills/productivity/corp-v1-channel-architecture-aerosim/SKILL.md`, SHA-256 `ecf45551eba3106cc4e94414bb9cad9a24974dbe253417b83252662fabbb05e8`: **Scope ↔ Architecture board alignment**, **Architecture Board Acceptance and Definition of Done**, **Architecture system of record**, **Release 2 Jira output delivery override**. Runtime-only additions are not attributed to the pinned remote SHA. They supply evidence-management lessons, not permission to adopt the project's tools or authority. +- Central baseline `a599b11944fcfdb7343de914b1d53763ddc24e40` (1.9.0). Board owner review request `1562171939961966693` authorizes central reference review and remote publication, followed by verified central runtime refresh; it does not authorize project rollout or authority changes. + +## Reusable operating additions + +### Intake and no-churn maintenance + +A human requirement statement is intake, not automatically solution approval. Preserve exact wording, actor, date and message; distinguish a cross-cutting constraint from a Feature outcome and route canonical identity/parentage to Scope. Before solution approval, maintain only the existing gate or assessment artifact: do not assign FR/NFR IDs, derive ADRs/interfaces/Tasks or allocate versions. After Scope publishes canonical records, retire the obsolete canonicalization blocker and name the remaining exact approval gate. Preserve intake history. + +Treat dated provenance as an evidence-window snapshot, not a cursor that must follow every bot message. Reuse the owning artifact/PR. Apply the existing [convergence procedure](scheduled-sync-evidence-convergence.md); edit only for material decisions, relevant path/shared-data changes or false current-state claims. An already accurate durable waiting gate plus verified unchanged state satisfies maintenance; it does not authorize solution work. Safe non-semantic repair remains possible without inventing approval. + +### Scope-to-board coverage and output acceptance + +Where a project already uses an Architecture board, reconcile its work references against canonical Scope items at handoff: exact canonical IDs, source links, purpose, dependencies and supersessions. Reuse one reference per item and purpose; do not duplicate implementation Tasks or claim alignment from counts alone. Coordinate with the existing writer and read back the result. This does not create a board, recurring job or Focus admission. + +Keep input readiness, execution, release membership and output acceptance separate using the existing [lifecycle dimensions](multidimensional-lifecycle-presentation-audit.md). Input checks record pass/fail/not-applicable with rationale, evidence and a missing-input owner. Completion requires applicable reviewable outputs and reciprocal traceability, exact revision validation/review, resolved conditions or an authorized exception, and exact-item acceptance evidence under the project's existing approval contract. Historical Done, a link-only comment or a readiness assessment is not accepted substantive output; material output changes require renewed acceptance without erasing history. If native filters cannot represent these independent dimensions, report the capability gap and retain a durable assessment rather than claiming title prefixes implement filters. + +### Destination and capability boundaries + +Resolve the active authorized system of record, release scope and output revision before editing. A project-local destination change must explicitly identify superseded guidance and the legacy/derived artifacts to which it still applies. Preserve canonical business IDs, source revisions and reciprocal links; keep server-native object IDs isolated when the platform resolves them globally. Pull current destination content before writing and read back substantive saved output, not merely the existence of links. Local generation is not server publication. A storage decision does not authorize implementation or change human decision ownership. + +C4/Draw.io/Docusaurus remain the central default; no Jira-only or CogArch-only policy is introduced here. Use project-approved tools and their governing skills. When a required capability is unavailable, narrow work to a coherent artifact without leaving prose and diagrams contradictory; identify the coordinated deferred change and report partial completion. The existing [C4 source/runtime reconciliation](c4-container-registry-component-views.md) owns the detailed two-baseline procedure; do not duplicate it here. + +## Improvements and contradiction resolution + +- Replaced forced `In Solution` transition with the canonical schema's solution state; approval history is unchanged. +- Reconciled proactive iteration with the source's no-churn rule and linked this reference from SKILL. +- Removed stale fixed channel counts in inherited references; the existing approved information boundary still controls access. +- Aligned the C4 reference navigation example with the central exact-label contract, without migrating any project names or navigation. +- Made delegated solution-package examples explicitly conditional on existing authorization; they cannot silently override central human gates. +- Reused existing C4, lifecycle, convergence, handoff and review references rather than copying their full rules. Updated the existing test's version assertion only; its approval and readiness mutation tests remain intact. + +## Excluded project decisions and source issues + +Excluded named owners, standing merge delegations, board/channel IDs, dispatch scripts and webhook transport, CogArch architecture IDs/native view strategy, the Release 2 Jira exception and its AERS issue policy, AeroSim naming and seven/eight-channel migrations. These are project decisions, not portable central defaults. Runtime and pinned package differ substantially; runtime still mixes historical scheduled/eight-channel prose with newer seven-channel wording. Do not infer access expansion or scheduler authorization from these historical references. The source's destination overrides are evidence of scoped precedence, not an invitation to migrate central C4 or Docusaurus. + +## Existing topology reconciliation + +The review also restores the existing Board-approved eight-channel topology, including UAT, in descriptions, boundary lists and handoff paths. This is consistency repair, not new channel authority; no historical bootstrap override is widened. + +## Verification + +Run `python3 -B -m unittest discover -s tests -v` and `git diff --check`. Tests cover package links, portable contracts, absence of stale channel counts and retained human gates alongside the existing negative readiness/decomposition tests. They do not prove a live board, architecture service, diagram or deployment was validated. No AeroSim or other project-adopted package is modified; central runtime packages are refreshed only after verified source publication. diff --git a/references/authority-precedence-and-concurrent-evidence.md b/references/authority-precedence-and-concurrent-evidence.md index 38164b8..fe80cc2 100644 --- a/references/authority-precedence-and-concurrent-evidence.md +++ b/references/authority-precedence-and-concurrent-evidence.md @@ -9,7 +9,7 @@ Apply the narrowest higher-authority instruction that governs the current run: 1. System and developer instructions. 2. The current user's invocation-local contract, including scheduled-job boundaries. 3. The installed project-local skill and its authorization override. -4. Verified human Discord decisions within the six authorized channels. +4. Verified human Discord decisions within the authorized channels. 5. Canonical remote default-branch records and exact remote PR artifacts. 6. Bot reports, local branches, uncommitted diffs, and agent assertions. diff --git a/references/c4-container-registry-component-views.md b/references/c4-container-registry-component-views.md index 8c625f0..9906719 100644 --- a/references/c4-container-registry-component-views.md +++ b/references/c4-container-registry-component-views.md @@ -39,12 +39,12 @@ Those phrases can misclassify the container itself as a component or the registr ## Navigation pattern -For the adopted project: +Use the exact central sidebar labels below unless a separately approved project-local navigation contract says otherwise. C4 annotations belong in page prose/titles, not an implicit sidebar renaming: ```text -Context (C1) -Overview (C2) -Container Registry (C3 views) +Context +Overview +Container Registry Web Application API Service Documentation Site 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/delegated-solution-package-tdd.md b/references/delegated-solution-package-tdd.md index ecb8870..30d9144 100644 --- a/references/delegated-solution-package-tdd.md +++ b/references/delegated-solution-package-tdd.md @@ -1,6 +1,6 @@ # Delegated solution-package TDD and handoff pattern -Use this reference when one change must transition several approved Features and add their complete Architecture/Kanban packages. +Use this reference when one change must transition several approved Features and add their complete Architecture/Kanban packages. No actor authority is granted by this reference: delegated-actor examples apply only when separately authorized for the exact decision under the active contract. Otherwise retain the human approval gates in SKILL.md; do not add agent approvals or Accepted records merely to follow the example sequence. ## RED contract diff --git a/references/multidimensional-lifecycle-presentation-audit.md b/references/multidimensional-lifecycle-presentation-audit.md index c7e97e1..32f9712 100644 --- a/references/multidimensional-lifecycle-presentation-audit.md +++ b/references/multidimensional-lifecycle-presentation-audit.md @@ -42,14 +42,14 @@ Do not accept a green build as semantic consistency. Search static prose for obs ## Coordinated remediation -1. Freeze six-channel high-watermarks and current remote default SHA. +1. Freeze authorized-channel high-watermarks and current remote default SHA. 2. Confirm the contradiction using canonical records and exact immutable implementation/deployment evidence. 3. Inventory every sibling surface and adapter that presents the affected records. 4. Update data derivation, types, visual nodes, semantic tables, accessibility text, static prose, and tests together. 5. Include negative assertions rejecting superseded current-state wording. 6. Run production-data derivation tests, all domain validators, TypeScript, strict build, browser QA, generated-output drift checks, and `git diff --check`. 7. Publish one owning PR, verify the complete changed-file list, wait for exact-head CI, merge only under the active authority contract, and verify exact-default CI. -8. Perform a final six-channel plus remote-artifact convergence pass. +8. Perform a final authorized-channel plus remote-artifact convergence pass. ## Concurrent candidate rule diff --git a/references/scheduled-sync-evidence-convergence.md b/references/scheduled-sync-evidence-convergence.md index f40441f..6dc8d81 100644 --- a/references/scheduled-sync-evidence-convergence.md +++ b/references/scheduled-sync-evidence-convergence.md @@ -1,10 +1,10 @@ # Scheduled synchronization evidence convergence -Use this procedure when an Architecture synchronization must correlate six authorized Discord channels with mutable Gitea pull requests and exact-head CI without churning an owning PR. +Use this procedure when an Architecture synchronization must correlate authorized Discord channels with mutable Gitea pull requests and exact-head CI without churning an owning PR. ## Freeze the initial evidence window -1. Read only the six authorized project channels. +1. Read only the authorized project channels. 2. Record one high-watermark per channel: newest message ID, timestamp, author ID, and author type. 3. Fetch potentially substantive messages in full. A truncated digest is discovery evidence only. 4. Preserve the frozen high-watermarks unchanged while repository and CI validation runs. diff --git a/tests/test_aerosim_lessons.py b/tests/test_aerosim_lessons.py new file mode 100644 index 0000000..3dabea7 --- /dev/null +++ b/tests/test_aerosim_lessons.py @@ -0,0 +1,45 @@ +"""Offline reference contracts; approval and runtime checks remain external.""" +from pathlib import Path +import re +import unittest + +ROOT = Path(__file__).resolve().parents[1] + + +class LessonsContract(unittest.TestCase): + def test_coherent_portable_solution_workflow(self): + skill = (ROOT / 'SKILL.md').read_text() + self.assertFalse('set solution status to `In Solution`' in skill, + 'must respect canonical lifecycle schema') + self.assertIn('references/aerosim-lessons-review.md', skill) + ref = ROOT / 'references/aerosim-lessons-review.md' + self.assertTrue(ref.exists()) + text = ref.read_text() + for value in ('d7900acfa923d8c7bb32f6e8e269048f5d4b8d4f', + 'canonical IDs', 'exact revision', 'assessment', + 'Excluded', 'no-churn'): + self.assertIn(value, text) + self.assertIn('a human team member explicitly approves', skill) + for path in (ROOT / 'references').glob('*.md'): + self.assertNotRegex(path.read_text(), r'six[- ](?:authorized|channel)') + self.assertIn('No actor authority is granted by this reference', + (ROOT / 'references/delegated-solution-package-tdd.md').read_text()) + + def test_eight_channel_boundary(self): + skill = (ROOT / 'SKILL.md').read_text() + boundary = skill.split('## Approved Information Boundary', 1)[1].split('## ', 1)[0] + channels = re.findall(r'^corp-v1--(.+)$', boundary, re.MULTILINE) + self.assertEqual(channels, ['general', 'scope', 'architecture', 'ui-ux', + 'kanban', 'delivery', 'uat', 'releases']) + self.assertNotIn('seven', skill.replace('other seven channels', 'other channels')) + self.assertIn('eight', skill) + + def test_local_links_resolve(self): + for path in [ROOT / 'SKILL.md', *sorted((ROOT / 'references').glob('*.md'))]: + for link in re.findall(r'\]\(([^)]+)\)', path.read_text()): + if '://' not in link and not link.startswith(('#', '<')): + self.assertTrue((path.parent / link.split('#')[0]).exists(), (path, link)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_task_breakdown_policy.py b/tests/test_task_breakdown_policy.py index c066de2..84984e3 100644 --- a/tests/test_task_breakdown_policy.py +++ b/tests/test_task_breakdown_policy.py @@ -59,7 +59,7 @@ class TaskBreakdownPolicyTest(unittest.TestCase): ) def test_operational_policy_is_complete_and_structured(self): - self.assertIn("version: 1.9.0", self.skill) + self.assertIn("version: 1.10.0", self.skill) self.assertEqual(policy_failures(self.task_section, self.approval_rule), []) def test_comments_and_weakened_rules_cannot_satisfy_policy(self):