moflo 4.10.29-rc.6 → 4.11.0

package/.claude/guidance/shipped/moflo-cross-install-memory-sharing.md

@@ -1,6 +1,6 @@
 # Cross-Installation Memory Sharing
 
-**Purpose:** Decide how to share moflo's durable learnings across git worktrees, machines, or a team — and how to do it WITHOUT corrupting search. Read this before configuring `memory.durable_path`, running `flo memory sync`, or pointing two checkouts at one database.
+**Purpose:** Decide how to share moflo's durable learnings across git worktrees, machines, or a team — WITHOUT corrupting search. Worktrees on one machine share automatically; read this before customizing that, running `flo memory sync`, or pointing two checkouts at one database.
 
 ---
 
@@ -26,7 +26,7 @@ Choose by who needs the learnings, not by what is easiest to wire.
 
 | Topology | Mechanism | How |
 |----------|-----------|-----|
-| Same machine, many worktrees / Conductor workspaces | `memory.durable_path` | Point every checkout at one durable-only store; session-start seeds + writes through automatically |
+| Same machine, many worktrees / Conductor workspaces | **Automatic** (default) | Learnings converge across worktrees at session-start with no config; override the store with `memory.durable_path`, or opt out with `memory.worktree_sharing: false` |
 | One person, many machines | `flo memory sync` | `--to <file>` then `--from <file>` via a synced folder (Dropbox/iCloud) or a hand-copied file |
 | A team sharing one repo | Git-tracked team artifact | `flo memory team-export` writes `.moflo/shared/learnings.jsonl`; teammates' session-start import-merges it after `git pull` |
 | A fresh/empty workspace that must be ready FAST | Whole-DB snapshot (`memory.hydrate_from`) | `flo memory backup --to <snap>` once; a new workspace restores the entire DB so search works on session one — no cold reindex |
@@ -35,16 +35,25 @@ The first three move the SAME durable slice and dedupe on `UNIQUE(namespace, key
 
 ---
 
-## Configure a Same-Machine Shared Store
+## Automatic Worktree Sharing (Default)
 
-Set `memory.durable_path` in `moflo.yaml` to a dedicated file — NOT a full `moflo.db`.
+**Worktrees on one machine need no setup — sharing is automatic.** When moflo starts in a checkout whose repo has git worktrees in play, it derives a durable-only store at `<git-common-dir>/moflo/durable.db` (a path every worktree computes identically, since they share one `.git`) and converges `learnings` + `knowledge` across them at session-start. Conductor builds on git worktrees, so its workspaces are covered too.
+
+| Guardrail | Behavior |
+|-----------|----------|
+| Activates only with worktrees | A plain single checkout writes nothing — byte-for-byte unchanged |
+| Never a full DB | The derived store is a dedicated `durable.db`, so it can't trip the index-divergence hazard above |
+| Opt out | `memory.worktree_sharing: false` |
+| Override the location | `memory.durable_path` (also use this to converge separate *clones*, which don't share a `.git`) |
+
+To override the store location, set a dedicated file — NOT a full `moflo.db`:
 
 ```yaml
 memory:
