moflo 4.12.4 → 4.12.6

package/.claude/guidance/shipped/moflo-agent-rules.md

@@ -176,6 +176,7 @@ npx flo memory store --namespace patterns --key "brief-descriptive-key" --value
 
 ## See Also
 
+- `.claude/guidance/moflo-inline-fixes.md` — Fix-vs-file rule for defects found mid-PR; the default is to fix them in the PR you are already in
 - `.claude/guidance/moflo-subagents.md` — Spawn protocol that consumes these universal rules
 - `.claude/guidance/moflo-task-icons.md` — Full ICON + [Role] format and icon map
 - `.claude/guidance/moflo-claude-swarm-cohesion.md` — How `TaskCreate` and swarm coordination layer on top of these rules

package/.claude/guidance/shipped/moflo-claude-swarm-cohesion.md

@@ -119,7 +119,7 @@ TaskList()  // Shows what's now unblocked
 TaskUpdate({ taskId: "2", status: "in_progress" })  // Next agent starts
 ```
 
-Close every task you open. moflo's PR gate reads the session transcript on `gh pr create` and prints `N tasks created this session, M still open` (#1374) — an unclosed list reports as unfinished work on the PR. Mark tasks that no longer apply `status: "deleted"`; that closes the loop exactly like `completed`.
+Close every task you open. moflo's PR gate reads the session transcript on `gh pr create` and prints `N tasks created this session, M still open` — an unclosed list reports as unfinished work on the PR. Mark tasks that no longer apply `status: "deleted"`; that closes the loop exactly like `completed`.
 
 ---
 

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

@@ -61,7 +61,7 @@ npx flo daemon start
 
 ## Available Agents
 
-The shipped agent roster — each is invoked via the `Agent` tool with `subagent_type: <name>`. The canonical handle is the `name:` frontmatter inside `.claude/agents/**/*.md` (filename may differ from agent name). Aspirational agents that never shipped were retired in #932 — `retired-files.json` enforces auto-prune on consumer upgrade.
+The shipped agent roster — each is invoked via the `Agent` tool with `subagent_type: <name>`. The canonical handle is the `name:` frontmatter inside `.claude/agents/**/*.md` (filename may differ from agent name). Aspirational agents that never shipped were retired — `retired-files.json` enforces auto-prune on consumer upgrade.
 
 ### Core Development
 `coder`, `reviewer`, `tester`, `planner`, `researcher`, `analyst`
@@ -119,10 +119,10 @@ The orchestrator is the calling Claude, not a named agent. Pick specialists from
 ### Background Workers
 
 The daemon ships seven workers — two scheduled by default (both local, no
-model calls) plus five manual-trigger only. The pre-#970 `audit`, `predict`,
+model calls) plus five manual-trigger only. The earlier `audit`, `predict`,
 and `document` workers were removed because they ran without a surfacing
-layer for findings. The `optimize` and `testgaps` workers were removed in
-#1258 — they were the only default-ON workers that spawned billed
+layer for findings. The `optimize` and `testgaps` workers were also
+removed — they were the only default-ON workers that spawned billed
 `claude --print` agents, on a 15/20-min timer with no change-detection, and
 their reports were never surfaced. Their capability now lives in the ad-hoc
 `/quicken` (perf) and `/ward` (test-gap) skills, which scope to the diff and

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

@@ -16,7 +16,7 @@
 | Claude Desktop (the macOS/Windows app) | **Out of scope — never** | None — moflo neither reads nor writes Claude Desktop config |
 | Other MCP-capable clients (Cline, Continue, etc.) | Unsupported, may incidentally work | None — bug reports require Claude Code reproduction |
 
-**Never** introduce a code path, search list, fixture, or doc that reads from or writes to `~/.claude/claude_desktop_config.json`, `~/Library/Application Support/Claude/`, or `%APPDATA%/Claude/`. Those are Claude **Desktop** paths. Including them in moflo's MCP-config search list caused issue #1126: a parseable Claude Desktop preferences file outranked a malformed project `.mcp.json`, masking the real failure and routing the auto-fixer down a no-op branch.
+**Never** introduce a code path, search list, fixture, or doc that reads from or writes to `~/.claude/claude_desktop_config.json`, `~/Library/Application Support/Claude/`, or `%APPDATA%/Claude/`. Those are Claude **Desktop** paths. Including them in moflo's MCP-config search list has already caused one regression: a parseable Claude Desktop preferences file outranked a malformed project `.mcp.json`, masking the real failure and routing the auto-fixer down a no-op branch.
 
 The one ambiguous-looking path is Claude Code's user-level config at `~/.claude.json` (where `claude mcp add` writes). MoFlo doesn't author or rewrite that file either; the project-local `.mcp.json` written by `flo init` is the canonical surface moflo owns end-to-end.
 
@@ -145,7 +145,7 @@ For the full `moflo.yaml` schema, gate toggles, model routing, and sandbox confi
 | Every 5+ file changes | `map` worker | Update codebase map (local, automatic) |
 | Complex debugging | `deepdive` worker | Deep code analysis (manual trigger) |
 
-**Performance and test-gap analysis are ad-hoc skills, not background workers.** The old always-on `optimize`/`testgaps` daemon workers were removed in #1258 — they were billed `claude --print` loops with no change-detection whose reports were never surfaced. Run `/quicken` and `/ward` when you want them; they scope to the diff and report in the conversation.
+**Performance and test-gap analysis are ad-hoc skills, not background workers.** The old always-on `optimize`/`testgaps` daemon workers were removed — they were billed `claude --print` loops with no change-detection whose reports were never surfaced. Run `/quicken` and `/ward` when you want them; they scope to the diff and report in the conversation.
 
 ### Worker Report Location
 
@@ -184,7 +184,7 @@ Checks: Node version (20+), Git, config validity, daemon status, memory database
 
 ## Monorepo Layout
 
-**Purpose:** prevent the most common moflo misconfig — daemon islands in monorepos (#1174).
+**Purpose:** prevent the most common moflo misconfig — daemon islands in monorepos.
 
 | Rule | Why |
 |------|-----|
@@ -209,7 +209,7 @@ The resolver (`findProjectRoot`) prefers the topmost ancestor with `.moflo/moflo
 | Embeddings fail offline / air-gapped | `fastembed` model cache missing | Pre-populate `~/.cache/fastembed` or set `FASTEMBED_CACHE` (see `docs/modules/embeddings.md`) |
 | `flo` command not found | Not in PATH | Use `npx flo` or `node node_modules/moflo/bin/index-guidance.mjs` |
 | Bundled guidance not indexed | Running inside the moflo repo | Bundled guidance only indexes when installed as a dependency in a different project |
