@xulthekl/team-flow 0.22.4

package/scripts/lib/solutions-capture.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * solutions-capture — 写入一条经验到 INDEX.md + 对应目录
+ *
+ * v0.5 复利贯穿机制脚本
+ * 用法：tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"
+ *
+ * 功能：
+ * 1. 在对应阶段目录下创建经验文件
+ * 2. 在 INDEX.md 中追加一行摘要
+ * 3. INDEX.md 超过 150 行时触发 index-gen 重建
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
+const MAX_INDEX_LINES = 150;
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9一-鿿]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+}
+
+export function run(args = {}) {
+  const phase = args.phase || 'cross-phase';
+  const domain = args.domain || 'general';
+  const type = args.type || 'insight';
+  const severity = args.severity || 'medium';
+  const summary = args.summary || '(no summary)';
+  const source = args.source || '';
+  const dir = args.dir || 'docs/solutions';
+
+  if (!PHASES.includes(phase)) {
+    console.error(`Invalid phase: ${phase}. Valid: ${PHASES.join(', ')}`);
+    process.exit(1);
+  }
+
+  // 确保目录存在
+  const phaseDir = join(dir, phase);
+  if (!existsSync(phaseDir)) mkdirSync(phaseDir, { recursive: true });
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  // 生成文件名
+  const date = new Date().toISOString().slice(0, 10);
+  const slug = slugify(summary);
+  const fileName = `${date}-${slug}.md`;
+  const filePath = join(phaseDir, fileName);
+
+  // 写经验文件
+  const content = `---
+phase: ${phase}
+domain: ${domain}
+type: ${type}
+severity: ${severity}
+date: ${date}
+source: ${source}
+---
+
+## 问题描述
+${summary}
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）
+`;
+  writeFileSync(filePath, content, 'utf-8');
+
+  // 追加 INDEX.md
+  const indexPath = join(dir, 'INDEX.md');
+  if (!existsSync(indexPath)) {
+    writeFileSync(indexPath, '# Solutions Index\n<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->\n| date | phase | domain | type | severity | summary | file |\n|------|-------|--------|------|----------|---------|------|\n', 'utf-8');
+  }
+  appendFileSync(indexPath, `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${summary.slice(0, 80)} | ${phase}/${fileName} |\n`, 'utf-8');
+
+  // 检查是否超过 150 行
+  const indexContent = readFileSync(indexPath, 'utf-8');
+  const dataLines = indexContent.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+  if (dataLines.length > MAX_INDEX_LINES) {
+    console.log(`INDEX.md exceeded ${MAX_INDEX_LINES} lines, consider running: tf solutions index-gen`);
+  }
+
+  console.log(`Captured: ${phase}/${fileName} (${severity}/${type})`);
+  return { file: `${phase}/${fileName}`, phase, domain, type, severity };
+}
+
+if (process.argv[1]?.includes('solutions-capture')) {
+  const args = {};
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i].startsWith('--')) {
+      const key = process.argv[i].replace('--', '');
+      const val = process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[++i] : true;
+      args[key] = val;
+    }
+  }
+  run(args);
+}

package/scripts/lib/solutions-index-gen.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * solutions-index-gen — 扫描 docs/solutions/<phase>/ 各阶段目录，重建 INDEX.md
+ *
+ * v0.5 复利贯穿机制脚本
+ * 用法：tf solutions index-gen [--dir <solutions-dir>]
+ *
+ * 功能：
+ * 1. 扫描 docs/solutions/ 下所有子目录中的 .md 文件
+ * 2. 解析每个文件的 frontmatter（phase/domain/type/severity/date/summary）
+ * 3. 按 severity 降序、date 降序排列
+ * 4. 重建 INDEX.md（≤150 行硬上限）
+ * 5. 超出 150 条时，淘汰 low severity 且 date 最早的条目
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+const MAX_INDEX_LINES = 150;
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim();
+      fm[key] = val;
+    }
+  }
+  return fm;
+}
+
+function extractSummary(content) {
+  // 取 frontmatter 后第一个非空行作为摘要
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
+  return lines[0]?.trim().slice(0, 80) || '(no summary)';
+}
+
+export function run(args = {}) {
+  const dir = args.dir || 'docs/solutions';
+  const indexPath = join(dir, 'INDEX.md');
+
+  if (!existsSync(dir)) {
+    console.error(`Solutions directory not found: ${dir}`);
+    process.exit(1);
+  }
+
+  const entries = [];
+
+  for (const phase of PHASES) {
+    const phaseDir = join(dir, phase);
+    if (!existsSync(phaseDir) || !statSync(phaseDir).isDirectory()) continue;
+
+    for (const file of readdirSync(phaseDir)) {
+      if (!file.endsWith('.md')) continue;
+      const filePath = join(phaseDir, file);
+      const content = readFileSync(filePath, 'utf-8');
+      const fm = parseFrontmatter(content);
+      if (!fm) continue;
+
+      entries.push({
+        date: fm.date || '1970-01-01',
+        phase: fm.phase || phase,
+        domain: fm.domain || 'general',
+        type: fm.type || 'insight',
+        severity: fm.severity || 'low',
+        summary: extractSummary(content),
+        file: `${phase}/${file}`,
+      });
+    }
+  }
+
+  // 排序：severity 降序，date 降序
+  entries.sort((a, b) => {
+    const sevDiff = (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3);
+    if (sevDiff !== 0) return sevDiff;
+    return b.date.localeCompare(a.date);
+  });
+
+  // 截断到 150 条
+  const kept = entries.slice(0, MAX_INDEX_LINES);
+  const dropped = entries.slice(MAX_INDEX_LINES);
+
+  // 生成 INDEX.md
+  let index = '# Solutions Index\n';
+  index += '<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->\n';
+  index += '| date | phase | domain | type | severity | summary | file |\n';
+  index += '|------|-------|--------|------|----------|---------|------|\n';
+  for (const e of kept) {
+    index += `| ${e.date} | ${e.phase} | ${e.domain} | ${e.type} | ${e.severity} | ${e.summary} | ${e.file} |\n`;
+  }
+
+  writeFileSync(indexPath, index, 'utf-8');
+  console.log(`INDEX.md rebuilt: ${kept.length} entries (${dropped.length} dropped)`);
+  if (dropped.length > 0) {
+    console.log(`Dropped ${dropped.length} low-priority entries (files preserved in directories)`);
+  }
+}
+
+// CLI 直接执行
+if (process.argv[1]?.includes('solutions-index-gen')) {
+  const args = {};
+  const dirIdx = process.argv.indexOf('--dir');
+  if (dirIdx > -1 && process.argv[dirIdx + 1]) args.dir = process.argv[dirIdx + 1];
+  run(args);
+}

