fix(plan): harden artifacts and build lifecycle

Clarify the plan skill with a complete artifact example and remove the
obsolete todo dependencies field from the frontend contract.

Add non-blocking Write diagnostics for malformed .plan.md artifacts so
files remain saved while agents receive structured repair guidance.

Improve plan builds by:
- Binding active builds to their session and turn
- Rejecting builds without valid todo IDs
- Settling state when the owning turn terminates
- Preventing builds with unsaved editor changes
- Preserving the current agent and sending only the plan path

Author: wsp1911

src/crates/assembly/core/builtin_skills/plan/SKILL.md

@@ -10,40 +10,37 @@ Produce a concise, evidence-backed implementation plan and leave project source
 ## Workflow
 
 1. Inspect the relevant code, configuration, documentation, and repository instructions using read-only tools. Resolve important behavior and ownership questions before drafting the plan.
-2. Ask the user only when missing information would materially change the approach. Present concrete options and put the recommended option first. Do not ask whether to proceed merely because research is complete.
+2. Ask the user when missing information would materially change the approach. Present concrete options and put the recommended option first. Do not ask whether to proceed merely because research is complete.
 3. Use `Task` only for read-only research that materially improves the plan. Keep delegated scopes bounded and synthesize the findings yourself.
-4. Write one plan artifact at `.bitfun/plans/<short-kebab-name>.plan.md`. Use a concise descriptive filename, and do not overwrite a different existing plan blindly.
-5. After a successful plan Write, stop tool use and link the plan file without repeating its contents.
+4. Use `Write` to create one plan artifact at `.bitfun/plans/<short-kebab-name>.plan.md`. Use a concise descriptive filename, and do not overwrite a different existing plan blindly.
+5. Once the plan artifact is created and meets the format and content requirements, stop tool use and link the file without repeating its contents.
 
 ## Plan Artifact
 
-Use `Write` with a payload containing the path header followed by the complete file:
+Create the artifact using this complete file structure. The artifact consists of a YAML frontmatter and a non-empty Markdown body whose first line is a level-1 heading.
 
-```text
-+++ .bitfun/plans/<short-kebab-name>.plan.md
-<complete plan file>
-```
-
-The file must start with YAML frontmatter in this shape. Always include `todos`; use `todos: []` for a simple plan. Every todo starts as `pending`, has a stable kebab-case ID, and includes `dependencies`, using `[]` when it has none.
-
-```yaml
+```markdown
 ---
 name: Short Plan Name
 overview: One or two sentence overview
 todos:
   - id: stable-todo-id
     content: Specific actionable task
     status: pending
-    dependencies: []
 ---
