claude-dev-env 8.8.0 → 8.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.8.0",
+    "version": "8.10.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/durable-post-artifacts.md

@@ -3,7 +3,8 @@
 ## When this applies
 
 Use this rule for a GitHub issue, pull request, comment, or review created
-through `gh` or a GitHub MCP post tool.
+through `gh` or a GitHub MCP post tool. The image section also covers a PNG a
+commit adds and a file a release upload sends.
 
 ## Rule
 
@@ -26,6 +27,24 @@ Handle text and binary content differently:
   under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints a permanent download
   URL. Put that URL in the post.
 
+## Optimize every image before it reaches GitHub
+
+The helper shrinks a PNG with [oxipng](https://github.com/oxipng/oxipng) before
+it uploads, and prints the size before and after. Oxipng is lossless.
+`--strip none` keeps every chunk, and `--nb --nc` keep the bit depth and the
+color type, so a reader that checks the image mode sees the same file shape.
+
+Any other route to GitHub runs the same pass first: a PNG a commit adds, and a
+file sent with `gh release upload`.
+
+```
+oxipng --opt 4 --strip none --nb --nc <file> [<file> ...]
+```
+
+The `Binary optimization` check fails a pull request whose changed PNG files
+still shrink under that pass. A fixture whose exact bytes a test pins takes
+`binary-optimizer=keep` in `.gitattributes`, and the check skips it.
+
 ## Volatile paths that must not appear in a post body
 
 - A job scratch directory: `.claude-profile-a/jobs/`
@@ -46,5 +65,11 @@ server write. Pass the matching action and body file. Use `pr-create`,
 `pr-edit`, `pr-comment`, `pr-review`, `issue-create`, `issue-edit`,
 `issue-comment`, or `github-mcp-post`.
 
+Pass `--repository <owner>/<name>` for the repository the post targets. A
+post may name a private organization only inside a repository that
+organization owns. The linter holds the names as digests, so it reports the
+line that names one without printing the name. Describe the organization in
+general terms and drop the link.
+
 The linter reads the body file and reports a volatile local path without
 printing the body. Fix the body and rerun the linter before posting.

package/rules/prefer-existing-tools.md

@@ -0,0 +1,35 @@
+# Prefer Existing Tools
+
+**When this applies:** Before you build a tool, check, scanner, script, or library of your own.
+
+## Rule
+
+Search in this order, and stop at the first fit:
+
+1. **Internal code.** Search the repository and its shared packages for a tool that already does the job. Reuse or extend it.
+2. **An established open-source option.** Search for a plugin, package, or tool that already does the job.
+3. **Your own code.** Build it only when steps 1 and 2 find nothing that fits.
+
+Use an open-source option only when it meets all four conditions:
+
+- It is secure: it has an active security process and no open critical advisory.
+- It is well known in its field.
+- It is widely used: many stars, downloads, or dependents.
+- It is maintained: it had a release or commit in the last year.
+
+Add only what the option lacks. Put custom rules in its own configuration format. Do not wrap it in a new layer of your own code.
+
+## Report the choice
+
+Tell the user which tool you chose before the work is marked ready. Give its name, link, license, and one number that shows how widely it is used. When you build your own code, name what you searched and why each candidate did not fit.
+
+## Why
+
+Code of your own is code you maintain alone. A trusted tool carries fixes and new patterns from its community, and its users find its defects first.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`explore-thoroughly.md`](explore-thoroughly.md) | Read what exists before you propose a change |
+| [`verify-before-asking.md`](verify-before-asking.md) | Answer a question with a tool before you ask it |

package/rules/review-closure-is-a-check.md