package/scripts/lib/solutions-inject.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * solutions-inject — 按 phase+domain 过滤 INDEX.md，输出 top-5 摘要
+ *
+ * v0.5 复利贯穿机制脚本
+ * 用法：tf solutions inject --phase <p> --domain <d>
+ *
+ * 功能：
+ * 1. 读取 docs/solutions/INDEX.md
+ * 2. 过滤：phase = 指定阶段 OR phase = cross-phase，且 domain 匹配
+ * 3. 按 severity 降序取 top-5
+ * 4. 输出摘要（供各 skill 注入上下文）
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+
+export function run(args = {}) {
+  const phase = args.phase || 'cross-phase';
+  const domain = args.domain || '';
+  const dir = args.dir || 'docs/solutions';
+  const indexPath = join(dir, 'INDEX.md');
+
+  if (!existsSync(indexPath)) {
+    console.log('<!-- No solutions index found, skipping injection -->');
+    return { entries: [] };
+  }
+
+  const content = readFileSync(indexPath, 'utf-8');
+  const lines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+
+  const entries = [];
+  for (const line of lines) {
+    const cols = line.split('|').map(c => c.trim()).filter(Boolean);
+    if (cols.length < 7) continue;
+    const [date, ePhase, eDomain, type, severity, summary, file] = cols;
+
+    // 过滤：phase 匹配或 cross-phase
+    const phaseMatch = ePhase === phase || ePhase === 'cross-phase';
+    // 过滤：domain 匹配（空 domain 表示通用）
+    const domainMatch = !domain || !eDomain || eDomain === 'general' || eDomain === domain;
+
+    if (phaseMatch && domainMatch) {
+      entries.push({ date, phase: ePhase, domain: eDomain, type, severity, summary, file });
+    }
+  }
+
+  // 按 severity 降序排序，取 top-5
+  entries.sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3));
+  const top5 = entries.slice(0, 5);
+
+  if (top5.length === 0) {
+    console.log('<!-- No matching solutions found -->');
+    return { entries: [] };
+  }
+
+  console.log(`## Solutions Context (phase=${phase}, domain=${domain || 'any'})`);
+  console.log('');
+  for (const e of top5) {
+    console.log(`- [${e.severity}] ${e.summary} (${e.phase}/${e.domain}, ${e.date}) → ${e.file}`);
+  }
+  console.log('');
+
+  return { entries: top5 };
+}
+
+if (process.argv[1]?.includes('solutions-inject')) {
+  const args = {};
+  for (let i = 2; i < process.argv.length; i += 2) {
+    const key = process.argv[i]?.replace('--', '');
+    const val = process.argv[i + 1];
+    if (key && val) args[key] = val;
+  }
+  run(args);
+}

