easy-coding-harness 0.1.8 → 0.3.0

package/templates/common/skills/ec-analysis/SKILL.md

@@ -3,6 +3,8 @@ name: ec-analysis
 description: ANALYSIS-stage skill. Use when ec-workflow enters ANALYSIS. Creates the dev-spec skeleton FIRST (template-first), then fills incrementally — producing the narrative plan, execution plan (execution.jsonl), and test strategy. Ends in WAITING_CONFIRM. Grounds every conclusion in real code, never restates the requirement.
 ---
 
+> **SKELETON FIRST — your first two tool calls MUST be: (1) Read `.easy-coding/templates/dev-spec-skeleton.md`, (2) Write its EXACT content to the task's dev-spec.md. No exceptions. Do not analyze or think before the skeleton file exists on disk.**
+
 # ec-analysis — turn a requirement into a confirmable plan
 
 ec-workflow dispatches you when a task enters ANALYSIS. You read the codebase, decide *how*
@@ -12,20 +14,44 @@ Communicate with the user in the user's language.
 
 ## HARD RULES (non-negotiable, violations = failed analysis)
 
-1. **Your FIRST tool call** in this skill MUST be a file-write that creates
-   `.easy-coding/tasks/{task-id}/dev-spec.md` with the COMPLETE template skeleton from the
-   "Required output" section below. No reading, no thinking out loud, no "let me analyze
-   first" — skeleton file FIRST. If this file does not exist after your first tool call, you
-   have already failed.
+1. **Your FIRST TWO tool calls** in this skill MUST be:
+   - **Call 1 (Read):** Read `.easy-coding/templates/dev-spec-skeleton.md`.
+   - **Call 2 (Write):** Write the EXACT content you just read to
+     `.easy-coding/tasks/{task-id}/dev-spec.md`. This is a mechanical copy — do not rephrase
+     headers, omit sections, rearrange content, or substitute placeholders with your own text.
+     The file content must be identical to the template you just read.
+   If dev-spec.md does not exist with the correct template after your second tool call,
+   you have already failed. Do not read code, think aloud, or analyze before the skeleton
+   is on disk.
 2. **All subsequent analysis** fills sections of this file via edits. You do NOT hold analysis
    in your head and dump it at the end — you write each section into the file as you go.
-3. **Your chat output to the user** MUST be the final content of dev-spec.md (copy it into
-   your reply or reference it). You MUST NOT invent a different, abbreviated format. No
-   "执行计划" summary tables, no bullet-point plans, no freestyle answers. The template IS
-   the format. If your reply to the user does not contain every mandatory section header from
-   the template, you have failed.
+3. **Your chat output to the user IS dev-spec.md, verbatim.** After dev-spec.md is complete,
+   use the Read tool to read it back, then output exactly what you read as your reply — this
+   is a copy operation, not a re-narration. Do NOT reconstruct it from memory, do NOT
+   abbreviate, do NOT invent a different format. No "执行计划" summary tables, no bullet-point
+   plans, no freestyle answers. The template IS the format. If your reply does not contain
+   every mandatory section header from the template, you have failed.
 4. **Three files must exist** in `.easy-coding/tasks/{task-id}/` when you finish:
    `dev-spec.md`, `execution.jsonl` (plan record), `test-strategy.md`. Missing any one = failed.
+5. **Stay faithful to the user's delivery form (anti-downgrade).** The delivery form —
+   change real code vs. produce a document — is set by the user's original request, NOT by
+   you. If the user asked to refactor / fix / add a feature (a CODE task), you MUST plan real
+   code changes. You may NOT downgrade it to "produce a report / audit / inventory only" or
+   "defer all changes to follow-up sub-tasks." A large change surface is NOT a reason to
+   downgrade: decompose it into batches/units in 实施拆解, and surface "split into batches? /
+   which subset this round?" as an explicit item in 待用户决策 for the user to decide. Never
+   make a scope-narrowing decision yourself and present it as settled. Never fabricate a
+   premise such as "the user already fixed scope X in INIT" or "auto_mode already selected Y"
+   to justify narrowing — `auto_mode` only waives the WAITING_CONFIRM confirmation step and
+   carries NO scope or delivery-form decision whatsoever.
+6. **改动范围 lists ONLY real project code.** The 改动范围 table carries only changes to real
+   project source/config files. Any harness artifact under `.easy-coding/` (dev-spec.md,
+   execution.jsonl, test-strategy.md, memory files, generated reports, etc.) is FORBIDDEN in
+   this table — those are process outputs, not "changes." The table MAY be empty, but ONLY
+   when the user explicitly asked for a no-code delivery form (e.g. a pure documentation
+   request); in that case declare the deliverable in 需求解析 > 输出. If the task type is a
+   code task (重构 / Bug 修复 / 新功能 / 性能优化) yet 改动范围 is empty, you have downgraded
+   the task — this is a failed analysis.
 
 ## Inputs to load (in this order)
 
