moflo 4.12.12 → 4.13.1

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

@@ -4,7 +4,7 @@
 
 ---
 
-## CLI Commands (26 Commands, 140+ Subcommands)
+## CLI Commands (27 Commands, 140+ Subcommands)
 
 ### Core Commands
 
@@ -40,6 +40,7 @@
 | `epic`        | 3           | Epic orchestrator — run/status/reset with single-branch or auto-merge strategy |
 | `doctor`      | 1           | System diagnostics with health checks                                         |
 | `completions` | 4           | Shell completions (bash, zsh, fish, powershell)                               |
+| `worktree`    | 3           | Provisioned git worktrees (add, list, remove) — alias `wt`                     |
 
 ### Quick Examples (MCP Preferred)
 
@@ -59,6 +60,49 @@ npx flo daemon start
 
 ---
 
+## Provisioned Worktrees (`flo worktree`)
+
+A bare `git worktree add` produces a valid checkout and an unrunnable workspace — no
+`node_modules`, none of the gitignored `.env` files, and dev servers that collide with the
+primary checkout on fixed ports. `flo worktree add` creates the worktree **and** provisions it.
+
+```bash
+flo worktree add feature/123-thing        # create + provision (this is what /flo -wt runs)
+flo worktree add feature/123 --json       # {"path":…,"branch":…,"index":0,"provisioned":true}
+flo worktree list                         # every worktree + its provisioning state
+flo worktree remove feature/123-thing     # refuses a dirty tree unless --force
+```
+
+Provisioning is driven by an optional `worktree:` block in `moflo.yaml`. **With no block, `add`
+creates the worktree and provisions nothing** — identical to a plain `git worktree add`.
+
+```yaml
+worktree:
+  dir: ../myrepo-worktrees   # default: <repo-parent>/<repo>-worktrees
+  copy: [".env", ".env.*"]   # gitignored files copied from the primary checkout
+  link: ["node_modules"]     # symlinked (junctioned on Windows) from the primary checkout
+  setup: "npm ci"            # run in the new worktree, with MOFLO_WORKTREE_INDEX in its env
+```
+
+| Key | Use it when | Watch out for |
+|-----|-------------|---------------|
+| `copy` | A fresh checkout is missing gitignored config a build needs | It relocates **secrets** outside the repo and outside its `.gitignore`. Sources must live inside the primary checkout; `../secrets` is rejected. |
+| `link` | `node_modules` is large and the project does not use npm workspaces | A symlinked root `node_modules` is fragile under npm/yarn workspaces — prefer `setup: npm ci` there. An existing destination is never clobbered. |
+| `setup` | Install/build steps must run per workspace | A non-zero exit marks the provision failed but leaves the worktree in place. |
+
+**Port collisions.** moflo cannot rewrite a project's hardcoded ports. It gives each worktree a
+small stable integer — unique among live worktrees, reused when one is removed — as
+`MOFLO_WORKTREE_INDEX` in the `setup` command's environment. Offset your own ports from it:
+
+```yaml
+worktree:
+  setup: "npm ci && node -e \"require('fs').writeFileSync('.env.local','PORT='+(3500+Number(process.env.MOFLO_WORKTREE_INDEX)*20))\""
+```
+
+Memory needs no setup: durable learnings already converge across a repo's worktrees
+automatically. See `moflo-cross-install-memory-sharing.md` for the snapshot recipe that also
+skips the structural cold-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 — `retired-files.json` enforces auto-prune on consumer upgrade.

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

@@ -138,3 +138,4 @@ A foreign-writer warning from the Writers Audit check (`flo doctor -c writers`)
 - `.claude/guidance/moflo-memory-strategy.md` — Namespaces, RAG indexing, and the durable-vs-derived split this doc builds on
 - `.claude/guidance/moflo-memory-protocol.md` — Search-and-traverse protocol for the shared `learnings` once it is populated
 - `.claude/guidance/moflo-core-guidance.md` — CLI, daemon, and `moflo.yaml` reference (the `memory` config block)
+- `.claude/guidance/moflo-cli-reference.md` — `flo worktree`, which provisions a new worktree's gitignored files, `node_modules`, and per-workspace port index (memory sharing needs no setup; the rest of the workspace does)

package/.claude/helpers/gate.cjs

@@ -920,10 +920,39 @@ function applyPromptStateReset(state, promptText, opts) {
   state.sddMode = detectSddMode(promptText);
   state.activeSddSlug = null;
 }
