Add a read-only next tool that reports where work stands and decide the future of open-plans

[fastner]

Problem

Effective Flow only recommends a follow-up at the end of a run: src/shared/next-steps.md emits at most two options from its build-validated edge table, and only the tool that just finished can emit them. A user who returns to a repository after a break has no single tool that answers "what is in flight and what do I run next?".

The closest tool, open-plans (src/tools/open-plans.md, 145 built lines), sees plan files only. It ignores concepts, local review reports with open findings, retained Effective Flow worktrees and delivery branches, staged changes, and an open pull request for the current branch. Its listing also overlaps with apply without an argument: src/tools/apply.md step 3 (none) already lists open plans, local review reports and, on a forge or external tracker, open finding issues, then asks for a source.

open-plans is wired into the rest of Effective Flow: the next-steps rows open-plans | at least one open plan and merge-gate | merged → open-plans, the omission rule at src/tools/merge-gate.md:1378, pointers in plan.md, plan-numbering.md, plan-archival.md, plan-reference-routing.md, apply-source-detection.md and session-title.md, the user guide, and several contract tests.

Proposal

Add a read-only tool, next (the name is still open for review). It collects state, maps that state onto rows that already exist in the next-steps edge table, and recommends at most two invocations with real arguments. It never starts one.

State sources, all read-only:

1. Configuration through the config locator, including the hidden-mode step 0 (plan.dir, concept.dir, tracker.mode).
2. Open plans, plans with an unclear status, and duplicate date-slug names, classified by the single-marker rule in src/shared/plan-status.md.
3. Concepts by their status line (src/shared/concept-contract.md).
4. Local review reports under <RUNTIME_STATE_ROOT>/.effective-flow/review/ that still carry open findings.
5. Worktree lifecycle records and retained delivery branches, read the way cleanup inventories them.
6. Current branch: staged changes, a non-base branch without a PR, and an open PR looked up with the remote helper's pr-list read. If the forge cannot be reached, the report says so and the tool does not guess.

The output is a compact state summary followed by the next-steps block. The priority order is in-flight delivery first (open PR, then retained branch, then staged changes), then open plans, concepts and review reports. Interactive and non-interactive runs behave the same: no questions, no writes.

Explicit decision: how open-plans and next work together. The implementing plan must choose one of these options and record why:

• A. Keep both. open-plans keeps its detailed table and next links to it. Two catalog entries overlap.
• B. Replace (recommended). next absorbs the open-plans table, the status-unclear list and the duplicate notice as one section. open-plans becomes a deprecated forwarding alias to next, per AGENTS.md: an entry in DEPRECATED_TOOL_ALIASES, and a src/tools/open-plans.md that prints one deprecation notice and then follows next verbatim with the arguments unchanged. merge-gate | merged then points to next.
• C. Split. Detailed plan listing moves into apply without an argument, which already lists candidates, and next covers orientation only. The alias target would then be apply, whose none path asks a question, so read-only behavior changes. This option is not recommended.

Acceptance criteria

• The plan records the chosen option (A, B or C) with its rationale before implementation.
• next writes no file, Git state or forge state, and it asks nothing.
• Every recommendation resolves to an existing edge-table row with its real arguments. A state that matches no row produces no recommendation.
• Hidden mode is honoured: plans are read from .effective-flow/plan, and a verified RUNTIME_STATE_ROOT is required.
• An unreachable forge is reported. It does not cause a guessed PR state.
• For option B: invoking open-plans prints the deprecation notice and produces the same listing as before inside the next output. The alias does not appear in the catalog, the router description or argument-hint.
• The next-steps guard, the tool-flow.md mirror guard, the session-title lists and the user guide are updated. pnpm test and node build.mjs pass.

Scope

src/tools/next.md (new), src/tools/open-plans.md, src/shared/next-steps.md, src/tools/merge-gate.md (merged-row omission rule), the shared fragments that name open-plans, build.mjs (TOOL_GROUPS, CONTEXT_BUDGET_LINES, DEPRECATED_TOOL_ALIASES, NEXT_STEPS_EXEMPT_TOOLS if needed), src/shared/session-title.md, the tests listed above, and docs/user-guide/.

Constraints and notes

• Renaming or removing an exposed tool is additive. It ships a deprecated alias with no ! and no BREAKING CHANGE: footer.
• Budget: give next a CONTEXT_BUDGET_LINES entry in the range of today's open-plans, and put each state source behind a lazy-include at its decision point.
• Open question: the next-steps guard requires every emitting tool to have its own row, while next reuses other tools' rows. Either add a narrow next row or extend the guard.
• next-steps.md is reached from merge-gate, and SKILL.md is in merge-gate's load set. This change therefore makes the merge-gate eval evidence stale, and it must be re-recorded before the next release.

Related

• Check mechanical plan-file rules with a deterministic plan-lint script #483: the plan-lint script should classify plan status for next.
• Add a read-only setup status mode that diagnoses configuration and missing domain skills #485: setup status covers configuration health, and next covers work state. Keep the two apart.