chati-dev 4.5.16 → 4.5.27

package/README.md

@@ -99,7 +99,7 @@ The agents guide you through each phase:
 |-------|-------------|--------|
 | **DISCOVER** | Agents interview you about what you want to build | Answer questions about your project |
 | **PLAN** | Agents create PRD, architecture, UX spec, phases, and tasks | Review and approve the plan |
-| **RAIL EXECUTION** | Dependency-ready tasks run on their explicitly selected model, with independent review, bounded rework, recovery, and local evidence | Review material scope or authority escalations |
+| **RAIL EXECUTION** | Dependency-ready tasks run on their explicitly selected model, with independent review, bounded rework, core-observed recovery, and authority-signed CI and acceptance evidence | Review material scope or authority escalations |
 | **RELEASE** | A sealed release lane checks evidence, Git and CI readiness, with explicit human authorization for external actions | Authorize merge, deployment, or publication |
 
 Quality gates run automatically between phases. If something doesn't meet the threshold, the system loops back and fixes it.
@@ -163,7 +163,7 @@ Chati.dev is provider-agnostic. You choose your AI provider during installation,
 | Provider | CLI | Deep Reasoning | Lightweight | Status |
 |----------|-----|---------------|-------------|--------|
 | **Claude** | `claude` | Opus | Sonnet / Haiku | Default |
-| **Gemini** | `gemini` | Pro | Flash | Full support |
+| **Gemini** | `gemini` | Pro | Flash | Legacy v1 support (outside the v2 RAIL pool) |
 | **Codex** | `codex` | Codex | Codex Mini | Full support |
 
 ### How Model Assignment Works
@@ -219,6 +219,11 @@ The system starts in `interactive` mode. Transition to `autonomous` requires bot
 | **RAIL EXECUTION** | Selected task executors, independent reviewers, browser capability where required | Execute the sealed task graph, collect evidence, recover interrupted attempts, and resolve bounded rework |
 | **RELEASE** | Release lane with human authority gate | Verify readiness and perform no external mutation without explicit authorization |
 
