fix(workflow): 强化 work 收口与 tasks 回写门禁

sincerely90 · sincerely90 · commit 9bdf9acd340c · 2026-06-13T15:11:06.000+08:00
diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
@@ -1,6 +1,6 @@
 {
   "name": "aisee-plugin",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "interface": {
     "displayName": "Aisee Plugin",
     "description": "Aisee plugin marketplace for OpenSpec, project memory, team knowledge, and Compound Engineering workflows."
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 本项目遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) 的结构，并使用 SemVer 管理版本。
 
+## [0.11.2] - 2026-06-13
+
+### Changed
+
+- `aisee:implementation-bridge`、Implementation Brief 模板、workflow 和 README 明确收口门禁：`ce-work` 完成当前批次前，必须先回写 `tasks.md` 或当前 schema 的 apply tracks。
+- `aisee context pack --for ce-work --json` 新增 `facts.derived.execution.completion_gate`，显式暴露 apply tracks、完成证据和 `writeback-required` 状态，避免执行层把“代码已改”误判为“work 已完成”。
+- `aisee context pack --for ce-work --json` 与 `--for aisee-verify --json` 在发现已有 review/test/manual evidence、但 apply tracks 仍无任何已完成项时，会报出 `APPLY_TRACKS_WRITEBACK_REQUIRED` blocker，阻止遗漏 `tasks.md` 回写。
+
 ## [0.11.1] - 2026-06-12
 
 ### Changed
diff --git a/README.en.md b/README.en.md
@@ -323,7 +323,7 @@ aisee doctor --json
 4. aisee:change-author
 5. openspec validate <change>
 6. aisee:implementation-bridge
-7. implementation / review / test
+7. implementation / review / test (write back `tasks.md` / apply tracks before marking the batch complete)
 8. openspec archive <change>
 
 For small, bounded, low-risk work, an abbreviated path is also valid:
diff --git a/README.md b/README.md
@@ -323,7 +323,7 @@ aisee doctor --json
 4. aisee:change-author
 5. openspec validate <change>
 6. aisee:implementation-bridge
-7. implementation / review / test
+7. implementation / review / test（完成当前批次前先回写 `tasks.md` / apply tracks）
 8. openspec archive <change>
 
 对小范围、边界明确、低风险工作，也可以直接走：
@@ -332,7 +332,7 @@ aisee doctor --json
 quick-fix / quick-research / 其它轻量 schema
   -> change-author
   -> implementation-bridge
-  -> implementation / review / test
+  -> implementation / review / test（完成当前批次前先回写 `tasks.md` / apply tracks）
   -> archive
 ```
 ```
diff --git a/docs/workflow.en.md b/docs/workflow.en.md
@@ -172,7 +172,7 @@ Implementation can be handled by a coding agent or human developer. Regardless o
 
 - Implement only the current change scope.
 - If specs, contracts, and code disagree, update the current OpenSpec change before continuing.
-- Update `tasks.md` or the current schema apply tracks after implementation.
+- Do not defer this until verify or archive; before `ce-work` reports the current batch complete, update `tasks.md` or the current schema apply tracks first.
 - Record test, manual verification, preview, monitoring, or review results as evidence.
 
 When a change touches public CLI behavior, HTTP endpoints, API/service contracts, schemas, parsers, path reads, security, or privacy, Tier 2 code review is recommended.
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -172,7 +172,7 @@ Knowledge matches 只作为提醒，不改变当前 change 的规范事实源，
 
 - 只实现当前 change 范围。
 - 如果发现 spec/contract/code 不一致，先回写当前 OpenSpec change，再继续实现。
-- 完成后更新 `tasks.md` 或当前 schema 的 apply tracks。
+- 不要等到 verify 或 archive 前再补写；`ce-work` 完成当前批次前，就应先更新 `tasks.md` 或当前 schema 的 apply tracks。
 - 测试、人工验证、预览、监控或 review 结果必须作为 evidence 记录。
 
 当 change 触及公开 CLI、HTTP endpoint、API/service contract、schema、parser、路径读取、安全或隐私表面时，建议执行 Tier 2 code review。
diff --git a/plugins/aisee-plugin/.claude-plugin/plugin.json b/plugins/aisee-plugin/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "aisee-plugin",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "AI-Enhanced Software Engineering plugin for OpenSpec and Compound Engineering workflows.",
   "author": {
     "name": "Fengliang"
diff --git a/plugins/aisee-plugin/.codex-plugin/plugin.json b/plugins/aisee-plugin/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "aisee-plugin",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "AI-Enhanced Software Engineering plugin for OpenSpec and Compound Engineering workflows.",
   "author": {
     "name": "Fengliang"
diff --git a/plugins/aisee-plugin/.cursor-plugin/plugin.json b/plugins/aisee-plugin/.cursor-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "aisee-plugin",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "AI-Enhanced Software Engineering plugin for OpenSpec and Compound Engineering workflows.",
   "author": {
     "name": "Fengliang"
diff --git a/plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md b/plugins/aisee-plugin/skills/aisee-implementation-bridge/SKILL.md
@@ -181,8 +181,11 @@ Brief 只做执行索引，不复制 OpenSpec artifact 正文：
 - 不创建新的长期计划文件；需要临时推理时，结论必须回写当前 schema 的 apply tracks 或追踪 artifact。
 - 不扩大 change 范围；超出范围的发现记录为 follow-up 或新 change 候选。
 - 完成实现后必须更新当前 schema 的 apply tracks 和验证证据；没有 apply tracks 的 schema 只记录必要 evidence。
+- `ce-work` 只有在本轮实现涉及的 apply tracks 已同步回写后，才能声明当前批次完成；app/device/quick-fix 默认先更新 `tasks.md` checkbox、验证任务和 evidence 入口，再离开 `ce-work`。
 - UI 实现涉及图标时，先复用项目已使用的组件库、图标包或设计系统图标；没有合适图标时允许使用 `better-icons` / Iconify 检索。优先使用全局安装的 `better-icons` 以减少冷启动；缺少时执行阶段应按项目包管理器安装或用 `npx -y better-icons` / `bunx better-icons` 完成一次性检索，并在 evidence 中记录命令、图标库和完整图标 ID。不要为了常见 UI 图标手写 SVG。
 
+CHECKPOINT: `ce-work` 完成前，必须先回写当前 schema 的 apply tracks。对默认以 `tasks.md` 追踪的 schema，至少要同步当前批次已完成 / 未完成状态、验证任务和 evidence 入口；如果代码已改但 apply tracks 仍未更新，不得把该批次报告为完成。
+
 ## 实现后审查建议
 
 Brief 必须根据当前 change 和 context pack 判断是否建议 Tier 2 code review。触发条件与 `aisee:verify` 保持一致：
diff --git a/plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-index-template.md b/plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-index-template.md
@@ -65,6 +65,7 @@ change_refs:
 ## Writeback Rules
 
 - Apply tracks:
+- Work completion gate:
 - Source-map, only if generated by schema:
 - Contract/artifact gap destination:
 - Evidence destination:
diff --git a/plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-template.md b/plugins/aisee-plugin/skills/aisee-implementation-bridge/references/brief-template.md
@@ -50,11 +50,13 @@ change_refs:
 - Allowed test paths:
 - Start from:
 - Apply tracks to update:
+- Before marking work complete:
 
 ## Rules
 
 - Follow current schema apply tracks; do not create a parallel durable plan.
 - Preserve traceability: source-map schema updates `source-map.md`; lighter schemas update the relevant artifact / apply tracks.
+- Do not report the current batch as complete before apply tracks are updated. For `tasks.md` schemas, update checkbox state, verification tasks, and evidence entry first.
 - If implementation facts conflict with specs or contracts, stop and update the current OpenSpec change first.
 - UI icons: reuse the project's component library or icon package first. If no suitable icon exists, use globally installed `better-icons` / Iconify first for speed; install or invoke it via the project package manager, `npx -y better-icons`, or `bunx better-icons` when missing. Record the command and final `prefix:name` icon IDs as evidence.
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aisee-plugin"
-version = "0.11.1"
+version = "0.11.2"
 description = "AI-Enhanced Software Engineering plugin for OpenSpec and Compound Engineering workflows."
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/src/aisee_cli/__init__.py b/src/aisee_cli/__init__.py
@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.11.1"
+__version__ = "0.11.2"
diff --git a/src/aisee_cli/context_pack.py b/src/aisee_cli/context_pack.py
@@ -107,6 +107,8 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
     traceability_mode = derive_traceability_mode(upstream_refs, produced_local_ids)
     parsed_artifacts = slim_artifacts(full_parsed_artifacts) if target == "ce-work" else full_parsed_artifacts
 
+    evidence = build_evidence(root, change)
+
     gaps = build_gaps(
         change_path=change_path,
         artifact_entries=artifact_entries,
@@ -123,6 +125,7 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
         schema_resolution=schema_resolution,
         schema_paths=schema_paths,
         produced_local_ids=produced_local_ids,
+        evidence=evidence,
     )
 
     read_order = build_read_order(root, change_path, artifact_entries, read_paths)
@@ -197,7 +200,7 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
         "generated": None,
         "gaps": gaps,
         "guardrails": build_guardrails(target, source_map_required, tasks_required),
-        "evidence": build_evidence(root, change),
+        "evidence": evidence,
         "meta": {
             "command": f"aisee context pack --change {change} --for {target} --json",
             "generated_at": datetime.now(timezone.utc).isoformat(),
@@ -221,6 +224,11 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
                 ce_plan_refinement_reason=ce_plan_refinement_reason,
                 gaps=gaps,
             ),
+            "completion_gate": build_completion_gate(
+                apply_tracks=pack["facts"]["parsed"]["schema"]["apply_tracks"],
+                task_state=task_state,
+                evidence=evidence,
+            ),
         }
         pack["facts"]["derived"]["execution"]["brief"] = build_execution_brief(
             root=root,
@@ -232,6 +240,9 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
             start_from=pack["facts"]["derived"]["execution"]["start_from"],
             verification_requirements=pack["facts"]["derived"]["verification_requirements"],
             gaps=gaps,
+            task_state=task_state,
+            evidence=evidence,
+            apply_tracks=pack["facts"]["parsed"]["schema"]["apply_tracks"],
         )
     elif target == "aisee-verify":
         pack["facts"]["derived"]["checks"] = {
@@ -244,7 +255,11 @@ def build_context_pack(project_root: Path, change: str, target: str) -> dict[str
             "tasks": summarize_task_checks(task_state),
             "contracts": summarize_contract_checks(artifact_entries, source_map, source_map.get("contract_sync")),
             "implementation": summarize_implementation_checks(code_paths, test_paths, source_map_required),
-            "review_and_tests": [],
+            "review_and_tests": summarize_review_and_test_checks(
+                evidence=evidence,
+                task_state=task_state,
+                apply_tracks=pack["facts"]["parsed"]["schema"]["apply_tracks"],
+            ),
         }
         pack["facts"]["derived"]["drift_candidates"] = []
     elif target == "ce-doc-review":
@@ -771,6 +786,7 @@ def build_gaps(
     schema_resolution: dict[str, Any],
     schema_paths: SchemaPaths,
     produced_local_ids: list[str],
+    evidence: dict[str, Any],
 ) -> list[dict[str, Any]]:
     gaps: list[dict[str, Any]] = []
     if not change_path.exists():
@@ -914,6 +930,13 @@ def build_gaps(
                     unmapped_reference_paths,
                 )
             )
+    apply_track_stale_gap = build_apply_track_writeback_gap(
+        schema_info=schema_info,
+        task_state=task_state,
+        evidence=evidence,
+    )
+    if apply_track_stale_gap is not None:
+        gaps.append(apply_track_stale_gap)
     gaps.extend(contract_sync_gaps(schema_info, artifact_entries, source_map, tasks_text))
     return gaps
 
@@ -1144,6 +1167,9 @@ def build_execution_brief(
     start_from: list[str],
     verification_requirements: list[str],
     gaps: list[dict[str, Any]],
+    task_state: dict[str, Any],
+    evidence: dict[str, Any],
+    apply_tracks: str | None,
 ) -> dict[str, Any]:
     authoritative_sources = [
         rel(root, change_path / relative_path)
@@ -1170,6 +1196,11 @@ def build_execution_brief(
         "allowed_paths": allowed_paths,
         "task_start": start_from,
         "verification": verification_requirements,
+        "completion_gate": build_completion_gate(
+            apply_tracks=apply_tracks,
+            task_state=task_state,
+            evidence=evidence,
+        ),
         "risks": risk_items,
     }
 
@@ -1199,6 +1230,31 @@ def build_guardrails(target: str, source_map_required: bool, tasks_required: boo
     return common
 
 
+def build_completion_gate(
+    *,
+    apply_tracks: str | None,
+    task_state: dict[str, Any],
+    evidence: dict[str, Any],
+) -> dict[str, Any]:
+    completion_evidence = collect_completion_evidence_paths(evidence)
+    return {
+        "apply_tracks": apply_tracks,
+        "must_write_back_before_complete": bool(apply_tracks),
+        "task_state": {
+            "total": task_state["total"],
+            "done": task_state["done"],
+            "open": task_state["open"],
+            "blocked": task_state["blocked"],
+        },
+        "completion_evidence_paths": completion_evidence,
+        "status": (
+            "writeback-required"
+            if apply_tracks and completion_evidence and task_state["done"] == 0 and task_state["total"] > 0
+            else "ready"
+        ),
+    }
+
+
 def build_evidence(root: Path, change: str) -> dict[str, Any]:
     review_dir = root / "docs" / "reviews"
     review_files: list[str] = []
@@ -1226,6 +1282,28 @@ def build_evidence(root: Path, change: str) -> dict[str, Any]:
     }
 
 
+def collect_completion_evidence_paths(evidence: dict[str, Any]) -> list[str]:
+    paths: list[str] = []
+    for key in ("ce_doc_review", "ce_code_review", "aisee_review_lens", "tests", "manual_verification"):
+        value = evidence.get(key)
+        if isinstance(value, list):
+            paths.extend(path for path in value if isinstance(path, str))
+    domain = evidence.get("details", {}).get("domain", {})
+    if isinstance(domain, dict):
+        for categories in domain.values():
+            if not isinstance(categories, dict):
+                continue
+            for entries in categories.values():
+                if not isinstance(entries, list):
+                    continue
+                for entry in entries:
+                    if isinstance(entry, dict):
+                        path = entry.get("path")
+                        if isinstance(path, str) and path:
+                            paths.append(path)
+    return dedupe(paths)
+
+
 def classify_evidence(review_files: list[str], verification_files: list[str]) -> dict[str, dict[str, list[str]]]:
     return {
         "docsite": {
@@ -1532,6 +1610,43 @@ def summarize_implementation_checks(code_paths: list[str], test_paths: list[str]
     }]
 
 
+def summarize_review_and_test_checks(
+    *,
+    evidence: dict[str, Any],
+    task_state: dict[str, Any],
+    apply_tracks: str | None,
+) -> list[dict[str, Any]]:
+    completion_evidence = collect_completion_evidence_paths(evidence)
+    return [{
+        "apply_tracks": apply_tracks,
+        "completion_evidence_count": len(completion_evidence),
+        "completion_evidence_paths": completion_evidence,
+        "task_done_count": task_state["done"],
+        "writeback_consistent": not (apply_tracks and completion_evidence and task_state["done"] == 0 and task_state["total"] > 0),
+    }]
+
+
+def build_apply_track_writeback_gap(
+    *,
+    schema_info: dict[str, Any],
+    task_state: dict[str, Any],
+    evidence: dict[str, Any],
+) -> dict[str, Any] | None:
+    apply_tracks = schema_info.get("apply_tracks")
+    if not isinstance(apply_tracks, str) or not apply_tracks.strip():
+        return None
+    completion_evidence = collect_completion_evidence_paths(evidence)
+    if not completion_evidence or task_state["total"] == 0 or task_state["done"] > 0:
+        return None
+    return gap(
+        "APPLY_TRACKS_WRITEBACK_REQUIRED",
+        "blocker",
+        "implementation or verification evidence exists, but apply tracks still show no completed tasks; update apply tracks before reporting work complete",
+        apply_tracks,
+        completion_evidence,
+    )
+
+
 def extract_paths(text: str) -> set[str]:
     paths = {match.group(1).rstrip(".,;:)]}") for match in PATH_PATTERN.finditer(text)}
     return {path for path in paths if not path.endswith("/")}
diff --git a/tests/test_context_pack.py b/tests/test_context_pack.py
diff --git a/tests/test_skill_cli_preflight.py b/tests/test_skill_cli_preflight.py

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "aisee-plugin",`
`3`		`- "version": "0.11.1",`
	`3`	`+ "version": "0.11.2",`
`4`	`4`	`"interface": {`
`5`	`5`	`"displayName": "Aisee Plugin",`
`6`	`6`	`"description": "Aisee plugin marketplace for OpenSpec, project memory, team knowledge, and Compound Engineering workflows."`