ultra-builder-pro-cli 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] — 2026-07-16
+
+### Fixed
+
+- Preserved Codex hook entry points for already-running tasks across plugin
+  refreshes, including cache versions whose adapter file or entire cache
+  directory had already disappeared. Historical cache versions are now kept in
+  the managed runtime manifest and restored as validated forwarders to the
+  current adapter.
+
+## [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 +221,9 @@ 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.2...HEAD
+[0.5.2]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.5.1...v0.5.2
+[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.2-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/codex.js

@@ -191,14 +191,53 @@ function pluginCacheRoot(configDir, marketplaceName) {
   return path.join(configDir, 'plugins', 'cache', marketplaceName, PLUGIN_NAME);
 }
 
-function listCachedHookAdapters(configDir, marketplaceName) {
+function normalizeHookCacheVersions(versions) {
+  const normalized = new Set();
+  for (const version of versions) {
+    if (typeof version !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9.+_-]*$/.test(version)) {
+      throw new Error(`invalid Codex plugin cache version: ${String(version)}`);
+    }
+    normalized.add(version);
+  }
+  return [...normalized].sort();
+}
+
+function listKnownHookCacheVersions(configDir, marketplaceName, manifest = null) {
+  const root = pluginCacheRoot(configDir, marketplaceName);
+  const versions = [];
+  if (fs.existsSync(root)) {
+    versions.push(...fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+      .map((entry) => entry.name));
+  }
+
+  if (manifest && manifest.source === SOURCE_TAG && manifest.adapter === 'codex') {
+    if (manifest.plugin && manifest.plugin.version !== undefined) {
+      versions.push(manifest.plugin.version);
+    }
+    if (manifest.hook_cache_versions !== undefined) {
+      if (!Array.isArray(manifest.hook_cache_versions)) {
+        throw new Error('invalid Codex runtime manifest hook_cache_versions');
+      }
+      versions.push(...manifest.hook_cache_versions);
+    }
+  }
+  return normalizeHookCacheVersions(versions);
+}
+
+function hookAdaptersForVersions(configDir, marketplaceName, versions) {
   const root = pluginCacheRoot(configDir, marketplaceName);
-  if (!fs.existsSync(root)) return [];
-  return fs.readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => path.join(root, entry.name, HOOK_ADAPTER_RELATIVE))
-    .filter((file) => fs.existsSync(file))
-    .sort();
+  return normalizeHookCacheVersions(versions)
+    .map((version) => path.join(root, version, HOOK_ADAPTER_RELATIVE));
+}
+
+function listCachedHookAdapters(configDir, marketplaceName, manifest = null) {
+  return hookAdaptersForVersions(
+    configDir,
+    marketplaceName,
+    listKnownHookCacheVersions(configDir, marketplaceName, manifest),
+  );
 }
 
 function hookForwarder(target) {
@@ -211,6 +250,20 @@ runpy.run_path(${JSON.stringify(path.resolve(target))}, run_name="__main__")
 `;
 }
 
+function prepareHookAdapterPath(file) {
+  const versionRoot = path.dirname(path.dirname(path.dirname(file)));
+  try {
+    const stat = fs.lstatSync(versionRoot);
+    if (stat.isSymbolicLink()) {
+      fs.unlinkSync(versionRoot);
+    } else if (!stat.isDirectory()) {
+      throw new Error(`Codex plugin cache version is not a directory: ${versionRoot}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
 function restoreCachedHookAdapters(previousAdapters, target) {
   const resolvedTarget = path.resolve(target);
   if (!fs.existsSync(resolvedTarget)) {
@@ -219,6 +272,7 @@ function restoreCachedHookAdapters(previousAdapters, target) {
   const restored = [];
   for (const previous of previousAdapters) {
     if (path.resolve(previous) === resolvedTarget || fs.existsSync(previous)) continue;
+    prepareHookAdapterPath(previous);
     writeAtomic(previous, hookForwarder(resolvedTarget));
     restored.push(previous);
   }
@@ -239,6 +293,7 @@ function writeRuntimeManifest(configDir, data) {
     plugin: data.plugin,
     marketplace: data.marketplace,
     agents: data.agents,
+    hook_cache_versions: data.hookCacheVersions,
   }, null, 2) + '\n');
   return file;
 }
@@ -250,20 +305,25 @@ function install(ctx = {}) {
   const marketplaceFile = resolveMarketplaceFile(ctx);
   ensureDir(configDir);
 
+  const previousManifest = readRuntimeManifest(configDir);
   const legacy = cleanupLegacyConfig(configDir);
   const plugin = buildPlugin({ repoRoot, pluginRoot });
   const agents = installAgents({ repoRoot, configDir });
   const marketplace = upsertMarketplace(marketplaceFile);
-  const manifestFile = writeRuntimeManifest(configDir, {
-    plugin: { root: plugin.root, version: plugin.version },
-    marketplace: { file: marketplace.file, name: marketplace.name },
-    agents: agents.installed,
-  });
+  const previousVersions = listKnownHookCacheVersions(
+    configDir,
+    marketplace.name,
+    previousManifest,
+  );
 
   let registration = null;
   let hookCompatibility = null;
   if (shouldRunPluginCli(ctx)) {
-    const previousAdapters = listCachedHookAdapters(configDir, marketplace.name);
+    const previousAdapters = hookAdaptersForVersions(
+      configDir,
+      marketplace.name,
+      previousVersions,
+    );
     try {
       registration = runPluginCli('add', marketplace.name, ctx);
     } catch (registrationError) {
@@ -285,6 +345,16 @@ function install(ctx = {}) {
       currentHookAdapter(configDir, marketplace.name, plugin),
     );
   }
+  const hookCacheVersions = normalizeHookCacheVersions([
+    ...previousVersions,
+    plugin.version,
+  ]);
+  const manifestFile = writeRuntimeManifest(configDir, {
+    plugin: { root: plugin.root, version: plugin.version },
+    marketplace: { file: marketplace.file, name: marketplace.name },
+    agents: agents.installed,
+    hookCacheVersions,
+  });
 
   return {
     target: configDir,
@@ -379,7 +449,9 @@ module.exports = {
     removeMarketplaceEntry,
     runPluginCli,
     pluginCacheRoot,
+    listKnownHookCacheVersions,
     listCachedHookAdapters,
+    prepareHookAdapterPath,
     restoreCachedHookAdapters,
   },
 };

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,
+};