easy-coding-harness 0.1.8 → 0.2.1

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/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}