@michaelxwb/code-flow 0.6.2 → 0.6.4

package/src/cli.js

@@ -10,7 +10,7 @@ const pkg = require('../package.json');
 const specWorkflowMigration = require('./migrate/spec-workflow');
 
 const usage = [
-  'Usage: code-flow init [--force] [--platform=<claude|codex|costrict|opencode>]',
+  'Usage: code-flow init [--force] [--platform=<claude|codex|costrict|opencode>] [--backup-dir=<path>]',
   '       code-flow migrate --spec-workflow <--dry-run|--prepare|--apply --plan <path>|--rollback <id>>',
   '       code-flow -v | --version',
   '       code-flow -h | --help'
@@ -83,6 +83,43 @@ function compareVersions(a, b) {
   return 0;
 }
 
+function modeFor(installed, force) {
+  if (force) return 'force';
+  if (!installed) return 'fresh';
+  if (compareVersions(installed, pkg.version) < 0) return 'upgrade';
+  return 'current';
+}
+
+// Per-platform install records live beside the legacy global .version so one
+// platform's upgrade never masks another platform's staleness.
+function readAdapterVersions(cwd) {
+  const file = path.join(cwd, '.code-flow', '.adapter-versions.json');
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (data && typeof data === 'object' && data.adapters && typeof data.adapters === 'object') {
+      return { core: typeof data.core === 'string' ? data.core : null, adapters: data.adapters };
+    }
+  } catch (_) { /* missing or corrupt: fall through */ }
+  return { core: null, adapters: {} };
+}
+
+function writeAdapterVersions(cwd, versions) {
+  const file = path.join(cwd, '.code-flow', '.adapter-versions.json');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ core: versions.core, adapters: versions.adapters }, null, 2) + '\n');
+}
+
+// Marker dirs proving a platform was installed before per-platform tracking.
+function platformFilesExist(cwd, platform) {
+  const markers = {
+    claude: ['.claude/commands'],
+    codex: ['.agents/skills'],
+    costrict: ['.costrict/commands'],
+    opencode: ['.opencode/commands'],
+  };
+  return (markers[platform] || []).some(rel => fs.existsSync(path.join(cwd, rel)));
+}
+
 // --- Merge functions ---
 
 // Replace fenced code blocks with same-length whitespace so byte offsets in
@@ -200,6 +237,56 @@ function mergeSettingsJson(srcFile, destFile) {
   return added;
 }
 
