claude-dev-env 1.62.1 → 1.64.0

package/agents/code-advisor.md

@@ -0,0 +1,22 @@
+---
+name: code-advisor
+description: Mid-run advisor for executor agents. A coder that hits a decision it can't reasonably solve consults this agent with its task, what it tried, and the exact blocker. Returns a plan, a correction, or a stop signal — guidance only. Has zero tools by design; it never runs commands, never edits files, never produces user-facing output.
+tools: []
+model: inherit
+color: purple
+---
+
+You are the advisor in an executor/advisor pair (Anthropic's advisor strategy: https://claude.com/blog/the-advisor-strategy). An executor agent — a coder partway through a task — consults you when it hits a decision it can't reasonably solve. You have no tools; everything you know arrives in the consultation message: the task, what the executor tried, the exact blocker, and any code excerpts it chose to include.
+
+Reply with exactly one of three signals, named on the first line:
+
+- **PLAN** — the blocker needs a different approach. Give concrete ordered steps the executor can run with its own tools. Name files, commands, and decision points; never hand back vague direction.
+- **CORRECTION** — the executor's approach is right but one thing is wrong. Name the wrong assumption or step and the precise fix.
+- **STOP** — no path satisfies the task as assigned (contradictory constraints, missing access, a rule that forbids every way through). Say why in one or two sentences so the executor can report it upward.
+
+Rules:
+
+- Guidance only. You never call tools, never write code blocks longer than a focused excerpt, and your reply goes to the executor, not the user.
+- Reason from what the executor sent. When the consultation lacks the facts a sound answer needs, your PLAN's first step is the exact lookup the executor should run, then what to do with each likely answer.
+- Keep replies short. The executor pays for every token of your answer twice — reading it and acting on it.
+- Never invent repository facts. Tie every claim to something in the consultation or label it for the executor to check.

package/agents/code-verifier.md

@@ -0,0 +1,42 @@
+---
+name: code-verifier
+description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
+tools: Read, Grep, Glob, Bash
+model: inherit
+color: orange
+---
+
+You are the verifier in a two-phase code workflow: coder agents wrote changes, and you grade the result on its own terms (Claude Code best practices, fresh-context review: https://code.claude.com/docs/en/best-practices). The agent doing the work is never the one grading it — that is you, so you trust nothing you did not run or read yourself this session.
+
+The caller gives you task texts, the diff scope, and baselines recorded before the coders ran. Treat every claim in the caller's message — and any coder summary quoted in it — as a hypothesis to test, never as a fact.
+
+Run all three layers, in this order:
+
+1. **Runnable gates.** Every check the task names (its verification section), plus the universal set whether or not the caller asked: compile/syntax checks on changed files, the recorded-baseline tests scoped to the changed modules — the test files the task names plus tests that import a changed module (the failure set must match the recorded baseline exactly — no new failures, none silently fixed without explanation), imports of changed modules, and any repo commit gate. Run the full recorded suite only when the caller recorded a full-suite baseline because the surface spans multiple modules or multiple coders. Run each command yourself and keep its output.
+2. **Two-way diff-vs-task reading.** Read each coder's diff against that coder's task text. Every task item maps to a hunk that does it; every hunk maps back to a task item — a hunk with no task item is out-of-scope change, a task item with no hunk is missing work.
+3. **Negative space.** Walk the task's item list asking "where is this one?": silent deferrals, stubs, TODO markers, the smaller half of a task shipped, a sync change without its async twin.
+
+Findings discipline:
+
+- A finding must cite a failing command (with its output) or a named task item. No citation, no finding.
+- Report gaps that affect correctness or the task's stated terms — never style preferences. Sound work produces zero findings; do not invent gaps to look thorough.
+- Never edit a file. You verify; repair agents repair.
+- Never execute code that drives the user's real input or screen — no live mouse moves, keystrokes, clicks, or window focus (pyautogui and its callers included). Run only the test commands the task names, scoped to the test files it names; no repo-wide test sweeps. Judge behavior equivalence by reading both versions, never by live execution of input-driving paths.
+
+Before you write the verdict, learn the surface hash of the work tree you verified. Use the branch mode — it resolves the work tree that holds the branch automatically, so it is immune to your own cwd:
+
+    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash-for-branch <branch under review>
+
+On Windows the same file sits at %USERPROFILE%\.claude\hooks\blocking\verification_verdict_store.py; invoke it with the python on your PATH. If the caller named an explicit work-tree path rather than a branch, use the explicit-directory mode instead:
+
+    python ~/.claude/hooks/blocking/verification_verdict_store.py --manifest-hash <explicit-work-tree-dir>
+
+The printed hash commits to every changed and untracked file's content in the verified work tree, so it names that surface no matter which directory you or the committer run from. If the CLI prints an empty-surface or wrong-work-tree error and no hash, you are pointed at a work tree with no changes versus origin/main — re-run with the branch mode to locate the correct work tree.
+
+End your final message with exactly one fenced verdict block — the verifier_verdict_minter hook parses it, binds it to that hash, and the verified_commit_gate hook unlocks `git commit`/`git push` for any work tree whose live surface matches it:
+
+```verdict
+{"all_pass": false, "findings": [{"check": "<gate or task item>", "detail": "<command + output, or the named task item and what is missing>"}], "manifest_sha256": "<hash the CLI printed>"}
+```
+
+Set `all_pass` to true with an empty `findings` list only when every layer came back clean. Always include `manifest_sha256` so the verdict clears the commit regardless of which work tree the verifier or the committer ran in. Any file change after you finish moves that hash and invalidates the verdict, so you are the last step before the commit.

package/bin/install.mjs

@@ -149,7 +149,7 @@ const INSTALL_GROUPS = {
         skills: [
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
-            'recall', 'remember', 'task-build'
+            'recall', 'remember', 'task-build', 'verified-build'
         ],
         includeDirectories: ['rules', 'docs', 'commands', 'agents', 'audit-rubrics'],
         includeAllHooks: true,

package/hooks/blocking/code_rules_dead_argparse_argument.py

@@ -0,0 +1,554 @@
+"""Dead argparse-argument check: an optional CLI flag whose value is never read."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_argparse_argument_constants import (  # noqa: E402
+    ACTION_KEYWORD_NAME,
+    ADD_ARGUMENT_METHOD_NAME,
+    ALL_PARSE_METHOD_NAMES,
+    ALL_SUPPRESSED_ACTION_NAMES,
+    ATTRGETTER_FUNCTION_NAME,
+    DEAD_ARGPARSE_ARGUMENT_GUIDANCE,
+    DEST_KEYWORD_NAME,
+    DEST_WORD_JOINER,
+    DEST_WORD_SEPARATOR,
+    EXPORTED_NAMES_ATTRIBUTE,
+    GETATTR_FUNCTION_NAME,
+    GETATTR_NAME_ARGUMENT_MINIMUM,
+    LONG_OPTION_PREFIX,
+    MAX_DEAD_ARGPARSE_ARGUMENT_ISSUES,
+    NAMESPACE_DICT_ATTRIBUTE_NAME,
+    NAMESPACE_KEYWORD_NAME,
+    OPTION_PREFIX,
+)
+
+
+def _string_constant_literal(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _keyword_string_literal(call_node: ast.Call, keyword_name: str) -> str | None:
+    """Return the string literal of a keyword argument, or None when absent."""
+    for each_keyword in call_node.keywords:
+        if each_keyword.arg == keyword_name:
+            return _string_constant_literal(each_keyword.value)
+    return None
+
+
+def _keyword_value_node(call_node: ast.Call, keyword_name: str) -> ast.expr | None:
+    """Return the value node of a keyword argument, or None when absent."""
+    for each_keyword in call_node.keywords:
+        if each_keyword.arg == keyword_name:
+            return each_keyword.value
+    return None
+
+
+def _option_string_arguments(call_node: ast.Call) -> list[str]:
+    """Return the leading positional string-literal arguments of an add_argument call."""
+    option_strings: list[str] = []
+    for each_argument in call_node.args:
+        literal_value = _string_constant_literal(each_argument)
+        if literal_value is None:
+            break
+        option_strings.append(literal_value)
+    return option_strings
+
+
+def _dest_from_option_string(option_string: str) -> str:
+    return option_string.lstrip(OPTION_PREFIX).replace(DEST_WORD_SEPARATOR, DEST_WORD_JOINER)
+
+
+def _has_keyword_argument(call_node: ast.Call, keyword_name: str) -> bool:
+    """Return whether the call passes a keyword argument with the given name."""
+    return any(each_keyword.arg == keyword_name for each_keyword in call_node.keywords)
+
+
+def _argument_dest_name(call_node: ast.Call) -> str | None:
+    """Return the dest name an optional add_argument call declares, or None.
+
+    A ``dest=`` keyword determines the dest outright: a string-literal value
+    (``dest="name"``) names it, while a non-literal ``dest=`` (a variable or
+    expression whose value the static scan cannot resolve) makes the real dest
+    unknowable, so the argument is skipped (None). Without a ``dest=`` keyword the
+    dest derives from the first long option (``--repo`` -> ``repo``, ``--dry-run``
+    -> ``dry_run``) and falls back to the first short option when no long option
+    is present. A bare positional argument (no leading dash) is a required
+    positional, never an optional flag, and yields None so the caller skips it.
+    """
+    if _has_keyword_argument(call_node, DEST_KEYWORD_NAME):
+        return _keyword_string_literal(call_node, DEST_KEYWORD_NAME)
+    option_strings = _option_string_arguments(call_node)
+    if not option_strings:
+        return None
+    if not option_strings[0].startswith(OPTION_PREFIX):
+        return None
+    for each_option in option_strings:
+        if each_option.startswith(LONG_OPTION_PREFIX):
+            return _dest_from_option_string(each_option)
+    return _dest_from_option_string(option_strings[0])
+
+
+def _has_suppressed_action(call_node: ast.Call) -> bool:
+    action_name = _keyword_string_literal(call_node, ACTION_KEYWORD_NAME)
+    return action_name in ALL_SUPPRESSED_ACTION_NAMES
+
+
+def _is_add_argument_call(node: ast.AST) -> bool:
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr == ADD_ARGUMENT_METHOD_NAME
+    )
+
+
+def _argument_dest_definitions(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return (dest_name, line) for each optional add_argument call in the module.
+
+    Positional arguments (a bare name with no leading dash) and the argparse
+    auto-actions ``help`` and ``version`` are excluded, since their parsed value
+    is never a meaningful readable dest.
+    """
+    dest_definitions: list[tuple[str, int]] = []
+    for each_node in ast.walk(tree):
+        if not _is_add_argument_call(each_node):
+            continue
+        assert isinstance(each_node, ast.Call)
+        if _has_suppressed_action(each_node):
+            continue
+        dest_name = _argument_dest_name(each_node)
+        if dest_name is None:
+            continue
+        dest_definitions.append((dest_name, each_node.lineno))
+    return dest_definitions
+
+
+def _attribute_read_names(tree: ast.Module) -> set[str]:
+    """Return every attribute name read or augmented-assigned in the module.
+
+    A read in Load context (``parsed_args.repo``) names the attribute, and an
+    augmented assignment (``parsed_args.count += 1``) reads the attribute before
+    writing it, so both count as a read of the dest name.
+    """
+    read_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Attribute) and isinstance(each_node.ctx, ast.Load):
+            read_names.add(each_node.attr)
+        if isinstance(each_node, ast.AugAssign) and isinstance(each_node.target, ast.Attribute):
+            read_names.add(each_node.target.attr)
+    return read_names
+
+
+def _dynamic_read_names(tree: ast.Module) -> set[str]:
+    """Return literal attribute names read via ``getattr`` and ``attrgetter``.
+
+    ``getattr(namespace, "repo")`` names its attribute in the second positional
+    argument, while ``attrgetter("a", "b")`` names one attribute per positional
+    argument; each literal string contributes a read name.
+    """
+    literal_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_name = None
+        if isinstance(each_node.func, ast.Name):
+            function_name = each_node.func.id
+        elif isinstance(each_node.func, ast.Attribute):
+            function_name = each_node.func.attr
+        if function_name == GETATTR_FUNCTION_NAME:
+            if len(each_node.args) >= GETATTR_NAME_ARGUMENT_MINIMUM:
+                literal_name = _string_constant_literal(each_node.args[1])
+                if literal_name is not None:
+                    literal_names.add(literal_name)
+        elif function_name == ATTRGETTER_FUNCTION_NAME:
+            for each_argument in each_node.args:
+                literal_name = _string_constant_literal(each_argument)
+                if literal_name is not None:
+                    literal_names.add(literal_name)
+    return literal_names
+
+
+def _exported_names(tree: ast.Module) -> set[str]:
+    """Return names listed in a module-level ``__all__`` literal."""
+    exported: set[str] = set()
+    for each_node in tree.body:
+        if not isinstance(each_node, ast.Assign):
+            continue
+        targets_all = any(
+            isinstance(each_target, ast.Name) and each_target.id == EXPORTED_NAMES_ATTRIBUTE
+            for each_target in each_node.targets
+        )
+        if not targets_all:
+            continue
+        if isinstance(each_node.value, (ast.List, ast.Tuple, ast.Set)):
+            for each_element in each_node.value.elts:
+                literal_name = _string_constant_literal(each_element)
+                if literal_name is not None:
+                    exported.add(literal_name)
+    return exported
+
+
+def _target_namespace_names(assign_target: ast.expr) -> set[str]:
+    """Return names an assignment target binds the namespace to.
+
+    A bare ``ast.Name`` target (``parsed = parse_args()``) binds one namespace
+    name. A tuple- or list-unpack target (``parsed, remaining =
+    parse_known_args()``) binds the namespace to its first ``ast.Name`` element,
+    matching the documented ``(namespace, remaining)`` return shape.
+    """
+    if isinstance(assign_target, ast.Name):
+        return {assign_target.id}
+    if isinstance(assign_target, (ast.Tuple, ast.List)):
+        for each_element in assign_target.elts:
+            if isinstance(each_element, ast.Name):
+                return {each_element.id}
+    return set()
+
+
+def _is_parse_method_call(node: ast.AST | None) -> bool:
+    """Return whether a node is a ``parse_args``/``parse_known_args`` method call.
+
+    The call's function is an attribute access (``parser.parse_args``) whose
+    attribute name is one of the tracked parse methods.
+    """
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and node.func.attr in ALL_PARSE_METHOD_NAMES
+    )
+
+
+def _parse_result_binding_targets(node: ast.AST) -> list[ast.expr] | None:
+    """Return the targets a statement binds a parse-method result to, or None.
+
+    A plain ``ast.Assign`` (``parsed = parse_args()``) or an annotated
+    ``ast.AnnAssign`` (``parsed: Namespace = parse_args()``) whose value is a
+    parse-method call binds the namespace; the returned list holds its target nodes,
+    one for an annotated assignment and one or more for a plain assignment. A node
+    that is not such a binding, including an annotated assignment with no value
+    (``parsed: Namespace``), returns None.
+    """
+    if isinstance(node, ast.Assign):
+        binding_targets: list[ast.expr] = node.targets
+        bound_value: ast.expr | None = node.value
+    elif isinstance(node, ast.AnnAssign):
+        binding_targets = [node.target]
+        bound_value = node.value
+    else:
+        return None
+    if not _is_parse_method_call(bound_value):
+        return None
+    return binding_targets
+
+
+def _parse_call_namespace_names(tree: ast.Module) -> set[str]:
+    """Return names bound to a plain or annotated ``parse_args``/``parse_known_args`` result."""
+    parse_call_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        binding_targets = _parse_result_binding_targets(each_node)
+        if binding_targets is None:
+            continue
+        for each_target in binding_targets:
+            parse_call_names |= _target_namespace_names(each_target)
+    return parse_call_names
+
+
+def _alias_namespace_names(tree: ast.Module, all_parse_call_names: set[str]) -> set[str]:
+    """Return names bound by re-assigning an existing namespace variable.
+
+    A simple ``alias = parsed_arguments`` re-binding aliases the namespace, and a
+    chain (``second = alias``) aliases it again, so the set grows to a fixed point
+    before it is returned.
+    """
+    all_namespace_names = set(all_parse_call_names)
+    keeps_growing = True
+    while keeps_growing:
+        keeps_growing = False
+        for each_node in ast.walk(tree):
+            if not isinstance(each_node, ast.Assign):
+                continue
+            if not isinstance(each_node.value, ast.Name):
+                continue
+            if each_node.value.id not in all_namespace_names:
+                continue
+            for each_target in each_node.targets:
+                if isinstance(each_target, ast.Name) and each_target.id not in all_namespace_names:
+                    all_namespace_names.add(each_target.id)
+                    keeps_growing = True
+    return all_namespace_names
+
+
+def _namespace_keyword_argument_names(tree: ast.Module) -> set[str]:
+    """Return names passed as the ``namespace=`` keyword to a parse-method call.
+
+    ``parser.parse_args(namespace=options)`` populates the pre-existing
+    ``options`` object, so its attribute reads name dests even though the parse
+    result is never bound; the keyword's ``ast.Name`` value names that namespace.
+    """
+    keyword_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_node = each_node.func
+        if not isinstance(function_node, ast.Attribute):
+            continue
+        if function_node.attr not in ALL_PARSE_METHOD_NAMES:
+            continue
+        keyword_value = _keyword_value_node(each_node, NAMESPACE_KEYWORD_NAME)
+        if isinstance(keyword_value, ast.Name):
+            keyword_names.add(keyword_value.id)
+    return keyword_names
+
+
+def _namespace_variable_names(tree: ast.Module) -> set[str]:
+    """Return names bound to a parse result, a ``namespace=`` object, or an alias.
+
+    A direct binding plain or annotated (``parsed = parse_args()`` or
+    ``parsed: Namespace = parse_args()``), the first element of a tuple-unpack of the
+    documented ``(namespace, remaining)`` return (``parsed, remaining =
+    parse_known_args()``), a ``namespace=`` keyword object
+    (``parse_args(namespace=options)``), and a simple re-binding chain
+    (``alias = parsed``) each name the same namespace.
+    """
+    seed_names = _parse_call_namespace_names(tree) | _namespace_keyword_argument_names(tree)
+    return _alias_namespace_names(tree, seed_names)
+
+
+def _attribute_value_name_ids(tree: ast.Module) -> set[int]:
+    """Return ``id()`` of every Name that is the object of an attribute access.
+
+    The Name in ``namespace.repo`` is the ``.value`` of an ``ast.Attribute``, so it
+    is a per-attribute read rather than a use of the namespace object itself.
+    """
+    return {
+        id(each_node.value)
+        for each_node in ast.walk(tree)
+        if isinstance(each_node, ast.Attribute) and isinstance(each_node.value, ast.Name)
+    }
+
+
+def _namespace_keyword_value_name_ids(tree: ast.Module) -> set[int]:
+    """Return ``id()`` of every Name passed as the ``namespace=`` keyword to a parse call.
+
+    ``parse_args(namespace=options)`` binds the namespace at this position rather
+    than consuming it, so this Name is excluded from the escape scan the way an
+    attribute-read object is.
+    """
+    keyword_value_ids: set[int] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_node = each_node.func
+        if not isinstance(function_node, ast.Attribute):
+            continue
+        if function_node.attr not in ALL_PARSE_METHOD_NAMES:
+            continue
+        keyword_value = _keyword_value_node(each_node, NAMESPACE_KEYWORD_NAME)
+        if isinstance(keyword_value, ast.Name):
+            keyword_value_ids.add(id(keyword_value))
+    return keyword_value_ids
+
+
+def _namespace_used_as_value(tree: ast.Module, all_namespace_names: set[str]) -> bool:
+    """Return whether a tracked namespace Name is used as a value rather than an attribute read.
+
+    A tracked namespace Name read in Load context anywhere in the module -- passed
+    to a call, returned, aliased, double-star unpacked, or nested inside a container
+    literal -- uses the namespace object itself and hides which attributes are read.
+    Two positions are excluded: the object of an attribute access (``namespace.repo``
+    is a per-attribute read) and a Name passed as the ``namespace=`` keyword to a
+    parse call (a binding site, not a consumption).
+    """
+    excluded_name_ids = _attribute_value_name_ids(tree) | _namespace_keyword_value_name_ids(tree)
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Name):
+            continue
+        if not isinstance(each_node.ctx, ast.Load):
+            continue
+        if each_node.id not in all_namespace_names:
+            continue
+        if id(each_node) in excluded_name_ids:
+            continue
+        return True
+    return False
+
+
+def _namespace_dict_accessed(tree: ast.Module, all_namespace_names: set[str]) -> bool:
+    """Return whether a tracked namespace exposes all attributes via ``__dict__``."""
+    for each_node in ast.walk(tree):
+        if (
+            isinstance(each_node, ast.Attribute)
+            and each_node.attr == NAMESPACE_DICT_ATTRIBUTE_NAME
+            and isinstance(each_node.value, ast.Name)
+            and each_node.value.id in all_namespace_names
+        ):
+            return True
+    return False
+
+
+def _namespace_escapes(tree: ast.Module, all_namespace_names: set[str]) -> bool:
+    """Return whether a namespace is consumed in a way that hides which dests are read.
+
+    A namespace whose attributes the static scan cannot enumerate makes any single
+    dest unprovably dead, so the check suppresses. Each of the following is such an
+    escape: a ``parse_args``/``parse_known_args`` bound method referenced as an
+    aliased value rather than called inline; a parse result bound to an attribute-
+    or subscript-target the scan cannot track; a parse result consumed inline within
+    a larger expression rather than bound to an assignment or a bare statement; a
+    tracked namespace read through ``__dict__``; and a tracked namespace Name used as
+    a value rather than an attribute read (passed to a call, returned, aliased,
+    double-star unpacked, or nested inside a container literal), excluding the object
+    of an attribute access and a Name passed as the ``namespace=`` keyword to a parse
+    call.
+    """
+    if _parse_method_is_aliased(tree):
+        return True
+    if _parse_result_binds_untracked_target(tree):
+        return True
+    if _parse_call_consumed_inline(tree):
+        return True
+    if _namespace_dict_accessed(tree, all_namespace_names):
+        return True
+    return _namespace_used_as_value(tree, all_namespace_names)
+
+
+def _parse_method_is_aliased(tree: ast.Module) -> bool:
+    """Return whether a ``parse_args``/``parse_known_args`` method is referenced uncalled.
+
+    The bound method is aliased when its attribute (``parser.parse_args``) appears
+    as a value rather than as the ``func`` of an enclosing call — assigned to a
+    name or passed around — so the resulting namespace is produced by a call the
+    scan cannot follow back to ``parse_args``.
+    """
+    all_called_function_ids = {
+        id(each_node.func) for each_node in ast.walk(tree) if isinstance(each_node, ast.Call)
+    }
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Attribute):
+            continue
+        if each_node.attr not in ALL_PARSE_METHOD_NAMES:
+            continue
+        if id(each_node) not in all_called_function_ids:
+            return True
+    return False
+
+
+def _parse_result_binds_untracked_target(tree: ast.Module) -> bool:
+    """Return whether a parse-method result binds to a target the scan cannot track.
+
+    A ``parse_args``/``parse_known_args`` result bound by a plain or annotated
+    assignment to a plain ``ast.Name`` target, or to a tuple/list whose first
+    element is a plain ``ast.Name``, is tracked as a namespace variable. A result
+    bound to an attribute target (``self.args``) or a subscript target binds the
+    namespace where the scan cannot follow its attribute reads, so it escapes.
+    """
+    for each_node in ast.walk(tree):
+        binding_targets = _parse_result_binding_targets(each_node)
+        if binding_targets is None:
+            continue
+        for each_target in binding_targets:
+            if not _target_namespace_names(each_target):
+                return True
+    return False
+
+
+def _parse_call_consumed_inline(tree: ast.Module) -> bool:
+    """Return whether a parse-method result is consumed inline rather than bound to a target.
+
+    A ``parse_args``/``parse_known_args`` call is statically trackable only when its
+    result is the value of a plain assignment (``parsed = parser.parse_args()``), an
+    annotated assignment (``parsed: Namespace = parser.parse_args()``), or a bare
+    expression statement (``parser.parse_args(namespace=options)``, whose result is
+    discarded after populating the keyword object). Consumed inside a larger
+    expression instead -- returned directly, passed to ``vars``, double-star
+    unpacked, or bound by a walrus -- the namespace never reaches a tracked name, so
+    the check suppresses.
+    """
+    statement_bound_call_ids: set[int] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.Assign, ast.AnnAssign, ast.Expr)):
+            continue
+        if _is_parse_method_call(each_node.value):
+            statement_bound_call_ids.add(id(each_node.value))
+    for each_node in ast.walk(tree):
+        if _is_parse_method_call(each_node) and id(each_node) not in statement_bound_call_ids:
+            return True
+    return False
+
+
+def check_dead_argparse_arguments(
+    content: str, file_path: str, full_file_content: str | None = None
+) -> list[str]:
+    """Flag an optional argparse flag whose parsed value the same file never reads.
+
+    An optional ``add_argument("--flag", ...)`` is dead when its dest name never
+    appears as an attribute read, an augmented-assignment target, or a literal
+    ``getattr``/``attrgetter`` access anywhere in the file, the name is not listed
+    in a module-level ``__all__``, and no parsed namespace escapes static view. A
+    namespace escapes when a ``parse_args``/``parse_known_args`` bound method is
+    referenced as an aliased value rather than called inline, when a parse result
+    binds to an attribute- or subscript-target the scan cannot track, when a parse
+    result is consumed inline within a larger expression rather than bound to an
+    assignment or a bare statement, when a tracked namespace is read through
+    ``__dict__``, or when a tracked namespace Name is used as a value rather than an
+    attribute read (passed to a call, returned, aliased, double-star unpacked, or
+    nested inside a container literal), excluding the object of an attribute access
+    and a Name passed as the ``namespace=`` keyword to a parse call. A namespace
+    name is tracked when it binds a parse result, a tuple-unpacked
+    parse result, a ``namespace=`` keyword object, or an alias of one of these.
+    Positional arguments and the argparse ``help``/``version`` auto-actions are never
+    flagged. Whole-file analysis runs against ``full_file_content`` when supplied so
+    an Edit fragment is judged against the reconstructed post-edit file.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the test/migration exemptions.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead optional argument, capped at the configured
+        maximum.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_migration_file(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    dest_definitions = _argument_dest_definitions(tree)
+    if not dest_definitions:
+        return []
+    all_namespace_names = _namespace_variable_names(tree)
+    if _namespace_escapes(tree, all_namespace_names):
+        return []
+    read_names = _attribute_read_names(tree) | _dynamic_read_names(tree) | _exported_names(tree)
+    issues: list[str] = []
+    for each_dest_definition in dest_definitions:
+        dest_name, dest_line = each_dest_definition
+        if dest_name in read_names:
+            continue
+        issues.append(
+            f"Line {dest_line}: CLI argument {dest_name!r} - {DEAD_ARGPARSE_ARGUMENT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_DEAD_ARGPARSE_ARGUMENT_ISSUES:
+            return issues
+    return issues

package/hooks/blocking/code_rules_enforcer.py

@@ -52,6 +52,9 @@ from code_rules_constants_config import (  # noqa: E402
     check_constants_outside_config_advisory,
     check_file_global_constants_use_count,
 )
+from code_rules_dead_argparse_argument import (  # noqa: E402
+    check_dead_argparse_arguments,
+)
 from code_rules_dead_config_field import (  # noqa: E402
     check_dead_config_dataclass_fields,
 )
@@ -282,6 +285,9 @@ def validate_content(
         all_issues.extend(
             check_dead_dataclass_fields(content, file_path, full_file_content)
         )
+        all_issues.extend(
+            check_dead_argparse_arguments(content, file_path, full_file_content)
+        )
         all_issues.extend(
             check_dead_config_dataclass_fields(content, file_path, full_file_content)
         )