easy-coding-harness 0.2.1 → 0.3.0

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "easy-coding-harness",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CLI scaffold for installing Easy Coding harness files into agent-native directories.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.alibaba-inc.com/shixin.ysx/easy-coding-harness.git"
+  },
+  "homepage": "https://gitlab.alibaba-inc.com/shixin.ysx/easy-coding-harness#readme",
+  "bugs": {
+    "url": "https://gitlab.alibaba-inc.com/shixin.ysx/easy-coding-harness/-/issues"
+  },
   "type": "module",
   "bin": {
     "easy-coding": "./dist/cli.js"

package/templates/claude/agents/ec-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: ec-implementer
-description: Easy Coding implementation sub-agent. Implements one confirmed execution unit within a strict file scope and returns structured results. Dispatched by ec-implementing during parallel IMPLEMENT.
+description: Easy Coding implementation sub-agent. Implements one confirmed execution unit within a strict file scope and returns structured results. Dispatched by ec-implementing for every unit regardless of strategy.
 ---
 
 You are an Easy Coding implementation sub-agent. You receive a task card with one unit and

package/templates/claude/agents/ec-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: ec-reviewer
-description: Easy Coding review sub-agent. Reviews changed files along one assigned dimension (correctness or compliance) and returns evidence-backed findings. Dispatched by ec-reviewing when the change set is large.
+description: Easy Coding review sub-agent. Reviews changed files along one assigned dimension (correctness or compliance) and returns evidence-backed findings. Dispatched by ec-reviewing for every review regardless of change-set size.
 ---
 
 You are an Easy Coding review sub-agent. You review the changed files along the single

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

@@ -155,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

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

@@ -57,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).
@@ -79,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.
@@ -90,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-workflow/SKILL.md

@@ -85,7 +85,7 @@ any stage --[user abort via ec-task-close]--> CLOSED
 | REVIEW | ec-reviewing | multi-dimension code review | verdict = accept |
 | VERIFICATION | ec-verification | hard gate: lint/typecheck/test + coverage | all pass AND user accepts |
 | MEMORY_SHORT | ec-memory | archive: short memory entry | written |
-| MEMORY_LONG | ec-memory | archive: long memory distillation | written |
+| MEMORY_LONG | ec-memory | archive: long memory distillation (conditional — no-op when short memory is under threshold) | state API `memory_long` instruction handled |
 | COMPLETE | ec-workflow | clear current_task, set task status, summary | terminal |
 | CLOSED | ec-task-close | user abort; no memory flow | terminal |
 
@@ -145,6 +145,10 @@ routing matches, and switching happens again.
 - **Archive only after user acceptance.** VERIFICATION passing does not complete the task.
   After the user accepts, call state API transitions in order:
   MEMORY_SHORT → MEMORY_LONG → COMPLETE. Do not jump directly from VERIFICATION to COMPLETE.
+  When transitioning to MEMORY_LONG, pass the state API snapshot to ec-memory and treat its
+  `memory_long` object as authoritative: `action == "no-op"` advances to COMPLETE without
+  reading or writing long memory; `action == "distill"` runs distillation for `trim_count`
+  older short-memory entries.
 - **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).

package/templates/shared-hooks/easy_coding_state.py

@@ -27,6 +27,9 @@ VALID_TRANSITIONS: dict[str, set[str]] = {
     "CLOSED": set(),
 }
 
+DEFAULT_SHORT_TERM_MAX = 10
+DEFAULT_SHORT_TERM_KEEP = 5
+
 
 class StateError(Exception):
     pass
@@ -61,6 +64,94 @@ def load_json(path: Path) -> dict | None:
         return None
 
 
+def parse_positive_int(value: str) -> int | None:
+    normalized = value.split("#", 1)[0].strip().strip("'\"")
+    try:
+        parsed = int(normalized)
+    except ValueError:
+        return None
+    return parsed if parsed >= 0 else None
+
+
+def read_memory_config(root: Path) -> dict[str, int]:
+    config = {
+        "short_term_max": DEFAULT_SHORT_TERM_MAX,
+        "short_term_keep": DEFAULT_SHORT_TERM_KEEP,
+    }
+    path = root / ".easy-coding" / "config.yaml"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return config
+
+    in_memory = False
+    memory_indent = 0
+    for raw_line in lines:
+        without_comment = raw_line.split("#", 1)[0].rstrip()
+        stripped = without_comment.strip()
+        if not stripped:
+            continue
+        indent = len(without_comment) - len(without_comment.lstrip(" "))
+        if stripped == "memory:":
+            in_memory = True
+            memory_indent = indent
+            continue
+        if in_memory and indent <= memory_indent:
+            in_memory = False
+        if not in_memory or ":" not in stripped:
+            continue
+        key, value = stripped.split(":", 1)
+        if key not in config:
+            continue
+        parsed = parse_positive_int(value)
+        if parsed is not None:
+            config[key] = parsed
+    return config
+
+
+def count_short_memories(root: Path) -> int:
+    short_dir = root / ".easy-coding" / "memory" / "short"
+    if not short_dir.is_dir():
+        return 0
+    count = 0
+    for entry in short_dir.glob("*.md"):
+        try:
+            if is_schema_v2_short_memory(entry.read_text(encoding="utf-8")):
+                count += 1
+        except OSError:
+            continue
+    return count
+
+
+def is_schema_v2_short_memory(content: str) -> bool:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return False
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped == "---":
+            return False
+        if not stripped.startswith("memory_schema:"):
+            continue
+        _, value = stripped.split(":", 1)
+        return parse_positive_int(value) == 2
+    return False
+
+
+def build_memory_long_instruction(root: Path) -> dict:
+    config = read_memory_config(root)
+    short_count = count_short_memories(root)
+    action = "distill" if short_count > config["short_term_max"] else "no-op"
+    trim_count = max(0, short_count - config["short_term_keep"]) if action == "distill" else 0
+    return {
+        "short_count": short_count,
+        "short_term_max": config["short_term_max"],
+        "short_term_keep": config["short_term_keep"],
+        "action": action,
+        "trim_count": trim_count,
+    }
+
+
 def write_json(path: Path, data: dict) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
@@ -331,7 +422,10 @@ def transition_task(
             session["last_seen_stage"] = stage
             session["last_agent"] = agent
         write_session(root, session, session_file)
-    return snapshot_state(root, session_file, session)
+    snapshot = snapshot_state(root, session_file, session)
+    if stage == "MEMORY_LONG":
+        snapshot["memory_long"] = build_memory_long_instruction(root)
+    return snapshot
 
 
 def close_current_task(