claude-dev-env 1.59.0 → 1.61.0

package/rules/file-global-constants.md

@@ -20,7 +20,13 @@ Test-file detection uses the following anchored patterns against the full relati
 
 ## `config/` files are exempt
 
-Constants placed in `config/` satisfy the constants-location rule; the use-count requirement applies only to production code outside `config/`.
+Constants placed in `config/` satisfy the constants-location rule; the use-count rule applies only to production code outside `config/`.
+
+## Dead constant in a dedicated constants module (cross-module)
+
+The use-count rule above governs a file-global constant in production code outside `config/` by counting same-file references. A dedicated constants module — a file whose name ends in `_constants.py`, or any module under a `config/` directory — exports its constants to importer modules elsewhere, so a same-file count proves nothing. A separate hook, `check_dead_module_constants` (dispatched from `code_rules_enforcer`), governs these modules: it flags an `UPPER_SNAKE` constant defined in the written module whose name appears in no `.py` module anywhere under the enclosing package tree — not imported, not read, not listed in an `__all__` literal, not named in a string annotation. That is the dead exported constant CODE_RULES §9.8 targets, caught at Write/Edit time.
+
+The scan resolves the enclosing package tree from the written file: for a constants module inside a package subdirectory, the tree is the package's parent (so an importer one directory up is in scope); for a `config/` module, the tree is the parent of the `config` directory. A module that declares its own `__all__` is skipped — the author's explicit export surface is taken as the liveness contract. A reference from a test module under the tree keeps a constant live. Test modules and migration modules are themselves exempt from the check.
 
 ## Examples
 

package/rules/no-cross-skill-duplicate-helpers.md

@@ -0,0 +1,29 @@
+---
+paths: "**/skills/*/scripts/**/*.py"
+---
+
+# Cross-Skill Duplicate Helpers
+
+**When this applies:** Any Write or Edit to a `.py` file under a skill's `scripts/` directory (`**/skills/<skill-name>/scripts/**/*.py`) that copies a top-level helper from another skill's `scripts/` directory.
+
+## The two duplication cases differ
+
+CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is blocking **within one skill** — two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` gate, and the fix is a shared module both import.
+
+Across **two skill folders** the same copy is a different call. Each skill folder installs on its own, so a shared module would couple two skills the install model keeps separate: deleting or reinstalling one skill would break a helper the other depends on. A small launch helper copied into each skill (for example a Chrome-open helper that reads the registry and runs `chrome.exe`) is a defensible skill-isolation tradeoff, not a regression.
+
+## Decision
+
+Before you copy a top-level helper from one skill's `scripts/` directory into another:
+
+- **Same skill, two modules** — extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` gate blocks the copy.
+- **Two skill folders, a small self-contained helper** — copy it; the skill-isolation tradeoff stands. A non-blocking `[CODE_RULES advisory]` names the source skill at Write time so the copy is a deliberate choice on record, not an oversight.
+- **Two skill folders, a large or behavior-bearing body** — when the copied body is large, holds business logic, or would drift in a way that changes behavior, raise the choice through `AskUserQuestion`: copy and accept drift, or stand up a shared dependency both skills declare (for example a published package both `requirements` files name, or a `_shared` module the install step writes into each skill). A shared dependency that survives independent install is the only shared-home path that does not break the install model.
+
+## What the advisory tells you
+
+The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never blocks) when a top-level function in the file being written has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders; within one skill the blocking gate already covers the copy.
+
+## Why this is a rule, not a wider gate
+
+Extending the blocking duplicate-body gate to span skill folders would deny the exact skill-isolation copy that keeps skills independently installable — a false positive on a sanctioned pattern. The boundary between "same skill, block" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment; the `[CODE_RULES advisory]` surfaces the signal; neither blocks the defensible copy.

package/rules/orphan-css-class.md

