[verified] refactor: reference diagrams-drawio

Merge READY_FOR_DELIVERY architecture gate

.gitea/workflows/validate.yaml

@@ -0,0 +1,17 @@
+name: Validate skill
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 2
+      - name: Run policy tests
+        run: python3 -m unittest discover -s tests -v
+      - name: Validate whitespace
+        run: git diff --check HEAD^ HEAD

SKILL.md

@@ -1,28 +1,28 @@
 ---
 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 six channels."
-version: 1.5.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 seven channels."
+version: 1.8.0
 author: Hermes Agent
 license: MIT
 metadata:
   hermes:
     tags: [corp-v1, discord, channel, architecture, c4, adr, requirements]
-    related_skills: [corp-v1--main, home-v1-discord, drawio-main, documentation-docusaurus]
+    related_skills: [corp-v1--main, home-v1-discord, diagrams-drawio, documentation-docusaurus, corp-v1--glossary]
 ---
 
 # Corp v1 Architecture Channel
 
 ## Overview
 
-This skill owns the solution phase and architecture coherence for a Corp v1 project. It monitors the project's `general`, `scope`, `architecture`, `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`, 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 `drawio-main` skill from:
+The default architecture model is C4. Architecture diagrams must be authored and validated using the global `diagrams-drawio` skill from:
 
 ```text
-https://gitea.lego-cloud.eu/home-v1-skills-code-agent/drawio-main
+https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio
 ```
 
-Do not duplicate `drawio-main` into each project by default. A project team may explicitly decide to adopt its own copy; that decision must also update the project's channel skills and steering record.
+Do not duplicate `diagrams-drawio` into each project by default. A project team may explicitly decide to adopt its own copy; that decision must also update the project's channel skills and steering record.
 
 Load the global `documentation-docusaurus` skill before changing project documentation structure, navigation, MDX, Draw.io embedding, or Docusaurus configuration. Its authoritative source is:
 
@@ -30,6 +30,19 @@ Load the global `documentation-docusaurus` skill before changing project documen
 https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus
 ```
 
+Load the global `corp-v1--glossary` skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--glossary` whenever project documentation needs to define or explain a reusable term. Maintain one canonical definition in the project's final top-level **Glossary** area and link to it from the owning domain page; do not duplicate glossary-style explanations across channel documentation.
+
+## Shared Corp v1 System Login
+
+When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1--main` and use only the Bitwarden-injected runtime secrets named:
+
+```text
+HL_V1_SSO_EMAIL
+HL_V1_SSO_PASSWORD
+```
+
+Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.
+
 ## When to Use
 
 Use this skill when:
@@ -62,12 +75,13 @@ Inspect only:
 corp-v1-<code>-general
 corp-v1-<code>-scope
 corp-v1-<code>-architecture
+corp-v1-<code>-ui-ux
 corp-v1-<code>-kanban
 corp-v1-<code>-delivery
 corp-v1-<code>-releases
 ```
 
-Use mapped-channel history to avoid duplicate work and new relevant activity from the other five channels. Never inspect another project's channels.
+Use mapped-channel history to avoid duplicate work and new relevant activity from the other six channels. Never inspect another project's channels.
 
 ## Architecture Documentation Contract
 
@@ -138,11 +152,11 @@ Every diagram must include a title, scope, element names, responsibilities, rela
 
 ## Draw.io Workflow
 
-1. Load global `drawio-main` before creating or modifying a diagram.
+1. Load global `diagrams-drawio` before creating or modifying a diagram.
 2. Load global `documentation-docusaurus` before changing the site or embedding a diagram.
 3. Store editable `.drawio` source in the documentation repository.
 4. Onboard the source through `docusaurus-plugin-drawio` using the MDX source-import workflow from `documentation-docusaurus`; do not publish only a static export.
-5. Export an additional review format only when `drawio-main` or project policy requires it.
+5. Export an additional review format only when `diagrams-drawio` or project policy requires it.
 6. Validate Draw.io source, Docusaurus build, source import, selected page/pageId, browser rendering, and console/network output.
 7. Link diagrams from Context, Overview, Container Registry entries, and FR/NFR pages as applicable.
 8. Commit source, MDX/configuration, lockfile, and any required rendered output together.
