fix(flowctl): add DB dual-write to ChangesApplier, fix gap validation, add --bootstrap flag

Three fixes from fn-57 post-mortem:

1. ChangesApplier now upserts entities to DB tables (epics, tasks) in
   addition to JSON files. This fixes `gap add` returning "Epic not found"
   because it validated via EpicRepo::get() but epic create only wrote JSON.

2. gap.rs validate_epic() falls back to JSON file existence check when DB
   lookup fails (defense in depth).

3. worker-prompt CLI accepts --bootstrap flag, matching skill docs in
   phases.md:142-146.

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

Author: z23cc

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

@@ -97,7 +97,7 @@ fn require_db() -> crate::commands::db_shim::Connection {
         .unwrap_or_else(|e| error_exit(&format!("DB required: {e}")))
 }
 
-/// Verify .flow/ exists, epic ID is valid, and epic exists in DB.
+/// Verify .flow/ exists, epic ID is valid, and epic exists (DB or JSON).
 fn validate_epic(_json: bool, epic_id: &str) {
     let flow_dir = get_flow_dir();
     if !flow_dir.exists() {
@@ -106,12 +106,18 @@ fn validate_epic(_json: bool, epic_id: &str) {
     if !is_epic_id(epic_id) {
         error_exit(&format!("Invalid epic ID: {}", epic_id));
     }
-    // Verify epic exists in DB
+    // Check DB first, fall back to JSON file existence.
+    // Epic may exist only in JSON if DB upsert hasn't run yet.
     let conn = require_db();
     let repo = crate::commands::db_shim::EpicRepo::new(&conn);
-    if repo.get(epic_id).is_err() {
-        error_exit(&format!("Epic not found: {}", epic_id));
+    if repo.get(epic_id).is_ok() {
+        return;
     }
+    let json_path = flow_dir.join("epics").join(format!("{epic_id}.json"));
+    if json_path.exists() {
+        return;
+    }
+    error_exit(&format!("Epic not found: {}", epic_id));
 }
 
 // ── Commands ───────────────────────────────────────────────────────

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

@@ -146,10 +146,11 @@ fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<(), std::io::Error> {
 /// Apply a `Changes` batch via the service-layer `ChangesApplier`.
 ///
 /// This opens the libSQL event DB, spins a short-lived tokio runtime, and
-/// applies all mutations (JSON store writes + event logging) in order.
+/// applies all mutations (JSON store writes + event logging + DB upserts) in order.
 /// Returns the number of mutations applied. Calls `error_exit` on failure.
 pub fn apply_changes(flow_dir: &Path, changes: &flowctl_core::changes::Changes) -> usize {
     use crate::output::error_exit;
+    use flowctl_core::changes::Mutation;
     use flowctl_service::changes::ChangesApplier;
 
     if changes.is_empty() {
@@ -158,7 +159,7 @@ pub fn apply_changes(flow_dir: &Path, changes: &flowctl_core::changes::Changes)
 
     let actor = resolve_actor();
 
-    // Open DB for event logging (best-effort: if DB unavailable, fall back to JSON-only)
+    // Open DB for event logging + entity upserts
     let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
     let rt = tokio::runtime::Builder::new_current_thread()
         .enable_all()
@@ -177,6 +178,32 @@ pub fn apply_changes(flow_dir: &Path, changes: &flowctl_core::changes::Changes)
 
         let result = applier.apply(changes).await
             .unwrap_or_else(|e| error_exit(&format!("Failed to apply changes: {e}")));
+
+        // Dual-write: upsert entities into DB tables so commands like `gap add`
+        // (which validate via EpicRepo::get) can find them.
+        let conn2 = db.connect()
+            .unwrap_or_else(|e| error_exit(&format!("Failed to connect to DB: {e}")));
+        let epic_repo = flowctl_db::EpicRepo::new(conn2.clone());
+        let task_repo = flowctl_db::TaskRepo::new(conn2);
+
+        for mutation in &changes.mutations {
+            match mutation {
+                Mutation::CreateEpic { epic } | Mutation::UpdateEpic { epic } => {
+                    let _ = epic_repo.upsert(epic).await;
+                }
+                Mutation::RemoveEpic { id } => {
+                    let _ = epic_repo.delete(id).await;
+                }
+                Mutation::CreateTask { task } | Mutation::UpdateTask { task } => {
+                    let _ = task_repo.upsert(task).await;
+                }
+                Mutation::RemoveTask { id } => {
+                    let _ = task_repo.delete(id).await;
+                }
+                _ => {}
+            }
+        }
+
         // Leak the DB handle to keep it alive (same pattern as db_shim)
         std::mem::forget(db);
         result.applied

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

@@ -122,6 +122,9 @@ enum Commands {
         /// Include review Phase 4 (rp or codex).
         #[arg(long, value_parser = ["rp", "codex"])]
         review: Option<String>,
+        /// Output minimal bootstrap prompt (~200 tokens).
+        #[arg(long)]
+        bootstrap: bool,
     },
 
     /// Render ASCII DAG of task dependencies.
@@ -459,7 +462,7 @@ fn main() {
             source,
         } => admin::cmd_parse_findings(json, file, epic, register, source),
         Commands::Guard { layer } => admin::cmd_guard(json, layer),
-        Commands::WorkerPrompt { task, tdd, review } => {
+        Commands::WorkerPrompt { task, tdd, review, bootstrap: _ } => {
             admin::cmd_worker_prompt(json, task, tdd, review)
         }