easy-coding-harness 0.5.2-beta.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@
 - `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` 字段无任何消费方，直接移除，可提交产物彻底去本地化。
+- `easy-coding upgrade` 会自动剥离存量项目中遗留的 `project_path` 字段，让老项目也随升级变干净。
+- 根治 hook 编译产物：hook launcher 设置 `sys.dont_write_bytecode=True`，运行时不再在 `.claude/hooks/`、`.codex/hooks/`、`.qoder/hooks/` 旁生成 `__pycache__/*.pyc`；同时 `init` / `add-agent` / `upgrade` 会向项目 `.gitignore` 追加 `__pycache__/` 作为兜底防御。launcher 内容变化会触发 `upgrade` 刷新存量 hook 注册。
+- 版本自 `0.5.2-beta.0` 升级为 `0.5.3`，合并 beta.0 的全部 portable hook 修复。跳过 `0.5.2` 正式版：升级检测的 `compareVersions` 会截断预发布后缀，若发 `0.5.2` 会把已安装 `0.5.2-beta.0` 的项目误判为已最新而不提示本次迁移；递增到 `0.5.3` 可让 beta 用户正确检测到升级。
+
 ## 0.5.2-beta.0
 
 - 修复 Claude Code hook 命令使用直接相对路径导致在子目录 cwd 下找不到 `.claude/hooks/*.py` 的问题；Claude、Codex、Qoder 的 hook 配置现在使用可共享的 portable relative launcher，并绑定 `.easy-coding/config.yaml` 的 `project.id`，避免把本机仓库绝对路径写入可提交配置，同时防止 supermodule 父仓 hook 被子仓 cwd 错路由。

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

@@ -208,6 +208,7 @@ var MAIN_SPEC_DIR = "main";
 var DEV_SPEC_DIR = "dev";
 var TEMPLATES_DIR = "templates";
 var SESSIONS_GITIGNORE_ENTRY = ".easy-coding/sessions/";
+var HOOK_BYTECODE_GITIGNORE_ENTRY = "__pycache__/";
 var GENERATED_REGION_START = "<!-- \u2550\u2550\u2550 easy-coding-harness generated (DO NOT EDIT BETWEEN MARKERS) \u2550\u2550\u2550 -->";
 var GENERATED_REGION_END = "<!-- \u2550\u2550\u2550 end easy-coding-harness generated \u2550\u2550\u2550 -->";
 
@@ -227,6 +228,13 @@ async function ensureGitignoreEntry(cwd, entry, heading = "# \u2550\u2550\u2550
 async function ensureEasyCodingSessionsIgnored(cwd) {
   return ensureGitignoreEntry(cwd, SESSIONS_GITIGNORE_ENTRY);
 }
+async function ensureHookBytecodeIgnored(cwd) {
+  return ensureGitignoreEntry(
+    cwd,
+    HOOK_BYTECODE_GITIGNORE_ENTRY,
+    "# \u2550\u2550\u2550 easy-coding-harness (auto-generated) \u2550\u2550\u2550\n# Python bytecode from hook scripts; do not commit"
+  );
+}
 
 // src/utils/install-manifest.ts
 import { createHash } from "crypto";
@@ -647,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",
@@ -658,7 +671,6 @@ function createProjectInitTask(params) {
     context: {
       agents_installed: params.agents,
       cli_version: VERSION,
-      project_path: params.cwd,
       init_source: params.initSource ?? "fresh",
       ...params.legacyAssets ? { legacy_assets: params.legacyAssets } : {},
       ...params.legacyMissingHarnessFiles ? { legacy_missing_harness_files: params.legacyMissingHarnessFiles } : {}
@@ -679,7 +691,6 @@ async function writeProjectInitTask(cwd, agents, options = {}) {
   await writeTaskJson(
     getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID),
     createProjectInitTask({
-      cwd,
       agents,
       initSource: options.initSource,
       legacyAssets: options.legacyAssets,
@@ -687,6 +698,141 @@ async function writeProjectInitTask(cwd, agents, options = {}) {
     })
   );
 }
+async function stripInitTaskProjectPath(cwd) {
+  const filePath = getTaskJsonPath(cwd, PROJECT_INIT_TASK_ID);
+  if (!await pathExists(filePath)) return false;
+  const task = await readTaskJson(filePath);
+  if (!task.context || !("project_path" in task.context)) return false;
+  task.context.project_path = void 0;
+  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;
@@ -830,6 +976,7 @@ function jsonStringContent(value) {
 }
 var HOOK_LAUNCHER_PYTHON = [
   "import io,json,os,re,runpy,sys",
+  "sys.dont_write_bytecode=True",
   "from pathlib import Path",
   "payload=sys.stdin.read()",
   "try:",
@@ -1264,6 +1411,7 @@ async function installHarnessToDir(targetDir, platforms, ctx) {
     legacyMissingHarnessFiles: ctx.legacyMissingHarnessFiles
   });
   await ensureEasyCodingSessionsIgnored(targetDir);
+  await ensureHookBytecodeIgnored(targetDir);
   return artifacts;
 }
 function supermoduleConfigFromContext(ctx) {
@@ -1759,6 +1907,7 @@ async function addAgent(opts) {
         mode: "merge"
       });
       await ensureEasyCodingSessionsIgnored(target.dir);
+      await ensureHookBytecodeIgnored(target.dir);
       await addAgentsToConfig(target.configPath, toInstall);
       await setPendingInitSince(target.dir, VERSION);
       installedLabels.push(`${target.label}: ${toInstall.join(", ")}`);
@@ -2831,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);
@@ -2861,9 +3010,12 @@ async function upgrade(opts) {
       artifacts
     });
     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);
+    await stripInitTaskProjectPath(target.dir);
   }
   if (parentTopologyRefresh) {
     await refreshSupermoduleParent(
@@ -2901,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 });
     }
   }