+The installed CLI exposes release readiness only. Applications that own a
+deployment integration can import `chati-dev/release`, inject a minted
+`ReleaseTransport`, and execute release or rollback only with the exact signed
+human authorization and smoke evidence required by the durable lane.
+
 ### How the Pipeline Works
 
 ```
@@ -258,7 +263,7 @@ The system starts in `interactive` mode. Transition to `autonomous` requires bot
        │    Dependency-ready task dispatch      │
        │    Selected model and harness only     │
        │    Independent review and rework       │
-       │    Recovery, tracking, local evidence  │
+       │ Recovery, tracking, signed evidence    │
        │                                        │
        └─ Opens release lane ───────────────────┐
                                                 │

package/bin/chati.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { resolve } from 'path';
+import { randomUUID } from 'crypto';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -27,8 +28,8 @@ const command = args[0] || 'init';
 // Without this, `chati orchestrate advance --agent detail` resolves targetDir to `<cwd>/detail/`.
 const KNOWN_SUBCOMMANDS = new Set([
   // CLI subcommands
-  'next', 'advance', 'init', 'status', 'validate-handoff', 'deviation', 'exit',
-  'install-v2', 'migrate-v2', 'rail-import', 'rail-next', 'rail-release-ready', 'rail-claim', 'rail-heartbeat', 'rail-recover', 'rail-complete', 'rail-review', 'rail-tracking-reconcile', 'rail-tracking-pending', 'rail-tracking-ack',
+  'next', 'advance', 'init', 'status', 'validate-handoff', 'deviation', 'exit', 'activate-harness',
+  'install-v2', 'migrate-v2', 'rail-import', 'rail-next', 'rail-dispatch', 'rail-review-run', 'rail-rework', 'rail-adjudicate', 'rail-release-ready', 'rail-recover', 'rail-complete', 'rail-tracking-reconcile', 'rail-tracking-pending', 'rail-tracking-ack', 'rail-tracking-lookup',
   'providers', 'detect-flow', 'backlog', 'qa-plan-score', 'qa-impl-score', 'scan',
   'spawn-team', 'team-status', 'team-dissolve',
   'stats', 'list', 'search', 'clean', 'check', // memory/registry subcommands
@@ -150,65 +151,102 @@ async function main() {
       break;
     }
 
-    case 'rail-release-ready': {
-      const handoffIndex = args.indexOf('--handoff-id');
-      const handoff_id = handoffIndex === -1 ? null : args[handoffIndex + 1];
-      if (!handoff_id) {
-        console.error('Error: rail-release-ready requires --handoff-id <id>');
+    case 'rail-dispatch': {
+      const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
+      if (!value('--handoff-id') || !value('--task-id')) {
+        console.error('Error: rail-dispatch requires --handoff-id <id> and --task-id <id>');
         process.exitCode = 1;
         break;
       }
+      const attemptId = value('--attempt-id') || `attempt-${randomUUID()}`;
       try {
-        const { selectRailReleaseReadiness } = await import('../src/orchestrator/rail-runtime.js');
-        console.log(JSON.stringify(selectRailReleaseReadiness({ projectDir: targetDir, handoff_id }), null, 2));
+        const { executeReadyRailTask } = await import('../src/terminal/run-rail-task.js');
+        const result = await executeReadyRailTask({
+          projectDir: targetDir,
+          handoff_id: value('--handoff-id'),
+          task_id: value('--task-id'),
+          attempt_id: attemptId,
+          operator_id: value('--operator-id') || 'operator://chati/cli',
+          ...(value('--timeout') ? { timeout: Number(value('--timeout')) } : {}),
+          ...(value('--browser-request-json') ? { browser_request: JSON.parse(value('--browser-request-json')) } : {}),
+        });
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exitCode = 1;
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_RELEASE_READINESS_FAILED'}: ${error.message}`);
+        let nextRequiredAction = 'rail_retry_same_attempt';
+        try {
+          const { resolveRailAttemptContext } = await import('../src/orchestrator/rail-runtime.js');
+          resolveRailAttemptContext({ projectDir: targetDir, handoff_id: value('--handoff-id'), attempt_id: attemptId });
+          nextRequiredAction = 'rail_recover_same_attempt_after_lease_expiry';
+        } catch {
+          // The dispatch never created a canonical claim.
+        }
+        console.error(JSON.stringify({
+          ok: false, action: 'error', error: error.code || 'RAIL_DISPATCH_FAILED',
+          detail: error.message, attempt_id: error.details?.attempt_id || attemptId,
+          next_required_action: nextRequiredAction,
+        }));
         process.exitCode = 1;
       }
       break;
     }
 
