ultra-builder-pro-cli 0.13.0 → 0.14.0

package/adapters/tests/codex.test.cjs

@@ -128,8 +128,13 @@ test('every generated skill is Codex-valid, UI-visible, and free of Claude host
       assert.doesNotMatch(text, /[\u3400-\u9fff]|ultra-review-findings-v1|Context7|Exa MCP|confidence\s*>=?\s*\d+/iu);
 
       const openai = yaml.load(fs.readFileSync(path.join(skillDir, 'agents', 'openai.yaml'), 'utf8'));
+      const openaiSource = fs.readFileSync(path.join(skillDir, 'agents', 'openai.yaml'), 'utf8');
       assert.ok(openai.interface.display_name);
       assert.ok(openai.interface.short_description);
+      assert.ok(openai.interface.short_description.length >= 25, name);
+      assert.ok(openai.interface.short_description.length <= 64, name);
+      assert.match(openaiSource, /short_description:\s+['"]/);
+      assert.match(openaiSource, /default_prompt:\s+['"]/);
       assert.match(openai.interface.default_prompt, new RegExp(`\\$ultra-builder-pro:${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
       assert.equal(openai.policy.allow_implicit_invocation, false);
       if (MCP_DEPENDENT_SKILLS.includes(name)) {
@@ -148,14 +153,15 @@ test('every generated skill is Codex-valid, UI-visible, and free of Claude host
     assert.match(cc, /claude --safe-mode/);
 
     const verify = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-verify', 'SKILL.md'), 'utf8');
-    assert.match(verify, /Codex owns the task/);
-    assert.match(verify, /claude --safe-mode/);
-    assert.match(verify, /codex-analysis\.md/);
-    assert.doesNotMatch(verify, /codex-output\.md|Claude synthesizes|Claude-only/);
+    assert.match(verify, /Keep the current host responsible/);
+    assert.match(verify, /installed collaboration companion/);
+    assert.match(verify, /host-analysis\.md/);
+    assert.doesNotMatch(verify, /codex exec|claude --safe-mode|Claude synthesizes|Claude-only/);
 
     const waiter = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-verify', 'scripts', 'verify_wait.py'), 'utf8');
-    assert.match(waiter, /ADVISOR = "claude"/);
-    assert.match(waiter, /OUTPUT_FILE = "claude-output\.md"/);
+    assert.match(waiter, /--advisor/);
+    assert.match(waiter, /advisor-output\.md/);
+    assert.doesNotMatch(waiter, /^ADVISOR\s*=|^OUTPUT_FILE\s*=/m);
 
     const review = fs.readFileSync(path.join(layout.pluginRoot, 'skills', 'ultra-review', 'SKILL.md'), 'utf8');
     assert.match(review, /native Codex custom agents/);
@@ -231,6 +237,7 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
 
     for (const rel of [
       'runtime/index.cjs',
+      'runtime/breadcrumb.cjs',
       'runtime/launch.cjs',
       'runtime/ultra-tools.cjs',
       'runtime/build/Release/better_sqlite3.node',

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

@@ -6,6 +6,10 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const { createChange } = require('../../mcp-server/lib/change-workflow.cjs');
+const { createTask } = require('../../mcp-server/lib/state-ops.cjs');
+const { compileRoleContext } = require('../../mcp-server/lib/context-spine.cjs');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const ADAPTER = path.join(REPO_ROOT, 'hooks', 'adapters', 'kimi.py');
@@ -18,6 +22,35 @@ function run(feature, payload, args = []) {
   });
 }
 
+function seedContext(project, taskId = 'task-7') {
+  const state = initStateDb(path.join(project, '.ultra', 'state.db'));
+  state.db.prepare(
+    `INSERT INTO baselines
+     (id, project_name, mode, status, approved_by, approval_note, converged_at)
+     VALUES ('baseline', 'fixture', 'greenfield', 'ready', 'test', 'fixture', ?)`,
+  ).run(new Date().toISOString());
+  const { change } = createChange(state.db, {
+    id: 'hook-change', title: 'Hook change', kind: 'quick',
+    intent: 'Inject the authoritative task.',
+    docs_impact: { status: 'none', rationale: 'fixture' },
+  }, { rootDir: project });
+  const task = createTask(state.db, {
+    id: taskId, title: 'Hook task', type: 'bugfix', priority: 'P0', change_id: change.id,
+  });
+  compileRoleContext(state.db, {
+    input: {
+      task_id: task.id, role: 'implement', gate: 'implementation',
+      execution_contract: {
+        slice_kind: 'tracer_bullet', public_seam: 'hook injection',
+        verification_command: 'node --test adapters/tests/kimi-hook.test.cjs',
+      },
+      next_action: 'Continue the authoritative hook task.',
+    },
+    change, tasks: [task], rootDir: project,
+  });
+  closeStateDb(state.db);
+}
+
 test('Kimi hook adapter rejects non-workflow policy hooks without blocking the host', () => {
   const result = run('block_dangerous_commands.py', {
     session_id: 'session-1',
@@ -33,10 +66,7 @@ test('Kimi hook adapter rejects non-workflow policy hooks without blocking the h
 test('Kimi hook adapter translates active edit context to the native message field', () => {
   const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-hook-'));
   try {
-    fs.mkdirSync(path.join(project, '.ultra'));
-    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
-      command: 'ultra-dev', task_id: 'task-7', step: '4.5', status: 'review_pending',
-    }));
+    seedContext(project);
     const result = run('active_task_context.py', {
       session_id: 'session-2',
       cwd: project,
@@ -57,9 +87,6 @@ test('Kimi hook adapter emits the native deny contract for projection writes', (
   const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-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,

package/adapters/tests/opencode.test.cjs

@@ -11,6 +11,9 @@ const { pathToFileURL } = require('node:url');
 const opencode = require('../opencode.js');
 const { parse: parseFm } = require('../_shared/frontmatter.cjs');
 const { skillsForRuntime } = require('../_shared/runtime-assets.cjs');
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const changes = require('../../mcp-server/lib/change-workflow.cjs');
+const { createTask } = require('../../mcp-server/lib/state-ops.cjs');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
@@ -69,10 +72,10 @@ test('install performs content-level OpenCode adaptation for commands, skills, r
     assert.match(review, /OpenCode `task` tool/);
     assert.match(review, /scripts\/review_wait\.py/);
     assert.match(codexCollab, /OpenCode remains primary/);
-    assert.match(verify, /OpenCode writes the first analysis/);
-    assert.match(verify, /opencode-analysis\.md/);
-    assert.match(verify, /codex exec -s read-only/);
-    assert.match(verify, /--ignore-user-config/);
+    assert.match(verify, /Keep OpenCode responsible/);
+    assert.match(verify, /host-analysis\.md/);
+    assert.match(verify, /installed collaboration companion/);
+    assert.doesNotMatch(verify, /codex exec|claude --safe-mode/);
     assert.doesNotMatch(plan, /LEGACY_STATE_MIGRATION_REQUIRED|v4\.4|v4\.5/);
     assert.match(plan, /never read or\s+write .*tasks\.json/i);
     assert.doesNotMatch(plan, /ultra-tools task create/);
@@ -176,93 +179,29 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.match(plugin, /\.ultra[\\/]tasks[\\/]tasks\.json/);
     assert.match(plugin, /throw new Error/);
     assert.match(plugin, /session\.compacted/);
+    assert.match(plugin, /breadcrumb\.cjs/);
+    assert.doesNotMatch(plugin, /workflow-state\.json|context-manifest\.json/);
     assert.doesNotMatch(plugin, /memory\.(?:retain|recall|reflect)|journal|observation|prompt[_ -]?capture/);
-    assert.match(plugin, /Ultra context spine/);
+    assert.match(plugin, /canonical breadcrumb/);
     assert.doesNotMatch(plugin, /providerMetadata|External providers/);
   } finally {
     fs.rmSync(target, { recursive: true, force: true });
   }
 });
 
-test('OpenCode context covers active changes and projection writes are blocked for Ultra projects', async () => {
+test('OpenCode routes a missing authority to init and always protects task projections', 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 });
-
     fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
-    fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
-    execFileSync('git', ['init'], { cwd: project, stdio: 'ignore' });
-    fs.writeFileSync(path.join(project, 'app.txt'), 'initial\n');
-    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
-    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'initial'], {
-      cwd: project, stdio: 'ignore',
-    });
-    const compiledHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: project, encoding: 'utf8' }).trim();
-    const changeRoot = path.join(project, '.ultra', 'changes', 'active', 'daily-fix');
-    fs.mkdirSync(changeRoot, { recursive: true });
-    fs.writeFileSync(path.join(changeRoot, 'context-manifest.json'), JSON.stringify({
-      schema_version: '2.0',
-      baseline: { id: 'project-baseline', mode: 'brownfield', status: 'ready', repository_revision: compiledHead },
-      change: { id: 'daily-fix', title: 'Daily fix', kind: 'quick', status: 'active', intent: 'Fix drift' },
-      role: 'implement',
-      gate: 'implementation',
-      next_action: 'Run the exact regression test.',
-      readiness: {
-        status: 'ready', blockers: [], warnings: ['CONTEXT_FILE_BUDGET_EXCEEDED'],
-      },
-      git: { head: compiledHead },
-      selected_task: { id: 'daily-task', status: 'in_progress' },
-      context: { token_estimate: 1200, budget: { max_tokens: 8000, max_files: 8 } },
-      providers: { memory: { provider: 'cloud-mem', status: 'available' } },
-    }));
-
+    const module = await import(`${pathToFileURL(path.join(target, 'plugins', 'ultra-builder-pro.js')).href}?baseline`);
+    const plugin = await module.UltraBuilderProPlugin({ directory: project });
     const output = { system: [] };
     await plugin['experimental.chat.system.transform']({}, output);
-    assert.match(output.system.join('\n'), /Ultra context spine/);
-    assert.match(output.system.join('\n'), /daily-fix/);
-    assert.match(output.system.join('\n'), /daily-task/);
-    assert.match(output.system.join('\n'), /Role: implement/);
-    assert.match(output.system.join('\n'), /Gate: implementation/);
-    assert.match(output.system.join('\n'), /Readiness: ready/);
-    assert.match(output.system.join('\n'), /Warnings: CONTEXT_FILE_BUDGET_EXCEEDED/);
-    assert.match(output.system.join('\n'), /Run the exact regression test/);
-    assert.doesNotMatch(output.system.join('\n'), /Fix drift|cloud-mem/);
-
-    const manifestFile = path.join(changeRoot, 'context-manifest.json');
-    const legacyManifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
-    legacyManifest.schema_version = '1.0';
-    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
-    const legacyOutput = { system: [] };
-    await plugin['experimental.chat.system.transform']({}, legacyOutput);
-    assert.match(legacyOutput.system.join('\n'), /CONTEXT_SNAPSHOT_UPGRADE_REQUIRED/);
-    legacyManifest.schema_version = '2.0';
-    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
-
-    delete legacyManifest.baseline;
-    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
-    const missingBaselineOutput = { system: [] };
-    await plugin['experimental.chat.system.transform']({}, missingBaselineOutput);
-    assert.match(missingBaselineOutput.system.join('\n'), /CONTEXT_SNAPSHOT_UPGRADE_REQUIRED/);
-    legacyManifest.baseline = {
-      id: 'project-baseline', mode: 'brownfield', status: 'ready', repository_revision: compiledHead,
-    };
-    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
-
-    fs.writeFileSync(path.join(project, 'app.txt'), 'changed\n');
-    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
-    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'change'], {
-      cwd: project, stdio: 'ignore',
-    });
-    const staleOutput = { system: [] };
-    await plugin['experimental.chat.system.transform']({}, staleOutput);
-    assert.match(staleOutput.system.join('\n'), /Readiness: blocked/);
-    assert.match(staleOutput.system.join('\n'), /CONTEXT_HEAD_STALE/);
-    assert.match(staleOutput.system.join('\n'), /recompile change\.context/);
-
+    const text = output.system.join('\n');
+    assert.match(text, /STATE_DB_MISSING/);
+    assert.match(text, /ultra-init/);
     await assert.rejects(
       plugin['tool.execute.before'](
         { tool: 'apply_patch' },
@@ -276,22 +215,69 @@ test('OpenCode context covers active changes and projection writes are blocked f
   }
 });
 
-test('OpenCode does not assume a project baseline is ready when no active change manifest exists', async () => {
+test('OpenCode injects the DB breadcrumb and ignores conflicting workflow projections', async () => {
   const target = mkTarget();
   const project = mkTarget();
+  let state;
   try {
     opencode.install({ configDir: target, repoRoot: REPO_ROOT });
-    fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
-    fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
-    const module = await import(`${pathToFileURL(path.join(target, 'plugins', 'ultra-builder-pro.js')).href}?baseline`);
+    execFileSync('git', ['init'], { cwd: project, stdio: 'ignore' });
+    fs.writeFileSync(path.join(project, 'app.txt'), 'initial\n');
+    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
+    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'initial'], {
+      cwd: project, stdio: 'ignore',
+    });
+    state = initStateDb(path.join(project, '.ultra', 'state.db'));
+    state.db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('baseline-db', 'fixture', 'greenfield', 'ready', 'test', 'fixture', ?)`,
+    ).run(new Date().toISOString());
+    const { change } = changes.createChange(state.db, {
+      id: 'db-authority-change', title: 'DB authority', kind: 'quick',
+      intent: 'Use one authoritative injected state.',
+      docs_impact: { status: 'none', rationale: 'test fixture' },
+    }, { rootDir: project });
+    const task = createTask(state.db, {
+      id: 'db-authority-task', title: 'Use DB authority', type: 'bugfix', priority: 'P0',
+      change_id: change.id,
+    });
+    changes.compileContext(state.db, {
+        id: change.id,
+        task_id: task.id,
+        role: 'implement',
+        gate: 'implementation',
+        execution_contract: {
+          slice_kind: 'tracer_bullet', public_seam: 'OpenCode injection',
+          verification_command: 'node --test adapters/tests/opencode.test.cjs',
+        },
+        next_action: 'Verify the DB-only OpenCode injection.',
+    }, { rootDir: project });
+
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-dev', task_id: 'projection-task', status: 'active', step: 'wrong',
+    }));
+    const projectionRoot = path.join(project, '.ultra', 'changes', 'active', 'projection-change');
+    fs.mkdirSync(projectionRoot, { recursive: true });
+    fs.writeFileSync(path.join(projectionRoot, 'context-manifest.json'), JSON.stringify({
+      schema_version: '2.0',
+      baseline: { id: 'projection-baseline', mode: 'brownfield', status: 'ready' },
+      change: { id: 'projection-change', kind: 'quick', status: 'active' },
+      selected_task: { id: 'projection-task', status: 'in_progress' },
+      readiness: { status: 'ready', blockers: [], warnings: [] },
+    }));
+
+    const module = await import(`${pathToFileURL(path.join(target, 'plugins', 'ultra-builder-pro.js')).href}?db-authority`);
     const plugin = await module.UltraBuilderProPlugin({ directory: project });
     const output = { system: [] };
     await plugin['experimental.chat.system.transform']({}, output);
     const text = output.system.join('\n');
-    assert.match(text, /ultra-status/);
-    assert.match(text, /ultra-init/);
-    assert.doesNotMatch(text, /Start daily work with the ultra-change workflow/);
+    assert.match(text, /Change: db-authority-change/);
+    assert.match(text, /Task: db-authority-task/);
+    assert.match(text, /Role: implement/);
+    assert.doesNotMatch(text, /projection-change|projection-task|projection-baseline/);
   } finally {
+    if (state) closeStateDb(state.db);
     fs.rmSync(target, { recursive: true, force: true });
     fs.rmSync(project, { recursive: true, force: true });
   }

package/docs/AGENT-CONTEXT.md

@@ -113,8 +113,10 @@ the shared read-only `context_spine.py` breadcrumb helper:
 - `pre_stop_check.py` reports unfinished workflow position at stop without denial;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-`workflow_context.py`, `active_task_context.py`, and `workflow_resume.py` read the
-same DB-derived breadcrumb through `context_spine.py`. `health_check.py` and
+`workflow_context.py`, `active_task_context.py`, `workflow_resume.py`, and the
+OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
+through the thin `context_spine.py` bridge. No hook reimplements the state query.
+`health_check.py` and
 `workflow_context.py` may inspect any initialized project;
 `active_task_context.py` always protects the task projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
@@ -149,7 +151,8 @@ Archive before prune; the confirmation token is intentionally required.
 ```text
 .ultra/
 ├── state.db                 # authoritative SQLite store
-├── workflow-state.json      # active workflow/recovery checkpoint
+├── runtime/
+│   └── checkpoint.json      # advisory breadcrumb recovery projection
 ├── changes/
 │   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation

package/docs/ARCHITECTURE.md

@@ -190,10 +190,17 @@ checking, review, convergence, and recovery. Each snapshot records:
 - one deterministic next action.
 
 `change.breadcrumb` derives the compact current position from state.db. Session,
-edit, and resume hooks inject only this breadcrumb, never the intent body,
+edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
+and inject only this breadcrumb, never the intent body,
 provider content, or a conversation summary. A changed git HEAD marks the
 snapshot stale and routes back to `change.context`.
 
+PRD decomposition and complex-task subdivision use the active host model. The
+MCP accepts the resulting structured tasks, validates schema, topology,
+baseline/change ownership, and transaction boundaries, then persists them. It
+does not call Anthropic, OpenAI, or another model provider and needs no separate
+model API credential.
+
 File count, token estimate, and context-share overflow produce warnings, never a
 refusal. The agent may narrow reads, load files lazily, or split a slice when that
 preserves correctness; it must not raise a threshold merely to clear a gate or

package/docs/ROADMAP.md

@@ -101,5 +101,5 @@ npm audit
 ## Out of scope for v1.0 (deferred)
 
 PLAN §13 lists Copilot / Cursor / Windsurf / 7 more runtimes, web
-dashboard / TUI, LLM provider abstraction, team-collab server, plugin
+dashboard / TUI, team-collab server, plugin
 marketplace.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -46,7 +46,7 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | DEGRADED, projected v2 breadcrumb; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
+| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | FULL, the native JS plugin invokes the same bundled DB breadcrumb reader; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
 | Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
@@ -73,7 +73,7 @@ they do not deny edits or stop active incident work.
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
 | Live/declared contracts | 36 | 36 | 36 | 36 |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
-| Context Spine v2 / breadcrumb | FULL | FULL, DB-generated projection consumed by native JS | FULL | FULL |
+| Context Spine v2 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
 | Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
@@ -126,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `11.0` |
+| Current state schema | `12.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, then adds authoritative baseline adoption state transactionally in 11.0 |
+| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, then runtime constraint compatibility in 12.0 |
 | Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
 | Failure behavior | rollback; no partially upgraded authority database |
 

package/hooks/active_task_context.py

@@ -2,13 +2,11 @@
 """Protect Ultra projections and restate an active task boundary before edits."""
 
 import json
-import sqlite3
 import sys
 from pathlib import Path
 
-from context_spine import read_breadcrumb, render_breadcrumb
+from context_spine import ContextSpineError, find_root, read_breadcrumb, render_breadcrumb
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
 TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
 
 
@@ -34,58 +32,32 @@ def main() -> None:
     except json.JSONDecodeError as exc:
         print(f"[active_task_context] invalid hook input: {exc}", file=sys.stderr)
         data = {}
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    for root in (start, *start.parents):
-        ultra = root / ".ultra"
-        state_file = ultra / "workflow-state.json"
-        initialized = (
-            (ultra / "state.db").is_file()
-            or state_file.is_file()
-            or (ultra / "changes" / "active").is_dir()
-        )
-        if not initialized:
-            continue
-        if targets_tasks_projection(data, root):
-            print(json.dumps({"hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": (
-                    "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
-                    ".ultra/state.db is authoritative; use the Ultra MCP task tools and "
-                    "run ultra-doctor when state or projection health is degraded."
-                ),
-            }}))
-            return
-        try:
-            breadcrumb = read_breadcrumb(root)
-        except (sqlite3.Error, OSError) as exc:
-            print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
-            breadcrumb = None
-        if breadcrumb and breadcrumb.get("task_id"):
-            print(json.dumps({"hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "additionalContext": render_breadcrumb(root, breadcrumb),
-            }}))
-            return
-        if not state_file.is_file():
-            break
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[active_task_context] cannot read {state_file}: {exc}", file=sys.stderr)
-            break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
-            break
-        task = state.get("task_id", state.get("task", "unknown"))
-        step = state.get("step", "unknown")
+    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    if root is None:
+        print(json.dumps({}))
+        return
+    if targets_tasks_projection(data, root):
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
-            "additionalContext": (
-                f"Active Ultra task {task}, step {step}. Keep this edit inside the approved "
-                "task and preserve .ultra/state.db as workflow authority."
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
+                ".ultra/state.db is authoritative; use the Ultra MCP task tools and "
+                "run ultra-doctor when state or projection health is degraded."
             ),
         }}))
         return
+    try:
+        breadcrumb = read_breadcrumb(root)
+    except ContextSpineError as exc:
+        print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        breadcrumb = None
+    if breadcrumb and breadcrumb.get("change_id"):
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": render_breadcrumb(root, breadcrumb),
+        }}))
+        return
     print(json.dumps({}))