claude-dev-env 1.82.0 → 1.84.0

package/skills/log-audit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: log-audit
+description: >-
+  Watches this repo's own logs for patterns worth acting on. Use for /log-audit,
+  "audit the logs", "what keeps failing", or "what's getting slower". Reads the
+  hook block log and the diagnostic extractor pipeline, clusters recurring errors
+  and timing regressions, opens a grouped fix PR or a tracked optimization issue
+  per real finding, and mines the defects Copilot and Bugbot keep catching into
+  skill-edit proposals. Runs as a background agent that resumes after a restart.
+---
+
+# log-audit
+
+Read the logs this repo writes about itself, find what keeps going wrong or keeps getting slower, and turn each real pattern into a tracked fix. `reference/charter.md` holds the full contract; this file is how to run a cycle.
+
+## One cycle
+
+1. **Collect.** Run `scripts/collect_log_window.py` to read the recent window of the hook block log into records.
+2. **Cluster.** Pipe those records into `scripts/cluster_recurrences.py` to group them by a normalized signature and rank the loudest first. When timing samples are on hand, the same module flags operations whose recent runs have grown slower than their earlier runs.
+3. **Mine reviewers.** Run `scripts/mine_copilot_findings.py` to sort recent reviewer-bot comments into defect classes and print a skill-edit proposal for each class.
+4. **File findings.** For each real finding, open a grouped fix pull request as a draft, or file a tracked optimization issue for a delay.
+5. **Report.** Write the per-cycle report: delays removed, pull requests opened, skill improvements suggested.
+6. **Re-arm.** Save cycle state and schedule the next cycle.
+
+## Scripts
+
+| File | What it does |
+|---|---|
+| `scripts/collect_log_window.py` | Tails the JSON-lines hook block log and prints the block records inside a time window as JSON. `--hours` sets the window; `--log-path` overrides the log location. |
+| `scripts/cluster_recurrences.py` | Reads that JSON on stdin, groups records by a normalized message signature, and prints the clusters ranked by recency-weighted count. Its `detect_timing_regressions` flags an operation whose recent runs are slower than its earliest runs. |
+| `scripts/mine_copilot_findings.py` | Reads a repo's reviewer-bot comments through `gh`, sorts them into defect classes, and prints one skill-edit proposal per class, most frequent first. Takes `--repo owner/name`. |
+
+Run the first two as a pipeline:
+
+```
+python scripts/collect_log_window.py --hours 24 | python scripts/cluster_recurrences.py
+```
+
+## What it reads
+
+In scope:
+
+- The hook block log at `~/.claude/logs/hook-blocks.log`, written by `hook_block_logger`.
+- The `hooks/diagnostic/` extractor pipeline. When Neon is set up, read through that pipeline's SQL — the shape of `queries/blocks_by_category.sql` and its siblings against the `hook_events` table, which carries `duration_ms` for timing work. When Neon is not set up, read the flat `hook-blocks.log` directly. Reuse the diagnostic pipeline's helpers; do not hold a second copy.
+
+Out of scope: Samsung-automation logs. Read this repo's log surfaces only.
+
+## Filing findings
+
+- A pull request or optimization issue carries its body in a file passed by path, following the `gh-body-file` rule.
+- Any paginated GitHub read follows the `gh-paginate` rule.
+- Group the related fixes for one finding into a single draft pull request rather than one PR per line.
+
+## Reviewer-defect mining
+
+`mine_copilot_findings.py` names a skill or rule edit for each defect class the reviewers keep catching — an edit that would block that class at write time rather than at review. These are proposals. A human applies them through review; the agent does not commit them on its own.
+
+## Cycle state and restart survival
+
+The agent keeps its state in a JSON file under `~/.claude/runtime/log-audit/` — the last window it read, the signatures it already reported, and the open items it filed. At the start of each cycle, read that file; at the end, write it back. Because the state lives in the durable runtime directory rather than the OS temp directory, a restart reads the same file and resumes the same run.
+
+## Cadence
+
+The agent runs on a recurring schedule following the repository's Scheduled Task Cadence: a sub-hour interval, with a 30-minute default. Re-arm the next cycle with `ScheduleWakeup` for a self-paced loop, or register a cron routine through `/schedule` for a fixed clock cadence.
+
+## Per-cycle report
+
+Each cycle ends with a short report: the delays removed, the pull requests opened, and the skill improvements suggested.

