ultra-builder-pro-cli 0.8.1 → 0.10.0

package/hooks/workflow_resume.py

@@ -3,11 +3,14 @@
 
 import json
 import os
+import sqlite3
 import sys
 import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
+from context_spine import find_root, read_breadcrumb, render_breadcrumb
+
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
@@ -86,6 +89,24 @@ def main() -> None:
         print(f"[workflow_resume] invalid hook input: {exc}", file=sys.stderr)
         data = {}
     start = Path(data.get("cwd") or Path.cwd()).resolve()
+    root = find_root(start)
+    if root is not None:
+        try:
+            breadcrumb = read_breadcrumb(root)
+        except (sqlite3.Error, OSError) as exc:
+            print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)
+            breadcrumb = None
+        if breadcrumb:
+            text = render_breadcrumb(root, breadcrumb)
+            event = data.get("hook_event_name", "SessionStart")
+            if event == "SessionStart":
+                print(json.dumps({"hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": text,
+                }}))
+            else:
+                print(json.dumps({"additionalContext": text}))
+            return
     for root in (start, *start.parents):
         state_file = root / ".ultra" / "workflow-state.json"
         checkpoint_file = root / ".ultra" / "runtime" / "checkpoint.json"

package/mcp-server/lib/change-workflow.cjs

@@ -6,6 +6,8 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const ops = require('./state-ops.cjs');
+const contextSpine = require('./context-spine.cjs');
+const specLearning = require('./spec-learning.cjs');
 
 const CHANGE_ID = /^[a-zA-Z0-9_-]+$/;
 const PROVIDER_KINDS = new Set(['memory', 'code_graph']);
@@ -227,13 +229,16 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     ? change.provider_refs
     : normalizeProviderRefs(input.provider_refs);
   const tasks = db.prepare(
-    'SELECT id, title, status, priority, stale, trace_to, context_file FROM tasks WHERE change_id = ? ORDER BY created_at ASC',
+    `SELECT id, title, type, status, priority, complexity, stale, trace_to,
+            context_file, files_modified, session_id, created_at, updated_at
+     FROM tasks WHERE change_id = ? ORDER BY created_at ASC`,
   ).all(change.id).map((task) => ({ ...task, stale: Boolean(task.stale) }));
   const specs = Array.isArray(input.spec_refs) ? input.spec_refs : [];
   const allowedPaths = Array.isArray(input.allowed_paths) ? input.allowed_paths : [];
   const head = gitHead(rootDir);
+  const spine = contextSpine.compileRoleContext(db, { input, change, tasks, rootDir });
   const manifest = {
-    schema_version: '1.0',
+    schema_version: '2.0',
     generated_at: nowIso(),
     change: {
       id: change.id, title: change.title, kind: change.kind, status: change.status,
@@ -241,7 +246,15 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     },
     git: { head },
     tasks,
+    selected_task: spine.selected_task,
     specs,
+    role: spine.role,
+    gate: spine.gate,
+    next_action: spine.next_action,
+    readiness: spine.readiness,
+    context: spine.context,
+    execution_contract: spine.execution_contract,
+    resume: spine.resume,
     providers,
     provider_boundary: 'metadata references only; memory and code graph content remain external',
     tool_policy: { allowed_paths: allowedPaths },
@@ -257,15 +270,24 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
   ops.tx(db, () => {
     db.prepare(
       `INSERT INTO context_snapshots
-       (id, change_id, task_id, git_head, provider_refs_json, manifest_path, manifest_hash)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+       (id, change_id, task_id, git_head, provider_refs_json, manifest_path, manifest_hash,
+        role, gate, next_action, readiness, blockers_json, context_json,
+        token_estimate, token_budget)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       `ctx-${crypto.randomUUID().slice(0, 12)}`, change.id, input.task_id || null,
       head, JSON.stringify(providers), relative, hash,
+      spine.role, spine.gate, spine.next_action, spine.readiness.status,
+      JSON.stringify(spine.readiness.blockers), JSON.stringify(spine),
+      spine.context.token_estimate, spine.context.budget.max_tokens,
     );
     upsertArtifact(db, {
       change_id: change.id, task_id: input.task_id || null, kind: 'context_manifest',
-      artifactPath: relative, contentHash: hash, metadata: { git_head: head },
+      artifactPath: relative, contentHash: hash,
+      metadata: {
+        git_head: head, role: spine.role, gate: spine.gate,
+        readiness: spine.readiness.status, token_estimate: spine.context.token_estimate,
+      },
     });
     for (const task of tasks) {
       if (!task.trace_to) continue;
@@ -278,7 +300,11 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
       .run(JSON.stringify(providers), nowIso(), change.id);
     ops.appendEventInTx(db, {
       type: 'context_updated', change_id: change.id, task_id: input.task_id || null,
-      payload: { manifest_path: relative, manifest_hash: hash, git_head: head },
+      payload: {
+        manifest_path: relative, manifest_hash: hash, git_head: head,
+        role: spine.role, gate: spine.gate, readiness: spine.readiness.status,
+        next_action: spine.next_action,
+      },
     });
   });
   return { manifest, context_manifest_path: manifestPath, manifest_hash: hash };
@@ -438,16 +464,43 @@ function filesUnder(dir) {
   return out;
 }
 
-function evidenceBlockers(change, evidence) {
+function evidenceBlockers(change, evidence, tasks) {
   const blockers = [];
   const rows = Array.isArray(evidence) ? evidence : [];
   const byCategory = new Map(rows.map((row) => [row.category, row]));
-  for (const category of REQUIRED_EVIDENCE[change.kind]) {
+  for (const category of REQUIRED_EVIDENCE[change.kind].filter((value) => value !== 'review')) {
     const row = byCategory.get(category);
     if (!row) blockers.push(`EVIDENCE_MISSING:${category}`);
     else if (!['pass', 'not_applicable'].includes(row.status)) blockers.push(`EVIDENCE_FAILED:${category}`);
     else if (!row.evidence || String(row.evidence).trim().length < 3) blockers.push(`EVIDENCE_EMPTY:${category}`);
   }
+  if (['standard', 'major'].includes(change.kind)) {
+    const reviews = rows.filter((row) => row.category === 'review');
+    for (const axis of ['spec_fidelity', 'engineering_standards']) {
+      const row = reviews.find((candidate) => candidate.axis === axis);
+      if (!row) blockers.push(`REVIEW_AXIS_MISSING:${axis}`);
+      else if (row.status !== 'pass') blockers.push(`REVIEW_AXIS_FAILED:${axis}`);
+      else if (!row.evidence || String(row.evidence).trim().length < 3) {
+        blockers.push(`REVIEW_AXIS_EMPTY:${axis}`);
+      }
+    }
+  }
+  const tests = byCategory.get('tests');
+  if (tests && ['standard', 'major', 'incident'].includes(change.kind)
+    && (!tests.seam || String(tests.seam).trim().length < 3)) {
+    blockers.push('TEST_SEAM_MISSING');
+  }
+  if (tests && (change.kind === 'incident' || tasks.some((task) => task.type === 'bugfix'))) {
+    const signal = tests.signal;
+    if (!signal) blockers.push('TEST_RED_SIGNAL_MISSING');
+    else {
+      if (!signal.command || String(signal.command).trim().length < 3) blockers.push('TEST_SIGNAL_COMMAND_MISSING');
+      if (!signal.expected_red || String(signal.expected_red).trim().length < 3) blockers.push('TEST_EXPECTED_RED_MISSING');
+      if (signal.observed_red !== true) blockers.push('TEST_RED_NOT_OBSERVED');
+      if (signal.observed_green !== true) blockers.push('TEST_GREEN_NOT_OBSERVED');
+      if (signal.deterministic !== true) blockers.push('TEST_SIGNAL_NOT_DETERMINISTIC');
+    }
+  }
   return blockers;
 }
 
@@ -457,11 +510,31 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   if (!['active', 'blocked'].includes(change.status)) {
     throw new ChangeWorkflowError('CHANGE_NOT_CONVERGEABLE', `change ${input.id} is ${change.status}`);
   }
-  const blockers = new Set(evidenceBlockers(change, input.evidence));
-  const tasks = db.prepare('SELECT id, status, stale FROM tasks WHERE change_id = ? ORDER BY id').all(change.id);
+  const tasks = db.prepare('SELECT id, type, status, stale FROM tasks WHERE change_id = ? ORDER BY id').all(change.id);
+  const blockers = new Set(evidenceBlockers(change, input.evidence, tasks));
   if (tasks.length === 0) blockers.add('NO_TASKS');
   if (tasks.some((task) => !['completed', 'expanded'].includes(task.status))) blockers.add('TASKS_INCOMPLETE');
   if (tasks.some((task) => Boolean(task.stale))) blockers.add('TASK_CONTEXT_STALE');
+  for (const task of tasks) {
+    const snapshot = db.prepare(
+      `SELECT readiness, context_json FROM context_snapshots
+       WHERE change_id = ? AND task_id = ?
+       ORDER BY created_at DESC, rowid DESC LIMIT 1`,
+    ).get(change.id, task.id);
+    if (!snapshot) {
+      blockers.add(`TASK_CONTEXT_MISSING:${task.id}`);
+      continue;
+    }
+    const context = parseJson(snapshot.context_json, 'context_snapshots.context_json');
+    if (snapshot.readiness !== 'ready') blockers.add(`TASK_CONTEXT_NOT_READY:${task.id}`);
+    if (!context.execution_contract?.public_seam) blockers.add(`TASK_SEAM_MISSING:${task.id}`);
+    if (!context.execution_contract?.verification_command) blockers.add(`TASK_VERIFICATION_MISSING:${task.id}`);
+  }
+
+  for (const candidate of specLearning.listSpecLearning(db, change.id)) {
+    if (candidate.status === 'proposed') blockers.add(`SPEC_LEARNING_UNRESOLVED:${candidate.id}`);
+    if (candidate.status === 'approved') blockers.add(`SPEC_LEARNING_NOT_APPLIED:${candidate.id}`);
+  }
 
   if (change.docs_impact.status === 'unknown') blockers.add('DOCS_IMPACT_UNKNOWN');
   if (change.docs_impact.status === 'none' && (!change.docs_impact.rationale || change.docs_impact.rationale.length < 3)) {
@@ -513,7 +586,8 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   const lines = [
     `# Verification: ${change.title}`, '',
     ...input.evidence.flatMap((row) => [
-      `## ${row.category}`, '', `Status: **${row.status}**`, '', String(row.evidence).trim(), '',
+      `## ${row.category}${row.axis ? `:${row.axis}` : ''}`, '',
+      `Status: **${row.status}**`, '', String(row.evidence).trim(), '',
     ]),
   ];
   fs.writeFileSync(verificationPath, `${lines.join('\n')}\n`);
@@ -618,6 +692,10 @@ module.exports = {
   listChanges,
   updateChange,
   compileContext,
+  readBreadcrumb: contextSpine.readBreadcrumb,
+  proposeSpecLearning: specLearning.proposeSpecLearning,
+  resolveSpecLearning: specLearning.resolveSpecLearning,
+  listSpecLearning: specLearning.listSpecLearning,
   convergeChange,
   archiveChange,
   normalizeDocsImpact,

package/mcp-server/lib/change-workflow.test.cjs

@@ -31,10 +31,20 @@ function cleanup({ rootDir, db }) {
 function standardEvidence() {
   return [
     { category: 'diff', status: 'pass', evidence: 'git diff reviewed' },
-    { category: 'tests', status: 'pass', evidence: 'node --test passed' },
+    {
+      category: 'tests', status: 'pass', evidence: 'node --test passed',
+      seam: 'public change workflow contract',
+    },
     { category: 'spec', status: 'pass', evidence: 'delta reconciled' },
     { category: 'docs', status: 'pass', evidence: 'docs/feature.md updated' },
-    { category: 'review', status: 'pass', evidence: 'review findings resolved' },
+    {
+      category: 'review', axis: 'spec_fidelity', status: 'pass',
+      evidence: 'Acceptance behavior matches the approved delta.',
+    },
+    {
+      category: 'review', axis: 'engineering_standards', status: 'pass',
+      evidence: 'Engineering findings are resolved.',
+    },
   ];
 }
 
@@ -42,10 +52,43 @@ function incidentEvidence() {
   return [
     { category: 'diagnosis', status: 'pass', evidence: 'Structured diagnosis artifact reviewed.' },
     { category: 'diff', status: 'pass', evidence: 'Root-cause fix diff reviewed.' },
-    { category: 'tests', status: 'pass', evidence: 'Regression test reproduces then verifies the fix.' },
+    {
+      category: 'tests', status: 'pass', evidence: 'Regression test reproduces then verifies the fix.',
+      seam: 'projection recovery boundary',
+      signal: {
+        command: 'node --test recovery.test.cjs',
+        expected_red: 'stale projection remains running',
+        observed_red: true,
+        observed_green: true,
+        deterministic: true,
+        duration_ms: 25,
+      },
+    },
   ];
 }
 
+function executionContext(taskId, overrides = {}) {
+  return {
+    task_id: taskId,
+    role: 'implement',
+    gate: 'implementation',
+    next_action: `Implement and verify ${taskId}.`,
+    context_refs: [
+      {
+        ref: 'README.md', kind: 'spec', reason: 'Public behavior contract', required: true,
+      },
+    ],
+    budget: { max_tokens: 2_000, max_files: 4 },
+    execution_contract: {
+      slice_kind: 'tracer_bullet',
+      public_seam: `public seam for ${taskId}`,
+      verification_command: `node --test ${taskId}.test.cjs`,
+      context_budget_percent: 40,
+    },
+    ...overrides,
+  };
+}
+
 test('createChange persists a change and an inspectable external-provider context manifest', () => {
   const fx = fixture();
   try {
@@ -120,7 +163,9 @@ test('convergeChange blocks incomplete work and marks a fully evidenced standard
     });
     ops.updateTaskStatus(fx.db, 'change-task', 'in_progress');
     ops.updateTaskStatus(fx.db, 'change-task', 'completed');
-    changes.compileContext(fx.db, { id: 'chg-converge' }, { rootDir: fx.rootDir });
+    changes.compileContext(fx.db, {
+      id: 'chg-converge', ...executionContext('change-task'),
+    }, { rootDir: fx.rootDir });
 
     const ready = changes.convergeChange(fx.db, {
       id: 'chg-converge', evidence: standardEvidence(),
@@ -148,12 +193,20 @@ test('archiveChange moves a ready change into immutable history and records base
     });
     ops.updateTaskStatus(fx.db, 'archive-task', 'in_progress');
     ops.updateTaskStatus(fx.db, 'archive-task', 'completed');
-    changes.compileContext(fx.db, { id: 'chg-archive' }, { rootDir: fx.rootDir });
+    changes.compileContext(fx.db, {
+      id: 'chg-archive', ...executionContext('archive-task'),
+    }, { rootDir: fx.rootDir });
     const converged = changes.convergeChange(fx.db, {
       id: 'chg-archive',
       evidence: [
         { category: 'diff', status: 'pass', evidence: 'diff reviewed' },
-        { category: 'tests', status: 'pass', evidence: 'tests passed' },
+        {
+          category: 'tests', status: 'pass', evidence: 'tests passed', seam: 'archive command',
+          signal: {
+            command: 'node --test archive-task.test.cjs', expected_red: 'archive accepts stale context',
+            observed_red: true, observed_green: true, deterministic: true, duration_ms: 10,
+          },
+        },
         { category: 'spec', status: 'not_applicable', evidence: 'No behavior contract changed.' },
       ],
     }, { rootDir: fx.rootDir });
@@ -306,7 +359,9 @@ test('incident convergence requires every structured diagnosis section and refre
     });
     ops.updateTaskStatus(fx.db, 'incident-task', 'in_progress');
     ops.updateTaskStatus(fx.db, 'incident-task', 'completed');
-    changes.compileContext(fx.db, { id: 'chg-incident-converge' }, { rootDir: fx.rootDir });
+    changes.compileContext(fx.db, {
+      id: 'chg-incident-converge', ...executionContext('incident-task'),
+    }, { rootDir: fx.rootDir });
 
     const blocked = changes.convergeChange(fx.db, {
       id: 'chg-incident-converge', evidence: incidentEvidence(),
@@ -344,3 +399,143 @@ test('incident convergence requires every structured diagnosis section and refre
     cleanup(fx);
   }
 });
+
+test('compileContext v2 persists role-scoped context, budget, execution contract, and breadcrumb in state.db', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-context-v2', title: 'Compile role context', kind: 'standard',
+      intent: 'Give each execution role only the context it needs.',
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'context-v2-task', title: 'Build role-scoped manifest', type: 'feature', priority: 'P0',
+      change_id: 'chg-context-v2',
+    });
+
+    const compiled = changes.compileContext(fx.db, {
+      id: 'chg-context-v2',
+      ...executionContext('context-v2-task'),
+    }, { rootDir: fx.rootDir });
+
+    assert.equal(compiled.manifest.schema_version, '2.0');
+    assert.equal(compiled.manifest.role, 'implement');
+    assert.equal(compiled.manifest.gate, 'implementation');
+    assert.equal(compiled.manifest.readiness.status, 'ready');
+    assert.equal(compiled.manifest.context.items[0].ref, 'README.md');
+    assert.match(compiled.manifest.context.items[0].digest, /^[0-9a-f]{64}$/);
+    assert.equal(compiled.manifest.execution_contract.slice_kind, 'tracer_bullet');
+    assert.equal(compiled.manifest.resume.task_id, 'context-v2-task');
+    assert.match(compiled.manifest.next_action, /Implement and verify/);
+
+    const snapshot = fx.db.prepare(
+      'SELECT role, gate, next_action, readiness, context_json, token_budget FROM context_snapshots ORDER BY created_at DESC LIMIT 1',
+    ).get();
+    assert.equal(snapshot.role, 'implement');
+    assert.equal(snapshot.gate, 'implementation');
+    assert.equal(snapshot.readiness, 'ready');
+    assert.equal(snapshot.token_budget, 2_000);
+    assert.equal(JSON.parse(snapshot.context_json).execution_contract.public_seam, 'public seam for context-v2-task');
+
+    const breadcrumb = changes.readBreadcrumb(fx.db, { id: 'chg-context-v2' }, { rootDir: fx.rootDir });
+    assert.equal(breadcrumb.change_id, 'chg-context-v2');
+    assert.equal(breadcrumb.task_id, 'context-v2-task');
+    assert.equal(breadcrumb.role, 'implement');
+    assert.equal(breadcrumb.readiness, 'ready');
+    assert.match(breadcrumb.context_manifest_hash, /^[0-9a-f]{64}$/);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('compileContext blocks a required missing ref or an over-budget role packet', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-context-budget', title: 'Bound context packet', kind: 'quick',
+      intent: 'Fail closed when required context is missing or too large.',
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'budget-task', title: 'Compile bounded packet', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-context-budget',
+    });
+
+    const compiled = changes.compileContext(fx.db, {
+      id: 'chg-context-budget',
+      ...executionContext('budget-task', {
+        context_refs: [
+          { ref: 'missing-contract.md', kind: 'spec', reason: 'Required contract', required: true },
+          { ref: 'README.md', kind: 'source', reason: 'Current implementation', required: true },
+        ],
+        budget: { max_tokens: 1, max_files: 1 },
+      }),
+    }, { rootDir: fx.rootDir });
+
+    assert.equal(compiled.manifest.readiness.status, 'blocked');
+    assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_REQUIRED_REF_MISSING:missing-contract.md'));
+    assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_FILE_BUDGET_EXCEEDED'));
+    assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_TOKEN_BUDGET_EXCEEDED'));
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('spec-learning candidates are approval-gated and unresolved candidates block convergence', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-learning', title: 'Converge learned contract', kind: 'quick',
+      intent: 'Promote stable implementation discoveries into an approved baseline update.',
+      docs_impact: { status: 'none', files: [], rationale: 'Fixture exercises the approval state machine.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'learning-task', title: 'Capture stable contract', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-learning',
+    });
+    ops.updateTaskStatus(fx.db, 'learning-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'learning-task', 'completed');
+    changes.compileContext(fx.db, {
+      id: 'chg-learning', ...executionContext('learning-task'),
+    }, { rootDir: fx.rootDir });
+
+    const proposed = changes.proposeSpecLearning(fx.db, {
+      id: 'learning-1', change_id: 'chg-learning', task_id: 'learning-task',
+      target_ref: 'README.md#contract', summary: 'The public command fails closed on stale context.',
+      evidence: ['node --test learning-task.test.cjs'],
+    }, { rootDir: fx.rootDir });
+    assert.equal(proposed.status, 'proposed');
+
+    const blocked = changes.convergeChange(fx.db, {
+      id: 'chg-learning',
+      evidence: [
+        { category: 'diff', status: 'pass', evidence: 'diff reviewed' },
+        {
+          category: 'tests', status: 'pass', evidence: 'regression passed', seam: 'public command',
+          signal: {
+            command: 'node --test learning-task.test.cjs', expected_red: 'stale context accepted',
+            observed_red: true, observed_green: true, deterministic: true, duration_ms: 20,
+          },
+        },
+        { category: 'spec', status: 'pass', evidence: 'candidate recorded' },
+      ],
+    }, { rootDir: fx.rootDir });
+    assert.ok(blocked.blockers.includes('SPEC_LEARNING_UNRESOLVED:learning-1'));
+
+    assert.equal(changes.resolveSpecLearning(fx.db, {
+      change_id: 'chg-learning', candidate_id: 'learning-1', decision: 'approve',
+      resolution: 'Stable public contract.',
+    }, { rootDir: fx.rootDir }).status, 'approved');
+    assert.equal(changes.resolveSpecLearning(fx.db, {
+      change_id: 'chg-learning', candidate_id: 'learning-1', decision: 'apply',
+      resolution: 'Applied to README.md#contract.',
+    }, { rootDir: fx.rootDir }).status, 'applied');
+
+    const projection = JSON.parse(fs.readFileSync(
+      path.join(fx.rootDir, '.ultra', 'changes', 'active', 'chg-learning', 'spec-learning.json'),
+      'utf8',
+    ));
+    assert.equal(projection.source, '.ultra/state.db');
+    assert.equal(projection.candidates[0].status, 'applied');
+  } finally {
+    cleanup(fx);
+  }
+});