feat: [ENG-2153] Curate command blocks execution and prevents concurrent actions

src/server/templates/sections/brv-instructions.md

@@ -80,6 +80,28 @@ brv curate view --help        # All filter options
 **⚠️ CRITICAL - LONG CONVERSATIONS:**
 If you modify code 10 times in a conversation, curate 10 times. Do NOT batch or skip. Each code change = immediate curate before moving on.
 
+## Decision: Wait by default, `--detach` needs BOTH gates
+
+Default is `brv curate "..."` (no flag) — **wait for it to finish** before continuing. Use `--detach` ONLY when BOTH gates hold:
+
+1. **Within-turn gate:** no remaining step in this turn reads/queries/references this data, AND no later curate in this turn builds on it.
+2. **User-signal gate:** user explicitly said not to wait — phrases addressed *to you* like "don't wait", "don't block on this", "fire and forget", "move on without waiting". Excludes "run in background" / "run async" (agent self-narrates these; not user signals).
+
+**If user phrasing is ambiguous → wait.** "Quick one, keep moving" is not enough.
+
+**NOT reasons to `--detach`** (common self-justifications to reject):
+- Curate is slow / large folder / many files → size is irrelevant, block anyway.
+- "Looks like the last step of the turn" → that's a guess, not evidence. Block.
+- "I can't think of anything that would depend on it" → block.
+
+If either gate is uncertain → wait. When in doubt, wait. Correctness beats latency.
+
+**After `--detach`:**
+- Report "queued" with the `logId` — do NOT claim "saved"
+- Before querying data from a prior `--detach`, run `brv curate view <logId>` and wait for `status: completed`
+
+**⚠️ CRITICAL:** `--detach` errors are silent. Always verify completion via `brv curate view <logId>` before trusting the data exists.
+
 ## Quick Reference Table
 
 | Task Type | Query? | Curate? |

src/server/templates/sections/command-reference.md

@@ -2,7 +2,8 @@
 
 ## Available Commands
 
-- `brv curate` - Curate context to the context tree (returns a logId on completion)
+- `brv curate` - Curate context to the context tree. **Blocking default — wait for it to finish before continuing** (returns `logId` on completion).
+- `brv curate <ctx> --detach` - Queue curate and return `logId` immediately. Use ONLY when BOTH (a) no remaining step in this turn reads this data or builds on it, AND (b) user explicitly said not to wait ("don't wait", "fire and forget"). See Workflow.
 - `brv curate view` - List curate history (last 10 entries by default)
 - `brv curate view <logId>` - Full detail for a specific entry: all files and operations performed (logId returned by `brv curate`)
 - `brv curate view --detail` - List entries with their file operations visible (no logId needed)

src/server/templates/sections/workflow.md

@@ -25,6 +25,20 @@ Use `brv curate` **after** you learn or create something valuable:
 
 After curating, use `brv curate view <logId>` to verify what was stored (logId printed on completion).
 
+## Execution Mode: wait by default
+
+Default is `brv curate "..."` (no flag) — **wait for it to finish** before continuing. Any follow-up (query, search, read, or a later curate that builds on this one) may depend on the curated data being live.
+
+Use `--detach` only when BOTH are true:
+1. No remaining step in this turn reads/queries/references this data, AND no later curate in this turn builds on it.
+2. User explicitly said not to wait — addressed to the agent, e.g. "don't wait", "don't block on this", "fire and forget", "move on without waiting". Excludes "run in background" / "run async" (agent self-narrates these).
+
+If user phrasing is ambiguous → wait. If either condition is uncertain → wait.
+
+Size/duration is NOT a reason to `--detach`. "Looks like the last step" is NOT a reason — it's a guess.
+
+After `--detach`, report "queued" (not "saved") and save the `logId`. Before any later read of that data, run `brv curate view <logId>` and wait for `status: completed`. Detach errors are silent.
+
 ## Context Tree Guideline
 
 Good context is:

src/server/templates/skill/SKILL.md

@@ -77,6 +77,38 @@ brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via
 brv curate "Authentication middleware details" -f src/middleware/auth.ts
 ```
 
+**Execution mode: wait by default**
+
+Default is **blocking** — call `brv curate "..."` with no flag and wait for it to finish before continuing. Any follow-up step (query, search, read, review, next curate that builds on this one) may depend on the just-curated data being live in the context tree.
+
+```bash
+brv curate "..."                 # DEFAULT — wait until done, then continue
+brv curate "..." --detach        # Only when BOTH conditions below hold
+```
+
+**Use `--detach` only when BOTH of the following are true:**
+
+1. No remaining step in this turn will query, search, read, or reference this curated data, AND no later curate in this turn builds on it.
+2. The user explicitly said not to wait — phrases addressed *to you* like "don't wait", "don't block on this", "fire and forget", "move on without waiting". The phrase must be something the user says to the agent, not something the agent would narrate about itself. This rules out "run in background" and "run async" as triggers — agents use those phrases to self-narrate at least as often as users use them to instruct, which creates a mirror-priming loop.
+
+**If the user's phrasing is ambiguous, wait.** Detach requires an unambiguous signal. "Quick one, keep moving" is not enough.
+
+If either condition is uncertain, do not `--detach`. Wait.
+
+**Size/duration is NOT a reason to `--detach`.** A slow curate whose output the next step reads must still block. **"Looks like the last step" is also NOT a reason** — that is a guess, not evidence.
+
+**Reporting:**
+- Blocking (default) → "Saved X"
+- `--detach` → "Queued X (log: `<logId>`)" — do NOT claim "saved" until verified
+
+**Cross-turn hygiene for detached curates (CRITICAL):** before any later tool call reads data a previous `--detach` submitted, run:
+
+```bash
+brv curate view <logId> --format json
+```
+
+Only proceed when `status: completed`. If `processing`, wait or tell the user. If `error`/`cancelled`, report and consider re-curate. `--detach` errors are silent — verification before trust is mandatory.
+
 ### 4. Review Pending Changes
 **Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.