chati-dev 4.5.16 → 4.5.28

package/framework/agents/plan/ux.md

@@ -42,7 +42,7 @@ Coordinate the design experience by activating 3 specialist sub-agents in sequen
 ## On Activation
 
 1. Read handoff from Architect
-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: `artifacts/1-Brief/brief-report.md` (target users)
 4. Read Architecture: `artifacts/3-Architecture/architecture.md` (tech constraints)
 5. Acknowledge inherited context
@@ -272,7 +272,7 @@ If score < 90%, identify which sub-agent's criteria failed and request correctio
 
 ### 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/quality/qa-implementation.md

@@ -34,7 +34,7 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 ## On Activation
 
 1. Read handoff from Dev 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 Tasks: `artifacts/6-Tasks/tasks.md` (acceptance criteria)
 4. Read Architecture: `artifacts/3-Architecture/architecture.md` (patterns)
 5. Read UX: `artifacts/4-UX/ux-specification.md` (Design System tokens, component states)
@@ -51,20 +51,21 @@ Validate that the implemented code meets quality standards: tests pass, coverage
 ### Pre-Flight: Decision Trail Check (Article XXII)
 ```
 Before beginning test execution:
-1. Read session.yaml decision_trail[] array (read-only — do NOT edit session.yaml directly)
+1. Run `node .chati.dev/orchestrator/chati-router.js status` and consume the
+   validated `decision_trail` array returned by the CLI
 2. Filter for unresolved entries (resolved: false) relevant to current phase
 3. For each unresolved entry:
    - Announce: "Known issue from prior revision: {what_was_wrong}. Avoid: {avoid}."
    - Actively check whether the current implementation addresses it
    - If resolved by current implementation: record the resolution in your handoff document
-     under "## Resolved Decision Trail" — the CLI will mark resolved: true in session.yaml
+     under "## Resolved Decision Trail"; the CLI will persist `resolved: true` canonically
    - If still present: treat as ERROR, skip to Silent Correction Loop immediately
 4. If no Decision Trail entries exist: proceed normally
 
 NOTE: Do NOT edit session.yaml directly. The mode-governance hook blocks direct writes.
 Record all Decision Trail entries and resolutions in your handoff document
 (artifacts/handoffs/qa-implementation-handoff.md) under "## Decision Trail" and
-"## Resolved Decision Trail" sections. The CLI merges these into session.yaml when you advance.
+"## Resolved Decision Trail" sections. The CLI-managed session manager merges these when you advance.
 ```
 
 ### Phase 1: Test Execution
@@ -237,7 +238,7 @@ Classification Decision Tree:
 3. Does the code simply not implement the spec?
    YES → CODE (Dev agent silent correction loop - existing behavior)
 4. Is the issue outside the defined scope?
-   YES → DEFER (add to session.yaml backlog)
+   YES → DEFER (return a backlog entry for the orchestrator to persist)
 
 For each correction request, include:
   FINDING: {defect description - one sentence, observable}
@@ -250,13 +251,13 @@ Routing Enforcement:
 - CODE → Dev agent via Silent Correction Loop (max 3 iterations, Article X)
 - SPEC → orchestrator notified, backward transition to Detail/Architect/Tasks
 - INTENT → orchestrator notified, deviation protocol activated (user must resolve)
-- DEFER → orchestrator adds to session.yaml backlog[], does NOT block approval
+- DEFER → orchestrator persists the item in canonical `backlog[]`, does NOT block approval
 
 Decision Trail Write:
 After each correction loop iteration, record a Decision Trail entry in your handoff document
 (artifacts/handoffs/qa-implementation-handoff.md) under a "## Decision Trail" section.
 Do NOT write to session.yaml directly — the mode-governance hook will block it.
-The CLI merges Decision Trail entries from your handoff into session.yaml when you advance.
+The CLI-managed session manager merges Decision Trail entries from your handoff when you advance.
 
 Decision Trail entry format (write in handoff document):
   id: DT-{next_sequence}
@@ -614,7 +615,7 @@ Save to: `artifacts/handoffs/qa-implementation-handoff.md`
 # The CLI records your completion when you run:
 #   node chati.dev/orchestrator/chati-router.js advance --agent qa-implementation --score <N>
 # The YAML below is for orchestrator reference only. Record decision_trail entries in
