chati-dev 4.5.16 → 4.5.28

package/framework/orchestrator/chati.md

@@ -43,11 +43,11 @@ When the user invokes the provider-native Chati entry point, execute this sequen
 ### Step 1: Load Context
 
 ```
-1. Read .chati/session.yaml (session state)
+1. Use the validated `session` object returned by the deterministic router
 2. Read .chati/project-context.md (provider-neutral project context)
 3. Read chati.dev/constitution.md (if first run or FRESH bracket - governance rules)
 4. Read chati.dev/config.yaml (version info, provider overrides)
-5. Detect language from session.yaml → respond in that language
+5. Use `session.language` from the router → respond in that language
 ```
 
 ### Step 2: Check Subcommands
@@ -98,21 +98,42 @@ node .chati.dev/orchestrator/chati-router.js next
 
 Parse the JSON output. The `action` field tells you what to do:
 
+<!-- ROUTER_ACTION_CATALOG:START -->
 | action | Go to |
 |--------|-------|
 | `setup` | Action: Setup |
 | `activate_interactive` | Action: Interactive Agent |
 | `spawn_routed_interactive` | Action: Routed Interactive Agent |
 | `resume_pending_interaction` | Action: Resume Pending Interaction |
+| `pending_interaction_in_flight` | Action: Pending Interaction In Flight |
+| `agent_execution_in_flight` | Action: Agent Execution In Flight |
+| `awaiting_agent_advance` | Action: Awaiting Agent Advance |
+| `pending_interaction_escalation_required` | Action: Pending Interaction Escalation |
 | `spawn_autonomous` | Action: Autonomous Agent |
 | `spawn_parallel` | Action: Parallel Spawn |
 | `spawn_team` | Action: Spawn Team (Article XXI) |
 | `rail_execute` | Action: RAIL Execution |
-| `resume` | Action: Resume |
+| `rail_task_executed` | Action: RAIL Execution |
+| `rail_task_execution_failed` | Action: RAIL Execution |
+| `rail_review_recorded` | Action: RAIL Execution |
+| `rail_rework_executed` | Action: RAIL Execution |
+| `rail_rework_failed` | Action: RAIL Execution |
+| `rail_adjudication_recorded` | Action: RAIL Execution |
 | `user_preview` | Action: User Preview |
+| `scaffold_decision` | Action: Scaffold Decision (legacy runtime only) |
+| `scaffold_decision_pending` | Action: Scaffold Decision Pending (legacy runtime only) |
+| `correction_loop` | Action: Correction Loop (legacy runtime only) |
+| `escalate` | Action: Correction Escalation (legacy runtime only) |
 | `complete` | Action: Complete |
 | `error` | Display error, suggest `/chati status` |
-| `version_mismatch` (in any response) | "Your CLI bundle is out of date. Run `npx chati-dev upgrade` to fix." Display once per session, then continue. |
+| `proceed` | Continue after the requested operational check |
+| `license_resolution_required` | Present the returned license recovery action |
+| `remediation_required` | Present the returned doctor remediation action |
+<!-- ROUTER_ACTION_CATALOG:END -->
+
+If `version_mismatch` appears in any response, say: "Your CLI bundle is out of
+date. Run `npx chati-dev upgrade` to fix." Display it once per session, then
+continue.
 
 **Internal: track context bracket from JSON `context_bracket` but DO NOT display it to the user.** The bracket is internal telemetry - users should never see "Context: FRESH (90%)" or framework jargon like "Initiating handoff protocol". Speak in natural language about what you are doing, not the internal state.
 