package/scripts/lib/solutions-promote.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * solutions-promote — 检查 change 内经验的晋升条件，执行 change→product 晋升
+ *
+ * v0.5 复利贯穿机制脚本
+ * 用法：tf solutions promote <change-dir> [--dir <solutions-dir>]
+ *
+ * 功能：
+ * 1. 读取 specs/<cap>/learnings.md
+ * 2. 逐条检查晋升条件（severity ≥ medium 且 type = pitfall/pattern）
+ * 3. 检查与全局 INDEX 是否重复（domain+type 匹配）
+ * 4. 符合条件 → 写入全局 docs/solutions/
+ * 5. 重复 → 更新已有条目的 severity 和确认次数
+ *
+ * 变更说明（v0.5 / 2026-07-21）：
+ * - 修正原稿在同步 run() 内使用 `await import('node:fs')` 取 mkdirSync 导致的语法错误，
+ *   改为在顶部静态 import mkdirSync，保持与其它 solutions-* 脚本一致的同步签名。
+ */
+
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+function parseFrontmatter(content) {
+  // learnings.md 中每个条目以 `## 标题` 开头，frontmatter 紧跟标题行之后；
+  // 故此处兼容 frontmatter 位于段首或标题行之后两种位置（^--- 只能匹配段首会漏判）。
+  const match = content.match(/(?:^|\n)---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx > 0) {
+      fm[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+    }
+  }
+  return fm;
+}
+
+function parseLearnings(content) {
+  // 解析 learnings.md 中的经验条目（## 标题分隔）
+  const sections = content.split(/^## /m).filter(s => s.trim());
+  return sections.map(s => {
+    const lines = s.trim().split('\n');
+    const title = lines[0]?.trim() || '';
+    const fm = parseFrontmatter(s);
+    return { title, fm, body: s.trim() };
+  }).filter(e => e.title && e.title !== 'Learnings');
+}
+
+export function run(args = {}) {
+  const changeDir = args._?.[0] || args.changeDir;
+  const solutionsDir = args.dir || 'docs/solutions';
+
+  if (!changeDir) {
+    console.error('Usage: tf solutions promote <change-dir>');
+    process.exit(1);
+  }
+
+  const learningsPath = join(changeDir, 'learnings.md');
+  if (!existsSync(learningsPath)) {
+    console.log(`No learnings.md found in ${changeDir}, nothing to promote`);
+    return { promoted: 0, updated: 0 };
+  }
+
+  const content = readFileSync(learningsPath, 'utf-8');
+  const learnings = parseLearnings(content);
+
+  if (learnings.length === 0) {
+    console.log('No learning entries found');
+    return { promoted: 0, updated: 0 };
+  }
+
+  // 读取全局 INDEX
+  const indexPath = join(solutionsDir, 'INDEX.md');
+  const indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf-8') : '';
+
+  let promoted = 0;
+  let updated = 0;
+
+  for (const learning of learnings) {
+    const severity = learning.fm?.severity || 'low';
+    const type = learning.fm?.type || 'insight';
+    const phase = learning.fm?.phase || 'cross-phase';
+    const domain = learning.fm?.domain || 'general';
+
+    // 晋升条件：severity ≥ medium 且 type = pitfall/pattern
+    const sevOk = severity === 'high' || severity === 'medium';
+    const typeOk = type === 'pitfall' || type === 'pattern';
+    if (!sevOk || !typeOk) continue;
+
+    // 检查重复：domain+type 匹配
+    const dupRegex = new RegExp(`\\| ${domain} \\| ${type} \\|`);
+    if (dupRegex.test(indexContent)) {
+      console.log(`Duplicate found (${domain}/${type}), marking as confirmed pattern`);
+      updated++;
+      continue;
+    }
+
+    // 写入全局
+    const date = learning.fm?.date || new Date().toISOString().slice(0, 10);
+    const phaseDir = join(solutionsDir, phase);
+    if (!existsSync(phaseDir)) {
+      mkdirSync(phaseDir, { recursive: true });
+    }
+
+    const slug = learning.title.toLowerCase().replace(/[^a-z0-9一-鿿]+/g, '-').slice(0, 40);
+    const fileName = `${date}-${slug}.md`;
+    const filePath = join(phaseDir, fileName);
+
+    const fileContent = `---
+phase: ${phase}
+domain: ${domain}
+type: ${type}
+severity: ${severity}
+date: ${date}
+source: ${basename(changeDir)}
+---
+
+${learning.body}
+`;
+    writeFileSync(filePath, fileContent, 'utf-8');
+
+    // 追加 INDEX
+    appendFileSync(indexPath, `| ${date} | ${phase} | ${domain} | ${type} | ${severity} | ${learning.title.slice(0, 80)} | ${phase}/${fileName} |\n`, 'utf-8');
+
+    console.log(`Promoted: ${phase}/${fileName}`);
+    promoted++;
+  }
+
+  console.log(`\nPromotion complete: ${promoted} promoted, ${updated} updated as confirmed`);
+  return { promoted, updated };
+}
+
+if (process.argv[1]?.includes('solutions-promote')) {
+  const args = { _: [] };
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i].startsWith('--')) {
+      const key = process.argv[i].replace('--', '');
+      const val = process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[++i] : true;
+      args[key] = val;
+    } else {
+      args._.push(process.argv[i]);
+    }
+  }
+  run(args);
+}