@@ -44,16 +70,19 @@ Communicate with the user in the user's language.
 
 If the task spans repositories: declare them in the dev-spec (trigger repo + involved repos
 by **name**, never local paths). For each involved repo, read its ABSTRACT to understand the
-interface. Cache any local path the user provides only in `state.json.repo_paths`. If a repo
-name cannot be located locally, ask the user for the path before proceeding.
+interface. Cache any local path the user provides through the state API only:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py set-repo-path --session-file <P> --repo <repo-name> --path <local-path>`.
+If a repo name cannot be located locally, ask the user for the path before proceeding.
 
 ## Analysis procedure (mandatory sequence)
 
 You MUST execute these steps in exact order. Do not rearrange, skip, or combine steps.
 
-1. **Write skeleton** — FIRST tool call: write `.easy-coding/tasks/{task-id}/dev-spec.md`
-   using the full template from the next section. Every section header and every `{待填写}`
-   placeholder must be present. This is not optional.
+1. **Write skeleton** — FIRST TWO tool calls:
+   - Read `.easy-coding/templates/dev-spec-skeleton.md` (the template file).
+   - Write its exact content to `.easy-coding/tasks/{task-id}/dev-spec.md`.
+   This is a copy operation, not a generation task. Every section header and every `{待填写}`
+   placeholder in the template must appear in the written file unchanged.
 2. **Fill 项目模式 + 任务类型** — edit dev-spec.md in place.
 3. **Fill 需求解析** — edit dev-spec.md: 目标 / 输入 / 输出 / 边界.
 4. **Read source code, fill 现状** — read the actual files, then edit dev-spec.md with
@@ -67,113 +96,55 @@ You MUST execute these steps in exact order. Do not rearrange, skip, or combine
 10. **Write execution.jsonl** — append the plan record (see section below).
 11. **Write test-strategy.md** — write the testability table (see section below).
 12. **Self-check** — run the gates below. Fix any failure in the files.
-13. **Present to user** — output the FINAL content of dev-spec.md to the user as your reply.
-    Do not summarize, abbreviate, or reformat. The dev-spec.md content IS your reply.
-
-## Required output: dev-spec.md template
-
-The skeleton below is the EXACT file you MUST write as step 1. Copy it character-for-character
-into `.easy-coding/tasks/{task-id}/dev-spec.md`. Do not rephrase headers, do not omit
-sections, do not invent alternative formats. Later steps fill the `{待填写}` placeholders
-via edits. Conditional sections are added only if applicable.
-
-````markdown
-[阶段：ANALYSIS]
-
-## 技术方案：{任务标题}
-
-### 项目模式
-{初创项目/迭代项目}
-
-### 任务类型
-{新功能 / Bug 修复 / 重构 / 性能优化 / 前端设计实现}
-
-### 需求解析
-- **目标**：{待填写 — 真正要解决的问题}
-- **输入**：{待填写 — 用户输入 / 系统输入 / 触发条件}
-- **输出**：{待填写 — 最终交付结果}
-- **边界**：{待填写 — 明确不做什么}
-
-### 现状
-- **相关代码 / 页面 / 接口 / 模块**：{待填写 — 基于实际文件与代码的现状说明}
-- **当前实现方式**：{待填写 — 现在是如何工作的}
-- **现有问题 / 缺口**：{待填写 — 为什么需要改}
-- **证据**：{待填写 — 引用的关键文件、类、页面、接口，含 file:line}
-
-### 冲突摘要
-- 需求 vs RULES：{待填写 或 "无冲突"}
-- 需求 vs ABSTRACT：{待填写 或 "无冲突"}
-- 需求 vs 现有代码：{待填写 或 "无冲突"}
-- Dev-Spec vs 现有代码：{待填写 或 "无冲突"}
-
-### 待用户决策
-- {待填写 — 影响技术路线、接口、改动范围的问题逐条列出；若无则写"无"}
-
-### 影响面分析
-- **涉及模块**：{待填写}
-- **核心类 / 页面 / 接口**：{待填写}
-- **数据库变更**：{有/无}
-- **接口变更**：{有/无}
-- **关联历史任务**：{待填写 — 相关短期记忆序号；无则"无"}
-
-### 改动范围
-| 改动文件 | 改动类型 | 文件编码 | 改动核心内容 |
-|----------|---------|---------|-------------|
-| `{文件路径}` | 新增 | 项目编码 {X}，依据：{xxx} | {核心改动} |
-| `{文件路径}` | 修改 | 保持原编码 {X} | {核心改动} |
-| `{文件路径}` | 删除 | — | {删除原因} |
-
-### 修改方案
-- **总体改法**：{待填写 — 一句话说清改哪里、怎么改}
-- **后端改动**：{待填写；不涉及则写"不涉及"}
-- **前端改动**：{待填写；不涉及则写"不涉及"}
-- **兼容处理**：{待填写 — 旧逻辑如何迁移、保留或替换}
-- **风险点**：{待填写 — 最容易出问题的位置}
-
-### 实施拆解
-
-| 单元 | 说明 | 类型 | 涉及文件 | 依赖 |
-|------|------|------|---------|------|
-| U1 | {title} | {backend/frontend/test/...} | {files} | — |
-| U2 | {title} | {type} | {files} | — |
-| U3 | {title} | {type} | {files} | U1, U2 |
-
-**执行策略**：{parallel / sequential / single}
-- 第一批（并行）：U1 {title} ｜ U2 {title}
-- 第二批（等待第一批）：U3 {title}
-（若 single：单一实施单元，主 agent 直接执行）
-
-### 测试策略
-
-| 测试点 | 级别 | 归属单元 | 方式 | 验证命令 |
-|--------|------|---------|------|---------|
-| {描述} | 必测 | U1 | 单测 | `npm test -- --filter=xxx` |
-| {描述} | 应测 | U2 | 快照 | `npm test -- --snapshot` |
-
-- **人工验收**：{待填写 — 用户需要检查的关键行为}
-- **无法验证项**：{待填写 — 无 / 说明缺失环境、数据或权限}
-
-### 风险与注意事项
-- {风险 1}
-- {风险 2}
-````
-
-> **编码规则**：修改已有文件必须保持原始编码；新文件声明项目编码并附证据；证据冲突或
-> 未知时标记"需用户确认"。用户可在确认前覆盖任何编码单元格。
-
-**条件展开章节**（仅在满足条件时添加，否则完全不出现）：
-
-- `### 背景数据应用` — 命中项目知识资产（ABSTRACT.md、BUSINESS.md、TECHNICAL.md、RULES.md）
-  且其内容影响本次方案时展开。含架构参考、业务记忆、技术记忆、记忆冲突、规范约束。
-- `### 核心改动明细` — 多模块且改动范围表不足以表达当前逻辑和目标逻辑时展开。
-  逐文件列出"当前逻辑 → 准备怎么改"。
-- `### 前端实现映射` — 涉及前端页面、组件、交互时展开。含页面/模块映射、组件映射、
-  数据来源、Mock 使用计划。
-
-**禁止输出**：
-- 仅复述需求、几乎不引用代码现状的空泛方案。
-- 只列"已加载哪些信息"但不给出具体可实施改法。
-- 为了凑格式输出与本次任务无关的条件章节。
+13. **Present to user** — Read dev-spec.md back from disk and output exactly what you read as
+    your reply. Do not summarize, abbreviate, reformat, or reconstruct from memory. The
+    dev-spec.md content on disk IS your reply.
+
+## Required output: dev-spec.md structure
+
+The template lives at `.easy-coding/templates/dev-spec-skeleton.md`. You MUST read it with
+the Read tool and write its exact content to the task's dev-spec.md as step 1. Do NOT generate
+the skeleton from memory or from this instruction — READ the file and WRITE what you read.
+
+If `.easy-coding/templates/dev-spec-skeleton.md` does not exist, tell the user to run
+`easy-coding upgrade` in the terminal to restore it. Do not generate the skeleton from memory.
+
+If the hook injects `[easy-coding:analysis-template-drift:missing:...]`, you have deviated
+from the template. Re-read the template file, compare it against your dev-spec.md, and fix
+any missing or renamed section headers immediately.
+
+**Mandatory section headers** (all 13 must be present in the skeleton — the hook validates these):
+
+1. `## 技术方案`
+2. `### 项目模式`
+3. `### 任务类型`
+4. `### 需求解析`
+5. `### 现状`
+6. `### 冲突摘要`
+7. `### 待用户决策`
+8. `### 影响面分析`
+9. `### 改动范围`
+10. `### 修改方案`
+11. `### 实施拆解`
+12. `### 测试策略`
+13. `### 风险与注意事项`
+
+> **Encoding rule**: modified files keep their original encoding; new files declare the
+> project encoding with evidence; conflicting or unknown encoding → mark "需用户确认".
+> Users can override any encoding cell at confirmation.
+
+**Conditional sections** (add only when applicable, otherwise omit entirely):
+
+- `### 背景数据应用` — project knowledge assets (ABSTRACT.md, BUSINESS.md, TECHNICAL.md,
+  RULES.md) are relevant and influence the plan.
+- `### 核心改动明细` — multi-module change where the scope table is insufficient to express
+  current logic and target logic.
+- `### 前端实现映射` — frontend pages, components, or interactions are involved.
+
+**Forbidden output:**
+- Restating requirements without citing code evidence.
+- Listing "loaded information" without a concrete implementation approach.
+- Including conditional sections that are irrelevant to the current task.
 
 ## Implementation units → execution.jsonl
 
