chati-dev 4.4.0 → 4.4.1

package/framework/manifest.sig

@@ -0,0 +1 @@
+EK1FsSHB+n5Dbo2dRSF1DPgRD35si2lygeQvPZZp91Vy069v6AlHbK/delS4LVkj/sAU7Tp5PoulKchOCF75AQ==

package/framework/orchestrator/chati.md

@@ -833,10 +833,13 @@ The orchestrator enforces `chati.dev/constitution.md`:
 
 | Level | Action | Articles |
 |-------|--------|----------|
-| **BLOCK** | Halt agent on violation | I, II, III, IV, VII, VIII, X, XI, XII, XIII, XV, XVIII, XX, XXI, XXII |
+| **BLOCK** | Halt agent on violation | I, II, III, IV, V, VII, VIII, X, XI, XII, XIII, XV, XX, XXI, XXII, XXIII |
 | **STRICT** | Must not bypass quality gates | XVII |
-| **GUIDE** | Correct without halting | V, IX, XIV, XVI, XIX |
+| **GUIDE** | Correct without halting | IX, XIV, XVI, XIX, XXIV |
 | **WARN** | Generate warning in QA | VI |
+| **FLAG** | Feature-flagged (inert until enabled) | XXV |
+
+Article XVIII was deprecated 2026-04-18 and folded into Article XVII; it carries no enforcement level.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "description": "AI-Powered Multi-Agent Orchestration System - Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
     "sync": "node scripts/sync-framework.js",
     "scan": "node scripts/scan-stale.js",
     "install-to": "node scripts/install-to.js",
-    "prepublishOnly": "node scripts/sync-framework.js && node scripts/scan-stale.js && node scripts/validate-package.js && node scripts/sign-manifest.js",
+    "prepublishOnly": "node scripts/sync-framework.js && node scripts/scan-stale.js && node scripts/sign-manifest.js && REQUIRE_SIGNED_MANIFEST=1 node scripts/validate-package.js",
     "test": "node --test test/**/*.test.js",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",

package/src/config/claude-settings-generator.js

@@ -30,6 +30,7 @@ const HOOK_REGISTRY = [
   //   2. PreToolUse catch-all below (backup — Claude sees deny reason, reports it)
   { name: 'prism-engine',      event: 'UserPromptSubmit', matcher: '.*' },
   { name: 'model-governance',  event: 'UserPromptSubmit', matcher: '.*' },
+  { name: 'reasoning-escalator', event: 'UserPromptSubmit', matcher: '.*' },
 
   // PreToolUse — fires before each tool call. Matcher targets specific tools.
   // license-guard is first on catch-all ".*" — blocks ALL tool calls when
@@ -38,11 +39,13 @@ const HOOK_REGISTRY = [
   // no tool call succeeds with an expired license.
   { name: 'license-guard',     event: 'PreToolUse', matcher: '.*' },
   { name: 'read-protection',   event: 'PreToolUse', matcher: 'Read' },
-  { name: 'constitution-guard',event: 'PreToolUse', matcher: 'Bash|Write|Edit' },
-  { name: 'mode-governance',   event: 'PreToolUse', matcher: 'Write|Edit' },
-  { name: 'style-guard',       event: 'PreToolUse', matcher: 'Write|Edit|Bash' },
-  { name: 'undercover-guard',  event: 'PreToolUse', matcher: 'Write|Edit|Bash' },
-  { name: 'team-quality-gate', event: 'PreToolUse', matcher: 'Write|Edit' },
+  { name: 'constitution-guard',event: 'PreToolUse', matcher: 'Bash|Write|Edit|NotebookEdit' },
+  { name: 'git-push-authority', event: 'PreToolUse', matcher: 'Bash' },
+  { name: 'mode-governance',   event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit' },
+  { name: 'style-guard',       event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit|Bash' },
+  { name: 'undercover-guard',  event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit|Bash' },
+  { name: 'team-quality-gate', event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit' },
+  { name: 'reasoning-escalator', event: 'PreToolUse', matcher: 'Write|Edit|NotebookEdit' },
 
   // PostToolUse — fires after each tool call. Used to auto-advance the pipeline
   // when an agent finishes writing its handoff. Hook inspects the written path
@@ -55,7 +58,7 @@ const HOOK_REGISTRY = [
   { name: 'post-dev',          event: 'PostToolUse', matcher: 'Write' },
 
   // PreCompact — fires before context compaction (observational).
-  { name: 'session-digest',    event: 'PreCompact', matcher: '' },
+  { name: 'session-digest',    event: 'PreCompact', matcher: '.*' },
 ];
 
 /**

package/src/installer/core.js

@@ -224,7 +224,7 @@ export async function installFramework(config) {
  *
  * New files added to the source framework are picked up automatically.
  */
-const FRAMEWORK_DIRS_TO_COPY = [
+export const FRAMEWORK_DIRS_TO_COPY = [
   'orchestrator',
   'agents',
   'templates',
@@ -824,7 +824,7 @@ export function copyCliDependencies(pkgDir, destNodeModules) {
  * If the file exists but is malformed: leave it alone, log a warning. We will
  * not silently destroy user data.
  */
-function writeClaudeSettingsWithMerge(settingsPath) {
+export function writeClaudeSettingsWithMerge(settingsPath) {
   createDir(dirname(settingsPath));
   const fresh = JSON.parse(generateClaudeSettings());
 
@@ -878,7 +878,37 @@ export function mergeClaudeSettings(existing, fresh) {
   merged.hooks = { ...existingHooks };
 
   for (const [eventName, freshGroups] of Object.entries(freshHooks)) {
-    const existingGroups = existingHooks[eventName] || [];
+    let existingGroups = existingHooks[eventName] || [];
+
+    // Widened-matcher upgrade: when a chati hook's matcher grows (e.g.
+    // Write|Edit -> Write|Edit|NotebookEdit), the old registration must be
+    // REPLACED, not kept alongside the new one - otherwise the hook fires
+    // twice for the overlapping tools on every upgraded install and
+    // settings.json grows without bound. Drop an existing registration of a
+    // command when the fresh settings register the SAME command on a matcher
+    // that is a strict superset of the existing one. A user-widened matcher
+    // (existing wider than fresh) is left untouched.
+    const toolsOf = (matcher) =>
+      matcher === '.*' || matcher === '' || matcher == null ? null : String(matcher).split('|');
+    const covers = (superTools, subTools) =>
+      superTools === null || (subTools !== null && subTools.every((t) => superTools.includes(t)));
+    const freshByCommand = new Map();
+    for (const g of freshGroups) {
+      for (const h of g.hooks || []) {
+        freshByCommand.set(h.command, { matcher: g.matcher, tools: toolsOf(g.matcher) });
+      }
+    }
+    existingGroups = existingGroups
+      .map((group) => ({
+        ...group,
+        hooks: (group.hooks || []).filter((h) => {
+          const freshReg = freshByCommand.get(h.command);
+          if (!freshReg || freshReg.matcher === group.matcher) return true;
+          return !covers(freshReg.tools, toolsOf(group.matcher));
+        }),
+      }))
+      .filter((group) => (group.hooks || []).length > 0);
+
     // Append fresh groups; we don't dedup at the group level (different
     // matchers are different groups). Within a single fresh group, the
     // hook commands are unique to chati so duplication risk is minimal.

package/src/installer/manifest.js

@@ -138,12 +138,38 @@ export function compareManifests(oldManifest, newManifest) {
  * @param {string} signatureBase64 - Base64-encoded Ed25519 signature
  * @returns {{ valid: boolean, reason: string }}
  */
-export function verifyManifest(manifest, signatureBase64) {
-  if (!SIGNING_PUBLIC_KEY) return { valid: false, reason: 'no-public-key' };
+export function verifyManifest(manifest, signatureBase64, publicKeyPem = null) {
+  // publicKeyPem is a test seam: production callers use the embedded key.
+  const key = publicKeyPem ? createPublicKey(publicKeyPem) : SIGNING_PUBLIC_KEY;
+  if (!key) return { valid: false, reason: 'no-public-key' };
 
-  const manifestJson = JSON.stringify(manifest, Object.keys(manifest).sort(), 2);
+  const manifestJson = serializeManifest(manifest);
   const signature = Buffer.from(signatureBase64, 'base64');
 
-  const valid = cryptoVerify(null, Buffer.from(manifestJson), SIGNING_PUBLIC_KEY, signature);
+  const valid = cryptoVerify(null, Buffer.from(manifestJson), key, signature);
   return { valid, reason: valid ? 'ok' : 'signature-mismatch' };
 }
+
+/**
+ * Canonical manifest serialization used by BOTH signing and verification.
+ *
+ * MUST NOT use a JSON.stringify replacer ARRAY: a replacer array filters keys
+ * at EVERY depth, so the per-file path keys inside `files` were dropped and
+ * the signature attested to an empty file map (and the written manifest.json
+ * itself contained "files": {}). Determinism comes from sorting the top-level
+ * keys and the files map explicitly.
+ *
+ * @param {object} manifest
+ * @returns {string}
+ */
+export function serializeManifest(manifest) {
+  const sorted = Object.fromEntries(
+    Object.entries(manifest).sort(([a], [b]) => a.localeCompare(b))
+  );
+  if (sorted.files && typeof sorted.files === 'object') {
+    sorted.files = Object.fromEntries(
+      Object.entries(sorted.files).sort(([a], [b]) => a.localeCompare(b))
+    );
+  }
+  return JSON.stringify(sorted, null, 2);
+}

package/src/installer/signing-public-key.pem

@@ -1,3 +1,3 @@
 -----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEA8thWGs1GHKpeJyUTejpBwp8TZ7iZiN3vDxGDoQf8dMs=
+MCowBQYDK2VwAyEAgo4u1bUZttpuxRluFnZc+3AMQH+U5xWEURN41kv/s0A=
 -----END PUBLIC KEY-----

package/src/installer/validator.js

@@ -5,6 +5,7 @@ import { hashFile } from './file-hasher.js';
 import { loadManifest } from './manifest.js';
 import { ADAPTABLE_FILES } from '../config/framework-adapter.js';
 import { validateSchema, CONFIG_SCHEMA } from '../utils/schema-validator.js';
+import { EXPECTED_ARTICLE_COUNT } from '../utils/constitution-meta.js';
 
 function resolveFrameworkDir(targetDir) {
   if (existsSync(join(targetDir, '.chati.dev'))) return '.chati.dev';
@@ -72,7 +73,7 @@ export async function validateInstallation(targetDir) {
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    results.constitution.pass = articleCount >= 22;
+    results.constitution.pass = articleCount === EXPECTED_ARTICLE_COUNT;
     results.constitution.details.push({ articleCount });
   }
   results.total += 1;

package/src/intelligence/registry-manager.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { EXPECTED_ARTICLE_COUNT } from '../utils/constitution-meta.js';
 import { flattenEntitiesMap } from '../utils/flatten-entities.js';
 
 /**
@@ -143,7 +144,7 @@ export function runHealthCheck(targetDir) {
   if (existsSync(constitutionPath)) {
     const content = readFileSync(constitutionPath, 'utf-8');
     const articleCount = (content.match(/^## Article/gm) || []).length;
-    checks.constitution.pass = articleCount >= 22;
+    checks.constitution.pass = articleCount === EXPECTED_ARTICLE_COUNT;
     checks.constitution.details = `${articleCount} articles`;
   } else {
     checks.constitution.details = 'Not found';

package/src/memory/magic-docs.js

@@ -12,7 +12,12 @@ import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
 const SECTION_HEADER = '## Current State';
-const SECTION_REGEX = /^## Current State\n([\s\S]*?)(?=\n## |\n---|\n$|$)/m;
+// The section ends at the next `## ` heading, a `---` rule, or the TRUE end of
+// the file. `$(?![\s\S])` is the absolute end-of-string: with the `m` flag a
+// bare `$` matches at every line end, which made the lazy capture stop after
+// the FIRST content line, orphaning the rest of the section below the
+// replacement on every write (the corruption grew with each update).
+const SECTION_REGEX = /^## Current State\n([\s\S]*?)(?=\n## |\n---|$(?![\s\S]))/m;
 
 /**
  * Update CLAUDE.md with current project state after a handoff.

package/src/orchestrator/cli.js

@@ -42,7 +42,8 @@ import { analyzeDeviationImpact, applyDeviation } from './index.js';
 import { detectQuickFlow, detectStandardFlow } from './index.js';
 import { getAgentFile } from '../terminal/prompt-builder.js';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
-import { join, resolve } from 'path';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import yaml from 'js-yaml';
 import {
@@ -53,6 +54,15 @@ import {
 } from '../intelligence/timeline.js';
 import { updateClaudeMd } from '../memory/magic-docs.js';
 
+// Spawn commands must reference the terminal runners with an absolute,
+// layout-independent path: the old monorepo-relative
+// 'packages/chati-dev/src/terminal/...' only resolves when the command runs
+// from the monorepo root, never in an installed project (.chati.dev/_cli/ or
+// node_modules). Anchoring to this file's own location works in every layout
+// because the src/ tree shape is preserved verbatim by the CLI bundling.
+const _THISDIR = dirname(fileURLToPath(import.meta.url));
+const RUNNER = (name) => JSON.stringify(join(_THISDIR, '..', 'terminal', name));
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -533,13 +543,14 @@ function sessionToPipelineState(session, projectDir) {
 
 /**
  * Build the spawn command string for an autonomous agent.
+ * Exported for testing (path resolution must hold in every install layout).
  */
-function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
+export function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
   const parts = [
-    'node', 'packages/chati-dev/src/terminal/run-agent.js',
+    'node', RUNNER('run-agent.js'),
     '--agent', agent,
     '--task-id', `${agent}-task`,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
     '--timeout', String(timeout || 600000),
@@ -549,14 +560,15 @@ function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout)
 
 /**
  * Build the parallel spawn command string.
+ * Exported for testing.
  */
-function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
+export function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
   const taskIds = agents.map(a => `${a}-task`).join(',');
   const parts = [
-    'node', 'packages/chati-dev/src/terminal/run-parallel.js',
+    'node', RUNNER('run-parallel.js'),
     '--agents', agents.join(','),
     '--task-ids', taskIds,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
     '--timeout', String(timeout || 900000),
@@ -2700,10 +2712,10 @@ async function handleSpawnTeam(projectDir, args) {
 
   // Build spawn command
   const spawnCmd = [
-    'node', join('packages', 'chati-dev', 'src', 'terminal', 'run-team.js'),
+    'node', RUNNER('run-team.js'),
     '--team-id', teamId,
     '--team-type', teamType,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent,
     '--provider', provider,
     '--timeout', args.timeout || '1800000',

package/src/orchestrator/deviation-handler.js

@@ -105,7 +105,9 @@ export function detectDeviation(userMessage, _pipelineState) {
  * @returns {{ impact: 'low'|'medium'|'high', affectedAgents: string[], recommendation: string, requiresConfirmation: boolean }}
  */
 export function analyzeDeviationImpact(deviationType, pipelineState, details = {}) {
-  const currentAgent = pipelineState.current_agent;
+  // sessionToPipelineState produces camelCase (currentAgent); accept the legacy
+  // snake_case shape too so direct callers keep working.
+  const currentAgent = pipelineState.currentAgent ?? pipelineState.current_agent;
   const completedAgents = Object.entries(pipelineState.agents || {})
     .filter(([, data]) => data.status === 'completed')
     .map(([name]) => name);
@@ -268,7 +270,7 @@ export function applyDeviation(pipelineState, deviationType, details) {
           changes.push(`Reset agent: ${agentName}`);
         }
 
-        newState.current_agent = targetAgent;
+        newState.currentAgent = targetAgent;
         changes.push(`Rolled back to: ${targetAgent}`);
 
         break;
@@ -302,7 +304,7 @@ export function applyDeviation(pipelineState, deviationType, details) {
         }
 
         // Reset to initial state
-        newState.current_agent = '';
+        newState.currentAgent = '';
         newState.backlog = [];
         changes.push('Reset all agents to initial state');
 

package/src/terminal/run-parallel.js

@@ -16,7 +16,7 @@
 
 import { fileURLToPath } from 'url';
 import { buildAgentPrompt } from './prompt-builder.js';
-import { spawnParallelGroup, spawnTerminal } from './spawner.js';
+import { spawnParallelGroup, spawnTerminal, killTerminal } from './spawner.js';
 import { TerminalMonitor } from './monitor.js';
 import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
 import { parseAgentOutput } from './handoff-parser.js';
@@ -254,13 +254,13 @@ async function main() {
  * @param {number} timeout - Per-agent timeout in ms
  * @returns {Promise<{ groupId: string, terminals: object[] }>}
  */
-async function sequentialFallback(configs, timeout) {
+async function sequentialFallback(configs, timeout, _spawnFn = spawnTerminal) {
   const groupId = `seq-fallback-${Date.now()}`;
   const terminals = [];
 
   for (let i = 0; i < configs.length; i++) {
     const cfg = configs[i];
-    const terminal = spawnTerminal({
+    const handle = _spawnFn({
       agent: cfg.agent,
       taskId: cfg.taskId,
       model: cfg.model,
@@ -270,26 +270,26 @@ async function sequentialFallback(configs, timeout) {
       timeout: cfg.timeout || timeout,
     });
 
-    // Wait for this terminal to finish before spawning the next
+    // Wait for the REAL process exit before spawning the next agent. The old
+    // implementation probed terminal.onExit?.(), a method TerminalHandle never
+    // had, so every agent "completed" instantly and the fallback ran the whole
+    // group in parallel - defeating its purpose (shedding rate-limit pressure).
     await new Promise((resolve) => {
-      const timer = setTimeout(() => {
-        terminal.kill?.();
+      if (!handle?.process || handle.status !== 'running') {
         resolve();
+        return;
+      }
+      const timer = setTimeout(() => {
+        killTerminal(handle).catch(() => {}).then(resolve, resolve);
       }, (cfg.timeout || timeout) + 5_000);
 
-      terminal.onExit?.(() => {
+      handle.process.once('exit', () => {
         clearTimeout(timer);
         resolve();
       });
-
-      // If terminal doesn't have onExit, resolve after a short poll
-      if (!terminal.onExit) {
-        clearTimeout(timer);
-        resolve();
-      }
     });
 
-    terminals.push(terminal);
+    terminals.push(handle);
 
     // Small delay between spawns to avoid rate limit pressure
     if (i < configs.length - 1) {

package/src/upgrade/backup.js

@@ -1,6 +1,24 @@
 import { existsSync, mkdirSync, cpSync, rmSync } from 'fs';
 import { join } from 'path';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { FRAMEWORK_DIRS_TO_COPY } from '../installer/core.js';
+
+/**
+ * The backup must cover exactly what the upgrade overwrites, or a rollback
+ * leaves the install in a chimera state (some dirs at the new version, some
+ * restored). The upgrade replaces every dir in FRAMEWORK_DIRS_TO_COPY (via
+ * copyFrameworkFiles), so that same list is the backup/restore scope - one
+ * source of truth, no asymmetry. Previously the backup saved 12 dirs and the
+ * restore returned only 10 (intelligence and data were backed up but never
+ * restored; hooks, domains, tasks, scaffold and others were never backed up
+ * at all).
+ */
+const BACKUP_DIRS = FRAMEWORK_DIRS_TO_COPY;
+
+const BACKUP_FILES = [
+  'constitution.md',
+  'config.yaml',
+];
 
 /**
  * Create backup of chati.dev/ directory before upgrade
@@ -17,28 +35,7 @@ export function createBackup(targetDir, currentVersion) {
 
   mkdirSync(backupDir, { recursive: true });
 
-  // Backup framework files (NOT artifacts or intelligence)
-  const dirsToBackup = [
-    'orchestrator',
-    'agents',
-    'templates',
-    'workflows',
-    'quality-gates',
-    'schemas',
-    'frameworks',
-    'i18n',
-    'patterns',
-    'migrations',
-    'intelligence',
-    'data',
-  ];
-
-  const filesToBackup = [
-    'constitution.md',
-    'config.yaml',
-  ];
-
-  for (const dir of dirsToBackup) {
+  for (const dir of BACKUP_DIRS) {
     const src = join(frameworkDir, dir);
     const dest = join(backupDir, dir);
     if (existsSync(src)) {
@@ -46,7 +43,7 @@ export function createBackup(targetDir, currentVersion) {
     }
   }
 
-  for (const file of filesToBackup) {
+  for (const file of BACKUP_FILES) {
     const src = join(frameworkDir, file);
     const dest = join(backupDir, file);
     if (existsSync(src)) {
@@ -68,26 +65,7 @@ export function restoreFromBackup(targetDir, version) {
     throw new Error(`Backup not found: ${backupDir}`);
   }
 
-  // Restore backed-up directories
-  const dirsToRestore = [
-    'orchestrator',
-    'agents',
-    'templates',
-    'workflows',
-    'quality-gates',
-    'schemas',
-    'frameworks',
-    'i18n',
-    'patterns',
-    'migrations',
-  ];
-
-  const filesToRestore = [
-    'constitution.md',
-    'config.yaml',
-  ];
-
-  for (const dir of dirsToRestore) {
+  for (const dir of BACKUP_DIRS) {
     const src = join(backupDir, dir);
     const dest = join(frameworkDir, dir);
     if (existsSync(src)) {
@@ -98,7 +76,7 @@ export function restoreFromBackup(targetDir, version) {
     }
   }
 
-  for (const file of filesToRestore) {
+  for (const file of BACKUP_FILES) {
     const src = join(backupDir, file);
     const dest = join(frameworkDir, file);
     if (existsSync(src)) {

package/src/upgrade/migrator.js

@@ -42,13 +42,25 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
   for (const file of files) {
     try {
       const content = yaml.load(readFileSync(join(migrationsDir, file), 'utf-8'));
-      const migration = content?.migration;
+      // Two header schemas exist: the nested `migration: { from, to }` form and
+      // the older flat `from_version`/`to_version` form (with `operations`
+      // instead of `steps`). The flat files were silently skipped here, which
+      // hid them from every upgrade.
+      const migration = content?.migration
+        ?? (content?.from_version && content?.to_version
+          ? { from: content.from_version, to: content.to_version, description: content.description, breaking: content.breaking }
+          : null);
 
       if (!migration?.from || !migration?.to) continue;
 
-      // Check if this migration is in the upgrade path
+      // A migration applies when its TARGET version lies inside the upgrade
+      // interval (fromVersion, toVersion]. The old condition compared the
+      // migration's `from` against the user's version with gte, which skipped
+      // every pending migration for users sitting ABOVE a migration's starting
+      // point (a 4.2.3 user never received v4.2-to-v4.3) and is wrong for
+      // users below it too (a 3.x user needs every step on the way up).
       if (
-        semver.gte(migration.from, fromVersion) &&
+        semver.gt(migration.to, fromVersion) &&
         semver.lte(migration.to, toVersion)
       ) {
         applicable.push({
@@ -57,7 +69,7 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
           to: migration.to,
           description: migration.description || '',
           breaking: migration.breaking || false,
-          steps: content.steps || [],
+          steps: content.steps || content.operations || [],
           rollback: content.rollback || [],
         });
       }
@@ -73,14 +85,20 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
 }
 
 /**
- * Execute a single migration step
+ * Execute a single migration step. Exported for testing.
  */
-async function executeMigrationStep(targetDir, step) {
+export async function executeMigrationStep(targetDir, step, sourceFile = '') {
   switch (step.type) {
     case 'create_directory': {
-      const dir = join(targetDir, step.path);
-      if (!existsSync(dir) || !step.idempotent) {
-        mkdirSync(dir, { recursive: true });
+      // Both shapes exist in the migration corpus: `path` (string) in the
+      // nested-schema files and `paths` (array) in the older flat-schema ones.
+      const dirs = Array.isArray(step.paths) ? step.paths : [step.path];
+      for (const rel of dirs) {
+        if (!rel) continue;
+        const dir = join(targetDir, rel);
+        if (!existsSync(dir) || !step.idempotent) {
+          mkdirSync(dir, { recursive: true });
+        }
       }
       break;
     }
@@ -100,7 +118,19 @@ async function executeMigrationStep(targetDir, step) {
 
       const content = yaml.load(readFileSync(filePath, 'utf-8')) || {};
 
-      if (step.operation === 'add_field') {
+      if (step.changes && typeof step.changes === 'object') {
+        // Older flat-schema shape: a `changes:` map of (possibly dotted)
+        // field -> value, applied as a plain set.
+        for (const [field, value] of Object.entries(step.changes)) {
+          const keys = field.split('.');
+          let obj = content;
+          for (let i = 0; i < keys.length - 1; i++) {
+            if (!obj[keys[i]]) obj[keys[i]] = {};
+            obj = obj[keys[i]];
+          }
+          obj[keys[keys.length - 1]] = value;
+        }
+      } else if (step.operation === 'add_field') {
         const keys = step.field.split('.');
         let obj = content;
         for (let i = 0; i < keys.length - 1; i++) {
@@ -176,7 +206,16 @@ async function executeMigrationStep(targetDir, step) {
     }
 
     default:
-      // Unknown step type - skip
+      // Copy-style steps (copy_file, copy_directory) from the older flat-schema
+      // migrations are subsumed by the upgrade's blanket copyFrameworkFiles, so
+      // skipping them is correct. Anything else unknown is surfaced instead of
+      // silently dropped, so an upgrader from a very old version knows what to
+      // review manually.
+      if (step.type !== 'copy_file' && step.type !== 'copy_directory') {
+        process.stderr.write(
+          `[chati] warning: migration step type "${step.type}"${sourceFile ? ` in ${sourceFile}` : ''} is not auto-executable; review the migration file manually\n`
+        );
+      }
       break;
   }
 }
@@ -196,7 +235,7 @@ export async function runMigrations(targetDir, fromVersion, toVersion) {
   for (const migration of migrations) {
     try {
       for (const step of migration.steps) {
-        await executeMigrationStep(targetDir, step);
+        await executeMigrationStep(targetDir, step, migration.file);
       }
       results.push({ file: migration.file, success: true });
     } catch (err) {

package/src/utils/constitution-meta.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Single source of truth for constitution metadata used by
+ * integrity checks.
+ *
+ * Every check that counts `## Article` headings (doctor, registry health,
+ * installer validator, stale-scan check 13) compares against THIS constant,
+ * so adding a constitutional article is a one-line bump here. The stale-scan
+ * asserts the canonical constitution.md actually contains this many articles,
+ * which keeps the constant honest.
+ */
+
+export const EXPECTED_ARTICLE_COUNT = 25;