claude-dev-env 1.93.0 → 1.94.0

package/skills/implement/CLAUDE.md

@@ -1,27 +0,0 @@
-# Spec Execution Skill
-
-This skill (`implement`) runs a spec end-to-end while maintaining a sidecar `implementation-notes.html` that records design decisions, deviations, tradeoffs, and open questions made during the build.
-
-**Trigger:** `/implement [path-to-spec]`, "build out this plan and keep notes".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full workflow: resolve spec, run it, write notes via `append_note.py` |
-| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI that creates or appends to `implementation-notes.html` |
-| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `scripts/` | Python CLI and constants for the notes file |
-
-## Conventions
-
-- The spec is taken from `$ARGUMENTS` (path) or the most recent plan in conversation context. If neither is present, the skill asks via `AskUserQuestion`.
-- Notes are appended as decisions are made — not batched at the end.
-- The `append_note.py` CLI accepts `--section decisions|deviations|tradeoffs|questions`, `--about`, `--note`, and optionally `--file`. When `--file` is omitted, the script writes to `./implementation-notes.html`.
-- `$CLAUDE_SKILL_DIR` is substituted by Claude Code at runtime so the bundled script is found regardless of the current working directory.
-- The notes file structure must not be hand-edited — `append_note.py` locates sections by `<section id="...">` markers and the first `</ul>` after each.

package/skills/implement/SKILL.md

@@ -1,66 +0,0 @@
----
-name: implement
-description: "Implement a spec while maintaining a running implementation-notes.html file that captures design decisions, deviations, tradeoffs, and open questions. Triggers: /implement, implement this spec, build out this plan and keep notes."
-argument-hint: "[path to spec file, or omit to use a spec already in context]"
----
-
-# implement
-
-Execute a spec end-to-end while keeping a sidecar `implementation-notes.html` that the user can read to see how the build diverged from or interpreted the written plan.
-
-## Instructions
-
-Carry out the following prompt against the spec resolved below.
-
-### Resolve `<SPEC>`
-
-- If `$ARGUMENTS` is non-empty, treat it as the path to the spec file and read it.
-- Otherwise, use the most recent plan / spec / design doc already present in the conversation context.
-- If neither is available, ask the user for the spec path via `AskUserQuestion` before proceeding.
-
-### Prompt to execute
-
-> Implement `<SPEC>`. As you work maintain a running `implementation-notes.html` file that captures anything I should know about how the implementation diverges from or interprets the spec, including:
->
-> - **Design decisions:** choices you made where the spec was ambiguous
-> - **Deviations:** places where you intentionally departed from the spec, and why
-> - **Tradeoffs:** alternatives you considered and why you picked what you did
-> - **Open questions:** anything you'd want me to confirm or revise
-
-### How to write notes
-
-Run `${CLAUDE_SKILL_DIR}/scripts/append_note.py` to append each entry. The script creates `implementation-notes.html` with the four sections on first run, then inserts a new `<li>` under the requested section. HTML-escapes `--about` and `--note` automatically. `${CLAUDE_SKILL_DIR}` is host-substituted by Claude Code at runtime so the bundled CLI is found regardless of the current working directory.
-
-```
-python "${CLAUDE_SKILL_DIR}/scripts/append_note.py" \
-  --section decisions \
-  --about "Storage location" \
-  --note "Wrote notes next to the spec because the spec path was provided." \
-  --file /path/to/spec-dir/implementation-notes.html
-```
-
-`--section` choices (slug → heading):
-
-| Slug | Heading |
-|---|---|
-| `decisions` | Design decisions |
-| `deviations` | Deviations |
-| `tradeoffs` | Tradeoffs |
-| `questions` | Open questions |
-
-`--file` is optional. When omitted, the script writes to `./implementation-notes.html` in the current working directory. When a spec path is known, pass `--file` so notes land next to the spec rather than in CWD.
-
-Append entries as decisions are made — do not batch them until the end.
-
-## Gotchas
-
-- **Do not hand-edit `implementation-notes.html`.** The append script locates each section by its `<section id="...">` marker and the first `</ul>` after it. Editing the structure breaks subsequent appends; the script raises a `RuntimeError` naming the missing marker.
-- **`--about` and `--note` are HTML-escaped automatically** — pass raw text, not pre-escaped HTML.
-
-## File index
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | This hub |
-| `packages/claude-dev-env/skills/implement/scripts/append_note.py` | CLI to append one entry to a section |
-| `packages/claude-dev-env/skills/implement/scripts/implement_scripts_constants/notes_constants.py` | Section slugs → headings and default filename |

package/skills/implement/scripts/CLAUDE.md

