chati-dev 1.0.1 → 1.1.0

package/framework/constitution.md

@@ -234,5 +234,30 @@ Example of BAD criteria:
 
 ---
 
-*chati.dev Constitution v1.0.0 — 10 Articles + Preamble*
+## Article XI: Mode Governance
+
+The pipeline operates in three execution modes that control agent permissions. Modes are derived from `project.state` in session.yaml.
+
+### Mode Definitions
+
+| Mode | States | Read Scope | Write Scope |
+|------|--------|------------|-------------|
+| **clarity** | clarity | Entire project (codebase + chati.dev/) | `chati.dev/` and `.chati/` only |
+| **build** | build, validate | Entire project | Entire project |
+| **deploy** | deploy | Entire project | Entire project + infra/CI operations |
+
+### Enforcement Rules
+
+1. In `clarity` mode, agents MAY read any file in the project (essential for brownfield-wu)
+2. In `clarity` mode, agents MUST NOT write/edit files outside `chati.dev/` and `.chati/`
+3. Transition to `build` requires QA-Planning score >= 95% (Article II)
+4. Transition to `deploy` requires QA-Implementation APPROVED
+5. Backward transition from `build` to `clarity` is permitted when QA-Implementation classifies an issue as `spec` or `architecture` (not `code`)
+6. Mode overrides require explicit user confirmation and are logged in session.yaml
+
+**Enforcement: BLOCK** — Write operations outside permitted scope are rejected.
+
+---
+
+*chati.dev Constitution v1.0.0 — 11 Articles + Preamble*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/orchestrator/chati.md

@@ -143,6 +143,119 @@ When an agent completes (score >= 95%):
 
 ---
 
