Update commit documentation to reflect default behavior of fast commit with deferred Codex review; clarify options for blocking review and configuration defaults.

Author: nikivdev

docs/commands/commit.md

@@ -1,19 +1,19 @@
 # f commit
 
-AI-powered commit with code review and GitEdit sync.
+AI-powered commit with deferred Codex review and GitEdit sync.
 
 ## Overview
 
-Stages all changes, runs AI code review for bugs and security issues, generates a commit message, commits, pushes, and syncs AI sessions to gitedit.dev.
+Stages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.
 
 ## Quick Start
 
 ```bash
-# Standard commit with review
+# Default flow: commit now, Codex review runs in background
 f commit
 
-# Fast commit (no AI review), then Codex reviews async in background
-f commit --quick
+# Blocking pre-commit review (legacy behavior)
+f commit --slow
 
 # Fast commit with custom message (no AI review, no Codex follow-up)
 f commit --fast "fix typo"
@@ -42,7 +42,8 @@ f commit -m "Fixes #123"
 | `--sync` | | Run synchronously (don't delegate to hub) |
 | `--context` | | Include AI session context in code review |
 | `--dry` | | Dry run: show context without committing |
-| `--quick` | | Commit now, run Codex review async in background |
+| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |
+| `--slow` | | Run blocking pre-commit review before commit |
 | `--fast [MSG]` | | Fast commit with no AI review (defaults to ".") |
 | `--codex` | | Use Codex instead of Claude for review |
 | `--review-model <MODEL>` | | Choose specific review model |
@@ -69,15 +70,15 @@ f commit --review-model codex-high
 
 ## Fast Commit + Deferred Codex Review
 
-Two flags for skipping the synchronous AI review when you want to commit quickly:
+`f commit` now uses this mode by default.
 
-### `--quick` — commit now, Codex reviews later
+### Default (`f commit`) / `--quick` — commit now, Codex reviews later
 
 Commits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.
 
 ```bash
+f commit
 f commit --quick
-f commit --quick -m "wip: rough draft"
 ```
 
 What happens:
@@ -86,6 +87,15 @@ What happens:
 3. Spawns a background Codex process that reviews the diff
 4. You keep working — check results later with `f commit-queue list`
 
+### `--slow` — run blocking review before commit
+
+Runs the pre-commit AI review before creating the commit.
+
+```bash
+f commit --slow
+f commit --slow --review-model codex-high
+```
+
 ### `--fast` — instant commit, no review at all
 
 Commits with a provided message (or `"."` if omitted). No AI review, no async follow-up. Useful for trivial changes.
@@ -99,20 +109,21 @@ f commit --fast              # message defaults to "."
 
 | Flag | AI message | Code review | Async review | Best for |
 |------|-----------|-------------|-------------|----------|
-| (none) | Yes | Yes (blocking) | No | Normal workflow |
-| `--quick` | Yes | No | Yes (Codex background) | Fast iteration, review later |
+| (none) | Yes | No | Yes (Codex background) | Default fast workflow |
+| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |
+| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |
 | `--fast` | No (you provide) | No | No | Trivial/WIP commits |
 
-### Default Fast Lane (No Extra Flags)
+### Opt Out Of Fast Default
 
-If you want `f commit` to default to fast commit + deferred Codex review, set:
+If you want plain `f commit` to run blocking review by default, set:
 
 ```toml
 [commit]
-quick-default = true
+quick-default = false
 ```
 
-With this enabled, plain `f commit` behaves like `f commit --quick` unless you explicitly ask for blocking review options.
+With this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.
 
 Run deep review in batches:
 
@@ -291,7 +302,7 @@ Threshold: 500+ lines added/removed.
 
 | Command | Description |
 |---------|-------------|
-| `f commit` | Full review + GitEdit sync (default) |
+| `f commit` | Fast commit + deferred Codex review (default) |
 | `f commitWithCheck` | Review without GitEdit sync |
 | `f commitSimple` | No review, just AI commit message |
 

docs/fast-commit-deep-review-loop.md

@@ -9,7 +9,6 @@ This guide configures a speed-first commit workflow with deferred deep review:
 
 ```toml
 [commit]
-quick-default = true
 queue = false
 queue_on_issues = false
 
@@ -66,6 +65,6 @@ This replaces manual “copy `f commit` output into Codex and ask to address all
 
 ## Notes
 
-- `quick-default = true` applies to plain `f commit` (not `f commit-with-check`) and uses the fast lane (`--quick`) unless you explicitly request blocking review options.
+- Plain `f commit` already uses the fast lane (`--quick`) by default. Set `quick-default = false` only if you want blocking review as the default.
 - Async queued Codex reviews now emit `commit_queue_review` mirror sync events to myflow/gitedit when the reviewed commit is current `HEAD` (the default `f commit --quick` flow).
 - `f reviews-todo codex --all` is a workflow alias over commit queue deep review.

