lint: flag optional #USAGE values without explicit defaults

[ikma-ricon]

Problem

mise file tasks expose #USAGE parse results as usage_* environment variables. If an optional arg/flag has no default=... and is omitted, usage does not export a replacement value, so a stale inherited parent usage_<name> can remain visible to the child task.

This caused a real review finding in KnickKnackLabs/sessions#89: nested sessions run / sessions wake could inherit usage_message and usage_headless from the parent agent dispatch and take the wrong no-message/headless path.

We documented the pattern in fold: notes/usage-defaults-clear-inherited-env.md.
Upstream discussion: jdx/mise#9460 (comment)

Proposed lint

Add a codebase lint for .mise/tasks/* that flags optional #USAGE args/flags read via usage_* when the directive lacks an explicit default.

Default desired shape:

#USAGE flag "--headless" default=#false
#USAGE flag "--model <model>" default=""
#USAGE arg "[message]" default=""
#USAGE flag "--meta <meta>" var=#true default=""

Rule sketch

For each executable task under .mise/tasks/:

1. Parse #USAGE directives.
2. Identify optional args/flags:
   • optional positional args like [message]
   • flags without required=#true
   • booleans without an explicit default
   • repeatable var=#true flags/args without an explicit default
3. If the task body references the corresponding usage_<snake_name> and the directive lacks default=..., report it.

Prefer checking read sites so docs-only/unused directives do not create noise.

Config / escape hatch

Support repo config for cases where ambient inheritance is intentional, e.g.:

[_.codebase.lint.usage-defaults]
allow = [".mise/tasks/foo:usage_model"]

or a directive-level suppression comment if that is more consistent with existing codebase lints.

Related

• codebase#13 — USAGE flag/placeholder mismatches
• codebase#21 — variadic #USAGE parsing hazards

[olavostauros]

Status update: blocked on shared infrastructure (PR #66)

This issue has no comments yet, but there's been progress on the USAGE-lint family:

What's unblocked

• codebase#13 (USAGE flag/placeholder mismatches) now has PR feat: add usage-flag-naming lint rule (#13) #66 ready — adds lib/usage-parser.sh, a shared library for parsing #USAGE directives from task files.
• codebase#21 (variadic #USAGE args) now has PR feat: add variadic-args lint rule #63 ready — implements detection for eval / read -ra on variadic usage_* values.

What this issue needs

The detection described here requires two capabilities, both now infrastructure-ready:

1. Phase 1 — Parse #USAGE directives → Identify optional args/flags and check for default=.... The shared parser from PR feat: add usage-flag-naming lint rule (#13) #66 already handles #USAGE flag and #USAGE arg line parsing.
2. Phase 2 — Scan task body for usage_* reads → The same approach used in PR feat: add variadic-args lint rule #63 (body-scanner for usage_* references).

The delta for this rule is:

• Extend lib/usage-parser.sh (or add a new function) to detect whether a directive has default=... and classify it as optional vs required.
• For flag lines: no required=#true means optional; if no default=..., flag it.
• For arg lines: [message] (bracket-wrapped) vs <message> vs message.
• Booleans without default=#false or default=#true: flag.
• Read-site check: only flag if the task body references usage_<snake_name>.

Dependency

This is blocked on PR #66 merging, since the shared USAGE parser lives in that branch. Once #66 lands, this becomes a medium-effort rule (3–5h):

• Parse directives for optionality + default presence
• Scan body for corresponding usage_* reads
• 10–12 fixture scenarios, ~15 BATS tests
• Config escape hatch per the issue proposal ([_.codebase.lint.usage-defaults])`