package/scripts/lib/spec-paths.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function specsDir(changeDir) {
+  return path.join(changeDir, 'specs');
+}
+
+function walk(dir, results = []) {
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, results);
+    } else if (entry.isFile()) {
+      results.push(full);
+    }
+  }
+
+  return results;
+}
+
+export function findCanonicalSpecFiles(changeDir) {
+  const root = specsDir(changeDir);
+  if (!fs.existsSync(root)) return [];
+
+  return walk(root)
+    .filter(file => {
+      if (path.basename(file) !== 'spec.md') return false;
+      const rel = path.relative(root, file).split(path.sep);
+      return rel.length === 2;
+    })
+    .sort();
+}
+
+export function findInvalidSpecFiles(changeDir) {
+  const root = specsDir(changeDir);
+  if (!fs.existsSync(root)) return [];
+
+  const invalid = [];
+
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+
+    const rel = `specs/${entry.name}`;
+    if (entry.name === 'README.md') continue;
+    if (entry.name === 'spec.md') {
+      invalid.push({ path: rel, expected: 'specs/<capability>/spec.md' });
+      continue;
+    }
+
+    const capability = entry.name.replace(/\.md$/, '');
+    invalid.push({ path: rel, expected: `specs/${capability}/spec.md` });
+  }
+
+  return invalid.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function formatSpecPathFailure(item) {
+  return `Invalid spec path: ${item.path}. Expected: ${item.expected}`;
+}
+
+export function validateSpecPathLayout(changeDir, options = {}) {
+  const requireSpecs = options.requireSpecs === true;
+  const specFiles = findCanonicalSpecFiles(changeDir);
+  const failures = findInvalidSpecFiles(changeDir).map(formatSpecPathFailure);
+
+  if (requireSpecs && specFiles.length === 0) {
+    failures.push('No canonical spec files found. Expected at least one specs/<capability>/spec.md');
+  }
+
+  return {
+    pass: failures.length === 0,
+    specFiles,
+    failures,
+  };
+}
+
+export function relativeSpecPath(changeDir, file) {
+  return toPosix(path.relative(changeDir, file));
+}

package/scripts/lib/state-loader.mjs

