chati-dev 4.3.0 → 4.4.0

package/README.md

@@ -128,8 +128,10 @@ The system saves your full session state (pipeline position, current agent, deci
 |---------|--------------|
 | **Specialized Agents** | Each agent has a defined mission, success criteria, and handoff protocol. Not one AI trying to do everything |
 | **Agent Teams** | Planning Team (Detail + Architect + UX + QA-Planning) and Build Team (Dev + QA-Implementation) with Wave-Based Pipeline. Teams work in parallel with peer-to-peer communication, cross-review, and intra-team quality assurance. No single agent bottleneck |
-| **Visual QA** | QA-Visual agent validates the visual experience: screenshots at 5 scroll positions, hover states, GSAP/Lenis verification, brandbook compliance. Powered by Playwright. |
-| **Premium Animations** | GSAP + ScrollTrigger + Lenis as mandatory stack for UI projects. Every page has scroll reveals, micro-interactions, and smooth scrolling. |
+| **Visual QA** | QA-Visual scores the rendered UI against an 8-dimension rubric (layout, typography, motion, interaction, color, spacing, accessibility, performance) with an anti-slop catalog and a spring-motion veto (linear easing and `transition: all` are rejected). Screenshots at multiple scroll positions, hover states, and brandbook compliance, powered by Playwright. |
+| **Premium Motion** | Premium motion is required for UI projects, with cubic-bezier easing and full reduced-motion support. The visual gate is animation-stack aware: the motion-premium presets use GSAP + Lenis, the saas-dashboard preset uses framer-motion. |
+| **Scaffold Presets** | Premium starting points applied at build time: motion-premium and motion-premium-3d for animated showcase sites, saas-dashboard for a token-driven app shell (sidebar, sortable data table, KPI cards, a Cmd+K command palette). |
+| **Execution Kinds** | A task declares how it executes. Deterministic dev tasks (lint, tests, file and schema checks) run as zero-LLM scripts through whitelisted executors instead of spending an agent turn. Feature-flagged, off by default, fully back-compatible. |
 | **Multi-CLI Architecture** | Choose your AI provider at install time: Claude, Gemini, or Codex. Each agent gets the optimal model for that provider |
 | **Quality Gates** | Every phase is validated before moving forward, including QA-Visual for visual quality. 3-tier verdicts: APPROVED, NEEDS_REVISION, or BLOCKED |
 | **Fault Vector Protocol** | Root Layer Routing classifies bugs by origin (INTENT/SPEC/CODE/DEFER). Evidence-Bound Verdicts, Decision Trail, and Echo Detection prevent cyclical rework |
@@ -137,7 +139,7 @@ The system saves your full session state (pipeline position, current agent, deci
 | **Session Lock** | Once activated, you stay inside the system. No accidentally "falling out" into generic AI mode |
 | **Multi-Terminal** | Autonomous agents run in parallel. Planning Team (Detail + Architect + UX + QA-Planning) and Build Team (Dev + QA-Implementation) coordinate via peer-to-peer mailbox |
 | **Memory System** | The system learns from mistakes. Gotchas are captured automatically and recalled when relevant |
-| **Execution Profiles** | Three profiles: explore (read-only), guided (default), autonomous (gate >= 95%). Includes safety net and circuit breaker |
+| **Execution Mode** | Two modes: interactive (default) and autonomous (gate >= 95%). Safety reversion to interactive on stuck loop, quality drop, scope creep, error cascade, or user override (Article XVII) |
 | **IDE-Agnostic** | Works with Claude Code, VS Code, Cursor, Gemini CLI, Codex CLI, and AntiGravity |
 | **4 Languages** | Interface supports English, Portuguese, Spanish, and French. Artifacts are always generated in English |
 | **Supply Chain Security** | Every file is cryptographically signed (Ed25519). Tampered packages are blocked on install |
@@ -190,17 +192,16 @@ Prompts are piped via stdin for all providers. You can override individual agent
 
 ---
 
-## Execution Profiles
+## Execution Mode
 
-Three profiles control how much autonomy agents have:
+Two modes control how much autonomy agents have:
 
-| Profile | Behavior | When to use |
-|---------|----------|-------------|
-| **explore** | Read-only. Agents analyze but don't modify files | Understanding a new codebase |
-| **guided** | Default. Agents propose changes, you approve | Normal development workflow |
+| Mode | Behavior | When to use |
+|------|----------|-------------|
+| **interactive** | Default. Agents propose changes, you approve | Normal development workflow |
 | **autonomous** | Agents execute without confirmation (quality gates >= 95%) | Trusted pipelines with high quality scores |
 
-The system starts in `guided` mode. Transition to `autonomous` requires both QA gates scoring >= 95%. A safety net with 5 triggers (stuck loop, quality drop, scope creep, error cascade, user override) automatically reverts to guided mode when needed.
+The system starts in `interactive` mode. Transition to `autonomous` requires both QA gates scoring >= 95%. Safety reversion takes the pipeline back to interactive on a stuck loop, quality drop, scope creep, error cascade, or user override (Article XVII).
 
 ---
 
@@ -274,13 +275,13 @@ Three systems operate transparently behind the pipeline:
 
 | System | What it does |
 |--------|-------------|
-| **Context Engine (PRISM)** | Injects the right context at the right time. 6 layers of context (from constitution rules down to keyword-matched domain rules). Uses Progressive Reinforcement: as context degrades, injection budgets INCREASE (1.5% to 5.0% of provider context window). Provider-aware for Claude (200K), Gemini (1M), and Codex (128K). |
+| **Context Engine (PRISM)** | Injects the right context at the right time. 6 layers of context (from constitution rules down to keyword-matched domain rules). Uses Progressive Reinforcement: as context degrades, injection budgets INCREASE (1.5% to 5.0% of provider context window). Provider-aware for Claude (1M), Gemini (1M), and Codex (128K). |
 | **Memory System (RECALL)** | Remembers decisions, gotchas, and lessons across sessions. Organized into 4 sectors: what happened (episodic), what we know (semantic), how we do things (procedural), and what we learned (reflective). |
 | **Decision Engine (COMPASS)** | Before creating something new, checks if a similar component already exists. Decides whether to reuse, adapt, or create from scratch. Keeps a registry of all project entities. |
 
 ### Constitution
 
-The system is governed by a **23-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
+The system is governed by a **25-article Constitution** that enforces agent behavior, quality standards, security, and system integrity:
 
 - **Agent Governance** - Every agent has a defined mission, scope, and success criteria
 - **Quality Standards** - Minimum 95% score on quality gates. 3-tier verdicts (APPROVED / NEEDS_REVISION / BLOCKED)
@@ -288,10 +289,14 @@ The system is governed by a **23-article Constitution** that enforces agent beha
 - **Mode Governance** - Planning mode can't modify project code. Build mode has full access
 - **Session Lock** - Once activated, all messages route through the orchestrator
 - **Model Governance** - Each agent runs on its designated model, enforced by the CLI adapter
-- **Execution Profiles** - Explore, guided, and autonomous modes with safety net and circuit breaker
+- **Execution Mode** - Interactive (default) and autonomous modes, with safety reversion to interactive (Article XVII)
 - **Multi-CLI** - Provider-agnostic architecture with adapter pattern and automatic model mapping
 - **Agent Teams** - Real-time peer communication between agents with cross-review, per-task QA, and sealed-bid quality assurance
 - **Fault Vector Protocol** - Root Layer Routing, Evidence-Bound Verdicts, Decision Trail, and Echo Detection for adversarial quality
+- **Anti-Loop Protocol** - the 3-Strike Rule and mandatory diagnosis mode stop an agent from editing the same file in circles
+- **Reasoning Tier** - per-task cognitive depth (standard / deep / deliberate) with deterministic escalation
+- **Model-Harness Parity** - a re-audit advisory when the active model family changes, so calibration does not drift silently
+- **Execution Kinds** - a task declares how it runs (agent, deterministic script, specialist, or human gate); deterministic dev work can run with no model call (feature-flagged, off by default)
 
 ---
 

package/bin/chati.js

@@ -141,6 +141,26 @@ async function main() {
         console.log(`  Framework sync skipped: ${err.message}`);
       }
 
+      // 2.6. Re-bundle CLI (Bug 4 part 3, v4.3.1+) — refreshes .chati.dev/_cli/
+      // and writes version.json so chati-router.js mismatch detection clears
+      // on the next invocation.
+      console.log('  Re-bundling CLI...');
+      try {
+        const { copyCliSource, copyCliDependencies } = await import('../src/installer/core.js');
+        const { writeFileSync } = await import('fs');
+        const fwDir = resolveFrameworkDir(targetDir);
+        const frameworkDir = join(targetDir, fwDir);
+        copyCliSource(join(__dirname, '..', 'src'), join(frameworkDir, '_cli'));
+        copyCliDependencies(join(__dirname, '..'), join(frameworkDir, '_cli', 'node_modules'));
+        writeFileSync(
+          join(frameworkDir, '_cli', 'version.json'),
+          JSON.stringify({ version: pkg.version, bundled_at: new Date().toISOString() }, null, 2),
+        );
+        console.log('  CLI re-bundled.');
+      } catch (err) {
+        console.log(`  CLI rebundle skipped: ${err.message}`);
+      }
+
       // 2.6. Detect tracked framework files and warn user (non-blocking)
       try {
         const { detectTrackedFrameworkFiles } = await import('../src/upgrade/tracked-files-detector.js');
@@ -343,7 +363,7 @@ async function main() {
       console.log('  - Specialized agents across DISCOVER, PLAN, BUILD, DEPLOY phases');
       console.log('  - 6 workflow blueprints');
       console.log('  - 6 templates');
-      console.log('  - Constitution (23 Articles + Preamble)');
+      console.log('  - Constitution (25 Articles + Preamble)');
       console.log('  - Dashboard TUI');
       console.log('  - Upgrade system with migrations');
       console.log('  - 6 IDE support');
@@ -419,7 +439,13 @@ Telemetry:
       const keyFlag = args.find(a => a.startsWith('--key='));
       const keyArg = keyFlag ? keyFlag.replace('--key=', '') : null;
       const { runActivate } = await import('../src/license/commands.js');
-      await runActivate(targetDir, keyArg);
+      const result = await runActivate(targetDir, keyArg);
+      // runActivate returns { ok, cancelled?, error? } and never exits the
+      // process itself (keeps it unit-testable). Translate to an exit code
+      // here at the CLI boundary: failures other than user-cancel exit 1.
+      if (result && result.ok === false && !result.cancelled) {
+        process.exit(1);
+      }
       break;
     }
 
@@ -454,7 +480,7 @@ Telemetry:
 
       const scaffoldSrc = (() => {
         try { return resolveScaffoldSource(targetDir); }
-        catch (e) { console.error(`Error: ${e.message}`); process.exit(1); }
+        catch (e) { console.error(`Error: ${e.message}`); process.exit(1); return undefined; }
       })();
 
       if (!sub || sub === 'list') {
@@ -525,8 +551,10 @@ Telemetry:
       const VALID_ORCHESTRATE_SUBS = new Set([
         'next', 'advance', 'init', 'status', 'validate-handoff',
         'deviation', 'exit', 'providers', 'detect-flow', 'backlog',
-        'qa-plan-score', 'qa-impl-score', 'scan',
+        'qa-plan-score', 'qa-impl-score', 'qa-visual-score', 'scan',
         'spawn-team', 'team-status', 'team-dissolve',
+        'wait-for-capture', 'wave-status', 'assess-coverage',
+        'wait-for-license', 'doctor', 'run-script-task',
       ]);
       if (!VALID_ORCHESTRATE_SUBS.has(subCommand)) {
         console.error(`Error: Unknown orchestrate subcommand "${subCommand}".`);

package/framework/agents/build/dev.md

@@ -105,7 +105,7 @@ The `motion-premium` scaffold preset (`scaffold/motion-premium/`) ships referenc
 
 **Context**
 
-Tailwind v4 is a major shift: the `@theme` block, CSS-first token declaration, Cascade Layers compilation, and arbitrary-value type inference all changed. The change introduced three silent-failure modes that pass `pnpm lint`, `pnpm typecheck`, and `pnpm build` with zero errors. One was caught by QA-Visual pixel inspection; two slipped past it and bit production in the focus-ai-website saga. All three now have deterministic gates in qa-visual, but dev must avoid them at build time — fixing in code is cheaper than fixing under a correction loop.
+Tailwind v4 is a major shift: the `@theme` block, CSS-first token declaration, Cascade Layers compilation, and arbitrary-value type inference all changed. The change introduced three silent-failure modes that pass `pnpm lint`, `pnpm typecheck`, and `pnpm build` with zero errors. One was caught by QA-Visual pixel inspection; two slipped past it and bit production in a reference-website case study. All three now have deterministic gates in qa-visual, but dev must avoid them at build time — fixing in code is cheaper than fixing under a correction loop.
 
 **Decision**
 
@@ -142,7 +142,7 @@ Prefer the promoted Tailwind utilities (`text-xs..text-hero`, `bg-primary`, etc.
 
 *Pitfall 2 — Unlayered global CSS defeats every utility.*
 
-Tailwind v4 places utilities inside `@layer utilities`. Per CSS Cascade Layers (Cascade Level 5), *unlayered* CSS always wins over any named layer — regardless of selector specificity. A single global reset outside `@layer` silently overrides `mx-auto`, `px-*`, `flex`, everything. This broke container centering for a full day on focus-ai-website (2026-04-16 incident) and was invisible at 1280px viewport — the x=0 container alignment only became visible at 1920px where lg:px-12 should have added padding but unlayered `* { margin: 0 }` outranked it.
+Tailwind v4 places utilities inside `@layer utilities`. Per CSS Cascade Layers (Cascade Level 5), *unlayered* CSS always wins over any named layer — regardless of selector specificity. A single global reset outside `@layer` silently overrides `mx-auto`, `px-*`, `flex`, everything. This broke container centering for a full day on a reference-website (a Tailwind v4 incident encountered in production) and was invisible at 1280px viewport — the x=0 container alignment only became visible at 1920px where lg:px-12 should have added padding but unlayered `* { margin: 0 }` outranked it.
 
 WRONG — kills every Tailwind margin/padding utility:
 ```css
@@ -298,7 +298,7 @@ React 19 (stable since late 2024) introduced four patterns that improve ergonomi
 
 **Context**
 
-Lenis (virtualized smooth scroll) + GSAP + ScrollTrigger form the premium animation stack. Initialization order is load-bearing: wrong order produces silent bugs (tab-restore snap, ScrollTrigger positions measured against the native scrollbar instead of Lenis, drifting RAF clocks). The `motion-premium` scaffold encodes all 13 "sauce patterns" learned from the focus-ai-website saga; this ADR names the canonical init sequence dev must preserve.
+Lenis (virtualized smooth scroll) + GSAP + ScrollTrigger form the premium animation stack. Initialization order is load-bearing: wrong order produces silent bugs (tab-restore snap, ScrollTrigger positions measured against the native scrollbar instead of Lenis, drifting RAF clocks). The `motion-premium` scaffold encodes all 13 "sauce patterns" learned from a reference-website case study; this ADR names the canonical init sequence dev must preserve.
 
 **Decision**
 
@@ -361,7 +361,7 @@ export async function initLenis() {
 
 **Context**
 
-Responsive design done wrong introduces a class of silent bugs that are invisible at 1280px and lethal at 1920px or 1200px. This ADR encodes the 12 principles learned from the focus-ai-website saga. They are non-negotiable for premium UI tasks. Principles 1, 2, 3, 7, 10, and 12 are enforced structurally by the `motion-premium` scaffold; the remaining six are dev discipline that visual-qa validates.
+Responsive design done wrong introduces a class of silent bugs that are invisible at 1280px and lethal at 1920px or 1200px. This ADR encodes the 12 principles learned from a reference-website case study. They are non-negotiable for premium UI tasks. Principles 1, 2, 3, 7, 10, and 12 are enforced structurally by the `motion-premium` scaffold; the remaining six are dev discipline that visual-qa validates.
 
 **Decision**
 
@@ -806,6 +806,8 @@ Score = criteria met / total criteria
 Threshold: >= 95% per task (minimum 9/10)
 ```
 
+This self-validation score is the Dev agent's own per-task done-check (it decides when a task is finished and ready to hand off). It is NOT the phase gate. The BUILD phase only advances when the separate QA-Implementation agent's verdict clears its threshold (enforced in the orchestrator pipeline manager). Never wire this self-score into a phase-transition decision; the separated QA verdict is always the gate.
+
 ---
 
 ## Intelligence Integration
@@ -822,7 +824,9 @@ Before implementing each task:
 After completing each task:
 1. If a new gotcha was discovered -> append to gotchas.yaml
 2. If a successful pattern was used -> append to patterns.yaml
-3. Update confidence.yaml with execution results
+3. Update confidence.yaml with execution results. When you write measured
+   values, set that agent's `calibration_status: calibrated` and
+   `last_calibrated` to today; never leave a measured number as `seed`.
 ```
 
 ---

package/framework/agents/discover/brief.md

@@ -559,6 +559,7 @@ domains:
   required:
     - constitution.yaml
     - global.yaml
+    - rules/human-writing-style.md
     - agents/brief.yaml
     - artifacts/handoffs/greenfield-wu-handoff.md  # or brownfield-wu-handoff.md
 ```
@@ -661,6 +662,7 @@ On failure:
 6. Negative scope is mandatory - explicitly document what will NOT be built
 7. Adapt question depth to user level (vibecoder = guided, power user = direct)
 8. Maximum 5 interaction rounds before compiling brief draft
+9. Apply `rules/human-writing-style.md` to brief-report.md prose, handoff Layer 1, conversation turns. Exempt: visual_references YAML, brief.yaml frontmatter, brief criteria tables.
 
 ---
 

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

@@ -377,6 +377,7 @@ domains:
   required:
     - constitution.yaml
     - global.yaml
+    - rules/human-writing-style.md
     - agents/brownfield-wu.yaml
 ```
 
@@ -474,6 +475,7 @@ On failure:
 6. Treat all scout call findings as preliminary (agents will re-run in full mode later)
 7. Preserve the user's terminology when documenting operational context
 8. Flag security-sensitive patterns (hardcoded secrets, exposed endpoints) as CRITICAL
+9. Apply `rules/human-writing-style.md` for all human-facing output (WU report prose, handoff Layer 1, user-facing conversation turns). Exempt: YAML blocks, tables, code, debt registry tables.
 
 ---
 

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

@@ -291,6 +291,7 @@ domains:
   required:
     - constitution.yaml
     - global.yaml
+    - rules/human-writing-style.md
     - agents/greenfield-wu.yaml
 ```
 
@@ -307,13 +308,28 @@ post-qa-planning gate fires when both align.
 
 ### motion-premium triggers (2D premium)
 Record `motion-premium` as a candidate when ALL of the following are true:
-- The stack includes **Next.js** (any version) OR **React** (any version).
+- The stack includes **Next.js** (any version). These presets ship Next.js templates, so a plain React or React+Vite stack is not a match.
 - The stack includes **Tailwind CSS** (any version — v3 or v4).
 - The stack includes at least one premium animation library: **GSAP**,
   **Lenis**, or **Framer Motion**. A user-described intent that clearly
   implies these (e.g. "smooth scroll pinning", "scroll-reveal storytelling",
   "page-scroll narrative") also counts — document the phrase as evidence.
 
+### saas-dashboard triggers (app-shell / data-dense)
+Record `saas-dashboard` as a candidate when ALL of the following are true:
+- The stack includes **Next.js** (any version). These presets ship Next.js templates, so a plain React or React+Vite stack is not a match.
+- The stack includes **Tailwind CSS** (any version).
+- The project is an **application or internal tool**, not a marketing or
+  showcase site. Any of these signals counts (document the phrase as evidence):
+  dashboard, admin panel, SaaS app, internal tool, analytics, data table,
+  KPI or metrics view, sidebar navigation, app shell, settings pages, command
+  palette (Cmd+K), CRUD over records, back office.
+
+saas-dashboard is the app-shell counterpart to the motion-premium presets. In
+practice it is mutually exclusive with them (an animated marketing site is not
+a data dashboard), but recording both is harmless: the auto-gate fires the
+highest-confidence candidate first and the user chooses.
+
 ### motion-premium-3d triggers (R3F + Three.js, workstream 3)
 Record `motion-premium-3d` as a candidate when ALL of the following are true:
 - The stack includes **Next.js** (any version).
@@ -443,6 +459,7 @@ On failure:
 3. Keep questions focused and progressive (don't ask everything at once)
 4. Adapt question depth to user level (vibecoder = simpler, power user = technical)
 5. Maximum 4 interaction rounds before generating report
+6. Apply `rules/human-writing-style.md` for all human-facing output (WU report prose, handoff Layer 1, user-facing conversation turns). Exempt: YAML blocks, tables, scaffold_signals.
 
 ---
 

package/framework/agents/plan/detail.md

@@ -325,6 +325,7 @@ Rules:
 |-------|--------|---------|
 | L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
 | L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
+| L1.5 | `chati.dev/rules/human-writing-style.md` | Anti-AI prose rules for human-facing PRD sections |
 | L2 | `artifacts/1-Brief/brief-report.md` | Problems, desired outcomes, constraints, target users |
 | L3 | `artifacts/handoffs/brief-handoff.md` | Brief agent handoff with decisions and open questions |
 
@@ -388,6 +389,7 @@ Beyond self-validation (Protocol 5.1), the Detail agent enforces:
 4. **NFR measurability**: Every non-functional requirement must include a measurable threshold (e.g., "response time < 200ms" not "fast response")
 5. **Scope boundaries are bilateral**: Both in-scope AND out-of-scope must be explicitly defined - omitting out-of-scope is a validation failure
 6. **Traceability is bidirectional**: Brief-to-PRD and PRD-to-Brief mappings must both exist with zero orphans in either direction
+7. **Human writing style**: Apply `rules/human-writing-style.md` to Executive Summary, Goals, Target Users, and Scope narrative prose. Exempt: FR/NFR/BR tables, Given-When-Then criteria, Traceability Matrix.
 
 ---
 

package/framework/agents/plan/tasks.md

@@ -85,12 +85,43 @@ Task Definition:
   - Priority: critical | high | medium | low
   - Size: XS (<1h) | S (1-2h) | M (2-4h) | L (4-8h) | XL (8h+ -> split!)
   - Dependencies: [T{x}.{y}, ...]
+  - Execution Kind: agent (default) | script | specialist | human  (see Step 2c)
   - Acceptance Criteria (Given-When-Then):
     - Given {initial context/state}
     - When {action is performed}
     - Then {expected outcome, verifiable}
 ```
 
+### Step 2c: Execution Kind (deterministic tasks run as scripts)
+
+Most tasks are `agent`: an LLM implements them. Some, though, are fully
+deterministic and waste an agent turn. When the `execution_kinds` feature is on,
+assign the right kind so the orchestrator can run deterministic work as a
+zero-LLM script. When the feature is off, every task runs as `agent` and this
+step is a no-op, so it is always safe to record the kind.
+
+Decision tree (top to bottom, first match wins):
+
+1. **human** - a critical, irreversible, legal, financial, or product-judgment
+   decision a person must own (for example "confirm the production migration",
+   "approve the pricing copy"). Set `execution_ref` to a one-line description of
+   the decision. A person decides; no automation.
+2. **script** - a deterministic dev operation with a single correct outcome and
+   no design judgment: run the linter or the test suite, verify build output
+   exists, validate a JSON file. Set `execution_ref` to an executor from
+   `chati.dev/executors/registry.yaml` with its argument, for example
+   `npm-script:test`, `npm-script:lint`, `path-check:dist,build`, or
+   `json-validate:package.json`. The acceptance criterion is the executor's pass
+   condition (exit 0, paths present, valid JSON). If no executor fits, it is not
+   a script task.
+3. **specialist** - creative work that carries a fixed methodology the agent must
+   follow exactly (reserved; today this resolves to `agent`).
+4. **agent** (default) - anything that needs implementation, design, or judgment.
+
+Be conservative: when in doubt between script and agent, choose agent. A script
+task that needs any interpretation is a defect. Only the registered executors
+are valid `script` refs; never invent an executor id.
+
 ### Step 2b: Animation Inventory → Tasks (1:1 mapping, REQUIRED when inventory exists)
 
 Before producing the final task list, check for `artifacts/4-UX/animation-inventory.md`. If it exists, it is the SOURCE OF TRUTH for every animation-related task in the build. The brand-architect locked this artifact at the `advance ux` gate; your job is to convert it into tasks faithfully.

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

@@ -157,6 +157,8 @@ Premium means:
 - Stagger animations on any repeated elements (cards, list items, grid children)
 - Page load MUST have an entrance animation sequence (not just content appearing)
 
+**Design toward the QA-Visual rubric.** The canonical quality bar is the 8-dimension rubric in `chati.dev/data/qa-rubrics.yaml` under `visual_rubric`. Its per-dimension premium markers are your targets; its slop markers are forbidden. The tokens, modular type scale, semantic color system, spacing scale, and motion language you define here are exactly what QA-Visual scores against, so set them to clear the premium band on every dimension. Layout, typography, color, and motion carry the highest weights. Concrete musts the rubric enforces: a base-unit spacing system (4px or 8px, no off-scale values), a modular type scale (a consistent ratio, not round-number sizes), a documented semantic color layer (no raw hex literals, accent restraint), cubic-bezier easing tied to each transition's physical metaphor (never `linear` or bare `ease`, never `transition: all`), and full interactive-state coverage. Avoid the anti-slop catalog tells (generic saturated-blue primary, metronomic identical section padding, the symmetric centered hero with no compositional interest).
+
 The 5 benchmark sites (landonorris.com, iertqa.com, toptier.relats.com, refractweb.com, magic5.ro) are the FLOOR, not the ceiling.
 
 If `visual_quality: functional` → reduce to CSS transitions only, no GSAP requirement.
@@ -379,10 +381,27 @@ Append a `## Scaffold Signals` section to your handoff file
   evidence:
     - "Named 3D reference site"
     - "Inventory row mapping to scaffold/motion-premium-3d/*"
+
+- preset: saas-dashboard
+  candidate: true
+  confidence: 0.0 to 1.0
+  evidence:
+    - "App-shell intent (dashboard, admin panel, SaaS app, internal tool)"
+    - "Brief names data tables, KPIs, sidebar navigation, or a command palette"
 ```
 
-Emit both entries when both presets apply — the post-qa-planning gate
-fires them in sequence after the user applies or skips the first.
+Emit each applicable entry. saas-dashboard is the app-shell counterpart and is
+mutually exclusive with the motion presets in practice (a data dashboard is not
+an animated marketing site); emit it instead of the motion presets when the
+brief describes an application rather than a showcase. The post-qa-planning gate
+fires the candidates in sequence after the user applies or skips the first.
+
+`confidence` scoring for `saas-dashboard` (gate threshold 0.7):
+- 1.0 — the brief explicitly calls the product a dashboard, admin panel, or
+  SaaS app AND names at least two app-shell elements (data tables, KPIs,
+  sidebar nav, command palette, settings).
+- 0.7 to 0.9 — clear application intent with one or two app-shell elements.
+- below 0.7 — ambiguous; a content or marketing site. Do NOT emit.
 
 `confidence` scoring for `motion-premium` (gate threshold 0.7):
 - 1.0 — multiple named premium refs (Oryzo + Norris + Relats, etc.) AND

package/framework/agents/plan/ux-component-engineer.md

@@ -17,6 +17,8 @@ You are the **Component Engineer**, a specialist sub-agent of the UX Manager. Yo
 
 Define HOW components behave, move, and comply with accessibility standards. Build the component hierarchy (Atomic Design), discover reusable components from 21st.dev, validate WCAG 2.2 + APCA compliance, and define the Motion System. Every component must have full state coverage and every animation must be GPU-accelerated with reduced-motion alternatives.
 
+**Design toward the QA-Visual rubric.** Your work is scored against the `motion`, `interaction`, and `accessibility` dimensions of `chati.dev/data/qa-rubrics.yaml` (`visual_rubric`). Targets the rubric enforces: every transition uses a cubic-bezier curve matched to its physical metaphor (deceleration for entering, acceleration for leaving), with a duration scale tied to element size (micro-interactions 80-150ms, component state 200-350ms, page-level <= 500ms); never `linear`, never bare `ease`, never `transition: all`. Every interactive element has four visually distinct states (resting, hover, active, disabled) and a high-contrast focus ring (>= 2px width, >= 2px offset). Accessibility is a hard gate: text meets WCAG 2.1 AA contrast at rendered size, focus order matches visual order, headings form a strict hierarchy with no skipped levels, and inputs never use placeholder as the sole label. A failing accessibility dimension caps the whole visual score at 70.
+
 ---
 
 ## On Activation
@@ -74,6 +76,14 @@ Use the BEST patterns found as the BASIS for this project's animation specs.
 Do NOT invent animation patterns from scratch - ALWAYS reference proven, production implementations.
 Adapt patterns to the project's design tokens (colors, fonts, spacing from Brand Architect).
 
+> Governance scope: the sites above (and shadcn/ui below) are external DISCOVERY
+> sources this agent reads at design time to ground specs in proven patterns.
+> They are tools, like any component library or icon set, not a lineage. The
+> authorship rule governs the SHIPPED output: it must be original work in the
+> project's own tokens and voice. When adapting a fetched component, reimplement
+> it against the project tokens and never carry over its branding, attribution,
+> or source-comment headers.
+
 **Component Library Strategy** (verified, scrapable sources):
 
 Primary: Shadcn/ui (MIT license, React + Radix UI + Tailwind + cva)

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

@@ -697,7 +697,7 @@ Criteria (binary pass/fail):
 16. Decision Trail checked pre-flight and updated post-correction (Article XXII)
 
 Score = criteria met / total criteria
-Threshold: >= 95% (15/16 minimum)
+Threshold: >= 95% (15/16 minimum). Canonical value: chati.dev/data/qa-rubrics.yaml (thresholds.qa-implementation); this number must match that file.
 ```
 
 ---

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

@@ -373,7 +373,7 @@ Criteria (binary pass/fail):
 10. Correction loops executed for all issues (or escalated with justification)
 
 Score = criteria met / total criteria
-Threshold: >= 95% (10/10 minimum, no criteria may fail)
+Threshold: >= 95% (10/10 minimum, no criteria may fail). Canonical value: chati.dev/data/qa-rubrics.yaml (thresholds.qa-planning); this number must match that file.
 ```
 
 ---

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

@@ -26,6 +26,15 @@ You are the **QA-Visual Agent**, a specialized quality gate focused exclusively
 ## Required MCPs
 - browser (Playwright MCP - mandatory, not optional)
 
+## Gateway weight (v4.3.1+)
+
+QA-Visual operates with two execution paths:
+
+- **Strong gateway (default):** real Playwright screenshots. Required for full verdict authority — score reflects what users actually see.
+- **Weak gateway (`gateway: WEAK`):** source-code analysis fallback when Playwright is unavailable (npm package missing OR chromium binary not installed). Score is capped below 90% to prevent fallback-only verdicts from clearing the threshold autonomously. The fallback exists as a backstop, not a primary path. When triggered, the report MUST surface `gateway: WEAK` so the human-in-the-loop knows the verdict is text-based and warrants extra scrutiny before advancing.
+
+Action when fallback triggers: emit a recovery instruction in the QA report — `Run: npx playwright install chromium` (binary missing) or `Run: npm install playwright` (package missing). See visual-qa.js error disambiguation (lines ~373-385).
+
 ---
 
 ## Mission
@@ -34,6 +43,12 @@ Validate that the implemented UI meets visual quality standards: animations are
 
 ---
 
+## Scoring rubric (canonical)
+
+The visual score is computed against the 8-dimension rubric in `chati.dev/data/qa-rubrics.yaml` under `visual_rubric`. That file is the single source of truth: the dimensions (layout, typography, motion, interaction, color, spacing_composition, accessibility, performance), their weights, the premium and slop markers, the measurable and judged signals, the `weak_dimension_cap`, the `anti_slop_catalog`, and the `scoring_protocol` all live there. Do NOT invent ad-hoc criteria. Score every dimension against the rubric and follow its `scoring_protocol`: scoring order (accessibility first, it carries the hardest cap), evidence standard, anti-slop catalog penalties, the weak-gateway cap (84 when Playwright is unavailable), the weighted-total formula, and correction-loop routing. Apply `weak_dimension_cap` before the weighted total. A measurable-signal finding MUST cite the computed value; a judged-signal finding MUST cite a screenshot filename (Article XXII evidence standard). The em-dash penalty and `visual-qa.js` `motion_errors` (the spring-motion veto) feed the motion and typography dimensions.
+
+---
+
 ## What This Agent Validates
 
 | Check | Tool |
@@ -295,33 +310,30 @@ If no reference data exists: skip this step, do not penalize score.
 
 ---
 
-## Scoring (DETERMINISTIC — calculated by CLI)
+## Scoring
+
+The verdict has two layers and there is no contradiction between them: the CLI gives the measured objective floor plus a hard-block veto; you give the 8-dimension rubric score.
 
-Do NOT calculate the score manually. Run the scoring CLI:
+### 1. Measured floor (CLI)
+
+Run the scoring CLI for the objective signals and the hard-block veto. Resolve `--animation-library` from architecture.md (the project's chosen motion stack):
 
 ```bash
-node .chati.dev/orchestrator/chati-router.js qa-visual-score --report /tmp/visual-qa/report.json --has-refs {true|false}
+node .chati.dev/orchestrator/chati-router.js qa-visual-score --report /tmp/visual-qa/report.json --animation-library {gsap-lenis|framer-motion|css|none} --has-refs {true|false}
 ```
 
-The CLI returns:
-```json
-{
-  "score": 85,
-  "threshold": 90,
-  "verdict": "NEEDS_CORRECTION",
-  "hardBlocked": false,
-  "errors": ["Lenis not active on all pages"],
-  "warnings": ["3 console error(s)"],
-  "dimensions": { "animScore": 50, "scrollScore": 80, ... }
-}
-```
+The GSAP/Lenis presence check applies ONLY to the `gsap-lenis` stack, so a framer-motion project (for example a saas-dashboard build) is never blocked for libraries it does not use. The CLI returns `hardBlocked: true` when there is a MEASURED failure: amateur-motion errors (the spring-motion veto: linear easing or transition:all), objective layout errors, reduced-motion violations, em-dashes, or missing GSAP/Lenis on a `gsap-lenis` project. It also returns `measured_signals` and a per-dimension breakdown.
+
+### 2. Quality score (you)
+
+Compute the 8-dimension score against `visual_rubric` in `chati.dev/data/qa-rubrics.yaml` per the Scoring rubric section above: the judged dimensions from the screenshots, the measurable signals, the weak-dimension cap, and the anti-slop catalog. Fold the CLI's measured signals into the matching dimensions (motion errors into motion, layout errors into layout, em-dashes into typography).
+
+### Verdict
 
-Use the returned `verdict` directly:
-- `APPROVED` → pass
-- `NEEDS_CORRECTION` → spawn Dev to fix, re-run
-- `BLOCKED` → hard block (GSAP/Lenis missing or em-dashes found)
+- If the CLI reports `hardBlocked: true` -> **BLOCKED**. Do NOT issue APPROVED while a measured failure stands, whatever the rubric score. Route to dev (Fault Vector Protocol: CODE).
+- Otherwise the verdict is your 8-dimension rubric score: **APPROVED** at >= 90 after the weak-dimension cap, else **NEEDS_CORRECTION** and route to dev.
 
-Do NOT override the CLI verdict. Your role is to add qualitative observations from the Visualizer report (subjective quality), but the score and verdict are deterministic.
+Never approve over a hard block, and never let a clean CLI floor stand in for the rubric: a project with zero measured errors can still score below 90 on the judged dimensions and need correction.
 
 ---
 
@@ -419,7 +431,7 @@ Criteria (binary pass/fail):
 8. Score calculated and above threshold OR escalation issued
 
 Score = criteria met / total criteria
-Threshold: >= 90%
+Threshold: >= 90%. Canonical value: chati.dev/data/qa-rubrics.yaml (thresholds.qa-visual); this number must match that file.
 ```
 
 ---

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.3.0"
+version: "4.4.0"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-04-18T00:00:00Z"
-installer_version: "4.3.0"
+updated_at: "2026-06-08T00:00:00Z"
+installer_version: "4.4.0"
 project_type: greenfield
 language: en
 ides: [claude-code]
@@ -35,7 +35,6 @@ features:
   rate_limiter_integration: true
   l5_keywords: true
   prompt_size_guard: true
-  ids_decision_engine: true
   surface_criteria: true
   parallel_fallback: true
   tool_mesh: true
@@ -53,6 +52,8 @@ features:
   model_fallback: true              # Automatic opus→sonnet fallback on overload
   frustration_detection: true       # Detect user frustration and adapt response style
   bash_security_checks: true        # 21-point shell injection defense system
+  # Execution Kinds — deterministic zero-LLM script executors for dev tasks
+  execution_kinds: false              # OFF by default (opt-in). Default task kind stays 'agent', so the pipeline is unchanged while off.
   # Agent Teams (v4.2.0 — Article XXI)
   agent_teams: true                   # Enable Claude Code native Agent Teams. Gated to claude provider; Gemini/Codex fall back silently.
   team_planning_size: 4               # Planning Team max teammates: detail + architect + ux + qa-planning