claude-dev-env 1.83.0 → 1.85.0

package/skills/code/SKILL.md

@@ -138,6 +138,8 @@ def load_config(config_path: str) -> AppConfig:
     """
 ```
 
+For a public function whose behavior needs a picture, lead the narrative with a diagram: one summary line, then a `::` literal block or a doctest showing a concrete input and its marked outcome, then a couple of short prose lines, then the `Args:` / `Returns:` sections. See `../../rules/plain-illustrative-docstrings.md` for the shape and a worked example.
+
 ### 13. Build infrastructure
 
 The project under development must contain:

package/skills/copilot-review/CLAUDE.md

@@ -4,7 +4,7 @@ Spawns a background subagent that polls the GitHub Copilot reviewer on the curre
 
 ## Purpose
 
-The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 5-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, or after 20 ticks.
+The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 6-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, resolve each addressed thread, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, three consecutive ticks with no Copilot review at the current HEAD, or after 20 ticks.
 
 ## Key file
 

package/skills/copilot-review/SKILL.md

@@ -2,10 +2,11 @@
 name: copilot-review
 description: >-
   Spawns a background subagent that babysits the GitHub Copilot reviewer on the current
-  PR: each ~5-min tick it fetches the latest copilot-pull-request-reviewer[bot] review,
-  fixes unaddressed findings against HEAD (commit, push, inline replies), re-requests
-  review, and exits on convergence. Triggers: '/copilot-review', 'watch copilot',
-  'babysit copilot review', 'keep re-requesting copilot'.
+  PR: each ~6-min tick it fetches the latest copilot-pull-request-reviewer[bot] review,
+  fixes unaddressed findings against HEAD (commit, push, inline replies, thread
+  resolution), re-requests review, and exits on convergence. Triggers:
+  '/copilot-review', 'watch copilot', 'babysit copilot review', 'keep re-requesting
+  copilot'.
 ---
 
 # Copilot Review
@@ -20,20 +21,18 @@ The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to k
 
 ### Step 0: Opt-out check
 
-Before any other work, inspect the `CLAUDE_REVIEWS_DISABLED` environment
-variable. Treat the value as a comma-separated list of skill tokens
-(case-insensitive, whitespace-tolerant). When the parsed list contains
-`copilot`, respond with the literal line `/copilot-review is disabled via
-CLAUDE_REVIEWS_DISABLED.` and stop — do not spawn the subagent, do not call
-the Copilot reviewer API, do not run any other step of this skill.
+Before any other work, run:
 
-PowerShell probe (Windows):
-
-```pwsh
-$disabled = ($env:CLAUDE_REVIEWS_DISABLED -split ',' | ForEach-Object { $_.Trim().ToLowerInvariant() })
-if ($disabled -contains 'copilot') { '/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.' }
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
 ```
 
+Exit 0 — Copilot reviews are disabled: respond with the literal line
+`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
+spawn the subagent, do not call the Copilot reviewer API, do not run any
+other step of this skill. Exit 1 — continue. Gate semantics live in the
+`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
+
 ### Step 1: Gather PR context
 
 From the current repo:
@@ -74,25 +73,27 @@ Pass this verbatim to the subagent (substituting the bracketed values):
 > 2. Fetch latest Copilot review via `pull_request_read(method="get_reviews", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")`.
 >    Capture `commit_id`, `state`, `submitted_at`, `id`.
 > 3. Decide the branch:
->    - **No review exists:** re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` != current HEAD:** re-request (step 4), schedule next wakeup, return.
->    - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** TDD-fix them, push, reply inline on each thread, re-request (step 4), schedule next wakeup, return.
+>    - **No review exists:** increment `no_review_count` (see escalation rule below), re-request (step 4), schedule next wakeup, return.
+>    - **Latest review's `commit_id` != current HEAD:** increment `no_review_count`, re-request (step 4), schedule next wakeup, return.
+>    - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** reset `no_review_count` to 0, TDD-fix them, push, reply inline on each thread, resolve each addressed thread, re-request (step 4), schedule next wakeup, return.
 >    - **Latest review's `commit_id` == current HEAD and clean:** report convergence to the parent with a one-sentence summary and terminate. The loop is done; skip the ScheduleWakeup call.
+>
+>    **Escalation rule:** `no_review_count` starts at 0, counts consecutive ticks where no Copilot review exists at the current HEAD, and resets to 0 on every push and every review sighted at HEAD. When it reaches 3, Copilot is not delivering reviews — report the stall to the parent with the count and the last request timestamp, then terminate without scheduling another wakeup.
 > 4. Re-request Copilot via `request_copilot_review(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER])`.
 >    The reviewer ID **must** be `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix — empirically verified: `Copilot`, `copilot`, and `github-copilot` all return `requested_reviewers: []` with no error, silently no-op.
 > 5. Schedule the next wakeup with `ScheduleWakeup`:
->    - `delaySeconds: 300`
+>    - `delaySeconds: 360`
 >    - `reason`: one short sentence on what you are waiting for.
 >    - `prompt`: the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
 >
 > **Fix protocol** (step 3, third branch):
 >
+> - Read `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` and apply it — it carries the shared fix sequence, the reply-and-resolve unit, and the unresolved-thread sweep.
 > - Read each referenced file:line.
 > - Write a failing test first when the finding has behavior to test. For pure doc or comment nits that have no behavior, go straight to the fix.
-> - Implement the fix.
 > - Stage the fix and create one new commit on the existing branch: `git add <files> && git commit -m "fix(review): ..."`.
 > - Push the new commit: `git push origin [BRANCH]`.
-> - Reply inline on each comment thread with `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA.
+> - Reply inline via `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA; then resolve each addressed thread via `pull_request_review_write(method="resolve_thread", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]", threadId="<PRRT id>")`, harvesting the `PRRT_…` id from `pull_request_read(method="get_review_comments", ...)`. Reply first, then resolve — atomic per thread, per the protocol.
 >
 > When a pre-push, pre-commit, or other hook rejects the change, solve it. Read the hook's error message, diagnose the root cause in the code or test, and fix that. Then rerun the commit or push. Hooks exist to catch real problems; treat each rejection as new evidence to act on.
 >
@@ -101,8 +102,9 @@ Pass this verbatim to the subagent (substituting the bracketed values):
 > - Convergence (clean review against HEAD): report one-sentence summary to parent and terminate.
 > - Blocker you have exhausted fix attempts on (API auth failure persists, CI regression whose root cause falls outside this PR, a hook you have investigated and cannot resolve in one commit): report the specific blocker and its diagnosis to the parent, then terminate without scheduling another wakeup.
 > - Parent sends `TaskStop`: terminate immediately.
+> - `no_review_count` reaches 3 (escalation rule above): report the stall and terminate.
 >
-> **Safety cap:** after 20 ticks without convergence, stop and report. That many rounds means something structural is wrong with the loop.
+> **Safety cap:** after 20 ticks without convergence, stop and report. This is the total-tick runaway guard, distinct from the 3-consecutive-no-review escalation; that many rounds means something structural is wrong with the loop.
 
 ### Step 4: Report back to the user
 
@@ -142,7 +144,7 @@ Subagent: [re-requests review, schedules next wakeup, returns]
 
 <example>
 Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
-Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, re-requests review, schedules next wakeup]
+Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
 </example>
 
 <example>

package/skills/findbugs/CLAUDE.md

@@ -4,13 +4,13 @@ Audits the current branch's pull request for bugs by spawning the `code-quality-
 
 ## Purpose
 
-Read-only. The skill resolves PR scope, writes the diff to a scoped temp file, and spawns two `code-quality-agent` instances (primary sonnet + secondary haiku) with a self-contained, context-free prompt covering all A–P audit categories. After both return it merges findings (de-dup, max-wins severity), posts one audit review to the PR via `post_audit_thread.py` (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty), and reports totals and cleared categories to the user.
+Read-only. The skill resolves PR scope via the `pr-scope-resolve` skill, writes the diff to a scoped temp file, and spawns two `code-quality-agent` instances (primary sonnet + secondary haiku) with a self-contained, context-free prompt covering all A–P audit categories. After both return it merges findings (de-dup, max-wins severity), posts one audit review to the PR via the `post-audit-findings` skill (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty), and reports totals and cleared categories to the user.
 
 ## Key file
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Five-step process: resolve scope, capture diff to a scoped temp path, spawn agents (clean-room prompt XML), post audit review via `post_audit_thread.py`, surface findings and offer `/fixbugs`. Includes refusals, output format, and the anchored-vs-unanchored finding split. |
+| `SKILL.md` | Five-step process: resolve scope (`pr-scope-resolve` skill), capture diff to a scoped temp path, spawn agents (clean-room prompt XML), post audit review (`post-audit-findings` skill), surface findings and offer `/fixbugs`. Includes refusals and the output format. |
 
 ## Constraints
 

package/skills/findbugs/SKILL.md

@@ -22,21 +22,21 @@ If the current branch has no associated PR and no diff against the default branc
 
 First match wins; respond with the quoted line exactly and stop:
 
-- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` contains the
-  token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
-  `/findbugs is disabled via CLAUDE_REVIEWS_DISABLED.` `/findbugs` is a PR
-  bug-audit skill in the same family as `/bugteam` and `/qbug`, so the
-  shared `bugteam` token disables all three.
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` carries the
+  token `bugteam`:
+  `/findbugs is disabled via CLAUDE_REVIEWS_DISABLED.` Run the check via
+  `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugteam`
+  (exit 0 = disabled). `/findbugs` is a PR bug-audit skill in the same family
+  as `/bugteam` and `/qbug`, so the shared `bugteam` token disables all three.
+  The gate semantics live in the `reviewer-gates` skill (`../reviewer-gates/SKILL.md`).
 
 ## The Process
 
 ### Step 1: Resolve PR scope
 
-Determine the audit target in this order:
+Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `findbugs`. Findbugs consumes the resolved `owner`, `repo`, `number`, `head_ref`, `base_ref`, and `url`; when no PR exists, the ladder's merge-base rung sets the audit scope. When no target exists, respond exactly with the sub-skill's canonical refusal line and stop:
 
-1. **Open PR for current branch.** Call `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` for the current branch (`N` comes from the parent skill's context, or fall back to `search_issues` MCP with the current branch name to recover the PR number). If a PR exists, capture its number, base ref, head ref, and URL.
-2. **No PR but a remote default branch exists.** Diff against the default branch's merge-base: `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`. Treat this as the audit scope.
-3. **Neither.** Respond exactly: `No PR or upstream diff found. Push the branch or open a PR first.` and stop.
+`No PR or upstream diff. /findbugs needs a target.`
 
 ### Step 2: Capture the full PR diff
 
@@ -102,6 +102,8 @@ The XML prompt skeleton:
   L. Behavior-equivalence for refactors
   M. Producer/consumer cardinality vs collection-type contract
   N. Test-name scenario verifier
+  O. Docstring / fixture-prose vs implementation drift
+  P. Name / regex / word-list vs behavior-contract precision
 
   The category list above is a summary. The binding definition of each
   category is its rubric file under $HOME/.claude/audit-rubrics/category_rubrics/
@@ -117,7 +119,7 @@ The XML prompt skeleton:
 </constraints>
 
 <output_format>
-  Follow the shared audit contract at ../bugteam/reference/audit-contract.md:
+  Follow the shared audit contract at $HOME/.claude/_shared/pr-loop/audit-contract.md:
 
   - Severity: P0 = will not run / data corruption; P1 = regression or silent
     failure; P2 = dead code, minor smell.
@@ -139,81 +141,18 @@ returns findings without posting them as inline comments is invisible
 to the gate. Findbugs remains read-only on code — the review post is
 the only side effect.
 
-**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
-`REQUEST_CHANGES` reviews with HTTP 422 when the authenticated identity
-matches the PR author ("Cannot approve/request changes on your own pull
-request"). `post_audit_thread.py` detects this case via `gh api user` +
-`gh api repos/<o>/<r>/pulls/<n>` and auto-resolves an alternate gh
-account's token for the reviews POST — the active `gh auth` account is
-not mutated; only the bearer token sent on the request changes. After
-the POST the active account is still whoever it was before, so no
-"swap back" step is needed.
-
-Configuration:
-
-- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle.
-  Set them when you need to pin a specific reviewer identity by token
-  rather than by account login.
-- `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated alternate
-  to prefer when a toggle is needed (for example,
-  `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). The env var name is shared across
-  every skill that invokes `post_audit_thread.py`. When unset, the
-  script falls back to the first alternate account `gh auth status`
-  reports.
-- The named alternate must be logged in (`gh auth login -h github.com -u
-  <login>`) before the audit skill runs. The script exits 1 with a
-  pointing-at-`gh auth login` message when self-PR is detected and no
-  usable alternate is authenticated.
-
-After the agent (and Haiku secondary) return and the merge is complete,
-serialize the merged findings to a JSON file and call
-`post_audit_thread.py`:
-
-```
-python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \
-  --skill findbugs \
-  --owner <owner> \
-  --repo <repo> \
-  --pr-number <N> \
-  --commit <head_sha> \
-  --state <CLEAN|DIRTY> \
-  --findings-json <path>
-```
-
-The findings JSON root is a list of objects shaped
-`{path, line, side, severity, description, fix_summary}`. Before
-serializing, partition the merged findings into anchored (line appears
-in the captured diff) and unanchored (line is not in the diff) buckets.
-Only anchored findings are serialized to the JSON — the GitHub reviews
-API rejects the entire POST if any inline comment in `comments[]`
-targets a line not in the diff at `--commit`, so a single unanchored
-entry breaks the whole review. Unanchored findings are surfaced via
-Step 5's user-facing output rather than as inline anchored comments.
-For each anchored finding, map `file` → `path`; split the finding's
-`failure_mode` at the literal `Fix:` heading so the failure narrative
-becomes `description` and the suffix beginning at `Fix:` (including
-the trailing `Validation:` clause) becomes `fix_summary` (the
-`failure_mode` field carries the full audit-to-fix handoff per
-[`agents/code-quality-agent.md`](../../agents/code-quality-agent.md)).
-When a finding's `failure_mode` omits the `Fix:` heading, write the
-full text to BOTH `description` and `fix_summary`. Set `side="RIGHT"`
-for every entry. Zero anchored findings → `--state CLEAN` with the
-findings file holding an empty array (`[]`); one or more anchored
-findings → `--state DIRTY` with the full list. CLEAN posts an APPROVE review (the
-request event; GitHub stores it as `state=APPROVED`) with a "no
-findings" summary; DIRTY posts a REQUEST_CHANGES review with one inline
-anchored comment per finding (each becomes its own resolvable thread on
-the PR).
-
 Capture `<head_sha>` once at the start of Step 4 via `git rev-parse
 HEAD` in the worktree the diff was scoped against.
 
-Exit codes: `0` on success (emits the new review's `html_url` to
-stdout, surface alongside the totals in Step 5); `1` on user input
-error; `2` on retry exhaustion (1s / 4s / 16s backoff across four
-attempts). On exit 2, tell the user the review post failed and that
-the unresolved-thread gate will not see this audit pass; do not retry
-silently.
+After the agent (and Haiku secondary) return and the merge is complete,
+apply the `post-audit-findings` skill (`../post-audit-findings/SKILL.md`)
+with `--skill findbugs`. That skill owns the findings-JSON mapping, the
+anchored-only serialization (unanchored findings surface via Step 5's
+user-facing output), the CLEAN/DIRTY decision, the self-PR reviewer
+toggle, and the exit codes. On exit 0, surface the emitted review
+`html_url` alongside the totals in Step 5. On exit 2, tell the user the
+review post failed and that the unresolved-thread gate will not see this
+audit pass; do not retry silently.
 
 ### Step 5: Surface findings, then clean up
 
@@ -285,7 +224,7 @@ Claude: [resolves PR #42 from current branch, fetches full diff, spawns code-qua
 
 <example>
 User: `/findbugs`
-Claude: `No PR or upstream diff found. Push the branch or open a PR first.`
+Claude: `No PR or upstream diff. /findbugs needs a target.`
 </example>
 
 <example>

package/skills/fixbugs/SKILL.md

@@ -47,11 +47,9 @@ If the filtered set is empty, refuse per the refusal cases above.
 
 ### Step 2: Re-resolve PR scope
 
-Re-establish the same PR target `/findbugs` used:
+Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `fixbugs` to resolve the same PR target `/findbugs` used — the fixes stay scoped to the files the `/findbugs` findings from Step 1 name. When no target exists, respond with the sub-skill's canonical refusal line and stop:
 
-1. `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` for the current branch (`N` comes from the parent skill's PR context, or fall back to `search_issues` MCP with the current branch name to recover the PR number).
-2. Fall back to `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`.
-3. Neither → respond `No PR or upstream diff. Cannot scope fixes.` and stop.
+`No PR or upstream diff. /fixbugs needs a target.`
 
 Capture: `<owner>/<repo>`, head branch, base branch, PR number, PR URL.
 

package/skills/log-audit/CLAUDE.md

@@ -0,0 +1,20 @@
+# log-audit
+
+Reads this repository's own logs, finds recurring errors and timing regressions, and turns each real pattern into a tracked fix. Triggered by `/log-audit`, `audit the logs`, `what keeps failing`, or `what's getting slower`.
+
+## Purpose
+
+The skill runs as a background agent on a recurring schedule. Each cycle it reads the hook block log and the diagnostic extractor pipeline, clusters recurring errors and timing regressions, opens a grouped draft fix pull request or a tracked optimization issue per finding, and mines the defects Copilot and Bugbot keep catching into skill-edit proposals. Cycle state lives under `~/.claude/runtime/log-audit/`, so a restart resumes the same run.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full instructions: the cycle steps, the three scripts and how to pipe them, the log sources in and out of scope, finding-filing rules, reviewer mining, cycle state, and cadence. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | The agent charter — the fixed contract the skill answers to. |
+| `scripts/` | The collect, cluster, and mine scripts and their constants package. |

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
+```