easy-coding-harness 0.1.8 → 0.3.0

package/templates/shared-hooks/easy_coding_status.py

@@ -1,7 +1,13 @@
-import json
-import os
 from pathlib import Path
 
+from easy_coding_state import (
+    HELP_SUFFIX,
+    get_pending_init_version,
+    is_project_init_required,
+    record_seen_stage,
+    snapshot_state,
+)
+
 
 READY_LINE = (
     "> **Easy Coding** · Ready · Use `ec-workflow` to start or resume a task, "
@@ -9,110 +15,95 @@ READY_LINE = (
 )
 WAITING_INIT_LINE = "> **Easy Coding** · Waiting init · Use `ec-init` to initialize"
 
-VALID_TRANSITIONS: dict[str, set[str]] = {
-    "idle": {"INIT"},
-    "INIT": {"ANALYSIS", "CLOSED"},
-    "ANALYSIS": {"WAITING_CONFIRM", "CLOSED"},
-    "WAITING_CONFIRM": {"IMPLEMENT", "ANALYSIS", "CLOSED"},
-    "IMPLEMENT": {"REVIEW", "ANALYSIS", "CLOSED"},
-    "REVIEW": {"VERIFICATION", "IMPLEMENT", "ANALYSIS", "CLOSED"},
-    "VERIFICATION": {"MEMORY_SHORT", "IMPLEMENT", "CLOSED"},
-    "MEMORY_SHORT": {"MEMORY_LONG", "CLOSED"},
-    "MEMORY_LONG": {"COMPLETE", "CLOSED"},
-    "COMPLETE": set(),
-    "CLOSED": set(),
-}
-
-
-def load_json(path: Path) -> dict | None:
-    if not path.exists():
-        return None
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-
-
-def load_task(root: Path, task_id: str | None) -> dict | None:
-    if not task_id:
-        return None
-    return load_json(root / ".easy-coding" / "tasks" / task_id / "task.json")
-
-
-def load_session(root: Path) -> dict | None:
-    ppid = os.getppid()
-    return load_json(root / ".easy-coding" / "sessions" / f"{ppid}.json")
-
-
-def write_session(root: Path, session: dict) -> None:
-    ppid = os.getppid()
-    session_path = root / ".easy-coding" / "sessions" / f"{ppid}.json"
-    session_path.parent.mkdir(parents=True, exist_ok=True)
-    session_path.write_text(json.dumps(session, indent=2, ensure_ascii=False), encoding="utf-8")
-
-
-def is_project_init_required(root: Path) -> bool:
-    project_init = load_json(root / ".easy-coding" / "tasks" / "project-init" / "task.json")
-    return bool(project_init and project_init.get("status") != "COMPLETE")
-
-
-def validate_transition(previous: str, current: str) -> str | None:
-    if previous == current:
-        return None
-    allowed = VALID_TRANSITIONS.get(previous, set())
-    if current in allowed:
-        return None
-    return f"ILLEGAL TRANSITION: {previous} -> {current}. Allowed from {previous}: {sorted(allowed) or 'NONE (terminal state)'}."
-
+MANDATORY_DEV_SPEC_HEADERS: list[str] = [
+    "## 技术方案",
+    "### 项目模式",
+    "### 任务类型",
+    "### 需求解析",
+    "### 现状",
+    "### 冲突摘要",
+    "### 待用户决策",
+    "### 影响面分析",
+    "### 改动范围",
+    "### 修改方案",
+    "### 实施拆解",
+    "### 测试策略",
+    "### 风险与注意事项",
+]
 
 def build_status_line(root: Path, session: dict, agent: str | None = None) -> str:
-    task_id = session.get("current_task")
+    state = snapshot_state(root, session=session)
+    task_id = state["current_task"]
     if task_id:
-        task = load_task(root, str(task_id))
-        status = str(task["status"]) if task and task.get("status") else "PENDING"
+        status = str(state["status"])
         line = f"> **Easy Coding** · `{task_id}` · `{status}`"
-        if task:
-            last_agent = task.get("last_agent")
-            if agent and last_agent and last_agent != agent:
-                line += f" · Handoff -> `{last_agent}`"
+        last_agent = state.get("last_agent")
+        if agent and last_agent and last_agent != agent:
+            line += f" · Handoff -> `{last_agent}`"
+        if state["is_terminal"] or state["task_missing"]:
+            line += f" · {HELP_SUFFIX}"
         return line
 
     if is_project_init_required(root):
         return WAITING_INIT_LINE
 
+    pending = get_pending_init_version(root)
+    if pending:
+        return (
+            f"> **Easy Coding** · Waiting init · "
+            f"Upgrade to v{pending} — run `ec-init` to adapt"
+        )
+
     return READY_LINE
 
 
 def build_machine_breadcrumbs(root: Path, session: dict, agent: str | None = None) -> list[str]:
-    task_id = session.get("current_task")
-    task = load_task(root, str(task_id)) if task_id else None
-    stage = str(task["status"]) if task and task.get("status") else "idle"
-    lines = [f"[workflow-state:{stage}]"]
+    state = snapshot_state(root, session=session)
+    task_id = state["current_task"]
+    task = state["task"]
+    stage = str(state["status"]) if task else "idle"
+    lines = [f"[workflow-state:{stage}]", f"[easy-coding:session-file:{state['session_file']}]"]
 
     if task_id:
         lines.append(f"[current-task:{task_id}]")
-        if task:
-            last_agent = task.get("last_agent")
-            if agent and last_agent and last_agent != agent:
-                lines.append(f"[easy-coding:handoff-from:{last_agent}]")
+        if state["task_missing"]:
+            lines.append(f"[easy-coding:current-task-missing:{task_id}]")
+        last_agent = state.get("last_agent")
+        if agent and last_agent and last_agent != agent:
+            lines.append(f"[easy-coding:handoff-from:{last_agent}]")
 
     if is_project_init_required(root):
         lines.append("[easy-coding:init-required]")
+    else:
+        pending = get_pending_init_version(root)
+        if pending:
+            lines.append(f"[easy-coding:upgrade-init-pending:{pending}]")
+
+    # Stage-specific reminders
+    if stage == "ANALYSIS" and task_id:
+        dev_spec = root / ".easy-coding" / "tasks" / str(task_id) / "dev-spec.md"
+        if dev_spec.exists():
+            try:
+                content = dev_spec.read_text(encoding="utf-8")
+                missing = [h for h in MANDATORY_DEV_SPEC_HEADERS if h not in content]
+                if missing:
+                    names = ",".join(h.lstrip("#").strip() for h in missing)
+                    lines.append(f"[easy-coding:analysis-template-drift:missing:{names}]")
+                else:
+                    lines.append("[easy-coding:analysis-template-ok]")
+            except OSError:
+                lines.append("[easy-coding:analysis-gate:skeleton-first-then-fill]")
+        else:
+            lines.append("[easy-coding:analysis-gate:skeleton-first-then-fill]")
 
     # State machine validation
-    last_seen = session.get("last_seen_stage")
-    if last_seen and task and task.get("status"):
+    if task_id and task and task.get("status"):
         current_stage = str(task["status"])
-        violation = validate_transition(last_seen, current_stage)
+        last_seen = session.get("last_seen_stage")
+        violation = record_seen_stage(root, str(task_id), current_stage)
         if violation:
             lines.append(f"[ILLEGAL-TRANSITION:{last_seen}->{current_stage}]")
             lines.append(f"[easy-coding:transition-error:{violation}]")
-        if last_seen != current_stage:
-            session["last_seen_stage"] = current_stage
-            write_session(root, session)
-    elif task and task.get("status"):
-        session["last_seen_stage"] = str(task["status"])
-        write_session(root, session)
 
     return lines
 

package/templates/shared-hooks/inject-subagent-context.py

@@ -4,6 +4,8 @@ import os
 from pathlib import Path
 import sys
 
+from easy_coding_state import snapshot_state
+
 
 def configure_stdio() -> None:
     for stream in (sys.stdin, sys.stdout, sys.stderr):
@@ -28,15 +30,6 @@ def find_ec_root(start: Path) -> Path | None:
         current = current.parent
 
 
-def load_json(path: Path) -> dict | None:
-    if not path.exists():
-        return None
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-
-
 def emit(event_name: str, context: str) -> None:
     print(
         json.dumps(
@@ -61,15 +54,15 @@ def main() -> int:
     if root is None:
         return 0
 
-    session = load_json(root / ".easy-coding" / "sessions" / f"{os.getppid()}.json") or {}
-    task_id = session.get("current_task")
+    state = snapshot_state(root)
+    task_id = state.get("current_task")
     context = [
         "[easy-coding:subagent-guard]",
         "Sub-agents must follow the task card, stay within the allowed file scope, and return structured results.",
         "They must not claim completion or verification without fresh evidence.",
     ]
     if task_id:
-        context.append(f"Active Easy Coding task: {task_id}")
+        context.append(f"Active Easy Coding task: {task_id} ({state['status']})")
 
     event_name = payload.get("hook_event_name") or payload.get("hookEventName") or "PreToolUse"
     emit(event_name, "\n".join(context))

package/templates/shared-hooks/inject-workflow-state.py

@@ -4,7 +4,8 @@ import os
 from pathlib import Path
 import sys
 
-from easy_coding_status import build_status_context, load_session
+from easy_coding_state import load_session
+from easy_coding_status import build_status_context
 
 
 def configure_stdio() -> None:

package/templates/shared-hooks/session-start.py

@@ -5,7 +5,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 import sys
 
-from easy_coding_status import build_status_context, load_session, write_session
+from easy_coding_state import load_session, write_session
+from easy_coding_status import build_status_context
 
 
 def configure_stdio() -> None:

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

@@ -1,96 +0,0 @@
----
-name: ec-init
-description: One-time project knowledge initialization after the easy-coding CLI install. Use when the user runs {{skill_trigger}}ec-init or hook context shows [easy-coding:init-required]. Idempotent. Detects startup vs iterative projects automatically and generates SOUL, RULES, ABSTRACT, and TEST_STRATEGY.
----
-
-# ec-init — project knowledge initialization
-
-The CLI is a dumb file mover; you are the smart half. You analyze the project and produce
-the knowledge assets every later stage depends on. This runs once per project; re-runs are
-safe.
-
-Communicate with the user in the user's language.
-
-## Entry guard (idempotency — run first)
-
-1. Read `.easy-coding/tasks/project-init/task.json`.
-   - File missing → the CLI never ran. Tell the user to run `easy-coding init` first. Stop.
-   - `status == "COMPLETE"` → already initialized. Show a short summary (project mode,
-     generated files, init date from `init_log`) and exit without changing anything.
-   - `status == "PENDING"` → proceed.
-2. Repeated calls must never duplicate files or corrupt existing ones.
-
-## Project mode detection (automatic — never ask the user)
-
-Scan the project root, excluding `.easy-coding/`, platform dirs (`.claude/`, `.agents/`,
-`.codex/`, `.qoder/`), lockfiles, and pure config skeletons (package.json, tsconfig,
-linter configs, CI yaml).
-
-- Substantive source files exist (.ts/.js/.java/.py/.go/.rs/... containing real logic)
-  → **iterative** (existing project).
-- Empty, or config skeleton only → **startup** (new project).
-
-Record the verdict in `config.yaml` under `project.mode` and in `init_log`.
-
-## Iterative project flow
-
-After each step append `{step, summary, timestamp}` to `init_log` in task.json — a later
-agent must be able to see what was generated and on what evidence.
-
-1. **SOUL.md — project identity.** Analyze README, package metadata, and code purpose. Write:
-   - What this project is (2-3 sentences, concrete, no marketing fluff)
-   - Dialogue standards (language to use with the user, tone, verbosity expectations)
-   - Hard prohibitions (e.g. never commit secrets, never edit generated directories)
-   Keep it under ~40 lines; SOUL is loaded on every task.
-2. **RULES.md — coding rules grounded in evidence,** not generic best practice. Detect:
-   - Languages and versions (from configs and sources)
-   - Naming conventions actually in use (scan representative files)
-   - Comment language: if more than 70% of existing comments are Chinese, the rule is
-     "comments in Chinese"; same logic for English; mixed → follow each file's dominant language
-   - Error handling style, import ordering, formatter/linter in use (read their configs)
-   Structure as one section per language plus a General section. Every rule must be
-   mechanically checkable — "be clean" is not a rule; "exported functions carry explicit
-   return types" is.
-3. **ABSTRACT.md — architecture cognition.** Scan directory structure and entrypoints. Write:
-   modules and their responsibilities, core data flow, tech stack with versions, external
-   dependencies and services, build and run commands. Use a named section per module —
-   later stages extract sections by name (the `abstract_modules` field in execution plans).
-4. **TEST_STRATEGY.md — project test baseline:** detected framework, test command, where
-   tests live, naming conventions, coverage expectations, which classes of code this project
-   tests vs skips. Also fill `config.yaml` `test.framework` and `test.command` with commands
-   you verified exist (read package.json scripts or equivalent — do not guess).
-5. **Memory init** — ensure `.easy-coding/memory/short/` and `memory/long/` exist with the
-   three long files (MEMORY.md, BUSINESS.md, TECHNICAL.md). Never write fake entries.
-6. **Mark complete** — task.json `status:"COMPLETE"` plus a final `init_log` entry. Tell the
-   user initialization is done and daily work goes through `{{skill_trigger}}ec-workflow`.
-
-## Startup project flow
-
-1. **Lightweight interview** — 3-5 questions, strictly one at a time, multiple-choice
-   preferred: project name and positioning, primary language and framework, test framework
-   preference, special coding conventions (optional), comment language (optional).
-2. Generate from the answers:
-   - SOUL.md (identity from answers, dialogue standards, prohibitions)
-   - RULES.md (baseline rules for the chosen language; mark sections "refine as code grows")
-   - TEST_STRATEGY.md (skeleton for the chosen framework)
-3. **Skip ABSTRACT.md** — no architecture exists yet. Note in init_log:
-   "ABSTRACT pending; ec-memory backfills after the first substantive task." (ec-memory
-   detects the missing file during MEMORY_LONG and generates it from the then-current code.)
-4. Memory init and completion marking, same as iterative steps 5-6.
-5. Recommend: design first with `{{skill_trigger}}ec-brainstorming`, then build via
-   `{{skill_trigger}}ec-workflow`.
-
-## Quality bar for generated files
-
-- Every claim grounded in observed evidence — file paths and configs you actually read.
-  No filler like "follow best practices".
-- SOUL stays short. RULES and ABSTRACT run as long as the evidence supports, in named
-  sections. TEST_STRATEGY must be concrete enough that ec-verification can derive runnable
-  commands from it.
-
-## Boundaries
-
-- Never modify business source code, dependencies, or git state.
-- Never create workflow tasks or touch `current_task` / `current_stage` in state.json.
-- Never regenerate knowledge files for a COMPLETE project-init — the user edits them
-  manually or asks ec-meta for guided customization.