chati-dev 4.3.0 → 4.3.1

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');

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**
 

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
 ```
 
@@ -443,6 +444,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/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

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.3.0"
+version: "4.3.1"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-04-18T00:00:00Z"
-installer_version: "4.3.0"
+updated_at: "2026-04-29T00:00:00Z"
+installer_version: "4.3.1"
 project_type: greenfield
 language: en
 ides: [claude-code]

package/framework/data/entity-registry.yaml

@@ -3,8 +3,8 @@
 # and by the Health Check for system integrity validation.
 
 metadata:
-  version: "4.3.0"
-  last_updated: "2026-04-14T00:00:00Z"
+  version: "4.3.1"
+  last_updated: "2026-04-29T00:00:00Z"
   entity_count: 100
   checksum_algorithm: sha256
 

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;
     }
 
@@ -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.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.
 

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

@@ -27,6 +27,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/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/scripts/visual-qa.js

@@ -370,8 +370,20 @@ async function main() {
         if (chromium) break;
       } catch { /* try next */ }
     }
-    if (!chromium) throw new Error('Playwright not installed. Run: npx playwright install chromium');
-    const browser = await chromium.launch({ headless: true });
+    if (!chromium) {
+      // v4.3.1+ G17: disambiguate npm-package-missing from binary-missing for actionable hints
+      throw new Error('Playwright npm package missing. Run: npm install playwright');
+    }
+    let browser;
+    try {
+      browser = await chromium.launch({ headless: true });
+    } catch (e) {
+      if (e.message.includes("Executable doesn't exist")
+          || e.message.includes('browserType.launch')) {
+        throw new Error('Chromium binary missing. Run: npx playwright install chromium');
+      }
+      throw e;
+    }
     const report = { pages: [], summary: {} };
 
     for (const pagePath of pages) {

package/framework/templates/brandbook-html-tmpl.md

@@ -103,5 +103,5 @@ sections must exist and what each must contain.
 
 ## Reference
 
-See `/Users/ogabrielalonso/code/focus-ai/ping/docs/brand/brandbook.html` for a production
+See `<your-project>/docs/brand/brandbook.html` for a production
 example with 14 sections, sticky nav, dark mode toggle, and complete token rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "AI-Powered Multi-Agent Orchestration System - Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -32,7 +32,8 @@
     "prepublishOnly": "node scripts/sync-framework.js && node scripts/scan-stale.js && node scripts/validate-package.js && node scripts/sign-manifest.js",
     "test": "node --test test/**/*.test.js",
     "lint": "eslint src/ bin/",
-    "lint:fix": "eslint src/ bin/ --fix"
+    "lint:fix": "eslint src/ bin/ --fix",
+    "verify-v431": "npm test && node scripts/scan-stale.js && npm run sync && node scripts/validate-package.js && node test/fixtures/manual-smoke-v430-upgrade.mjs"
   },
   "keywords": [
     "ai",

package/src/installer/core.js

@@ -147,6 +147,15 @@ export async function installFramework(config) {
     join(frameworkDir, '_cli', 'node_modules')      // .chati.dev/_cli/node_modules/
   );
 
+  // v4.3.1+ — Write version stamp so chati-router.js can detect bundle/canonical
+  // mismatch on subsequent invocations. Pre-v4.3.1 installs lack this file;
+  // mismatch detection silent-skips when it's missing (graceful degradation).
+  writeFileSync(
+    join(frameworkDir, '_cli', 'version.json'),
+    JSON.stringify({ version, bundled_at: new Date().toISOString() }, null, 2),
+    'utf-8'
+  );
+
   // Write config.yaml
   writeFileSync(
     join(frameworkDir, 'config.yaml'),
@@ -701,7 +710,7 @@ function createDir(dir) {
  * Used to bundle the CLI source into the user's .chati.dev/_cli/ folder so
  * the framework runs self-contained (no `npx chati-dev` dependency).
  */
-function copyCliSource(srcDir, destDir) {
+export function copyCliSource(srcDir, destDir) {
   if (!existsSync(srcDir)) return;
   createDir(destDir);
   const entries = readdirSync(srcDir);
@@ -748,7 +757,7 @@ function copyDirVerbatim(srcDir, destDir) {
  * which works whether the package is hoisted or nested in the user's
  * node_modules (npx cache, npm install, etc.).
  */
-function copyCliDependencies(pkgDir, destNodeModules) {
+export function copyCliDependencies(pkgDir, destNodeModules) {
   let pkg;
   try {
     pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));

package/src/orchestrator/cli.js

@@ -634,6 +634,17 @@ function writeSessionLock(projectDir, currentAgent, stateInfo = {}) {
   const localMdPath = join(projectDir, 'CLAUDE.local.md');
   let content = existsSync(localMdPath) ? readFileSync(localMdPath, 'utf-8') : '';
 
+  // Phase display is authoritatively driven by session.mode on disk. Callers
+  // previously passed stateInfo.phase derived from transient intermediate
+  // values (the next agent's expected phase before user approval), causing
+  // the lock to drift ahead of session.yaml (e.g. show "build" while
+  // session.mode was still "plan" awaiting approval).
+  let authoritativePhase = null;
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session?.mode) authoritativePhase = session.mode;
+  } catch { /* non-fatal — fall back to stateInfo */ }
+
   const lockInner = `## Session Lock -- ACTIVE
 
 **Chati.dev session is ACTIVE.** Follow these rules for EVERY message:
@@ -645,7 +656,7 @@ function writeSessionLock(projectDir, currentAgent, stateInfo = {}) {
 
   const stateInner = `## Current State
 - **Agent**: ${currentAgent || 'None'}
-- **Phase**: ${stateInfo.phase || 'discover'}
+- **Phase**: ${authoritativePhase || stateInfo.phase || 'discover'}
 - **Pipeline**: ${stateInfo.position ?? 0}/${stateInfo.total ?? '?'} (${stateInfo.progress ?? 0}%)
 - **Mode**: ${stateInfo.mode || 'interactive'}`;
 

package/src/orchestrator/session-manager.js

@@ -171,6 +171,14 @@ export function migrateSession(session) {
   const fromVersion = session.schema_version || null;
   session.schema_version = CURRENT_SCHEMA_VERSION;
 
+  // Seed required scalar fields absent from pre-v4.3.0 sessions.
+  // validateSession() requires version/mode/project_type; older sessions may lack them.
+  // Without these guards, upgrade-path catastrophe (data-centralisation E2E 2026-04-28):
+  // v3.x install → v4.3.0 migrate adds schema_version: '1.2' but validator fails on missing fields.
+  if (!session.version)      session.version = '1.0';
+  if (!session.mode)         session.mode = 'discover';
+  if (!session.project_type) session.project_type = session.project?.type || 'greenfield';
+
   // Ensure fields added in v1.0 exist
   if (!session.completed_agents) session.completed_agents = [];
   if (!session.agent_results) session.agent_results = {};