@shundoo-ai/dsh-cosmic 1.0.16 → 1.0.18

package/skills/cosmic-build/skills/cosmic-design/scripts/capability_plan_emit.py

@@ -1,1422 +0,0 @@
-#!/usr/bin/env python3
-"""capability_plan_emit — capabilityPlan section 规整化脚本。
-
-角色
-----
-类似 data_model_emit.py 之于 dataModel：
-LLM 写出的 capability plan 草稿（可能含自创字段名）经此脚本规整为
-PRD v0.4 schema 的 design.{workNo}.capabilityPlan.json。
-
-为什么需要这个脚本（M1.8 修复）
--------------------------------
-car_rental 案例（思考 202605191406）暴露：LLM 高频写出
-`{"tasks": [{"type": "add_operation", "targetEntity": "car",
-"operationKey": "rent_out", "displayName": "租出"}, ...]}`
-这种自创 schema，与 schemas/capability-plan.schema.json 完全错位。
-finalize_design.py 不读取，design_validator.py 不校验，
-development-plan.md 不渲染——capability 链路实际未生效。
-
-本脚本提供"草稿→规整产物"的可控通道：
-  1. 读取 LLM 写在 stage_b.{workNo}.capabilityPlan.draft.json 的草稿；
-  2. 字段名归一映射（type→capability、targetEntity→formNumber、
-     裸 operationKey/operationName 顶层→input 包装等）；
-  3. 自动补 taskId、version、phases 包装；
-  4. 兜底校验（schema 严格、与本脚本归一后产物一致）；
-  5. 写入 _runtime/design.{workNo}.capabilityPlan.json。
-
-任何无法自动归一的差异（capability 不在 enum / 缺关键字段无法补）→
-立即 ERROR 并给出"应该写什么"的修正建议。
-
-Fan-out fragment 产物所有权
---------------------------
-`emit_fragment` 只写一个 capability fragment。全部 fragment 成功后，
-capabilityPlan 产物 owner 显式调用一次 `merge-fragments`；worker 不再竞争
-共享主段的收口职责。
-
-compile 时机：由唯一产物 owner 显式 merge：
-- snapshot 存在 + 编译成功 → 主段为编译态（fieldKey 已反查、含 batchKey）；
-- snapshot 存在 + 编译失败 → 主段保持语义形态 + stderr 输出 errors（finalize
-  端凭 batchKey 缺失即 ERROR，不再反应式 --compile 救场）；
-- snapshot 缺失 → 显式 merge 失败，grouped tasks 不得完成。
-- design.dataModel.json 存在 → 字段存在性 + scope 校验以 `snapshot ∪ design.dataModel`
-  作并集真值源（本轮新设计、平台未拉取的字段被同轮 capabilityPlan 引用是合法形态）；
-  displayName / bizWord 反查仍仅以 snapshot 为源（B 方向：子 Agent 应写英文 fieldKey，
-  该点由 `make-fan-out-subagent-write-fieldkey-only` change 独立治理）。
-
-fragment emit 保持独立；compile 无法产出可执行主段时，显式 merge 立即失败，
-不得等到 finalize 才暴露。
-保留独立 `--link` CLI 入口供手动恢复场景。
-
-CLI
----
-    python capability_plan_emit.py --app-root <abs_path> --work-no <workNo>
-    python capability_plan_emit.py --app-root <abs_path> --work-no <workNo> --strict
-        # strict: 不接受任何兼容映射，发现自创字段名直接 ERROR
-    python capability_plan_emit.py --app-root <abs_path> --work-no <workNo> --link
-        # 兼容恢复别名；正常路径只显式调用一次 --mode merge-fragments
-    python capability_plan_emit.py --app-root <abs_path> --work-no <workNo> --link --force-unlock
-        # 强制清理残留锁文件后执行 link
-
-Exit codes
-----------
-    0  规整成功，产物已落盘
-    2  入参错误 / 草稿文件不存在
-    3  草稿 JSON 解析失败
-    4  存在不可归一的字段名 / 缺失关键参数 / compile 失败
-    5  规整后产物仍不通过 schema 严格校验
-    6  manifest / 上游 dataModel task 前置未满足
-    7  锁超时无法获取（--link 模式）
-
-Output
-------
-{appRoot}/_runtime/design.{workNo}.capabilityPlan.json （PRD schema）
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Any
-
-# ---------------------------------------------------------------------------
-# 常量与映射
-# ---------------------------------------------------------------------------
-
-CAPABILITY_ENUM = {"add_rules", "add_operation", "set_complex_property", "set_properties", "list_column", "filter_config", "list_view_props", "toolbar_config"}
-PHASE_ENUM = {"metadata-class", "code-class", "ui-class"}
-
-# LLM 高频自创字段名 → PRD 字段名（task 级）
-TASK_FIELD_ALIASES: dict[str, str] = {
-    "type": "capability",
-    "capabilityId": "capability",
-    "capability_id": "capability",
-    "targetEntity": "formNumber",
-    "entityKey": "formNumber",
-    "bizName": "formNumber",  # 仅当 task 顶层无 formNumber 时才映射
-    "form": "formNumber",
-}
-
-# input 内可被顶层平铺的字段（应自动收编入 input）
-INPUT_TOP_LEVEL_KEYS = {
-    "operationKey", "operationName", "operationType",
-    "rules", "ruleName", "modifications",
-    "fieldKey", "complexType", "config",
-    "buttonHint", "serviceHint", "forceWrite",
-    "displayName",  # → operationName (add_operation only)
-    # list capabilities high-frequency fields
-    "operation", "columnKey", "parentScope", "properties",
-    "referenceColumn", "position", "name", "order", "hyperlink",
-    "afterColumn", "columnType",
-}
-
-INPUT_FIELD_ALIASES: dict[str, str] = {
-    "displayName": "operationName",
-    "name": "operationName",
-}
-
-# 各 capability input 的"无条件必填"字段（与 capabilities/<cap>/schema.json 的
-# 顶层 required 严格对齐；条件必填（如 add_rules.businessDesc 在 requiresPlugin=true
-# 时才必填）由 _strict_validate 的 conditional 分支接管，不在此处罗列）。
-#
-# 历史教训（M1.OPT-A1）：曾在此把 add_rules 的 rules 列为无条件必填，叠加
-# `_is_present([]) == False` 的"空容器=不存在"语义，导致 LLM 严格按 capability-plan.md
-# §0.2 范本写 `"rules": []`（requiresPlugin=true 占位）时被脚本毙掉，引发
-# ~190 行思考摇摆（参见 PRD-M2 / 思考202605191406）。已收敛到 schema 单源真相。
-REQUIRED_INPUT_FIELDS: dict[str, set[str]] = {
-    "add_operation": {"formNumber", "operationName", "operationKey"},
-    "add_rules": {"formNumber"},
-    "set_complex_property": {"formNumber", "fieldKey", "complexType"},
-    # add-set-properties-to-fan-out：set_properties 入参三必填字段与 capabilities/set_properties/schema.json
-    # 保持一致；properties 字段的 minProperties=1 由 _validate_conditional_required 充补。
-    "set_properties": {"formNumber", "elementKey", "properties"},
-    # list capabilities — unconditional required fields per manifest.json schemas
-    "list_column": {"formNumber", "operation"},
-    "filter_config": {"formNumber", "operation", "parentScope"},
-    "list_view_props": {"formNumber", "operation", "properties"},
-    "toolbar_config": {"formNumber", "operation", "name", "operationKey"},
-}
-
-RE_TASK_ID = re.compile(r"^C\d+$")
-RE_OP_KEY = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]*$")
-
-EXIT_UPSTREAM_PREREQ = 6
-
-
-def _load_design_manifest(app_root: Path, work_no: str) -> dict[str, Any] | None:
-    path = app_root / "_runtime" / f"design-manifest.{work_no}.json"
-    if not path.is_file():
-        return None
-    try:
-        data = json.loads(path.read_text(encoding="utf-8-sig"))
-    except (json.JSONDecodeError, OSError):
-        return None
-    return data if isinstance(data, dict) else None
-
-
-def _manifest_enabled(manifest: dict[str, Any] | None, capability_id: str) -> bool:
-    if not manifest:
-        return False
-    tasks = manifest.get("tasks")
-    if not isinstance(tasks, list):
-        return False
-    for t in tasks:
-        if not isinstance(t, dict):
-            continue
-        if str(t.get("taskType") or "") != capability_id:
-            continue
-        payload = t.get("payload") if isinstance(t.get("payload"), dict) else {}
-        return payload.get("decision") == "enabled"
-    return False
-
-
-def _manifest_allows_without_data_model(app_root: Path, work_no: str) -> bool:
-    # 在 D1 内联架构下，capabilityPlan 不再是独立可启用任务，它由 D1 (dataModel)
-    # 子 Agent 内联读取 _dispatcher 后产出；dataModel 始终是 capabilityPlan 的前置，
-    # 该分支保留为 False。
-    return False
-
-
-def _manifest_requires_data_model(app_root: Path, work_no: str) -> bool:
-    manifest = _load_design_manifest(app_root, work_no)
-    return bool(manifest and _manifest_enabled(manifest, "dataModel"))
-
-
-def _guard_upstream_ready(
-    app_root: Path,
-    work_no: str,
-    msgs: list[str],
-    *,
-    require_snapshot: bool,
-) -> int | None:
-    """capabilityPlan emit 前置：manifest 必须存在；仅启用 dataModel 时要求 dataModel 产物。"""
-    manifest = _load_design_manifest(app_root, work_no)
-    if manifest is None:
-        msgs.append(
-            "[ERROR] DESIGN_MANIFEST_REQUIRED: 缺少 design-manifest；"
-            "动态 DAG 模式下 capabilityPlan 只能由 manifest 调度。"
-        )
-        return EXIT_UPSTREAM_PREREQ
-    if _manifest_allows_without_data_model(app_root, work_no):
-        msgs.append(
-            "[INFO] design manifest 未启用 dataModel；capabilityPlan 允许基于既有对象语义形态产出。"
-        )
-        return None
-    if not _manifest_requires_data_model(app_root, work_no):
-        msgs.append(
-            "[ERROR] DESIGN_MANIFEST_CAPABILITY_DISABLED: manifest 未启用 dataModel，禁止产出 capabilityPlan section。"
-        )
-        return EXIT_UPSTREAM_PREREQ
-    try:
-        from data_model_ready_check import collect_data_model_not_ready_reasons
-    except ImportError as exc:
-        msgs.append(f"[ERROR] 无法加载 data_model_ready_check: {exc}")
-        return EXIT_UPSTREAM_PREREQ
-
-    reasons = collect_data_model_not_ready_reasons(
-        app_root, work_no, require_snapshot=require_snapshot,
-    )
-    if not reasons:
-        return None
-
-    msgs.append(
-        "[ERROR] CAPABILITY_PLAN_PREREQ_DATAMODEL: capabilityPlan 依赖 dataModel 产物"
-        "（dataModel section / metadata snapshot），当前 dataModel 产物尚未完成。"
-    )
-    msgs.append(
-        "  说明: 在设计 DAG 中，capabilityPlan 必须等待 dependsOn 对应 section 就绪。"
-    )
-    for i, reason in enumerate(reasons, 1):
-        msgs.append(f"  [{i}] {reason}")
-    msgs.append(
-        "  须先完成 dataModel: python .../skills/cosmic-design/scripts/data_model_emit.py "
-        f'--app-root "{app_root}" --work-no "{work_no}"'
-    )
-    msgs.append("  dataModel section ready 后，再重跑 capability_plan_emit --compile（capabilityPlan draft 可保留）")
-    msgs.append("  NEXT_REQUIRED_CAPABILITY=dataModel")
-    return EXIT_UPSTREAM_PREREQ
-
-
-# ---------------------------------------------------------------------------
-# 主流程
-# ---------------------------------------------------------------------------
-
-def emit(app_root: Path, work_no: str, strict: bool = False) -> tuple[int, dict[str, Any] | None, list[str]]:
-    """读取草稿 → 规整 → 落盘。返回 (exit_code, plan_dict | None, messages)。"""
-    runtime_dir = app_root / "_runtime"
-    out_path = runtime_dir / f"design.{work_no}.capabilityPlan.json"
-    # Primary: section file (LLM writes directly). Fallback: old draft path.
-    draft_path = out_path
-    legacy_draft = runtime_dir / f"stage_b.{work_no}.capabilityPlan.draft.json"
-
-    msgs: list[str] = []
-
-    blocked = _guard_upstream_ready(app_root, work_no, msgs, require_snapshot=False)
-    if blocked is not None:
-        return blocked, None, msgs
-
-    if not draft_path.exists():
-        # 兜底：尝试读旧版 draft 路径
-        if legacy_draft.exists():
-            msgs.append(
-                f"[INFO] 主产物不存在，回退读取旧版草稿: {legacy_draft}"
-            )
-            draft_path = legacy_draft
-        else:
-            msgs.append(
-                f"[ERROR] section 文件不存在: {out_path}（也允许旧版草稿 {legacy_draft}）"
-            )
-            return 2, None, msgs
-
-    try:
-        draft = json.loads(draft_path.read_text(encoding="utf-8-sig"))
-    except (json.JSONDecodeError, OSError) as e:
-        msgs.append(f"[ERROR] 草稿 JSON 解析失败: {e}")
-        return 3, None, msgs
-
-    if not isinstance(draft, dict):
-        msgs.append("[ERROR] 草稿顶层必须是对象")
-        return 4, None, msgs
-
-    plan, normalize_msgs, hard_errors = _normalize(draft, strict=strict)
-    msgs.extend(normalize_msgs)
-
-    if hard_errors:
-        msgs.append(f"[ERROR] 存在不可自动归一的差异，需 LLM 手工修正（来源：{draft_path}）：")
-        for e in hard_errors:
-            msgs.append(f"  - {e}")
-        msgs.append("  参考: capabilities/_dispatcher/SKILL.md §0 schema 范本")
-        return 4, None, msgs
-
-    schema_errors = _strict_validate(plan)
-    if schema_errors:
-        msgs.append(f"[ERROR] 规整后仍不通过 schema 严格校验（产物：{out_path}）：")
-        for e in schema_errors:
-            msgs.append(f"  - {e}")
-        return 5, None, msgs
-
-    out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(
-        json.dumps(plan, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-    n_tasks = sum(len(p.get("tasks") or []) for p in plan.get("phases") or [])
-    msgs.append(f"[OK] capability plan emitted: {out_path} (tasks={n_tasks})")
-    return 0, plan, msgs
-
-
-def emit_and_compile(
-    app_root: Path,
-    work_no: str,
-    *,
-    strict: bool = False,
-) -> tuple[int, dict[str, Any] | None, list[str]]:
-    """emit 后编译 input；启用 dataModel 时要求 dataModel section + snapshot 就绪。"""
-    msgs: list[str] = []
-    blocked = _guard_upstream_ready(app_root, work_no, msgs, require_snapshot=True)
-    if blocked is not None:
-        return blocked, None, msgs
-
-    code, plan, emit_msgs = emit(app_root, work_no, strict=strict)
-    # --compile 模式下 emit 的 "[OK] capability plan emitted" 是中间态语义形态产物的成功提示，
-    # 若后续 compile 失败会误导主控以为整体成功；保留 [INFO]/[WARN]/[ERROR]，过滤掉中间 [OK]。
-    msgs.extend([m for m in emit_msgs if not m.startswith("[OK] capability plan emitted")])
-    if code != 0 or plan is None:
-        return code, plan, msgs
-
-    snap = app_root / "_runtime" / f"metadata-snapshot.{work_no}.json"
-    if not snap.is_file():
-        if _manifest_allows_without_data_model(app_root, work_no):
-            msgs.append(
-                f"[WARN] metadata-snapshot 缺失: {snap}；design manifest 未启用 dataModel，"
-                "本次保留语义形态 capabilityPlan，不执行 snapshot compile。"
-            )
-            return 0, plan, msgs
-        msgs.append(
-            f"[ERROR] metadata-snapshot 缺失: {snap}\n"
-            "  → --compile 需要 snapshot；请重跑 data_model_emit.py"
-        )
-        return EXIT_UPSTREAM_PREREQ, None, msgs
-    try:
-        from capability_input_compiler import compile_plan
-
-        snap_data = json.loads(snap.read_text(encoding="utf-8-sig"))
-        # restore-set-complex-property-contract-truth：并集真值源（snapshot ∪ design.dataModel）
-        dm_path = app_root / "_runtime" / f"design.{work_no}.dataModel.json"
-        design_dm: dict[str, Any] | None = None
-        if dm_path.is_file():
-            try:
-                design_dm = json.loads(dm_path.read_text(encoding="utf-8-sig"))
-            except Exception as dm_exc:  # noqa: BLE001
-                msgs.append(
-                    f"[WARN] design.dataModel 加载失败: {dm_exc}；本次以仅 snapshot 模式编译"
-                )
-                design_dm = None
-        compiled, errors = compile_plan(plan, snap_data, design_data_model=design_dm)
-        if errors:
-            msgs.append("[ERROR] capability input 编译失败:")
-            for e in errors:
-                msgs.append(f"  - {e}")
-            # 原子化：emit() 已在磁盘落下语义形态 plan，compile 失败时必须删除，
-            # 避免下游 finalize_design.py / 主控误读为“已编译”；同时保证 exit code 4 + 无文件产物。
-            out_path = app_root / "_runtime" / f"design.{work_no}.capabilityPlan.json"
-            if out_path.is_file():
-                try:
-                    out_path.unlink()
-                    msgs.append(f"[INFO] 已删除编译失败的中间产物: {out_path}")
-                except OSError as unlink_exc:
-                    msgs.append(f"[WARN] 中间产物删除失败: {unlink_exc}")
-            return 4, None, msgs
-        out_path = app_root / "_runtime" / f"design.{work_no}.capabilityPlan.json"
-        out_path.write_text(
-            json.dumps(compiled, ensure_ascii=False, indent=2) + "\n",
-            encoding="utf-8",
-        )
-        msgs.append(f"[OK] capability plan compiled in-place: {out_path}")
-        return 0, compiled, msgs
-    except Exception as exc:
-        msgs.append(f"[ERROR] compile 异常: {exc}")
-        return 4, None, msgs
-
-
-def _normalize(draft: dict[str, Any], *, strict: bool) -> tuple[dict[str, Any], list[str], list[str]]:
-    """把任意输入归一为 PRD schema。
-
-    返回 (plan, soft_messages, hard_errors)。
-    soft_messages: 自动归一过程中的提示（不阻断）
-    hard_errors:   无法归一的硬错误（阻断）
-    """
-    soft: list[str] = []
-    hard: list[str] = []
-
-    # 1. 顶层归一：抽 phases / 裸 tasks
-    if isinstance(draft.get("phases"), list):
-        phases_raw = draft["phases"]
-        version = str(draft.get("version") or "1.0.0")
-    elif isinstance(draft.get("tasks"), list):
-        if strict:
-            hard.append(
-                "顶层缺 phases 包装（strict 模式禁止自动包装）"
-                "；正确形态见 _dispatcher/SKILL.md §0.1"
-            )
-            return {}, soft, hard
-        soft.append(
-            "[WARN] 顶层 tasks 缺 phases 包装 → 自动包装为 metadata-class phase"
-        )
-        phases_raw = [{"phase": "metadata-class", "tasks": draft["tasks"]}]
-        version = str(draft.get("version") or "1.0.0")
-    else:
-        hard.append("顶层既无 phases 也无 tasks，无法识别任何 capability 任务")
-        return {}, soft, hard
-
-    if version != "1.0.0":
-        soft.append(f"[WARN] version='{version}' 不是 '1.0.0'，已强制写为 '1.0.0'")
-        version = "1.0.0"
-
-    # 2. phase 归一
-    phases_out: list[dict[str, Any]] = []
-    seen_task_ids_global: set[str] = set()
-    auto_id_counter = 1
-
-    for p_idx, phase in enumerate(phases_raw):
-        ploc = f"$.phases[{p_idx}]"
-        if not isinstance(phase, dict):
-            hard.append(f"{ploc} 不是对象")
-            continue
-        phase_name = str(phase.get("phase") or phase.get("phaseName") or "metadata-class").strip()
-        if phase_name not in PHASE_ENUM:
-            hard.append(
-                f"{ploc}.phase='{phase_name}' 不在 {sorted(PHASE_ENUM)}"
-            )
-            continue
-        tasks_raw = phase.get("tasks")
-        if tasks_raw is None:
-            soft.append(f"[WARN] {ploc} 无 tasks，自动填空数组")
-            tasks_raw = []
-        if not isinstance(tasks_raw, list):
-            hard.append(f"{ploc}.tasks 不是数组")
-            continue
-
-        tasks_out: list[dict[str, Any]] = []
-        seen_task_ids_phase: set[str] = set()
-
-        for t_idx, task in enumerate(tasks_raw):
-            tloc = f"{ploc}.tasks[{t_idx}]"
-            if not isinstance(task, dict):
-                hard.append(f"{tloc} 不是对象")
-                continue
-            normalized, t_soft, t_hard = _normalize_task(
-                task, p_idx, t_idx,
-                phase_name=phase_name,
-                strict=strict,
-                auto_id_seed=lambda: _next_auto_id(seen_task_ids_global, auto_id_counter)[0],
-            )
-            soft.extend(t_soft)
-            hard.extend(t_hard)
-            if normalized is None:
-                continue
-            tid = normalized.get("taskId") or ""
-            if tid in seen_task_ids_phase:
-                hard.append(
-                    f"{tloc}.taskId='{tid}' 在 phase 内重复"
-                )
-                continue
-            if not tid:
-                tid, auto_id_counter = _next_auto_id(seen_task_ids_global, auto_id_counter)
-                normalized["taskId"] = tid
-                soft.append(
-                    f"[WARN] {tloc} taskId 缺失，已自动分配为 '{tid}'"
-                )
-            seen_task_ids_phase.add(tid)
-            seen_task_ids_global.add(tid)
-            tasks_out.append(normalized)
-
-        phases_out.append({"phase": phase_name, "tasks": tasks_out})
-
-    plan: dict[str, Any] = {
-        "version": version,
-        "phases": phases_out,
-    }
-    return plan, soft, hard
-
-
-def _next_auto_id(used: set[str], counter: int) -> tuple[str, int]:
-    while True:
-        candidate = f"C{counter}"
-        counter += 1
-        if candidate not in used:
-            return candidate, counter
-
-
-def _normalize_task(
-    task: dict[str, Any],
-    p_idx: int, t_idx: int,
-    *,
-    phase_name: str,
-    strict: bool,
-    auto_id_seed: Any,
-) -> tuple[dict[str, Any] | None, list[str], list[str]]:
-    """单个 task 的归一。"""
-    soft: list[str] = []
-    hard: list[str] = []
-    loc = f"$.phases[{p_idx}].tasks[{t_idx}]"
-
-    out: dict[str, Any] = {}
-
-    # taskId
-    raw_id = str(task.get("taskId") or task.get("id") or "").strip()
-    if raw_id and not RE_TASK_ID.match(raw_id):
-        if strict:
-            hard.append(f"{loc}.taskId='{raw_id}' 不符合 ^C\\d+$（strict 模式禁止自动重写）")
-        else:
-            soft.append(f"[WARN] {loc}.taskId='{raw_id}' 格式异常，将自动重新分配")
-            raw_id = ""
-    if raw_id:
-        out["taskId"] = raw_id
-
-    # capability（含 type 别名映射）
-    cap = task.get("capability")
-    if not cap:
-        for alias_src in ("type", "capabilityId", "capability_id"):
-            if alias_src in task and task[alias_src]:
-                cap = task[alias_src]
-                if strict:
-                    hard.append(
-                        f"{loc} 用 '{alias_src}' 替代 'capability'（strict 模式不允许）"
-                    )
-                else:
-                    soft.append(
-                        f"[WARN] {loc} 字段名 '{alias_src}' → 'capability' 自动归一"
-                    )
-                break
-    cap = str(cap or "").strip()
-    if not cap:
-        hard.append(f"{loc}.capability 缺失，无法归一")
-        return None, soft, hard
-    if cap not in CAPABILITY_ENUM:
-        hard.append(
-            f"{loc}.capability='{cap}' 不在 {sorted(CAPABILITY_ENUM)}；"
-            "请回 _dispatcher/SKILL.md §0 选择 manifest 中已定义的 capability 类型"
-        )
-        return None, soft, hard
-    out["capability"] = cap
-
-    # formNumber（含 targetEntity / entityKey 别名映射）
-    form_no = str(task.get("formNumber") or "").strip()
-    if not form_no:
-        for alias_src in ("targetEntity", "entityKey", "form", "bizName"):
-            if alias_src in task and task[alias_src]:
-                form_no = str(task[alias_src]).strip()
-                if strict:
-                    hard.append(
-                        f"{loc} 用 '{alias_src}' 替代 'formNumber'（strict 模式不允许）"
-                    )
-                else:
-                    soft.append(
-                        f"[WARN] {loc} 字段名 '{alias_src}' → 'formNumber' 自动归一"
-                    )
-                break
-    if not form_no:
-        hard.append(f"{loc}.formNumber 缺失，无法归一")
-        return None, soft, hard
-    out["formNumber"] = form_no
-
-    # input（含顶层平铺 → input 包装）
-    inp_raw = task.get("input")
-    if isinstance(inp_raw, dict):
-        inp = dict(inp_raw)
-    elif inp_raw is None:
-        inp = {}
-        # 顶层平铺：自动收编
-        leaked: list[str] = []
-        aliases = INPUT_FIELD_ALIASES if cap == "add_operation" else {}
-        for k in INPUT_TOP_LEVEL_KEYS:
-            if k in task:
-                target_k = aliases.get(k, k)
-                inp[target_k] = task[k]
-                leaked.append(k)
-        if leaked:
-            if strict:
-                hard.append(
-                    f"{loc} input 字段顶层平铺: {leaked}（strict 模式不允许）"
-                )
-                return None, soft, hard
-            soft.append(
-                f"[WARN] {loc} input 字段顶层平铺 {leaked} → 自动收编入 input"
-            )
-    else:
-        hard.append(f"{loc}.input 不是对象")
-        return None, soft, hard
-
-    # input 字段名别名映射
-    aliases = INPUT_FIELD_ALIASES if cap == "add_operation" else {}
-    inp_normalized: dict[str, Any] = {}
-    for k, v in inp.items():
-        target_k = aliases.get(k, k)
-        if target_k != k:
-            soft.append(
-                f"[WARN] {loc}.input 字段名 '{k}' → '{target_k}' 自动归一"
-            )
-        inp_normalized[target_k] = v
-
-    # input.formNumber 默认与 task.formNumber 一致
-    if not str(inp_normalized.get("formNumber") or "").strip():
-        inp_normalized["formNumber"] = form_no
-        soft.append(f"[INFO] {loc}.input.formNumber 自动从 task.formNumber 继承")
-
-    # 必填字段检查
-    required = REQUIRED_INPUT_FIELDS.get(cap, set())
-    missing = [k for k in required if not _is_present(inp_normalized.get(k))]
-    if missing:
-        hard.append(
-            f"{loc}.input 缺必填字段: {missing}（capability={cap}）；"
-            "见 _dispatcher/SKILL.md §0.2 对应正例"
-        )
-        return None, soft, hard
-
-    # add_operation 特殊：operationKey 命名
-    if cap == "add_operation":
-        op_key = str(inp_normalized.get("operationKey") or "").strip()
-        if not RE_OP_KEY.match(op_key):
-            hard.append(
-                f"{loc}.input.operationKey='{op_key}' 不符合 ^[a-zA-Z][a-zA-Z0-9_]*$"
-            )
-            return None, soft, hard
-        op_type = str(inp_normalized.get("operationType") or "").strip()
-        if not op_type:
-            # v1.4: 缺失或仍是旧"custom"语义层 → 兜底 donothing；compiler/runner 会用 snapshot 白名单再校验
-            inp_normalized["operationType"] = "donothing"
-        elif op_type in {"custom", "approve", "reject", "cancel_approve"}:
-            inp_normalized["operationType"] = "donothing"
-            soft.append(
-                f"{loc}.input.operationType='{op_type}' 是已废弃的语义值，已自动迁移为 'donothing'"
-            )
-
-    out["input"] = inp_normalized
-
-    # 可选字段透传
-    for k in ("extractionSource", "parallelKey", "dependencyHints"):
-        if k in task and task[k] is not None:
-            out[k] = task[k]
-
-    return out, soft, hard
-
-
-def _is_present(v: Any) -> bool:
-    """字段是否"存在"——仅判 None 与空字符串。
-
-    历史教训（M1.OPT-A1）：旧实现把空 list/dict 也视作"不存在"，与 schema
-    含义不一致——空数组/空对象是合法值，应让 schema 的 conditional required
-    去判定（如 add_rules.rules 在 requiresPlugin=true 时合法为空）。"空容器
-    =不存在"的语义曾导致 LLM 范本和 emit 行为冲突，被毙的人花 190 行思考
-    猜原因（参见思考202605191406）。
-    """
-    if v is None:
-        return False
-    if isinstance(v, str) and not v.strip():
-        return False
-    return True
-
-
-# ---------------------------------------------------------------------------
-# 严格 schema 兜底校验（与 design_validator.py 的 CP 系列保持等价）
-# ---------------------------------------------------------------------------
-
-def _strict_validate(plan: dict[str, Any]) -> list[str]:
-    """严格 schema 校验（手写实现，与 capabilities/<cap>/schema.json 保持等价）。
-
-    位置坐标使用 0-based JSON Pointer 风格 `$.phases[I].tasks[J]`，与 LLM/jq/
-    人眼一致。M1.OPT-B1 之前用 1-based 让 LLM 用 30 行思考猜偏移规则。
-    """
-    errs: list[str] = []
-    if str(plan.get("version") or "") != "1.0.0":
-        errs.append("$.version != '1.0.0'")
-    phases = plan.get("phases")
-    if not isinstance(phases, list) or not phases:
-        errs.append("$.phases 必须是非空数组")
-        return errs
-    for p_idx, phase in enumerate(phases):
-        ploc = f"$.phases[{p_idx}]"
-        if not isinstance(phase, dict):
-            errs.append(f"{ploc} 不是对象")
-            continue
-        if str(phase.get("phase") or "") not in PHASE_ENUM:
-            errs.append(f"{ploc}.phase 不在 enum {sorted(PHASE_ENUM)}")
-        if not isinstance(phase.get("tasks"), list):
-            errs.append(f"{ploc}.tasks 必须是数组")
-            continue
-        seen: set[str] = set()
-        for t_idx, task in enumerate(phase["tasks"]):
-            tloc = f"{ploc}.tasks[{t_idx}]"
-            if not isinstance(task, dict):
-                errs.append(f"{tloc} 不是对象")
-                continue
-            tid = str(task.get("taskId") or "").strip()
-            if not RE_TASK_ID.match(tid):
-                errs.append(f"{tloc}.taskId 不符合 ^C\\d+$")
-            elif tid in seen:
-                errs.append(f"{tloc}.taskId='{tid}' 重复")
-            else:
-                seen.add(tid)
-            cap = str(task.get("capability") or "").strip()
-            if cap not in CAPABILITY_ENUM:
-                errs.append(f"{tloc}.capability 不在 enum {sorted(CAPABILITY_ENUM)}")
-            if not str(task.get("formNumber") or "").strip():
-                errs.append(f"{tloc}.formNumber 缺失")
-            inp = task.get("input")
-            if not isinstance(inp, dict):
-                errs.append(f"{tloc}.input 必须是对象")
-                continue
-            errs.extend(_validate_conditional_required(cap, inp, f"{tloc}.input"))
-    return errs
-
-
-def _validate_conditional_required(cap: str, inp: dict[str, Any], loc: str) -> list[str]:
-    """capability-aware 条件必填（替代 schema 的 allOf/if/then 分支）。
-
-    单点真相目前是 ``capabilities/<cap>/schema.json``（M2 已归位）；本函数与之保持等价：
-      - add_rules + requiresPlugin=true  → businessDesc 必填
-      - add_rules + requiresPlugin=false 或缺省 → rules 必填且 minItems >= 1
-    若未来要切换到 jsonschema 库直读 schema 文件，此函数可整体替换。
-    """
-    errs: list[str] = []
-    if cap == "add_rules":
-        requires_plugin = inp.get("requiresPlugin")
-        if requires_plugin is True:
-            biz_desc = str(inp.get("businessDesc") or "").strip()
-            if not biz_desc:
-                errs.append(
-                    f"{loc}.businessDesc 缺失（capability=add_rules + "
-                    "requiresPlugin=true 时必填，作为 backendTasks.coreLogic 的来源）"
-                )
-        else:
-            rules = inp.get("rules")
-            if not isinstance(rules, list) or len(rules) < 1:
-                errs.append(
-                    f"{loc}.rules 必须为非空数组（capability=add_rules + "
-                    "requiresPlugin=false/缺省 时 minItems=1；若本 task 仅作为 "
-                    "backendTasks 信息载体请显式设 requiresPlugin=true）"
-                )
-    elif cap == "set_properties":
-        # add-set-properties-to-fan-out：与 capabilities/set_properties/schema.json 保持等价
-        # （properties 必须是非空对象，minProperties >= 1）。
-        props = inp.get("properties")
-        if not isinstance(props, dict) or not props:
-            errs.append(
-                f"{loc}.properties 必须为非空对象（capability=set_properties；"
-                "至少包含一条字段简单属性键值对，推荐键名见 capability-plan.schema.json 的 "
-                "$defs.setPropertiesPropertyName）"
-            )
-        elem_key = str(inp.get("elementKey") or "").strip()
-        if not elem_key:
-            errs.append(
-                f"{loc}.elementKey 缺失或为空（capability=set_properties；设计期可填 bizWord，"
-                "compile 层推平为 {isv}_ 前缀 fieldKey）"
-            )
-    elif cap == "list_column":
-        op = str(inp.get("operation") or "").strip()
-        if op == "modifyColumn":
-            props = inp.get("properties")
-            if not isinstance(props, dict) or not props:
-                errs.append(
-                    f"{loc}.properties 必须为非空对象（capability=list_column + "
-                    "operation=modifyColumn）"
-                )
-            if not str(inp.get("columnKey") or "").strip():
-                errs.append(
-                    f"{loc}.columnKey 缺失（capability=list_column + "
-                    "operation=modifyColumn）"
-                )
-        elif op == "removeColumn":
-            if not str(inp.get("columnKey") or "").strip():
-                errs.append(
-                    f"{loc}.columnKey 缺失（capability=list_column + "
-                    "operation=removeColumn）"
-                )
-        elif op == "moveColumn":
-            for k in ("columnKey", "position", "referenceColumn"):
-                if not str(inp.get(k) or "").strip():
-                    errs.append(
-                        f"{loc}.{k} 缺失（capability=list_column + "
-                        "operation=moveColumn）"
-                    )
-        elif op == "addColumn":
-            if not str(inp.get("fieldKey") or "").strip():
-                errs.append(
-                    f"{loc}.fieldKey 缺失（capability=list_column + "
-                    "operation=addColumn）"
-                )
-    elif cap == "filter_config":
-        op = str(inp.get("operation") or "").strip()
-        if op == "addFilter":
-            if not str(inp.get("fieldKey") or "").strip():
-                errs.append(
-                    f"{loc}.fieldKey 缺失（capability=filter_config + "
-                    "operation=addFilter）"
-                )
-        elif op == "removeFilter":
-            if not str(inp.get("columnKey") or "").strip():
-                errs.append(
-                    f"{loc}.columnKey 缺失（capability=filter_config + "
-                    "operation=removeFilter）"
-                )
-    elif cap == "list_view_props":
-        props = inp.get("properties")
-        if not isinstance(props, dict) or not props:
-            errs.append(
-                f"{loc}.properties 必须为非空对象（capability=list_view_props）"
-            )
-    elif cap == "toolbar_config":
-        if not str(inp.get("name") or "").strip():
-            errs.append(f"{loc}.name 缺失（capability=toolbar_config）")
-        op_key = str(inp.get("operationKey") or "").strip()
-        if not op_key:
-            errs.append(f"{loc}.operationKey 缺失（capability=toolbar_config）")
-    return errs
-
-
-# ---------------------------------------------------------------------------
-# fan-out fragment 模式（parallelize-capability-plan-fan-out）
-# ---------------------------------------------------------------------------
-
-_FRAGMENT_NAME = "design.{work_no}.capabilityPlan.{cap}.fragment.json"
-_FRAGMENT_DRAFT_NAME = "design.{work_no}.capabilityPlan.{cap}.fragment.draft.json"
-_CLASSIFICATION_NAME = "design.{work_no}.capabilityPlan.classification.json"
-_LINK_LOCK_NAME = ".cap_plan_link.lock"
-_LINK_LOCK_TIMEOUT = 60  # 秒；超时视为残留并强制接管
-
-
-def _run_compat_link(app_root: Path, work_no: str, *, relink: bool = False) -> None:
-    """仅供 ``--mode link`` 使用的兼容恢复路径。
-
-    正常派发不会在 fragment emit 后调用本函数；唯一 capabilityPlan 产物
-    owner 显式调用一次 ``merge-fragments``。兼容行为：
-    1. 读 classification.json 获取期望 capability 全集
-    2. 检查所有 fragment 是否已落盘
-    3. 全集到齐 + 幂等决策 → 获取简易文件锁 + 调 merge_fragments 合并
-    4. 未到齐 / 主段已是最新 / 获取锁失败 → 静默退出
-
-    幂等护卫（主段已存在场景）：
-      - relink=False（默认）：比较任一 fragment mtime、> 主段 mtime →
-        自动重链；否则静默跳过（原有护卫语义）。
-      - relink=True：强制删除旧主段后重新合并（用于调试/人工修补 fragment
-        后的简便中止点）。
-
-    本函数失败不影响已落盘的 fragment。
-    """
-    runtime_dir = app_root / "_runtime"
-    out_path = runtime_dir / f"design.{work_no}.capabilityPlan.json"
-
-    # 读 classification.json 得期望 cap 全集
-    cls_path = runtime_dir / _CLASSIFICATION_NAME.format(work_no=work_no)
-    if not cls_path.is_file():
-        return  # 零分类场景，不触发 link
-
-    try:
-        cls_data = json.loads(cls_path.read_text(encoding="utf-8-sig"))
-    except (OSError, json.JSONDecodeError):
-        return  # 解析失败不阻断 emit_fragment 本身
-
-    classifications = cls_data.get("classifications") or []
-    if not isinstance(classifications, list) or not classifications:
-        return  # 零分类
-
-    expected_caps = sorted({
-        str(c.get("capability") or "")
-        for c in classifications
-        if isinstance(c, dict) and str(c.get("capability") or "")
-    })
-    if not expected_caps:
-        return
-
-    # 检查全集是否到齐，同时收集 fragment 路径用于 mtime 计算
-    fragment_paths: list[Path] = []
-    for cap in expected_caps:
-        frag_path = runtime_dir / _FRAGMENT_NAME.format(work_no=work_no, cap=cap)
-        if not frag_path.is_file():
-            return  # 未到齐，静默退出
-        fragment_paths.append(frag_path)
-
-    # 主段已存在：按 relink + fragment mtime 决策是否重链
-    if out_path.is_file():
-        if not relink:
-            try:
-                out_mtime = out_path.stat().st_mtime
-                newest_frag_mtime = max(p.stat().st_mtime for p in fragment_paths)
-            except OSError:
-                return
-            if newest_frag_mtime <= out_mtime:
-                return  # 主段已是最新，幂等护卫
-            print(
-                f"[compat-link] [INFO] 检测到 fragment 比主段更新，执行兼容重链【"
-                f"newestFragmentMtime={newest_frag_mtime:.0f} > mainMtime={out_mtime:.0f}】",
-                file=sys.stderr,
-            )
-            relink = True
-        # relink=True：删除旧主段（下游 merge 会重写）
-        try:
-            out_path.unlink()
-            print(
-                f"[compat-link] [INFO] --relink: 旧主段已删除 {out_path.name}",
-                file=sys.stderr,
-            )
-        except OSError as exc:
-            print(
-                f"[compat-link] [WARN] 旧主段删除失败，跳过重链: {exc}",
-                file=sys.stderr,
-            )
-            return
-
-    # 全集到齐 —— 尝试获取简易文件锁（非阻塞）
-    lock_path = runtime_dir / _LINK_LOCK_NAME
-    lock_fd = _acquire_link_lock(lock_path)
-    if lock_fd is None:
-        return  # 另一个子 Agent 已在 merge，让它完成
-
-    try:
-        # 双重检查：获取锁后再看一次主段是否已产出
-        if out_path.is_file():
-            return
-        # 调 merge_fragments（它会读 manifest 做二次确认）
-        code, _plan, msgs = merge_fragments(app_root, work_no)
-        for m in msgs:
-            print(f"[compat-link] {m}", file=sys.stderr)
-    finally:
-        _release_link_lock(lock_fd, lock_path)
-
-
-def _try_inline_compile(app_root: Path, work_no: str, out_path: Path) -> bool:
-    """显式 fragment merge 后立即编译主段。
-
-    收口语义（与 spec 三场景一一对应）：
-      - snapshot 存在 + 编译成功 → 用编译产物覆盖主段（task 自带 batchKey）。
-      - snapshot 存在 + 编译失败 → 不覆盖主段，stderr 输出 errors（保持语义形态
-        让 finalize 凭 batchKey 缺失继续报 ERROR，不再反应式 --compile 救场）。
-      - snapshot 缺失 → 返回 False，显式 merge 立即失败。
-
-    返回 plan 是否已编译、可进入任务完成态。编译失败时 fragment 保留，
-    但 grouped dispatch 必须失败。
-    """
-    runtime_dir = app_root / "_runtime"
-    snap_path = runtime_dir / f"metadata-snapshot.{work_no}.json"
-
-    if not snap_path.is_file():
-        print(
-            "[capability-plan-merge] [ERROR] metadata snapshot 不存在；"
-            "显式 merge 无法产出可执行 plan",
-            file=sys.stderr,
-        )
-        return False
-
-    try:
-        sys.path.insert(0, str(Path(__file__).resolve().parent))
-        from capability_input_compiler import compile_plan  # type: ignore[import-not-found]
-
-        plan = json.loads(out_path.read_text(encoding="utf-8-sig"))
-        snap = json.loads(snap_path.read_text(encoding="utf-8-sig"))
-        # restore-set-complex-property-contract-truth：并集真值源（snapshot ∪ design.dataModel）
-        # 存在性 + scope 校验；displayName 反查仍仅 snapshot（B 方向）
-        dm_path = runtime_dir / f"design.{work_no}.dataModel.json"
-        design_dm = None
-        if dm_path.is_file():
-            try:
-                design_dm = json.loads(dm_path.read_text(encoding="utf-8-sig"))
-            except Exception as dm_exc:  # noqa: BLE001
-                print(
-                    f"[capability-plan-merge] [WARN] design.dataModel 加载失败: {dm_exc}；"
-                    f"本次以仅 snapshot 模式编译",
-                    file=sys.stderr,
-                )
-                design_dm = None
-        else:
-            print(
-                "[capability-plan-merge] [INFO] design.dataModel.json 不存在，本次以仅 snapshot 模式编译",
-                file=sys.stderr,
-            )
-        compiled, errors = compile_plan(plan, snap, design_data_model=design_dm)
-    except Exception as exc:  # noqa: BLE001
-        print(
-            f"[capability-plan-merge] [ERROR] compile 异常，主段保持语义形态：{exc}",
-            file=sys.stderr,
-        )
-        return False
-
-    if errors:
-        print(
-            "[capability-plan-merge] [ERROR] compile_plan 失败，主段保持语义形态；"
-            "详见下列错误位置：",
-            file=sys.stderr,
-        )
-        for e in errors:
-            print(f"  - {e}", file=sys.stderr)
-        return False
-
-    tmp = out_path.with_suffix(out_path.suffix + ".tmp")
-    tmp.write_text(
-        json.dumps(compiled, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-    tmp.replace(out_path)
-    print(
-        f"[capability-plan-merge] [OK] 主段已编译为 fieldKey 形态: {out_path}",
-        file=sys.stderr,
-    )
-    return True
-
-
-def _acquire_link_lock(lock_path: Path) -> int | None:
-    """尝试以原子创建方式获取简易文件锁。返回 fd（成功）或 None（失败）。
-
-    超时检测：若锁文件 mtime 超过 _LINK_LOCK_TIMEOUT 秒，视为残留并强制接管。
-    """
-    import time
-
-    if lock_path.is_file():
-        try:
-            age = time.time() - lock_path.stat().st_mtime
-        except OSError:
-            age = 0
-        if age > _LINK_LOCK_TIMEOUT:
-            # 残留锁：强制清理
-            print(
-                f"[compat-link] 检测到锁残留（{age:.0f}s > {_LINK_LOCK_TIMEOUT}s），强制接管",
-                file=sys.stderr,
-            )
-            try:
-                lock_path.unlink()
-            except OSError:
-                return None
-        else:
-            return None  # 锁正被持有，不等待
-
-    try:
-        fd = os.open(str(lock_path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-        return fd
-    except OSError:
-        return None  # 竞态失败——另一个进程抢先创建
-
-
-def _release_link_lock(fd: int | None, lock_path: Path) -> None:
-    """释放锁：关闭 fd + 删除锁文件。"""
-    if fd is not None:
-        try:
-            os.close(fd)
-        except OSError:
-            pass
-    try:
-        lock_path.unlink(missing_ok=True)
-    except OSError:
-        pass
-
-
-def _register_cp_section_in_manifest(app_root: Path, work_no: str) -> None:
-    """将 cp_section 注册到 metadata/_emit_manifest.json。"""
-    manifest_path = app_root / "metadata" / "_emit_manifest.json"
-    if not manifest_path.is_file():
-        return  # emit_manifest 不存在时不强制创建（依赖 data_model_emit 先产出）
-
-    try:
-        mf = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
-    except (OSError, json.JSONDecodeError):
-        return
-
-    artifacts = mf.setdefault("artifacts", [])
-    # 幂等：已有 cp_section 则不重复追加
-    if any(isinstance(a, dict) and a.get("type") == "cp_section" for a in artifacts):
-        return
-
-    artifacts.append({"type": "cp_section", "version": "1.0"})
-    try:
-        manifest_path.write_text(
-            json.dumps(mf, ensure_ascii=False, indent=2) + "\n",
-            encoding="utf-8",
-        )
-        print(
-            "[capability-plan-merge] cp_section 已注册到 _emit_manifest.json",
-            file=sys.stderr,
-        )
-    except OSError:
-        pass
-
-
-def emit_fragment(
-    app_root: Path,
-    work_no: str,
-    capability: str,
-    *,
-    strict: bool = False,
-    relink: bool = False,
-) -> tuple[int, dict[str, Any] | None, list[str]]:
-    """fan-out 子 Agent 调用：把 fragment 草稿规整为 fragment 产物。
-
-    输入：``{appRoot}/_runtime/design.{workNo}.capabilityPlan.<cap>.fragment.draft.json``
-    输出：``{appRoot}/_runtime/design.{workNo}.capabilityPlan.<cap>.fragment.json``
-
-    fragment 形态等同完整 plan（含 version + phases），但 tasks 仅含本 capability。
-    返回 (exit_code, plan_dict | None, messages)。
-    """
-    msgs: list[str] = []
-    if capability not in CAPABILITY_ENUM:
-        msgs.append(
-            f"[ERROR] capability='{capability}' 不在 {sorted(CAPABILITY_ENUM)}"
-        )
-        return 2, None, msgs
-
-    runtime_dir = app_root / "_runtime"
-    draft_path = runtime_dir / _FRAGMENT_DRAFT_NAME.format(work_no=work_no, cap=capability)
-    out_path = runtime_dir / _FRAGMENT_NAME.format(work_no=work_no, cap=capability)
-
-    if not draft_path.exists():
-        msgs.append(f"[ERROR] fragment 草稿不存在: {draft_path}")
-        return 2, None, msgs
-
-    try:
-        draft = json.loads(draft_path.read_text(encoding="utf-8-sig"))
-    except (json.JSONDecodeError, OSError) as e:
-        msgs.append(f"[ERROR] fragment 草稿 JSON 解析失败: {e}")
-        return 3, None, msgs
-
-    if not isinstance(draft, dict):
-        msgs.append("[ERROR] fragment 草稿顶层必须是对象")
-        return 4, None, msgs
-
-    plan, normalize_msgs, hard_errors = _normalize(draft, strict=strict)
-    msgs.extend(normalize_msgs)
-
-    if hard_errors:
-        msgs.append(f"[ERROR] fragment 不可自动归一（来源：{draft_path}）：")
-        for e in hard_errors:
-            msgs.append(f"  - {e}")
-        return 4, None, msgs
-
-    foreign: list[str] = []
-    for p_idx, phase in enumerate(plan.get("phases") or []):
-        for t_idx, task in enumerate(phase.get("tasks") or []):
-            cap = str(task.get("capability") or "")
-            if cap != capability:
-                foreign.append(
-                    f"$.phases[{p_idx}].tasks[{t_idx}].capability='{cap}' 不属于 '{capability}'"
-                )
-    if foreign:
-        msgs.append(
-            f"[ERROR] fragment 含跨 capability task；fragment 必须仅含本 capability="
-            f"'{capability}' 的 tasks："
-        )
-        for e in foreign:
-            msgs.append(f"  - {e}")
-        return 4, None, msgs
-
-    schema_errors = _strict_validate(plan)
-    if schema_errors:
-        msgs.append(f"[ERROR] fragment schema 校验失败：")
-        for e in schema_errors:
-            msgs.append(f"  - {e}")
-        return 5, None, msgs
-
-    out_path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = out_path.with_suffix(out_path.suffix + ".tmp")
-    tmp.write_text(
-        json.dumps(plan, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-    tmp.replace(out_path)
-    n_tasks = sum(len(p.get("tasks") or []) for p in plan.get("phases") or [])
-    msgs.append(
-        f"[OK] capability fragment emitted: {out_path} "
-        f"(capability={capability}, tasks={n_tasks})"
-    )
-
-    return 0, plan, msgs
-
-
-def merge_fragments(
-    app_root: Path,
-    work_no: str,
-) -> tuple[int, dict[str, Any] | None, list[str]]:
-    """主控调用：扫描 fragment 文件 → 合并 → 写完整 capabilityPlan。
-
-    与 manifest 上 origin=append-fan-out 的 task 数比对；缺失或非法即拒绝合并。
-    items 顺序按 capability 字典序稳定。返回 (exit_code, plan_dict | None, messages)。
-
-    正常路径由 grouped capabilityPlan 产物 owner 显式调用且仅调用一次。
-    ``--mode link`` 只保留为兼容恢复别名。
-    """
-    msgs: list[str] = []
-    runtime_dir = app_root / "_runtime"
-    out_path = runtime_dir / f"design.{work_no}.capabilityPlan.json"
-
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
-    try:
-        from design_task_protocol import FAN_OUT_ORIGIN, load_manifest
-    except ImportError as exc:
-        msgs.append(f"[ERROR] 无法加载 design_task_protocol: {exc}")
-        return EXIT_UPSTREAM_PREREQ, None, msgs
-
-    manifest = load_manifest(app_root, work_no)
-    if manifest is None:
-        msgs.append("[ERROR] design manifest 不存在或非法；merge-fragments 不应被调用")
-        return EXIT_UPSTREAM_PREREQ, None, msgs
-
-    expected_caps = sorted({
-        str(t.get("taskType") or "")
-        for t in (manifest.get("tasks") or [])
-        if isinstance(t, dict) and t.get("origin") == FAN_OUT_ORIGIN
-    })
-    if not expected_caps:
-        msgs.append(
-            "[ERROR] manifest 上无 origin=append-fan-out 的 task；merge-fragments 不应被调用"
-        )
-        return EXIT_UPSTREAM_PREREQ, None, msgs
-
-    fragments_by_cap: dict[str, dict[str, Any]] = {}
-    missing: list[str] = []
-    for cap in expected_caps:
-        path = runtime_dir / _FRAGMENT_NAME.format(work_no=work_no, cap=cap)
-        if not path.is_file():
-            missing.append(str(path))
-            continue
-        try:
-            data = json.loads(path.read_text(encoding="utf-8-sig"))
-        except (json.JSONDecodeError, OSError) as e:
-            msgs.append(f"[ERROR] fragment 解析失败 {path}: {e}")
-            return 3, None, msgs
-        if not isinstance(data, dict):
-            msgs.append(f"[ERROR] fragment 顶层非对象 {path}")
-            return 4, None, msgs
-        fragments_by_cap[cap] = data
-
-    if missing:
-        msgs.append(
-            f"[ERROR] fragment 缺失：期望 capabilities={expected_caps}, "
-            f"缺失文件={missing}；merge 拒绝执行"
-        )
-        return 4, None, msgs
-
-    # 合并：按 phase 名归集 tasks，capability 字典序稳定
-    merged_phases: dict[str, list[dict[str, Any]]] = {}
-    for cap in sorted(fragments_by_cap.keys()):
-        plan = fragments_by_cap[cap]
-        for phase in plan.get("phases") or []:
-            phase_name = str(phase.get("phase") or "metadata-class")
-            merged_phases.setdefault(phase_name, []).extend(phase.get("tasks") or [])
-
-    if not merged_phases:
-        merged_phases["metadata-class"] = []
-
-    # taskId 重分配以避免跨 fragment 冲突（不同 fragment 各自从 C1 开始）
-    final_phases: list[dict[str, Any]] = []
-    counter = 1
-    seen: set[str] = set()
-    for phase_name in sorted(merged_phases.keys()):
-        new_tasks: list[dict[str, Any]] = []
-        for task in merged_phases[phase_name]:
-            tid = str(task.get("taskId") or "")
-            if not tid or tid in seen or not RE_TASK_ID.match(tid):
-                while f"C{counter}" in seen:
-                    counter += 1
-                tid = f"C{counter}"
-                counter += 1
-                task = dict(task)
-                task["taskId"] = tid
-            seen.add(tid)
-            new_tasks.append(task)
-        final_phases.append({"phase": phase_name, "tasks": new_tasks})
-
-    merged = {"version": "1.0.0", "phases": final_phases}
-
-    schema_errors = _strict_validate(merged)
-    if schema_errors:
-        msgs.append("[ERROR] fragments 合并产物 schema 校验失败：")
-        for e in schema_errors:
-            msgs.append(f"  - {e}")
-        return 5, None, msgs
-
-    out_path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = out_path.with_suffix(out_path.suffix + ".tmp")
-    tmp.write_text(
-        json.dumps(merged, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-    tmp.replace(out_path)
-    if not _try_inline_compile(app_root, work_no, out_path):
-        msgs.append(
-            "[ERROR] fragments 已合并但 capabilityPlan 编译失败；"
-            "grouped tasks 禁止标记 completed"
-        )
-        return 4, merged, msgs
-    _register_cp_section_in_manifest(app_root, work_no)
-    merged = json.loads(out_path.read_text(encoding="utf-8-sig"))
-    n_tasks = sum(len(p.get("tasks") or []) for p in merged.get("phases") or [])
-    msgs.append(
-        f"[OK] fragments merged: {out_path} "
-        f"(fragments={list(fragments_by_cap.keys())}, tasks={n_tasks})"
-    )
-    return 0, merged, msgs
-
-
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="规整化 capability plan 草稿为 PRD schema 产物"
-    )
-    parser.add_argument("--app-root", required=True, help="Absolute path to app root")
-    parser.add_argument("--work-no", required=True, help="工作项编号（如 000 / 001）")
-    parser.add_argument(
-        "--strict", action="store_true",
-        help="严格模式：发现任何自创字段名直接 ERROR，不做兼容映射",
-    )
-    parser.add_argument(
-        "--compile", action="store_true",
-        help="规整后使用 metadata-snapshot 编译 input（M2.2）并覆盖产物",
-    )
-    parser.add_argument(
-        "--mode",
-        choices=("emit", "emit-fragment", "merge-fragments", "link"),
-        default="emit",
-        help=(
-            "emit: 默认模式，规整完整 plan 草稿（兼容旧路径）；"
-            "emit-fragment: fan-out 子 Agent 调用，需配合 --capability；"
-            "merge-fragments: 扫描 fragment 文件合并为完整 plan；"
-            "link: 兼容恢复命令；正常流程显式调用一次 merge-fragments"
-        ),
-    )
-    parser.add_argument(
-        "--capability", default="",
-        help="emit-fragment 模式必填：本 fan-out 子 Agent 负责的 capability 名",
-    )
-    parser.add_argument(
-        "--force-unlock", action="store_true",
-        help="强制清理兼容 link 锁残留（异常中断后恢复）",
-    )
-    parser.add_argument(
-        "--relink", action="store_true",
-        help=(
-            "强制重新合并主段：主段已存在时删除后重跑 merge_fragments。"
-            "emit-fragment / link 两种模式下均生效；默认不开启时，仅"
-            "在 fragment mtime > 主段 mtime 时自动重链。"
-        ),
-    )
-    args = parser.parse_args(argv)
-
-    app_root = Path(args.app_root).resolve()
-    if not app_root.exists():
-        print(f"[ERROR] app-root not found: {app_root}", file=sys.stderr)
-        return 2
-
-    work_no = str(args.work_no).strip()
-
-    # --force-unlock: 强制清理锁残留
-    if getattr(args, "force_unlock", False):
-        lock_path = app_root / "_runtime" / _LINK_LOCK_NAME
-        if lock_path.is_file():
-            lock_path.unlink()
-            print(f"[OK] 锁文件已清理: {lock_path}", file=sys.stderr)
-        else:
-            print(f"[INFO] 锁文件不存在: {lock_path}", file=sys.stderr)
-        if args.mode not in ("link",):
-            return 0
-
-    # --mode link: 兼容恢复别名
-    if args.mode == "link":
-        _run_compat_link(app_root, work_no, relink=getattr(args, "relink", False))
-        out_path = app_root / "_runtime" / f"design.{work_no}.capabilityPlan.json"
-        if out_path.is_file():
-            print(f"[OK] 主段已产出: {out_path}")
-            return 0
-        else:
-            print("[WARN] link 未成功（fragment 未到齐或 classification 缺失）", file=sys.stderr)
-            return 4
-
-    if args.mode == "emit-fragment":
-        cap = str(args.capability).strip()
-        if not cap:
-            print("[ERROR] --capability is required for --mode emit-fragment", file=sys.stderr)
-            return 2
-        if args.compile:
-            print(
-                "[WARN] --compile 在 emit-fragment 模式下被忽略；"
-                "fragment 编译留待主控 merge-fragments 后整体处理",
-                file=sys.stderr,
-            )
-        code, _plan, msgs = emit_fragment(
-            app_root, work_no, cap,
-            strict=args.strict,
-            relink=getattr(args, "relink", False),
-        )
-        for m in msgs:
-            if m.startswith("[ERROR]") or m.startswith("  -") or m.startswith("  参考"):
-                print(m, file=sys.stderr)
-            else:
-                print(m)
-        return code
-
-    if args.mode == "merge-fragments":
-        code, _plan, msgs = merge_fragments(app_root, work_no)
-        for m in msgs:
-            if m.startswith("[ERROR]") or m.startswith("  -") or m.startswith("  参考"):
-                print(m, file=sys.stderr)
-            else:
-                print(m)
-        return code
-
-    if args.compile:
-        code, _plan, msgs = emit_and_compile(app_root, work_no, strict=args.strict)
-    else:
-        code, _plan, msgs = emit(app_root, work_no, strict=args.strict)
-    for m in msgs:
-        # 把 [INFO]/[WARN]/[OK] 走 stdout，[ERROR] 走 stderr
-        if m.startswith("[ERROR]") or m.startswith("  -") or m.startswith("  参考"):
-            print(m, file=sys.stderr)
-        else:
-            print(m)
-    return code
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())