lint: warn on -- before task-owned #USAGE flags

[brownie-ricon]

Problem

With mise #USAGE tasks, task-owned flags should be passed directly. A -- separator before those flags can prevent mise/usage from parsing them.

Fresh example from KnickKnackLabs/notes#15 work:

run notes setup --yes -- --pattern "agents/*/Zettels/**"

After adding --yes, this invocation returned success but did not parse --pattern, so setup silently used the default pattern. The intended command was:

run notes setup --yes --pattern "agents/*/Zettels/**"

The current BATS guidance already says no -- separator is needed for declared #USAGE flags, but this is easy to forget and hard to spot in review.

Proposed lint

Warn on command invocations in shell/BATS files where a -- separator is immediately followed by a flag that belongs to the target mise task.

Possible conservative implementation:

1. Parse .mise/tasks/<task> for declared #USAGE flag long names.
2. Scan test/shell files for invocations shaped like:
   • <tool> <task> ... -- --<flag>
   • mise run <task> ... -- --<flag>
3. Warn only when --<flag> is declared by that task.

This should stay a warning because some tasks intentionally forward raw flags to a nested command.

Related

• fold bats-tool-testing.md — "No -- separator needed"

[olavostauros]

Dependency note

I evaluated this issue against the current codebase lint rule set. The detection approach is well-sketched (cross-reference #USAGE flag declarations against invocation patterns), and the bug class is real — I confirmed the notes#15 example where -- --pattern silently defaulted.

Blocker: lib/usage-parser.sh should land first

PR #66 (feat/usage-flag-naming, for #13) introduces lib/usage-parser.sh — a shared library that provides usage_flag_name() and usage_env_name() for parsing #USAGE directives. This rule should source and reuse that library rather than reimplementing the same parsing logic.

The implementation order should be:

1. Merge PR feat: add usage-flag-naming lint rule (#13) #66 (or at minimum land lib/usage-parser.sh) — unblocks lint: warn on -- before task-owned #USAGE flags #39 and several other USAGE-aware lint rules.
2. Implement lint: warn on -- before task-owned #USAGE flags #39 — a new .mise/tasks/lint/usage-double-dash that sources lib/usage-parser.sh, scans shell/BATS files for mise run <task> ... -- --<flag> patterns, and warns when <flag> matches a declared #USAGE flag in that task.

Related sibling issues

A similar USAGE-parsing dependency chain applies to #35 (optional defaults) and #43 (#USAGE examples) — all would benefit from the shared parser landing first.

Implementation plan

I sketched a full implementation plan in the issues-evaluate session. Key points:

• Rule name: usage-double-dash
• Conservative: Only flags when the --<flag> matches a declared #USAGE flag for that task — intentional forwarding to subprocesses passes cleanly.
• Ignore mechanisms: codebase:ignore usage-double-dash in mise.toml or inline # codebase:ignore usage-double-dash — forwarding to ssh.
• Effort: ~3–5h including fixtures (6 fixture scenarios: clean, dirty, ignored-inline, ignored-repo, forwarded-flags, mixed).