docs: add the plan for the compiled parser and config layer

[jdx]

PLAN.md — the plan for this work written down end to end, including the parts that do not exist yet.

Three PRs in (#797, #798, #799), the plan lived in PR descriptions and in my head. That is fine for one PR and not for a dozen, especially for the config layer, where the shape is worth arguing about before it gets built.

Checkboxes rather than prose, so the file doubles as status: an unchecked box means the thing does not exist. Ticking them as things land keeps it honest, and makes it obvious when a branch of the plan has stalled.

What it covers

• Why — mise's measured numbers, and the fact that mise already hand-maintains two argv scanners to avoid building its clap tree. That workaround existing is the argument for the project.
• How it is arranged — the four rules that hold it together: code authors and the spec defines; usage-lib is the reference implementation; the hot path stays small; end users never need a second binary.
• Milestones — what is done, the derive work next, the table stakes after it (help, self-contained completions, docs, diagnostics).
• The gate — the perf targets, measured with tak against a shadow CLI generated from mise's own committed spec. Explicitly: if the targets miss by a wide margin, write that down and stop. Nothing touches mise before this.
• Known usage-lib divergences — as a to-do list, since each is a small change to lib/src/parse.rs and the corpus already knows how to verify a fix.
• Config — the v2 design, from reading all four CLIs.

The config section is the part worth reviewing

mise, hk, pitchfork, and fnox have each independently built the same settings model — a TOML registry, build.rs codegen, a typed Settings plus a meta map, project-over-global-over-defaults layering — and agree on ~80% of the vocabulary. The differences are mostly drift rather than intent:

• Every one hand-writes the CLI-to-settings binding, and every one has a hole in it: hk declares sources.cli entries nothing reads, pitchfork's --help documents a CLI layer it does not have (copied by hand into its committed spec), and fnox resolves age_key_file through a hardcoded five-way chain because its settings and config files are separate systems.
• Only hk can say where a value came from, and it needed a second parallel merge to do it.
• Docs/schema generation is three separate reimplementations, and fnox has none.

The proposal is to declare props in code, lower them into the spec's config { prop ... } block — which exists today and no CLI emits or consumes — and generate the CLI binding instead of hand-writing it. That block needs extending first (deprecated, enum, optional, aliases, merge, scope, per-source lists), which is spec-first per the canonicality rule.

Three open questions are listed rather than decided, including whether config belongs in this repo at all.

AI-assisted — Tool: Claude Code; model: anthropic/claude-fable-5; version: unavailable.

---

Note

Low Risk
Documentation-only addition with no runtime, build, or API changes.

Overview
Introduces PLAN.md as the canonical, in-repo plan for the compiled argv parser work and the later shared config layer—replacing plan text that lived only in PR descriptions.

The doc uses unchecked checkboxes as status (unchecked = not built yet) and covers motivation (mise/clap cost), architecture (spec → usage-derive / usage-argv / usage-lib), milestones (done vs derive vs gate vs adoption), perf gate targets, corpus gaps, known usage-lib divergences as a fix list, and a config design sketch (unify mise/hk/pitchfork/fnox settings) with open questions—not implementation.

^{Reviewed by Cursor Bugbot for commit 96b60f9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@jdx, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 49 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 66afda1b-873f-47a9-afc3-09d7098ccdef

📥 Commits

Reviewing files that changed from the base of the PR and between 4fdc688 and 96b60f9.

📒 Files selected for processing (1)

• PLAN.md

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Adds an end-to-end roadmap for the compiled argv parser and proposed shared configuration layer.

• Documents the architecture, completed parser work, upcoming derive and framework milestones, and performance gate.
• Records known parser divergences and gaps in the conformance corpus.
• Proposes a spec-first configuration model while explicitly leaving major design questions open.

Confidence Score: 5/5

The documentation-only pull request appears safe to merge.

The change introduces no runtime or build behavior, and no concrete inaccurate or actionable documentation defect remains.

Important Files Changed

Filename	Overview
PLAN.md	Adds a documentation-only implementation plan whose checked status claims align with the repository and whose unfinished proposals are clearly marked.

_{Reviews (1): Last reviewed commit: "docs: add the plan for the compiled pars..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▃▁▂█▄▅▃▃▂▂▅▅▂▆▅▃▅	110,531,405 → 110,567,634	+0.03%	11.11 → 12.05ms	+8.46%
startup	▃▃▁▃▅██▅▅▆▆▇▆▆▆▆▆	1,201,311 → 1,201,475	+0.01%	1.02 → 1.05ms	+2.60%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{96b60f9da6ff vs 4fdc688ea2d9 · measured on the runner, not pushed to the history.}