-# your handoff document under "## Decision Trail" — the CLI will merge them into session.yaml.
+# your handoff document under "## Decision Trail"; the CLI will merge them into canonical state.
 agents:
   qa-implementation:
     status: completed
@@ -728,7 +729,7 @@ Threshold: >= 95% (15/16 minimum). Canonical value: chati.dev/data/qa-rubrics.ya
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Project type, current pipeline position, execution mode, Dev agent status |
+| L0 | Router-validated prompt context | Project type, current pipeline position, execution mode, Dev agent status |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules, blocker taxonomy |
 | L2 | `artifacts/6-Tasks/tasks.md` | Acceptance criteria for verification (Given-When-Then) |
 | L3 | `artifacts/3-Architecture/architecture.md` | Architecture patterns, conventions, tech stack for code review |
@@ -832,7 +833,7 @@ On error during execution:
 
 ### 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/quality/qa-planning.md

@@ -41,7 +41,7 @@ Validate that every Brief problem traces through to a testable task, no requirem
    - `artifacts/5-Phases/phases.md`
    - `artifacts/6-Tasks/tasks.md`
 2. Read ALL handoffs: `artifacts/handoffs/`
-3. Read `.chati/session.yaml` for agent scores and criteria counts
+3. Use the validated canonical session context supplied in the activation prompt for agent scores and criteria counts. Never read `.chati/session.yaml` directly.
 
 **Team Mode Note (Article XXI):** In Team Mode, QA-Planning runs as the 4th member of the Planning Team BEFORE the Phases and Tasks agents have executed. In this mode, skip Phase and Task artifact validation (Chains 2-3: PRD->Phases and Phases->Tasks) - those artifacts do not exist yet. Focus validation on Detail (PRD), Architect (architecture.md), and UX (ux-specification.md) outputs only. Chains 2-3 will be validated in sequential mode after Phases and Tasks complete.
 
@@ -403,7 +403,7 @@ Threshold: >= 95% (10/10 minimum, no criteria may fail). Canonical value: chati.
 
 | Level | Source | Purpose |
 |-------|--------|---------|
-| L0 | `.chati/session.yaml` | Agent scores, criteria counts, pipeline state, execution mode |
+| L0 | Router-validated prompt context | Agent scores, criteria counts, pipeline state, execution mode |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules, quality standards |
 | L2 | `artifacts/1-Brief/brief-report.md` | Problems list for traceability chain origin |
 | L3 | `artifacts/2-PRD/prd.md` | Requirements list (FR/NFR) for traceability chain |
@@ -518,7 +518,7 @@ signed router. The reviewer cannot be replaced by the executor it evaluates.
 - **Team mode (v4.2.3+)**: Runs as 4th member of the Planning Team (Article XXI). Activates AFTER Detail (TT-PLN-001), Architect (TT-PLN-002), and UX (TT-PLN-003) complete their tasks. Task ID: TT-PLN-005.
 - **Communication**: Sends `qa_review_finding` messages via team mailbox to ALL THREE team members (detail, architect, ux) - not just the responsible agent. Corrections may affect cross-artifact consistency, so all agents must review findings together, re-validate their own work, and cross-review again before QA-Planning re-validates. Max 2 correction cycles. Team dissolves only when QA-Planning score >= 95%.
 - **Internal parallelization**: Traceability chain validation (4 chains) can run in parallel. Criteria quality assessment can run concurrently with placeholder scanning. Adversarial review runs after all other validations complete.
-- **Merge point**: Team dissolution handles the planning-to-phases transition. QA-Planning score is synced to session.yaml by the orchestrator.
+- **Merge point**: Team dissolution handles the planning-to-phases transition. The orchestrator persists the QA-Planning score canonically.
 
 ---
 

package/framework/agents/quality/qa-visual.md