@@ -188,6 +202,23 @@ Use stable IDs such as `FR-0001` and `NFR-0001`. Requirements must be unambiguou
 
 Architecture derives and maintains implementation-task semantics, dependencies, sequencing, and readiness from the FR/NFR solution. Scope hosts the canonical task records and reader pages under their owning Feature; Architecture must not create a competing task registry page or task navigation.
 
+Architecture owns complete Task decomposition for every Feature allocated to the release.
+
+Before reporting a release planning-ready, Architecture must:
+
+1. Architecture creates missing Tasks, reviews existing Tasks, and retains, revises, supersedes, or removes them according to the current Feature outcomes and Architecture boundaries. Architecture may freely revise or remove only draft Tasks with no implementation approval, Kanban admission, execution, or completion evidence;
+2. define between two and six independently executable Tasks per Feature; permit one Task only when a recorded Architecture rationale proves it is the smallest atomic, independently verifiable boundary;
+3. map the Feature's Tasks collectively, exactly, and reciprocally to every acceptance-outcome ID and every applicable active `FR-*` and `NFR-*` record;
+4. encode acyclic within-Feature sequencing and require every entry Task to depend on all terminal Tasks of every prerequisite Feature;
+5. give each Task one specific outcome, repository/component owner, canonical/display identity, task-specific implementation artifacts, concrete inputs and outputs, failure boundaries, exclusions, verification steps, and future acceptance-evidence requirements;
+6. keep draft Tasks separate from implementation approval and Kanban Focus admission.
+
+Architecture must not report planning readiness while any Feature allocated to the release lacks this complete Task breakdown. A Feature-shaped placeholder Task, a generated empty Task group, or requirement coverage without executable Tasks does not satisfy the gate.
+
+Approved, Kanban-admitted, in-progress, or completed Tasks must not be deleted or silently rewritten. Retain an obsolete Task with a terminal Superseded or Cancelled status, its prior evidence and history, and explicit replacement links.
+
+A material change to Task scope, outcome, dependency, repository, or component invalidates the Task's existing implementation approval, returns the Task to its pre-approval state, and always requires renewed human `Approved for Implementation` before implementation can resume. After renewed approval, execution still requires a separate exact-task Kanban Focus admission.
+
 ```text
 canonical_id | display_id | feature | outcome | scope | dependencies | owner | status | acceptance evidence | affected repository/component
 ```
@@ -198,14 +229,31 @@ Use canonical Task IDs `TASK-<ZERO_PADDED_NUMBER>` and separate project-scoped d
 
 Maintain a version allocation registry linking Features to intended versions. Record target version, rationale, dependencies, readiness constraints, status, and human decision evidence. Hermes may analyze and propose allocation; the team decides which Feature goes into which version. Do not invent version assignments or treat a proposal as final.
 
+## Delivery Readiness State
+
+Architecture uses the task flow `IN_DESIGN → READY_FOR_DELIVERY → IN_PROGRESS`. `READY_FOR_DELIVERY` is a fail-closed, pre-execution readiness state: Architecture may emit it for an exact Task only when all of the following evidence is durable and linked to that Task:
+
+1. an exact item-specific `Approved for Implementation` decision from a human team member;
+2. complete task inputs, including implementation artifacts, concrete inputs and outputs, failure boundaries, exclusions, verification steps, and future acceptance-evidence requirements;
+3. evidence that all entry dependencies are satisfied; and
+4. for a Task that affects the user interface or user experience, exact approved UI/UX implementation-handoff evidence; otherwise the readiness record explicitly records UI/UX as not applicable with a rationale.
+
+`READY_FOR_DELIVERY` does not mean Focus admission, assignment, claim, implementation start, `delivery_started`, or `IN_PROGRESS`. Architecture records the satisfied gate and sends a handoff to Kanban for a separate exact-task Focus-admission decision; only the authorized delivery-flow owner may subsequently record `IN_PROGRESS` when implementation actually starts.
+
+Scope owns the canonical Task lifecycle schema. Architecture must not silently mutate or outrun Scope-owned canonical lifecycle schema: when the schema cannot represent `READY_FOR_DELIVERY`, return the handoff to Scope for canonicalization and keep the Task in its prior state. Never infer this state from solution-package completeness, UI/UX discussion, dependency expectations, CI success, or implementation activity.
+
 ## Kanban Handoff
 