+
+# Short Plan Name
+
+...
 ```
 
-Follow the frontmatter with a non-empty Markdown body whose first line is a level-1 heading. Keep the plan proportional to the request and cite specific workspace-relative files with Markdown links when useful.
+- Todos help break down complex plans into manageable, trackable tasks. Always include `todos`; use `todos: []` for a simple plan. Every todo starts as `pending` and has a stable kebab-case ID.
+- The plan should be concise and actionable. Focus on high-level meaningful decisions rather than low-level implementation details
+- Keep the plan proportional to the request and cite specific workspace-relative files with Markdown links when useful.
 
 ## Rules
 
 - Do not edit project source, change configuration, run mutating commands, or otherwise implement the task while this planning workflow applies. The only permitted mutation is a `.bitfun/plans/*.plan.md` artifact.
-- If the plan Write fails or falls back under `.bitfun/tmp`, fix only the plan artifact write and retry; that fallback is not a completed plan.
-- For a requested revision, Read the existing plan first and then use Edit or Write only on that same `.bitfun/plans/*.plan.md` file. Do not create another plan card merely to revise it.
-- The successful plan Write is the final tool call for the planning turn.
-- Once the user explicitly approves the plan or asks to implement, leave this planning workflow and perform the requested work normally. This skill does not require an Agent or mode switch.
+- Before creating a new plan, inspect `.bitfun/plans` and choose an unused filename.
+- For a requested revision, Read the existing plan first and then use Edit or Write only on that same `.bitfun/plans/*.plan.md` file.
+- Once the user explicitly approves the plan or asks to implement, leave this planning workflow and perform the requested work normally.

src/crates/assembly/core/src/agentic/tools/implementations/file_write_tool.rs

@@ -1,3 +1,6 @@
+use super::plan_artifact_diagnostics::{
+    diagnose_plan_artifact, is_plan_artifact_path, PlanArtifactIssue,
+};
 use crate::agentic::tools::file_permissions::file_permission_intents_allowing_managed_plan_edits;
 use crate::agentic::tools::file_read_state_runtime::{
     assert_file_not_unexpectedly_modified, file_mutation_timestamp_ms, get_stored_file_read_state,
@@ -240,6 +243,7 @@ impl FileWriteTool {
         missing_path_fallback: bool,
         path_format_warning: Option<&str>,
         ignored_parameter_names: &[String],
+        plan_artifact_issues: Option<&[PlanArtifactIssue]>,
     ) -> ToolResult {
         let mut assistant_message = if missing_path_fallback {
             format!(
@@ -264,19 +268,42 @@ impl FileWriteTool {
                 formatted_names
             ));
         }
+        if let Some(issues) = plan_artifact_issues.filter(|issues| !issues.is_empty()) {
+            assistant_message.push_str("\nThe `.plan.md` artifact does not match the plan format:");
+            for issue in issues {
+                assistant_message.push_str("\n- ");
+                assistant_message.push_str(&issue.message);
+            }
+            assistant_message.push_str(
+                "\nUse Edit on the written file to fix these issues before finishing.",
+            );
+        }
+        let mut data = json!({
+            "file_path": logical_path,
+            "bytes_written": outcome.bytes_written,
+            "lines_written": outcome.lines_written,
+            "success": true,
+            "status": outcome.status.as_str(),
+            "missing_path_fallback": missing_path_fallback,
+            "rename_required": missing_path_fallback,
+            "path_format_corrected": path_format_warning.is_some(),
+            "path_format_warning": path_format_warning,
+            "message": assistant_message,
+        });
+        if let Some(issues) = plan_artifact_issues {
+            data["plan_format"] = json!({
+                "valid": issues.is_empty(),
+                "issues": issues
+                    .iter()
+                    .map(|issue| json!({
+                        "code": issue.code,
+                        "message": issue.message.as_str(),
+                    }))
+                    .collect::<Vec<_>>(),
+            });
+        }
         ToolResult::Result {
-            data: json!({
-                "file_path": logical_path,
-                "bytes_written": outcome.bytes_written,
-                "lines_written": outcome.lines_written,
-                "success": true,
-                "status": outcome.status.as_str(),
-                "missing_path_fallback": missing_path_fallback,
-                "rename_required": missing_path_fallback,
-                "path_format_corrected": path_format_warning.is_some(),
-                "path_format_warning": path_format_warning,
-                "message": assistant_message,
-            }),
+            data,
             result_for_assistant: Some(assistant_message),
             image_attachments: None,
         }
@@ -543,6 +570,8 @@ impl Tool for FileWriteTool {
 
         let resolved = context.resolve_tool_path(&file_path)?;
         let path_format_warning = Self::path_format_correction_warning(&resolved);
+        let plan_artifact_issues =
+            is_plan_artifact_path(&resolved.logical_path).then(|| diagnose_plan_artifact(&content));
         context.enforce_path_operation(ToolPathOperation::Write, &resolved)?;
         context
             .record_light_checkpoint(
@@ -562,6 +591,7 @@ impl Tool for FileWriteTool {
                 missing_path_fallback,
                 path_format_warning.as_deref(),
                 &ignored_parameter_names,
+                plan_artifact_issues.as_deref(),
             );
             return Ok(vec![result]);
         }
@@ -598,6 +628,7 @@ impl Tool for FileWriteTool {
                 missing_path_fallback,
                 path_format_warning.as_deref(),
                 &ignored_parameter_names,
+                plan_artifact_issues.as_deref(),
             );
             return Ok(vec![result]);
         }
@@ -634,6 +665,7 @@ impl Tool for FileWriteTool {
             missing_path_fallback,
             path_format_warning.as_deref(),
             &ignored_parameter_names,
+            plan_artifact_issues.as_deref(),
         );
 
         Ok(vec![result])
@@ -642,7 +674,7 @@ impl Tool for FileWriteTool {
 
 #[cfg(test)]
 mod tests {
-    use super::FileWriteTool;
+    use super::{diagnose_plan_artifact, FileWriteTool};
     use crate::agentic::tools::file_tool_guidance::{
         file_tool_guidance_message, is_file_tool_guidance_message, FILE_TOOL_GUIDANCE_PREFIX,
     };
@@ -893,6 +925,39 @@ mod tests {
         assert!(validation.message.is_none());
     }
 
+    #[test]
+    fn write_success_result_reports_non_blocking_plan_issues() {
+        let logical_path = ".bitfun/plans/example.plan.md";
+        let content = "---\nname: Example\noverview: Overview\ntodos: []\n---\n";
+        let issues = diagnose_plan_artifact(content);
+
+        let result = FileWriteTool::write_success_result(
+            logical_path,
+            super::write_file_success_outcome(logical_path, false, content),
+            false,
+            None,
+            &[],
+            Some(&issues),
+        );
+        let ToolResult::Result {
+            data,
+            result_for_assistant,
+            ..
+        } = result
+        else {
+            panic!("expected result");
+        };
+
+        assert_eq!(data["success"], true);
+        assert_eq!(data["plan_format"]["valid"], false);
+        assert_eq!(
+            data["plan_format"]["issues"][0]["code"],
+            "missing_markdown_body"
+        );
+        let assistant_message = result_for_assistant.as_deref().unwrap_or_default();
+        assert!(assistant_message.contains("does not match the plan format"));
+    }
+
     #[cfg(windows)]
     #[tokio::test]
     async fn write_result_reports_normalized_windows_drive_path() {
@@ -927,6 +992,7 @@ mod tests {
             false,
             Some(&warning),
             &[],
+            None,
         );
         let ToolResult::Result {
             data,

src/crates/assembly/core/src/agentic/tools/implementations/mod.rs

@@ -52,6 +52,7 @@ pub mod miniapp_publish_tool;
 pub mod page_deploy_tool;
 #[cfg(feature = "tools-miniapp")]
 pub mod page_publish_tool;
+mod plan_artifact_diagnostics;
 #[cfg(feature = "tools-miniapp")]
 pub mod playbook_tool;
 #[cfg(feature = "tools-agent-control")]