Require Every CLI Script to Answer Help and Refuse Unknown Arguments

.agents/skills/python-codestyle/SKILL.md

@@ -4,15 +4,16 @@ description: >-
   Governs Python code style for ptr727/ProjectTemplate fleet repos: the build-versus-lint-only
   profile split, the uv/ruff/pyright/mypy/pytest toolchain, src layout, formatting and linting,
   comment and docstring conventions, type hints, naming, imports, patterns to avoid, test
-  conventions, and versioning. Use this whenever writing, reviewing, or editing a .py file, a
-  pyproject.toml, or a uv.lock, whenever running or choosing a Python formatting, lint, type-check,
-  or test command, whenever deciding whether a Python subtree is a shippable project or a lint-only
-  scripts tree, whenever choosing pyright versus mypy for a repo's CI gate, or whenever writing or
-  reviewing a Python test. Triggers even when the task looks like a small local fix ("just add a
-  helper function", "silence this lint warning", "add a dependency") or verification step ("run
-  the tests"), because choosing pytest before reading the profile turns an intentional unittest
-  suite into a false missing-dependency diagnosis. Applies only to a repo's Python side, a repo
-  with no Python has no use for this Skill.
+  conventions, versioning, and the --help and unknown-argument rule for a script. Use this
+  whenever writing, reviewing, or editing a .py file, a pyproject.toml, or a uv.lock, whenever
+  running or choosing a Python formatting, lint, type-check, or test command, whenever deciding
+  whether a Python subtree is a shippable project or a lint-only scripts tree, whenever choosing
+  pyright versus mypy for a repo's CI gate, or whenever writing or reviewing a Python test.
+  Triggers even when the task looks like a small local fix ("just add a helper function", "silence
+  this lint warning", "add a dependency") or verification step ("run the tests"), because choosing
+  pytest before reading the profile turns an intentional unittest suite into a false
+  missing-dependency diagnosis. Applies only to a repo's Python side, a repo with no Python has no
+  use for this Skill.
 ---
 
 # Python Codestyle
@@ -247,6 +248,17 @@ Before pushing or opening a PR:
 - Markdown in this directory follows CODESTYLE.md's repo-wide Markdown and Spelling rules,
   packaged as the `comment-and-doc-style` Skill.
 
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->
+
 <!-- External -->
 
 [docs-link]: https://docs.pytest.org/

.agents/skills/shell-codestyle/SKILL.md

@@ -4,16 +4,17 @@ description: >-
   Governs Bash/shell script style for ptr727/ProjectTemplate fleet repos: when a bootstrap or
   host-tool script may be shell instead of Python, the mandatory set -Eeuo pipefail header, the
   pipefail-versus-early-reader pitfall, self-recursive command shims, self-locating scripts, the
-  shellcheck-plus-shfmt clean-compile, and the why-not-what comment rule. Use this whenever
-  writing, reviewing, or editing a shell script (a `.sh` file, or an extensionless bash/sh shebang
-  script), whenever deciding whether a new script should be Bash or Python, or whenever a pipeline
-  built from `curl`/`grep`/`jq`-style commands looks like it silently swallowed a failure, or
-  whenever a script or probe writes a wrapper or shim named after a command it also calls.
-  Triggers even when the task looks like a one-line tweak to an existing script, because a missing
-  `-e`/`pipefail`, or a reader piped straight from a producer that closes the pipe early, are each
-  invisible until the exact failure mode they guard against actually happens. Fleet-wide: a shell
-  script can appear in any repo (a bootstrap that installs the interpreter, a host tool that must
-  run before a toolchain exists), not only a repo whose primary language is shell.
+  shellcheck-plus-shfmt clean-compile, the --help and unknown-argument rule, and the why-not-what
+  comment rule. Use this whenever writing, reviewing, or editing a shell script (a `.sh` file, or
+  an extensionless bash/sh shebang script), whenever deciding whether a new script should be Bash
+  or Python, or whenever a pipeline built from `curl`/`grep`/`jq`-style commands looks like it
+  silently swallowed a failure, or whenever a script or probe writes a wrapper or shim named after
+  a command it also calls. Triggers even when the task looks like a one-line tweak to an existing
+  script, because a missing `-e`/`pipefail`, or a reader piped straight from a producer that
+  closes the pipe early, are each invisible until the exact failure mode they guard against
+  actually happens. Fleet-wide: a shell script can appear in any repo (a bootstrap that installs
+  the interpreter, a host tool that must run before a toolchain exists), not only a repo whose
+  primary language is shell.
 ---
 
 # Shell Codestyle
@@ -75,3 +76,14 @@ depend on Python either. Everything else is Python, with a test under its own sc
 - **Comments say why, never what.** The code states what it does. A comment restating it goes
   stale silently, where a comment carrying a reason fails visibly when the reason stops being
   true.
+
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->

.claude-plugin/fleet-skills/.source-digests/python-codestyle

@@ -1 +1 @@
-4a55b75c694378d2
+aee8b6541472e858

.claude-plugin/fleet-skills/.source-digests/shell-codestyle

@@ -1 +1 @@
-52454c88dd2aedc0
+3880094e1fe1db20

.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md

@@ -4,15 +4,16 @@ description: >-
   Governs Python code style for ptr727/ProjectTemplate fleet repos: the build-versus-lint-only
   profile split, the uv/ruff/pyright/mypy/pytest toolchain, src layout, formatting and linting,
   comment and docstring conventions, type hints, naming, imports, patterns to avoid, test
-  conventions, and versioning. Use this whenever writing, reviewing, or editing a .py file, a
-  pyproject.toml, or a uv.lock, whenever running or choosing a Python formatting, lint, type-check,
-  or test command, whenever deciding whether a Python subtree is a shippable project or a lint-only
-  scripts tree, whenever choosing pyright versus mypy for a repo's CI gate, or whenever writing or
-  reviewing a Python test. Triggers even when the task looks like a small local fix ("just add a
-  helper function", "silence this lint warning", "add a dependency") or verification step ("run
-  the tests"), because choosing pytest before reading the profile turns an intentional unittest
-  suite into a false missing-dependency diagnosis. Applies only to a repo's Python side, a repo
-  with no Python has no use for this Skill.
+  conventions, versioning, and the --help and unknown-argument rule for a script. Use this
+  whenever writing, reviewing, or editing a .py file, a pyproject.toml, or a uv.lock, whenever
+  running or choosing a Python formatting, lint, type-check, or test command, whenever deciding
+  whether a Python subtree is a shippable project or a lint-only scripts tree, whenever choosing
+  pyright versus mypy for a repo's CI gate, or whenever writing or reviewing a Python test.
+  Triggers even when the task looks like a small local fix ("just add a helper function", "silence
+  this lint warning", "add a dependency") or verification step ("run the tests"), because choosing
+  pytest before reading the profile turns an intentional unittest suite into a false
+  missing-dependency diagnosis. Applies only to a repo's Python side, a repo with no Python has no
+  use for this Skill.
 ---
 
 # Python Codestyle
@@ -247,6 +248,17 @@ Before pushing or opening a PR:
 - Markdown in this directory follows CODESTYLE.md's repo-wide Markdown and Spelling rules,
   packaged as the `comment-and-doc-style` Skill.
 
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->
+
 <!-- External -->
 
 [docs-link]: https://docs.pytest.org/

.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md

@@ -4,16 +4,17 @@ description: >-
   Governs Bash/shell script style for ptr727/ProjectTemplate fleet repos: when a bootstrap or
   host-tool script may be shell instead of Python, the mandatory set -Eeuo pipefail header, the
   pipefail-versus-early-reader pitfall, self-recursive command shims, self-locating scripts, the
-  shellcheck-plus-shfmt clean-compile, and the why-not-what comment rule. Use this whenever
-  writing, reviewing, or editing a shell script (a `.sh` file, or an extensionless bash/sh shebang
-  script), whenever deciding whether a new script should be Bash or Python, or whenever a pipeline
-  built from `curl`/`grep`/`jq`-style commands looks like it silently swallowed a failure, or
-  whenever a script or probe writes a wrapper or shim named after a command it also calls.
-  Triggers even when the task looks like a one-line tweak to an existing script, because a missing
-  `-e`/`pipefail`, or a reader piped straight from a producer that closes the pipe early, are each
-  invisible until the exact failure mode they guard against actually happens. Fleet-wide: a shell
-  script can appear in any repo (a bootstrap that installs the interpreter, a host tool that must
-  run before a toolchain exists), not only a repo whose primary language is shell.
+  shellcheck-plus-shfmt clean-compile, the --help and unknown-argument rule, and the why-not-what
+  comment rule. Use this whenever writing, reviewing, or editing a shell script (a `.sh` file, or
+  an extensionless bash/sh shebang script), whenever deciding whether a new script should be Bash
+  or Python, or whenever a pipeline built from `curl`/`grep`/`jq`-style commands looks like it
+  silently swallowed a failure, or whenever a script or probe writes a wrapper or shim named after
+  a command it also calls. Triggers even when the task looks like a one-line tweak to an existing
+  script, because a missing `-e`/`pipefail`, or a reader piped straight from a producer that
+  closes the pipe early, are each invisible until the exact failure mode they guard against
+  actually happens. Fleet-wide: a shell script can appear in any repo (a bootstrap that installs
+  the interpreter, a host tool that must run before a toolchain exists), not only a repo whose
+  primary language is shell.
 ---
 
 # Shell Codestyle
@@ -75,3 +76,14 @@ depend on Python either. Everything else is Python, with a test under its own sc
 - **Comments say why, never what.** The code states what it does. A comment restating it goes
   stale silently, where a comment carrying a reason fails visibly when the reason stops being
   true.
+
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->

.github/actions/python-directories/python_directories.py

@@ -23,14 +23,15 @@
 
 from __future__ import annotations
 
+import argparse
 import io
 import os
 import posixpath
 import subprocess
 import sys
 import tomllib
 import uuid
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from pathlib import Path
 
 UNCOVERED_SHOWN = 10
@@ -127,7 +128,10 @@ def uncovered(directories: list[str], tracked: list[str]) -> list[str]:
     ]
 
 
-def main() -> int:
+def main(argv: Sequence[str] = ()) -> int:
+    argparse.ArgumentParser(description=__doc__.splitlines()[0] if __doc__ else None).parse_args(
+        list(argv)
+    )
     # A tracked path need not be valid UTF-8, and a warning naming one must not crash the step it only warns in.
     if isinstance(sys.stdout, io.TextIOWrapper):
         sys.stdout.reconfigure(errors="backslashreplace")
@@ -187,4 +191,4 @@ def read_once(path: str) -> str:
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main(sys.argv[1:]))

.github/skills/python-codestyle/SKILL.md

@@ -4,15 +4,16 @@ description: >-
   Governs Python code style for ptr727/ProjectTemplate fleet repos: the build-versus-lint-only
   profile split, the uv/ruff/pyright/mypy/pytest toolchain, src layout, formatting and linting,
   comment and docstring conventions, type hints, naming, imports, patterns to avoid, test
-  conventions, and versioning. Use this whenever writing, reviewing, or editing a .py file, a
-  pyproject.toml, or a uv.lock, whenever running or choosing a Python formatting, lint, type-check,
-  or test command, whenever deciding whether a Python subtree is a shippable project or a lint-only
-  scripts tree, whenever choosing pyright versus mypy for a repo's CI gate, or whenever writing or
-  reviewing a Python test. Triggers even when the task looks like a small local fix ("just add a
-  helper function", "silence this lint warning", "add a dependency") or verification step ("run
-  the tests"), because choosing pytest before reading the profile turns an intentional unittest
-  suite into a false missing-dependency diagnosis. Applies only to a repo's Python side, a repo
-  with no Python has no use for this Skill.
+  conventions, versioning, and the --help and unknown-argument rule for a script. Use this
+  whenever writing, reviewing, or editing a .py file, a pyproject.toml, or a uv.lock, whenever
+  running or choosing a Python formatting, lint, type-check, or test command, whenever deciding
+  whether a Python subtree is a shippable project or a lint-only scripts tree, whenever choosing
+  pyright versus mypy for a repo's CI gate, or whenever writing or reviewing a Python test.
+  Triggers even when the task looks like a small local fix ("just add a helper function", "silence
+  this lint warning", "add a dependency") or verification step ("run the tests"), because choosing
+  pytest before reading the profile turns an intentional unittest suite into a false
+  missing-dependency diagnosis. Applies only to a repo's Python side, a repo with no Python has no
+  use for this Skill.
 ---
 
 # Python Codestyle
@@ -247,6 +248,17 @@ Before pushing or opening a PR:
 - Markdown in this directory follows CODESTYLE.md's repo-wide Markdown and Spelling rules,
   packaged as the `comment-and-doc-style` Skill.
 
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->
+
 <!-- External -->
 
 [docs-link]: https://docs.pytest.org/

.github/skills/shell-codestyle/SKILL.md

@@ -4,16 +4,17 @@ description: >-
   Governs Bash/shell script style for ptr727/ProjectTemplate fleet repos: when a bootstrap or
   host-tool script may be shell instead of Python, the mandatory set -Eeuo pipefail header, the
   pipefail-versus-early-reader pitfall, self-recursive command shims, self-locating scripts, the
-  shellcheck-plus-shfmt clean-compile, and the why-not-what comment rule. Use this whenever
-  writing, reviewing, or editing a shell script (a `.sh` file, or an extensionless bash/sh shebang
-  script), whenever deciding whether a new script should be Bash or Python, or whenever a pipeline
-  built from `curl`/`grep`/`jq`-style commands looks like it silently swallowed a failure, or
-  whenever a script or probe writes a wrapper or shim named after a command it also calls.
-  Triggers even when the task looks like a one-line tweak to an existing script, because a missing
-  `-e`/`pipefail`, or a reader piped straight from a producer that closes the pipe early, are each
-  invisible until the exact failure mode they guard against actually happens. Fleet-wide: a shell
-  script can appear in any repo (a bootstrap that installs the interpreter, a host tool that must
-  run before a toolchain exists), not only a repo whose primary language is shell.
+  shellcheck-plus-shfmt clean-compile, the --help and unknown-argument rule, and the why-not-what
+  comment rule. Use this whenever writing, reviewing, or editing a shell script (a `.sh` file, or
+  an extensionless bash/sh shebang script), whenever deciding whether a new script should be Bash
+  or Python, or whenever a pipeline built from `curl`/`grep`/`jq`-style commands looks like it
+  silently swallowed a failure, or whenever a script or probe writes a wrapper or shim named after
+  a command it also calls. Triggers even when the task looks like a one-line tweak to an existing
+  script, because a missing `-e`/`pipefail`, or a reader piped straight from a producer that
+  closes the pipe early, are each invisible until the exact failure mode they guard against
+  actually happens. Fleet-wide: a shell script can appear in any repo (a bootstrap that installs
+  the interpreter, a host tool that must run before a toolchain exists), not only a repo whose
+  primary language is shell.
 ---
 
 # Shell Codestyle
@@ -75,3 +76,14 @@ depend on Python either. Everything else is Python, with a test under its own sc
 - **Comments say why, never what.** The code states what it does. A comment restating it goes
   stale silently, where a comment carrying a reason fails visibly when the reason stops being
   true.
+
+## Command-Line Arguments
+
+<!-- include: CODESTYLE.md > Command-Line Arguments -->
+
+A command-line script is one a person or an agent runs by name. A hook its host runs, taking its input from that host rather than from a command line, is not one.
+
+- **Every command-line script answers `--help` and `-h`** by printing its usage and exiting 0, changing nothing. An agent learns a script's interface by asking it, so a script that reads `--help` as an input acts in a way nobody predicted.
+- **An argument the script does not recognize is refused**, with a non-zero exit before any read or write. An unrecognized first argument is never taken as a default mode or as a target.
+
+<!-- /include -->