easy-coding-harness 0.1.7 → 0.2.1

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

@@ -24,15 +24,20 @@ NO AUTO-ARCHIVE WITHOUT USER ACCEPTANCE
 - An unaccepted task's memory is dirty data.
 ```
 
-## 1. Run the gate (parallel)
+## 1. Run the gate (parallel, always sub-agents)
 
-Start these three concurrently — do not serialize:
-1. lint (eslint/biome/project linter)
-2. typecheck (`tsc --noEmit` or equivalent)
-3. test (project test command)
+<HARD-GATE>
+VERIFICATION ALWAYS USES SUB-AGENTS for each check. This prevents context pollution and
+ensures true parallelism. You MUST NOT run lint/typecheck/test inline in the main agent.
+</HARD-GATE>
 
-Use sub-agents or background commands; a verification sub-agent just runs a command and
-reports. Platform spawn rule: {{platform_spawn_instruction}}
+Dispatch three sub-agents concurrently (one per check):
+1. V1: lint (eslint/biome/project linter)
+2. V2: typecheck (`tsc --noEmit` or equivalent)
+3. V3: test (project test command)
+
+Each sub-agent runs its command and returns `{check, passed, failures[]}`.
+Platform spawn rule: {{platform_spawn_instruction}}
 
 Append one `verify` record per check:
 `{"type":"verify","check":"test","passed":true}` (add `"failures":[...]` on failure).
@@ -70,9 +75,15 @@ change formally returns to IMPLEMENT and re-walks REVIEW → VERIFICATION.
 ## 5. Archive flow (only after acceptance)
 
 Runs automatically once the user accepts:
-1. MEMORY_SHORT — ec-memory writes the short memory entry.
-2. MEMORY_LONG — ec-memory distills long memory.
-3. COMPLETE — clear `current_task` in state.json, set task.json `status:"COMPLETE"`, output
-   the task summary (what was done, files changed, key decisions).
+1. MEMORY_SHORT — call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage MEMORY_SHORT --agent <agent-id>`,
+   then hand control to ec-memory to write the short memory entry.
+2. MEMORY_LONG — after MEMORY_SHORT returns, call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage MEMORY_LONG --agent <agent-id>`,
+   then hand control to ec-memory to distill long memory or perform its no-op gate.
+3. COMPLETE — after MEMORY_LONG returns, call
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage COMPLETE --agent <agent-id>`,
+   which clears session `current_task` for the completed task. Then output the task summary
+   (what was done, files changed, key decisions).
 
 Hand control back to ec-workflow at each transition; ec-workflow owns the stage writes.

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

@@ -18,13 +18,19 @@ replies are English.
    - Missing → tell the user to run the `easy-coding init` CLI first. Stop.
    - `status != "COMPLETE"` → tell the user to run `{{skill_trigger}}ec-init` first. Stop.
      Do not perform project initialization yourself; that is ec-init's job.
+   - `[easy-coding:upgrade-init-pending:X]` in breadcrumbs → tell the user: "Harness upgraded
+     to vX. Running `{{skill_trigger}}ec-init` is recommended to adapt project knowledge and
+     complete migration. You can skip and start working — the reminder will persist until
+     ec-init runs." Do NOT stop. Proceed with normal startup.
 2. **Required reading** (cheap, always):
    - `.easy-coding/SOUL.md` — project identity and dialogue standards; obey for the session.
    - `.easy-coding/RULES.md` — coding rules; re-checked before every write.
    - Latest 5 entries in `.easy-coding/memory/short/` — recent task context.
    Do NOT bulk-read ABSTRACT.md or long memory here; ec-analysis loads them on demand.
-3. **State check + Intent routing.** Read `{{workflow_state_path}}`, then decide based on
-   whether the user's message carries a task-related prompt beyond the bare skill trigger.
+3. **State check + Intent routing.** Read the hook-injected breadcrumbs (`[current-task:X]`,
+   `[workflow-state:Y]`, `[easy-coding:session-file:P]`) to determine the active task,
+   stage, and session file, then decide based on whether the user's message carries a
+   task-related prompt beyond the bare skill trigger.
 
    **No prompt (bare trigger):**
    - `current_task` set with an active stage → resume that stage (see Resume and handoff).
