chati-dev 4.1.6 → 4.2.0

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.6",
+  "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/orchestrator/cli.js

@@ -30,8 +30,11 @@ import {
 import { analyzeDeviationImpact, applyDeviation } from './index.js';
 import { detectQuickFlow, detectStandardFlow } from './index.js';
 import { AGENT_FILE_MAP } from '../terminal/prompt-builder.js';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
+import {
+  initTaskList, readTaskList, getTeamProgress,
+} from '../terminal/team-task-list.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -375,12 +378,27 @@ async function handleNext(projectDir) {
   // Resolve model for next agent
   const modelInfo = resolveAgentModel(nextAgent, projectDir);
 
-  // Check for parallel group
+  // Check for parallel group — with Agent Teams override (Article XXI)
   let action, spawnCommand = null, parallelSpawnCommand = null, parallelAgents = [];
+  let teamData = null;
   if (nextInfo.isParallel && nextInfo.group.length > 1) {
-    action = 'spawn_parallel';
-    parallelAgents = nextInfo.group;
-    parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+    // When agent_teams is enabled, substitute spawn_parallel with spawn_team
+    if (isAgentTeamsEnabled(projectDir)) {
+      const teamType = nextInfo.group.includes('dev') ? 'build' : 'planning';
+      const teamConfig = TEAM_CONFIGS[teamType];
+      const teamId = generateTeamId(teamConfig.slug);
+      action = 'spawn_team';
+      parallelAgents = teamConfig.members;
+      teamData = {
+        team_id: teamId,
+        team_type: teamType,
+        members: teamConfig.members,
+      };
+    } else {
+      action = 'spawn_parallel';
+      parallelAgents = nextInfo.group;
+      parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+    }
   } else if (isInteractive) {
     action = 'activate_interactive';
   } else {
@@ -391,7 +409,7 @@ async function handleNext(projectDir) {
   const progress = getPipelineProgress(pipelineState);
   const bracket = estimateContextBracket(completedAgents.length, AGENT_PIPELINE.length);
 
-  return {
+  const result = {
     action,
     agent: nextAgent,
     agent_file: agentFile,
@@ -407,6 +425,15 @@ async function handleNext(projectDir) {
     session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
     status_summary: `${lastAgent} completed. Next: ${nextAgent} (${action.replace('_', ' ')}, ${agentDef?.phase || 'unknown'} phase).`,
   };
+
+  // Include team data when spawn_team action is selected (Article XXI)
+  if (teamData) {
+    result.team_id = teamData.team_id;
+    result.team_type = teamData.team_type;
+    result.members = teamData.members;
+  }
+
+  return result;
 }
 
 async function handleAdvance(projectDir, args) {
@@ -929,6 +956,367 @@ async function handleScan(projectDir, args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Agent Teams Handlers (Article XXI)
+// ---------------------------------------------------------------------------
+
+const TEAM_CONFIGS = {
+  planning: {
+    members: ['detail', 'architect', 'ux'],
+    slug: 'pln',
+    templateFile: 'team-planning-tasks.yaml',
+  },
+  build: {
+    members: ['dev', 'qa-implementation'],
+    slug: 'bld',
+    templateFile: 'team-build-tasks.yaml',
+  },
+};
+
+function generateTeamId(slug) {
+  const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  return `TM-${date}-${slug}`;
+}
+
+function isAgentTeamsEnabled(projectDir) {
+  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  if (!existsSync(configPath)) return false;
+  const raw = readFileSync(configPath, 'utf-8');
+  const match = raw.match(/agent_teams:\s*(true|false)/);
+  return match ? match[1] === 'true' : false;
+}
+
+async function handleSpawnTeam(projectDir, args) {
+  const teamType = args['team-type'];
+  if (!teamType || !TEAM_CONFIGS[teamType]) {
+    return errorResult('--team-type required (planning|build)', 'MISSING_TEAM_TYPE');
+  }
+
+  // Check feature flag
+  if (!isAgentTeamsEnabled(projectDir)) {
+    return {
+      action: 'spawn_parallel',
+      fallback_required: true,
+      fallback_reason: 'agent_teams_disabled',
+    };
+  }
+
+  const config = TEAM_CONFIGS[teamType];
+  const teamId = generateTeamId(config.slug);
+  const teamDir = join(projectDir, '.chati', 'teams', teamId);
+  const mailboxDir = join(teamDir, 'mailbox');
+  const taskListPath = join(teamDir, 'tasks.yaml');
+  const templatePath = join(projectDir, 'chati.dev', 'templates', config.templateFile);
+
+  // Create team directories
+  mkdirSync(mailboxDir, { recursive: true });
+
+  // Initialize task list from template
+  try {
+    initTaskList(taskListPath, templatePath, { team_id: teamId });
+
+    // For build teams: dynamically populate tasks from tasks.md (Article XXI §9)
+    if (teamType === 'build') {
+      const tasksArtifact = join(projectDir, 'chati.dev', 'artifacts', '6-Tasks', 'tasks.md');
+      if (existsSync(tasksArtifact)) {
+        const tasksContent = readFileSync(tasksArtifact, 'utf-8');
+        // Extract task IDs (pattern: T{phase}.{seq})
+        const taskMatches = tasksContent.match(/^#+\s*(T\d+\.\d+)[:\s—-]+(.+)$/gm) || [];
+        const dynamicTasks = [];
+        let seq = 1;
+
+        for (const match of taskMatches) {
+          const m = match.match(/^#+\s*(T\d+\.\d+)[:\s—-]+(.+)$/);
+          if (!m) continue;
+          const [, taskRef, title] = m;
+          const seqStr = String(seq).padStart(3, '0');
+
+          // Dev task
+          dynamicTasks.push({
+            id: `TT-BLD-${seqStr}-DEV`,
+            title: `${taskRef}: ${title.trim()}`,
+            assigned_to: 'dev',
+            status: 'pending',
+            score: null,
+            blocker: null,
+            source_task: taskRef,
+            depends_on: seq > 1 ? [`TT-BLD-${String(seq - 1).padStart(3, '0')}-QA`] : [],
+            threshold: 95,
+          });
+
+          // QA review task
+          dynamicTasks.push({
+            id: `TT-BLD-${seqStr}-QA`,
+            title: `${taskRef}: Review + approve`,
+            assigned_to: 'qa-implementation',
+            status: 'pending',
+            score: null,
+            blocker: null,
+            source_task: taskRef,
+            depends_on: [`TT-BLD-${seqStr}-DEV`],
+            threshold: 95,
+          });
+
+          seq++;
+        }
+
+        if (dynamicTasks.length > 0) {
+          const taskList = readTaskList(taskListPath);
+          if (taskList) {
+            taskList.tasks = dynamicTasks;
+            taskList.last_updated = new Date().toISOString();
+            const yaml = await import('js-yaml');
+            writeFileSync(taskListPath, yaml.default.dump(taskList, { lineWidth: -1, noRefs: true }), 'utf-8');
+          }
+        }
+      }
+    }
+  } catch (err) {
+    return errorResult(`Failed to init team task list: ${err.message}`, 'TEAM_INIT_ERROR');
+  }
+
+  // Update session with team entry
+  const previousAgent = args['previous-agent'] || 'none';
+  const provider = args.provider || 'claude';
+
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session) {
+      if (!session.teams) session.teams = [];
+      session.teams.push({
+        team_id: teamId,
+        phase: teamType === 'planning' ? 'planning' : 'build',
+        mission: teamType === 'planning'
+          ? 'Co-design PRD, architecture, and UX specification with cross-validated alignment'
+          : 'Implement all tasks with per-task QA review and evidence-based quality gates',
+        lead: 'orchestrator',
+        roster: config.members,
+        status: 'forming',
+        task_list_path: `.chati/teams/${teamId}/tasks.yaml`,
+        mailbox_path: `.chati/teams/${teamId}/mailbox/`,
+        formed_at: new Date().toISOString(),
+        dissolved_at: null,
+        team_score: null,
+        member_scores: {},
+        correction_cycles: 0,
+        echo_events: [],
+        fallback_used: false,
+      });
+
+      if (!session.team_events) session.team_events = [];
+      session.team_events.push({
+        timestamp: new Date().toISOString(),
+        event: 'formed',
+        team_id: teamId,
+        trigger: `${teamType} team formation after ${previousAgent}`,
+      });
+
+      await updateSession(projectDir, session);
+    }
+  } catch { /* non-critical: session update may fail, team can still spawn */ }
+
+  // Build spawn command
+  const spawnCmd = [
+    'node', join('packages', 'chati-dev', 'src', 'terminal', 'run-team.js'),
+    '--team-id', teamId,
+    '--team-type', teamType,
+    '--project-dir', resolve(projectDir),
+    '--previous-agent', previousAgent,
+    '--provider', provider,
+    '--timeout', args.timeout || '1800000',
+  ].join(' ');
+
+  return {
+    action: 'spawn_team',
+    team_id: teamId,
+    team_type: teamType,
+    members: config.members,
+    task_list_path: `.chati/teams/${teamId}/tasks.yaml`,
+    mailbox_path: `.chati/teams/${teamId}/mailbox/`,
+    spawn_team_command: spawnCmd,
+    poll_interval_ms: 5000,
+    fallback_required: false,
+  };
+}
+
+async function handleTeamStatus(projectDir, args) {
+  const teamId = args['team-id'];
+  if (!teamId) return errorResult('--team-id required', 'MISSING_TEAM_ID');
+
+  const taskListPath = join(projectDir, '.chati', 'teams', teamId, 'tasks.yaml');
+  const progress = getTeamProgress(taskListPath);
+
+  // Read echo events from session
+  let echoEvents = [];
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session && session.teams) {
+      const team = session.teams.find(t => t.team_id === teamId);
+      if (team) echoEvents = team.echo_events || [];
+    }
+  } catch { /* non-critical */ }
+
+  return {
+    team_id: teamId,
+    status: progress.done === progress.total ? 'completing' : 'active',
+    member_progress: progress.memberProgress,
+    total_tasks: progress.total,
+    completed_tasks: progress.done,
+    pending_tasks: progress.pending,
+    blocked_tasks: progress.blocked,
+    echo_events: echoEvents,
+  };
+}
+
+async function handleTeamDissolve(projectDir, args) {
+  const teamId = args['team-id'];
+  if (!teamId) return errorResult('--team-id required', 'MISSING_TEAM_ID');
+
+  const taskListPath = join(projectDir, '.chati', 'teams', teamId, 'tasks.yaml');
+  const progress = getTeamProgress(taskListPath);
+
+  // Derive team type from team ID slug (for mailbox checks and tier threshold)
+  const teamType = teamId.includes('-bld') ? 'build' : 'planning';
+
+  // Read echo events from session
+  let echoEvents = [];
+  try {
+    const { loaded: echoLoaded, session: echoSession } = loadSession(projectDir);
+    if (echoLoaded && echoSession && echoSession.teams) {
+      const team = echoSession.teams.find(t => t.team_id === teamId);
+      if (team) echoEvents = team.echo_events || [];
+    }
+  } catch { /* best-effort */ }
+
+  // Calculate team score
+  const memberScores = {};
+  let totalScore = 0;
+  let scoreCount = 0;
+  for (const [member, data] of Object.entries(progress.memberProgress)) {
+    if (data.score !== null) {
+      memberScores[member] = data.score;
+      totalScore += data.score;
+      scoreCount++;
+    }
+  }
+  const teamScore = scoreCount > 0 ? Math.round((totalScore / scoreCount) * 10) / 10 : 0;
+
+  // Team Quality Gate — verify all 6 conditions (Article XXI section 6)
+  const allDone = progress.done === progress.total;
+  // Dynamic tier threshold per Article XXI §6: must meet highest tier in roster
+  // QA agents (qa-planning, qa-implementation) require 95%, standard agents 90%
+  const QA_AGENTS = ['qa-planning', 'qa-implementation'];
+  const teamConfig = TEAM_CONFIGS[teamType];
+  const hasQaAgent = teamConfig ? teamConfig.members.some(m => QA_AGENTS.includes(m)) : false;
+  const tierThreshold = hasQaAgent ? 95 : 90;
+  const allScoresPass = Object.values(memberScores).every(s => s >= tierThreshold);
+  const noBlockers = progress.blocked === 0;
+
+  // Check mailbox cleanliness
+  let mailboxClean = true;
+  try {
+    const { readInbox } = await import('../terminal/team-task-list.js');
+    const mailboxDir = join(projectDir, '.chati', 'teams', teamId, 'mailbox');
+    // Check all members for unresolved messages
+    const dissolveTeamConfig = TEAM_CONFIGS[teamType];
+    if (dissolveTeamConfig) {
+      for (const member of dissolveTeamConfig.members) {
+        const inbox = readInbox(mailboxDir, member);
+        const unresolved = inbox.filter(m => m.type === 'task_review_findings' && m.payload?.verdict === 'block');
+        if (unresolved.length > 0) { mailboxClean = false; break; }
+      }
+    }
+  } catch { /* mailbox check is best-effort */ }
+
+  // Check correction cycles against config limit (Article XXI §6)
+  let correctionCyclesOk = true;
+  let maxCorrectionCycles = 2; // default per constitution
+  try {
+    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    if (existsSync(configPath)) {
+      const configRaw = readFileSync(configPath, 'utf-8');
+      const maxMatch = configRaw.match(/team_correction_cycles_max:\s*(\d+)/);
+      if (maxMatch) maxCorrectionCycles = parseInt(maxMatch[1], 10);
+    }
+  } catch { /* use default */ }
+  try {
+    const { loaded, session: sess } = loadSession(projectDir);
+    if (loaded && sess && sess.teams) {
+      const team = sess.teams.find(t => t.team_id === teamId);
+      if (team && team.correction_cycles > maxCorrectionCycles) correctionCyclesOk = false;
+    }
+  } catch { /* best-effort */ }
+
+  // Determine dissolution state based on all conditions
+  const qualityGatePassed = allDone && allScoresPass && mailboxClean && noBlockers && correctionCyclesOk && teamScore >= tierThreshold;
+  const state = qualityGatePassed ? 'clean' : 'degraded';
+  const gateFailures = [];
+  if (!allDone) gateFailures.push('incomplete_tasks');
+  if (!allScoresPass) gateFailures.push('scores_below_threshold');
+  if (!mailboxClean) gateFailures.push('unresolved_mailbox_messages');
+  if (!noBlockers) gateFailures.push('open_blockers');
+  if (!correctionCyclesOk) gateFailures.push('correction_cycles_exceeded');
+  if (teamScore < 90) gateFailures.push('team_score_below_threshold');
+
+  // Update session
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session && session.teams) {
+      const team = session.teams.find(t => t.team_id === teamId);
+      if (team) {
+        team.status = state === 'clean' ? 'dissolved' : 'degraded';
+        team.dissolved_at = new Date().toISOString();
+        team.team_score = teamScore;
+        team.member_scores = memberScores;
+      }
+
+      if (!session.team_events) session.team_events = [];
+      session.team_events.push({
+        timestamp: new Date().toISOString(),
+        event: state === 'clean' ? 'dissolved' : 'degraded',
+        team_id: teamId,
+        trigger: state === 'clean' ? 'Team Quality Gate passed' : `Degraded dissolution — failures: ${gateFailures.join(', ')}`,
+        state,
+      });
+
+      // Sync member scores to agents block
+      if (session.agents) {
+        for (const [member, score] of Object.entries(memberScores)) {
+          if (session.agents[member]) {
+            session.agents[member].score = score;
+            session.agents[member].status = 'completed';
+            session.agents[member].completed_at = new Date().toISOString();
+          }
+        }
+      }
+
+      await updateSession(projectDir, session);
+    }
+  } catch { /* non-critical */ }
+
+  return {
+    dissolved: true,
+    team_id: teamId,
+    team_score: teamScore,
+    member_scores: memberScores,
+    state,
+    all_tasks_complete: allDone,
+    echo_events: echoEvents,
+    quality_gate: {
+      passed: qualityGatePassed,
+      failures: gateFailures,
+      checks: {
+        all_tasks_complete: allDone,
+        all_scores_pass_threshold: allScoresPass,
+        mailbox_clean: mailboxClean,
+        no_open_blockers: noBlockers,
+        correction_cycles_ok: correctionCyclesOk,
+        team_score_above_threshold: teamScore >= 90,
+      },
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -977,8 +1365,17 @@ export async function runOrchestrate(subCommand, argv, projectDir) {
       case 'scan':
         output(await handleScan(projectDir, args));
         break;
+      case 'spawn-team':
+        output(await handleSpawnTeam(projectDir, args));
+        break;
+      case 'team-status':
+        output(await handleTeamStatus(projectDir, args));
+        break;
+      case 'team-dissolve':
+        output(await handleTeamDissolve(projectDir, args));
+        break;
       default:
-        output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan`, 'UNKNOWN_COMMAND'));
+        output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan, spawn-team, team-status, team-dissolve`, 'UNKNOWN_COMMAND'));
         break;
     }
   } catch (err) {