moflo 4.9.19 → 4.9.21

package/.claude/guidance/shipped/moflo-spell-troubleshooting.md

@@ -0,0 +1,149 @@
+# Spell Troubleshooting — Sandbox, Network, and Permission Failures
+
+**Purpose:** Diagnostic playbook for spell step failures that look like environmental issues but are actually capability/sandbox boundaries. Reference this when a step "should work" but produces DNS errors, silent no-ops, or confusing downstream failures. Pair with `.claude/guidance/moflo-spell-sandboxing.md` for the underlying enforcement model.
+
+---
+
+## Bash Step Fails With DNS / SSH Resolution Errors
+
+The single most common spell failure mode. The step works fine in your normal shell, then fails inside a spell with what looks like a network/DNS problem.
+
+### Typical Error Messages
+
+- `ssh: Could not resolve hostname github.com: Temporary failure in name resolution`
+- `fatal: Could not read from remote repository.`
+- `curl: (6) Could not resolve host ...`
+- `getaddrinfo ENOTFOUND ...`
+- Any other DNS/connection failure where the **same command works in your normal shell**.
+
+### Tell-Tale Clue
+
+The error mentions `Temporary failure in name resolution` — a **glibc-specific** wording. That means the step is running inside a Linux sandbox (`bwrap` on Linux / WSL), **not** your outer shell. Git Bash or PowerShell won't produce that exact message.
+
+### Root Cause
+
+`src/cli/spells/core/bwrap-sandbox.ts` isolates the network by default:
+
+```ts
+if (!hasNet && !needsToolHomeAccess(options.permissionLevel)) {
+  args.push('--unshare-net');   // ← no network, no DNS
+}
+```
+
+A bash step gets network access **only when one of these is true**:
+
+1. The step declares a `net` capability, **or**
+2. The step's `permissionLevel` is `elevated` or `autonomous`.
+
+If neither applies, bwrap runs the command in a namespace with `--unshare-net`, and DNS silently fails. **There is no log line announcing the network was taken away** — you just see the command's own DNS error.
+
+### Fix
+
+For any bash step that does `git pull` / `git push` / `git fetch`, `gh` API calls, `curl`, `npm install`, or any other outbound network call:
+
+```yaml
+- id: create-branch
+  type: bash
+  permissionLevel: elevated       # ← grants network in bwrap
+  config:
+    command: "git pull origin main && ..."
+```
+
+Or declare the `net` capability explicitly if the step doesn't need the full `elevated` profile. **Note:** `bash-command.ts` must include `net` in its declared capabilities for the engine to accept the grant — otherwise you'll see:
+
+```
+Capability violation: step type "bash" does not declare capability "net"
+```
+
+### Quick Diagnosis Checklist
+
+When a spell's bash step can't reach the network, walk through these in order:
+
+| # | Question | If yes |
+|---|----------|--------|
+| 1 | Does the same command work in your outer shell? | Sandbox-related, not config — go to #2 |
+| 2 | Is the error wording glibc-style (`Temporary failure in name resolution`)? | bwrap is involved — go to #3 |
+| 3 | Does the failing step have `permissionLevel: elevated` or a `net` capability? | If no, add one and retry |
+| 4 | Does the multi-command step start with `set -e`? | If no, add it (see § Multi-Command `set -e` Traps below) |
+
+---
+
+## Multi-Command `set -e` Traps
+
+A bash step that chains multiple statements without `set -e` will **return exit code 0 even when the real work failed**, producing confusing errors several steps later.
+
+### Symptom
+
+A spell step appears to succeed (`exitCode: 0`), but a later step fails with something that should have been impossible — typically:
+
+- `pathspec did not match` on a branch that was never created
+- `nothing to commit` when you expected staged changes
+- File operations on paths that don't exist
+
+### Root Cause
+
+Without `set -e`, a multi-command bash step like this:
+
+```yaml
+- id: prep-branch
+  type: bash
+  config:
+    command: "git pull origin main && git checkout -b feat/x && git stash pop || true"
+```
+
+…will mask a failure in `git pull` (e.g. blocked by `--unshare-net`) because the trailing `git stash pop || true` returns 0 for the whole step. Downstream steps assume the branch exists and produce the confusing `pathspec` error.
+
+### Fix
+
+Lead every multi-command bash step with `set -e`:
+
+```yaml
+- id: prep-branch
+  type: bash
+  permissionLevel: elevated
+  config:
+    command: |
+      set -e
+      git pull origin main
+      git checkout -b feat/x
+      git stash pop || true   # only this one is allowed to fail
+```
+
+`set -e` makes the shell exit on any non-zero status, surfacing the real failure at the right step.
+
+---
+
+## Capability Violation Errors
+
+When a spell YAML restricts capabilities a command doesn't declare, or grants new types beyond the command's defaults, the runner blocks execution before the step runs.
+
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| `Capability violation: step type "X" does not declare capability "Y"` | YAML restricts a capability the step command doesn't list | Add `Y` to the step command's `capabilities` array (in code), or remove the restriction from YAML |
+| `CAPABILITY_DENIED at runtime` | A command tried to access a path/host outside its effective scope | Tighten the command, or widen the YAML capability scope to include the resource |
+
+See `.claude/guidance/moflo-spell-sandboxing.md` § Enforcement at Runtime for the two-layer enforcement model.
+
+---
+
+## Step Silently No-Ops
+
+A step appears to run (`exitCode: 0`), produces no output, and downstream steps act as if no work happened.
+
+| Likely cause | Diagnostic |
+|--------------|------------|
+| Command writes to stdout but bwrap blocks the working directory | Check `permissionLevel`; bwrap restricts `fs:write` to declared scopes |
+| Variable interpolation produced an empty string | Run with `dryRun: true` to see resolved configs (see `moflo-spell-runner.md`) |
+| `continueOnError: true` is hiding a real failure | Remove `continueOnError` temporarily, re-run, inspect error output |
+| Trailing `|| true` on the only critical statement | Restructure with `set -e` and place `|| true` only on cleanup statements |
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability types, enforcement layers, permission levels (the model these failures exercise)
+- `.claude/guidance/moflo-spell-engine.md` — Step definition format and types
+- `.claude/guidance/moflo-spell-runner.md` — Dry-run validation, error codes, pause/resume
+- `.claude/guidance/moflo-yaml-reference.md` — `sandbox:` block in `moflo.yaml` (master toggle, tier selection)
+- `src/cli/spells/core/bwrap-sandbox.ts` — Source for `--unshare-net` and namespace setup
+- `src/cli/spells/core/permission-resolver.ts` — Capability → permission level derivation