package/skills/log-audit/reference/CLAUDE.md

@@ -0,0 +1,9 @@
+# log-audit/reference
+
+Reference material for the `log-audit` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `charter.md` | The agent's contract: what it watches (this repo's hook-block log and diagnostic extractor pipeline), what it looks for (recurring errors and timing regressions), what it files per finding (grouped draft fix PR or tracked optimization issue), how it mines reviewer defect patterns into skill-definition proposals, and the per-cycle report it emits. Cycle state lives under `~/.claude/runtime/log-audit/`; the agent runs on a sub-hour cadence. |

package/skills/log-audit/reference/charter.md

@@ -0,0 +1,52 @@
+# Log-Audit Agent Charter
+
+The contract for the log-audit agent: what it watches, what it looks for, and what it produces each cycle. The skill body (`SKILL.md`) and its scripts carry out this contract; this document is the fixed reference they answer to.
+
+## What the agent is
+
+A background agent that reads this repository's own log surfaces, finds patterns worth acting on, and turns each real pattern into a tracked fix. It runs on its own without a person driving it and picks up where it left off after a restart.
+
+## Cycle state and cadence
+
+The agent keeps its own state on disk under `~/.claude/runtime/log-audit/`. This directory holds durable cycle state — the last window it read, the signatures it already reported, and the open items it filed — so a restart resumes the same run rather than starting over. The OS temp directory is not a home for this state, because temp files can be cleared between sessions.
+
+The agent runs on a recurring schedule. It follows the repository's Scheduled Task Cadence: a sub-hour interval, with a 30-minute default.
+
+## Log sources it reads
+
+In scope:
+
+- The hook block log at `~/.claude/logs/hook-blocks.log`, written by `hook_block_logger`. Each line is one JSON record naming the hook that blocked, the event, the reason, the tool, and a short input excerpt.
+- The `hooks/diagnostic/` extractor pipeline. When Neon is configured, the agent reads through the pipeline's SQL — the shape of `queries/blocks_by_category.sql` and its siblings against the `hook_events` table, which carries `duration_ms` for timing work. When Neon is not configured, the agent reads the flat `hook-blocks.log` directly. It reuses the diagnostic pipeline's helpers rather than holding a second copy of them.
+
+Out of scope:
+
+- Samsung-automation logs. The agent reads this repository's log surfaces only.
+
+## What it looks for
+
+Two kinds of pattern:
+
+- Recurring errors. The same failure showing up again and again. The agent groups log records by a normalized message signature — the message with its digits, paths, and hashes stripped — so records that differ only in those details fall into one cluster. It ranks clusters by count weighted toward recent activity.
+- Timing regressions. The same operation taking longer over time. When a repeated operation's duration climbs across cycles, the agent flags it as an unnecessary delay, separate from any error.
+
+## What it does per finding
+
+For each real finding, the agent takes one of two tracked actions:
+
+- Opens a grouped fix pull request as a draft, gathering the related fixes into one branch.
+- Files a tracked optimization issue when the finding is a delay to chase rather than a fix to write.
+
+Both paths carry their body in a file passed by path, following the `gh-body-file` rule, and any paginated GitHub read follows the `gh-paginate` rule.
+
+## Reviewer-defect mining
+
+The agent also reads the defect patterns that Copilot and Bugbot catch again and again across recent pull requests. It clusters those comments into defect classes and proposes concrete edits to the skill definitions that would block each class upstream, at the point of writing, rather than at review. These are proposals: they land through review, not by the agent applying them on its own.
+
+## Per-cycle report
+
+Each cycle ends with a short report covering:
+
+- Delays removed.
+- Pull requests opened.
+- Skill improvements suggested.

package/skills/log-audit/scripts/CLAUDE.md