@@ -162,7 +183,9 @@ Run via Bash:
 node .chati.dev/orchestrator/chati-router.js init --type {detected_type} --language {detected_lang} --name "{detected_name}" --workflow {detected_workflow}
 ```
 
-Parse JSON → read `first_agent_file` → activate that agent immediately (go to **Action: Interactive Agent**).
+Parse the JSON, then run the deterministic router again with `next`. Follow the
+returned action. V2 must dispatch conversational work through **Action: Routed
+Interactive Agent** and must never execute an agent inside the opened harness.
 
 The user should experience a smooth start: they describe their project, the orchestrator confirms what it detected, and the first agent begins immediately.
 
@@ -170,12 +193,13 @@ The user should experience a smooth start: they describe their project, the orch
 
 ## Action: Interactive Agent
 
-These agents (greenfield-wu, brownfield-wu, brief) run in the same conversation.
+This action is retained only for legacy v1 installations. A v2 installation
+must reject it and run the deterministic router again to obtain a routed action.
 
 1. Treat `model_info` as internal routing evidence. Do not display it or ask the user to switch models. V2 conversational work uses Routed Interactive Agent instead.
-2. Read the **FULL** agent file from `agent_file` in the JSON response (do NOT use limit/offset - read the entire file)
-3. Load its full content and **become** that agent
-4. Follow the agent's instructions - the user interacts with you directly
+2. Read the **FULL** agent file from `agent_file` in the JSON response (do NOT use limit/offset, read the entire file)
+3. Follow the legacy agent instructions in the current conversation.
+4. Keep this path isolated from v2 installations.
 5. When the agent completes its work and self-validates, extract the score
 6. Present **Completion Options** (see below) - wait for user choice before advancing
 7. **MANDATORY - On user approval, run via Bash:**
@@ -197,9 +221,11 @@ internal router.
 2. Execute the exact `spawn_command` returned by the router.
 3. Parse the JSON result:
    - `complete`: present Completion Options. On approval, advance the agent.
-   - `needs_input`: ask only `needs_input_question` in the user's language,
-     relay the response through `--additional-context`, then rerun the same
-     exact provider and model binding. Limit this relay to three cycles.
+   - `needs_input`: do not construct or modify a runner command. Run the
+     deterministic router again, which returns `resume_pending_interaction`,
+     then follow Action: Resume Pending Interaction. This keeps the exact
+     question, response transport and provider binding under the canonical
+     relay contract.
    - `error`: use the Recovery Protocol. Never silently change provider or
      model in a v2 installation.
 4. The opened CLI remains the conversation orchestrator. The routed process
@@ -208,16 +234,76 @@ internal router.
 ## Action: Resume Pending Interaction
 
 The routed process already asked a question and the canonical session stored
-it. Do not execute `spawn_command` yet and do not dispatch the agent again.
+it. `spawn_command` is intentionally null. Do not dispatch the agent again.
 
 1. Present only the exact `question` returned by the router, using
    `session.language`.
-2. When the user answers, execute the returned `spawn_command` once with
-   `--additional-context "{user_response}"` appended.
+2. When the user answers, write `{ "response": "<exact user response>" }` to
+   `response_file` using the harness's native file-write tool, never a shell
+   command. Then execute `deferred_spawn_command` exactly once and unchanged.
 3. Parse the new result using Action: Routed Interactive Agent.
 4. Read `relay_cycles` from the router response. After three unresolved relay cycles, use the configured reasoning
    escalation. Do not invent an answer or silently switch providers.
 
+## Action: Agent Execution In Flight
+
+Another opened CLI already owns the exact execution claim for this step. Do
+not build, copy, or re-run a spawn command. Tell the user that the current step
+is already running in another CLI and keep the canonical session unchanged.
+
+## Action: Awaiting Agent Advance
+
+The routed process finished successfully, but its exact result has not yet
+been committed through canonical `advance`.
+
+1. Do not dispatch the agent again and do not synthesize a replacement result.
+2. If this CLI owns the completed process result, immediately submit that exact
+   handoff and score through `orchestrate advance`.
+3. If another CLI owns the result, present `status_summary` and wait for that
+   CLI to finish canonical advance. A different CLI may resume only through an
+   explicit recovery path that preserves the original execution evidence.
+4. Run `next` again only after canonical advance succeeds.
+
+## Action: Pending Interaction In Flight
+
+Another process already owns this exact relay. Do not execute any command and
+do not ask the question again. Tell the user briefly that the response is still
+being processed. The router automatically recovers an abandoned claim after
+the runner timeout plus its safety margin.
+
+## Action: Pending Interaction Escalation
+
+The same interaction remained unresolved after three complete relays. Do not
+run a fourth deferred command and do not escalate a technical judgment directly
+to the user. The router has already selected the installation-eligible top-tier
+adjudication route in `model_info`. Execute `spawn_command` exactly once and
+parse its result using Action: Routed Interactive Agent. Ask the user only when
+the adjudicator returns `needs_input` because the remaining issue requires
+authority, product intent or information no configured model can infer safely.
+
+## Action: Scaffold Decision (legacy runtime only)
+
+Present the three exact options returned by the router in the session language.
+Do not apply files before the user selects `apply`. Route `dryrun`, `apply`, or
+`skip` back through `advance --decision` with the unchanged agent and score.
+
+## Action: Scaffold Decision Pending (legacy runtime only)
+
+Present the dry-run result in the session language. The next executable choice
+must be either `apply` or `skip`, sent through `advance --decision` with the
+unchanged agent and score.
+
+## Action: Correction Loop (legacy runtime only)
+
+Invoke only the returned correction target, with the returned findings and
+fault origin. Do not advance another agent until that correction completes and
+passes its normal gate.
+
+## Action: Correction Escalation (legacy runtime only)
+
+The bounded correction limit was reached. Present the returned evidence and
+options in the session language, then wait for the explicit human decision.
+
 ---
 
 ## Completion Options (Protocol 3 - Guided Options)
@@ -277,11 +363,15 @@ or the kind is `agent`, skip this entirely and use the normal agent path. This
 is purely a dispatch optimization: it never changes WHAT a task must achieve,
 only what executes it, and it is invisible when the feature is off.
 
-- **script**: run it deterministically with no LLM. Via Bash:
-  `node .chati.dev/orchestrator/chati-router.js run-script-task --ref "{execution_ref}" --id "{task_id}" --title "{task_title}"`
+- **script**: run it deterministically with no LLM. Write the task fields as
+  JSON (`kind`, `ref`, `id`, `title`) to
+  `.chati/runtime/script-task-request.json` using the harness's native file
+  tool. Then execute the fixed command below. Never interpolate task fields
+  into a shell command:
+  `node .chati.dev/orchestrator/chati-router.js run-script-task --request-file .chati/runtime/script-task-request.json`
   Handle the JSON `status`:
   - `passed` → the task is done. Advance: `node .chati.dev/orchestrator/chati-router.js advance --agent {current_agent} --score 100`
-  - `failed` → the deterministic check is negative. Route to dev (Fault Vector Protocol: CODE) to fix, then re-run the script task.
+  - `failed` → the deterministic check is negative. In v2, return the sealed task to the RAIL implementation or rework lane, then re-run the script task. Legacy v1 may use its existing implementation agent.
   - `error` → the executor could not run. Surface the summary to the user and check the execution_ref against the executor registry.
   - `ran: false` → the feature is off or the kind is not script; fall back to the agent path silently.
 - **human**: present the decision in the user's language as a Guided Option and wait for their choice. Record it, then advance. Never decide for them.
@@ -305,23 +395,15 @@ These agents run in separate processes using the exact provider and model bindin
 3. Execute `spawn_command` via Bash tool (the full command is in the JSON)
 4. Wait for JSON output from the spawned process. Handle `status`:
    - `"complete"` → Present **Completion Options** (see above) → on approval, run `node chati.dev/orchestrator/chati-router.js advance --agent {name} --score {score}`
-   - `"needs_input"` → Read `needs_input_question`, present to user in their language, then re-run spawn with `--additional-context "{user_response}"` (max 3 relay cycles)
+   - `"needs_input"` → Run the deterministic router again and follow **Action: Resume Pending Interaction**. Never interpolate the response into a command.
    - `"error"` → Apply Recovery Protocol (see below)
 
-### Sequential Fallback
+### Provider Failure
 
-If terminal spawning fails (CLI not found, system error), fall back **silently**:
-```
-1. Do NOT display any error or fallback message to the user
-2. Read the agent .md file directly and become that agent in-conversation
-3. Execute the agent's mission and write all deliverables (artifact + handoff)
-4. MANDATORY on completion — before presenting any summary:
-   - Run via Bash: `node .chati.dev/orchestrator/chati-router.js advance --agent {name} --score {score}`
-   - This persists the completion to session.yaml, updates Magic Docs, and
-     activates the next agent. Skipping it leaves the pipeline frozen.
-5. Present Completion Options exactly as the normal spawn path does
-6. Continue pipeline normally — the user should not notice any difference
-```
+If terminal spawning fails (CLI not found, authentication or system error), do
+not execute the task inside the opened conversation CLI and do not substitute a
+provider or model. Preserve the signed route and pending response, then apply
+the Recovery Protocol. The conversation CLI remains the orchestrator only.
 
 **NOTE:** A provider-native post-tool hook may also fire on handoff write when
 supported. In interactive mode, the explicit router advance call remains the
@@ -347,12 +429,9 @@ Planning phase agents (detail, architect, ux) run simultaneously.
 3. Consolidate and parse the member outputs without replacing their bindings
 4. Present **Completion Options** (Parallel Group variant) - wait for user choice
 5. On approval, for each completed agent, run `node chati.dev/orchestrator/chati-router.js advance --agent {name} --score {score}`
-6. If partial or total failure (spawning unavailable):
-   ```
-   Fall back silently to sequential in-conversation execution.
-   Do NOT display error messages about spawning or CLI availability.
-   Read each agent .md file and execute sequentially within the conversation.
-   ```
+6. If partial or total failure (spawning unavailable), preserve each signed
+   member binding and apply the Recovery Protocol. Never execute a task agent
+   inside the opened conversation CLI.
 
 ### Parallelization Rules
 - GROUP 1 (Planning Team): detail, architect, ux, qa-planning - run as team (QA-Planning activates after trio completes)
@@ -672,10 +751,10 @@ If the Agent tool is unavailable or any sub-agent spawn fails:
    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 .chati.dev/orchestrator/chati-router.js team-dissolve --team-id {team_id}
-   to mark the team as degraded in session.yaml
+   to mark the team as degraded through the canonical session manager
 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
+5. If `spawn_parallel` also fails, preserve the signed member bindings and
+   apply the Recovery Protocol. Do not execute the agents in-conversation.
 ```
 
 ---
