Require Every CLI Script to Answer Help and Refuse Unknown Arguments

[ptr727]

Adds the CODESTYLE.md General "Command-Line Arguments" rule (every CLI script answers --help and refuses unknown arguments before it reads or writes anything) and the tests/test_cli_usage.py gate that enforces it, and brings the existing scripts into line.

Closes on promotion: #2285

Known items, each with its class:

• spec/audit.py runs git config --get remote.origin.url on import, so scripts importing it read before parsing arguments (introduced, tracked in Resolve spec/audit.py's Hub Name Lazily So Importing Scripts Parse Arguments Before Any Read #2829).
• The three agent-safety hooks run by name are exempted in NOT_COMMAND_LINE (introduced, tracked in Make the Agent-Safety Hooks Run by Name Answer --help and Refuse Unknown Arguments #2786).
• --check sentence-length hits on CODESTYLE.md Shell paragraph sentences (pre-existing).
• Local review findings on the gate's soundness (unknown-flag assertion accepts a "usage" substring, ignored paths and env passthrough not covered, detached grandchildren unseen, a leading-hyphen NAME now read as an option in spec/resolve_description.py) (introduced, deferred to Harden the CLI Usage Gate Against False Greens #2831).

Local gates run: ruff format and check, mypy, prose gate, repo_gate.py, spec/validate.py, build_dist.py --check, and the full unittest suite (2550 tests, OK).

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: ptr727/ProjectTemplate/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 596fa07b-0f91-45ad-8e0a-ca0927c5ab0b

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 14.81481% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.26%. Comparing base (65c14a2) to head (8d0648f).
⚠️ Report is 2 commits behind head on develop.

Files with missing lines	Patch %	Lines
spec/workflow_reuse.py	0.00%	9 Missing ⚠️
spec/fidelity_honesty.py	0.00%	6 Missing ⚠️
spec/resolve_description.py	25.00%	6 Missing ⚠️
spec/validate.py	50.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2832      +/-   ##
===========================================
- Coverage    60.31%   60.26%   -0.05%     
===========================================
  Files           16       16              
  Lines         8479     8489      +10     
===========================================
+ Hits          5114     5116       +2     
- Misses        3365     3373       +8     

Flag	Coverage Δ
python-3.13	60.26% <14.81%> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟡 Changes recommended

The gate skips Windows entirely and cannot discover extensionless command-line scripts.

2 open findings

• Discover extensionless executable CLI scripts · New
• Avoid skipping CLI argument tests on Windows · New

What changed in this PR

This PR adds a fleet-wide command-line argument rule and a test gate for scripts shipped by ProjectTemplate. It also updates existing entry points to answer help requests and reject unknown arguments.

Changes:

• Define the rule in CODESTYLE.md and distribute it through the Python and shell skills.
• Add a test gate for help and unknown-argument behavior.
• Update Python and PowerShell entry points to parse or reject arguments.

File	Description
tests/​test_cli_usage.py	Adds the CLI argument gate.
spec/​workflow_reuse.py	Parses CLI options.
spec/​validate.py	Parses CLI arguments.
spec/​resolve_description.py	Parses required arguments.
spec/​fidelity_honesty.py	Parses the report option.
host-setup/​windows/​setup-wsl.ps1	Rejects unknown or misplaced arguments.
host-setup/​windows/​install-tools.ps1	Rejects unknown options.
CODESTYLE.md	Defines the command-line rule.
catalog/​snippets/​hub-fetch-run.py	Adds help and first-argument validation.
.github/​skills/​shell-codestyle/​SKILL.md	Distributes the shell rule.
.github/​skills/​python-codestyle/​SKILL.md	Distributes the Python rule.
.github/​actions/​python-directories/​python_directories.py	Parses CLI arguments.
.claude-plugin/​fleet-skills/​skills/​shell-codestyle/​SKILL.md	Distributes the shell rule.
.claude-plugin/​fleet-skills/​skills/​python-codestyle/​SKILL.md	Distributes the Python rule.
.claude-plugin/​fleet-skills/​.source-digests/​shell-codestyle	Updates the generated source digest.
.claude-plugin/​fleet-skills/​.source-digests/​python-codestyle	Updates the generated source digest.
.agents/​skills/​shell-codestyle/​SKILL.md	Adds the rule to the shell skill source.
.agents/​skills/​python-codestyle/​SKILL.md	Adds the rule to the Python skill source.

🧠 Review effort: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.