jettypod 4.4.118 → 4.4.121

package/crates/jettypod-core/src/work.rs

@@ -0,0 +1,1086 @@
+//! Work item CRUD and status management.
+//!
+//! Port of `lib/work-tracking/index.js` — the core data operations for
+//! creating, querying, and updating work items. Complex cascading logic
+//! (worktree merging, session management) lives in their respective modules.
+
+
+use crate::db::Database;
+use crate::error::{CoreError, Result, WorkError};
+use rusqlite::params;
+use serde::{Deserialize, Serialize};
+use strum::{AsRefStr, Display, EnumString};
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/// Work item type.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, AsRefStr, Display, EnumString)]
+#[serde(rename_all = "snake_case")]
+#[strum(serialize_all = "snake_case")]
+pub enum ItemType {
+    Epic,
+    Feature,
+    Chore,
+    Bug,
+}
+
+/// Work item status.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, AsRefStr, Display, EnumString)]
+#[serde(rename_all = "snake_case")]
+#[strum(serialize_all = "snake_case")]
+pub enum Status {
+    Backlog,
+    Todo,
+    #[serde(rename = "in_progress")]
+    #[strum(serialize = "in_progress")]
+    InProgress,
+    Blocked,
+    Done,
+    Cancelled,
+}
+
+/// Work item mode — controls the workflow progression.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, AsRefStr, Display, EnumString)]
+#[serde(rename_all = "snake_case")]
+#[strum(serialize_all = "snake_case")]
+pub enum Mode {
+    Discovery,
+    Speed,
+    Stable,
+    Production,
+}
+
+/// Work item phase — tracks discovery vs implementation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, AsRefStr, Display, EnumString)]
+#[serde(rename_all = "snake_case")]
+#[strum(serialize_all = "snake_case")]
+pub enum Phase {
+    Discovery,
+    Implementation,
+}
+
+/// A complete work item row from the database.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WorkItem {
+    pub id: i64,
+    #[serde(rename = "type")]
+    pub item_type: ItemType,
+    pub title: String,
+    pub description: Option<String>,
+    pub status: Status,
+    pub parent_id: Option<i64>,
+    pub epic_id: Option<i64>,
+    pub branch_name: Option<String>,
+    pub mode: Option<Mode>,
+    pub current: bool,
+    pub phase: Option<Phase>,
+    pub scenario_file: Option<String>,
+    pub completed_at: Option<String>,
+    pub created_at: Option<String>,
+    pub display_order: Option<i64>,
+    pub needs_discovery: bool,
+    pub ready_for_review: bool,
+    pub conversational: bool,
+    pub plan_at_creation: Option<String>,
+    pub rejection_count: i64,
+    pub rejection_round: Option<i64>,
+    pub rejection_history: Option<String>,
+    pub rejection_reason: Option<String>,
+    pub rejected_at: Option<String>,
+    pub qa_steps: Option<String>,
+}
+
+/// Options for creating a work item.
+#[derive(Debug, Default)]
+pub struct CreateOptions {
+    pub description: String,
+    pub parent_id: Option<i64>,
+    pub mode: Option<Mode>,
+    pub needs_discovery: bool,
+    pub conversational: bool,
+}
+
+/// A discovery decision for an epic.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DiscoveryDecision {
+    pub id: i64,
+    pub work_item_id: i64,
+    pub aspect: String,
+    pub decision: String,
+    pub rationale: String,
+    pub created_at: Option<String>,
+}
+
+// ---------------------------------------------------------------------------
+// Title sanitization
+// ---------------------------------------------------------------------------
+
+const MAX_TITLE_LEN: usize = 60;
+
+/// Sanitize a work item title — strip HTML, dangerous chars, and truncate.
+pub fn sanitize_title(title: &str) -> String {
+    // Strip HTML tags
+    let no_html = strip_html_tags(title);
+    // Remove dangerous characters: $ ` \
+    let safe: String = no_html
+        .chars()
+        .filter(|c| *c != '$' && *c != '`' && *c != '\\')
+        .collect();
+    // Remove control characters and normalize whitespace
+    let normalized: String = safe
+        .chars()
+        .map(|c| if c.is_control() || c == '\n' || c == '\r' { ' ' } else { c })
+        .collect();
+    let trimmed = normalized.split_whitespace().collect::<Vec<_>>().join(" ");
+
+    // Truncate to max length
+    if trimmed.len() > MAX_TITLE_LEN {
+        trimmed[..MAX_TITLE_LEN].to_string()
+    } else {
+        trimmed
+    }
+}
+
+fn strip_html_tags(s: &str) -> String {
+    let mut result = String::with_capacity(s.len());
+    let mut in_tag = false;
+    for c in s.chars() {
+        match c {
+            '<' => in_tag = true,
+            '>' => in_tag = false,
+            _ if !in_tag => result.push(c),
+            _ => {}
+        }
+    }
+    result
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+
+/// Create a new work item. Returns the new item's ID.
+pub fn create(
+    db: &Database,
+    item_type: ItemType,
+    title: &str,
+    opts: CreateOptions,
+) -> Result<i64> {
+    let title = sanitize_title(title);
+    if title.is_empty() {
+        return Err(WorkError::EmptyTitle.into());
+    }
+
+    let conn = db.conn();
+
+    // Resolve epic_id from parent chain
+    let (epic_id, rejection_round) = if let Some(pid) = opts.parent_id {
+        let parent: (String, Option<i64>, i64) = conn.query_row(
+            "SELECT type, epic_id, rejection_count FROM work_items WHERE id = ?",
+            params![pid],
+            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
+        ).map_err(|_| WorkError::NotFound(pid))?;
+
+        let (parent_type, parent_epic_id, parent_rejection_count) = parent;
+        let parent_item_type = parent_type.parse::<ItemType>().map_err(|_|
+            WorkError::Other(format!("invalid parent type: {parent_type}")))?;
+        let eid = match parent_item_type {
+            ItemType::Epic => Some(pid),
+            _ => parent_epic_id,
+        };
+        let rr = if parent_rejection_count > 0 {
+            Some(parent_rejection_count)
+        } else {
+            None
+        };
+        (eid, rr)
+    } else {
+        (None, None)
+    };
+
+    // Determine phase for features
+    let phase = match item_type {
+        ItemType::Feature => {
+            if opts.mode.is_some() {
+                Some(Phase::Implementation)
+            } else {
+                Some(Phase::Discovery)
+            }
+        }
+        _ => None,
+    };
+
+    // Chores and bugs never have modes
+    let mode = match item_type {
+        ItemType::Chore | ItemType::Bug | ItemType::Epic => None,
+        ItemType::Feature => opts.mode,
+    };
+
+    let plan = crate::auth::current_plan();
+
+    conn.execute(
+        "INSERT INTO work_items (type, title, description, parent_id, epic_id, mode, \
+         needs_discovery, phase, status, plan_at_creation, rejection_round, conversational) \
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'backlog', ?9, ?10, ?11)",
+        params![
+            item_type.as_ref(),
+            title,
+            opts.description,
+            opts.parent_id,
+            epic_id,
+            mode.map(|m| m.to_string()),
+            opts.needs_discovery as i32,
+            phase.map(|p| p.to_string()),
+            plan,
+            rejection_round,
+            opts.conversational as i32,
+        ],
+    )?;
+
+    Ok(conn.last_insert_rowid())
+}
+
+/// Get a single work item by ID.
+pub fn get(db: &Database, id: i64) -> Result<WorkItem> {
+    db.conn()
+        .query_row("SELECT * FROM work_items WHERE id = ?", params![id], row_to_work_item)
+        .map_err(|e| match e {
+            rusqlite::Error::QueryReturnedNoRows => {
+                CoreError::Work(WorkError::NotFound(id))
+            }
+            other => CoreError::Database(other),
+        })
+}
+
+/// Get all children of a work item.
+pub fn get_children(db: &Database, parent_id: i64) -> Result<Vec<WorkItem>> {
+    let mut stmt = db.conn().prepare(
+        "SELECT * FROM work_items WHERE parent_id = ? ORDER BY id",
+    )?;
+    let items = stmt
+        .query_map(params![parent_id], row_to_work_item)?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+    Ok(items)
+}
+
+/// Get the full work item tree, optionally including completed items.
+pub fn get_tree(db: &Database, include_completed: bool) -> Result<Vec<WorkItem>> {
+    get_tree_limited(db, include_completed, None)
+}
+
+/// Like [`get_tree`] but with an optional cap on completed items.
+/// When `completed_limit` is `Some(n)`, only the `n` most-recently completed
+/// items are included (by `completed_at DESC`).  Active items always included.
+pub fn get_tree_limited(
+    db: &Database,
+    include_completed: bool,
+    completed_limit: Option<i64>,
+) -> Result<Vec<WorkItem>> {
+    let sql = match (include_completed, completed_limit) {
+        (true, None) => "SELECT * FROM work_items ORDER BY id".to_string(),
+        (false, _) => "SELECT * FROM work_items WHERE status NOT IN ('done', 'cancelled') ORDER BY id".to_string(),
+        (true, Some(n)) => format!(
+            "SELECT * FROM work_items WHERE status NOT IN ('done', 'cancelled') \
+             UNION ALL \
+             SELECT * FROM ( \
+                 SELECT * FROM work_items WHERE status IN ('done', 'cancelled') \
+                 ORDER BY completed_at DESC NULLS LAST, id DESC \
+                 LIMIT {n} \
+             ) ORDER BY id"
+        ),
+    };
+
+    let mut stmt = db.conn().prepare(&sql)?;
+    let items = stmt
+        .query_map([], row_to_work_item)?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+    Ok(items)
+}
+
+/// Walk up the parent chain to find the epic for a work item.
+///
+/// Uses a recursive CTE to traverse the parent chain in a single query
+/// instead of N sequential lookups.
+pub fn find_epic(db: &Database, item_id: i64) -> Result<Option<WorkItem>> {
+    let sql = "\
+        WITH RECURSIVE ancestors(id, depth) AS ( \
+            SELECT id, 0 FROM work_items WHERE id = ?1 \
+            UNION ALL \
+            SELECT w.parent_id, a.depth + 1 \
+            FROM work_items w \
+            JOIN ancestors a ON w.id = a.id \
+            WHERE w.parent_id IS NOT NULL AND a.depth < 20 \
+        ) \
+        SELECT w.* FROM work_items w \
+        JOIN ancestors a ON w.id = a.id \
+        WHERE w.type = 'epic' \
+        LIMIT 1";
+
+    let mut stmt = db.conn().prepare(sql)?;
+    let mut rows = stmt.query_map(params![item_id], row_to_work_item)?;
+    match rows.next() {
+        Some(Ok(item)) => Ok(Some(item)),
+        Some(Err(e)) => Err(e.into()),
+        None => Ok(None),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Update operations
+// ---------------------------------------------------------------------------
+
+/// Update a single column on a work item.
+fn update_field(db: &Database, id: i64, column: &str, value: &dyn rusqlite::types::ToSql) -> Result<()> {
+    let sql = format!("UPDATE work_items SET {} = ? WHERE id = ?", column);
+    db.conn().execute(&sql, rusqlite::params![value, id])?;
+    Ok(())
+}
+
+/// Update a work item's status.
+pub fn update_status(db: &Database, id: i64, status: Status) -> Result<()> {
+    let completed_at = if status == Status::Done {
+        Some(chrono::Utc::now().to_rfc3339())
+    } else {
+        None
+    };
+
+    db.conn().execute(
+        "UPDATE work_items SET status = ?, completed_at = ? WHERE id = ?",
+        params![status.as_ref(), completed_at, id],
+    )?;
+
+    // Clear current flag if completing/cancelling
+    if status == Status::Done || status == Status::Cancelled {
+        db.conn().execute(
+            "UPDATE work_items SET current = 0 WHERE id = ? AND current = 1",
+            params![id],
+        )?;
+    }
+
+    // Clear ready_for_review when moving back to in_progress (rejection)
+    if status == Status::InProgress {
+        db.conn().execute(
+            "UPDATE work_items SET ready_for_review = 0 WHERE id = ? AND ready_for_review = 1",
+            params![id],
+        )?;
+    }
+
+    Ok(())
+}
+
+/// Set a work item's branch name.
+pub fn set_branch(db: &Database, id: i64, branch: &str) -> Result<()> {
+    update_field(db, id, "branch_name", &branch)
+}
+
+/// Set a work item's scenario file path.
+pub fn set_scenario(db: &Database, id: i64, scenario_file: &str) -> Result<()> {
+    update_field(db, id, "scenario_file", &scenario_file)
+}
+
+/// Set a work item's mode (features only).
+pub fn set_mode(db: &Database, id: i64, mode: &str) -> Result<()> {
+    let item_type: String = db.conn().query_row(
+        "SELECT type FROM work_items WHERE id = ?",
+        params![id],
+        |row| row.get(0),
+    ).map_err(|_| WorkError::NotFound(id))?;
+
+    let parsed_type = item_type.parse::<ItemType>().map_err(|_|
+        WorkError::Other(format!("invalid item type: {item_type}")))?;
+
+    if parsed_type != ItemType::Feature {
+        return Err(WorkError::Other(format!(
+            "Only features have modes (#{} is a {})",
+            id, parsed_type
+        ))
+        .into());
+    }
+
+    update_field(db, id, "mode", &mode)
+}
+
+/// Set a work item as the current active item.
+pub fn set_current(db: &Database, id: i64) -> Result<()> {
+    let conn = db.conn();
+    conn.execute("UPDATE work_items SET current = 0 WHERE current = 1", [])?;
+    conn.execute(
+        "UPDATE work_items SET current = 1 WHERE id = ?",
+        params![id],
+    )?;
+    Ok(())
+}
+
+/// Update a work item's description.
+pub fn set_description(db: &Database, id: i64, description: &str) -> Result<()> {
+    update_field(db, id, "description", &description)
+}
+
+/// Mark a work item as ready for review.
+pub fn set_ready_for_review(db: &Database, id: i64) -> Result<()> {
+    update_field(db, id, "ready_for_review", &1i32)
+}
+
+/// Set a work item's QA steps (JSON string).
+pub fn set_qa_steps(db: &Database, id: i64, qa_steps: &str) -> Result<()> {
+    update_field(db, id, "qa_steps", &qa_steps)
+}
+
+/// Update a work item's title (sanitizes input).
+pub fn set_title(db: &Database, id: i64, title: &str) -> Result<()> {
+    let sanitized = sanitize_title(title);
+    if sanitized.is_empty() {
+        return Err(WorkError::EmptyTitle.into());
+    }
+    update_field(db, id, "title", &sanitized)
+}
+
+/// Set a work item's parent epic (or clear it with None).
+pub fn set_epic(db: &Database, id: i64, epic_id: Option<i64>) -> Result<()> {
+    update_field(db, id, "epic_id", &epic_id)
+}
+
+/// Batch-update display orders within a transaction.
+pub fn set_display_orders(db: &Database, orders: &[(i64, i64)]) -> Result<()> {
+    let conn = db.conn();
+    let tx = conn.unchecked_transaction()?;
+    for (id, order) in orders {
+        tx.execute(
+            "UPDATE work_items SET display_order = ? WHERE id = ?",
+            params![order, id],
+        )?;
+    }
+    tx.commit()?;
+    Ok(())
+}
+
+/// Transition a feature from discovery to implementation.
+pub fn complete_discovery(
+    db: &Database,
+    id: i64,
+    scenario_file: Option<&str>,
+    discovery_winner: Option<&str>,
+    discovery_rationale: Option<&str>,
+) -> Result<()> {
+    db.conn().execute(
+        "UPDATE work_items SET \
+         phase = 'implementation', mode = 'speed', status = 'todo', \
+         scenario_file = ?1, discovery_winner = ?2, \
+         discovery_rationale = ?3, \
+         discovery_completed_at = datetime('now') \
+         WHERE id = ?4",
+        params![scenario_file, discovery_winner, discovery_rationale, id],
+    )?;
+    Ok(())
+}
+
+/// Increment the rejection count for a work item and append to rejection history.
+pub fn increment_rejection(db: &Database, id: i64, reason: Option<&str>) -> Result<()> {
+    let conn = db.conn();
+
+    // Read current history and count so we can append
+    let (current_history, current_count): (Option<String>, i64) = conn.query_row(
+        "SELECT rejection_history, rejection_count FROM work_items WHERE id = ?1",
+        params![id],
+        |row| Ok((row.get(0)?, row.get(1)?)),
+    )?;
+
+    // Build updated history JSON array
+    let mut history: Vec<serde_json::Value> = current_history
+        .as_deref()
+        .and_then(|h| serde_json::from_str(h).ok())
+        .unwrap_or_default();
+
+    // Get current timestamp from SQLite for consistency
+    let now: String = conn.query_row("SELECT datetime('now')", [], |row| row.get(0))?;
+
+    let new_round = current_count + 1;
+    history.push(serde_json::json!({
+        "round": new_round,
+        "reason": reason,
+        "at": now,
+    }));
+
+    let history_json = serde_json::to_string(&history)?;
+
+    conn.execute(
+        "UPDATE work_items SET \
+         rejection_count = rejection_count + 1, \
+         rejection_reason = ?1, \
+         rejected_at = datetime('now'), \
+         rejection_history = ?3, \
+         ready_for_review = 0, \
+         status = 'in_progress' \
+         WHERE id = ?2",
+        params![reason, id, history_json],
+    )?;
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Onboarding seeding
+// ---------------------------------------------------------------------------
+
+/// Seed the "Project Planning" epic and onboarding chores for a blank project.
+///
+/// Returns `Some((epic_id, chore_ids))` if items were created, or `None` if
+/// a "Project Planning" epic already exists.
+pub fn seed_onboarding(db: &Database) -> Result<Option<(i64, Vec<i64>)>> {
+    // Check if onboarding epic already exists
+    let exists: bool = db.conn().query_row(
+        "SELECT EXISTS(SELECT 1 FROM work_items WHERE type = 'epic' AND title = 'Project Planning')",
+        [],
+        |row| row.get(0),
+    )?;
+    if exists {
+        return Ok(None);
+    }
+
+    let epic_id = create(
+        db,
+        ItemType::Epic,
+        "Project Planning",
+        CreateOptions {
+            description: "Get your project set up and planned. Work through these chores one at a time \
+                          — each one is a short conversation.".to_string(),
+            ..Default::default()
+        },
+    )?;
+
+    let chores = onboarding_chores(epic_id);
+    let mut chore_ids = Vec::with_capacity(chores.len());
+    for (title, description) in &chores {
+        let id = create(
+            db,
+            ItemType::Chore,
+            title,
+            CreateOptions {
+                description: description.to_string(),
+                parent_id: Some(epic_id),
+                ..Default::default()
+            },
+        )?;
+        chore_ids.push(id);
+    }
+
+    Ok(Some((epic_id, chore_ids)))
+}
+
+/// Onboarding chore definitions — mirrors `lib/seed-onboarding.js`.
+fn onboarding_chores(epic_id: i64) -> Vec<(&'static str, String)> {
+    let tone = "HOW TO RESPOND:\n\
+        You are a collaborator, not an AI assistant. You're a knowledgeable partner having a real conversation.\n\
+        - Do NOT open with a summary or recap of what you've been asked to do\n\
+        - Do NOT list steps or outline a plan before starting\n\
+        - Do NOT say \"I'll help you with...\", \"Let me guide you through...\", or \"Great question!\"\n\
+        - Do NOT use headers, bullet lists, or formatted option blocks in your first message\n\
+        - DO jump straight into conversation like a person who just sat down across the table\n\
+        - DO ask one question at a time, then actually listen to the response\n\
+        - DO keep responses short — a few sentences, not paragraphs\n\
+        - DO respond naturally to what the user says, adapting your follow-ups accordingly";
+
+    vec![
+        ("Align on the user journey", format!(
+            "{tone}\n\n\
+            YOUR ROLE: Help the user articulate what their product does and how people will use it.\n\n\
+            CONVERSATION FLOW:\n\n\
+            1. OPEN — Jump straight in. Something like:\n   \
+               \"So — what are you building? Walk me through what happens when someone opens this thing up.\"\n   \
+               (Adapt to context. Be casual. No preamble.)\n\n\
+            2. LISTEN AND DIG — Based on what they say, ask natural follow-ups. One at a time:\n   \
+               - \"And then what? What happens after [thing they mentioned]?\"\n   \
+               - \"How do they find that the first time?\"\n   \
+               - \"What's the moment where it clicks — like, this is actually useful?\"\n   \
+               Don't rush this. Let them think. Some people need 2-3 exchanges to articulate their vision.\n\n\
+            3. IF THEY'RE VAGUE — Don't present a formatted options list. Talk through possibilities naturally:\n   \
+               \"I could see this going a few ways. You could do [approach A] — really simple, users just [action]. \
+               Or something more like [approach B] where they [different flow]. What feels closer?\"\n   \
+               If they're really stuck, describe 2-3 directions conversationally and ask what resonates.\n\n\
+            4. CONFIRM — Once the journey is clear, reflect it back casually:\n   \
+               \"Cool, so basically: user shows up, [does X], then [does Y], and the payoff is [Z]. That feel right?\"\n   \
+               Wait for them to confirm or adjust.\n\n\
+            5. RECORD — After they confirm, run:\n   \
+               jettypod work epic-implement {epic_id} --aspect=\"User Journey\" --decision=\"<summary of chosen journey>\" --rationale=\"<why this flow>\"\n\n\
+            6. HAND OFF — Say something like: \"Nice. Close this chat and start the next chore in your backlog to keep going.\""
+        )),
+        ("Explore UX approaches", format!(
+            "{tone}\n\n\
+            YOUR ROLE: Help the user decide how their product should FEEL to use. This is about the experience, not the tech.\n\n\
+            CONTEXT: Read the user journey decision first:\n  \
+              jettypod decisions --epic={epic_id}\n\n\
+            CONVERSATION FLOW:\n\n\
+            1. OPEN — Reference what they already decided and pivot naturally:\n   \
+               \"So last time you said users would [brief journey recap]. Now I'm curious — what should that actually \
+               feel like? Like, when someone [key action], are you imagining something minimal and fast, or more guided and hand-holdy?\"\n   \
+               (Use their actual words from the decision. Don't be generic.)\n\n\
+            2. EXPLORE THROUGH CONVERSATION — Don't dump three formatted options. Talk through directions:\n   \
+               \"One direction would be something really stripped down — [describe the feel]. That works well when [context]. \
+               But you could also go more toward [different feel] where [description]. The trade-off is [honest assessment].\"\n   \
+               Let them react. Follow their energy.\n\n\
+            3. GET SPECIFIC — Once a direction emerges, push on it:\n   \
+               \"OK so if we go that route, the main screen would probably be [description]. Does that feel right or is that too [much/little]?\"\n\n\
+            4. OFFER PROTOTYPES (if it would help) — If they're torn or want to see it:\n   \
+               \"Want me to throw together a quick prototype of that? Nothing fancy — just enough to feel it out.\"\n   \
+               If yes, use: jettypod project prototype start <approach-name>\n   \
+               Build a minimal throwaway prototype, then: jettypod project prototype merge\n   \
+               After they try it: \"What did you think? Does that feel like the right direction, or should we adjust?\"\n\n\
+            5. CONFIRM — Lock in the winner:\n   \
+               \"Alright, so the feel is [description]. I'll record that.\"\n\n\
+            6. RECORD — Run:\n   \
+               jettypod work epic-implement {epic_id} --aspect=\"UX Approach\" --decision=\"<chosen approach>\" --rationale=\"<why>\"\n\n\
+            7. HAND OFF — \"Close this chat and start the next chore from your backlog.\""
+        )),
+        ("Choose a tech stack", format!(
+            "{tone}\n\n\
+            YOUR ROLE: Help the user pick the right tech stack based on what they're building and how it should feel.\n\n\
+            CONTEXT: Read previous decisions first:\n  \
+              jettypod decisions --epic={epic_id}\n\n\
+            CONVERSATION FLOW:\n\n\
+            1. OPEN — Connect the dots from previous decisions:\n   \
+               \"You're building [journey] and you want it to feel [UX approach]. That actually narrows down the tech quite a bit.\"\n   \
+               Then lead with your honest take:\n   \
+               \"I'd probably go with [recommendation] for this. Here's why — [reason].\"\n   \
+               (Have an opinion. Don't just present options neutrally.)\n\n\
+            2. HAVE A REAL DISCUSSION — After giving your take, open it up:\n   \
+               \"That said — do you have a preference? Are you already comfortable with something, or is there a stack you've been wanting to try?\"\n   \
+               Respond to what they say. If they push back, engage with it honestly:\n   \
+               \"Yeah, [their preference] could work. The main thing you'd lose is [trade-off]. The main thing you'd gain is [benefit]. \
+               Honestly, either would be fine for this.\"\n\n\
+            3. IF THEY WANT OPTIONS — Talk through 2-3 stacks conversationally, not as formatted comparison blocks:\n   \
+               \"[Stack A] would be the fastest to get going — you'd have [benefit] out of the box. \
+               [Stack B] is more flexible but you'd need to wire up [thing] yourself. \
+               And then there's [Stack C] which is honestly overkill here unless you specifically want [thing].\"\n\n\
+            4. LAND ON A DECISION — Once they choose:\n   \
+               \"Solid choice. [One sentence of genuine validation — why it fits their specific project, not generic praise].\"\n\n\
+            5. RECORD — Run:\n   \
+               jettypod work epic-implement {epic_id} --aspect=\"Tech Stack\" --decision=\"<chosen stack>\" --rationale=\"<why>\"\n\n\
+            6. HAND OFF — \"One more chore left — close this chat and start it from your backlog.\""
+        )),
+        ("Break the project into epics", format!(
+            "{tone}\n\n\
+            YOUR ROLE: Break the project into buildable phases (epics) based on everything they've decided.\n\n\
+            CONTEXT: Read all previous decisions first:\n  \
+              jettypod decisions --epic={epic_id}\n\n\
+            CONVERSATION FLOW:\n\n\
+            1. OPEN — Bring it all together and jump straight to the breakdown:\n   \
+               \"Alright — you're building [journey], it should feel [UX approach], and you're using [tech stack]. \
+               Let me suggest how to break this into phases.\"\n   \
+               Then just propose the epics conversationally:\n   \
+               \"I'd start with [Epic 1] — that's the foundation, stuff like [examples]. \
+               Then [Epic 2] which covers [what]. And then [Epic 3] for [what].\"\n   \
+               (Don't over-explain what an epic is. Keep it natural.)\n\n\
+            2. QUICK CONTEXT (only if needed) — If they seem unsure about the structure:\n   \
+               \"Each of these is a phase. Inside each one we'll define specific features — things users can actually do. \
+               You don't need to think about that yet though.\"\n\n\
+            3. GET FEEDBACK — After proposing:\n   \
+               \"Does that breakdown make sense? Anything you'd add, cut, or reorder?\"\n   \
+               Adjust based on their input. Don't be precious about your proposal.\n\n\
+            4. CREATE — Once they confirm, create each epic:\n   \
+               jettypod work create epic \"<title>\" \"<description>\"\n   \
+               Do this for each one.\n\n\
+            5. RECOMMEND A STARTING POINT:\n   \
+               \"If I were you, I'd start with [Epic name] — [brief reason, like 'everything else depends on it' \
+               or 'it's the quickest win to get something real'].\"\n\n\
+            6. CLOSE — \"Your project is planned. Pick an epic from the backlog and tell Claude 'Let's plan [epic name]' to start building.\""
+        )),
+    ]
+}
+
+// ---------------------------------------------------------------------------
+// Discovery decisions
+// ---------------------------------------------------------------------------
+
+/// Record an architectural/design decision for an epic.
+pub fn add_decision(
+    db: &Database,
+    work_item_id: i64,
+    aspect: &str,
+    decision: &str,
+    rationale: &str,
+) -> Result<i64> {
+    db.conn().execute(
+        "INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) \
+         VALUES (?1, ?2, ?3, ?4)",
+        params![work_item_id, aspect, decision, rationale],
+    )?;
+    Ok(db.conn().last_insert_rowid())
+}
+
+/// Get a single decision by ID.
+pub fn get_decision(db: &Database, id: i64) -> Result<Option<DiscoveryDecision>> {
+    let mut stmt = db.conn().prepare(
+        "SELECT id, work_item_id, aspect, decision, rationale, created_at \
+         FROM discovery_decisions WHERE id = ?",
+    )?;
+    let mut rows = stmt
+        .query_map(params![id], |row| {
+            Ok(DiscoveryDecision {
+                id: row.get(0)?,
+                work_item_id: row.get(1)?,
+                aspect: row.get(2)?,
+                decision: row.get(3)?,
+                rationale: row.get(4)?,
+                created_at: row.get(5)?,
+            })
+        })?;
+    match rows.next() {
+        Some(Ok(d)) => Ok(Some(d)),
+        Some(Err(e)) => Err(e.into()),
+        None => Ok(None),
+    }
+}
+
+/// Get all decisions for a work item.
+pub fn get_decisions(db: &Database, work_item_id: i64) -> Result<Vec<DiscoveryDecision>> {
+    let mut stmt = db.conn().prepare(
+        "SELECT id, work_item_id, aspect, decision, rationale, created_at \
+         FROM discovery_decisions WHERE work_item_id = ? ORDER BY created_at",
+    )?;
+    let decisions = stmt
+        .query_map(params![work_item_id], |row| {
+            Ok(DiscoveryDecision {
+                id: row.get(0)?,
+                work_item_id: row.get(1)?,
+                aspect: row.get(2)?,
+                decision: row.get(3)?,
+                rationale: row.get(4)?,
+                created_at: row.get(5)?,
+            })
+        })?
+        .collect::<std::result::Result<Vec<_>, _>>()?;
+    Ok(decisions)
+}
+
+// ---------------------------------------------------------------------------
+// Row mapping
+// ---------------------------------------------------------------------------
+
+/// Parse a required string column into a typed enum.
+fn parse_column<T: std::str::FromStr>(row: &rusqlite::Row, idx: &str) -> rusqlite::Result<T> {
+    let s: String = row.get(idx)?;
+    s.parse::<T>().map_err(|_| rusqlite::Error::FromSqlConversionFailure(
+        0, rusqlite::types::Type::Text, format!("invalid value: {s}").into(),
+    ))
+}
+
+/// Parse an optional string column into a typed enum.
+fn parse_opt_column<T: std::str::FromStr>(row: &rusqlite::Row, idx: &str) -> rusqlite::Result<Option<T>> {
+    let val: Option<String> = row.get(idx)?;
+    match val {
+        Some(s) if !s.is_empty() => s.parse::<T>()
+            .map(Some)
+            .map_err(|_| rusqlite::Error::FromSqlConversionFailure(
+                0, rusqlite::types::Type::Text, format!("invalid value: {s}").into(),
+            )),
+        _ => Ok(None),
+    }
+}
+
+fn row_to_work_item(row: &rusqlite::Row<'_>) -> rusqlite::Result<WorkItem> {
+    Ok(WorkItem {
+        id: row.get("id")?,
+        item_type: parse_column::<ItemType>(row, "type")?,
+        title: row.get("title")?,
+        description: row.get("description")?,
+        status: parse_column::<Status>(row, "status")?,
+        parent_id: row.get("parent_id")?,
+        epic_id: row.get("epic_id")?,
+        branch_name: row.get("branch_name")?,
+        mode: parse_opt_column::<Mode>(row, "mode")?,
+        current: row.get::<_, i32>("current")? != 0,
+        phase: parse_opt_column::<Phase>(row, "phase")?,
+        scenario_file: row.get("scenario_file")?,
+        completed_at: row.get("completed_at")?,
+        created_at: row.get("created_at")?,
+        display_order: row.get("display_order")?,
+        needs_discovery: row.get::<_, i32>("needs_discovery")? != 0,
+        ready_for_review: row.get::<_, i32>("ready_for_review")? != 0,
+        conversational: row.get::<_, i32>("conversational")? != 0,
+        plan_at_creation: row.get("plan_at_creation")?,
+        rejection_count: row.get("rejection_count")?,
+        rejection_round: row.get("rejection_round")?,
+        rejection_history: row.get("rejection_history")?,
+        rejection_reason: row.get("rejection_reason")?,
+        rejected_at: row.get("rejected_at")?,
+        qa_steps: row.get("qa_steps")?,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::db::Database;
+
+    fn test_db() -> (tempfile::TempDir, Database) {
+        let dir = tempfile::tempdir().unwrap();
+        let db_path = dir.path().join("test.db");
+        let db = Database::open_path_unchecked(&db_path).unwrap();
+        (dir, db)
+    }
+
+    #[test]
+    fn sanitize_title_strips_html() {
+        assert_eq!(sanitize_title("<b>Hello</b> world"), "Hello world");
+    }
+
+    #[test]
+    fn sanitize_title_removes_dangerous_chars() {
+        assert_eq!(sanitize_title("test $VAR `cmd` back\\slash"), "test VAR cmd backslash");
+    }
+
+    #[test]
+    fn sanitize_title_truncates() {
+        let long = "a".repeat(100);
+        assert_eq!(sanitize_title(&long).len(), MAX_TITLE_LEN);
+    }
+
+    #[test]
+    fn sanitize_title_normalizes_whitespace() {
+        assert_eq!(sanitize_title("  hello   world  "), "hello world");
+    }
+
+    #[test]
+    fn create_and_get() {
+        let (_dir, db) = test_db();
+        let id = create(
+            &db,
+            ItemType::Epic,
+            "Test Epic",
+            CreateOptions::default(),
+        )
+        .unwrap();
+
+        let item = get(&db, id).unwrap();
+        assert_eq!(item.title, "Test Epic");
+        assert_eq!(item.item_type, ItemType::Epic);
+        assert_eq!(item.status, Status::Backlog);
+        assert!(item.mode.is_none());
+    }
+
+    #[test]
+    fn create_feature_with_discovery_phase() {
+        let (_dir, db) = test_db();
+        let id = create(
+            &db,
+            ItemType::Feature,
+            "Test Feature",
+            CreateOptions::default(),
+        )
+        .unwrap();
+
+        let item = get(&db, id).unwrap();
+        assert_eq!(item.phase, Some(Phase::Discovery));
+        assert!(item.mode.is_none());
+    }
+
+    #[test]
+    fn create_chore_has_no_mode() {
+        let (_dir, db) = test_db();
+        let epic_id = create(
+            &db,
+            ItemType::Epic,
+            "Parent Epic",
+            CreateOptions::default(),
+        )
+        .unwrap();
+
+        let chore_id = create(
+            &db,
+            ItemType::Chore,
+            "Test Chore",
+            CreateOptions {
+                parent_id: Some(epic_id),
+                mode: Some(Mode::Speed), // Should be ignored for chores
+                ..Default::default()
+            },
+        )
+        .unwrap();
+
+        let item = get(&db, chore_id).unwrap();
+        assert!(item.mode.is_none());
+        assert_eq!(item.epic_id, Some(epic_id));
+    }
+
+    #[test]
+    fn create_with_parent_sets_epic_id() {
+        let (_dir, db) = test_db();
+        let epic_id = create(&db, ItemType::Epic, "Epic", CreateOptions::default()).unwrap();
+        let feature_id = create(
+            &db,
+            ItemType::Feature,
+            "Feature",
+            CreateOptions {
+                parent_id: Some(epic_id),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+        let chore_id = create(
+            &db,
+            ItemType::Chore,
+            "Chore",
+            CreateOptions {
+                parent_id: Some(feature_id),
+                ..Default::default()
+            },
+        )
+        .unwrap();
+
+        // Feature under epic: epic_id = epic
+        let feature = get(&db, feature_id).unwrap();
+        assert_eq!(feature.epic_id, Some(epic_id));
+
+        // Chore under feature: inherits epic_id from feature
+        let chore = get(&db, chore_id).unwrap();
+        assert_eq!(chore.epic_id, Some(epic_id));
+    }
+
+    #[test]
+    fn update_status_sets_completed_at() {
+        let (_dir, db) = test_db();
+        let id = create(&db, ItemType::Chore, "Task", CreateOptions::default()).unwrap();
+
+        update_status(&db, id, Status::Done).unwrap();
+        let item = get(&db, id).unwrap();
+        assert_eq!(item.status, Status::Done);
+        assert!(item.completed_at.is_some());
+
+        // Reset clears completed_at
+        update_status(&db, id, Status::InProgress).unwrap();
+        let item = get(&db, id).unwrap();
+        assert!(item.completed_at.is_none());
+    }
+
+    #[test]
+    fn set_current_clears_previous() {
+        let (_dir, db) = test_db();
+        let id1 = create(&db, ItemType::Chore, "Task 1", CreateOptions::default()).unwrap();
+        let id2 = create(&db, ItemType::Chore, "Task 2", CreateOptions::default()).unwrap();
+
+        set_current(&db, id1).unwrap();
+        assert!(get(&db, id1).unwrap().current);
+
+        set_current(&db, id2).unwrap();
+        assert!(!get(&db, id1).unwrap().current);
+        assert!(get(&db, id2).unwrap().current);
+    }
+
+    #[test]
+    fn get_children_works() {
+        let (_dir, db) = test_db();
+        let epic_id = create(&db, ItemType::Epic, "Epic", CreateOptions::default()).unwrap();
+        create(
+            &db,
+            ItemType::Feature,
+            "F1",
+            CreateOptions { parent_id: Some(epic_id), ..Default::default() },
+        ).unwrap();
+        create(
+            &db,
+            ItemType::Feature,
+            "F2",
+            CreateOptions { parent_id: Some(epic_id), ..Default::default() },
+        ).unwrap();
+
+        let children = get_children(&db, epic_id).unwrap();
+        assert_eq!(children.len(), 2);
+    }
+
+    #[test]
+    fn find_epic_traverses_chain() {
+        let (_dir, db) = test_db();
+        let epic_id = create(&db, ItemType::Epic, "Epic", CreateOptions::default()).unwrap();
+        let feature_id = create(
+            &db,
+            ItemType::Feature,
+            "Feature",
+            CreateOptions { parent_id: Some(epic_id), ..Default::default() },
+        ).unwrap();
+        let chore_id = create(
+            &db,
+            ItemType::Chore,
+            "Chore",
+            CreateOptions { parent_id: Some(feature_id), ..Default::default() },
+        ).unwrap();
+
+        let epic = find_epic(&db, chore_id).unwrap().unwrap();
+        assert_eq!(epic.id, epic_id);
+    }
+
+    #[test]
+    fn discovery_decisions_crud() {
+        let (_dir, db) = test_db();
+        let epic_id = create(&db, ItemType::Epic, "Epic", CreateOptions::default()).unwrap();
+
+        add_decision(&db, epic_id, "Architecture", "REST API", "Simple and well-understood").unwrap();
+        add_decision(&db, epic_id, "Database", "SQLite", "Embedded, no server needed").unwrap();
+
+        let decisions = get_decisions(&db, epic_id).unwrap();
+        assert_eq!(decisions.len(), 2);
+        assert_eq!(decisions[0].aspect, "Architecture");
+        assert_eq!(decisions[1].aspect, "Database");
+    }
+
+    #[test]
+    fn set_mode_rejects_non_features() {
+        let (_dir, db) = test_db();
+        let id = create(&db, ItemType::Chore, "Chore", CreateOptions::default()).unwrap();
+        assert!(set_mode(&db, id, "speed").is_err());
+    }
+
+    #[test]
+    fn get_tree_filters_completed() {
+        let (_dir, db) = test_db();
+        let id1 = create(&db, ItemType::Chore, "Active", CreateOptions::default()).unwrap();
+        let id2 = create(&db, ItemType::Chore, "Done", CreateOptions::default()).unwrap();
+        update_status(&db, id2, Status::Done).unwrap();
+
+        let active = get_tree(&db, false).unwrap();
+        assert_eq!(active.len(), 1);
+        assert_eq!(active[0].id, id1);
+
+        let all = get_tree(&db, true).unwrap();
+        assert_eq!(all.len(), 2);
+    }
+
+    #[test]
+    fn rejection_tracking() {
+        let (_dir, db) = test_db();
+        let id = create(&db, ItemType::Feature, "Feature", CreateOptions::default()).unwrap();
+
+        increment_rejection(&db, id, Some("Needs more tests")).unwrap();
+        let item = get(&db, id).unwrap();
+        assert_eq!(item.rejection_count, 1);
+        assert_eq!(item.rejection_reason.as_deref(), Some("Needs more tests"));
+        assert!(item.rejected_at.is_some());
+
+        // Child should inherit rejection_round
+        let child_id = create(
+            &db,
+            ItemType::Chore,
+            "Fix",
+            CreateOptions { parent_id: Some(id), ..Default::default() },
+        ).unwrap();
+        let child = get(&db, child_id).unwrap();
+        assert_eq!(child.rejection_round, Some(1));
+    }
+
+    #[test]
+    fn complete_discovery_transition() {
+        let (_dir, db) = test_db();
+        let id = create(&db, ItemType::Feature, "Feature", CreateOptions::default()).unwrap();
+
+        complete_discovery(&db, id, Some("test.feature"), Some("Approach A"), Some("Best fit")).unwrap();
+        let item = get(&db, id).unwrap();
+        assert_eq!(item.phase, Some(Phase::Implementation));
+        assert_eq!(item.mode, Some(Mode::Speed));
+        assert_eq!(item.status, Status::Todo);
+        assert_eq!(item.scenario_file.as_deref(), Some("test.feature"));
+    }
+}