🐛 fix(main_loop): enforce plan lifecycle ordering

Claim the first executable plan in plan-file order after resuming any in-progress plan, preserve skipped as its own workflow phase, and document the required post-done commit gate in the agent rules.

tests/test_main_loop_cli.py

@@ -245,6 +245,55 @@ class MainLoopCliTests(unittest.TestCase):
             text = progress.read_text(encoding="utf-8")
             self.assertIn(f"`2026-01-05-env.md` in-progress: {note}", text)
 
+    def test_claim_prefers_earlier_env_blocked_plan_over_later_pending_plan(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            plans_dir = root / "docs" / "superpowers" / "plans"
+            plans_dir.mkdir(parents=True)
+            (plans_dir / "2026-01-01-env.md").write_text("env", encoding="utf-8")
+            (plans_dir / "2026-01-02-pending.md").write_text(
+                "pending", encoding="utf-8"
+            )
+
+            progress = root / "memory-bank" / "progress.md"
+            progress.parent.mkdir(parents=True)
+            env = self._current_env()
+            note = f"env:{env}:Task2"
+            progress.write_text(
+                "\n".join(
+                    [
+                        "# Plan 状态",
+                        "",
+                        "<!-- plan-status:start -->",
+                        f"- [ ] `2026-01-01-env.md` blocked: {note}",
+                        "- [ ] `2026-01-02-pending.md` pending",
+                        "<!-- plan-status:end -->",
+                        "",
+                    ]
+                ),
+                encoding="utf-8",
+            )
+
+            result = run_cli(
+                "claim",
+                "-plans",
+                "docs/superpowers/plans",
+                "-progress",
+                "memory-bank/progress.md",
+                cwd=root,
+            )
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            self.assertEqual(
+                result.stdout.strip(),
+                "\n".join(
+                    [
+                        "PLAN=docs/superpowers/plans/2026-01-01-env.md",
+                        f"NOTE={note}",
+                    ]
+                ),
+            )
+
     def test_finish_updates_line(self):
         with tempfile.TemporaryDirectory() as tmp_dir:
             root = Path(tmp_dir)
@@ -329,13 +378,62 @@ class MainLoopCliTests(unittest.TestCase):
             self.assertEqual(result.returncode, 0, msg=result.stderr)
             text = progress.read_text(encoding="utf-8")
             self.assertIn("phase: done", text)
-            self.assertIn("spec: docs/superpowers/specs/2026-05-18-demo-design.md", text)
+            self.assertIn(
+                "spec: docs/superpowers/specs/2026-05-18-demo-design.md", text
+            )
             self.assertIn("executor: executing-plans", text)
             self.assertIn(
                 "constraints: karpathy-guidelines,.agents,AGENT_RULES",
                 text,
             )
 
+    def test_finish_skipped_updates_workflow_phase_to_skipped(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            progress = root / "memory-bank" / "progress.md"
+            progress.parent.mkdir(parents=True)
+            progress.write_text(
+                "\n".join(
+                    [
+                        "# 当前进展",
+                        "",
+                        "## Workflow State",
+                        "",
+                        "<!-- workflow-state:start -->",
+                        "phase: executing",
+                        "plan: docs/superpowers/plans/2026-05-18-demo.md",
+                        "<!-- workflow-state:end -->",
+                        "",
+                        "## Plan Status",
+                        "",
+                        "<!-- plan-status:start -->",
+                        "- [ ] `2026-05-18-demo.md` in-progress",
+                        "<!-- plan-status:end -->",
+                        "",
+                    ]
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+
+            result = run_cli(
+                "finish",
+                "-plan",
+                "docs/superpowers/plans/2026-05-18-demo.md",
+                "-status",
+                "skipped",
+                "-progress",
+                "memory-bank/progress.md",
+                "-note",
+                "obsolete",
+                cwd=root,
+            )
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr)
+            text = progress.read_text(encoding="utf-8")
+            self.assertIn("phase: skipped", text)
+            self.assertIn("- [ ] `2026-05-18-demo.md` skipped: obsolete", text)
+
     def test_record_updates_workflow_state_block(self):
         with tempfile.TemporaryDirectory() as tmp_dir:
             root = Path(tmp_dir)
@@ -378,7 +476,9 @@ class MainLoopCliTests(unittest.TestCase):
             text = progress.read_text(encoding="utf-8")
             self.assertIn("<!-- workflow-state:start -->", text)
             self.assertIn("phase: planning", text)
-            self.assertIn("spec: docs/superpowers/specs/2026-05-18-demo-design.md", text)
+            self.assertIn(
+                "spec: docs/superpowers/specs/2026-05-18-demo-design.md", text
+            )
             self.assertIn("plan: docs/superpowers/plans/2026-05-18-demo.md", text)
             self.assertIn("executor: executing-plans", text)
             self.assertIn(
@@ -450,7 +550,9 @@ class MainLoopCliTests(unittest.TestCase):
 
             text = progress.read_text(encoding="utf-8")
             self.assertIn("phase: done", text)
-            self.assertIn("spec: docs/superpowers/specs/2026-05-18-demo-design.md", text)
+            self.assertIn(
+                "spec: docs/superpowers/specs/2026-05-18-demo-design.md", text
+            )
             self.assertIn("plan: docs/superpowers/plans/2026-05-18-demo.md", text)
             self.assertIn("executor: executing-plans", text)
             self.assertIn(
@@ -513,7 +615,9 @@ class MainLoopCliTests(unittest.TestCase):
 
             text = progress.read_text(encoding="utf-8")
             self.assertIn("phase: planning", text)
-            self.assertIn("spec: docs/superpowers/specs/2026-05-18-demo-design.md", text)
+            self.assertIn(
+                "spec: docs/superpowers/specs/2026-05-18-demo-design.md", text
+            )
             self.assertIn("plan: docs/superpowers/plans/2026-05-18-demo.md", text)
             self.assertIn("executor: executing-plans", text)
             self.assertIn(
@@ -571,7 +675,9 @@ class MainLoopCliTests(unittest.TestCase):
 
             text = progress.read_text(encoding="utf-8")
             self.assertIn("phase: planning", text)
-            self.assertIn("spec: docs/superpowers/specs/2026-05-18-demo-design.md", text)
+            self.assertIn(
+                "spec: docs/superpowers/specs/2026-05-18-demo-design.md", text
+            )
             self.assertIn("plan: docs/superpowers/plans/2026-05-18-demo.md", text)
             self.assertIn("executor: executing-plans", text)
             self.assertIn(

tests/test_sync_templates_placeholders.py

@@ -76,6 +76,7 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
             ROOT / "templates" / "prompts" / "coding" / "close-task.template.md"
         ).read_text(encoding="utf-8")
         self.assertIn("main_loop.py finish", close_task_template)
+        self.assertIn("如本轮来自 `main_loop.py claim`", close_task_template)
         self.assertIn("workflow-state.phase", close_task_template)
         self.assertIn("## Completed", close_task_template)
         self.assertIn("## Not Completed", close_task_template)
@@ -86,6 +87,7 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         verify_change_template = (
             ROOT / "templates" / "prompts" / "coding" / "verify-change.template.md"
         ).read_text(encoding="utf-8")
+        self.assertIn("如本轮来自 `main_loop.py claim`", verify_change_template)
         self.assertIn("workflow-state.phase", verify_change_template)
         self.assertIn("plan-status", verify_change_template)
         self.assertIn("## Validated", verify_change_template)
@@ -108,9 +110,9 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         self.assertIn("## Open Questions", code_review_template)
         self.assertIn("## Residual Risk", code_review_template)
 
-        prompts_readme = (
-            ROOT / "templates" / "prompts" / "README.md"
-        ).read_text(encoding="utf-8")
+        prompts_readme = (ROOT / "templates" / "prompts" / "README.md").read_text(
+            encoding="utf-8"
+        )
         self.assertIn("AGENT_RULES.md", prompts_readme)
         self.assertIn("docs/superpowers/", prompts_readme)
         self.assertIn("不是流程权威", prompts_readme)
@@ -132,16 +134,27 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase):
         self.assertNotIn("main_loop.py claim", agent_behavior_template)
         self.assertNotIn("playbook.py -record-spec", agent_behavior_template)
         self.assertNotIn("playbook.py -record-plan", agent_behavior_template)
-        self.assertIn("项目上下文与执行状态写入 `memory-bank/`", agent_behavior_template)
+        self.assertIn(
+            "项目上下文与执行状态写入 `memory-bank/`", agent_behavior_template
+        )
 
-        rules_template = (
-            ROOT / "templates" / "AGENT_RULES.template.md"
-        ).read_text(encoding="utf-8")
+        rules_template = (ROOT / "templates" / "AGENT_RULES.template.md").read_text(
+            encoding="utf-8"
+        )
         self.assertIn("唯一流程约束中心", rules_template)
         self.assertIn("唯一设计与计划产物中心", rules_template)
         self.assertIn("memory-bank/progress.md", rules_template)
+        self.assertIn("已有 `in-progress` 优先恢复", rules_template)
+        self.assertIn("按 Plan 文件顺序选择第一个可执行 Plan", rules_template)
+        self.assertIn("Plan `done` 后必须完成一次 commit", rules_template)
+        self.assertIn(
+            "不得由 `main_loop.py finish` 自动执行 `git commit`", rules_template
+        )
+        self.assertIn("工作区保持干净后再领取下一个 Plan", rules_template)
 
-    def test_sync_templates_replaces_playbook_scripts_without_main_language_support(self):
+    def test_sync_templates_replaces_playbook_scripts_without_main_language_support(
+        self,
+    ):
         with tempfile.TemporaryDirectory() as tmp_dir:
             config_body = f"""
 [playbook]