-// 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.
-var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|t)(?:[:\s]|$)|\b(?:npx|pnpx)\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\b|(?:^|;|&&|\|\|)\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\s|\b(?:cargo|go|deno|dotnet|mvn)\s+test\b|\bgradle\w*\s+test\b/i;
+// Match npm/yarn/pnpm/bun/turbo/nx/lerna 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.
+//
+// #1484 — the package-manager arm allows a BOUNDED run of selector tokens
+// between the tool and the script name. Every monorepo invocation puts the
+// workspace selection there (`npm run --prefix packages/api test`,
+// `pnpm --filter @acme/api test`, `yarn workspace @acme/api test`), and the old
+// `<pm> [run] test` shape had no slot for it — so a green suite earned no
+// credit and check-before-pr hard-blocked `gh pr create` with no way out.
+//
+// This arm credits the gate, so every way it can over-match is a way the gate
+// fails OPEN. Four properties bound it, and each is pinned by a test:
+//   * separators are HORIZONTAL-only (`[ \t]`, not `\s`). Claude Code runs
+//     multi-line Bash blocks as one string, so a `\s` separator would let
+//     `npm run build\ntest -f dist/x` bridge a newline into the unrelated Unix
+//     `test` builtin and credit a suite that never ran.
+//   * the token class excludes shell separators (; & | < > ( ) $ `) so a match
+//     can never span `npm run build && rm -rf test`, and excludes `#` so a
+//     trailing comment (`npm run build # fix test later`) can't supply the
+//     keyword.
+//   * the class is NEGATED rather than a positive path class. `[-\w=/.:@]`
+//     would pass on POSIX and silently keep missing Windows' `--prefix
+//     C:\repo\pkg` form (Rule #1).
+//   * the `t` alias keeps its own NARROW arm below — reachable only directly
+//     after the package manager, never after selector tokens, so a stray bare
+//     `t` argument (`npm run build --env t`) can't credit the gate.
+// The script name keeps its `(?:[:\s]|$)` terminator, so `test-utils`, `test/`
+// and `dist-tags.test` still don't match. The repetition is bounded at 8 and its
+// character classes are disjoint from the separator, so there is no backtracking
+// blowup (27k-char pathological input: 0 ms).
+var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun|turbo|nx|lerna)[ \t]+(?:[^\s;&|<>()$`#]+[ \t]+){0,8}test(?:[:\s]|$)|(?:^|[^a-z])(?:npm|yarn|pnpm|bun)[ \t]+(?:run[ \t]+)?t(?:[:\s]|$)|\b(?:npx|pnpx)\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\b|(?:^|;|&&|\|\|)\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\s|\b(?:cargo|go|deno|dotnet|mvn)\s+test\b|\bgradle\w*\s+test\b/i;
 // #1322 — failure markers in a test runner's own OUTPUT.
 //
 // This is deliberately not an exit-code check: Claude Code's PostToolUse payload

package/.claude/skills/fl/phases.md

@@ -106,30 +106,64 @@ implementation, tests, simplify, commit, and PR from inside it. The current chec
 untouched. Durable learnings still converge automatically — a worktree shares the repo's
 `<git-common-dir>/moflo/durable.db` (see `/memory-worktree`).
 
-Compute paths with Node, never string-concatenate — the branch name contains `/`, and the
-worktree dir must sit **outside** the checkout on every OS (Rule #1: no hardcoded separators,
-no `/tmp`, no `mkdir -p`):
+Use `flo worktree add`. It computes the path, creates the branch off the repo's default
+branch, and **provisions** the tree per the optional `worktree:` block in `moflo.yaml` — copying
+gitignored `.env` material, linking `node_modules`, running a `setup` command. A fresh worktree is
+otherwise a valid checkout and an unrunnable workspace. Do not hand-roll the path or shell
+`git worktree add` directly: the path computation and the copy/link/setup steps are
+platform-sensitive (Rule #1) and live in tested code.
 
 ```bash
-# 1. Fresh base — update main in the current checkout first (worktrees share objects).
-git fetch origin main
+cd "<repo-root>" && flo worktree add "<type>/<issue-number>-<short-desc>" --json
+```
+
+Bind the repo root to the call. `flo worktree` resolves the repo from its working directory, and in
+Claude Code that resets between calls — run it from the wrong place and it silently targets a
+different repository (`Not a registered worktree of this repo` on the good day, the wrong repo's
+worktree on the bad one).
 
-# 2. Resolve a sibling worktree path: <repo-parent>/<repo>-worktrees/<slugged-branch>
-#    Slug the branch's "/" to "-" so the dir is flat and valid on Windows/macOS/Linux.
-node -e "const p=require('path'),cp=require('child_process');const root=cp.execSync('git rev-parse --show-toplevel').toString().trim();const branch=process.argv[1];const slug=branch.replace(/[\\\\/]/g,'-');const dir=p.join(p.dirname(root),p.basename(root)+'-worktrees',slug);console.log(dir)" "<type>/<issue-number>-<short-desc>"
+It prints one JSON object — read `path` from it:
 
-# 3. Create the worktree + branch off origin/main in one step (the printed path from step 2).
-git worktree add -b <type>/<issue-number>-<short-desc> "<computed-path>" origin/main
+```json
+{"path":"/abs/path/to/repo-worktrees/type-123-slug","branch":"type/123-slug","index":0,"provisioned":true}
 ```
 
-Then `cd "<computed-path>"` and run **every** remaining phase (implement → tests → simplify →
-commit → PR) from there. Report the worktree path to the user. Leave the worktree in place
-after the PR — the user may want to inspect it; note that `git worktree remove "<path>"` cleans
-it up when done.
+Then run **every** remaining phase (implement → tests → simplify → commit → PR) against that
+`path`, and report it to the user.
+
+**A bare `cd` does not stick.** In Claude Code the Bash working directory resets to the project root
+after each call, so `cd <path>` in one call and `npm test` in the next runs the test in the WRONG
+tree — the primary checkout — and everything looks fine until the PR contains no changes. Bind the
+directory to each command instead:
+
+- shell commands — put the `cd` in the *same* call: `cd "<path>" && npm test`
+- git — prefer `git -C "<path>" status` over cd'ing at all
+- file edits — use the absolute path under `<path>`; never a repo-relative one
+
+**Fallback — `flo worktree` not available.** The command ships in the same package as this skill,
+so normally they move together. They can still drift apart: a `flo` binary on PATH older than the
+synced `.claude/skills/`, or a moflo source checkout whose change has not been published and
+reinstalled yet. If the command errors with `Unknown command: worktree`, do NOT stop — create the
+worktree the plain way and continue the run, noting to the user that provisioning was skipped:
+
+```bash
+git fetch origin
+node -e "const p=require('path'),cp=require('child_process');const root=cp.execSync('git rev-parse --show-toplevel').toString().trim();const branch=process.argv[1];const dir=p.join(p.dirname(root),p.basename(root)+'-worktrees',branch.replace(/[\\/]/g,'-'));console.log(dir)" "<type>/<issue-number>-<short-desc>"
+git worktree add -b "<type>/<issue-number>-<short-desc>" "<computed-path>" origin/main
+```
 
-If `git worktree add` fails because the path already exists (a prior run), reuse it:
-`cd "<computed-path>" && git status` and continue, or pick a `-2` suffix — do not delete a dir
-you did not just create.
+The tree is then a valid checkout with no `node_modules` and no gitignored `.env` files — fine for a
+typecheck-only ticket, and not for one that runs the app.
+
+Notes:
+- `--from <ref>` overrides the base ref (default: the repo's default branch via `origin/HEAD`).
+- `provisioned: false` means a copy/link/setup step failed — the worktree is still a usable
+  checkout. Surface the failing step to the user rather than silently continuing to run tests that
+  will fail for want of a dependency.
+- If the branch's worktree already exists (a prior run), `add` reuses it rather than deleting it.
+- Leave the worktree in place after the PR — the user may want to inspect it. Clean up with
+  `flo worktree remove "<branch>"` (it refuses a tree with uncommitted changes unless `--force`).
+  `flo worktree list` shows every worktree and its provisioning state.
 
 ### 3.3 Implement
 Follow the plan from the ticket.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/eric-cielo/moflo/main/docs/Moflo_md.png?v=6" alt="MoFlo" />
+  <img src="https://raw.githubusercontent.com/eric-cielo/moflo/main/docs/Moflo_wide.png?v=7" alt="MoFlo" />
 </p>
 
 # MoFlo
@@ -349,6 +349,89 @@ Inside Claude Code, the `/flo` (or `/fl`) slash command drives GitHub issue exec
 
 Flags compose: e.g. `/flo -sd -m <issue>` runs the SDD cycle and auto-merges. Each modifier has a `--no-*` form (`--no-sdd`, `--no-verify`, `--no-merge`) to override a `moflo.yaml` default for a single run — including `--no-verify`, since verify-before-done is on by default. For full options and details, type `/flo` with no arguments — Claude Code will display the complete skill documentation. Also available as `/fl`.
 
+### Provisioned worktrees (`-w` / `flo worktree`)
+
+Running two tickets at once means two worktrees, and a bare `git worktree add` gives you a valid
+checkout that you cannot actually run: no `node_modules`, none of your gitignored `.env` files, and
+dev servers that fight the primary checkout over the same ports. `/flo -w` drives `flo worktree add`,
+which creates the worktree **and** provisions it.
+
+Provisioning is opt-in per project. **With no `worktree:` block in `moflo.yaml`, `flo worktree add`
+creates the worktree and provisions nothing** — exactly what a plain `git worktree add` would do.
+
+```yaml
+worktree:
+  dir: ../myrepo-worktrees   # default: <repo-parent>/<repo>-worktrees
+  copy: [".env", ".env.*"]   # gitignored files copied from the primary checkout
+  link: ["node_modules"]     # symlinked (junctioned on Windows) from the primary checkout
+  setup: "npm ci"            # run inside the new worktree after copy/link
+```
+
+| Key | Reach for it when | Watch out for |
+|-----|-------------------|---------------|
+| `copy` | A fresh checkout is missing gitignored config your build needs | It relocates **secrets** outside the repo, and outside its `.gitignore`. Sources must live inside the primary checkout — `../secrets` is refused. |
+| `link` | `node_modules` is large and you are not using npm workspaces | A symlinked root `node_modules` is fragile under npm/yarn workspaces — prefer `setup: npm ci` there. An existing path is never clobbered. |
+| `setup` | Install or build steps must run per workspace | A non-zero exit marks the provision failed but leaves the worktree in place. |
+
+**Ports.** MoFlo cannot rewrite your hardcoded ports — it has no way to know which files hold them.
+Instead each worktree gets a small integer, unique among live worktrees and reused when one is
+removed, exported to the `setup` command as `MOFLO_WORKTREE_INDEX`. Offset your own ports from it:
+
+```yaml
+worktree:
+  setup: "npm ci && node -e \"require('fs').writeFileSync('.env.local','PORT='+(3000+Number(process.env.MOFLO_WORKTREE_INDEX)*20))\""
+```
+
+`flo worktree remove` refuses a tree with uncommitted changes unless you pass `--force`, and names
+any gitignored files it discarded that provisioning did not create. MoFlo's own
+`.moflo/worktree.json` never counts as "uncommitted work" — otherwise every worktree it created
+would demand `--force` — but un-pushed specs under `.moflo/specs/` do.
+
+Memory needs no setup at all: durable learnings already converge across a repo's worktrees
+automatically — see [Sharing learnings across installations](#sharing-learnings-across-installations).
+
+#### Running it inside a Claude session
+
+`flo worktree` is a plain CLI command with no MCP wrapper, so it works the same whether you type it
+in a terminal or Claude runs it through Bash. `/flo -w` takes the second path — that is all the flag
+does.
+
+One thing to know if you drive it yourself from a session, and the reason `/flo -w` handles it for
+you: **Claude Code resets the Bash working directory to the project root after every call.** Two
+consequences, both silent when you get them wrong:
+
+```bash
+# ✗ the cd is gone by the next call — this resolves the WRONG repo
+cd path/to/repo
+flo worktree add feature/42-thing --json
+
+# ✓ bind the directory to the call
+cd path/to/repo && flo worktree add feature/42-thing --json
+```
+
+```bash
+# ✗ runs the tests in the PRIMARY checkout; the run goes green and the PR is empty
+cd "$WORKTREE"
+npm test
+
+# ✓ bind it, or skip cd entirely where the tool supports it
+cd "$WORKTREE" && npm test
+git -C "$WORKTREE" status
+```
+
+`flo worktree` resolves the repository from its working directory, so a call made from the wrong
+place targets a different repository — usually reported as `Not a registered worktree of this repo`,
+occasionally as work landing somewhere you did not intend. When editing files in the worktree, use
+absolute paths under the path `add` printed rather than repo-relative ones.
+
+Read the worktree location from `--json` rather than reconstructing it; the sibling-directory
+convention lives in one tested function, and a second copy of that rule will drift from it.
+
+If you are on a `flo` older than the skills synced into `.claude/` — which happens in a MoFlo source
+checkout before a change is published, or when a global `flo` lags the project's devDependency —
+the command reports `Unknown command: worktree`. `/flo -w` falls back to a plain `git worktree add`
+and tells you provisioning was skipped, rather than failing the run.
+
 ### Spec-Driven Development (SDD)
 
 `/flo` can run the full **spec → plan → (review) → implement → verify** cycle — the 2026 agentic-coding pattern — with two independent modifiers. Turning SDD on is opt-in, but once a run is armed for it (via `-sd` or `sdd.default`) **both halves are enforced**: the front half by an implement gate, the back half by verify-before-done.
@@ -637,6 +720,17 @@ flo gate prompt-reminder         # Context bracket tracking
 flo gate session-reset           # Reset gate state
 ```
 
+### Worktrees
+
+```bash
+flo worktree add feature/123-thing   # Create a worktree and provision it (alias: flo wt)
+flo worktree add feature/123 --json  # {"path":…,"branch":…,"index":0,"provisioned":true}
+flo worktree add feature/123 --from v2.1.0    # Branch off a specific ref
+flo worktree add feature/123 --no-provision   # Create it, skip copy/link/setup
+flo worktree list                    # Every worktree and its provisioning state
+flo worktree remove feature/123-thing         # Refuses a dirty tree unless --force
+```
+
 ### Diagnostics
 
 ```bash

package/bin/gate.cjs

@@ -920,10 +920,39 @@ function applyPromptStateReset(state, promptText, opts) {
   state.sddMode = detectSddMode(promptText);
   state.activeSddSlug = null;
 }
-// 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.
-var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|t)(?:[:\s]|$)|\b(?:npx|pnpx)\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\b|(?:^|;|&&|\|\|)\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\s|\b(?:cargo|go|deno|dotnet|mvn)\s+test\b|\bgradle\w*\s+test\b/i;
+// Match npm/yarn/pnpm/bun/turbo/nx/lerna 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.
+//
+// #1484 — the package-manager arm allows a BOUNDED run of selector tokens
+// between the tool and the script name. Every monorepo invocation puts the
+// workspace selection there (`npm run --prefix packages/api test`,
+// `pnpm --filter @acme/api test`, `yarn workspace @acme/api test`), and the old
+// `<pm> [run] test` shape had no slot for it — so a green suite earned no
+// credit and check-before-pr hard-blocked `gh pr create` with no way out.
+//
+// This arm credits the gate, so every way it can over-match is a way the gate
+// fails OPEN. Four properties bound it, and each is pinned by a test:
+//   * separators are HORIZONTAL-only (`[ \t]`, not `\s`). Claude Code runs
+//     multi-line Bash blocks as one string, so a `\s` separator would let
+//     `npm run build\ntest -f dist/x` bridge a newline into the unrelated Unix
+//     `test` builtin and credit a suite that never ran.
+//   * the token class excludes shell separators (; & | < > ( ) $ `) so a match
+//     can never span `npm run build && rm -rf test`, and excludes `#` so a
+//     trailing comment (`npm run build # fix test later`) can't supply the
+//     keyword.
+//   * the class is NEGATED rather than a positive path class. `[-\w=/.:@]`
+//     would pass on POSIX and silently keep missing Windows' `--prefix
+//     C:\repo\pkg` form (Rule #1).
+//   * the `t` alias keeps its own NARROW arm below — reachable only directly
+//     after the package manager, never after selector tokens, so a stray bare
+//     `t` argument (`npm run build --env t`) can't credit the gate.
+// The script name keeps its `(?:[:\s]|$)` terminator, so `test-utils`, `test/`
+// and `dist-tags.test` still don't match. The repetition is bounded at 8 and its
+// character classes are disjoint from the separator, so there is no backtracking
+// blowup (27k-char pathological input: 0 ms).
+var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun|turbo|nx|lerna)[ \t]+(?:[^\s;&|<>()$`#]+[ \t]+){0,8}test(?:[:\s]|$)|(?:^|[^a-z])(?:npm|yarn|pnpm|bun)[ \t]+(?:run[ \t]+)?t(?:[:\s]|$)|\b(?:npx|pnpx)\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\b|(?:^|;|&&|\|\|)\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\s|\b(?:cargo|go|deno|dotnet|mvn)\s+test\b|\bgradle\w*\s+test\b/i;
 // #1322 — failure markers in a test runner's own OUTPUT.
 //
 // This is deliberately not an exit-code check: Claude Code's PostToolUse payload

package/dist/src/cli/commands/index.js

@@ -68,6 +68,11 @@ const commandLoaders = {
     epic: () => import('./epic.js'),
     // Spec-Driven Development artifacts (Epic #1269)
     sdd: () => import('./sdd.js'),
+    worktree: () => import('./worktree.js'),
+    // Alias key, not just `aliases: ['wt']` on the command: lazy commands resolve
+    // through `commandLoaders` by name, and an alias declared only on the command
+    // object is unreachable until something has already loaded it.
+    wt: () => import('./worktree.js'),
     // GitHub Repository Setup
     github: () => import('./github.js'),
     // /flo run ledger + per-run token rollup (#1333).