docs(pr138): retrofit acceptance-pack evidence for evidence-first review gate

dare_framework/plan_v2/__init__.py

@@ -7,16 +7,21 @@
 from dare_framework.plan_v2.registry import SubAgentRegistry
 from dare_framework.plan_v2.types import (
     Milestone,
+    PlanStateName,
     PlannerState,
+    STEP_STATES,
     Step,
     Task,
+    is_valid_state_transition,
 )
 from dare_framework.plan_v2.prompts import PLAN_AGENT_SYSTEM_PROMPT, SUB_AGENT_TASK_PROMPT
 from dare_framework.plan_v2.tools import (
     CreatePlanTool,
     DecomposeTaskTool,
     DelegateToSubAgentTool,
+    FinishPlanTool,
     ReflectTool,
+    ReviseCurrentPlanTool,
     ValidatePlanTool,
     VerifyMilestoneTool,
 )
@@ -25,15 +30,20 @@
     "CreatePlanTool",
     "DecomposeTaskTool",
     "DelegateToSubAgentTool",
+    "FinishPlanTool",
     "Milestone",
     "PLAN_AGENT_SYSTEM_PROMPT",
+    "PlanStateName",
     "Planner",
     "SUB_AGENT_TASK_PROMPT",
+    "STEP_STATES",
     "PlannerState",
     "ReflectTool",
+    "ReviseCurrentPlanTool",
     "Step",
     "SubAgentRegistry",
     "Task",
     "ValidatePlanTool",
     "VerifyMilestoneTool",
+    "is_valid_state_transition",
 ]

dare_framework/plan_v2/planner.py

@@ -9,7 +9,9 @@
 from dare_framework.plan_v2.tools import (
     CreatePlanTool,
     DecomposeTaskTool,
+    FinishPlanTool,
     ReflectTool,
+    ReviseCurrentPlanTool,
     SubAgentTool,
     ValidatePlanTool,
     VerifyMilestoneTool,
@@ -30,6 +32,8 @@ def __init__(
         self._tools: list[ITool] = [
             CreatePlanTool(self._state),
             ValidatePlanTool(self._state),
+            ReviseCurrentPlanTool(self._state),
+            FinishPlanTool(self._state),
             VerifyMilestoneTool(self._state),
             ReflectTool(self._state),
             DecomposeTaskTool(self._state),

dare_framework/plan_v2/prompts.py

@@ -1,11 +1,13 @@
 """Plan Agent and sub-agent prompts."""
 
-PLAN_AGENT_SYSTEM_PROMPT = """You are a planning agent. You have tools to create and validate a plan, and to delegate steps to sub-agents. Each sub-agent (e.g. sub_agent_general) is a tool: pass the step description as "task" and the step identifier as "step_id".
-Before every action, check the [Plan State] block: it shows Phase, Completed, Pending, and **NEXT**. Follow **NEXT** strictly; do not repeat completed steps.
+PLAN_AGENT_SYSTEM_PROMPT = """You are a planning agent. You have tools to create, validate, revise, and finish a plan, and to delegate steps to sub-agents. Each sub-agent (e.g. sub_agent_general) is a tool: pass the step description as "task" and the step identifier as "step_id".
+Before every action, check the [Plan State] block: it shows Plan Status, step statuses, Completed, Pending, and **NEXT**. Follow **NEXT** strictly; do not repeat completed steps.
 When the user gives a task:
 1. Call create_plan exactly once with plan_description (short summary) and steps: a list of objects, each with step_id (e.g. "step1"), description (what to do), and optional params (dict). Do NOT call create_plan again after success.
 2. Call validate_plan(success=True) to confirm the plan.
 3. For each step, call the matching sub-agent tool (e.g. sub_agent_general) with task=<step description> and step_id=<step_id from plan>. Delegate each step exactly once; do not repeat a completed step. Check the tool result's "progress" field: only delegate steps that are in "Pending", never repeat steps in "Completed". Execute steps in order.
+4. If plan content must change, call revise_current_plan and then validate_plan(success=True) again.
+5. When all steps are terminal, call finish_plan(target_state="done" or "abandoned") to close the plan.
 Keep steps concise and ordered. Use sub-agent tools (sub_agent_general, sub_agent_special_*) to execute steps; do not execute steps yourself."""
 
 SUB_AGENT_TASK_PROMPT = """You receive a task from the plan agent. Execute it using your tools and return a clear result. Be concise."""