-After human Feature implementation approval, Architecture sends dependency-ready task records to Kanban. Architecture does not place tasks into Focus `InBacklog`; Kanban records the separate human task-admission decision. Keep task dependencies and readiness evidence current when Kanban or Delivery reports drift.
+After human Feature implementation approval, Architecture applies the `READY_FOR_DELIVERY` gate to each exact Task and sends only qualifying task records to Kanban. Architecture does not place tasks into Focus `InBacklog`; Kanban records the separate human task-admission decision. Keep task dependencies and readiness evidence current when Kanban or Delivery reports drift.
 
 ## 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.
 
+## UI/UX Coordination
+
+Architecture supplies UI/UX with system boundaries, interfaces, data availability, security/privacy constraints, and affected containers/components. UI/UX owns the frontend experience, Penpot design source, design-system decisions, accessibility evidence, and implementation handoff. Neither channel silently changes the other channel’s approved constraints.
+
 ## Synchronization Workflow
 
 1. Read new same-project activity and enough architecture history to avoid duplicates.
@@ -213,7 +261,7 @@ Every architecture iteration must add or materially improve a useful project-doc
 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.
-6. Use `drawio-main` for every diagram change and `documentation-docusaurus` for every documentation, navigation, MDX, plugin, or embedding change.
+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.
 
@@ -235,12 +283,12 @@ Requires team approval for:
 - finalizing which Feature belongs to which version;
 - changing system boundaries, major technologies, security posture, data handling, or deployment topology;
 - resolving genuine contradictions in product requirements;
-- adopting a project-specific `drawio-main` copy;
+- adopting a project-specific `diagrams-drawio` copy;
 - irreversible or high-impact implementation/deployment work.
 
 ## Common Pitfalls
 
-1. Drawing architecture without loading `drawio-main`.
+1. Drawing architecture without loading `diagrams-drawio`.
 2. Duplicating the global Draw.io skill without a team decision.
 3. Treating every C4 level as mandatory regardless of value.
 4. Marking draft decisions or requirements as approved.
@@ -256,13 +304,14 @@ Requires team approval for:
 14. Publishing static diagram exports without onboarding the editable `.drawio` source into Docusaurus.
 15. Reintroducing Architecture Feature pages or task reader navigation instead of linking canonical Scope pages.
 16. Renaming task display IDs by rewriting historic canonical identities, evidence, or append-only hashes.
+17. Treating `READY_FOR_DELIVERY` as automatic Focus admission or `IN_PROGRESS`, or emitting it without exact implementation approval, complete task inputs, satisfied entry dependencies, and applicable approved UI/UX handoff evidence.
 
 ## Verification Checklist
 
-- [ ] Only the six same-project channels were inspected.
+- [ ] Only the seven same-project channels were inspected.
 - [ ] Architecture documentation reflects verified status.
 - [ ] C4 scope and level are appropriate.
-- [ ] `drawio-main` governed every diagram change.
+- [ ] `diagrams-drawio` governed every diagram change.
 - [ ] `documentation-docusaurus` governed navigation, MDX, plugin, and source embedding changes.
 - [ ] Architecture has its dedicated sidebar ordered Context, Overview, Container Registry, Requirements - Functional → Registry + FR pages, Requirements - Non-Functional → Registry + NFR pages.
 - [ ] Architecture has no Features menu/pages and no task registry/reader navigation.
@@ -273,9 +322,11 @@ Requires team approval for:
 - [ ] ADR, FR, and NFR entries have stable IDs and traceability.
 - [ ] Every solution Feature has explicit human `Approved for Solution` evidence.
 - [ ] Eligible Features have dependency-aware task derivation and version proposals, with canonical task reader pages under their Scope Feature.