docs/flow-toml-spec.md

@@ -43,12 +43,19 @@ install = ["linear"]  # optional: ensure skills are installed (local ~/.codex/sk
 # allow_direct_fallback = true
 
 [commit]             # optional: commit workflow defaults
-# quick-default = true        # make `f commit` behave like `--quick` by default
+# quick-default = false       # optional override: make plain `f commit` run blocking review (`--slow`)
 # queue = false               # keep fast path pushing by default
 # queue_on_issues = false     # do not force queue-only flow on review issues
 # message-fallbacks = ["rise:zai:glm-5", "rise:cerebras:gpt-oss-120b", "remote", "openai"]
 # review-fallbacks = ["glm5", "rise:cerebras:gpt-oss-120b", "codex-high"]
 
+[task_resolution]    # optional: nested-task disambiguation policy
+# preferred_scopes = ["mobile", "root"]    # used when plain task name is ambiguous
+# warn_on_implicit_scope = true             # print note when fallback routing is applied
+[task_resolution.routes]
+# dev = "mobile"                            # route ambiguous task name -> scope
+# test = "root"
+
 [options]            # optional: transport/runtime integrations
 # myflow_mirror = true         # mirror commit + queue review events to myflow
 # myflow_url = "https://myflow.sh"
@@ -100,7 +107,8 @@ fr = "f run"
 - `[skills]`: optional skill enforcement; `sync_tasks` generates `.ai/skills` from tasks and `install` ensures registry skills are present (skills are gitignored by default).
 - `[skills.codex]`: optional Codex tuning; task skill `agents/openai.yaml` generation, post-sync force reload, and implicit invocation policy defaults.
 - `[skills.seq]`: optional defaults for `f skills fetch ...` (local seq scraper integration).
-- `[commit]`: optional commit workflow defaults; `quick-default = true` makes plain `f commit` use fast commit + deferred Codex deep review.
+- `[commit]`: optional commit workflow defaults; plain `f commit` uses fast commit + deferred Codex deep review by default. Set `quick-default = false` to make plain `f commit` run blocking review instead.
+- `[task_resolution]`: optional policy for nested task discovery (`f <scope>:<task>`, preferred scopes, and per-task routes when plain names collide).
 - `[options]`: optional integration/runtime toggles; use `myflow_mirror` for mirror sync and `codex_bin` to route review calls through a wrapper transport.
 - `[commit.testing]`: optional local testing gate evaluated during `f commit`; supports Bun-first strict mode plus optional AI scratch-test fallback (`.ai/test` by default).
 - `[commit.skill_gate]`: optional required-skill policy for `f commit`; can enforce presence and minimum skill versions.

src/ask.rs

@@ -460,6 +460,8 @@ mod tests {
             config_path: PathBuf::from("flow.toml"),
             relative_dir: String::new(),
             depth: 0,
+            scope: "root".to_string(),
+            scope_aliases: vec!["root".to_string()],
         }
     }
 

src/cli.rs

@@ -223,7 +223,7 @@ pub enum Commands {
     Branches(BranchesCommand),
     #[command(
         about = "AI-powered commit with code review and optional GitEdit sync.",
-        long_about = "Stages all changes (or only paths passed via --path), runs code review for bugs/security, generates commit message, commits, pushes (unless commit queue is enabled), and syncs AI sessions to gitedit.dev when enabled in global config.",
+        long_about = "Stages all changes (or only paths passed via --path), commits quickly by default, starts deferred Codex deep review in the background, and syncs AI sessions to gitedit.dev when enabled in global config. Use --slow to run blocking review before commit.",
         alias = "c"
     )]
     Commit(CommitOpts),
@@ -792,13 +792,25 @@ pub struct TasksCommand {
 pub enum TasksAction {
     /// List tasks from the current project flow.toml.
     List(TasksListOpts),
+    /// Show duplicate task names discovered across nested flow.toml files.
+    Dupes(TasksDupesOpts),
 }
 
 #[derive(Args, Debug, Clone)]
 pub struct TasksListOpts {
     /// Path to the project flow config (flow.toml).
     #[arg(long, default_value = "flow.toml")]
     pub config: PathBuf,
+    /// Show only duplicate task names and their scopes.
+    #[arg(long)]
+    pub dupes: bool,
+}
+
+#[derive(Args, Debug, Clone)]
+pub struct TasksDupesOpts {
+    /// Path to the project flow config (flow.toml).
+    #[arg(long, default_value = "flow.toml")]
+    pub config: PathBuf,
 }
 
 #[derive(Args, Debug, Clone)]
@@ -1450,6 +1462,9 @@ pub struct CommitOpts {
     /// Commit immediately and run Codex review asynchronously in the background.
     #[arg(long, conflicts_with = "dry")]
     pub quick: bool,
+    /// Run blocking review before committing (legacy commitWithCheck behavior).
+    #[arg(long, conflicts_with = "quick")]
+    pub slow: bool,
     /// Use Codex instead of Claude for code review (default: Claude).
     #[arg(long)]
     pub codex: bool,

src/commit.rs

@@ -1136,7 +1136,7 @@ pub fn commit_quick_default_enabled() -> bool {
         }
     }
 
-    false
+    true
 }
 
 fn commit_review_fail_open_enabled(repo_root: &Path) -> bool {

src/config.rs

@@ -108,6 +108,14 @@ pub struct Config {
     /// Setup defaults (global or project-level).
     #[serde(default)]
     pub setup: Option<SetupConfig>,
+    /// Task lookup resolution policy for nested flow.toml discovery.
+    #[serde(
+        default,
+        rename = "task_resolution",
+        alias = "task-resolution",
+        alias = "taskResolution"
+    )]
+    pub task_resolution: Option<TaskResolutionConfig>,
     /// SSH defaults (global or project-level).
     #[serde(default)]
     pub ssh: Option<SshConfig>,
