claude-dev-env 1.93.0 → 1.94.0

package/skills/monitor-open-prs/scripts/test_discover_open_prs.py

@@ -1,149 +0,0 @@
-"""Tests for discover_open_prs.py — merges gh-search output across owners."""
-
-from __future__ import annotations
-
-import importlib.util
-import json
-import pathlib
-import sys
-
-import pytest
-
-
-def _load_discovery_module():
-    scripts_directory = pathlib.Path(__file__).parent
-    sys.path.insert(0, str(scripts_directory))
-    module_path = scripts_directory / "discover_open_prs.py"
-    module_spec = importlib.util.spec_from_file_location(
-        "discover_open_prs", module_path
-    )
-    loaded_module = importlib.util.module_from_spec(module_spec)
-    sys.modules["discover_open_prs"] = loaded_module
-    module_spec.loader.exec_module(loaded_module)
-    return loaded_module
-
-
-discover_open_prs = _load_discovery_module()
-
-
-def _make_fake_gh(responses_by_owner: dict):
-    """Return a callable whose behavior mocks subprocess.run for gh search."""
-
-    class FakeCompletedProcess:
-        def __init__(self, stdout_text: str):
-            self.stdout = stdout_text
-            self.returncode = 0
-
-    def fake_run(command_argv, check, capture_output, text):
-        owner = _extract_owner_argument(command_argv)
-        stdout_text = json.dumps(responses_by_owner.get(owner, []))
-        return FakeCompletedProcess(stdout_text)
-
-    return fake_run
-
-
-def _extract_owner_argument(command_argv) -> str:
-    for each_index, each_token in enumerate(command_argv):
-        if each_token == "--owner":
-            return command_argv[each_index + 1]
-    return ""
-
-
-class TestDiscoverOpenPrsBothOwnersReturnResults:
-    def test_merges_prs_across_both_owners(self, monkeypatch):
-        first_owner_prs = [
-            {
-                "number": 1,
-                "repository": {"nameWithOwner": "jl-cmd/alpha"},
-                "url": "https://github.com/jl-cmd/alpha/pull/1",
-                "headRefName": "feat-one",
-                "baseRefName": "main",
-            }
-        ]
-        second_owner_prs = [
-            {
-                "number": 2,
-                "repository": {"nameWithOwner": "JonEcho/beta"},
-                "url": "https://github.com/JonEcho/beta/pull/2",
-                "headRefName": "feat-two",
-                "baseRefName": "main",
-            }
-        ]
-        fake_run = _make_fake_gh(
-            {"jl-cmd": first_owner_prs, "JonEcho": second_owner_prs}
-        )
-        monkeypatch.setattr(discover_open_prs.subprocess, "run", fake_run)
-
-        all_discovered = discover_open_prs.discover_open_prs(
-            all_owners=["jl-cmd", "JonEcho"]
-        )
-
-        assert len(all_discovered) == 2
-        discovered_numbers = sorted(each["number"] for each in all_discovered)
-        assert discovered_numbers == [1, 2]
-
-
-class TestDiscoverOpenPrsOneOwnerEmpty:
-    def test_handles_single_owner_returning_empty_list(self, monkeypatch):
-        first_owner_prs = [
-            {
-                "number": 5,
-                "repository": {"nameWithOwner": "jl-cmd/gamma"},
-                "url": "https://github.com/jl-cmd/gamma/pull/5",
-                "headRefName": "feat-five",
-                "baseRefName": "main",
-            }
-        ]
-        fake_run = _make_fake_gh({"jl-cmd": first_owner_prs, "JonEcho": []})
-        monkeypatch.setattr(discover_open_prs.subprocess, "run", fake_run)
-
-        all_discovered = discover_open_prs.discover_open_prs(
-            all_owners=["jl-cmd", "JonEcho"]
-        )
-
-        assert len(all_discovered) == 1
-        assert all_discovered[0]["number"] == 5
-
-
-class TestDiscoverOpenPrsBothEmpty:
-    def test_returns_empty_list_when_no_owner_has_open_prs(self, monkeypatch):
-        fake_run = _make_fake_gh({"jl-cmd": [], "JonEcho": []})
-        monkeypatch.setattr(discover_open_prs.subprocess, "run", fake_run)
-
-        all_discovered = discover_open_prs.discover_open_prs(
-            all_owners=["jl-cmd", "JonEcho"]
-        )
-
-        assert all_discovered == []
-
-
-class TestDiscoverOpenPrsEntryShape:
-    def test_each_entry_exposes_number_owner_repo_refs_and_url(self, monkeypatch):
-        fake_run = _make_fake_gh(
-            {
-                "jl-cmd": [
-                    {
-                        "number": 42,
-                        "repository": {"nameWithOwner": "jl-cmd/demo"},
-                        "url": "https://github.com/jl-cmd/demo/pull/42",
-                        "headRefName": "feat-demo",
-                        "baseRefName": "main",
-                    }
-                ],
-                "JonEcho": [],
-            }
-        )
-        monkeypatch.setattr(discover_open_prs.subprocess, "run", fake_run)
-
-        all_discovered = discover_open_prs.discover_open_prs(
-            all_owners=["jl-cmd", "JonEcho"]
-        )
-
-        assert len(all_discovered) == 1
-        only_entry = all_discovered[0]
-        assert only_entry["number"] == 42
-        assert only_entry["owner"] == "jl-cmd"
-        assert only_entry["repo"] == "demo"
-        assert only_entry["head_ref"] == "feat-demo"
-        assert only_entry["base_ref"] == "main"
-        assert only_entry["url"].endswith("/pull/42")

