chati-dev 4.1.5 → 4.2.0

package/framework/agents/plan/ux.md

@@ -54,7 +54,9 @@ Coordinate the design experience by activating 3 specialist sub-agents in sequen
 
 ## Execution: 5-Step Coordination
 
-### Step 1: Activate Brand & DS Architect (Phase 0)
+### Step 1: Activate Brand & DS Architect (Phase 0 — sequential, requires user approval)
+
+This step runs SEQUENTIALLY (not in parallel) because the visual direction must be approved by the user before other sub-agents can start.
 
 Read `chati.dev/agents/plan/ux-brand-architect.md` and execute Phase 0:
 - Brand identity (voice, visual language, typography, color, spacing, iconography, motion philosophy)
@@ -62,48 +64,73 @@ Read `chati.dev/agents/plan/ux-brand-architect.md` and execute Phase 0:
 - Reference benchmarking (5 permanent sites + user-provided)
 - Brandbook outputs: `brandbook.md` + `brandbook.html` (14 sections, standalone)
 
-**Gate**: Brandbook must be complete before proceeding. User must approve visual direction.
-
-### Step 2: Activate UX Researcher (Phases 1-2)
-
-Read `chati.dev/agents/plan/ux-researcher.md` and execute Phases 1-2:
-- User flow mapping for all personas (happy + error paths)
-- Information architecture / sitemap
-- Responsive strategy with breakpoints
-- Layout diversity (min 2 archetypes)
-- Domain-realistic content (zero lorem ipsum)
-
-**Input**: Reads brandbook for visual direction context.
-**Output**: Sections 1-2 of ux-specification.md.
-
-### Step 3: Activate Component Engineer (Phase 3)
-
-Read `chati.dev/agents/plan/ux-component-engineer.md` and execute Phase 3:
-- Interaction patterns (forms, loading, empty, notifications, errors)
-- Component hierarchy (Atomic Design: atoms, molecules, organisms)
-- Component discovery via 21st.dev (WebFetch scrapping)
-- Component Discovery Log (MANDATORY: every molecule/organism)
-- Accessibility audit (WCAG 2.2 + APCA)
-- Motion System (library, tokens, micro-interactions, scroll animations)
-- States coverage (all states for all interactive components)
-
-**Input**: Reads brandbook for motion personality, reads user flows for component identification.
-**Output**: Section 3 of ux-specification.md + component-discovery-log.md.
-
-### Step 4: Activate Brand & DS Architect (Phase 4 — second pass)
-
-Return to Brand & DS Architect for Design System completion:
+**Gate**: Brandbook must be complete and user must approve visual direction before proceeding.
+
+When in solo mode: read and execute in-conversation (existing behavior).
+When in team mode: spawn via Agent tool, wait for completion before Step 2.
+
+### Step 2: Spawn UX Sub-Team (Phases 1-3 — parallel after brand approval)
+
+After brand direction is approved, spawn UX Researcher and Component Engineer as a **Mini-Team** using the Agent tool. Both run in parallel and communicate via sub-team mailbox.
+
+Create sub-team mailbox directory: `.chati/teams/{team_id}/sub-ux/mailbox/`
+
+Spawn 2 agents via Agent tool IN PARALLEL (single message, both calls):
+
+```
+Agent tool call 1:
+  description: "UX Researcher — user flows, IA, responsive strategy"
+  prompt: [Read and follow chati.dev/agents/plan/ux-researcher.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-ux/mailbox/
+    Brand direction approved. Read brandbook at chati.dev/artifacts/4-UX/brandbook.md
+    Execute Phases 1-2: user flows (happy + error paths), IA/sitemap, responsive, layout diversity.
+    Write output to sections 1-2 of chati.dev/artifacts/4-UX/ux-specification.md
+    After completing: write cross-review to mailbox for Component Engineer:
+      type: cross_review_request
+      to: component-engineer
+      questions:
+        1. "Do all screens in the user flows have corresponding components in your hierarchy?"
+        2. "Are the responsive breakpoints compatible with your component variant strategy?"
+        3. "Are there interaction patterns implied by the flows that need dedicated components?"
+    Read Component Engineer's cross-review response before finalizing.]
+
+Agent tool call 2:
+  description: "Component Engineer — components, motion, a11y"
+  prompt: [Read and follow chati.dev/agents/plan/ux-component-engineer.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-ux/mailbox/
+    Brand direction approved. Read brandbook at chati.dev/artifacts/4-UX/brandbook.md
+    Execute Phase 3: interaction patterns, atomic design, component discovery, a11y, motion system.
+    Write output to section 3 of chati.dev/artifacts/4-UX/ux-specification.md
+    Write component-discovery-log.md
+    After completing: write cross-review to mailbox for UX Researcher:
+      type: cross_review_request
+      to: ux-researcher
+      questions:
+        1. "Are there user flow states that need components I haven't specified?"
+        2. "Does the motion system timing conflict with your flow transition expectations?"
+        3. "Are the error/empty/loading states sufficient for all flows you defined?"
+    Read UX Researcher's cross-review response before finalizing.]
+```
+
+When NOT in team mode (solo/fallback): execute sequentially in-conversation — first UX Researcher (Phases 1-2), then Component Engineer (Phase 3).
+
+### Step 3: Brand & DS Architect — Second Pass (Phase 4)
+
+After UX Researcher and Component Engineer complete, re-activate Brand Architect for Design System completion:
 - Complete 6 token layers using findings from Steps 2-3
 - Map components to tokens
 - Tokenization audit (>= 95% coverage)
 - Dark mode strategy
 
