easy-coding-harness 0.9.1 → 0.10.0-beta.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
+## 0.10.0-beta.0
+
+- 接入 `easy-dev-spec/v1` Canonical Spec：同步最终 producer 协议实现并新增只读
+  `inspect-dev-spec`、确定性 `select-dev-spec-scope`、选择式 `create-task-from-spec` 与
+  依赖证据 `satisfy-spec-dependency` 状态 API；用户选择多个 Spec task 后仍只创建一个
+  Harness task，消费上下文按仓库形成闭包。
+- Task、Unit 与执行证据新增来源 Spec SHA、仓库、source task/step、符号和测试命令追踪；
+  ANALYSIS 使用最终 READY 语义机械校验全局、契约、仓库、任务和验收闭环，并继续校验
+  仓库身份、基线、hard 依赖及 task/change/step/test 追踪。
+- IMPLEMENT、REVIEW、VERIFICATION 与 Git 范围按 `repo_id` 隔离；pending integration
+  依赖允许完成本地检查，但在证据闭合前禁止进入 MEMORY 或宣称全链路完成。
+- 保持历史/legacy task、现有状态图、approval/workflow mode 与指纹证据兼容；Canonical
+  Spec 始终只读，本地 dev-spec、execution plan 和 test strategy 作为带来源哈希的派生物。
+- 补齐 Codex 根身份兼容：真实运行时写入的裸 `root`、既有 `/root` 及其协作子路径统一
+  规范化为 `codex`，避免状态行、breadcrumb、任务列表与 claim 再次误报跨 Agent handoff。
+
 ## 0.9.1
 
 - 正式发布 Codex Agent 身份归一化修复：协作路径 `/root`、`/root/...` 与平台身份

package/README.md

@@ -92,6 +92,23 @@ any stage --[user abort via ec-task-close]--> CLOSED
   并留下当前指纹下的绿色证据，就不算通过。
 - `MEMORY` 先写入本次任务短期记忆，再执行长期记忆阈值门禁；未超过阈值时长期沉淀为 no-op。
 
+## Canonical Dev Spec
+
+Harness 可选择性消费 easy-dev-spec 生成的单文件 `easy-dev-spec/v1` Canonical Spec：
+
+1. `ec-workflow` 先只读检查 manifest、仓库、任务 DAG、依赖和 baseline，不创建任务。
+2. 用户明确选择一个或多个 Spec task；`select-dev-spec-scope` 按仓库提取确定性消费
+   闭包，Harness 不默认导入整份 Spec，也不会读取未选任务正文。
+3. 一次选择创建一个 Harness task；ANALYSIS 使用最终 producer READY 门禁，并将
+   selected task 映射为带 `repo_id`、`source_task_id`、source steps、文件、符号和测试
+   命令的 Unit。
+4. `hard` 依赖决定执行顺序，冻结的 `contract` 依赖允许并行编码，`integration` 依赖
+   在证据闭合前阻止全链路完成。
+
+Canonical Spec 是只读设计源；`.easy-coding/tasks/<task-id>/` 下的 `dev-spec.md`、
+`execution.jsonl` 和 `test-strategy.md` 是绑定来源 SHA-256 的运行时派生物，不会把开发
+进度写回源 Spec。无 Canonical manifest 的历史 Dev-Spec 继续走原有整文分析流程。
+
 ## Supermodule 模型
 
 在包含 `.gitmodules` 的父仓中，Easy Coding Harness 按 git 边界分层运行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-coding-harness",
-  "version": "0.9.1",
+  "version": "0.10.0-beta.0",
   "description": "CLI scaffold for installing Easy Coding harness files into agent-native directories.",
   "repository": {
     "type": "git",

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

@@ -73,6 +73,21 @@ frozen concrete mode, and any `pending_transition`; `dev-spec.md` is the human-r
 /`review`/`verify`/`handoff` records). Because plan and log live on disk, not in an agent's
 context window, a task survives session end and agent switches with zero information loss.
 
