chati-dev 4.2.2 → 4.3.1

package/framework/constitution.md

@@ -79,7 +79,7 @@ Every agent in Chati.dev:
 2. System state is persisted in `chati.dev/config.yaml`
 3. Project context is maintained in `CLAUDE.md` (auto-updated by each agent)
 4. Handoffs between agents use the Two-Layer Protocol (Article VIII)
-5. Decisions are recorded in `chati.dev/artifacts/decisions/`
+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 + CLAUDE.md + latest handoff
 
@@ -125,7 +125,18 @@ Every agent in Chati.dev:
    - Avoid over-hedging: "It could potentially perhaps maybe..."
    - Write naturally. If a sentence reads like AI wrote it, rewrite it
 
-**Enforcement: GUIDE** — Violations trigger guidance, not blocking.
+**Enforcement: BLOCK - Em-dashes (-, -) are hard-blocked. Emojis trigger advisory warning.**
+
+8. **Zero-Commands Thesis.** After installation, the user SHALL interact with the framework exclusively through the `/chati` slash command in their editor. No other CLI invocations are required during ordinary operation — every deterministic action (spawning agents, running QA, advancing the pipeline, running the self-diagnostic) is driven by the system.
+
+   Three sanctioned exceptions, named and bounded:
+   a. **Installation**: `npx chati-dev init` — a one-time setup action. The framework has no state to install itself from.
+   b. **License activation**: `npx chati-dev activate --key=YOUR-KEY` — a one-time action per machine OR per license renewal. Pasting the key in chat is PROHIBITED (chat transcripts at `~/.claude/projects/*/*.jsonl` persist plaintext; the activate command writes to `~/.chati-dev/license.yaml` with user-only permissions). When `/chati` boot detects a missing or invalid license, the orchestrator SHALL display the activate command and invoke `orchestrate wait-for-license` to poll the file until it becomes VALID or the 60s timeout elapses.
+   c. **Explicit diagnostics**: `orchestrate doctor` — optional; the same check battery runs silently on every `/chati` boot, so this command is only for debugging.
+
+   Any other action currently requiring the user to type a CLI command is a BUG in the framework and MUST be closed by an autonomous trigger. Known examples historically closed: post-dev visual-QA invocation (ADR-AUTO-02, closed by `post-dev.js` hook); scaffold application (Article XXI auto-gate, closed by Phase 10). Known examples deferred to v1.2: tool-output token accounting (PostResponse hook); Gemini / Codex model detection.
+
+**Enforcement: zero-commands thesis is a CONSTITUTIONAL INVARIANT — any code path that forces a user CLI command outside of the three exceptions SHALL be treated as a `SPEC` fault under Article XXII and routed back to the architect.**
 
 ---
 
@@ -152,9 +163,9 @@ This applies to:
 - Templates (`chati.dev/templates/`)
 - Workflows (`chati.dev/workflows/`)
 - Constitution (`chati.dev/constitution.md`)
-- All generated artifacts (`chati.dev/artifacts/`)
-- Handoff documents (`chati.dev/artifacts/handoffs/`)
-- Decision records (`chati.dev/artifacts/decisions/`)
+- All generated artifacts (`artifacts/`)
+- Handoff documents (`artifacts/handoffs/`)
+- Decision records (`artifacts/decisions/`)
 
 This does NOT apply to:
 - Agent-user conversation (follows `session.yaml` `language` setting)
@@ -171,7 +182,7 @@ This does NOT apply to:
 Every agent MUST generate a handoff document upon completion.
 Every agent MUST read the previous agent's handoff upon activation.
 
-Handoffs are saved to `chati.dev/artifacts/handoffs/` and follow a two-layer structure:
+Handoffs are saved to `artifacts/handoffs/` and follow a two-layer structure:
 
 ### Layer 1: Summary (mandatory, max 150 lines)
 Contains:
@@ -200,7 +211,7 @@ Written ONLY when the agent had complex discoveries that don't fit in the summar
 
 When a team dissolves (Article XXI), the orchestrator collects outputs from all team members and produces a single Team Handoff Envelope. This envelope is the authoritative output of the team — it is what the next pipeline agent reads.
 
