chati-dev 4.5.28 → 4.5.29

package/framework/agents/plan/tasks.md

@@ -13,8 +13,8 @@ You are the **Tasks Agent**, responsible for breaking phases into atomic, execut
 - **Duration**: 30-60 min
 - **Ratio**: 50% Human / 50% AI
 - **Absorbs**: SM (structured task creation, Given-When-Then criteria)
-- **Execution binding**: resolved at runtime by installation-v2 task routing; never self-select or downgrade
-- **Routing**: exact provider, model, and reasoning are bound by the signed task router
+- **Execution binding**: resolved at planning seal time by the signed installation-v2 task router, never by a hard-coded vendor default
+- **Routing**: each task declares its risk and independence need. The signed catalog then binds the exact build and review models and reasoning configuration.
 
 ## Required MCPs
 - None
@@ -199,6 +199,16 @@ After creating all tasks, run a critical self-review:
 Document findings and fix before presenting to user.
 ```
 
+### Step 3c: Execution Design, Routing, and Total Effort
+
+For every task, define the execution design before writing the JSON graph:
+
+1. Validate every dependency points to an existing earlier or parallel-safe task. There must be no self-dependency, duplicate edge, or cycle.
+2. Map at least one PRD requirement ID to `requirement_refs`. Reconcile the complete PRD requirement list. A requirement with no task is a planning defect.
+3. Set `routing_profile.risk_level` to `low`, `medium`, `high`, or `critical`, and set `required_independence_level` to `A`, `B`, or `C`. `A` requires an independent provider for review unless the selected installation cannot support it, in which case stop and ask for installation reconfiguration instead of weakening the task.
+4. Estimate the whole lifecycle, not only implementation. `effort_plan` must contain p50 and p80 minutes for AI build, AI review, an AI rework reserve, human active time, and human wait time. Its `total` is the exact sum of those components. Set `rework_margin_pct` explicitly, normally at least 10%.
+5. Do not name a vendor, model, or reasoning tier in the v2 source task graph. At the sealed handoff, the signed capability catalog selects and records `execution_binding` and `review_binding` from the selected installation providers. This keeps routing current when the catalog changes, without embedding personal model preferences in CHATI.
+
 ### Step 4: Validate & Present
 ```
 Validate all criteria, present to user for approval
@@ -207,16 +217,20 @@ Validate all criteria, present to user for approval
 ### Step 5: Produce the RAIL task graph
 
 When the project has a v2 installation, write the machine-readable task graph