@@ -690,36 +769,123 @@ review, bounded rework, ClickUp projection and the Release Lane.
    ```
    node .chati.dev/orchestrator/chati-router.js rail-next --handoff-id {handoff_id}
    ```
-3. Execute only a dependency-ready task. Use its selected provider and model
-   binding from `.chati/v2/installation.json`. Never substitute an unselected
-   vendor or model.
-4. Record every claim, review, completion, rework count and ClickUp projection
+3. Dispatch one returned task only through the production RAIL boundary:
+   ```
+   node .chati.dev/orchestrator/chati-router.js rail-dispatch --handoff-id {handoff_id} --task-id {task_id} --harness {current_harness}
+   ```
+   This command reads the task binding from the sealed handoff, verifies it
+   against the signed installation, claims the attempt, checks provider
+   readiness, and invokes the exact provider, model and reasoning setting.
+   Before creating the provider process, RAIL persists a claim-bound initial
+   launch reservation. Authority-bearing providers run inside a Linux
+   Bubblewrap PID namespace bound to the authenticated local PID, host and
+   process group. Missing or untrusted containment fails closed before process
+   creation. If the supervisor stops after the initial dispatch and before
+   canonical execution evidence, that attempt can never auto-recover or launch
+   a second mutating provider; it requires explicit operator remediation.
+   Never invoke the task CLI directly or substitute another binding.
+   If execution returns `rail_task_execution_failed`, keep the returned
+   `attempt_id`. Transient retries run inside that same command while its
+   supervisor and lease remain live. After the command exits, another process
+   cannot reuse the claim. Wait for lease expiry, then run `rail-recover` for
+   that same attempt instead of `rail-dispatch`; recovery and provider launch
+   occur atomically in the new supervisor process. A failed execution is canonical
+   audit evidence but does not consume the attempt's successful result slot.
+   Any post-claim error also returns the canonical `attempt_id` with
+   `rail_recover_same_attempt_after_lease_expiry`. On an orderly failure, the
+   owning supervisor expires its own lease before exiting; an abrupt stop uses
+   the original lease deadline. Never mint a replacement attempt for
+   that task: let the current supervisor retry internally, or recover that
+   exact attempt after the lease has expired only when the prior failure
+   already has canonical execution evidence.
+4. After a successful dispatch, run the independent selected reviewer:
+   ```
+   The executor must have committed a clean result that descends from the
+   sealed base. The reviewer binds its evidence to that exact result commit.
+   node .chati.dev/orchestrator/chati-router.js rail-review-run --handoff-id {handoff_id} --attempt-id {attempt_id} --harness {current_harness}
+   ```
+   `rail-review-run` is the only accepted review entry point. Never construct
+   or submit a review decision directly: RAIL accepts only the decision parsed
+   from output bound to the authorized terminal completion receipt.
+   Review and adjudication run through the selected provider's native read-only
+   mode. RAIL also snapshots the complete project filesystem recursively,
+   including ignored files, nested repositories, Git internals and non-journal
+   `.chati` state, then rejects any mutation before accepting evidence. External
+   symlinks and special files fail closed. Only exact canonical RAIL journal
+   paths remain outside the postcondition.
+   Follow only `next_required_action`. For `rail_rework_required`, run:
+   ```
+   node .chati.dev/orchestrator/chati-router.js rail-rework --handoff-id {handoff_id} --attempt-id {attempt_id} --harness {current_harness}
+   ```
+   If this returns `rail_rework_failed`, reconcile or recover the lease when
+   required and rerun `rail-rework` with that same attempt id. A failed rework
+   does not consume its authorizing decision. Do not start another review until
+   a successful rework result is journaled. Before a mutating rework provider
+   starts, RAIL reserves the exact source decision under the current claim
+   generation. A concurrent rework is rejected before launch; an unreceipted
+   prior launch requires reconciliation rather than a second provider.
+   Then run a fresh `rail-review-run`. Never reuse a prior acceptance.
+5. If review returns `rail_adjudication_required`, run the selected top-tier
+   council. It may use only providers enabled by the signed installation:
+   ```
+   node .chati.dev/orchestrator/chati-router.js rail-adjudicate --handoff-id {handoff_id} --attempt-id {attempt_id} --harness {current_harness}
+   ```
+   A bounded correction returns to `rail-rework`. A handoff revision returns to
+   Planning. Human authority is valid only for scope, security, privacy, cost
+   or an external action.
+6. Record every claim, review, completion, rework count and ClickUp projection
    through RAIL. ClickUp is a projection, while the local journal remains
    canonical during an outage. For the internal profile, a merged completion
    MUST include `actual_human_effort`, `actual_ai_processing`, `rework_cycles`
    and one verified review reference per rework cycle. RAIL writes the
    in-progress, ready-to-merge and closed projections automatically; do not
    create a parallel manual tracking path.
-5. After two normal rework cycles, use the configured top-tier adjudication
-   route. Escalate to a human only for an authority decision, not an ordinary
-   technical correction.
-6. When `rail-next` has no ready work, check the Release Lane. It may prepare
-   evidence, but cannot deploy or publish without explicit authorization.
-
-## Action: Resume
-
-The user is returning to an active session.
-
-1. Present a natural-language summary of where we are in the user's language. Translate the internal `status_summary` into user-friendly terms - never say "qa-planning completed" or expose internal agent names.
-2. Track context bracket internally - do NOT display.
-3. Offer options in plain language (translate internal agent names to user-facing phase descriptions):
+   Reconcile canonical state with `rail-tracking-reconcile`; never invent a
+   ClickUp receipt. For external delivery, run `rail-tracking-pending` before
+   any remote call. A new item is durably marked `sent_unconfirmed` before its
+   operation and payload are returned. Send that payload at most once, then
+   record a successful response with `rail-tracking-ack`. If the response is
+   absent or uncertain, rerunning `rail-tracking-pending` returns only
+   `lookup_before_resend`, without an operation or payload. Perform an
+   idempotency-key lookup and record its JSON result through
+   `rail-tracking-lookup`. Resend only after that lookup proves `not_found` and
+   a subsequent `rail-tracking-pending` returns a fresh send instruction.
+   Every signed acknowledgement or lookup must echo the returned
+   `delivery_attempt` and `delivery_attempted_at`; receipts from an earlier
+   generation fail closed.
+   The runtime maintains live leases automatically. There are no standalone
+   public claim or heartbeat commands. Each task, review, rework, adjudication
+   and completion action owns the claim from one long-lived supervisor, then
+   explicitly relinquishes it after persisting its canonical result. The next
+   action atomically recovers that released claim before any provider launch.
+   If an interrupted build process requires explicit recovery, use only the
+   installed router:
    ```
-   1. Continue (Recommended)
-   2. Review what we just produced
-   3. Show me the full project status
+   node .chati.dev/orchestrator/chati-router.js rail-recover --handoff-id {handoff_id} --attempt-id {attempt_id} --operator-id {operator_id}
    ```
-
----
+   Recovery accepts no caller-supplied process identity, lease duration or
+   reconciliation. It requires an expired lease and canonical evidence for the
+   prior failed execution, then records recovery and launches the selected
+   provider in that same live process, which remains the lease supervisor until
+   execution ends. An interrupted initial dispatch without canonical execution
+   evidence is permanently ineligible for automatic recovery, even if its
+   original processes appear stopped. An unresolved launch reservation or
+   unreceipted prepared effect likewise fails closed for explicit operator
+   handling.
+7. Completion requires real Git, passed CI, accepted review and acceptance
+   evidence in `--completion-json`. CI and acceptance evidence each require an
+   exact signed receipt from the project-bound authority certified by CHATI at
+   `.chati/v2/rail/evidence-authority.json`; a missing, expired or mismatched
+   authority fails closed. `git.base_ref` must equal the sealed base,
+   `git.result_ref` must be its non-base descendant, `git.commit_refs` must
+   include both, and `ci.commit_ref` plus the latest accepted review must equal
+   that result commit. Call `rail-complete` first for
+   `ready_to_merge`, then again for `merged`. Never synthesize CI or effort
+   evidence. A dependency unlocks only after the merged journal record.
+8. When `rail-next` has no ready work, run `rail-release-ready`. The Release
+   Lane may prepare evidence, but its production transport cannot deploy,
+   publish or roll back without explicit human authorization scoped to the
+   immutable release attempt and passed smoke evidence.
 
 ## Action: User Preview (legacy runtime only)
 
