chati-dev 4.1.6 → 4.2.0

package/README.md

@@ -277,7 +277,7 @@ Three systems operate transparently behind the pipeline:
 
 ### Constitution
 
-The system is governed by a **19-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
+The system is governed by a **22-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
 
 - **Agent Governance** — Every agent has a defined mission, scope, and success criteria
 - **Quality Standards** — Minimum 95% score on quality gates. 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)
@@ -287,6 +287,8 @@ The system is governed by a **19-article Constitution** that enforces agent beha
 - **Model Governance** — Each agent runs on its designated model, enforced by the CLI adapter
 - **Execution Profiles** — Explore, guided, and autonomous modes with safety net and circuit breaker
 - **Multi-CLI** — Provider-agnostic architecture with adapter pattern and automatic model mapping
+- **Agent Teams** — Real-time peer communication between agents with cross-review, per-task QA, and sealed-bid quality assurance
+- **Fault Vector Protocol** — Root Layer Routing, Evidence-Bound Verdicts, Decision Trail, and Echo Detection for adversarial quality
 
 ---
 
@@ -396,7 +398,7 @@ your-project/
 │   │   ├── build/                # Dev
 │   │   └── deploy/               # DevOps
 │   ├── workflows/                # 7 workflow blueprints
-│   ├── templates/                # 10 artifact templates
+│   ├── templates/                # 12 artifact templates
 │   ├── schemas/                  # 5 JSON schemas
 │   ├── intelligence/             # PRISM, RECALL, COMPASS specs
 │   ├── domains/                  # Per-agent and per-workflow configs
@@ -408,7 +410,7 @@ your-project/
 │   ├── data/                     # Entity registry
 │   ├── i18n/                     # EN, PT, ES, FR translations
 │   ├── migrations/               # Version migration scripts
-│   ├── constitution.md           # 19 Articles + Preamble
+│   ├── constitution.md           # 22 Articles + Preamble
 │   └── config.yaml               # System configuration
 └── packages/
     └── chati-dev/                # CLI + runtime engine
@@ -459,5 +461,5 @@ For security concerns, see our [Security Policy](.github/SECURITY.md).
 
 <p align="center">
   <sub>Built with structure, validated by agents, governed by constitution.</sub><br>
-  <sub>Chati.dev v4.1 "Phoenix" &copy; 2026</sub>
+  <sub>Chati.dev v4.2 "Phoenix" &copy; 2026</sub>
 </p>

package/framework/agents/build/dev.md

@@ -112,6 +112,16 @@ For each task:
      Skip entirely for backend-only, config, or test-only tasks.
 
   3. Implement code
+     PARADIGM RULE (Article XX — 3-Strike Rule):
+       IF you have edited the same file 3 times in this task without resolving the problem:
+         → STOP. Do not edit that file again.
+         → Read the COMPLETE file line by line.
+         → Write down the root cause in ONE sentence.
+         → Change approach completely (CSS→JS, client→server, complex→simple).
+         → Determine: "What information do I actually need, and what is the most direct way to get it?"
+         → Only then implement the fix with the NEW approach.
+       Violating this rule caps your task score at 0%.
+       This rule is separate from ANTI-LOOP RULE (which governs critique steps 5.5/6.5).
      -> Output: "Implementation done. Running self-critique (5.5)..."
   4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
      -> Output: "Self-critique complete. Running tests..."
@@ -198,7 +208,7 @@ WHILE tasks_pending:
          → ADOPT/ADAPT if match found; CUSTOM only as last resort
          → Log: "Component source: {status} [{source}]"
          → If unavailable: log "Research skipped" and proceed
-    3. Implement code
+    3. Implement code (PARADIGM RULE applies — see Interactive Mode Step 3)
        -> Output: "T{X} implementation done. Self-critique (5.5)..."
     4. Run self-critique (Step 5.5) — 1 fix pass, then proceed
        -> Output: "T{X} critique done. Running tests..."
@@ -683,6 +693,49 @@ ANTI-CYCLE RULE: Levels are a one-way escalation path. NEVER go back to a previo
 
 ---
 
