@gong-ym/ai-spec-auto 0.2.14 → 0.2.15

package/bin/archive-change.js

@@ -1,474 +1,560 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const runtimeState = require('./runtime-state');
-const {
-  resolveRuntimePaths,
-  getCandidatePaths,
-} = require('./runtime-paths');
-const { pushVisualRuntimeStateSnapshot, drainVisualRuntimeStatePushes } = require('../internal/visual-hooks/runtime-state-pusher');
-
-function printUsage() {
-  console.log(`Usage:
-  ai-spec-auto archive-change --target <dir> [--change-id <id>] [options]
-
-Options:
-  --target <dir>         Target project directory (default: .)
-  --change-id <id>       OpenSpec change id; if omitted, infer from .ai-spec/current-run.json
-  --complete-run         After archive, write runtime success and clear current inbox files
-  --json                 Print JSON result only
-  --pretty               Print readable summary (default)
-  --help                 Show this help
-`);
-}
-
-function parseArgs(argv) {
-  const args = [...argv];
-  const options = {
-    target: '.',
-    pretty: true,
-    json: false,
-  };
-
-  while (args.length > 0) {
-    const arg = args.shift();
-    switch (arg) {
-      case '--target':
-        options.target = args.shift();
-        break;
-      case '--change-id':
-        options.changeId = args.shift();
-        break;
-      case '--complete-run':
-        options.completeRun = true;
-        break;
-      case '--json':
-        options.json = true;
-        options.pretty = false;
-        break;
-      case '--pretty':
-        options.pretty = true;
-        options.json = false;
-        break;
-      case '--help':
-      case '-h':
-        options.help = true;
-        break;
-      default:
-        throw new Error(`Unknown argument: ${arg}`);
-    }
-  }
-
-  return options;
-}
-
-function readJsonIfExists(filePath) {
-  if (!fs.existsSync(filePath)) {
-    return null;
-  }
-  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-}
-
-function ensureDir(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
-}
-
-function listFilesRecursive(rootDir) {
-  if (!fs.existsSync(rootDir)) {
-    return [];
-  }
-
-  const files = [];
-  const stack = [rootDir];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    const entries = fs.readdirSync(current, { withFileTypes: true });
-    for (const entry of entries) {
-      const nextPath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(nextPath);
-      } else if (entry.isFile()) {
-        files.push(nextPath);
-      }
-    }
-  }
-
-  return files.sort();
-}
-
-function countTaskCompletion(tasksPath) {
-  if (!fs.existsSync(tasksPath)) {
-    return { completed: 0, total: 0 };
-  }
-
-  const content = fs.readFileSync(tasksPath, 'utf8');
-  const lines = content.split('\n');
-  let completed = 0;
-  let total = 0;
-
-  for (const line of lines) {
-    if (/^- \[[ xX]\]\s+/.test(line.trim())) {
-      total += 1;
-      if (/^- \[[xX]\]\s+/.test(line.trim())) {
-        completed += 1;
-      }
-    }
-  }
-
-  return { completed, total };
-}
-
-function normalizeMarkdown(content) {
-  return String(content || '').replace(/\r\n/g, '\n').trim();
-}
-
-function normalizeSpecsArtifactPath(relPath) {
-  const value = String(relPath || '').trim();
-  if (!value) {
-    return null;
-  }
-
-  const normalized = value.replace(/[\\/]+$/, '');
-  if (/[\\/]specs$/.test(normalized)) {
-    return normalized;
-  }
-
-  const match = normalized.match(/^(.*[\\/]specs)(?:[\\/].+)?$/);
-  return match ? match[1] : normalized;
-}
-
-function mergeSpecFile(targetPath, incomingContent, changeId) {
-  if (!fs.existsSync(targetPath)) {
-    fs.writeFileSync(targetPath, `${incomingContent.trim()}\n`, 'utf8');
-    return 'added';
-  }
-
-  const existingContent = fs.readFileSync(targetPath, 'utf8');
-  const normalizedExisting = normalizeMarkdown(existingContent);
-  const normalizedIncoming = normalizeMarkdown(incomingContent);
-
-  if (!normalizedIncoming || normalizedExisting === normalizedIncoming || normalizedExisting.includes(normalizedIncoming)) {
-    return 'unchanged';
-  }
-
-  const merged = [
-    existingContent.trimEnd(),
-    '',
-    `<!-- merged from change: ${changeId} -->`,
-    '',
-    normalizedIncoming,
-    '',
-  ].join('\n');
-  fs.writeFileSync(targetPath, merged, 'utf8');
-  return 'updated';
-}
-
-function resolveChangeId(targetDir, explicitChangeId) {
-  if (explicitChangeId) {
-    return explicitChangeId;
-  }
-
-  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
-  return currentRun?.task?.change_id || currentRun?.anchor?.task?.change_id || null;
-}
-
-function buildArchiveDestination(baseArchiveDir, changeId, now = new Date()) {
-  const day = now.toISOString().slice(0, 10);
-  const baseName = `${day}-${changeId}`;
-  let candidate = path.join(baseArchiveDir, baseName);
-  let suffix = 1;
-
-  while (fs.existsSync(candidate)) {
-    suffix += 1;
-    candidate = path.join(baseArchiveDir, `${baseName}-${suffix}`);
-  }
-
-  return candidate;
-}
-
-function buildAlreadyArchivedResult(targetDir, changeId) {
-  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
-  const proposalPath = currentRun?.artifacts?.proposal
-    ? path.join(targetDir, currentRun.artifacts.proposal)
-    : null;
-  const specsPath = currentRun?.artifacts?.specs
-    ? path.join(targetDir, normalizeSpecsArtifactPath(currentRun.artifacts.specs))
-    : null;
-  const designPath = currentRun?.artifacts?.design
-    ? path.join(targetDir, currentRun.artifacts.design)
-    : null;
-
-  if (!proposalPath || !specsPath || !designPath) {
-    return null;
-  }
-  if (!proposalPath.includes(`${path.sep}openspec${path.sep}changes${path.sep}archive${path.sep}`)) {
-    return null;
-  }
-  if (!fs.existsSync(proposalPath) || !fs.existsSync(specsPath) || !fs.existsSync(designPath)) {
-    return null;
-  }
-  if ((currentRun?.task?.change_id || currentRun?.anchor?.task?.change_id || null) !== changeId) {
-    return null;
-  }
-
-  const archivedDir = path.dirname(proposalPath);
-  const archivedRel = path.relative(targetDir, archivedDir);
-  return {
-    kind: 'archive-change-result',
-    status: 'success',
-    target: targetDir,
-    change_id: changeId,
-    archived_to: archivedRel,
-    archived_artifacts: {
-      proposal: path.relative(targetDir, proposalPath),
-      specs: path.relative(targetDir, specsPath),
-      design: path.relative(targetDir, designPath),
-      tasks: currentRun?.artifacts?.tasks || null,
-      checklist: currentRun?.artifacts?.checklist || null,
-      iterations: currentRun?.artifacts?.iterations || null,
-    },
-    merged: {
-      added_domains: [],
-      added_specs: [],
-      updated_specs: [],
-      unchanged_specs: [],
-    },
-    task_completion: countTaskCompletion(path.join(archivedDir, 'tasks.md')),
-    already_archived: true,
-  };
-}
-
-function clearCurrentRuntimeArtifacts(targetDir) {
-  const runtimePaths = resolveRuntimePaths(targetDir);
-  const entries = [
-    runtimePaths.currentDispatch,
-    runtimePaths.currentExecutionJson,
-    runtimePaths.currentExecutionMd,
-    runtimePaths.currentRuntimeActionJson,
-    runtimePaths.currentRuntimeActionMd,
-    runtimePaths.tmpCurrentDispatch,
-    runtimePaths.tmpCurrentExecution,
-    runtimePaths.tmpCurrentRuntimeAction,
-  ];
-
-  const cleared = {};
-  for (const entry of entries) {
-    let count = 0;
-    for (const candidate of getCandidatePaths(entry)) {
-      if (!fs.existsSync(candidate)) {
-        continue;
-      }
-      fs.unlinkSync(candidate);
-      count += 1;
-    }
-    cleared[entry.relPath] = count;
-  }
-
-  return cleared;
-}
-
-function completeRunAfterArchive(targetDir, archiveResult) {
-  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
-  if (!currentRun?.run_id) {
-    return null;
-  }
-
-  const runtimeResult = runtimeState.completeRunState({
-    target: targetDir,
-    runId: currentRun.run_id,
-    fromRole: currentRun.current_role || 'archive-change',
-    toRole: 'archive-change',
-    status: 'success',
-    message: '归档完成，增量规范已合并并已写入归档目录。',
-    artifactsData: archiveResult.archived_artifacts,
-    skipArtifactCheck: true,
-    clearPendingGate: true,
-  });
-  const cleared = clearCurrentRuntimeArtifacts(targetDir);
-
-  return {
-    ...runtimeResult,
-    cleared_runtime_artifacts: cleared,
-  };
-}
-
-function buildArchivedAdditionalArtifacts(currentArtifacts, changeId, archivedRelBase) {
-  const currentAdditional = Array.isArray(currentArtifacts?.additional) ? currentArtifacts.additional : [];
-  if (currentAdditional.length === 0) {
-    return [];
-  }
-
-  const activeBase = `openspec/changes/${changeId}`;
-  return currentAdditional
-    .map((item) => String(item || '').trim())
-    .filter(Boolean)
-    .map((item) => item.replace(/[\\/]+$/, ''))
-    .map((item) => {
-      if (item === activeBase || item.startsWith(`${activeBase}/`)) {
-        return item.replace(activeBase, archivedRelBase);
-      }
-      return item;
-    });
-}
-
-function archiveChange(options = {}) {
-  const targetDir = path.resolve(options.target || '.');
-  const changeId = resolveChangeId(targetDir, options.changeId);
-  if (!changeId) {
-    throw new Error('Missing change id: use --change-id or ensure .ai-spec/current-run.json contains task.change_id');
-  }
-
-  const changeDir = path.join(targetDir, 'openspec', 'changes', changeId);
-  if (!fs.existsSync(changeDir)) {
-    const alreadyArchived = buildAlreadyArchivedResult(targetDir, changeId);
-    if (!alreadyArchived) {
-      throw new Error(`OpenSpec change directory does not exist: ${path.relative(targetDir, changeDir)}`);
-    }
-    if (options.completeRun) {
-      alreadyArchived.runtime_transition = completeRunAfterArchive(targetDir, alreadyArchived);
-    }
-    return alreadyArchived;
-  }
-
-  const proposalPath = path.join(changeDir, 'proposal.md');
-  const tasksPath = path.join(changeDir, 'tasks.md');
-  const designPath = path.join(changeDir, 'design.md');
-  const checklistPath = path.join(changeDir, 'checklist.md');
-  const iterationsPath = path.join(changeDir, 'iterations.md');
-  const specsDir = path.join(changeDir, 'specs');
-
-  if (!fs.existsSync(proposalPath)) {
-    throw new Error(`proposal.md is missing for change ${changeId}`);
-  }
-  if (!fs.existsSync(tasksPath)) {
-    throw new Error(`tasks.md is missing for change ${changeId}`);
-  }
-  if (!fs.existsSync(designPath)) {
-    throw new Error(`design.md is missing for change ${changeId}`);
-  }
-  if (!fs.existsSync(specsDir)) {
-    throw new Error(`specs/ is missing for change ${changeId}`);
-  }
-
-  const targetSpecsDir = path.join(targetDir, 'openspec', 'specs');
-  ensureDir(targetSpecsDir);
-
-  const merged = {
-    added_domains: [],
-    added_specs: [],
-    updated_specs: [],
-    unchanged_specs: [],
-  };
-  const seenDomains = new Set();
-  const sourceSpecFiles = listFilesRecursive(specsDir);
-  for (const sourceFile of sourceSpecFiles) {
-    const relFromSpecs = path.relative(specsDir, sourceFile);
-    const domain = relFromSpecs.split(path.sep)[0] || null;
-    const targetFile = path.join(targetSpecsDir, relFromSpecs);
-    const targetDomainDir = path.dirname(targetFile);
-    const domainRel = domain ? path.join('openspec', 'specs', domain) : null;
-
-    if (domainRel && !fs.existsSync(targetDomainDir) && !seenDomains.has(domainRel)) {
-      ensureDir(targetDomainDir);
-      merged.added_domains.push(domainRel);
-      seenDomains.add(domainRel);
-    } else {
-      ensureDir(targetDomainDir);
-    }
-
-    const mergeStatus = mergeSpecFile(targetFile, fs.readFileSync(sourceFile, 'utf8'), changeId);
-    const relTargetFile = path.relative(targetDir, targetFile);
-    if (mergeStatus === 'added') {
-      merged.added_specs.push(relTargetFile);
-    } else if (mergeStatus === 'updated') {
-      merged.updated_specs.push(relTargetFile);
-    } else {
-      merged.unchanged_specs.push(relTargetFile);
-    }
-  }
-
-  const archiveRoot = path.join(targetDir, 'openspec', 'changes', 'archive');
-  ensureDir(archiveRoot);
-  const archivedPath = buildArchiveDestination(archiveRoot, changeId, options.now || new Date());
-  fs.renameSync(changeDir, archivedPath);
-  const archivedRelBase = path.relative(targetDir, archivedPath);
-  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
-
-  const result = {
-    kind: 'archive-change-result',
-    status: 'success',
-    target: targetDir,
-    change_id: changeId,
-    archived_to: archivedRelBase,
-    archived_artifacts: {
-      proposal: path.relative(targetDir, path.join(archivedPath, 'proposal.md')),
-      specs: path.relative(targetDir, path.join(archivedPath, 'specs')),
-      design: path.relative(targetDir, path.join(archivedPath, 'design.md')),
-      tasks: path.relative(targetDir, path.join(archivedPath, 'tasks.md')),
-      checklist: fs.existsSync(path.join(archivedPath, 'checklist.md'))
-        ? path.relative(targetDir, path.join(archivedPath, 'checklist.md'))
-        : null,
-      iterations: fs.existsSync(path.join(archivedPath, 'iterations.md'))
-        ? path.relative(targetDir, path.join(archivedPath, 'iterations.md'))
-        : null,
-      additional: buildArchivedAdditionalArtifacts(currentRun?.artifacts || null, changeId, archivedRelBase),
-    },
-    merged,
-    task_completion: countTaskCompletion(path.join(archivedPath, 'tasks.md')),
-  };
-
-  if (options.completeRun) {
-    result.runtime_transition = completeRunAfterArchive(targetDir, result);
-  }
-
-  pushVisualRuntimeStateSnapshot(targetDir);
-
-  return result;
-}
-
-function printPretty(result) {
-  console.log('archive-change');
-  console.log(`  target: ${result.target}`);
-  console.log(`  change_id: ${result.change_id}`);
-  console.log(`  archived_to: ${result.archived_to}`);
-  console.log(`  added_domains: ${result.merged.added_domains.length}`);
-  console.log(`  added_specs: ${result.merged.added_specs.length}`);
-  console.log(`  updated_specs: ${result.merged.updated_specs.length}`);
-  console.log(`  unchanged_specs: ${result.merged.unchanged_specs.length}`);
-  console.log(`  tasks: ${result.task_completion.completed}/${result.task_completion.total}`);
-  if (result.runtime_transition?.state?.status) {
-    console.log(`  run_status: ${result.runtime_transition.state.status}`);
-  }
-}
-
-async function main(argv = process.argv.slice(2)) {
-  const options = parseArgs(argv);
-  if (options.help) {
-    printUsage();
-    return 0;
-  }
-
-  const result = archiveChange(options);
-  await drainVisualRuntimeStatePushes();
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    printPretty(result);
-  }
-  return 0;
-}
-
-if (require.main === module) {
-  try {
-    main().then((code) => process.exit(code));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-}
-
-module.exports = {
-  archiveChange,
-  main,
-  parseArgs,
-};
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const runtimeState = require('./runtime-state');
+const {
+  resolveRuntimePaths,
+  getCandidatePaths,
+} = require('./runtime-paths');
+const { pushVisualRuntimeStateSnapshot, drainVisualRuntimeStatePushes } = require('../internal/visual-hooks/runtime-state-pusher');
+
+function printUsage() {
+  console.log(`Usage:
+  ai-spec-auto archive-change --target <dir> [--change-id <id>] [options]
+
+Options:
+  --target <dir>         Target project directory (default: .)
+  --change-id <id>       OpenSpec change id; if omitted, infer from .ai-spec/current-run.json
+  --complete-run         After archive, write runtime success and clear current inbox files
+  --json                 Print JSON result only
+  --pretty               Print readable summary (default)
+  --help                 Show this help
+`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    target: '.',
+    pretty: true,
+    json: false,
+  };
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    switch (arg) {
+      case '--target':
+        options.target = args.shift();
+        break;
+      case '--change-id':
+        options.changeId = args.shift();
+        break;
+      case '--complete-run':
+        options.completeRun = true;
+        break;
+      case '--json':
+        options.json = true;
+        options.pretty = false;
+        break;
+      case '--pretty':
+        options.pretty = true;
+        options.json = false;
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function listFilesRecursive(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const files = [];
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const nextPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(nextPath);
+      } else if (entry.isFile()) {
+        files.push(nextPath);
+      }
+    }
+  }
+
+  return files.sort();
+}
+
+function countTaskCompletion(tasksPath) {
+  if (!fs.existsSync(tasksPath)) {
+    return { completed: 0, total: 0 };
+  }
+
+  const content = fs.readFileSync(tasksPath, 'utf8');
+  const lines = content.split('\n');
+  let completed = 0;
+  let total = 0;
+
+  for (const line of lines) {
+    if (/^- \[[ xX]\]\s+/.test(line.trim())) {
+      total += 1;
+      if (/^- \[[xX]\]\s+/.test(line.trim())) {
+        completed += 1;
+      }
+    }
+  }
+
+  return { completed, total };
+}
+
+function generateArchiveSummary(archivedPath, changeId) {
+  const proposalPath = path.join(archivedPath, 'proposal.md');
+  const designPath = path.join(archivedPath, 'design.md');
+  const tasksPath = path.join(archivedPath, 'tasks.md');
+  const checklistPath = path.join(archivedPath, 'checklist.md');
+  const specMdPath = path.join(archivedPath, 'spec.md');
+
+  // 提取标题
+  let title = changeId;
+  if (fs.existsSync(proposalPath)) {
+    const content = fs.readFileSync(proposalPath, 'utf8');
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    if (titleMatch) title = titleMatch[1].trim();
+  }
+
+  // 提取业务目标（从 proposal）
+  let businessGoal = '';
+  if (fs.existsSync(proposalPath)) {
+    const content = fs.readFileSync(proposalPath, 'utf8');
+    // 找“业务目标”或“目标”部分
+    const goalMatch = content.match(/(?:业务目标|目标|## Goal)[^#]*?([\s\S]*?)(?=#|$)/i);
+    if (goalMatch) businessGoal = goalMatch[1].trim().slice(0, 300);
+  }
+
+  // 提取任务完成情况
+  const taskStats = countTaskCompletion(tasksPath);
+
+  // 提取关键设计决策（从 design）
+  let designDecisions = '';
+  if (fs.existsSync(designPath)) {
+    const content = fs.readFileSync(designPath, 'utf8');
+    const decisionMatch = content.match(/(?:设计决策|关键决策|技术方案|## Decision)[^#]*?([\s\S]*?)(?=##|$)/i);
+    if (decisionMatch) designDecisions = decisionMatch[1].trim().slice(0, 200);
+  }
+
+  // 提取验收结论（从 checklist）
+  let acceptance = '';
+  if (fs.existsSync(checklistPath)) {
+    const content = fs.readFileSync(checklistPath, 'utf8');
+    // 先匹配 ## 结论 / ## Conclusion 二级标题，再回退匹配 # 验收 / # 结论 一级标题
+    const conclusionMatch = content.match(/## (?:结论|Conclusion)[^#]*?([\s\S]*?)(?=##?\s|$)/i)
+      || content.match(/# (?:验收|结论)[^#]*?([\s\S]*?)(?=##?\s|$)/i);
+    if (conclusionMatch) acceptance = conclusionMatch[1].trim().slice(0, 200);
+  }
+
+  // 提取规格（从 spec.md 或 specs/ 目录）
+  let specSummary = '';
+  if (fs.existsSync(specMdPath)) {
+    specSummary = fs.readFileSync(specMdPath, 'utf8').trim().slice(0, 300);
+  }
+
+  const now = new Date().toISOString().slice(0, 10);
+  const summary = [
+    `# ${title}`,
+    '',
+    `> 归档日期：${now}  |  任务完成：${taskStats.completed}/${taskStats.total}`,
+    '',
+    businessGoal ? `## 业务目标\n\n${businessGoal}\n` : '',
+    specSummary ? `## 需求规格\n\n${specSummary}\n` : '',
+    designDecisions ? `## 设计决策\n\n${designDecisions}\n` : '',
+    acceptance ? `## 验收结论\n\n${acceptance}\n` : '',
+  ].filter(Boolean).join('\n');
+
+  const summaryPath = path.join(archivedPath, 'summary.md');
+  fs.writeFileSync(summaryPath, summary, 'utf8');
+  return summaryPath;
+}
+
+function cleanupProcessFiles(archivedPath) {
+  const processFiles = ['proposal.md', 'design.md', 'tasks.md', 'checklist.md', 'iterations.md', 'spec.md'];
+  const removed = [];
+  for (const file of processFiles) {
+    const filePath = path.join(archivedPath, file);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+
+function normalizeMarkdown(content) {
+  return String(content || '').replace(/\r\n/g, '\n').trim();
+}
+
+function normalizeSpecsArtifactPath(relPath) {
+  const value = String(relPath || '').trim();
+  if (!value) {
+    return null;
+  }
+
+  const normalized = value.replace(/[\\/]+$/, '');
+  if (/[\\/]specs$/.test(normalized)) {
+    return normalized;
+  }
+
+  const match = normalized.match(/^(.*[\\/]specs)(?:[\\/].+)?$/);
+  return match ? match[1] : normalized;
+}
+
+function mergeSpecFile(targetPath, incomingContent, changeId) {
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, `${incomingContent.trim()}\n`, 'utf8');
+    return 'added';
+  }
+
+  const existingContent = fs.readFileSync(targetPath, 'utf8');
+  const normalizedExisting = normalizeMarkdown(existingContent);
+  const normalizedIncoming = normalizeMarkdown(incomingContent);
+
+  if (!normalizedIncoming || normalizedExisting === normalizedIncoming || normalizedExisting.includes(normalizedIncoming)) {
+    return 'unchanged';
+  }
+
+  const merged = [
+    existingContent.trimEnd(),
+    '',
+    `<!-- merged from change: ${changeId} -->`,
+    '',
+    normalizedIncoming,
+    '',
+  ].join('\n');
+  fs.writeFileSync(targetPath, merged, 'utf8');
+  return 'updated';
+}
+
+function resolveChangeId(targetDir, explicitChangeId) {
+  if (explicitChangeId) {
+    return explicitChangeId;
+  }
+
+  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
+  return currentRun?.task?.change_id || currentRun?.anchor?.task?.change_id || null;
+}
+
+function buildArchiveDestination(baseArchiveDir, changeId, now = new Date()) {
+  const day = now.toISOString().slice(0, 10);
+  const baseName = `${day}-${changeId}`;
+  let candidate = path.join(baseArchiveDir, baseName);
+  let suffix = 1;
+
+  while (fs.existsSync(candidate)) {
+    suffix += 1;
+    candidate = path.join(baseArchiveDir, `${baseName}-${suffix}`);
+  }
+
+  return candidate;
+}
+
+function buildAlreadyArchivedResult(targetDir, changeId) {
+  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
+  const proposalPath = currentRun?.artifacts?.proposal
+    ? path.join(targetDir, currentRun.artifacts.proposal)
+    : null;
+  const specsPath = currentRun?.artifacts?.specs
+    ? path.join(targetDir, normalizeSpecsArtifactPath(currentRun.artifacts.specs))
+    : null;
+  const designPath = currentRun?.artifacts?.design
+    ? path.join(targetDir, currentRun.artifacts.design)
+    : null;
+
+  if (!proposalPath || !specsPath || !designPath) {
+    return null;
+  }
+  if (!proposalPath.includes(`${path.sep}openspec${path.sep}changes${path.sep}archive${path.sep}`)) {
+    return null;
+  }
+  if (!fs.existsSync(proposalPath) || !fs.existsSync(specsPath) || !fs.existsSync(designPath)) {
+    return null;
+  }
+  if ((currentRun?.task?.change_id || currentRun?.anchor?.task?.change_id || null) !== changeId) {
+    return null;
+  }
+
+  const archivedDir = path.dirname(proposalPath);
+  const archivedRel = path.relative(targetDir, archivedDir);
+  return {
+    kind: 'archive-change-result',
+    status: 'success',
+    target: targetDir,
+    change_id: changeId,
+    archived_to: archivedRel,
+    archived_artifacts: {
+      proposal: path.relative(targetDir, proposalPath),
+      specs: path.relative(targetDir, specsPath),
+      design: path.relative(targetDir, designPath),
+      tasks: currentRun?.artifacts?.tasks || null,
+      checklist: currentRun?.artifacts?.checklist || null,
+      iterations: currentRun?.artifacts?.iterations || null,
+    },
+    merged: {
+      added_domains: [],
+      added_specs: [],
+      updated_specs: [],
+      unchanged_specs: [],
+    },
+    task_completion: countTaskCompletion(path.join(archivedDir, 'tasks.md')),
+    already_archived: true,
+  };
+}
+
+function clearCurrentRuntimeArtifacts(targetDir) {
+  const runtimePaths = resolveRuntimePaths(targetDir);
+  const entries = [
+    runtimePaths.currentDispatch,
+    runtimePaths.currentExecutionJson,
+    runtimePaths.currentExecutionMd,
+    runtimePaths.currentRuntimeActionJson,
+    runtimePaths.currentRuntimeActionMd,
+    runtimePaths.tmpCurrentDispatch,
+    runtimePaths.tmpCurrentExecution,
+    runtimePaths.tmpCurrentRuntimeAction,
+  ];
+
+  const cleared = {};
+  for (const entry of entries) {
+    let count = 0;
+    for (const candidate of getCandidatePaths(entry)) {
+      if (!fs.existsSync(candidate)) {
+        continue;
+      }
+      fs.unlinkSync(candidate);
+      count += 1;
+    }
+    cleared[entry.relPath] = count;
+  }
+
+  return cleared;
+}
+
+function completeRunAfterArchive(targetDir, archiveResult) {
+  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
+  if (!currentRun?.run_id) {
+    return null;
+  }
+
+  const runtimeResult = runtimeState.completeRunState({
+    target: targetDir,
+    runId: currentRun.run_id,
+    fromRole: currentRun.current_role || 'archive-change',
+    toRole: 'archive-change',
+    status: 'success',
+    message: '归档完成，增量规范已合并并已写入归档目录。',
+    artifactsData: archiveResult.archived_artifacts,
+    skipArtifactCheck: true,
+    clearPendingGate: true,
+  });
+  const cleared = clearCurrentRuntimeArtifacts(targetDir);
+
+  return {
+    ...runtimeResult,
+    cleared_runtime_artifacts: cleared,
+  };
+}
+
+function buildArchivedAdditionalArtifacts(currentArtifacts, changeId, archivedRelBase) {
+  const currentAdditional = Array.isArray(currentArtifacts?.additional) ? currentArtifacts.additional : [];
+  if (currentAdditional.length === 0) {
+    return [];
+  }
+
+  const activeBase = `openspec/changes/${changeId}`;
+  return currentAdditional
+    .map((item) => String(item || '').trim())
+    .filter(Boolean)
+    .map((item) => item.replace(/[\\/]+$/, ''))
+    .map((item) => {
+      if (item === activeBase || item.startsWith(`${activeBase}/`)) {
+        return item.replace(activeBase, archivedRelBase);
+      }
+      return item;
+    });
+}
+
+function archiveChange(options = {}) {
+  const targetDir = path.resolve(options.target || '.');
+  const changeId = resolveChangeId(targetDir, options.changeId);
+  if (!changeId) {
+    throw new Error('Missing change id: use --change-id or ensure .ai-spec/current-run.json contains task.change_id');
+  }
+
+  const changeDir = path.join(targetDir, 'openspec', 'changes', changeId);
+  if (!fs.existsSync(changeDir)) {
+    const alreadyArchived = buildAlreadyArchivedResult(targetDir, changeId);
+    if (!alreadyArchived) {
+      throw new Error(`OpenSpec change directory does not exist: ${path.relative(targetDir, changeDir)}`);
+    }
+    if (options.completeRun) {
+      alreadyArchived.runtime_transition = completeRunAfterArchive(targetDir, alreadyArchived);
+    }
+    return alreadyArchived;
+  }
+
+  const proposalPath = path.join(changeDir, 'proposal.md');
+  const tasksPath = path.join(changeDir, 'tasks.md');
+  const designPath = path.join(changeDir, 'design.md');
+  const checklistPath = path.join(changeDir, 'checklist.md');
+  const iterationsPath = path.join(changeDir, 'iterations.md');
+  const specsDir = path.join(changeDir, 'specs');
+
+  if (!fs.existsSync(proposalPath)) {
+    throw new Error(`proposal.md is missing for change ${changeId}`);
+  }
+  if (!fs.existsSync(tasksPath)) {
+    throw new Error(`tasks.md is missing for change ${changeId}`);
+  }
+  if (!fs.existsSync(designPath)) {
+    throw new Error(`design.md is missing for change ${changeId}`);
+  }
+  if (!fs.existsSync(specsDir)) {
+    throw new Error(`specs/ is missing for change ${changeId}`);
+  }
+
+  const targetSpecsDir = path.join(targetDir, 'openspec', 'specs');
+  ensureDir(targetSpecsDir);
+
+  const merged = {
+    added_domains: [],
+    added_specs: [],
+    updated_specs: [],
+    unchanged_specs: [],
+  };
+  const seenDomains = new Set();
+  const sourceSpecFiles = listFilesRecursive(specsDir);
+  for (const sourceFile of sourceSpecFiles) {
+    const relFromSpecs = path.relative(specsDir, sourceFile);
+    const domain = relFromSpecs.split(path.sep)[0] || null;
+    const targetFile = path.join(targetSpecsDir, relFromSpecs);
+    const targetDomainDir = path.dirname(targetFile);
+    const domainRel = domain ? path.join('openspec', 'specs', domain) : null;
+
+    if (domainRel && !fs.existsSync(targetDomainDir) && !seenDomains.has(domainRel)) {
+      ensureDir(targetDomainDir);
+      merged.added_domains.push(domainRel);
+      seenDomains.add(domainRel);
+    } else {
+      ensureDir(targetDomainDir);
+    }
+
+    const mergeStatus = mergeSpecFile(targetFile, fs.readFileSync(sourceFile, 'utf8'), changeId);
+    const relTargetFile = path.relative(targetDir, targetFile);
+    if (mergeStatus === 'added') {
+      merged.added_specs.push(relTargetFile);
+    } else if (mergeStatus === 'updated') {
+      merged.updated_specs.push(relTargetFile);
+    } else {
+      merged.unchanged_specs.push(relTargetFile);
+    }
+  }
+
+  const archiveRoot = path.join(targetDir, 'openspec', 'changes', 'archive');
+  ensureDir(archiveRoot);
+  const archivedPath = buildArchiveDestination(archiveRoot, changeId, options.now || new Date());
+  fs.renameSync(changeDir, archivedPath);
+
+  // 先统计任务完成情况（在清理之前）
+  const taskCompletionStats = countTaskCompletion(path.join(archivedPath, 'tasks.md'));
+
+  // 生成精简 summary 并清理过程文件
+  const summaryPath = generateArchiveSummary(archivedPath, changeId);
+  const removedFiles = cleanupProcessFiles(archivedPath);
+
+  const archivedRelBase = path.relative(targetDir, archivedPath);
+  const currentRun = readJsonIfExists(path.join(targetDir, '.ai-spec', 'current-run.json'));
+
+  const result = {
+    kind: 'archive-change-result',
+    status: 'success',
+    target: targetDir,
+    change_id: changeId,
+    archived_to: archivedRelBase,
+    summary: path.relative(targetDir, summaryPath),
+    removed_process_files: removedFiles,
+    archived_artifacts: {
+      summary: path.relative(targetDir, summaryPath),
+      specs: fs.existsSync(path.join(archivedPath, 'specs'))
+        ? path.relative(targetDir, path.join(archivedPath, 'specs'))
+        : null,
+      additional: buildArchivedAdditionalArtifacts(currentRun?.artifacts || null, changeId, archivedRelBase),
+    },
+    merged,
+    task_completion: taskCompletionStats,
+  };
+
+  if (options.completeRun) {
+    result.runtime_transition = completeRunAfterArchive(targetDir, result);
+  }
+
+  pushVisualRuntimeStateSnapshot(targetDir);
+
+  return result;
+}
+
+function printPretty(result) {
+  console.log('archive-change');
+  console.log(`  target: ${result.target}`);
+  console.log(`  change_id: ${result.change_id}`);
+  console.log(`  archived_to: ${result.archived_to}`);
+  console.log(`  summary: ${result.summary}`);
+  console.log(`  cleaned: ${result.removed_process_files.join(', ') || '(none)'}`);
+  console.log(`  added_domains: ${result.merged.added_domains.length}`);
+  console.log(`  added_specs: ${result.merged.added_specs.length}`);
+  console.log(`  updated_specs: ${result.merged.updated_specs.length}`);
+  console.log(`  unchanged_specs: ${result.merged.unchanged_specs.length}`);
+  if (result.runtime_transition?.state?.status) {
+    console.log(`  run_status: ${result.runtime_transition.state.status}`);
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printUsage();
+    return 0;
+  }
+
+  const result = archiveChange(options);
+  await drainVisualRuntimeStatePushes();
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printPretty(result);
+  }
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    main().then((code) => process.exit(code));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  archiveChange,
+  main,
+  parseArgs,
+};