feat(flowctl): add Phase 1.5 Investigation + --investigation CLI flag

Add Phase 1.5 "Investigation" to the phase registry between Re-anchor
and TDD/Implement. Add --investigation flag to `task spec` command for
patching `## Investigation targets` sections. Update default task spec
template to include empty investigation targets placeholder.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

flowctl/crates/flowctl-cli/src/commands/task/mod.rs

@@ -57,6 +57,9 @@ pub enum TaskCmd {
         /// Acceptance section file.
         #[arg(long, alias = "acceptance")]
         accept: Option<String>,
+        /// Investigation targets section file.
+        #[arg(long)]
+        investigation: Option<String>,
     },
     /// Reset task to todo.
     Reset {
@@ -171,7 +174,7 @@ fn parse_domain(s: &str) -> Domain {
 fn create_task_spec(id: &str, title: &str, acceptance: Option<&str>) -> String {
     let acceptance_content = acceptance.unwrap_or("- [ ] TBD");
     format!(
-        "# {} {}\n\n## Description\nTBD\n\n## Acceptance\n{}\n\n## Done summary\nTBD\n\n## Evidence\n- Commits:\n- Tests:\n- PRs:\n",
+        "# {} {}\n\n## Description\nTBD\n\n## Investigation targets\n\n## Acceptance\n{}\n\n## Done summary\nTBD\n\n## Evidence\n- Commits:\n- Tests:\n- PRs:\n",
         id, title, acceptance_content
     )
 }
@@ -338,7 +341,8 @@ pub fn dispatch(cmd: &TaskCmd, json: bool) {
             file,
             desc,
             accept,
-        } => query::cmd_task_set_spec(json, id, file.as_deref(), desc.as_deref(), accept.as_deref()),
+            investigation,
+        } => query::cmd_task_set_spec(json, id, file.as_deref(), desc.as_deref(), accept.as_deref(), investigation.as_deref()),
         TaskCmd::Reset { task_id, cascade } => mutate::cmd_task_reset(json, task_id, *cascade),
         TaskCmd::Skip { task_id, reason } => mutate::cmd_task_skip(json, task_id, reason.as_deref()),
         TaskCmd::Split {

flowctl/crates/flowctl-cli/src/commands/task/query.rs

@@ -18,6 +18,7 @@ pub(super) fn cmd_task_set_spec(
     file: Option<&str>,
     description: Option<&str>,
     acceptance: Option<&str>,
+    investigation: Option<&str>,
 ) {
     let flow_dir = ensure_flow_exists();
 
@@ -28,8 +29,8 @@ pub(super) fn cmd_task_set_spec(
         ));
     }
 
-    if file.is_none() && description.is_none() && acceptance.is_none() {
-        error_exit("Requires --file, --description, or --acceptance");
+    if file.is_none() && description.is_none() && acceptance.is_none() && investigation.is_none() {
+        error_exit("Requires --file, --description, --acceptance, or --investigation");
     }
 
     let mut doc = load_task_doc(&flow_dir, task_id);
@@ -67,6 +68,12 @@ pub(super) fn cmd_task_set_spec(
         sections_updated.push("## Acceptance");
     }
 
+    if let Some(inv_file) = investigation {
+        let inv_content = read_file_or_stdin(inv_file);
+        doc.body = patch_body_section(&doc.body, "## Investigation targets", &inv_content);
+        sections_updated.push("## Investigation targets");
+    }
+
     doc.frontmatter.updated_at = Utc::now();
     write_task_doc(&flow_dir, task_id, &doc);
 

flowctl/crates/flowctl-core/src/types.rs

@@ -305,6 +305,7 @@ impl std::fmt::Display for PhaseStatus {
 pub const PHASE_DEFS: &[(&str, &str, &str)] = &[
     ("0", "Verify Configuration", "OWNED_FILES verified and configuration validated"),
     ("1", "Re-anchor", "Run flowctl show <task> and verify spec was read"),
+    ("1.5", "Investigation", "Required investigation target files read and patterns noted"),
     ("2a", "TDD Red-Green", "Failing tests written and confirmed to fail"),
     ("2", "Implement", "Feature implemented and code compiles"),
     ("2.5", "Verify & Fix", "flowctl guard passes and diff reviewed"),
@@ -319,9 +320,9 @@ pub const PHASE_DEFS: &[(&str, &str, &str)] = &[
 /// Phase sequences by mode (from Python constants.py).
 /// Phase `5c` (outputs_dump) is NOT in these static sequences — it is added
 /// dynamically by `worker-phase next` based on the `outputs.enabled` config.
-pub const PHASE_SEQ_DEFAULT: &[&str] = &["0", "1", "2", "2.5", "3", "5", "5b", "6"];
-pub const PHASE_SEQ_TDD: &[&str] = &["0", "1", "2a", "2", "2.5", "3", "5", "5b", "6"];
-pub const PHASE_SEQ_REVIEW: &[&str] = &["0", "1", "2", "2.5", "3", "4", "5", "5b", "6"];
+pub const PHASE_SEQ_DEFAULT: &[&str] = &["0", "1", "1.5", "2", "2.5", "3", "5", "5b", "6"];
+pub const PHASE_SEQ_TDD: &[&str] = &["0", "1", "1.5", "2a", "2", "2.5", "3", "5", "5b", "6"];
+pub const PHASE_SEQ_REVIEW: &[&str] = &["0", "1", "1.5", "2", "2.5", "3", "4", "5", "5b", "6"];
 
 // ── Evidence ─────────────────────────────────────────────────────────
 
@@ -551,7 +552,7 @@ mod tests {
 
     #[test]
     fn test_phase_defs_complete() {
-        assert_eq!(PHASE_DEFS.len(), 11);
+        assert_eq!(PHASE_DEFS.len(), 12);
         // Verify all phase sequences reference valid phase IDs
         let valid_ids: Vec<&str> = PHASE_DEFS.iter().map(|(id, _, _)| *id).collect();
         for seq_id in PHASE_SEQ_DEFAULT {