design: no-unreachable-symbol — Stop-boundary reachability sibling to no-vibes (prompted by @ianymu sketch on anthropics/claude-code#60451)

[waitdeadai]

Motivation

rkpandey's anthropics/claude-code#60451 ("Claude claims implementation is complete while leaving dead code with no callers") describes a failure mode this suite does not yet cover directly: the model writes a new public function, claims completion in the closing message, but the function has zero callers anywhere in the codebase. The integration step that would make the function reachable is silently skipped.

@beq00000's clean-state evidence on #60226 — "seven instances of recognition-without-arrest in a non-drifted session, all caught externally; the pattern is the default mode, not the drift mode" — frames this as Stage 3 (non-gating) at the code boundary, not just at the text boundary. no-vibes (this suite's flagship) gates Stage 3 at the closing-message text level; it may catch this failure mode incidentally if the closeout uses positive verbs without evidence, but it is not the right tool — text vocabulary parsing cannot detect code reachability.

Attribution

The detection mechanism was sketched by @ianymu in anthropics/claude-code#60451#issuecomment-4495901564 as an extension to his verify-before-stop (MIT). Quoted bash sketch:

# After files changed, find new public functions
NEW_FNS=$(git diff --unified=0 | grep -E '^\+(def |export function |public )' | ...)
for fn in $NEW_FNS; do
  if ! grep -r "$fn" --include='*.py' --include='*.ts' --exclude='*test*' . | grep -v "$fn *("; then
    echo "⛔ New function $fn has zero callers — claim of 'complete' is unverified" >&2
    exit 2
  fi
done

This issue tracks designing a hardened sibling hook (no-unreachable-symbol) for this suite that absorbs the idea with explicit credit, applies the scientific framework documented in docs/methodology/fixture-driven-iteration.md, and addresses the false-positive surface a naive port would leave open.

Failure mode (precise definition)

Stop event boundary. Files changed in this turn introduce one or more new publicly-accessible symbols in any of: Python def , TypeScript/JavaScript export function / export class, Rust pub fn / pub struct, Go capital-letter exports, Ruby def , Java public . For each newly-introduced symbol, the codebase (excluding test files) contains zero invocations or references that resolve to that symbol.

The model's closing message may or may not claim completion. The hook fires on the codebase state regardless of closeout text — this is the independence-of-signal property that distinguishes it from no-vibes.

False-positive surface (must be addressed before strict mode)

A naive grep-for-callers approach fires false positives on:

1. Entry-point functions called by frameworks: web routes (@app.route("/foo"), FastAPI handlers, Django views), CLI commands (@click.command, argparse subcommands, typer apps), event handlers, signal handlers, callback registrations (atexit.register(...), addEventListener), React/Vue/Svelte component exports, Next.js page exports. These have zero in-repo callers by design — the framework invokes them.

