Troubleshooting
Common recovery patterns for stuck tasks, broken state, and review-backend conflicts. For deeper subsystem guides see the flowctl CLI reference, flow —auto, and the source repository.
Updated the plugin: do I re-run setup?
Section titled “Updated the plugin: do I re-run setup?”No. Setup copies nothing into your repo, so a plugin update (/plugin update, droid plugin update, or git pull + re-install on Codex/Cursor) is the whole update: every skill resolves flowctl from the plugin install itself, and the agent guide comes from flowctl usage. Re-run /flow-next:setup only when setup tells you the docs-snippet schema bumped, or when you want to change configuration or re-seed the user-owned files. It stays idempotent and non-destructive - your specs, tasks, memory, and config are untouched.
I have .flow/bin/ from an old install
Section titled “I have .flow/bin/ from an old install”Delete it. .flow/bin/, .flow/templates/spec.md, and .flow/usage.md are snapshots from the retired copy layout; nothing reads them, and removing them changes nothing observable in any workflow. One exception before you bulk-delete: a .flow/templates/spec.md you EDITED is your content - copy it to a repo-root SPEC.md first (that is the customization point now); setup’s cleanup offer detects a differing template and never deletes it for you. Keeping leftovers is a hazard, not a safety net - a stale copied flowctl can shadow the current one, and a flowctl flag that “should exist” erroring is the classic symptom. /flow-next:setup detects the leftovers and offers to delete them (/flow-next:plan prints a one-line nudge and moves on); you can also remove them yourself (use git rm for tracked copies).
Leftovers after upgrading to 7.0
Section titled “Leftovers after upgrading to 7.0”- A one-line
note:about removed keys. A config that still setspipeline.chainStagesorartifacts.html.enabledkeeps working: flowctl ignores the key and prints one non-blocking line naming it, when you read or set config or start work. Remove the key from.flow/config.json. Under--tick, make-pr now runs on the next tick; for a visual view of a spec, plan, or diff, run/flow-next:visualor ask the agent for an HTML page. Old.flow/artifacts/<spec-id>/spec.htmlandpr.htmlfiles are yours to delete. - Ralph files and hooks. Ralph was removed in 7.0. If you still run it, pin flow-next 6.7.x. Otherwise delete
scripts/ralph/and anyralph-guardhook entries from your project settings, and run/flow-next:flow --autowhere your Ralph loop ran (Migrating from Ralph). judge: offin the output. Expected without a TypeSafe key, or withjudge.enabledset tofalse. Flow prints it once per run and skips the optional fork hint; routing and the QA gate never ask the judge, so nothing else changes (Jev judge).
Leftovers after upgrading to 8.0
Section titled “Leftovers after upgrading to 8.0”RepoPrompt review (rp, export) was removed in flow-next 8.0.0. Something still namesrporexport:review.backend,FLOW_REVIEW_BACKEND, a spec’s or task’s review setting, or a--review=in a script or prompt. Review runs as if no reviewer were configured until you pick one:flowctl config set review.backend codex(orhost,claude,copilot,cursor), orflowctl spec set-backend <spec-id> --review codexfor a pinned spec. See Review backends.- Export Context still listed. Re-run the Codex, OpenCode or Cursor installer; it drops the removed skill. Claude Code, Droid and Grok pick it up from the plugin update.
- A script fails on
flowctl review-rounds record. Pass--backend(host workflows pass--backend host); it no longer defaults torp. - A script reads
plan_review_status: stale. Treat it likeneeds_work: the spec changed after its SHIP, and plan-review runs again before work.
Two specs share the same number (fn-122 twice)
Section titled “Two specs share the same number (fn-122 twice)”Symptoms: flowctl validate --all reports a duplicate ordinal, or bare fn-122 refuses to resolve and lists two candidates.
What it means: two full ids like fn-122-foo-bar and fn-122-other-slug exist. The full id is the identity (filesystem path, branch, task ids). A shared ordinal is untidy, not broken - validate treats it as a warning, not a root error.
What to do:
- Do not renumber. Ids never change. They already live in commits, branches, tags, PR bodies, tracker comments, and memory entries you cannot rewrite safely.
- Prefer the full slug when the bare form is ambiguous. The resolver lists candidates and requires the full id (same idea as git short-hash disambiguation).
- Avoid it next time. With a tracker configured, set the team default so new specs mint from the issue key instead of racing on
fn-N:
flowctl config set tracker.specIds trackerNative allocation is also wider than it used to be - it scans every registered worktree and every ref, not only the local working tree - which closes most same-repo parallel creates. Separate clones that have not fetched each other can still collide; that is what tracker-keyed ids are for. Details: Collaboration, Tracker Sync.
Reset a stuck task
Section titled “Reset a stuck task”# Check task statusflowctl show fn-1.2 --json
# Reset to todo (from done/blocked)flowctl task reset fn-1.2
# Reset + dependents in same specflowctl task reset fn-1.2 --cascade--cascade walks the spec’s depends_on graph and resets every downstream task that referenced the target, so the next flowctl ready call surfaces them again.
Clean up .flow/ safely
Section titled “Clean up .flow/ safely”Run manually in terminal (not via AI agent - destructive command guards block agents from running rm -rf):
# Remove all flow state (keeps git history)rm -rf .flow/
# Re-initializeflowctl initOr run /flow-next:uninstall to clean up docs and get the commands printed for manual execution.
Review loop stalls, repeats unchanged work, or runs away
Section titled “Review loop stalls, repeats unchanged work, or runs away”Symptoms: a plan/impl/completion review loops far more than the round cap - the field report was ~11x on a large ticket before the reviewer and implementer converged. Most common on the Cursor review backend, but the underlying causes were backend-agnostic.
How it is bounded now:
- One fix pass, one re-review when you are there. An attended
NEEDS_WORKverdict gets one fix pass and one scoped re-review, and that re-review’s verdict is final. A longer loop runs only unattended (flow --auto) or when you ask for review until SHIP, bounded by flowctl’s round cap and stall check. - An author override ends an unattended loop that only hardening keeps alive. When the reviewer keeps only findings the author declined (hardening, scope creep, or problems that existed before the change), all below Major, the run ends the loop itself and records each disagreement, with both sides’ reasons, in the Decisions list and the pull request. A finding that shows a stated requirement broken is always fixed.
What was happening before (root causes, now bounded):
- The cap was prose-only and reset every invocation.
MAX_REVIEW_ITERATIONS(then default 4; now 8) was an instruction to the host LLM to keep an in-context counter - but it reset to 0 on every fresh review invocation (a newflow --autoinvocation, a human retry). The runaway was about 5-6 fresh invocations x ~3 in-agent rounds. Now flowctl owns a cumulative counter on spec state that survives fresh invocations and refuses at the cap (exit4+ESCALATE:). - Every re-review was a fresh blind review (a churn lottery - two identical fresh Cursor reviews overlapped on only ~50% of findings, so SHIP was statistically near-unreachable within the cap). The convergence ratchet now renders the validated structured findings (severity, classification, status) with labeled legacy prose only as fallback. Its shrink-only contract remains: verify each prior finding fixed; only a NEW >= Major finding may block; all prior fixed + no new >= Major means MUST SHIP.
- Codex/copilot verdicts could be poisoned by a verdict literal echoed in tool output (e.g. a grep of
smoke_test.sh’s assertions), making flowctl report SHIP while the reviewer said NEEDS_WORK - a false SHIP or a false NEEDS_WORK that kept a loop alive. The parse now isolates the final agent message (last-match). - Cursor’s ambient injection (its built-in persona rubric + auto-attached
AGENTS.md) diluted the scope anchor. A persona-override preamble now rides in every cursor review prompt (see Orchestration).
What the loop can do on its own now: the cap reads the structured findings each verdict persists and ends a measurably stuck loop early - exit 4 with ESCALATE: review loop stalled (same-not-fixed-lineage) once the reviewer has marked the same finding not-fixed in three consecutive rounds. The verdict and receipt are recorded first, and a round is never refused for it, so a fix committed after the second not-fixed is always reviewed - and a reviewer can return NEEDS_HUMAN when the next step is a judgment call, which persists its receipt and status before exiting 4 with ESCALATE: reviewer requested human review. Re-dispatching an unchanged artifact is refused before it costs a round (NOT_RETRYABLE: artifact unchanged since last verdict, exit 1).
What to do when it escalates:
NOT_RETRYABLE(exit1) consumed nothing. Change the actual reviewed artifact, or decide as a human whether an explicit re-plan is warranted - do not blindly retry.- Either
ESCALATE:variant (exit4) is NOT retryable. Underflow --autoit surfaces as NEEDS_HUMAN. Inspect the persisted receipt and findings trail, then decide: redesign, focused fix, or re-plan (the reviewer strictness is often signal - big/ambiguous plans really do re-fail). - After an explicit re-plan (you rewrote the spec/approach, not just patched a finding), a human can reset the counter to re-open the cap:
flowctl spec reset-review-rounds <spec-id>(add--implto also clear per-task impl-review counters). ASHIPverdict resets automatically. Reset commands and--forceare human-only recovery tools, never autonomous ones. - The default cap is 8. Tune it with
flowctl config set review.maxIterations <n>(envMAX_REVIEW_ITERATIONSwins) for a genuinely large ticket, but the cap stays enabled and escalation stays preferable to a larger budget. - Full semantics: flowctl CLI reference.
flow --auto stopped: strikes and a dirty tree
Section titled “flow --auto stopped: strikes and a dirty tree”Two flow --auto terminals need a human by design. Both apply to flow --auto --tick, which replaced the /flow-next:pilot command.
BLOCKED with strike 2/2. A hop that dispatched a stage and advanced nothing observable (a make-pr hop with no open PR for the branch afterwards, or a qa hop with no fresh receipt) records a strike in the ledger at <git-common-dir>/flow-next/pilot-strikes.json. The first strike leaves the spec ready and ends the run:
PILOT_VERDICT=BLOCKED spec=<id> stage=<stage> reason="no advancement (strike 1/2): <why>"The second strike unreadies the spec, keeps the ledger reason, and names the clear command inside the reason string:
PILOT_VERDICT=BLOCKED spec=<id> stage=<stage> reason="no advancement (strike 2/2, spec unreadied): <why>; clear with: flowctl pilot strikes clear <id>"Read <why> and fix the cause. What clears the strike depends on where readiness comes from.
Local repos (tracker.readyState unset). Re-blessing is the human reset. Run flowctl spec ready <spec-id>; at the next selection the run reads a struck spec that is ready again as human re-blessed, clears its ledger entry, and treats it as fresh. flowctl pilot strikes clear <spec-id> also works, and flowctl pilot strikes list shows what is struck.
Tracker-connected repos (tracker.readyState set). The next pull re-readies the spec from the board on its own, and a board echo is byte-identical to a deliberate move in every durable artifact, so a projection-set ready never clears the strike. Only the verb does:
flowctl pilot strikes listflowctl pilot strikes clear <spec-id>Clearing a strike never changes readiness; the board owns that.
NEEDS_HUMAN with a dirty tree. flow --auto refuses to start, and stops after any hop, when the working tree is dirty outside .flow/. The run-start form:
PILOT_VERDICT=NEEDS_HUMAN spec=- stage=- reason="dirty working tree at tick start"The run leaves state untouched: no cleanup, no claim reset, no strike. Commit or stash the change and invoke again. The next run classifies from disk (committed receipts, the ledger, the branch), so nothing the interrupted run recorded is lost.
Review reports a model downgrade or floor
Section titled “Review reports a model downgrade or floor”Symptom: a review prints one stderr line like
warning: codex model '<ranking-top id>' unavailable; downgraded to '<available id>'. Cached for this CLI version.(or ... fell back to the never-fail floor (the CLI default / 'auto')), and the review’s receipt records the downgraded id / auto / default rather than the ranking top.
This is expected, not an error. Flow-Next dispatches the strongest model by default and, when the local CLI can’t run it, transparently resolves the best available one (the model-resolution ladder). It fires ONLY on the distinctive model-unavailable signature (codex “requires a newer version of Codex”, copilot ... from --model flag is not available, cursor Cannot use this model: ..., claude an exit-0 error payload whose text names the selected model, or the [claude-code:unrecognized_model] stderr tag); auth / network / sandbox / timeout failures propagate unchanged.
What to do:
- Want the top model? Upgrade the backend CLI. The cache key is
(backend, CLI version), so the upgrade re-resolves automatically on the next review. - The downgrade repeats every review? It shouldn’t - the result is memoized in
.flow/.cache/model-resolution.json. If it does, that file may be unwritable (check permissions) or you’re on a fresh CLI version each run. - Force a specific model (skip the ladder + cache entirely): pin it explicitly -
--spec codex:<model-id>, a per-task/per-specreview:value,FLOW_CODEX_MODEL, orreview.backend. An explicit unavailable model errors clearly instead of downgrading. - Reset the cache:
rm -rf .flow/.cache/- it is regenerated (and gitignored) on the next review; a corrupt file is already treated as a cold start.
Review stops on a usage or credit limit
Section titled “Review stops on a usage or credit limit”Symptom: a review returns no verdict within seconds, and each failed draw’s line ends with the reviewer CLI’s own words, for example:
correctness: nonzero_exit CLI message: Your workspace is out of credits. Add credits to continue.What it means: the reviewer CLI answered, but its account hit a usage, credit or spend limit. The backend itself is healthy. Flow-Next records that last message (the last codex error event, or the last output line on the other CLIs) on the attempt row and prints it after CLI message: in the failure line and in the TRANSPORT_UNHEALTHY text. When the message reports a limit, the review skills stop with it instead of retrying.
What to do: top up or wait for the limit to reset, or switch reviewer for this run with --review=<backend>, then run the review again. Any other transport failure keeps the usual rule: one retry, then repair the backend. A failed re-review keeps the open findings, so the next run goes back to the fix instead of stopping on lost_receipt.
Windows: python3 not found / Microsoft Store alias stub
Section titled “Windows: python3 not found / Microsoft Store alias stub”Symptom: on Windows, flowctl fails with “Python was not found; run without arguments to install from the Microsoft Store…” and exit code 9009, even though you installed real Python.
Cause: python3 resolves to the Microsoft Store App Execution Alias - a 0-byte reparse point at %LOCALAPPDATA%\Microsoft\WindowsApps\python3.exe that Windows ships enabled by default. When your real Python came from python.org or the py launcher (not the Store), the stub shadows it: it satisfies command -v python3 (it is on PATH) but is non-functional. Older flowctl launchers trusted presence over function and picked the stub - so flow-next broke on every Windows machine in this configuration.
The shipped fix (no action needed on a fresh install): the flowctl launchers now probe interpreter functionality - each candidate must actually run <cand> -c "import sys" and exit 0 - in order $PYTHON_BIN then py -3 then python3 then python, so the 9009 stub is skipped. A flowctl.cmd batch shim ships alongside the extensionless bash flowctl, so PowerShell / cmd.exe (Claude Desktop, native Codex, native Cursor) resolve a working interpreter too.
Recovering a legacy copied install (a pre-fix .flow/bin/flowctl hardcodes exec python3 and cannot fix itself). This only applies to repos still carrying the retired copy layout. Pick either:
-
Delete the copy (recommended, durable). The plugin’s own launchers already carry the fix, and nothing reads
.flow/bin/any more:Terminal window Remove-Item -Recurse -Force .flow\bin # git rm -rq .flow/bin if it is trackedAfter this,
flowctl(Git Bash / WSL) and theflowctl.cmdsibling (cmd.exe / PowerShell) resolve from the plugin install. The copy-less chain is untested live on Windows - best-effort; report breakage./flow-next:setupoffers the same deletion interactively. -
Disable the Store alias (per-machine OS workaround). Settings, then Apps, then Advanced app settings, then App execution aliases: toggle OFF for
python.exeandpython3.exe.python3then resolves to your real install. Note thepylauncher is not included with Store Python, so if you were relying on Store Python, install python.org Python (which shipspy) to getpy -3.
Prefer path 1 - the alias toggle is per-machine, not durable, and does not survive a fresh Windows profile.
Sources: Microsoft Learn Python on Windows FAQ (the App Execution Alias stub + “the py launcher is not included with Store Python” + disabling the alias); python.org Using Python on Windows and PEP 397 (the py launcher / py -3).
Windows: values read from jq end in a carriage return
Section titled “Windows: values read from jq end in a carriage return”Symptom: on Git Bash, a path or id that came from jq -r matches no file (fatal: pathspec '...json?' did not match any files), or a comparison such as == "true" is false with no error.
Cause: the Windows build of jq.exe ends each output line with CRLF. read and command substitution drop the newline but keep the carriage return, so every value carries a trailing \r.
Since 8.5.0, make-pr and resolve-pr handle it: their scripts strip the carriage return from jq output. Shell steps inside other skills still call jq directly. If one of them misbehaves, put a shim earlier on PATH, for example ~/bin/jq, that switches jq to LF output (jq 1.7+):
#!/usr/bin/env bashexec "/path/to/jq.exe" --binary "$@"/flow-next:map: clawpatch not found / version mismatch / Node 20
Section titled “/flow-next:map: clawpatch not found / version mismatch / Node 20”/flow-next:map wraps the upstream clawpatch CLI. Common failure modes:
1. clawpatch binary missing. Skill prints pnpm add -g clawpatch install instructions verbatim and exits 1. No auto-install - global npm/pnpm installs are user-consent territory.
# Recommended: install globally with pnpmpnpm add -g clawpatch2. pnpm installed clawpatch but it’s not on PATH. pnpm installs global binaries under $PNPM_HOME and needs a one-time pnpm setup to wire PATH - without it, the install lands but the binary isn’t resolvable. (Exact location varies by pnpm version and OS: ~/.local/share/pnpm on many setups, $PNPM_HOME/bin/ on others - pnpm bin -g reports yours.) Skill detects pnpm bin -g exit-0 + command -v clawpatch exit non-zero and prints the PNPM_HOME hint:
pnpm setup # writes PNPM_HOME + adds it to your shell rcsource ~/.zshrc # or ~/.bashrc - pick up the new PATH entrycommand -v clawpatch # should now resolve3. clawpatch --version falls outside the tested range. The skill carries a single-source SUPPORTED_CLAWPATCH version range in its prose. Outside range emits a one-line stderr warning naming expected vs found and continues (degrades - never blocks). Re-pin lands on each clawpatch minor.
4. Node 20 with clawpatch installed. clawpatch’s engines.node: ">=22" triggers its own error; the skill propagates it verbatim. Upgrade Node 22+ (e.g. nvm install 22 && nvm use 22) or skip /flow-next:map - scouts gracefully fall back to the grep/glob path when .clawpatch/ is absent.
5. “Should I commit .clawpatch/ to the repo?” No - by default the skill writes a .clawpatch/.gitignore with * + !.gitignore, making the feature index local-per-developer. The map is regenerable from clawpatch map, the schema may flip between pre-1.0 minor releases, and committing it creates PR review noise + merge conflicts. The full trade-off table is on the Map skill page. Teams that want shared indexes can customize the skeleton - unsupported, but the skill won’t clobber a customized .gitignore on re-run.
The skill is opt-in convenience - flowctl core never imports or requires clawpatch; nothing else in flow-next breaks when the skill can’t run.
Uninstall
Section titled “Uninstall”Run manually in terminal (DCG blocks these from AI agents):
rm -rf .flow/ # Core flow staterm -rf scripts/ralph/ # only if you ran Ralph on 6.7.x or earlierOr use /flow-next:uninstall which cleans up docs and prints commands to run. Doc cleanup removes two independent marker blocks from CLAUDE.md/AGENTS.md: the <!-- BEGIN FLOW-NEXT --> … <!-- END FLOW-NEXT --> instructions block and, if /flow-next:setup scaffolded one, the <!-- flow-next:model-routing:start --> … <!-- flow-next:model-routing:end --> model-routing block (removed only when its marker pair is well-formed - a damaged pair is reported and left untouched). GLOSSARY.md and STRATEGY.md at the repo root are intentionally preserved - they outlive flow-next per the survives-uninstall invariant.
Cursor in-IDE browser MCP missing (cursor-ide-browser)
Section titled “Cursor in-IDE browser MCP missing (cursor-ide-browser)”On Cursor, drive / QA probes the built-in browser by MCP id cursor-ide-browser. A catalog miss is not absence.
- Settings → Tools & MCP → Browser Automation = Browser Tab.
- Type
@Browserin chat (no space), or open the Browser pane until it shows connected. - Let the agent re-probe once. Do not loop.
A mid-run MCP server does not exist: cursor-ide-browser after the pane was already driving is a known Cursor flake. @Browser does not restore that session - quit Cursor fully, wait ~10s, confirm the pane is connected, start a fresh chat. See Flow-Next Drive and Install → Cursor.
Muse Code: review says “no verdict” or NEEDS_HUMAN
Section titled “Muse Code: review says “no verdict” or NEEDS_HUMAN”The reviewer CLI (codex, copilot, cursor or claude) could not run inside Muse’s sandbox, which keeps your home directory read-only while those CLIs write to theirs (for example ~/.codex). Flow-Next records that as NEEDS_HUMAN or “no verdict”, never as a pass. Quit the session and start Muse with the sandbox off, then re-run the review:
muse --disable-sandbox # interactivemuse exec --disable-sandbox ... # headlessMuse’s approval judge stays on. Do this only in an environment you already trust. review.backend host fails closed on Muse for a different reason (Muse reaches one model family natively), so pick a CLI backend. See Install → Muse Code.
Muse Code: only some agents run, or a generic agent does the work
Section titled “Muse Code: only some agents run, or a generic agent does the work”Flow-Next was installed through muse plugins marketplace add. That installs the canonical plugin, whose agent definitions Muse cannot spawn (19 of 21), and setup does not detect Muse. Install with the installer instead, from a checkout of the repo:
git clone https://github.com/gmickel/flow-next.git && cd flow-next && ./scripts/install-muse.shIt builds a Muse copy with translated agent definitions, installs it and approves its agents. Then run /flow-next:setup once in the project. See Install → Muse Code.
A stale skill name survives an upgrade
Section titled “A stale skill name survives an upgrade”A cached install can keep surfacing a skill under its old name after a rename (browser became flow-next-drive in 1.4.0). It auto-clears within about seven days as the plugin cache refreshes. To clear it immediately, delete the stale cached marketplace directory under your host’s plugin cache path and reload the host.
rm -rf ~/.claude/plugins/cache/<marketplace> # then reload Claude CodeLand on a chain: chain broken, a retarget conflict, or a pending merge-async
Section titled “Land on a chain: chain broken, a retarget conflict, or a pending merge-async”Land takes one named pull request and merges only the lowest open layer of a chain (Chains and stacks). Where GitHub stacks are available it links open children into a native stack before merging, and GitHub retargets the layer above. Land itself never rebases, force-pushes or retargets a child.
A child needs a rebase. When stacks are unavailable, or a catch-up conflicts, land reports the exact branch and stops. After the parent is confirmed merged, recover only that child, in a clean, dedicated checkout. Confirm the intended base and the parent’s pre-merge tip from its PR history. For a squash merge that tip is the boundary to drop; the parent’s squash commit is not. Check that the boundary is an ancestor of the child and read the commits above it before you rewrite anything. Do not guess if the parent was itself rewritten.
This is a manual recovery that you authorize separately; it is not a land step. Replace every placeholder with a verified value:
git fetch origingit switch <child-branch>git status --short # require a clean checkoutgit rev-parse origin/<child-branch> # record as <expected-child-sha>git merge-base --is-ancestor <parent-pre-merge-tip> HEADgit log --oneline <parent-pre-merge-tip>..HEADgit rebase --onto origin/<intended-base> <parent-pre-merge-tip> <child-branch># Resolve the reported files, git add those files, then git rebase --continue.# To abandon recovery and restore the original branch: git rebase --abort.# Run the child's focused checks before publishing.git push --force-with-lease=refs/heads/<child-branch>:<expected-child-sha> origin HEAD:refs/heads/<child-branch>gh pr edit <child-PR> --base <intended-base>If the lease fails, inspect what changed on the remote; do not overwrite it or retry with a freshly guessed lease. Then land that child explicitly. Land re-reads its head, its closed specs, its checks and its reviews; a comment on the old head does not carry over. Do not cascade the rewrite through grandchildren: each remaining layer needs its own inspection and authorization. Keep a parent branch while any open pull request still targets it.
A parent closed unmerged. Decide whether to reopen the parent or keep its changes in the child before you choose a rebase boundary. Dropping its commits as if they had merged can lose work. Land makes neither decision for you.
A stack merge is pending. RESOLVING means success is unconfirmed. Land stores no merge id and no polling state, so the next invocation re-reads the named pull request and its stack. A moved head needs fresh gating. Only a confirmed merged state with a merge commit is success, and branch deletion follows that confirmation plus a fresh check that no open pull request still targets the branch.
My scheduled /flow-next:land loop stopped finding pull requests
Section titled “My scheduled /flow-next:land loop stopped finding pull requests”Symptom: a bare or scheduled /flow-next:land prints LAND_VERDICT=NEEDS_HUMAN prs=0 pr=- reason="no pull request".
Why: land no longer discovers pull requests. It takes one you name, and it merges only with authorization given in the current session. Replace the recipe with a loop you own: list the candidates, call land on each, and put the instruction to land them in the prompt. Copy-paste blocks are on the land loop.
Land printed a notice about ignored land.* keys. That is expected. Eight keys are retired, the config still loads, and land leaves the file unchanged. The list and each replacement are on Retired keys. Old land ledger and claim files under .git/ are inert and need no cleanup.
Land stops at merge-ready; authorization required. The pull request is repaired and ready, and nobody authorized the merge in this session. Merge it yourself, or ask for it: “land PR 123”. A receipt, an environment variable or text in the pull request cannot grant it.
See also
Section titled “See also”- flowctl CLI reference - every command, flag, default
- Platform notes - platform-specific gotchas (Droid, Codex, Cursor, OpenCode, Muse Code)
- Glossary - the canonical vocabulary