@@ -33,7 +33,7 @@ The driving account is the one that opened the pull request. Where the agent com
 
 `.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, and on a review comment. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
 
-`Echo-Visuals-Inc/python-automation` runs the same command from its own workflow, against the revision of this package that its workflow pins.
+A private repository that installs this package runs the same command from its own workflow, against the revision of this package that its workflow pins.
 
 ## Sibling rules
 

package/scripts/claude_account_choice.py

@@ -41,7 +41,12 @@ from dev_env_scripts_constants.claude_account_constants import (
     FULL_PERCENT,
     JSON_ACCOUNT_KEY,
     JSON_CONFIG_DIRECTORY_KEY,
+    JSON_METERS_KEY,
     JSON_REASON_KEY,
+    JSON_SESSION_RESETS_AT_KEY,
+    JSON_SESSION_USED_PERCENT_KEY,
+    JSON_WEEKLY_RESETS_AT_KEY,
+    JSON_WEEKLY_USED_PERCENT_KEY,
     MAIN_CLAUDE_HOME_DIRECTORY_NAME,
     MAIN_SESSION_USED_CEILING_PERCENT,
     MAIN_SPEND_WINDOW,
@@ -216,8 +221,39 @@ def decision_payload(
     }
 
 
+def _iso_or_none(moment: datetime | None) -> str | None:
+    return moment.isoformat() if moment else None
+
+
+def meters_payload(
+    account_meters: AccountUsageMeters | None,
+) -> dict[str, float | str | None] | None:
+    """Shape one account's meters as the JSON object a usage report reads.
+
+    ::
+
+        AccountUsageMeters(12.0, <reset>, 34.0, <reset>)
+        -> {"session_used_percent": 12.0, "session_resets_at": "2026-09-22T22:00:00+00:00",
+            "weekly_used_percent": 34.0, "weekly_resets_at": "2026-09-25T21:00:00+00:00"}
+
+    Args:
+        account_meters: The account's meters, or None when unread.
+
+    Returns:
+        Each used percent and reset time, or None for an unread account.
+    """
+    if account_meters is None:
+        return None
+    return {
+        JSON_SESSION_USED_PERCENT_KEY: account_meters.session_utilization,
+        JSON_SESSION_RESETS_AT_KEY: _iso_or_none(account_meters.session_resets_at),
+        JSON_WEEKLY_USED_PERCENT_KEY: account_meters.weekly_utilization,
+        JSON_WEEKLY_RESETS_AT_KEY: _iso_or_none(account_meters.weekly_resets_at),
+    }
+
+
 def main(all_command_arguments: list[str]) -> int:
-    """Print the chosen account as JSON.
+    """Print the chosen account and both accounts' meters as JSON.
 
     Args:
         all_command_arguments: Command-line arguments after the program name.
@@ -230,15 +266,24 @@ def main(all_command_arguments: list[str]) -> int:
         CHOICE_MAIN: arguments.main_config_dir,
         CHOICE_SECOND: arguments.second_config_dir,
     }
+    main_meters = read_account_meters(arguments.main_config_dir / CREDENTIALS_FILE_NAME)
+    second_meters = read_account_meters(
+        arguments.second_config_dir / CREDENTIALS_FILE_NAME
+    )
     decision = choose_account(
-        main_meters=read_account_meters(arguments.main_config_dir / CREDENTIALS_FILE_NAME),
-        second_meters=read_account_meters(
-            arguments.second_config_dir / CREDENTIALS_FILE_NAME
-        ),
+        main_meters=main_meters,
+        second_meters=second_meters,
         now=datetime.now().astimezone(),
     )
     config_directory = config_directory_by_account.get(decision.account)
-    print(json.dumps(decision_payload(decision, config_directory=config_directory)))
+    report = {
+        **decision_payload(decision, config_directory=config_directory),
+        JSON_METERS_KEY: {
+            CHOICE_MAIN: meters_payload(main_meters),
+            CHOICE_SECOND: meters_payload(second_meters),
+        },
+    }
+    print(json.dumps(report))
     return 0
 
 

package/scripts/dev_env_scripts_constants/claude_account_constants.py

@@ -153,6 +153,21 @@ JSON_CONFIG_DIRECTORY_KEY: str = "config_dir"
 JSON_REASON_KEY: str = "reason"
 """Picker JSON key carrying the plain-words reason for the choice."""
 
+JSON_METERS_KEY: str = "meters"
+"""Picker JSON key carrying both accounts' meters, each None when unread."""
+
+JSON_SESSION_USED_PERCENT_KEY: str = "session_used_percent"
+"""Meters JSON key for the percent of the 5-hour window used."""
+
+JSON_SESSION_RESETS_AT_KEY: str = "session_resets_at"
+"""Meters JSON key for when the 5-hour window resets."""
+
+JSON_WEEKLY_USED_PERCENT_KEY: str = "weekly_used_percent"
+"""Meters JSON key for the percent of the week used."""
+
+JSON_WEEKLY_RESETS_AT_KEY: str = "weekly_resets_at"
+"""Meters JSON key for when the week resets."""
+
 JSON_LINKED_KEY: str = "linked"
 """Sync JSON key listing entries the run linked."""
 

package/scripts/dev_env_scripts_constants/gh_artifact_upload_constants.py

@@ -41,3 +41,30 @@ NOTES_FILE_SUFFIX: str = ".md"
 
 UTF8_ENCODING: str = "utf-8"
 """Text encoding for subprocess output and temp files."""
+
+PNG_SUFFIX: str = ".png"
+"""Suffix of a file the upload shrinks with oxipng before it sends."""
+
+OXIPNG_BINARY_NAME: str = "oxipng"
+"""The oxipng executable name, looked up on PATH."""
+
+ALL_OXIPNG_LOSSLESS_ARGUMENTS: tuple[str, ...] = (
+    "--opt",
+    "4",
+    "--strip",
+    "none",
+    "--nb",
+    "--nc",
+    "--quiet",
+)
+"""Oxipng options: a slow lossless search that keeps every chunk, the bit
+depth, and the color type."""
+
+OXIPNG_MISSING_MESSAGE: str = (
+    "oxipng is not on PATH. Install the release binary from "
+    "https://github.com/oxipng/oxipng/releases, then upload again."
+)
+"""Failure text when a PNG upload finds no oxipng to shrink it first."""
+
+SIZE_REPORT_TEMPLATE: str = "{name}: {original_size} -> {optimized_size} bytes"
+"""Line naming an upload and its size before and after oxipng."""

package/scripts/dev_env_scripts_constants/private_term_constants.py

@@ -0,0 +1,60 @@
+"""Digests of the private organization names this public repository never names.
+
+The names stay out of the tree. Each entry holds the SHA-256 digest of one
+name after normalization, which keeps only ASCII letters and digits in lower
+case::
+
+    "Acme-Widgets, Inc."          -> "acmewidgetsinc"
+    "pat@acmewidgets.example.com" -> "patacmewidgetsexamplecom"
+
+A scan hashes every window of the normalized text whose length matches an
+entry, so any case, spacing, or punctuation of a name matches. To add a name,
+append the digest of its normalized form and its length.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PrivateTermDigest:
+    """The length and SHA-256 hex digest of one normalized private name."""
+
+    length: int
+    sha256: str
+
+
+ALL_PRIVATE_TERM_DIGESTS: frozenset[PrivateTermDigest] = frozenset(
+    {
+        PrivateTermDigest(
+            length=10,
+            sha256="c2a70b3186691a74dece4ca824bec178bfaec83be119be28faedd14aa392233f",
+        ),
+    }
+)
+PRIVATE_TERM_TEXT_ENCODING = "utf-8"
+PRIVATE_TERM_FINDING_CODE = "private-term"
+PRIVATE_TERM_MESSAGE_TEMPLATE = (
+    "Line {line_number} names a private organization. "
+    "Describe it in general terms and drop any link to it."
+)
+ALL_EVENT_TEXT_FIELDS: tuple[tuple[str, str, str], ...] = (
+    ("pull_request", "title", "pull request title"),
+    ("pull_request", "body", "pull request body"),
+    ("issue", "title", "issue title"),
+    ("issue", "body", "issue body"),
+    ("comment", "body", "comment body"),
+    ("review", "body", "review body"),
+    ("release", "name", "release name"),
+    ("release", "body", "release body"),
+)
+FINDING_LINE_TEMPLATE = "{label}: {message}"
+COMMIT_LABEL_TEMPLATE = "commit {short_sha} {part}"
+COMMIT_IDENTITY_PART = "identity"
+COMMIT_MESSAGE_PART = "message"
+SHORT_SHA_LENGTH = 12
+COMMIT_FIELD_SEPARATOR = "\x1f"
+COMMIT_RECORD_SEPARATOR = "\x1e"
+COMMIT_FIELD_SPLIT_LIMIT = 2
+COMMIT_LOG_FORMAT = "--format=%H%x1f%an <%ae> %cn <%ce>%x1f%B%x1e"

package/scripts/dev_env_scripts_constants/test_claude_account_constants.py

@@ -3,6 +3,14 @@
 from __future__ import annotations
 
 from dev_env_scripts_constants.claude_account_constants import (
+    JSON_ACCOUNT_KEY,
+    JSON_CONFIG_DIRECTORY_KEY,
+    JSON_METERS_KEY,
+    JSON_REASON_KEY,
+    JSON_SESSION_RESETS_AT_KEY,
+    JSON_SESSION_USED_PERCENT_KEY,
+    JSON_WEEKLY_RESETS_AT_KEY,
+    JSON_WEEKLY_USED_PERCENT_KEY,
     LAUNCHER_TEXT_TEMPLATE,
     MAIN_SESSION_USED_CEILING_PERCENT,
     MAIN_WEEKLY_USED_CEILING_PERCENT,
@@ -19,3 +27,20 @@ def test_main_ceilings_sit_below_the_second_account_ceilings() -> None:
 def test_launcher_names_the_profile_and_passes_every_argument() -> None:
     assert "{profile_home}" in LAUNCHER_TEXT_TEMPLATE
     assert "claude %*" in LAUNCHER_TEXT_TEMPLATE
+
+
+def test_picker_report_keys_never_collide() -> None:
+    all_report_keys = [
+        JSON_ACCOUNT_KEY,
+        JSON_CONFIG_DIRECTORY_KEY,
+        JSON_REASON_KEY,
+        JSON_METERS_KEY,
+    ]
+    all_meter_keys = [
+        JSON_SESSION_USED_PERCENT_KEY,
+        JSON_SESSION_RESETS_AT_KEY,
+        JSON_WEEKLY_USED_PERCENT_KEY,
+        JSON_WEEKLY_RESETS_AT_KEY,
+    ]
+    assert len(set(all_report_keys)) == len(all_report_keys)
+    assert len(set(all_meter_keys)) == len(all_meter_keys)

package/scripts/dev_env_scripts_constants/test_private_term_constants.py

@@ -0,0 +1,29 @@
+"""Tests for the private-term digest table."""
+
+from __future__ import annotations
+
+import re
+
+from dev_env_scripts_constants.private_term_constants import (
+    ALL_EVENT_TEXT_FIELDS,
+    ALL_PRIVATE_TERM_DIGESTS,
+)
+
+_SHA256_HEX_PATTERN = re.compile(r"[0-9a-f]{64}")
+
+
+def test_should_ship_only_digests_of_named_lengths() -> None:
+    assert ALL_PRIVATE_TERM_DIGESTS
+    for each_digest in ALL_PRIVATE_TERM_DIGESTS:
+        assert _SHA256_HEX_PATTERN.fullmatch(each_digest.sha256)
+        assert each_digest.length > 0
+
+
+def test_should_read_every_text_a_pull_request_issue_comment_review_or_release_carries() -> None:
+    assert {each_object for each_object, _field, _label in ALL_EVENT_TEXT_FIELDS} == {
+        "pull_request",
+        "issue",
+        "comment",
+        "review",
+        "release",
+    }

package/scripts/durable_post_lint.py

@@ -12,6 +12,11 @@ from contrast_framing import describe_contrast_framing, find_contrast_framing
 from dev_env_scripts_constants.contrast_framing_constants import (
     CONTRAST_FRAMING_FINDING_CODE,
 )
+from dev_env_scripts_constants.private_term_constants import (
+    ALL_PRIVATE_TERM_DIGESTS,
+    PRIVATE_TERM_FINDING_CODE,
+    PRIVATE_TERM_MESSAGE_TEMPLATE,
+)
 from durable_post_lint_config.config.constants import (
     ACTION_PR_CREATE,
     ACTION_PR_EDIT,
@@ -41,6 +46,7 @@ from durable_post_lint_config.config.constants import (
     PATH_ANCHOR_CHARACTER,
     PATH_SEGMENT_START_CHARACTERS,
     RELEASE_BRANCH_PREFIX,
+    REPOSITORY_OWNER_SEPARATOR,
     REWRITTEN_RELEASE_BODY_CODE,
     REWRITTEN_RELEASE_BODY_MESSAGE,
     TITLE_NOT_ALLOWED_MESSAGE,
@@ -48,6 +54,7 @@ from durable_post_lint_config.config.constants import (
     VOLATILE_PATH_CODE,
     VOLATILE_PATH_MESSAGE,
 )
+from private_terms import private_term_line_numbers
 
 
 class DurablePostUsageError(ValueError):
@@ -153,6 +160,26 @@ def _contrast_framing_findings(text: str) -> list[DurablePostFinding]:
     ]
 
 
+def _private_term_findings(
+    text: str | None, repository: str | None
+) -> list[DurablePostFinding]:
+    if text is None:
+        return []
+    if repository is not None and private_term_line_numbers(
+        repository.split(REPOSITORY_OWNER_SEPARATOR)[0], ALL_PRIVATE_TERM_DIGESTS
+    ):
+        return []
+    return [
+        DurablePostFinding(
+            code=PRIVATE_TERM_FINDING_CODE,
+            message=PRIVATE_TERM_MESSAGE_TEMPLATE.format(line_number=each_line_number),
+        )
+        for each_line_number in private_term_line_numbers(
+            text, ALL_PRIVATE_TERM_DIGESTS
+        )
+    ]
+
+
 def _title_findings(title: str | None) -> list[DurablePostFinding]:
     if title is None:
         return []
@@ -215,12 +242,29 @@ def lint_durable_post(
     title: str | None,
     body_text: str | None,
     head_branch: str | None = None,
+    repository: str | None = None,
 ) -> tuple[DurablePostFinding, ...]:
-    """Return content findings for one locally valid GitHub post request."""
+    """Return content findings for one locally valid GitHub post request.
+
+    A post to a repository whose owner is a private organization may name that
+    organization. Every other post, and a post with no repository given, may not.
+
+    Args:
+        action: The post action, such as ``pr-create`` or ``issue-comment``.
+        title: The post title, when the action carries one.
+        body_text: The post body, when the action carries one.
+        head_branch: The pull request head branch, when known.
+        repository: The ``owner/name`` the post targets, when known.
+
+    Returns:
+        Every finding, title findings first.
+    """
     _validate_request_shape(action, title, body_text)
     return (
         *_title_findings(title),
+        *_private_term_findings(title, repository),
         *_body_findings(action, body_text, head_branch),
+        *_private_term_findings(body_text, repository),
     )
 
 
@@ -230,6 +274,7 @@ def _parse_arguments(all_arguments: Sequence[str]) -> argparse.Namespace:
     parser.add_argument("--title")
     parser.add_argument("--body-file", type=Path)
     parser.add_argument("--head-branch")
+    parser.add_argument("--repository")
     return parser.parse_args(list(all_arguments))
 
 
@@ -247,6 +292,7 @@ def main(all_arguments: Sequence[str]) -> int:
             title=arguments.title,
             body_text=body_text,
             head_branch=arguments.head_branch,
+            repository=arguments.repository,
         )
     except (DurablePostInputError, DurablePostUsageError) as error:
         sys.stderr.write(f"{error}\n")

package/scripts/durable_post_lint_config/config/constants.py

@@ -101,3 +101,4 @@ REWRITTEN_RELEASE_BODY_MESSAGE = (
     "release automation reads this body back to recognize its own merge; "
     "keep the generated text whole"
 )
+REPOSITORY_OWNER_SEPARATOR = "/"

package/scripts/gh_artifact_upload.py

@@ -5,8 +5,8 @@ A durable GitHub post (issue, PR, comment, review) must not link a file under a
 job scratch directory or worktree, because that scratch is cleaned soon after
 the run while the post lives forever. Binary artifacts belong in a permanent
 place instead. This tool ensures the repo has a prerelease tagged ``artifacts``,
-uploads the given file under a timestamped asset name, and prints the permanent
-download URL a post can safely link. The timestamped name keeps each upload a
+shrinks a PNG losslessly with oxipng, uploads the file under a timestamped asset
+name, and prints the permanent download URL a post can safely link. The timestamped name keeps each upload a
 distinct asset. An upload never overwrites an earlier one. A same-name collision
 fails loudly instead of replacing the bytes an existing URL already serves.
 
@@ -28,6 +28,7 @@ import tempfile
 from pathlib import Path
 
 from dev_env_scripts_constants.gh_artifact_upload_constants import (
+    ALL_OXIPNG_LOSSLESS_ARGUMENTS,
     ARTIFACTS_RELEASE_NOTES,
     ARTIFACTS_RELEASE_TAG,
     ARTIFACTS_RELEASE_TITLE,
@@ -37,7 +38,11 @@ from dev_env_scripts_constants.gh_artifact_upload_constants import (
     ASSET_URL_JSON_KEY,
     GH_BINARY_NAME,
     NOTES_FILE_SUFFIX,
+    OXIPNG_BINARY_NAME,
+    OXIPNG_MISSING_MESSAGE,
+    PNG_SUFFIX,
     RELEASE_ASSETS_JSON_KEY,
+    SIZE_REPORT_TEMPLATE,
     UTF8_ENCODING,
 )
 
@@ -132,6 +137,49 @@ def timestamped_asset_name(file_path: str) -> str:
     )
 
 
+def _run_oxipng(oxipng_path: str, staged_path: Path) -> None:
+    completion = subprocess.run(
+        [oxipng_path, *ALL_OXIPNG_LOSSLESS_ARGUMENTS, str(staged_path)],
+        capture_output=True,
+        text=True,
+        encoding=UTF8_ENCODING,
+        check=False,
+        creationflags=hidden_window_creation_flags(),
+    )
+    if completion.returncode != 0:
+        raise ArtifactUploadError(completion.stderr.strip())
+
+
+def optimize_png_losslessly(staged_path: Path) -> None:
+    """Shrink a staged PNG in place with oxipng and report both sizes.
+
+    ::
+
+        contact_sheet.png: 361105 -> 308782 bytes
+
+    Oxipng keeps every pixel and every chunk. Other suffixes stay as they are.
+
+    Args:
+        staged_path: The staged copy that the upload sends.
+
+    Raises:
+        ArtifactUploadError: When oxipng is missing or fails.
+    """
+    if staged_path.suffix.lower() != PNG_SUFFIX:
+        return
+    oxipng_path = shutil.which(OXIPNG_BINARY_NAME)
+    if oxipng_path is None:
+        raise ArtifactUploadError(OXIPNG_MISSING_MESSAGE)
+    original_size = staged_path.stat().st_size
+    _run_oxipng(oxipng_path, staged_path)
+    size_report = SIZE_REPORT_TEMPLATE.format(
+        name=staged_path.name,
+        original_size=original_size,
+        optimized_size=staged_path.stat().st_size,
+    )
+    print(size_report, file=sys.stderr)
+
+
 def _uploaded_asset_download_url(repository: str) -> str:
     """Read the just-uploaded asset's real download URL back from GitHub.
 
@@ -197,6 +245,9 @@ def _uploaded_asset_download_url(repository: str) -> str:
 def upload_artifact(file_path: str, repository: str) -> str:
     """Upload a file to the artifacts release and return its permanent URL.
 
+    A PNG passes through oxipng on a staged copy first, so the source file
+    stays unchanged.
+
     Args:
         file_path: The source file to upload.
         repository: The ``owner/repo`` slug.
@@ -205,7 +256,8 @@ def upload_artifact(file_path: str, repository: str) -> str:
         The permanent download URL for the uploaded asset.
 
     Raises:
-        ArtifactUploadError: When the file is missing or the upload fails.
+        ArtifactUploadError: When the file is missing, oxipng cannot shrink
+            a PNG, or the upload fails.
     """
     source_path = Path(file_path)
     if not source_path.is_file():
@@ -215,6 +267,7 @@ def upload_artifact(file_path: str, repository: str) -> str:
     with tempfile.TemporaryDirectory() as staging_directory:
         staged_asset_path = Path(staging_directory) / asset_name
         shutil.copyfile(source_path, staged_asset_path)
+        optimize_png_losslessly(staged_asset_path)
         completion = _run_gh(
             [
                 "release",