ultra-builder-pro-cli 0.5.0 → 0.5.1

package/mcp-server/tests/migrate.test.cjs

@@ -73,6 +73,17 @@ test('migrate forward inserts tasks + events, records migration_history, creates
     const taskIds = db.prepare('SELECT id FROM tasks ORDER BY id').all().map((r) => r.id);
     assert.deepEqual(taskIds, ['task-1', 'task-2', 'task-3']);
 
+    const migrated = db.prepare(
+      'SELECT id, deps, estimated_days, context_file, created_at, updated_at FROM tasks ORDER BY id',
+    ).all();
+    assert.deepEqual(JSON.parse(migrated[1].deps), ['task-1']);
+    assert.equal(migrated[1].estimated_days, 1.5);
+    assert.equal(migrated[1].context_file, '.ultra/tasks/contexts/task-2.md');
+    for (const task of migrated) {
+      assert.match(task.created_at, /^2026-04-15T00:00:00\.000Z$/);
+      assert.match(task.updated_at, /^2026-04-16T00:00:00\.000Z$/);
+    }
+
     // Status comes from tasks.json (task-3 = pending), not the context md (blocked)
     const t3 = db.prepare("SELECT status FROM tasks WHERE id = 'task-3'").get();
     assert.equal(t3.status, 'pending');
@@ -85,6 +96,27 @@ test('migrate forward inserts tasks + events, records migration_history, creates
     assert.equal(mig[0].direction, 'forward');
     assert.equal(mig[0].status, 'success');
     closeStateDb(db);
+
+    const projected = JSON.parse(fs.readFileSync(
+      path.join(dir, '.ultra', 'tasks', 'tasks.json'),
+      'utf8',
+    ));
+    assert.equal(projected.schema_version, '4.5');
+    assert.equal(projected.source, '.ultra/state.db');
+    assert.equal(projected.tasks.length, 3);
+    assert.equal(projected.tasks[1].estimated_days, 1.5);
+    assert.deepEqual(projected.tasks[1].deps, ['task-1']);
+    assert.match(
+      fs.readFileSync(path.join(dir, '.ultra', 'tasks', 'contexts', 'task-2.md'), 'utf8'),
+      /Wire JWT validation into the request pipeline/,
+    );
+    const contextTemplate = fs.readFileSync(
+      path.join(dir, '.ultra', 'tasks', 'contexts', 'TEMPLATE.md'),
+      'utf8',
+    );
+    assert.doesNotMatch(contextTemplate, /> \*\*Status\*\*:/);
+    assert.doesNotMatch(contextTemplate, /mid_workflow_recall|session_context/);
+    assert.match(contextTemplate, /Preserve this acceptance item/);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
@@ -112,7 +144,7 @@ test('migrate --rollback restores .ultra contents and writes a rollback row', ()
 
     // .ultra/tasks/tasks.json restored to original v4.4 content
     const tasksJson = JSON.parse(fs.readFileSync(path.join(dir, '.ultra', 'tasks', 'tasks.json'), 'utf8'));
-    assert.equal(tasksJson.schema_version, '4.4');
+    assert.equal(tasksJson.version, '4.4');
     assert.equal(tasksJson.tasks.length, 3);
     closeStateDb(undefined);
   } finally {
@@ -120,6 +152,29 @@ test('migrate --rollback restores .ultra contents and writes a rollback row', ()
   }
 });
 
+test('migrate refuses to merge a v4.4 projection into a non-empty state.db', () => {
+  const dir = tmpProject();
+  try {
+    const dbPath = path.join(dir, '.ultra', 'state.db');
+    const init = require('../lib/state-db.cjs').initStateDb(dbPath);
+    require('../lib/state-ops.cjs').createTask(init.db, {
+      id: 'existing', title: 'existing task', type: 'feature', priority: 'P1',
+    });
+    closeStateDb(init.db);
+
+    const r = runCli(['migrate', '--from=4.4', '--to=4.5', '--source-dir', dir]);
+    assert.equal(r.code, 2);
+    assert.equal(r.envelope.error.code, 'MIGRATE_FAILED');
+    assert.match(r.envelope.error.message, /non-empty state\.db/);
+
+    const db = openStateDb(dbPath);
+    assert.deepEqual(db.prepare('SELECT id FROM tasks ORDER BY id').all(), [{ id: 'existing' }]);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('migrate rejects unsupported --from / --to versions', () => {
   const r1 = runCli(['migrate', '--from=3.0', '--to=4.5', '--dry', '--source-dir', FIXTURE]);
   assert.equal(r1.code, 1);

package/mcp-server/tests/projector.test.cjs

@@ -34,7 +34,7 @@ function readJson(p) {
 test('projectTasks emits a v4.5-conformant tasks.json', () => {
   const { dir, db } = tmpProject();
   try {
-    ops.createTask(db, { id: 'p-1', title: 'first', type: 'feature', priority: 'P1', tag: 'main' });
+    ops.createTask(db, { id: 'p-1', title: 'first', type: 'feature', priority: 'P1', tag: 'main', estimated_days: 2.5 });
     ops.createTask(db, { id: 'p-2', title: 'second', type: 'bugfix', priority: 'P2' });
     ops.updateTaskStatus(db, 'p-1', 'in_progress');
 
@@ -49,6 +49,7 @@ test('projectTasks emits a v4.5-conformant tasks.json', () => {
 
     const p1 = projection.tasks.find((t) => t.id === 'p-1');
     assert.equal(p1.status, 'in_progress');
+    assert.equal(p1.estimated_days, 2.5);
     closeStateDb(db);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -78,6 +79,37 @@ test('projectContext rebuilds header but preserves the body', () => {
   }
 });
 
+test('projectContext removes the legacy body status banner while preserving task content', () => {
+  const { dir, db } = tmpProject();
+  try {
+    ops.createTask(db, {
+      id: 'legacy-body', title: 'legacy context body', type: 'feature', priority: 'P1',
+      context_file: '.ultra/tasks/contexts/task-legacy-body.md',
+    });
+    const ctxFile = path.join(dir, '.ultra', 'tasks', 'contexts', 'task-legacy-body.md');
+    fs.mkdirSync(path.dirname(ctxFile), { recursive: true });
+    fs.writeFileSync(ctxFile, [
+      '# Task legacy-body',
+      '',
+      '> **Status**: pending | **Priority**: P1 | **Complexity**: 4',
+      '',
+      '## Context',
+      'Keep this body.',
+      '',
+    ].join('\n'));
+
+    projector.projectContext(db, 'legacy-body', {}, { rootDir: dir });
+    const text = fs.readFileSync(ctxFile, 'utf8');
+    assert.match(text, /status: pending/);
+    assert.doesNotMatch(text, /> \*\*Status\*\*:/);
+    assert.match(text, /# Task legacy-body/);
+    assert.match(text, /Keep this body\./);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('manual edits to tasks.json are overwritten on the next projectAll', () => {
   const { dir, db } = tmpProject();
   try {

package/mcp-server/tests/server-contract.test.cjs

@@ -131,7 +131,7 @@ test('task.create + task.get round trip via MCP', async () => {
     await withClient(proj, async (client) => {
       const created = await client.callTool({
         name: 'task.create',
-        arguments: { id: 'mcp-1', title: 'first', type: 'feature', priority: 'P1' },
+        arguments: { id: 'mcp-1', title: 'first', type: 'feature', priority: 'P1', estimated_days: 2.5 },
       });
       const createdData = readToolPayload(created);
       assert.equal(createdData.id, 'mcp-1');
@@ -141,6 +141,39 @@ test('task.create + task.get round trip via MCP', async () => {
       const gotData = readToolPayload(got);
       assert.equal(gotData.task.id, 'mcp-1');
       assert.equal(gotData.task.title, 'first');
+      assert.equal(gotData.task.estimated_days, 2.5);
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
+test('state-backed MCP tools fail closed when a non-empty v4.4 tasks.json meets an empty state.db', async () => {
+  const proj = tmpProject();
+  try {
+    const tasksDir = path.join(proj.dir, '.ultra', 'tasks');
+    fs.mkdirSync(tasksDir, { recursive: true });
+    fs.writeFileSync(path.join(tasksDir, 'tasks.json'), JSON.stringify({
+      version: '4.4',
+      tasks: [{
+        id: 'legacy-1', title: 'legacy task', type: 'feature', priority: 'P1',
+        status: 'pending', dependencies: [], estimated_days: 1,
+        context_file: 'contexts/task-legacy-1.md',
+      }],
+    }));
+
+    await withClient(proj, async (client) => {
+      const listed = await client.callTool({ name: 'task.list', arguments: {} });
+      const error = expectError(listed);
+      assert.equal(error.code, 'LEGACY_STATE_MIGRATION_REQUIRED');
+      assert.match(error.message, /ultra-tools migrate --from=4\.4 --to=4\.5/);
+      assert.equal(error.details.legacy_task_count, 1);
+
+      const created = await client.callTool({
+        name: 'task.create',
+        arguments: { title: 'must not overwrite legacy', type: 'feature', priority: 'P1' },
+      });
+      assert.equal(expectError(created).code, 'LEGACY_STATE_MIGRATION_REQUIRED');
     });
   } finally {
     fs.rmSync(proj.dir, { recursive: true, force: true });

package/mcp-server/tests/state-db.test.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const stateDb = require('../lib/state-db.cjs');
+
+test('initStateDb upgrades a v8A.1 database in place with estimated_days', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-db-upgrade-'));
+  const file = path.join(dir, 'state.db');
+  try {
+    const db = stateDb.openStateDb(file);
+    const oldSql = fs.readFileSync(stateDb.SCHEMA_FILE, 'utf8')
+      .replace(/^\s*estimated_days.*\n/m, '')
+      .replace(/^INSERT OR IGNORE INTO schema_version \(version, description\)\nVALUES \('8A\.2'.*\n/m, '');
+    db.exec(oldSql);
+    stateDb.closeStateDb(db);
+
+    const upgraded = stateDb.initStateDb(file);
+    const columns = upgraded.db.prepare('PRAGMA table_info(tasks)').all().map((row) => row.name);
+    assert.ok(columns.includes('estimated_days'));
+    assert.equal(upgraded.schema_version, '8A.2');
+    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '8A.2'").get());
+    stateDb.closeStateDb(upgraded.db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/mcp-server/tests/state-ops.test.cjs

@@ -20,14 +20,15 @@ function freshDb() {
   return { ...t, db: init.db };
 }
 
-test('createTask inserts a row, defaults status=pending, emits task_created', () => {
+test('createTask inserts a row, preserves estimated_days, defaults status=pending, emits task_created', () => {
   const { dir, db } = freshDb();
   try {
     const out = ops.createTask(db, {
-      id: 'task-001', title: 'first task', type: 'feature', priority: 'P1',
+      id: 'task-001', title: 'first task', type: 'feature', priority: 'P1', estimated_days: 2.5,
     });
     assert.equal(out.id, 'task-001');
     assert.equal(out.status, 'pending');
+    assert.equal(out.estimated_days, 2.5);
     const events = db.prepare('SELECT type, task_id FROM events').all();
     assert.equal(events.length, 1);
     assert.equal(events[0].type, 'task_created');
@@ -38,6 +39,18 @@ test('createTask inserts a row, defaults status=pending, emits task_created', ()
   }
 });
 
+test('patchTask updates estimated_days', () => {
+  const { dir, db } = freshDb();
+  try {
+    ops.createTask(db, { id: 'estimate', title: 'estimate task', type: 'feature', priority: 'P2' });
+    const out = ops.patchTask(db, 'estimate', { estimated_days: 1.5 });
+    assert.equal(out.estimated_days, 1.5);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('createTask rejects duplicates with DUPLICATE_TASK_ID', () => {
   const { dir, db } = freshDb();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Gemini CLI.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-dev/SKILL.md

@@ -6,7 +6,6 @@ mcp_tools_required:
   - task.update
   - task.get
   - task.list
-cli_fallback: "task update"
 ---
 
 # ultra-dev — Phase 3.4
@@ -17,6 +16,19 @@ MCP `task.update`; the projector regenerates `tasks.json` and context-md
 frontmatter. The skill only writes context-md **bodies** (Change Log,
 Completion, Dual-Write notes).
 
+## Authority failure boundary
+
+All task selection and transitions require the live MCP state tools. If they
+are unavailable or return an authority error, stop. For
+`LEGACY_STATE_MIGRATION_REQUIRED`, instruct:
+
+```bash
+ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>
+```
+
+Never fall back to `.ultra/tasks/tasks.json`, direct SQLite writes, or a task
+CLI. The JSON file is only a projector-owned view.
+
 ## Design decisions vs pre-Phase-3
 
 - **Single-write status**: Step 1.5 / Step 5 stop touching `contexts/task-{id}.md`
@@ -30,9 +42,7 @@ Completion, Dual-Write notes).
 
 ## Prerequisites
 
-- `.ultra/tasks/tasks.json` exists (from `/ultra-plan`)
-- At least one task with `status=pending`
-- `state.db` initialized (first `task.*` call will init if missing)
+- `task.list` succeeds against state.db and returns at least one `pending` task
 
 ## Arguments
 
@@ -82,8 +92,6 @@ Acceptance sections. Use the Acceptance list as the initial todo set.
 { "id": "<id>", "patch": { "status": "in_progress" } }
 ```
 
-**CLI fallback**: `ultra-tools task update <id> --status in_progress`.
-
 Projector runs after the write → `tasks.json` + `contexts/task-{id}.md`
 frontmatter re-generated with `status: in_progress`. **Do not hand-edit either.**
 
@@ -191,14 +199,11 @@ Checkpoint `step="4.5", status="review_done", review_session=<id>, review_iterat
 {
   "id": "<id>",
   "patch": {
-    "status": "completed",
-    "completion_commit": "_pending_"  // overwritten in Step 6 after commit
+    "status": "completed"
   }
 }
 ```
 
-**CLI fallback**: `ultra-tools task update <id> --status completed`.
-
 Projector regenerates frontmatter. **Then** write the context-md **body**
 Completion section (skill responsibility, not projector):
 
@@ -297,15 +302,15 @@ Log in context-md body Change Log:
 history. Specs may grow (EXPANSION) or be corrected (CORRECTION). Specs must
 never silently shrink (REDUCTION without gate).
 
-## MCP → CLI fallback matrix
+## MCP failure matrix
 
-| Purpose | MCP tool (phase) | CLI / runtime fallback |
-|---------|------------------|------------------------|
-| Select pending task | `task.list` (2) / `task.get` (2) | `ultra-tools task list --status pending` |
-| Status → in_progress | `task.update` (2) | `ultra-tools task update <id> --status in_progress` |
+| Purpose | MCP tool (phase) | Failure behavior |
+|---------|------------------|------------------|
+| Select pending task | `task.list` (2) / `task.get` (2) | stop and surface the MCP error |
+| Status → in_progress | `task.update` (2) | stop; do not edit a projection |
 | Pre-review checkpoint | none | write `.ultra/workflow-state.json`; lifecycle hooks restore it |
 | Run review | none | `/ultra-review all` + Host-native review agents |
-| Status → completed | `task.update` (2) | `ultra-tools task update <id> --status completed` |
+| Status → completed | `task.update` (2) | stop; do not claim completion |
 | Ask user | none | current Host's native user-interaction surface |
 
 ## What this skill DOES NOT do
@@ -319,6 +324,6 @@ never silently shrink (REDUCTION without gate).
 
 | | |
 |---|---|
-| **Input** | `.ultra/tasks/tasks.json`, `.ultra/tasks/contexts/task-<id>.md` body, state.db |
+| **Input** | state.db via MCP, plus the `context_file` body returned for the selected task |
 | **Writes** | state.db (via `task.update`), context-md body (Completion + Change Log), workflow-state.json checkpoints |
 | **Next** | `/ultra-dev <next-id>` or `/ultra-test` when all Walking Skeleton + critical-path tasks complete |

package/skills/ultra-plan/SKILL.md

@@ -8,7 +8,6 @@ mcp_tools_required:
   - task.dependency_topo
   - plan.export
   - plan.get
-cli_fallback: "task create"
 ---
 
 # ultra-plan — Phase 3.3
@@ -18,6 +17,20 @@ the authority** (D32): every new task is created via MCP `task.create`; the
 projector regenerates `.ultra/tasks/tasks.json` and context-md frontmatter
 automatically. Context-md bodies are written by this skill (not projector).
 
+## Authority failure boundary
+
+Before planning, call a state-backed MCP tool. If the MCP server is missing,
+unreachable, or returns any authority error, stop before creating tasks. In
+particular, `LEGACY_STATE_MIGRATION_REQUIRED` means the project still has a
+non-empty v4.4 projection; tell the user to run:
+
+```bash
+ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>
+```
+
+Never read or write `.ultra/tasks/tasks.json` as a fallback. It is a generated
+projection, not an alternate task store. There is no task-mutation CLI fallback.
+
 ## Prerequisites
 
 - `/ultra-research` completed — specs must be 100% (no `[NEEDS CLARIFICATION]`)
@@ -26,6 +39,13 @@ automatically. Context-md bodies are written by this skill (not projector).
 
 ## Workflow
 
+### Workflow activation
+
+At entry, write `.ultra/workflow-state.json` with
+`{"command":"ultra-plan","task_id":"plan","step":"0","status":"active","ts":"<ISO8601>"}`.
+This activates the workflow-only hooks. Mark it terminal only after the MCP
+task writes and verification complete.
+
 ### Input Mode Selection (BEFORE Step 0)
 
 Two entry points lead into the planner:
@@ -140,7 +160,7 @@ On fail → instruct user to run `/ultra-research` targeting the gap.
 
 Fields per task: `id`, `title` (action verb + target), `type`
 (architecture/feature/bugfix), `priority` (P0-P3), `complexity` (1-10),
-`status` (pending initially), `dependencies` (task IDs), `estimated_days`,
+`status` (pending initially), `deps` (task IDs), `estimated_days`,
 `context_file`, `trace_to` (spec section anchor).
 
 #### Integration tasks — MANDATORY inserts
@@ -187,19 +207,13 @@ For **each** task in the planned list (topological order):
   "type": "architecture",
   "priority": "P0",
   "complexity": 4,
+  "estimated_days": 2,
   "deps": [],
   "tag": "<git branch>",              // optional
   "trace_to": ".ultra/specs/product.md#US-01"
 }
 ```
 
-**CLI fallback** (per task):
-```bash
-ultra-tools task create \
-  --title "Walking skeleton: …" --type architecture --priority P0 \
-  --complexity 4 --trace-to ".ultra/specs/product.md#US-01"
-```
-
 After each `task.create`, the server auto-runs the projector — `tasks.json`
 and `contexts/task-{id}.md` (frontmatter only) appear.
 
@@ -299,16 +313,17 @@ Summary output:
 | **Output (projected)** | `.ultra/tasks/tasks.json`, `.ultra/tasks/contexts/task-*.md` |
 | **Next** | `/ultra-dev` |
 
-## MCP → CLI fallback matrix
+## MCP failure matrix
 
-| Purpose | MCP tool | CLI fallback |
-|---------|----------|--------------|
+| Purpose | MCP tool | Failure behavior |
+|---------|----------|------------------|
 | Scope mode prompt | none | current Host's native user-interaction surface |
-| Create task | `task.create` | `ultra-tools task create --title … --type … --priority …` |
+| Create task | `task.create` | stop; surface the MCP error; never write a projection |
 
 ## What this skill DOES NOT do
 
 - Does NOT write state.db directly — all task writes go through `task.create`
 - Does NOT regenerate `tasks.json` — projector owns that
+- Does NOT read `tasks.json` when MCP state is empty or unavailable
 - Does NOT start implementation — that's `/ultra-dev`
 - Does NOT re-run research — if specs are incomplete, redirects to `/ultra-research`

package/skills/ultra-status/SKILL.md

@@ -16,13 +16,20 @@ Single-call dashboard. Pulls task state from state.db (authoritative), layers
 in `.ultra/test-report.json` + `.ultra/delivery-report.json` (file artifacts),
 reports progress + risks + workflow routing.
 
+## Authority failure boundary
+
+`task.list` and `task.get` are the only task-state inputs. If either is
+unavailable or returns an authority error, surface it and stop. Never fall back to `.ultra/tasks/tasks.json`.
+On `LEGACY_STATE_MIGRATION_REQUIRED`, instruct the
+user to run `ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>`.
+
 ## Workflow
 
 ### Phase 0 — Environment validation
 
 | Check | If missing |
 |-------|-----------|
-| `.ultra/tasks/tasks.json` projection present (or state.db reachable) | suggest `/ultra-init` |
+| state.db reachable through `task.list` | suggest `/ultra-init` only when `.ultra/` is absent; otherwise surface the MCP error |
 | At least one task visible via `task.list` | suggest `/ultra-plan` |
 | `task.list` returns valid rows | surface error |
 
@@ -42,8 +49,6 @@ reports progress + risks + workflow routing.
 // → { events: [...], next_since_id: M }
 ```
 
-**CLI fallback**: `ultra-tools task list` + `ultra-tools session list`.
-
 Also read:
 - `.ultra/test-report.json` — if present
 - `.ultra/delivery-report.json` — if present
@@ -132,12 +137,12 @@ When `task-id` provided:
 Display: title, status, priority, complexity, deps, files_modified (if set),
 session_id (if active), `context_file`, `trace_to`, stale flag, update history.
 
-## MCP → CLI fallback matrix
+## MCP and CLI matrix
 
 | Purpose | MCP tool | CLI fallback |
 |---------|----------|--------------|
-| List tasks | `task.list` | `ultra-tools task list` |
-| Single task detail | `task.get` | `ultra-tools task get <id>` |
+| List tasks | `task.list` | none; fail closed |
+| Single task detail | `task.get` | none; fail closed |
 | Cost panel (Phase 6.3) | — | `ultra-tools status --cost --json --since 7d` |
 
 ## Cost panel (Phase 6.3)

package/skills/ultra-test/SKILL.md

@@ -4,7 +4,6 @@ description: "Pre-delivery quality audit — Anti-Pattern + Coverage Gap + Wirin
 runtime: all
 mcp_tools_required:
   - task.list
-cli_fallback: "task list"
 ---
 
 # ultra-test — Phase 3.5
@@ -14,6 +13,13 @@ each writes a JSON gate result; the skill aggregates into `.ultra/test-report.js
 This is **not** for running unit tests (that is `/ultra-dev`). This is the
 pre-ship gate.
 
+## Authority failure boundary
+
+The completed-task precheck requires MCP `task.list`. If it is unavailable or
+returns an authority error, stop the audit. Never fall back to
+`.ultra/tasks/tasks.json`. For `LEGACY_STATE_MIGRATION_REQUIRED`, instruct
+`ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>`.
+
 ## Prerequisites
 
 - `task.list` returns ≥1 task with `status=completed`
@@ -173,11 +179,11 @@ when `passed=true`.
 | Performance | all Core Web Vitals (if frontend) |
 | Security | 0 critical/high |
 
-## MCP → CLI fallback matrix
+## MCP failure matrix
 
 | Purpose | MCP tool | CLI fallback |
 |---------|----------|--------------|
-| Confirm ≥1 completed task | `task.list { status: "completed" }` | `ultra-tools task list --status completed` |
+| Confirm ≥1 completed task | `task.list { status: "completed" }` | none; fail closed |
 | Confirm risky auto-fix | none | current Host's native user-interaction surface |
 
 ## What this skill DOES NOT do

package/spec/cli-protocol.md

@@ -1,9 +1,9 @@
 # `ultra-tools` CLI protocol
 
-`ultra-tools` is the shell fallback for the live MCP state contract
-(PLAN §4, D12). Every tool in `spec/mcp-tools.yaml` has a matching
-`ultra-tools <subcommand>`; host-native review, impact discovery, skill
-resolution, and human interaction are intentionally outside this protocol.
+`ultra-tools` is the maintenance CLI around the live MCP runtime (PLAN §4,
+D12). The mapping registry below reserves stable command names for MCP tools;
+it does not mean every mapping is executable. Task lifecycle workflows must use
+the live MCP server and fail closed when it is unavailable.
 
 Trace: PLAN §6 Phase 1.4, decisions D12 / D29 / D33 / D37.
 
@@ -74,9 +74,10 @@ informational. Never rely on stderr for status.
 
 ## 5. Tool ↔ CLI mapping
 
-The mapping below is generated from `spec/mcp-tools.yaml` by
+The compatibility mapping below is generated from `spec/mcp-tools.yaml` by
 `spec/scripts/check-cli-mapping.cjs` and asserted at gate time. This table
-is the authoritative reference; do not duplicate it in command md files.
+is a naming contract, not an implementation inventory; do not advertise a row
+as a fallback unless `ultra-tools <family> --help` lists it.
 
 | MCP tool                  | CLI subcommand              | Phase | Writer  |
 |---------------------------|-----------------------------|------:|---------|
@@ -102,13 +103,11 @@ is the authoritative reference; do not duplicate it in command md files.
 | `plan.export`             | `plan export`               | 8a    | mcp     |
 | `plan.get`                | `plan get`                  | 8a    | any     |
 
-`Writer = mcp` rows go through the MCP server's single-writer connection;
-the CLI shells out to the running MCP server over stdio rather than
-touching `.ultra/state.db` directly. `Writer = any` rows are safe to
-execute from any process — read-only queries and `events` appends fall
-into this bucket because `events.id AUTOINCREMENT` makes concurrent
-INSERTs collision-free under WAL + `busy_timeout`. The full policy lives
-in `docs/STATE-DB-ACCESS-POLICY.md` (Phase 2.2 / R25).
+Current executable maintenance surfaces are `task init-project`,
+`session close|get|list|admission|heartbeat|subscribe|reap`, `status`, `db`,
+`migrate`, and `legacy-memory`. In particular, `task create|update|list|get`
+are not CLI fallbacks. The full access policy lives in
+`docs/STATE-DB-ACCESS-POLICY.md` (Phase 2.2 / R25).
 
 ## 6. Versioning
 

package/spec/mcp-tools.yaml

@@ -14,6 +14,8 @@ info:
     Host-native review, impact, skill discovery, and human-interaction capabilities
     are documented by each adapter's capability map rather than advertised as MCP.
     Generators consume this YAML to derive types, validators, and CLI parsers (R19).
+    cli_subcommand values reserve stable names; runtime availability is defined by
+    ultra-tools <family> --help. Task lifecycle skills use MCP and fail closed.
     Adding a tool requires: (a) update this file, (b) add valid+invalid
     fixture to spec/fixtures/{valid,invalid}/, (c) `npm run test:spec` green.
 
@@ -40,6 +42,7 @@ tools:
         type:           { type: string, enum: [architecture, feature, bugfix] }
         priority:       { type: string, enum: [P0, P1, P2, P3] }
         complexity:     { type: integer, minimum: 1, maximum: 10 }
+        estimated_days: { type: number, exclusiveMinimum: 0, description: 'estimated implementation effort in days' }
         deps:           { type: array, items: { type: string } }
         files_modified: { type: array, items: { type: string }, description: 'Phase 8A conflict detection' }
         parent_id:      { type: string, description: 'Phase 8A.3 parent reference for task.expand children' }
@@ -56,6 +59,7 @@ tools:
     errors:
       - { code: VALIDATION_ERROR, description: 'input failed schema validation' }
       - { code: DUPLICATE_TASK_ID, description: 'task id already exists' }
+      - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
       - { code: STATE_DB_LOCKED, description: 'database is locked', retriable: true }
     cli_subcommand: task create
     emits_events: [task_created]
@@ -79,6 +83,7 @@ tools:
             status:        { type: string, enum: [pending, in_progress, completed, blocked, expanded] }
             priority:      { type: string, enum: [P0, P1, P2, P3] }
             complexity:    { type: integer, minimum: 1, maximum: 10 }
+            estimated_days: { type: number, exclusiveMinimum: 0 }
             deps:          { type: array, items: { type: string } }
             files_modified: { type: array, items: { type: string } }
             session_id:    { type: string }
@@ -96,6 +101,7 @@ tools:
       - { code: TASK_NOT_FOUND, description: 'no task with given id' }
       - { code: ILLEGAL_STATUS_TRANSITION, description: 'transition rejected by state machine' }
       - { code: VALIDATION_ERROR, description: 'patch failed schema validation' }
+      - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
     cli_subcommand: task update
     emits_events: [task_started, task_completed, task_blocked, task_stale_marked]
     trace_to: '§7.3, §7.2'
@@ -123,6 +129,7 @@ tools:
         count: { type: integer, minimum: 0 }
     errors:
       - { code: VALIDATION_ERROR, description: 'filter failed schema validation' }
+      - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
     cli_subcommand: task list
     emits_events: []
     trace_to: '§7.3'

package/spec/schemas/state-db.sql

@@ -21,6 +21,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   type              TEXT NOT NULL CHECK (type IN ('architecture', 'feature', 'bugfix')),
   priority          TEXT NOT NULL CHECK (priority IN ('P0', 'P1', 'P2', 'P3')),
   complexity        INTEGER CHECK (complexity BETWEEN 1 AND 10),
+  estimated_days    REAL CHECK (estimated_days IS NULL OR estimated_days > 0),
   status            TEXT NOT NULL DEFAULT 'pending'
                       CHECK (status IN ('pending', 'in_progress', 'completed', 'blocked', 'expanded')),
   deps              TEXT,                -- JSON array of task ids
@@ -152,3 +153,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('5.2', 'Phase 5.2 — circuit_breaker table for per-task trip tracking');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('8A.1', 'Phase 8A.1 — tasks.parent_id for task.expand parent→children');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('8A.2', 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');

package/spec/schemas/tasks.v4.5.schema.json

@@ -26,6 +26,7 @@
         "type":       { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
         "priority":   { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
         "complexity": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "estimated_days": { "type": "number", "exclusiveMinimum": 0 },
         "status": {
           "type": "string",
           "enum": ["pending", "in_progress", "completed", "blocked", "expanded"],