@@ -0,0 +1,23 @@
+# Orphan CSS Class in Generated Markup
+
+**When this applies:** Any Write or Edit to a production `.py` file that builds HTML by emitting `class="..."` attributes inside string literals and pairs them with a `<style>` block — in the same file or in a companion module beside it.
+
+## Rule
+
+Every class name a markup string references has a matching `.<class>` selector in the `<style>` block. A class that appears in the markup but carries no selector anywhere is a dead attribute (or a missing rule): the markup names a style that the stylesheet never defines, so a reader who trusts the class to be styled is misled, and the attribute adds noise without effect.
+
+When you add a `class="..."` attribute, add its `.<class>` selector to the `<style>` block in the same change. When you drop a selector, drop the class attribute it styled.
+
+## What the gate checks
+
+The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` (wired into `code_rules_enforcer.py`) runs on every production Python write. It:
+
+1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
+2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.
+3. Flags each referenced class with no matching selector in that whole set.
+
+The check stays quiet for a file that emits no `class="..."` markup, and for a file whose markup has no `<style>` source nearby (its stylesheet lives outside the scan, so the gate cannot judge it). Test files are exempt, since a fixture may carry intentional orphan markup.
+
+## Why this is a hook, not a lint pass
+
+A class attribute with no matching selector reads as styled but renders unstyled. Native elements such as `<details>` stay functional without CSS, so the gap survives review as a cosmetic defect rather than a crash — exactly the class of issue that slips past a manual pass and lands as a deferred code-standard finding. Catching it at Write time keeps the markup and the stylesheet in step as each line is written.

package/skills/_shared/pr-loop/scripts/preflight_worktree.py

@@ -0,0 +1,392 @@
+"""Preflight guard for the working directory and worktree before a PR-convergence run.
+
+Usage:
+  python preflight_worktree.py --owner <O> --repo <R> --mode <strict|classify>
+
+Modes:
+  strict   — autoconverge: the working directory must be the PR's own repo so
+             EnterWorktree can create and enter the branch worktree. Any other
+             state aborts (exit 1).
+  classify — pr-converge: emit the environment classification so the caller can
+             route. same_repo and different_repo both succeed (exit 0); a
+             re-rooted session (no git work tree, or no readable origin) aborts
+             (exit 1).
+
+Output (stdout):
+  A line 'PREFLIGHT_OUTCOME=<same_repo|different_repo|re_rooted>', a
+  human-readable summary, and, on abort, a recovery instruction.
+
+Exit codes:
+  0 — safe to continue for the given mode
+  1 — abort (the caller must stop and recover)
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_self_dir = Path(__file__).resolve().parent
+if str(_self_dir) not in sys.path:
+    sys.path.insert(0, str(_self_dir))
+
+from skills_pr_loop_constants.preflight_constants import (
+    ABORT_DIFFERENT_REPO_STRICT_TEMPLATE,
+    ABORT_RE_ROOTED_TEMPLATE,
+    ABORT_WORKTREE_BROKEN_TEMPLATE,
+    ALL_GIT_IS_INSIDE_WORK_TREE_ARGS,
+    ALL_GIT_REMOTE_GET_URL_ARGS,
+    ALL_GIT_WORKTREE_LIST_ARGS,
+    ALL_PREFLIGHT_MODES,
+    CWD_IDENTITY_UNKNOWN,
+    EXIT_PREFLIGHT_ABORT,
+    EXIT_PREFLIGHT_OK,
+    GIT_DIRECTORY_FLAG,
+    GIT_EXECUTABLE,
+    GIT_INSIDE_WORK_TREE_TRUE,
+    GIT_SUBPROCESS_TIMEOUT_SECONDS,
+    MODE_ARG_FLAG,
+    MODE_STRICT,
+    OUTCOME_DIFFERENT_REPO,
+    OUTCOME_MARKER_TEMPLATE,
+    OUTCOME_RE_ROOTED,
+    OUTCOME_SAME_REPO,
+    OWNER_ARG_FLAG,
+    PREFLIGHT_CLI_DESCRIPTION,
+    REMOTE_URL_IDENTITY_PATTERN,
+    REPO_ARG_FLAG,
+    ROUTE_DIFFERENT_REPO_TEMPLATE,
+    SUMMARY_DIFFERENT_REPO_TEMPLATE,
+    SUMMARY_RE_ROOTED_TEMPLATE,
+    SUMMARY_SAME_REPO_TEMPLATE,
+)
+
+
+@dataclass(frozen=True)
+class RepoIdentity:
+    """A GitHub repository identity parsed from a git remote URL.
+
+    Attributes:
+        owner: Repository owner (login or org), lower-cased for comparison.
+        repo: Repository name, lower-cased for comparison.
+    """
+
+    owner: str
+    repo: str
+
+
+@dataclass(frozen=True)
+class PreflightVerdict:
+    """Classification of the working directory against a target PR repo.
+
+    Attributes:
+        outcome: One of OUTCOME_SAME_REPO, OUTCOME_DIFFERENT_REPO, or
+            OUTCOME_RE_ROOTED.
+        cwd_identity: Parsed identity of the working directory's origin, or
+            None when there is no git work tree, no origin, or an unparseable
+            origin URL.
+        has_healthy_worktree_machinery: True when 'git worktree list' runs
+            cleanly in the working directory.
+    """
+
+    outcome: str
+    cwd_identity: RepoIdentity | None
+    has_healthy_worktree_machinery: bool
+
+
+def parse_repo_identity(remote_url: str) -> RepoIdentity | None:
+    """Parse a GitHub owner/repo from a git remote URL.
+
+    Accepts the https, git@ (scp-like), and ssh:// forms and drops a trailing
+    '.git'. Comparison is case-insensitive, so the returned owner and repo are
+    lower-cased.
+
+    Args:
+        remote_url: The remote URL from 'git remote get-url origin'.
+
+    Returns:
+        A RepoIdentity, or None when the URL is not a GitHub remote.
+    """
+    match = REMOTE_URL_IDENTITY_PATTERN.search(remote_url.strip())
+    if match is None:
+        return None
+    return RepoIdentity(
+        owner=match.group("owner").lower(),
+        repo=match.group("repo").lower(),
+    )
+
+
+def _run_git(
+    working_directory: Path, all_git_arguments: tuple[str, ...]
+) -> subprocess.CompletedProcess[str]:
+    """Run a git subcommand in a working directory with a bounded timeout.
+
+    Args:
+        working_directory: Directory to run git in (passed via 'git -C').
+        all_git_arguments: The git subcommand and its arguments.
+
+    Returns:
+        The completed process with captured text stdout and stderr.
+    """
+    return subprocess.run(
+        [
+            GIT_EXECUTABLE,
+            GIT_DIRECTORY_FLAG,
+            str(working_directory),
+            *all_git_arguments,
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=GIT_SUBPROCESS_TIMEOUT_SECONDS,
+    )
+
+
+def is_inside_work_tree(working_directory: Path) -> bool:
+    """Report whether the working directory is inside a git work tree.
+
+    Args:
+        working_directory: Directory to test.
+
+    Returns:
+        True when 'git rev-parse --is-inside-work-tree' prints 'true'.
+    """
+    completed = _run_git(working_directory, ALL_GIT_IS_INSIDE_WORK_TREE_ARGS)
+    return completed.returncode == 0 and (
+        completed.stdout.strip() == GIT_INSIDE_WORK_TREE_TRUE
+    )
+
+
+def worktree_machinery_is_healthy(working_directory: Path) -> bool:
+    """Report whether git worktree machinery works in the working directory.
+
+    EnterWorktree relies on 'git worktree' to create and enter the branch
+    worktree; a failing worktree list means it cannot.
+
+    Args:
+        working_directory: Directory to test.
+
+    Returns:
+        True when 'git worktree list' exits cleanly.
+    """
+    completed = _run_git(working_directory, ALL_GIT_WORKTREE_LIST_ARGS)
+    return completed.returncode == 0
+
+
+def classify_environment(
+    working_directory: Path, pr_identity: RepoIdentity
+) -> PreflightVerdict:
+    """Classify the working directory against the target PR repository.
+
+    Args:
+        working_directory: The session's current working directory.
+        pr_identity: The PR's owner/repo (lower-cased for comparison).
+
+    Returns:
+        A PreflightVerdict naming the outcome and the worktree-machinery health.
+    """
+    if not is_inside_work_tree(working_directory):
+        return PreflightVerdict(OUTCOME_RE_ROOTED, None, False)
+    has_healthy_machinery = worktree_machinery_is_healthy(working_directory)
+    remote = _run_git(working_directory, ALL_GIT_REMOTE_GET_URL_ARGS)
+    if remote.returncode != 0:
+        return PreflightVerdict(OUTCOME_RE_ROOTED, None, has_healthy_machinery)
+    cwd_identity = parse_repo_identity(remote.stdout)
+    if cwd_identity is None:
+        return PreflightVerdict(OUTCOME_DIFFERENT_REPO, None, has_healthy_machinery)
+    if cwd_identity == pr_identity:
+        return PreflightVerdict(OUTCOME_SAME_REPO, cwd_identity, has_healthy_machinery)
+    return PreflightVerdict(OUTCOME_DIFFERENT_REPO, cwd_identity, has_healthy_machinery)
+
+
+def decide_exit_code(verdict: PreflightVerdict, mode: str) -> int:
+    """Decide the process exit code from a classification and the mode.
+
+    Args:
+        verdict: The classification of the working directory.
+        mode: MODE_STRICT (autoconverge) or MODE_CLASSIFY (pr-converge).
+
+    Returns:
+        EXIT_PREFLIGHT_OK when it is safe to continue, else EXIT_PREFLIGHT_ABORT.
+    """
+    if verdict.outcome == OUTCOME_RE_ROOTED:
+        return EXIT_PREFLIGHT_ABORT
+    if verdict.outcome == OUTCOME_SAME_REPO:
+        if not verdict.has_healthy_worktree_machinery:
+            return EXIT_PREFLIGHT_ABORT
+        return EXIT_PREFLIGHT_OK
+    if mode == MODE_STRICT:
+        return EXIT_PREFLIGHT_ABORT
+    return EXIT_PREFLIGHT_OK
+
+
+def _cwd_identity_labels(verdict: PreflightVerdict) -> tuple[str, str]:
+    """Return display labels for the working directory's owner and repo.
+
+    Args:
+        verdict: The classification of the working directory.
+
+    Returns:
+        The lower-cased owner and repo, or the unknown placeholder for each
+        when the working directory identity could not be parsed.
+    """
+    if verdict.cwd_identity is None:
+        return CWD_IDENTITY_UNKNOWN, CWD_IDENTITY_UNKNOWN
+    return verdict.cwd_identity.owner, verdict.cwd_identity.repo
+
+
+def _same_repo_lines(
+    verdict: PreflightVerdict, working_directory: Path, pr_identity: RepoIdentity
+) -> list[str]:
+    """Build the report lines for the same-repo outcome.
+
+    Args:
+        verdict: The classification of the working directory.
+        working_directory: The session's current working directory.
+        pr_identity: The PR's owner/repo.
+
+    Returns:
+        A summary line, plus an abort line when the worktree machinery is broken.
+    """
+    report_lines = [
+        SUMMARY_SAME_REPO_TEMPLATE.format(
+            owner=pr_identity.owner, repo=pr_identity.repo
+        )
+    ]
+    if not verdict.has_healthy_worktree_machinery:
+        report_lines.append(
+            ABORT_WORKTREE_BROKEN_TEMPLATE.format(cwd=working_directory)
+        )
+    return report_lines
+
+
+def _different_repo_lines(
+    verdict: PreflightVerdict, mode: str, pr_identity: RepoIdentity
+) -> list[str]:
+    """Build the report lines for the different-repo outcome.
+
+    Args:
+        verdict: The classification of the working directory.
+        mode: MODE_STRICT (autoconverge) or MODE_CLASSIFY (pr-converge).
+        pr_identity: The PR's owner/repo.
+
+    Returns:
+        A summary line, plus an abort line under strict mode or a route line
+        under classify mode.
+    """
+    cwd_owner, cwd_repo = _cwd_identity_labels(verdict)
+    report_lines = [
+        SUMMARY_DIFFERENT_REPO_TEMPLATE.format(
+            cwd_owner=cwd_owner,
+            cwd_repo=cwd_repo,
+            owner=pr_identity.owner,
+            repo=pr_identity.repo,
+        )
+    ]
+    if mode == MODE_STRICT:
+        report_lines.append(
+            ABORT_DIFFERENT_REPO_STRICT_TEMPLATE.format(
+                cwd_owner=cwd_owner,
+                cwd_repo=cwd_repo,
+                owner=pr_identity.owner,
+                repo=pr_identity.repo,
+            )
+        )
+    else:
+        report_lines.append(
+            ROUTE_DIFFERENT_REPO_TEMPLATE.format(
+                owner=pr_identity.owner, repo=pr_identity.repo
+            )
+        )
+    return report_lines
+
+
+def _re_rooted_lines(working_directory: Path, pr_identity: RepoIdentity) -> list[str]:
+    """Build the report lines for the re-rooted outcome.
+
+    Args:
+        working_directory: The session's current working directory.
+        pr_identity: The PR's owner/repo.
+
+    Returns:
+        A summary line and an abort line with the recovery instruction.
+    """
+    return [
+        SUMMARY_RE_ROOTED_TEMPLATE.format(cwd=working_directory),
+        ABORT_RE_ROOTED_TEMPLATE.format(owner=pr_identity.owner, repo=pr_identity.repo),
+    ]
+
+
+def build_report_lines(
+    verdict: PreflightVerdict,
+    mode: str,
+    working_directory: Path,
+    pr_identity: RepoIdentity,
+) -> list[str]:
+    """Build the stdout report lines for a classification.
+
+    Args:
+        verdict: The classification of the working directory.
+        mode: MODE_STRICT (autoconverge) or MODE_CLASSIFY (pr-converge).
+        working_directory: The session's current working directory.
+        pr_identity: The PR's owner/repo.
+
+    Returns:
+        Lines to print: the machine-readable outcome marker first, then a
+        summary and a recovery or routing instruction when relevant.
+    """
+    report_lines = [OUTCOME_MARKER_TEMPLATE.format(outcome=verdict.outcome)]
+    if verdict.outcome == OUTCOME_SAME_REPO:
+        report_lines.extend(_same_repo_lines(verdict, working_directory, pr_identity))
+    elif verdict.outcome == OUTCOME_DIFFERENT_REPO:
+        report_lines.extend(_different_repo_lines(verdict, mode, pr_identity))
+    else:
+        report_lines.extend(_re_rooted_lines(working_directory, pr_identity))
+    return report_lines
+
+
+def main(all_arguments: list[str]) -> int:
+    """Classify the working directory and report whether the run can continue.
+
+    Args:
+        all_arguments: The argument vector (sys.argv[1:] in normal use).
+
+    Returns:
+        The process exit code (EXIT_PREFLIGHT_OK or EXIT_PREFLIGHT_ABORT).
+    """
+    parser = argparse.ArgumentParser(description=PREFLIGHT_CLI_DESCRIPTION)
+    parser.add_argument(OWNER_ARG_FLAG, required=True)
+    parser.add_argument(REPO_ARG_FLAG, required=True)
+    parser.add_argument(MODE_ARG_FLAG, required=True, choices=ALL_PREFLIGHT_MODES)
+    parsed_arguments = parser.parse_args(all_arguments)
+    pr_identity = RepoIdentity(
+        owner=parsed_arguments.owner.lower(),
+        repo=parsed_arguments.repo.lower(),
+    )
+    working_directory = Path.cwd()
+    try:
+        verdict = classify_environment(working_directory, pr_identity)
+    except subprocess.TimeoutExpired:
+        print(
+            OUTCOME_MARKER_TEMPLATE.format(outcome=OUTCOME_RE_ROOTED),
+            file=sys.stdout,
+        )
+        print(
+            ABORT_RE_ROOTED_TEMPLATE.format(
+                owner=pr_identity.owner, repo=pr_identity.repo
+            ),
+            file=sys.stdout,
+        )
+        return EXIT_PREFLIGHT_ABORT
+    for each_report_line in build_report_lines(
+        verdict, parsed_arguments.mode, working_directory, pr_identity
+    ):
+        print(each_report_line, file=sys.stdout)
+    return decide_exit_code(verdict, parsed_arguments.mode)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/preflight_constants.py

@@ -0,0 +1,70 @@
+"""Constants for the worktree/cwd preflight guard shared by pr-loop skills."""
+
+import re
+
+OUTCOME_SAME_REPO = "same_repo"
+OUTCOME_DIFFERENT_REPO = "different_repo"
+OUTCOME_RE_ROOTED = "re_rooted"
+
+MODE_STRICT = "strict"
+MODE_CLASSIFY = "classify"
+ALL_PREFLIGHT_MODES = (MODE_STRICT, MODE_CLASSIFY)
+
+EXIT_PREFLIGHT_OK = 0
+EXIT_PREFLIGHT_ABORT = 1
+
+GIT_EXECUTABLE = "git"
+GIT_DIRECTORY_FLAG = "-C"
+ALL_GIT_IS_INSIDE_WORK_TREE_ARGS = ("rev-parse", "--is-inside-work-tree")
+ALL_GIT_REMOTE_GET_URL_ARGS = ("remote", "get-url", "origin")
+ALL_GIT_WORKTREE_LIST_ARGS = ("worktree", "list")
+GIT_INSIDE_WORK_TREE_TRUE = "true"
+GIT_SUBPROCESS_TIMEOUT_SECONDS = 30
+
+REMOTE_URL_IDENTITY_PATTERN = re.compile(
+    r"github\.com[:/](?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$"
+)
+
+CWD_IDENTITY_UNKNOWN = "unknown"
+
+OWNER_ARG_FLAG = "--owner"
+REPO_ARG_FLAG = "--repo"
+MODE_ARG_FLAG = "--mode"
+
+PREFLIGHT_CLI_DESCRIPTION = (
+    "Verify the working directory and worktree before a PR-convergence run."
+)
+
+OUTCOME_MARKER_TEMPLATE = "PREFLIGHT_OUTCOME={outcome}"
+
+SUMMARY_SAME_REPO_TEMPLATE = (
+    "OK: the working directory is the PR repo {owner}/{repo}; EnterWorktree can "
+    "create and enter the branch worktree."
+)
+SUMMARY_DIFFERENT_REPO_TEMPLATE = (
+    "The working directory repo {cwd_owner}/{cwd_repo} differs from the PR repo "
+    "{owner}/{repo}."
+)
+SUMMARY_RE_ROOTED_TEMPLATE = (
+    "The working directory {cwd} is not a usable checkout of a GitHub repo "
+    "(no git work tree, or no readable origin remote)."
+)
+ABORT_DIFFERENT_REPO_STRICT_TEMPLATE = (
+    "ABORT: autoconverge runs inside the PR's own repo, but this session is "
+    "rooted in {cwd_owner}/{cwd_repo}. Start the session from a checkout of "
+    "{owner}/{repo} and re-run."
+)
+ABORT_RE_ROOTED_TEMPLATE = (
+    "ABORT: this session is not rooted in a git checkout (a resumed or "
+    "background session can re-root to the home directory). Start the session "
+    "from a checkout of {owner}/{repo} and re-run."
+)
+ABORT_WORKTREE_BROKEN_TEMPLATE = (
+    "ABORT: the git worktree machinery in {cwd} is broken (git worktree list "
+    "failed), so EnterWorktree cannot create the branch worktree. Run "
+    "'git worktree prune' in {cwd} and re-run."
+)
+ROUTE_DIFFERENT_REPO_TEMPLATE = (
+    "ROUTE: resolve the PR worktree for {owner}/{repo} and cd into it before "
+    "any local work (cross-repo PR)."
+)