fix(obs): remove shadowing dispatcher + binary-precedence guard (Phases 1+2)#460
Merged
Conversation
Phase 1 (Option A): delete dead obs dispatcher + symlink + obs.1 + obs test + inventory refs (fully fixes the live shadowing bug). Phase 2: general binary-precedence guard, elevated to a decision - audit found B1 suffix-strip invariant already false (em<->email-dispatcher, 4 helper files), so B3 post-source self-check is recommended. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The flow-cli obs() dispatcher shadowed /opt/homebrew/bin/obs
(obsidian-cli-ops) but required a python/obs_cli.py flow-cli never
ships, so typing `obs` always errored "Python CLI not found". A shell
function beats a PATH binary in lookup, so the broken dispatcher won in
every interactive shell. The zsh/functions/obs.zsh symlink (sourced
after the dispatcher loop) compounded this when obsidian-cli-ops was
present.
Phase 1 (Option A): delete the dispatcher and scrub every obs
reference, dropping flow-cli from 15 to 14 dispatchers.
- Delete lib/dispatchers/obs.zsh, zsh/functions/obs.zsh, man/man1/obs.1,
and tests/test-obs-dispatcher.zsh.
- Scrub obs from inventories: flow.plugin.zsh, lib/help-compliance.zsh
(15->14 + map), lib/help-browser.zsh, and
commands/{flow,alias,tutorial,doctor}.zsh.
- Remove dangling SEE ALSO obs(1) refs and the flow.1 obs subcommand
block (flow.1, g.1, mcp.1, qu.1, r.1); vendored scribe.1 left as-is.
- Update test suites for 14 dispatchers (help-compliance, dogfood,
atlas-bridge, browser-preview, cli) and remove obs-specific blocks
(legacy obs_help alias, _obs_help direct test, obs src-file case).
After: `type obs` -> /opt/homebrew/bin/obs (no obs() function). Affected
guards green; the man-page coverage guard now derives 14 dispatchers and
requires obs.1 gone.
Deferred: headline "15 dispatchers" docs and Phase 2 (general
binary-precedence guard, form TBD).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 2 (Option B3) of the obs shadowing fix: a general binary-precedence
guard in the dispatcher loader so no future dispatcher can silently mask
an installed binary the way the broken obs() did.
After sourcing each lib/dispatchers/*.zsh, the loader diffs the function
table and unfunctions any newly-defined, non-`_` command whose name
resolves to an external PATH binary (whence -p) — UNLESS:
- it is an intentional shadow: FLOW_INTENTIONAL_SHADOWS=(r mcp cc),
overridable by pre-setting the array (cc launches Claude Code, not
the C compiler; r/mcp are flow's dispatchers), or
- it is forced: FLOW_FORCE_DISPATCHER_<NAME>=1.
The skip is logged under FLOW_DEBUG. Keying on the functions a file
actually defines means no filename convention is needed and `_`-helpers
are ignored automatically — unlike the spec's B1, whose filename->command
guess was already false (email-dispatcher.zsh defines `em`; several
helper files define no command at all).
Adds tests/test-dispatcher-binary-precedence.zsh (16 cases:
drop-on-collision, allowlist/force keep, helper preserved, real r/mcp/cc
survive a live load, obs is not a function) and registers it in
run-all.sh.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Follow-up to the obs dispatcher removal (fix(obs)) and the binary-
precedence guard (feat(dispatchers)). Scrubs the now-removed obs
dispatcher from active documentation and repairs the mkdocs nav left
dangling after tutorials/41-obs-dispatcher.md was deleted.
- Dispatcher count "15" -> "14" across active docs: CLAUDE.md, README,
MASTER-DISPATCHER-GUIDE/API-REFERENCE/ARCHITECTURE, reference/index,
DOC-DASHBOARD, commands/at, REFCARD-TEACH/EMAIL, EMAIL-DISPATCHER-GUIDE,
and 8 tutorial footers (35,37,38,39,40,42,43,44).
- Remove obs from inline dispatcher lists/tables/grammar examples in
CLAUDE.md, MASTER-* guides, PHILOSOPHY, commands/{flow,alias,config},
CONTRIBUTING, getting-started/{quick-start,00-welcome}, index,
QUICK-REFERENCE, ENHANCED-HELP-QUICK-START.
- Remove the deleted obs tutorial's nav entry (mkdocs.yml) and its
mermaid node + table row (docs/tutorials/index.md).
Historical records left frozen per convention: CHANGELOG(.md),
docs/CHANGELOG.md, RELEASES.md, docs/specs/*, and .archive/*.
Verified: mkdocs build --strict passes (exit 0); no dangling links to
41-obs-dispatcher; "obs" as a naming-convention example (CONVENTIONS,
PHILOSOPHY) and the separate zsh/ obs() smart-function are left as-is.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Record the obs removal, the B3 binary-precedence guard, and the 15->14 docs sweep in the session log + Active Worktrees table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ORCHESTRATE-*.md is a feature-branch working artifact; it should not land on dev (per CLAUDE.md merge-cleanup rule). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Data-Wise
force-pushed
the
feature/obs-dispatcher-shadowing
branch
from
ab5cd4f to
1e0ec56
Compare
- Guard: snapshot the function table once around the whole batch instead of
per-file, and use the fork-free ${commands} hash instead of $(whence -p).
Eliminates the ~10ms startup overhead (59ms -> ~46ms); test still 16/16.
- Docs: scrub stray 'obs' dispatcher refs missed by the sweep
(getting-started/00-welcome 8->14 list, CONVENTIONS, PHILOSOPHY).
- CLAUDE.md: document FLOW_INTENTIONAL_SHADOWS + FLOW_FORCE_DISPATCHER_<NAME>
with the empty-array override caveat.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Enforces the documented footgun: an explicitly-emptied allowlist (set, not
unset — zsh ${+arr} is 1 for empty arrays) skips the (r mcp cc) default, so a
default-protected shadow like cc is dropped; unset keeps it. Both run in a
fresh `zsh -f` because the guard only acts on functions new to the source
pass — re-sourcing an already-loaded shell would be a no-op. 16 -> 18 cases.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Data-Wise
pushed a commit
that referenced
this pull request
Jun 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
flow-cli's
obsdispatcher shadowed the real Homebrewobs(obsidian-cli-ops) but required apython/obs_cli.pyflow-cli never ships, soobsalways errored. A shell function beats a PATH binary, so the broken dispatcher won in every interactive shell.Phase 1 — remove the dead dispatcher (
222c43b2)Delete
lib/dispatchers/obs.zsh,zsh/functions/obs.zsh,man/man1/obs.1,tests/test-obs-dispatcher.zsh; scrubobsfrom inventories (flow.plugin.zsh, help-compliance/browser,commands/{flow,alias,doctor,tutorial}.zsh) and dangling SEE ALSOobs(1)refs. 15 → 14 dispatchers. After:type obs→/opt/homebrew/bin/obs.Phase 2 — general binary-precedence guard (
f28b7007)_flow_load_dispatcherwraps eachlib/dispatchers/*.zshsource,unfunctions any new command that resolves to a PATH binary unless inFLOW_INTENTIONAL_SHADOWS=(r mcp cc)orFLOW_FORCE_DISPATCHER_<NAME>=1. Keys on real defined names (skips_*helpers; no filename convention). New guard testtests/test-dispatcher-binary-precedence.zsh(16/16).Docs (
67b0071d)15 → 14 dispatcher sweep across ~30 active files + mkdocs nav repair (
mkdocs --strictclean). Historical CHANGELOG/RELEASES/specs/.archive left frozen.Companion work
The
obs.1man page is re-homed inData-Wise/obsidian-cli-ops#25; Homebrew install inData-Wise/homebrew-tap#110.Verification
Full suite: 58 passed, 1 pre-existing unrelated failure (
dogfood-scholar-config-sync, fixed separately in #459), 1 expected timeout (e2e-em-dispatcher).🤖 Generated with Claude Code