+## Canonical Spec integration
+
+An `easy-dev-spec/v1` Canonical Spec is a read-only design source, not progress storage.
+`inspect-dev-spec` validates the document with the protocol implementation pinned from
+`easy-dev-spec@7eb9b64`; after explicit task selection, `select-dev-spec-scope` returns one
+deterministic producer-compatible closure per repository, and `create-task-from-spec` creates one
+Harness task with the source ID/revision/SHA, selected task IDs, portable repository bindings,
+baseline classifications, and dependency evidence.
+
+ANALYSIS derives local `dev-spec.md`, `execution.jsonl`, and `test-strategy.md` for the selected
+consumption closure. Canonical-backed units keep repository, source task/steps, files, symbols,
+and test commands. Hard dependencies shape the Unit DAG, READY contracts can run in parallel,
+and integration dependencies block end-to-end completion until evidence is recorded. The source
+Canonical Spec is never rewritten with Harness runtime state.
+
 ## Memory system
 
 Short memory: one schema-v2 file per task, sliding window (max 10, keep 5). Long memory:
@@ -93,9 +108,10 @@ demand.
 continues. All platform-agnostic artifacts (dev-spec, execution.jsonl, task.json, memory)
 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.
-Owner identities use platform namespaces. Codex collaboration paths such as `/root` and
-`/root/...` normalize to `codex`, so internal Codex delegation is not mistaken for a cross-agent
-handoff; existing task files with those paths remain compatible without migration.
+Owner identities use platform namespaces. Codex root identities such as `root`, `/root`, and
+their collaboration subpaths normalize to `codex`, so internal Codex delegation is not mistaken
+for a cross-agent handoff; existing task files with those identities remain compatible without
+migration.
 
 Handoff is target-less. The leaving agent writes a `handoff` record with `from`, `stage`,
 `summary`, and `timestamp`, then releases its session pointer. It does not know or record the

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

@@ -21,6 +21,24 @@ Communicate with the user in the user's language.
 4. Inspect concrete code paths and tests. Expand context only when evidence reveals another
    dependency or risk.
 
+For a task with `task.json.spec_source`, re-run `inspect-dev-spec` against the stored source and
+every stored `task.repo_paths` repository binding. The schema, spec ID, revision, and SHA-256
+must still match. Then call the read-only selector for the exact stored selection:
+
+```bash
+{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py inspect-dev-spec \
+  --spec <stored-source> --repo-path <repo-id>=<stored-path> [--repo-path <repo-id>=<stored-path>]...
+
+{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py select-dev-spec-scope \
+  --spec <stored-source> --spec-task <selected-task-id> [--spec-task <selected-task-id>]...
+```
+
+Load only the returned per-repository consumption closures: manifest/global context, selected
+task and repository sections, related contracts, direct dependency summaries, selected
+changes/steps/tests, and relevant integration rows. Never replace the selector with a whole-file
+read. `scope-drifted` requires current-code conflict analysis before confirmation;
+`baseline-unavailable` or unresolved repository identity remains blocked in ANALYSIS.
+
 ## Analysis artifacts
 
 Copy `.easy-coding/templates/dev-spec-skeleton.md` first, then replace every `[[EC_TODO:...]]`.
@@ -43,11 +61,33 @@ Execution plan records use:
     "acceptance_criteria": ["observable result"],
     "test_points": ["targeted check"],
     "contracts": ["input/output/invariant or none"],
-    "risks": ["known risk or none"]
+    "risks": ["known risk or none"],
+    "repo_id": "R1",
+    "source_task_id": "R1-T1",
+    "source_step_ids": ["S1"],
+    "symbols": ["Class#method"],
+    "test_commands": ["exact source test command", "optional local command"]
   }]
 }
 ```
 
+The five source fields are mandatory only for Canonical-backed code units. Default to one unit
+per selected Spec task. A split may cover only one `repo_id` and one `source_task_id`, and all
+units together must cover every source step exactly once. Map selected hard dependencies into
+`depends_on`, contract dependencies into `contracts`, and dependency levels into
+`parallel_groups`.
+
+Canonical-backed `dev-spec.md`, `execution.jsonl`, and `test-strategy.md` are runtime-derived
+evidence, not a second maintained Spec. Record the source path/ID/revision/SHA, selected tasks
+and repositories, baseline/conflict result, Unit mapping, source test mapping, and pending
+integration edges.
+
+Every source test command remains mandatory. Additional commands from the current repository are
+allowed only when `test-strategy.md` records why the Canonical command alone is insufficient.
+For every selected source test, `test-strategy.md` must spell out its Test ID, source task ID,
+owning Unit ID, repository-relative test file, and exact Canonical command; the state gate checks
+these markers mechanically.
+
 Prefer one coherent unit over artificial file-level splitting. Use parallel only for truly
 independent write scopes. Better unit contracts reduce later REVIEW rework.
 
@@ -120,3 +160,5 @@ controls waiting; it never changes the selected execution depth.
 - No code task with an empty change scope.
 - No unit without acceptance criteria, test points, contracts, and risks.
 - No transition without a valid workflow proposal.
+- No Canonical-backed transition with changed source SHA, unresolved repository identity,
+  incomplete selected-task coverage, or an open Unit/Step/File/Symbol/Test traceability gap.

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

@@ -44,6 +44,9 @@ with `.easy-coding/sessions/` always excluded. The CLI already added it to `.git
    `repo_paths`), the commit/push covers every involved repo. Read `repo_paths` from the
    current task state to locate each checkout, check changes, and commit/push them as one
    coherent change set — do not leave a sub-repo behind.
+   For Canonical-backed tasks, this set is exactly the repositories referenced by
+   `selected_spec_tasks` and resolved in `spec_repositories`; unselected Spec repositories stay
+   out of scope.
 5. **Supermodule two-step commits.** If the current repo has `.gitmodules`, or the current
    task touches a git submodule path, treat each submodule as an independent git boundary:
    commit and push child repos first, then commit and push the parent gitlink update. If a
@@ -59,6 +62,7 @@ with `.easy-coding/sessions/` always excluded. The CLI already added it to `.git
 - Do not commit `spec/dev/` unless the user explicitly asks.
 - Do not omit managed `easy-coding upgrade` changes merely because they were created outside
   the current agent turn.
+- Never modify or stage the source Canonical Spec merely to record Harness execution progress.
 - In a supermodule task launched from the parent root, parent `.easy-coding/` belongs to the
   parent git. Child `.easy-coding/memory/` changes created by memory archive belong to the
   owning child git and must be committed before the parent gitlink update.

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

@@ -60,6 +60,11 @@ Sub-agents never dispatch other sub-agents or read `.easy-coding` workflow asset
 ## Identity       Easy Coding implementation unit
 ## Workflow Mode  {fast|standard|strict}
 ## Task           {unit description}
+## Source Spec    {spec_id@revision + sha256 | NONE}
+## Source Task    {source_task_id | NONE}
+## Repository     {repo_id + resolved repository root | current project}
+## Source Steps   {source_step_ids | NONE}
+## Symbols        {symbols | confirmed local symbols}
 ## Editable Scope {unit.files | NONE — read-only}
 ## Acceptance     {unit.acceptance_criteria}
 ## Test Points    {unit.test_points and exact targeted commands}
@@ -68,17 +73,23 @@ Sub-agents never dispatch other sub-agents or read `.easy-coding` workflow asset
 ## Coding Rules   {pre-digested RULES sections}
 ## Architecture   {pre-digested ABSTRACT sections}
 ## Output
-changed_files[], summary, deliverable|null, issues[], needs_attention[]
+status:"completed", repo_id|null, source_task_id|null, changed_files[], summary,
+deliverable|null, issues:[], needs_attention:[]
 ```
 
 ## Dispatch and result loop
 
-1. Append a `dispatch` record before work begins.
+1. Append a `dispatch` record before work begins. Canonical-backed records include `repo_id` and
+   `source_task_id`; resolve every file relative to `task.repo_paths[repo_id]` before dispatch.
 2. Execute according to dependency order and selected owner.
 3. Run targeted unit tests and self-audit scope, contracts, TODOs, and introduced warnings.
-4. Append one `result` record. Include unresolved issues rather than hiding them.
+4. Append one `result` record. Only a successful unit uses `status:"completed"`; include
+   unresolved issues rather than hiding them, and do not advance while `issues` or
+   `needs_attention` is non-empty.
 5. If a result changes a cross-unit contract, stop dependent units and return to ANALYSIS.
 6. For parallel units, detect overlapping writes before advancing.
+7. If implementation needs a file, symbol, repository, or source step outside the mapped
+   Canonical change set, stop and return to ANALYSIS instead of expanding scope implicitly.
 
 Do not emit a progress message for every trivial edit. Report at unit boundaries to reduce
 conversation overhead while keeping work observable.

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

@@ -14,6 +14,13 @@ Every new code task enters REVIEW. Read-only tasks do not. Obtain the current fi
 Review the final diff against `dev-spec.md`, RULES, unit acceptance criteria, tests, contracts,
 and obvious security risks. Every finding cites `file:line`.
 
+For Canonical-backed tasks, group evidence by `repo_id` and `source_task_id`. Every selected
+Spec task needs an implementation result and source test evidence; file references remain
+repo-relative within the owning repository. Missing or expanded source change/step coverage is
+a blocking correctness finding. Every Canonical review record includes its `repo_id` and
+`source_task_id`; emit at least one current-fingerprint record per selected task and required
+review dimension. A global record without source ownership cannot satisfy the gate.
+
 ## Depth by workflow mode
 
 - `fast`: main Agent performs one final-diff self-review across correctness, scope, tests, and
@@ -67,6 +74,8 @@ Fast and Standard normally use `combined`; Strict uses at least two distinct dim
   "reviewer": "main-or-independent-agent",
   "implementation_fingerprint": "<state-api value>",
   "timestamp": "<ISO-8601>",
+  "repo_id": "<canonical repo-id; omit for non-Canonical tasks>",
+  "source_task_id": "<canonical task-id; omit for non-Canonical tasks>",
   "findings": []
 }
 ```

package/templates/common/skills/ec-task-management/SKILL.md

@@ -18,6 +18,8 @@ Call the state API snapshot and show:
 - task `concrete_workflow_mode` or ANALYSIS proposal when present;
 - harness enabled/disabled state;
 - active and resumable tasks.
+- for Canonical-backed tasks: source Spec ID/revision/SHA, selected task IDs, repository
+  bindings/baseline status, and pending dependency evidence.
 
 Explain precedence:
 
@@ -50,3 +52,8 @@ confirmed interaction.
 Support listing, creating, selecting, claiming, handing off, and closing tasks through the
 state API. Preserve pending transitions when merely changing approval mode. Never infer user
 acceptance from opening this panel.
+
+When creating from a Canonical Spec, call `inspect-dev-spec`, display the complete task and
+dependency selection, then call `select-dev-spec-scope` and `create-task-from-spec` only after
+explicit user selection. Multiple selected Spec tasks still create one Harness task, while the
+selector returns one deterministic consumption closure per selected repository.

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

@@ -42,7 +42,9 @@ Append one record per executed check:
   "passed": true,
   "implementation_fingerprint": "<state-api value>",
   "config_fingerprint": "<state-api value>",
-  "timestamp": "<ISO-8601>"
+  "timestamp": "<ISO-8601>",
+  "repo_id": "<canonical repo-id; omit for non-Canonical tasks>",
+  "source_task_id": "<canonical task-id; omit for non-Canonical tasks>"
 }
 ```
 
@@ -64,5 +66,26 @@ do not append a later synthetic pass without rerunning the failed command.
   user wait.
 - A reported in-scope problem returns to IMPLEMENT; out-of-scope work becomes a separate task.
 
+For Canonical-backed tasks, run each repository's commands from `task.repo_paths[repo_id]` and
+cover every selected task's source test IDs. Report pending integration edges separately from
+local green checks. They do not block local implementation evidence, but the state API blocks
+`VERIFICATION -> MEMORY` until evidence is recorded with `satisfy-spec-dependency`. Never claim
+end-to-end completion while an integration edge remains pending. Every Canonical verify record
+includes the owning `repo_id` and `source_task_id`; duplicate check names in different source
+tasks remain separate evidence records. In `strict`, every involved repository independently
+records all four check types; a repository-specific non-applicable record still needs its reason
+and source ownership.
+
+Record the exact integration edge only after its evidence exists:
+
+```bash
+{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py satisfy-spec-dependency \
+  --task-id <harness-task-id> \
+  --source-task <source-spec-task-id> \
+  --spec-task <target-spec-task-id> \
+  --evidence "<verifiable evidence>" \
+  --agent <agent>
+```
+
 The state API rejects VERIFICATION -> MEMORY unless all evidence for the current implementation
 and config fingerprints is green.

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

@@ -52,7 +52,36 @@ plan decision; Auto continues immediately. Both remove later waiting, not qualit
    - Present with `status != "COMPLETE"`: invoke `{{skill_trigger}}ec-init`, then stop.
    - `[easy-coding:upgrade-init-pending:X]`: recommend `{{skill_trigger}}ec-init` for vX
      adaptation, but allow the user to continue; this reminder is not a workflow block.
-3. Match the user's intent against `current_task` and the active task list before resuming.
+3. When the user explicitly references a Dev-Spec, run the read-only `inspect-dev-spec` command
+   before ordinary task creation. For `protocol=canonical-v1`, show every task ID, repository,
+   title, dependency, and baseline status; never select all tasks by default. After the user
+   chooses one or more tasks and resolves repository paths or omitted hard-dependency evidence,
+   call `create-task-from-spec` once for the complete selection. A document without a Canonical
+   manifest remains a legacy ANALYSIS input for an ordinary task. A malformed, DRAFT, or otherwise
+   non-READY Canonical Spec stays blocked and must never be downgraded to the legacy route. Never
+   edit the source Spec.
+
+   ```bash
+   {{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py inspect-dev-spec \
+     --spec <path> [--repo-path <repo-id>=<path>]...
+
+   {{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py select-dev-spec-scope \
+     --spec <path> --spec-task <task-id> [--spec-task <task-id>]...
+
+   {{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task-from-spec \
+     --spec <path> --spec-task <task-id> [--spec-task <task-id>]... \
+     --task-id <harness-task-id> --type <type> --title <title> \
+     --repo-path <repo-id>=<path> [--dependency-evidence <dependency-id>=<evidence>]... \
+     --agent <agent-id> --session-file <P>
+   ```
+
+   `select-dev-spec-scope` is read-only and may run only after explicit task selection. Its
+   per-repository payload is the authoritative ANALYSIS context; do not load unselected task
+   bodies from the source document.
+
+   When multiple selected tasks depend on the same target, disambiguate creation evidence with
+   `<source-task-id>-><dependency-task-id>=<evidence>`.
+4. Match the user's intent against `current_task` and the active task list before resuming.
    If the user names or clearly matches another task, confirm the switch and call
    `claim-task --task-id <id> --agent <agent-id> --session-file <P>`. Do not execute task A
    under task B's request.
@@ -64,10 +93,10 @@ plan decision; Auto continues immediately. Both remove later waiting, not qualit
      to the requested deliverable. Feature, bugfix, refactor, performance, and workflow changes
      are code tasks. Use `doc`, `analysis`, or `report` only when the user explicitly requested
      a no-code deliverable; never downgrade a code request to the read-only completion path.
-4. Resume the matched/current task, then load only state-relevant assets. Do not read five full
+5. Resume the matched/current task, then load only state-relevant assets. Do not read five full
    memories at every startup; ANALYSIS searches memory metadata and opens relevant entries on
    demand.
-5. If another Agent last owned the task, summarize the stored handoff before continuing.
+6. If another Agent last owned the task, summarize the stored handoff before continuing.
 
 ## Stage dispatch
 

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

@@ -24,6 +24,13 @@
 - 需求 vs 现有代码：[[EC_TODO:填写结果或“无冲突”]]
 - Dev-Spec vs 现有代码：[[EC_TODO:填写结果或“无冲突”]]
 
+### Canonical Spec 来源
+- **来源**：[[EC_TODO:非 Canonical 任务写“无”；否则填写 repo-relative path、spec_id、revision、SHA-256]]
+- **选择任务 / 仓库**：[[EC_TODO:非 Canonical 任务写“无”；否则填写 selected task IDs 与 repo IDs]]
+- **消费闭包**：[[EC_TODO:非 Canonical 任务写“无”；否则填写 contracts、direct dependencies、changes、steps、tests 摘要]]
+- **基线与冲突**：[[EC_TODO:非 Canonical 任务写“无”；否则逐仓填写 exact/scope-unchanged/scope-drifted/baseline-unavailable 及处理结论]]
+- **待闭合 integration**：[[EC_TODO:非 Canonical 任务或不存在时写“无”；否则列依赖边和证据要求]]
+
 ### 影响面分析
 - **涉及模块**：[[EC_TODO:涉及模块]]
 - **核心类 / 页面 / 接口**：[[EC_TODO:核心类 / 页面 / 接口]]
@@ -49,11 +56,11 @@
 
 ### 实施拆解
 
-| 单元 | 说明 | 类型 | 涉及文件 | 依赖 | 验收条件 | 测试点 | 跨单元契约 |
-|------|------|------|---------|------|---------|-------|-----------|
-| U1 | [[EC_TODO:单元标题]] | [[EC_TODO:backend/frontend/test/...]] | [[EC_TODO:涉及文件]] | — | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证]] | [[EC_TODO:输入输出或“无”]] |
-| U2 | [[EC_TODO:单元标题]] | [[EC_TODO:单元类型]] | [[EC_TODO:涉及文件]] | — | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证]] | [[EC_TODO:输入输出或“无”]] |
-| U3 | [[EC_TODO:单元标题]] | [[EC_TODO:单元类型]] | [[EC_TODO:涉及文件]] | U1, U2 | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证]] | [[EC_TODO:与 U1/U2 的契约]] |
+| 单元 | 说明 | 类型 | 仓库 / 来源任务 / 步骤 | 涉及文件 / 符号 | 依赖 | 验收条件 | 测试点 / 命令 | 跨单元契约 |
+|------|------|------|----------------------|-----------------|------|---------|---------------|-----------|
+| U1 | [[EC_TODO:单元标题]] | [[EC_TODO:backend/frontend/test/...]] | [[EC_TODO:普通任务写“当前仓库 / 无 / 无”；Canonical 写 repo_id / source_task_id / source_step_ids]] | [[EC_TODO:文件与 symbols]] | — | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证与 test_commands]] | [[EC_TODO:输入输出或“无”]] |
+| U2 | [[EC_TODO:单元标题]] | [[EC_TODO:单元类型]] | [[EC_TODO:仓库 / 来源任务 / 步骤]] | [[EC_TODO:文件与 symbols]] | — | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证与命令]] | [[EC_TODO:输入输出或“无”]] |
+| U3 | [[EC_TODO:单元标题]] | [[EC_TODO:单元类型]] | [[EC_TODO:仓库 / 来源任务 / 步骤]] | [[EC_TODO:文件与 symbols]] | U1, U2 | [[EC_TODO:可验证结果]] | [[EC_TODO:定向验证与命令]] | [[EC_TODO:与 U1/U2 的契约]] |
 
 **执行策略**：[[EC_TODO:parallel / sequential / single]]
 - 第一批（并行）：U1 [[EC_TODO:单元标题]] ｜ U2 [[EC_TODO:单元标题]]