+## 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.
+3. Acknowledge: "Team mode active. I am Dev in Build Team {id}."
+
+If team mode is NOT active: ignore this entire section and operate as defined above.
+
+### Per-Task QA Mode (Build Team Only)
+
+When in Build Team, QA-Implementation does NOT run as a batch after all tasks. Instead, QA reviews EACH task as you complete it:
+
+**After EACH task reaches score >= 95%:**
+
+1. Write to mailbox: message type `task_ready_for_review` containing:
+   - `task_id`: The task identifier (e.g., T1.1)
+   - `commit_hash`: The local commit hash for this task
+   - `score`: Your self-validation score
+   - `artifacts`: List of files changed
+   - `self_critique_findings`: Summary of Step 5.5 + 6.5 findings
+
+2. **Continue to NEXT task immediately** — do NOT wait for QA response.
+
+3. **Poll inbox at task boundaries** for QA findings on previous tasks:
+   - Check for messages of type `task_review_findings` from QA
+   - If QA returns verdict `block`: pause current task, fix the blocking issue on the previous task, then resume current task
+   - If QA returns verdict `warn`: log to Decision Trail (Article XXII), continue
+   - If QA returns verdict `pass`: no action needed, continue
+
+4. **Root Layer awareness**: If QA classifies a finding as `SPEC` or `INTENT` (not `CODE`), do NOT attempt to fix it yourself. The orchestrator will handle backward routing per Article XXII. Only fix `CODE` findings.
+
+5. **Max correction loops per task**: 3 (Article X). If QA blocks the same task 3 times, escalate to orchestrator.
+
+**Dev Preview Step in Team Mode:**
+The dev preview step still runs after ALL tasks complete. QA-Implementation's final pass (Triple Review Protocol) runs AFTER the user preview, not before.
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/plan/architect.md

@@ -51,37 +51,54 @@ Coordinate the technical design by activating 2 specialist sub-agents in sequenc
 
 ---
 
-## Execution: 4-Step Coordination
+## Execution: 3-Step Coordination
 
-### Step 1: Activate System Architect
+### Step 1: Spawn Architecture Sub-Team
 
-Read `chati.dev/agents/plan/architect-system.md` and execute Steps 1-3:
-- Tech stack selection with 3 options per layer (user selects)
-- System architecture design (components, patterns, data flow)
-- API design with error contract, pagination, rate limiting
-- Authentication and authorization model
-- Deployment architecture
-- Security review (OWASP Top 10)
-- Scalability approach
+When in team mode (Article XXI), spawn System Architect and Data Engineer as a **Mini-Team** using the Agent tool. Both run in parallel and communicate via a sub-team mailbox.
 
-**Gate**: Tech stack must be selected before Data Engineer can start (database choice needed).
+Create sub-team mailbox directory: `.chati/teams/{team_id}/sub-architect/mailbox/`
 
-### Step 2: Activate Data Engineer
+Spawn 2 agents via Agent tool IN PARALLEL (single message, both calls):
 
-Read `chati.dev/agents/plan/architect-data-engineer.md` and execute:
-- Schema design from PRD entities + API endpoints
-- Schema annotations (DESCRIPTION, VALUES, JOIN COLUMN, UNITS)
-- RLS policies per table per operation (USING/WITH CHECK)
-- Migration strategy with rollback (DOWN section mandatory)
-- Index design for anticipated query patterns
-- Seed data (domain-realistic, idempotent)
-- Backup and recovery plan
+```
+Agent tool call 1:
+  description: "System Architect — infrastructure, APIs, deployment"
+  prompt: [Read and follow chati.dev/agents/plan/architect-system.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-architect/mailbox/
+    Execute Steps 1-3: tech stack, system architecture, API design, auth, deployment, security, scalability.
+    GATE: Present 3 tech stack options to the user. User must select before proceeding.
+    After completing: write your artifact to chati.dev/artifacts/3-Architecture/system-architecture.md
+    Then write a cross-review to the mailbox for Data Engineer:
+      type: cross_review_request
+      to: data-engineer
+      questions:
+        1. "Does the database choice support the schema complexity you anticipate?"
+        2. "Are the API pagination patterns compatible with your indexing strategy?"
+        3. "Does the caching approach conflict with data mutation consistency?"
+    Read Data Engineer's cross-review response from mailbox before finalizing.]
+
+Agent tool call 2:
+  description: "Data Engineer — schema, RLS, migrations, indexes"
+  prompt: [Read and follow chati.dev/agents/plan/architect-data-engineer.md.
+    Sub-team mode active. Mailbox: .chati/teams/{team_id}/sub-architect/mailbox/
+    Execute: schema design, annotations, RLS policies, migrations, indexes, seed data, backup.
+    After completing: write your artifact to chati.dev/artifacts/3-Architecture/data-architecture.md
+    Then write a cross-review to the mailbox for System Architect:
+      type: cross_review_request
+      to: system-architect
+      questions:
+        1. "Does the auth model cover all RLS role requirements?"
+        2. "Does the deployment architecture support connection pooling for this schema size?"
+        3. "Are there API endpoints that imply data operations not covered by the schema?"
+    Read System Architect's cross-review response from mailbox before finalizing.]
+```
 
-**Input**: Reads System Architect's tech stack (database choice) and API design (query patterns).
+When NOT in team mode (solo/fallback): execute the existing sequential pattern — read each .md file and execute in-conversation, Step 1 then Step 2.
 
-### Step 3: Cross-Validate
+### Step 2: Cross-Validate (Manager)
 
-Before consolidating, verify coherence between System and Data:
+After both sub-agents return, the Manager reads both artifacts and verifies coherence:
 
 1. **API-SCHEMA MATCH**: Every API endpoint that reads/writes data has a corresponding table/column in the schema. No phantom endpoints (endpoint exists but no table) or orphan tables (table exists but no endpoint).
 
@@ -91,9 +108,9 @@ Before consolidating, verify coherence between System and Data:
 
 4. **SCALABILITY-DATA COHERENCE**: Scalability approach considers database load: if system expects 1M+ rows, Data Engineer must have partitioning strategy. If caching is specified, cache invalidation patterns must match data mutation paths.
 
-If mismatches found: route correction to the responsible sub-agent.
+Also read the sub-team mailbox for any unresolved cross-review findings between System Architect and Data Engineer. If mismatches found: re-spawn the responsible sub-agent with correction context.
 
-### Step 4: Consolidate & Handoff
+### Step 3: Consolidate & Handoff
 
 Each sub-agent writes its own artifact first (human-reviewable), then the Manager consolidates.
 
@@ -188,3 +205,49 @@ Score = criteria met / 10. Threshold: >= 90% (9/10 minimum).
 | Cross-validation mismatch | Route correction to responsible sub-agent |
 | User rejects tech stack | Re-activate System Architect with feedback |
 | Schema doesn't match API | Re-activate Data Engineer with API endpoint list |
+
+---
+
+## 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 Architect 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 architecture and self-validation (score >= threshold), execute the cross-review step:
+
+**RECEIVE cross-review from Detail:**
+
+Check inbox for `cross_review_request` from Detail. If received, respond to each question with specific architectural findings:
+- Entity count alignment (PRD entities vs DB tables)
+- Contradictions between requirements and architecture constraints
+- Scope decisions that conflict with the technical design
+
+Write response to mailbox with type `cross_review_response`, including severity per finding: `info`, `warn`, or `block`.
+
+**SEND cross-review request to UX:**
+
+Write a mailbox message with type `cross_review_request` containing:
+- Artifact reference: `architecture.md`
+- 3 targeted questions:
+  1. "Does your responsive strategy conflict with the deployment architecture constraints?"
+  2. "Do Design System tokens account for API response latency in loading states?"
+  3. "Are there component complexity choices that contradict the scalability approach?"
+
+**WAIT for UX response:**
+
+Poll inbox for `cross_review_response` from UX (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 architecture INDEPENDENTLY first (sealed-bid model). Only read teammates' outputs during cross-review.

package/framework/agents/plan/detail.md

@@ -406,6 +406,50 @@ Beyond self-validation (Protocol 5.1), the Detail agent enforces:
 
 ---
 
+## 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 Detail 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 the PRD and self-validation (score >= threshold), execute the cross-review step before marking your task done:
+
+**SEND cross-review request to Architect:**
+
+Write a mailbox message with type `cross_review_request` containing:
+- Artifact reference: `prd.md`
+- 3 targeted questions:
+  1. "Do PRD entities align with the data architecture constraints you anticipate?"
+  2. "Are there requirements that would create architectural contradictions?"
+  3. "Are scope decisions in Section 4 likely to conflict with your design?"
+
+**RECEIVE cross-review from UX** (if available):
+
+Check inbox for `cross_review_request` from UX. If received, respond with specific findings about PRD-UX alignment. Write response to mailbox with type `cross_review_response`.
+
+**WAIT for Architect response:**
+
+Poll inbox for `cross_review_response` from Architect (max wait: 10 minutes, then proceed without response). If response received:
+- Incorporate non-conflicting feedback into PRD
+- Log any unresolvable conflicts as Decision Trail entries (Article XXII)
+- Do NOT reduce your self-validation score based on cross-review — score reflects YOUR criteria only
+
+**Mark task done:** Update Shared Task List with status = `done` and score.
+
+**Critical rule:** Produce your PRD INDEPENDENTLY first (sealed-bid model). Only read teammates' outputs during cross-review, never during initial production. This prevents groupthink.
+
+---
+
 ## Input
 
 $ARGUMENTS

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.