chati-dev 4.3.0 → 4.4.0

package/framework/intelligence/confidence.yaml

@@ -1,11 +1,22 @@
 # Intelligence Layer — Agent Confidence Calibration
-# Tracks agent performance across technologies and patterns
-# Updated after each execution
-# NEVER overwritten during upgrades
+# Tracks agent performance across technologies and patterns.
+# Updated after each execution (the agent appends real results here).
+# NEVER overwritten during upgrades.
+#
+# calibration_status:
+#   seed         — initial estimate, NOT measured from real runs. Treat as a
+#                  prior, not evidence. Replaced by measured values after runs.
+#   uncalibrated — no data yet. overall is null until the agent has run enough
+#                  times to calibrate. Do not treat the absence of a number as
+#                  low confidence; it means unknown.
+#   calibrated   — overall and breakdowns reflect measured results across runs.
+#
+# Every pipeline agent has an entry so it has a place to accrue calibration.
 
 confidence:
   dev:
     overall: 0.90
+    calibration_status: seed
     by_technology:
       react: 0.92
       nextjs: 0.88
@@ -17,10 +28,11 @@ confidence:
       crud_operations: 0.95
       form_handling: 0.92
       api_design: 0.88
-    last_calibrated: "2026-02-07"
+    last_calibrated: null
 
   architect:
     overall: 0.88
+    calibration_status: seed
     by_technology:
       react: 0.90
       nextjs: 0.87
@@ -30,13 +42,80 @@ confidence:
       monolith: 0.92
       microservices: 0.80
       serverless: 0.78
-    last_calibrated: "2026-02-07"
+    last_calibrated: null
 
   qa-implementation:
     overall: 0.92
+    calibration_status: seed
     by_category:
       test_execution: 0.95
       security_scan: 0.90
       code_review: 0.88
       acceptance_verification: 0.93
-    last_calibrated: "2026-02-07"
+    last_calibrated: null
+
+  # Uncalibrated: every other pipeline agent. overall stays null until measured.
+  greenfield-wu:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  brownfield-wu:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  brief:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  detail:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  architect-system:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  architect-data-engineer:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  ux:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  ux-brand-architect:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  ux-component-engineer:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  ux-researcher:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  phases:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  tasks:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  qa-planning:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  qa-visual:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  visualizer:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null
+  devops:
+    overall: null
+    calibration_status: uncalibrated
+    last_calibrated: null

package/framework/intelligence/context-engine.md

@@ -33,7 +33,7 @@ The orchestrator injects context through 6 hierarchical layers:
 
 | Layer | Name | Source | When Active |
 |-------|------|--------|-------------|
-| **L0** | Constitution | `chati.dev/constitution.md` (Articles I-XXIII) | ALWAYS (non-negotiable) |
+| **L0** | Constitution | `chati.dev/constitution.md` (Articles I-XXV) | ALWAYS (non-negotiable) |
 | **L1** | Mode + Global | `config.yaml` + mode governance (planning/build/deploy) | ALWAYS |
 | **L2** | Agent Scope | `chati.dev/agents/{agent}/` — mission, inputs, outputs, criteria | When agent is active |
 | **L3** | Pipeline State | `.chati/session.yaml` — pipeline position, scores, backlog | When session is active |
@@ -42,7 +42,7 @@ The orchestrator injects context through 6 hierarchical layers:
 
 ### Layer Activation by Bracket
 
-| Bracket | Active Layers | Budget Ratio | Claude (200K) | Gemini (1M) | Codex (128K) |
+| Bracket | Active Layers | Budget Ratio | Claude (1M) | Gemini (1M) | Codex (128K) |
 |---------|--------------|-------------|---------------|-------------|--------------|
 | FRESH | L0, L1 | 1.5% | 3,000 | 15,000 | 1,920 |
 | MODERATE | L0, L1, L2, L3 | 2.5% | 5,000 | 25,000 | 3,200 |
@@ -60,7 +60,7 @@ The orchestrator produces a structured XML block injected into agent prompts:
 ```xml
 <chati-context bracket="MODERATE">
   <constitution>
-    Articles I-XXIII governing agent behavior.
+    Articles I-XXV governing agent behavior.
     Key: Self-validation required. Loop until quality threshold.
     Guided options (1,2,3). Persistent session state.
     Two-layer handoff. Language protocol. Deviation protocol.
@@ -116,7 +116,7 @@ estimatedTokens = promptText.length / 4
 remainingPercent = (1 - estimatedTokens / providerLimit) * 100
 ```
 
-This replaces the legacy heuristic (`turnCount / maxTurns`) which was inaccurate for sessions with large tool results or long agent outputs. The token-based approach scales correctly across providers (Claude 200K, Gemini 1M, Codex 128K).
+This replaces the legacy heuristic (`turnCount / maxTurns`) which was inaccurate for sessions with large tool results or long agent outputs. The token-based approach scales correctly across providers (Claude 1M, Gemini 1M, Codex 128K).
 
 Fallback: If prompt text is unavailable, the turn-count heuristic is used.
 
@@ -150,11 +150,15 @@ If Smart Continuation is insufficient, the orchestrator spawns a new session:
 
 | Condition | Threshold | Rationale |
 |-----------|-----------|-----------|
+| BUILD phase + DEPLETED/CRITICAL | Immediate (default to Level 2) | During code generation a depleted window produces regressions faster than a reset costs; a clean slate beats in-place compaction |
 | Multiple compactions | 3+ in single session | Context is churning too fast |
 | Post-compact quality | Agent score drops >15% | Compaction lost critical context |
 | Critical bracket persists | CRITICAL for 3+ consecutive interactions | Recovery not working |
+| Echo loop detected | 2+ echo entries in the current phase (session.yaml decision_trail) | The model is looping; a fresh session breaks the cycle |
 | Agent handoff pending | Current agent done, next agent needs fresh context | Clean start is better |
 
+**BUILD-phase reset preference:** During the BUILD phase, when the active agent reaches DEPLETED or CRITICAL, the orchestrator defaults to Level 2 (Autonomous Session Spawn, a clean reset) rather than Level 1 (Smart Continuation, in-place compaction). Compaction preserves continuity but not a clean slate, so the model can keep wrapping up work prematurely while code is being written; a reset carrying a full handoff is safer there. Level 1 stays the default for the MODERATE bracket and for the DISCOVER and PLAN phases.
+
 ### IDE-Specific Behavior
 
 | IDE | Level 1 | Level 2 |
@@ -185,7 +189,7 @@ Memory injection follows the same progressive reinforcement principle: as contex
 
 ---
 
-*Context Engine v4.3.0 — Chati.dev Intelligence Layer (Progressive Reinforcement Model)*
+*Context Engine v4.4.0 — Chati.dev Intelligence Layer (Progressive Reinforcement Model)*
 
 ---
 

package/framework/intelligence/decision-engine.md

@@ -96,7 +96,7 @@ npx chati-dev health
 Checks:
 1. All registered entities exist on disk
 2. Schema files are valid JSON
-3. Constitution has >= 23 articles
+3. Constitution has >= 25 articles
 4. Agents contain required protocol references
 5. Entity count matches actual file count
 6. Checksums match (if calculated)

package/framework/orchestrator/chati-router.js

@@ -28,6 +28,51 @@ const ROUTER_ARGS = process.argv.slice(2);
 async function findCliModule(projectDir) {
   // Resolve framework dir (.chati.dev/ or chati.dev/ for legacy)
   const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+
+  // --- VERSION MISMATCH DETECTION (v4.3.1+) ---
+  // G8: reset stale state from previous invocations within same process.
+  findCliModule._mismatch = null;
+
+  // Compare canonical version (chati.dev/config.yaml.installer_version) against
+  // installed bundle (.chati.dev/_cli/version.json). Pre-v4.3.1 installs lack
+  // version.json — silent skip (graceful degradation).
+  let installedVersion = null;
+  let bundledVersion = null;
+  try {
+    const configPath = join(projectDir, fwDir, 'config.yaml');
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, 'utf-8');
+      const m = raw.match(/^installer_version:\s*['"]?([^\s'"]+)/m);
+      installedVersion = m ? m[1] : null;
+    }
+    const versionStampPath = join(projectDir, fwDir, '_cli', 'version.json');
+    if (existsSync(versionStampPath)) {
+      bundledVersion = JSON.parse(readFileSync(versionStampPath, 'utf-8')).version;
+    }
+    if (installedVersion && bundledVersion && installedVersion !== bundledVersion) {
+      // G6: severity-aware warning. Major diff signals breaking schema/behavior changes.
+      const installedMajor = parseInt(String(installedVersion).split('.')[0], 10);
+      const bundledMajor = parseInt(String(bundledVersion).split('.')[0], 10);
+      const majorDiff =
+        !Number.isNaN(installedMajor) &&
+        !Number.isNaN(bundledMajor) &&
+        installedMajor !== bundledMajor;
+      const severityNote = majorDiff
+        ? ' Major version change — review CHANGELOG before upgrading.'
+        : '';
+      process.stderr.write(
+        `[chati] WARNING: CLI bundle version (${bundledVersion}) ` +
+        `does not match installed framework (${installedVersion}).${severityNote} ` +
+        `Run: npx chati-dev upgrade\n`
+      );
+      findCliModule._mismatch = {
+        bundle: bundledVersion,
+        installed: installedVersion,
+        major_diff: majorDiff,
+      };
+    }
+  } catch { /* non-critical — proceed to candidates loop */ }
+
   const candidates = [
     // PRIMARY: bundled CLI inside framework dir (self-contained install — no npx needed)
     join(projectDir, fwDir, '_cli', 'orchestrator', 'cli.js'),
@@ -90,9 +135,11 @@ async function routeAdvance(agentName, score) {
 
   try {
     const cliMod = await findCliModule(PROJECT_DIR);
+    if (findCliModule._mismatch) result.version_mismatch = findCliModule._mismatch;
     if (!cliMod) {
       result.ok = false;
       result.error = 'cli_module_not_found';
+      result.reason = 'Bundled CLI not found in .chati.dev/_cli/. Reinstall with: npx chati-dev upgrade';
       return result;
     }
 
@@ -145,7 +192,7 @@ const VALID_ORCHESTRATE_SUBS = new Set([
   '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',
+  'wait-for-license', 'doctor', 'run-script-task',
 ]);
 
 /**
@@ -174,16 +221,21 @@ function parseFlagArgs(argv) {
  */
 async function dispatchOrchestrate(subCommand, argv) {
   const cliMod = await findCliModule(PROJECT_DIR);
+  const mismatch = findCliModule._mismatch;
   if (!cliMod) {
-    return {
+    const out = {
       ok: false,
       action: 'error',
       error: 'cli_module_not_found',
-      reason: 'Bundled CLI not found in .chati.dev/_cli/. Reinstall with: npx chati-dev init',
+      reason: 'Bundled CLI not found in .chati.dev/_cli/. Reinstall with: npx chati-dev upgrade',
     };
+    if (mismatch) out.version_mismatch = mismatch;
+    return out;
   }
   try {
-    return await captureOrchestrate(cliMod, subCommand, argv, PROJECT_DIR);
+    const result = await captureOrchestrate(cliMod, subCommand, argv, PROJECT_DIR);
+    if (mismatch && result && typeof result === 'object') result.version_mismatch = mismatch;
+    return result;
   } catch (err) {
     return {
       ok: false,
@@ -327,9 +379,11 @@ async function main() {
   // -----------------------------------------------------------------------
   try {
     const cliMod = await findCliModule(PROJECT_DIR);
+    if (findCliModule._mismatch) result.version_mismatch = findCliModule._mismatch;
     if (!cliMod) {
       result.action = 'error';
-      result.error = 'cli_module_not_found: bundled CLI missing in .chati.dev/_cli/. Reinstall with: npx chati-dev init';
+      result.error = 'cli_module_not_found';
+      result.reason = 'Bundled CLI missing in .chati.dev/_cli/. Reinstall with: npx chati-dev upgrade';
     } else {
       result.pipeline = await captureOrchestrate(cliMod, 'next', [], PROJECT_DIR);
       result.action = result.pipeline.action;

package/framework/orchestrator/chati-update.md

@@ -10,7 +10,7 @@ You are the **Chati Update Agent**, a specialized evolution advisor for the chat
 
 1. **NEVER copy blindly** - Adapt concepts to chati.dev's identity and patterns
 2. **NEVER break existing tests** - All tests must continue passing (run `npm test` to verify)
-3. **NEVER violate the constitution** - 23 articles are sacred
+3. **NEVER violate the constitution** - 25 articles are sacred
 4. **NEVER skip comparison** - Every finding MUST be validated against current state
 5. **ALWAYS present options** - Numbered 1, 2, 3 format before any implementation
 6. **ALWAYS use sub-agents** - Parallelize SCAN and COMPARE for throughput
@@ -102,7 +102,7 @@ Launch **in parallel** with Phase 1 a **Task agent (subagent_type=Explore, thoro
 Map the COMPLETE current state of chati.dev. Analyze:
 
 1. **CONSTITUTION** - Read chati.dev/constitution.md fully. Extract:
-   - All 23 articles with key rules
+   - All 25 articles with key rules
    - Quality thresholds
    - Governance patterns
 
@@ -247,7 +247,7 @@ Use `/ralph-loop` with the following prompt structure:
 
 REQUIREMENTS:
 1. Implement each change following chati.dev patterns and conventions
-2. Respect the constitution (23 articles) - especially originality
+2. Respect the constitution (25 articles) - especially originality
 3. Update relevant tests for each change
 4. Run full test suite after each change - ALL must pass
 5. Run lint after each change - must be clean
@@ -300,6 +300,22 @@ After ralph-wiggum completes, generate final report:
 
 ---
 
+## Phase 7: MODEL-HARNESS PARITY (Article XXIV)
+
+This step runs whether the update was triggered by a reference comparison or by a model change.
+
+1. **Re-baseline the model.** Record the current model as the audited one so the parity advisory clears:
+   - set `session.model_at_last_audit = session.active_model`
+   Write this through the session manager (the CLI-managed path), never by editing `.chati/session.yaml` directly.
+
+2. **Model-change audit checklist.** When the model family changed, re-check the parts of the harness whose calibration is model-dependent, and keep the model-agnostic parts:
+   - Context bracket token budgets (Article XII, `context-engine.md`): are the FRESH/MODERATE/DEPLETED/CRITICAL boundaries still right for the new window size?
+   - Agent confidence calibration (`intelligence/confidence.yaml`): re-calibrate after a few real runs on the new model.
+   - Load-bearing agents: is any scaffolding agent now redundant because the new model does that step natively? Is any new capability worth a new agent?
+   - Keep unchanged: the Articles, the quality gates and thresholds, the registry. These are model-agnostic.
+
+---
+
 ## Error Handling
 
 - **Clone fails**: Ask user for correct URL/path, suggest alternatives

package/framework/orchestrator/chati.md

@@ -104,6 +104,7 @@ Parse the JSON output. The `action` field tells you what to do:
 | `user_preview` | Action: User Preview |
 | `complete` | Action: Complete |
 | `error` | Display error, suggest `/chati status` |
+| `version_mismatch` (in any response) | "Your CLI bundle is out of date. Run `npx chati-dev upgrade` to fix." Display once per session, then continue. |
 
 **Internal: track context bracket from JSON `context_bracket` but DO NOT display it to the user.** The bracket is internal telemetry - users should never see "Context: FRESH (90%)" or framework jargon like "Initiating handoff protocol". Speak in natural language about what you are doing, not the internal state.
 
@@ -228,6 +229,24 @@ Quality gate passed: {score}%.
 
 ---
 
+## Action: Script Task (Execution Kinds)
+
+When the `execution_kinds` feature is on and the next task's `execution_kind` is
+not `agent`, route it here instead of spawning an agent. When the feature is off
+or the kind is `agent`, skip this entirely and use the normal agent path. This
+is purely a dispatch optimization: it never changes WHAT a task must achieve,
+only what executes it, and it is invisible when the feature is off.
+
+- **script**: run it deterministically with no LLM. Via Bash:
+  `node .chati.dev/orchestrator/chati-router.js run-script-task --ref "{execution_ref}" --id "{task_id}" --title "{task_title}"`
+  Handle the JSON `status`:
+  - `passed` → the task is done. Advance: `node .chati.dev/orchestrator/chati-router.js advance --agent {current_agent} --score 100`
+  - `failed` → the deterministic check is negative. Route to dev (Fault Vector Protocol: CODE) to fix, then re-run the script task.
+  - `error` → the executor could not run. Surface the summary to the user and check the execution_ref against the executor registry.
+  - `ran: false` → the feature is off or the kind is not script; fall back to the agent path silently.
+- **human**: present the decision in the user's language as a Guided Option and wait for their choice. Record it, then advance. Never decide for them.
+- **specialist**: reserved; today, run it through the normal agent path.
+
 ## Action: Autonomous Agent
 
 These agents run in separate Claude Code processes.
@@ -789,7 +808,7 @@ interactive (default):
   → All 8 universal protocols apply.
 
 autonomous (Ralph Wiggum mode):
-  → Requires: most recent QA gate score >= 95% (Article XVIII prerequisite).
+  → Requires: most recent QA gate score >= 95% (Article XVII prerequisite).
   → If quality gate not met, inform user and suggest guided mode instead.
   → Agent executes without asking unless blocker encountered.
   → Primarily for Dev agent during BUILD phase.

package/framework/quality-gates/planning-gate.md

@@ -34,6 +34,8 @@ QA-Planning
 | Agent defined weak criteria | -10 |
 
 ## Decision
+Thresholds are canonical in `chati.dev/data/qa-rubrics.yaml` (thresholds.qa-planning); the values below must match that file.
+
 - **Score >= 95**: APPROVED -> proceed to BUILD
 - **Score < 95**: Silent correction loop (max 3 per agent)
 - **Still < 95 after loops**: ESCALATE to user

package/framework/rules/human-writing-style.md

@@ -0,0 +1,47 @@
+# Human Writing Style — Anti-AI Guidelines
+
+**Scope**: Apply to all human-facing outputs: WU reports, Briefs, PRDs, handoff Layer 1 summaries, conversation turns with the user.
+**Exemption**: Tasks lists, JSON, YAML, code blocks, qa-*.md structured tables, Given-When-Then criteria — do NOT apply.
+
+## Rules
+
+### 1. No generic opening phrases
+Do not open with "In today's fast-paced world", "In the ever-evolving landscape", "As we navigate", or any variant. Start with the subject matter directly.
+
+### 2. No AI-favored filler verbs
+Avoid: delve, leverage, facilitate, utilize, empower, harness. Use: use, help, run, build, drive, enable — only when the simpler word fits.
+
+### 3. No rhetorical tricolons
+Avoid: "not only X, but also Y, and Z", "robust, scalable, and maintainable". State the one thing that matters. Cut the rest.
+
+### 4. No unnecessary hedging
+Remove: "it's worth noting", "it's important to mention", "it should be noted", "one could argue", "arguably". If it is worth saying, say it directly.
+
+### 5. No meta-closings
+Remove: "In conclusion", "To summarize", "Overall", "Ultimately", "In summary". End on the last substantive point.
+
+### 6. No sycophancy
+Never open a response with "Great question!", "Excellent point!", "Absolutely!", or any approval of the user's input.
+
+### 7. No performative bold
+Do not bold words that carry no additional weight in context. Bold only genuine warnings, field labels, or terms the reader must not miss.
+
+### 8. No robotic bullet parallelism
+Bullet lists must not read as machine-generated triplets of the same syntactic form. Vary sentence length and structure. Mix noun phrases with full sentences where it reads better.
+
+### 9. No negation-revelation pattern
+Avoid: "This isn't just a dashboard — it's a command center." State what it is. Do not theatricalize via contrast.
+
+### 10. No stacked generic adjectives
+Avoid: "comprehensive, robust, scalable solution". Use the adjective only if it is specific and load-bearing. Remove the rest.
+
+## Multilingual application
+
+Framework supports en/pt/es/fr (Article VII). The English patterns above are EXEMPLARS, not exhaustive enumeration. When producing output in pt-BR / es / fr, apply the SAME PRINCIPLES to language-equivalent forms:
+
+- Filler verbs: pt "elucidar / alavancar / facilitar"; es "profundizar / aprovechar / facilitar"; fr "approfondir / exploiter / faciliter"
+- Generic openings: pt "No mundo atual em constante mudança"; es "En el mundo actual"; fr "Dans le monde d'aujourd'hui"
+- Meta-closings: pt "Em conclusão / Em resumo"; es "En conclusión"; fr "En conclusion / Pour conclure"
+- Sycophancy: pt "Ótima pergunta!"; es "¡Excelente pregunta!"; fr "Excellente question !"
+
+Agent applies the principle to the target language; do not require literal translation of English examples.

package/framework/scaffold/motion-premium/README.md

@@ -1,6 +1,16 @@
 # Motion Premium Scaffold — v1.0.0
 
-Opinionated premium animation infrastructure for Next.js / React 18+ / Tailwind v4 projects. Ships the 13 non-negotiable sauce patterns + 12 responsive principles proven on reference implementations (focus-ai-website).
+Opinionated premium animation infrastructure for Next.js / React 18+ / Tailwind v4 projects. Ships the 13 non-negotiable sauce patterns + 12 responsive principles proven on reference implementations (reference-website).
+
+## Setup
+
+After `npm install`, run once to download the chromium browser binary used by QA-Visual screenshots:
+
+```bash
+npx playwright install chromium
+```
+
+Without this step, QA-Visual falls back to source-code analysis (gateway: WEAK) and skips screenshot-based gates.
 
 ## What this scaffold gives you
 
@@ -74,7 +84,7 @@ All 15 files listed above match `scaffold.yaml` `files[]` exactly.
 - **Scaffold**: `motion-premium@1.0.0`
 - **Requires framework**: chati.dev >= 4.3.0
 - **Requires stack**: Next.js OR React Vite, Tailwind v4+, TypeScript 5+, React 18+, Node 18+
-- **Reference implementation**: `focus-ai-website` (all 13 sauce patterns verified in production)
+- **Reference implementation**: `reference-website` (all 13 sauce patterns verified in production)
 
 ## Upgrading
 

package/framework/scaffold/motion-premium/lib/animations/tokens.ts.template

@@ -102,7 +102,7 @@ export type StaggerKey = keyof typeof STAGGERS;
 // SCROLL_TRIGGER_DEFAULTS — common trigger start/end strings
 // The GSAP "top 80%" syntax means: "fire when element's top is at 80% down
 // the viewport". Defaults here encode the weight/timing recommendations
-// from the reference implementation (focus-ai-website) — they produce the
+// from the reference implementation (reference-website) — they produce the
 // signature feel of the premium pattern set.
 // -----------------------------------------------------------------------
 export const SCROLL_TRIGGER_DEFAULTS = {

package/framework/scaffold/motion-premium/scaffold.yaml

@@ -15,11 +15,12 @@ framework:
   chati_dev: ">=4.3.0"
 
 stack:
-  build_tools: ["nextjs", "react-vite"]
+  build_tools: ["nextjs"]
   tailwind: ">=4.0.0"
   typescript: ">=5.0.0"
   node: ">=18.0.0"
   react: ">=18.0.0"
+  next: ">=13.0.0"
   # Runtime peer deps imported directly by templates. Bumping policy: every two
   # minor bumps, re-validate templates. GSAP 3.12 is the stable line post-3.11;
   # framer-motion 11 is the React 19 support line; lenis 1.1 introduced the
@@ -27,6 +28,10 @@ stack:
   gsap: "^3.12.5"
   "framer-motion": "^11.0.0"
   lenis: "^1.1.0"
+  # v4.3.1+: Playwright required for QA-Visual screenshot-based gate.
+  # Without it, visual-qa.js falls back to source-code analysis (gateway: WEAK).
+  # Run `npx playwright install chromium` once after npm install for the binary.
+  playwright: "^1.44.0"
 
 # Placeholder resolution — keys reference brand source fields.
 # Resolved once at scaffold apply time (Decision 3: install-time, one-shot).

package/framework/scaffold/motion-premium-3d/README.md

@@ -2,6 +2,16 @@
 
 React Three Fiber + Three.js scroll-driven 3D layer for premium sites. Extends `motion-premium` — apply that one FIRST (the 2D base), then this one on top.
 
+## Setup
+
+After `npm install`, run once to download the chromium browser binary used by QA-Visual screenshots:
+
+```bash
+npx playwright install chromium
+```
+
+QA-Visual Phase 3c uses real browser screenshots to count `canvas_hosts` and `scene_fallbacks` in the rendered DOM. Without chromium, R3F visual QA is blind.
+
 ## When to apply
 
 Apply when the project brief or Animation Inventory cites **explicit 3D intent**:

package/framework/scaffold/motion-premium-3d/components/webgl/WebGLContext.tsx.template

@@ -24,7 +24,7 @@ import { detectWebGL, type WebGLAvailability } from '@/lib/webgl/detect';
 
 export interface WebGLContextValue {
   status: 'pending' | 'available' | 'unavailable';
-  reason: WebGLAvailability extends { reason: infer R } ? R | null : null;
+  reason: Extract<WebGLAvailability, { available: false }>['reason'] | null;
   webglVersion: 1 | 2 | null;
 }
 

package/framework/scaffold/motion-premium-3d/scaffold.yaml

@@ -33,6 +33,9 @@ stack:
   # but also declares the dep so a standalone apply (no motion-premium first)
   # still has an accurate peer-dep surface.
   gsap: "^3.12.5"
+  # v4.3.1+: Playwright required for QA-Visual canvas_hosts + scene_fallbacks
+  # checks (Phase 3c). Without it, R3F visual QA is blind (canvas not screenshotted).
+  playwright: "^1.44.0"
 
 # Inherits motion-premium's brand placeholders — at apply time the loader
 # resolves identically (brand.ts > brandbook.md > interactive). SceneFallback

package/framework/scaffold/saas-dashboard/README.md

@@ -0,0 +1,58 @@
+# saas-dashboard scaffold preset
+
+A premium SaaS dashboard and app-shell starting point. Where the motion-premium
+presets target animated showcase sites, this preset targets the build-me-a-tool
+category: a data-dense application shell that looks designed, not generated.
+
+## What it ships
+
+29 templates across foundation, primitives, shell, data, interaction, and a
+composed sample page:
+
+- **Foundation**: `app/globals.css` (the full token system, fluid type scale,
+  reduced-motion handling, the `xl` breakpoint override), `lib/brand.ts` (typed
+  tokens), and the single `Container` authority for max-width and padding.
+- **Primitives**: `Button`, `Card`, `Input`, `Badge`, `Spinner`, each with full
+  resting, hover, active, disabled, and focus states.
+- **Shell**: `AppShell`, `Sidebar` (collapsible, keyboard-accessible, responsive
+  drawer), `Topbar` (search trigger, breadcrumb, user menu), `NavItem`,
+  `ThemeToggle`, `Breadcrumb`.
+- **Data**: `DataTable` (typed, sortable, sticky header, selection, empty and
+  loading states), `StatCard` and `StatCardGrid` (KPI with delta semantics and a
+  sparkline), `Chart` (a self-contained SVG area chart, no chart dependency).
+- **Interaction**: `CommandPalette` (Cmd+K, fuzzy filter, keyboard nav, hand
+  rolled, no extra dependency), `Field` and `Form` (labeled inputs, validation
+  states, never placeholder-only labels).
+- **Feedback**: `EmptyState`.
+- **Sample**: `app/dashboard/page.tsx` composes the shell, stat cards, a chart,
+  and a data table to demonstrate the preset.
+
+## Design system
+
+- **Color**: a calibrated dark palette built from a single neutral hue with even
+  perceptual luminance steps, a 6-color data-viz series, and a designed light
+  theme via `[data-theme="light"]` (never `filter: invert`). Every color is a
+  CSS custom property; components never carry a raw hex.
+- **Type**: a 1.25 modular scale with fluid `clamp()` values, role-differentiated
+  line-heights, and optical tracking.
+- **Space**: a 4px base unit tuned for data density.
+- **Motion**: cubic-bezier easing matched to the metaphor, a duration scale, and
+  full reduced-motion support. No linear easing, no `transition: all`.
+
+## Quality contract
+
+This preset is built to clear the QA-Visual rubric
+(`chati.dev/data/qa-rubrics.yaml`) on every dimension: layout, typography, color,
+spacing, interaction, motion, accessibility (WCAG 2.1 AA), and performance
+(animate only `transform` and `opacity`).
+
+## Dependencies
+
+`lucide-react` (icons) and `framer-motion` (micro-interactions). The chart and
+the command palette are hand-rolled, so there is no chart library and no command
+menu dependency.
+
+## Brandable
+
+The accent color (`ACCENT_HEX`, `ACCENT_HOVER_HEX`) is resolved at apply time
+from your brand source. The neutral and semantic scales are the designed system.