chati-dev 4.1.6 → 4.2.1

package/framework/hooks/license-guard.js

@@ -19,7 +19,7 @@ import { homedir } from 'os';
 
 const API_BASE = 'https://chati.dev/api';
 const TELEMETRY_ENDPOINT = 'https://chati.dev/api/telemetry';
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours — shorter window to catch expirations faster
 const PING_THROTTLE_MS = 5 * 60 * 1000; // 5 minutes
 
 const GLOBAL_DIR = join(homedir(), '.chati-dev');
@@ -31,9 +31,9 @@ async function main() {
   for await (const chunk of process.stdin) input += chunk;
 
   try {
-    // Read global license file
+    // Read global license file — REQUIRED for operation
     if (!existsSync(LICENSE_PATH)) {
-      allow(); // No license configured — orchestrator handles inline activation
+      block('No license found. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
       return;
     }
 
@@ -41,7 +41,7 @@ async function main() {
     const licenseKey = readYamlField(licenseRaw, 'key');
 
     if (!licenseKey || licenseKey === 'null') {
-      allow();
+      block('No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing');
       return;
     }
 
@@ -89,8 +89,15 @@ async function main() {
         return;
       }
       block(buildMessage(data.status, data.reason));
-    } catch { /* expected: API may be unreachable — fail open */
-      allow();
+    } catch {
+      // API unreachable — check if we have a recent VALID cache to fall back on
+      // If cache is less than 24h old AND was VALID, allow (grace period for network issues)
+      // Otherwise block — we cannot verify the license
+      if (age < 24 * 60 * 60 * 1000 && status === 'VALID') {
+        allow(); // grace: last check was recent and valid, allow despite network issue
+      } else {
+        block('Unable to verify license (network issue). If this persists, check your connection.\nRun: npx chati-dev activate --key=YOUR-KEY');
+      }
     }
   } catch { /* expected: stdin parse may fail — fail open */
     allow();

package/framework/hooks/prism-engine.js

@@ -26,6 +26,17 @@ function readSessionState(projectDir) {
     return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
   };
 
+  // Detect active team (Article XXI)
+  let activeTeamId = null;
+  let activeTeamPhase = null;
+  const teamStatusMatch = raw.match(/teams:[\s\S]*?status:\s*(active|forming)/m);
+  if (teamStatusMatch) {
+    const teamIdMatch = raw.match(/team_id:\s*(TM-\d{8}-[a-z]{3})/m);
+    activeTeamId = teamIdMatch ? teamIdMatch[1] : null;
+    const teamPhaseMatch = raw.match(/phase:\s*(planning|build)/m);
+    activeTeamPhase = teamPhaseMatch ? teamPhaseMatch[1] : null;
+  }
+
   return {
     mode: extract('mode') || 'discover',
     currentAgent: extract('current_agent') || null,
@@ -33,6 +44,8 @@ function readSessionState(projectDir) {
     pipelinePosition: extract('pipeline_position') || null,
     turnCount: parseInt(extract('turn_count') || '0', 10),
     provider: extract('provider') || 'claude',
+    activeTeamId,
+    activeTeamPhase,
   };
 }
 
@@ -81,12 +94,12 @@ async function main() {
 
     // Primary: turn-count tracks cumulative context consumption across the session.
     // Fallback: prompt-length for first turn or missing session data.
+    const promptText = event.prompt || '';
     let remainingPercent;
     const maxTurns = 40;
     if (session.turnCount > 0) {
       remainingPercent = Math.max(0, Math.round((1 - session.turnCount / maxTurns) * 100));
     } else {
-      const promptText = event.prompt || '';
       const estimatedTokens = Math.ceil(promptText.length / 4);
       const contextLimit = hookResolveLimit(inferredModel, session.provider);
       remainingPercent = Math.max(0, Math.round((1 - estimatedTokens / contextLimit) * 100));
@@ -111,6 +124,22 @@ async function main() {
       }
     }
 
+    // L6 Team Roster Layer (Article XII, Article XXI) — injected when a team is active
+    // Max 500 tokens, flat budget. Contains team metadata + shared task status only.
+    let teamContextBlock = '';
+    if (session.activeTeamId && bracket !== 'CRITICAL') {
+      const taskListPath = join(projectDir, '.chati', 'teams', session.activeTeamId, 'tasks.yaml');
+      if (existsSync(taskListPath)) {
+        // Read and cap at 800 chars (~200 tokens) to stay within 500-token budget
+        const rawTasks = readFileSync(taskListPath, 'utf-8').trim().slice(0, 800);
+        teamContextBlock = [
+          `  <team-context team-id="${session.activeTeamId}" phase="${session.activeTeamPhase}">`,
+          `    ${rawTasks.split('\n').join('\n    ')}`,
+          '  </team-context>',
+        ].join('\n');
+      }
+    }
+
     // Frustration detection — adapt response style when user is frustrated
     const frustrationDetected = detectFrustration(promptText);
 
@@ -127,6 +156,7 @@ async function main() {
       session.currentAgent ? `  <agent>${session.currentAgent}</agent>` : '',
       session.pipelinePosition ? `  <pipeline-position>${session.pipelinePosition}</pipeline-position>` : '',
       memoryBlock,
+      teamContextBlock,
       bracket === 'CRITICAL' ? '  <advisory>Context running low. Consider handoff or summary.</advisory>' : '',
       microcompactAdvisory,
       frustrationDetected ? '  <advisory priority="high">User shows signs of frustration. Be more direct, acknowledge the issue explicitly, focus on the solution, avoid repeating previous suggestions.</advisory>' : '',

package/framework/hooks/settings.json

@@ -5,6 +5,10 @@
       {
         "matcher": ".*",
         "hooks": [
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/license-guard.js"
+          },
           {
             "type": "command",
             "command": "node chati.dev/hooks/prism-engine.js"
@@ -55,6 +59,10 @@
           {
             "type": "command",
             "command": "node chati.dev/hooks/style-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node chati.dev/hooks/team-quality-gate.js"
           }
         ]
       },

package/framework/hooks/team-quality-gate.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Team Quality Gate Hook — PreToolUse (Write|Edit)
+ *
+ * Prevents cross-member artifact contamination in team mode.
+ * When a team is active, each teammate can only write to paths
+ * associated with their assigned tasks.
+ *
+ * If no team is active (CHATI_TEAM_ID absent, or no active team
+ * in session.yaml), this hook allows immediately — zero overhead.
+ *
+ * Article XXI: Agent Teams Governance
+ * Enforcement: BLOCK — writes to another member's artifact scope are rejected.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+// Artifact scope per agent — defines which output paths each agent owns
+const AGENT_ARTIFACT_SCOPES = {
+  detail: [
+    'chati.dev/artifacts/2-PRD/',
+    'chati.dev/artifacts/handoffs/detail-',
+    'prd.md',
+  ],
+  architect: [
+    'chati.dev/artifacts/3-Architecture/',
+    'chati.dev/artifacts/handoffs/architect-',
+    'architecture.md',
+  ],
+  ux: [
+    'chati.dev/artifacts/4-UX/',
+    'chati.dev/artifacts/handoffs/ux-',
+    'ux-specification.md',
+    'brandbook.md',
+    'brandbook.html',
+    'component-discovery-log.md',
+    'reference-analysis.md',
+  ],
+  dev: [
+    'src/',
+    'lib/',
+    'app/',
+    'pages/',
+    'components/',
+    'utils/',
+    'hooks/',
+    'styles/',
+    'public/',
+    'test/',
+    'tests/',
+    '__tests__/',
+    'chati.dev/artifacts/8-Implementation/',
+    'chati.dev/artifacts/handoffs/dev-',
+  ],
+  'qa-implementation': [
+    'chati.dev/artifacts/9-QA-Implementation/',
+    'chati.dev/artifacts/handoffs/qa-implementation-',
+  ],
+};
+
+// Shared paths any teammate can write to
+const SHARED_PATHS = [
+  '.chati/',
+  'chati.dev/artifacts/handoffs/teams/',
+  'chati.dev/artifacts/decisions/',
+];
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  try {
+    const event = JSON.parse(input);
+    const projectDir = event.cwd || process.cwd();
+
+    // Quick exit: no team active → allow everything
+    const teamId = process.env.CHATI_TEAM_ID;
+    if (!teamId) {
+      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      return;
+    }
+
+    // Detect current agent from env or session
+    const currentAgent = process.env.CHATI_TEAM_MEMBER || detectAgentFromSession(projectDir);
+    if (!currentAgent) {
+      // Cannot determine agent → allow (fail-open for safety)
+      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      return;
+    }
+
+    // Get the file path being written
+    const filePath = event.tool_input?.file_path || '';
+    if (!filePath) {
+      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      return;
+    }
+
+    // Normalize path relative to project
+    const relativePath = filePath.replace(projectDir + '/', '').replace(projectDir, '');
+
+    // Check shared paths first — always allowed
+    if (SHARED_PATHS.some(sp => relativePath.startsWith(sp))) {
+      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      return;
+    }
+
+    // Check if another agent owns this path
+    for (const [agent, scopes] of Object.entries(AGENT_ARTIFACT_SCOPES)) {
+      if (agent === currentAgent) continue;
+      for (const scope of scopes) {
+        if (relativePath.startsWith(scope) || (!scope.includes('/') && relativePath.endsWith(scope))) {
+          process.stdout.write(JSON.stringify({
+            result: 'block',
+            reason: `[Team Quality Gate] ${currentAgent} cannot write to ${relativePath} — this path belongs to ${agent}. Use the team mailbox to coordinate changes (Article XXI).`,
+          }));
+          return;
+        }
+      }
+    }
+
+    // Path not owned by anyone specific → allow
+    process.stdout.write(JSON.stringify({ result: 'allow' }));
+  } catch (err) {
+    // Fail-open: hook errors should not block execution
+    process.stderr.write(`[chati] team-quality-gate: ${err.message}\n`);
+    process.stdout.write(JSON.stringify({ result: 'allow' }));
+  }
+}
+
+function detectAgentFromSession(projectDir) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) return null;
+  const raw = readFileSync(sessionPath, 'utf-8');
+  const match = raw.match(/current_agent:\s*(.+)/m);
+  return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
+}
+
+// Only run main when executed directly
+import { fileURLToPath } from 'url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}

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"
+          }
+        }
+      }
     }
   }
 }