ultra-builder-pro-cli 0.5.0 → 0.5.2

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"],

package/ultra-tools/cli.cjs

@@ -3,9 +3,9 @@
 /**
  * ultra-tools — runtime-agnostic state engine for Ultra Builder Pro.
  *
- * Shell fallback for Ultra task/session state, status, database maintenance,
- * migration, and explicit legacy-memory cleanup. User interaction, skill
- * discovery, and subagent delegation stay on each host's native surfaces.
+ * Maintenance CLI for Ultra initialization, status, database operations,
+ * migration, and explicit legacy-memory cleanup. Authoritative task mutations
+ * stay on the live MCP server; this CLI is not a task-state fallback.
  *
  * Usage:
  *   ultra-tools <subcommand> [...]
@@ -33,8 +33,8 @@ USAGE:
   ultra-tools <subcommand> [args]
 
 SUBCOMMANDS:
-  task      create | update | list | get | delete
-  session   spawn | close | get | list | admission | heartbeat | subscribe
+  task      init-project
+  session   close | get | list | admission | heartbeat | subscribe | reap
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
   migrate   --from=4.4 --to=4.5 [--dry|--rollback]          (Phase 2)

package/ultra-tools/commands/migrate.cjs

@@ -5,6 +5,7 @@ const path = require('node:path');
 
 const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
+const projector = require('../../mcp-server/lib/projector.cjs');
 
 const SUPPORTED_FROM = '4.4';
 const SUPPORTED_TO = '4.5';
@@ -78,12 +79,85 @@ function copyDirSync(src, dst) {
   }
 }
 
+function isoTimestamp(value, fallback) {
+  const candidate = value || fallback;
+  const date = new Date(candidate);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`migrate: invalid timestamp ${JSON.stringify(candidate)}`);
+  }
+  return date.toISOString();
+}
+
+function projectRelativeContextPath(sourceDir, value) {
+  if (!value) return null;
+  const normalized = String(value).replaceAll('\\', '/');
+  if (normalized.startsWith('.ultra/')) return normalized;
+  if (normalized.startsWith('contexts/')) return `.ultra/tasks/${normalized}`;
+  if (path.isAbsolute(value)) {
+    const relative = path.relative(sourceDir, value).replaceAll(path.sep, '/');
+    if (relative.startsWith('../') || relative === '..') {
+      throw new Error(`migrate: context_file escapes project root: ${value}`);
+    }
+    return relative;
+  }
+  return `.ultra/tasks/contexts/${path.basename(normalized)}`;
+}
+
+function sanitizeLegacyContextTemplate(sourceDir) {
+  const file = path.join(sourceDir, '.ultra', 'tasks', 'contexts', 'TEMPLATE.md');
+  if (!fs.existsSync(file)) return false;
+  const current = fs.readFileSync(file, 'utf8');
+  const next = current
+    .replace(/^>\s*\*\*Status\*\*:.*(?:\r?\n|$)(?:\r?\n)?/mi, '')
+    .replace(
+      /Read by mid_workflow_recall\.py and session_context\.py and injected into agent context\./g,
+      'Used as task-local acceptance criteria by the active Ultra workflow.',
+    );
+  if (next === current) return false;
+  fs.writeFileSync(file, next);
+  return true;
+}
+
+function normalizeLegacyTask(task, tasksJson, contextHeaders, sourceDir) {
+  if (!task || typeof task !== 'object') throw new Error('migrate: every task must be an object');
+  for (const field of ['id', 'title', 'type', 'priority', 'status']) {
+    if (task[field] === undefined || task[field] === null || task[field] === '') {
+      throw new Error(`migrate: task ${task.id || '(unknown)'} missing ${field}`);
+    }
+  }
+  const deps = task.dependencies ?? task.deps ?? [];
+  if (!Array.isArray(deps)) throw new Error(`migrate: task ${task.id} dependencies must be an array`);
+  if (task.estimated_days !== undefined
+      && (!Number.isFinite(task.estimated_days) || task.estimated_days <= 0)) {
+    throw new Error(`migrate: task ${task.id} estimated_days must be a positive number`);
+  }
+  const createdAt = isoTimestamp(task.created_at, tasksJson.created);
+  const updatedAt = isoTimestamp(task.updated_at, tasksJson.updated || tasksJson.created);
+  const ctx = contextHeaders[task.id];
+  const contextFile = projectRelativeContextPath(
+    sourceDir,
+    task.context_file || (ctx && ctx._file),
+  );
+  return {
+    ...task,
+    deps,
+    estimated_days: task.estimated_days ?? null,
+    context_file: contextFile,
+    created_at: createdAt,
+    updated_at: updatedAt,
+  };
+}
+
 function planForward(sourceDir) {
   const tasksPath = path.join(sourceDir, '.ultra', 'tasks', 'tasks.json');
   const tasksJson = readJsonOptional(tasksPath);
   if (!tasksJson || !Array.isArray(tasksJson.tasks)) {
     throw new Error(`migrate: tasks.json missing or malformed at ${tasksPath}`);
   }
+  const version = String(tasksJson.version || tasksJson.schema_version || '');
+  if (version !== SUPPORTED_FROM) {
+    throw new Error(`migrate: expected v${SUPPORTED_FROM} tasks.json, found ${version || '(missing version)'}`);
+  }
 
   const contextHeaders = {};
   for (const file of findContexts(sourceDir)) {
@@ -107,9 +181,12 @@ function planForward(sourceDir) {
   const eventsPath = path.join(sourceDir, '.ultra', 'activity-log.json');
   const events = readJsonOptional(eventsPath);
   const eventList = Array.isArray(events) ? events : [];
+  const tasks = tasksJson.tasks.map((task) => (
+    normalizeLegacyTask(task, tasksJson, contextHeaders, sourceDir)
+  ));
 
   return {
-    tasks: tasksJson.tasks,
+    tasks,
     events: eventList,
     contextHeaders,
     warnings,
@@ -118,50 +195,44 @@ function planForward(sourceDir) {
 
 function applyForward(db, plan) {
   const insertTask = db.prepare(
-    "INSERT INTO tasks (id, title, type, priority, complexity, status, deps, tag, trace_to, context_file, created_at, updated_at) VALUES (@id, @title, @type, @priority, @complexity, @status, @deps, @tag, @trace_to, @context_file, @created_at, @updated_at)",
+    "INSERT INTO tasks (id, title, type, priority, complexity, estimated_days, status, deps, tag, trace_to, context_file, created_at, updated_at) VALUES (@id, @title, @type, @priority, @complexity, @estimated_days, @status, @deps, @tag, @trace_to, @context_file, @created_at, @updated_at)",
   );
   const insertEvent = db.prepare(
     "INSERT INTO events (ts, type, task_id, session_id, runtime, payload_json) VALUES (@ts, @type, @task_id, @session_id, @runtime, @payload)",
   );
 
-  const taskInserted = ops.tx(db, () => {
-    let n = 0;
-    for (const t of plan.tasks) {
-      const ctx = plan.contextHeaders[t.id];
-      insertTask.run({
-        id: t.id,
-        title: t.title,
-        type: t.type,
-        priority: t.priority,
-        complexity: t.complexity ?? null,
-        status: t.status,
-        deps: t.deps ? JSON.stringify(t.deps) : null,
-        tag: t.tag ?? null,
-        trace_to: t.trace_to ?? null,
-        context_file: ctx ? ctx._file : null,
-        created_at: t.created_at,
-        updated_at: t.updated_at,
-      });
-      n++;
-    }
-    return n;
-  });
-
-  const eventsInserted = ops.tx(db, () => {
-    let n = 0;
-    for (const e of plan.events) {
-      insertEvent.run({
-        ts: e.ts || new Date().toISOString(),
-        type: e.type,
-        task_id: e.task_id ?? null,
-        session_id: e.session_id ?? null,
-        runtime: e.runtime ?? null,
-        payload: e.payload === undefined ? null : JSON.stringify(e.payload),
-      });
-      n++;
-    }
-    return n;
-  });
+  let taskInserted = 0;
+  for (const t of plan.tasks) {
+    insertTask.run({
+      id: t.id,
+      title: t.title,
+      type: t.type,
+      priority: t.priority,
+      complexity: t.complexity ?? null,
+      estimated_days: t.estimated_days,
+      status: t.status,
+      deps: JSON.stringify(t.deps),
+      tag: t.tag ?? null,
+      trace_to: t.trace_to ?? null,
+      context_file: t.context_file,
+      created_at: t.created_at,
+      updated_at: t.updated_at,
+    });
+    taskInserted++;
+  }
+
+  let eventsInserted = 0;
+  for (const e of plan.events) {
+    insertEvent.run({
+      ts: e.ts || new Date().toISOString(),
+      type: e.type,
+      task_id: e.task_id ?? null,
+      session_id: e.session_id ?? null,
+      runtime: e.runtime ?? null,
+      payload: e.payload === undefined ? null : JSON.stringify(e.payload),
+    });
+    eventsInserted++;
+  }
 
   return { taskInserted, eventsInserted };
 }
@@ -220,14 +291,23 @@ function cmdForward(flags) {
   let db;
   try {
     db = initStateDb(dbPath).db;
-    const counts = applyForward(db, plan);
-    recordMigration(db, {
-      from: SUPPORTED_FROM,
-      to: SUPPORTED_TO,
-      direction: 'forward',
-      status: 'success',
-      notes: `tasks=${counts.taskInserted} events=${counts.eventsInserted} warnings=${plan.warnings.length}`,
+    const counts = ops.tx(db, () => {
+      const existing = db.prepare('SELECT COUNT(*) AS count FROM tasks').get().count;
+      if (existing > 0) {
+        throw new Error(`migrate: refusing to merge into non-empty state.db (tasks=${existing})`);
+      }
+      const inserted = applyForward(db, plan);
+      recordMigration(db, {
+        from: SUPPORTED_FROM,
+        to: SUPPORTED_TO,
+        direction: 'forward',
+        status: 'success',
+        notes: `tasks=${inserted.taskInserted} events=${inserted.eventsInserted} warnings=${plan.warnings.length}`,
+      });
+      return inserted;
     });
+    projector.projectAll(db, { rootDir: sourceDir });
+    const contextTemplateSanitized = sanitizeLegacyContextTemplate(sourceDir);
     emit({
       ok: true,
       data: {
@@ -240,6 +320,7 @@ function cmdForward(flags) {
         tasks_inserted: counts.taskInserted,
         events_inserted: counts.eventsInserted,
         warnings: plan.warnings,
+        context_template_sanitized: contextTemplateSanitized,
       },
     });
     return 0;
@@ -351,4 +432,11 @@ Rollback restores from the latest backup-v4.4-* directory and writes a
 matching migration_history rollback row before dropping state.db.
 `;
 
-module.exports = { dispatch, USAGE, parseFlags, planForward, parseFrontmatter };
+module.exports = {
+  dispatch,
+  USAGE,
+  parseFlags,
+  planForward,
+  parseFrontmatter,
+  sanitizeLegacyContextTemplate,
+};

package/ultra-tools/commands/task.cjs

@@ -1,10 +1,8 @@
 'use strict';
 
-// CLI dispatcher for the `task` family. Phase 3.1 implements `init-project`
-// as the fallback for /ultra-init when MCP is unreachable. Additional verbs
-// (create / update / list / ...) will be wired in Phase 3.3+ as each command
-// migrates — they share the same stdout envelope contract declared in
-// spec/cli-protocol.md §2.
+// CLI dispatcher for the only task-family maintenance command. Runtime task
+// reads and writes intentionally remain MCP-only so a Host cannot silently
+// bypass the state-authority and projection-conflict gates.
 
 const { initProject, InitProjectError } = require('../../mcp-server/lib/init-project.cjs');
 
@@ -87,7 +85,7 @@ function dispatch(args) {
   switch (verb) {
     case 'init-project': return dispatchInitProject(rest);
     default:
-      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown task verb '${verb}'; see spec/cli-protocol.md for supported task CLI verbs` } });
+      emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown task verb '${verb}'; only init-project is supported by the maintenance CLI` } });
       return 1;
   }
 }

package/.ultra-template/tasks/contexts/TEMPLATE.md

@@ -1,57 +0,0 @@
-# Task {id}: {title}
-
-> **Status**: pending | **Priority**: {priority} | **Complexity**: {complexity}
-
-## Context
-
-**What**: [Clear description of what to build/change]
-
-**Why**: [Business value linking to Persona + Scenario from specs]
-
-**Constraints**:
-- [Technical or business constraint 1]
-- [Technical or business constraint 2]
-
-## Implementation
-
-**Target Files**:
-- `path/to/file.ts` (create)
-- `path/to/existing.ts` (modify: description)
-
-**Pattern**: [Reference to existing code patterns to follow]
-
-**Tech Notes**: [Framework/library specific guidance]
-
-## Acceptance
-
-**Tests**:
-- [ ] `test command here`
-- [ ] Pass: [scenario 1 description]
-- [ ] Pass: [scenario 2 description]
-
-**Verification**:
-```bash
-# Manual verification command
-curl -X POST localhost:3000/api/example
-```
-
-## Trace
-
-**Source**: `.ultra/specs/product.md#section-id`
-
-## Change Log
-
-| Date | Change | Specs Updated | Reason |
-|------|--------|---------------|--------|
-| {created_date} | Initial creation | - | Generated by /ultra-plan |
-
-## Completion
-
-> _Fill when task completed_
-
-- **Completed**: {date}
-- **Commit**: {hash}
-- **Summary**: {brief description of what was delivered}
-
----
-*Generated by /ultra-plan*

package/.ultra-template/tasks/tasks.json

@@ -1,33 +0,0 @@
-{
-  "version": "4.4",
-  "created": "",
-  "updated": "",
-  "project": {
-    "name": "",
-    "type": "",
-    "stack": ""
-  },
-  "tasks": [],
-  "metadata": {
-    "totalTasks": 0,
-    "completedTasks": 0,
-    "inProgressTasks": 0,
-    "pendingTasks": 0,
-    "totalEstimatedDays": 0
-  },
-  "_schema": {
-    "_comment": "Lightweight task registry - full context in contexts/task-{id}.md",
-    "task_example": {
-      "id": "1",
-      "title": "Action verb + specific target",
-      "type": "feature|architecture|bugfix",
-      "priority": "P0|P1|P2|P3",
-      "complexity": "1-10",
-      "status": "pending|in_progress|completed|blocked",
-      "dependencies": ["task_id"],
-      "estimated_days": 2,
-      "context_file": "contexts/task-1.md",
-      "trace_to": ".ultra/specs/product.md#section-id"
-    }
-  }
-}