-| `mcp__moflo__*` tools missing in monorepo session | Nested `.moflo/` directories spawned separate daemons (#1174) | Run `flo doctor -c nested-moflo`; if any are found, `flo doctor --fix -c nested-moflo` archives them. Restart Claude Code to reconnect. |
+| `mcp__moflo__*` tools missing in monorepo session | Nested `.moflo/` directories spawned separate daemons | Run `flo doctor -c nested-moflo`; if any are found, `flo doctor --fix -c nested-moflo` archives them. Restart Claude Code to reconnect. |
 
 See `.claude/guidance/moflo-memory-strategy.md` for memory-specific troubleshooting and `.claude/guidance/moflo-spell-troubleshooting.md` for spell sandbox/network failures.
 

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

@@ -145,6 +145,27 @@ Use relative names (not absolute paths) so the links work across project context
 
 ---
 
+## 10. Never Cite Issue or PR Numbers
+
+**Write the rule, not where it came from.** Strip every `(#NNNN)`, `issue #NNNN`, `Epic #NNNN`, and `per PR #NNNN` from guidance. A reader who hits a bare issue number cannot resolve it without leaving the document, and in guidance that ships between projects the number points at the *reader's* issue tracker, not the author's — so it is worse than useless there. Provenance belongs in `git log` and `git blame`, which is where it stays accurate.
+
+The cost is not just confusion. Guidance is loaded, chunked, and RAG-retrieved on nearly every task, so an unresolvable citation is a permanent context tax that dilutes the rule it is attached to.
+
+Below, `#NNNN` stands in for a real issue number — written that way so these examples do not themselves violate the rule.
+
+| Instead of | Write |
+|---|---|
+| `verify_before_done` is on by default (#NNNN) | `verify_before_done` is on by default |
+| Never run `flo init` in a sub-workspace (issue #NNNN) | Never run `flo init` in a sub-workspace |
+| The `optimize` worker was removed in #NNNN — it was a billed loop | The `optimize` worker was removed — it was a billed loop |
+| `### Case Study: #NNNN Hive-Mind Shutdown` | `### Case Study: Hive-Mind Shutdown Flake` |
+
+**When the number is load-bearing, relabel — don't just delete.** A case-study heading or a table keyed by `#NNNN layer 1` / `#NNNN attempt 4` uses the numbers to carry a *sequence*. Replace them with descriptive ordinals (`Attempt 1`, `Attempt 2`) so the progression survives.
+
+**This applies to every reader-facing surface, not just `.md` guidance** — skills, agent definitions, slash commands, and any template your tooling writes into a project (a generated `CLAUDE.md` block, a scaffolded config file). Source-code comments in your own repo are exempt: they are read where the number resolves.
+
+---
+
 ## See Also
 
 - `.claude/guidance/moflo-memory-strategy.md` — Companion rules on namespaces, RAG indexing, and search patterns the data feeds

package/.claude/guidance/shipped/moflo-inline-fixes.md

@@ -0,0 +1,98 @@
+# Inline Fixes — Resolve Small Defects in the PR You Are Already In
+
+**Purpose:** Decide between "fix it here" and "file a follow-up" when a defect surfaces while you are working on something else. The default is **fix it here**. Opening a separate ticket for a small problem spends a full issue → branch → research → tests → review → PR → merge cycle on a change that a reviewer confirms in thirty seconds, and it is the single most common way agent work becomes slower than doing it by hand.
+
+---
+
+## 1. The Default Is Fix, Not File
+
+**Fix a small defect in the PR you are already in.** Do not open a ticket, do not branch a new cycle, do not defer it to "follow-up".
+
+Filing is the exception and must be earned. Before you file, name which threshold in the table below the defect crosses. If you cannot name one, fix it.
+
+**Never file a ticket to record work you could have finished in the time it took to write the ticket.** A ticket that says "rename this variable" costs more to triage than the rename costs to do.
+
+---
+
+## 2. Trivial vs. Non-Trivial Decision Table
+
+The split is about review burden and blast radius, not line count alone.
+
+| Signal | Fix inline | File separately |
+|--------|-----------|-----------------|
+| Net production LOC | ≤ ~10 | > ~10 or spans multiple subsystems |
+| New tests required | 0–1 small assertion | dedicated test file or several new tests |
+| Public API surface | unchanged | adds, removes, or renames an export |
+| Behaviour change | matches intent already documented | could surprise a consumer |
+| Reviewer friction | confirmable in under 30 seconds | needs context this PR does not carry |
+| Relationship to the main fix | same file or same subsystem | different subsystem entirely |
+| Risk if shipped wrong | reverts cleanly in one commit | needs a coordinated migration |
+
+**Any single row in the right column flips it to non-trivial.** A three-line fix in an unrelated subsystem is non-trivial, because the reviewer of your PR has no context for it.
+
+---
+
+## 3. Defects Your Own Work Surfaces Are Never Follow-Ups
+
+A defect that your change **caused, unmasked, or invalidated** is part of the change. It is not a discovery to be logged.
+
+| Situation | Action |
+|-----------|--------|
+| A test you just made red | Fix it now, in this PR |
+| A lint, type, or build error your edit introduced | Fix it now |
+| A stale bound, count, or snapshot your change invalidated | Update it now |
+| A test that pinned the exact bug you are fixing | Update the test in the same commit |
+| A reviewer comment on this PR | Address it in this PR |
+| A neighbouring function with the same defect you just fixed | Fix it here if it clears the table above |
+
+Treating any of these as a separate ticket ships a knowingly broken tree and asks a human to re-triage work that was already in your hands.
+
+---
+
+## 4. Batch Fixes; Do Not Serialise CI Rounds
+
+**Group related fixes into one push.** Every push burns a full CI round, and reviewers re-read the diff each time.
+
+- Fix everything you have found, then run the suite once, then push once.
+- Do not push a one-line fix, wait for CI, then push the next one-line fix.
+- When several small defects share a root cause, fix the cause and say so, rather than patching each symptom in its own commit.
+
+Serialised single-fix rounds are slower than one careful pass, and they make the change history harder to read for no gain.
+
+---
+
+## 5. How to Surface Inline Fixes
+
+Bundling is not hiding. Make every drive-by visible:
+
+- **In the commit body** — one bullet under `Also fixed:`.
+- **In the PR description** — the same bullets under a `## Drive-by fixes` heading.
+- **Do not retitle the PR.** The main subject stays the original fix; drive-bys are footnotes.
+
+```
+fix(cli): drain stdout/stderr before exit to avoid a Windows async-pipe race
+
+[main fix description]
+
+Also fixed:
+- Removed a redundant `stream.destroyed` check already covered by `!stream.writable`.
+- Corrected the module-count lower bound this change invalidated.
+```
+
+---
+
+## 6. When an Inline Fix Grows
+
+If a fix expands past the trivial threshold mid-flight — the "one-line check" turns out to need three new tests and a migration — **stop and back out**. File it, and stay focused on the original PR.
+
+The decision point is the moment you realise the fix is not trivial. Catching it there keeps the discipline without bloating the PR. An over-scoped PR is expensive; a deferred trivial fix is more expensive still.
+
+**When you do file, finish the rest first.** Deliver every part of the current work that is not blocked, then state plainly what you left out and why. Never stop the whole task to file a ticket.
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-agent-rules.md` — Git, branch, and PR conventions these fixes land through
+- `.claude/guidance/moflo-root-cause-discipline.md` — Fixing the cause rather than the symptom, which is what makes a batch of small fixes collapse into one
+- `.claude/guidance/moflo-guidance-rules.md` — Universal writing rules this doc follows

package/.claude/guidance/shipped/moflo-root-cause-discipline.md

@@ -52,7 +52,7 @@ When fix N didn't work, do these in order — not in parallel, not skipping step
 1. **Read every prior fix on this surface in full.** Not the commit message — the code. Note what each one was trying to prevent and what it actually does.
 2. **Reproduce the failure deterministically** before touching code. If you can't reproduce it, you don't understand it.
 3. **Trace the data flow.** Where does the bad state originate? What writes it? What reads it? What invariant got violated?
-4. **Question the test, not just the code.** What invariant does the failing test actually encode? Does that invariant match the runtime contract, or is the test stricter? A test stricter than the contract will produce flakes that look like bugs but aren't. (See #1017 case study.)
+4. **Question the test, not just the code.** What invariant does the failing test actually encode? Does that invariant match the runtime contract, or is the test stricter? A test stricter than the contract will produce flakes that look like bugs but aren't. (See the hive-mind shutdown case study below.)
 5. **Identify the structural cause** — the place where the bug becomes possible, not the place where it becomes visible.
 6. **Now consider fixes.** The cheapest fix at the structural cause beats the cleverest fix at the symptom every time. If the cause is "test asserts X, runtime contract is Y, X is stricter," the fix is in the test.
 
@@ -105,9 +105,9 @@ When you find that the test is the actual problem: change the test, document why
 
 **Smell test:** read the test setup as a description of production behavior. If steps appear that production code does not perform, the test is mocking around a real bug.
 
-### Case Study: #1053 Memory Traversal
+### Case Study: Memory Traversal Healer Probe
 
-> "Healer: probeMemoryGetNeighbors() runs first in checkMemoryAccessFunctional so the bridge instantiates after the seed lands (sql.js whole-DB writeback clobbers external file writes once the in-memory snapshot warms)." — PR #1053 commit
+> "Healer: probeMemoryGetNeighbors() runs first in checkMemoryAccessFunctional so the bridge instantiates after the seed lands (sql.js whole-DB writeback clobbers external file writes once the in-memory snapshot warms)." — the fix commit
 
 Diagnosis correct; fix wrong. The clobber stayed in production. `moflo@4.9.37` shipped two regressions to every consumer (migration-induced embedding loss + `memory_store` silent drop) because the suite was engineered around the failure it had just detected.
 
@@ -120,18 +120,18 @@ Diagnosis correct; fix wrong. The clobber stayed in production. `moflo@4.9.37` s
 
 ---
 
-## Concrete Example: #1017 Hive-Mind Shutdown
+## Concrete Example: Hive-Mind Shutdown Flake
 
 This is the canonical case study for this guidance — and it has a second-order lesson that makes it even more useful.
 
 | Attempt | Approach | Outcome |
 |---------|----------|---------|
-| #1017 first try | Loop list+delete in `clearNamespace` | Race window remained — broadcasts landed mid-loop |
-| #1024 layer 1 | Detach adapter BEFORE `clearNamespace` (after `terminateAgent`) | Race narrowed but not eliminated |
-| #1024 layer 2 | Add `purgeHiveNamespacesDirect` raw sql.js DELETE | Looked bulletproof; actually clobber-prone vs daemon's stale snapshot (#981 single-writer) |
-| #1024 declared green | All 6 CI checks pass once | Same flake reappeared on next PR's CI |
-| #1027 attempt 4 | Move `adapter.detach()` BEFORE `terminateAgent`; delete `purgeHiveNamespacesDirect` | Code simplified by -73 LOC. **Same flake on macos-latest CI.** |
-| #1027 — actual fix | Run launcher a SECOND time after doctor in the populated harness | Test passes. Race is intrinsic to multi-process sql.js + daemon kill timing; the harness assertion was over-strict. |
+| 1 | Loop list+delete in `clearNamespace` | Race window remained — broadcasts landed mid-loop |
+| 2 | Detach adapter BEFORE `clearNamespace` (after `terminateAgent`) | Race narrowed but not eliminated |
+| 3 | Add `purgeHiveNamespacesDirect` raw sql.js DELETE | Looked bulletproof; actually clobber-prone vs daemon's stale snapshot — it violates the single-writer contract |
+| — declared green | All 6 CI checks pass once | Same flake reappeared on next PR's CI |
+| 4 | Move `adapter.detach()` BEFORE `terminateAgent`; delete `purgeHiveNamespacesDirect` | Code simplified by -73 LOC. **Same flake on macos-latest CI.** |
+| 5 — actual fix | Run launcher a SECOND time after doctor in the populated harness | Test passes. Race is intrinsic to multi-process sql.js + daemon kill timing; the harness assertion was over-strict. |
 
 The first three attempts kept asking "how do we delete this row harder?" The fourth attempt was a structural simplification that was correct on its own merits (-73 LOC, removed dead code, simpler shutdown ordering) but **did not fix the flake**.
 

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

@@ -6,7 +6,7 @@
 
 ## When to Use `-sd` vs `-v` vs Neither
 
-Two independent modifiers on `/flo`, orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`. The **spec/plan ceremony (`-sd`) is opt-in**; **verify-before-done (`-v`) runs by default** (#1294) — separable from SDD by design.
+Two independent modifiers on `/flo`, orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`. The **spec/plan ceremony (`-sd`) is opt-in**; **verify-before-done (`-v`) runs by default** — separable from SDD by design.
 
 | Situation | Flag | Effect |
 |-----------|------|--------|
@@ -44,7 +44,7 @@ A spec is pre-implementation intent for **one** unit of work, not a project rule
 
 Existing spec rows are removed by the `purge-spec-chunks` migration on the next session start.
 
-**Where specs live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init`. To make specs reviewable in the PR, point `sdd.specs_dir` at a **tracked** path and commit them:
+**Where specs live is configurable (`sdd.specs_dir`).** The default `.moflo/specs` is **gitignored** by `flo init`. To make specs reviewable in the PR, point `sdd.specs_dir` at a **tracked** path and commit them:
 
 | `sdd.specs_dir` | Committed? | Use when |
 |-----------------|------------|----------|
@@ -78,7 +78,7 @@ The two review checkpoints are the point: **a spec must be reviewed before its p
 
 When enforced, `gh pr create` is blocked until the change has been verified end-to-end since the last code edit.
 
-- **On by default (#1294).** Enforced for every `/flo` run; disable per-project with `gates.verify_before_done: false` or per-run with `--no-verify`. On upgrade, consumers with no `verify_before_done` key start enforcing; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
+- **On by default.** Enforced for every `/flo` run; disable per-project with `gates.verify_before_done: false` or per-run with `--no-verify`. On upgrade, consumers with no `verify_before_done` key start enforcing; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
 - **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: verify, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
 - **A source edit invalidates a prior verification** — re-run `/verify` after editing. `/ward` and `/quicken` are targeted audits, not the completion gate.
 
@@ -86,13 +86,13 @@ When enforced, `gh pr create` is blocked until the change has been verified end-
 
 ## SDD & Verify moflo.yaml Defaults
 
-`sdd.default` is off (opt-in); `verify_before_done` is **on** (#1294). Override per run with the flags.
+`sdd.default` is off (opt-in); `verify_before_done` is **on**. Override per run with the flags.
 
 ```yaml
 sdd:
   default: false              # true → every /flo run uses the SDD cycle unless --no-sdd
 gates:
-  verify_before_done: true    # on by default (#1294); false → skip /verify unless -v. Per-run: --no-verify
+  verify_before_done: true    # on by default; false → skip /verify unless -v. Per-run: --no-verify
 ```
 
 Check wiring status with `/healer` (or `/eldar`) — the `SDD + Verify Wiring` check reports whether the gate cases and hooks are present and which toggles are on.

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

@@ -124,7 +124,7 @@ steps:
 
 ### agent — NOT EXECUTABLE
 
-**Do not use this step type.** It has never spawned a subagent — moflo has no agent spawner in the spell runner. It is still registered so existing spell YAML keeps parsing, but casting it now always fails with an explanatory error (#1334). Earlier versions returned `success: true` and a `result` string for work that never happened.
+**Do not use this step type.** It has never spawned a subagent — moflo has no agent spawner in the spell runner. It is still registered so existing spell YAML keeps parsing, but casting it now always fails with an explanatory error. Earlier versions returned `success: true` and a `result` string for work that never happened.
 
 **To run a Claude subagent from a spell, use a `bash` step:**
 

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

@@ -57,13 +57,13 @@ session_continuity:
 
 # Memory backend
 memory:
-  backend: node-sqlite            # node-sqlite (default) | rvf (pure-TS fallback) | json (last resort). Passed to createDatabase() as the preferred provider (#1144).
+  backend: node-sqlite            # node-sqlite (default) | rvf (pure-TS fallback) | json (last resort). Passed to createDatabase() as the preferred provider.
   embedding_model: Xenova/all-MiniLM-L6-v2   # 384-dim neural embeddings
   namespace: default              # Default namespace for memory operations
-  # worktree_sharing: false                            # opt-OUT (#1231): automatic durable-learning sharing across git worktrees is ON by default (derived at <git-common-dir>/moflo/durable.db, active only when worktrees exist; a single checkout is untouched). Set false to disable.
-  # durable_path: ~/.moflo-shared/team-learnings.db   # opt-in (#1232): OVERRIDE the auto worktree store — a custom durable-only path for learnings/knowledge, or to converge separate clones. Point at a DEDICATED store, never a full moflo.db. Env override: MOFLO_DURABLE_PATH.
-  # team_artifact: .moflo/shared/learnings.jsonl       # opt-in (#1234): git-tracked JSONL the team commits; session-start import-merges it. Env override: MOFLO_TEAM_ARTIFACT. See moflo-cross-install-memory-sharing.md.
-  # hydrate_from: /abs/path/to/moflo-snapshot.db       # opt-in (#1244): whole-DB snapshot to seed a fresh/empty workspace on session-start (skips the cold reindex). No-op once the local DB has content. Take one with "flo memory backup --to <path>". Env override: MOFLO_HYDRATE_FROM.
+  # worktree_sharing: false                            # opt-OUT: automatic durable-learning sharing across git worktrees is ON by default (derived at <git-common-dir>/moflo/durable.db, active only when worktrees exist; a single checkout is untouched). Set false to disable.
+  # durable_path: ~/.moflo-shared/team-learnings.db   # opt-in: OVERRIDE the auto worktree store — a custom durable-only path for learnings/knowledge, or to converge separate clones. Point at a DEDICATED store, never a full moflo.db. Env override: MOFLO_DURABLE_PATH.
+  # team_artifact: .moflo/shared/learnings.jsonl       # opt-in: git-tracked JSONL the team commits; session-start import-merges it. Env override: MOFLO_TEAM_ARTIFACT. See moflo-cross-install-memory-sharing.md.
+  # hydrate_from: /abs/path/to/moflo-snapshot.db       # opt-in: whole-DB snapshot to seed a fresh/empty workspace on session-start (skips the cold reindex). No-op once the local DB has content. Take one with "flo memory backup --to <path>". Env override: MOFLO_HYDRATE_FROM.
 
 # Hook toggles (all on by default — disable to slim down)
 hooks:
@@ -132,7 +132,7 @@ auto_update:
   enabled: true                          # Master toggle for version-change auto-sync
   scripts: true                          # Sync .claude/scripts/ from moflo bin/
   helpers: true                          # Sync .claude/helpers/ from moflo source
-  hook_block_drift: regenerate           # warn | regenerate | off (default: regenerate since #1227)
+  hook_block_drift: regenerate           # warn | regenerate | off (default: regenerate)
   claudemd_injection_drift: regenerate   # warn | regenerate | off
 
 # Which skill categories to install (OPTIONAL — omit to get every skill)
@@ -245,10 +245,10 @@ skills:
 | `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
 | `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
 | `auto_update.enabled: false` | Disable all on-session auto-sync (scripts, helpers, drift checks) |
-| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (#881, default since #1227 — basename guard from #1180 keeps user-owned hooks safe). |
+| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (default; a basename guard keeps user-owned hooks safe). |
 | `auto_update.hook_block_drift: warn` | Print drift notice but leave settings.json unchanged. Opt-out from auto-regen. |
 | `auto_update.hook_block_drift: off` | Skip hook-block drift detection entirely |
-| `auto_update.claudemd_injection_drift: regenerate` | Auto-refresh the MoFlo block in `CLAUDE.md` when it drifts from the current generator (#1142, default) |
+| `auto_update.claudemd_injection_drift: regenerate` | Auto-refresh the MoFlo block in `CLAUDE.md` when it drifts from the current generator (default) |
 | `auto_update.claudemd_injection_drift: warn` | Print a drift notice on session start but leave `CLAUDE.md` unchanged |
 | `auto_update.claudemd_injection_drift: off` | Skip CLAUDE.md injection drift detection entirely |
 

package/.claude/helpers/gate.cjs

@@ -963,6 +963,45 @@ function creditIsLive(flag, stored, scope) {
   return stored === now;
 }
 
+// #1410 — is this Bash command actually a `gh pr create` invocation? Delegates
+// to pr-create-command.cjs, which sanitises data regions (quotes, heredoc
+// bodies, comments) before looking for the command, so the gate neither misses
+// real invocations (newline-separated, piped, parenthesised) nor fires on
+// commands that merely quote the literal (`git commit -m "...gh pr create..."`).
+//
+// Fail-safe, in BOTH directions, because this runs on every Bash call in every
+// consumer. gate-hook.mjs maps a non-zero exit from this script to exit 2, so an
+// uncaught throw here does not degrade one gate — it blocks every Bash call the
+// consumer makes. So a load failure (partial `.claude/helpers` sync mid-upgrade,
+// hand-pruned install) AND a throw from the matcher itself both fall back to the
+// pre-#1410 regex: previous behaviour, not a wedged session.
+//
+// Not silent (#854, hook-authoring §4): the fallback path advises on stderr and
+// continues. If this ever fires it means the matcher crashed, which is worth
+// being loud about — and it cannot spam a healthy session, because a healthy
+// session never reaches it.
+var LEGACY_PR_CREATE_RE = /(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/;
+var prCreateMatcher = null;
+function isPrCreateCommand(cmd) {
+  if (prCreateMatcher === null) {
+    try {
+      prCreateMatcher = require('./pr-create-command.cjs').isPrCreateCommand;
+    } catch (e) {
+      prCreateMatcher = false;
+      process.stderr.write('moflo: pr-create-command.cjs unavailable (' + (e && e.message) + ') — PR gates fall back to the legacy matcher. Run `npx flo doctor --fix`.\n');
+    }
+    if (typeof prCreateMatcher !== 'function') prCreateMatcher = false;
+  }
+  if (prCreateMatcher) {
+    try {
+      return prCreateMatcher(cmd);
+    } catch (e) {
+      process.stderr.write('moflo: pr-create matcher threw (' + (e && e.message) + ') — falling back to the legacy matcher. Please report with the command that triggered it.\n');
+    }
+  }
+  return LEGACY_PR_CREATE_RE.test(cmd);
+}
+
 // Classifier-aware simplify gate skip. Returns a string reason if the gate
 // can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
 // so the gate's "trivial" definition matches the skill's exactly.
@@ -1600,12 +1639,12 @@ switch (command) {
     break;
   }
   case 'check-before-pr': {
-    // Anchored to command-start (or chained via && / || / ;) so heredoc bodies
-    // and quoted strings that contain the literal "gh pr create" don't trip
-    // the gate during regular `git commit -m "...gh pr create..."` flows. The
-    // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
+    // Anchored to command-start so heredoc bodies and quoted strings that
+    // contain the literal "gh pr create" don't trip the gate during regular
+    // `git commit -m "...gh pr create..."` flows, while still catching the
+    // chained, piped, parenthesised, and multi-line shapes (#1410).
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    if (!isPrCreateCommand(cmd)) break;
     // #1374 — close the loop the TaskCreate reminder opens. Advisory: stdout,
     // no exit, and worded as a reminder, because a message may only claim to
     // block when it blocks (#1326). An open task list is a reporting failure,
@@ -1680,7 +1719,7 @@ switch (command) {
       }
     }
     var missing = [];
-    if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count, #1322)');
+    if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify (or /distill) 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;
@@ -1716,7 +1755,7 @@ switch (command) {
     // command (docs-only diffs are exempt, so this never blocks a docs PR).
     if (!config.verify_before_done) break;
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    if (!isPrCreateCommand(cmd)) break;
     // No-source-files exemption — a docs-only / path-inert diff needs no verify.
     var changedD = getChangedFilesVsBase();
     if (changedD && changedD.length > 0) {