sillyspec 3.18.2 → 3.18.3

package/src/knowledge-match.js

@@ -0,0 +1,130 @@
+/**
+ * knowledge-match.js — knowledge 关键词匹配引擎
+ * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * 从 INDEX.md 解析所有知识条目
+ * @param {string} indexDir - knowledge 目录路径
+ * @returns {{ category: string, keywords: string[], file: string, anchor: string, display: string, line: string }[]}
+ */
+export function parseKnowledgeIndex(indexDir) {
+  const indexPath = join(indexDir, 'INDEX.md')
+  if (!existsSync(indexPath)) return []
+
+  const content = readFileSync(indexPath, 'utf8')
+  const entries = []
+  let currentCategory = ''
+
+  for (const line of content.split('\n')) {
+    // 匹配 ## Category 行
+    const catMatch = line.match(/^##\s+(.+)/)
+    if (catMatch) {
+      currentCategory = catMatch[1].trim()
+      continue
+    }
+
+    // 匹配条目行：- 关键词1|关键词2 → [显示名](文件名#锚点)
+    const entryMatch = line.match(/^-\s+(.+?)\s*→\s*\[(.+?)\]\(([^#)]+)(?:#([^)]+))?\)/)
+    if (entryMatch) {
+      const keywords = entryMatch[1].split('|').map(k => k.trim()).filter(Boolean)
+      const display = entryMatch[2].trim()
+      const file = entryMatch[3].trim()
+      const anchor = entryMatch[4] ? entryMatch[4].trim() : ''
+      entries.push({ category: currentCategory, keywords, file, anchor, display, line })
+    }
+  }
+
+  return entries
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 单个关键词是否命中上下文。
+ * - 过短关键词（<2 字符）视为噪音，不参与匹配
+ * - 非 ASCII（中文等）用子串匹配
+ * - ASCII 关键词用词边界匹配，避免子串误命中（如 "DB" 不命中 "dashboard"）
+ */
+function keywordMatchesContext(keyword, contextLower) {
+  const kw = keyword.toLowerCase().trim()
+  if (kw.length < 2) return false
+  if (/[^\x00-\x7f]/.test(kw)) return contextLower.includes(kw)
+  return new RegExp(`(^|[^a-z0-9])${escapeRegex(kw)}([^a-z0-9]|$)`).test(contextLower)
+}
+
+/**
+ * 用任务上下文匹配知识条目
+ * @param {string} indexDir - knowledge 目录路径
+ * @param {string} taskContext - 任务上下文（task 名称 + 描述，用于关键词匹配）
+ * @returns {{ matched: boolean, entries: Array, report: string, json: object }}
+ */
+export function matchKnowledge(indexDir, taskContext) {
+  const indexPath = join(indexDir, 'INDEX.md')
+
+  // INDEX.md 不存在
+  if (!existsSync(indexPath)) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches (INDEX.md not found)',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const allEntries = parseKnowledgeIndex(indexDir)
+  if (allEntries.length === 0 || !taskContext) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const contextLower = taskContext.toLowerCase()
+  const matched = allEntries.filter(entry => {
+    return entry.keywords.some(kw => keywordMatchesContext(kw, contextLower))
+  })
+
+  if (matched.length === 0) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const sources = matched.map(e => {
+    const base = e.anchor ? `${e.file}#${e.anchor}` : e.file
+    return ` - ${base}`
+  }).join('\n')
+
+  const report = [
+    'Knowledge Context',
+    '─────────────────',
+    `Status: matched`,
+    `Entries: ${matched.length}`,
+    'Sources:',
+    sources
+  ].join('\n')
+
+  const json = {
+    matched: true,
+    entry_count: matched.length,
+    entries: matched.map(e => ({
+      file: e.file,
+      anchor: e.anchor,
+      keywords: e.keywords,
+      category: e.category
+    }))
+  }
+
+  return { matched: true, entries: matched, report, json }
+}

package/src/progress.js

@@ -38,7 +38,16 @@ const CHANGES_SUBDIR = 'changes';
 const GLOBAL_FILE = 'global.json';
 const CURRENT_VERSION = 3;
 const VALID_STAGES = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive', 'quick', 'explore'];
-const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting'];
+const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'waiting', 'stale'];
+
+// Stage statuses (superset of step statuses)
+const VALID_STAGE_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'revising', 'stale'];
+
+// Main flow stage order (for downstream cascade)
+// 完整主流程顺序（含 scan），用于下游 cascade
+const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', 'archive'];
+// 主流程阶段（不含 scan/quick/explore 等辅助阶段）
+const MAIN_FLOW_ORDER = STAGE_ORDER;
 
 const STAGE_LABELS = {
   brainstorm: '🧠 需求探索',
@@ -208,13 +217,18 @@ export class ProgressManager {
     if (!changeRows || changeRows.length === 0 || changeRows[0].values.length === 0) return null;
     const [changeId, cName, currentStage, noWorktree, lastActive] = changeRows[0].values[0];
 
-    // 2. 从 stages 表获取所有阶段
-    const stageRows = sqlDb.exec('SELECT id, stage, status, started_at, completed_at FROM stages WHERE change_id = ? ORDER BY id', [changeId]);
+    // 2. 从 stages 表获取所有阶段（含 revision 列）
+    const stageRows = sqlDb.exec('SELECT id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason FROM stages WHERE change_id = ? ORDER BY id', [changeId]);
     const stageMap = {};
     const stageIds = [];
     if (stageRows && stageRows.length > 0) {
-      for (const [sId, stage, status, startedAt, completedAt] of stageRows[0].values) {
-        stageMap[stage] = { _dbId: sId, status, startedAt, completedAt };
+      for (const [sId, stage, status, startedAt, completedAt, revision, reopenedFromStep, reopenedAt, staleReason] of stageRows[0].values) {
+        stageMap[stage] = { _dbId: sId, status, startedAt, completedAt,
+          ...(revision ? { revision } : {}),
+          ...(reopenedFromStep ? { reopenedFromStep } : {}),
+          ...(reopenedAt ? { reopenedAt } : {}),
+          ...(staleReason ? { staleReason } : {}),
+        };
         stageIds.push(sId);
       }
     }
@@ -291,6 +305,11 @@ export class ProgressManager {
         steps,
         startedAt: info.startedAt,
         completedAt: info.completedAt,
+        // Revision v1 fields
+        ...(info.revision ? { revision: info.revision } : {}),
+        ...(info.reopenedFromStep ? { reopenedFromStep: info.reopenedFromStep } : {}),
+        ...(info.reopenedAt ? { reopenedAt: info.reopenedAt } : {}),
+        ...(info.staleReason ? { staleReason: info.staleReason } : {}),
       };
     }
 
@@ -343,15 +362,20 @@ export class ProgressManager {
       // 3. 遍历 stages，UPSERT stages 表和 steps 表
       if (data.stages && typeof data.stages === 'object') {
         for (const [stageName, stageData] of Object.entries(data.stages)) {
-          // UPSERT stages 行
+          // UPSERT stages 行（含 revision 列）
           sqlDb.run(
-            `INSERT INTO stages (change_id, stage, status, started_at, completed_at)
-             VALUES (?, ?, ?, ?, ?)
+            `INSERT INTO stages (change_id, stage, status, started_at, completed_at, revision, reopened_from_step, reopened_at, stale_reason)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
              ON CONFLICT(change_id, stage) DO UPDATE SET
                status = excluded.status,
                started_at = excluded.started_at,
-               completed_at = excluded.completed_at`,
-            [changeId, stageName, stageData.status || 'pending', stageData.startedAt || null, stageData.completedAt || null]
+               completed_at = excluded.completed_at,
+               revision = COALESCE(excluded.revision, stages.revision),
+               reopened_from_step = excluded.reopened_from_step,
+               reopened_at = excluded.reopened_at,
+               stale_reason = excluded.stale_reason`,
+            [changeId, stageName, stageData.status || 'pending', stageData.startedAt || null, stageData.completedAt || null,
+             stageData.revision || 0, stageData.reopenedFromStep || null, stageData.reopenedAt || null, stageData.staleReason || null]
           );
 
           // 获取 stage_id
@@ -955,7 +979,7 @@ export class ProgressManager {
     console.log('  ═══════════════════════════════════════');
     console.log('');
 
-    const statusIcons = { pending: '⬜', 'in-progress': '🔵', completed: '✅', failed: '❌', blocked: '🚫', waiting: '⏸️' };
+    const statusIcons = { pending: '⬜', 'in-progress': '🔵', completed: '✅', failed: '❌', blocked: '🚫', waiting: '⏸️', revising: '🔧', stale: '⚠️' };
 
     for (const stage of VALID_STAGES) {
       const stageData = data.stages[stage] || emptyStage();
@@ -965,6 +989,17 @@ export class ProgressManager {
 
       console.log(`  ${icon} ${label}${isCurrent}`);
 
+      // Show revision info
+      if (stageData.revision && stageData.revision > 0) {
+        console.log(`    📋 revision: ${stageData.revision}${stageData.reopenedFromStep ? `, from step: ${stageData.reopenedFromStep}` : ''}`);
+      }
+      if (stageData.staleReason) {
+        console.log(`    ⚠️ stale: ${stageData.staleReason}`);
+        if (stage === 'archive') {
+          console.log(`    📁 已有归档文件仍保留在磁盘上，但不再可信。`);
+        }
+      }
+
       if (stageData.steps && stageData.steps.length > 0) {
         for (const step of stageData.steps) {
           const si = statusIcons[step.status] || '○';
@@ -996,13 +1031,316 @@ export class ProgressManager {
       }
     }
 
+    // ── Next 建议 ──
+    const suggestion = this._getNextSuggestion(data);
+    if (suggestion) {
+      console.log('');
+      console.log(`  💡 ${suggestion.text}`);
+      if (suggestion.command) console.log(`     ${suggestion.command}`);
+    }
+
     console.log('');
   }
 
+  /**
+   * 根据当前状态给出下一步建议
+   * @param {object} data - progress data
+   * @returns {{ text: string, command?: string }|null}
+   */
+  _getNextSuggestion(data) {
+    // 找到第一个 revising 阶段
+    const revisingStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'revising');
+    if (revisingStage) {
+      const sd = data.stages[revisingStage];
+      return {
+        text: `${STAGE_LABELS[revisingStage] || revisingStage} 正在修订中（revision ${sd.revision || 1}），请继续完成修订。`,
+        command: `sillyspec run ${revisingStage}`,
+      };
+    }
+
+    // 找到第一个 stale 阶段（上游已修，下游需要重建）
+    const staleStage = STAGE_ORDER.find(s => data.stages[s]?.status === 'stale');
+    if (staleStage) {
+      const sd = data.stages[staleStage];
+      return {
+        text: `${STAGE_LABELS[staleStage] || staleStage} 已失效（${sd.staleReason || '上游修订'}），需要从第一步重建。`,
+        command: `sillyspec run ${staleStage} --reopen --from-step 1`,
+      };
+    }
+
+    // 找到第一个有 pending/waiting/failed 步骤的 in-progress 阶段
+    for (const s of STAGE_ORDER) {
+      const sd = data.stages[s];
+      if (!sd) continue;
+      if (sd.status === 'in-progress' && sd.steps) {
+        const hasPending = sd.steps.some(st => ['pending', 'waiting', 'failed'].includes(st.status));
+        if (hasPending) {
+          return {
+            text: `${STAGE_LABELS[s] || s} 进行中，继续执行下一步。`,
+            command: `sillyspec run ${s}`,
+          };
+        }
+      }
+    }
+
+    // 找到第一个 pending 主流程阶段
+    for (const s of STAGE_ORDER) {
+      const sd = data.stages[s];
+      if (sd && sd.status === 'pending' && sd.steps && sd.steps.length > 0) {
+        // 检查上游是否都 completed
+        const idx = STAGE_ORDER.indexOf(s);
+        const upstream = STAGE_ORDER.slice(0, idx);
+        const upstreamOk = upstream.every(us =>
+          data.stages[us]?.status === 'completed' || !data.stages[us] || data.stages[us].status === 'pending'
+        );
+        if (upstreamOk) {
+          return {
+            text: `可以开始 ${STAGE_LABELS[s] || s}。`,
+            command: `sillyspec run ${s}`,
+          };
+        }
+      }
+    }
+
+    return null;
+  }
+
   async status(cwd, changeName = null) {
     await this.show(cwd, changeName);
   }
 
+  /**
+   * Revision v1 状态一致性检查
+   * 只报告，不自动修复。
+   * @param {string} cwd
+   * @param {string|null} changeName
+   * @returns {{ ok: boolean, issues: string[], warnings: string[] }}
+   */
+  async checkConsistency(cwd, changeName = null) {
+    const data = await this.read(cwd, changeName);
+    if (!data) {
+      return { ok: false, issues: ['无法读取进度数据'], warnings: [] };
+    }
+
+    const issues = [];
+    const warnings = [];
+
+    for (const stageName of STAGE_ORDER) {
+      const sd = data.stages[stageName];
+      if (!sd) continue;
+
+      // a. completed stage 不能有 pending/stale steps
+      if (sd.status === 'completed' && sd.steps) {
+        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
+        for (const step of badSteps) {
+          issues.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed`);
+        }
+      }
+
+      // b. revising stage 应有 revision > 0 或 reopenedFromStep
+      if (sd.status === 'revising') {
+        if (!sd.revision || sd.revision < 1) {
+          issues.push(`${stageName}: 状态为 revising 但 revision 缺失或为 0`);
+        }
+        if (!sd.reopenedFromStep) {
+          warnings.push(`${stageName}: 状态为 revising 但未记录 reopenedFromStep`);
+        }
+      }
+
+      // c. stale stage 应有 staleReason
+      if (sd.status === 'stale') {
+        if (!sd.staleReason) {
+          warnings.push(`${stageName}: 状态为 stale 但缺少 staleReason`);
+        }
+      }
+
+      // d. 下游 completed 不能出现在上游 stale/revising 之后
+      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      for (let i = 0; i < stageIdx; i++) {
+        const upstream = STAGE_ORDER[i];
+        const upData = data.stages[upstream];
+        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
+          if (sd.status === 'completed') {
+            issues.push(`${stageName}: 状态为 completed，但上游 ${upstream} 状态为 ${upData.status}（下游不应在上游修订/失效时保持 completed）`);
+          }
+        }
+      }
+
+      // e. step stale 时 stage 不应是 completed
+      if (sd.status === 'completed' && sd.steps) {
+        const staleSteps = sd.steps.filter(s => s.status === 'stale');
+        for (const step of staleSteps) {
+          issues.push(`${stageName}/${step.name}: step 状态为 stale，但 stage 状态为 completed`);
+        }
+      }
+    }
+
+    // 输出报告
+    console.log('');
+    console.log('  ═══════════════════════════════════════');
+    console.log('  状态一致性检查');
+    console.log('  ═══════════════════════════════════════');
+
+    if (issues.length === 0 && warnings.length === 0) {
+      console.log('  ✅ 未发现一致性问题');
+    } else {
+      if (issues.length > 0) {
+        console.log(`\n  ❌ 问题 (${issues.length}):`);
+        for (const issue of issues) console.log(`     - ${issue}`);
+      }
+      if (warnings.length > 0) {
+        console.log(`\n  ⚠️ 警告 (${warnings.length}):`);
+        for (const w of warnings) console.log(`     - ${w}`);
+      }
+    }
+    console.log('');
+
+    return { ok: issues.length === 0, issues, warnings };
+  }
+
+  /**
+   * Revision v1.2 状态修复
+   * 默认 dry-run，--apply 才真正修改 DB。
+   * 只修安全项，不碰产物文件、不 reset/reopen stage。
+   *
+   * @param {string} cwd
+   * @param {object} opts
+   * @param {boolean} [opts.apply=false]
+   * @param {string|null} [opts.changeName]
+   * @returns {{ fixable: object[], manual: string[], applied: object[] }}
+   */
+  async repairConsistency(cwd, opts = {}) {
+    const { apply = false, changeName = null } = opts;
+
+    const data = await this.read(cwd, changeName);
+    if (!data) {
+      console.log('❌ 无法读取进度数据');
+      return { fixable: [], manual: ['无法读取进度数据'], applied: [] };
+    }
+
+    const fixable = []; // { stage, action, description, apply: (data) => void }
+    const manual = [];  // string
+
+    const now = new Date().toLocaleString('zh-CN', { hour12: false });
+
+    for (const stageName of STAGE_ORDER) {
+      const sd = data.stages[stageName];
+      if (!sd) continue;
+
+      // Fix a: stale stage 缺 staleReason → 补默认原因
+      if (sd.status === 'stale' && !sd.staleReason) {
+        const reason = stageName === 'archive'
+          ? 'upstream stage revised; existing archive artifacts are preserved but no longer trusted'
+          : 'unknown upstream revision';
+        fixable.push({
+          stage: stageName,
+          action: 'set_stale_reason',
+          description: `${stageName}: stale 缺 staleReason → 补 "${reason}"`,
+          apply: (d) => { d.stages[stageName].staleReason = reason; },
+        });
+      }
+
+      // Fix b: 上游 stale/revising，下游仍 completed → cascade stale
+      const stageIdx = STAGE_ORDER.indexOf(stageName);
+      for (let i = 0; i < stageIdx; i++) {
+        const upstream = STAGE_ORDER[i];
+        const upData = data.stages[upstream];
+        if (upData && (upData.status === 'stale' || upData.status === 'revising')) {
+          if (sd.status === 'completed') {
+            const upStatus = upData.status;
+            const reason = `upstream ${upstream} is ${upStatus}`;
+            fixable.push({
+              stage: stageName,
+              action: 'cascade_stale',
+              description: `${stageName}: completed → stale（上游 ${upstream} 为 ${upStatus}）`,
+              apply: (d) => {
+                d.stages[stageName].status = 'stale';
+                d.stages[stageName].staleReason = reason;
+                d.stages[stageName].completedAt = null;
+              },
+            });
+          }
+        }
+      }
+
+      // Fix c: archive stale 缺 staleReason（专用文案）
+      if (stageName === 'archive' && sd.status === 'stale' && !sd.staleReason) {
+        // 已在 Fix a 中处理，这里不重复
+      }
+
+      // Fix d: revising stage 缺 reopenedAt → 补当前时间
+      if (sd.status === 'revising' && !sd.reopenedAt) {
+        fixable.push({
+          stage: stageName,
+          action: 'set_reopened_at',
+          description: `${stageName}: revising 缺 reopenedAt → 补当前时间`,
+          apply: (d) => { d.stages[stageName].reopenedAt = now; },
+        });
+      }
+
+      // Manual a: completed stage 里有 pending/stale/in-progress steps
+      if (sd.status === 'completed' && sd.steps) {
+        const badSteps = sd.steps.filter(s => ['pending', 'stale', 'in-progress'].includes(s.status));
+        for (const step of badSteps) {
+          manual.push(`${stageName}/${step.name}: step 状态为 ${step.status}，但 stage 状态为 completed（需手动确认）`);
+        }
+      }
+
+      // Manual b: revising stage 缺 reopenedFromStep
+      if (sd.status === 'revising' && !sd.reopenedFromStep) {
+        manual.push(`${stageName}: revising 缺 reopenedFromStep（需手动确认修订起始步骤）`);
+      }
+
+      // Manual c: steps 为空但 stage completed
+      if (sd.status === 'completed' && (!sd.steps || sd.steps.length === 0)) {
+        manual.push(`${stageName}: completed 但 steps 为空（需手动确认）`);
+      }
+    }
+
+    // 输出报告
+    console.log('');
+    console.log('  ═══════════════════════════════════════');
+    console.log(`  状态修复 ${apply ? '（--apply 模式）' : '（dry-run 模式）'}`);
+    console.log('  ═══════════════════════════════════════');
+
+    if (fixable.length === 0 && manual.length === 0) {
+      console.log('  ✅ 未发现问题，无需修复');
+      console.log('');
+      return { fixable: [], manual: [], applied: [] };
+    }
+
+    const applied = [];
+
+    if (fixable.length > 0) {
+      console.log(`\n  🔧 可自动修复 (${fixable.length}):`);
+      for (const item of fixable) {
+        console.log(`     - ${item.description}`);
+        if (apply) {
+          item.apply(data);
+          applied.push({ stage: item.stage, action: item.action });
+        }
+      }
+      if (!apply) {
+        console.log('\n  💡 使用 --apply 执行修复');
+      }
+    }
+
+    if (manual.length > 0) {
+      console.log(`\n  👆 需手动处理 (${manual.length}):`);
+      for (const m of manual) console.log(`     - ${m}`);
+    }
+
+    if (apply && applied.length > 0) {
+      data.lastActive = now;
+      await this._write(cwd, data, changeName);
+      console.log(`\n  ✅ 已修复 ${applied.length} 项`);
+    }
+
+    console.log('');
+
+    return { fixable, manual, applied };
+  }
+
   async validate(cwd, changeName = null) {
     const data = await this.read(cwd, changeName);
     if (!data) { console.log('❌ 无法读取进度数据'); return false; }
@@ -1038,6 +1376,121 @@ export class ProgressManager {
     return true;
   }
 
+  /**
+   * 重新打开已完成的阶段进入修订模式
+   * - 不带 fromStep：只允许存在 pending/stale/waiting/failed 步骤时继续
+   * - 带 fromStep：从该步骤起，当前及后续步骤标记 stale/pending
+   * - 自动级联标记下游阶段为 stale
+   *
+   * @param {string} cwd
+   * @param {string} stage - 要重开的阶段
+   * @param {object} opts
+   * @param {string|number} [opts.fromStep] - 步骤名或序号（1-based）
+   * @param {string} [opts.changeName]
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  async reopenStage(cwd, stage, opts = {}) {
+    const { fromStep, changeName = null } = opts;
+
+    const data = await this.read(cwd, changeName);
+    if (!data) return { ok: false, error: '无法读取进度数据' };
+
+    const stageData = data.stages[stage];
+    if (!stageData) return { ok: false, error: `未知阶段: ${stage}` };
+
+    const steps = stageData.steps || [];
+
+    // 确定 fromStep 对应的 index
+    let fromIdx = null;
+    if (fromStep != null) {
+      if (typeof fromStep === 'number' || /^\d+$/.test(String(fromStep))) {
+        fromIdx = parseInt(String(fromStep), 10) - 1; // 1-based → 0-based
+        if (fromIdx < 0 || fromIdx >= steps.length) {
+          return { ok: false, error: `步骤序号超出范围: ${fromStep}（共 ${steps.length} 步）` };
+        }
+      } else {
+        // 按名称匹配
+        fromIdx = steps.findIndex(s => s.name === fromStep);
+        if (fromIdx === -1) {
+          return { ok: false, error: `步骤不存在: ${fromStep}` };
+        }
+      }
+    }
+
+    // 如果不带 fromStep，检查是否存在中断步骤
+    if (fromIdx === null) {
+      const hasInterrupted = steps.some(s =>
+        ['pending', 'stale', 'waiting', 'failed'].includes(s.status)
+      );
+      if (!hasInterrupted) {
+        return { ok: false, error: `阶段 ${stage} 所有步骤均已完成，请使用 --from-step 指定从哪一步开始修订` };
+      }
+      // 找到第一个中断步骤
+      fromIdx = steps.findIndex(s =>
+        ['pending', 'stale', 'waiting', 'failed'].includes(s.status)
+      );
+    }
+
+    // 执行重开操作
+    const newRevision = (stageData.revision || 0) + 1;
+    const fromStepName = steps[fromIdx].name;
+    const now = new Date().toLocaleString('zh-CN', { hour12: false });
+
+    // 更新步骤状态：fromStep 之前的保持 completed，fromStep 变 pending，之后的变 stale
+    for (let i = 0; i < steps.length; i++) {
+      if (i === fromIdx) {
+        steps[i].status = 'pending';
+        steps[i].completedAt = null;
+        steps[i].output = null;
+      } else if (i > fromIdx) {
+        steps[i].status = 'stale';
+        steps[i].completedAt = null;
+      }
+      // i < fromIdx: 保持原状（completed）
+    }
+
+    stageData.status = 'revising';
+    stageData.completedAt = null;
+    stageData.revision = newRevision;
+    stageData.reopenedFromStep = `${fromIdx + 1}: ${fromStepName}`; // 存 "index: name" 格式
+    stageData.reopenedAt = now;
+    stageData.steps = steps;
+
+    data.lastActive = now;
+    data.currentStage = stage;
+
+    await this._write(cwd, data, changeName);
+
+    // 级联标记下游阶段为 stale
+    const downstreamStages = this._getDownstreamStages(stage);
+    if (downstreamStages.length > 0) {
+      const data2 = await this.read(cwd, changeName); // 重新读取以获取最新状态
+      if (data2) {
+        for (const ds of downstreamStages) {
+          if (data2.stages[ds] && data2.stages[ds].status === 'completed') {
+            data2.stages[ds].status = 'stale';
+            data2.stages[ds].staleReason = `上游阶段 ${stage} 已修订 (revision ${newRevision})`;
+            data2.stages[ds].completedAt = null;
+          }
+        }
+        await this._write(cwd, data2, changeName);
+      }
+    }
+
+    return { ok: true, revision: newRevision, fromStep: fromStepName };
+  }
+
+  /**
+   * 获取指定阶段的下游主流程阶段列表
+   * @param {string} stage
+   * @returns {string[]}
+   */
+  _getDownstreamStages(stage) {
+    const idx = MAIN_FLOW_ORDER.indexOf(stage);
+    if (idx === -1) return [];
+    return MAIN_FLOW_ORDER.slice(idx + 1);
+  }
+
   async reset(cwd, stage, changeName = null) {
     if (stage) {
       const data = await this.read(cwd, changeName);