package/skills/monitor-open-prs/test_skill_contract.py

@@ -1,27 +0,0 @@
-"""Markdown assertion tests for monitor-open-prs SKILL.md."""
-
-from __future__ import annotations
-
-import pathlib
-
-
-def _read_skill_text() -> str:
-    skill_path = pathlib.Path(__file__).parent / "SKILL.md"
-    return skill_path.read_text(encoding="utf-8")
-
-
-def test_skill_has_frontmatter_name():
-    skill_text = _read_skill_text()
-    assert skill_text.startswith("---\n")
-    assert "name: monitor-open-prs" in skill_text
-
-
-def test_skill_references_bugbot_retrigger_flag():
-    skill_text = _read_skill_text()
-    assert "--bugbot-retrigger" in skill_text
-
-
-def test_skill_enumerates_both_owner_scopes():
-    skill_text = _read_skill_text()
-    assert "jl-cmd" in skill_text
-    assert "JonEcho" in skill_text

package/skills/post-audit-findings/SKILL.md

@@ -1,80 +0,0 @@
----
-name: post-audit-findings
-description: >-
-  Publishes an audit pass as a GitHub PR review through post_audit_thread.py:
-  maps findings to the review-comment JSON shape, splits anchored from
-  unanchored, and collects the comment and thread ids for the fix loop. Invoked
-  by audit skills (bugteam, qbug, findbugs) after each pass; not for ad-hoc
-  comments.
----
-
-# Post Audit Findings
-
-**Core principle:** every audit pass — CLEAN or DIRTY — lands on the PR as exactly one review, so the unresolved-thread gate sees the pass and each finding becomes its own resolvable thread.
-
-## How callers invoke this
-
-- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "post-audit-findings", args: "--skill <caller> --owner <O> --repo <R> --pr-number <N> --commit <head_sha> --state <CLEAN|DIRTY> --findings-json <path>"})`.
-- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/post-audit-findings/SKILL.md` and apply it with the parameters below."
-
-`--skill <caller>` is required — the posted review names the audit skill that produced it. Capture `<head_sha>` once, at the start of the posting step, via `git rev-parse HEAD` in the worktree the diff was scoped against.
-
-## Findings-JSON mapping
-
-The findings file's root is a list of objects shaped `{path, line, side, severity, description, fix_summary}`. Map each audit finding:
-
-- Finding `file` → `path`.
-- The `failure_mode` field carries both the failure narrative AND the `Fix:` / `Validation:` text (per [`agents/code-quality-agent.md`](../../agents/code-quality-agent.md), "The `failure_mode` field is the audit-to-fix handoff"). Split it at the literal `Fix:` heading: the prefix becomes `description`; the suffix starting at `Fix:` (including the trailing `Validation:` clause) becomes `fix_summary`. When a finding omits the `Fix:` heading, write the full `failure_mode` text to BOTH fields so the script's `INLINE_COMMENT_BODY_TEMPLATE` still renders coherently.
-- Set `side="RIGHT"` for every entry.
-- On CLEAN, the file holds an empty array (`[]`).
-
-## Anchored vs unanchored partition
-
-Before serializing, partition findings into **anchored** (the line appears in the diff at `--commit`) and **unanchored** (it does not). Only anchored findings go into the JSON — the GitHub reviews API rejects the ENTIRE POST when any inline comment targets a line outside the diff, so a single unanchored entry breaks the whole review. Surface unanchored findings in the caller's user-facing report instead.
-
-Zero anchored findings → `--state CLEAN`; one or more → `--state DIRTY`.
-
-## Posting
-
-```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/post_audit_thread.py" \
-  --skill <caller> \
-  --owner <owner> \
-  --repo <repo> \
-  --pr-number <N> \
-  --commit <head_sha> \
-  --state <CLEAN|DIRTY> \
-  --findings-json <path>
-```
-
-The script POSTs one review to `/repos/{owner}/{repo}/pulls/{N}/reviews`: `event=APPROVE` on CLEAN (GitHub stores it as `state=APPROVED`; empty `comments[]`; body documents "no findings"), `event=REQUEST_CHANGES` on DIRTY (one inline anchored comment per finding; each becomes its own resolvable thread).
-
-**Self-PR auto-toggle.** GitHub rejects both `APPROVE` and `REQUEST_CHANGES` with HTTP 422 when the authenticated identity matches the PR author. `post_audit_thread.py` detects this 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 on the request changes, so no swap-back step exists.
-
-Configuration:
-
-- `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the toggle — set one to pin a reviewer identity by token.
-- `BUGTEAM_REVIEWER_ACCOUNT` names which authenticated alternate to prefer (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 runs; on self-PR with no usable alternate the script exits 1 with a message pointing at `gh auth login`.
-
-**Exit codes:** `0` — success; the new review's `html_url` prints to stdout (surface it in the caller's report). `1` — user input error. `2` — retry exhaustion (1s / 4s / 16s backoff across four attempts): a hard blocker. On exit 2 the caller halts the loop (`error: post_audit_thread retry exhausted`) or tells the user the review post failed and the unresolved-thread gate will not see this pass — never a silent retry.
-
-## Harvest ids for the fix loop
-
-After a DIRTY post, fetch the new review's threads once and record, per finding: the finding comment's URL, its numeric comment id (the reply anchor), and its thread node id (`PRRT_…`, the `resolve_thread` handle):
-
-```
-pull_request_read(method="get_review_comments", ...) → match comments to the new review id
-```
-
-Hand the id triple to the fix step — `pr-fix-protocol` consumes it for the reply-and-resolve unit. Harvesting at post time saves the fix executor a second fetch and pins the mapping before any thread state changes.
-
-## Gotchas
-
-- **One unanchored comment voids the whole review.** The partition is not an optimization; skipping it makes every DIRTY post a coin flip.
-- **CLEAN still posts.** A pass that finds nothing and posts nothing is invisible to the unresolved-thread gate and to anyone auditing the loop's history.
-- **Exit 2 is a stop, not a retry.** The script already retried with backoff; a caller looping on top of it hammers the API to no effect.
-
-## Folder map
-
-- `SKILL.md` — this file. The posting script and its body template constants live in `_shared/pr-loop/scripts/` (`post_audit_thread.py`, `pr_loop_shared_constants/post_audit_thread_constants.py`); the review-payload reference is `_shared/pr-loop/gh-payloads.md`.

package/skills/pr-consistency-audit/CLAUDE.md

@@ -1,34 +0,0 @@
-# pr-consistency-audit skill
-
-Audits a PR for cross-file inconsistencies: wrong argument names, missing required args, references to files or scripts that do not exist, stale feature remnants, docstring-vs-code mismatches, placeholder text, cross-file contradictions, parameter naming convention violations, and cross-platform bugs.
-
-**Trigger:** "audit this PR", "find inconsistencies", "cross-reference docs against scripts", "check for stale references", "PR consistency audit".
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Full process: build manifest, find canonical sources, run 10 detection rules, produce summary |
-| `reference/detection-rules.md` | All 10 detection rules with procedures |
-| `reference/illustrations.md` | Concrete examples of findings with why-they-matter explanations |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `reference/` | Detection rules and worked illustrations |
-
-## Process overview
-
-1. **Build manifest** — read every changed file; track argparse args, MCP tool calls, shell commands, file path references, named constants, and docstring claims. Write to a temp JSON file.
-2. **Find canonical sources** — note which files define the ground truth for each concept (schemas, payloads, config files, `.py` sources).
-3. **Run all 10 detection rules** — write each finding at once to a temp CSV with `file_path | line_number | rule_id | severity | what_is_wrong | what_it_should_be | evidence_path | evidence_detail`.
-4. **Produce summary** — print totals by rule and severity; list top findings; cite the CSV and manifest paths.
-
-## Severity
-
-| Severity | Meaning |
-|---|---|
-| P0 | Runtime failure — the command or tool call will error |
-| P1 | Confusing or wrong — will mislead but not crash |
-| P2 | Cleanup — stale references, docs out of sync |

package/skills/pr-consistency-audit/SKILL.md

@@ -1,116 +0,0 @@
----
-name: pr-consistency-audit
-description: >-
-  Audits a PR for cross-file inconsistencies: wrong arguments, missing files or
-  scripts, stale remnants, docstring mismatches, and cross-platform bugs. Use
-  when the user says 'audit this PR', 'find inconsistencies', 'cross-reference
-  docs against scripts', 'check for stale references', or 'PR consistency
-  audit'.
----
-
-# PR Consistency Audit
-
-Read every changed file in a pull request. Find every inconsistency across files. Leave nothing unchecked. Leave nothing assumed. Zero context needed beyond the diff.
-
-## Gotchas
-
-- The highest-signal rule is canonical-source cross-reference. Do it first. Do it slowly. Copilot found 20 of its 43 findings with this rule alone. Missing it means missing half the bugs.
-- Parameter naming conventions are per-tool, not per-project. `issue_read` uses `issue_number` (snake_case). `add_issue_comment` uses `issueNumber` (camelCase). A doc that mixes them is wrong even if snake_case works for `issue_read`.
-- When a finding appears in many files with the same wrong pattern, flag every instance individually. Do not say "this is wrong in 20 files" and move on. List every file with its line.
-- Template files and obstacle files are often skipped because they feel "generated" or "low priority." They are not. Copilot found 6 issues in template files that human auditors never opened.
-- A manifest written to a temp file is not optional. Hold all script signatures, all MCP tool names, all constants, and all concept names in a JSON file. Read from it during detection. Memory fails. Files do not.
-
-## When this skill applies
-
-Trigger when the user provides a PR diff, a list of changed files, or asks to audit cross-file consistency. The agent needs no prior knowledge of the repo, the scripts, or the project conventions.
-
-## Process
-
-### Step 1: Build the manifest
-
-Read every file in the diff. Top to bottom. Build `<tmp>/audit-manifest-<timestamp>.json`. Track:
-
-- Python scripts → argparse arguments (`add_argument("--name", ...)`), which are `required=True`
-- MCP tool call patterns in docs → tool name, every parameter used, file and line
-- Shell commands (`gh`, `git`, `python`, `bash`) → full command, file, line
-- File paths referenced in docs → whether they resolve to real files
-- Named concepts in prose → "inline_lag", "COPILOT_WAIT", "bugfind", phase names, state values. File and line each.
-- Constants, thresholds, timeouts → value, concept it measures, file, line
-- Functions with docstring claims → function name, claim made, file, line
-
-### Step 2: Find canonical sources
-
-Identify the files that define the authoritative form of each concept. Signs a file is canonical:
-
-- Has structured schemas, payload definitions, API contracts (files like `gh-payloads.md`, `mcp_tool_signatures.json`, `config.py`)
-- Name includes "reference", "spec", "schema", "payload", "contract", "canonical"
-- Other files cite it as the source of truth
-- It defines the implementation that docstrings describe (the `.py` file, not the `.md` that talks about it)
-
-For each canonical source, note what concept it is canonical for. When a rule needs to decide what is "correct," the canonical source wins.
-
-### Step 3: Run detection rules
-
-Read [`reference/detection-rules.md`](reference/detection-rules.md). Run all ten rules against every file. Write findings immediately to `<tmp>/inconsistency-audit-<timestamp>.csv`:
-
-```
-file_path | line_number | rule_id | severity | what_is_wrong | what_it_should_be | evidence_path | evidence_detail
-```
-
-### Step 4: Produce summary
-
-Print to stdout:
-
-```
-====== DIFF INCONSISTENCY AUDIT ======
-Files audited: <N>
-Canonical sources: <list>
-Total findings: <N>
-
-By rule:
-Rule 1 — canonical_source_cross_reference: X (P0: A, P1: B, P2: C)
-...
-
-By severity:
-P0 (runtime failure): X
-P1 (confusing or wrong): Y
-P2 (cleanup): Z
-
-Top findings:
-1. file:line — [P0] — what is wrong — what it should be
-2. ...
-
-Full report: <tmp>/inconsistency-audit-<timestamp>.csv
-Manifest: <tmp>/audit-manifest-<timestamp>.json
-====== END AUDIT ======
-```
-
-## Constraints
-
-- Read every file completely. No skimming.
-- Write findings immediately. Do not batch in memory.
-- Every finding cites file:line of problem AND file:line of evidence.
-- When two files contradict, flag both. Do not guess which is correct.
-- If unresolvable, mark "unresolvable — no canonical source found."
-- Run every rule. The highest-signal findings come from rules you think will be empty.
-
-## Severity
-
-| Severity | Meaning |
-|----------|---------|
-| P0 | Runtime failure — the command or tool call will error |
-| P1 | Confusing or wrong — will mislead but not crash |
-| P2 | Cleanup — stale references, docs out of sync |
-
-## File index
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Hub — process, constraints, gotchas |
-| `reference/detection-rules.md` | All 10 detection rules with procedures |
-| `reference/illustrations.md` | Concrete findings with why-they-matter explanations |
-
-## Folder map
-
-- `SKILL.md` — hub.
-- `reference/` — detection rules and illustrations.

package/skills/pr-consistency-audit/reference/CLAUDE.md

@@ -1,16 +0,0 @@
-# pr-consistency-audit/reference
-
-Reference material for the `pr-consistency-audit` skill. These files define the detection rules the skill runs and show worked examples of findings.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `detection-rules.md` | All 10 detection rules, each with a procedure for how to run it |
-| `illustrations.md` | Concrete examples of findings with explanations of why each matters |
-
-## Conventions
-
-- The skill reads `detection-rules.md` during Step 3 (run detection rules). Every rule must run against every file; none are skippable.
-- Rule 1 (canonical-source cross-reference) is the highest-signal rule. The skill runs it first.
-- `illustrations.md` is for reviewers and skill authors, not for the skill's runtime process.

package/skills/pr-consistency-audit/reference/detection-rules.md

@@ -1,96 +0,0 @@
-# Detection Rules
-
-All 10 rules. Run every rule against every file. Do not skip. Do not combine. Rules are independent — a file can trigger multiple rules.
-
-## Rule 1: Canonical-source cross-reference
-
-For every canonical source, scan every other file for usages of the concepts it defines. The canonical source is the ground truth. Flag every mismatch.
-
-How: Take the canonical MCP payload doc. Extract every tool name and its parameter names. Scan every markdown file for calls to those tools. Compare each call's parameter names against the canonical form.
-
-How: Take the canonical config file. Extract every constant name and value. Scan every other file. Flag any file that hardcodes the value. Flag any file that uses a different value for the same concept.
-
-This rule caught 20 of Copilot's 43 findings. It is the highest-signal rule. Run it first.
-
-## Rule 2: Parameter naming convention
-
-Group all MCP tool calls by tool name. Check whether all call sites use the same parameter naming convention.
-
-How: Extract every parameter name from every tool call. Group by tool. If `add_issue_comment` appears in 10 files and 8 use `issueNumber` while 2 use `issue_number`, flag the 2.
-
-Conventions are per-tool. `issue_read` uses `issue_number` (snake_case). `add_issue_comment` uses `issueNumber` (camelCase). Snake_case for `add_issue_comment` is wrong.
-
-Also: check for two different parameter names that mean the same thing. `--number` vs `--pr-number` for a script that expects `--pr-number`.
-
-## Rule 3: Code vs docstring behavior
-
-For every function whose docstring makes a claim about return values or error handling, read the implementation.
-
-How: Find docstrings that say "returns X when Y" or "raises Z on error." Trace the code path. If the docstring says returns 0 when path missing but the code catches OSError and returns failure, flag it.
-
-How: Find docstrings that claim a side effect. Check whether the code does it unconditionally. Flag missing precondition checks.
-
-How: Find error handling claims like "tolerates already-removed worktrees." Read the except blocks. Read the conditionals. Verify every claim.
-
-## Rule 4: Nonexistent reference
-
-Every file path, script name, function name, tool name, or import referenced in a doc must resolve to something real.
-
-How: Extract every backtick-quoted identifier. Try to resolve it against the diff and the repo. Flag anything that cannot be found. A reference to `fetch_copilot_inline_comments.py` when no such file exists is P0. A reference to `EnterWorktree(path=...)` when no MCP tool by that name exists is P0.
-
-## Rule 5: Placeholder detection
-
-Scan for text that looks like a template never filled in. This is text that cannot be executed as written.
-
-Patterns to search for:
-- Double spaces where a value should be: "Spawn  — brief it: check  for"
-- Angle-bracket placeholders outside the standard `<O>` `<R>` `<N>` `<SHA>` set
-- Ellipsis as placeholder: "...", "…"
-- "TODO", "FIXME", "HACK", "XXX" in production documentation
-- "TKTK", "TK", "placeholder"
-- Missing arguments after a flag: `--flag` with no value following
-- Sentences that trail off: text ending in ", or", "like", "such as" without completing
-
-Severity: unexecutable placeholder is P0. Incomplete but still directionally useful is P1.
-
-## Rule 6: Cross-file contradiction
-
-When two files describe the same operation, they must agree.
-
-How: Group descriptions by topic — "how to post a review," "how to trigger bugbot," "who owns PR posting." For each topic, extract the description from every file. Compare who performs the action, what API is used, what parameters are passed, what the workflow order is. Flag any contradiction.
-
-Flag both files. Do not assume which is correct unless a canonical source resolves it.
-
-## Rule 7: Stale reference
-
-When a doc describes a feature, branch, phase, or pattern by name, verify the implementation still contains it.
-
-How: Extract named concepts from decision branches and gotcha sections. Search implementation files for each concept. If a doc describes an "inline_lag" branch but no implementation file contains "inline_lag" or "inline_lag_streak," the doc references a removed feature.
-
-P1: doc mentions something absent from implementation. P0: doc decision tree includes a branch whose predicate can never be reached because the implementation was removed.
-
-## Rule 8: Cross-platform assumption
-
-Code that handles platform-specific behavior must not break on other platforms.
-
-When you see Windows-specific patterns (`os.chmod` with `stat.S_IWRITE`, backslash paths, ReadOnly attribute handling), check: Does it run on Linux without crashing? Does `os.chmod(path, stat.S_IWRITE)` produce the right permissions on POSIX? It sets write-only, stripping read and execute from directories.
-
-Flag anything that would fail on a non-Windows system. Flag the reverse: POSIX-only code that would fail on Windows.
-
-## Rule 9: Script invocation correctness
-
-Every `python scripts/foo.py --*` in docs must match the script's actual argparse interface.
-
-From your manifest, compare each documented invocation against the script's `add_argument` definitions. Check every flag name matches exactly. Check every `required=True` argument is present. Check no argument appears that the script does not accept.
-
-Missing required args = P0. Wrong flag names = P0. Missing optional args = P2.
-
-argparse converts `--pr-number` to `pr_number`. The invocation flag is `--pr-number`, not `--pr_number` or `--number`.
-
-## Rule 10: Value consistency
-
-When the same named concept has a numeric value in multiple files, all files must agree.
-
-How: Group constants, thresholds, and timeouts by semantic concept. "Bugbot post-trigger wakeup" vs "inline-lag retry delay" are different concepts. Values that represent the same thing must match. Flag any file whose value differs from the majority or from the canonical config.
-
-Values that legitimately differ by context are not conflicts. Group by full semantic meaning before comparing.

package/skills/pr-consistency-audit/reference/illustrations.md

@@ -1,78 +0,0 @@
-# Illustrations
-
-Concrete examples of findings with why-they-matter explanations.
-
-## Wrong argument name in script invocation
-
-```
-file_path: SKILL.md
-line_number: 100
-rule_id: 9
-severity: P0
-what_is_wrong: check_bugbot_ci.py --check-active --sha <SHA>
-what_it_should_be: check_bugbot_ci.py --owner <O> --repo <R> --check-active --sha <SHA>
-evidence_path: scripts/check_bugbot_ci.py
-evidence_detail: lines 134-136 define add_argument("--owner", required=True) and add_argument("--repo", required=True). Both required args are missing from the documented invocation.
-```
-
-Why this matters: If an agent copies the command from the doc, the script fails with "the following arguments are required: --owner, --repo." The agent cannot trigger bugbot.
-
-## Parameter naming convention mismatch across tool family
-
-```
-file_path: SKILL.md
-line_number: 162
-rule_id: 2
-severity: P0
-what_is_wrong: add_issue_comment(owner="OWNER", repo="REPO", issue_number=NUMBER, body="bugbot run")
-what_it_should_be: add_issue_comment(owner="OWNER", repo="REPO", issueNumber=NUMBER, body="bugbot run")
-evidence_path: _shared/pr-loop/gh-payloads.md
-evidence_detail: lines 67-72 document add_issue_comment with issueNumber (camelCase). issue_read uses issue_number (snake_case) — the two tools have different conventions.
-```
-
-Why this matters: The tool call fails at runtime. Twenty files had this same bug because they copied from each other.
-
-## Docstring claim contradicts implementation
-
-```
-file_path: scripts/remove_tree.py
-line_number: 15
-rule_id: 3
-severity: P0
-what_is_wrong: Docstring says "returns 0 when the path never existed." Implementation calls shutil.rmtree(target_path) which raises FileNotFoundError, caught as OSError, returning EXIT_CODE_REMOVE_TREE_FAILURE.
-what_it_should_be: Check Path(target_path).exists() before rmtree and return 0 when absent, or update the docstring.
-evidence_path: scripts/remove_tree.py
-evidence_detail: line 15 docstring claim vs lines 22-28 implementation — the except OSError handler returns EXIT_CODE_REMOVE_TREE_FAILURE for FileNotFoundError.
-```
-
-Why this matters: Teardown scripts calling remove_tree() on an already-cleaned temp directory get a failure return. The orchestrator treats this as a real error.
-
-## Stale feature reference in gotcha section
-
-```
-file_path: SKILL.md
-line_number: 34
-rule_id: 7
-severity: P1
-what_is_wrong: Gotcha describes "inline_lag" with its own streak counter and 90s wait. The decision branch for inline_lag is still present in per-tick.md lines 102-106 — the feature was supposed to be removed but both the gotcha and the branch remain.
-what_it_should_be: Remove the gotcha and the inline_lag decision branch from per-tick.md.
-evidence_path: reference/per-tick.md
-evidence_detail: lines 102-106 still contain the fourth BUGBOT decision branch for inline_lag.
-```
-
-Why this matters: An agent reading the gotcha thinks inline_lag is real and may misclassify a dirty review as transient lag, waiting rather than fixing.
-
-## Placeholder text in template file
-
-```
-file_path: bugteam/obstacles/self-population.md
-line_number: 5
-rule_id: 5
-severity: P1
-what_is_wrong: "Spawn  — brief it: check  for an open PR  " contains double spaces where an agent invocation, repo, and PR number should be.
-what_it_should_be: Fill in the concrete Agent call or remove the section until populated.
-evidence_path: bugteam/obstacles/self-population.md
-evidence_detail: Template has placeholder spacing with no variable substitutions defined.
-```
-
-Why this matters: Obstacle files are reference material for agents. An obstacle with "Spawn — brief it: check for" and no target wastes context and confuses.