@@ -0,0 +1,27 @@
+# log-audit/scripts
+
+The collect, cluster, and mine scripts for the `log-audit` skill, plus their constants package.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `collect_log_window.py` | Tails the JSON-lines hook block log and prints the block records inside a time window as JSON. |
+| `test_collect_log_window.py` | Tests for `collect_log_window.py`. |
+| `cluster_recurrences.py` | Groups block records by a normalized signature, ranks them by recency-weighted count, and flags timing regressions. |
+| `test_cluster_recurrences.py` | Tests for `cluster_recurrences.py`. |
+| `mine_copilot_findings.py` | Sorts reviewer-bot comments into defect classes and prints one skill-edit proposal per class. |
+| `test_mine_copilot_findings.py` | Tests for `mine_copilot_findings.py`. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `log_audit_constants/` | Named constants imported by the three scripts. |
+
+## Running
+
+```
+python collect_log_window.py --hours 24 | python cluster_recurrences.py
+python mine_copilot_findings.py --repo owner/name
+```

package/skills/log-audit/scripts/cluster_recurrences.py

@@ -0,0 +1,261 @@
+"""Group hook-block records by a normalized signature and rank the clusters.
+
+Two failures can read differently only because one names line 12 and the other
+line 348. They are the same failure. This script strips the varying parts down
+to one signature, so it counts how often each real failure recurs. It ranks the
+loudest first and weights recent blocks over stale ones. It also reads timing
+samples for one operation and flags that operation when its recent runs have
+grown slower than its earlier runs.
+
+Reads the JSON record list collect_log_window prints, on stdin.
+
+Usage:
+    collect_log_window.py --hours 24 | cluster_recurrences.py
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+_script_directory = str(Path(__file__).resolve().parent)
+if _script_directory not in sys.path:
+    sys.path.insert(0, _script_directory)
+
+from log_audit_constants.cluster_recurrences_constants import (  # noqa: E402
+    DIGIT_PATTERN,
+    HASH_PATTERN,
+    MIN_TIMING_SAMPLES_PER_HALF,
+    PATH_PATTERN,
+    RECENCY_DECAY_BASE,
+    RECENCY_HALF_LIFE_HOURS,
+    SAMPLE_HALVES,
+    SECONDS_PER_HOUR,
+    SIGNATURE_PLACEHOLDER,
+    TIMING_REGRESSION_RATIO,
+)
+from log_audit_constants.collect_log_window_constants import (  # noqa: E402
+    RECORD_LEVEL_KEY,
+    RECORD_MESSAGE_KEY,
+    RECORD_SOURCE_KEY,
+    RECORD_TIMESTAMP_KEY,
+)
+
+from collect_log_window import LogRecord  # noqa: E402
+
+
+@dataclass(frozen=True)
+class SignatureCluster:
+    """A group of records that share one normalized message signature.
+
+    Attributes:
+        signature: The normalized message the grouped records share.
+        count: How many records fell into the cluster.
+        latest_timestamp: The most recent record's timestamp in the cluster.
+        score: The recency-weighted sum of the cluster's records.
+    """
+
+    signature: str
+    count: int
+    latest_timestamp: datetime
+    score: float
+
+
+@dataclass(frozen=True)
+class TimingSample:
+    """One measured run of a repeated operation.
+
+    Attributes:
+        operation: The operation's name.
+        timestamp: When the run happened.
+        duration_ms: How long the run took, in milliseconds.
+    """
+
+    operation: str
+    timestamp: datetime
+    duration_ms: float
+
+
+@dataclass(frozen=True)
+class TimingRegression:
+    """A repeated operation whose recent runs have grown slower.
+
+    Attributes:
+        operation: The operation's name.
+        baseline_ms: The mean duration of the earliest runs.
+        recent_ms: The mean duration of the latest runs.
+        ratio: The recent mean divided by the baseline mean.
+    """
+
+    operation: str
+    baseline_ms: float
+    recent_ms: float
+    ratio: float
+
+
+def normalize_signature(message: str) -> str:
+    """Reduce a message to a signature shared by its recurring variants.
+
+    Args:
+        message: A raw block-reason message.
+
+    Returns:
+        The message with paths, hashes, and numbers replaced by a placeholder
+        and runs of whitespace collapsed to single spaces.
+    """
+    without_paths = re.sub(PATH_PATTERN, SIGNATURE_PLACEHOLDER, message)
+    without_hashes = re.sub(HASH_PATTERN, SIGNATURE_PLACEHOLDER, without_paths)
+    without_numbers = re.sub(DIGIT_PATTERN, SIGNATURE_PLACEHOLDER, without_hashes)
+    return re.sub(r"\s+", " ", without_numbers).strip()
+
+
+def recency_weight(record_timestamp: datetime, now: datetime) -> float:
+    """Weight a record by how recent it is, halving each half-life of age.
+
+    Args:
+        record_timestamp: When the record was written.
+        now: The current time age is measured against.
+
+    Returns:
+        A weight near one for a fresh record, falling toward zero as it ages.
+    """
+    age_hours = (now - record_timestamp).total_seconds() / SECONDS_PER_HOUR
+    non_negative_age_hours = max(age_hours, 0.0)
+    return RECENCY_DECAY_BASE ** (non_negative_age_hours / RECENCY_HALF_LIFE_HOURS)
+
+
+def rank_signature_clusters(
+    all_records: list[LogRecord], now: datetime
+) -> list[SignatureCluster]:
+    """Group records by signature and rank them by recency-weighted count.
+
+    Args:
+        all_records: The block records to group.
+        now: The current time used to weight each record.
+
+    Returns:
+        One cluster per distinct signature, highest score first.
+    """
+    records_by_signature: dict[str, list[LogRecord]] = defaultdict(list)
+    for each_record in all_records:
+        records_by_signature[normalize_signature(each_record.message)].append(
+            each_record
+        )
+    clusters: list[SignatureCluster] = []
+    for each_signature, each_signature_records in records_by_signature.items():
+        score = sum(
+            recency_weight(each_grouped.timestamp, now)
+            for each_grouped in each_signature_records
+        )
+        latest_timestamp = max(
+            each_grouped.timestamp for each_grouped in each_signature_records
+        )
+        clusters.append(
+            SignatureCluster(
+                signature=each_signature,
+                count=len(each_signature_records),
+                latest_timestamp=latest_timestamp,
+                score=score,
+            )
+        )
+    return sorted(
+        clusters,
+        key=lambda cluster: (cluster.score, cluster.count),
+        reverse=True,
+    )
+
+
+def _mean_duration(all_samples: list[TimingSample]) -> float:
+    """Return the mean duration in milliseconds of the given samples."""
+    return sum(each_sample.duration_ms for each_sample in all_samples) / len(
+        all_samples
+    )
+
+
+def detect_timing_regressions(
+    all_samples: list[TimingSample],
+) -> list[TimingRegression]:
+    """Flag operations whose recent runs are slower than their earliest runs.
+
+    Args:
+        all_samples: Timing samples across one or more operations.
+
+    Returns:
+        One regression per operation whose recent-to-baseline duration ratio
+        reaches the regression threshold, highest ratio first.
+    """
+    samples_by_operation: dict[str, list[TimingSample]] = defaultdict(list)
+    for each_sample in all_samples:
+        samples_by_operation[each_sample.operation].append(each_sample)
+    regressions: list[TimingRegression] = []
+    for each_operation, each_operation_samples in samples_by_operation.items():
+        if len(each_operation_samples) < MIN_TIMING_SAMPLES_PER_HALF * SAMPLE_HALVES:
+            continue
+        ordered_samples = sorted(
+            each_operation_samples, key=lambda sample: sample.timestamp
+        )
+        baseline_ms = _mean_duration(ordered_samples[:MIN_TIMING_SAMPLES_PER_HALF])
+        recent_ms = _mean_duration(ordered_samples[-MIN_TIMING_SAMPLES_PER_HALF:])
+        if baseline_ms <= 0:
+            continue
+        ratio = recent_ms / baseline_ms
+        if ratio >= TIMING_REGRESSION_RATIO:
+            regressions.append(
+                TimingRegression(
+                    operation=each_operation,
+                    baseline_ms=baseline_ms,
+                    recent_ms=recent_ms,
+                    ratio=ratio,
+                )
+            )
+    return sorted(regressions, key=lambda regression: regression.ratio, reverse=True)
+
+
+def _record_from_json_dict(all_record_fields: dict[str, str]) -> LogRecord:
+    """Rebuild a LogRecord from one collect_log_window JSON dict."""
+    return LogRecord(
+        timestamp=datetime.fromisoformat(all_record_fields[RECORD_TIMESTAMP_KEY]),
+        source=all_record_fields[RECORD_SOURCE_KEY],
+        level=all_record_fields[RECORD_LEVEL_KEY],
+        message=all_record_fields[RECORD_MESSAGE_KEY],
+    )
+
+
+def main() -> int:
+    """Read records on stdin and print ranked signature clusters.
+
+    Returns:
+        The process exit code; zero on success, one when stdin is not a JSON
+        list of well-formed records.
+    """
+    try:
+        records_payload = json.load(sys.stdin)
+    except json.JSONDecodeError as decode_error:
+        print(f"cluster_recurrences: stdin is not valid JSON: {decode_error}", file=sys.stderr)
+        return 1
+    if not isinstance(records_payload, list):
+        print("cluster_recurrences: stdin JSON must be a list of records", file=sys.stderr)
+        return 1
+    try:
+        records = [
+            _record_from_json_dict(each_record_fields)
+            for each_record_fields in records_payload
+        ]
+    except (KeyError, TypeError, ValueError) as record_error:
+        print(f"cluster_recurrences: malformed record in stdin: {record_error}", file=sys.stderr)
+        return 1
+    clusters = rank_signature_clusters(records, datetime.now())
+    for each_cluster in clusters:
+        print(
+            f"{each_cluster.count}\t{each_cluster.score:.2f}\t{each_cluster.signature}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/log-audit/scripts/collect_log_window.py

@@ -0,0 +1,199 @@
+"""Read the recent window of the hook block log into structured records.
+
+Tails the JSON-lines hook block log every blocking hook appends to, and hands
+back the block events inside a time window as plain records. Picture the audit
+agent waking up: it asks this script for the last few hours of blocks, and gets
+one record per block carrying when it happened, which hook fired, and why. Those
+records feed cluster_recurrences, which groups them by a normalized signature.
+
+Usage:
+    collect_log_window.py --hours 24
+    collect_log_window.py --hours 6 --log-path /path/to/hook-blocks.log
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+_script_directory = str(Path(__file__).resolve().parent)
+if _script_directory not in sys.path:
+    sys.path.insert(0, _script_directory)
+
+from log_audit_constants.collect_log_window_constants import (  # noqa: E402
+    BLOCK_LEVEL_LABEL,
+    DEFAULT_WINDOW_HOURS,
+    HOOK_BLOCKS_LOG_RELATIVE_PATH,
+    LOG_HOOK_KEY,
+    LOG_REASON_KEY,
+    LOG_TIMESTAMP_KEY,
+    RECORD_LEVEL_KEY,
+    RECORD_MESSAGE_KEY,
+    RECORD_SOURCE_KEY,
+    RECORD_TIMESTAMP_KEY,
+)
+
+
+@dataclass(frozen=True)
+class LogRecord:
+    """One block event read from the hook block log.
+
+    Attributes:
+        timestamp: When the block happened, parsed from the record's ISO string.
+        source: The hook that blocked, taken from the record's hook field.
+        level: The severity label; every hook-block record reads as a block.
+        message: The human-readable block reason.
+    """
+
+    timestamp: datetime
+    source: str
+    level: str
+    message: str
+
+
+def parse_log_line(raw_line: str) -> LogRecord | None:
+    """Parse one hook-block-log line into a LogRecord.
+
+    Args:
+        raw_line: A single line of the JSON-lines hook block log.
+
+    Returns:
+        The parsed record, or None when the line is blank, is not a JSON object,
+        or omits the timestamp, hook, or reason field, or carries a timestamp
+        that does not parse as an ISO datetime.
+    """
+    stripped_line = raw_line.strip()
+    if not stripped_line:
+        return None
+    try:
+        record_fields = json.loads(stripped_line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(record_fields, dict):
+        return None
+    timestamp_text = record_fields.get(LOG_TIMESTAMP_KEY)
+    source_text = record_fields.get(LOG_HOOK_KEY)
+    message_text = record_fields.get(LOG_REASON_KEY)
+    if not isinstance(timestamp_text, str):
+        return None
+    if not isinstance(source_text, str) or not isinstance(message_text, str):
+        return None
+    try:
+        parsed_timestamp = datetime.fromisoformat(timestamp_text)
+    except ValueError:
+        return None
+    return LogRecord(
+        timestamp=parsed_timestamp,
+        source=source_text,
+        level=BLOCK_LEVEL_LABEL,
+        message=message_text,
+    )
+
+
+def _records_within_window(
+    all_lines: Iterable[str], window_start: datetime
+) -> list[LogRecord]:
+    """Parse each line and keep the records at or after the window start.
+
+    Args:
+        all_lines: The hook-block-log lines to parse, in file order.
+        window_start: The earliest timestamp a kept record may carry.
+
+    Returns:
+        The in-window records in the order their lines appear.
+    """
+    kept_records: list[LogRecord] = []
+    for each_line in all_lines:
+        parsed_record = parse_log_line(each_line)
+        if parsed_record is None:
+            continue
+        if parsed_record.timestamp >= window_start:
+            kept_records.append(parsed_record)
+    return kept_records
+
+
+def collect_records(log_text: str, window_start: datetime) -> list[LogRecord]:
+    """Parse log text and keep records at or after the window start.
+
+    Args:
+        log_text: The full text of the hook block log.
+        window_start: The earliest timestamp a kept record may carry.
+
+    Returns:
+        The in-window records in the order they appear in the log.
+    """
+    return _records_within_window(log_text.splitlines(), window_start)
+
+
+def read_log_window(
+    log_path: Path, window_hours: int, now: datetime
+) -> list[LogRecord]:
+    """Read the hook block log and return records within the window.
+
+    Args:
+        log_path: Path to the JSON-lines hook block log.
+        window_hours: How many hours back from now to keep.
+        now: The current time the window is measured back from.
+
+    Returns:
+        The in-window records, or an empty list when the log file is absent.
+    """
+    window_start = now - timedelta(hours=window_hours)
+    try:
+        with log_path.open(encoding="utf-8") as log_file:
+            return _records_within_window(log_file, window_start)
+    except FileNotFoundError:
+        return []
+
+
+def _default_log_path() -> Path:
+    """Return the home-relative path of the hook block log."""
+    return Path.home() / HOOK_BLOCKS_LOG_RELATIVE_PATH
+
+
+def _record_as_json_dict(record: LogRecord) -> dict[str, str]:
+    """Render a record as a JSON-ready dict with an ISO timestamp string.
+
+    Args:
+        record: The record to render.
+
+    Returns:
+        A dict of string values keyed by the record's field names.
+    """
+    return {
+        RECORD_TIMESTAMP_KEY: record.timestamp.isoformat(),
+        RECORD_SOURCE_KEY: record.source,
+        RECORD_LEVEL_KEY: record.level,
+        RECORD_MESSAGE_KEY: record.message,
+    }
+
+
+def main() -> int:
+    """Print the recent hook-block records as JSON to stdout.
+
+    Returns:
+        The process exit code; zero on success.
+    """
+    parser = argparse.ArgumentParser(description="Tail the hook block log window.")
+    parser.add_argument("--hours", type=int, default=DEFAULT_WINDOW_HOURS)
+    parser.add_argument("--log-path", type=str, default=None)
+    parsed_arguments = parser.parse_args()
+    log_path = (
+        Path(parsed_arguments.log_path).expanduser().resolve()
+        if parsed_arguments.log_path is not None
+        else _default_log_path()
+    )
+    records = read_log_window(log_path, parsed_arguments.hours, datetime.now())
+    json.dump(
+        [_record_as_json_dict(each_record) for each_record in records], sys.stdout
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/log-audit/scripts/log_audit_constants/CLAUDE.md

@@ -0,0 +1,12 @@
+# log-audit/scripts/log_audit_constants
+
+Named constants imported by the `log-audit` scripts. Each module holds the tunables for one script, keeping magic values out of the scripts.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `__init__.py` | Package marker. |
+| `collect_log_window_constants.py` | The hook-block-log path, default window, block level label, and the input and output record key names for `collect_log_window.py`. |
+| `cluster_recurrences_constants.py` | The signature-stripping regexes, recency decay, and timing-regression thresholds for `cluster_recurrences.py`. |
+| `mine_copilot_findings_constants.py` | The reviewer-bot logins, the recent-pulls and per-pull comments endpoint templates, the recent-pull count, and the defect-class keyword and proposal maps for `mine_copilot_findings.py`. |

package/skills/log-audit/scripts/log_audit_constants/cluster_recurrences_constants.py

@@ -0,0 +1,23 @@
+"""Constants for the cluster_recurrences script.
+
+PATH_PATTERN, HASH_PATTERN, DIGIT_PATTERN: regexes stripped from a message, in this
+    order, so records that differ only in a path, hash, or number share one signature.
+SIGNATURE_PLACEHOLDER: the token each stripped span collapses to.
+SECONDS_PER_HOUR: seconds in one hour, dividing a record's age into hours.
+RECENCY_DECAY_BASE: the weight a record carries once it is one half-life old.
+RECENCY_HALF_LIFE_HOURS: age in hours at which a record's weight reaches the decay base.
+TIMING_REGRESSION_RATIO: recent-over-baseline duration ratio that flags a regression.
+MIN_TIMING_SAMPLES_PER_HALF: samples required in the baseline half and the recent half.
+SAMPLE_HALVES: the number of halves a timing series splits into before it can be judged.
+"""
+
+PATH_PATTERN = r"(?:[A-Za-z]:)?(?:[\\/][\w.\-]+)+"
+HASH_PATTERN = r"\b[0-9a-f]{7,40}\b"
+DIGIT_PATTERN = r"\d+"
+SIGNATURE_PLACEHOLDER = "*"
+SECONDS_PER_HOUR = 3600
+RECENCY_DECAY_BASE = 0.5
+RECENCY_HALF_LIFE_HOURS = 24.0
+TIMING_REGRESSION_RATIO = 1.5
+MIN_TIMING_SAMPLES_PER_HALF = 3
+SAMPLE_HALVES = 2

package/skills/log-audit/scripts/log_audit_constants/collect_log_window_constants.py

@@ -0,0 +1,24 @@
+"""Constants for the collect_log_window script.
+
+HOOK_BLOCKS_LOG_RELATIVE_PATH: home-relative path of the JSON-lines hook block log.
+DEFAULT_WINDOW_HOURS: how many hours back a collection reads when no window is given.
+BLOCK_LEVEL_LABEL: the level stamped on every record read from the hook block log.
+LOG_TIMESTAMP_KEY: hook-block-log JSON key holding the ISO-8601 block time.
+LOG_HOOK_KEY: hook-block-log JSON key holding the blocking hook's name.
+LOG_REASON_KEY: hook-block-log JSON key holding the human-readable block reason.
+RECORD_TIMESTAMP_KEY: output-record key holding the ISO-8601 block time.
+RECORD_SOURCE_KEY: output-record key holding the blocking hook's name.
+RECORD_LEVEL_KEY: output-record key holding the severity label.
+RECORD_MESSAGE_KEY: output-record key holding the block reason.
+"""
+
+HOOK_BLOCKS_LOG_RELATIVE_PATH = ".claude/logs/hook-blocks.log"
+DEFAULT_WINDOW_HOURS = 24
+BLOCK_LEVEL_LABEL = "block"
+LOG_TIMESTAMP_KEY = "timestamp"
+LOG_HOOK_KEY = "hook"
+LOG_REASON_KEY = "reason"
+RECORD_TIMESTAMP_KEY = "timestamp"
+RECORD_SOURCE_KEY = "source"
+RECORD_LEVEL_KEY = "level"
+RECORD_MESSAGE_KEY = "message"