package/.claude/guidance/shipped/moflo-subagents.md

@@ -1,150 +1,79 @@
-# MoFlo Subagents Guide
+# MoFlo Subagents — Spawn Protocol
 
-**Purpose:** Protocol for subagents spawned by coordinators. Follow these steps before doing any work.
+**Purpose:** Steps every subagent MUST run when spawned by a coordinator. The single-sentence directive injected by `SubagentStart` (see `.claude/helpers/subagent-bootstrap.json`) tells every subagent to memory-search first, then follow this protocol. Universal coding/coordination rules every agent (coordinator OR subagent) shares live in `.claude/guidance/moflo-agent-rules.md` — read those after Step 1.
 
 ---
 
-## 1. Search Memory FIRST
+## Step 1: Search Memory FIRST
 
-**Before reading any files or exploring code, search memory for guidance relevant to your task.**
+**Before reading any files or exploring code, search memory.** This is the bootstrap action — moflo's gates will block your `Glob`/`Grep`/`Read` calls until you do.
 
-### Namespaces to search:
-
-| Namespace | When to search | What it returns |
-|-----------|---------------|-----------------|
-| `guidance` | always | Guidance docs, coding rules, domain context |
-| `patterns` | always | Learned patterns from previous task execution |
-| `learnings` | always | User-directed decisions + distilled insights (post-mortems, gotchas, lessons learned) |
-| `code-map` | navigating code | Project overviews, directory contents, type-to-file mappings |
-| `tests` | test/coverage queries | Indexed test inventory — pinpoint specs and coverage for a given function/module |
-
-**Always search `patterns` and `learnings` alongside `guidance`.** Patterns hold solutions to already-solved problems; learnings hold incident insights and user-stated decisions. Skipping either means repeating past mistakes or violating standing decisions.
-
-**Search `code-map` BEFORE using Glob/Grep for navigation.** It's faster and returns structured results including file-level type mappings.
-
-**Search `tests` when looking for test coverage** of a function, module, or behavior — it indexes the test tree separately so you can pinpoint specs without grepping the whole repo.
-
-### Option A: MCP Tools (Preferred)
-
-If you have MCP tools available (check for `mcp__moflo__*`), use them directly:
-
-| Tool | Purpose |
-|------|---------|
-| `mcp__moflo__memory_search` | Semantic search with domain-aware embeddings |
-| `mcp__moflo__memory_store` | Store patterns with auto-vectorization |
-| `mcp__moflo__hooks_route` | Get agent routing suggestions |
-
-### Option B: CLI via Bash
-
-```bash
-npx flo memory search --query "[describe your task]" --namespace guidance --limit 5
+```
+mcp__moflo__memory_search   query: "[describe your task]"   namespace: "guidance"
 ```
 
-| Your task involves... | Search namespace | Example query |
-|-----------------------|------------------|---------------|
-| Database/entities | `guidance` + `patterns` + `learnings` | `"database entity migration"` |
-| Frontend components | `guidance` + `patterns` + `learnings` | `"React frontend component"` |
-| API endpoints | `guidance` + `patterns` + `learnings` | `"API route endpoint pattern"` |
-| Authentication | `guidance` + `patterns` + `learnings` | `"auth middleware JWT"` |
-| Prior solutions/gotchas | `patterns` + `learnings` | `"audit log service pattern"` |
-| Past incident/lesson | `learnings` | `"windows postinstall file locks"` |
-| Where is a file/type? | `code-map` | `"CompanyEntity file location"` |
-| What's in a directory? | `code-map` | `"back-office api routes"` |
-| Tests for a function | `tests` | `"audit log service tests"` |
-| Coverage for a module | `tests` | `"auth middleware test cases"` |
-
-Use results with score > 0.3. If no good results, fall back to reading project guidance docs.
-
----
-
-## 2. Check for Project-Specific Overrides
+Run the search **at least three times** — once each against `guidance`, `patterns`, and `learnings`. Patterns hold prior solutions; learnings hold standing decisions and post-mortem insights. Skipping either repeats past mistakes. Add `code-map` when navigating code, `tests` when looking for test coverage.
 
-Claude Code automatically loads all `.claude/guidance/*.md` files into your context. If the consuming project has its own guidance files (e.g., domain rules, entity patterns, tech stack conventions), they are already available to you — no need to read them manually.
+CLI fallback when MCP is unavailable: `npx flo memory search --query "..." --namespace guidance --limit 5`.
 
-Project-specific guidance always takes precedence over generic MoFlo guidance.
+The full namespace reference, query examples by domain, and tool catalog live in `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — read that next.
 
 ---
 
-## 3. Universal Rules
-
-### Memory Protocol
-- Search memory before exploring files
-- Store discoveries back to memory when done
-- Use `patterns` namespace for solutions and gotchas
-- Use `learnings` namespace for architectural choices, user-requested decisions, and distilled insights (`knowledge` is a deprecated alias — writes are auto-redirected)
+## Step 2: Apply Universal Agent Rules
 
-### Git/Branches
-- Use conventional commit prefixes: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
-- Use branch prefixes: `feature/`, `fix/`, `refactor/`
-- Use kebab-case for branch names
+Every moflo agent — coordinator or subagent — must follow `.claude/guidance/moflo-agent-rules.md`. The most load-bearing rules for subagents specifically:
 
-### Pull Requests — CRITICAL: Always target the correct repo
-**NEVER run bare `gh pr create` in a forked repository.** The `gh` CLI defaults to the upstream parent repo, not the fork's origin. This has caused PRs to be accidentally opened against upstream.
+| Rule | Detail |
+|------|--------|
+| **Task Icons** | `TaskCreate` MUST use **ICON + [Role]** in `subject` and `activeForm` — see `.claude/guidance/moflo-task-icons.md`. Example: `🧪 [Tester] Run unit tests` / activeForm: `🧪 Running unit tests` |
+| **PR target repo (CRITICAL)** | Never run bare `gh pr create` in a forked repo — it defaults to upstream. Always pass `--repo "$REPO"`. Full workflow in `moflo-agent-rules.md` |
+| **MCP-first tool selection** | Prefer `mcp__moflo__*` tools over `npx flo` CLI. CLI is fallback only |
+| **Build & test after changes** | Never leave failing tests; fix red signals at the source |
 
-**Required workflow:**
-```bash
-# 1. Determine the correct repo from the origin remote
-REPO=$(git remote get-url origin | sed 's|.*github.com[:/]||;s|\.git$||')
-
-# 2. ALWAYS pass --repo to gh pr create
-gh pr create --repo "$REPO" --title "..." --body "..."
-
-# 3. For merge: also pass --repo
-gh pr merge <number> --repo "$REPO" --squash
-```
+The full set (git/branch conventions, file organization, build/test discipline, storing discoveries) is in `.claude/guidance/moflo-agent-rules.md`.
 
-This applies to ALL `gh` commands that target a repo: `pr create`, `pr merge`, `pr list`, `issue create`, etc.
+---
 
-### File Organization
-- Never save working files to repository root
-- Keep changes focused (3-10 files)
-- Stay within feature scope
+## Step 3: Check for Project-Specific Overrides
 
-### Build & Test
-- Build and test after code changes
-- Never leave failing tests
+Claude Code automatically loads all `.claude/guidance/*.md` files into your context. If the consuming project has its own guidance files (domain rules, entity patterns, tech-stack conventions), they're already available — no need to read them manually.
 
-### Task Icons (MANDATORY)
-- `TaskCreate` MUST use **ICON + [Role]** in `subject` and `activeForm`
-- Full icon map: `.claude/guidance/shipped/moflo-task-icons.md`
-- Example: `🧪 [Tester] Run unit tests` / activeForm: `🧪 Running unit tests`
+**Project-specific guidance always takes precedence over generic MoFlo guidance.**
 
 ---
 
-## 4. Store Discoveries
+## Step 4: Store Discoveries Before Reporting
 
-If you discover something new (pattern, solution, gotcha), store it:
+Before signing off your work, store anything useful you discovered during the task. Future agents shouldn't have to re-discover what you already learned.
 
-### MCP (Preferred):
-```
-mcp__moflo__memory_store
-  namespace: "patterns"
-  key: "brief-descriptive-key"
-  value: "1-2 sentence insight"
-```
+| Namespace | What to store |
+|-----------|---------------|
+| `patterns` | Solutions to tricky bugs, gotchas, workarounds |
+| `learnings` | Architectural choices, user-stated decisions, post-mortem insights |
 
-### CLI Fallback:
-```bash
-npx flo memory store --namespace patterns --key "brief-descriptive-key" --value "1-2 sentence insight"
-```
+**Store:** Patterns that worked, gotchas you hit, workarounds for limitations.
+**Skip:** Generic summaries of retrieved guidance, restated rules, trivial file-location notes.
 
-**Store:** Solutions to tricky bugs, patterns that worked, gotchas, workarounds
-**Skip:** Summaries of retrieved guidance, general rules, file locations
+See `.claude/guidance/moflo-agent-rules.md` § Storing Discoveries for the full MCP/CLI invocation patterns.
 
 ---
 
-## 5. When Complete
+## Step 5: When Complete
+
+1. Report findings to the coordinator
+2. Confirm any discoveries are stored (Step 4)
+3. The coordinator will mark your task `completed` via `TaskUpdate`
 
-1. Report findings to coordinator
-2. Store learnings if you discovered something new
-3. Coordinator will mark your task as completed
+Do not mark your own task completed — that's the coordinator's responsibility.
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-task-icons.md` — Mandatory ICON + [Role] format for every `TaskCreate` and `Agent` description spawned by a coordinator
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarm coordinators cooperate when subagents are spawned in batches
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — The memory-search-first rule this protocol enforces, with namespace-selection guidance
-- `.claude/guidance/shipped/moflo-memorydb-maintenance.md` — How the memory namespaces are populated and refreshed; required reading when search returns no results
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Full CLI/MCP reference including the spell gates that block subagent spawn before memory is searched
+- `.claude/guidance/moflo-agent-rules.md` — Universal rules every agent (coordinator OR subagent) shares
+- `.claude/guidance/moflo-task-icons.md` — Mandatory ICON + [Role] format for every `TaskCreate` and `Agent` description
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — How task lists and swarm coordinators cooperate when subagents are spawned in batches
+- `.claude/guidance/moflo-memory-strategy.md` — Memory architecture, namespaces, search patterns
+- `.claude/guidance/moflo-memorydb-maintenance.md` — How memory namespaces are populated and refreshed
+- `.claude/guidance/moflo-core-guidance.md` — Full CLI/MCP reference including the spell gates that block subagent spawn before memory is searched

package/.claude/guidance/shipped/moflo-task-icons.md

@@ -66,7 +66,7 @@ The spinner is the primary visual feedback during agent execution. Without icons
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-subagents.md` — Subagent protocol; `TaskCreate`/`Agent` icon rule is enforced as part of the spawning checklist
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarms cooperate; icons distinguish swarm-spawned vs single-agent work
-- `.claude/guidance/shipped/moflo-user-facing-language.md` — Companion UX rule for any text shown to end users
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Spell Gate that enforces icon format on `TaskCreate`
+- `.claude/guidance/moflo-subagents.md` — Subagent protocol; `TaskCreate`/`Agent` icon rule is enforced as part of the spawning checklist
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — How task lists and swarms cooperate; icons distinguish swarm-spawned vs single-agent work
+- `.claude/guidance/moflo-user-facing-language.md` — Companion UX rule for any text shown to end users
+- `.claude/guidance/moflo-core-guidance.md` — Spell Gate that enforces icon format on `TaskCreate`

package/.claude/guidance/shipped/moflo-user-facing-language.md

@@ -37,6 +37,6 @@
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-task-icons.md` — Companion UX rule: spinner text must use ICON + [Role] so non-technical users can identify the working agent
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Permission disclosure output where this language rule has the largest user-visible surface
-- `.claude/guidance/shipped/moflo-error-handling.md` — Sibling rule for what error messages must contain; this doc governs how those messages are phrased
+- `.claude/guidance/moflo-task-icons.md` — Companion UX rule: spinner text must use ICON + [Role] so non-technical users can identify the working agent
+- `.claude/guidance/moflo-spell-sandboxing.md` — Permission disclosure output where this language rule has the largest user-visible surface
+- `.claude/guidance/moflo-error-handling.md` — Sibling rule for what error messages must contain; this doc governs how those messages are phrased

package/.claude/guidance/shipped/moflo-verbose-command-filtering.md

@@ -35,11 +35,11 @@ npm run build -- --verbose 2>&1 | grep -E "error TS|Failed|Cannot find"
 
 ## Why It Matters
 
-Case study: issue #903 burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
+A representative incident burned ~25K tokens across 5 tee-then-grep round-trips where a single grep-at-source would have surfaced the same signal once. Filtering at source is not an optimization — it is the default shape for any verbose command whose full output you do not need in your context.
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
-- `.claude/guidance/shipped/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline
+- `.claude/guidance/moflo-core-guidance.md` — Hub for moflo's CLI/MCP surface and runtime conventions
+- `.claude/guidance/moflo-memory-strategy.md` — Companion rules on RAG indexing and context discipline

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -184,8 +184,7 @@ Global registration is useful for ad-hoc projects where you don't want to commit
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub: getting started, anti-drift defaults, troubleshooting
-- `.claude/guidance/shipped/moflo-cli-reference.md` — Commands, agents, hooks, hive-mind, ruvector — the surfaces this config gates
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — What `sandbox:` actually does at the bash-step boundary, with capability/permission interaction
-- `.claude/guidance/shipped/moflo-session-start.md` — Where these config fields are read and applied during session start
-- `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/settings.json` (the hook wiring; complementary to `moflo.yaml` toggles)
+- `.claude/guidance/moflo-core-guidance.md` — Hub: getting started, anti-drift defaults, troubleshooting
+- `.claude/guidance/moflo-cli-reference.md` — Commands, agents, hooks, hive-mind, ruvector — the surfaces this config gates
+- `.claude/guidance/moflo-spell-sandboxing.md` — What `sandbox:` actually does at the bash-step boundary, with capability/permission interaction
+- `.claude/guidance/moflo-settings-injection.md` — What moflo writes into `.claude/settings.json` (the hook wiring; complementary to `moflo.yaml` toggles)

package/.claude/helpers/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -83,6 +83,78 @@ var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state
 var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
+
+// Namespace classification (#931). The hint used to be emitted on every prompt
+// by prompt-hook.mjs which cost ~40 tokens × every prompt × every consumer.
+// Now we classify here, store on workflow-state, and let check-before-agent
+// emit it once when Claude is actually about to spawn an agent.
+//
+// SYNC: these regexes + classifyNamespaceHint + applyPromptStateReset are
+// duplicated verbatim in src/cli/init/helpers-generator.ts (the embedded
+// gate.cjs fallback used by `flo init` when source helpers can't be located).
+// Any edit to either copy MUST be applied to both — there is no shared module
+// because helpers-generator emits a self-contained string template.
+var NS_LEARNINGS_RE = /\b(remember|recall|insight|lesson learned|gotcha|post.?mortem)\b|we (decid|agree|chose|said)/;
+var NS_TEST_RE = /\b(test|spec|coverage|tested|test case|test cases|tests for|spec for)\b/;
+var NS_EXPLICIT = [
+  { pattern: /\b(pattern|convention|best practice|style|coding rule)\b/, ns: 'patterns', label: 'code patterns and conventions' },
+  { pattern: /\b(code.?map|file structure|project structure|directory)\b/, ns: 'code-map', label: 'codebase navigation' },
+];
+var NS_PATTERN_RES = [/\b(template|example|similar to|how do we|how should)\b/];
+var NS_DOMAIN_RES = [
+  /\b(guidance|guide|docs|documentation|rules|how-to)\b/,
+  /\b(architecture|design|domain|tenant|migrat|schema|deploy)/,
+  /\b(rule|requirement|constraint|compliance)\b/,
+];
+var NS_NAV_RES = [
+  /\b(find|where|which file|look up|locate|endpoint|route|url|path)\b/,
+  /\b(class|function|method|component|service|entity|module)\b/,
+];
+
+function classifyNamespaceHint(promptText) {
+  var lower = (promptText || '').toLowerCase();
+  if (NS_TEST_RE.test(lower)) return 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
+  if (NS_LEARNINGS_RE.test(lower)) return 'Memory namespace hint: use "learnings" for user-directed decisions and distilled insights.';
+  for (var i = 0; i < NS_EXPLICIT.length; i++) {
+    if (NS_EXPLICIT[i].pattern.test(lower)) return 'Memory namespace hint: use "' + NS_EXPLICIT[i].ns + '" for ' + NS_EXPLICIT[i].label + '.';
+  }
+  for (var j = 0; j < NS_DOMAIN_RES.length; j++) {
+    if (NS_DOMAIN_RES[j].test(lower)) return 'Memory namespace hint: search "guidance" and "learnings" for domain rules and project decisions.';
+  }
+  for (var k = 0; k < NS_PATTERN_RES.length; k++) {
+    if (NS_PATTERN_RES[k].test(lower)) return 'Memory namespace hint: use "patterns" for code patterns and conventions.';
+  }
+  for (var m = 0; m < NS_NAV_RES.length; m++) {
+    if (NS_NAV_RES[m].test(lower)) return 'Memory namespace hint: use "code-map" for codebase navigation.';
+  }
+  return '';
+}
+
+// Apply per-prompt state reset shared by `prompt-reminder` (full) and
+// `prompt-state-reset` (defensive safety-net, no emission). Idempotent — both
+// UserPromptSubmit hooks can run it without compounding any field. Caller
+// owns interactionCount and the user-visible REMINDER/Context emissions, so
+// this helper stays silent.
+function applyPromptStateReset(state, promptText) {
+  state.memorySearched = false;
+  // Wipe per-actor memory tracking too — a new user prompt is a fresh window
+  // for both parent AND any subagents the parent may spawn during this turn.
+  state.memorySearchedBy = {};
+  // learningsStored is session-scoped — once stored, it stays true until session reset.
+  // Resetting per-prompt caused false blocks when PR creation was on a later prompt.
+  var DIRECTIVE_MAX_LEN = 20;
+  var escaped = /^@@\s*/.test(promptText || '');
+  state.memoryRequired = !escaped && (promptText || '').length >= 4 && (TASK_RE.test(promptText || '') || (promptText || '').length > DIRECTIVE_MAX_LEN);
+  // Stash namespace hint for check-before-agent to emit when Claude actually
+  // spawns an Agent (#931). Empty string when nothing matched — overwriting
+  // any stale value from the previous prompt.
+  state.lastNamespaceHint = classifyNamespaceHint(promptText);
+  // Per-actor emission tracking — each subagent's session gets the hint at
+  // most once per prompt, but a fresh prompt resets every actor's window so
+  // subsequent agents (parent + subagents that spawn their own agents) all
+  // see the new classification on their first check-before-agent.
+  state.lastNamespaceHintEmittedBy = {};
+}
 // Match npm/yarn/pnpm/bun test, npx vitest|jest|..., bare runners at command-start only,
 // and language-native test commands. The bare-runner arm is anchored so that
 // `npm install jest`, `grep -r vitest src/`, and similar don't false-positive.
