ultra-builder-pro-cli 0.20.0 → 0.21.1

package/spec/schemas/change-delta.v1.schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/schemas/change-delta.v1.schema.json",
+  "title": "Ultra Change delta v1",
+  "type": "object",
+  "required": [
+    "$schema",
+    "change_id",
+    "baseline_anchor",
+    "decisions",
+    "non_goals",
+    "acceptance",
+    "documentation_impact",
+    "unknowns",
+    "mutations"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "ultra-change-delta-v1" },
+    "change_id": { "type": "string", "minLength": 1 },
+    "baseline_anchor": {
+      "type": "object",
+      "required": ["baseline_id", "repository_revision", "specs"],
+      "additionalProperties": false,
+      "properties": {
+        "baseline_id": { "type": "string", "minLength": 1 },
+        "repository_revision": { "type": ["string", "null"] },
+        "specs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "required": ["path", "digest"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+            }
+          }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "summary"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
+          "summary": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "non_goals": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "acceptance": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "criterion", "verification"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
+          "criterion": { "type": "string", "minLength": 1 },
+          "verification": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "documentation_impact": {
+      "type": "object",
+      "required": ["status", "files", "rationale"],
+      "additionalProperties": false,
+      "properties": {
+        "status": { "enum": ["none", "required"] },
+        "files": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "rationale": { "type": "string", "minLength": 3 }
+      }
+    },
+    "unknowns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "summary", "blocking"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
+          "summary": { "type": "string", "minLength": 1 },
+          "blocking": { "type": "boolean" }
+        }
+      }
+    },
+    "no_semantic_change_reason": { "type": "string", "minLength": 3 },
+    "mutations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "action",
+          "target_path",
+          "overlay_path",
+          "before_digest",
+          "after_digest",
+          "acceptance_refs",
+          "documentation_refs"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
+          "action": { "enum": ["add", "update"] },
+          "target_path": { "type": "string", "minLength": 1 },
+          "overlay_path": { "type": "string", "minLength": 1 },
+          "before_digest": {
+            "type": ["string", "null"],
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "after_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "acceptance_refs": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "documentation_refs": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "mutations": { "maxItems": 0 }
+        }
+      },
+      "then": { "required": ["no_semantic_change_reason"] }
+    }
+  ]
+}

package/spec/schemas/documentation-reconciliation.v1.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/schemas/documentation-reconciliation.v1.schema.json",
+  "title": "Ultra documentation reconciliation v1",
+  "type": "object",
+  "required": [
+    "$schema",
+    "change_id",
+    "delta_artifact_id",
+    "delta_digest",
+    "documents"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "ultra-documentation-reconciliation-v1" },
+    "change_id": { "type": "string", "minLength": 1 },
+    "delta_artifact_id": { "type": "string", "minLength": 1 },
+    "delta_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "no_change_reason": { "type": "string", "minLength": 3 },
+    "documents": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "action",
+          "overlay_path",
+          "before_digest",
+          "after_digest",
+          "delta_refs",
+          "acceptance_refs",
+          "verification",
+          "consumers"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "action": { "enum": ["add", "update"] },
+          "overlay_path": { "type": "string", "minLength": 1 },
+          "before_digest": {
+            "type": ["string", "null"],
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "after_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "delta_refs": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "acceptance_refs": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "verification": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["command", "status", "evidence_refs"],
+              "additionalProperties": false,
+              "properties": {
+                "command": { "type": "string", "minLength": 1 },
+                "status": { "const": "pass" },
+                "evidence_refs": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          },
+          "consumers": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["type", "id", "relation"],
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "enum": ["artifact", "project", "baseline", "change", "task", "workflow", "external"]
+                },
+                "id": { "type": "string", "minLength": 1 },
+                "relation": { "type": "string", "minLength": 1 }
+              }
+            }
+          },
+          "no_consumer_reason": { "type": "string", "minLength": 3 }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "documents": { "maxItems": 0 }
+        }
+      },
+      "then": { "required": ["no_change_reason"] }
+    }
+  ]
+}

package/spec/schemas/mcp-tools.schema.json

@@ -60,7 +60,7 @@
         },
         "family": {
           "type": "string",
-          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan", "baseline", "change", "decision", "workflow", "system"]
+          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan", "baseline", "change", "decision", "workflow", "artifact", "system"]
         },
         "description": { "type": "string", "minLength": 10 },
         "phase": {

package/spec/schemas/state-db.sql

@@ -1,5 +1,5 @@
 -- Ultra Builder Pro — authoritative state schema
--- This file builds .ultra/state.db, the source of truth for all
+-- This file builds .ultra/.runtime/state.db, the source of truth for all
 -- baseline / change / task / session / event / telemetry data. tasks.json and context md status
 -- headers are projections.
 --
@@ -15,7 +15,7 @@
 -- ──────────────────────────── project baseline ─────────────────────────────
 -- The baseline is the approved, repository-scoped snapshot that every change
 -- is measured against. It stores digests and evidence references, never source,
--- prompt, transcript, memory, or code-graph payloads.
+-- prompt, transcript, general memory-provider, or code-graph payloads.
 CREATE TABLE IF NOT EXISTS baselines (
   id                  TEXT PRIMARY KEY,
   project_name        TEXT NOT NULL,
@@ -159,6 +159,8 @@ CREATE TABLE IF NOT EXISTS sessions (
 
 CREATE INDEX IF NOT EXISTS sessions_active ON sessions(status, task_id);
 CREATE INDEX IF NOT EXISTS sessions_lease  ON sessions(lease_expires_at) WHERE status = 'running';
+CREATE UNIQUE INDEX IF NOT EXISTS sessions_one_active_task
+  ON sessions(task_id) WHERE status = 'running';
 
 -- ──────────────────────────── schema_version ──────────────────────────────
 -- Cross-version misread guard (D30, R27). Single row per applied version.
@@ -225,20 +227,51 @@ CREATE INDEX IF NOT EXISTS circuit_breaker_tripped ON circuit_breaker(tripped_at
 
 -- ──────────────────────────── change artifacts ────────────────────────────
 CREATE TABLE IF NOT EXISTS artifacts (
-  id            TEXT PRIMARY KEY,
-  change_id     TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
-  task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
-  kind          TEXT NOT NULL,
-  path          TEXT NOT NULL,
-  content_hash  TEXT,
-  metadata_json TEXT,
-  status        TEXT NOT NULL DEFAULT 'current' CHECK (status IN ('current', 'archived')),
-  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-  updated_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-  UNIQUE(change_id, kind, path)
+  id              TEXT PRIMARY KEY,
+  owner_type      TEXT NOT NULL
+                    CHECK (owner_type IN ('project', 'baseline', 'change', 'task', 'workflow')),
+  owner_id        TEXT NOT NULL,
+  change_id       TEXT REFERENCES changes(id) ON DELETE SET NULL,
+  task_id         TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  kind            TEXT NOT NULL,
+  path            TEXT NOT NULL,
+  digest          TEXT,
+  content_hash    TEXT,
+  before_digest   TEXT,
+  after_digest    TEXT,
+  provenance_json TEXT NOT NULL DEFAULT '{}',
+  metadata_json   TEXT,
+  managed         INTEGER NOT NULL DEFAULT 0 CHECK (managed IN (0, 1)),
+  status          TEXT NOT NULL DEFAULT 'current'
+                    CHECK (status IN ('current', 'stale', 'terminal', 'archived')),
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE(owner_type, owner_id, kind, path)
 );
 
 CREATE INDEX IF NOT EXISTS artifacts_change ON artifacts(change_id, kind);
+CREATE INDEX IF NOT EXISTS artifacts_owner ON artifacts(owner_type, owner_id, status);
+CREATE INDEX IF NOT EXISTS artifacts_path ON artifacts(path, status);
+CREATE UNIQUE INDEX IF NOT EXISTS artifacts_one_active_path
+  ON artifacts(path) WHERE status <> 'archived';
+
+CREATE TABLE IF NOT EXISTS artifact_edges (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_type TEXT NOT NULL
+                CHECK (source_type IN ('artifact', 'project', 'baseline', 'change', 'task', 'workflow', 'external')),
+  source_id   TEXT NOT NULL,
+  target_type TEXT NOT NULL
+                CHECK (target_type IN ('artifact', 'project', 'baseline', 'change', 'task', 'workflow', 'external')),
+  target_id   TEXT NOT NULL,
+  relation    TEXT NOT NULL,
+  created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE(source_type, source_id, target_type, target_id, relation)
+);
+
+CREATE INDEX IF NOT EXISTS artifact_edges_source
+  ON artifact_edges(source_type, source_id);
+CREATE INDEX IF NOT EXISTS artifact_edges_target
+  ON artifact_edges(target_type, target_id);
 
 CREATE TABLE IF NOT EXISTS context_snapshots (
   id                 TEXT PRIMARY KEY,
@@ -265,6 +298,8 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
 );
 
 CREATE INDEX IF NOT EXISTS context_snapshots_change ON context_snapshots(change_id, created_at);
+CREATE INDEX IF NOT EXISTS context_snapshots_binding
+  ON context_snapshots(change_id, task_id, role, gate, created_at);
 
 CREATE TABLE IF NOT EXISTS spec_learning_candidates (
   id            TEXT PRIMARY KEY,
@@ -495,3 +530,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('18.0', 'Adaptive capability transitions, independent initialization, and recoverable workflow migration');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('19.0', 'Non-ceremonial decision completion and host-neutral intent persistence');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('20.0', 'Typed artifact registry, normalized dependency edges, and orphan diagnostics');

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

@@ -9,7 +9,7 @@
   "properties": {
     "schema_version": { "const": "4.5" },
     "generated_at":   { "type": "string", "format": "date-time" },
-    "source":         { "const": ".ultra/state.db", "description": "authoritative source (D32)" },
+    "source":         { "const": ".ultra/.runtime/state.db", "description": "authoritative source (D32)" },
     "tasks": {
       "type": "array",
       "items": { "$ref": "#/$defs/task" }

package/ultra-tools/cli.cjs

@@ -17,6 +17,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
 
 const VERSION = (() => {
   try {
@@ -38,7 +39,7 @@ SUBCOMMANDS:
   system    doctor [--repair] | restore | rebaseline
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=<4.4|4.5> --to=<4.5|19.0> [--dry|--rollback]
+  migrate   --from=<4.4|4.5> --to=<4.5|20.0> [--dry|--rollback]
   legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
   --help / -h      show this message
@@ -75,7 +76,7 @@ const TELEMETRY_SUBCOMMANDS = new Set(['session']);
 
 function emitCliTelemetry(sub, rest) {
   try {
-    const dbPath = path.resolve('.ultra', 'state.db');
+    const dbPath = runtimePaths.locateStateDb(process.cwd());
     if (!fs.existsSync(dbPath)) return;
     const Database = require('better-sqlite3');
     const db = new Database(dbPath);

package/ultra-tools/commands/db.cjs

@@ -2,11 +2,14 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const Database = require('better-sqlite3');
 
 const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const runtimePaths = require('../../mcp-server/lib/runtime-paths.cjs');
 
-const DEFAULT_DB_PATH = path.join('.ultra', 'state.db');
-const DEFAULT_BACKUP_DIR = path.join('.ultra', 'backups');
+const DEFAULT_DB_PATH = runtimePaths.STATE_DB_RELATIVE_PATH;
+const DEFAULT_BACKUP_DIR = path.join(runtimePaths.RUNTIME_RELATIVE_DIR, 'backups');
 
 function parseFlags(args) {
   const flags = { _: [] };
@@ -50,9 +53,19 @@ function dispatch(args) {
   }
 }
 
+function resolveAuthorityPath(flags, { migrateLegacy = true } = {}) {
+  const env = flags.path
+    ? { UBP_DB_PATH: path.resolve(flags.path) }
+    : process.env;
+  return runtimePaths.resolveConfiguredStateDb(process.cwd(), {
+    env,
+    migrateLegacy,
+  }).stateDbPath;
+}
+
 function cmdInit(flags) {
-  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
   try {
+    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
     const { db, schema_version, created, tables, path: actualPath } = initStateDb(dbPath);
     closeStateDb(db);
     emit({
@@ -80,13 +93,13 @@ function cmdInit(flags) {
 }
 
 function withOpenDb(flags, fn, errorCode) {
-  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
-  if (!fs.existsSync(dbPath)) {
-    emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}; run 'db init' first` } });
-    return 2;
-  }
   let db;
   try {
+    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
+    if (!fs.existsSync(dbPath)) {
+      emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}; run 'db init' first` } });
+      return 2;
+    }
     db = openStateDb(dbPath);
     const data = fn(db, dbPath);
     emit({ ok: true, data: { path: dbPath, ...data } });
@@ -131,24 +144,54 @@ function defaultBackupPath() {
   return path.join(DEFAULT_BACKUP_DIR, `state-db-${ts}.db`);
 }
 
-function cmdBackup(flags) {
-  const dbPath = path.resolve(flags.path || DEFAULT_DB_PATH);
-  const targetPath = path.resolve(flags.to || defaultBackupPath());
-  if (!fs.existsSync(dbPath)) {
-    emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}` } });
-    return 2;
+function quoteSqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function createOnlineBackup(db, targetPath, {
+  beforeSnapshot = null,
+} = {}) {
+  const stage = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.snapshot-${process.pid}-${randomUUID()}`,
+  );
+  try {
+    if (beforeSnapshot) beforeSnapshot();
+    // VACUUM INTO is SQLite's synchronous, transactionally consistent
+    // snapshot primitive. It reads committed pages through SQLite rather than
+    // copying a main file that may lag committed WAL frames.
+    db.exec(`VACUUM INTO ${quoteSqlString(stage)}`);
+    const snapshot = new Database(stage, { readonly: true, fileMustExist: true });
+    try {
+      const integrity = snapshot.pragma('integrity_check');
+      if (integrity.length !== 1 || integrity[0].integrity_check !== 'ok') {
+        throw new Error('SQLite backup snapshot failed integrity_check');
+      }
+    } finally {
+      snapshot.close();
+    }
+    fs.renameSync(stage, targetPath);
+    return fs.statSync(targetPath).size;
+  } finally {
+    fs.rmSync(stage, { force: true });
   }
-  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+}
+
+function cmdBackup(flags) {
   let db;
   try {
-    // Flush WAL into the main file so a plain copy captures all committed
-    // writes; fall back to copy-only on a fresh file with no WAL.
+    const dbPath = resolveAuthorityPath(flags, { migrateLegacy: true });
+    const targetPath = runtimePaths.assertManagedBackupDestination(
+      process.cwd(),
+      flags.to || defaultBackupPath(),
+    ).targetPath;
+    if (!fs.existsSync(dbPath)) {
+      emit({ ok: false, error: { code: 'DB_NOT_FOUND', message: `state.db missing at ${dbPath}` } });
+      return 2;
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
     db = openStateDb(dbPath);
-    db.pragma('wal_checkpoint(TRUNCATE)');
-    closeStateDb(db);
-    db = null;
-    fs.copyFileSync(dbPath, targetPath);
-    const size = fs.statSync(targetPath).size;
+    const size = createOnlineBackup(db, targetPath);
     emit({ ok: true, data: { source: dbPath, target: targetPath, size_bytes: size } });
     return 0;
   } catch (err) {
@@ -168,8 +211,16 @@ Verbs (Phase 2):
   integrity  [--path <db>]              run PRAGMA integrity_check
   backup     [--path <db>] [--to <out>] online .backup() to a file
 
-Default db: .ultra/state.db
-Default backup: .ultra/backups/state-db-{iso}.db
+Default db: .ultra/.runtime/state.db
+Default backup: .ultra/.runtime/backups/state-db-{iso}.db
 `;
 
-module.exports = { dispatch, USAGE, DEFAULT_DB_PATH, DEFAULT_BACKUP_DIR };
+module.exports = {
+  dispatch,
+  USAGE,
+  DEFAULT_DB_PATH,
+  DEFAULT_BACKUP_DIR,
+  _internal: {
+    createOnlineBackup,
+  },
+};