+- [ ] Every Feature allocated to the planned release has a reviewed, non-placeholder Task breakdown covering every acceptance outcome and applicable requirement, with acyclic within-Feature and cross-Feature dependencies.
 - [ ] Task display IDs use `<UPPERCASE_PROJECT_CODE>-TS-<NUMBER>` without rewriting historic canonical identities, evidence, or append-only hashes.
 - [ ] Only a human team member moved a Feature to `Approved for Implementation` or finalized its version.
-- [ ] Tasks were proposed to Kanban with readiness/dependency evidence; Architecture did not self-admit them to Focus `InBacklog`.
+- [ ] Every emitted `READY_FOR_DELIVERY` Task has exact implementation approval, complete task inputs, satisfied entry dependencies, and applicable approved UI/UX handoff evidence (or an explicit not-applicable rationale).
+- [ ] `READY_FOR_DELIVERY` remained distinct from Focus admission, assignment, claim, `delivery_started`, and `IN_PROGRESS`; Architecture did not self-admit Tasks to Focus `InBacklog`.
 - [ ] At least one useful solution artifact was improved, or the exact human approval/clarification gate was documented.
 - [ ] Proposed items remain visibly proposed.
 - [ ] Documentation and diagram checks passed.

tests/test_task_breakdown_policy.py