@@ -826,7 +992,7 @@ Before routing to the current agent, check for inline queries. Handle them WITHO
 | Signal | Action |
 |--------|--------|
 | "what did we learn", "show memories", "past decisions" | Load `.chati/memories/`, present summary grouped by type |
-| "what happened today", "show progress", "session summary" | Read session.yaml, present timeline with scores |
+| "what happened today", "show progress", "session summary" | Run `node .chati.dev/orchestrator/chati-router.js status`, validate its JSON, and present the returned timeline and scores |
 | "how does this work", "what agents exist", "what phase" | Explain pipeline position, list agents, show next steps |
 
 Multi-language signals also apply (e.g., "o que aprendemos", "mostra o progresso", "como funciona").
@@ -971,7 +1137,7 @@ When the independent RAIL reviewer classifies a fault:
 
 ### ALLOWED
 - Read any file in the project (for state detection)
-- Write to .chati/session.yaml (session state)
+- Request session transitions through the CLI session manager or deterministic router
 - Reconcile every enabled harness's native session-lock file
 - Present status dashboards
 - Generate session digests
@@ -1005,12 +1171,14 @@ Level 1 - Retry:
 Level 2 - Escalate:
   Agent fails 3 consecutive times → present options:
   1. Retry with different approach
-  2. Skip agent (document risk in session.yaml)
+  2. Skip agent through `deviation --type skip --target {agent}`. Show its impact first and rerun with `--confirm true` only after explicit user confirmation; the returned deviation record is the risk evidence.
   3. Return to previous agent
 
 Level 3 - Session Recovery:
-  session.yaml corrupted → attempt reconstruction from .chati/project-context.md + artifacts
-  If reconstruction fails → suggest re-init preserving artifacts
+  Router reports unsafe session state → run `node .chati.dev/orchestrator/chati-router.js doctor`
+  Report the validated diagnostics and stop. A model or harness MUST NOT read,
+  reconstruct, or edit canonical session state. Recovery requires an explicit
+  user-owned backup restore or re-init outside the active session.
 
 Level 4 - Graceful Degradation:
   Critical error → save state, notify user with recovery instructions
@@ -1023,7 +1191,7 @@ Level 4 - Graceful Degradation:
 
 1. **Single Entry Point**: The orchestrator is the ONLY way users interact with Chati.dev
 2. **Transparent Routing**: Users should understand which agent is active and why
-3. **State Preservation**: Every state change is logged in session.yaml. No action is lossy
+3. **State Preservation**: Every state change is logged through the canonical session manager. No action is lossy
 4. **Fail-Safe Defaults**: When uncertain, default to planning mode and the safest agent
 5. **Progressive Disclosure**: Start simple, reveal depth on demand
 6. **Pipeline Respect**: Never skip pipeline steps without explicit user consent
@@ -1040,7 +1208,7 @@ Self-validation checklist for orchestrator decisions:
 2. **Mode compliance**: Operation respects current mode restrictions?
 3. **Pipeline integrity**: Routing follows defined pipeline order?
 4. **Deviation handling**: Deviation properly logged and context preserved?
-5. **Session consistency**: session.yaml in sync with actual state?
+5. **Session consistency**: validated router state in sync with actual state?
 6. **Language consistency**: All interactions in user's chosen language?
 7. **Constitution compliance**: No constitutional article violated?
 8. **Handoff completeness**: Handoff contains all required data?

package/framework/schemas/session.schema.json

@@ -142,7 +142,7 @@
           "type": "object",
           "required": ["status", "score", "criteria_count"],
           "properties": {
-            "status": { "enum": ["pending", "in_progress", "waiting_for_user", "completed", "skipped", "needs_revalidation"] },
+            "status": { "enum": ["pending", "in_progress", "waiting_for_user", "awaiting_advance", "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" }

package/framework/tasks/orchestrator-deviation.md

@@ -21,7 +21,7 @@ criteria:
 Handle changes to project scope, priorities, or approach that deviate from the current plan. Evaluate impact, propose alternatives, and re-route the pipeline.
 
 ## Prerequisites
-- Session state at `.chati/session.yaml`
+- Router-validated canonical session context
 - Current plan in artifacts (brief, requirements, phases, etc.)
 - Constitution at `chati.dev/constitution.md`
 - User input describing the change

package/framework/tasks/orchestrator-escalate.md

@@ -22,7 +22,7 @@ Handle agent failures, blockers, and critical issues by collecting context, clas
 
 ## Prerequisites
 - Failure signal from agent
-- Session state at `.chati/session.yaml`
+- Router-validated canonical session context
 - Agent definition with failure handling rules
 - Error logs or stack traces (if available)
 

package/framework/tasks/orchestrator-handoff.md

@@ -23,7 +23,7 @@ Receive output from a completed agent, validate it, create a handoff document, u
 ## Prerequisites
 - Agent has signaled completion
 - Agent output available
-- Session file at `.chati/session.yaml`
+- Deterministic router and canonical session manager available
 - Handoff directory at `.chati/artifacts/handoffs/`
 - Agent definition with success criteria
 
@@ -68,7 +68,7 @@ Write handoff to file system:
 - Set appropriate permissions
 
 ### 6. Update Session State
-Modify `.chati/session.yaml`:
+Run the router's canonical completion or `advance --agent <agent> --score <score>` action. The session manager must atomically:
 - Set agent status to `completed`
 - Add completion timestamp
 - Increment pipeline progress
@@ -143,10 +143,10 @@ If handoff document can't be saved:
 - Escalate with write error details
 
 ### Session Update Failure
-If `.chati/session.yaml` update fails:
-- Retry with backup creation
-- If persistent: Continue with in-memory state
-- Warn user about state persistence issue
+If the router reports a session update failure:
+- Report the exact error and stop
+- Do not retry by editing, replacing or reconstructing session state
+- Preserve the handoff artifact for a later canonical retry
 
 ### Circular Routing Detected
 If next agent would create a loop:

package/framework/tasks/orchestrator-health.md

@@ -64,7 +64,7 @@ Verify task files in `chati.dev/tasks/`:
 
 ### 4. Validate Schema Files
 Check schema definitions in `chati.dev/schemas/`:
-- session.yaml
+- canonical session schema
 - handoff.yaml
 - config.yaml
 - Agent-specific schemas
@@ -74,12 +74,8 @@ Verify:
 - Required fields documented
 - Data types specified
 
-### 5. Test Session File
-If session exists at `.chati/session.yaml`:
-- Validate YAML syntax
-- Check schema compliance
-- Verify referenced artifacts exist
-- Check for corruption indicators
+### 5. Test Canonical Session State
+Run `node chati.dev/orchestrator/chati-router.js doctor`. Consume the returned checks without opening the session file. Report unsafe or corrupt state exactly as returned and stop any mutable workflow.
 
 ### 6. Verify Directory Structure
 Ensure required directories exist:
@@ -199,7 +195,7 @@ health_report:
       - file: "chati.dev/installer/install.js"
         status: "ok"
         executable: true
-      - file: ".chati/session.yaml"
+      - file: "canonical-session-state (validated by router doctor)"
         status: "ok"
         valid: true
         schema_compliant: true
@@ -237,7 +233,7 @@ health_report:
     valid_schemas: 8
     issues: []
     schemas:
-      - "session.yaml"
+      - "canonical-session-schema"
       - "handoff.yaml"
       - "config.yaml"
 

package/framework/tasks/orchestrator-mode-switch.md

@@ -21,7 +21,7 @@ criteria:
 Execute transitions between modes (planning, build, deploy) while enforcing Article XI governance rules and validating quality gates.
 
 ## Prerequisites
-- Session state at `.chati/session.yaml`
+- Validated session state returned by `chati-router.js status`
 - Constitution Article XI at `chati.dev/constitution.md`
 - Quality scores from QA agents
 - Agent completion statuses
@@ -36,7 +36,7 @@ Identify the transition request:
 - **Backward**: QA-Implementation found spec issues, reverting to planning
 
 ### 2. Load Current Mode State
-Read session to understand current position:
+Run `node chati.dev/orchestrator/chati-router.js status` and use only the returned validated session context to understand:
 - Current mode (planning/build/deploy)
 - Last completed agent in current mode
 - Quality scores
@@ -104,11 +104,7 @@ Based on autonomous_gate and confidence:
 - **Block**: confidence low → escalate with issues
 
 ### 8. Update Session Mode
-If transition approved:
-- Change `mode` field in session.yaml
-- Set `current_agent` to first agent of new mode
-- Log transition in `mode_transitions` array
-- Update `pipeline_position`
+If transition is approved, execute the router-returned transition action. The canonical session manager changes `mode`, selects the first agent, appends `mode_transitions` and updates pipeline position. Never edit the session file directly.
 
 ### 9. Apply Mode Scope Restrictions
 Enforce Article XI scope rules for new mode: