ultra-builder-pro-cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-07-16
+
+### Changed
+
+- Made task lifecycle workflows fail closed when MCP state is unavailable or
+  reports an authority conflict. Removed the nonexistent task create/update/list
+  CLI fallbacks from Claude Code, OpenCode, and Codex workflow assets.
+- Advanced the state schema to `8A.2` so `estimated_days` is authoritative and
+  survives MCP create/update, projection, and legacy migration.
+
+### Fixed
+
+- Fixed the v4.4→v4.5 migration for the real Ultra task shape: top-level
+  `version`, `dependencies`, relative `contexts/...` paths, date-only project
+  timestamps, and task rows without individual timestamps.
+- Added a state-authority gate that returns `LEGACY_STATE_MIGRATION_REQUIRED`
+  when a non-empty v4.4 task projection meets an empty state database, instead
+  of returning a misleading empty task list.
+- Made migration task/event inserts atomic, refused merges into a non-empty task
+  table, projected immediately after success, and preserved context bodies while
+  removing obsolete duplicate status banners and retired memory-hook references.
+- Added deterministic projection-write guards for Claude Code `Edit|Write`,
+  OpenCode `tool.execute.before`, and Codex `Edit|Write|apply_patch` during active
+  Ultra workflows.
+
 ## [0.5.0] — 2026-07-16
 
 ### Added
@@ -186,7 +211,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.5.0
 [0.4.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.4.0
 [0.3.0]: https://github.com/rocky2431/ultra-builder-pro-cli/releases/tag/v0.3.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.5.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.5.1-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)

package/adapters/_shared/codex-assets.cjs

@@ -818,7 +818,7 @@ function buildHooksManifest() {
         { hooks: [commandHook('workflow_context.py', 10, 'Loading active Ultra workflow')] },
       ],
       PreToolUse: [
-        { matcher: 'Edit|Write', hooks: [commandHook('active_task_context.py', 3, 'Checking active Ultra task')] },
+        { matcher: 'Edit|Write|apply_patch', hooks: [commandHook('active_task_context.py', 3, 'Checking active Ultra task')] },
       ],
       PreCompact: [
         { matcher: 'manual|auto', hooks: [commandHook('workflow_checkpoint.py', 10, 'Saving Ultra workflow checkpoint')] },

package/adapters/opencode.js

@@ -341,6 +341,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 const TERMINAL = new Set(["committed", "completed", "done", "cancelled"]);
+const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
 
 function findActiveWorkflow(directory) {
   let current = path.resolve(directory);
@@ -374,6 +375,25 @@ function contextText(active) {
   ].join("\\n");
 }
 
+function targetPaths(tool, args) {
+  if (!args || typeof args !== "object") return [];
+  const paths = [args.file_path, args.filePath, args.filepath, args.path]
+    .filter((value) => typeof value === "string" && value.length > 0);
+  const patch = args.patch ?? args.command;
+  if (String(tool).toLowerCase() === "apply_patch" && typeof patch === "string") {
+    const pattern = /^\\*\\*\\* (?:Add|Update|Delete) File: (.+?)\\s*$/gm;
+    for (const match of patch.matchAll(pattern)) paths.push(match[1].trim());
+  }
+  return [...new Set(paths)];
+}
+
+function isTasksProjection(active, candidate) {
+  const target = path.isAbsolute(candidate)
+    ? path.resolve(candidate)
+    : path.resolve(active.root, candidate);
+  return target === path.resolve(active.root, TASKS_PROJECTION);
+}
+
 export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
   const root = worktree || directory;
   let active = findActiveWorkflow(root);
@@ -390,7 +410,18 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
       refresh();
       if (active) output.context.push(contextText(active));
     },
-    "tool.execute.before": async () => { refresh(); },
+    "tool.execute.before": async (input, output) => {
+      refresh();
+      if (!active) return;
+      const tool = String(input?.tool ?? "").toLowerCase();
+      if (!["write", "edit", "apply_patch"].includes(tool)) return;
+      if (targetPaths(tool, output?.args).some((candidate) => isTasksProjection(active, candidate))) {
+        throw new Error(
+          "Ultra Builder Pro refused a direct write to .ultra/tasks/tasks.json. " +
+          ".ultra/state.db is authoritative; use MCP task tools or run the required v4.4 to v4.5 migration."
+        );
+      }
+    },
     "tool.execute.after": async () => { refresh(); },
   };
 };

package/adapters/tests/claude.test.cjs

@@ -55,6 +55,8 @@ test('Claude plugin collaboration and learn workflows are safe native plugin ass
     const geminiCollab = read('gemini-collab');
     const verify = read('ultra-verify');
     const review = read('ultra-review');
+    const plan = read('ultra-plan');
+    const status = read('ultra-status');
 
     assert.match(learn, /~\/.claude\/skills\/learned-<pattern-slug>-unverified\/SKILL\.md/);
     assert.doesNotMatch(learn, /_unverified\.md/);
@@ -64,6 +66,10 @@ test('Claude plugin collaboration and learn workflows are safe native plugin ass
     assert.match(verify, /-s read-only/);
     assert.match(verify, /\$CLAUDE_PLUGIN_ROOT\/skills\/ultra-verify\/scripts\/verify_wait\.py/);
     assert.match(review, /\$CLAUDE_PLUGIN_ROOT\/skills\/ultra-review\/scripts\/review_wait\.py/);
+    assert.match(plan, /LEGACY_STATE_MIGRATION_REQUIRED/);
+    assert.match(plan, /never read or write .*tasks\.json/i);
+    assert.match(status, /never fall back .*tasks\.json/i);
+    assert.doesNotMatch(plan, /ultra-tools task create/);
 
     for (const [name, contents] of Object.entries({ codexCollab, geminiCollab, verify })) {
       assert.doesNotMatch(contents, /--yolo|--full-auto|\/codex:/, name);

package/adapters/tests/codex-hook.test.cjs

@@ -74,6 +74,31 @@ test('Codex hook adapter maps apply_patch payloads to Edit-compatible file input
   assert.ok(outputs.every((entry) => entry.tool_name === 'Edit'));
 });
 
+test('Codex hook adapter denies apply_patch writes to tasks.json during an active Ultra workflow', () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-codex-hook-deny-'));
+  try {
+    fs.mkdirSync(path.join(project, '.ultra'));
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-plan', task_id: 'plan', step: 'persist', status: 'active',
+    }));
+    const result = run('active_task_context.py', {
+      session_id: 'session-deny',
+      cwd: project,
+      hook_event_name: 'PreToolUse',
+      tool_name: 'apply_patch',
+      tool_input: {
+        patch: '*** Begin Patch\n*** Update File: .ultra/tasks/tasks.json\n*** End Patch',
+      },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.hookSpecificOutput.permissionDecision, 'deny');
+    assert.match(output.hookSpecificOutput.permissionDecisionReason, /\.ultra\/state\.db/);
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('Codex hook adapter converts compact recovery context to PostCompact schema', () => {
   const script = [
     'import importlib.util, json, pathlib',

package/adapters/tests/codex.test.cjs

@@ -147,6 +147,12 @@ test('every generated skill is Codex-valid, UI-visible, and free of Claude host
     assert.match(review, /native Codex custom agents/);
     assert.match(review, /~\/plugins\/ultra-builder-pro\/skills\/ultra-review/);
 
+    const plan = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-plan', 'SKILL.md'), 'utf8');
+    const status = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-status', 'SKILL.md'), 'utf8');
+    assert.match(plan, /LEGACY_STATE_MIGRATION_REQUIRED/);
+    assert.match(plan, /Never read or write .*tasks\.json/i);
+    assert.match(status, /Never fall back to .*tasks\.json/i);
+
     const coreWorkflowText = [
       ...COMMANDS,
       'ultra-review',
@@ -196,6 +202,7 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     }
     assert.doesNotMatch(serializedHooks, /memory|recall|journal|observation_capture|user_prompt_capture|block_dangerous|post_edit_guard/);
     assert.match(serializedHooks, /\$PLUGIN_ROOT\/hooks\/adapters\/codex\.py/);
+    assert.match(serializedHooks, /apply_patch/);
 
     const mcp = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, '.mcp.json'), 'utf8'));
     const server = mcp.mcpServers['ultra-builder-pro'];

package/adapters/tests/opencode.test.cjs

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { pathToFileURL } = require('node:url');
 
 const opencode = require('../opencode.js');
 const { parse: parseFm } = require('../_shared/frontmatter.cjs');
@@ -70,6 +71,9 @@ test('install performs content-level OpenCode adaptation for commands, skills, r
     assert.match(geminiCollab, /OpenCode remains primary/);
     assert.match(verify, /OpenCode remains primary/);
     assert.match(verify, /opencode-analysis\.md/);
+    assert.match(plan, /LEGACY_STATE_MIGRATION_REQUIRED/);
+    assert.match(plan, /never read or write .*tasks\.json/i);
+    assert.doesNotMatch(plan, /ultra-tools task create/);
 
     const markdown = [];
     for (const root of ['commands', 'skills', 'agents']) {
@@ -165,6 +169,8 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.match(plugin, /experimental\.chat\.system\.transform/);
     assert.match(plugin, /experimental\.session\.compacting/);
     assert.match(plugin, /tool\.execute\.before/);
+    assert.match(plugin, /\.ultra[\\/]tasks[\\/]tasks\.json/);
+    assert.match(plugin, /throw new Error/);
     assert.match(plugin, /session\.compacted/);
     assert.doesNotMatch(plugin, /memory|recall|journal|observation/);
   } finally {
@@ -172,6 +178,37 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
   }
 });
 
+test('OpenCode before-tool hook blocks tasks.json writes only during an active workflow', async () => {
+  const target = mkTarget();
+  const project = mkTarget();
+  try {
+    opencode.install({ configDir: target, repoRoot: REPO_ROOT });
+    const pluginFile = path.join(target, 'plugins', 'ultra-builder-pro.js');
+    const module = await import(pathToFileURL(pluginFile).href);
+    const plugin = await module.UltraBuilderProPlugin({ directory: project });
+
+    await plugin['tool.execute.before'](
+      { tool: 'edit' },
+      { args: { filePath: '.ultra/tasks/tasks.json' } },
+    );
+
+    fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-plan', task_id: 'plan', step: 'persist', status: 'active',
+    }));
+    await assert.rejects(
+      plugin['tool.execute.before'](
+        { tool: 'apply_patch' },
+        { args: { patch: '*** Begin Patch\n*** Update File: .ultra/tasks/tasks.json\n*** End Patch' } },
+      ),
+      /state\.db is authoritative/,
+    );
+  } finally {
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('install preserves user mcp entries; uninstall removes only owned Ultra assets', () => {
   const target = mkTarget();
   const configFile = path.join(target, 'opencode.json');

package/commands/ultra-dev.md

@@ -8,7 +8,6 @@ mcp_tools_required:
   - task.update
   - task.get
   - task.list
-cli_fallback: "task update"
 ---
 
 # /ultra-dev
@@ -18,6 +17,8 @@ cli_fallback: "task update"
 把一个 task 从 `pending` 推到 `completed`：进入 feature 分支 → RED/GREEN/REFACTOR
 TDD → 质量门 → `/ultra-review all` → 完成 → commit/merge。**单写**：状态只通过
 MCP `task.update` 改一次；projector 自动更新 tasks.json + context-md frontmatter。
+MCP 状态工具失败时 fail closed；`LEGACY_STATE_MIGRATION_REQUIRED` 只允许先跑
+v4.4→v4.5 迁移，绝不从 `tasks.json` 回退或直接改投影。
 
 ## 参数
 

package/commands/ultra-plan.md

@@ -6,7 +6,6 @@ model: opus
 workflow-ref: "@skills/ultra-plan/SKILL.md"
 mcp_tools_required:
   - task.create
-cli_fallback: "task create"
 ---
 
 # /ultra-plan
@@ -18,6 +17,11 @@ Skeleton 贯穿所有层，再切 vertical slices，每 3-4 个 feature task 插
 Integration Checkpoint。任务写入 state.db（MCP `task.create`），projector
 自动生成 `.ultra/tasks/tasks.json` + contexts/*.md frontmatter。
 
+入口先写 active `.ultra/workflow-state.json`。MCP 不可用或返回
+`LEGACY_STATE_MIGRATION_REQUIRED` 时立即停止，提示运行
+`ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>`；绝不读取或写入
+`tasks.json` 作为回退。
+
 ## 参数
 
 | 位 | 含义 | 缺省 |

package/commands/ultra-status.md

@@ -7,7 +7,6 @@ workflow-ref: "@skills/ultra-status/SKILL.md"
 mcp_tools_required:
   - task.list
   - task.get
-cli_fallback: "task list"
 ---
 
 # /ultra-status
@@ -16,6 +15,8 @@ cli_fallback: "task list"
 
 一次调用拿整个项目近况：任务进度（来自 state.db `task.list`）+ 测试状态（`test-report.json`）+
 发布状态（`delivery-report.json`）+ 风险检测 + 下一步命令路由。只读。
+任务状态只接受 MCP `task.list`/`task.get`；失败时原样报告并停止，绝不读取
+`tasks.json` 冒充权威数据。旧 v4.4 数据必须先执行正式迁移。
 
 ## 参数
 

package/commands/ultra-test.md

@@ -6,7 +6,6 @@ model: opus
 workflow-ref: "@skills/ultra-test/SKILL.md"
 mcp_tools_required:
   - task.list
-cli_fallback: "task list"
 ---
 
 # /ultra-test
@@ -16,6 +15,8 @@ cli_fallback: "task list"
 `/ultra-deliver` 前的项目级质量审计：6 类 gate（Anti-Pattern / Coverage Gap /
 Wiring / E2E / Performance / Security）× auto-fix loop。**只读** state.db，
 写 `.ultra/test-report.json` 作为 `/ultra-deliver` 的准入凭证。
+completed-task 前置检查必须来自 MCP `task.list`；失败时停止，绝不回退到
+`tasks.json`。`LEGACY_STATE_MIGRATION_REQUIRED` 必须先完成 v4.4→v4.5 迁移。
 
 **注意**：这不是跑单测（那是 `/ultra-dev`）。这是交付前的体检。
 

package/docs/COMMIT-HASH-BACKFILL.md

@@ -77,10 +77,10 @@ The post-commit hook installed by `skills/ultra-dev/` will invoke this
 flow as soon as a feat commit lands on a task branch:
 
 ```
-post-commit hook → if commit message starts with "feat:" and the
+post-commit workflow → if commit message starts with "feat:" and the
                    working tree contains contexts/task-N.md →
-                   ultra-tools task update --id task-N \
-                       --completion-commit $(git rev-parse HEAD) &&
+                   MCP task.update {id: task-N,
+                       patch: {completion_commit: $(git rev-parse HEAD)}} &&
                    git add contexts/task-N.md &&
                    git commit -m "chore: record task-N completion hash"
 ```

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -41,7 +41,7 @@ result for primary verification.
 | Lifecycle | Claude Code | OpenCode | Codex | Gemini CLI |
 |---|---|---|---|---|
 | Session context/health | FULL, native `SessionStart` | FULL, system transform + event refresh | FULL, native `SessionStart` | N/A |
-| Active edit boundary | FULL, `PreToolUse Edit|Write` | DEGRADED, tool lifecycle can refresh but not inject a native pre-edit message | FULL, `PreToolUse Edit|Write` | N/A |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | N/A |
 | Compaction recovery | FULL, `PreCompact` + compact resume matcher | FULL, native compacting context | FULL, `PreCompact` + `PostCompact` | N/A |
 | Incomplete-stop gate | FULL, native blocking `Stop` hook | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` hook | N/A |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | N/A |

package/hooks/active_task_context.py

@@ -6,6 +6,22 @@ import sys
 from pathlib import Path
 
 TERMINAL = {"committed", "completed", "done", "cancelled"}
+TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
+
+
+def targets_tasks_projection(data: dict, root: Path) -> bool:
+    tool_input = data.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return False
+    for key in ("file_path", "filePath", "filepath", "path"):
+        value = tool_input.get(key)
+        if not isinstance(value, str) or not value.strip():
+            continue
+        candidate = Path(value)
+        resolved = candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+        if resolved == (root / TASKS_PROJECTION).resolve():
+            return True
+    return False
 
 
 def main() -> None:
@@ -29,6 +45,18 @@ def main() -> None:
             break
         task = state.get("task_id", state.get("task", "unknown"))
         step = state.get("step", "unknown")
+        if targets_tasks_projection(data, root):
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": (
+                    "Refusing a direct write to .ultra/tasks/tasks.json during an active Ultra "
+                    "workflow. .ultra/state.db is authoritative; use the Ultra MCP task tools. "
+                    "If they report LEGACY_STATE_MIGRATION_REQUIRED, run the v4.4 to v4.5 "
+                    "migration before continuing."
+                ),
+            }}))
+            return
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "additionalContext": (

package/mcp-server/lib/projector.cjs

@@ -16,8 +16,8 @@ const SCHEMA_VERSION = '4.5';
 const SOURCE_TAG = '.ultra/state.db';
 
 // Frozen SELECTs — values bind through @placeholders.
-const LIST_TASKS_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks ORDER BY created_at ASC";
-const READ_TASK_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks WHERE id = @id";
+const LIST_TASKS_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks ORDER BY created_at ASC";
+const READ_TASK_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks WHERE id = @id";
 
 function rowToProjection(row) {
   if (!row) return null;
@@ -87,6 +87,11 @@ function buildContextDoc(taskRow, existingBody) {
   headerLines.push('---', '');
 
   let body = existingBody || '';
+  // v4.4 contexts carried a second generated status banner in the Markdown
+  // body. Once frontmatter is authoritative, retaining that line creates two
+  // state surfaces that can disagree. Remove only the legacy generated line;
+  // all task-authored body content remains intact.
+  body = body.replace(/^>\s*\*\*Status\*\*:.*(?:\r?\n|$)(?:\r?\n)?/mi, '');
   // Strip any previous STALE banner so re-projection after reset is clean.
   body = body.replace(/^> ⚠️\s*STALE[^\n]*\n(?:>[^\n]*\n)*\n?/m, '');
   if (taskRow.stale) {

package/mcp-server/lib/state-authority.cjs

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class StateAuthorityError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.retriable = false;
+    this.details = details;
+  }
+}
+
+function inspectProjection(rootDir) {
+  const projectionPath = path.join(rootDir, '.ultra', 'tasks', 'tasks.json');
+  if (!fs.existsSync(projectionPath)) return null;
+  let projection;
+  try {
+    projection = JSON.parse(fs.readFileSync(projectionPath, 'utf8'));
+  } catch (error) {
+    throw new StateAuthorityError(
+      'STATE_PROJECTION_INVALID',
+      `cannot validate ${projectionPath}: ${error.message}`,
+      { projection_path: projectionPath },
+    );
+  }
+  if (!projection || !Array.isArray(projection.tasks)) {
+    throw new StateAuthorityError(
+      'STATE_PROJECTION_INVALID',
+      `${projectionPath} does not contain a tasks array`,
+      { projection_path: projectionPath },
+    );
+  }
+  return {
+    path: projectionPath,
+    version: String(projection.version || projection.schema_version || 'unknown'),
+    taskCount: projection.tasks.length,
+  };
+}
+
+function assertStateAuthority(db, rootDir) {
+  const authoritativeCount = db.prepare('SELECT COUNT(*) AS count FROM tasks').get().count;
+  if (authoritativeCount > 0) return;
+  const projection = inspectProjection(rootDir);
+  if (!projection || projection.taskCount === 0) return;
+
+  const details = {
+    authoritative_task_count: authoritativeCount,
+    legacy_task_count: projection.taskCount,
+    projection_path: projection.path,
+    projection_version: projection.version,
+  };
+  if (projection.version === '4.4') {
+    throw new StateAuthorityError(
+      'LEGACY_STATE_MIGRATION_REQUIRED',
+      `state.db has no tasks but ${projection.path} contains ${projection.taskCount} v4.4 tasks; `
+        + 'run ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root> before using Ultra MCP tools',
+      details,
+    );
+  }
+  throw new StateAuthorityError(
+    'STATE_AUTHORITY_CONFLICT',
+    `state.db has no tasks but ${projection.path} contains ${projection.taskCount} tasks; refusing projection fallback`,
+    details,
+  );
+}
+
+module.exports = {
+  StateAuthorityError,
+  inspectProjection,
+  assertStateAuthority,
+};

package/mcp-server/lib/state-db.cjs

@@ -9,7 +9,7 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '8A.1';
+const EXPECTED_VERSION = '8A.2';
 
 const REQUIRED_TABLES = Object.freeze([
   'tasks',
@@ -60,6 +60,22 @@ function applySchema(db) {
   runScript(db, readSchemaSql());
 }
 
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+}
+
+function applyCompatibleUpgrades(db) {
+  const taskColumns = columnNames(db, 'tasks');
+  if (!taskColumns.has('estimated_days')) {
+    db.transaction(() => {
+      db.exec('ALTER TABLE tasks ADD COLUMN estimated_days REAL CHECK (estimated_days IS NULL OR estimated_days > 0)');
+      db.prepare(
+        'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
+      ).run(EXPECTED_VERSION, 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');
+    })();
+  }
+}
+
 function ensureSchemaVersion(db) {
   // schema_version is an audit trail — multiple rows across phase upgrades.
   // Guard by checking whether the expected version row exists rather than
@@ -82,6 +98,7 @@ function initStateDb(dbPath) {
   if (missing.length > 0) {
     applySchema(db);
   }
+  applyCompatibleUpgrades(db);
   const version = ensureSchemaVersion(db);
   return {
     db,
@@ -104,6 +121,7 @@ module.exports = {
   SCHEMA_FILE,
   openStateDb,
   applySchema,
+  applyCompatibleUpgrades,
   applyPragmas,
   ensureSchemaVersion,
   initStateDb,

package/mcp-server/lib/state-ops.cjs

@@ -23,14 +23,14 @@ const STATUS_TRANSITIONS = Object.freeze({
 });
 
 const TASK_FIELDS = Object.freeze([
-  'id', 'title', 'type', 'priority', 'complexity', 'status',
+  'id', 'title', 'type', 'priority', 'complexity', 'estimated_days', 'status',
   'deps', 'files_modified', 'session_id', 'stale', 'complexity_hint',
   'tag', 'trace_to', 'context_file', 'completion_commit', 'parent_id',
   'created_at', 'updated_at',
 ]);
 
 const PATCHABLE_FIELDS = Object.freeze([
-  'priority', 'complexity', 'deps', 'files_modified',
+  'priority', 'complexity', 'estimated_days', 'deps', 'files_modified',
   'session_id', 'stale', 'complexity_hint', 'tag', 'trace_to',
   'context_file', 'completion_commit',
 ]);
@@ -140,6 +140,7 @@ function createTask(db, input) {
     type: input.type,
     priority: input.priority,
     complexity: input.complexity ?? null,
+    estimated_days: input.estimated_days ?? null,
     status: 'pending',
     deps: input.deps ? JSON.stringify(input.deps) : null,
     files_modified: input.files_modified ? JSON.stringify(input.files_modified) : null,

package/mcp-server/server.cjs

@@ -18,6 +18,7 @@ const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontext
 const { version: PACKAGE_VERSION } = require('../package.json');
 
 const { initStateDb, closeStateDb } = require('./lib/state-db.cjs');
+const { assertStateAuthority } = require('./lib/state-authority.cjs');
 const ops = require('./lib/state-ops.cjs');
 const projector = require('./lib/projector.cjs');
 const telemetry = require('./lib/telemetry.cjs');
@@ -413,6 +414,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true }) {
     let toolDb = null;
     try {
       toolDb = STATELESS_TOOLS.has(name) ? null : getDb();
+      if (toolDb) assertStateAuthority(toolDb, rootDir);
       result = await dispatchTool(name, args, toolDb, { rootDir });
     } catch (err) {
       const code = err.code || (err instanceof ops.StateOpsError ? err.code : 'STATE_DB_ERROR');