@@ -203,6 +275,11 @@ switch (command) {
     // Advisory only — agent spawning is never blocked.
     // Memory-first enforcement happens at the scan/read gate layer.
     // SubagentStart hook injects guidance directive into subagent context.
+    //
+    // #931 — TaskCreate REMINDER and the namespace hint moved here from
+    // prompt-reminder. They only matter when Claude is actually about to spawn
+    // an Agent; emitting per-prompt cost ~90 tokens × every prompt × every
+    // consumer.
     var s = readState();
     if (config.task_create_first && !s.tasksCreated) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
@@ -210,6 +287,24 @@ switch (command) {
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
       process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
     }
+    if (s.lastNamespaceHint) {
+      // Per-actor single-shot. Each session_id gets the hint at most once per
+      // prompt, but the hint itself stays available for other actors (e.g.
+      // a subagent that spawns its own agent has its own session_id and is
+      // entitled to a fresh emission). Falls back to a `_legacy_` bucket when
+      // Claude Code didn't forward a session_id (older host or direct CLI
+      // invocation), preserving the old "emit once globally" behavior. The
+      // map is wiped by applyPromptStateReset on every new prompt.
+      var sid = process.env.HOOK_SESSION_ID || '';
+      var emittedBy = s.lastNamespaceHintEmittedBy || {};
+      var bucket = sid || '_legacy_';
+      if (!emittedBy[bucket]) {
+        process.stdout.write(s.lastNamespaceHint + '\n');
+        emittedBy[bucket] = true;
+        s.lastNamespaceHintEmittedBy = emittedBy;
+        writeState(s);
+      }
+    }
     break;
   }
   case 'check-before-scan': {
@@ -277,7 +372,8 @@ switch (command) {
     break;
   }
   case 'record-skill-run': {
-    if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
+    var skName = (process.env.TOOL_INPUT_skill || '');
+    if (skName === 'simplify' || skName === 'flo-simplify') {
       var s = readState();
       var changed = false;
       if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
@@ -346,7 +442,7 @@ switch (command) {
     }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
-    if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');
+    if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify has not run since the last code edit');
     if (config.learnings_gate && !s.learningsStored) missing.push('learnings have not been stored (call mcp__moflo__memory_store)');
     if (missing.length === 0) break;
     process.stderr.write('BLOCKED: gh pr create requires the following before opening a PR:\n');
@@ -371,20 +467,16 @@ switch (command) {
     break;
   }
   case 'prompt-reminder': {
+    // Full per-prompt reset. Wired as the first UserPromptSubmit hook (via
+    // prompt-hook.mjs). Owns interactionCount + Context warnings; the
+    // TaskCreate REMINDER and namespace hint moved to check-before-agent
+    // (#931) so they only fire when Claude is actually about to spawn an
+    // Agent.
     var s = readState();
-    s.memorySearched = false;
-    // Wipe per-actor memory tracking too — a new user prompt is a fresh window
-    // for both parent AND any subagents the parent may spawn during this turn.
-    s.memorySearchedBy = {};
-    // learningsStored is session-scoped — once stored, it stays true until session reset.
-    // Resetting per-prompt caused false blocks when PR creation was on a later prompt.
     var prompt = process.env.CLAUDE_USER_PROMPT || '';
-    var DIRECTIVE_MAX_LEN = 20;
-    var escaped = /^@@\s*/.test(prompt);
-    s.memoryRequired = !escaped && prompt.length >= 4 && (TASK_RE.test(prompt) || prompt.length > DIRECTIVE_MAX_LEN);
+    applyPromptStateReset(s, prompt);
     s.interactionCount = (s.interactionCount || 0) + 1;
     writeState(s);
-    if (!s.tasksCreated) console.log('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.');
     if (config.context_tracking) {
       var ic = s.interactionCount;
       if (ic > 30) console.log('Context: CRITICAL. Commit, store learnings, suggest new session.');
@@ -393,12 +485,30 @@ switch (command) {
     }
     break;
   }
+  case 'prompt-state-reset': {
+    // Defensive safety-net hook (#931 dedupe). Wired as the second
+    // UserPromptSubmit hook so an exception in prompt-hook.mjs doesn't skip
+    // the per-prompt state reset. Idempotent — applyPromptStateReset only
+    // sets fields to derived values, and we deliberately do NOT increment
+    // interactionCount or emit anything (that's prompt-reminder's job).
+    //
+    // Skip the disk write on the normal path: prompt-reminder runs first and
+    // already wrote the byte-identical post-reset state. Only writeState when
+    // the reset actually changed something (i.e., prompt-reminder was skipped
+    // because prompt-hook.mjs threw before invoking it).
+    var s = readState();
+    var prompt = process.env.CLAUDE_USER_PROMPT || '';
+    var before = JSON.stringify(s);
+    applyPromptStateReset(s, prompt);
+    if (JSON.stringify(s) !== before) writeState(s);
+    break;
+  }
   case 'compact-guidance': {
     console.log('Pre-Compact: Check CLAUDE.md for rules. Use memory search to recover context after compact.');
     break;
   }
   case 'session-reset': {
-    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null });
+    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} });
     break;
   }
   default: