feat(flowctl): add .flow/outputs/ narrative handoff layer (fn-20.2)

Adds a lightweight per-task narrative dump at `.flow/outputs/<task-id>.md`
that workers write in new Phase 5c and the next worker auto-reads during
Phase 1 re-anchor. Gated on a new `outputs.enabled` config key (default
true), fully independent from `memory.enabled` — outputs is a narrative
handoff layer, not part of the verified memory system.

- flowctl-core: new `OutputEntry` protocol type (convention #8)
- flowctl-service: new `OutputsStore` (file-system native, no libSQL)
- flowctl-cli: new `flowctl outputs write|list|show` commands
- Phase 5c `outputs_dump` added to worker sequence dynamically based on
  `outputs.enabled` config; worker.md Phase 1 extended to list+show prior
  outputs (limit 3) and Phase 5c added between Phase 5 and Phase 5b
- `done_task()` in lifecycle.rs intentionally unchanged — worker owns the
  dump explicitly in Phase 5c, keeping runtime agnostic of narrative shape
- Missing `## Surprises`/`## Decisions` sections allowed (pitfall #2)

Author: z23cc

agents/worker.md

@@ -156,6 +156,17 @@ This returns a compact index (~50 tokens/entry). If you see relevant entries, fe
 ```
 Only fetch full content for entries relevant to your task's technology/domain.
 
+**Check prior outputs** (if `outputs.enabled` is true, default):
+```bash
+<FLOWCTL> config get outputs.enabled --json
+<FLOWCTL> outputs list --epic <EPIC_ID> --limit 3 --json
+```
+For each entry returned, fetch its content and include verbatim in your context:
+```bash
+<FLOWCTL> outputs show <prior-task-id>
+```
+These are lightweight narrative handoffs from earlier tasks in this epic — read them to understand what upstream work surprised the previous worker, what decisions they made, and what gotchas to watch for. Skip gracefully if the list is empty (new epic) or if `outputs.enabled` is false.
+
 Parse the spec carefully. Identify:
 - Acceptance criteria
 - Dependencies on other tasks
@@ -474,6 +485,43 @@ Status MUST be `done`. If not:
 4. **Do NOT send "Task complete" message until status is confirmed `done`**
 <!-- /section:core -->
 
+<!-- section:outputs -->
+## Phase 5c: Outputs Dump (if outputs.enabled)
+
+**Skip if `outputs.enabled` is false.** This is gated on its own config key — independent from `memory.enabled`. Outputs are a lightweight narrative handoff layer (plain markdown, no verification), separate from the verified memory system.
+
+After completing the task, write a ≤200-word narrative dump to `.flow/outputs/<TASK_ID>.md` for the next worker in this epic:
+
+```bash
+# Check if outputs is enabled (default: true)
+OUTPUTS_ENABLED=$(<FLOWCTL> config get outputs.enabled --json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('value', True))" 2>/dev/null || echo "True")
+
+if [ "$OUTPUTS_ENABLED" = "True" ] || [ "$OUTPUTS_ENABLED" = "true" ]; then
+  <FLOWCTL> outputs write <TASK_ID> --file - << 'EOF'
+## Summary
+
+<1–3 sentence summary of what you implemented, ≤200 words total>
+
+## Surprises
+
+- <Thing that surprised you during implementation, or "None">
+- <Another gotcha, if any>
+
+## Decisions
+
+- <Key design/architecture decision + rationale>
+- <Another decision, if any>
+EOF
+fi
+```
+
+**Rules:**
+- All three sections are allowed to be missing or empty — downstream readers handle that gracefully
+- Focus on narrative handoff: what would help the next worker, not comprehensive docs
+- Don't repeat spec content — only things you learned while working
+- This is narrative handoff, NOT verified memory. Save verified pitfalls/conventions in Phase 5b.
+<!-- /section:outputs -->
+
 <!-- section:memory -->
 ## Phase 5b: Memory Auto-Save (if memory enabled)
 

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

@@ -15,6 +15,7 @@ use crate::commands::helpers::get_flow_dir;
 fn get_default_config() -> serde_json::Value {
     json!({
         "memory": {"enabled": true},
+        "outputs": {"enabled": true},
         "planSync": {"enabled": true, "crossEpic": false},
         "review": {"backend": null},
         "scouts": {"github": false},

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

@@ -10,6 +10,7 @@ pub mod epic;
 pub mod gap;
 pub mod hook;
 pub mod memory;
+pub mod outputs;
 pub mod query;
 pub mod ralph;
 pub mod rp;

flowctl/crates/flowctl-cli/src/commands/outputs.rs

@@ -0,0 +1,196 @@
+//! Outputs commands: write, list, show.
+//!
+//! Thin CLI wrapper over `flowctl_service::outputs::OutputsStore`. Provides
+//! a lightweight narrative handoff layer at `.flow/outputs/<task-id>.md` that
+//! workers populate in Phase 5c and read during Phase 1 re-anchor.
+
+use std::fs;
+use std::io::Read;
+
+use clap::Subcommand;
+use serde_json::json;
+
+use flowctl_core::id::is_task_id;
+use flowctl_service::outputs::OutputsStore;
+
+use crate::output::{error_exit, json_output};
+
+use super::helpers::get_flow_dir;
+
+#[derive(Subcommand, Debug)]
+pub enum OutputsCmd {
+    /// Write output markdown for a task (from file or stdin via '-').
+    Write {
+        /// Task ID (e.g. fn-1.3).
+        task_id: String,
+        /// Path to content file, or '-' for stdin.
+        #[arg(long)]
+        file: String,
+    },
+    /// List prior outputs for an epic, newest-first.
+    List {
+        /// Epic ID.
+        #[arg(long)]
+        epic: String,
+        /// Max entries to return.
+        #[arg(long)]
+        limit: Option<usize>,
+    },
+    /// Print the full markdown content for a task's output file.
+    Show {
+        /// Task ID (e.g. fn-1.3).
+        task_id: String,
+    },
+}
+
+pub fn dispatch(cmd: &OutputsCmd, json: bool) {
+    match cmd {
+        OutputsCmd::Write { task_id, file } => cmd_outputs_write(json, task_id, file),
+        OutputsCmd::List { epic, limit } => cmd_outputs_list(json, epic, *limit),
+        OutputsCmd::Show { task_id } => cmd_outputs_show(json, task_id),
+    }
+}
+
+/// Open the store, exiting cleanly if `.flow/` is missing.
+fn open_store(json: bool) -> OutputsStore {
+    let flow_dir = get_flow_dir();
+    if !flow_dir.exists() {
+        if json {
+            json_output(json!({"error": ".flow/ does not exist. Run 'flowctl init' first."}));
+            std::process::exit(1);
+        } else {
+            error_exit(".flow/ does not exist. Run 'flowctl init' first.");
+        }
+    }
+    match OutputsStore::new(&flow_dir) {
+        Ok(store) => store,
+        Err(e) => {
+            if json {
+                json_output(json!({"error": format!("failed to open outputs store: {e}")}));
+                std::process::exit(1);
+            } else {
+                error_exit(&format!("failed to open outputs store: {e}"));
+            }
+        }
+    }
+}
+
+fn cmd_outputs_write(json: bool, task_id: &str, file: &str) {
+    if !is_task_id(task_id) {
+        if json {
+            json_output(json!({"error": format!("Invalid task ID: {task_id}")}));
+            std::process::exit(1);
+        } else {
+            error_exit(&format!(
+                "Invalid task ID: {task_id}. Expected format: fn-N.M or fn-N-slug.M"
+            ));
+        }
+    }
+
+    // Read content from file or stdin.
+    let content = if file == "-" {
+        let mut buf = String::new();
+        if let Err(e) = std::io::stdin().read_to_string(&mut buf) {
+            error_exit(&format!("failed to read stdin: {e}"));
+        }
+        buf
+    } else {
+        match fs::read_to_string(file) {
+            Ok(c) => c,
+            Err(e) => error_exit(&format!("failed to read {file}: {e}")),
+        }
+    };
+
+    let store = open_store(json);
+    match store.write(task_id, &content) {
+        Ok(path) => {
+            if json {
+                json_output(json!({
+                    "task_id": task_id,
+                    "path": path.to_string_lossy(),
+                    "bytes": content.len(),
+                }));
+            } else {
+                println!("Wrote {} ({} bytes)", path.display(), content.len());
+            }
+        }
+        Err(e) => {
+            if json {
+                json_output(json!({"error": format!("write failed: {e}")}));
+                std::process::exit(1);
+            } else {
+                error_exit(&format!("write failed: {e}"));
+            }
+        }
+    }
+}
+
+fn cmd_outputs_list(json: bool, epic_id: &str, limit: Option<usize>) {
+    let store = open_store(json);
+    match store.list_for_epic(epic_id, limit) {
+        Ok(entries) => {
+            if json {
+                let arr: Vec<_> = entries
+                    .iter()
+                    .map(|e| {
+                        json!({
+                            "task_id": e.task_id,
+                            "path": e.path.to_string_lossy(),
+                            "mtime": e.mtime,
+                        })
+                    })
+                    .collect();
+                json_output(json!({"entries": arr, "count": entries.len()}));
+            } else if entries.is_empty() {
+                println!("(no outputs for epic {epic_id})");
+            } else {
+                for e in &entries {
+                    println!("{}\t{}", e.task_id, e.path.display());
+                }
+            }
+        }
+        Err(e) => {
+            if json {
+                json_output(json!({"error": format!("list failed: {e}")}));
+                std::process::exit(1);
+            } else {
+                error_exit(&format!("list failed: {e}"));
+            }
+        }
+    }
+}
+
+fn cmd_outputs_show(json: bool, task_id: &str) {
+    if !is_task_id(task_id) {
+        if json {
+            json_output(json!({"error": format!("Invalid task ID: {task_id}")}));
+            std::process::exit(1);
+        } else {
+            error_exit(&format!(
+                "Invalid task ID: {task_id}. Expected format: fn-N.M or fn-N-slug.M"
+            ));
+        }
+    }
+
+    let store = open_store(json);
+    match store.read(task_id) {
+        Ok(content) => {
+            if json {
+                json_output(json!({
+                    "task_id": task_id,
+                    "content": content,
+                }));
+            } else {
+                print!("{content}");
+            }
+        }
+        Err(e) => {
+            if json {
+                json_output(json!({"error": format!("read failed: {e}")}));
+                std::process::exit(1);
+            } else {
+                error_exit(&format!("read failed: {e}"));
+            }
+        }
+    }
+}

flowctl/crates/flowctl-cli/src/commands/workflow/phase.rs

@@ -61,14 +61,16 @@ const PHASE_DEFS: &[PhaseDef] = &[
     PhaseDef { id: "3",   title: "Commit",                done_condition: "Changes committed with conventional commit message" },
     PhaseDef { id: "4",   title: "Review",                done_condition: "SHIP verdict received from reviewer" },
     PhaseDef { id: "5",   title: "Complete",              done_condition: "flowctl done called and task status is done" },
+    PhaseDef { id: "5c",  title: "Outputs Dump",          done_condition: "Narrative summary written to .flow/outputs/<task-id>.md" },
     PhaseDef { id: "5b",  title: "Memory Auto-Save",      done_condition: "Non-obvious lessons saved to memory (if any)" },
     PhaseDef { id: "6",   title: "Return",                done_condition: "Summary returned to main conversation" },
 ];
 
 /// Canonical ordering of all phases — used to merge sequences.
-const CANONICAL_ORDER: &[&str] = &["0", "1", "2a", "2", "2.5", "3", "4", "5", "5b", "6"];
+const CANONICAL_ORDER: &[&str] = &["0", "1", "2a", "2", "2.5", "3", "4", "5", "5c", "5b", "6"];
 
 /// Default phase sequence (Worktree + Teams, always includes Phase 0).
+/// Phase 5c is appended when `outputs.enabled` is true (default).
 const PHASE_SEQ_DEFAULT: &[&str] = &["0", "1", "2", "2.5", "3", "5", "5b", "6"];
 const PHASE_SEQ_TDD: &[&str]    = &["0", "1", "2a", "2", "2.5", "3", "5", "5b", "6"];
 const PHASE_SEQ_REVIEW: &[&str] = &["0", "1", "2", "2.5", "3", "4", "5", "5b", "6"];
@@ -77,12 +79,31 @@ fn get_phase_def(phase_id: &str) -> Option<&'static PhaseDef> {
     PHASE_DEFS.iter().find(|p| p.id == phase_id)
 }
 
-/// Build the phase sequence based on mode flags.
-fn build_phase_sequence(tdd: bool, review: bool) -> Vec<&'static str> {
-    if !tdd && !review {
-        return PHASE_SEQ_DEFAULT.to_vec();
+/// Read `outputs.enabled` from .flow/config.json. Default: true.
+fn is_outputs_enabled() -> bool {
+    use flowctl_core::types::{CONFIG_FILE, FLOW_DIR};
+    let cfg_path = std::env::current_dir()
+        .unwrap_or_else(|_| std::path::PathBuf::from("."))
+        .join(FLOW_DIR)
+        .join(CONFIG_FILE);
+    if !cfg_path.exists() {
+        return true;
+    }
+    match std::fs::read_to_string(&cfg_path) {
+        Ok(content) => {
+            let cfg: serde_json::Value =
+                serde_json::from_str(&content).unwrap_or(serde_json::json!({}));
+            cfg.get("outputs")
+                .and_then(|m| m.get("enabled"))
+                .and_then(|v| v.as_bool())
+                .unwrap_or(true)
+        }
+        Err(_) => true,
     }
+}
 
+/// Build the phase sequence based on mode flags.
+fn build_phase_sequence(tdd: bool, review: bool) -> Vec<&'static str> {
     let mut phases = HashSet::new();
     for p in PHASE_SEQ_DEFAULT {
         phases.insert(*p);
@@ -97,6 +118,9 @@ fn build_phase_sequence(tdd: bool, review: bool) -> Vec<&'static str> {
             phases.insert(*p);
         }
     }
+    if is_outputs_enabled() {
+        phases.insert("5c");
+    }
     CANONICAL_ORDER.iter().copied().filter(|p| phases.contains(p)).collect()
 }
 

flowctl/crates/flowctl-cli/src/main.rs

@@ -19,6 +19,7 @@ use commands::{
     gap::GapCmd,
     hook::HookCmd,
     memory::MemoryCmd,
+    outputs::OutputsCmd,
     query,
     ralph::RalphCmd,
     rp::RpCmd,
@@ -184,6 +185,11 @@ enum Commands {
         #[command(subcommand)]
         cmd: MemoryCmd,
     },
+    /// Outputs commands (narrative handoff between tasks).
+    Outputs {
+        #[command(subcommand)]
+        cmd: OutputsCmd,
+    },
     /// Checkpoint commands.
     Checkpoint {
         #[command(subcommand)]
@@ -478,6 +484,7 @@ fn main() {
         Commands::Dep { cmd } => commands::dep::dispatch(&cmd, json),
         Commands::Gap { cmd } => commands::gap::dispatch(&cmd, json),
         Commands::Memory { cmd } => commands::memory::dispatch(&cmd, json),
+        Commands::Outputs { cmd } => commands::outputs::dispatch(&cmd, json),
         Commands::Checkpoint { cmd } => commands::checkpoint::dispatch(&cmd, json),
         Commands::Stack { cmd } => commands::stack::dispatch(&cmd, json),
         Commands::Invariants { cmd } => commands::stack::dispatch_invariants(&cmd, json),

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

@@ -8,6 +8,7 @@ pub mod dag;
 pub mod error;
 pub mod frontmatter;
 pub mod id;
+pub mod outputs;
 pub mod review_protocol;
 pub mod state_machine;
 pub mod task_profile;
@@ -17,5 +18,6 @@ pub mod types;
 pub use dag::TaskDag;
 pub use error::CoreError;
 pub use id::{parse_id, slugify, EpicId, ParsedId, TaskId};
+pub use outputs::OutputEntry;
 pub use state_machine::{Status, Transition, TransitionError};
 pub use types::{Epic, Evidence, Phase, Task};