aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/docs/tool-discovery-report.md

@@ -1,87 +1,87 @@
-# Tool Discovery Report - Design Squad
-
-## Metadata
-- Date: 2026-02-17
-- Squad: `design`
-- Domain: design-system
-- Policy: internal-first (`internal-infrastructure-library.yaml`)
-
-## Internal Coverage Summary
-
-### Internal assets validated first
-1. `workspace/domains/design-system/*` (tokens, components, guidelines, MCP handlers)
-2. `squads/design/scripts/design-system/*` (manifest sync, metadata generation/validation, MCP checks)
-3. `squads/design/*` (tasks, checklists, workflows, protocols)
-4. `.aios-core/infrastructure/*` (generic validation and dependency tooling)
-
-### Capabilities fully covered internally
-- DS token catalog and component metadata
-- DS manifest synchronization and drift validation
-- MCP skeleton and MCP tool validation
-- Task/checklist governance validation
-- Accessibility/process governance checklists
-
-### Capabilities partially covered internally
-- Visual regression baseline execution across browsers/cloud
-- Figma file ingestion and live sync at scale
-- Cross-repo design telemetry aggregation
-
-### External-only or enhancement gaps
-1. Managed visual regression service integration
-2. Official design-file API sync hardening (Figma org-level workflows)
-3. Optional cloud artifact storage/CDN for DS assets
-
-## External Discovery Scope (only for real gaps)
-
-### MCP / APIs
-- Figma API / MCP bridge (enhancement for `ds-figma-pipeline`)
-- GitHub API (PR checks for DS governance automation)
-
-### CLI / Tooling
-- Playwright (fallback/enhancement for visual checks)
-- Chromatic or Percy (managed visual regression)
-
-### Libraries
-- Storybook test runner ecosystem (if squad chooses Storybook-first baseline)
-
-## Internal vs External Decisions
-
-### Internal primary (required)
-1. `squads/design/scripts/design-system/sync_design_manifest.cjs`
-2. `squads/design/scripts/design-system/validate_design_manifest_drift.cjs`
-3. `squads/design/scripts/design-system/generate_components_metadata.cjs`
-4. `squads/design/scripts/design-system/validate_components_metadata.cjs`
-5. `squads/design/scripts/design-system/validate_task_checklist_bindings.cjs`
-6. `squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
-7. `squads/design/scripts/design-system/test_mcp_tools.cjs`
-
-### External fallback/enhancement (optional)
-1. Playwright (`ds-visual-regression`) when native baselines are insufficient
-2. Chromatic/Percy for managed diff pipelines
-3. Figma API for enterprise sync scenarios
-
-## Prioritized Recommendations
-
-### Quick Wins
-1. Keep internal scripts as mandatory quality gate before any external tool.
-2. Wire visual regression tasks to prefer local Playwright path first.
-3. Keep Figma integration optional and triggered only by explicit design-file workflows.
-
-### Strategic
-1. Add unified wrapper task to orchestrate metadata + manifest + MCP health in one command.
-2. Add explicit fallback matrix in `ds-visual-regression.md` by cost tier.
-
-### Avoid for now
-1. Replacing internal DS governance pipeline with third-party SaaS.
-2. Adding external tools that duplicate existing internal checks.
-
-## Sources
-- `workspace/domains/design-system/mcp/config.json`
-- `workspace/domains/design-system/metadata/components.json`
-- `workspace/domains/design-system/metadata/tokens/index.json`
-- `squads/design/scripts/design-system/sync_design_manifest.cjs`
-- `squads/design/scripts/design-system/validate_design_manifest_drift.cjs`
-- `squads/design/scripts/design-system/validate_task_checklist_bindings.cjs`
-- `squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
-- `squads/design/config.yaml`
-- `squads/design/README.md`
+# Tool Discovery Report - Design Squad
+
+## Metadata
+- Date: 2026-02-17
+- Squad: `design`
+- Domain: design-system
+- Policy: internal-first (`internal-infrastructure-library.yaml`)
+
+## Internal Coverage Summary
+
+### Internal assets validated first
+1. `workspace/domains/design-system/*` (tokens, components, guidelines, MCP handlers)
+2. `squads/design/scripts/design-system/*` (manifest sync, metadata generation/validation, MCP checks)
+3. `squads/design/*` (tasks, checklists, workflows, protocols)
+4. `.aios-core/infrastructure/*` (generic validation and dependency tooling)
+
+### Capabilities fully covered internally
+- DS token catalog and component metadata
+- DS manifest synchronization and drift validation
+- MCP skeleton and MCP tool validation
+- Task/checklist governance validation
+- Accessibility/process governance checklists
+
+### Capabilities partially covered internally
+- Visual regression baseline execution across browsers/cloud
+- Figma file ingestion and live sync at scale
+- Cross-repo design telemetry aggregation
+
+### External-only or enhancement gaps
+1. Managed visual regression service integration
+2. Official design-file API sync hardening (Figma org-level workflows)
+3. Optional cloud artifact storage/CDN for DS assets
+
+## External Discovery Scope (only for real gaps)
+
+### MCP / APIs
+- Figma API / MCP bridge (enhancement for `ds-figma-pipeline`)
+- GitHub API (PR checks for DS governance automation)
+
+### CLI / Tooling
+- Playwright (fallback/enhancement for visual checks)
+- Chromatic or Percy (managed visual regression)
+
+### Libraries
+- Storybook test runner ecosystem (if squad chooses Storybook-first baseline)
+
+## Internal vs External Decisions
+
+### Internal primary (required)
+1. `squads/design/scripts/design-system/sync_design_manifest.cjs`
+2. `squads/design/scripts/design-system/validate_design_manifest_drift.cjs`
+3. `squads/design/scripts/design-system/generate_components_metadata.cjs`
+4. `squads/design/scripts/design-system/validate_components_metadata.cjs`
+5. `squads/design/scripts/design-system/validate_task_checklist_bindings.cjs`
+6. `squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
+7. `squads/design/scripts/design-system/test_mcp_tools.cjs`
+
+### External fallback/enhancement (optional)
+1. Playwright (`ds-visual-regression`) when native baselines are insufficient
+2. Chromatic/Percy for managed diff pipelines
+3. Figma API for enterprise sync scenarios
+
+## Prioritized Recommendations
+
+### Quick Wins
+1. Keep internal scripts as mandatory quality gate before any external tool.
+2. Wire visual regression tasks to prefer local Playwright path first.
+3. Keep Figma integration optional and triggered only by explicit design-file workflows.
+
+### Strategic
+1. Add unified wrapper task to orchestrate metadata + manifest + MCP health in one command.
+2. Add explicit fallback matrix in `ds-visual-regression.md` by cost tier.
+
+### Avoid for now
+1. Replacing internal DS governance pipeline with third-party SaaS.
+2. Adding external tools that duplicate existing internal checks.
+
+## Sources
+- `workspace/domains/design-system/mcp/config.json`
+- `workspace/domains/design-system/metadata/components.json`
+- `workspace/domains/design-system/metadata/tokens/index.json`
+- `squads/design/scripts/design-system/sync_design_manifest.cjs`
+- `squads/design/scripts/design-system/validate_design_manifest_drift.cjs`
+- `squads/design/scripts/design-system/validate_task_checklist_bindings.cjs`
+- `squads/design/scripts/design-system/validate_mcp_skeleton.cjs`
+- `squads/design/config.yaml`
+- `squads/design/README.md`

package/pro/squads/design/docs/tool-integration-plan.md

@@ -1,44 +1,44 @@
-# Tool Integration Plan - Design Squad
-
-## Objective
-Keep Design Squad execution internal-first and integrate external tooling only where internal coverage is partial.
-
-## Wave 1 (Immediate)
-1. Enforce internal quality chain as baseline:
-   - `generate_components_metadata.cjs`
-   - `validate_components_metadata.cjs`
-   - `sync_design_manifest.cjs`
-   - `validate_design_manifest_drift.cjs`
-   - `validate_task_checklist_bindings.cjs`
-   - `validate_mcp_skeleton.cjs`
-2. Require this chain before `ds-*` delivery completion.
-3. Add structural AST baseline for MCP/contracts:
-   - `npm run ast:scan:design-system`
-   - output: `.aios/ast/design-system-structural-model.json`
-
-## Wave 2 (Short-term)
-1. In `ds-visual-regression`, prioritize local Playwright baseline path.
-2. Add explicit cost/benefit gate before adopting managed visual regression SaaS.
-3. Keep `ds-figma-pipeline` external integration optional and capability-driven.
-
-## Wave 3 (Optional)
-1. Introduce managed visual regression provider (Chromatic/Percy) only for teams needing multi-browser cloud snapshots and PR UX.
-2. Introduce enterprise Figma API automation only for orgs with approved app governance.
-
-## Task Wiring (Internal-first)
-- `ds-setup-design-system`: internal scripts + metadata registry
-- `ds-generate-documentation`: local metadata/guideline sources
-- `ds-validate-ai-readiness`: internal MCP health first
-- `ds-visual-regression`: local path first, managed provider as optional enhancement
-- `ds-figma-pipeline`: explicit opt-in integration
-
-## Success Metrics
-1. 100% DS task completions pass internal quality chain.
-2. 0 external tool usage for capabilities already covered internally.
-3. External tools adopted only with documented gap justification.
-
-## Validation Checklist
-- [ ] Internal capability used as primary for each mapped capability
-- [ ] External tools tagged as fallback/enhancement
-- [ ] Cost and access constraints documented before external adoption
-- [ ] `tool-discovery-report.md` and `capability-tools.yaml` synchronized
+# Tool Integration Plan - Design Squad
+
+## Objective
+Keep Design Squad execution internal-first and integrate external tooling only where internal coverage is partial.
+
+## Wave 1 (Immediate)
+1. Enforce internal quality chain as baseline:
+   - `generate_components_metadata.cjs`
+   - `validate_components_metadata.cjs`
+   - `sync_design_manifest.cjs`
+   - `validate_design_manifest_drift.cjs`
+   - `validate_task_checklist_bindings.cjs`
+   - `validate_mcp_skeleton.cjs`
+2. Require this chain before `ds-*` delivery completion.
+3. Add structural AST baseline for MCP/contracts:
+   - `npm run ast:scan:design-system`
+   - output: `.aios/ast/design-system-structural-model.json`
+
+## Wave 2 (Short-term)
+1. In `ds-visual-regression`, prioritize local Playwright baseline path.
+2. Add explicit cost/benefit gate before adopting managed visual regression SaaS.
+3. Keep `ds-figma-pipeline` external integration optional and capability-driven.
+
+## Wave 3 (Optional)
+1. Introduce managed visual regression provider (Chromatic/Percy) only for teams needing multi-browser cloud snapshots and PR UX.
+2. Introduce enterprise Figma API automation only for orgs with approved app governance.
+
+## Task Wiring (Internal-first)
+- `ds-setup-design-system`: internal scripts + metadata registry
+- `ds-generate-documentation`: local metadata/guideline sources
+- `ds-validate-ai-readiness`: internal MCP health first
+- `ds-visual-regression`: local path first, managed provider as optional enhancement
+- `ds-figma-pipeline`: explicit opt-in integration
+
+## Success Metrics
+1. 100% DS task completions pass internal quality chain.
+2. 0 external tool usage for capabilities already covered internally.
+3. External tools adopted only with documented gap justification.
+
+## Validation Checklist
+- [ ] Internal capability used as primary for each mapped capability
+- [ ] External tools tagged as fallback/enhancement
+- [ ] Cost and access constraints documented before external adoption
+- [ ] `tool-discovery-report.md` and `capability-tools.yaml` synchronized

package/pro/squads/design/protocols/ai-first-governance.md

@@ -1,56 +1,56 @@
-# AI-First Governance Protocol (Design Squad)
-
-## Purpose
-
-Prevent research drift, contradictory claims, and non-canonical references by enforcing behavior at agent/task/workflow level.
-
-## Mandatory Rules
-
-1. Canonical Source Hierarchy
-- `workspace/system/*` for global policy/governance.
-- `workspace/ui/registry.json` for component distribution truth.
-- `workspace/domains/design-system/*` for DS metadata and glossary.
-- `squads/design/data/*` for squad-local knowledge and guides.
-- `docs/research/*` is supporting evidence, never final source of truth.
-
-2. Evidence Contract
-- Every recommendation must include explicit evidence pointers:
-  - artifact path
-  - status (`implemented`, `partial`, `concept`)
-  - date (`YYYY-MM-DD`)
-- If evidence is missing, mark as `assumption` and do not present as fact.
-
-3. Contradiction Guard
-- Never claim completion if any dependency is `partial` or `concept`.
-- If two artifacts conflict, prefer canonical source hierarchy and log conflict.
-
-4. Research-to-Execution Handshake
-- Before proposing execution, map:
-  - `Existing` (what already exists)
-  - `Gap` (what is missing)
-  - `Decision` (what will be done now)
-- Output must include unresolved items explicitly.
-
-5. Language for Status Claims
-- Use only:
-  - `Implemented`
-  - `Partially implemented`
-  - `Concept only`
-- Avoid absolute statements like "100% complete" unless all dependencies are `Implemented`.
-
-## Required Output Block (for agents/tasks)
-
-```yaml
-governance_check:
-  protocol: squads/design/protocols/ai-first-governance.md
-  canonical_sources_checked:
-    - path: ""
-      status: "implemented|partial|concept"
-      date: "YYYY-MM-DD"
-  evidence:
-    - claim: ""
-      source: ""
-  contradictions_found: []
-  unresolved_items: []
-```
-
+# AI-First Governance Protocol (Design Squad)
+
+## Purpose
+
+Prevent research drift, contradictory claims, and non-canonical references by enforcing behavior at agent/task/workflow level.
+
+## Mandatory Rules
+
+1. Canonical Source Hierarchy
+- `workspace/system/*` for global policy/governance.
+- `workspace/ui/registry.json` for component distribution truth.
+- `workspace/domains/design-system/*` for DS metadata and glossary.
+- `squads/design/data/*` for squad-local knowledge and guides.
+- `docs/research/*` is supporting evidence, never final source of truth.
+
+2. Evidence Contract
+- Every recommendation must include explicit evidence pointers:
+  - artifact path
+  - status (`implemented`, `partial`, `concept`)
+  - date (`YYYY-MM-DD`)
+- If evidence is missing, mark as `assumption` and do not present as fact.
+
+3. Contradiction Guard
+- Never claim completion if any dependency is `partial` or `concept`.
+- If two artifacts conflict, prefer canonical source hierarchy and log conflict.
+
+4. Research-to-Execution Handshake
+- Before proposing execution, map:
+  - `Existing` (what already exists)
+  - `Gap` (what is missing)
+  - `Decision` (what will be done now)
+- Output must include unresolved items explicitly.
+
+5. Language for Status Claims
+- Use only:
+  - `Implemented`
+  - `Partially implemented`
+  - `Concept only`
+- Avoid absolute statements like "100% complete" unless all dependencies are `Implemented`.
+
+## Required Output Block (for agents/tasks)
+
+```yaml
+governance_check:
+  protocol: squads/design/protocols/ai-first-governance.md
+  canonical_sources_checked:
+    - path: ""
+      status: "implemented|partial|concept"
+      date: "YYYY-MM-DD"
+  evidence:
+    - claim: ""
+      source: ""
+  contradictions_found: []
+  unresolved_items: []
+```
+

package/pro/squads/design/protocols/governance-execution-boundary.md

@@ -1,59 +1,59 @@
-# Governance-Execution Boundary Protocol
-
-## Purpose
-
-Define the strict boundary between governance (rule-making) and execution (rule-using) within the Design Squad.
-
-## Principle
-
-> "Governance creates, execution uses."
-
-No execution agent may create new governance artifacts (rules, tokens specs, protocols, checklists). No governance agent should implement components or run audits directly.
-
-## Ownership Matrix
-
-### Governance Agents (Create Rules)
-
-| Agent | Owns | Creates |
-|-------|------|---------|
-| @design-chief | Orchestration, routing | Quality gate definitions, routing rules |
-| @dave-malouf | DesignOps, process | Maturity models, scaling protocols, operational checklists |
-| @dan-mall | Adoption, stakeholder | Adoption frameworks, narrative guidelines |
-
-### Execution Agents (Use Rules)
-
-| Agent | Owns | Uses |
-|-------|------|------|
-| @brad-frost | Architecture, components | Token specs, component matrix, WCAG checklists |
-| @nano-banana-generator | Visual support | Visual spec templates, brand tokens |
-
-## Artifact Ownership
-
-| Artifact Type | Owner (Governance) | Consumer (Execution) |
-|---------------|-------------------|---------------------|
-| Token specifications | @design-chief | @brad-frost |
-| Component matrix | @dave-malouf | @brad-frost |
-| WCAG checklists | @dave-malouf | @brad-frost |
-| Prompt injection templates | @design-chief | All agents |
-| Registry schema | @design-chief | @brad-frost |
-| Handoff protocols | @dave-malouf | All agents |
-| Visual specs | @design-chief | @nano-banana-generator |
-
-## Decision Escalation
-
-1. **Execution agent needs new rule** → Request to @design-chief
-2. **Governance conflict** → @design-chief mediates
-3. **Cross-squad governance** → Follow handoff protocol
-4. **Emergency override** → @design-chief with documented justification
-
-## Enforcement
-
-- Agents MUST check their role before creating artifacts
-- Governance agents MUST NOT implement code directly
-- Execution agents MUST cite governance source for every decision
-- Violations are logged and reviewed in squad retrospectives
-
-## Related
-
-- [AI-First Governance](ai-first-governance.md)
-- [Handoff Protocol](handoff.md)
+# Governance-Execution Boundary Protocol
+
+## Purpose
+
+Define the strict boundary between governance (rule-making) and execution (rule-using) within the Design Squad.
+
+## Principle
+
+> "Governance creates, execution uses."
+
+No execution agent may create new governance artifacts (rules, tokens specs, protocols, checklists). No governance agent should implement components or run audits directly.
+
+## Ownership Matrix
+
+### Governance Agents (Create Rules)
+
+| Agent | Owns | Creates |
+|-------|------|---------|
+| @design-chief | Orchestration, routing | Quality gate definitions, routing rules |
+| @dave-malouf | DesignOps, process | Maturity models, scaling protocols, operational checklists |
+| @dan-mall | Adoption, stakeholder | Adoption frameworks, narrative guidelines |
+
+### Execution Agents (Use Rules)
+
+| Agent | Owns | Uses |
+|-------|------|------|
+| @brad-frost | Architecture, components | Token specs, component matrix, WCAG checklists |
+| @nano-banana-generator | Visual support | Visual spec templates, brand tokens |
+
+## Artifact Ownership
+
+| Artifact Type | Owner (Governance) | Consumer (Execution) |
+|---------------|-------------------|---------------------|
+| Token specifications | @design-chief | @brad-frost |
+| Component matrix | @dave-malouf | @brad-frost |
+| WCAG checklists | @dave-malouf | @brad-frost |
+| Prompt injection templates | @design-chief | All agents |
+| Registry schema | @design-chief | @brad-frost |
+| Handoff protocols | @dave-malouf | All agents |
+| Visual specs | @design-chief | @nano-banana-generator |
+
+## Decision Escalation
+
+1. **Execution agent needs new rule** → Request to @design-chief
+2. **Governance conflict** → @design-chief mediates
+3. **Cross-squad governance** → Follow handoff protocol
+4. **Emergency override** → @design-chief with documented justification
+
+## Enforcement
+
+- Agents MUST check their role before creating artifacts
+- Governance agents MUST NOT implement code directly
+- Execution agents MUST cite governance source for every decision
+- Violations are logged and reviewed in squad retrospectives
+
+## Related
+
+- [AI-First Governance](ai-first-governance.md)
+- [Handoff Protocol](handoff.md)

package/pro/squads/design/protocols/handoff.md

@@ -1,60 +1,60 @@
-# Design System Squad - Handoff Protocol
-
-**Version:** 2.0.0  
-**Purpose:** Preserve context across DS agents and cross-squad delegation.
-
-## Standard Format
-
-```yaml
-handoff:
-  from: "@{current-agent}"
-  to: "@{target-agent}|/{target-squad}"
-  project: "{project-name}"
-  objective: "{goal}"
-  completed:
-    - "{done_1}"
-  artifacts:
-    - "{path_1}"
-  constraints:
-    - "{constraint_1}"
-  open_risks:
-    - "{risk_1}"
-  next_steps:
-    - "{next_step_1}"
-```
-
-## Intra-Squad Flows
-
-### 1. DesignOps -> Design System Architecture
-`@dave-malouf -> @brad-frost`
-
-Use when operations diagnosis is complete and implementation starts.
-
-### 2. Architecture -> Orchestration
-`@brad-frost -> @design-chief`
-
-Use when work requires staged rollout, review routing, or cross-squad coordination.
-
-### 3. Adoption Narrative -> Ops/Architecture
-`@dan-mall -> @dave-malouf` and/or `@brad-frost`
-
-Use when buy-in is secured and execution plan must be formalized.
-
-## Cross-Squad Flows
-
-### 4. DS -> Brand
-`@design-chief -> /Brand`
-
-Use when request is logo, brand strategy, positioning, or pricing.
-
-### 5. DS -> Content Visual
-`@design-chief -> /ContentVisual`
-
-Use when request is thumbnail, YouTube visuals, photography, or editing.
-
-## Quality Rules
-
-- No handoff without explicit objective.
-- No handoff without artifact paths.
-- No out-of-scope execution inside `squads/design`.
-- Receiver must confirm acceptance before execution.
+# Design System Squad - Handoff Protocol
+
+**Version:** 2.0.0  
+**Purpose:** Preserve context across DS agents and cross-squad delegation.
+
+## Standard Format
+
+```yaml
+handoff:
+  from: "@{current-agent}"
+  to: "@{target-agent}|/{target-squad}"
+  project: "{project-name}"
+  objective: "{goal}"
+  completed:
+    - "{done_1}"
+  artifacts:
+    - "{path_1}"
+  constraints:
+    - "{constraint_1}"
+  open_risks:
+    - "{risk_1}"
+  next_steps:
+    - "{next_step_1}"
+```
+
+## Intra-Squad Flows
+
+### 1. DesignOps -> Design System Architecture
+`@dave-malouf -> @brad-frost`
+
+Use when operations diagnosis is complete and implementation starts.
+
+### 2. Architecture -> Orchestration
+`@brad-frost -> @design-chief`
+
+Use when work requires staged rollout, review routing, or cross-squad coordination.
+
+### 3. Adoption Narrative -> Ops/Architecture
+`@dan-mall -> @dave-malouf` and/or `@brad-frost`
+
+Use when buy-in is secured and execution plan must be formalized.
+
+## Cross-Squad Flows
+
+### 4. DS -> Brand
+`@design-chief -> /Brand`
+
+Use when request is logo, brand strategy, positioning, or pricing.
+
+### 5. DS -> Content Visual
+`@design-chief -> /ContentVisual`
+
+Use when request is thumbnail, YouTube visuals, photography, or editing.
+
+## Quality Rules
+
+- No handoff without explicit objective.
+- No handoff without artifact paths.
+- No out-of-scope execution inside `squads/design`.
+- Receiver must confirm acceptance before execution.