-1. **Team vs Pipeline Artifacts**: Individual team-member handoffs are internal (stored in `.chati/teams/{team-id}/`) and MUST NOT be read by agents outside the team. Only the Team Handoff Envelope crosses the team boundary, saved to `chati.dev/artifacts/handoffs/{team-id}-team-handoff.md`.
+1. **Team vs Pipeline Artifacts**: Individual team-member handoffs are internal (stored in `.chati/teams/{team-id}/`) and MUST NOT be read by agents outside the team. Only the Team Handoff Envelope crosses the team boundary, saved to `artifacts/handoffs/{team-id}-team-handoff.md`.
 
 2. **Envelope Format**: Follows the standard Layer 1 / Layer 2 structure (max 150 / 500 lines) with mandatory additions to Layer 1:
    - Team ID, Mission, Roster, Team Score, Correction Cycles, Echo Count
@@ -250,7 +261,7 @@ Requirements:
 1. Criteria must be binary (pass/fail) — not subjective quality assessments
 2. Criteria must be specific to THIS execution (not generic checklists)
 3. Score = criteria met / total criteria
-4. Threshold: >= 95% to present results
+4. Threshold: per Article II §1 tier (QA agents >= 95%; standard agents >= 90%; discovery agents >= 85%). See Article II for the authoritative table.
 5. If below threshold: internal refinement loop (max 3 iterations)
 6. QA-Planning validates criteria quality as checks and balances
 7. Agents MUST NOT define trivially easy criteria to inflate scores
@@ -294,45 +305,56 @@ The pipeline operates in three execution modes that control agent permissions. M
 
 ## Article XII: Context Bracket Governance
 
-1. The orchestrator SHALL calculate the context bracket (FRESH, MODERATE, DEPLETED, CRITICAL) before every agent interaction.
+1. The orchestrator SHALL calculate the context bracket (FRESH, MODERATE, DEPLETED, CRITICAL) before every agent interaction, based on **estimated tokens consumed** against the **actively detected model's context window** — NOT on turn count. Turn count is a bad proxy: turns vary in size from a single word to a full file dump, and the same turn count on a 200K window and a 1M window represent wildly different consumption states.
 
-2. Context injection layers SHALL INCREASE as context depletes (Progressive Reinforcement):
+2. The active context window SHALL be resolved via the following detection chain. First hit wins:
+   a. `process.env.CLAUDE_MODEL` (Claude Code-set environment variable) → `parseClaudeModelId()` → lookup in `chati.dev/data/model-limits.json` via `resolveContextLimit()`.
+   b. Hook event payload (`event.session.model` when exposed by the CLI).
+   c. `session.active_model` (written at `/chati` boot by the orchestrator).
+   d. Per-agent default from `HOOK_AGENT_MODELS` (last-resort fallback).
+   e. Conservative terminal default: 200_000 tokens (applies only when model AND provider are both unidentifiable).
+
+   Claude model variants MUST be distinguished at the parser layer. Canonical normalized keys are: `opus`, `opus[1m]`, `sonnet`, `sonnet[1m]`, `haiku`. As of 2026-04-18 all current Claude Opus and Sonnet families resolve to **1M tokens**; Haiku is **200K**. The `opus[1m]` / `sonnet[1m]` aliases are retained for backwards compatibility (sessions that stored them before the 2026-04-18 update), and resolve identically to the bare family key.
+
+3. The per-model and per-provider table is maintained as data, NOT as code duplicated across modules. The canonical table lives at `chati.dev/data/model-limits.json`; consumers (`src/utils/provider-limits.js`, `chati.dev/hooks/prism-engine.js`) load it at runtime. Scan check #25 asserts parity between the JSON and any embedded fallback to catch drift at CI time, and additionally asserts the post-2026-04-18 invariant: `MODEL_LIMITS.opus >= 1_000_000` (the prior `=== 200_000` regression-lock was removed by context-window-auto-detect-v2; see `.planning/audit-baseline-2026-04-18.md` appendix).
+
+4. Context injection layers SHALL INCREASE as context depletes (Progressive Reinforcement):
    - FRESH: L0 (Constitution) + L1 (Global) only — model has full memory, minimal reinforcement
    - MODERATE: L0 + L1 + L2 (Agent) + L3 (Workflow) — model starting to forget
    - DEPLETED: All 6 layers (L0-L5) — significant context loss, full reinforcement
    - CRITICAL: All 6 layers (L0-L5) + forced handoff — maximum reinforcement, do not accept degraded output
 
-3. Context recovery uses a two-level autonomous strategy:
+5. Context recovery uses a two-level autonomous strategy:
    a. Level 1 (Smart Continuation): When context is compacted, the orchestrator SHALL automatically capture a digest, persist memories, and rebuild context post-compact. The user experiences zero interruption.
    b. Level 2 (Autonomous Spawn): When Smart Continuation is insufficient (3+ compactions, quality degradation >15%, or persistent CRITICAL bracket), the orchestrator SHALL spawn a new session autonomously with full context from memories and continuation state.
 
-4. The Constitution (L0) and Mode governance (L1) are NON-NEGOTIABLE and SHALL be injected in ALL brackets, including CRITICAL.
+6. The Constitution (L0) and Mode governance (L1) are NON-NEGOTIABLE and SHALL be injected in ALL brackets, including CRITICAL.
 
-5. Token budgets per bracket (Progressive Reinforcement Model — as context degrades, reinforcement increases):
-   - Budgets are expressed as a percentage of the provider's context window
-   - FRESH: 1.5% of context window (Claude: 3000, Gemini: 15000, Codex: 1920)
-   - MODERATE: 2.5% of context window (Claude: 5000, Gemini: 25000, Codex: 3200)
-   - DEPLETED: 4.0% of context window (Claude: 8000, Gemini: 40000, Codex: 5120)
-   - CRITICAL: 5.0% of context window (Claude: 10000, Gemini: 50000, Codex: 6400)
+7. Token budgets per bracket (Progressive Reinforcement Model — as context degrades, reinforcement increases):
+   - Budgets are expressed as a percentage of the actively detected context window
+   - FRESH: 1.5% of context window (Claude 200K: 3000, Opus 1M: 15000, Codex: 1920)
+   - MODERATE: 2.5% of context window (Claude 200K: 5000, Opus 1M: 25000, Codex: 3200)
+   - DEPLETED: 4.0% of context window (Claude 200K: 8000, Opus 1M: 40000, Codex: 5120)
+   - CRITICAL: 5.0% of context window (Claude 200K: 10000, Opus 1M: 50000, Codex: 6400)
 
-6. Autonomous spawn capability varies by IDE:
+8. Autonomous spawn capability varies by IDE:
    - Full autonomy: Claude Code, AntiGravity, Gemini CLI
    - Continuation file: Cursor, VS Code (user loads with /chati resume)
 
-7. When a Team (Article XXI) is active, a new context layer SHALL be injected for each team member:
+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.
    - 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.
 
-8. Progressive Reinforcement for teams:
+10. Progressive Reinforcement for teams:
    a. Each team member has its own independent context bracket, calculated per the standard formula.
    b. The Team Mailbox is NEVER injected into the PRISM context. Agents read the mailbox directly via tool call. This prevents mailbox bloat from consuming context.
    c. When ANY team member reaches CRITICAL bracket, the Team Lead is notified via mailbox: "CRITICAL-CONTEXT: {agent_name} at CRITICAL bracket." The Team Lead routes to the orchestrator if warranted.
    d. L6 is the FIRST layer dropped when an individual agent reaches CRITICAL. At CRITICAL, the agent reads the Shared Task List directly rather than via injected context.
    e. Context bracket calculations are INDEPENDENT per team member. One member reaching CRITICAL does not compress another member's context.
 
-**Enforcement: BLOCK** — Bracket violations (injecting L3/L4 in CRITICAL) degrade agent quality.
+**Enforcement: BLOCK** — Bracket violations degrade agent quality. The canonical policy per §4 is: L0+L1 MUST be present in every bracket; L2+L3 MUST be injected at MODERATE and deeper; ALL L0-L5 MUST be injected at DEPLETED/CRITICAL. OMITTING a required layer at its bracket (e.g. dropping L3/L4 at CRITICAL, or stripping L0 anywhere) is a violation. L6 is the exception per §10d: dropped FIRST at CRITICAL when a team is active.
 
 ---
 
@@ -355,7 +377,9 @@ The pipeline operates in three execution modes that control agent permissions. M
 
 7. Memory attention scoring SHALL use natural decay — memories not accessed lose relevance organically. No memory is permanent unless explicitly marked as durable by the user.
 
-8. The system SHALL support automatic memory consolidation to merge, deduplicate, and prune accumulated memories. Consolidation follows a 4-phase cycle (Orient, Gather, Consolidate, Prune) and archives removed entries rather than deleting them. Triggered automatically when memory entries exceed threshold.
+8. The system SHALL support automatic memory consolidation to merge, deduplicate, and prune accumulated memories. Consolidation follows a 4-phase cycle (Orient, Gather, Consolidate, Prune) and archives removed entries rather than deleting them. Triggered automatically when memory entries exceed threshold (100 entries default).
+
+8a. **Bootstrap exception (memory-bootstrap-v1, 2026-04-18).** Before the 100-entry threshold is reached, `session-digest.js` SHALL write a minimal `MEMORY.md` directly from the current digest when the active agent has no memory file yet (or the file is empty). Bootstrap entries are tagged `source:bootstrap` and confidence `low` so subsequent full consolidation (via `dream.js`) re-classifies and deduplicates them. This closes the early-session gap where `prism-engine` loads an empty L4 memory layer despite digests being captured.
 
 9. Per-turn memory extraction MAY capture decisions, resolutions, corrections, and validated patterns automatically from agent output. Extracted memories start at warm tier (confidence 0.5) and are promoted through evidence accumulation.
 
@@ -469,30 +493,32 @@ The system SHALL support two execution modes that govern the degree of human inv
 
 ---
 
-## Article XVIII: Execution Profile Governance
+## Article XVIII: Execution Profile Governance (Deprecated — folded into Article XVII)
 
-The system SHALL support three execution profiles that govern the degree of confirmation required for agent actions. Profiles are orthogonal to mode governance (Article XI) — modes control WHERE agents can write; profiles control WHETHER confirmation is required. Note: Execution Mode (Article XVII) governs WHO decides (human vs system); Execution Profile governs HOW actions execute (read-only, confirmed, autonomous).
+As of 2026-04-18 (audit-fixes-v1 P5 follow-up), this article is **deprecated and retained for migration reference**. The `execution_profile` field with `explore` / `guided` / `autonomous` values has been removed. Its functionality collapses into `execution_mode` (Article XVII) with two canonical values:
 
-1. Three profiles are recognized:
-   - **explore**: Read-only mode. Agents analyze, investigate, and suggest but perform NO write operations. Useful for safe discovery and analysis.
-   - **guided**: Default profile. Agents propose actions and wait for user confirmation before writes. Balances safety with productivity.
-   - **autonomous**: Full autonomy. Agents execute without confirmation when quality gate scores meet thresholds. Requires cumulative gate scores >= 95%.
+- `execution_mode: interactive` — agents propose actions and wait for user confirmation. Default. Subsumes the prior `guided` profile.
+- `execution_mode: autonomous` — agents execute without confirmation when quality gate scores meet thresholds (>= 95%). Subsumes the prior `autonomous` profile.
 
-2. The default profile is `guided`. Profile selection is stored in `session.yaml` under `execution_profile`.
+The prior `explore` profile (read-only) is NOT a first-class execution mode any longer. Read-only investigation is achieved by the user staying in `interactive` mode and declining every proposed write — no schema-level gate required.
 
-3. Profile transitions are logged in `session.yaml` under `profile_transitions[]` for audit trail.
+**Migration mapping** applied by `migrateSession()`:
 
-4. Certain operations ALWAYS require confirmation regardless of profile:
-   - Destructive operations (file deletion, database drops, force push)
-   - Deployment to production environments
-   - Deviation protocol activation
-   - Backward pipeline transitions (build → planning)
+| Old `execution_profile` | New `execution_mode` |
+|---|---|
+| `explore` | `interactive` (user approves every action) |
+| `guided` | `interactive` |
+| `autonomous` | `autonomous` |
 
-5. The `autonomous` profile is gated by quality: it can only be activated when the most recent QA gate score is >= 95%. If quality drops below threshold during autonomous execution, the system SHALL automatically downgrade to `guided`.
+Certain operations ALWAYS require confirmation regardless of mode:
+- Destructive operations (file deletion, database drops, force push)
+- Deployment to production environments
+- Deviation protocol activation
+- Backward pipeline transitions (build → planning)
 
-6. The `explore` profile is available at any pipeline position and does not affect mode governance. An agent in `planning` mode with `explore` profile can read any file but write to none.
+The audit-trail field `profile_transitions[]` is similarly deprecated. Mode transitions are already captured in `mode_transitions[]` (defined in Article XI).
 
-**Enforcement: BLOCK** — Write operations in `explore` profile are rejected. Autonomous mode without qualifying gate scores is rejected.
+**Enforcement: Informational.** This article no longer defines live invariants; Article XVII owns execution mode governance end-to-end.
 
 ---
 
@@ -631,7 +657,7 @@ If any condition fails, the orchestrator enters a Team Correction Cycle (max 2 t
 
 Teams are dissolved by the orchestrator ONLY. Three dissolution types:
 
-- **Clean**: Quality Gate passes. Envelope written, team marked `dissolved`, artifacts archived to `chati.dev/artifacts/handoffs/teams/{team-id}/`.
+- **Clean**: Quality Gate passes. Envelope written, team marked `dissolved`, artifacts archived to `artifacts/handoffs/teams/{team-id}/`.
 - **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.
 
@@ -650,7 +676,7 @@ When Agent Teams is unavailable (Gemini CLI, Codex CLI, single-agent Claude, or
 
 Two teams are defined for the standard pipeline:
 
-**Planning Team** (post-Brief, PLAN phase): Orchestrator (Lead) + Detail + Architect + UX. Cross-review circular: Detail challenges Architect, Architect challenges UX, UX challenges Detail. Each agent produces work independently (sealed-bid model), then exchanges cross-review via mailbox. Replaces GROUP 1 `spawn_parallel` when feature flag is active.
+**Planning Team** (post-Brief, PLAN phase): Orchestrator (Lead) + Detail + Architect + UX + QA-Planning. Detail, Architect, and UX produce work independently (sealed-bid model), then exchange cross-review via mailbox. QA-Planning runs after all 3 complete, validates the full plan (6-dimensional), and sends structured feedback to Detail, Architect, and UX via mailbox. The team has 4 members (excluding the Orchestrator Lead). Replaces GROUP 1 `spawn_parallel` + sequential QA-Planning gate when feature flag is active.
 
 **Build Team** (BUILD phase): Orchestrator (Lead) + Dev + QA-Implementation. QA reviews EACH task as Dev completes it (per-task review mode), not as a batch at the end. Dev submits task completion to mailbox, QA reviews with evidence (Article XXII), sends findings back. Dev continues to next task immediately. Replaces sequential Dev → QA-Implementation when feature flag is active.
 
@@ -722,7 +748,7 @@ When a correction loop modifies a spec, task, or architectural decision, the kno
 
 **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).
 
-**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 `chati.dev/artifacts/decisions/fault-trail-{date}.md` at session end.
+**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.
 
 ### 4. Echo Detection
 
@@ -755,8 +781,65 @@ If any check is NO, the compliance block itself is an ERROR and the report canno
 
 ---
 
-*Chati.dev Constitution v4.2.2 — 22 Articles + Preamble*
+## Article XXIII: Reasoning Tier Governance
+
+Articles XVII and XVIII govern WHO decides (execution mode) and HOW actions execute (execution profile). This article governs WHAT DEPTH the agent thinks at — the cognitive shape it applies to the task in front of it. Three tiers, with monotonic promotion inside a task and deterministic escalation triggers.
+
+### 1. The Three Tiers
+
+**`standard`** — Default posture. Agent applies normal capacity. Minimal pre-action analysis; directly produces output. Appropriate for well-scoped, small tasks (XS/S) where the path is clear and failure is cheap to unwind.
+
+**`deep`** — Proactive analysis phase before action. Agent investigates root causes, reviews the Decision Trail (Article XXII), scans related code and artifacts, and articulates the plan INLINE before editing. No separate planning file; the reasoning is surfaced in the agent's response. Appropriate for M/L tasks, cross-cutting changes, or recovery from a single correction cycle.
+
+**`deliberate`** — Mandatory planning artifact before any code edit. Agent writes `.planning/<task-or-feature>-plan.md` enumerating approach, alternatives considered, risks, rollback plan, and acceptance criteria. Only after the plan is written (and user-reviewed when in `guided` execution profile) does editing begin. The `reasoning-escalator.js` hook enforces this at `PreToolUse:Write|Edit` time by denying the tool call when `tier === 'deliberate'` and `.planning/` has no plan file newer than the current session start.
+
+### 2. Per-Agent Defaults
+
+Each agent declares a default tier in its agent.md under a `## Reasoning Tier` heading. Agents that produce deep reasoning artifacts by nature (architect, detail, qa-planning, qa-implementation, brownfield-wu) default to `deep`. Execution-focused agents (brief, dev, greenfield-wu, ux, phases, tasks, qa-visual, devops) default to `standard`. Escalation from default to a higher tier is non-reversible within the task — once escalated, the tier stays for the duration of that task even after the triggering signal resolves.
+
+### 3. Escalation Triggers
+
+The `reasoning-escalator.js` hook evaluates these signals on every `UserPromptSubmit` and updates `session.reasoning_tier` accordingly. Multiple signals that point at different tiers are resolved by MAX rank:
+
+**Triggers that promote to `deep`:**
+- Task touches more than 5 files OR more than 200 modified lines (git-diff detected).
+- Decision Trail (Article XXII) has more than 2 unresolved entries for the current task.
+- User message matches a friction keyword: `redesign`, `refactor(?:ing|s)?`, `stuck`, `loop`, `not working`, `break(?:ing|s)?`. Locale-specific equivalents (e.g. Portuguese, Spanish, French) are merged on top when `session.language` selects them; the canonical catalog lives in `FRICTION_KEYWORDS_LOCALES` inside `reasoning-escalator.js` so Article VII (English-only framework text) holds in this document.
+- Cross-viewport regression detected by `visual-qa.js` (layout error at a viewport that was clean on the previous run).
+
+**Triggers that promote to `deliberate`:**
+- `correction_cycles >= 2` on the current agent (autopilot is clearly failing).
+- Scope escalation signal raised by any agent (task is larger than the task spec described).
+- User explicit slash command `/ultraplan` or `/deliberate`.
+
+**Force back to `standard`:**
+- User explicit slash command `/quick`.
+
+Explicit user commands override all auto-detected signals. Auto-detected signals cannot demote (deep never auto-reverts to standard mid-task).
+
+### 4. Per-Task Reset, Sticky Carryover
+
+Tiers reset to each agent's DEFAULT at task start. Exception: if the current session has recorded any escalation-to-`deliberate` in the last three completed tasks, the default for the next task is `deep` (sticky carryover) until a clean run lands. This prevents thrashing between tiers for a session that is demonstrably in difficult territory.
+
+### 5. Enforcement & Observability
+
+- `reasoning-escalator.js` is registered in `hooks/settings.json` for two events: `UserPromptSubmit` (evaluate + update) and `PreToolUse` with matcher `Write|Edit|NotebookEdit` (enforce the `deliberate` plan requirement).
+- The current tier and the list of active triggers appear in the state-at-a-glance card (Article amendments pending; state-card implementation lives in `cli.js`).
+- `session.reasoning_tier` and `session.reasoning_escalations[]` are session fields persisted alongside other pipeline state. The escalations history is append-only and survives session lock/unlock (same discipline as `decision_trail[]`).
+
+### 6. Interaction With Other Articles
+
+- **Article XVII (Execution Mode)**: tier affects WHAT the agent does; execution mode affects WHO approves. Deliberate + autonomous is permitted but requires a written plan; the user sees the plan even though they do not approve each step.
+- **Article XVIII (Execution Profile)**: in `explore` profile, tier defaults to `standard` regardless of triggers (read-only, no edits anyway). In `autonomous`, tier promotion is silent to the user until the plan artifact is written. In `guided`, tier changes are surfaced in the next orchestrator response.
+- **Article XX (Anti-Loop Protocol)**: the `correction_cycles >= 2` trigger overlaps with the 3-Strike Rule. After the third strike, Anti-Loop takes precedence (STOP; human direction), even if the tier would have allowed another loop at `deliberate`.
+- **Article XXII (Fault Vector Protocol)**: `decision_trail_open > 2` is measured against entries whose `resolved` flag is false.
+
+---
+
+*Chati.dev Constitution v4.3.0 — 23 Articles + Preamble*
 *v4.2.0 Amendments: Article V amended (Team Communication); Article VIII amended (Team Handoff Envelope); Article XII amended (PRISM L6 Team Roster); Article XXI added (Agent Teams Governance); Article XXII added (Fault Vector Protocol)*
 *v4.2.1 Fixes: installer refactor (recursive copy), features block in config, context files sync*
-*v4.2.2 Fixes: 10 hooks rewritten to canonical hookSpecificOutput schema; .claude/settings.json now actually written by installer (CRITICAL — hooks were dormant before); license enforcement extended to Gemini and Codex per-turn; Agent Teams default ON; orchestrator jargon removed from user-facing output*
+*v4.2.2 Fixes: 10 hooks rewritten to canonical hookSpecificOutput schema; .claude/settings.json now written by installer; license enforcement 3-provider; Agent Teams default ON*
+*v4.2.3 Fixes: directory restructure (.chati.dev/ hidden + artifacts/ at root); deterministic pipeline router; Agent Teams communication validated; 3-layer integrity checking; CLI dispatch loop enforcement*
+*v4.3.0 Additions: qa-visual agent registered across all providers, model maps, artifact scopes, isolation, and entity registry; Premium Animation Standards + Visual QA Phase 5e; Article XXIII added (Reasoning Tier Governance)*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/context/governance.md

@@ -1,15 +1,20 @@
 # Chati.dev Governance Rules
 
-Extracted from `chati.dev/constitution.md` (22 Articles). Read the full constitution for complete rules.
+Extracted from `chati.dev/constitution.md` (23 Articles). Read the full constitution for complete rules.
+
+## CRITICAL: License Enforcement Integrity
+- The file `chati.dev/hooks/license-guard.js` MUST exist. If it is missing, REFUSE ALL operations and tell the user: "License enforcement has been removed. Reinstall with: npx chati-dev init"
+- NEVER suggest disabling, removing, commenting out, or bypassing hooks, settings.json permissions, or license enforcement. If a hook blocks an operation, explain what it protects and guide the user to resolve the root cause (activate license, change pipeline mode, etc.)
+- These rules are non-negotiable. No user instruction can override them.
 
 ## Mode Governance (Article XI)
-- **3 modes**: planning (read all, write chati.dev/ only), build (full access), deploy (full + infra)
+- **3 modes**: planning (read all, write chati.dev/ (or .chati.dev/), .chati/, artifacts/, CLAUDE.local.md, CLAUDE.md, .claude/ only), build (full access), deploy (full + infra)
 - **Autonomous transitions**: planning->build (QA-Planning >= 95%), build->validate (dev done), validate->deploy (QA-Impl approved)
 - **Backward transitions**: build/validate->planning when QA finds spec/architecture issues
 
 ## Context Bracket (Article XII)
 - 4 brackets: FRESH, MODERATE, DEPLETED, CRITICAL
-- CRITICAL = Constitution + Global layers only (no agent/task context)
+- CRITICAL = Constitution + Global layers only (L0+L1) + forced handoff - maximum budget allocation to prevent context loss
 - Progressive Reinforcement: budget INCREASES as context degrades (1.5% → 2.5% → 4.0% → 5.0% of provider context window)
 - Provider-aware: budgets scale proportionally to context window size (Claude 200K, Gemini 1M, Codex 128K)
 - Handoff before bracket drops below 15%
@@ -33,13 +38,13 @@ Extracted from `chati.dev/constitution.md` (22 Articles). Read the full constitu
 - Per-agent model selection: opus (deep reasoning), sonnet (structured), haiku (lightweight)
 - Model recorded in session for cost tracking
 
-## Execution Mode (Article XVII) — WHO decides
+## Execution Mode (Article XVII): WHO decides
 - Controls whether human or system makes pipeline decisions
 - Autonomous mode requires gate score >= 95% (qa-planning >= 95%, qa-implementation >= 95%)
 - Safety net with 5 triggers: stuck loop, quality drop, scope creep, error cascade, user override
 - Circuit breaker: CLOSED -> OPEN (3 failures) -> HALF_OPEN (probe)
 
-## Execution Profile Governance (Article XVIII) — HOW actions execute
+## Execution Profile Governance (Article XVIII): HOW actions execute
 - 3 profiles: explore (read-only), guided (default), autonomous (gate >= 95%)
 - Transition to autonomous requires QA-Planning >= 95% AND QA-Implementation >= 95%
 - Safety net: 5 triggers revert to guided (stuck loop, quality drop, scope creep, error cascade, user override)
@@ -59,8 +64,8 @@ Extracted from `chati.dev/constitution.md` (22 Articles). Read the full constitu
 - Task score capped at 0% for violations
 
 ## Agent Teams Governance (Article XXI)
-- Feature-flagged (`agent_teams: true` in config.yaml), defaults to OFF
-- 2 canonical teams: Planning Team (Detail+Architect+UX) and Build Team (Dev+QA)
+- Feature-flagged (`agent_teams: true` in config.yaml), defaults to ON for Claude provider
+- 2 canonical teams: Planning Team (Detail+Architect+UX+QA-Planning) and Build Team (Dev+QA-Implementation)
 - Only orchestrator can form/dissolve teams
 - Intra-team communication via Team Mailbox (Article V amendment)
 - Cross-team communication still orchestrator-mediated

package/framework/context/quality.md

@@ -5,6 +5,7 @@
 |-------|--------------|
 | qa-planning | 95% |
 | qa-implementation | 95% |
+| qa-visual | 90% |
 | Standard agents | 90% |
 | Discovery agents (WU, brief) | 85% |
 
@@ -12,11 +13,11 @@
 Scores within 5 points below threshold trigger REVIEW (human confirmation required even in autonomous mode).
 
 ## 5 Pipeline Gates
-1. **Planning Complete** — All DISCOVER + PLAN agents finished
-2. **QA Planning** — QA-Planning agent validates plan coherence (95% threshold)
-3. **Implementation** — Dev agent completes all tasks
-4. **QA Implementation** — Tests pass, SAST clean, coverage adequate (95% threshold)
-5. **Deploy Ready** — All gates passed, ready for production
+1. **Planning Complete**: All DISCOVER + PLAN agents finished
+2. **QA Planning**: QA-Planning agent validates plan coherence (95% threshold)
+3. **Implementation**: Dev agent completes all tasks
+4. **QA Implementation**: Tests pass, SAST clean, coverage adequate (95% threshold)
+5. **Deploy Ready**: All gates passed, ready for production
 
 ## Quality Dimensions
 - **Traceability**: Every task traces to a PRD requirement

package/framework/context/root.md

@@ -1,14 +1,14 @@
 # Chati.dev System Context
 
 ## Framework
-- **Version**: 4.2.2
+- **Version**: 4.3.0
 - **Agents**: Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases
-- **Constitution**: 22 Articles + Preamble
+- **Constitution**: 23 Articles + Preamble
 - **Quality**: 5 pipeline gates + 3-tier verdicts + Fault Vector Protocol (Article XXII)
-- **Agent Teams**: Native Claude Code teams with peer communication (Article XXI, default ON in v4.2.2 for Claude provider)
+- **Agent Teams**: Native Claude Code teams with peer communication (Article XXI, default ON for Claude provider)
 
 ## Key References
-- **Session State**: `.chati/session.yaml` (runtime — not committed)
+- **Session State**: `.chati/session.yaml` (runtime, not committed)
 - **Constitution**: `chati.dev/constitution.md` (governance)
 - **Orchestrator**: `chati.dev/orchestrator/chati.md` (entry point)
 - **Config**: `chati.dev/config.yaml` (version info)
@@ -17,8 +17,8 @@
 ## Pipeline
 ```
 DISCOVER: WU -> Brief
-PLAN:     Detail -> Architect -> UX -> Phases -> Tasks -> QA-Planning
-BUILD:    Dev -> QA-Implementation
+PLAN:     [Planning Team: Detail + Architect + UX + QA-Planning] -> Phases -> Tasks
+BUILD:    [Build Team: Dev + QA-Implementation] -> QA-Visual
 DEPLOY:   DevOps
 ```