@@ -184,10 +155,13 @@ Decompose the work into units, then append ONE `plan` record to
 {"type":"plan","strategy":"parallel","units":[{"id":"U1","title":"...","type":"backend","files":["..."],"depends_on":[],"rules_sections":["naming","error-handling"],"abstract_modules":["user-service"]}],"parallel_groups":[{"level":0,"units":["U1","U2"]},{"level":1,"units":["U3"]}]}
 ```
 
-Strategy selection (drives whether ec-implementing spawns sub-agents):
-- `single` — one unit. Main agent implements directly.
-- `sequential` — multiple units with a hard dependency chain.
-- `parallel` — two or more independent units. ec-implementing MUST use sub-agents.
+Strategy selection (drives ec-implementing's sub-agent orchestration shape — every strategy
+dispatches sub-agents; none implements inline):
+- `single` — one unit. ec-implementing dispatches one sub-agent.
+- `sequential` — multiple units with a hard dependency chain. ec-implementing dispatches
+  sub-agents one at a time in dependency order.
+- `parallel` — two or more independent units. ec-implementing dispatches sub-agents per level
+  concurrently.
 
 Each unit carries `rules_sections` and `abstract_modules` so ec-implementing can build a
 precise task card without the sub-agent re-reading the whole repo. `depends_on` sets the
@@ -226,7 +200,7 @@ VERIFICATION baseline).
 - [ ] `dev-spec.md` 文件是否已写入 `.easy-coding/tasks/{task-id}/`？
 - [ ] `execution.jsonl` 文件是否已写入？
 - [ ] `test-strategy.md` 文件是否已写入？
-- [ ] dev-spec.md 是否包含全部 12 个核心章节标题？
+- [ ] dev-spec.md 是否包含全部 13 个必填章节标题（参见上方清单）？
 - [ ] 每个"现状"断言是否引用了真实文件/类/行号？
 - [ ] 是否有具体的修改方案，而非仅罗列"已加载的文件"？
 - [ ] 不适用的条件章节是否已完全省略（而非留空）？
@@ -234,9 +208,15 @@ VERIFICATION baseline).
 - [ ] 改动范围表中每行是否填写了文件编码及证据？
 - [ ] 所有 `{待填写}` 占位符是否已替换为实际内容？
 - [ ] 回复给用户的内容是否是 dev-spec.md 的完整内容（而非自创的缩略格式）？
+- [ ] 交付形态是否忠于用户原始需求？代码类任务（重构/修复/功能）是否规划了真实代码改动，而非降级为"仅出报告/分析清单/留作后续子任务"？
+- [ ] 「改动范围」是否只含真实项目源码/配置，且不含任何 `.easy-coding/` 下的 harness 产物（dev-spec/execution/test-strategy/记忆/报告）？
+- [ ] 若「改动范围」为空，是否确为用户明确要求的无代码交付形态，而非 AI 自行降级的结果？
+- [ ] 任何"本次不做全部 / 分批落地 / 范围收窄"的决定，是否已列入「待用户决策」交由用户拍板，而非自行拍板并假托既定？
 
 ## Revision handling
 
+> 修订同样受 HARD RULE 5/6 约束：用户的修订诉求若是扩大或细化代码改动，不得借机把任务降级为"出报告"；范围收窄仍须作为 待用户决策 项由用户确认。
+
 On user revision request at WAITING_CONFIRM, do NOT reply with only a change summary.
 Re-output the COMPLETE revised dev-spec.md:
 
@@ -250,6 +230,7 @@ Re-output the COMPLETE revised dev-spec.md:
 
 ## End state
 
-Output the COMPLETE content of dev-spec.md as your reply to the user — not a summary, not a
-different format, not a table you invented. Then set stage to WAITING_CONFIRM and hand
-control back to ec-workflow. Never start implementing from this skill.
+Read dev-spec.md back from disk and output the COMPLETE content as your reply to the user —
+not a summary, not a different format, not a table you invented. Then set stage to
+WAITING_CONFIRM and hand control back to ec-workflow. Never start implementing from this
+skill.

package/templates/common/skills/ec-brainstorming/SKILL.md

@@ -78,5 +78,5 @@ be suspended (ec-workflow's intent routing handles the rest).
 
 - Write no implementation code, scaffold nothing, take no implementation action.
 - The only ec-* skill you may invoke is `ec-workflow` (on user confirmation after approval).
-  Do not touch state.json or the state machine directly.
+  Do not touch session files, task status fields, or the state machine directly.
 - One question per message — never overwhelm.

package/templates/common/skills/ec-git/SKILL.md

@@ -6,8 +6,8 @@ description: Git discipline skill for Easy Coding projects. Use when the task in
 # ec-git — git discipline
 
 Activate for any git operation inside an Easy Coding project: pull, merge, rebase, commit,
-push, PR. You manage git hygiene only — you never change `state.json` stage fields or trigger
-stage transitions.
+push, PR. You manage git hygiene only — you never change session files, task status fields,
+or trigger stage transitions.
 
 Communicate with the user in the user's language.
 
@@ -15,7 +15,7 @@ Communicate with the user in the user's language.
 
 | Path | In commit set? | Why |
 |---|---|---|
-| `state.json` | **never** | personal runtime state, differs per developer |
+| `sessions/` | **never** | personal runtime state, differs per developer |
 | `config.yaml` | yes | shared team config |
 | `tasks/*/task.json` `dev-spec.md` `execution.jsonl` `test-strategy.md` | yes | per-task folders, no merge conflicts; team-readable decision record |
 | `SOUL.md` `RULES.md` `ABSTRACT.md` `TEST_STRATEGY.md` `CHANGELOG.md` | yes | shared project knowledge |
@@ -24,7 +24,7 @@ Communicate with the user in the user's language.
 | `spec/dev/` | only if user explicitly asks | dev-spec candidates for the *current* requirement, default out of commit |
 
 `.easy-coding/` changes are part of the commit set by default (treated like code changes),
-with `state.json` always excluded. The CLI already added `state.json` to `.gitignore`.
+with `.easy-coding/sessions/` always excluded. The CLI already added it to `.gitignore`.
 
 ## Rules
 
@@ -33,15 +33,15 @@ with `state.json` always excluded. The CLI already added `state.json` to `.gitig
 2. **Conflict handling for `.easy-coding/`** (mostly `memory/`): first explain the conflict
    details to the user, get confirmation, then do an inductive semantic merge — never blindly
    pick ours/theirs. This requirement applies only to conflicts inside `.easy-coding/`.
-3. **Cross-repo commit sets.** When a task spans repos (per the dev-spec / `state.json`
-   `repo_paths`), the commit/push covers every involved repo. Read `repo_paths` to locate
-   each one, check changes, and commit/push them as one coherent change set — do not leave a
-   sub-repo behind.
+3. **Cross-repo commit sets.** When a task spans repos (per the dev-spec / current task
+   `repo_paths`), the commit/push covers every involved repo. Read `repo_paths` from the
+   current task state to locate each checkout, check changes, and commit/push them as one
+   coherent change set — do not leave a sub-repo behind.
 4. **No false success.** Never claim a commit or push succeeded without reading the command
    output. A failed push reported as success is a serious error.
 
 ## Boundaries
 
-- Do not touch `state.json` stage fields or run stage transitions — git only.
-- Do not commit `state.json`.
+- Do not touch session files, task status fields, or run stage transitions — git only.
+- Do not commit `.easy-coding/sessions/`.
 - Do not commit `spec/dev/` unless the user explicitly asks.

package/templates/common/skills/ec-implementing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ec-implementing
-description: IMPLEMENT-stage skill. Use when ec-workflow enters IMPLEMENT with a confirmed plan. Executes execution.jsonl units under strict file-scope control, enforces RULES compliance and encoding preservation, writes tests per strategy, and dispatches sub-agents for parallel work.
+description: IMPLEMENT-stage skill. Use when ec-workflow enters IMPLEMENT with a confirmed plan. Executes execution.jsonl units under strict file-scope control, enforces RULES compliance and encoding preservation, writes tests per strategy, and dispatches sub-agents for every unit regardless of strategy.
 ---
 
 # ec-implementing — execute the confirmed plan
@@ -33,38 +33,45 @@ Communicate with the user in the user's language.
 
 ## Sub-agent dispatch
 
-Read the `plan` record's `strategy` field. Then:
+Read the `plan` record's `strategy` field. EVERY strategy dispatches sub-agents — the field
+only decides the orchestration shape, never whether the main agent writes code itself:
 
-- `single` → main agent implements directly, no sub-agents.
-- `sequential` → main agent implements units one by one in dependency order.
-- `parallel` → sub-agents are MANDATORY (see gate below).
+- `single` → dispatch ONE sub-agent for the single unit.
+- `sequential` → dispatch sub-agents one at a time in dependency order (await each `result`
+  before dispatching the next).
+- `parallel` → dispatch sub-agents per level concurrently (see gate below).
 
 <HARD-GATE>
-PARALLEL STRATEGY = MANDATORY SUB-AGENT DISPATCH. NO EXCEPTIONS.
+EVERY STRATEGY = MANDATORY SUB-AGENT DISPATCH. NO EXCEPTIONS.
 
-If the plan record says `"strategy":"parallel"`, you MUST dispatch sub-agents using
-{{sub_agent_dispatch}}. You are FORBIDDEN from implementing parallel units yourself.
-Doing the work inline instead of dispatching is a protocol violation equivalent to
-skipping WAITING_CONFIRM.
+You MUST dispatch sub-agents using {{sub_agent_dispatch}} for every unit, whatever the
+strategy. You are FORBIDDEN from implementing any unit yourself in the main agent. Doing the
+work inline instead of dispatching is a protocol violation equivalent to skipping
+WAITING_CONFIRM.
 
 Self-check before writing ANY implementation code:
-- Is strategy "parallel"? → Did I dispatch via {{sub_agent_dispatch}}? If no → STOP.
-- Am I working on a unit in a parallel level without dispatching? → STOP.
+- Am I about to write implementation code in the main agent? → STOP. Dispatch a sub-agent.
+- Did every unit get a dispatch (single=1, sequential=N serial, parallel=N concurrent)? If no → STOP.
 
-The ONLY case where you implement code directly is strategy "single" or "sequential".
+There is NO case where the main agent writes implementation code itself. Even a single unit
+goes through a sub-agent — this isolates implementation context from the main agent's window.
 </HARD-GATE>
 
-Parallel dispatch loop:
-1. Sort `parallel_groups` by level.
-2. Read RULES.md and ABSTRACT.md once.
-3. For each unit in the current level, build a **task card** (next section) and dispatch.
-4. Dispatch all units in the level concurrently via {{sub_agent_dispatch}}.
+## Dispatch loop (all strategies)
+
+1. Read RULES.md and ABSTRACT.md once — the main agent pre-digests context; sub-agents never
+   read them.
+2. For each unit, build a **task card** (next section). Append a `dispatch` record before
+   dispatching and a `result` record per returned unit, to execution.jsonl.
+3. Dispatch according to strategy, via {{sub_agent_dispatch}}:
+   - `single` → dispatch the one unit, await its `result`.
+   - `sequential` → sort units by `depends_on`; dispatch one, await its `result`, then the next.
+   - `parallel` → sort `parallel_groups` by level; dispatch all units in a level concurrently,
+     await the level, then advance.
    Platform spawn rule: {{platform_spawn_instruction}}
-5. Append a `dispatch` record per unit, then a `result` record per returned unit, to
-   execution.jsonl.
-6. After the level returns: check for file conflicts (two units touched the same file),
+4. After each unit/level returns: check for file conflicts (two units touched the same file),
    collect `issues` and `needs_attention`. Resolve conflicts before advancing.
-7. Advance to the next level. After all levels, summarize.
+5. After all units/levels, summarize.
 
 ## Task card — the sub-agent contract
 
@@ -105,8 +112,8 @@ hit something that invalidates the plan, return to ANALYSIS instead of improvisi
 
 ## Self-check gates (before handing back)
 
-- [ ] Strategy was "parallel" → ALL units dispatched via sub-agents? (VIOLATION if no)
-- [ ] Strategy was "sequential" → units implemented in dependency order?
+- [ ] EVERY unit was dispatched to a sub-agent — no inline implementation by the main agent? (VIOLATION if no)
+- [ ] Sequential units dispatched in dependency order; parallel units dispatched per level?
 - [ ] Each dispatched unit has a `dispatch` record in execution.jsonl?
 - [ ] Each returned unit has a `result` record?
 - [ ] No files modified outside the change-scope table?

package/templates/common/skills/ec-memory/SKILL.md

@@ -14,24 +14,41 @@ recorded comment/doc language.
 
 ## MEMORY_SHORT — write one short memory entry
 
-Create one file under `.easy-coding/memory/short/` with schema-v2 frontmatter:
+Create one file under `.easy-coding/memory/short/` following the format in
+`.easy-coding/memory/SHORT_MEMORY_TEMPLATE.md`. File naming convention:
+`{NNN}_{YYYYMMDD}_{smart_name}.md`. The entry is immutable after creation.
+Frontmatter (all fields required):
 
 ```yaml
 ---
+memory_schema: 2
 id: SM-{YYYYMMDD}-{NN}
 date: {YYYY-MM-DD}
-task_type: {feature | bugfix | refactor | perf}
-domain: {business domain}
-tags: [tag1, tag2]
-related_files: [file1, file2]
-target_long: {business | technical | both | none}
+task_type: {feature | bugfix | refactor | perf | doc | workflow}
+project_mode: {startup | iteration}
+domain:
+  - {business domain or module}
+tags:
+  - {keyword}
+related_files:
+  - {key file or module}
+commit: {hash | none}
+verification: {passed | partial | not_run}
+memory_value: {business | technical | both | none}
+target_long: {BUSINESS | TECHNICAL | BOTH | NONE}
 ---
-{body: what was done, why this approach, key decisions. Pull facts from execution.jsonl
-result/verify records, not from a fuzzy memory of the conversation.}
+The body follows the template structure: Task Summary, Execution Evidence, Business Memory
+Candidates, Technical Memory Candidates, Non-Distillation Content, and Related Memories.
+Pull facts from execution.jsonl result/verify records, not from a fuzzy memory of the
+conversation. Refer to SHORT_MEMORY_TEMPLATE.md for the complete section format.
 ```
 
 If the task was cross-repo, record the repo names involved and the collaboration reason.
 
+**Immutability:** Short memories are write-once. Never edit an existing short memory file —
+create a new one instead. Short memories serve as both a recent-detail sliding window and a
+distillation buffer for long-term memory.
+
 **Sliding window (informational):** The short memory directory has a soft cap defined by
 `memory.short_term_max` (default 10). MEMORY_SHORT only WRITES one entry per completed task
 — it never counts, trims, or triggers distillation. Trimming is exclusively MEMORY_LONG's
@@ -40,21 +57,25 @@ responsibility and only runs when the threshold is exceeded.
 ## MEMORY_LONG — distill durable knowledge (CONDITIONAL)
 
 <HARD-GATE>
-MEMORY_LONG IS A NO-OP WHEN SHORT MEMORY COUNT <= threshold.
+MEMORY_LONG IS CONTROLLED BY THE STATE API `memory_long` INSTRUCTION.
 
 Before performing ANY distillation work:
-1. Count `.md` files in `.easy-coding/memory/short/` (only files with schema-v2 frontmatter).
-2. Read `memory.short_term_max` from `.easy-coding/config.yaml` (default: 10).
-3. If count <= short_term_max: output "MEMORY_LONG: no-op (short memory count = {N},
+1. Read the `memory_long` object returned by the state API transition to MEMORY_LONG.
+   If it is not visible in context, re-run the same transition command for MEMORY_LONG to
+   re-emit the snapshot, then use that `memory_long` object.
+2. Treat `memory_long.action` as authoritative. Do NOT recount short memories yourself and
+   do NOT override the state API instruction with prompt reasoning.
+3. If `action == "no-op"`: output "MEMORY_LONG: no-op (short memory count = {short_count},
    threshold = {short_term_max})" and immediately hand back to ec-workflow to advance to
    COMPLETE. Do NOT read long memory files, do NOT attempt distillation, do NOT modify any file.
-4. If count > short_term_max: proceed with distillation below.
+4. If `action == "distill"`: distill exactly the older `trim_count` short-memory entries
+   and keep the latest `short_term_keep` entries.
 
 This gate is absolute. Even a single short memory entry below threshold does NOT trigger
 long-term compression regardless of any other signal.
 </HARD-GATE>
 
-### When count > threshold: distillation flow
+### When action == "distill": distillation flow
 
 Three-file long memory:
 - `MEMORY.md` — index of all entries with status (active | deprecated | superseded | deleted).
@@ -62,8 +83,8 @@ Three-file long memory:
 - `TECHNICAL.md` — architecture decisions, implementation patterns, gotchas.
 
 Distillation steps:
-1. Read `memory.short_term_keep` from config (default: 5). Keep the latest N entries;
-   the older entries become distillation candidates.
+1. Use `memory_long.short_term_keep` and `memory_long.trim_count`. Keep the latest
+   `short_term_keep` entries; the older `trim_count` entries become distillation candidates.
 2. Read the `target_long` of candidate short memories; route to business/technical.
 3. **Progressive loading** — read only the existing long entries matching this round's
    domain/tags/related_files. No unbounded whole-repo memory scan.
@@ -73,6 +94,10 @@ Distillation steps:
 5. **Retirement check**: for older entries decide delete (no value) / merge (semantic
    duplicate) / deprecate (was valid, now superseded).
 6. Update the `MEMORY.md` index to reflect every change.
+7. After the long-memory files and index are successfully written, delete the consumed
+   short-memory candidate files. Leave only the latest `short_term_keep` short memories.
+   This is sliding-window consumption after successful distillation, not destructive
+   deletion of durable long-term knowledge.
 
 ## ABSTRACT backfill / update
 

package/templates/common/skills/ec-reviewing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ec-reviewing
-description: REVIEW-stage skill. Use when ec-workflow enters REVIEW. Reviews changed files across correctness, RULES compliance, completeness, tests, and security; returns a graded verdict (accept/fix/replan/blocked) with file-and-line evidence; dispatches multi-dimension sub-agents when the change set is large.
+description: REVIEW-stage skill. Use when ec-workflow enters REVIEW. Reviews changed files across correctness, RULES compliance, completeness, tests, and security; returns a graded verdict (accept/fix/replan/blocked) with file-and-line evidence; dispatches multi-dimension sub-agents for every review regardless of change-set size.
 ---
 
 # ec-reviewing — graded, evidence-backed review

package/templates/common/skills/ec-task-close/SKILL.md

@@ -18,9 +18,10 @@ when you recognize abandonment intent in the user's message.
    Require an explicit yes. (Skip the confirm only if the task is already COMPLETE and the
    user just wants it tidied.)
 2. **Record the reason.** Capture the user's reason in one line.
-3. **Clean state:**
-   - `task.json`: `status` → `CLOSED`, `closed_reason` → "{reason}".
-   - `state.json`: `current_task` → null (leave `current_stage` as the hook will report idle).
+3. **Close through the state API:** run
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py close-current --session-file <P> --reason "<reason>" --agent <agent-id>`.
+   This sets `task.json.status` to `CLOSED`, records `closed_reason`, updates history, and
+   clears session `current_task` so the next hook injection returns to Ready.
 4. **No memory flow.** Do not run MEMORY_SHORT/LONG. An incomplete task's memory is dirty data.
 5. **Linked tasks.** If the task has `spawned_from` or `spawned_tasks`, note the closure fact
    on the relation so a future agent understands the chain.