feat(config-upgrade): NeedsJudgment sniffer for the zen pr-merge double-merge; port live zenmode fix to shipped defaults

[jlong]

HELD — do not dispatch until the live zenmode.md change (applied in the shelbi project 2026-08-16, dropping zen pr-merge from the review->done finalize path) has proven out over a few real Zen merges. This makes the fix reach all projects, not just new ones, via the config-upgrade self-heal channel.

Problem

For a workflow whose review -> done transition already merges (e.g. app: actions: [merge, delete_branch], merge_strategy: squash), the Zen instructions told the orchestrator to run shelbi zen pr-merge AND then move the card to done. That double-merges: zen pr-merge squash-merges + deletes the branch, then the transition's merge action finds the branch already merged and fails ("branch not on origin" / empty-commit), stranding the card in review even though the work shipped. Reported by more than one orchestrator, so it is systemic.

The corrected policy (already live in this project's zenmode.md): the workflow transition OWNS the merge. Zen gates (self-review + zen ci-watch green) and then triggers the transition via shelbi task move <task> --to done. It does NOT run zen pr-merge. zen pr-merge stays only for the Release flow (external bump / Homebrew tap PRs, not governed by a review->done transition).

Why a config-upgrade sniffer (not just a template edit)

Shelbi copies its default zenmode.md and orchestrator instructions.md into each project at shelbi init; after that the project owns its (user-editable, self-heal-preserved) copy. So editing the shipped template ONLY reaches NEW projects. Existing projects keep the deprecated forked text. The config-upgrade pass is the vehicle that repairs existing installs on boot.

Deliverables

1. Config-upgrade sniffer in crates/shelbi-cli/src/commands/config_upgrade.rs, classified NeedsJudgment (prose is user-customizable; no safe deterministic rewrite). Surfaces are already enumerated in config_surfaces.rs: project.<name>.zenmode (zenmode.md) and project.<name>.agent.orchestrator.instructions (instructions.md), both SurfaceFormat::Markdown.
   • Detection (conservative content-sniff): a zenmode.md/orchestrator-instructions surface whose merge/finalize prose instructs running shelbi zen pr-merge as part of the ordinary review->done finalize (i.e. zen pr-merge present in the merge-conditions steps together with a subsequent "move ... to done"), in a project that has a workflow whose review -> done transition contains a merge action. Do NOT flag the Release-flow zen pr-merge usage.
   • Finding message: explain the double-merge hazard. proposed_fix: the corrected gate-then-transition policy (drop zen pr-merge; gate via zen ci-watch; finalize via task move --to done). The orchestrator repairs its own copy with judgment, preserving customizations, then applies via the existing --apply-finding <id> path if a targeted apply is wired.
   • No FINDINGS_SCHEMA_VERSION bump expected (same finding shape).
2. Shipped default templates updated so NEW projects ship the corrected text (belt-and-suspenders; the sniffer then won't fire on fresh installs): the default zenmode.md template and the default orchestrator instructions.md template (crates/shelbi-state/src/default_orchestrator.md.template and the shipped zenmode.md default) — replace the pr-create -> ci-watch -> pr-merge -> move-to-done sequence with the gate-then-transition sequence, keeping zen pr-merge documented for the Release flow.
3. AGENTS.md guardrail — add this section to the root AGENTS.md (verbatim), so agents never again change a default without a matching self-heal path:

## Changing shipped defaults (existing installs don't get them for free)

Shelbi copies its default agent instructions, `zenmode.md`, workflows, keys, and
other config into each project at `shelbi init`. After that the project owns its
copy — users edit them freely and Shelbi's self-heal preserves those edits. So
**editing a shipped default template only reaches NEW projects.** Every
already-initialized project keeps its forked copy untouched.

When you change a default that existing projects should adopt, pair the template
edit with a **config-upgrade sniffer** so existing installs self-heal on next
boot (`crates/shelbi-cli/src/commands/config_upgrade.rs`; surfaces in
`config_surfaces.rs` already include `zenmode.md`, per-agent `instructions.md`,
workflows, and the global/project YAMLs):

- **Auto-healable** (deterministic, non-lossy rewrite): add an `AutoHeal` sniffer
  plus its write-back in `config_upgrade_apply.rs`. The on-start pass applies it
  and discloses a `config-upgrade` line per project on `events.log`.
- **Needs judgment** (user-customizable prose, ambiguous, or potentially lossy —
  most instruction / `zenmode.md` changes): add a `NeedsJudgment` sniffer. It is
  written to the findings file the orchestrator ingests at boot, and the
  orchestrator repairs its own copy with judgment, preserving customizations.
  When unsure, classify `NeedsJudgment` rather than risk a lossy auto-heal.

A PR that edits a `*.template` / default config (or a shipped workflow /
instructions file) but adds no config-upgrade sniffer is incomplete for existing
users. Ship both.

Acceptance Criteria

• A project whose zenmode.md (or orchestrator instructions.md) still instructs the zen pr-merge-then-move-to-done double-merge produces a NeedsJudgment config-upgrade finding on hub start / shelbi reload.
• The finding is scoped per project, names the surface, and its proposed_fix states the gate-then-transition policy.
• Release-flow zen pr-merge usage does NOT trigger a finding.
• A project already on the corrected text produces no finding (no false positive).
• Shipped default zenmode.md and orchestrator instructions.md templates carry the corrected flow, so a fresh shelbi init yields no finding.
• The ## Changing shipped defaults ... section above is present in the root AGENTS.md.
• cargo build/test/clippy green; new sniffer covered by a unit test (detects deprecated text, ignores corrected text and release-flow usage).

---

Auto-opened by Shelbi — review at: /Users/jlong/.shelbi/projects/shelbi/tasks/zen-finalize-merges-via-the-review-done-transition-not-zen-pr-merge-port-live-zenmode-fix-to-shipped-defaults.md

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shelbi	Ready	Preview	Aug 16, 2026 9:37pm