easy-coding-harness 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
+## 0.6.0
+
+- 状态机移除无实际工作内容的 `WAITING_CONFIRM`；阶段完成后通过 `task.json.pending_transition` 记录待确认边，状态仍停留在当前阶段，直到用户明确确认。
+- 所有合法阶段迁移默认统一提供“确认进入/返回目标阶段、交接给其他智能体、Other”三分支；优先使用智能体原生选项功能，纯文本编号仅作为无原生能力时的回退；handoff 会保留待确认边，下一智能体 claim 后可直接恢复该门禁。
+- 合并 `MEMORY_SHORT` 与 `MEMORY_LONG` 为单一 `MEMORY`：先写并检查点化短期记忆，再由状态 API 计算长期记忆 `no-op/distill` 指令，原阈值门禁保持不变。
+- MEMORY 短期记忆检查点校验 `memory_schema: 2`、`source_task` 当前任务归属和 SHA-256 内容指纹；长期记忆指令冻结 `candidate_files/kept_files`，只有明确候选允许被消费，保留项缺失或候选未清理均不能完成归档；旧 `MEMORY_LONG` 恢复通过显式兼容标记保留。
+- MEMORY 配置强制满足 `0 <= short_term_keep <= short_term_max`；非法窗口直接阻断并提示修正 config.yaml，避免超过阈值后出现零候选、无法收敛的空蒸馏循环。
+- 状态 API 新增 `request-transition`、`confirm-transition`、`cancel-transition` 以及 MEMORY 进度命令；hook 对用户输入完全只读，不再从原生选项、裸编号或自然语言自动写状态，所有确认均由智能体核对当前任务和目标状态后显式执行。
+- `easy-coding upgrade` 幂等迁移 0.5.x 活跃任务和 session：`WAITING_CONFIRM → ANALYSIS`、`MEMORY_SHORT/MEMORY_LONG → MEMORY`，同步清洗阶段历史并保留记忆恢复进度。
+- 工作流 skills、主约束、README、设计/介绍/使用文档及生成后 hook 测试全面对齐新状态模型。
+
 ## 0.5.3
 
 - 根治 `task.json` 绝对路径泄漏：`.easy-coding/tasks/project-init/task.json` 不再写入本机仓库绝对路径。该 `project_path` 字段无任何消费方，直接移除，可提交产物彻底去本地化。

package/README.md

@@ -69,20 +69,18 @@ easy-coding init --submodules packages/a,packages/b
 ## 工作流
 
 ```text
-INIT -> ANALYSIS -> WAITING_CONFIRM -> IMPLEMENT -> REVIEW -> VERIFICATION
-                          ^                ^                      |
-                          |                +---- repair loop -----+
-                          +--- revision ---+                      |
-                                                        [user acceptance]
-                                                                  |
-                                          MEMORY_SHORT -> MEMORY_LONG -> COMPLETE
+INIT -> ANALYSIS -> IMPLEMENT -> REVIEW -> VERIFICATION -> MEMORY -> COMPLETE
+          ^            ^          |             |
+          +-- replan ---+          +--- fix -----+
+                       ^                         |
+                       +------- repair ----------+
+every edge --[user confirmation by default]--> target stage
 any stage --[user abort via ec-task-close]--> CLOSED
 ```
 
-- `WAITING_CONFIRM` 是计划确认硬门控，未确认不进入实现。
+- 每个阶段完成后先记录 `pending_transition`，默认必须由用户确认才进入目标阶段；优先通过智能体原生选项功能选择确认、交接给其他智能体或使用 free-form Other，纯文本编号仅作回退。
 - `VERIFICATION` 是验证硬门控，未实际运行的 lint、typecheck、test 不算通过。
-- `MEMORY_SHORT` 写入本次任务短期记忆。
-- `MEMORY_LONG` 只有短期记忆数量超过阈值时才沉淀长期记忆，否则 no-op。
+- `MEMORY` 先写入本次任务短期记忆，再执行长期记忆阈值门禁；未超过阈值时长期沉淀为 no-op。
 
 ## Supermodule 模型
 

package/dist/cli.js