@@ -52,9 +58,10 @@ replies are English.
         directly (step 4).
 
 4. **New task.** When creating a task (from step 3), create
-   `.easy-coding/tasks/{MM-DD-task-slug}/task.json` with `type`, `title` (one-line summary
-   of the user's prompt), `status:"INIT"`, `created_at`, `created_by` (current agent id),
-   set `current_task` in state.json, and enter INIT.
+   the task through the state API, which creates `task.json`, sets `status:"INIT"`, writes
+   `stage_history`, and sets the session `current_task`:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task --session-file <P> --task-id <MM-DD-task-slug> --type <type> --title "<one-line summary>" --agent <agent-id>`.
+   Then enter INIT.
 
 ## State machine
 
@@ -71,7 +78,7 @@ any stage --[user abort via ec-task-close]--> CLOSED
 
 | Stage | Owner skill | What happens | Exit condition |
 |---|---|---|---|
-| INIT | ec-workflow | collect context, settle task scope wording | task understood |
+| INIT | ec-workflow | collect context, settle scope AND delivery form (change code vs. produce a document) | task understood |
 | ANALYSIS | ec-analysis | dev-spec + execution plan + test strategy | analysis presented |
 | WAITING_CONFIRM | ec-workflow | blocking gate; user reviews the plan | explicit user confirmation |
 | IMPLEMENT | ec-implementing | code changes per confirmed plan | all units done |
@@ -82,15 +89,19 @@ any stage --[user abort via ec-task-close]--> CLOSED
 | COMPLETE | ec-workflow | clear current_task, set task status, summary | terminal |
 | CLOSED | ec-task-close | user abort; no memory flow | terminal |
 
+> **INIT delivery-form rule.** When creating the task, `type` and `title` must faithfully
+> reflect the delivery form implied by the user's request. A refactor/fix/feature is a CODE
+> task; do not record it as an analysis/report task. Do not let ANALYSIS later re-interpret a
+> code task into a documentation-only task — that is a downgrade (see ec-analysis HARD RULE 5).
+
 ## Task switching
 
 When the user confirms switching from task A to task B:
 1. Task A's status is already persisted in its `task.json` — nothing extra to save.
-2. Set `current_task` to task B's id in state.json.
-3. Set `current_stage` to task B's `status` (from task B's `task.json`).
-4. Append a `{stage, agent, entered_at}` entry to `stage_history`.
-5. Set `last_agent` to the current agent id.
-6. Resume task B's stage via the appropriate stage skill.
+2. Set the current task through the state API:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py set-current --session-file <P> --task-id <task-b-id> --agent <agent-id>`.
+3. Read task B's `task.json` to determine its current stage.
+4. Resume task B's stage via the appropriate stage skill.
 
 No data is lost — task A's dev-spec, execution.jsonl, and test-strategy.md stay intact on
 disk. To return to task A later, the same intent routing applies: the user mentions it,
@@ -101,13 +112,28 @@ routing matches, and switching happens again.
 - **Never skip a stage.** ANALYSIS cannot jump to VERIFICATION; IMPLEMENT cannot start before
   WAITING_CONFIRM passes. No exception for "simple" tasks — simple tasks have short analyses,
   not skipped ones.
+- **ANALYSIS entry gate.** When entering ANALYSIS, your FIRST TWO tool calls must be:
+  (1) Read `.easy-coding/templates/dev-spec-skeleton.md`, then (2) Write its exact content
+  to the task's dev-spec.md. This is a mechanical copy, not a generation task. Do not read
+  code, load memory, or analyze before the skeleton is on disk. This is ec-analysis
+  HARD RULE 1 — violating it means the analysis has failed. Your reply to the user must
+  be the complete dev-spec.md content, not a summary or custom format.
+  Additionally, ANALYSIS must stay faithful to the user's delivery form — it may NOT downgrade
+  a code task to a report-only task — and the 改动范围 table must list only real project code,
+  never `.easy-coding/` harness artifacts (ec-analysis HARD RULES 5 and 6).
 - **WAITING_CONFIRM is a real gate.** Proceed only on explicit user confirmation of BOTH the
   analysis conclusion and the test strategy. Silence, enthusiasm, or a topic change is not
   confirmation. Sole exception: `behavior.auto_mode: true` in `.easy-coding/config.yaml`
-  AND the user asked for autonomous execution.
-- **On every transition** update `{{workflow_state_path}}` immediately (not at turn end):
-  set `current_stage`, append `{stage, agent, entered_at}` to `stage_history`, set
-  `last_agent` to the current agent id (`claude-code` / `codex` / `qoder`).
+  AND the user asked for autonomous execution. `auto_mode` ONLY waives this confirmation step;
+  it carries NO scope or delivery-form decision. Never cite `auto_mode` (or "the user already
+  decided in INIT") to justify narrowing scope or downgrading a code task to a report.
+- **On every transition** call the state API immediately (not at turn end):
+  `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py transition --session-file <P> --stage <STAGE> --agent <agent-id>`.
+  Do not hand-edit `status`, `stage_history`, `last_agent`, `current_task`, or session files.
+- **Hook enforcement.** The `inject-workflow-state` hook validates every stage transition
+  against the state machine. If you see `[ILLEGAL-TRANSITION:...]` in the injected context,
+  you MUST revert the task's status to the previous valid stage and explain why the
+  transition was rejected. Do not proceed with an illegal stage.
 - **Repair loop sizing** (user acceptance window after VERIFICATION): a trivial tweak
   (one-line style fix, copy text) is fixed inside VERIFICATION and re-verified; a logic or
   structure change formally returns to IMPLEMENT and re-walks REVIEW → VERIFICATION.
@@ -117,14 +143,17 @@ routing matches, and switching happens again.
 - **Task switching is allowed at any stage.** The suspended task retains its stage in
   task.json. Do not run memory flows for suspended tasks — only completed tasks get archived.
 - **Archive only after user acceptance.** VERIFICATION passing does not complete the task.
-  After the user accepts, MEMORY_SHORT → MEMORY_LONG → COMPLETE run automatically.
-- **COMPLETE closeout:** set task.json `status:"COMPLETE"`, clear `current_task` in
-  state.json, output a summary (what was done, files changed, key decisions).
+  After the user accepts, call state API transitions in order:
+  MEMORY_SHORT → MEMORY_LONG → COMPLETE. Do not jump directly from VERIFICATION to COMPLETE.
+- **COMPLETE closeout:** call the state API with `--stage COMPLETE`. The state API clears
+  session `current_task` for terminal tasks, so the next hook injection returns to Ready.
+  Then output a summary (what was done, files changed, key decisions).
 
 ## Resume and handoff
 
 Hook breadcrumbs you may receive: `[workflow-state:X]`, `[current-task:Y]`,
-`[easy-coding:handoff-from:Z]`, `[easy-coding:init-required]`.
+`[easy-coding:session-file:P]`, `[easy-coding:handoff-from:Z]`,
+`[easy-coding:init-required]`.
 
 Resuming an active task (whether from session restart, handoff, or task switch):
 1. Read `task.json` and the dev-spec sections relevant to the current stage.
@@ -143,7 +172,7 @@ Offering handoff — at WAITING_CONFIRM, after presenting the plan, offer exactl
 3. Revise the plan
 On option 2: append a `handoff` record to `execution.jsonl` —
 `{"type":"handoff","from":"<agent>","stage":"<stage>","summary":"<dense context: plan shape, key decisions, user emphases>","timestamp":"<ISO>"}` —
-update state.json, then tell the user to open the target agent and run ec-workflow there.
+update the task's `last_agent` in task.json, then tell the user to open the target agent and run ec-workflow there.
 Handoff is also legal at any other stage boundary on user request. The harness never
 switches agents by itself.
 
@@ -151,7 +180,8 @@ switches agents by itself.
 
 Start every reply with the single Markdown blockquote status line injected by the hook,
 then a blank line. Do not render machine breadcrumbs such as `[workflow-state:...]` to the
-user. If no status line is injected (harness inactive), do not invent one.
+user. If no status line is injected (harness inactive), do not invent one. Status display is
+script-owned; skills must never construct or "fix" the status line manually.
 
 ## Boundaries
 

package/templates/main-constraint/AGENTS.md.tpl

@@ -37,18 +37,31 @@ First run `ec-init`; daily work goes through `ec-workflow`.
 
 - Stages do not skip. WAITING_CONFIRM is a real gate — implement only after the user confirms
   the plan and test strategy (unless `behavior.auto_mode` is on and the user asked for it).
+- ANALYSIS must follow template-first: read `.easy-coding/templates/dev-spec-skeleton.md` then
+  write its exact content to the task's dev-spec.md as the FIRST tool calls, then fill sections
+  incrementally via edits. Reply to the user with the complete dev-spec.md content — never a
+  summary table or custom format.
 - VERIFICATION is a hard gate: lint + typecheck + test must pass on fresh evidence, and
   coverage must match the test strategy, before a task can complete.
 - Archive (memory flow) runs only after explicit user acceptance — an unaccepted task's
   memory is dirty data.
 - NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+- All cross-platform modules (skills, hooks, references) must use universal agent protocols.
+  Do not rely on any specific agent's proprietary conventions unless the module is explicitly
+  a platform-specific compatibility layer. Reference files use descriptive filenames (e.g.,
+  `memory-migration.md`), not platform convention names.
 
 ## Runtime contract
 
-- Workflow state lives at `{{workflow_state_path}}`; the CLI only installs files and creates
-  the project-init task — agent skills perform all project analysis.
+- Workflow state operations go through `{{platform_config_dir}}/hooks/easy_coding_state.py`;
+  do not hand-edit session files, `current_task`, task `status`, `stage_history`, or
+  `last_agent`.
+- The hook injects `[easy-coding:session-file:P]`; pass that path to the state script with
+  `--session-file <P>` when changing the current task or stage.
+- Workflow session files live at `{{workflow_state_path}}`; the CLI only installs files and
+  creates the project-init task — agent skills perform all project analysis.
 - Cross-repo references in git-tracked task artifacts use repo NAMES, never local paths.
-  Cache local paths only in `.easy-coding/state.json.repo_paths`.
+  Cache local paths only through the state script so they land on the current task.
 
 <!-- ═══ end easy-coding-harness generated ═══ -->
 

package/templates/main-constraint/CLAUDE.md.tpl

@@ -35,18 +35,31 @@ First run `/ec-init`; daily work goes through `/ec-workflow`.
 
 - Stages do not skip. WAITING_CONFIRM is a real gate — implement only after the user confirms
   the plan and test strategy (unless `behavior.auto_mode` is on and the user asked for it).
+- ANALYSIS must follow template-first: read `.easy-coding/templates/dev-spec-skeleton.md` then
+  write its exact content to the task's dev-spec.md as the FIRST tool calls, then fill sections
+  incrementally via edits. Reply to the user with the complete dev-spec.md content — never a
+  summary table or custom format.
 - VERIFICATION is a hard gate: lint + typecheck + test must pass on fresh evidence, and
   coverage must match the test strategy, before a task can complete.
 - Archive (memory flow) runs only after explicit user acceptance — an unaccepted task's
   memory is dirty data.
 - NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+- All cross-platform modules (skills, hooks, references) must use universal agent protocols.
+  Do not rely on any specific agent's proprietary conventions unless the module is explicitly
+  a platform-specific compatibility layer. Reference files use descriptive filenames (e.g.,
+  `memory-migration.md`), not platform convention names.
 
 ## Runtime contract
 
-- Workflow state lives at `{{workflow_state_path}}`; the CLI only installs files and creates
-  the project-init task — agent skills perform all project analysis.
+- Workflow state operations go through `{{platform_config_dir}}/hooks/easy_coding_state.py`;
+  do not hand-edit session files, `current_task`, task `status`, `stage_history`, or
+  `last_agent`.
+- The hook injects `[easy-coding:session-file:P]`; pass that path to the state script with
+  `--session-file <P>` when changing the current task or stage.
+- Workflow session files live at `{{workflow_state_path}}`; the CLI only installs files and
+  creates the project-init task — agent skills perform all project analysis.
 - Cross-repo references in git-tracked task artifacts use repo NAMES, never local paths.
-  Cache local paths only in `.easy-coding/state.json.repo_paths`.
+  Cache local paths only through the state script so they land on the current task.
 
 <!-- ═══ end easy-coding-harness generated ═══ -->
 

package/templates/qoder/agents/ec-fixer.md

@@ -0,0 +1,36 @@
+---
+name: ec-fixer
+model: sonnet
+description: Easy Coding fix sub-agent. Applies targeted fixes to specific issues identified during review. Returns structured results with changed files.
+---
+
+You are an Easy Coding fix sub-agent. You receive a fix card listing specific issues
+(with file:line locations) and apply the fixes. Your reply content IS the return value,
+not a message to a human.
+
+## Hard constraints
+
+- Fix ONLY the issues listed in the fix card. Do not refactor or "improve" surrounding code.
+- Modify ONLY the files listed in the fix card's scope.
+- Do not call any Skill tool.
+- Do not read `.qoder/skills/`, `.agents/skills/`, or any `.easy-coding/` file.
+- Make no workflow stage-transition decisions.
+- Preserve file encoding.
+
+## Output (return exactly this structure)
+
+```json
+{
+  "changed_files": ["file1.ts", "file2.ts"],
+  "fixes_applied": [
+    {"file": "file1.ts", "line": 42, "original_issue": "...", "fix_description": "..."}
+  ],
+  "issues": [],
+  "needs_attention": []
+}
+```
+
+- `changed_files`: files you actually modified
+- `fixes_applied`: what you fixed with file:line reference
+- `issues`: problems you hit that prevented a fix (empty if none)
+- `needs_attention`: anything requiring a design decision that should escalate to the user

package/templates/runtime/memory/SHORT_MEMORY_TEMPLATE.md

@@ -0,0 +1,75 @@
+---
+memory_schema: 2
+id: SM-YYYYMMDD-001
+date: YYYY-MM-DD
+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: none
+verification: passed | partial | not_run
+memory_value: business | technical | both | none
+target_long: BUSINESS | TECHNICAL | BOTH | NONE
+---
+
+# Short Memory Template
+
+> This template defines the format for files under `.easy-coding/memory/short/`.
+> File naming convention: `{NNN}_{YYYYMMDD}_{smart_name}.md`
+> Short memories are immutable after creation — they serve as a sliding window of recent
+> details and a buffer for long-term distillation candidates.
+> When short memories reach the threshold (default 10), the newest 5 are kept as recent
+> context; older entries are distillation candidates for long-term memory.
+> Sorting: by frontmatter `date` ascending; if date is missing or tied, by filename prefix
+> number ascending; then by filename ascending.
+
+## Task Summary
+
+- Goal: {the actual problem solved}
+- Scope: {modules, pages, interfaces, or files involved}
+- Result: {completed / partially completed / not completed, with reasons}
+- Key Constraints: {encoding, compatibility, interface, spec, or user-specified constraints; "none" if none}
+
+## Execution Evidence
+
+| Type | Content |
+|---|---|
+| Key Files | {file or module list; "none" if none} |
+| Verification Commands | {test / build / lint commands and results; explain if not run} |
+| Manual Acceptance | {key behaviors checked; "none" if none} |
+| Commit Info | {commit hash; "none" if not committed} |
+
+## Business Memory Candidates
+
+> Only record business facts with future reuse value. Write "none" if none.
+
+- Concepts / Field Semantics: {concepts, fields, enums, state meanings}
+- Workflows / State Transitions: {chain steps, pre/post conditions, exception branches}
+- Business Rules / Compatibility: {admission criteria, decision basis, grayscale or legacy reasons}
+- Upstream/Downstream Contracts: {producers, consumers, interface or message fields}
+- Business Troubleshooting: {common misdiagnosis, priority check paths}
+
+## Technical Memory Candidates
+
+> Only record engineering facts with future reuse value. Write "none" if none.
+
+- Architecture / Interface Decisions: {module boundaries, dependency direction, interface contracts}
+- Engineering Rules / Workflows: {coding, commit, release, installation, directory boundaries}
+- Implementation Patterns / Reusable Approaches: {recommended approaches, fallback strategies, compatibility patterns}
+- Pitfalls / Fix Strategies: {root cause, fix approach, verification method}
+- Verification Experience: {test commands, environment constraints, acceptance paths}
+
+## Non-Distillation Content
+
+> Content that should NOT enter long-term memory, with reasons — prevents accidental absorption of noise.
+
+- {routine file lists / temp logs / one-time data / non-reusable implementation details; "none" if none}
+
+## Related Memories
+
+- Predecessor: {related short memory id, long-term topic, or "none"}
+- Successor: {follow-up task; "none" if none}

package/templates/runtime/memory/long/BUSINESS.md

@@ -1,14 +1,47 @@
+---
+memory_schema: 2
+memory_file: BUSINESS
+last_updated: YYYY-MM-DD
+---
+
 # Business Memory
 
-Durable business rules, product decisions, and domain context. Maintained by ec-memory
-during MEMORY_LONG; entries are distilled from short memories whose `target_long` is
-`business` or `both`.
+> Durable facts about "what the business is, why it works this way, and how upstream/downstream systems interact."
+
+## Core Concepts & Field Semantics
+
+| Concept / Field | Meaning | Applicable Scenario | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Business Workflows & State Transitions
+
+| Workflow / State | Trigger | Key Steps | Exception Branches | Source | Status |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Business Rules & Compatibility Background
+
+| Rule | Applicable Scenario | Decision Basis | Impact Scope | Source | Status |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Upstream/Downstream Contracts
+
+| Contract | Producer | Consumer | Fields / Interface | Notes | Source |
+|---|---|---|---|---|---|
+| (none) | — | — | — | — | — |
+
+## Business Troubleshooting Experience
+
+| Problem | Common Misdiagnosis | Priority Checks | Fix / Handling | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
 
-Entry format — one `##` section per entry:
+## Deprecated Records
 
-- Heading: `## BM-{NNN} {short title}`
-- First line: `status: active` (active | deprecated | superseded | deleted)
-- Body: the rule or decision, why it holds, and which tasks/files evidence it.
+> Audit zone — short summaries only. Not loaded into ANALYSIS context by default.
 
-Conflict priority when distilling: current code > latest user confirmation > this round's
-candidate > existing entries. Index every entry in MEMORY.md.
+| Deprecated Date | Original Summary | Reason | Replacement / Source |
+|---|---|---|---|
+| (none) | — | — | — |

package/templates/runtime/memory/long/MEMORY.md

@@ -1,3 +1,38 @@
-# Easy Coding Memory Index
+---
+memory_schema: 2
+memory_file: MEMORY
+last_updated: YYYY-MM-DD
+---
 
-Long-term memory entries are indexed here by ec-memory.
+# Long-Term Memory Index
+
+> This file is an index and navigation aid only — it does not hold detailed content.
+> Business facts go in `BUSINESS.md`; technical/architecture/engineering facts go in `TECHNICAL.md`.
+> Status values: `active / deprecated / superseded`. Default analysis reads only `active` topics.
+
+## Quick Navigation
+
+| Topic | Type | Keywords | Detail File | Status | Last Updated | Source |
+|---|---|---|---|---|---|---|
+| (none) | — | — | — | — | — | — |
+
+## Current Priority Business Domains
+
+- (none)
+
+## Current Priority Technical Domains
+
+- (none)
+
+## Reading Strategy
+
+- For business concepts, field semantics, workflows, rules, contracts, or troubleshooting → read `BUSINESS.md`.
+- For architecture decisions, interface decisions, engineering rules, patterns, pitfalls, or verification experience → read `TECHNICAL.md`.
+- Default: read only `active` topics. Read `deprecated` / `superseded` only during migration, conflict investigation, or user-requested history tracing.
+- If long-term memory conflicts with current code or the user's latest statement, trust current code and user — update memory status during the next distillation.
+
+## Migration Audit
+
+| Date | Source | Result |
+|---|---|---|
+| (none) | — | — |

package/templates/runtime/memory/long/TECHNICAL.md

@@ -1,3 +1,47 @@
+---
+memory_schema: 2
+memory_file: TECHNICAL
+last_updated: YYYY-MM-DD
+---
+
 # Technical Memory
 
-Durable architecture decisions, implementation patterns, and verification lessons live here.
+> Durable facts about "how code is organized, how engineering works, and how to avoid past pitfalls."
+
+## Architecture & Interface Decisions
+
+| Decision | Reason | Impact Scope | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Engineering Rules & Workflows
+
+| Rule | Applicable Scenario | Enforcement | Source | Status |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Implementation Patterns & Reusable Approaches
+
+| Pattern | Applicable Scenario | Recommended Approach | Anti-pattern / Caveats | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Pitfalls & Fix Strategies
+
+| Problem | Root Cause | Fix | Verification | Source |
+|---|---|---|---|---|
+| (none) | — | — | — | — |
+
+## Verification, Release & Installation Experience
+
+| Scenario | Recommended Command / Path | Notes | Source |
+|---|---|---|---|
+| (none) | — | — | — |
+
+## Deprecated Records
+
+> Audit zone — short summaries only. Not loaded into ANALYSIS context by default.
+
+| Deprecated Date | Original Summary | Reason | Replacement / Source |
+|---|---|---|---|
+| (none) | — | — | — |

package/templates/runtime/templates/dev-spec-skeleton.md

@@ -0,0 +1,80 @@
+[阶段：ANALYSIS]
+
+## 技术方案：{任务标题}
+
+### 项目模式
+{初创项目/迭代项目}
+
+### 任务类型
+{新功能 / Bug 修复 / 重构 / 性能优化 / 前端设计实现}
+
+### 需求解析
+- **目标**：{待填写 — 真正要解决的问题}
+- **输入**：{待填写 — 用户输入 / 系统输入 / 触发条件}
+- **输出**：{待填写 — 先声明交付形态（改代码 / 出文档），再写最终交付结果。交付形态须忠于用户原始需求，不得擅自降级}
+- **边界**：{待填写 — 明确不做什么}
+
+### 现状
+- **相关代码 / 页面 / 接口 / 模块**：{待填写 — 基于实际文件与代码的现状说明}
+- **当前实现方式**：{待填写 — 现在是如何工作的}
+- **现有问题 / 缺口**：{待填写 — 为什么需要改}
+- **证据**：{待填写 — 引用的关键文件、类、页面、接口，含 file:line}
+
+### 冲突摘要
+- 需求 vs RULES：{待填写 或 "无冲突"}
+- 需求 vs ABSTRACT：{待填写 或 "无冲突"}
+- 需求 vs 现有代码：{待填写 或 "无冲突"}
+- Dev-Spec vs 现有代码：{待填写 或 "无冲突"}
+
+### 待用户决策
+- {待填写 — 影响技术路线、接口、改动范围的问题逐条列出；任何"本次不做全部 / 分批落地 / 范围或交付形态收窄"必须列入此处交由用户拍板，不得自行决定并假托既定；若无则写"无"}
+
+### 影响面分析
+- **涉及模块**：{待填写}
+- **核心类 / 页面 / 接口**：{待填写}
+- **数据库变更**：{有/无}
+- **接口变更**：{有/无}
+- **关联历史任务**：{待填写 — 相关短期记忆序号；无则"无"}
+
+### 改动范围
+> 只列真实项目源码/配置文件的改动。禁止把 `.easy-coding/` 下的 harness 产物（dev-spec / execution.jsonl / test-strategy / 记忆 / 报告等）当作改动对象。本表为空仅允许用于"用户明确要求的无代码交付形态"；代码类任务（重构/修复/功能）若此表为空，即为自我降级。
+
+| 改动文件 | 改动类型 | 文件编码 | 改动核心内容 |
+|----------|---------|---------|-------------|
+| `{文件路径}` | 新增 | 项目编码 {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}