-  durable_path: ~/.moflo-shared/team-learnings.db   # a durable-only store, created on first flush
+  durable_path: ~/.moflo-shared/team-learnings.db   # overrides the auto store; created on first flush
 ```
 
-The path must resolve to a file that is NOT any project's `.moflo/moflo.db`. Pointing it at a real `moflo.db` re-introduces the whole-DB-sharing hazard. `MOFLO_DURABLE_PATH` overrides the config per process; relative paths resolve against the project root.
+Pointing `durable_path` at a real `moflo.db` re-introduces the whole-DB-sharing hazard. `MOFLO_DURABLE_PATH` overrides per process; relative paths resolve against the project root. The `/memory-worktree` skill verifies, customizes, or opts out for you.
 
 ---
 
@@ -111,6 +120,7 @@ flo doctor -c shared-db
 
 | Result | Meaning |
 |--------|---------|
+| **pass** — "Automatic worktree learning sharing active" | No `durable_path` set, but worktrees are present — the auto-derived durable-only store is on and safe |
 | **pass** — "durable-only shared store configured" | `durable_path` points at a dedicated file — safe |
 | **warn** — "points at a full moflo.db" | `durable_path` aliases or is named like a full DB — repoint it at a dedicated store |
 | **warn** — "is a symlink" | The local `moflo.db` is symlinked into a shared location — replace it with a local DB and use `durable_path` |

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

@@ -60,7 +60,8 @@ memory:
   backend: node-sqlite            # node-sqlite (default) | rvf (pure-TS fallback) | json (last resort). Passed to createDatabase() as the preferred provider (#1144).
   embedding_model: Xenova/all-MiniLM-L6-v2   # 384-dim neural embeddings
   namespace: default              # Default namespace for memory operations
-  # durable_path: ~/.moflo-shared/team-learnings.db   # opt-in (#1232): share durable namespaces (learnings, knowledge) across worktrees / Conductor workspaces. Point at a DEDICATED store, never a full moflo.db. Env override: MOFLO_DURABLE_PATH.
+  # 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.
 

package/.claude/skills/memory-team/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: memory-team
+description: |
+  Guided setup for sharing moflo's durable learnings through a git-tracked JSONL artifact — for a whole
+  TEAM on one repo, OR for one person across several MACHINES (a team of one). Use when the user says
+  "share learnings with my team", "commit our moflo memory", "sync memory across my laptop and desktop",
+  "set up memory.team_artifact", or "auto-export learnings on every PR". Installs a pre-commit hook so the
+  artifact rides along in every commit. For many worktrees on ONE machine, use /memory-worktree instead.
+arguments: "[--solo]"
+---
+
+# /memory-team — Share Learnings via a Git-Tracked Artifact
+
+Wires up **`memory.team_artifact`**: a diffable JSONL file (`.moflo/shared/learnings.jsonl`) that lives
+**in the repo**, reviewed like any other change. Teammates `git pull` it and their next session
+auto-imports the merged learnings; each entry is stamped with its git author. This skill also installs a
+**pre-commit hook** so the artifact is re-exported and staged on every commit — the learnings ride along
+in each PR with zero effort.
+
+> **One mechanism, two audiences.** A *team* and *one person across machines* are the same problem — push
+> the durable slice through git. This skill covers both; the only difference is whether anyone else is on
+> the other end. (Prefer a private, non-git file for your own machines? See "Advanced" at the bottom —
+> `flo memory sync` moves a binary artifact that keeps embeddings verbatim.)
+
+**Arguments:** `$ARGUMENTS` — pass `--solo` to skip team-oriented wording (still identical setup).
+
+## When to use
+
+- "share learnings / memory with my team"
+- "commit our moflo knowledge to the repo"
+- "sync memory between my laptop and desktop"
+- "auto-export the learnings on every PR / commit"
+- "set up `team_artifact`"
+
+For **many worktrees on one machine**, that's a shared local store, not git — use `/memory-worktree`.
+
+## Procedure
+
+### Step 0 — Memory first (gate requirement)
+
+```
+mcp__moflo__memory_search { query: "team_artifact learnings jsonl git share import session-start", namespace: "guidance" }
+```
+
+### Step 1 — Confirm this is the git path
+
+- Team on one repo, or one person across machines who both push to the same repo? → correct skill.
+- Many worktrees on **one** machine, no cross-machine need? → redirect to `/memory-worktree`.
+- A private synced file (Dropbox/USB), no git? → point at the Advanced section (`flo memory sync`).
+
+### Step 2 — Set the config
+
+Read the project-root `moflo.yaml` and add/merge under `memory:` — **preserve existing keys**:
+
+```yaml
+memory:
+  team_artifact: .moflo/shared/learnings.jsonl
+```
+
+`.moflo/shared/learnings.jsonl` is the default; only override if the user wants a different tracked path.
+
+### Step 3 — First export (creates + tracks the artifact)
+
+```bash
+npx flo memory team-export 2>&1
+```
+
+This writes the JSONL, and **rewrites `.gitignore`** from a blanket `.moflo/` to `.moflo/*` +
+`!/.moflo/shared/` so the shared artifact is tracked while the machine-local DB stays ignored. Surface
+what it reports (entries added, `.gitignore` change). If there are no durable learnings yet, that's fine —
+the artifact is created empty and fills in as learnings accrue.
+
+### Step 4 — Install the pre-commit hook
+
+The hook re-exports and stages the artifact on every commit, so it's never stale in a PR. Handle three
+cases; **do not clobber** an existing hook.
+
+Define the managed block (POSIX `sh` — git runs hooks via `sh` on Linux, macOS, **and** Windows):
+
+```sh
+# >>> moflo team-export (managed by /memory-team) >>>
+# Refresh the shared learnings artifact so it rides along in this commit.
+npx --no-install flo memory team-export >/dev/null 2>&1 || true
+if [ -n "$(git status --porcelain -- .moflo/shared/learnings.jsonl 2>/dev/null)" ]; then
+  git add .moflo/shared/learnings.jsonl
+fi
+# <<< moflo team-export (managed by /memory-team) <<<
+```
+
+Install it:
+
+1. **Husky present** (`.husky/pre-commit` exists) → append the block to that file.
+2. **Existing `.git/hooks/pre-commit`** → if it already contains the `moflo team-export` markers, leave it
+   (idempotent); otherwise append the block after the shebang.
+3. **No hook** → create `.git/hooks/pre-commit` with `#!/bin/sh` as the first line, then the block.
+
+On POSIX, make it executable:
+
+```bash
+node -e "require('fs').chmodSync('.git/hooks/pre-commit', 0o755)"
+```
+
+(Use the Node `fs.chmodSync` primitive, not `chmod` — it's a harmless no-op on Windows. Never shell out
+to `chmod` in a cross-platform step.)
+
+- The `|| true` keeps a failed export from ever blocking a commit.
+- The `git status --porcelain` guard means the artifact is only re-staged when it actually changed — no
+  empty-diff churn on unrelated commits.
+
+### Step 5 — Commit and share
+
+```bash
+git add .moflo/shared/learnings.jsonl .gitignore
+git commit -m "chore: share moflo learnings"
+git push
+```
+
+Teammates (or your other machine) run `git pull`; their **next session auto-imports** the merged file —
+no manual import command. To pull learnings without waiting for a restart:
+
+```bash
+npx flo memory team-import 2>&1
+```
+
+## Output
+
+End with a single-block summary:
+
+```
+Team Memory Sharing — configured
+─────────────────────────────────
+Artifact:    .moflo/shared/learnings.jsonl  (git-tracked, JSONL, author-stamped)
+Config key:  memory.team_artifact
+PR hook:     .git/hooks/pre-commit  → re-exports + stages on every commit
+Import:      automatic at session start (after git pull)  |  npx flo memory team-import
+Scope:       learnings + knowledge only (embeddings regenerated on import)
+```
+
+## Advanced — one person, a private file (no git)
+
+If you're solo and would rather not commit learnings, carry a binary artifact instead. It keeps the
+embeddings verbatim (no recompute on the far side) and merges idempotently:
+
+```bash
+npx flo memory sync --to   ~/Dropbox/moflo-learnings.db   # machine A
+npx flo memory sync --from ~/Dropbox/moflo-learnings.db   # machine B
+```
+
+Same durable slice, no repo footprint, no review — the trade-off is it's not diffable and not shared.
+
+## Rules
+
+- **Don't** reimplement export/import or the `.gitignore` rewrite — `flo memory team-export/team-import`
+  own all of it (`team-artifact-sync.ts`). This skill sets config, runs them, and installs the hook.
+- **Don't** overwrite an existing pre-commit hook or husky config — append the marked block only.
+- **Don't** use `chmod` / `mkdir` / `rm` in shell steps — Windows lacks them on PATH; use Node `fs`.
+- Embeddings are intentionally **omitted** from the JSONL (384 floats/row would wreck diffs) — they're
+  regenerated on import. Don't try to add them.
+
+## See Also
+
+- `/memory-worktree` — same-machine sharing across worktrees / Conductor (a shared local store, not git)
+- `flo memory team-export --help` / `flo memory sync --help`
+- `docs/blog/memory-sharing.html` — the design rationale (durable slice, why not share the whole DB)

package/.claude/skills/memory-worktree/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: memory-worktree
+description: |
+  Verify, customize, or opt out of moflo's AUTOMATIC durable-learning sharing across git worktrees /
+  Conductor workspaces on one machine. As of the worktree-auto-sharing change this is on by default —
+  learnings converge across a repo's worktrees with no setup. Use when the user asks "is memory shared
+  across my worktrees?", "where are my worktree learnings stored?", "turn off worktree memory sharing",
+  "share learnings across my separate clones", or "point my worktrees at a custom store". For a team or
+  cross-machine (git-tracked) sharing, use /memory-team instead.
+arguments: "[--off | --path <store>]"
+---
+
+# /memory-worktree — Durable Sharing Across Worktrees (Automatic)
+
+Working across git worktrees is a core moflo competency, so durable-learning sharing across the
+worktrees of a repo is now **automatic and on by default**. When a checkout is part of a repo with
+worktrees in play, moflo derives a shared durable store at **`<git-common-dir>/moflo/durable.db`** and
+converges the `learnings` + `knowledge` namespaces across every worktree at session start — no config.
+A plain single checkout writes nothing and behaves exactly as before.
+
+This skill is for the three things you might still want: **verify** it's working, **customize** where it
+stores (or extend it to non-worktree clones), or **opt out**.
+
+> Only the durable slice travels. Structural + ephemeral data stays local per checkout and rebuilds
+> itself — the same safety model the auto path is built on (a dedicated `durable.db`, never a full
+> `moflo.db`). See [[memory-team]] for the git-tracked, cross-machine variant.
+
+**Arguments:** `$ARGUMENTS` — `--off` to opt out, `--path <store>` to set a custom shared store.
+
+## When to use
+
+- "Is memory / are learnings shared across my worktrees?" → **verify** (Step 1).
+- "Where are my worktree learnings stored?" → it's `<git-common-dir>/moflo/durable.db`; verify to confirm.
+- "Turn off / disable worktree memory sharing" → **opt out** (Step 2).
+- "Share learnings across my separate clones / a custom location" → **customize** (Step 3).
+
+For a team, or your own laptop+desktop over git, that's `/memory-team`, not this.
+
+## Procedure
+
+### Step 0 — Memory first (gate requirement)
+
+```
+mcp__moflo__memory_search { query: "durable_path worktree sharing auto git common dir learnings", namespace: "guidance" }
+```
+
+### Step 1 — Verify (default action)
+
+Run the safety/status check and surface it verbatim:
+
+```bash
+npx flo doctor -c shared-db 2>&1
+```
+
+- **"Automatic worktree learning sharing active (<path>)"** → it's working; the path is the shared store.
+- **"No shared full moflo.db detected…"** → auto sharing is NOT active here. Most likely this checkout
+  has no sibling worktrees yet (auto only turns on once worktrees exist). Confirm with the user; if they
+  expected sharing across *separate clones* (not worktrees), go to Step 3 — auto can't converge those.
+- **A `warn`** → a full-DB misconfig is present; follow the check's `fix` line.
+
+To see that learnings actually converged, from a second worktree:
+
+```bash
+npx flo memory list --namespace learnings 2>&1 | head
+```
+
+### Step 2 — Opt out (`--off`)
+
+If the user wants it off, set the toggle in the project-root `moflo.yaml` (preserve other `memory:` keys):
+
+```yaml
+memory:
+  worktree_sharing: false
+```
+
+Explain: this stops the auto flush/seed at session start. Anything already converged into a worktree's
+local DB stays; nothing new propagates. Takes effect next session.
+
+### Step 3 — Customize the store (`--path`, or non-worktree clones)
+
+Setting an explicit `memory.durable_path` **overrides** the auto derivation — use it to:
+- put the shared store somewhere other than `.git/moflo/` (e.g. a synced/backed-up location), or
+- converge checkouts that are **separate clones**, not git worktrees (auto only covers worktrees, since
+  only worktrees share a git common dir).
+
+```yaml
+memory:
+  durable_path: ~/.moflo-shared/<repo-name>-learnings.db
+```
+
+The path must live outside any single checkout and must **not** be named `moflo.db`. Create the parent
+dir with a Node primitive (cross-platform — never `mkdir -p`):
+
+```bash
+node -e "const p=require('path'),fs=require('fs');fs.mkdirSync(p.dirname(process.argv[1]),{recursive:true})" "<chosen-store-path>"
+```
+
+Then re-run `npx flo doctor -c shared-db` to confirm it reports the durable-only store as safe.
+
+## Output
+
+End with a single-block summary of what state you left it in, e.g.:
+
+```
+Worktree Memory Sharing
+────────────────────────
+Mode:         automatic (default)  |  custom durable_path  |  disabled
+Store:        <git-common-dir>/moflo/durable.db  (or the custom/none path)
+Config:       memory.worktree_sharing / memory.durable_path
+Verify:       npx flo doctor -c shared-db
+Scope:        learnings + knowledge only (structural stays local)
+```
+
+## Rules
+
+- **Don't** re-implement the sync or path derivation — it's `resolveDurablePath` / `syncDurableAtSessionStart`
+  in `src/cli/services/durable-sync.ts`; this skill only reads config, sets the two keys, and verifies.
+- **Never** set `durable_path` to a file named `moflo.db` or the local `.moflo/moflo.db` — that's the
+  HNSW-index-divergence hazard `flo doctor -c shared-db` guards against.
+- **Don't** use `mkdir -p` / `rm` / `cp` in shell steps — Windows lacks them on PATH. Use Node `fs`.
+- **Cross-machine or team? Wrong skill.** Redirect to `/memory-team`.
+
+## See Also
+
+- `/memory-team` — git-tracked JSONL sharing for teams **and** one person across machines
+- `flo doctor -c shared-db` — reports auto-sharing status and catches full-DB misconfig
+- `docs/blog/memory-sharing.html` — the design rationale (durable vs structural vs ephemeral)

package/README.md

@@ -67,7 +67,7 @@ MoFlo makes deliberate choices so you don't have to:
 |---------|-------------|
 | **Semantic Memory** | 384-dim domain-aware embeddings. Store knowledge, search it instantly. |
 | **Reflection** | Distills durable lessons from your sessions into searchable memory — automatically (auto-meditate), or on demand with `/meditate`. |
-| **Cross-Install Sharing** | Share durable `learnings` across git worktrees, your own machines, or a whole team — via `memory.durable_path`, `flo memory sync`, or a git-tracked artifact. Structural namespaces stay local. [Full documentation →](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md) |
+| **Cross-Install Sharing** | Durable `learnings` follow you across git worktrees **automatically** (no setup) — and across your own machines or a whole team via `flo memory sync` or a git-tracked artifact. Structural namespaces stay local. [Full documentation →](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md) |
 | **Code Navigation** | Indexes your codebase structure so Claude can answer "where does X live?" without Glob/Grep. |
 | **Guidance Indexing** | Chunks your project docs (`.claude/guidance/`, `docs/`) and makes them searchable. |
 | **Gates** | Enforces memory-first and task-creation patterns via Claude Code hooks. Prevents Claude from skipping steps. |
@@ -271,7 +271,7 @@ Pick the mechanism by topology:
 
 | You want to share across… | Use | How |
 |---------------------------|-----|-----|
-| Git worktrees / Conductor workspaces (same machine) | `memory.durable_path` in `moflo.yaml` | Point every checkout at one durable-only store; session-start seeds + writes through automatically |
+| Git worktrees / Conductor workspaces (same machine) | **Automatic** — nothing to set | Learnings converge across worktrees at session-start (stored at `<git-common-dir>/moflo/durable.db`). Override with `memory.durable_path`; opt out with `memory.worktree_sharing: false` |
 | Your own laptop + desktop + CI | `flo memory sync --to/--from <file>` | Export to a synced folder (Dropbox/iCloud) or a copied file, import on the other machine |
 | A whole team on one repo | `flo memory team-export` → commit `.moflo/shared/learnings.jsonl` | Teammates' session-start import-merges it after `git pull` (first-write-wins; author provenance retained) |
 | A fresh workspace that must be ready fast | `flo memory backup/restore` or `memory.hydrate_from` | Seed a new workspace from a **whole-DB snapshot** so it's searchable on session one — no cold reindex. Safe because each workspace owns its own copy (a one-time restore, not live sharing) |

package/bin/session-start-launcher.mjs

@@ -2175,11 +2175,38 @@ try {
   // override is set or moflo.yaml has an UNcommented `durable_path:` line (the
   // generated config ships a commented example, which this regex ignores).
   const durableYamlPath = resolve(projectRoot, 'moflo.yaml');
-  let durableEnabled = Boolean(process.env.MOFLO_DURABLE_PATH);
-  if (!durableEnabled && existsSync(durableYamlPath)) {
-    try {
-      durableEnabled = /^[ \t]*durable_path[ \t]*:/m.test(readFileSync(durableYamlPath, 'utf-8'));
-    } catch { /* unreadable yaml — treat as not-configured */ }
+  // Read moflo.yaml ONCE, then run every pre-gate regex against the one string —
+  // every consumer with a moflo.yaml pays a single read here, not one per key.
+  let durableYaml = '';
+  try {
+    if (existsSync(durableYamlPath)) durableYaml = readFileSync(durableYamlPath, 'utf-8');
+  } catch { /* unreadable yaml — treat as not-configured */ }
+  let durableEnabled = Boolean(process.env.MOFLO_DURABLE_PATH) || /^[ \t]*durable_path[ \t]*:/m.test(durableYaml);
+  // Auto-enable across git worktrees — moflo's core multi-worktree competency.
+  // When durable_path isn't explicitly configured, still run the sync IF this
+  // repo has worktrees in play (this checkout is a linked worktree, or the
+  // shared .git has a non-empty worktrees/ registry), unless the user opted out
+  // with `worktree_sharing: false`. A plain single checkout short-circuits on a
+  // cheap fs stat with no module import, so solo users pay ~nothing. The
+  // authoritative derivation lives in durable-sync.ts#resolveDurablePath.
+  if (!durableEnabled) {
+    const optedOut = /^[ \t]*(worktree_sharing|worktreeSharing)[ \t]*:[ \t]*false\b/m.test(durableYaml);
+    if (!optedOut) {
+      try {
+        const dotgit = join(projectRoot, '.git');
+        const st = statSync(dotgit);
+        if (st.isFile()) {
+          // Linked worktree — `.git` file's `gitdir:` points into `.git/worktrees/…`.
+          // A submodule's points into `.git/modules/…` (no worktrees segment) and
+          // must NOT auto-share with its superproject, so gate on the segment.
+          if (/[\\/]worktrees[\\/]/.test(readFileSync(dotgit, 'utf-8'))) durableEnabled = true;
+        } else if (st.isDirectory()) {
+          try {
+            if (readdirSync(join(dotgit, 'worktrees')).length > 0) durableEnabled = true;
+          } catch { /* no worktrees registry (ENOENT) — stay off */ }
+        }
+      } catch { /* no/unreadable .git — not a worktree, stay off */ }
+    }
   }
   const durablePaths = durableEnabled
     ? [
@@ -2191,6 +2218,12 @@ try {
   if (durablePath) {
     const { syncDurableAtSessionStart } = await import(pathToFileURL(durablePath).href);
     const result = await syncDurableAtSessionStart({ projectRoot });
+    if (result?.autoWorktree && (result.seededToLocal > 0 || result.flushedToShared > 0)) {
+      emitMutation(
+        'auto-shared learnings across git worktrees',
+        'converging durable learnings for this repo — set memory.worktree_sharing: false to opt out',
+      );
+    }
     if (result?.seededToLocal > 0) {
       emitMutation(
         'seeded shared learnings',

package/dist/src/cli/commands/doctor-checks-shared-db.js

@@ -22,6 +22,7 @@ import * as path from 'path';
 import { memoryDbPath } from '../services/moflo-paths.js';
 import { findProjectRoot } from '../services/project-root.js';
 import { loadMofloConfig } from '../config/moflo-config.js';
+import { resolveDurablePath } from '../services/durable-sync.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 const NAME = 'Shared Full DB';
 /**
@@ -99,6 +100,18 @@ export async function checkSharedFullDb(deps) {
                 message: `Durable-only shared store configured (${durableRaw}) — safe; structural namespaces stay local.`,
             };
         }
+        // 3. No explicit durable_path — surface automatic worktree sharing when it's
+        //    active, so the default-on behavior is visible (and reassuringly safe:
+        //    the derived store is a dedicated durable.db, never a full moflo.db).
+        const auto = resolveDurablePath(root, config);
+        if (auto.autoWorktree && auto.path) {
+            return {
+                name: NAME,
+                status: 'pass',
+                message: `Automatic worktree learning sharing active (${auto.path}) — durable learnings converge across this ` +
+                    `repo's git worktrees; structural namespaces stay local. Set memory.worktree_sharing: false to disable.`,
+            };
+        }
         return {
             name: NAME,
             status: 'pass',

package/dist/src/cli/config/moflo-config.js

@@ -228,6 +228,13 @@ function mergeConfig(raw, root) {
                 const v = raw.memory?.durable_path ?? raw.memory?.durablePath;
                 return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
             })(),
+            // #1231 follow-up — opt-out toggle for automatic worktree learning
+            // sharing. Only an explicit `false` disables it; absent/true leaves the
+            // default auto-behavior on. Detection + derivation live in durable-sync.ts.
+            worktree_sharing: (() => {
+                const v = raw.memory?.worktree_sharing ?? raw.memory?.worktreeSharing;
+                return typeof v === 'boolean' ? v : undefined;
+            })(),
             team_artifact: (() => {
                 const v = raw.memory?.team_artifact ?? raw.memory?.teamArtifact;
                 return typeof v === 'string' && v.trim().length > 0 ? v.trim() : undefined;
@@ -340,11 +347,21 @@ function mergeConfig(raw, root) {
  * Tries moflo.yaml first, then moflo.config.json.
  * Returns defaults merged with file contents.
  */
+/**
+ * A fresh defaults-only config for `root`. Deep-clones DEFAULT_CONFIG so a caller
+ * mutating the returned config's nested objects (e.g. `cfg.memory.durable_path =
+ * …`) can't poison the module-global DEFAULT_CONFIG and leak into every later
+ * load — a shallow spread shares the nested `memory`/`hooks`/… references, a
+ * latent cross-contamination bug.
+ */
+function freshDefaultConfig(root) {
+    return { ...structuredClone(DEFAULT_CONFIG), project: { name: path.basename(root) } };
+}
 export function loadMofloConfig(projectRoot) {
     const root = projectRoot || process.cwd();
     const configFile = findConfigFile(root);
     if (!configFile) {
-        return { ...DEFAULT_CONFIG, project: { name: path.basename(root) } };
+        return freshDefaultConfig(root);
     }
     try {
         const content = fs.readFileSync(configFile.path, 'utf-8');
@@ -360,12 +377,12 @@ export function loadMofloConfig(projectRoot) {
             throw new Error('js-yaml is required to parse moflo.yaml. Install it: npm install js-yaml');
         }
         if (!raw || typeof raw !== 'object') {
-            return { ...DEFAULT_CONFIG, project: { name: path.basename(root) } };
+            return freshDefaultConfig(root);
         }
         return mergeConfig(raw, root);
     }
     catch {
-        return { ...DEFAULT_CONFIG, project: { name: path.basename(root) } };
+        return freshDefaultConfig(root);
     }
 }
 /**

package/dist/src/cli/init/executor.js

@@ -48,6 +48,8 @@ export const SKILLS_MAP = {
         'memory-patterns',
         'memory-optimization',
         'vector-search',
+        'memory-worktree', // guided memory.durable_path setup (same-machine worktrees)
+        'memory-team', // guided memory.team_artifact setup + PR pre-commit hook
     ],
     spells: [
         'spell-builder',

package/dist/src/cli/services/durable-sync.js

@@ -33,6 +33,8 @@
  *
  * @module cli/services/durable-sync
  */
+import * as path from 'path';
+import * as fs from 'fs';
 import { findProjectRoot } from './project-root.js';
 import { stableAbsolute, pickConfiguredPath } from './configured-path.js';
 import { memoryDbPath } from './moflo-paths.js';
@@ -40,24 +42,127 @@ import { loadMofloConfig } from '../config/moflo-config.js';
 import { cherryPickLearningsFromLegacy, DURABLE_NAMESPACES, isDurableNamespace, } from './cherry-pick-learnings.js';
 export { isDurableNamespace };
 /**
- * Resolve the configured durable-store path to an absolute path, or `null`
- * when the feature is off (no env, no `memory.durable_path`) or misconfigured
- * (points at this project's own local DB — syncing a DB with itself is a
- * no-op, so we disable rather than thrash).
+ * Read `<projectRoot>/.git` ONCE and classify the checkout for worktree sharing,
+ * using filesystem reads only (no `git` subprocess, so it's PATH-independent and
+ * cross-platform, Rule #1). Returns the shared `.git` common dir plus whether
+ * THIS checkout is a linked worktree — or `null` when it's not a git repo root,
+ * `.git` is unreadable, or it's a **submodule**.
  *
- * Precedence: `MOFLO_DURABLE_PATH` env > `memory.durable_path` (moflo.yaml).
- * Relative values resolve against the project root. Path-pick + symlink-stable
- * identity live in {@link pickConfiguredPath}/{@link stableAbsolute}.
+ * - Primary checkout: `<root>/.git` is a directory → that IS the common dir.
+ * - Linked worktree:  `<root>/.git` is a FILE (`gitdir: <main>/.git/worktrees/<id>`)
+ *   whose `commondir` file points back to the shared `.git`.
+ * - Submodule:        `<root>/.git` is also a FILE, but `gitdir: <super>/.git/modules/<name>`
+ *   with NO `commondir`. It is NOT a worktree and must NEVER share a durable
+ *   store with its superproject — excluded via the `worktrees/` segment +
+ *   `commondir` checks (real worktrees have both; submodules have neither).
+ *
+ * The primary tree and all its worktrees resolve to the SAME common dir, which
+ * is what lets an auto-derived shared store converge with zero config.
+ */
+function readGitLayout(projectRoot) {
+    const dotgit = path.join(projectRoot, '.git');
+    let st;
+    try {
+        st = fs.statSync(dotgit);
+    }
+    catch {
+        return null;
+    }
+    if (st.isDirectory())
+        return { commonDir: dotgit, linkedWorktree: false };
+    if (!st.isFile())
+        return null;
+    try {
+        const m = fs.readFileSync(dotgit, 'utf-8').match(/gitdir:\s*(.+)/);
+        if (!m)
+            return null;
+        let gitdir = m[1].trim();
+        if (!path.isAbsolute(gitdir))
+            gitdir = path.resolve(projectRoot, gitdir);
+        // Linked worktree only — exclude submodules (`.../modules/...`, no commondir).
+        if (!/[\\/]worktrees[\\/]/.test(gitdir))
+            return null;
+        let cd = fs.readFileSync(path.join(gitdir, 'commondir'), 'utf-8').trim();
+        if (!path.isAbsolute(cd))
+            cd = path.resolve(gitdir, cd);
+        return { commonDir: path.resolve(cd), linkedWorktree: true };
+    }
+    catch {
+        return null;
+    }
+}
+/** The shared git common dir for `projectRoot`, or `null` — see {@link readGitLayout}. */
+export function resolveGitCommonDir(projectRoot) {
+    return readGitLayout(projectRoot)?.commonDir ?? null;
+}
+/**
+ * Decide whether to AUTO-enable durable sharing for `projectRoot`, returning the
+ * shared `.git` common dir to derive the store under — or `null` to stay off.
+ *
+ * Activates ONLY when git worktrees are actually in play, so a plain single
+ * checkout (and any submodule) writes nothing and behaves byte-identically to
+ * before. "In play" = this checkout is itself a linked worktree, OR the shared
+ * `.git` has a non-empty `worktrees/` registry (a sibling worktree exists).
+ */
+export function detectWorktreeCommonDir(projectRoot) {
+    const layout = readGitLayout(projectRoot);
+    if (!layout)
+        return null;
+    if (layout.linkedWorktree)
+        return layout.commonDir;
+    // Primary checkout — activate only if it has registered linked worktrees.
+    try {
+        if (fs.readdirSync(path.join(layout.commonDir, 'worktrees')).length > 0)
+            return layout.commonDir;
+    }
+    catch {
+        /* no worktrees registry (ENOENT) or unreadable — treat as no worktrees */
+    }
+    return null;
+}
+/**
+ * Resolve the durable-store path to an absolute path, or `null` when there's
+ * nothing to sync.
+ *
+ * Precedence:
+ *   1. Explicit config — `MOFLO_DURABLE_PATH` env > `memory.durable_path`
+ *      (moflo.yaml). Relative values resolve against the project root.
+ *   2. Auto worktree sharing — when NOTHING is explicitly configured, moflo's
+ *      multi-worktree competency kicks in: if this checkout is part of a repo
+ *      with git worktrees in play, derive a shared store at
+ *      `<git-common-dir>/moflo/durable.db`. Every worktree of the repo resolves
+ *      to the same path, so their learnings converge with zero config. Opt out
+ *      with `memory.worktree_sharing: false`. A single checkout (no worktrees)
+ *      derives nothing and stays byte-identical to before.
+ *
+ * A store that aliases this project's own local DB is rejected (syncing a DB
+ * with itself is a no-op). Path-pick + symlink-stable identity live in
+ * {@link pickConfiguredPath}/{@link stableAbsolute}.
  */
 export function resolveDurablePath(projectRoot = findProjectRoot(), config) {
-    const abs = pickConfiguredPath(process.env.MOFLO_DURABLE_PATH, (config ?? loadMofloConfig(projectRoot)).memory.durable_path, projectRoot);
-    if (!abs)
-        return { path: null, skipped: 'not-configured' };
-    // Self-reference guard — never let the shared store alias the local DB.
-    if (stableAbsolute(abs) === stableAbsolute(memoryDbPath(projectRoot))) {
-        return { path: null, skipped: 'same-as-local' };
+    const cfg = config ?? loadMofloConfig(projectRoot);
+    const local = () => stableAbsolute(memoryDbPath(projectRoot));
+    const abs = pickConfiguredPath(process.env.MOFLO_DURABLE_PATH, cfg.memory.durable_path, projectRoot);
+    if (abs) {
+        // Self-reference guard — never let the shared store alias the local DB.
+        if (stableAbsolute(abs) === local()) {
+            return { path: null, skipped: 'same-as-local' };
+        }
+        return { path: abs };
     }
-    return { path: abs };
+    // No explicit config → auto-share across git worktrees unless opted out.
+    if (cfg.memory.worktree_sharing !== false) {
+        const commonDir = detectWorktreeCommonDir(projectRoot);
+        if (commonDir) {
+            const derived = path.join(commonDir, 'moflo', 'durable.db');
+            // Paranoia guard — a derived path should never alias the local DB, but a
+            // pathological `.git` layout shouldn't turn into a self-sync.
+            if (stableAbsolute(derived) !== local()) {
+                return { path: derived, autoWorktree: true };
+            }
+        }
+    }
+    return { path: null, skipped: 'not-configured' };
 }
 /**
  * Seed durable rows from the shared store into this project's local DB.
@@ -77,6 +182,14 @@ export async function seedDurableFromShared(projectRoot, durablePath) {
  * Local is the source, the shared store the target (created on first flush).
  */
 export async function flushDurableToShared(projectRoot, durablePath) {
+    // Ensure the parent dir exists — auto-derived worktree stores live under
+    // `<git-common-dir>/moflo/`, which won't exist on the very first flush.
+    try {
+        fs.mkdirSync(path.dirname(durablePath), { recursive: true });
+    }
+    catch {
+        /* a real open failure surfaces from cherry-pick below */
+    }
     return cherryPickLearningsFromLegacy({
         projectRoot,
         legacyPaths: [memoryDbPath(projectRoot)],
@@ -96,7 +209,7 @@ export async function flushDurableToShared(projectRoot, durablePath) {
  */
 export async function syncDurableAtSessionStart(opts = {}) {
     const projectRoot = opts.projectRoot ?? findProjectRoot();
-    const { path: durablePath, skipped } = resolveDurablePath(projectRoot, opts.config);
+    const { path: durablePath, skipped, autoWorktree } = resolveDurablePath(projectRoot, opts.config);
     if (!durablePath) {
         return { durablePath: null, skipped, flushedToShared: 0, seededToLocal: 0 };
     }
@@ -106,6 +219,7 @@ export async function syncDurableAtSessionStart(opts = {}) {
     const seed = await seedDurableFromShared(projectRoot, durablePath);
     return {
         durablePath,
+        autoWorktree: autoWorktree ?? false,
         flushedToShared: flush.copied,
         seededToLocal: seed.copied,
     };

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.10.29-rc.6';
+export const VERSION = '4.11.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.29-rc.6",
+  "version": "4.11.0",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -94,7 +94,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.10.29-rc.5",
+    "moflo": "^4.10.29",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"