-to `.chati/v2/planning/tasks.json`. This file is required before the Tasks
-agent can advance. It is the source used to create the sealed RAIL handoff.
+to `artifacts/6-Tasks/tasks.json`, within the Tasks agent's write scope.
+This candidate is required before the Tasks agent can advance. Do not write
+to `.chati`: the trusted orchestrator validates the candidate and atomically
+promotes its exact bytes to `.chati/v2/planning/tasks.json` for council review.
+Only council approval permits creation of the dispatchable sealed RAIL handoff.
 
 ```json
 {
-  "version": "1.0.0",
+  "version": "2.0.0",
   "source_artifacts": {
     "requirements_path": "artifacts/2-PRD/prd.md",
     "architecture_path": "artifacts/3-Architecture/architecture.md",
-    "qa_plan_path": "artifacts/7-QA/qa-plan.md"
+    "qa_plan_path": "artifacts/7-QA-Planning/qa-planning-report.md",
+    "task_details_path": "artifacts/6-Tasks/tasks.md"
   },
   "tasks": [{
     "id": "T1.1",
@@ -224,18 +238,26 @@ agent can advance. It is the source used to create the sealed RAIL handoff.
     "criteria": [{ "given": "the approved project baseline", "when": "the task is executed", "then": "the stated, verifiable outcome exists" }],
     "execution_scope_ref": "artifact://task-scope/T1.1",
     "routing_constraints_ref": "policy://routing/T1.1",
-    "execution_binding": {
-      "provider_id": "openai",
-      "harness_id": "codex",
-      "model_id": "the-model-selected-during-installation",
-      "reasoning_configuration": "high"
+    "routing_profile": {
+      "risk_level": "medium"
     },
+    "required_independence_level": "A",
+    "requirement_refs": ["FR-001"],
     "clickup_ref": "clickup://task/T1.1",
     "estimate": {
       "ai_processing": { "unit": "minutes", "value": 30 },
       "human_effort": { "unit": "minutes", "value": 10 },
       "uncertainty": "medium"
     },
+    "effort_plan": {
+      "ai_build": { "p50_minutes": 30, "p80_minutes": 45 },
+      "ai_review": { "p50_minutes": 10, "p80_minutes": 15 },
+      "ai_rework_reserve": { "p50_minutes": 6, "p80_minutes": 12 },
+      "human_active": { "p50_minutes": 10, "p80_minutes": 15 },
+      "human_wait": { "p50_minutes": 0, "p80_minutes": 10 },
+      "rework_margin_pct": 20,
+      "total": { "p50_minutes": 56, "p80_minutes": 97 }
+    },
     "requires_browser": false
   }]
 }
@@ -244,9 +266,16 @@ agent can advance. It is the source used to create the sealed RAIL handoff.
 Rules:
 
 - Preserve the same task IDs, dependencies and Given-When-Then criteria in the prose artifact and JSON task graph.
+- Write each task's explicit scope and its `execution_scope_ref` label in that task's section of `tasks.md`. A URI alone is not an execution scope. The compiler freezes this document, source artifacts, graph and criterion text inside the handoff; execution, review, rework and adjudication consume those exact bytes, not mutable files at the old paths.
+- Keep the serialized frozen Planning bundle below 1,000,000 UTF-8 bytes. The compiler rejects missing, corrupt or oversized material instead of omitting or truncating it.
+- For local certified verification, provide `verification_checks` on every task. Each check has exactly `check_id`, `kind` (`ci` or `acceptance`), zero-based `criterion_indices`, `executable_binding` (canonical absolute `executable_path` plus its observed SHA-256), literal `args`, `script_path`, and `timeout_ms` (1 to 1,800,000). Use an explicitly identified interpreter that reads the frozen script from stdin. Do not select commands from a builder-modified package file automatically.
+- Write check scripts under `artifacts/6-Tasks/verification/`. Include at least one CI check with empty criterion indices and acceptance checks covering every criterion. Every listed check is mandatory; do not add shell/env overrides, ignored failures or a caller-supplied verdict. The compiler freezes script bytes and tool identities into the handoff for council approval. Local check results must not be labeled remote CI; browser criteria still need real browser evidence.
 - `clickup_ref` is mandatory for the internal profile. It is an opaque mapping, not permission to mutate ClickUp directly.
-- `execution_binding` is mandatory. Select only a provider, harness, model and reasoning configuration present in `.chati/v2/installation.json`; choose the best eligible binding for that task. Never name an unselected vendor or rely on an implicit fallback.
+- `routing_profile`, `required_independence_level`, `requirement_refs`, and the complete `effort_plan` are mandatory in v2. The compiler binds and records the exact selected `execution_binding` and `review_binding`; no task may invent a vendor or rely on an implicit fallback.
 - If `requires_browser` is true, provide a complete task-specific `browser_policy`. A global MCP configuration is not sufficient.
+- For the local real-browser observer, also provide `browser_verification` with exactly `schema_version: 1`, `tool_id: "chati-playwright-api-v1"`, `evidence_kind: "dom-assertions"`, zero-based `criterion_indices` covering all task criteria, and `observation`. The observation has exactly `application`, `browser`, `hostname`, `ready_path`, `timeout_ms`, and `steps`. Application fields are a native `executable_binding`, literal `args`, a `script_path` under `artifacts/6-Tasks/verification/`, and a port from 1024 to 65535. The startup script runs against an isolated exact-commit copy with `PORT` and `HOST`, without host credentials or networking. Browser fields are its observed native Chromium `executable_binding` and exact installed `playwright_version`.
+- This observer requires policy `mode: "unauthenticated"`, `tool: "approved-other"`, and `approved_tool_id: "chati-playwright-api-v1"`. The scenario hostname must belong to the approved domains and match the canonical execution delegation. Preserve required action confirmation and data classification. Supported steps are `navigate` with local `path`; `click` or `assert_visible` with `selector`; `fill` or `assert_text` with `selector` and `text`. Start with navigation, include a real assertion, and do not supply JavaScript evaluation, arbitrary environment, profile or sandbox overrides.
+- The compiler freezes the startup bytes and scenario into `browser_verification_plan`. Local `rail-verify` observes the browser and returns the existing certified browser manifest only after protected artifact persistence. The supported `internal-30d` retention class means a fixed 30-day logical lifetime with opportunistic physical collection, not guaranteed erasure while the CLI is stopped. DOM assertions and a values-redacted structure are not visual-quality evidence. Never downgrade an authenticated or visual requirement to this capability merely to pass verification; unsupported requirements remain blockers.
 - Do not infer missing execution scope, estimates, dependencies, ClickUp refs or browser policy. Return to planning and make the information explicit.
 
 ---
@@ -390,7 +419,7 @@ Wave 3 (Sequential):
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/tasks-handoff.md`
+Save to: `artifacts/handoffs/tasks/tasks-handoff.md`
 
 ### Session Update
 ```yaml
@@ -400,10 +429,9 @@ agents:
     score: {calculated}
     criteria_count: 10
     completed_at: "{timestamp}"
-current_agent: dev
 ```
 
-> **In Team Mode (Article XXI):** QA-Planning already ran inside the Planning Team before Tasks. After the task graph is valid and sealed, the orchestrator returns `rail_execute`. Do not write `current_agent: dev`, create a Build Team, or route to a DevOps agent.
+> QA-Planning already ran before Tasks. After the task graph is valid and sealed, the automatic Execution Design Council must accept the frozen artifacts before the orchestrator returns `rail_execute`. The orchestrator owns `current_agent` from here: never write `current_agent: dev`, create a Build Team, or route to a DevOps agent.
 
 ---
 
@@ -415,7 +443,7 @@ current_agent: dev
 3. Adjust task sizes or priorities
 ```
 
-> **In Team Mode (Article XXI):** QA-Planning ran inside the Planning Team, not after Tasks. The orchestrator advances exclusively to the sealed RAIL handoff after Tasks completes.
+> **In Team Mode (Article XXI):** QA-Planning ran inside the Planning Team, not after Tasks. The orchestrator advances exclusively to the sealed RAIL handoff after Tasks completes and the Execution Design Council accepts.
 
 ---
 
@@ -491,13 +519,13 @@ Rules:
 ### Receives
 - **From**: Phases agent
 - **Artifact**: `artifacts/5-Phases/phases.md` (phase breakdown, wave structure)
-- **Handoff file**: `artifacts/handoffs/phases-handoff.md`
+- **Handoff file**: `artifacts/handoffs/phases/phases-handoff.md`
 - **Expected content**: Phase breakdown summary, MVP scope, dependency map, wave structure, timeline estimates, traceability matrix (PRD to Phases)
 
 ### Sends
 - **To**: QA-Planning agent
 - **Artifact**: `artifacts/6-Tasks/tasks.md`
-- **Handoff file**: `artifacts/handoffs/tasks-handoff.md`
+- **Handoff file**: `artifacts/handoffs/tasks/tasks-handoff.md`
 - **Handoff content**: Task breakdown summary, total task count by phase, size distribution, execution order with parallelization markers, traceability matrix (PRD to Phases to Tasks), self-validation score
 
 ---
@@ -557,7 +585,7 @@ signals. The signed router owns the exact provider and model selection.
 ## Parallelization
 
 - **Can run in parallel with**: No other agent (sequential dependency - requires Phases as input)
-- **Cannot run in parallel with**: Phases agent (upstream dependency), QA-Planning agent (downstream dependency - requires tasks as input)
+- **Cannot run in parallel with**: Phases agent (upstream dependency), Execution Design Council (downstream gate over the finished task graph)
 - **Internal parallelization**: Task breakdown for different phases can proceed concurrently once all phase definitions are read. Acceptance criteria writing can be parallelized across independent tasks.
 - **Merge point**: Tasks agent completes after the Planning Team dissolves. QA-Planning runs inside the Planning Team (not after Tasks).
 

package/framework/agents/plan/ux-brand-architect.md

@@ -363,7 +363,7 @@ scaffold — the user would have to request it manually and the pipeline ships
 bespoke animation code that duplicates the templates.
 
 Append a `## Scaffold Signals` section to your handoff file
-(`artifacts/handoffs/ux-handoff.md`). Schema (one entry per preset):
+(`artifacts/handoffs/ux/ux-handoff.md`). Schema (one entry per preset):
 
 ```markdown
 ## Scaffold Signals

package/framework/agents/plan/ux.md

@@ -47,6 +47,30 @@ Coordinate the design experience by activating 3 specialist sub-agents in sequen
 4. Read Architecture: `artifacts/3-Architecture/architecture.md` (tech constraints)
 5. Acknowledge inherited context
 
+### Visual applicability before specialist activation
+
+The canonical Brief may explicitly declare `visual_quality: not_applicable`
+and `visual_references: []` for a product with no visual/rendering surface.
+Only the runtime's verification of the current Discovery council approval
+authorizes that exception. UX cannot waive requirements by writing its own
+assessment, changing the Brief, or counting absent artifacts as passed checks.
+Missing, ambiguous, rejected or conflicting declarations retain the visual
+workflow below; premium requirements or a visual reference analysis conflict
+with this exception. Return the real conflict rather than creating dummy HTML.
+
+For this approved non-visual branch only, replace the visual specialist steps
+with a scoped `artifacts/4-UX/ux-specification.md`: document applicable caller
+flows, error/interaction contracts, upstream traceability, each excluded visual
+criterion and its reason, and conditions that would reopen visual work. Keep
+the complete canonical UX handoff with summary and outputs. Do not spawn visual
+specialists or fabricate brandbooks, tokens, component discovery or screenshots.
+The mandatory visual artifacts and 21-criterion visual rubric below apply to
+visual products. In the non-visual branch, exclude justified visual N/A criteria
+from the denominator, never mark them PASS; retain the >=90% threshold on all
+applicable criteria. QA must independently check scope and those exclusions.
+This branch does not waive QA-Planning, councils, task verification, RAIL or any
+separately required framework browser test. A runtime N/A is not a visual PASS.
+
 **Agent-Driven Opening:**
 > "I'll coordinate the design experience through 3 specialists: Brand Architect (visual identity), UX Researcher (user flows), and Component Engineer (components + accessibility). Starting with brand identity to set the visual direction."
 
@@ -229,12 +253,12 @@ If score < 90%, identify which sub-agent's criteria failed and request correctio
 ### Receives
 - **From**: Architect agent (and Brief indirectly)
 - **Artifacts**: `architecture.md`, `brief-report.md`
-- **Handoff**: `artifacts/handoffs/architect-handoff.md`
+- **Handoff**: `artifacts/handoffs/architect/architect-handoff.md`
 
 ### Sends
 - **To**: Phases agent
 - **Artifacts**: All outputs listed above
-- **Handoff**: `artifacts/handoffs/ux-handoff.md`
+- **Handoff**: `artifacts/handoffs/ux/ux-handoff.md`
 - **Content**: UX specification summary, Design System token overview, screen inventory, component complexity assessment, accessibility compliance status, self-validation score
 
 ---

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

@@ -64,7 +64,7 @@ Before beginning test execution:
 
 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
+(artifacts/handoffs/qa-implementation/qa-implementation-handoff.md) under "## Decision Trail" and
 "## Resolved Decision Trail" sections. The CLI-managed session manager merges these when you advance.
 ```
 
@@ -255,7 +255,7 @@ Routing Enforcement:
 
 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.
+(artifacts/handoffs/qa-implementation/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-managed session manager merges Decision Trail entries from your handoff when you advance.
 
@@ -607,7 +607,7 @@ Save to: `artifacts/9-QA-Implementation/qa-implementation-report.md`
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/qa-implementation-handoff.md`
+Save to: `artifacts/handoffs/qa-implementation/qa-implementation-handoff.md`
 
 ### Session Update
 ```yaml
@@ -743,14 +743,14 @@ Threshold: >= 95% (15/16 minimum). Canonical value: chati.dev/data/qa-rubrics.ya
 
 ### Receives
 - **From**: Dev agent
-- **Artifact**: Implementation code + `artifacts/handoffs/dev-handoff.md`
-- **Handoff file**: `artifacts/handoffs/dev-handoff.md`
+- **Artifact**: Implementation code + `artifacts/handoffs/dev/dev-handoff.md`
+- **Handoff file**: `artifacts/handoffs/dev/dev-handoff.md`
 - **Expected content**: Implementation summary, task completion status, per-task scores, commit hashes, blocker resolutions, self-critique results
 
 ### Sends
 - **To**: DevOps agent (DEPLOY phase transition)
 - **Artifact**: `artifacts/9-QA-Implementation/qa-implementation-report.md`
-- **Handoff file**: `artifacts/handoffs/qa-implementation-handoff.md`
+- **Handoff file**: `artifacts/handoffs/qa-implementation/qa-implementation-handoff.md`
 - **Handoff content**: Validation result (APPROVED/NEEDS CORRECTION), weighted score, test results, security scan summary, code review findings, acceptance criteria verification, adversarial review findings, correction history, state transition to DEPLOY
 
 ---
@@ -851,7 +851,7 @@ In Build Team, the orchestrator assigns you work per wave:
 **Wave 0 (no completed tasks to review yet):**
 1. Run baseline lint + typecheck on the project
 2. Set up test infrastructure if needed (test runner config, coverage setup)
-3. Review `artifacts/handoffs/qa-planning-handoff.md` to prepare your review checklist
+3. Review `artifacts/handoffs/qa-planning/qa-planning-handoff.md` to prepare your review checklist
 4. Write a `qa_baseline_ready` JSON file to the mailbox with your baseline results
 5. STOP and return your baseline summary
 
@@ -872,7 +872,7 @@ In Build Team, the orchestrator assigns you work per wave:
    - PRD requirement coverage vs `artifacts/2-PRD/prd.md`
    - Security scan
    - Performance review
-2. Write your final handoff to `artifacts/handoffs/qa-implementation-handoff.md`
+2. Write your final handoff to `artifacts/handoffs/qa-implementation/qa-implementation-handoff.md`
 
 You do NOT poll the mailbox. The orchestrator tells you exactly what to review each wave.
 Per-task review respects the 3-correction-loop cap per task (Article X).

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

@@ -7,7 +7,7 @@ You are the **QA-Planning Agent**, the quality gate between PLANNING (planning)
 ## Identity
 
 - **Role**: Planning Quality Gate & Criteria Supervisor
-- **Pipeline Position**: 4th Planning Team member (activates after Detail, Architect, UX complete) | Sequential fallback: 8th (after Tasks)
+- **Pipeline Position**: installation-v2: after Detail, Architect and UX, before Phases and Tasks (teams disabled) | Legacy Team Mode: 4th Planning Team member | Sequential fallback: 8th (after Tasks), legacy only
 - **Category**: Quality
 - **Question Answered**: IS everything traceable and rigorous?
 - **Duration**: 15-30 min (automated validation)
@@ -32,6 +32,38 @@ Validate that every Brief problem traces through to a testable task, no requirem
 
 ## On Activation
 
+### Installation-v2 Stage Scope
+
+Apply this scope only when the activation prompt identifies installation-v2.
+It governs all artifact reads, traceability chains, penalties, dimensional checks,
+self-validation criteria, report templates and completion guidance below.
+Without v2 activation, retain the legacy sequential and Team Mode behavior.
+
+Review the current WU, Brief, PRD, Architecture and UX artifacts and handoffs.
+Missing or contradictory requirements in those current inputs remain findings
+under the existing QA criteria. Phases and Tasks are downstream of this stage.
+When they have not run, their absence alone is not a current-stage gap or penalty.
+Record checks awaiting their outputs (including Chains 2-4 and task-specific
+acceptance or animation checks) as pending downstream verification, never as a completed PASS.
+If downstream artifacts already exist, inspect relevant evidence and report
+defects or inconsistencies; their presence does not imply completion or approval
+and does not replace mandatory downstream validation. Do not lower the existing
+rubric threshold or dismiss defects in current Planning inputs.
+
+Preserve each downstream obligation with its owner and required evidence.
+Phases must still assign the PRD requirements. Tasks must still encode and freeze
+the complete task decomposition, acceptance criteria and required verification
+contracts; the compiler must validate the executable task graph. The
+Execution Design council must review the resulting Phases, Tasks and compiled
+plan. RAIL execution, independent review, verification and acceptance remain required.
+
+An APPROVED QA result is input to the normal Planning council, not permission
+to enter BUILD. The parent advances through Phases, Tasks/compiler and Execution
+Design before RAIL. The legacy direct-to-BUILD guidance and post-Tasks sequential
+validation below do not change that v2 route or authorize a gate bypass.
+
+### Collect the Artifacts for the Active Stage
+
 1. Read ALL PLANNING artifacts:
    - `artifacts/0-WU/` (wu report)
    - `artifacts/1-Brief/brief-report.md`
@@ -43,7 +75,29 @@ Validate that every Brief problem traces through to a testable task, no requirem
 2. Read ALL handoffs: `artifacts/handoffs/`
 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.
+**Artifact language:** Validate all authored prose, including both handoff layers
+(Summary and Deep Context), as English. Clearly identified quoted original input,
+such as Brain Dump (Raw), stays verbatim in its source language and is not a language violation.
+Verify its source attribution and correspondence to retained input; a quote label
+or code fence does not exempt newly authored summaries or analysis. Do not require
+translation of original input. Conversation and the terminal handoff envelope use
+the session language, not the artifact language. Evaluate this distinction
+semantically, not by counting foreign words in identifiers, citations or raw input.
+
+**Non-visual scope:** When the current Discovery-approved Brief explicitly
+declares `visual_quality: not_applicable` and `visual_references: []`, review
+the scoped UX specification and its complete handoff, not fabricated brandbook
+HTML. Runtime verification of that exact approved Brief is required for the UX
+advance exception; the agent's own N/A assessment does not grant it. Independently
+check every excluded visual criterion against Brief, PRD and Architecture.
+Conflicting visual requirements, references or a newly introduced rendering
+surface require correction/review of the upstream scope, not silent exemption.
+N/A visual criteria are excluded from the denominator, never counted as PASS.
+All applicable functional, coherence, traceability and quality checks remain.
+Do not waive Planning/execution-design councils, RAIL, CI/acceptance or any
+separately required framework browser validation.
+
+**Legacy 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. Installation-v2 follows its Stage Scope above even with teams disabled.
 
 ---
 
@@ -290,7 +344,7 @@ Save to: `artifacts/7-QA-Planning/qa-planning-report.md`
 ```
 
 ### Handoff (Protocol 5.5)
-Save to: `artifacts/handoffs/qa-planning-handoff.md`
+Save to: `artifacts/handoffs/qa-planning/qa-planning-handoff.md`
 
 ### Session Update
 ```yaml
@@ -426,7 +480,7 @@ Threshold: >= 95% (10/10 minimum, no criteria may fail). Canonical value: chati.
 ### Sends
 - **To**: ALL Planning Team members via mailbox (qa_review_finding messages sent to detail + architect + ux simultaneously, so corrections trigger cross-review among all 3)
 - **Artifact**: `artifacts/7-QA-Planning/qa-planning-report.md`
-- **Handoff file**: `artifacts/handoffs/qa-planning-handoff.md`
+- **Handoff file**: `artifacts/handoffs/qa-planning/qa-planning-handoff.md`
 - **Handoff content**: Validation result (APPROVED/NEEDS CORRECTION), score, traceability summary, penalties applied, adversarial review findings, correction history, state transition to BUILD
 
 ---

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

@@ -77,7 +77,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`
+1. Read handoff from Dev agent: `artifacts/handoffs/dev/dev-handoff.md`
 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)
@@ -376,7 +376,7 @@ All screenshots saved to: /tmp/visual-qa/
 ```
 
 ### Handoff
-Save to: `artifacts/handoffs/qa-visual-handoff.md`
+Save to: `artifacts/handoffs/qa-visual/qa-visual-handoff.md`
 
 ---
 
@@ -384,13 +384,13 @@ Save to: `artifacts/handoffs/qa-visual-handoff.md`
 
 ### Receives
 - **From**: Dev agent
-- **Artifact**: `artifacts/handoffs/dev-handoff.md`
+- **Artifact**: `artifacts/handoffs/dev/dev-handoff.md`
 - **Expected content**: Affected routes, animation library installation confirmation
 
 ### Sends
 - **To**: QA-Implementation agent (provides visual evidence for Phase 5d + 5e)
 - **Artifact**: `artifacts/9-QA-Implementation/qa-visual-report.md`
-- **Handoff file**: `artifacts/handoffs/qa-visual-handoff.md`
+- **Handoff file**: `artifacts/handoffs/qa-visual/qa-visual-handoff.md`
 - **Handoff content**: Visual verdict (APPROVED/NEEDS CORRECTION), score, screenshot paths, animation check results, brandbook findings
 
 ---

package/framework/config.yaml

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

package/framework/constitution.md

@@ -156,7 +156,9 @@ Every agent in Chati.dev:
 
 ## Article VII: English-Only Documentation
 
-All system documentation, agent definitions, templates, artifacts, handoffs, and generated content MUST be written in English. No exceptions.
+All agent-authored prose in system documentation, agent definitions, templates,
+artifacts, handoffs, and generated content MUST be written in English.
+Both handoff layers, including Summary and Deep Context, follow this rule.
 
 This applies to:
 - Agent command files (`chati.dev/agents/`)
@@ -170,6 +172,13 @@ This applies to:
 This does NOT apply to:
 - Agent-user conversation (follows the validated `language` value supplied by router context)
 - Console output, prompts, guidance, error messages (interaction language)
+- Clearly identified quoted original input, such as Brain Dump (Raw), preserved
+  verbatim in its source language for traceability. This is not an exemption for authored prose:
+  summaries, analysis and surrounding explanations remain English. A quote label
+  or code fence alone does not make newly authored content original input.
+
+The localized terminal handoff envelope is a visible response, not a handoff
+artifact. Do not copy its localized prose into the Markdown handoff file.
 
 **Rationale:** Portability, team collaboration, tooling compatibility.
 
@@ -184,6 +193,8 @@ Every agent MUST read the previous agent's handoff upon activation.
 
 Handoffs are saved to `artifacts/handoffs/` and follow a two-layer structure:
 
+Agent handoffs use `artifacts/handoffs/{agent}/{agent}-handoff.md`. Each agent owns only its subdirectory, including temporary files required by atomic editors. Flat `{agent}-handoff.md` files remain read-only legacy inputs, used only when the new path is absent. An invalid new output must not be replaced by stale legacy content. Team envelope paths remain unchanged.
+
 ### Layer 1: Summary (mandatory, max 150 lines)
 Contains:
 - Mission completed (1-2 sentences)

package/framework/context/governance.md

@@ -31,7 +31,8 @@ Extracted from `chati.dev/constitution.md` (25 Articles). Read the full constitu
 - Health check validates registry vs filesystem
 
 ## Session Lock (Article XV)
-- When session is active, ALL messages route through orchestrator
+- When session is active, ALL user messages in the user-facing coordinator route through orchestrator
+- A provider subprocess already delegated an agent/task executes only that assignment and returns its result to the parent. It must not recursively activate the entry skill/router, dispatch pipeline agents or advance/recover session state. Runtime checks and tool permissions remain unchanged.
 - Only the enabled harness's native Chati exit command can deactivate the session
 - Lock state is mirrored to each enabled harness's native local lock file
 

package/framework/context/root.md

@@ -1,7 +1,7 @@
 # Chati.dev System Context
 
 ## Framework
-- **Version**: 4.5.28
+- **Version**: 4.5.29
 - **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)
@@ -25,3 +25,5 @@ RELEASE:  Evidence gate -> Explicit human authorization -> External action
 
 ## How to Use
 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.
+
+These entry steps belong to the user-facing coordinator. A provider subprocess already launched with an agent/task assignment is a delegated worker: use its supplied canonical context, execute only the assigned scope and return the required result envelope to the parent. Do not recursively activate the Chati skill/router, dispatch pipeline agents or advance/recover session state. This role distinction does not grant permissions or bypass runtime checks.

package/framework/domains/constitution.yaml

@@ -37,7 +37,7 @@ rules:
     priority: normal
 
   - id: art-vii
-    text: "All documentation and artifacts must be in English."
+    text: "All authored prose in documentation and both handoff layers must be English; clearly identified quoted original input stays verbatim in its source language, not newly authored prose disguised as a quote."
     priority: high
 
   - id: art-viii

package/framework/domains/global.yaml

@@ -11,7 +11,7 @@ rules:
     priority: normal
 
   - id: artifacts-english
-    text: "All artifacts (PRD, architecture docs, task definitions) must be in English."
+    text: "All authored prose in artifacts and both handoff layers must be English; clearly identified quoted original input stays verbatim in its source language. A quote label does not exempt authored analysis."
     priority: high
 
   - id: interaction-lang

package/framework/domains/workflows/standard-flow.yaml

@@ -4,10 +4,15 @@
 
 steps:
   - brief
+  - council-discovery
   - detail
   - architect
-  - tasks
+  - ux
   - qa-planning
+  - council-planning
+  - phases
+  - tasks
+  - council-execution-design
   - rail
   - release
 
@@ -16,14 +21,8 @@ rules:
     text: "Standard Flow targets 2-5 requirements. Escalate to full pipeline if scope exceeds this range."
     priority: critical
   - id: sf-quality
-    text: "QA-Planning approval and independent RAIL review are mandatory. Score >= 95% is required."
+    text: "QA-Planning approval, the automatic cross-provider planning council, and independent RAIL review are mandatory. Score >= 95% is required."
     priority: critical
-  - id: sf-no-ux-skip
-    text: "UX agent is excluded. If design-heavy requirements surface, escalate to full pipeline."
-    priority: high
-  - id: sf-no-phases
-    text: "Phases agent is excluded. Tasks agent handles scope decomposition directly from PRD + Architecture."
-    priority: high
   - id: sf-escalation-up
     text: "If architect discovers multi-service complexity or QA finds UX gaps, offer escalation to full pipeline."
     priority: high

package/framework/hooks/advance-trigger.js

@@ -8,7 +8,7 @@
  * deterministically — without depending on Claude remembering to call advance.
  *
  * Trigger condition: the Write tool just wrote a file at
- *   artifacts/handoffs/<agent>-handoff.md
+ *   artifacts/handoffs/<agent>/<agent>-handoff.md (or a legacy flat path)
  * where the handoff's YAML frontmatter declares `status: completed` and
  * contains `score: <N>`.
  *
@@ -87,7 +87,8 @@ async function main() {
   // Match agent handoff files in either layout:
   //   <root>/artifacts/handoffs/<agent>-handoff.md
   //   <root>/.chati.dev/artifacts/handoffs/<agent>-handoff.md
-  const handoffMatch = filePath.match(/artifacts\/handoffs\/([a-z0-9-]+)-handoff\.md$/);
+  const handoffMatch = filePath.match(/artifacts\/handoffs\/([a-z0-9-]+)\/\1-handoff\.md$/)
+    || filePath.match(/artifacts\/handoffs\/([a-z0-9-]+)-handoff\.md$/);
   if (!handoffMatch) return;
   const agent = handoffMatch[1];
 

package/framework/hooks/brief-validator.js

@@ -33,7 +33,7 @@ async function main() {
   process.stdout.write('{}\n');
 
   if (toolName !== 'Write') return;
-  if (!filePath.endsWith('handoffs/brief-handoff.md')) return;
+  if (!/artifacts\/handoffs\/(?:brief\/)?brief-handoff\.md$/.test(filePath)) return;
 
   // Validate brief-report.md
   const reportCandidates = [

package/framework/hooks/post-dev.js

@@ -114,7 +114,7 @@ export function decideSpawn(ctx) {
   if (!ctx.filePath) return null;
 
   // Match only dev-handoff.md in the canonical paths.
-  const handoffMatch = ctx.filePath.match(/artifacts\/handoffs\/dev-handoff\.md$/);
+  const handoffMatch = ctx.filePath.match(/artifacts\/handoffs\/(?:dev\/)?dev-handoff\.md$/);
   if (!handoffMatch) return null;
 
   // Read the handoff to confirm status=completed and score passes threshold.

package/framework/hooks/team-quality-gate.js

@@ -21,16 +21,19 @@ const AGENT_ARTIFACT_SCOPES = {
   detail: [
     'artifacts/2-PRD/',
     'artifacts/handoffs/detail-',
+    'artifacts/handoffs/detail/',
     'prd.md',
   ],
   architect: [
     'artifacts/3-Architecture/',
     'artifacts/handoffs/architect-',
+    'artifacts/handoffs/architect/',
     'architecture.md',
   ],
   ux: [
     'artifacts/4-UX/',
     'artifacts/handoffs/ux-',
+    'artifacts/handoffs/ux/',
     'ux-specification.md',
     'brandbook.md',
     'brandbook.html',
@@ -52,17 +55,21 @@ const AGENT_ARTIFACT_SCOPES = {
     '__tests__/',
     'artifacts/8-Implementation/',
     'artifacts/handoffs/dev-',
+    'artifacts/handoffs/dev/',
   ],
   'qa-planning': [
     'artifacts/7-QA-Planning/',
-    'artifacts/handoffs/qa-planning',
+    'artifacts/handoffs/qa-planning-',
+    'artifacts/handoffs/qa-planning/',
   ],
   'qa-implementation': [
     'artifacts/9-QA-Implementation/',
     'artifacts/handoffs/qa-implementation-',
+    'artifacts/handoffs/qa-implementation/',
   ],
   'qa-visual': [
-    'artifacts/handoffs/qa-visual',
+    'artifacts/handoffs/qa-visual-',
+    'artifacts/handoffs/qa-visual/',
   ],
 };
 

package/framework/i18n/en.yaml

@@ -23,6 +23,7 @@ installer:
   llm_provider_label: "AI Provider"
   ide_selection_title: "Select your IDEs / CLIs (multiple allowed):"
   provider_selection_title: "Which AI providers will you use?"
+  council_providers_required: "Select at least two distinct providers capable of review for the required quality council."
   editor_selection_title: "Which editor IDEs should get rules files? (optional)"
   provider_claude_hint: "Anthropic official CLI"
   provider_gemini_hint: "Google AI terminal agent"