+## Mode Enforcement Protocol
+
+### Scope Validation
+
+Before any agent writes a file, the orchestrator validates the operation against the current mode:
+
+```
+If project.state == "clarity":
+  ALLOW write to: chati.dev/**, .chati/**
+  BLOCK write to: everything else
+  ALLOW read: everything (essential for brownfield-wu codebase analysis)
+
+If project.state == "build" OR "validate":
+  ALLOW write to: everything
+  ALLOW read: everything
+
+If project.state == "deploy":
+  ALLOW write to: everything
+  ALLOW read: everything
+  ALLOW infra operations (CI/CD, deployment)
+```
+
+### Autonomous Mode Transitions
+
+Mode transitions are AUTOMATIC based on quality gate results. The orchestrator executes the transition when the trigger condition is met.
+
+```
+clarity -> build:
+  TRIGGER: qa-planning agent completes with score >= 95%
+  ACTION:
+    1. Update project.state = "build"
+    2. Log transition in session.yaml mode_transitions:
+       - timestamp: "{now}"
+         from: clarity
+         to: build
+         trigger: "qa-planning completed with score {score}%"
+         type: automatic
+    3. Notify user: "Planning approved. Entering BUILD mode."
+    4. Route to dev agent
+
+build -> validate:
+  TRIGGER: dev agent completes all assigned tasks
+  ACTION:
+    1. Update project.state = "validate"
+    2. Log transition in mode_transitions
+    3. Route to qa-implementation agent
+
+validate -> deploy:
+  TRIGGER: qa-implementation agent APPROVED
+  ACTION:
+    1. Update project.state = "deploy"
+    2. Log transition in mode_transitions
+    3. Notify user: "Code validated. Entering DEPLOY mode."
+    4. Route to devops agent
+
+deploy -> completed:
+  TRIGGER: devops agent completes deployment
+  ACTION:
+    1. Update project.state = "completed"
+    2. Log transition in mode_transitions
+    3. Present final project summary
+```
+
+### Backward Transitions
+
+```
+build/validate -> clarity:
+  TRIGGER: qa-implementation classifies issue as:
+    - issue_type: "spec" (requirement gap, ambiguity, conflict)
+    - issue_type: "architecture" (design flaw, missing component)
+  ACTION:
+    1. Update project.state = "clarity"
+    2. Log backward transition in mode_transitions:
+       - type: backward
+         reason: "{QA finding description}"
+    3. Identify target agent:
+       - issue_type "spec" -> route to detail agent
+       - issue_type "architecture" -> route to architect agent
+    4. Mark downstream agents as "needs_revalidation" in session.yaml
+    5. Route to target agent with QA findings as context
+    6. After fix: re-run qa-planning before returning to build
+
+  NOT TRIGGERED when issue_type is:
+    - "code" (implementation bug) -> fix in build mode
+    - "test" (missing/failing tests) -> fix in build mode
+    - "security" (vulnerability) -> fix in build mode
+```
+
+### Mode Override (via Deviation Protocol)
+
+When user requests to skip phases (e.g., "I need to code this NOW"):
+
+```
+1. Orchestrator detects intent to change mode
+2. Inform user of current state and what will be skipped:
+   "You're in CLARITY mode. Skipping to BUILD will bypass:
+    - {list of pending CLARITY agents}
+    Artifacts from these agents will not be generated."
+3. Request explicit confirmation
+4. If confirmed:
+   - Update project.state to requested mode
+   - Log override in mode_transitions:
+     - type: override
+       skipped_agents: [list of skipped agents]
+       reason: "{user's stated reason}"
+   - Mark skipped agents as "skipped" in session.yaml (not "completed")
+   - Continue with target agent
+5. After override session completes, suggest:
+   "You skipped CLARITY phases. Want to go back and complete planning?"
+```
+
+---
+
 ## Deviation Protocol (Protocol 5.7)
 
 ```
@@ -302,7 +415,7 @@ To activate autonomous mode:
 ## Constitution Enforcement
 
 The orchestrator enforces the Constitution (chati.dev/constitution.md):
-- **BLOCK** enforcement: Halt agent on violation (Articles I, II, III, IV, VII, VIII, X)
+- **BLOCK** enforcement: Halt agent on violation (Articles I, II, III, IV, VII, VIII, X, XI)
 - **GUIDE** enforcement: Correct behavior without halting (Articles V, IX)
 - **WARN** enforcement: Generate warning in QA (Article VI)
 

package/framework/schemas/session.schema.json

@@ -60,7 +60,7 @@
           "type": "object",
           "required": ["status", "score", "criteria_count"],
           "properties": {
-            "status": { "enum": ["pending", "in_progress", "completed"] },
+            "status": { "enum": ["pending", "in_progress", "completed", "skipped", "needs_revalidation"] },
             "score": { "type": "number", "minimum": 0, "maximum": 100 },
             "criteria_count": { "type": "integer", "minimum": 0 },
             "completed_at": { "type": ["string", "null"], "format": "date-time" }
@@ -98,6 +98,27 @@
           "resolved": { "type": "boolean" }
         }
       }
+    },
+    "mode_transitions": {
+      "type": "array",
+      "description": "Audit trail of all mode transitions",
+      "items": {
+        "type": "object",
+        "required": ["timestamp", "from", "to", "trigger"],
+        "properties": {
+          "timestamp": { "type": "string", "format": "date-time" },
+          "from": { "enum": ["clarity", "build", "validate", "deploy", "completed"] },
+          "to": { "enum": ["clarity", "build", "validate", "deploy", "completed"] },
+          "trigger": { "type": "string", "description": "What caused the transition (agent completion, override, backward)" },
+          "type": { "enum": ["automatic", "backward", "override"], "description": "Transition classification" },
+          "skipped_agents": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Agents skipped (override only)"
+          },
+          "reason": { "type": "string", "description": "User reason (override only) or QA finding (backward only)" }
+        }
+      }
     }
   }
 }

package/framework/workflows/brownfield-fullstack.yaml

@@ -99,6 +99,23 @@ phases:
         creates: [chati.dev/artifacts/8-Validation/deploy-report.md]
 
 transitions:
-  clarity_to_build: "QA-Planning score >= 95%"
-  build_to_deploy: "QA-Implementation APPROVED"
-  deploy_to_completed: "DevOps deployment verified"
+  clarity_to_build:
+    trigger: "qa-planning.score >= 95"
+    type: automatic
+    action: "Update project.state = build"
+  build_to_validate:
+    trigger: "dev.status == completed"
+    type: automatic
+    action: "Update project.state = validate"
+  validate_to_deploy:
+    trigger: "qa-implementation.status == approved"
+    type: automatic
+    action: "Update project.state = deploy"
+  deploy_to_completed:
+    trigger: "devops.status == completed"
+    type: automatic
+    action: "Update project.state = completed"
+  backward_to_clarity:
+    trigger: "qa-implementation.issue_type in [spec, architecture]"
+    type: backward
+    action: "Update project.state = clarity, route to responsible agent"

package/framework/workflows/greenfield-fullstack.yaml

@@ -103,6 +103,23 @@ phases:
         notes: "Git operations, deployment, documentation"
 
 transitions:
-  clarity_to_build: "QA-Planning score >= 95%"
-  build_to_deploy: "QA-Implementation APPROVED"
-  deploy_to_completed: "DevOps deployment verified"
+  clarity_to_build:
+    trigger: "qa-planning.score >= 95"
+    type: automatic
+    action: "Update project.state = build"
+  build_to_validate:
+    trigger: "dev.status == completed"
+    type: automatic
+    action: "Update project.state = validate"
+  validate_to_deploy:
+    trigger: "qa-implementation.status == approved"
+    type: automatic
+    action: "Update project.state = deploy"
+  deploy_to_completed:
+    trigger: "devops.status == completed"
+    type: automatic
+    action: "Update project.state = completed"
+  backward_to_clarity:
+    trigger: "qa-implementation.issue_type in [spec, architecture]"
+    type: backward
+    action: "Update project.state = clarity, route to responsible agent"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AI-Powered Multi-Agent Development Framework — 13 agents, 7 IDEs, 4 languages",
   "type": "module",
   "bin": {