@@ -0,0 +1,154 @@
+// scripts/lib/state-loader.mjs — lightweight .team-flow.yaml state file reader/writer
+import fs from 'node:fs';
+import path from 'node:path';
+
+const STATE_FILE = '.team-flow.yaml';
+
+const BUILTIN_DEFAULTS = {
+  state: 'exploring',
+  workflow: 'auto',
+  revision: null,
+  artifacts_hash: null,
+  contract_hash: null,
+  execution_mode: null,
+  execution_plan_hash: null,
+  execution_plan_revision: null,
+  batches_completed: 0,
+  test_result: null,
+  spec_merged: false,
+  change_name: null,
+  last_transition: null,
+  last_transition_from: null,
+  last_transition_to: null,
+  dp_0_decisions: null,
+  dp_0_result: null,
+  dp_0_confirmed: null,
+  dp_0_timestamp: null,
+  dp_1_result: null,
+  dp_1_timestamp: null,
+  dp_2_result: null,
+  dp_2_timestamp: null,
+  dp_3_result: null,
+  dp_3_timestamp: null,
+  dp_4_result: null,
+  dp_4_timestamp: null,
+  dp_5_result: null,
+  dp_5_timestamp: null,
+  dp_6_result: null,
+  dp_6_timestamp: null,
+  dp_7_result: null,
+  dp_7_timestamp: null,
+};
+
+/**
+ * Read state file, merging with built-in defaults.
+ * Returns a complete state object even if the file doesn't exist.
+ */
+export function readState(changeDir) {
+  const filePath = path.join(changeDir, STATE_FILE);
+  if (!fs.existsSync(filePath)) {
+    return { ...BUILTIN_DEFAULTS, change_name: path.basename(changeDir) };
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const parsed = parseYaml(raw);
+  return { ...BUILTIN_DEFAULTS, ...parsed };
+}
+
+/**
+ * Write state object to .team-flow.yaml.
+ */
+export function writeState(changeDir, state) {
+  const filePath = path.join(changeDir, STATE_FILE);
+  const lines = [];
+  lines.push('# .team-flow.yaml — lightweight state machine');
+  lines.push('# Derived data. Always rebuildable from artifacts. Lost/corrupt → fall back to content-level detection.');
+  lines.push('');
+  lines.push('# === Core state ===');
+  lines.push(`state: ${state.state || 'exploring'}`);
+  lines.push(`workflow: ${state.workflow || 'auto'}`);
+  lines.push(`revision: ${state.revision ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Hashes (fast staleness detection) ===');
+  lines.push(`artifacts_hash: ${state.artifacts_hash ?? 'null'}`);
+  lines.push(`contract_hash: ${state.contract_hash ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Execution progress ===');
+  lines.push(`execution_mode: ${state.execution_mode ?? 'null'}`);
+  lines.push(`execution_plan_hash: ${state.execution_plan_hash ?? 'null'}`);
+  lines.push(`execution_plan_revision: ${state.execution_plan_revision ?? 'null'}`);
+  lines.push(`batches_completed: ${state.batches_completed ?? 0}`);
+  lines.push(`test_result: ${state.test_result ?? 'null'}`);
+  lines.push(`spec_merged: ${state.spec_merged ?? false}`);
+  lines.push('');
+  lines.push('# === Metadata ===');
+  lines.push(`change_name: ${state.change_name ?? path.basename(changeDir)}`);
+  lines.push(`last_transition: ${state.last_transition ?? 'null'}`);
+  lines.push(`last_transition_from: ${state.last_transition_from ?? 'null'}`);
+  lines.push(`last_transition_to: ${state.last_transition_to ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Decision points ===');
+  lines.push(`dp_0_decisions: ${state.dp_0_decisions ?? 'null'}`);
+  lines.push(`dp_0_result: ${state.dp_0_result ?? 'null'}`);
+  lines.push(`dp_0_confirmed: ${state.dp_0_confirmed ?? 'null'}`);
+  lines.push(`dp_0_timestamp: ${state.dp_0_timestamp ?? 'null'}`);
+  lines.push(`dp_1_result: ${state.dp_1_result ?? 'null'}`);
+  lines.push(`dp_1_timestamp: ${state.dp_1_timestamp ?? 'null'}`);
+  lines.push(`dp_2_result: ${state.dp_2_result ?? 'null'}`);
+  lines.push(`dp_2_timestamp: ${state.dp_2_timestamp ?? 'null'}`);
+  lines.push(`dp_3_result: ${state.dp_3_result ?? 'null'}`);
+  lines.push(`dp_3_timestamp: ${state.dp_3_timestamp ?? 'null'}`);
+  lines.push(`dp_4_result: ${state.dp_4_result ?? 'null'}`);
+  lines.push(`dp_4_timestamp: ${state.dp_4_timestamp ?? 'null'}`);
+  lines.push(`dp_5_result: ${state.dp_5_result ?? 'null'}`);
+  lines.push(`dp_5_timestamp: ${state.dp_5_timestamp ?? 'null'}`);
+  lines.push(`dp_6_result: ${state.dp_6_result ?? 'null'}`);
+  lines.push(`dp_6_timestamp: ${state.dp_6_timestamp ?? 'null'}`);
+  lines.push(`dp_7_result: ${state.dp_7_result ?? 'null'}`);
+  lines.push(`dp_7_timestamp: ${state.dp_7_timestamp ?? 'null'}`);
+
+  fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+}
+
+/**
+ * Update a single field in the state file.
+ */
+export function updateField(changeDir, field, value) {
+  const state = readState(changeDir);
+  state[field] = value;
+  writeState(changeDir, state);
+}
+
+/**
+ * Rebuild state file from artifacts — recomputes hashes.
+ * Requires hash functions to be passed in (avoids circular dependency).
+ */
+export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash }) {
+  const state = readState(changeDir);
+  state.artifacts_hash = computeArtifactsHash(changeDir);
+  state.contract_hash = computeContractHash(changeDir);
+  writeState(changeDir, state);
+  return state;
+}
+
+// Minimal YAML parser — top-level fields only, zero dependencies.
+// Handles strings, null, integers. No nested structures needed.
+function parseYaml(content) {
+  const result = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = trimmed.match(/^(\w[\w_]*):\s*(.*)/);
+    if (match) {
+      const val = match[2].trim();
+      if (val === 'null' || val === '') {
+        result[match[1]] = null;
+      } else if (/^\d+$/.test(val)) {
+        result[match[1]] = parseInt(val, 10);
+      } else {
+        result[match[1]] = val;
+      }
+    }
+  }
+  return result;
+}