ultra-builder-pro-cli 0.14.0 → 0.16.0

package/mcp-server/lib/spec-learning.cjs

@@ -33,8 +33,14 @@ function rowToCandidate(row) {
   catch (error) {
     throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning evidence: ${error.message}`);
   }
-  const candidate = { ...row, evidence };
+  let applyEvidence;
+  try { applyEvidence = JSON.parse(row.apply_evidence_json || '[]'); }
+  catch (error) {
+    throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning apply evidence: ${error.message}`);
+  }
+  const candidate = { ...row, evidence, apply_evidence: applyEvidence };
   delete candidate.evidence_json;
+  delete candidate.apply_evidence_json;
   return candidate;
 }
 
@@ -102,6 +108,66 @@ function normalizeEvidence(value) {
   return [...new Set(value.map((entry) => entry.trim()))];
 }
 
+function targetFile(rootDir, targetRef) {
+  const separator = String(targetRef || '').lastIndexOf('#');
+  if (separator <= 0 || separator === targetRef.length - 1) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must use project-relative path#anchor');
+  }
+  const relative = targetRef.slice(0, separator);
+  if (path.isAbsolute(relative)) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must be project-relative');
+  }
+  const root = path.resolve(rootDir);
+  const file = path.resolve(root, relative);
+  if (file !== root && !file.startsWith(`${root}${path.sep}`)) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref escapes the project root');
+  }
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    throw new SpecLearningError('LEARNING_TARGET_MISSING', `target file does not exist: ${relative}`);
+  }
+  return { file, relative };
+}
+
+function digestFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function verifyApplyEvidence(input, current, rootDir) {
+  const appliedRef = typeof input.applied_ref === 'string' ? input.applied_ref.trim() : '';
+  const beforeDigest = typeof input.before_digest === 'string' ? input.before_digest.trim() : '';
+  const afterDigest = typeof input.after_digest === 'string' ? input.after_digest.trim() : '';
+  const evidence = normalizeEvidence(input.apply_evidence);
+  if (appliedRef !== current.target_ref || !/^[0-9a-f]{64}$/.test(beforeDigest)
+    || !/^[0-9a-f]{64}$/.test(afterDigest) || beforeDigest === afterDigest
+    || evidence.length === 0) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_REQUIRED',
+      'apply requires the exact target ref, distinct before/after digests, and durable evidence refs',
+    );
+  }
+  if (current.before_digest && current.before_digest !== beforeDigest) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'before_digest does not match the proposed target state',
+    );
+  }
+  const target = targetFile(rootDir, appliedRef);
+  if (digestFile(target.file) !== afterDigest) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'after_digest does not match the current target file',
+    );
+  }
+  const workflows = require('./workflow-state.cjs');
+  try {
+    workflows.resolveProjectSourceRef(rootDir, appliedRef, 'applied_ref');
+    for (const ref of evidence) workflows.resolveProjectSourceRef(rootDir, ref, 'apply_evidence');
+  } catch (error) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', `applied target or evidence anchor is invalid: ${error.message}`,
+    );
+  }
+  return { appliedRef, beforeDigest, afterDigest, evidence };
+}
+
 function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
   const change = mutableChange(db, input.change_id);
   const id = String(input.id || `learning-${crypto.randomUUID().slice(0, 12)}`).trim();
@@ -120,6 +186,8 @@ function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
     }
   }
   const evidence = normalizeEvidence(input.evidence);
+  const proposedTarget = targetFile(rootDir, targetRef);
+  const proposedDigest = digestFile(proposedTarget.file);
   const proposedAt = nowIso();
   return ops.tx(db, () => {
     try {
@@ -128,6 +196,9 @@ function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
          (id, change_id, task_id, target_ref, summary, evidence_json, proposed_at)
          VALUES (?, ?, ?, ?, ?, ?, ?)`,
       ).run(id, change.id, input.task_id || null, targetRef, summary, JSON.stringify(evidence), proposedAt);
+      db.prepare(
+        'UPDATE spec_learning_candidates SET before_digest = ? WHERE id = ? AND change_id = ?',
+      ).run(proposedDigest, id, change.id);
     } catch (error) {
       if (String(error.message).includes('UNIQUE')) {
         throw new SpecLearningError('DUPLICATE_LEARNING_ID', `spec-learning candidate ${id} exists`);
@@ -164,13 +235,19 @@ function resolveSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
     throw new SpecLearningError('VALIDATION_ERROR', `${input.decision} requires a resolution`);
   }
   const timestamp = nowIso();
+  const application = status === 'applied'
+    ? verifyApplyEvidence(input, current, rootDir)
+    : null;
   return ops.tx(db, () => {
     db.prepare(
       `UPDATE spec_learning_candidates
-       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?
+       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?, applied_ref = ?,
+       before_digest = COALESCE(?, before_digest), after_digest = ?, apply_evidence_json = ?
        WHERE id = ? AND change_id = ?`,
     ).run(
       status, resolution || null, timestamp, status === 'applied' ? timestamp : null,
+      application?.appliedRef || null, application?.beforeDigest || null,
+      application?.afterDigest || null, JSON.stringify(application?.evidence || []),
       current.id, change.id,
     );
     ops.appendEventInTx(db, {

package/mcp-server/lib/state-db.cjs

@@ -9,10 +9,14 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '12.0';
+const EXPECTED_VERSION = '16.0';
 const KIMI_SCHEMA_VERSION = '9.1';
 const CONTEXT_SCHEMA_VERSION = '10.0';
 const BASELINE_SCHEMA_VERSION = '11.0';
+const ADOPTION_SCHEMA_VERSION = '12.0';
+const WORKFLOW_SCHEMA_VERSION = '13.0';
+const AUTHORITY_SCHEMA_VERSION = '14.0';
+const SEMANTIC_SCHEMA_VERSION = '15.0';
 
 const MIGRATED_GAPS = Object.freeze([{
   id: 'legacy-rebaseline-required',
@@ -42,6 +46,10 @@ const REQUIRED_TABLES = Object.freeze([
   'incidents',
   'projection_jobs',
   'event_consumers',
+  'workflow_runs',
+  'workflow_steps',
+  'decision_threads',
+  'decision_items',
 ]);
 
 function applyBaselineUpgrade(db, { legacyState = false } = {}) {
@@ -63,6 +71,7 @@ function applyBaselineUpgrade(db, { legacyState = false } = {}) {
       worktree_digest     TEXT,
       worktree_files_json TEXT NOT NULL DEFAULT '[]',
       worktree_accepted   INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1)),
+      known_red_accepted  INTEGER NOT NULL DEFAULT 0 CHECK (known_red_accepted IN (0, 1)),
       spec_refs_json      TEXT NOT NULL DEFAULT '[]',
       evidence_json       TEXT NOT NULL DEFAULT '[]',
       verification_json   TEXT NOT NULL DEFAULT '[]',
@@ -70,6 +79,7 @@ function applyBaselineUpgrade(db, { legacyState = false } = {}) {
       gaps_json           TEXT NOT NULL DEFAULT '[]',
       classification_json TEXT NOT NULL DEFAULT '{}',
       provider_refs_json  TEXT NOT NULL DEFAULT '{}',
+      research_run_id     TEXT,
       approved_by         TEXT,
       approval_note       TEXT,
       started_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -114,17 +124,55 @@ function applyBaselineColumns(db) {
     db, 'baselines', columns, 'worktree_accepted',
     'INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1))',
   ) || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'known_red_accepted',
+    'INTEGER NOT NULL DEFAULT 0 CHECK (known_red_accepted IN (0, 1))',
+  ) || changed;
   changed = addColumnIfMissing(db, 'baselines', columns, 'gaps_json', "TEXT NOT NULL DEFAULT '[]'") || changed;
   changed = addColumnIfMissing(
     db, 'baselines', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'",
   ) || changed;
+  changed = addColumnIfMissing(db, 'baselines', columns, 'research_run_id', 'TEXT') || changed;
   return changed;
 }
 
 function applyChangeColumns(db) {
   if (!tableNames(db).includes('changes')) return false;
   const columns = columnNames(db, 'changes');
-  return addColumnIfMissing(db, 'changes', columns, 'baseline_bypass_json', 'TEXT');
+  let changed = false;
+  changed = addColumnIfMissing(db, 'changes', columns, 'baseline_bypass_json', 'TEXT') || changed;
+  changed = addColumnIfMissing(db, 'changes', columns, 'contract_json', "TEXT NOT NULL DEFAULT '{}'") || changed;
+  changed = addColumnIfMissing(db, 'changes', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'") || changed;
+  changed = addColumnIfMissing(
+    db, 'changes', columns, 'research_disposition_json', "TEXT NOT NULL DEFAULT '{}'",
+  ) || changed;
+  changed = addColumnIfMissing(
+    db, 'changes', columns, 'alignment_thread_id',
+    'TEXT REFERENCES decision_threads(id) ON DELETE SET NULL',
+  ) || changed;
+  return changed;
+}
+
+function applySemanticAuthorityColumns(db) {
+  let changed = false;
+  if (tableNames(db).includes('workflow_steps')) {
+    const columns = columnNames(db, 'workflow_steps');
+    changed = addColumnIfMissing(
+      db, 'workflow_steps', columns, 'semantic_records_json', "TEXT NOT NULL DEFAULT '[]'",
+    ) || changed;
+  }
+  if (tableNames(db).includes('spec_learning_candidates')) {
+    const columns = columnNames(db, 'spec_learning_candidates');
+    for (const [name, definition] of [
+      ['applied_ref', 'TEXT'],
+      ['before_digest', 'TEXT'],
+      ['after_digest', 'TEXT'],
+      ['apply_evidence_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ]) {
+      changed = addColumnIfMissing(db, 'spec_learning_candidates', columns, name, definition) || changed;
+    }
+  }
+  return changed;
 }
 
 function quoteSqlString(value) {
@@ -151,7 +199,14 @@ function readSchemaSql() {
 }
 
 function applyPragmas(db) {
-  db.pragma('journal_mode = WAL');
+  const journalMode = db.pragma('journal_mode = WAL', { simple: true });
+  if (String(journalMode).toLowerCase() !== 'wal') {
+    const error = new Error(
+      `state.db requires SQLite WAL mode; storage returned ${String(journalMode || 'unknown')}`,
+    );
+    error.code = 'STATE_DB_WAL_UNAVAILABLE';
+    throw error;
+  }
   db.pragma('synchronous = NORMAL');
   db.pragma('busy_timeout = 5000');
   db.pragma('foreign_keys = ON');
@@ -202,6 +257,19 @@ function applyCompatibleColumns(db) {
   if (!taskColumns.has('change_id')) {
     db.exec('ALTER TABLE tasks ADD COLUMN change_id TEXT REFERENCES changes(id) ON DELETE SET NULL');
   }
+  const taskAdditions = [
+    ['outcome', 'TEXT'],
+    ['slice_kind', "TEXT CHECK (slice_kind IS NULL OR slice_kind IN ('tracer_bullet', 'expand_contract', 'integration_checkpoint'))"],
+    ['public_seam', 'TEXT'],
+    ['verification_command', 'TEXT'],
+    ['acceptance_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ['context_refs_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ['docs_impact_json', "TEXT NOT NULL DEFAULT '{\"status\":\"unknown\",\"files\":[],\"rationale\":null}'"],
+    ['ownership_json', "TEXT NOT NULL DEFAULT '{}'"],
+  ];
+  for (const [name, definition] of taskAdditions) {
+    if (!taskColumns.has(name)) db.exec(`ALTER TABLE tasks ADD COLUMN ${name} ${definition}`);
+  }
   if (tables.has('events')) {
     const eventColumns = columnNames(db, 'events');
     if (!eventColumns.has('change_id')) db.exec('ALTER TABLE events ADD COLUMN change_id TEXT');
@@ -339,7 +407,10 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       "SELECT 1 FROM migration_history WHERE to_version = '10.0' AND status = 'success' LIMIT 1",
     ).get();
     const needsContextMigration = Boolean(
-      fromVersion && ![CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+      fromVersion && ![
+        CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION,
+        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
+      ].includes(fromVersion)
         && !contextMigration,
     );
     if (contextChanged || needsContextMigration) {
@@ -356,10 +427,14 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     applyBaselineUpgrade(db, { legacyState });
     applyBaselineColumns(db);
     applyChangeColumns(db);
+    applySemanticAuthorityColumns(db);
     const baselineMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '11.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && ![BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+    if (fromVersion && ![
+      BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION, WORKFLOW_SCHEMA_VERSION,
+      AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
+    ].includes(fromVersion)
       && !baselineMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -372,6 +447,32 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       );
     }
     if (legacyState) {
+      const legacyBaselines = db.prepare(
+        "SELECT id, mode, status, classification_json, gaps_json FROM baselines WHERE status != 'superseded'",
+      ).all();
+      for (const baseline of legacyBaselines) {
+        let classification = {};
+        let gaps = [];
+        try { classification = JSON.parse(baseline.classification_json || '{}'); } catch { classification = {}; }
+        try { gaps = JSON.parse(baseline.gaps_json || '[]'); } catch { gaps = []; }
+        if (!gaps.some((gap) => gap?.id === MIGRATED_GAPS[0].id)) gaps.push(MIGRATED_GAPS[0]);
+        classification.migration = {
+          previous_mode: baseline.mode,
+          previous_status: baseline.status,
+          from_schema: fromVersion || 'unknown',
+          requires_research_workflow: true,
+        };
+        db.prepare(
+          `UPDATE baselines SET mode = 'migrated', status = 'adopting',
+           classification_json = ?, gaps_json = ?, approved_by = NULL, approval_note = ?,
+           converged_at = NULL, research_run_id = NULL, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+           WHERE id = ?`,
+        ).run(
+          JSON.stringify(classification), JSON.stringify(gaps),
+          'Legacy project preserved; evidence-backed brownfield re-adoption is required',
+          baseline.id,
+        );
+      }
       db.prepare(
         `UPDATE baselines SET status = 'adopting', approved_by = NULL, approval_note = ?,
          converged_at = NULL, worktree_state = 'unavailable', worktree_digest = NULL,
@@ -393,18 +494,74 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
            VALUES (?, ?, 'forward', 'success', ?)`,
         ).run(
           BASELINE_SCHEMA_VERSION,
-          EXPECTED_VERSION,
+          ADOPTION_SCHEMA_VERSION,
           'Add repository snapshots, authoritative gap ledger, incident governance, and required re-adoption',
         );
       }
     }
+    const workflowMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '13.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !workflowMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === ADOPTION_SCHEMA_VERSION ? fromVersion : ADOPTION_SCHEMA_VERSION,
+        WORKFLOW_SCHEMA_VERSION,
+        'Add durable cross-stage workflow runs, step evidence, output digests, blockers, and recovery',
+      );
+    }
+    const authorityMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '14.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !authorityMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === WORKFLOW_SCHEMA_VERSION ? fromVersion : WORKFLOW_SCHEMA_VERSION,
+        AUTHORITY_SCHEMA_VERSION,
+        'Persist known-red acceptance and continuously revalidate ready baseline authority',
+      );
+    }
+    const semanticMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '15.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !semanticMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === AUTHORITY_SCHEMA_VERSION ? fromVersion : AUTHORITY_SCHEMA_VERSION,
+        SEMANTIC_SCHEMA_VERSION,
+        'Add typed research semantics, complete change contracts, verified learning application, and reconciliation provenance',
+      );
+    }
+    const dialogueMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '16.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !dialogueMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === SEMANTIC_SCHEMA_VERSION ? fromVersion : SEMANTIC_SCHEMA_VERSION,
+        EXPECTED_VERSION,
+        'Add durable one-question decision dialogue, owner checkpoints, and workflow alignment gates',
+      );
+    }
     db.exec('CREATE INDEX IF NOT EXISTS tasks_change ON tasks(change_id) WHERE change_id IS NOT NULL');
     db.exec('CREATE INDEX IF NOT EXISTS events_change ON events(change_id, id)');
     db.prepare(
       'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
     ).run(
       EXPECTED_VERSION,
-      'Evidence-backed repository snapshots, gap ledger, safe re-adoption, and incident break-glass governance',
+      'Durable one-question decision dialogue, owner checkpoints, and workflow alignment gates',
     );
   })();
 }
@@ -431,7 +588,10 @@ function initStateDb(dbPath) {
     db = openStateDb(dbPath);
     const existing = new Set(tableNames(db));
     const fromVersion = latestSchemaVersion(db);
-    const legacyState = existing.size > 0 && fromVersion !== EXPECTED_VERSION;
+    const legacyState = existing.size > 0
+      && ![
+        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
+      ].includes(fromVersion);
     backupPath = migrationBackup(db, dbPath, fromVersion, existing);
     applyCompatibleColumns(db);
     const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));

package/mcp-server/lib/state-ops.cjs

@@ -25,15 +25,19 @@ const STATUS_TRANSITIONS = Object.freeze({
 
 const TASK_FIELDS = Object.freeze([
   'id', 'title', 'type', 'priority', 'complexity', 'estimated_days', 'status',
-  'deps', 'files_modified', 'session_id', 'stale', 'complexity_hint',
-  'tag', 'trace_to', 'context_file', 'completion_commit', 'parent_id',
+  'deps', 'files_modified', 'session_id', 'stale',
+  'tag', 'trace_to', 'outcome', 'slice_kind', 'public_seam', 'verification_command',
+  'acceptance_json', 'context_refs_json', 'docs_impact_json', 'ownership_json',
+  'context_file', 'completion_commit', 'parent_id',
   'change_id',
   'created_at', 'updated_at',
 ]);
 
 const PATCHABLE_FIELDS = Object.freeze([
   'priority', 'complexity', 'estimated_days', 'deps', 'files_modified',
-  'session_id', 'stale', 'complexity_hint', 'tag', 'trace_to',
+  'session_id', 'stale', 'tag', 'trace_to',
+  'outcome', 'slice_kind', 'public_seam', 'verification_command',
+  'acceptance', 'context_refs', 'docs_impact', 'ownership',
   'context_file', 'completion_commit',
   'change_id',
 ]);
@@ -89,7 +93,7 @@ function withRetry(fn, { attempts = 10, baseMs = 50, capMs = 2000 } = {}) {
 }
 
 function tx(db, fn) {
-  return withRetry(() => db.transaction(fn)());
+  return withRetry(() => db.transaction(fn).immediate());
 }
 
 // ─── tasks ───────────────────────────────────────────────────────────────
@@ -97,17 +101,132 @@ function tx(db, fn) {
 function rowToTask(row) {
   if (!row) return null;
   const out = { ...row };
+  // Pre-13 databases may retain this retired Claude-specific column. It is
+  // intentionally ignored instead of leaking host/model assumptions into the
+  // current task contract or projections.
+  delete out.complexity_hint;
   for (const k of ['deps', 'files_modified']) {
     if (typeof out[k] === 'string') {
       try { out[k] = JSON.parse(out[k]); } catch { out[k] = null; }
     }
   }
+  const jsonFields = {
+    acceptance_json: ['acceptance', []],
+    context_refs_json: ['context_refs', []],
+    docs_impact_json: ['docs_impact', { status: 'unknown', files: [], rationale: null }],
+    ownership_json: ['ownership', {}],
+  };
+  for (const [column, [field, fallback]] of Object.entries(jsonFields)) {
+    try { out[field] = typeof out[column] === 'string' ? JSON.parse(out[column]) : fallback; }
+    catch { out[field] = fallback; }
+    delete out[column];
+  }
   if (out.stale !== undefined && out.stale !== null) {
     out.stale = Boolean(out.stale);
   }
   return out;
 }
 
+function normalizeObjectArray(value, field) {
+  if (!Array.isArray(value) || value.some((item) => !item || typeof item !== 'object' || Array.isArray(item))) {
+    throw new StateOpsError('VALIDATION_ERROR', `${field} must be an array of objects`);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeAcceptance(value) {
+  const items = normalizeObjectArray(value, 'acceptance');
+  const ids = new Set();
+  return items.map((item, index) => {
+    const id = String(item.id || '').trim();
+    const criterion = String(item.criterion || '').trim();
+    const verification = String(item.verification || '').trim();
+    if (!id || !criterion || !verification || ids.has(id)) {
+      throw new StateOpsError(
+        'VALIDATION_ERROR', `acceptance[${index}] requires a unique id, criterion, and verification`,
+      );
+    }
+    ids.add(id);
+    return { id, criterion, verification };
+  });
+}
+
+function normalizeContextRefs(value) {
+  return normalizeObjectArray(value, 'context_refs').map((item, index) => {
+    const ref = String(item.ref || '').trim();
+    const reason = String(item.reason || '').trim();
+    if (!ref || !reason) {
+      throw new StateOpsError('VALIDATION_ERROR', `context_refs[${index}] requires ref and reason`);
+    }
+    return {
+      ref, reason, kind: String(item.kind || 'source').trim(), required: item.required !== false,
+    };
+  });
+}
+
+function normalizeDocsImpact(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new StateOpsError('VALIDATION_ERROR', 'docs_impact must be an object');
+  }
+  const status = String(value.status || 'unknown').trim();
+  if (!['unknown', 'required', 'none'].includes(status)) {
+    throw new StateOpsError('VALIDATION_ERROR', 'docs_impact.status must be unknown, required, or none');
+  }
+  const files = value.files === undefined ? [] : value.files;
+  if (!Array.isArray(files) || files.some((item) => typeof item !== 'string' || !item.trim())) {
+    throw new StateOpsError('VALIDATION_ERROR', 'docs_impact.files must be an array of paths');
+  }
+  return {
+    status, files: files.map((item) => item.trim()),
+    rationale: value.rationale == null ? null : String(value.rationale).trim(),
+  };
+}
+
+function normalizeOwnership(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new StateOpsError('VALIDATION_ERROR', 'ownership must be an object');
+  }
+  const reviewers = value.reviewers === undefined ? [] : value.reviewers;
+  if (!Array.isArray(reviewers) || reviewers.some((item) => typeof item !== 'string' || !item.trim())) {
+    throw new StateOpsError('VALIDATION_ERROR', 'ownership.reviewers must be an array of names');
+  }
+  return {
+    owner: value.owner == null ? null : String(value.owner).trim(),
+    reviewers: reviewers.map((item) => item.trim()),
+  };
+}
+
+function taskContractBlockers(task) {
+  const blockers = [];
+  if (!String(task?.outcome || '').trim()) blockers.push('TASK_OUTCOME_MISSING');
+  if (!['tracer_bullet', 'expand_contract', 'integration_checkpoint'].includes(task?.slice_kind)) {
+    blockers.push('TASK_SLICE_KIND_MISSING');
+  }
+  if (!String(task?.public_seam || '').trim()) blockers.push('TASK_PUBLIC_SEAM_MISSING');
+  if (!String(task?.verification_command || '').trim()) blockers.push('TASK_VERIFICATION_COMMAND_MISSING');
+  if (!Array.isArray(task?.acceptance) || task.acceptance.length === 0) blockers.push('TASK_ACCEPTANCE_MISSING');
+  if (!Array.isArray(task?.context_refs) || task.context_refs.length === 0) blockers.push('TASK_CONTEXT_REFS_MISSING');
+  if (!String(task?.trace_to || '').trim()) blockers.push('TASK_TRACEABILITY_MISSING');
+  if (!task?.docs_impact || task.docs_impact.status === 'unknown') blockers.push('TASK_DOCS_IMPACT_UNRESOLVED');
+  else if (task.docs_impact.status === 'required' && task.docs_impact.files.length === 0) {
+    blockers.push('TASK_DOCS_FILES_MISSING');
+  } else if (!String(task.docs_impact.rationale || '').trim()) blockers.push('TASK_DOCS_RATIONALE_MISSING');
+  if (!String(task?.ownership?.owner || '').trim()) blockers.push('TASK_OWNER_MISSING');
+  return blockers;
+}
+
+function assertTaskExecutionContract(task) {
+  const blockers = taskContractBlockers(task);
+  if (blockers.length > 0) {
+    throw new StateOpsError(
+      'TASK_EXECUTION_CONTRACT_INCOMPLETE',
+      `task ${task?.id || '(unknown)'} execution contract is incomplete`,
+      { details: { blockers } },
+    );
+  }
+  return task;
+}
+
 function readTask(db, id) {
   const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
   return rowToTask(row);
@@ -116,13 +235,14 @@ function readTask(db, id) {
 // Single static SQL with named parameters and NULL-pass-through filters.
 // Every value flows through @bindings; the string is a frozen literal so no
 // concatenation / interpolation hooks can flag injection risk.
-const LIST_TASKS_SQL = "SELECT * FROM tasks WHERE (@status IS NULL OR status = @status) AND (@tag IS NULL OR tag = @tag) AND (@since IS NULL OR updated_at >= @since) ORDER BY created_at ASC LIMIT IIF(@maxn IS NULL, -1, @maxn)";
+const LIST_TASKS_SQL = "SELECT * FROM tasks WHERE (@status IS NULL OR status = @status) AND (@tag IS NULL OR tag = @tag) AND (@change_id IS NULL OR change_id = @change_id) AND (@since IS NULL OR updated_at >= @since) ORDER BY created_at ASC LIMIT IIF(@maxn IS NULL, -1, @maxn)";
 
 function listTasks(db, filter = {}) {
   const status = filter.status && filter.status !== 'any' ? filter.status : null;
   return db.prepare(LIST_TASKS_SQL).all({
     status,
     tag: filter.tag || null,
+    change_id: filter.change_id || null,
     since: filter.since || null,
     maxn: filter.limit || null,
   }).map(rowToTask);
@@ -203,9 +323,18 @@ function createTask(db, input) {
     files_modified: input.files_modified ? JSON.stringify(input.files_modified) : null,
     session_id: input.session_id ?? null,
     stale: 0,
-    complexity_hint: input.complexity_hint ?? null,
     tag: input.tag ?? derivedTag,
     trace_to: input.trace_to ?? null,
+    outcome: input.outcome ?? null,
+    slice_kind: input.slice_kind ?? null,
+    public_seam: input.public_seam ?? null,
+    verification_command: input.verification_command ?? null,
+    acceptance_json: JSON.stringify(input.acceptance === undefined ? [] : normalizeAcceptance(input.acceptance)),
+    context_refs_json: JSON.stringify(input.context_refs === undefined ? [] : normalizeContextRefs(input.context_refs)),
+    docs_impact_json: JSON.stringify(input.docs_impact === undefined
+      ? { status: 'unknown', files: [], rationale: null }
+      : normalizeDocsImpact(input.docs_impact)),
+    ownership_json: JSON.stringify(input.ownership === undefined ? {} : normalizeOwnership(input.ownership)),
     context_file: input.context_file ?? null,
     completion_commit: null,
     parent_id: input.parent_id ?? null,
@@ -271,6 +400,26 @@ function patchTask(db, id, patch = {}) {
         }
         value = value === null ? null : JSON.stringify(value);
       }
+      if (key === 'acceptance') {
+        sets.push('acceptance_json = ?');
+        params.push(JSON.stringify(normalizeAcceptance(value)));
+        continue;
+      }
+      if (key === 'context_refs') {
+        sets.push('context_refs_json = ?');
+        params.push(JSON.stringify(normalizeContextRefs(value)));
+        continue;
+      }
+      if (key === 'docs_impact') {
+        sets.push('docs_impact_json = ?');
+        params.push(JSON.stringify(normalizeDocsImpact(value)));
+        continue;
+      }
+      if (key === 'ownership') {
+        sets.push('ownership_json = ?');
+        params.push(JSON.stringify(normalizeOwnership(value)));
+        continue;
+      }
       if (key === 'stale') value = value ? 1 : 0;
       sets.push(`${key} = ?`);
       params.push(value);
@@ -709,11 +858,11 @@ function markTasksStaleBySpecSections(db, sections) {
 // shows up under a synthetic "unknown" runtime bucket. Writes go through
 // mcp-server/lib/telemetry.cjs — don't insert telemetry rows directly.
 
-const AGGREGATE_BY_RUNTIME_SQL = "SELECT COALESCE(s.runtime, 'unknown') AS runtime, COUNT(*) AS calls, COALESCE(SUM(t.tokens_input), 0) AS tokens_in, COALESCE(SUM(t.tokens_output), 0) AS tokens_out, COALESCE(SUM(t.cost_usd), 0.0) AS cost_usd FROM telemetry t LEFT JOIN sessions s ON t.session_id = s.sid WHERE (@since IS NULL OR t.ts >= @since) GROUP BY COALESCE(s.runtime, 'unknown') ORDER BY cost_usd DESC";
+const AGGREGATE_BY_RUNTIME_SQL = "SELECT COALESCE(s.runtime, 'unknown') AS runtime, COUNT(*) AS calls, COALESCE(SUM(t.tokens_input), 0) AS tokens_in, COALESCE(SUM(t.tokens_output), 0) AS tokens_out, COALESCE(SUM(t.cost_usd), 0.0) AS cost_usd, SUM(CASE WHEN t.event_type = 'token_usage' AND (COALESCE(t.tokens_input, 0) > 0 OR COALESCE(t.tokens_output, 0) > 0) AND t.cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced_usage_events, SUM(CASE WHEN t.event_type = 'token_usage' AND (COALESCE(t.tokens_input, 0) > 0 OR COALESCE(t.tokens_output, 0) > 0) AND t.cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS priced_usage_events FROM telemetry t LEFT JOIN sessions s ON t.session_id = s.sid WHERE (@since IS NULL OR t.ts >= @since) GROUP BY COALESCE(s.runtime, 'unknown') ORDER BY cost_usd DESC";
 
-const AGGREGATE_BY_TASK_SQL = "SELECT s.task_id AS task_id, COUNT(*) AS calls, COALESCE(SUM(t.tokens_input), 0) AS tokens_in, COALESCE(SUM(t.tokens_output), 0) AS tokens_out, COALESCE(SUM(t.cost_usd), 0.0) AS cost_usd FROM telemetry t JOIN sessions s ON t.session_id = s.sid WHERE s.task_id IS NOT NULL AND (@since IS NULL OR t.ts >= @since) GROUP BY s.task_id ORDER BY cost_usd DESC LIMIT @maxn";
+const AGGREGATE_BY_TASK_SQL = "SELECT s.task_id AS task_id, COUNT(*) AS calls, COALESCE(SUM(t.tokens_input), 0) AS tokens_in, COALESCE(SUM(t.tokens_output), 0) AS tokens_out, COALESCE(SUM(t.cost_usd), 0.0) AS cost_usd, SUM(CASE WHEN t.event_type = 'token_usage' AND (COALESCE(t.tokens_input, 0) > 0 OR COALESCE(t.tokens_output, 0) > 0) AND t.cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced_usage_events, SUM(CASE WHEN t.event_type = 'token_usage' AND (COALESCE(t.tokens_input, 0) > 0 OR COALESCE(t.tokens_output, 0) > 0) AND t.cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS priced_usage_events FROM telemetry t JOIN sessions s ON t.session_id = s.sid WHERE s.task_id IS NOT NULL AND (@since IS NULL OR t.ts >= @since) GROUP BY s.task_id ORDER BY cost_usd DESC LIMIT @maxn";
 
-const AGGREGATE_BY_SESSION_SQL = "SELECT @sid AS session_id, COUNT(*) AS tool_calls, COALESCE(SUM(tokens_input), 0) AS tokens_in, COALESCE(SUM(tokens_output), 0) AS tokens_out, COALESCE(SUM(cost_usd), 0.0) AS cost_usd FROM telemetry WHERE session_id = @sid";
+const AGGREGATE_BY_SESSION_SQL = "SELECT @sid AS session_id, COUNT(*) AS tool_calls, COALESCE(SUM(tokens_input), 0) AS tokens_in, COALESCE(SUM(tokens_output), 0) AS tokens_out, COALESCE(SUM(cost_usd), 0.0) AS cost_usd, SUM(CASE WHEN event_type = 'token_usage' AND (COALESCE(tokens_input, 0) > 0 OR COALESCE(tokens_output, 0) > 0) AND cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced_usage_events, SUM(CASE WHEN event_type = 'token_usage' AND (COALESCE(tokens_input, 0) > 0 OR COALESCE(tokens_output, 0) > 0) AND cost_usd IS NOT NULL THEN 1 ELSE 0 END) AS priced_usage_events FROM telemetry WHERE session_id = @sid";
 
 function aggregateTelemetryByRuntime(db, { since = null } = {}) {
   return db.prepare(AGGREGATE_BY_RUNTIME_SQL).all({ since });
@@ -765,6 +914,8 @@ module.exports = {
   StateOpsError,
   STATUS_TRANSITIONS,
   PATCHABLE_FIELDS,
+  taskContractBlockers,
+  assertTaskExecutionContract,
   SESSION_PATCHABLE,
   openStateDb,
   tx,