@@ -78,7 +78,7 @@ The visual score is computed against the 8-dimension rubric in `chati.dev/data/q
 ## On Activation
 
 1. Read handoff from Dev agent: `artifacts/handoffs/dev-handoff.md`
-2. Read `.chati/session.yaml` for affected routes and project type
+2. Use the validated canonical session context supplied in the activation prompt for affected routes and project type. Never read `.chati/session.yaml` directly.
 3. Read brandbook: `artifacts/4-UX/brandbook.md` (token values for visual comparison)
 4. Read UX specification: `artifacts/4-UX/ux-specification.md` (component states, motion spec)
 5. Read architecture: `artifacts/3-Architecture/architecture.md` (confirm animation library choices)

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.5.16"
+version: "4.5.28"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-08-28T00:00:00Z"
-installer_version: "4.5.16"
+updated_at: "2026-09-01T00:00:00Z"
+installer_version: "4.5.28"
 project_type: greenfield
 language: en
 ides: []

package/framework/constitution.md

@@ -53,7 +53,7 @@ Every agent in Chati.dev:
 2. Operates within its designated pipeline position
 3. Cannot modify artifacts owned by other agents without orchestrator approval
 4. Must implement all 8 Universal Protocols (5.1-5.8)
-5. Reports its status, score, and output to session.yaml
+5. Returns its status, score, and output in the handoff for canonical session-manager persistence
 6. Defers cross-scope requests to the orchestrator via Deviation Protocol (5.7)
 
 **Enforcement: BLOCK** — Agents that violate governance are halted by the orchestrator.
@@ -75,13 +75,13 @@ Every agent in Chati.dev:
 
 ## Article III: Memory & Context
 
-1. Session state is persisted in `.chati/session.yaml` (IDE-agnostic)
+1. The canonical session manager persists session state in `.chati/session.yaml` (IDE-agnostic)
 2. System state is persisted in `chati.dev/config.yaml`
 3. Project context is maintained in `.chati/project-context.md`; provider-native context files consume it but never own it
 4. Handoffs between agents use the Two-Layer Protocol (Article VIII)
 5. Decisions are recorded in `artifacts/decisions/`
 6. Intelligence (gotchas, patterns, confidence) grows in `chati.dev/intelligence/`
-7. Context is never lost between sessions: resume reads session.yaml + `.chati/project-context.md` + latest handoff
+7. Context is never lost between sessions: the resume router validates canonical session state and supplies it with `.chati/project-context.md` and the latest handoff
 
 **Enforcement: BLOCK** — Agents must persist state before completion.
 
@@ -109,12 +109,12 @@ Every agent in Chati.dev:
 
 ## Article V: Communication Protocol
 
-1. Agents communicate exclusively through handoff documents and session.yaml
+1. Agents communicate exclusively through handoff documents and validated canonical session context supplied by the orchestrator
 2. Agent-to-agent communication follows a three-tier model:
-   a. **Intra-Team** (Team-Scoped Peer Communication — PERMITTED): When the orchestrator has formed a team (Article XXI), agents within that team MAY communicate directly via the Team Mailbox (`.chati/teams/{team-id}/mailbox/`). Rules: (i) messages MUST include sender, recipient, timestamp, and type; (ii) agents MAY only write to the mailbox of a team they are enrolled in (per session.yaml `teams[].roster`); (iii) agents MUST NOT modify another agent's messages — append only; (iv) the audit trail requirement is satisfied by the mailbox files themselves — the orchestrator reads them after every team cycle.
+   a. **Intra-Team** (Team-Scoped Peer Communication — PERMITTED): When the orchestrator has formed a team (Article XXI), agents within that team MAY communicate directly via the Team Mailbox (`.chati/teams/{team-id}/mailbox/`). Rules: (i) messages MUST include sender, recipient, timestamp, and type; (ii) agents MAY only write to the mailbox of a team present in the router-validated `teams[].roster`; (iii) agents MUST NOT modify another agent's messages — append only; (iv) the audit trail requirement is satisfied by the mailbox files themselves — the orchestrator reads them after every team cycle.
    b. **Cross-Team** (Orchestrator-Mediated — REQUIRED): Communication between agents in different teams, or between a team agent and a solo pipeline agent, MUST route through the orchestrator. No direct path exists between teams.
-   c. **Solo Pipeline** (No Change): Agents operating outside of any team follow the original rule — all communication is exclusively through handoff documents and session.yaml. The orchestrator mediates all routing.
-3. User-facing messages use the interaction language (session.yaml `language` field)
+   c. **Solo Pipeline** (No Change): Agents operating outside of any team communicate through handoff documents and orchestrator-supplied canonical context. The orchestrator mediates all routing and persistence.
+3. User-facing messages use the interaction language supplied by router-validated context
 4. Error messages are constructive: what failed, why, and how to fix
 5. Status updates are concise and actionable
 6. Technical jargon is adapted to detected user level (vibecoder vs power user)
@@ -168,7 +168,7 @@ This applies to:
 - Decision records (`artifacts/decisions/`)
 
 This does NOT apply to:
-- Agent-user conversation (follows `session.yaml` `language` setting)
+- Agent-user conversation (follows the validated `language` value supplied by router context)
 - Console output, prompts, guidance, error messages (interaction language)
 
 **Rationale:** Portability, team collaboration, tooling compatibility.
@@ -205,7 +205,7 @@ Written ONLY when the agent had complex discoveries that don't fit in the summar
 2. Reads Layer 2 (Deep Context) only if present and relevant
 3. Reads referenced artifacts in recommended order
 4. Acknowledges inherited context before starting work
-5. Fallback: session.yaml + `.chati/project-context.md` if handoff is missing
+5. If the handoff is missing, invoke router recovery and stop on an invalid response. Agents never reconstruct state from storage files.
 
 ### Team Handoff Envelope (Article XXI teams only)
 
@@ -280,7 +280,7 @@ Example of BAD criteria:
 
 ## Article XI: Mode Governance
 
-The pipeline operates in three execution modes that control agent permissions. Modes are derived from `project.state` in session.yaml.
+The pipeline operates in three execution modes that control agent permissions. Modes are supplied by the router from validated canonical state.
 
 ### Mode Definitions
 
@@ -297,7 +297,7 @@ The pipeline operates in three execution modes that control agent permissions. M
 3. Transition to `rail` requires QA-Planning score >= 95% and a sealed Planning-to-RAIL handoff
 4. Transition to `release` requires complete RAIL execution evidence and independent approval for every task
 5. Backward transition from `rail` to `planning` is permitted when independent review classifies an issue as `SPEC` or `INTENT`
-6. Mode overrides require explicit user confirmation and are logged in session.yaml
+6. Mode overrides require explicit user confirmation and are logged through the canonical session manager
 
 **Enforcement: BLOCK** — Write operations outside permitted scope are rejected.
 
@@ -340,7 +340,7 @@ The pipeline operates in three execution modes that control agent permissions. M
 8. Autonomous spawn capability is declared by each harness profile. Unsupported native team or spawn mechanics fall back to Chati's provider-neutral process runner without changing the routed model binding.
 
 9. When a Team (Article XXI) is active, a new context layer SHALL be injected for each team member:
-   - **L6 — Team Roster Layer**: Injected only when `session.yaml` has an active team entry. Contains: Team ID, Mission Statement, Roster with roles, Shared Task List status (task IDs, assigned_to, status, score only — not full descriptions), Decision Trail count, Echo count.
+   - **L6 — Team Roster Layer**: Injected only when router-validated context has an active team entry. Contains: Team ID, Mission Statement, Roster with roles, Shared Task List status (task IDs, assigned_to, status, score only — not full descriptions), Decision Trail count, Echo count.
    - Max token budget: 500 tokens (flat — does not scale with bracket size).
    - Injection trigger: ANY bracket when a team is active.
    - Injection order: L0, L1, L2, L6, L3, L4, L5.
@@ -415,7 +415,7 @@ Once the orchestrator is activated through a provider-native Chati entry point,
 4. **Explicit exit only**: The session lock is released ONLY by explicit user intent through the provider-native Chati exit command or clear natural language exit requests in the user's language.
 5. **Exit preserves state**: On exit, all session state, progress, and partial work MUST be persisted and every enabled harness lock is set to INACTIVE.
 6. **Resume re-locks**: Invoking Chati after an exit re-activates every enabled harness lock.
-7. **IDE restart resilience**: Provider-native lock files persist across restarts and the next activation reconciles them from session.yaml.
+7. **IDE restart resilience**: Provider-native lock files persist across restarts and the next activation reconciles them from router-validated canonical state.
 
 **Enforcement: BLOCK** — Responses outside the Chati.dev system while session lock is active are violations.
 
@@ -492,7 +492,7 @@ The system SHALL support two execution modes that govern the degree of human inv
 
 7. Loop protection: the pipeline manager tracks consecutive correction cycles for each reviewer-to-rework-target pair. Two normal correction cycles are allowed. A third consecutive failure SHALL use the installation-selected top-tier adjudication route before a human escalation. Human escalation is reserved for authority decisions, unresolved scope or conflicting evidence.
 
-8. Mode transitions are logged in session.yaml under `mode_transitions[]` for audit trail.
+8. Mode transitions are logged through the canonical session manager under `mode_transitions[]` for audit trail.
 
 **Enforcement: STRICT** — Autonomous mode MUST NOT bypass quality gates. All agents MUST respect the configured thresholds.
 
@@ -547,7 +547,7 @@ When multiple CLI providers are enabled, the system SHALL coordinate agent execu
    c. Task-specific quality, cost and review-independence requirements
    d. Availability evidence, otherwise a controlled block
 
-7. Cost tracking SHALL include provider information. Each model selection entry in session.yaml includes: provider, model, agent, timestamp, and estimated token usage.
+7. Cost tracking SHALL include provider information. Each canonical model-selection entry persisted by the session manager includes: provider, model, agent, timestamp, and estimated token usage.
 
 **Enforcement: BLOCK** — Provider and model selection is an installation contract, not an advisory preference.
 
@@ -630,7 +630,7 @@ The orchestrator SHALL consider team formation during planning when two or more
 
 The orchestrator MUST NOT form a team for: discovery phase agents (WU, Brief — these require sequential context building), QA agents as team leads (QA is always an independent validator), or convenience alone (team formation has coordination overhead).
 
-On formation, the orchestrator MUST: (a) generate a unique team-id (format: `TM-{YYYYMMDD}-{3-char-slug}`); (b) write the team definition to `session.yaml` under `teams[]`; (c) create `.chati/teams/{team-id}/` with mailbox/ and shared task list; (d) notify each enrolled agent of their role; (e) log the formation event in `team_events[]`.
+On formation, the orchestrator MUST: (a) generate a unique team-id (format: `TM-{YYYYMMDD}-{3-char-slug}`); (b) persist the team definition through the canonical session manager under `teams[]`; (c) create `.chati/teams/{team-id}/` with mailbox/ and shared task list; (d) notify each enrolled agent of their role; (e) persist the formation event in `team_events[]` through the same manager.
 
 ### 3. Team Lead Authority
 
@@ -666,7 +666,7 @@ Teams are dissolved by the orchestrator ONLY. Three dissolution types:
 - **Degraded**: Quality Gate fails after 2 Team Correction Cycles. Completed tasks preserved, failing tasks return to solo pipeline. Team marked `degraded`.
 - **Forced**: Constitutional violation detected. Team immediately halted. Completed tasks preserved, incomplete tasks return to pipeline backlog.
 
-On dissolution, the orchestrator MUST: update `teams[].status`, write Team Handoff Envelope, sync task scores to `session.yaml` `agents` block, and log dissolution event.
+On dissolution, the orchestrator MUST use the canonical session manager to update `teams[].status`, sync task scores to the `agents` block and log the dissolution event, while separately writing the Team Handoff Envelope.
 
 ### 8. Fallback Behavior (Graceful Degradation)
 
@@ -749,7 +749,7 @@ If a tool is unavailable (not in package.json, MCP offline): log the unavailabil
 
 When a correction loop modifies a spec, task, or architectural decision, the known-bad state MUST be recorded to prevent cyclical re-introduction.
 
-**Decision Trail Record:** Stored in `session.yaml` under `decision_trail[]`. Each entry contains: id (DT-NNNN), trigger (what caused revision), fault_origin (INTENT/SPEC/CODE/DEFER), what_was_wrong (precise description), avoid (what NOT to repeat), evidence_hash (SHA-1 for Echo Detection matching), correction_loop (which iteration), logged_at, resolved (boolean).
+**Decision Trail Record:** Persisted by the canonical session manager under `decision_trail[]`. Agents receive the validated entries through router prompt context and return new records in their handoff instead of accessing session storage directly. Each entry contains: id (DT-NNNN), trigger (what caused revision), fault_origin (INTENT/SPEC/CODE/DEFER), what_was_wrong (precise description), avoid (what NOT to repeat), evidence_hash (SHA-1 for Echo Detection matching), correction_loop (which iteration), logged_at, resolved (boolean).
 
 **Persistence Rules:** (a) Decision Trail entries are APPEND-ONLY — no entry may be deleted or modified after writing. (b) When a QA agent begins a new review cycle, it MUST read all existing Decision Trail entries for the current task BEFORE evaluating — this prevents flagging a known-bad state as a new defect. (c) Entries survive team dissolution and are included in the Team Handoff Envelope. (d) Entries are archived to `artifacts/decisions/fault-trail-{date}.md` at session end.
 

package/framework/context/protocols.md

@@ -25,7 +25,7 @@ Agent retries on failure. Investigate root cause before escalating.
 
 ## 7. Deviation Protocol
 - Deviations handled by orchestrator (not separate agent)
-- Requires user confirmation + audit trail in session.yaml
+- Requires user confirmation plus an audit trail persisted by the canonical session manager
 - Types: scope change, approach change, skip agent, add agent
 
 ## 8. Interaction Model

package/framework/context/quality.md

@@ -32,7 +32,7 @@ Scores within 5 points below threshold trigger REVIEW (human confirmation requir
 ## Fault Vector Protocol (Article XXII)
 - **Root Layer Routing**: INTENT (requirement wrong) -> Brief/Detail | SPEC (spec wrong) -> Architect/Tasks | CODE (implementation wrong) -> bounded RAIL rework | DEFER (out of scope) -> Backlog
 - **Evidence-Bound Verdicts**: ERROR/WARNING require tool evidence. Without evidence -> downgraded to SUGGESTION (non-blocking)
-- **Decision Trail**: Known-bad states logged in session.yaml `decision_trail[]`. Agents read before iterating.
+- **Decision Trail**: Known-bad states are persisted canonically in `decision_trail[]` and supplied to agents in their validated activation context.
 - **Echo Detection**: Similarity >= 0.85 with prior Decision Trail entry = ECHO. Escalate immediately, no more automated loops.
 - **FVP Compliance Checklist**: Mandatory in every QA correction report
 

package/framework/context/root.md

@@ -1,19 +1,19 @@
 # Chati.dev System Context
 
 ## Framework
-- **Version**: 4.5.16
+- **Version**: 4.5.28
 - **Agents**: Specialized discovery and planning agents feeding provider-neutral RAIL execution and a sealed release lane
 - **Constitution**: 25 Articles + Preamble
 - **Quality**: 5 pipeline gates + 3-tier verdicts + Fault Vector Protocol (Article XXII)
 - **Provider Policy**: Claude, Codex, and Grok bindings are selected at installation and enforced per task
 
 ## Key References
-- **Session State**: `.chati/session.yaml` (runtime, not committed)
+- **Session State**: canonical session-manager state (runtime, not committed)
 - **Constitution**: `chati.dev/constitution.md` (governance)
 - **Orchestrator**: `chati.dev/orchestrator/chati.md` (entry point)
 - **Config**: `chati.dev/config.yaml` (version info)
 - **Canonical Project Context**: `.chati/project-context.md`
-- **Runtime State**: `.chati/session.yaml`, mirrored to provider-native lock files
+- **Runtime State**: canonical session-manager state, mirrored to provider-native lock files
 
 ## Pipeline
 ```
@@ -24,4 +24,4 @@ RELEASE:  Evidence gate -> Explicit human authorization -> External action
 ```
 
 ## How to Use
-Use the provider-native Chati entry point to activate the orchestrator. It reads session.yaml, `.chati/project-context.md`, and the latest handoff to determine where you left off and what comes next.
+Use the provider-native Chati entry point to activate the orchestrator. The deterministic router validates canonical session state and returns the project context and next action. Harnesses never open the session file directly.

package/framework/data/entity-registry.yaml

@@ -272,7 +272,7 @@ entities:
     session:
       path: chati.dev/schemas/session.schema.json
       type: schema
-      purpose: "JSON schema for .chati/session.yaml runtime state"
+      purpose: "JSON schema for canonical runtime session state"
       keywords: [session, state, validation, runtime]
       dependencies: []
       adaptability: 0.2

package/framework/domains/agents/orchestrator.yaml

@@ -24,7 +24,7 @@ authority:
   redirectMessage: "The orchestrator delegates specialized work to the appropriate agent."
 
 outputs:
-  - session.yaml
+  - router-validated canonical session context
   - handoff documents
 
 rules:
@@ -45,7 +45,7 @@ rules:
     priority: high
 
   - id: orch-session
-    text: "Persist all state changes to session.yaml immediately."
+    text: "Persist all state changes immediately through the canonical session manager."
     priority: high
 
   # Provider Routing (v3.0.0)

package/framework/domains/constitution.yaml

@@ -147,7 +147,7 @@ articles:
         priority: critical
       - evidence-bound-verdicts: "ERROR findings require tool evidence (lint/typecheck/test/screenshot). Without evidence, downgrade to SUGGESTION (non-blocking)."
         priority: critical
-      - decision-trail: "Append-only log of known-bad states in session.yaml decision_trail[]. Agents read before iterating."
+      - decision-trail: "Append-only canonical log of known-bad states. The router supplies decision_trail[] to agents before iteration."
         priority: high
       - echo-detection: "Content-similarity >= 0.85 with prior Decision Trail entry = ECHO. Escalate immediately, no more automated loops."
         priority: critical

package/framework/hooks/advance-trigger.js

@@ -20,6 +20,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';
+import { readHookSession } from './session-reader.js';
 
 // Canonical gate thresholds live in data/qa-rubrics.yaml. These literals are
 // only a last-resort fallback for when that file is briefly unavailable (for
@@ -98,12 +99,9 @@ async function main() {
   //   that failed its threshold (score below cutoff) OR verdict is
   //   NEEDS_FIX/REJECTED. Correction loops are an INTERNAL quality process
   //   (Fault Vector Protocol, Article XXII), not a forward step.
-  const sessionPath = join(cwd, '.chati', 'session.yaml');
-  if (!existsSync(sessionPath)) return;
-  let raw;
-  try { raw = readFileSync(sessionPath, 'utf-8'); } catch { return; }
-  const modeMatch = raw.match(/^\s*execution_mode:\s*(.+)$/m);
-  const profile = modeMatch ? modeMatch[1].trim().replace(/^["']|["']$/g, '') : 'interactive';
+  const sessionRead = readHookSession(cwd);
+  if (!sessionRead.loaded) return;
+  const profile = sessionRead.session?.execution_mode || 'interactive';
 
   // Read the written handoff and check its frontmatter declares completion.
   if (!existsSync(filePath)) return;

package/framework/hooks/git-push-authority.js

@@ -10,19 +10,23 @@
  *   - it only ever denies push / PR-creation / release-creation commands;
  *   - it only enforces while a pipeline is active (session.mode is a pipeline
  *     phase) AND the current agent is set AND is not devops;
- *   - outside an active session (no session, completed session) it does
- *     nothing.
+ *   - an unavailable or malformed session denies an external operation rather
+ *     than silently removing the release authority boundary.
  *
- * Fails open (with an stderr log) on any internal error: a guard crash must
- * never block every Bash command.
+ * Fails closed for push, merge, and release operations on any internal error.
  */
-import { existsSync, readFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { join } from 'path';
+import { readHookSession } from './session-reader.js';
 
 const PUSH_PATTERNS = [
   // git push, including global options that carry a value (git -C <path> push,
-  // git -c k=v push) so an agent cannot side-step the guard with -C.
-  /\bgit\s+(?:-{1,2}\S+(?:\s+\S+)?\s+)*push\b/i,
+  // git -c k=v push) so an agent cannot side-step the guard with -C. Shell
+  // quotes around the subcommand are semantically inert, so match them too.
+  /\bgit\s+(?:-{1,2}\S+(?:\s+\S+)?\s+)*(?:push|["']push["'])(?=\s|$)/i,
+  /\bgit\s+(?:-{1,2}\S+(?:\s+\S+)?\s+)*(?:send-pack|["']send-pack["'])(?=\s|$)/i,
+  // A one-off git alias can hide a push behind an arbitrary final subcommand.
+  /\bgit\b[^\n;&|]*\s-c\s+alias\.[^=\s]+=(?:["']?[^\n;&|]*\b(?:git\s+)?push\b)/i,
   /\bgh\s+pr\s+(?:create|merge)\b/i,
   /\bgh\s+release\s+create\b/i,
 ];
@@ -38,30 +42,35 @@ function isPushCommand(command) {
  * Block only when a push/PR command runs while a pipeline is active (mode is a
  * pipeline phase) and the current driver is a non-devops agent.
  */
-function shouldBlockPush(command, mode, agent, { v2 = false } = {}) {
+function shouldBlockPush(command, mode, agent, { v2 = false, sessionStatus = null } = {}) {
   if (!isPushCommand(command)) return false;
-  if (v2) return Boolean(mode && ACTIVE_MODES.includes(mode) && agent);
+  // Pausing a v2 session does not delegate external authority. The explicit
+  // manual boundary is `/chati exit`; otherwise a paused RAIL attempt could
+  // publish or push without the evidence and human-authorization gate.
+  if (v2) return Boolean(mode && ACTIVE_MODES.includes(mode));
+  if (sessionStatus === 'paused') return false;
   return Boolean(mode && ACTIVE_MODES.includes(mode) && agent && agent !== 'devops');
 }
 
 function readSessionField(projectDir, key) {
-  const p = join(projectDir, '.chati', 'session.yaml');
-  if (!existsSync(p)) return null;
-  try {
-    const raw = readFileSync(p, 'utf-8');
-    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
-    if (!m) return null;
-    const v = m[1].trim().replace(/^["']|["']$/g, '');
-    return v === 'null' || v === '' ? null : v;
-  } catch {
-    return null;
-  }
+  const result = readHookSession(projectDir);
+  return result.loaded ? result.session?.[key] ?? null : null;
 }
 
 async function main() {
   let input = '';
   for await (const chunk of process.stdin) input += chunk;
 
+  const deny = (reason) => {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }));
+  };
+
   try {
     const event = JSON.parse(input);
     if ((event.tool_name || '') !== 'Bash') {
@@ -75,30 +84,29 @@ async function main() {
     }
 
     const projectDir = event.cwd || process.cwd();
-    const mode = readSessionField(projectDir, 'mode');
-    const agent = readSessionField(projectDir, 'current_agent');
-    const isV2 = existsSync(join(projectDir, '.chati', 'v2', 'installation.json'));
+    const sessionRead = readHookSession(projectDir);
+    if (!sessionRead.loaded) {
+      deny(`[Session Security] Push, merge, and release operations are blocked because session.yaml could not be validated: ${sessionRead.error || 'the session is missing'}`);
+      return;
+    }
+    const mode = sessionRead.session?.mode ?? null;
+    const agent = sessionRead.session?.current_agent ?? null;
+    const sessionStatus = sessionRead.session?.session_status ?? null;
+    const isV2 = sessionRead.session?.runtime_version === 2
+      || existsSync(join(projectDir, '.chati', 'v2', 'installation.json'));
 
     // Only enforce while a pipeline is active with a non-devops driver.
-    if (shouldBlockPush(command, mode, agent, { v2: isV2 })) {
-      process.stdout.write(JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          permissionDecision: 'deny',
-          permissionDecisionReason: isV2
-            ? `[Release Lane] RAIL execution cannot push, merge, or publish directly. Complete the evidence gate and obtain explicit authorization for the external action. Current phase: "${mode}".`
-            : `[Article IV] Only the devops agent may push to a remote or open a pull request during an active legacy pipeline. The current agent is "${agent}". Let the legacy pipeline reach devops, or run /chati exit to take manual control.`,
-        },
-      }));
+    if (shouldBlockPush(command, mode, agent, { v2: isV2, sessionStatus })) {
+      deny(isV2
+        ? `[Release Lane] RAIL execution cannot push, merge, or publish directly. Complete the evidence gate and obtain explicit authorization for the external action. Current phase: "${mode}".`
+        : `[Article IV] Only the devops agent may push to a remote or open a pull request during an active legacy pipeline. The current agent is "${agent}". Let the legacy pipeline reach devops, or run /chati exit to take manual control.`);
       return;
     }
 
     process.stdout.write('{}');
   } catch (err) {
-    // Fail open: a guard crash must not block every Bash command. Log so the
-    // failure is visible instead of silently disabling enforcement.
-    process.stderr.write(`[chati] git-push-authority error (allowing operation): ${err && err.message ? err.message : err}\n`);
-    process.stdout.write('{}');
+    process.stderr.write(`[chati] git-push-authority error (denying external operation): ${err && err.message ? err.message : err}\n`);
+    deny('[Session Security] Push, merge, and release operations are blocked because the release authority hook could not validate its input.');
   }
 }