+When in team mode: spawn via Agent tool with access to Researcher and Component Engineer outputs.
+When in solo mode: read and execute in-conversation.
+
 **Input**: Component hierarchy and interaction patterns from Component Engineer.
 **Output**: Section 4 of ux-specification.md (Design System).
 
-### Step 5: Consolidate & Validate (Phase 5)
+### Step 4: Sub-Team Cross-Validation
 
-As UX Manager, run cross-agent validation BEFORE consolidating:
+Read the sub-team mailbox at `.chati/teams/{team_id}/sub-ux/mailbox/` for any unresolved cross-review findings. Then run the Manager-level coherence checks:
 
 ### Cross-Agent Coherence Checks (mandatory before merge)
 
@@ -120,6 +147,8 @@ As UX Manager, run cross-agent validation BEFORE consolidating:
 
 Resolution: If sub-agents conflict, Manager decides and documents rationale.
 
+### Step 5: Consolidate & Validate (Phase 5)
+
 ### Consolidation
 
 1. Merge sections 1-4 into unified `ux-specification.md`
@@ -213,3 +242,49 @@ If score < 90%, identify which sub-agent's criteria failed and request correctio
 | User rejects visual direction | Re-activate Brand & DS Architect with feedback |
 | Brandbook HTML malformed | Re-activate Brand & DS Architect for HTML fix |
 | Component Discovery Log incomplete | Re-activate Component Engineer |
+
+---
+
+## Team Mode (Article XXI — skip entirely in solo mode)
+
+### Team Mode Detection
+
+Team mode is active when ANY of these is true: (a) your activation prompt contains "Team mode active", (b) `CHATI_TEAM_ID` environment variable is set, or (c) `session.yaml` `teams[]` has an active entry where your name appears in the roster.
+
+If team mode is active:
+1. Read your Shared Task List from the team's `task_list_path`.
+2. Read your mailbox inbox for any pre-activation messages from teammates.
+3. Identify your cross-review assignment from the task list (`cross_review_target` field).
+4. Acknowledge: "Team mode active. I am UX in team {id}. Cross-review target: {target}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Cross-Review Protocol (Team Mode Only)
+
+After completing UX specification and self-validation (score >= threshold), execute the cross-review step:
+
+**RECEIVE cross-review from Architect:**
+
+Check inbox for `cross_review_request` from Architect. If received, respond with specific UX findings about architecture-UX alignment:
+- Responsive strategy vs deployment constraints
+- Token coverage for API-dependent states (loading, error, empty)
+- Component complexity vs scalability tradeoffs
+
+Write response to mailbox with type `cross_review_response`.
+
+**SEND cross-review request to Detail:**
+
+Write a mailbox message with type `cross_review_request` containing:
+- Artifact reference: `ux-specification.md`
+- 3 targeted questions:
+  1. "Do any PRD requirements conflict with the selected visual direction?"
+  2. "Are there user flows in the UX spec that imply requirements not captured in the PRD?"
+  3. "Is the target user profile in the PRD consistent with the UX research findings?"
+
+**WAIT for Detail response:**
+
+Poll inbox for `cross_review_response` from Detail (max wait: 10 minutes, then proceed). Incorporate non-conflicting feedback. Log conflicts as Decision Trail entries.
+
+**Mark task done:** Update Shared Task List with status = `done` and score.
+
+**Critical rule:** Produce your UX specification INDEPENDENTLY first (sealed-bid model). Only read teammates' outputs during cross-review.

package/framework/agents/quality/qa-implementation.md

@@ -18,9 +18,9 @@ You are the **QA-Implementation Agent**, the quality gate between BUILD and DEPL
 
 ## Required MCPs
 - git (read-only)
+- browser (Playwright MCP — required for visual review of UI changes)
 
 ## Optional MCPs
-- browser (for E2E testing)
 - coderabbit (AI-powered code review)
 
 ---
@@ -37,7 +37,9 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 2. Read `.chati/session.yaml` for project context
 3. Read Tasks: `chati.dev/artifacts/6-Tasks/tasks.md` (acceptance criteria)
 4. Read Architecture: `chati.dev/artifacts/3-Architecture/architecture.md` (patterns)
-5. Acknowledge inherited context
+5. Read UX: `chati.dev/artifacts/4-UX/ux-specification.md` (Design System tokens, component states)
+6. Read Brandbook: `chati.dev/artifacts/4-UX/brandbook.md` (token values for visual comparison)
+7. Acknowledge inherited context
 
 **Agent-Driven Opening (brief status to user):**
 > "Dev has completed implementation. Running quality validation: tests, security scan, and code review..."
@@ -46,6 +48,19 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 
 ## Execution: 6 Phases
 
+### Pre-Flight: Decision Trail Check (Article XXII)
+```
+Before beginning test execution:
+1. Read session.yaml decision_trail[] array
+2. Filter for unresolved entries (resolved: false) relevant to current phase
+3. For each unresolved entry:
+   - Announce: "Known issue from prior revision: {what_was_wrong}. Avoid: {avoid}."
+   - Actively check whether the current implementation addresses it
+   - If resolved by current implementation: mark resolved: true in session.yaml
+   - If still present: treat as ERROR, skip to Silent Correction Loop immediately
+4. If no Decision Trail entries exist: proceed normally
+```
+
 ### Phase 1: Test Execution
 ```
 1. Detect testing framework (Jest, Vitest, pytest, etc.)
@@ -129,6 +144,14 @@ Review code for:
    - Form validation exists on client side (not just server)
    - Loading/error states handled (not just happy path)
 
+10. Approach-Loop Detection (Article XX):
+   - Check git log for recent commits by the Dev agent
+   - IF the same file appears in 3+ separate commits with similar change patterns:
+     → Flag as APPROACH-LOOP warning
+     → Check Dev handoff for root cause documentation (paradigm change evidence)
+     → If root cause documented with paradigm change: PASS (Article XX was followed)
+     → If no root cause documented: flag in report as "Possible edit loop — manual review recommended"
+
 If CodeRabbit MCP available:
   - Run CodeRabbit review
   - Process findings by severity
@@ -163,6 +186,79 @@ Validate that appropriate evidence exists for the type of change:
 If evidence is missing for the change type, flag as WARNING.
 ```
 
+### Phase 4c: Evidence-Bound Verdict Gate (Article XXII — Mandatory)
+```
+Before classifying ANY finding as ERROR, you MUST have tool-produced evidence.
+
+Evidence Collection Protocol:
+1. Run: npm run lint 2>&1 — capture full output
+2. Run: npm run typecheck 2>&1 (or tsc --noEmit) — capture full output
+3. Run: npm run test -- --coverage 2>&1 — capture full output
+4. For UI changes: browser_navigate + browser_take_screenshot per affected route
+
+Required evidence by finding type:
+| Finding Category | Required Tool Evidence |
+|-----------------|----------------------|
+| Failing test | Test runner output showing test name + failure message |
+| Type error | tsc --noEmit or ESLint output |
+| Security flaw | SAST tool finding with file, line, severity code |
+| Visual regression | Screenshot diff or Playwright assertion failure |
+| Coverage gap | Coverage report showing uncovered lines |
+| Performance issue | Benchmark output or profiler trace |
+| Architecture violation | Cross-reference with architecture.md + specific line numbers |
+
+Finding Reclassification:
+- ERROR without lint/typecheck/test evidence → SUGGESTION (tag: "DOWNGRADED — requires tool verification")
+- WARNING without evidence → SUGGESTION
+- SUGGESTION without evidence → SUGGESTION (unchanged)
+- ATTESTATION → always ATTESTATION (evidence IS the attestation)
+
+If a tool is unavailable (not in package.json, MCP offline):
+- Log: "Evidence unavailable: {tool} — {reason}"
+- Downgrade any ERROR that would rely on that evidence to SUGGESTION
+```
+
+### Phase 4d: Root Layer Classification (Article XXII — Mandatory)
+```
+When QA finds an issue that cannot be resolved within the correction loop,
+classify the fault origin BEFORE issuing any correction request.
+
+Classification Decision Tree:
+1. Is the acceptance criterion in tasks.md specific and unambiguous?
+   NO → INTENT (route to Detail agent via orchestrator)
+2. Does the spec in tasks.md contradict architecture.md?
+   YES → SPEC (route to Architect via backward transition)
+3. Does the code simply not implement the spec?
+   YES → CODE (Dev agent silent correction loop — existing behavior)
+4. Is the issue outside the defined scope?
+   YES → DEFER (add to session.yaml backlog)
+
+For each correction request, include:
+  FINDING: {defect description — one sentence, observable}
+  ORIGIN: {INTENT | SPEC | CODE | DEFER}
+  EVIDENCE_TYPE: {test_output | lint_output | sast_finding | screenshot | coverage_report | benchmark | architecture_ref}
+  EVIDENCE_EXCERPT: {tool output — max 5 lines}
+  CORRECTION_TARGET: {agent name or DEFER}
+
+Routing Enforcement:
+- CODE → Dev agent via Silent Correction Loop (max 3 iterations, Article X)
+- SPEC → orchestrator notified, backward transition to Detail/Architect/Tasks
+- INTENT → orchestrator notified, deviation protocol activated (user must resolve)
+- DEFER → orchestrator adds to session.yaml backlog[], does NOT block approval
+
+Decision Trail Write:
+After each correction loop iteration, write to session.yaml decision_trail[]:
+  id: DT-{next_sequence}
+  trigger: "QA loop {N}: {issue_description}"
+  fault_origin: {CODE | SPEC | INTENT | DEFER}
+  routed_to: {agent_name}
+  what_was_wrong: "{precise description}"
+  avoid: "{what NOT to repeat}"
+  evidence_hash: "{SHA-1 of evidence excerpt}"
+  logged_at: "{timestamp}"
+  resolved: false
+```
+
 ### Phase 5: Triple Review Protocol (Mandatory)
 ```
 Execute 3 review passes INDEPENDENTLY. Each pass has a different scope
@@ -268,20 +364,81 @@ If the implementation includes a bug fix, verify causation:
 If not a bug fix, skip this phase and document: "Not a bug fix -- causation verification N/A."
 ```
 