+// OpenCode v2 merge: migrate the v1 `plugin` key to `plugins`, drop the
+// auto-discovered local path (`.opencode/plugins/*` loads without config),
+// and union template `plugins` entries without overwriting user content.
+function mergeOpencodeJson(srcFile, destFile) {
+  const src = JSON.parse(fs.readFileSync(srcFile, 'utf8'));
+  const dest = JSON.parse(fs.readFileSync(destFile, 'utf8'));
+  const added = [];
+  const isLocalEntry = (e) => {
+    const p = typeof e === 'string' ? e : (e && e.package);
+    return typeof p === 'string' && /(^|\/)\.opencode\/plugins\//.test(p);
+  };
+  if (Array.isArray(dest.plugin)) {
+    const carried = dest.plugin.filter((e) => !isLocalEntry(e));
+    delete dest.plugin;
+    added.push(`removed legacy 'plugin' key (v1 → v2)`);
+    if (carried.length > 0 && !Array.isArray(dest.plugins)) dest.plugins = carried;
+  } else if ('plugin' in dest) {
+    delete dest.plugin;
+    added.push(`removed legacy 'plugin' key (v1 → v2)`);
+  }
+  if (Array.isArray(dest.plugins)) {
+    const before = dest.plugins.length;
+    dest.plugins = dest.plugins.filter((e) => !isLocalEntry(e));
+    if (dest.plugins.length !== before) added.push('removed auto-discovered local plugin entry');
+  }
+  if (Array.isArray(src.plugins)) {
+    if (!Array.isArray(dest.plugins)) dest.plugins = [];
+    const seen = new Set(dest.plugins.map((e) => JSON.stringify(e)));
+    for (const entry of src.plugins) {
+      const key = JSON.stringify(entry);
+      if (!seen.has(key)) {
+        dest.plugins.push(entry);
+        seen.add(key);
+        added.push(`plugins +${typeof entry === 'string' ? entry : key}`.slice(0, 80));
+      }
+    }
+  }
+  for (const key of Object.keys(src)) {
+    if (key === 'plugins' || key === 'plugin') continue;
+    if (!(key in dest)) {
+      dest[key] = src[key];
+      added.push(key);
+    }
+  }
+  if (added.length > 0) {
+    fs.writeFileSync(destFile, JSON.stringify(dest, null, 2) + '\n');
+  }
+  return added;
+}
+
 function mergeConfigYml(srcFile, destFile) {
   const srcText = fs.readFileSync(srcFile, 'utf8');
   const destText = fs.readFileSync(destFile, 'utf8');
@@ -342,6 +429,53 @@ function copyFileIfMissing(srcFile, destFile) {
   fs.copyFileSync(srcFile, destFile);
 }
 
+function removeLegacyClaudeSkills(cwd, removed, opts) {
+  // 0.1-era code-flow deployed its own skills (cf-*.md) under .claude/skills/.
+  // Only those historically managed names may be touched; everything else is
+  // user-owned and must survive init. Managed entries are backed up before
+  // removal. The legacy dir belongs to the claude domain: other platforms
+  // must never touch it.
+  const options = opts || {};
+  if (options.platform && options.platform !== 'claude') return;
+  const legacySkills = path.join(cwd, '.claude', 'skills');
+  if (!fs.existsSync(legacySkills)) return;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(legacySkills, { withFileTypes: true });
+  } catch (error) {
+    const code = error && error.code ? ` (${error.code})` : '';
+    process.stderr.write(`Warning: failed to list deprecated .claude/skills/${code}; left untouched. Remove it manually.\n`);
+    return;
+  }
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupRoot = options.backupDir
+    ? path.resolve(cwd, options.backupDir)
+    : path.join(cwd, '.code-flow', 'backups', stamp);
+  for (const entry of entries) {
+    if (!MANAGED_LEGACY_SKILL_NAMES.has(entry.name)) continue; // user-owned: keep
+    const src = path.join(legacySkills, entry.name);
+    const rel = path.join('.claude', 'skills', entry.name);
+    try {
+      const dest = path.join(backupRoot, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      if (entry.isDirectory()) {
+        copyDirRecursive(src, dest, true);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(src, dest);
+      } else {
+        continue;
+      }
+      fs.rmSync(src, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+      removed.push(`${rel} (backup: ${path.relative(cwd, dest)})`);
+    } catch (error) {
+      const code = error && error.code ? ` (${error.code})` : '';
+      const message = error && error.message ? error.message : String(error);
+      process.stderr.write(`Warning: failed to migrate deprecated ${rel}${code}: ${message}\n`);
+    }
+  }
+}
+
 // Files renamed in 0.x → 1.x that may linger in upgraded projects.
 // Each entry: { path: relative-to-cwd, replacedBy: hint string for the warning }.
 const ORPHAN_FILES = [
@@ -367,35 +501,30 @@ function removeOrphanFiles(cwd, removed) {
   }
 }
 
-function removeLegacyClaudeSkills(cwd, removed) {
-  const legacySkills = path.join(cwd, '.claude', 'skills');
-  if (!fs.existsSync(legacySkills)) return;
-
-  try {
-    fs.rmSync(legacySkills, {
-      recursive: true,
-      force: true,
-      maxRetries: 5,
-      retryDelay: 100
-    });
-    if (!fs.existsSync(legacySkills)) {
-      removed.push('.claude/skills/');
-      return;
-    }
-  } catch (error) {
-    const code = error && error.code ? ` (${error.code})` : '';
-    const message = error && error.message ? error.message : String(error);
-    process.stderr.write(`Warning: failed to remove deprecated .claude/skills/${code}: ${message}\n`);
-    return;
-  }
-
-  process.stderr.write('Warning: failed to remove deprecated .claude/skills/. Remove it manually.\n');
-}
+// Skill entries historically deployed by code-flow 0.x under .claude/skills/.
+// Only these names are managed legacy content; any other entry is user-owned.
+const MANAGED_LEGACY_SKILL_NAMES = new Set([
+  'cf-init.md',
+  'cf-inject.md',
+  'cf-learn.md',
+  'cf-scan.md',
+  'cf-stats.md',
+  'cf-validate.md',
+]);
 
 // --- pyyaml dependency: probe first, fall back through PEP 668 strategies ---
 
-function ensurePyYaml() {
-  const probe = spawnSync('python3', ['-c', 'import yaml'], { stdio: 'ignore' });
+// --- pyyaml dependency: probe first, fall back through PEP 668 strategies ---
+// Bounded waits: each attempt carries its own timeout inside a total budget,
+// with progress on stderr. spawnFn/logFn/nowFn are injectable for tests.
+const PIP_PER_ATTEMPT_MS = 60000;
+const PIP_TOTAL_MS = 120000;
+
+function ensurePyYaml(spawnFn, logFn, nowFn) {
+  const spawn = spawnFn || spawnSync;
+  const log = logFn || ((message) => process.stderr.write(message));
+  const now = nowFn || Date.now;
+  const probe = spawn('python3', ['-c', 'import yaml'], { stdio: 'ignore' });
   if (!probe.error && probe.status === 0) return; // already installed
 
   const attempts = [
@@ -403,11 +532,18 @@ function ensurePyYaml() {
     ['-m', 'pip', 'install', 'pyyaml'],
     ['-m', 'pip', 'install', '--user', '--break-system-packages', 'pyyaml'],
   ];
-  for (const args of attempts) {
-    const result = spawnSync('python3', args, { stdio: 'ignore' });
+  const started = now();
+  for (let i = 0; i < attempts.length; i++) {
+    const remaining = PIP_TOTAL_MS - (now() - started);
+    if (remaining <= 0) break;
+    log(`Installing pyyaml (attempt ${i + 1}/${attempts.length})...\n`);
+    const result = spawn('python3', attempts[i], {
+      stdio: 'ignore',
+      timeout: Math.min(PIP_PER_ATTEMPT_MS, remaining),
+    });
     if (!result.error && result.status === 0) return;
   }
-  process.stderr.write(
+  log(
     'Warning: pyyaml install failed. Run manually:\n' +
     '  python3 -m pip install --user pyyaml\n' +
     '  # or, on PEP 668 systems:\n' +
@@ -468,10 +604,21 @@ function parsePlatform(args) {
   return null;
 }
 
+function parseStringFlag(args, name) {
+  const prefix = `--${name}=`;
+  for (const arg of args) {
+    if (arg.startsWith(prefix)) return arg.slice(prefix.length);
+  }
+  const idx = args.indexOf(`--${name}`);
+  if (idx !== -1) return args[idx + 1] || '';
+  return '';
+}
+
 // --- Main init ---
 
-function runInit(force, platform) {
+function runInit(force, platform, opts) {
   const cwd = process.cwd();
+  const options = opts || {};
   const installedVersion = readInstalledVersion(cwd);
   if (installedVersion && compareVersions(installedVersion, '0.4.2') >= 0 && compareVersions(installedVersion, '0.6.0') < 0) {
     process.stdout.write(`${JSON.stringify({ status: 'migration_required', version: installedVersion, command: 'code-flow migrate --spec-workflow --dry-run' })}\n`);
@@ -483,16 +630,28 @@ function runInit(force, platform) {
   const coreDir = path.join(baseDir, 'core');
   const adaptersDir = path.join(baseDir, 'adapters');
 
-  // Determine mode
-  let mode;
+  // Determine mode: global mode drives core files and messaging; each
+  // platform additionally resolves its own mode from per-platform records so
+  // upgrading one platform can never mask another platform's staleness.
+  // A global upgrade also refreshes the selected platform (previous behavior).
+  const mode = modeFor(installedVersion, force);
+  const adapterVersions = readAdapterVersions(cwd);
+  const adapterPrev = typeof adapterVersions.adapters[platform] === 'string'
+    ? adapterVersions.adapters[platform]
+    : null;
+  let platformMode;
   if (force) {
-    mode = 'force';
-  } else if (!installedVersion) {
-    mode = 'fresh';
-  } else if (compareVersions(installedVersion, pkg.version) < 0) {
-    mode = 'upgrade';
+    platformMode = 'force';
+  } else if (!adapterPrev && !platformFilesExist(cwd, platform)) {
+    platformMode = 'fresh';
+  } else if (
+    (adapterPrev && compareVersions(adapterPrev, pkg.version) < 0) ||
+    (!adapterPrev && platformFilesExist(cwd, platform)) ||
+    mode === 'upgrade'
+  ) {
+    platformMode = 'upgrade';
   } else {
-    mode = 'current';
+    platformMode = 'current';
   }
 
   const created = [];
@@ -502,8 +661,10 @@ function runInit(force, platform) {
   const removed = [];
   const results = { created, updated, merged, skipped };
 
-  // Track + copy helper for directory trees
-  const processDir = (srcDir, destDir, prefix) => {
+  // Track + copy helper for directory trees. dirMode is resolved per area:
+  // core files follow the global mode, platform files follow platformMode.
+  const processDir = (srcDir, destDir, prefix, dirMode) => {
+    const effective = dirMode || mode;
     if (!fs.existsSync(srcDir)) return;
     const files = collectFiles(srcDir, '');
     for (const rel of files) {
@@ -516,10 +677,10 @@ function runInit(force, platform) {
         created.push(label);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.copyFileSync(src, dest);
-      } else if (mode === 'force') {
+      } else if (effective === 'force') {
         updated.push(label);
         fs.copyFileSync(src, dest);
-      } else if (mode === 'upgrade' && cat === 'tool') {
+      } else if (effective === 'upgrade' && cat === 'tool') {
         updated.push(label);
         fs.copyFileSync(src, dest);
       } else {
@@ -529,7 +690,7 @@ function runInit(force, platform) {
   };
 
   // Process .code-flow/ (core)
-  processDir(path.join(coreDir, 'code-flow'), path.join(cwd, '.code-flow'), '.code-flow');
+  processDir(path.join(coreDir, 'code-flow'), path.join(cwd, '.code-flow'), '.code-flow', mode);
 
   // Process Claude adapter
   if (platform === 'claude') {
@@ -537,7 +698,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'claude', 'CLAUDE.md'),
       dest: path.join(cwd, 'CLAUDE.md'),
       label: 'CLAUDE.md',
-      mode,
+      mode: platformMode,
       mergeFn: mergeClaudeMd,
       toolOnUpgrade: false,
       results,
@@ -547,14 +708,14 @@ function runInit(force, platform) {
     processDir(
       path.join(adaptersDir, 'claude', 'commands'),
       path.join(cwd, '.claude', 'commands'),
-      '.claude/commands'
+      '.claude/commands', platformMode
     );
 
     installAdapterFile({
       src: path.join(adaptersDir, 'claude', 'settings.local.json'),
       dest: path.join(cwd, '.claude', 'settings.local.json'),
       label: '.claude/settings.local.json',
-      mode,
+      mode: platformMode,
       mergeFn: mergeSettingsJson,
       toolOnUpgrade: false,
       results,
@@ -567,7 +728,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'costrict', 'CLAUDE.md'),
       dest: path.join(cwd, 'CLAUDE.md'),
       label: 'CLAUDE.md',
-      mode,
+      mode: platformMode,
       mergeFn: mergeClaudeMd,
       toolOnUpgrade: false,
       results,
@@ -577,14 +738,14 @@ function runInit(force, platform) {
     processDir(
       path.join(adaptersDir, 'costrict', 'commands'),
       path.join(cwd, '.costrict', 'commands'),
-      '.costrict/commands'
+      '.costrict/commands', platformMode
     );
 
     installAdapterFile({
       src: path.join(adaptersDir, 'costrict', 'settings.local.json'),
       dest: path.join(cwd, '.costrict', 'settings.local.json'),
       label: '.costrict/settings.local.json',
-      mode,
+      mode: platformMode,
       mergeFn: mergeSettingsJson,
       toolOnUpgrade: false,
       results,
@@ -597,7 +758,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'codex', 'AGENTS.md'),
       dest: path.join(cwd, 'AGENTS.md'),
       label: 'AGENTS.md',
-      mode,
+      mode: platformMode,
       mergeFn: mergeClaudeMd,
       toolOnUpgrade: false,
       results,
@@ -607,7 +768,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'codex', 'hooks.json'),
       dest: path.join(cwd, '.codex', 'hooks.json'),
       label: '.codex/hooks.json',
-      mode,
+      mode: platformMode,
       mergeFn: mergeSettingsJson,
       toolOnUpgrade: false,
       results,
@@ -617,7 +778,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'codex', 'config.toml'),
       dest: path.join(cwd, '.codex', 'config.toml'),
       label: '.codex/config.toml',
-      mode,
+      mode: platformMode,
       mergeFn: mergeCodexConfigToml,
       toolOnUpgrade: false,
       results,
@@ -627,7 +788,7 @@ function runInit(force, platform) {
     processDir(
       path.join(adaptersDir, 'codex', 'skills'),
       path.join(cwd, '.agents', 'skills'),
-      '.agents/skills'
+      '.agents/skills', platformMode
     );
   }
 
@@ -637,7 +798,7 @@ function runInit(force, platform) {
       src: path.join(adaptersDir, 'opencode', 'AGENTS.md'),
       dest: path.join(cwd, 'AGENTS.md'),
       label: 'AGENTS.md',
-      mode,
+      mode: platformMode,
       mergeFn: mergeClaudeMd,
       toolOnUpgrade: false,
       results,
@@ -647,7 +808,7 @@ function runInit(force, platform) {
     processDir(
       path.join(adaptersDir, 'opencode', 'plugins'),
       path.join(cwd, '.opencode', 'plugins'),
-      '.opencode/plugins'
+      '.opencode/plugins', platformMode
     );
 
     // Stamp main package version into the plugin's package.json
@@ -662,15 +823,15 @@ function runInit(force, platform) {
     processDir(
       path.join(adaptersDir, 'opencode', 'commands'),
       path.join(cwd, '.opencode', 'commands'),
-      '.opencode/commands'
+      '.opencode/commands', platformMode
     );
 
     installAdapterFile({
       src: path.join(adaptersDir, 'opencode', 'opencode.json'),
       dest: path.join(cwd, 'opencode.json'),
       label: 'opencode.json',
-      mode,
-      mergeFn: mergeSettingsJson,
+      mode: platformMode,
+      mergeFn: mergeOpencodeJson,
       toolOnUpgrade: false,
       results,
     });
@@ -689,8 +850,8 @@ function runInit(force, platform) {
     }
   }
 
-  // Clean up legacy .claude/skills/
-  removeLegacyClaudeSkills(cwd, removed);
+  // Clean up legacy .claude/skills/ (claude domain only; user-owned kept, managed backed up)
+  removeLegacyClaudeSkills(cwd, removed, { platform, backupDir: options.backupDir || '' });
 
   // Clean up renamed orphan scripts (only meaningful on upgrade)
   if (mode === 'upgrade' || mode === 'force') {
@@ -700,13 +861,16 @@ function runInit(force, platform) {
   // Install pyyaml — probe first, fall back through PEP 668 strategies
   ensurePyYaml();
 
-  // Write version
+  // Write version (legacy global file kept for compatibility) + per-platform records
   writeVersion(cwd, pkg.version);
+  adapterVersions.adapters[platform] = pkg.version;
+  adapterVersions.core = pkg.version;
+  writeAdapterVersions(cwd, adapterVersions);
 
   // Output summary
   if (mode === 'upgrade') {
     process.stdout.write(`\ncode-flow upgraded: ${installedVersion} → ${pkg.version}\n\n`);
-  } else if (mode === 'current' && created.length === 0 && updated.length === 0 && merged.length === 0) {
+  } else if (mode === 'current' && platformMode === 'current' && created.length === 0 && updated.length === 0 && merged.length === 0) {
     process.stdout.write(`code-flow v${pkg.version} already up to date.\n`);
     process.exit(0);
   } else if (mode === 'force') {
@@ -841,7 +1005,7 @@ if (args[0] === 'init') {
   if (platform !== 'claude' && platform !== 'codex' && platform !== 'costrict' && platform !== 'opencode') {
     fail(`Error: --platform must be "claude", "codex", "costrict", or "opencode", got "${platform}".`);
   }
-  runInit(force, platform);
+  runInit(force, platform, { backupDir: parseStringFlag(args, 'backup-dir') });
 }
 
 if (args[0] === 'migrate') {

package/src/core/code-flow/config.yml

@@ -24,7 +24,8 @@ budget:
 quality_loop:
     enabled: true
     post_check: true            # PostToolUse 违规反馈（只提示不阻断）
-    stop_check: true            # Stop 收尾按 validation.yml 校验
+    stop_check: true            # Stop 收尾按 validation.yml 校验（heavy 项跳过）
+    finish_check: true          # 任务 finish 时全量执行 validation.yml（含 heavy，每任务一次）
     correction_capture: true    # 纠正句式采集（喂 cf-learn 候选）
     # 注入时对 spec 内容做保守无损压缩（去行尾空白、折叠多空行、剥 HTML 注释、去重 bullet）
     # 缺省视为 true；仅显式 false 关闭

package/src/core/code-flow/scripts/cf_acceptance_evidence.py

@@ -0,0 +1,100 @@
+"""Append execution history without erasing the user's acceptance contract."""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Mapping, Sequence
+from uuid import uuid4
+
+STATES = frozenset(("planned", "pending", "tbd", "verified", "unverified", "failed", "incomplete", "not_configured", "e2e_deferred", "manual_pending"))
+
+
+def scenario_line(line: str, scenario_id: str) -> bool:
+    return bool(re.match(rf"^\s*(?:\|\s*|[-*]\s+){re.escape(scenario_id)}(?=\s*[:|])", line))
+
+
+def line_status(line: str, scenario_id: str) -> str:
+    if not scenario_line(line, scenario_id):
+        return ""
+    if line.lstrip().startswith("|"):
+        cells = [cell.strip().lower() for cell in line.strip().strip("|").split("|")]
+        return next((cell for cell in reversed(cells) if cell in STATES), "")
+    match = re.match(r"^\s*[-*]\s+[^:]+:\s*([a-z0-9_]+)\b", line, re.I)
+    return match.group(1).lower() if match and match.group(1).lower() in STATES else ""
+
+
+def _status_line(line: str, scenario_id: str, status: str) -> str:
+    if not scenario_line(line, scenario_id):
+        return line
+    if line.lstrip().startswith("|"):
+        cells = line.split("|")
+        for index in range(len(cells) - 1, 0, -1):
+            if cells[index].strip().lower() in STATES:
+                cells[index] = f" {status} "
+                return "|".join(cells)
+        return line.rstrip().rstrip("|") + f"| {status} |"
+    prefix = r"(^\s*[-*]\s+[^:]+:\s*)"
+    if line_status(line, scenario_id):
+        return re.sub(prefix + r"(?:" + "|".join(sorted(STATES)) + r")\b", rf"\g<1>{status}", line, count=1, flags=re.I)
+    return re.sub(prefix, rf"\g<1>{status} — ", line, count=1)
+
+
+def _patch_section(section: str, scenario_id: str, status: str, record: str) -> str:
+    contract = re.search(r"(?ms)^### Acceptance Contract[^\n]*\n(.*?)(?=^### |^## |\Z)", section)
+    if contract:
+        body = "\n".join(_status_line(line, scenario_id, status) for line in contract.group(1).splitlines()) + "\n"
+        section = section[:contract.start(1)] + body + section[contract.end(1):]
+    evidence = re.search(r"(?ms)^### Acceptance Evidence[^\n]*\n(.*?)(?=^### |^## |\Z)", section)
+    if evidence:
+        body = evidence.group(1)
+        if record not in body.splitlines():
+            body = body.rstrip() + "\n" + record + "\n\n"
+        section = section[:evidence.start(1)] + body + section[evidence.end(1):]
+    else:
+        section = section.rstrip() + "\n\n### Acceptance Evidence\n" + record + "\n"
+    return section
+
+
+def sync_task_evidence(task: Path, scenario_id: str, confirmed_by: str, evidence: str, owner: str = "", status: str = "verified") -> None:
+    text = task.read_text(encoding="utf-8")
+    task_pattern = re.escape(owner) if owner else r"TASK-\d+"
+    match = re.search(rf"(?ms)^##\s+{task_pattern}:.*?(?=^## |\Z)", text)
+    if match is None:
+        raise ValueError(f"acceptance owner missing: {owner}")
+    record = f"- {scenario_id}: {status} — {evidence} (confirmed_by: {confirmed_by})"
+    section = _patch_section(match.group(0), scenario_id, status, record)
+    text = text[:match.start()] + section + text[match.end():]
+    coverage = re.search(r"(?ms)^## Acceptance Coverage[^\n]*\n(.*?)(?=^## |\Z)", text)
+    if coverage:
+        body = "\n".join(_status_line(line, scenario_id, status) for line in coverage.group(1).splitlines()) + "\n"
+        text = text[:coverage.start(1)] + body + text[coverage.end(1):]
+    from cf_spec_context import _atomic_text
+    _atomic_text(task, text)
+
+
+def persist_results(path: Path, data: dict[str, object], results: Sequence[Mapping[str, object]]) -> None:
+    rows = {row["id"]: row for row in data["scenarios"]}
+    run_id, executed_at = uuid4().hex, datetime.now(timezone.utc).isoformat()
+    updates = []
+    for result in results:
+        state = str(result["status"])
+        if state in ("not_included", "manual_pending"):
+            continue
+        row = rows[result["id"]]
+        row["revision"] = int(row.get("revision", 0)) + 1
+        status = "verified" if state == "passed" else state
+        row["status"] = status
+        record = {**result, "revision": row["revision"], "run_id": run_id, "executed_at": executed_at}
+        row["evidence"] = record
+        row.setdefault("runs", []).append(record)
+        updates.append((row, record, status))
+    from cf_spec_context import _atomic_text
+    _atomic_text(path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+    task_name = data.get("task_file")
+    if isinstance(task_name, str) and task_name:
+        task = Path(task_name) if Path(task_name).is_absolute() else path.parent / task_name
+        for row, record, status in updates:
+            detail = f"automated command {record['status']}; run_id={run_id}"
+            sync_task_evidence(task, str(row["id"]), "runner", detail, str(row.get("owner", "")), status)