@@ -0,0 +1,105 @@
+from pathlib import Path
+import re
+import unittest
+
+
+COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+def task_section(skill: str) -> str:
+    operative = COMMENT.sub("", skill)
+    return operative.split("## Task and Dependency Breakdown", 1)[1].split("## Version Allocation", 1)[0]
+
+
+def readiness_section(skill: str) -> str:
+    operative = COMMENT.sub("", skill)
+    return operative.split("## Delivery Readiness State", 1)[1].split("## Kanban Handoff", 1)[0]
+
+
+def policy_failures(section: str, approval_rule: str) -> list[str]:
+    section = COMMENT.sub("", section)
+    patterns = {
+        "ownership": r"(?m)^Architecture owns complete Task decomposition for every Feature allocated to the release\.$",
+        "lifecycle": r"(?m)^1\. Architecture creates missing Tasks, reviews existing Tasks, and retains, revises, supersedes, or removes them according to the current Feature outcomes and Architecture boundaries\. Architecture may freely revise or remove only draft Tasks with no implementation approval, Kanban admission, execution, or completion evidence;$",
+        "cardinality": r"(?m)^2\. define between two and six independently executable Tasks per Feature; permit one Task only when a recorded Architecture rationale proves it is the smallest atomic, independently verifiable boundary;$",
+        "mapping": r"(?m)^3\. map the Feature's Tasks collectively, exactly, and reciprocally to every acceptance-outcome ID and every applicable active `FR-\*` and `NFR-\*` record;$",
+        "dependencies": r"(?m)^4\. encode acyclic within-Feature sequencing and require every entry Task to depend on all terminal Tasks of every prerequisite Feature;$",
+        "contract": r"(?m)^5\. give each Task one specific outcome, repository/component owner, canonical/display identity, task-specific implementation artifacts, concrete inputs and outputs, failure boundaries, exclusions, verification steps, and future acceptance-evidence requirements;$",
+        "separate-gates": r"(?m)^6\. keep draft Tasks separate from implementation approval and Kanban Focus admission\.$",
+        "planning-readiness": r"(?m)^Architecture must not report planning readiness while any Feature allocated to the release lacks this complete Task breakdown\. A Feature-shaped placeholder Task, a generated empty Task group, or requirement coverage without executable Tasks does not satisfy the gate\.$",
+        "protected-history": r"(?m)^Approved, Kanban-admitted, in-progress, or completed Tasks must not be deleted or silently rewritten\. Retain an obsolete Task with a terminal Superseded or Cancelled status, its prior evidence and history, and explicit replacement links\.$",
+        "approval-invalidation": approval_rule,
+    }
+    return [name for name, pattern in patterns.items() if re.search(pattern, section) is None]
+
+
+def readiness_failures(section: str) -> list[str]:
+    patterns = {
+        "sequence": r"`IN_DESIGN → READY_FOR_DELIVERY → IN_PROGRESS`",
+        "implementation-approval": r"exact item-specific `Approved for Implementation`",
+        "complete-inputs": r"complete task inputs",
+        "entry-dependencies": r"all entry dependencies are satisfied",
+        "ui-ux-evidence": r"approved UI/UX implementation-handoff evidence",
+        "ui-ux-not-applicable": r"explicitly records UI/UX as not applicable",
+        "not-execution": r"does not mean Focus admission, assignment, claim, implementation start, `delivery_started`, or `IN_PROGRESS`",
+        "kanban-admission": r"handoff to Kanban for a separate exact-task Focus-admission decision",
+        "scope-schema": r"must not silently mutate or outrun Scope-owned canonical lifecycle schema",
+        "scope-fallback": r"return the handoff to Scope for canonicalization and keep the Task in its prior state",
+    }
+    return [name for name, pattern in patterns.items() if re.search(pattern, section) is None]
+
+
+class TaskBreakdownPolicyTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.skill = Path(__file__).parents[1].joinpath("SKILL.md").read_text()
+        cls.task_section = task_section(cls.skill)
+        cls.approval_rule = (
+            r"(?m)^A material change to Task scope, outcome, dependency, repository, or component invalidates the Task's existing implementation approval, returns the Task to its pre-approval state, and always requires renewed human `Approved for Implementation` before implementation can resume\. After renewed approval, execution still requires a separate exact-task Kanban Focus admission\.$"
+        )
+
+    def test_operational_policy_is_complete_and_structured(self):
+        self.assertIn("version: 1.8.0", self.skill)
+        self.assertEqual(policy_failures(self.task_section, self.approval_rule), [])
+
+    def test_comments_and_weakened_rules_cannot_satisfy_policy(self):
+        self.assertTrue(policy_failures(f"<!--{self.task_section}-->", self.approval_rule))
+        mutations = {
+            "draft-protection": ("with no implementation approval, Kanban admission, execution, or completion evidence", "even with implementation approval, Kanban admission, execution, or completion evidence"),
+            "planning-readiness": ("must not report planning readiness", "may report planning readiness"),
+            "placeholder-rejection": ("A Feature-shaped placeholder Task, a generated empty Task group, or requirement coverage without executable Tasks does not satisfy the gate.", ""),
+            "cardinality": ("between two and six", "at least two"),
+            "mapping": ("exactly, and reciprocally", "loosely"),
+            "dependencies": ("all terminal Tasks", "some Tasks"),
+            "approval": ("invalidates the Task's existing implementation approval", "invalidates prior readiness evidence"),
+            "renewal": ("always requires renewed human", "may require renewed human"),
+        }
+        for name, (old, new) in mutations.items():
+            with self.subTest(name=name):
+                self.assertTrue(policy_failures(self.task_section.replace(old, new), self.approval_rule))
+
+    def test_ready_for_delivery_is_a_fail_closed_pre_execution_state(self):
+        section = readiness_section(self.skill)
+        self.assertEqual(readiness_failures(section), [])
+
+    def test_ready_for_delivery_gate_cannot_be_weakened(self):
+        section = readiness_section(self.skill)
+        mutations = [
+            ("exact item-specific `Approved for Implementation`", "implementation is expected"),
+            ("complete task inputs", "partial task inputs"),
+            ("all entry dependencies are satisfied", "entry dependencies are expected to be satisfied"),
+            ("approved UI/UX implementation-handoff evidence", "a UI/UX discussion"),
+            ("explicitly records UI/UX as not applicable with a rationale", "assumes UI/UX is not applicable"),
+            ("separate exact-task Focus-admission decision", "automatic Focus admission"),
+            ("does not mean Focus admission", "means Focus admission"),
+            ("return the handoff to Scope for canonicalization and keep the Task in its prior state", "continue with a local readiness state"),
+        ]
+        for old, new in mutations:
+            with self.subTest(old=old):
+                changed = section.replace(old, new)
+                self.assertNotEqual(changed, section)
+                self.assertTrue(readiness_failures(changed))
+
+
+if __name__ == "__main__":
+    unittest.main()