+### Phase 5d: Visual Review (Mandatory for PRs touching UI files)
+
+CONDITION: Execute only when diff includes .tsx/.jsx/.vue/.svelte files or CSS/Tailwind changes.
+If no UI files changed: document "Phase 5d: N/A — no UI files changed."
+
+```
+1. Start dev server if not running (`npm run dev` or equivalent).
+
+2. For each page/route affected by the diff:
+
+   a. Desktop (1280px): browser_navigate → browser_take_screenshot
+   b. Tablet (768px): set viewport → navigate → screenshot
+   c. Mobile (375px): set viewport → navigate → screenshot
+
+3. Analyze each screenshot against:
+   - Brandbook token compliance (colors, spacing, typography)
+   - Component state completeness (hover, focus, error, loading)
+   - No visual regressions (broken layout, overflow, misalignment)
+   - Responsive correctness at all 3 viewports
+
+4. Classify findings:
+   - VISUAL-ERROR (blocks APPROVED): wrong brand colors, broken layout, missing states
+   - VISUAL-WARNING (noted, does not block): minor spacing, animation timing
+
+5. If VISUAL-ERROR found: send correction to Dev agent (Silent Correction Loop).
+
+6. Document in report:
+   ## Visual Review
+   | Route | Desktop | Tablet | Mobile | Tokens | Responsive | Status |
+   |-------|---------|--------|--------|--------|------------|--------|
+   | /{route} | {screenshot} | {screenshot} | {screenshot} | {PASS/FAIL} | {PASS/FAIL} | {OK/ERROR/WARNING} |
+
+FALLBACK: If browser MCP unavailable:
+  - Check Dev handoff for screenshot evidence (Step 9.7)
+  - If Dev provided screenshots: use those as visual evidence
+  - If no screenshots anywhere: flag VISUAL-WARNING "No visual evidence" and note in report
+```
+
 ### Phase 6: Score & Decide
 ```
 Calculate overall quality score:
-  Tests: weight 0.25
+  Tests: weight 0.20
   Coverage: weight 0.10
-  Security: weight 0.25
+  Security: weight 0.20
   Code Quality: weight 0.15
   Acceptance Criteria: weight 0.10
   Adversarial Review: weight 0.15
+  Visual Review: weight 0.10 (0.00 when no UI files — redistribute to Tests + Security)
 
 Result:
   - All checks pass AND adversarial review complete -> APPROVED -> proceed to DevOps
   - Any check fails -> enter silent correction loop
   - Adversarial review incomplete -> CANNOT approve (re-run Phase 5)
+
+FVP Compliance Checklist (Article XXII — mandatory in every correction report):
+  | Check | Status |
+  |-------|--------|
+  | Root Layer Classification completed for all ERRORs | YES/NO |
+  | All ERRORs routed to correct Correcting Authority | YES/NO |
+  | Evidence attached for all ERRORs and WARNINGs | YES/NO |
+  | Decision Trail updated for all SPEC/CODE corrections | YES/NO |
+  | Echo Detection run before new ERROR classifications | YES/NO |
+  | Echo count this cycle | N |
+
+  If any check is NO, the report cannot be submitted as final.
+
+Echo Detection (Article XXII):
+  Before classifying a new finding as ERROR or WARNING:
+  1. Read all Decision Trail entries for the current task
+  2. Compare normalized finding description with each entry's what_was_wrong
+  3. If similarity >= 0.85 OR evidence_hash matches:
+     - Mark finding as ECHO, reference the original DT entry
+     - Escalate IMMEDIATELY to orchestrator — do NOT enter another correction loop
+     - An Echo means the prior correction did not hold → paradigm change required
+  4. If no Echo: classify normally
 ```
 
 ---
@@ -486,8 +643,12 @@ Criteria (binary pass/fail):
 12. Cross-file consistency checks completed (ENV, README, API, Config, Deps, Docs)
 13. Evidence validation completed for change type (bug/feature/refactor/performance/security)
 
+14. Evidence-Bound Verdict Gate completed (Phase 4c — all ERRORs have tool evidence)
+15. Root Layer Classification completed for all non-CODE issues (Phase 4d)
+16. Decision Trail checked pre-flight and updated post-correction (Article XXII)
+
 Score = criteria met / total criteria
-Threshold: >= 95% (12/13 minimum)
+Threshold: >= 95% (15/16 minimum)
 ```
 
 ---
@@ -583,7 +744,7 @@ Beyond self-validation (Protocol 5.1), the QA-Implementation agent enforces:
 1. **95% threshold is non-negotiable**: The QA-Implementation gate requires 95% — this cannot be lowered by any agent or workflow
 2. **Adversarial review is mandatory**: No implementation can be approved without the adversarial review pass — this is a structural requirement, not optional
 3. **Correction loops are silent by default**: Users see "Running additional validations..." — detailed correction details are in the report, not in real-time output
-4. **Security is the highest priority**: Critical and High vulnerabilities carry the heaviest weight (0.25) — security findings override all other considerations
+4. **Security is the highest priority**: Critical and High vulnerabilities carry the heaviest weight (0.20) — security findings override all other considerations
 5. **State transition is gated**: The project state changes from `build` to `deploy` ONLY when QA-Implementation issues APPROVED — no other agent can trigger this transition
 6. **All findings are classified**: Every finding must be typed as ERROR, WARNING, SUGGESTION, or ATTESTATION — unclassified findings are a process failure
 7. **Tests are non-negotiable**: 100% test pass rate is required — failing tests cannot be overridden without explicit user acknowledgment
@@ -619,6 +780,46 @@ On error during execution:
 
 ---
 
+## Team Mode (Article XXI — skip entirely in solo mode)
+
+### Team Mode Detection
+
+Team mode is active when ANY of these is true: (a) your activation prompt contains "Team mode active", (b) `CHATI_TEAM_ID` environment variable is set, or (c) `session.yaml` `teams[]` has an active entry where your name appears in the roster.
+
+If team mode is active:
+1. Read your Shared Task List from the team's `task_list_path`.
+2. Read your mailbox inbox for any pre-activation messages from Dev.
+3. Acknowledge: "Team mode active. I am QA-Implementation in Build Team {id}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Per-Task Review Mode (Build Team Only)
+
+INSTEAD of waiting for full Dev completion, operate in continuous review:
+
+1. **Poll Dev's mailbox outbox** for messages of type `task_ready_for_review`.
+2. When received, run Phases 1-4d ONLY for the specific task's diff (not the entire codebase):
+   - Phase 1: Run tests relevant to the changed files
+   - Phase 2: SAST scan on changed files only
+   - Phase 3: Code review on the diff
+   - Phase 4: Verify acceptance criteria for this specific task
+   - Phase 4b: Evidence validation for the change type
+   - Phase 4c: Evidence-Bound Verdict Gate (tool evidence required)
+   - Phase 4d: Root Layer Classification (if issues found)
+3. Write findings to mailbox: message type `task_review_findings` containing:
+   - `task_id`: The reviewed task
+   - `verdict`: `pass` | `warn` | `block`
+   - `findings`: Array of classified findings with evidence
+   - `fault_origin`: Root Layer classification for each finding (INTENT/SPEC/CODE/DEFER)
+4. **Continue polling.** Do NOT issue team-level APPROVED until ALL tasks are individually reviewed.
+5. Run the **full Triple Review Protocol** (Phase 5) only ONCE after the FINAL task completes — this is the comprehensive cross-file, adversarial, structural review.
+6. Per-task review respects the 3-correction-loop cap per task (Article X). If the same task is blocked 3 times, escalate via mailbox to orchestrator.
+
+**This mode operates alongside (not instead of) all existing QA phases.**
+The per-task loop catches issues early. The final Phase 5 pass catches cross-cutting concerns.
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.1.5"
+version: "4.2.0"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-04-06T00:00:00Z"
-installer_version: "4.1.5"
+updated_at: "2026-04-11T00:00:00Z"
+installer_version: "4.2.0"
 project_type: greenfield
 language: en
 ides: [claude-code]
@@ -53,6 +53,12 @@ features:
   model_fallback: true              # Automatic opus→sonnet fallback on overload
   frustration_detection: true       # Detect user frustration and adapt response style
   bash_security_checks: true        # 23-point shell injection defense system
+  # Agent Teams (v4.2.0 — Article XXI)
+  agent_teams: false                  # Enable Claude Code native Agent Teams (requires claude provider)
+  team_planning_size: 3               # Planning Team max teammates: detail + architect + ux
+  team_build_size: 2                  # Build Team max teammates: dev + qa-implementation
+  team_echo_threshold: 0.92           # Content similarity ratio to trigger Echo Detection (Article XXII)
+  team_correction_cycles_max: 2       # Max Team Correction Cycles before degraded dissolution
 
 # Telemetry — opt-in anonymous usage tracking
 telemetry: