ultra-builder-pro-cli 0.14.0 → 0.15.0

package/mcp-server/lib/init-project.cjs

@@ -14,11 +14,12 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { initStateDb } = require('./state-db.cjs');
+const { EXPECTED_VERSION, initStateDb } = require('./state-db.cjs');
 const { assertStateAuthority, inspectProjection } = require('./state-authority.cjs');
 const baselines = require('./baseline-workflow.cjs');
 const runtimeState = require('./runtime-state.cjs');
 const ops = require('./state-ops.cjs');
+const workflows = require('./workflow-state.cjs');
 
 const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
@@ -137,13 +138,12 @@ const MANIFEST_NAMES = new Set([
   'pom.xml', 'build.gradle', 'build.gradle.kts', 'Gemfile', 'composer.json',
 ]);
 const SOURCE_EXTENSIONS = new Set([
-  '.c', '.cc', '.cpp', '.cs', '.go', '.java', '.js', '.jsx', '.kt', '.kts', '.mjs',
-  '.move', '.php', '.py', '.rb', '.rs', '.sol', '.swift', '.ts', '.tsx', '.vue',
+  '.astro', '.c', '.cc', '.cpp', '.cs', '.css', '.dart', '.ex', '.exs', '.fs', '.fsx',
+  '.go', '.graphql', '.gql', '.hcl', '.html', '.java', '.js', '.jsx', '.kt', '.kts',
+  '.less', '.lua', '.mjs', '.move', '.php', '.proto', '.py', '.r', '.R', '.rb', '.rs',
+  '.sass', '.scala', '.scss', '.sh', '.sol', '.svelte', '.swift', '.tf', '.ts', '.tsx',
+  '.vue',
 ]);
-const SOURCE_DIR_SEGMENTS = new Set([
-  'src', 'app', 'apps', 'lib', 'server', 'backend', 'frontend', 'api', 'cmd', 'internal',
-]);
-
 function scanRepositoryFiles(rootDir, { maxFiles = 5000, maxDepth = 8 } = {}) {
   const files = [];
   function walk(dir, depth) {
@@ -198,6 +198,122 @@ function packageProfile(rootDir) {
   }
 }
 
+const JAVASCRIPT_TECHNOLOGIES = Object.freeze([
+  { packages: ['next'], name: 'Next.js', capability: 'frontend' },
+  { packages: ['react'], name: 'React', capability: 'frontend' },
+  { packages: ['vue', 'nuxt'], name: 'Vue', capability: 'frontend' },
+  { packages: ['svelte', '@sveltejs/kit'], name: 'Svelte', capability: 'frontend' },
+  { packages: ['@angular/core'], name: 'Angular', capability: 'frontend' },
+  { packages: ['express'], name: 'Express', capability: 'backend' },
+  { packages: ['fastify'], name: 'Fastify', capability: 'backend' },
+  { packages: ['@nestjs/core'], name: 'NestJS', capability: 'backend' },
+  { packages: ['hono'], name: 'Hono', capability: 'backend' },
+  { packages: ['koa'], name: 'Koa', capability: 'backend' },
+  { packages: ['commander', 'yargs', 'oclif'], name: 'Node CLI', capability: 'cli' },
+  { packages: ['@prisma/client', 'prisma'], name: 'Prisma' },
+  { packages: ['typescript'], name: 'TypeScript' },
+  { packages: ['vitest'], name: 'Vitest' },
+  { packages: ['jest'], name: 'Jest' },
+  { packages: ['playwright', '@playwright/test'], name: 'Playwright' },
+]);
+
+function readTextBounded(file, maxBytes = 256 * 1024) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes) return '';
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function detectTechnologyProfile(rootDir, files) {
+  const technologies = new Set();
+  const capabilities = new Set();
+  const packageFiles = files.filter((file) => path.basename(file) === 'package.json').slice(0, 100);
+  for (const relative of packageFiles) {
+    let pkg;
+    try { pkg = JSON.parse(readTextBounded(path.join(rootDir, relative))); }
+    catch { continue; }
+    technologies.add('Node.js');
+    const dependencies = new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+    ]);
+    if (pkg.bin && (typeof pkg.bin === 'string' || typeof pkg.bin === 'object')) {
+      capabilities.add('cli');
+    }
+    for (const technology of JAVASCRIPT_TECHNOLOGIES) {
+      if (!technology.packages.some((name) => dependencies.has(name))) continue;
+      technologies.add(technology.name);
+      if (technology.capability) capabilities.add(technology.capability);
+    }
+  }
+
+  if (files.some((file) => file === 'tsconfig.json' || /\.(ts|tsx)$/.test(file))) {
+    technologies.add('TypeScript');
+  }
+  if (files.some((file) => /(^|\/)index\.html$/.test(file))) {
+    technologies.add('HTML');
+    capabilities.add('frontend');
+  }
+  if (files.some((file) => /\.(css|scss|sass|less)$/.test(file))) technologies.add('CSS');
+
+  const pythonFiles = files.filter((file) => (
+    ['pyproject.toml', 'requirements.txt'].includes(path.basename(file)) || file.endsWith('.py')
+  ));
+  if (pythonFiles.length > 0) {
+    technologies.add('Python');
+    const declarations = pythonFiles
+      .filter((file) => ['pyproject.toml', 'requirements.txt'].includes(path.basename(file)))
+      .map((file) => readTextBounded(path.join(rootDir, file)).toLowerCase())
+      .join('\n');
+    for (const [needle, label, capability] of [
+      ['fastapi', 'FastAPI', 'backend'], ['django', 'Django', 'backend'],
+      ['flask', 'Flask', 'backend'], ['typer', 'Typer', 'cli'], ['click', 'Click', 'cli'],
+      ['pytest', 'Pytest', null],
+    ]) {
+      if (!declarations.includes(needle)) continue;
+      technologies.add(label);
+      if (capability) capabilities.add(capability);
+    }
+  }
+  if (files.some((file) => ['go.mod', 'go.work'].includes(path.basename(file)) || file.endsWith('.go'))) {
+    technologies.add('Go');
+  }
+  if (files.some((file) => path.basename(file) === 'Cargo.toml' || file.endsWith('.rs'))) {
+    technologies.add('Rust');
+    const cargo = files.filter((file) => path.basename(file) === 'Cargo.toml')
+      .map((file) => readTextBounded(path.join(rootDir, file)).toLowerCase()).join('\n');
+    if (cargo.includes('clap')) {
+      technologies.add('Clap');
+      capabilities.add('cli');
+    }
+  }
+  if (files.some((file) => ['pom.xml', 'build.gradle', 'build.gradle.kts'].includes(path.basename(file)))) {
+    technologies.add('JVM');
+  }
+  if (files.some((file) => path.basename(file) === 'Gemfile' || file.endsWith('.rb'))) {
+    technologies.add('Ruby');
+  }
+  if (files.some((file) => path.basename(file) === 'composer.json' || file.endsWith('.php'))) {
+    technologies.add('PHP');
+  }
+
+  let projectType = 'other';
+  if (capabilities.has('frontend') && capabilities.has('backend')) projectType = 'fullstack';
+  else if (capabilities.has('frontend')) projectType = 'web';
+  else if (capabilities.has('backend')) projectType = 'api';
+  else if (capabilities.has('cli')) projectType = 'cli';
+  return {
+    detected_project_type: projectType,
+    detected_stack: technologies.size > 0 ? [...technologies].join(', ') : null,
+    technology_signals: [...technologies],
+    capability_signals: [...capabilities].sort(),
+  };
+}
+
 function classifyRepository(absTarget) {
   const { files, truncated } = scanRepositoryFiles(absTarget);
   const packageData = packageProfile(absTarget);
@@ -220,12 +336,10 @@ function classifyRepository(absTarget) {
   }).slice(0, 100);
   const sourceSignals = files.filter((file) => {
     const lower = file.toLowerCase();
-    if (testSignals.includes(file) || lower.endsWith('.config.js') || lower.endsWith('.config.ts')) return false;
-    const segments = file.split('/');
+    if (testSignals.includes(file) || /(^|\/)[^/]+\.config\.(c|m)?(j|t)s$/.test(lower)) return false;
     const ext = path.extname(file);
     if (!SOURCE_EXTENSIONS.has(ext)) return false;
-    return segments.some((segment) => SOURCE_DIR_SEGMENTS.has(segment))
-      || /(^|\/)(main|index|server|app)\.[^.]+$/.test(lower);
+    return true;
   }).slice(0, 200);
   const workspaceRoots = [...new Set(packageData.workspacePatterns
     .flatMap((pattern) => expandWorkspacePattern(absTarget, pattern)))]
@@ -247,12 +361,15 @@ function classifyRepository(absTarget) {
   if (deploymentSignals.length > 0) reasons.push('DEPLOYMENT_PRESENT');
   if (databaseSignals.length > 0) reasons.push('PERSISTED_STATE_PRESENT');
   if (workspaceMarkers.length > 0 || workspaceRoots.length > 0) reasons.push('MONOREPO_PRESENT');
+  if (truncated) reasons.push('SCAN_TRUNCATED');
   if (reasons.length === 0) reasons.push('SKELETON_ONLY');
   const mode = sourceSignals.length > 0 || testSignals.length > 0
-    || deploymentSignals.length > 0 || databaseSignals.length > 0
+    || deploymentSignals.length > 0 || databaseSignals.length > 0 || truncated
     ? 'brownfield' : 'greenfield';
+  const technologyProfile = detectTechnologyProfile(absTarget, files);
   return {
     mode,
+    ...technologyProfile,
     reasons,
     repository_kind: workspaceMarkers.length > 0 || workspaceRoots.length > 0 ? 'monorepo' : 'single',
     workspace_markers: workspaceMarkers,
@@ -290,7 +407,7 @@ function rollbackInitialization(ultraDir, backupPath) {
 }
 
 function projectionMigrationError(projection) {
-  const targets = { '4.4': '4.5', '4.5': '12.0' };
+  const targets = { '4.4': '4.5', '4.5': EXPECTED_VERSION };
   const target = targets[projection.version];
   if (target) {
     return new InitProjectError(
@@ -307,6 +424,67 @@ function projectionMigrationError(projection) {
   );
 }
 
+function ensureInitializationWorkflows(db, baseline, { rootDir }) {
+  let initRun = workflows.listWorkflows(
+    db, { kind: 'init', baseline_id: baseline.id, limit: 1 }, { rootDir },
+  )[0];
+  let researchRun = workflows.listWorkflows(
+    db, { kind: 'research', baseline_id: baseline.id, limit: 1 }, { rootDir },
+  )[0];
+  if (baseline.status === 'ready') {
+    const compatibilityOnly = baseline.mode === 'migrated';
+    const provenanceComplete = !compatibilityOnly
+      && initRun?.status === 'completed'
+      && researchRun?.status === 'completed'
+      && baseline.research_run_id === researchRun.id;
+    return {
+      init_id: initRun?.id || null,
+      init_status: initRun?.status || 'missing',
+      research_id: researchRun?.id || null,
+      research_mode: researchRun?.mode || null,
+      research_status: compatibilityOnly
+        ? 'not_required' : (researchRun?.status || 'missing'),
+      provenance_status: compatibilityOnly
+        ? 'compatibility_only' : (provenanceComplete ? 'complete' : 'incomplete'),
+      next_action: compatibilityOnly
+        ? 'ultra-init' : (provenanceComplete ? 'ultra-change' : 'ultra-doctor'),
+    };
+  }
+  if (!initRun) {
+    initRun = workflows.startWorkflow(db, {
+      kind: 'init', baseline_id: baseline.id,
+      subject: `Establish the ${baseline.mode} baseline for ${baseline.project_name}.`,
+      metadata: { repository_revision: baseline.repository_revision, scope: baseline.scope },
+    }, { rootDir });
+    for (const stepId of ['inspect-authority', 'classify-repository', 'scaffold-authority']) {
+      initRun = workflows.recordWorkflowStep(db, {
+        id: initRun.id, step_id: stepId, status: 'completed',
+      }, { rootDir });
+    }
+  }
+
+  if (baseline.mode !== 'migrated') {
+    if (!researchRun) {
+      const researchMode = baseline.mode === 'brownfield' ? 'adoption' : 'full';
+      researchRun = workflows.startWorkflow(db, {
+        kind: 'research', mode: researchMode, baseline_id: baseline.id,
+        subject: baseline.mode === 'brownfield'
+          ? 'Adopt the existing system as an evidence-backed product and architecture baseline.'
+          : 'Validate the complete product and architecture baseline before planning.',
+      }, { rootDir });
+    }
+  }
+  return {
+    init_id: initRun.id,
+    init_status: initRun.status,
+    research_id: researchRun?.id || null,
+    research_mode: researchRun?.mode || null,
+    research_status: researchRun?.status || 'not_started',
+    provenance_status: 'in_progress',
+    next_action: baseline.mode === 'migrated' ? 'ultra-init' : 'ultra-research',
+  };
+}
+
 function resumeProject({
   absTarget, ultraDir, source, project_name, project_type, stack, resolvedMode,
   scope, repositoryProfile, projection,
@@ -316,6 +494,7 @@ function resumeProject({
   let initialized;
   let copiedFiles = [];
   let baselineResult;
+  let workflowResult;
   try {
     initialized = initStateDb(stateDbPath);
     const { db } = initialized;
@@ -331,6 +510,7 @@ function resumeProject({
         classification: repositoryProfile,
       }, { rootDir: absTarget });
     }
+    workflowResult = ensureInitializationWorkflows(db, baselineResult, { rootDir: absTarget });
     ops.appendEvent(db, {
       type: 'project_resumed',
       payload: {
@@ -367,16 +547,19 @@ function resumeProject({
     created_path: ultraDir,
     state_db_path: stateDbPath,
     status: 'resumed',
-    mode: resolvedMode,
+    mode: baselineResult.mode,
     baseline: {
       id: baselineResult.id,
       mode: baselineResult.mode,
       status: baselineResult.status,
+      project_type: baselineResult.project_type,
+      stack: baselineResult.stack,
       repository_revision: baselineResult.repository_revision,
       scope: baselineResult.scope,
     },
     copied_files: copiedFiles,
     repository_profile: repositoryProfile,
+    workflow: workflowResult,
   };
   if (initialized.backup_path) result.migration_backup_path = initialized.backup_path;
   return result;
@@ -404,8 +587,12 @@ function initProject({
   ensureTargetDir(absTarget);
   const repositoryProfile = classifyRepository(absTarget);
   const resolvedMode = mode === 'auto' ? repositoryProfile.mode : detectProjectMode(absTarget, mode);
+  const resolvedProjectType = project_type || repositoryProfile.detected_project_type;
+  const resolvedStack = stack || repositoryProfile.detected_stack || undefined;
   repositoryProfile.detected_mode = repositoryProfile.mode;
   repositoryProfile.mode = resolvedMode;
+  repositoryProfile.selected_project_type = resolvedProjectType;
+  repositoryProfile.selected_stack = resolvedStack || null;
   const source = ensureTemplate(source_template);
   const ultraDir = path.join(absTarget, '.ultra');
 
@@ -422,7 +609,8 @@ function initProject({
       throw projectionMigrationError(projection);
     }
     return resumeProject({
-      absTarget, ultraDir, source, project_name, project_type, stack, resolvedMode,
+      absTarget, ultraDir, source, project_name, project_type: resolvedProjectType,
+      stack: resolvedStack, resolvedMode,
       scope, repositoryProfile, projection,
     });
   }
@@ -441,6 +629,7 @@ function initProject({
 
   let copiedFiles;
   let baselineResult;
+  let workflowResult;
   try {
     fs.mkdirSync(ultraDir, { recursive: true });
     copiedFiles = copyTemplate(source, ultraDir);
@@ -449,11 +638,13 @@ function initProject({
     const { db } = initStateDb(stateDbPath);
     try {
       baselineResult = baselines.startBaseline(db, {
-        id: 'project-baseline', project_name, project_type, stack,
+        id: 'project-baseline', project_name, project_type: resolvedProjectType,
+        stack: resolvedStack,
         mode: resolvedMode, repository_revision: baselines.gitHead(absTarget),
         scope: scope === undefined ? ['.'] : scope,
         classification: repositoryProfile,
       }, { rootDir: absTarget });
+      workflowResult = ensureInitializationWorkflows(db, baselineResult, { rootDir: absTarget });
       ops.appendEvent(db, {
         type: 'project_initialized',
         payload: {
@@ -491,11 +682,14 @@ function initProject({
       id: baselineResult.id,
       mode: baselineResult.mode,
       status: baselineResult.status,
+      project_type: baselineResult.project_type,
+      stack: baselineResult.stack,
       repository_revision: baselineResult.repository_revision,
       scope: baselineResult.scope,
     },
     copied_files: copiedFiles,
     repository_profile: repositoryProfile,
+    workflow: workflowResult,
   };
   if (backupPath) result.backup_path = backupPath;
   return result;

package/mcp-server/lib/plan-store.cjs

@@ -18,8 +18,11 @@ function renderPlanMd(plan) {
   const lines = [];
   lines.push('# Execution Plan');
   lines.push('');
+  if (plan.change_id) lines.push(`- Change: ${plan.change_id}`);
   lines.push(`- Waves: ${plan.waves.length}`);
-  lines.push(`- Estimated cost: $${plan.estimated_cost_usd}`);
+  lines.push(plan.estimated_cost_usd === null
+    ? '- Estimated cost: unavailable (exact runtime model was not recorded)'
+    : `- Estimated cost: $${plan.estimated_cost_usd}`);
   lines.push(`- Estimated duration: ${plan.estimated_duration_min} min`);
   if (plan.conflict_surface.length > 0) {
     lines.push(`- Conflicts: ${plan.conflict_surface.length}`);

package/mcp-server/lib/pricing.cjs

@@ -10,31 +10,28 @@
 //   Claude:  https://www.anthropic.com/pricing
 //   OpenAI:  https://platform.openai.com/docs/pricing
 //
-// `default` inside each runtime is the fallback when a session did not
-// record which specific model it used.
+// Pricing is exact-model only. A runtime label is not a billable model and
+// host applications can route the same runtime through different providers.
+// Missing or unknown models therefore return null instead of a fabricated
+// estimate.
 
 const PRICING = Object.freeze({
   claude: Object.freeze({
     'claude-opus-4-7':      { input: 15e-6, output: 75e-6 },
     'claude-sonnet-4-6':    { input: 3e-6,  output: 15e-6 },
     'claude-haiku-4-5':     { input: 0.8e-6, output: 4e-6 },
-    default:                { input: 3e-6,  output: 15e-6 }, // assume sonnet
   }),
   codex: Object.freeze({
     'gpt-5.4':              { input: 2e-6,  output: 10e-6 },
-    default:                { input: 2e-6,  output: 10e-6 },
-  }),
-  opencode: Object.freeze({
-    // OpenCode is a frontend over whichever model the user configured;
-    // treat as sonnet-equivalent unless a model name is passed in.
-    default:                { input: 3e-6,  output: 15e-6 },
   }),
+  opencode: Object.freeze({}),
+  kimi: Object.freeze({}),
 });
 
 function computeCost(runtime, model, tokens_input, tokens_output) {
   const r = PRICING[runtime];
   if (!r) return null;
-  const p = (model && r[model]) || r.default;
+  const p = model ? r[model] : null;
   if (!p) return null;
   const ti = Number(tokens_input) || 0;
   const to = Number(tokens_output) || 0;

package/mcp-server/lib/project-breadcrumb.cjs

@@ -120,6 +120,12 @@ function renderProjectBreadcrumb(rootDir, breadcrumb) {
   if (Array.isArray(breadcrumb.warnings) && breadcrumb.warnings.length > 0) {
     lines.push(`Warnings: ${breadcrumb.warnings.join(', ')}`);
   }
+  if (breadcrumb.workflow) {
+    lines.push(
+      `Workflow: ${breadcrumb.workflow.id} (${breadcrumb.workflow.kind}/${breadcrumb.workflow.status})`,
+      `Step: ${breadcrumb.workflow.current_step || 'finalize'}`,
+    );
+  }
   lines.push(
     `Next: ${breadcrumb.next_action || 'Inspect Ultra status.'}`,
     `Route: ${breadcrumb.recommended_workflow || 'ultra-doctor'}`,

package/mcp-server/lib/projector.cjs

@@ -16,8 +16,11 @@ const SCHEMA_VERSION = '4.5';
 const SOURCE_TAG = '.ultra/state.db';
 
 // Frozen SELECTs — values bind through @placeholders.
-const LIST_TASKS_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks ORDER BY created_at ASC";
-const READ_TASK_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks WHERE id = @id";
+const TASK_PROJECTION_COLUMNS = 'id, title, type, priority, complexity, estimated_days, status, 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, created_at, updated_at';
+const LIST_TASKS_FOR_PROJECTION_SQL = `SELECT ${TASK_PROJECTION_COLUMNS} FROM tasks ORDER BY created_at ASC`;
+const READ_TASK_FOR_PROJECTION_SQL = `SELECT ${TASK_PROJECTION_COLUMNS} FROM tasks WHERE id = @id`;
+const CONTRACT_START = '<!-- ultra:task-contract:start -->';
+const CONTRACT_END = '<!-- ultra:task-contract:end -->';
 
 function rowToProjection(row) {
   if (!row) return null;
@@ -28,6 +31,17 @@ function rowToProjection(row) {
     }
     if (out[k] === null || out[k] === undefined) delete out[k];
   }
+  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);
   for (const k of Object.keys(out)) {
     if (out[k] === null || out[k] === undefined) delete out[k];
@@ -94,17 +108,57 @@ function buildContextDoc(taskRow, existingBody) {
   body = body.replace(/^>\s*\*\*Status\*\*:.*(?:\r?\n|$)(?:\r?\n)?/mi, '');
   // Strip any previous STALE banner so re-projection after reset is clean.
   body = body.replace(/^> ⚠️\s*STALE[^\n]*\n(?:>[^\n]*\n)*\n?/m, '');
+  body = body.replace(
+    new RegExp(`${CONTRACT_START}[\\s\\S]*?${CONTRACT_END}\\n*`, 'm'),
+    '',
+  );
   if (taskRow.stale) {
     const banner = [
       `> ⚠️ STALE since ${taskRow.updated_at || new Date().toISOString()}`,
-      '> spec 改动可能让此 task 上下文失效；重新跑 spec 对齐后再继续。',
+      '> Specification evidence may have changed. Recompile the task context before continuing.',
       '',
     ].join('\n');
     body = banner + body;
   }
+  body = buildTaskContract(taskRow) + body;
   return headerLines.join('\n') + body;
 }
 
+function buildTaskContract(task) {
+  const acceptance = Array.isArray(task.acceptance) ? task.acceptance : [];
+  const refs = Array.isArray(task.context_refs) ? task.context_refs : [];
+  const docs = task.docs_impact || { status: 'unknown', files: [], rationale: null };
+  const ownership = task.ownership || {};
+  const lines = [
+    CONTRACT_START,
+    '## Execution Contract (generated from state.db)',
+    '',
+    `- Outcome: ${task.outcome || 'unresolved'}`,
+    `- Slice: ${task.slice_kind || 'unresolved'}`,
+    `- Public seam: ${task.public_seam || 'unresolved'}`,
+    `- Verification: ${task.verification_command || 'unresolved'}`,
+    `- Trace: ${task.trace_to || 'unresolved'}`,
+    `- Owner: ${ownership.owner || 'unresolved'}`,
+    `- Documentation: ${docs.status || 'unknown'}${docs.rationale ? ` — ${docs.rationale}` : ''}`,
+    '',
+    '### Acceptance',
+    '',
+    ...(acceptance.length > 0
+      ? acceptance.map((item) => `- ${item.id}: ${item.criterion} — verify with \`${item.verification}\``)
+      : ['- unresolved']),
+    '',
+    '### Context References',
+    '',
+    ...(refs.length > 0
+      ? refs.map((item) => `- \`${item.ref}\` — ${item.reason}`)
+      : ['- unresolved']),
+    '',
+    CONTRACT_END,
+    '',
+  ];
+  return lines.join('\n');
+}
+
 function escapeYaml(str) {
   if (str == null) return '';
   if (/[:#\[\]\{\}&\*!|>'"%@`]/.test(str) || /^\s|\s$/.test(str)) {

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, {