easy-coding-harness 0.1.8 → 0.3.0

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

@@ -0,0 +1,174 @@
+---
+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.
+
+## Config file ownership — read before writing anything
+
+Two files, two owners. Never cross the line:
+
+- **`.easy-coding/config.yaml` is owned by the `easy-coding` CLI.** It holds the structural
+  fields the CLI is authoritative for: `version`, `harness_version`, `agents`,
+  `project.name`, `memory`, `tasks`, `behavior`. You may READ it. You must NEVER write to it,
+  add fields to it, or regenerate it — doing so corrupts the CLI contract and breaks
+  `easy-coding upgrade`.
+- **`.easy-coding/project.yaml` is owned by you (ec-init).** Your entire project-analysis
+  configuration lives here. The CLI never reads this file, so writing it can never break the
+  CLI — but stay within the schema below so later stages can rely on it.
+
+Write `project.yaml` with exactly this shape. If it already exists, read-modify-write
+(update changed fields, preserve the rest) — never blow it away:
+
+```yaml
+# Easy Coding project profile — generated by ec-init. Safe to re-run.
+mode: iterative            # startup | iterative — your detection verdict
+language: typescript       # primary language
+test:
+  framework: vitest        # detected test framework
+  command: "npm test"      # a test command you VERIFIED exists (read package.json etc.)
+build:                     # optional — include only when detected
+  command: "npm run build"
+lint:                      # optional — include only when detected
+  command: "npm run lint"
+```
+
+Field whitelist: `mode`, `language`, `test.*`, `build.*`, `lint.*`. Do not invent other
+top-level keys. Do not copy any CLI-owned field (`harness_version`, `agents`, …) into this
+file.
+
+## 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. Run the **compliance scan** (see below),
+     then exit.
+   - `status == "PENDING"` → proceed with full initialization.
+2. Repeated calls must never duplicate files or corrupt existing ones.
+
+## Compliance scan (for COMPLETE projects)
+
+When `status == "COMPLETE"`, scan the project against the current harness version's
+initialization standard. Check each item:
+
+- **Memory format**: `.easy-coding/memory/long/MEMORY.md` has `memory_schema: 2` frontmatter?
+  `BUSINESS.md` and `TECHNICAL.md` exist? `SHORT_MEMORY_TEMPLATE.md` exists?
+  Short memories under `memory/short/` all have schema-v2 frontmatter?
+- **Knowledge files**: `SOUL.md`, `RULES.md`, `ABSTRACT.md`, `TEST_STRATEGY.md` — present
+  and non-empty?
+- **Project profile**: `project.yaml` exists with `mode` and `test` fields (ec-init owns it;
+  `config.yaml` is CLI-owned — not ec-init's concern)?
+
+**If all checks pass:** show "initialization is up to date" with a brief summary and exit.
+
+**If gaps are found:** list each gap with a one-line explanation. Ask the user whether to
+run supplementary initialization for the missing items. The user MUST confirm — do not
+auto-fix, as overwriting could destroy user-customized content with real value.
+
+On confirmation: execute only the missing/outdated steps — memory migration (load
+`references/memory-migration.md` if old-format memory detected), missing file generation,
+template updates. Do not re-generate files that already exist and pass the check.
+
+On decline: exit with the gap list as a reference for the user to address manually.
+
+**Clear upgrade marker:** After the compliance scan completes (whether all checks passed or
+gaps were fixed), run
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py project-init-complete --agent <agent-id>`.
+This removes `pending_init_since` and clears the "Waiting init · Upgrade" status line so the
+user is no longer prompted on every session.
+
+## 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 `project.yaml` under `mode` (see **Config file ownership**) and in
+`init_log`. Never touch `config.yaml`.
+
+## 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 `project.yaml` `test.framework` and `test.command` with commands
+   you verified exist (read package.json scripts or equivalent — do not guess).
+5. **Memory migration probe** — Check for old-format memory files:
+   - `.easy-coding/memory/long/MEMORY.md` exists but lacks `memory_schema: 2` frontmatter
+   - `.easy-coding/memory/long/BUSINESS.md` or `TECHNICAL.md` missing
+   - `.easy-coding/memory/short/*.md` files without `memory_schema: 2` frontmatter
+   If any trigger condition is met: load `references/memory-migration.md` (relative to this
+   skill's directory — the same directory that contains this SKILL.md) and execute the
+   migration procedure automatically. No user confirmation needed — migration is part of
+   initialization. Output an audit summary when done.
+6. **Memory init** — ensure `.easy-coding/memory/short/` and `memory/long/` exist with the
+   three long files (MEMORY.md, BUSINESS.md, TECHNICAL.md) using `memory_schema: 2` templates.
+   Also ensure `SHORT_MEMORY_TEMPLATE.md` exists in `memory/` as format reference. Never write
+   fake entries.
+7. **Mark complete** — write the final `init_log` entry, then run
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py project-init-complete --agent <agent-id>`.
+   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 migration probe and memory init, same as iterative steps 5-7.
+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 session files.
+- For COMPLETE projects: the compliance scan may propose supplementary initialization, but
+  never overwrite existing knowledge files without explicit user confirmation. Missing files
+  can be created; existing files are only updated via migration procedures (e.g., memory
+  migration), never silently regenerated.

package/templates/common/bundled-skills/ec-init/references/memory-migration.md

@@ -0,0 +1,87 @@
+# Memory Migration Procedure
+
+> Loaded by ec-init when old-format memory is detected during initialization.
+> Migration scope is strictly `.easy-coding/memory/` — never modify business code, specs, or other project files.
+
+## Trigger Conditions
+
+Any ONE of the following triggers automatic migration during ec-init (no user confirmation
+needed — migration is part of initialization, not a separate decision):
+
+1. `.easy-coding/memory/long/MEMORY.md` exists but lacks `memory_schema: 2` in its frontmatter
+2. `.easy-coding/memory/long/BUSINESS.md` is missing
+3. `.easy-coding/memory/long/TECHNICAL.md` is missing
+4. `.easy-coding/memory/short/*.md` files exist that lack YAML frontmatter or have `memory_schema != 2`
+5. `MEMORY.md` is still old-format long-form prose rather than a schema-2 index/navigation file
+
+## Migration Principles
+
+1. Migration executes automatically as part of ec-init. Inform the user what was detected and what will be migrated, but do not ask for confirmation — the user already triggered initialization.
+2. Old long-term memory content must not be discarded — migrate it to `BUSINESS.md`, `TECHNICAL.md`, the new index, or deprecated records.
+3. Old short-term memories are NOT converted to new format first. All old short memories participate in a single batch settlement.
+4. After successful migration, delete all processed old short-term files. New schema-2 short memories then follow the sliding window rules.
+5. If old and new content conflict, trust current code and user's latest statement. Old content goes to the "Deprecated Records" section of the appropriate file.
+6. The migration process must output an audit summary listing what was identified, migrated, deleted, and not distilled.
+7. Migration is a one-time operation, not incremental.
+
+## Old Long-Term Memory Split Rules
+
+Read the old `.easy-coding/memory/long/MEMORY.md` and split content by topic. **Also read
+`BUSINESS.md` and `TECHNICAL.md` if they already exist** — they may contain entries from
+prior usage. Merge existing entries with newly split content; do not overwrite or discard
+entries already present in these files.
+
+**→ BUSINESS.md:**
+- Business rules, field semantics, business workflows, state transitions
+- Upstream/downstream contracts, business troubleshooting experience
+
+**→ TECHNICAL.md:**
+- Architecture decisions, interface decisions, tech selections
+- Engineering rules, implementation patterns
+- Pitfalls and fix strategies, verification/release/installation experience
+
+**→ Deprecated Records:**
+- Expired content, content superseded by current code, content conflicting with user's latest statement
+
+After splitting, rewrite `MEMORY.md` as a `memory_schema: 2` index containing only: Topic, Type, Keywords, Detail File, Status, Last Updated, Source.
+
+## Old Short-Term Memory Batch Settlement
+
+Read `.easy-coding/memory/short/*.md`:
+
+- Files lacking YAML frontmatter, or with `memory_schema != 2`, are treated as old-format
+- Do NOT require old short memories to first gain new frontmatter — settle them as-is
+- ALL old short memories participate in one batch, even if fewer than 10 (to prevent re-triggering migration)
+- Stable sorting order:
+  1. By frontmatter `date` ascending
+  2. If date is missing, unparseable, or tied → by filename prefix number ascending
+  3. Still tied → by filename ascending
+- Classify all old short memories by content into: business candidates, technical candidates, non-distillation content
+- Write results to `BUSINESS.md` / `TECHNICAL.md`
+- Update `MEMORY.md` index with sources
+- After success, delete all processed old short files
+
+**Content that does NOT enter long-term memory:**
+- Routine file modification lists
+- One-time task logs
+- Temporary logs, temp order numbers, one-time mock data
+- Implementation details with no reuse value
+
+## Migration Audit Output
+
+```markdown
+### Memory Migration Complete
+
+- Old-format files identified: {file list}
+- Business topics migrated: {topic list; "none" if none}
+- Technical topics migrated: {topic list; "none" if none}
+- Old short memories deleted: {file list; "none" if none}
+- Non-distilled content and reasons: {summary; "none" if none}
+- Conflict handling: {old content deprecated / new content adopted / no conflicts}
+
+Proceeding with new memory structure.
+```
+
+## Return
+
+After migration completes, return to ec-init's normal flow. Background data should be re-loaded using the new three-file memory structure.

package/templates/common/bundled-skills/ec-meta/SKILL.md

@@ -21,9 +21,12 @@ source in the global npm install.
 ## Source-of-truth rules
 
 - `ec-workflow`'s SKILL.md is the source of truth for the workflow.
-- `.easy-coding/config.yaml` is the source of truth for project configuration.
+- `.easy-coding/config.yaml` is the CLI-owned source of truth for structural config
+  (`harness_version`, `agents`, `memory`, `behavior`, …) — the CLI reads and writes it.
+- `.easy-coding/project.yaml` is the ec-init-owned source of truth for project analysis
+  (`mode`, `language`, `test`, `build`, `lint`) — the CLI never reads it.
 - Customization edits the LOCAL installed copy only, never the scaffold source package.
-- Never edit runtime data here: `state.json`, `tasks/`, `memory/`.
+- Never edit runtime data here: `sessions/`, `tasks/`, `memory/`.
 - Warn the user: harness-managed files (ec-* skills, shared hooks, generated hook config,
   generated main-constraint regions) are **overwritten by `easy-coding upgrade`**. Durable
   customization belongs in project custom instructions (outside the generated markers) or in

package/templates/common/bundled-skills/ec-meta/references/customize-local/README.md

@@ -15,7 +15,8 @@ How to change the harness locally without losing it on `easy-coding upgrade`.
 `easy-coding upgrade` **never touches**:
 
 - `config.yaml` (only `harness_version` is bumped)
-- `state.json`, `tasks/`, `memory/`, `spec/`
+- `project.yaml` (ec-init's project profile)
+- `sessions/`, `tasks/`, `memory/`, `spec/`
 - `SOUL.md` / `RULES.md` / `ABSTRACT.md` / `TEST_STRATEGY.md` / `CHANGELOG.md`
 - the user region of `CLAUDE.md` / `AGENTS.md` (outside the markers)
 

package/templates/common/bundled-skills/ec-meta/references/local-architecture/README.md

@@ -10,7 +10,7 @@ The harness deliberately separates **platform-native files** from **shared runti
   and the main constraint file. They live in each platform's standard directory
   (`.claude/`, `.agents/` + `.codex/`, `.qoder/`). The agent's own `/` or `$` discovery finds
   them — the harness invents no new discovery mechanism.
-- **Shared runtime data** (`.easy-coding/`): `config.yaml`, `state.json`, `tasks/`, `memory/`,
+- **Shared runtime data** (`.easy-coding/`): `config.yaml`, `project.yaml`, `sessions/`, `tasks/`, `memory/`,
   `spec/`, and the project knowledge assets (SOUL/RULES/ABSTRACT/TEST_STRATEGY/CHANGELOG).
   Skills and hooks read and write these.
 
@@ -21,8 +21,9 @@ analysis, workflow operation). The CLI never analyzes the project.
 
 ```
 .easy-coding/
-  config.yaml        shared project config (in git)
-  state.json         personal workflow state (NOT in git)
+  config.yaml        CLI-owned structural config (in git)
+  project.yaml       ec-init project profile (in git)
+  sessions/          personal workflow session files (NOT in git)
   SOUL.md            project identity + dialogue standards
   RULES.md           coding rules (per-language sections)
   ABSTRACT.md        architecture cognition
@@ -44,13 +45,15 @@ analysis, workflow operation). The CLI never analyzes the project.
 8 stages + 2 terminals, owned by ec-workflow:
 `INIT → ANALYSIS → WAITING_CONFIRM → IMPLEMENT → REVIEW → VERIFICATION → MEMORY_SHORT →
 MEMORY_LONG → COMPLETE`, plus `CLOSED` (user abort, no memory flow). WAITING_CONFIRM and
-VERIFICATION are hard gates. The current stage persists in `state.json`; hooks inject it as a
-breadcrumb so every reply can render the status line.
+VERIFICATION are hard gates. The active task pointer lives in `sessions/{ppid}.json`;
+when the task reaches `COMPLETE` or `CLOSED`, the state API clears `current_task` so the
+session returns to Ready. Each task's stage persists in its `task.json`. Hooks inject the
+session and task state as breadcrumbs so every reply can render the status line.
 
-Task switching: `state.json.current_task` is a single slot, but the user can switch between
-tasks at any time. When a user's prompt doesn't match the active task, ec-workflow's intent
-router offers to suspend the current task and switch. The suspended task retains its stage in
-`task.json`; no data is lost. Each task folder is self-contained.
+Task switching: the session file has a single `current_task` slot, but the user can switch
+between tasks at any time. When a user's prompt doesn't match the active task, ec-workflow's
+intent router offers to suspend the current task and switch. The suspended task retains its
+stage in `task.json`; no data is lost. Each task folder is self-contained.
 
 ## Task persistence
 
@@ -77,5 +80,5 @@ demand.
 
 `.easy-coding/` is a dead drop. Agent A writes results and leaves; agent B reads them and
 continues. All platform-agnostic artifacts (dev-spec, execution.jsonl, task.json, memory)
-make cross-agent handoff lossless. `state.json` records `last_agent` so a new agent knows a
-task was handed off rather than self-interrupted.
+make cross-agent handoff lossless. `task.json.last_agent` records the last owner so a new
+agent knows a task was handed off rather than self-interrupted.

package/templates/common/bundled-skills/ec-meta/references/platform-files/README.md

@@ -22,7 +22,7 @@ discovery surfaces them under `/ec-` or `$ec-`.
 
 - **Skills** (`SKILL.md`): frontmatter `name` + `description`, then markdown instructions.
   They carry the workflow logic. Platform differences — the skill trigger (`/` vs `$`), the
-  state-file path, and the sub-agent spawn instruction — are filled in from a small
+  session path, state API path, and the sub-agent spawn instruction — are filled in from a small
   placeholder map at install time, so one source template serves all three platforms.
 - **Sub-agent definitions**: role baselines for the implementer / reviewer / verifier
   sub-agents. Claude/Qoder use markdown frontmatter; Codex uses TOML with
@@ -31,10 +31,14 @@ discovery surfaces them under `/ec-` or `$ec-`.
 
 ## Hooks and settings
 
-Three Python hooks, shared verbatim across platforms (only the JSON wrapper differs):
+Python runtime files are shared verbatim across platforms (only the JSON wrapper differs):
 
-- `session-start.py` — ensures `state.json` exists; injects resume / init-required / handoff
-  breadcrumbs. Idempotent.
+- `easy_coding_state.py` — the single runtime API for current-task pointers, task status,
+  transitions, and task state reads.
+- `easy_coding_status.py` — renders the Markdown status line and machine breadcrumbs from
+  state API snapshots.
+- `session-start.py` — ensures the per-session file exists; performs legacy `state.json`
+  migration; injects resume / init-required / handoff breadcrumbs. Idempotent.
 - `inject-workflow-state.py` — injects the `workflow-state` and `current-task` breadcrumbs so
   the status line can render.
 - `inject-subagent-context.py` — injects the sub-agent guard before an Agent tool call.