Add explicit plan artifacts

Author: Kun

.trellis/spec/backend/task-workflow-contracts.md

@@ -35,6 +35,18 @@ def update_task(
 def is_task_ready(store: TaskStore, record: TaskRecord) -> bool: ...
 def validate_task_graph(store: TaskStore) -> None: ...
 def task_graph_needs_verification(store: TaskStore) -> bool: ...
+
+def create_plan(
+    store: TaskStore,
+    *,
+    title: str,
+    content: str,
+    verification: str,
+    task_ids: list[str] | None = None,
+    metadata: dict[str, str] | None = None,
+) -> PlanArtifact: ...
+
+def get_plan(store: TaskStore, plan_id: str) -> PlanArtifact: ...
 ```
 
 ### 3. Contracts
@@ -53,6 +65,11 @@ def task_graph_needs_verification(store: TaskStore) -> bool: ...
 - `task_list` must expose ready state in rendered JSON metadata as `"ready": "true"` or `"false"`.
 - Completing a 3+ non-cancelled task graph without a verification task must expose a `verification_nudge` in the returned `task_update` JSON metadata.
 - Verification nudge is output metadata only; it must not mutate the stored task record.
+- `PlanArtifact` is the durable plan boundary for implementation workflow.
+- `PlanArtifact.verification` is required and must be non-empty.
+- `PlanArtifact.task_ids` must reference existing durable tasks.
+- Plan artifacts use a separate store namespace from task records.
+- `plan_save` and `plan_get` are main-surface tools, but they do not enter TodoWrite state.
 
 ### 4. Validation & Error Matrix
 
@@ -67,6 +84,9 @@ def task_graph_needs_verification(store: TaskStore) -> bool: ...
 | 3 completed non-verification tasks | `task_graph_needs_verification(...) is True` |
 | graph includes verification task | `task_graph_needs_verification(...) is False` |
 | `task_update` closes 3rd non-verification task | output metadata includes `verification_nudge=true` |
+| save plan with missing verification | Pydantic validation error |
+| save plan with unknown task id | `ValueError("Unknown task dependencies...")` |
+| get missing plan | `KeyError("Unknown plan...")` |
 
 ### 5. Good / Base / Bad Cases
 
@@ -100,6 +120,24 @@ update_task(store, task_id=task.id, depends_on=[task.id])
 
 Expected: reject self-dependency.
 
+#### Plan Artifact
+
+```python
+task = create_task(store, title="Implement feature")
+plan = create_plan(
+    store,
+    title="Feature plan",
+    content="Use the existing task store and tests.",
+    verification="Run pytest tests/test_tasks.py",
+    task_ids=[task.id],
+)
+```
+
+Expected:
+- plan has stable id
+- verification criteria are non-empty
+- referenced task IDs exist
+
 ### 6. Tests Required
 
 - `tests/test_tasks.py::test_task_store_transitions_dependencies_and_ready_rule`
@@ -108,6 +146,8 @@ Expected: reject self-dependency.
 - `tests/test_tasks.py::test_task_graph_needs_verification_after_closing_three_tasks`
 - `tests/test_tasks.py::test_task_graph_with_verification_task_does_not_need_nudge`
 - `tests/test_tasks.py::test_task_update_tool_marks_verification_nudge_in_output_metadata`
+- `tests/test_tasks.py::test_plan_artifact_roundtrip_requires_verification_and_known_tasks`
+- `tests/test_tasks.py::test_plan_tools_save_and_get_artifacts`
 - `tests/test_tool_system_registry.py::test_main_projection_preserves_current_product_tool_surface`
 
 ### 7. Wrong vs Correct

.trellis/tasks/04-14-redefine-coding-deepgent-final-goal/task.json

@@ -50,7 +50,8 @@
     "04-14-stage-16b-latest-valid-compact-view-selection",
     "04-14-stage-16c-virtual-pruning-view-metadata",
     "04-14-stage-17a-task-graph-readiness-and-transition-invariants",
-    "04-14-stage-17b-plan-verify-workflow-boundary"
+    "04-14-stage-17b-plan-verify-workflow-boundary",
+    "04-15-stage-17c-explicit-plan-artifact-boundary"
   ],
   "parent": null,
   "relatedFiles": [],

.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/prd.md

@@ -0,0 +1,133 @@
+# Stage 17C: Explicit Plan Artifact Boundary
+
+## Goal
+
+Add a durable explicit plan artifact boundary that can serve as stable input for later verification workflows, without adding plan-mode UI, coordinator runtime, mailbox, or multi-agent communication.
+
+## Upgraded Function
+
+The workflow system is upgraded from task completion nudges to a store-backed implementation plan artifact.
+
+## Expected Benefit
+
+* Recoverability: plans can be saved and retrieved outside chat history.
+* Testability: verification criteria become required structured data.
+* Maintainability: future verifier subagents can consume a stable artifact instead of parsing arbitrary prose.
+
+## Out of Scope
+
+* EnterPlanMode / ExitPlanMode tools
+* approval UI
+* coordinator runtime
+* mailbox / SendMessage
+* verifier subagent execution
+
+## Requirements
+
+* Add `PlanArtifact`.
+* Add `plan_save` and `plan_get`.
+* Require non-empty verification criteria.
+* Validate referenced `task_ids` exist.
+* Store plans in a namespace separate from tasks.
+* Register plan tools in the main tool surface and capability registry.
+
+## Acceptance Criteria
+
+* [ ] Plan artifacts roundtrip through store.
+* [ ] Plan artifacts reject missing verification criteria.
+* [ ] Plan artifacts reject unknown task IDs.
+* [ ] `plan_save` / `plan_get` are exposed as main tools.
+* [ ] Existing task tools still pass.
+* [ ] Focused tests, full tests, ruff, and mypy pass.
+
+## cc-haha Alignment
+
+### Expected effect
+
+Aligning this behavior should improve workflow discipline, testability, and future verifier readiness.
+
+The local runtime effect is: implementation plans become explicit artifacts with verification criteria, matching cc-haha's plan-file / ExitPlanMode principle without copying its UI or approval runtime.
+
+### Source-backed alignment matrix
+
+| Area | cc-haha source behavior | Expected local effect | Local target | Status | Decision |
+|---|---|---|---|---|---|
+| Plan file | `plans.ts`, plan-mode attachments, and `ExitPlanModeV2Tool` use a persisted plan file as workflow artifact | local workflow has a stable plan artifact | `PlanArtifact` | partial | Implement store-backed artifact now |
+| Verification criteria | plan instructions require a verification section | plan artifact must define how to verify | required `verification` field | align | Implement now |
+| Approval UI | ExitPlanMode asks/coordinates approval | user approval flow | none | defer | Out of scope |
+
+## LangChain Architecture
+
+Use:
+
+* strict Pydantic schemas
+* LangGraph store namespace
+* normal LangChain tools
+
+Avoid:
+
+* prompt-only plan parsing
+* UI approval
+* coordinator/mailbox runtime
+
+## Checkpoint: Stage 17C
+
+State:
+- checkpoint
+
+Verdict:
+- APPROVE
+
+Implemented:
+- Added `PlanArtifact`, `PlanSaveInput`, and `PlanGetInput`.
+- Added plan store helpers:
+  - `PLAN_ROOT_NAMESPACE`
+  - `plan_namespace()`
+  - `create_plan()`
+  - `get_plan()`
+- Added model-visible tools:
+  - `plan_save`
+  - `plan_get`
+- Registered plan tools in `ToolSystemContainer`.
+- Added plan capabilities to `tool_system.capabilities`.
+- Updated task workflow executable spec.
+
+Verification:
+- `pytest -q tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_app.py tests/test_subagents.py`
+- `pytest -q`
+- `ruff check src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py src/coding_deepgent/containers/tool_system.py src/coding_deepgent/tool_system/capabilities.py tests/test_tasks.py tests/test_tool_system_registry.py tests/test_tool_system_middleware.py tests/test_app.py`
+- `mypy src/coding_deepgent/tasks/schemas.py src/coding_deepgent/tasks/store.py src/coding_deepgent/tasks/tools.py src/coding_deepgent/tasks/__init__.py src/coding_deepgent/containers/tool_system.py src/coding_deepgent/tool_system/capabilities.py`
+
+cc-haha alignment:
+- Source files inspected:
+  - `/root/claude-code-haha/src/utils/plans.ts`
+  - `/root/claude-code-haha/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts`
+  - `/root/claude-code-haha/src/utils/attachments.ts`
+  - `/root/claude-code-haha/src/utils/messages.ts`
+- Aligned:
+  - plan artifact is now explicit and requires verification.
+- Deferred:
+  - plan-mode UI
+  - approval flow
+  - coordinator/mailbox runtime
+
+LangChain architecture:
+- Primitive used:
+  - LangChain tools + Pydantic schemas
+  - LangGraph store
+- Why no heavier abstraction:
+  - 17C only establishes the artifact boundary; runtime approval and verifier execution are separate stages.
+
+Boundary findings:
+- New issue handled:
+  - storing plans under the task namespace caused `list_tasks()` to read plan artifacts as tasks because LangGraph store search is prefix-like. Plan artifacts now use a separate `coding_deepgent_plans` root namespace.
+- Residual risk:
+  - plan artifacts are saved/retrieved but not yet consumed by verifier execution.
+
+Decision:
+- continue
+
+Reason:
+- Tests, ruff, and mypy passed.
+- Scope stayed non-UI and LangChain-native.
+- No coordinator, mailbox, or multi-agent communication was introduced.

.trellis/tasks/04-15-stage-17c-explicit-plan-artifact-boundary/task.json

@@ -0,0 +1,44 @@
+{
+  "id": "stage-17c-explicit-plan-artifact-boundary",
+  "name": "stage-17c-explicit-plan-artifact-boundary",
+  "title": "Stage 17C: Explicit Plan Artifact Boundary",
+  "description": "",
+  "status": "planning",
+  "dev_type": null,
+  "scope": null,
+  "priority": "P2",
+  "creator": "kun",
+  "assignee": "kun",
+  "createdAt": "2026-04-15",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "codex/stage-12-14-context-compact-foundation",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [
+    {
+      "phase": 1,
+      "action": "implement"
+    },
+    {
+      "phase": 2,
+      "action": "check"
+    },
+    {
+      "phase": 3,
+      "action": "finish"
+    },
+    {
+      "phase": 4,
+      "action": "create-pr"
+    }
+  ],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "04-14-redefine-coding-deepgent-final-goal",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}

coding-deepgent/src/coding_deepgent/containers/tool_system.py

@@ -11,7 +11,14 @@
 from coding_deepgent.permissions.rules import PermissionRuleSpec, expand_rule_specs
 from coding_deepgent.skills import load_skill
 from coding_deepgent.subagents import run_subagent
-from coding_deepgent.tasks import task_create, task_get, task_list, task_update
+from coding_deepgent.tasks import (
+    plan_get,
+    plan_save,
+    task_create,
+    task_get,
+    task_list,
+    task_update,
+)
 from coding_deepgent.tool_system import (
     ToolCapability,
     ToolGuardMiddleware,
@@ -54,7 +61,9 @@ class ToolSystemContainer(containers.DeclarativeContainer):
     memory_tools: Any = providers.Dependency(default=providers.Object([save_memory]))
     skill_tools: Any = providers.Dependency(default=providers.Object([load_skill]))
     task_tools: Any = providers.Dependency(
-        default=providers.Object([task_create, task_get, task_list, task_update])
+        default=providers.Object(
+            [task_create, task_get, task_list, task_update, plan_save, plan_get]
+        )
     )
     subagent_tools: Any = providers.Dependency(default=providers.Object([run_subagent]))
     extension_capabilities: Any = providers.Dependency(default=providers.Object([]))

coding-deepgent/src/coding_deepgent/tasks/__init__.py

@@ -1,4 +1,7 @@
 from .schemas import (
+    PlanArtifact,
+    PlanGetInput,
+    PlanSaveInput,
     TaskCreateInput,
     TaskGetInput,
     TaskListInput,
@@ -8,29 +11,42 @@
 )
 from .store import (
     TASK_ROOT_NAMESPACE,
+    PLAN_ROOT_NAMESPACE,
+    create_plan,
     create_task,
+    get_plan,
     get_task,
     is_task_ready,
     list_tasks,
+    plan_namespace,
     task_namespace,
     task_graph_needs_verification,
     update_task,
     validate_task_graph,
 )
-from .tools import task_create, task_get, task_list, task_update
+from .tools import plan_get, plan_save, task_create, task_get, task_list, task_update
 
 __all__ = [
+    "PlanArtifact",
+    "PlanGetInput",
+    "PlanSaveInput",
+    "PLAN_ROOT_NAMESPACE",
     "TASK_ROOT_NAMESPACE",
     "TaskCreateInput",
     "TaskGetInput",
     "TaskListInput",
     "TaskRecord",
     "TaskStatus",
     "TaskUpdateInput",
+    "create_plan",
     "create_task",
+    "get_plan",
     "get_task",
     "is_task_ready",
     "list_tasks",
+    "plan_get",
+    "plan_namespace",
+    "plan_save",
     "task_create",
     "task_get",
     "task_list",

coding-deepgent/src/coding_deepgent/tasks/schemas.py

@@ -85,3 +85,37 @@ def _has_update(self) -> "TaskUpdateInput":
         ):
             raise ValueError("at least one update field is required")
         return self
+
+
+class PlanArtifact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    title: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    verification: str = Field(..., min_length=1)
+    task_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("id", "title", "content", "verification", mode="before")
+    @classmethod
+    def _strip_plan_text(cls, value: str) -> str:
+        return str(value).strip()
+
+
+class PlanSaveInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    title: str = Field(..., min_length=1)
+    content: str = Field(..., min_length=1)
+    verification: str = Field(..., min_length=1)
+    task_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, str] = Field(default_factory=dict)
+    runtime: ToolRuntime
+
+
+class PlanGetInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    plan_id: str = Field(..., min_length=1)
+    runtime: ToolRuntime