@@ -655,6 +655,11 @@ async function writeMemoryScaffold(easyCodingDir) {
 // src/utils/task-json.ts
 import { readdir } from "fs/promises";
 import path7 from "path";
+var LEGACY_STAGE_MAP = {
+  WAITING_CONFIRM: "ANALYSIS",
+  MEMORY_SHORT: "MEMORY",
+  MEMORY_LONG: "MEMORY"
+};
 function createProjectInitTask(params) {
   return {
     type: "project-init",
@@ -702,6 +707,132 @@ async function stripInitTaskProjectPath(cwd) {
   await writeTaskJson(filePath, task);
   return true;
 }
+function isLegacyStage(value) {
+  return typeof value === "string" && value in LEGACY_STAGE_MAP;
+}
+function migrateStage(value) {
+  return isLegacyStage(value) ? LEGACY_STAGE_MAP[value] : value;
+}
+function migrateStageHistory(task) {
+  if (!Array.isArray(task.stage_history)) return false;
+  let changed = false;
+  const migrated = [];
+  for (const rawEntry of task.stage_history) {
+    if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+      migrated.push(rawEntry);
+      continue;
+    }
+    const entry = { ...rawEntry };
+    const mappedStage = migrateStage(entry.stage);
+    if (mappedStage !== entry.stage) {
+      entry.stage = mappedStage;
+      changed = true;
+    }
+    const previous = migrated.at(-1);
+    if (previous && typeof previous === "object" && !Array.isArray(previous) && previous.stage === entry.stage) {
+      changed = true;
+      continue;
+    }
+    migrated.push(entry);
+  }
+  if (changed) task.stage_history = migrated;
+  return changed;
+}
+function migrateTaskWorkflowState(task) {
+  const legacyStatus = isLegacyStage(task.status) ? task.status : null;
+  const legacyRequestedAt = Array.isArray(task.stage_history) ? [...task.stage_history].reverse().find(
+    (entry) => entry && typeof entry === "object" && !Array.isArray(entry) && entry.stage === "WAITING_CONFIRM"
+  ) : null;
+  let changed = migrateStageHistory(task);
+  if (legacyStatus) {
+    task.status = LEGACY_STAGE_MAP[legacyStatus];
+    changed = true;
+  }
+  if (legacyStatus === "WAITING_CONFIRM" && !task.pending_transition) {
+    const requestedAt = legacyRequestedAt && typeof legacyRequestedAt === "object" && !Array.isArray(legacyRequestedAt) ? String(
+      legacyRequestedAt.entered_at ?? (/* @__PURE__ */ new Date()).toISOString()
+    ) : (/* @__PURE__ */ new Date()).toISOString();
+    task.pending_transition = {
+      from: "ANALYSIS",
+      to: "IMPLEMENT",
+      requested_at: requestedAt,
+      requested_by: String(task.last_agent ?? "upgrade-migration"),
+      reason: "migrated-from-WAITING_CONFIRM"
+    };
+    changed = true;
+  }
+  if (legacyStatus === "MEMORY_LONG") {
+    const progress = task.memory_progress && typeof task.memory_progress === "object" ? { ...task.memory_progress } : {};
+    if (progress.short_memory_written !== true) {
+      progress.short_memory_written = true;
+    }
+    progress.legacy_short_memory_assumed = true;
+    progress.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+    task.memory_progress = progress;
+    changed = true;
+  }
+  return changed;
+}
+async function taskFiles(cwd) {
+  const tasksDir = path7.join(cwd, EASY_CODING_DIR, TASKS_DIR);
+  if (!await pathExists(tasksDir)) return [];
+  const entries = await readdir(tasksDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => path7.join(tasksDir, entry.name, "task.json"));
+}
+async function sessionFiles(cwd) {
+  const sessionsDir = path7.join(cwd, EASY_CODING_DIR, SESSIONS_DIR);
+  if (!await pathExists(sessionsDir)) return [];
+  const entries = await readdir(sessionsDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => path7.join(sessionsDir, entry.name));
+}
+async function readJsonRecord(filePath) {
+  try {
+    const parsed = JSON.parse(await readTextFile(filePath));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function hasLegacyWorkflowState(cwd) {
+  for (const filePath of await taskFiles(cwd)) {
+    if (!await pathExists(filePath)) continue;
+    const task = await readJsonRecord(filePath);
+    if (!task) continue;
+    if (isLegacyStage(task.status) || Array.isArray(task.stage_history) && task.stage_history.some(
+      (entry) => entry && typeof entry === "object" && !Array.isArray(entry) && isLegacyStage(entry.stage)
+    )) {
+      return true;
+    }
+  }
+  for (const filePath of await sessionFiles(cwd)) {
+    const session = await readJsonRecord(filePath);
+    if (!session) continue;
+    if (isLegacyStage(session.last_seen_stage)) return true;
+  }
+  return false;
+}
+async function migrateLegacyWorkflowState(cwd) {
+  let tasksUpdated = 0;
+  let sessionsUpdated = 0;
+  for (const filePath of await taskFiles(cwd)) {
+    if (!await pathExists(filePath)) continue;
+    const task = await readJsonRecord(filePath);
+    if (!task) continue;
+    if (!migrateTaskWorkflowState(task)) continue;
+    await writeTextFile(filePath, JSON.stringify(task, null, 2));
+    tasksUpdated += 1;
+  }
+  for (const filePath of await sessionFiles(cwd)) {
+    const session = await readJsonRecord(filePath);
+    if (!session) continue;
+    const mappedStage = migrateStage(session.last_seen_stage);
+    if (mappedStage === session.last_seen_stage) continue;
+    session.last_seen_stage = mappedStage;
+    await writeTextFile(filePath, JSON.stringify(session, null, 2));
+    sessionsUpdated += 1;
+  }
+  return { tasksUpdated, sessionsUpdated };
+}
 async function setPendingInitSince(cwd, version) {
   const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
   if (!await pathExists(filePath)) return;
@@ -2849,7 +2980,7 @@ async function upgrade(opts) {
     ].filter(Boolean) : [],
     "Will overwrite managed skills, hooks, agents, templates, and generated main-constraint regions.",
     "Will update project-init task to recommend ec-init re-run for version adaptation.",
-    "Will not touch memory, state, spec, or project knowledge files."
+    "Will migrate legacy workflow stage metadata; memory content, spec, and project knowledge files remain untouched."
   ].join("\n");
   if (opts.dryRun) {
     console.log(summary);
@@ -2880,6 +3011,7 @@ async function upgrade(opts) {
     });
     await ensureEasyCodingSessionsIgnored(target.dir);
     await ensureHookBytecodeIgnored(target.dir);
+    await migrateLegacyWorkflowState(target.dir);
     await updateHarnessVersion(target.configPath, VERSION);
     await updateSupermoduleConfig(target.configPath, target.supermodule);
     await setPendingInitSince(target.dir, VERSION);
@@ -2921,7 +3053,7 @@ async function resolvePendingUpgradeTargets(targets) {
         `${target.label} harness version ${installedVersion} is newer than CLI ${VERSION}. Update the CLI first.`
       );
     }
-    if (relation === -1 || relation === 0 && await needsHookConfigRefresh(target, config)) {
+    if (relation === -1 || relation === 0 && (await needsHookConfigRefresh(target, config) || await hasLegacyWorkflowState(target.dir))) {
       pending.push({ target, config });
     }
   }