2. Plugin/registry patterns: functions added to a module-level registry via HANDLERS["foo"] = my_foo_handler or register("foo", my_handler). Grep finds the function definition but not a my_handler( invocation site.

3. Dynamic dispatch: getattr(module, name), globals()[name], JavaScript bracket access obj["method"], Python's __getattr__. The invocation is hidden behind a string lookup.

4. Decorator-based dispatch: any @some_decorator that wires the function into a framework — the function never appears at a literal call site, only its decorated form is invoked by the framework.

5. Public library API: a function intended to be called by external library consumers. No in-repo callers exist by design.

6. Subclass overrides: a new method on a subclass invoked via base-class polymorphism. Grep may not find a direct cls.method( call if dispatch is instance.method() on a polymorphic variable.

7. Test scaffolding / migration code: a function written in preparation for a follow-up PR's wiring. Strict reading is a false positive; intent reading is partially true.

8. Async/handler delegation patterns: callbacks passed as values rather than invoked at a call site (run_in_executor(my_fn), setTimeout(my_fn, 0)).

The honest read: the false-positive surface is broader than the true-positive surface in unbounded grep mode. Strict default would be unusable. Hook must default to advisory mode (advisory stderr + exit 0) with strict mode (exit 2) opt-in only.

Design choices

• Advisory by default: stderr warning, exit 0. Opt-in to strict mode via LDP_UNREACHABLE_SYMBOL_BLOCK=1 (matches no-vibes / sql-bulk-delete-warn env-var convention).
• Per-language frontmatter: separate symbol-extraction regex and exclusion patterns per *.py, *.ts / *.tsx / *.js, *.rs, *.go. Hook config picks language by file extension of the new symbol's defining file.
• Built-in decorator exclusion list: @app.route, @router.get, @router.post, @click.command, @pytest.fixture, @app.get, @app.post, @cli.command, @router.*, @FastAPI(...), plus framework-specific patterns. Configurable via .no-unreachable-symbol.toml or similar.
• Built-in path exclusion globs: **/routes/**, **/handlers/**, **/cli/**, **/views/**, **/pages/**, **/api/** (configurable).
• Registry-pattern detection: scan for register\(["'<symbol>["'] and HANDLERS\[["'<symbol>["'] patterns; treat as evidence the symbol is wired.
• Subclass-override heuristic: if the symbol name matches a method in any base class in the same module, treat as polymorphic and skip the gate.
• Public-API marker: respect __all__ in Python modules and export annotations in tsconfig; if the symbol is in the public API surface, downgrade to "no in-repo caller; library API assumed" message rather than block.

Composition with existing tooling

Three independent signals at the Stop boundary:

Hook	Signal source	Operator effort	Failure shape it catches
no-vibes (this suite)	Closing-message text vocabulary	passive	positive closeout verb + no proximate evidence in text
claude-verify-before-stop (@ianymu)	External VERIFIED log file	active write	model fabricates verification narrative without log entry
no-unreachable-symbol (proposed)	Git diff + codebase grep	passive	new public symbol with zero callers

Each catches a different sub-failure of Stage 3 (non-gating). Stack composes without overlap.

Empirical baseline (honest limit)

The MAST/MAD dataset is multi-agent text trajectories. It has no analogue for "git diff + codebase reachability" ground truth. This hook ships without an F1 baseline.

What it ships with instead, per docs/methodology/fixture-driven-iteration.md:

• Per-language positive fixtures: new symbol with zero callers (hook should fire)
• Per-language negative fixtures: properly wired (hook should not fire)
• Per-language edge fixtures: decorator-wired, registry-wired, dynamic dispatch, subclass override, public API marker, framework callback (hook should not fire on any of these)

The fixture suite is the contract the regex is responsible to. Strict mode opt-in is gated on the fixture suite passing across all configured languages.

A future direction: build an empirical baseline by mining anthropics/claude-code issues + PR bodies for "dead code with no callers" reports and labelling diffs. Out of scope for this issue.

Implementation plan (sliced)

• Slice 0 — Python only, advisory mode, built-in decorator exclusion, __all__ respect. Fixture suite: 8-12 positives, 8-12 negatives, 6-8 edges. Ship when all pass.
• Slice 1 — TypeScript / JavaScript. Same shape; framework patterns for Express, FastAPI-equivalents (Next.js handlers), React components.
• Slice 2 — Rust + Go. pub fn / capital exports. Trait dispatch and impl blocks add complexity.
• Slice 3 — Strict mode opt-in. Configurable .no-unreachable-symbol.toml. Document the operator-side cost of strict mode.

Acceptance criteria for the first slice

• Hook file at hooks/no-unreachable-symbol.sh per repo convention
• Test fixtures at tests/stress/no-unreachable-symbol/{positive,negative,edge}/
• All fixtures pass under bash tests/stress/run.sh --hook no-unreachable-symbol
• README entry under "What's shipped" with honest scope (advisory; per-language coverage; false-positive limitations documented)
• Attribution to @ianymu's sketch and verify-before-stop repo in the hook file's comment header
• Composition note linking no-vibes and verify-before-stop as siblings in the same Stage 3 family

Open questions

• Should the hook also consider new public classes with no instantiation sites, not just functions? Same false-positive surface (data classes, framework-instantiated handlers); same advisory framing applies.
• Cross-language project handling: how does the hook behave when the new symbol is in Python but a TypeScript file might call it via cross-language IPC? Treat as out-of-scope for v1.
• Should we attempt an AST-level reachability pass (ast.parse in Python, ts-morph or similar) for higher precision? Tradeoff: precision vs runtime cost vs language coverage. v1 stays grep-based; AST-level is a future slice.

cc: @ianymu for visibility on the design absorption with credit; happy to coordinate if the sketch direction has more nuance than what we captured here.

[waitdeadai]

Slice 0 implementation landed in commit c48244c.

What ships:

• hooks/no-unreachable-symbol.sh (153 lines): Python-only, advisory mode by default, strict mode opt-in via LDP_UNREACHABLE_SYMBOL_BLOCK=1
• tests/no-unreachable-symbol/smoke.sh: bespoke harness using temp git repos per scenario; 12 scenarios across positive/negative/edge; all pass locally
• tests/no-unreachable-symbol/README.md: documents why this hook needs a bespoke harness (state-dependent signal source doesn't fit the JSON-stdin stress runner)
• Wired into hooks/hooks.json for Stop + SubagentStop events
• plugin.json description bumped 28 → 29 patterns
• README "Outside MAST scope (by design)" subsection documents the hook's empirical-baseline-limit honestly

False-positive surface coverage in Slice 0 (matches the audit in the issue body):

• Decorator-wired exclusion (@app.route, @router.get, @pytest.fixture, @dataclass, @property, @staticmethod, @classmethod, Flask/FastAPI/click/typer patterns) — covered by smoke tests N2, N3, N4
• __all__ public-API marker respected via Python AST extraction — covered by N5
• Registry-pattern detection (HANDLERS["foo"] = sym, dict-literal values) — covered by N6
• Private-prefix (_helper) and dunder (__init__) symbols always skipped — covered by N7, E2

Reference-check loosening (worth flagging): initial implementation used \bsym\s*\( (call-form only). That false-positived on the N6 registry-value case (HANDLERS = {"foo": foo_handler} — the symbol is referenced as a bare identifier in a dict literal, not called). Loosened to \bsym\b (any text reference outside the def/class line) in hooks/no-unreachable-symbol.sh:108. False-negative direction is intentional in advisory mode — a function the codebase knows by name is more likely wired than one with zero textual mentions. The methodology-doc property holds: the fixture suite caught the bug; the regression is now gated.

What stays for future slices:

• Slice 1: TypeScript / JavaScript (export function, export class, React component exports)
• Slice 2: Rust (pub fn, pub struct, trait dispatch) + Go (capital-letter exports)
• Slice 3: Strict mode opt-in documented, project-level exclusion config (.no-unreachable-symbol.toml or similar)
• AST-level reachability pass (ast.parse in Python, ts-morph in TS) for higher precision — tradeoff against runtime cost; v1 stays grep-based

Open question from the issue body, partially answered: for new public classes with no instantiation sites — Slice 0 handles class Foo: the same as def foo, so both trigger the advisory (positive scenario P2). Same false-positive surface (framework-instantiated handlers, data classes); same advisory framing applies.

Leaving this issue open until Slice 1 (TS/JS) lands. Engagement on the design or false-positive cases beyond what the audit covered is welcome.

[waitdeadai]

Slice 1 (TypeScript / JavaScript) landed in commit bf102a6.

What ships:

• Symbol extraction for export function, export class, export const|let|var, export default function|class (all require an identifier-start char after the keyword to skip anonymous defaults — bug caught by the new E-TS2 fixture)
• Decorator exclusions for 30+ framework decorators: NestJS (@Controller, @Injectable, @Module, @Get/@Post/@Put/@Delete/@Patch, @UseGuards, @UseInterceptors, @WebSocketGateway, @SubscribeMessage), Angular (@Component, @Directive, @NgModule, @Pipe), TypeORM (@Entity, @Repository, @Schema, @Prop), GraphQL (@Resolver, @Query, @Mutation, @Subscription, @ObjectType, @InputType, @Field, @Args), Microservices (@EventPattern, @MessagePattern), Scheduler (@Cron, @Interval, @Timeout)
• Path-glob skip: pages/**, app/**, api/**, routes/** — Next.js page/app router conventions and generic route folders where the default export is framework-invoked, not directly called
• Public-API marker analogous to Python's __all__: any index.{ts,tsx,js,jsx} barrel re-export (export { foo } from './bar' or export *) treats the re-exported symbols as public API
• Registry-pattern detection: HANDLERS, COMMANDS, PLUGINS, ROUTES const-assigned dicts (same shape as Python's registry check, extended for TS const conventions)
• Private prefix (_underscore) always skipped
• Reference check exclusions: node_modules, dist, build, .next, tests, test, __tests__, .git

Smoke coverage (12 new TS/JS scenarios + 12 Python from Slice 0 = 24 total, all returning expected exit codes):

• P-TS1 / P-TS2 / P-TS3 — bare exports with no references (function / class / arrow-const)
• N-TS1 — exported function with import + call in another file
• N-TS2 — NestJS @Controller decorated class
• N-TS3 — Next.js pages/about.tsx default export (path-glob skip)
• N-TS4 — barrel re-export through index.ts
• N-TS5 — TS const-dict registry pattern
• N-TS6 — _private prefix
• N-TS7 — export default class with import elsewhere
• E-TS1 — no TS/JS files in diff
• E-TS2 — anonymous export default function () (no name to extract)

Wording fix from Slice 0: the advisory message changed from "zero callers" to "zero references under exclusion-aware grep" to honestly describe the reference-permissive check that Slice 0 already implemented. Slice 0 fixtures updated to match the new wording.

Bug caught by the new fixture set: initial export-default symbol-extraction regex matched function\s+ followed by any character including (, so export default function () (anonymous default) tried to extract a non-identifier "symbol" string from the rest of the line and false-positived. Tightened all five export … symbol-extraction guards to require an identifier-start character after the keyword. Smoke E-TS2 is the regression case.

Methodology-doc property held under live use: added new fixtures, fixture suite caught the bug, commit traces the fix. Same pattern as Slice 0's registry-value-form discovery.

What stays for future slices:

• Slice 2: Rust (pub fn, pub struct, pub enum, trait dispatch) + Go (capital-letter exports, interface-method dispatch)
• Slice 3: Strict mode opt-in documentation, project-level exclusion config (.no-unreachable-symbol.toml or YAML), per-project framework-conventions extension
• Slice 4: TS-specific interface / type / enum detection (reference-check pattern differs from value-symbols; types are referenced as types not as call targets)
• Slice 5: AST-level reachability — Python ast.parse, TS via ts-morph or @typescript-eslint/parser. Trades runtime cost for higher precision; eliminates comment-mention false negatives.

Leaving this issue open for Slices 2-5 + ongoing false-positive surface refinement. Substantive design or false-positive case reports welcome.