chati-dev 4.1.5 → 4.2.0

package/framework/orchestrator/chati.md

@@ -77,6 +77,7 @@ Parse the JSON output. The `action` field tells you what to do:
 | `activate_interactive` | Action: Interactive Agent |
 | `spawn_autonomous` | Action: Autonomous Agent |
 | `spawn_parallel` | Action: Parallel Spawn |
+| `spawn_team` | Action: Spawn Team (Article XXI) |
 | `resume` | Action: Resume |
 | `user_preview` | Action: User Preview |
 | `complete` | Action: Complete |
@@ -237,6 +238,8 @@ If terminal spawning fails (CLI not found, system error), fall back **silently**
 
 Planning phase agents (detail, architect, ux) run simultaneously.
 
+**NOTE (Article XXI):** When `features.agent_teams: true` in config.yaml, the orchestrator MUST attempt `spawn_team` FIRST for GROUP 1 agents (detail, architect, ux) and BUILD pair (dev, qa-implementation). Only fall back to `spawn_parallel` if team spawning is unavailable or fails. The CLI `orchestrate next` command handles this automatically — when teams are enabled, it returns `spawn_team` instead of `spawn_parallel`.
+
 1. Display: "Spawning parallel group: {agents}"
 2. Execute `parallel_spawn_command` via Bash tool
 3. Parse consolidated JSON output
@@ -256,6 +259,156 @@ Planning phase agents (detail, architect, ux) run simultaneously.
 
 ---
 
+## Action: Spawn Team (Article XXI)
+
+Agent Teams enable real-time peer communication between agents. The orchestrator acts as Team Lead, spawning teammates as native Claude Code sub-agents (Agent tool), and coordinating their work through a shared task list and filesystem-based mailbox.
+
+### Step 1: Register Team in Session
+
+Run via Bash to create team directories, task list, and session entry:
+```
+node packages/chati-dev/bin/chati.js orchestrate spawn-team --team-type {planning|build} --previous-agent {last_completed_agent}
+```
+Parse JSON. If `fallback_required: true` → fall back silently to `spawn_parallel`. Do NOT display error messages.
+
+Display: "Forming {team_type} team: {members}"
+
+### Step 2: Spawn Teammates via Agent Tool
+
+Use the Claude Code **Agent tool** to spawn each teammate as a sub-agent. This is the same mechanism used by `chati-update.md` for SCAN/COMPARE phases.
+
+**For Planning Team** (post-Brief): spawn 3 agents IN PARALLEL by making all Agent tool calls in a SINGLE message:
+
+```
+Agent tool call 1:
+  description: "Detail agent — expand PRD"
+  prompt: [Read and follow chati.dev/agents/plan/detail.md.
+    Team mode active: team_id={team_id}.
+    Read shared task list at {task_list_path} — your task is TT-PLN-001.
+    Mailbox directory: {mailbox_path}
+    Cross-review target: architect (send cross_review_request after completing PRD).
+    Previous agent handoff: chati.dev/artifacts/handoffs/brief-handoff.md
+    CRITICAL: Produce your PRD INDEPENDENTLY first (sealed-bid). Only read teammates' outputs during cross-review.
+    Write your handoff to chati.dev/artifacts/handoffs/detail-handoff.md when done.]
+
+Agent tool call 2:
+  description: "Architect agent — design architecture"
+  prompt: [Read and follow chati.dev/agents/plan/architect.md.
+    Team mode active: team_id={team_id}.
+    Read shared task list at {task_list_path} — your task is TT-PLN-002.
+    Mailbox directory: {mailbox_path}
+    Cross-review target: ux (send cross_review_request after completing architecture).
+    Previous agent handoff: chati.dev/artifacts/handoffs/brief-handoff.md
+    CRITICAL: Produce your architecture INDEPENDENTLY first (sealed-bid).
+    Write your handoff to chati.dev/artifacts/handoffs/architect-handoff.md when done.]
+
+Agent tool call 3:
+  description: "UX agent — design UX specification"
+  prompt: [Read and follow chati.dev/agents/plan/ux.md.
+    Team mode active: team_id={team_id}.
+    Read shared task list at {task_list_path} — your task is TT-PLN-003.
+    Mailbox directory: {mailbox_path}
+    Cross-review target: detail (send cross_review_request after completing UX spec).
+    Previous agent handoff: chati.dev/artifacts/handoffs/brief-handoff.md
+    CRITICAL: Produce your UX specification INDEPENDENTLY first (sealed-bid).
+    Write your handoff to chati.dev/artifacts/handoffs/ux-handoff.md when done.]
+```
+
+**For Build Team** (BUILD phase): spawn 2 agents IN PARALLEL:
+
+```
+Agent tool call 1:
+  description: "Dev agent — implement tasks"
+  prompt: [Read and follow chati.dev/agents/build/dev.md.
+    Team mode active: team_id={team_id}.
+    Read shared task list at {task_list_path}.
+    Mailbox directory: {mailbox_path}
+    Per-task QA mode: after each task, write task_ready_for_review to mailbox.
+    Continue to next task immediately — do NOT wait for QA response.
+    Poll mailbox at task boundaries for QA findings.
+    Previous agent handoff: chati.dev/artifacts/handoffs/qa-planning-handoff.md
+    Write your handoff to chati.dev/artifacts/handoffs/dev-handoff.md when done.]
+
+Agent tool call 2:
+  description: "QA-Implementation agent — per-task review"
+  prompt: [Read and follow chati.dev/agents/quality/qa-implementation.md.
+    Team mode active: team_id={team_id}.
+    Read shared task list at {task_list_path}.
+    Mailbox directory: {mailbox_path}
+    Per-task review mode: poll mailbox for task_ready_for_review from Dev.
+    Run Evidence Gate (Phase 4c) and Root Layer Classification (Phase 4d) per task.
+    Write task_review_findings to mailbox for each reviewed task.
+    Run full Triple Review Protocol (Phase 5) only after the FINAL task.
+    Previous context: chati.dev/artifacts/handoffs/qa-planning-handoff.md (plan overview)
+    Write your handoff to chati.dev/artifacts/handoffs/qa-implementation-handoff.md when done.]
+```
+
+### Step 3: Collect Results
+
+When all Agent tool calls return:
+
+1. Read each agent's handoff from `chati.dev/artifacts/handoffs/`
+2. Read the shared task list for final scores:
+   ```
+   node packages/chati-dev/bin/chati.js orchestrate team-status --team-id {team_id}
+   ```
+3. If any agent failed: note which one and its error
+4. Dissolve the team:
+   ```
+   node packages/chati-dev/bin/chati.js orchestrate team-dissolve --team-id {team_id}
+   ```
+5. Parse dissolution JSON — check `quality_gate.passed`:
+   - If `true`: present Completion Options (Team variant)
+   - If `false`: display `quality_gate.failures` and offer correction options
+
+6. Present **Completion Options** (Team variant):
+   ```
+   {team_type} team completed. Team score: {team_score}%.
+   Members: {member1}: {score1}%, {member2}: {score2}%, ...
+   Quality Gate: {PASSED | FAILED: {failures}}
+
+   1. Approve and continue to {next_agent} (Recommended)
+   2. Review artifacts from a specific team member
+   3. Re-run a specific team member for improvements
+   ```
+
+### Echo Escalation
+
+When reviewing the team-dissolve JSON, if `echo_events` is non-empty and count >= 3 for any member:
+```
+Team member {agent} appears stuck in a repetition loop (Article XXII Echo Detection).
+
+1. Intervene directly — provide specific guidance (Recommended)
+2. Remove {agent} from team — complete its work sequentially
+3. Dissolve entire team — fall back to sequential pipeline
+```
+
+### Team Transition Protocol
+
+After Planning Team (detail + architect + ux) completes and user approves:
+1. Dissolve Planning Team: `team-dissolve --team-id {planning-team-id}`
+2. Continue pipeline normally through Phases, Tasks, QA-Planning (these are NOT parallelizable and run sequentially as interactive or autonomous agents)
+3. When BUILD phase activates: attempt to form Build Team (dev + qa-implementation) following the same Steps 1-3 above
+4. Build Team uses per-task QA mode: QA reviews each Dev task as it completes, not as a batch
+
+**Team cleanup order:** Dissolve current team BEFORE creating next team. Never two teams active simultaneously.
+
+### Team Fallback
+
+If the Agent tool is unavailable or any sub-agent spawn fails:
+```
+1. Fall back silently to spawn_parallel (GROUP 1) or spawn_autonomous (BUILD)
+   Use the existing Action: Parallel Spawn or Action: Autonomous Agent flow
+2. Do NOT display any error or fallback message to the user
+3. Run: node packages/chati-dev/bin/chati.js orchestrate team-dissolve --team-id {team_id}
+   to mark the team as degraded in session.yaml
+4. All quality gates and thresholds remain unchanged
+5. Alternatively, if spawn_parallel also fails, use Sequential Fallback:
+   read each agent .md file and execute sequentially in-conversation
+```
+
+---
+
 ## Action: Resume
 
 The user is returning to an active session.
@@ -315,6 +468,10 @@ DEPLOY:
 Current Agent: {current_agent}
 Backlog: {count} items ({high_priority} high priority)
 Context: {bracket} ({remaining}%)
+
+TEAMS (if active):
+  {team_id}: {status} — members: {roster} — score: {team_score}%
+  Decision Trail: {decision_trail_count} entries ({unresolved} unresolved)
 ```
 
 ---
@@ -454,8 +611,9 @@ The orchestrator enforces `chati.dev/constitution.md`:
 
 | Level | Action | Articles |
 |-------|--------|----------|
-| **BLOCK** | Halt agent on violation | I, II, III, IV, VII, VIII, X, XI, XV |
-| **GUIDE** | Correct without halting | V, IX |
+| **BLOCK** | Halt agent on violation | I, II, III, IV, VII, VIII, X, XI, XII, XIII, XV, XVIII, XX, XXI, XXII |
+| **STRICT** | Must not bypass quality gates | XVII |
+| **GUIDE** | Correct without halting | V, IX, XIV, XVI, XIX |
 | **WARN** | Generate warning in QA | VI |
 
 ---
@@ -483,6 +641,14 @@ If QA finds spec or architecture issues:
 - issue_type "architecture" → route to architect agent
 - issue_type "code" → fix in build mode (no backward transition)
 
+### Root Layer Routing (Article XXII)
+
+When QA-Implementation classifies a fault via the Fault Vector Protocol:
+- `INTENT` → escalate to user via deviation protocol (requirement is flawed)
+- `SPEC` → backward transition to Architect, UX, or Tasks agent
+- `CODE` → Dev agent silent correction loop (existing behavior)
+- `DEFER` → add to session backlog, do not block approval
+
 ---
 
 ## Authority Boundaries
@@ -496,6 +662,10 @@ If QA finds spec or architecture issues:
 - Manage backlog items
 - Spawn parallel terminals
 - Decide execution mode (interactive vs autonomous)
+- Form and dissolve Agent Teams (Team Lead role, Article XXI)
+- Monitor shared task list and mailbox during team execution
+- Detect and respond to echo events within teams (Article XXII)
+- Route corrections to correct layer via Root Layer Routing (Article XXII)
 
 ### ALLOWED
 - Read any file in the project (for state detection)

package/framework/schemas/session.schema.json

@@ -194,6 +194,166 @@
           "reason": { "type": "string", "description": "User reason (override only) or QA finding (backward only)" }
         }
       }
+    },
+    "teams": {
+      "type": "array",
+      "default": [],
+      "description": "Agent Teams state tracking (Article XXI). Empty array when teams are not active.",
+      "items": {
+        "type": "object",
+        "required": ["team_id", "phase", "roster", "status"],
+        "properties": {
+          "team_id": {
+            "type": "string",
+            "pattern": "^TM-\\d{8}-[a-z]{3}$",
+            "description": "Unique team identifier (e.g., TM-20260411-pln)"
+          },
+          "phase": {
+            "enum": ["planning", "build"],
+            "description": "Pipeline phase this team serves"
+          },
+          "mission": {
+            "type": "string",
+            "description": "Team Mission Statement (one sentence, measurable outcome)"
+          },
+          "lead": {
+            "type": "string",
+            "default": "orchestrator",
+            "description": "Team Lead agent name"
+          },
+          "roster": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Agent names enrolled in this team (excluding lead)"
+          },
+          "status": {
+            "enum": ["forming", "active", "completing", "dissolved", "degraded"],
+            "description": "Team lifecycle state"
+          },
+          "task_list_path": {
+            "type": ["string", "null"],
+            "description": "Path to shared task list YAML"
+          },
+          "mailbox_path": {
+            "type": ["string", "null"],
+            "description": "Path to team mailbox directory"
+          },
+          "formed_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "dissolved_at": {
+            "type": ["string", "null"],
+            "format": "date-time"
+          },
+          "team_score": {
+            "type": ["number", "null"],
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Aggregate team score (average of member task scores)"
+          },
+          "member_scores": {
+            "type": "object",
+            "description": "Per-member score at dissolution",
+            "patternProperties": { ".*": { "type": "number" } }
+          },
+          "correction_cycles": {
+            "type": "integer",
+            "default": 0,
+            "description": "Number of Team Correction Cycles consumed (max 2)"
+          },
+          "echo_events": {
+            "type": "array",
+            "default": [],
+            "description": "Echo Detection events within this team (Article XXII)",
+            "items": {
+              "type": "object",
+              "properties": {
+                "detected_at": { "type": "string", "format": "date-time" },
+                "member": { "type": "string" },
+                "similarity": { "type": "number" },
+                "action_taken": { "type": "string" }
+              }
+            }
+          },
+          "fallback_used": {
+            "type": "boolean",
+            "default": false,
+            "description": "True if team spawning failed and sequential fallback was used"
+          }
+        }
+      }
+    },
+    "team_events": {
+      "type": "array",
+      "default": [],
+      "description": "Audit trail of team lifecycle events (Article XXI)",
+      "items": {
+        "type": "object",
+        "required": ["timestamp", "event", "team_id"],
+        "properties": {
+          "timestamp": { "type": "string", "format": "date-time" },
+          "event": { "enum": ["formed", "dissolved", "degraded", "echo_detected", "fallback_activated", "correction_cycle"] },
+          "team_id": { "type": "string" },
+          "trigger": { "type": "string", "description": "What caused this event" },
+          "state": { "enum": ["clean", "degraded"], "description": "Dissolution state (for dissolved/degraded events)" }
+        }
+      }
+    },
+    "decision_trail": {
+      "type": "array",
+      "default": [],
+      "description": "Known-bad state log to prevent cyclical re-introduction of defects (Article XXII). Append-only.",
+      "items": {
+        "type": "object",
+        "required": ["id", "trigger", "fault_origin", "what_was_wrong", "avoid", "logged_at"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^DT-\\d{4}$",
+            "description": "Decision Trail entry ID (e.g., DT-0001)"
+          },
+          "trigger": {
+            "type": "string",
+            "description": "What caused this revision (QA finding, user rejection, echo event)"
+          },
+          "fault_origin": {
+            "enum": ["INTENT", "SPEC", "CODE", "DEFER"],
+            "description": "Root Layer classification (Article XXII)"
+          },
+          "routed_to": {
+            "type": "string",
+            "description": "Agent the correction was routed to"
+          },
+          "what_was_wrong": {
+            "type": "string",
+            "description": "Precise description of the defect or known-bad state"
+          },
+          "avoid": {
+            "type": "string",
+            "description": "What NOT to do on the next iteration"
+          },
+          "evidence_hash": {
+            "type": ["string", "null"],
+            "description": "SHA-1 of the evidence excerpt for Echo Detection matching"
+          },
+          "correction_loop": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 3,
+            "description": "Which correction loop iteration produced this entry"
+          },
+          "logged_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "resolved": {
+            "type": "boolean",
+            "default": false,
+            "description": "True when the correcting agent has addressed this entry"
+          }
+        }
+      }
     }
   }
 }

package/framework/templates/team-build-tasks.yaml

@@ -0,0 +1,56 @@
+# Team Build Tasks Template (Article XXI)
+# Used by orchestrator when forming a Build Team (BUILD phase)
+# QA reviews EACH task as Dev completes it (per-task review, not batch)
+
+team_type: build
+phase: build
+mission: "Implement all tasks with per-task QA review and evidence-based quality gates"
+
+# NOTE: Tasks are dynamically populated from tasks.md at team formation time.
+# This template defines the PATTERN, not the actual tasks.
+# The orchestrator reads tasks.md and generates TT-BLD-{NNN} entries per task.
+
+task_pattern:
+  dev_task:
+    id_format: "TT-BLD-{NNN}-DEV"
+    assigned_to: dev
+    status: pending
+    score: null
+    blocker: null
+    threshold: 95
+    on_complete:
+      notify: qa-implementation
+      message_type: task_ready_for_review
+      include: [task_id, commit_hash, score, artifacts, self_critique_findings]
+
+  qa_review:
+    id_format: "TT-BLD-{NNN}-QA"
+    assigned_to: qa-implementation
+    status: pending
+    score: null
+    blocker: null
+    depends_on: ["TT-BLD-{NNN}-DEV"]
+    threshold: 95
+    protocol:
+      - "Run Evidence Gate (Phase 4c): lint, typecheck, test output required"
+      - "Classify fault origin (Phase 4d): INTENT | SPEC | CODE | DEFER"
+      - "Check Decision Trail for known-bad states before review"
+      - "Issue per-task verdict: pass | warn | block"
+    on_block:
+      action: notify_dev
+      message_type: task_review_findings
+      include: [task_id, verdict, findings, evidence, fault_origin]
+
+# Example of dynamically generated tasks (orchestrator produces these):
+#
+# tasks:
+#   - id: TT-BLD-001-DEV
+#     title: "T1.1: Initialize Next.js + App Router"
+#     assigned_to: dev
+#     source_task: T1.1
+#     ...
+#   - id: TT-BLD-001-QA
+#     title: "T1.1: Review + approve"
+#     assigned_to: qa-implementation
+#     depends_on: [TT-BLD-001-DEV]
+#     ...

package/framework/templates/team-planning-tasks.yaml

@@ -0,0 +1,73 @@
+# Team Planning Tasks Template (Article XXI)
+# Used by orchestrator when forming a Planning Team (post-Brief)
+# Cross-review assignments form a circular review: Detail -> Architect -> UX -> Detail
+
+team_type: planning
+phase: plan
+mission: "Co-design PRD, architecture, and UX specification with cross-validated alignment"
+
+tasks:
+  - id: TT-PLN-001
+    title: "Expand Brief into PRD with acceptance criteria"
+    assigned_to: detail
+    status: pending
+    score: null
+    blocker: null
+    depends_on: []
+    cross_review:
+      target: architect
+      questions:
+        - "Do PRD entities align with the data architecture constraints you anticipate?"
+        - "Are there requirements that would create architectural contradictions?"
+        - "Are scope decisions in Section 4 likely to conflict with your design?"
+    artifacts_produced:
+      - prd.md
+    threshold: 90
+
+  - id: TT-PLN-002
+    title: "Design system architecture and data architecture"
+    assigned_to: architect
+    status: pending
+    score: null
+    blocker: null
+    depends_on: []
+    cross_review:
+      target: ux
+      questions:
+        - "Does the responsive strategy conflict with deployment architecture constraints?"
+        - "Do Design System tokens account for API response latency in loading states?"
+        - "Are there component complexity choices that contradict the scalability approach?"
+    artifacts_produced:
+      - architecture.md
+    threshold: 90
+
+  - id: TT-PLN-003
+    title: "Design UX specification with brandbook, user flows, and components"
+    assigned_to: ux
+    status: pending
+    score: null
+    blocker: null
+    depends_on: []
+    cross_review:
+      target: detail
+      questions:
+        - "Do any PRD requirements conflict with the selected visual direction?"
+        - "Are there user flows implying requirements not captured in the PRD?"
+        - "Is the target user profile consistent with UX research findings?"
+    artifacts_produced:
+      - ux-specification.md
+      - brandbook.md
+      - brandbook.html
+    threshold: 90
+
+  - id: TT-PLN-004
+    title: "Cross-validate alignment: PRD entities = DB tables = UI components"
+    assigned_to: null
+    status: pending
+    score: null
+    blocker: null
+    depends_on: [TT-PLN-001, TT-PLN-002, TT-PLN-003]
+    cross_review: null
+    artifacts_produced: []
+    threshold: 95
+    notes: "Assigned by Team Lead after individual tasks complete. All 3 members participate."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.1.5",
+  "version": "4.2.0",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {

package/src/autonomy/safety-net.js

@@ -12,6 +12,7 @@ export const SAFETY_TRIGGERS = {
   CRITICAL_RISK: 'critical_risk', // Security/data risk detected
   TIMEOUT: 'timeout', // Agent exceeded time limit
   GOTCHA_SPIKE: 'gotcha_spike', // 5+ new gotchas in current session
+  EDIT_LOOP: 'edit_loop', // Same file edited 3+ times in current task (Article XX)
 };
 
 // Critical risk keywords
@@ -98,6 +99,9 @@ export function evaluateTrigger(trigger, state) {
     case SAFETY_TRIGGERS.GOTCHA_SPIKE:
       return evaluateGotchaSpike(state);
 
+    case SAFETY_TRIGGERS.EDIT_LOOP:
+      return evaluateEditLoop(state);
+
     default:
       return {
         triggered: false,
@@ -291,6 +295,34 @@ function evaluateGotchaSpike(state) {
   };
 }
 
+/**
+ * Article XX — Detect edit loops (same file edited 3+ times in current task).
+ * state.fileEdits should be an object: { 'path/to/file.tsx': 3, ... }
+ */
+function evaluateEditLoop(state) {
+  const threshold = 3;
+  const fileEdits = state.fileEdits || {};
+  const loopedFiles = Object.entries(fileEdits)
+    .filter(([, count]) => count >= threshold);
+
+  if (loopedFiles.length > 0) {
+    const details = loopedFiles
+      .map(([path, count]) => `${path} (${count} edits)`)
+      .join(', ');
+    return {
+      triggered: true,
+      severity: 'critical',
+      details: `Edit loop detected (Article XX): ${details}. Stop and diagnose root cause before continuing.`,
+    };
+  }
+
+  return {
+    triggered: false,
+    severity: 'warning',
+    details: 'No edit loops detected',
+  };
+}
+
 /**
  * Get critical risk keywords list.
  * @returns {string[]}

package/src/config/gemini-hooks-generator.js

@@ -533,14 +533,14 @@ main();
 
 /**
  * Generate the style guard hook for Gemini CLI.
- * BeforeTool event -- advisory: enforces em-dash and emoji standards.
+ * BeforeTool event -- blocking: rejects em-dashes and emojis in generated content.
  */
 function generateStyleGuard() {
   return `${HOOK_HEADER}
 /**
  * Style Guard -- BeforeTool
- * Advisory: enforces Constitution Article V writing standards
- * (no em-dashes, no emojis in generated content).
+ * Blocking: rejects em-dashes and emojis in generated content.
+ * Constitution Article V enforcement.
  */
 async function main() {
   let input = '';
@@ -584,8 +584,8 @@ async function main() {
 
     if (result.violations && result.violations.length > 0) {
       console.log(JSON.stringify({
-        decision: 'allow',
-        reason: \`[Style Guard] \${result.violations.join(' ')}\`,
+        decision: 'block',
+        reason: \`[Style Guard] \${result.violations.join(' ')} Rewrite without em-dashes and emojis.\`,
       }));
       return;
     }