@@ -593,6 +601,7 @@ impl Default for Config {
             git: None,
             jj: None,
             setup: None,
+            task_resolution: None,
             ssh: None,
             macos: None,
             proxy: None,
@@ -812,6 +821,30 @@ pub struct SetupServerConfig {
     pub host: Option<crate::deploy::HostConfig>,
 }
 
+/// Task lookup policy for nested flow.toml discovery.
+#[derive(Debug, Clone, Deserialize, Default)]
+pub struct TaskResolutionConfig {
+    /// Preferred scope order for ambiguous task names (e.g. ["mobile", "root"]).
+    #[serde(
+        default,
+        rename = "preferred_scopes",
+        alias = "preferred-scopes",
+        alias = "preferredScopes"
+    )]
+    pub preferred_scopes: Vec<String>,
+    /// Exact task-name routes (task -> scope), used before preferred scope order.
+    #[serde(default)]
+    pub routes: HashMap<String, String>,
+    /// Print a note when implicit scope routing chooses a target.
+    #[serde(
+        default,
+        rename = "warn_on_implicit_scope",
+        alias = "warn-on-implicit-scope",
+        alias = "warnOnImplicitScope"
+    )]
+    pub warn_on_implicit_scope: Option<bool>,
+}
+
 /// Global feature toggles.
 #[derive(Debug, Clone, Default, Deserialize)]
 pub struct OptionsConfig {
@@ -947,6 +980,26 @@ impl OptionsConfig {
     }
 }
 
+impl TaskResolutionConfig {
+    fn merge(&mut self, other: TaskResolutionConfig) {
+        if self.preferred_scopes.is_empty() {
+            self.preferred_scopes = other.preferred_scopes;
+        } else {
+            for scope in other.preferred_scopes {
+                if !self.preferred_scopes.iter().any(|s| s == &scope) {
+                    self.preferred_scopes.push(scope);
+                }
+            }
+        }
+        if self.warn_on_implicit_scope.is_none() {
+            self.warn_on_implicit_scope = other.warn_on_implicit_scope;
+        }
+        for (task, scope) in other.routes {
+            self.routes.entry(task).or_insert(scope);
+        }
+    }
+}
+
 /// Configuration for a single managed HTTP server process.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ServerConfig {
@@ -1882,6 +1935,13 @@ fn merge_config(base: &mut Config, other: Config) {
             }
         }
     }
+    if base.task_resolution.is_none() {
+        base.task_resolution = other.task_resolution;
+    } else if let (Some(base_resolution), Some(other_resolution)) =
+        (base.task_resolution.as_mut(), other.task_resolution)
+    {
+        base_resolution.merge(other_resolution);
+    }
     if base.analytics.is_none() {
         base.analytics = other.analytics;
     }
@@ -2416,6 +2476,36 @@ codex_bin = "/tmp/codex-jazz"
         assert_eq!(cfg.options.codex_bin.as_deref(), Some("/tmp/codex-jazz"));
     }
 
+    #[test]
+    fn task_resolution_config_parses() {
+        let toml = r#"
+[task_resolution]
+preferred_scopes = ["mobile", "root"]
+warn_on_implicit_scope = true
+
+[task_resolution.routes]
+dev = "mobile"
+test = "root"
+"#;
+        let cfg: Config = toml::from_str(toml).expect("task_resolution should parse");
+        let resolution = cfg
+            .task_resolution
+            .expect("task_resolution config expected");
+        assert_eq!(
+            resolution.preferred_scopes,
+            vec!["mobile".to_string(), "root".to_string()]
+        );
+        assert_eq!(resolution.warn_on_implicit_scope, Some(true));
+        assert_eq!(
+            resolution.routes.get("dev").map(String::as_str),
+            Some("mobile")
+        );
+        assert_eq!(
+            resolution.routes.get("test").map(String::as_str),
+            Some("root")
+        );
+    }
+
     #[test]
     fn commit_testing_config_parses() {
         let toml = r#"