-    case 'rail-claim': {
-      const value = (flag) => {
-        const index = args.indexOf(flag);
-        return index === -1 ? null : args[index + 1];
-      };
-      const required = ['--handoff-id', '--task-id', '--attempt-id', '--operator-id', '--harness-process-id'];
-      if (required.some((flag) => !value(flag))) {
-        console.error(`Error: rail-claim requires ${required.join(', ')}`);
+    case 'rail-review-run':
+    case 'rail-rework':
+    case 'rail-adjudicate': {
+      const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
+      if (!value('--handoff-id') || !value('--attempt-id')) {
+        console.error(`Error: ${command} requires --handoff-id <id> and --attempt-id <id>`);
         process.exitCode = 1;
         break;
       }
       try {
-        const { claimRailTask } = await import('../src/orchestrator/rail-runtime.js');
-      const result = claimRailTask({
-          projectDir: targetDir, handoff_id: value('--handoff-id'), task_id: value('--task-id'), attempt_id: value('--attempt-id'),
-          operator_id: value('--operator-id'), harness_process_id: value('--harness-process-id'), git_dir: value('--git-dir') || targetDir,
+        const modulePath = command === 'rail-review-run'
+          ? '../src/terminal/run-rail-review.js'
+          : command === 'rail-rework'
+            ? '../src/terminal/run-rail-rework.js'
+            : '../src/terminal/run-rail-adjudication.js';
+        const exportName = command === 'rail-review-run'
+          ? 'executeRailReview'
+          : command === 'rail-rework'
+            ? 'executeRailRework'
+            : 'executeRailAdjudication';
+        const runtime = await import(modulePath);
+        const result = await runtime[exportName]({
+          projectDir: targetDir,
+          handoff_id: value('--handoff-id'),
+          attempt_id: value('--attempt-id'),
+          ...(value('--timeout') ? { timeout: Number(value('--timeout')) } : {}),
         });
         console.log(JSON.stringify(result, null, 2));
+        const validReviewControlFlow = command === 'rail-review-run'
+          && ['rail_rework_required', 'rail_adjudication_required', 'human_authority_required'].includes(result.next_required_action);
+        if (!result.ok && !validReviewControlFlow) process.exitCode = 1;
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_CLAIM_FAILED'}: ${error.message}`);
+        const code = command === 'rail-review-run'
+          ? 'RAIL_REVIEW_FAILED'
+          : command === 'rail-rework'
+            ? 'RAIL_REWORK_FAILED'
+            : 'RAIL_ADJUDICATION_FAILED';
+        console.error(`Error: ${error.code || code}: ${error.message}`);
         process.exitCode = 1;
       }
       break;
     }
 
-    case 'rail-heartbeat': {
-      const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
-      const required = ['--handoff-id', '--attempt-id', '--claim-id', '--operator-id'];
-      if (required.some((flag) => !value(flag))) {
-        console.error(`Error: rail-heartbeat requires ${required.join(', ')}`);
+    case 'rail-release-ready': {
+      const handoffIndex = args.indexOf('--handoff-id');
+      const handoff_id = handoffIndex === -1 ? null : args[handoffIndex + 1];
+      if (!handoff_id) {
+        console.error('Error: rail-release-ready requires --handoff-id <id>');
         process.exitCode = 1;
         break;
       }
       try {
-        const { heartbeatRailTask } = await import('../src/orchestrator/rail-runtime.js');
-        console.log(JSON.stringify(heartbeatRailTask({
-          projectDir: targetDir, handoff_id: value('--handoff-id'), attempt_id: value('--attempt-id'),
-          claim_id: value('--claim-id'), operator_id: value('--operator-id'),
-        }), null, 2));
+        const { selectRailReleaseReadiness } = await import('../src/orchestrator/rail-runtime.js');
+        console.log(JSON.stringify(selectRailReleaseReadiness({ projectDir: targetDir, handoff_id }), null, 2));
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_HEARTBEAT_FAILED'}: ${error.message}`);
+        console.error(`Error: ${error.code || 'RAIL_RELEASE_READINESS_FAILED'}: ${error.message}`);
         process.exitCode = 1;
       }
       break;
@@ -216,22 +254,40 @@ async function main() {
 
     case 'rail-recover': {
       const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
-      const required = ['--handoff-id', '--attempt-id', '--operator-id', '--harness-process-id', '--reconciliation'];
+      const required = ['--handoff-id', '--attempt-id', '--operator-id'];
       if (required.some((flag) => !value(flag))) {
         console.error(`Error: rail-recover requires ${required.join(', ')}`);
         process.exitCode = 1;
         break;
       }
+      const attemptId = value('--attempt-id');
       try {
-        const reconciliation = JSON.parse(readFileSync(resolve(value('--reconciliation')), 'utf8'));
-        const { recoverRailTask } = await import('../src/orchestrator/rail-runtime.js');
-        console.log(JSON.stringify(recoverRailTask({
-          projectDir: targetDir, handoff_id: value('--handoff-id'), attempt_id: value('--attempt-id'),
-          operator_id: value('--operator-id'), harness_process_id: value('--harness-process-id'), reconciliation,
+        const { resolveRailAttemptContext } = await import('../src/orchestrator/rail-runtime.js');
+        const { executeReadyRailTask } = await import('../src/terminal/run-rail-task.js');
+        const context = resolveRailAttemptContext({
+          projectDir: targetDir,
+          handoff_id: value('--handoff-id'),
+          attempt_id: attemptId,
+        });
+        const result = await executeReadyRailTask({
+          projectDir: targetDir,
+          handoff_id: value('--handoff-id'),
+          task_id: context.task.task_id,
+          attempt_id: attemptId,
+          operator_id: value('--operator-id'),
           git_dir: value('--git-dir') || targetDir,
-        }), null, 2));
+          recover_expired: true,
+          ...(value('--timeout') ? { timeout: Number(value('--timeout')) } : {}),
+          ...(value('--browser-request-json') ? { browser_request: JSON.parse(value('--browser-request-json')) } : {}),
+        });
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.ok) process.exitCode = 1;
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_RECOVERY_FAILED'}: ${error.message}`);
+        console.error(JSON.stringify({
+          ok: false, action: 'error', error: error.code || 'RAIL_RECOVERY_FAILED',
+          detail: error.message, attempt_id: error.details?.attempt_id || attemptId,
+          next_required_action: 'rail_recover_and_dispatch_same_attempt',
+        }));
         process.exitCode = 1;
       }
       break;
@@ -247,10 +303,10 @@ async function main() {
       try {
         const completion = JSON.parse(readFileSync(resolve(value('--completion')), 'utf8'));
         const { completeRailTask } = await import('../src/orchestrator/rail-runtime.js');
-        const { completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, completed_at, metrics } = completion;
+        const { completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, acceptance_authority_receipt, completed_at, metrics } = completion;
         console.log(JSON.stringify(completeRailTask({
           projectDir: targetDir, handoff_id: value('--handoff-id'), completion_id, attempt_id, claim_id, operator_id, state, git, ci,
-          reviews, acceptance_evidence_refs, ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }),
+          reviews, acceptance_evidence_refs, acceptance_authority_receipt, ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }),
         }), null, 2));
       } catch (error) {
         console.error(`Error: ${error.code || 'RAIL_COMPLETION_FAILED'}: ${error.message}`);
@@ -276,8 +332,8 @@ async function main() {
 
     case 'rail-tracking-pending': {
       try {
-        const { listPendingClickUpProjections } = await import('../src/orchestrator/clickup-runtime.js');
-        console.log(JSON.stringify(listPendingClickUpProjections({ projectDir: targetDir }), null, 2));
+        const { preparePendingClickUpProjections } = await import('../src/orchestrator/clickup-runtime.js');
+        console.log(JSON.stringify(preparePendingClickUpProjections({ projectDir: targetDir }), null, 2));
       } catch (error) {
         console.error(`Error: ${error.code || 'RAIL_TRACKING_PENDING_FAILED'}: ${error.message}`);
         process.exitCode = 1;
@@ -285,43 +341,45 @@ async function main() {
       break;
     }
 
-    case 'rail-tracking-ack': {
+    case 'rail-tracking-lookup': {
       const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
-      if (!value('--handoff-id') || !value('--projection-id') || !value('--receipt')) {
-        console.error('Error: rail-tracking-ack requires --handoff-id <id>, --projection-id <id> and --receipt <receipt.json>');
+      if (!value('--handoff-id') || !value('--projection-id') || !value('--result')) {
+        console.error('Error: rail-tracking-lookup requires --handoff-id <id>, --projection-id <id> and --result <lookup.json>');
         process.exitCode = 1;
         break;
       }
       try {
-        const receipt = JSON.parse(readFileSync(resolve(value('--receipt')), 'utf8'));
-        const { acknowledgeClickUpProjection } = await import('../src/orchestrator/clickup-runtime.js');
-        console.log(JSON.stringify(acknowledgeClickUpProjection({
-          projectDir: targetDir,
-          handoff_id: value('--handoff-id'),
-          projection_id: value('--projection-id'),
-          receipt,
+        const result = JSON.parse(readFileSync(resolve(value('--result')), 'utf8'));
+        const { resolveClickUpProjectionLookup } = await import('../src/orchestrator/clickup-runtime.js');
+        console.log(JSON.stringify(resolveClickUpProjectionLookup({
+          projectDir: targetDir, handoff_id: value('--handoff-id'),
+          projection_id: value('--projection-id'), result,
         }), null, 2));
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_TRACKING_ACK_FAILED'}: ${error.message}`);
+        console.error(`Error: ${error.code || 'RAIL_TRACKING_LOOKUP_FAILED'}: ${error.message}`);
         process.exitCode = 1;
       }
       break;
     }
 
-    case 'rail-review': {
+    case 'rail-tracking-ack': {
       const value = (flag) => { const index = args.indexOf(flag); return index === -1 ? null : args[index + 1]; };
-      if (!value('--review') || !value('--invocation')) {
-        console.error('Error: rail-review requires --review <review.json> and --invocation <invocation.json>');
+      if (!value('--handoff-id') || !value('--projection-id') || !value('--receipt')) {
+        console.error('Error: rail-tracking-ack requires --handoff-id <id>, --projection-id <id> and --receipt <receipt.json>');
         process.exitCode = 1;
         break;
       }
       try {
-        const review = JSON.parse(readFileSync(resolve(value('--review')), 'utf8'));
-        const invocation = JSON.parse(readFileSync(resolve(value('--invocation')), 'utf8'));
-        const { recordRailReview } = await import('../src/orchestrator/review-runtime.js');
-        console.log(JSON.stringify(recordRailReview({ projectDir: targetDir, review, invocation }), null, 2));
+        const receipt = JSON.parse(readFileSync(resolve(value('--receipt')), 'utf8'));
+        const { acknowledgeClickUpProjection } = await import('../src/orchestrator/clickup-runtime.js');
+        console.log(JSON.stringify(acknowledgeClickUpProjection({
+          projectDir: targetDir,
+          handoff_id: value('--handoff-id'),
+          projection_id: value('--projection-id'),
+          receipt,
+        }), null, 2));
       } catch (error) {
-        console.error(`Error: ${error.code || 'RAIL_REVIEW_FAILED'}: ${error.message}`);
+        console.error(`Error: ${error.code || 'RAIL_TRACKING_ACK_FAILED'}: ${error.message}`);
         process.exitCode = 1;
       }
       break;
@@ -834,7 +892,7 @@ Telemetry:
       // (e.g., `chati orchestrate xyz` should not silently create cwd/xyz/ as targetDir)
       const VALID_ORCHESTRATE_SUBS = new Set([
         'next', 'advance', 'init', 'status', 'validate-handoff',
-        'deviation', 'exit', 'providers', 'detect-flow', 'backlog',
+        'deviation', 'exit', 'activate-harness', 'providers', 'detect-flow', 'backlog',
         'qa-plan-score', 'qa-impl-score', 'qa-visual-score', 'scan',
         'spawn-team', 'team-status', 'team-dissolve',
         'wait-for-capture', 'wave-status', 'assess-coverage',

package/framework/agents/build/dev.md

@@ -35,7 +35,7 @@ Implement each task from the approved task breakdown with high quality, followin
 ## On Activation
 
 1. Read handoff from QA-Planning
-2. Read `.chati/session.yaml` for execution_mode and project context
+2. Use the validated canonical session context supplied in the activation prompt for `execution_mode` and project context. Never read `.chati/session.yaml` directly.
 3. Read Tasks: `artifacts/6-Tasks/tasks.md`
 4. Read Architecture: `artifacts/3-Architecture/architecture.md`
 5. Read UX: `artifacts/4-UX/ux-specification.md` (Design System tokens)
@@ -574,7 +574,7 @@ User can intervene at any point.
 
 ### Autonomous Mode (Ralph Wiggum)
 ```
-Activated when session.yaml execution_mode = autonomous
+Activated when the router-validated prompt context has `execution_mode = autonomous`
 
 ANTI-LOOP GUARANTEE: Each step (5.5, 6.5) executes ONCE per attempt.
 No re-running tests after 6.5. No cycling back to 5.5.
@@ -987,13 +987,13 @@ This agent supports TASK-LEVEL parallelization (all modes):
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Execution mode (interactive/autonomous), pipeline state, agent statuses |
+| L0 | Router-validated prompt context | Execution mode (interactive/autonomous), pipeline state, agent statuses |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, blocker taxonomy, handoff rules |
 | L2 | `artifacts/6-Tasks/tasks.md` | Task definitions with acceptance criteria (Given-When-Then) |
 | L3 | `artifacts/3-Architecture/architecture.md` | Tech stack, patterns, conventions, file structure |
 | L4 | `artifacts/4-UX/ux-specification.md` | Design System tokens for token enforcement |
 
-**Workflow Awareness**: The Dev agent must check `session.yaml` for `execution_mode` to determine whether to operate in interactive (user acknowledgment per task) or autonomous (Ralph Wiggum) mode. It must also read intelligence files for known gotchas before each task.
+**Workflow Awareness**: The Dev agent uses `execution_mode` from its validated activation context to determine whether to operate in interactive (user acknowledgment per task) or autonomous (Ralph Wiggum) mode. If absent, return `needs_input`; never inspect canonical session storage directly. It must also read intelligence files for known gotchas before each task.
 
 ---
 
@@ -1097,7 +1097,7 @@ ANTI-CYCLE RULE: Levels are a one-way escalation path. NEVER go back to a previo
 
 ### 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.
+Team mode is active when your validated activation prompt says "Team mode active" or `CHATI_TEAM_ID` is set. Never inspect canonical session storage to infer membership.
 
 If team mode is active:
 1. Read your Shared Task List from the team's `task_list_path`.

package/framework/agents/deploy/devops.md

@@ -34,7 +34,7 @@ Ship the validated code to production: organize commits, create pull requests, d
 ## On Activation
 
 1. Read handoff from QA-Implementation
-2. Read `.chati/session.yaml` for project context
+2. Use the validated canonical session context supplied in the activation prompt for project context. Never read `.chati/session.yaml` directly.
 3. Read QA-Implementation report: `artifacts/9-QA-Implementation/qa-implementation-report.md`
 4. Verify QA-Implementation status is APPROVED
 5. Read QA-Visual report if it exists: `artifacts/9-QA-Implementation/qa-visual-report.md`. If found, verify QA-Visual score >= 90% before proceeding. If the report is missing, note it as "QA-Visual not run" and continue (it is not a hard blocker if the project has no UI).
@@ -142,9 +142,9 @@ Validation:
 ```
 1. Complete your handoff document (artifacts/handoffs/devops-handoff.md) with final state.
    Do NOT edit session.yaml directly — the mode-governance hook blocks this.
-   The CLI records completion and updates session.yaml when you run:
+   The CLI records completion in canonical state when you run:
      node chati.dev/orchestrator/chati-router.js advance --agent devops --score <N>
-   Reference state for handoff document (orchestrator will apply to session.yaml):
+   Reference state for the handoff document (the orchestrator will persist it canonically):
    - project.state: completed
    - devops status: completed
 2. Update `.chati/project-context.md` with final project state
@@ -167,7 +167,7 @@ Criteria (binary pass/fail):
 7. CHANGELOG.md generated/updated
 8. No hardcoded secrets in deployed code
 9. SSL is valid on deployed URL
-10. Session.yaml updated to completed state
+10. Canonical state recorded as completed
 
 Score = criteria met / total criteria
 Threshold: >= 90% (9/10 minimum)
@@ -340,7 +340,7 @@ Rules:
 | `git-ops` | Git Operations | Organize commits, ensure conventional format, create PR, push to remote | After verify-prereqs |
 | `deploy` | Deploy | Build project, deploy to target platform, verify deployment (URL, SSL, response) | After git-ops |
 | `docs-gen` | Generate Documentation | Generate/update README.md, CHANGELOG.md, API.md | After deploy |
-| `finalize` | Finalize | Generate final handoff (CLI advances session.yaml to completed), update `.chati/project-context.md`, generate final summary | After docs-gen |
+| `finalize` | Finalize | Generate final handoff (CLI records canonical completion), update `.chati/project-context.md`, generate final summary | After docs-gen |
 
 ---
 
@@ -348,7 +348,7 @@ Rules:
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Project state, pipeline position, agent statuses, deployment configuration |
+| L0 | Router-validated prompt context | Project state, pipeline position, agent statuses, deployment configuration |
 | L1 | `chati.dev/constitution.md` | Protocols, handoff rules, session finalization requirements |
 | L2 | `artifacts/9-QA-Implementation/qa-implementation-report.md` | Approval status, test results, security scan, code review findings |
 | L3 | `artifacts/3-Architecture/architecture.md` | Deployment strategy, platform target, infrastructure configuration |
@@ -414,7 +414,7 @@ signals to the signed router. This agent cannot change its provider or model.
 4. **Documentation is not optional**: README.md and CHANGELOG.md are part of the deployment - code without documentation is an incomplete delivery
 5. **Only DevOps pushes**: No other agent is authorized to push to remote or create PRs - this boundary is absolute
 6. **Conventional commits enforced**: All commits must follow the conventional format (feat:, fix:, docs:, chore:) - free-form commit messages are rejected
-7. **Session finalization is the last action**: Updating session.yaml to `state: completed` and `.chati/project-context.md` with the final project state is the definitive last step
+7. **Session finalization is the last action**: Return `state: completed` and the final project-context changes in the handoff so the router and canonical session manager persist them as the definitive last step
 
 ---
 

package/framework/agents/discover/brief.md

@@ -32,7 +32,7 @@ Extract, analyze, and document the core problems, desired outcomes, target users
 ## On Activation
 
 1. Read handoff from previous agent (greenfield-wu or brownfield-wu)
-2. Read `.chati/session.yaml` for language and project context
+2. Use the validated canonical session context supplied in the activation prompt for language and project context. Never read `.chati/session.yaml` directly.
 3. Process Layer 1 (Summary), then Layer 2 if present
 4. Acknowledge inherited context before starting work
 
@@ -91,7 +91,7 @@ Adapt method depth to user level:
 Purpose: Get everything out of the user's head without filtering
 
 IMPORTANT - Check for initial_context FIRST:
-  IF session.yaml contains initial_context (from /chati <prompt> inline input):
+  IF the validated activation context contains `initial_context` (from /chati <prompt> inline input):
     1. Treat initial_context as the PRIMARY brain dump input
     2. Parse it for: vision, problems, users, constraints, references
     3. Acknowledge what was captured: "From your initial description, I captured: {summary}"
@@ -573,7 +573,7 @@ domains:
 Pre-conditions:
   - WU agent completed with score >= 85%
   - WU handoff file exists at artifacts/handoffs/
-  - session.yaml updated with WU completion data
+  - Canonical state contains WU completion data
 Input data:
   Layer 1 (Summary):
     - Project type (greenfield/brownfield)
@@ -603,7 +603,7 @@ Contents:
   - User-approved brief status
 Post-conditions:
   - Brief report at artifacts/1-Brief/brief-report.md
-  - session.yaml updated with Brief completion data
+  - Canonical state contains Brief completion data
   - User has explicitly approved the brief
 ```
 

package/framework/agents/discover/brownfield-wu.md

@@ -32,7 +32,7 @@ Produce a comprehensive understanding of the existing project: its tech stack, a
 ## On Activation
 
 1. Read handoff from orchestrator (if any)
-2. Read `.chati/session.yaml` for project context and language
+2. Use the validated canonical session context supplied in the activation prompt for project context and language. Never read `.chati/session.yaml` directly.
 3. Acknowledge inherited context
 4. Begin discovery in user's interaction language
 
@@ -389,7 +389,7 @@ domains:
 ```
 Pre-conditions:
   - Project identified as brownfield
-  - session.yaml initialized with project.type = brownfield
+- Canonical session state initialized by the session manager with `project.type = brownfield`
   - Existing codebase accessible at project root
 Input data:
   - User's project description and goals
@@ -417,7 +417,7 @@ Contents:
     - Integration map with external service details
 Post-conditions:
   - Full WU report at artifacts/0-WU/wu-full-report.md
-  - session.yaml updated with WU completion data
+  - Canonical state contains WU completion data
 ```
 
 ---

package/framework/agents/discover/greenfield-wu.md

@@ -32,7 +32,7 @@ Capture the user's current operational context - their workflow, tools, friction
 ## On Activation
 
 1. Read handoff from orchestrator (if any)
-2. Read `.chati/session.yaml` for project context and language
+2. Use the validated canonical session context supplied in the activation prompt for project context and language. Never read `.chati/session.yaml` directly.
 3. Acknowledge inherited context
 4. Begin operational discovery in user's interaction language
 
@@ -389,7 +389,7 @@ word per line. If nothing qualifies, omit the section entirely (empty list).
 ```
 Pre-conditions:
   - Project identified as greenfield
-  - session.yaml initialized with project.type = greenfield
+- Canonical session state initialized by the session manager with `project.type = greenfield`
 Input data:
   - User's initial project description
   - Detected language
@@ -408,7 +408,7 @@ Contents:
   - User level assessment update
 Post-conditions:
   - WU report at artifacts/0-WU/wu-operational-report.md
-  - session.yaml updated by CLI via `node chati.dev/orchestrator/chati-router.js advance --agent greenfield-wu --score <N>` (do NOT edit session.yaml directly)
+  - Canonical state updated by CLI via `node chati.dev/orchestrator/chati-router.js advance --agent greenfield-wu --score <N>`
 ```
 
 ---

package/framework/agents/plan/architect.md

@@ -41,7 +41,7 @@ Coordinate the technical design by activating 2 specialist sub-agents in sequenc
 ## On Activation
 
 1. Read handoff from Detail (greenfield) or Brief (brownfield)
-2. Read `.chati/session.yaml` for project context
+2. Use the validated canonical session context supplied in the activation prompt for project context. Never read `.chati/session.yaml` directly.
 3. Read PRD: `artifacts/2-PRD/prd.md`
 4. Read Brief: `artifacts/1-Brief/brief-report.md` (includes visual reference captures with animation libraries detected — GSAP, Lenis, ScrollTrigger counts — use to inform frontend stack decisions)
 5. If brownfield: Read WU report for existing stack/schema assessment
@@ -222,7 +222,7 @@ Score = criteria met / 10. Threshold: >= 90% (9/10 minimum).
 
 ### 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.
+Team mode is active when your validated activation prompt says "Team mode active" or `CHATI_TEAM_ID` is set. Never inspect canonical session storage to infer membership.
 
 If team mode is active:
 1. Read your Shared Task List from the team's `task_list_path`.

package/framework/agents/plan/detail.md

@@ -33,7 +33,7 @@ Create a comprehensive, unambiguous Product Requirements Document that translate
 ## On Activation
 
 1. Read handoff from previous agent (Brief or Architect in brownfield)
-2. Read `.chati/session.yaml` for project context
+2. Use the validated canonical session context supplied in the activation prompt for project context. Never read `.chati/session.yaml` directly.
 3. Read Brief artifact: `artifacts/1-Brief/brief-report.md`
 4. If brownfield: also read Architecture artifact for existing constraints
 5. Acknowledge inherited context
@@ -323,13 +323,13 @@ Rules:
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
+| L0 | Router-validated prompt context | Project type, current pipeline position, mode, agent statuses |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
 | L1.5 | `chati.dev/rules/human-writing-style.md` | Anti-AI prose rules for human-facing PRD sections |
 | L2 | `artifacts/1-Brief/brief-report.md` | Problems, desired outcomes, constraints, target users |
 | L3 | `artifacts/handoffs/brief-handoff.md` | Brief agent handoff with decisions and open questions |
 
-**Workflow Awareness**: The Detail agent must check `session.yaml` to understand its pipeline position and whether it is operating in a greenfield or brownfield flow, as this changes which upstream artifacts are available.
+**Workflow Awareness**: Use the validated session context in the activation prompt to understand pipeline position and whether the flow is greenfield or brownfield. If that context is missing, return `needs_input`; never inspect the session file directly.
 
 ---
 
@@ -414,7 +414,7 @@ or substitute that binding.
 
 ### 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.
+Team mode is active when your validated activation prompt says "Team mode active" or `CHATI_TEAM_ID` is set. Never inspect canonical session storage to infer membership.
 
 If team mode is active:
 1. Read your Shared Task List from the team's `task_list_path`.

package/framework/agents/plan/phases.md

@@ -33,7 +33,7 @@ Break the PRD requirements into ordered development phases where Phase 1 is alwa
 ## On Activation
 
 1. Read handoff from UX agent
-2. Read `.chati/session.yaml` for project context
+2. Use the validated canonical session context supplied in the activation prompt for project context. Never read `.chati/session.yaml` directly.
 3. Read PRD: `artifacts/2-PRD/prd.md`
 4. Read Architecture: `artifacts/3-Architecture/architecture.md`
 5. Acknowledge inherited context
@@ -294,7 +294,7 @@ Rules:
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
+| L0 | Router-validated prompt context | Project type, current pipeline position, mode, agent statuses |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
 | L2 | `artifacts/2-PRD/prd.md` | Full requirements list with IDs, priorities, and acceptance criteria |
 | L3 | `artifacts/3-Architecture/architecture.md` | Tech constraints, infrastructure dependencies, deployment strategy |

package/framework/agents/plan/tasks.md

@@ -33,7 +33,7 @@ Create atomic, testable, estimable tasks for each phase. Every task has a clear
 ## On Activation
 
 1. Read handoff from Phases agent
-2. Read `.chati/session.yaml` for project context
+2. Use the validated canonical session context supplied in the activation prompt for project context. Never read `.chati/session.yaml` directly.
 3. Read Phases: `artifacts/5-Phases/phases.md`
 4. Read PRD: `artifacts/2-PRD/prd.md`
 5. Read Architecture: `artifacts/3-Architecture/architecture.md`
@@ -476,7 +476,7 @@ Rules:
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
+| L0 | Router-validated prompt context | Project type, current pipeline position, mode, agent statuses |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
 | L2 | `artifacts/5-Phases/phases.md` | Phase breakdown, wave structure, requirement assignments |
 | L3 | `artifacts/2-PRD/prd.md` | Full requirements list with acceptance criteria for traceability |