@@ -1,22 +0,0 @@
-# scripts (spec-build skill)
-
-Support scripts for the spec-build (`implement`) skill. These scripts create and append to the `implementation-notes.html` sidecar file the skill maintains during a spec build.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `append_note.py` | CLI that creates `implementation-notes.html` with four sections on first run and appends a `<li>` to a named section on later runs |
-| `test_append_note.py` | Tests for `append_note.py` |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `implement_scripts_constants/` | Section slug → heading map and default filename constant |
-
-## Conventions
-
-- `append_note.py` imports section metadata from `implement_scripts_constants.notes_constants`.
-- HTML-escaping of `--about` and `--note` is handled by the script; callers pass raw text.
-- The script is invoked as `python "${CLAUDE_SKILL_DIR}/scripts/append_note.py"` from within the skill, where `$CLAUDE_SKILL_DIR` resolves to the installed skill directory at runtime.

package/skills/implement/scripts/append_note.py

@@ -1,133 +0,0 @@
-#!/usr/bin/env python3
-"""Append an entry to implementation-notes.html under one of four sections.
-
-Used by the `implement` skill. Creates the file with all four sections if it
-does not exist; otherwise appends a new <li> under the requested section.
-
-Usage:
-    python append_note.py --section decisions --about "Where to write the file" --note "Wrote next to spec rather than CWD because spec path was known."
-    python append_note.py --section questions --about "Auth model" --note "Spec didn't say whether sessions persist across restarts." --file ./notes.html
-"""
-
-from __future__ import annotations
-
-import argparse
-import html
-import sys
-from pathlib import Path
-
-from implement_scripts_constants.notes_constants import DEFAULT_NOTES_FILENAME, HEADING_BY_SLUG
-
-
-def _build_skeleton() -> str:
-    section_blocks = "\n".join(
-        f'  <section id="{each_slug}">\n    <h2>{each_heading}</h2>\n    <ul></ul>\n  </section>'
-        for each_slug, each_heading in HEADING_BY_SLUG.items()
-    )
-    return (
-        "<!doctype html>\n"
-        '<html lang="en">\n'
-        "<head>\n"
-        '  <meta charset="utf-8">\n'
-        "  <title>Implementation notes</title>\n"
-        "</head>\n"
-        "<body>\n"
-        "  <h1>Implementation notes</h1>\n"
-        f"{section_blocks}\n"
-        "</body>\n"
-        "</html>\n"
-    )
-
-
-def _ensure_file(target: Path) -> str:
-    if not target.exists():
-        target.parent.mkdir(parents=True, exist_ok=True)
-        skeleton = _build_skeleton()
-        target.write_text(skeleton, encoding="utf-8")
-        return skeleton
-    return target.read_text(encoding="utf-8")
-
-
-def _render_entry(about: str, note: str) -> str:
-    return f"<li><strong>{html.escape(about)}:</strong> {html.escape(note)}</li>"
-
-
-def _insert_entry(document: str, slug: str, entry: str) -> str:
-    open_marker = f'<section id="{slug}">'
-    section_close_marker = "</section>"
-    close_marker = "</ul>"
-    section_start = document.find(open_marker)
-    if section_start == -1:
-        raise RuntimeError(
-            f"section '{slug}' not found in file — the file may have been "
-            f"edited by hand. Restore the four <section id=...> blocks or "
-            f"delete the file so it can be regenerated."
-        )
-    section_end = document.find(section_close_marker, section_start)
-    if section_end == -1:
-        raise RuntimeError(
-            f"section '{slug}' is missing its closing </section> — the file "
-            f"may have been edited by hand."
-        )
-    close_at = document.find(close_marker, section_start, section_end)
-    if close_at == -1:
-        raise RuntimeError(
-            f"section '{slug}' is missing its closing </ul> — the file may "
-            f"have been edited by hand."
-        )
-    boundary = close_at
-    while boundary > 0 and document[boundary - 1] in (" ", "\n"):
-        boundary -= 1
-    new_line = f"\n      {entry}"
-    return document[:boundary] + new_line + "\n    " + document[close_at:]
-
-
-def _parse_arguments() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description=f"Append an entry to {DEFAULT_NOTES_FILENAME}.",
-    )
-    parser.add_argument(
-        "--section",
-        required=True,
-        choices=sorted(HEADING_BY_SLUG.keys()),
-        help="Which section to append under.",
-    )
-    parser.add_argument(
-        "--about",
-        required=True,
-        help="Short label naming the part of the spec this entry relates to.",
-    )
-    parser.add_argument(
-        "--note",
-        required=True,
-        help="The decision / deviation / tradeoff / question itself.",
-    )
-    parser.add_argument(
-        "--file",
-        default=DEFAULT_NOTES_FILENAME,
-        help=(
-            f"Path to the notes file. Defaults to ./{DEFAULT_NOTES_FILENAME} "
-            f"in the current working directory."
-        ),
-    )
-    return parser.parse_args()
-
-
-def main() -> int:
-    """Parse CLI arguments and append one entry to the notes file.
-
-    Returns:
-        Process exit code (0 on success).
-    """
-    arguments = _parse_arguments()
-    target_path = Path(arguments.file).expanduser().resolve()
-    document = _ensure_file(target_path)
-    entry = _render_entry(arguments.about, arguments.note)
-    updated = _insert_entry(document, arguments.section, entry)
-    target_path.write_text(updated, encoding="utf-8")
-    print(f"appended to [{arguments.section}] in {target_path}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/implement/scripts/implement_scripts_constants/CLAUDE.md

@@ -1,22 +0,0 @@
-# implement_scripts_constants
-
-Constants module for the `implement` skill's `append_note.py` script.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `notes_constants.py` | `HEADING_BY_SLUG` dict (section slugs → display headings) and `DEFAULT_NOTES_FILENAME` |
-
-## Exported constants
-
-| Constant | Value | Used by |
-|---|---|---|
-| `HEADING_BY_SLUG` | `{"decisions": "Design decisions", "deviations": "Deviations", "tradeoffs": "Tradeoffs", "questions": "Open questions"}` | `append_note.py` — maps `--section` slug to the `<h2>` heading in the HTML file |
-| `DEFAULT_NOTES_FILENAME` | `"implementation-notes.html"` | `append_note.py` — default output path when `--file` is omitted |
-
-## Conventions
-
-- This module is imported directly by `append_note.py` in the parent `scripts/` directory.
-- Adding a new section requires a new entry in `HEADING_BY_SLUG` and a matching branch in `append_note.py`.

package/skills/implement/scripts/implement_scripts_constants/notes_constants.py

@@ -1,12 +0,0 @@
-"""Configuration for the implementation-notes append script."""
-
-from __future__ import annotations
-
-HEADING_BY_SLUG: dict[str, str] = {
-    "decisions": "Design decisions",
-    "deviations": "Deviations",
-    "tradeoffs": "Tradeoffs",
-    "questions": "Open questions",
-}
-
-DEFAULT_NOTES_FILENAME = "implementation-notes.html"

package/skills/implement/scripts/test_append_note.py

@@ -1,191 +0,0 @@
-"""Tests for append_note.
-
-Covers:
-- _build_skeleton emits a four-section HTML document keyed by every slug
-- _ensure_file creates a fresh file on first call and round-trips on subsequent calls
-- _render_entry HTML-escapes the about label and the note body
-- _insert_entry puts the first <li> on its own line and keeps a 6-space indent across entries
-- _insert_entry raises a descriptive RuntimeError when the section block is missing
-- _insert_entry raises a descriptive RuntimeError when the closing </ul> is missing
-- main appends through the CLI surface against a real on-disk file
-"""
-
-from __future__ import annotations
-
-import importlib.util
-import subprocess
-import sys
-from pathlib import Path
-from types import ModuleType
-
-import pytest
-
-_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
-
-
-def _load_module() -> ModuleType:
-    if str(_SCRIPTS_DIRECTORY) not in sys.path:
-        sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
-    module_path = _SCRIPTS_DIRECTORY / "append_note.py"
-    spec = importlib.util.spec_from_file_location("append_note", module_path)
-    assert spec is not None
-    assert spec.loader is not None
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-append_note_module = _load_module()
-HEADING_BY_SLUG = append_note_module.HEADING_BY_SLUG
-
-
-def test_should_build_skeleton_with_every_section_slug() -> None:
-    skeleton = append_note_module._build_skeleton()
-
-    for each_slug, each_heading in HEADING_BY_SLUG.items():
-        assert f'<section id="{each_slug}">' in skeleton
-        assert f"<h2>{each_heading}</h2>" in skeleton
-    assert skeleton.count("<ul></ul>") == len(HEADING_BY_SLUG)
-
-
-def test_should_create_file_with_skeleton_on_first_ensure(tmp_path: Path) -> None:
-    target = tmp_path / "subdir" / "implementation-notes.html"
-
-    document = append_note_module._ensure_file(target)
-
-    assert target.exists()
-    assert document == target.read_text(encoding="utf-8")
-    assert '<section id="decisions">' in document
-
-
-def test_should_return_existing_content_on_subsequent_ensure(tmp_path: Path) -> None:
-    target = tmp_path / "notes.html"
-    custom_content = "<!doctype html><html><body>existing</body></html>\n"
-    target.write_text(custom_content, encoding="utf-8")
-
-    returned = append_note_module._ensure_file(target)
-
-    assert returned == custom_content
-
-
-def test_should_escape_html_metacharacters_in_about_and_note() -> None:
-    entry = append_note_module._render_entry("a<b & c>d", "<script>x</script>")
-
-    assert "<script>" not in entry
-    assert "&lt;script&gt;" in entry
-    assert "a&lt;b &amp; c&gt;d" in entry
-
-
-def test_should_put_first_entry_on_its_own_line_inside_empty_ul() -> None:
-    skeleton = append_note_module._build_skeleton()
-    entry = append_note_module._render_entry("First", "alpha")
-
-    after_first = append_note_module._insert_entry(skeleton, "decisions", entry)
-
-    assert "<ul>      <li>" not in after_first
-    assert "<ul>\n      <li>" in after_first
-
-
-def test_should_keep_uniform_six_space_indent_across_multiple_entries() -> None:
-    skeleton = append_note_module._build_skeleton()
-    first_entry = append_note_module._render_entry("First", "alpha")
-    second_entry = append_note_module._render_entry("Second", "beta")
-
-    after_first = append_note_module._insert_entry(skeleton, "decisions", first_entry)
-    after_second = append_note_module._insert_entry(after_first, "decisions", second_entry)
-
-    decisions_section_start = after_second.index('<section id="decisions">')
-    decisions_section_end = after_second.index("</section>", decisions_section_start)
-    decisions_section = after_second[decisions_section_start:decisions_section_end]
-
-    assert "          <li>" not in decisions_section
-    assert decisions_section.count("\n      <li>") == 2
-
-
-def test_should_raise_when_requested_section_is_absent() -> None:
-    document_without_section = "<html><body></body></html>\n"
-    entry = append_note_module._render_entry("x", "y")
-
-    with pytest.raises(RuntimeError, match="section 'decisions' not found"):
-        append_note_module._insert_entry(document_without_section, "decisions", entry)
-
-
-def test_should_raise_when_closing_ul_is_missing() -> None:
-    truncated_section = '<section id="decisions">\n    <h2>Design decisions</h2>\n    <ul>\n  </section>\n'
-    entry = append_note_module._render_entry("x", "y")
-
-    with pytest.raises(RuntimeError, match="missing its closing </ul>"):
-        append_note_module._insert_entry(truncated_section, "decisions", entry)
-
-
-def test_should_not_borrow_closing_ul_from_a_later_section() -> None:
-    malformed_first_with_intact_second = (
-        '<section id="decisions">\n'
-        '    <h2>Design decisions</h2>\n'
-        '    <ul>\n'
-        '  </section>\n'
-        '  <section id="deviations">\n'
-        '    <h2>Deviations</h2>\n'
-        '    <ul></ul>\n'
-        '  </section>\n'
-    )
-    entry = append_note_module._render_entry("x", "y")
-
-    with pytest.raises(RuntimeError, match="missing its closing </ul>"):
-        append_note_module._insert_entry(malformed_first_with_intact_second, "decisions", entry)
-
-
-def test_should_raise_when_closing_section_is_missing() -> None:
-    section_without_close = '<section id="decisions">\n    <h2>Design decisions</h2>\n    <ul></ul>\n'
-    entry = append_note_module._render_entry("x", "y")
-
-    with pytest.raises(RuntimeError, match="missing its closing </section>"):
-        append_note_module._insert_entry(section_without_close, "decisions", entry)
-
-
-def test_should_append_through_cli_against_real_file(tmp_path: Path) -> None:
-    target = tmp_path / "notes.html"
-    script_path = _SCRIPTS_DIRECTORY / "append_note.py"
-
-    first_run = subprocess.run(
-        [
-            sys.executable,
-            str(script_path),
-            "--section",
-            "decisions",
-            "--about",
-            "First",
-            "--note",
-            "alpha",
-            "--file",
-            str(target),
-        ],
-        cwd=str(_SCRIPTS_DIRECTORY),
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-    second_run = subprocess.run(
-        [
-            sys.executable,
-            str(script_path),
-            "--section",
-            "questions",
-            "--about",
-            "Q1",
-            "--note",
-            "<beta & gamma>",
-            "--file",
-            str(target),
-        ],
-        cwd=str(_SCRIPTS_DIRECTORY),
-        capture_output=True,
-        text=True,
-        check=False,
-    )
-
-    assert first_run.returncode == 0, first_run.stderr
-    assert second_run.returncode == 0, second_run.stderr
-    output = target.read_text(encoding="utf-8")
-    assert "<li><strong>First:</strong> alpha</li>" in output
-    assert "<li><strong>Q1:</strong> &lt;beta &amp; gamma&gt;</li>" in output

package/skills/log-audit/CLAUDE.md

@@ -1,20 +0,0 @@
-# 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

@@ -1,66 +0,0 @@
----
-name: log-audit
-description: >-
-  Watches this repo's own logs for patterns worth acting on: clusters recurring
-  errors and timing regressions, then opens a grouped fix PR or a tracked
-  optimization issue per real finding. Use for /log-audit, 'audit the logs',
-  'what keeps failing', or 'what's getting slower'.
----
-
-# 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

@@ -1,9 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-# 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
-```