claude-dev-env 1.38.0 → 1.39.0

package/skills/doc-gist/references/examples/README.md

@@ -0,0 +1,5 @@
+The example files in this directory are verbatim copies of Thariq Shihipar's [html-effectiveness](https://thariqs.github.io/html-effectiveness/) prototypes, used with permission as reference material for the doc-gist skill's artifact design gallery.
+
+Each file demonstrates a distinct HTML artifact shape — annotated PR diff, design system swatches, incident timeline, slide deck, prompt tuner — and serves as learning material for fresh per-request HTML design. The gallery teaches what shapes work; the agent adapts per request rather than copying.
+
+See [SKILL.md](../../SKILL.md) for the full gallery-to-artifact-type mapping.

package/skills/doc-gist/scripts/config/gist_upload_constants.py

@@ -0,0 +1,16 @@
+"""Constants for the gist_upload utility.
+
+GIST_HOST_PREFIX: anchor for parsing gh's emitted gist URL into user + id.
+PREVIEW_URL_TEMPLATE: the htmlpreview.github.io shape that renders a raw gist file.
+GIST_DEFAULT_FILENAME: filename used when input is stdin (no filename to inherit).
+MINIMUM_GIST_URL_PARTS: gh's gist URL is /<user>/<id>; need at least these many segments.
+"""
+
+GIST_HOST_PREFIX = "https://gist.github.com/"
+PREVIEW_URL_TEMPLATE = (
+    "https://htmlpreview.github.io/?https://gist.githubusercontent.com/"
+    "{user}/{gist_id}/raw/{filename}"
+)
+GIST_DEFAULT_FILENAME = "doc.html"
+MINIMUM_GIST_URL_PARTS = 2
+UPLOAD_TIMEOUT_SECONDS = 45

package/skills/doc-gist/scripts/gist_upload.py

@@ -0,0 +1,177 @@
+"""Upload an HTML file as a secret GitHub gist and emit the htmlpreview URL.
+
+Single-purpose transport. Takes HTML on stdin or via `--input <path>`, runs
+`gh gist create` (secret by default), parses the gist URL from gh's output,
+composes the htmlpreview.github.io preview URL, optionally opens it in the
+default browser, and prints both URLs.
+
+Designed to compose with anything that produces HTML — pipe in the output of
+a script, the contents of a hand-authored file, or have the auto-publish
+hook invoke it on a file Claude just wrote. The script does not opine on
+HTML shape, structure, or styling.
+
+Usage:
+    gist_upload.py --input <path>
+    gist_upload.py --input - --filename writeup.html < some.html
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import webbrowser
+from pathlib import Path
+from urllib.parse import quote
+
+_script_directory = str(Path(__file__).resolve().parent)
+if _script_directory not in sys.path:
+    sys.path.insert(0, _script_directory)
+
+from config.gist_upload_constants import (  # noqa: E402
+    GIST_DEFAULT_FILENAME,
+    GIST_HOST_PREFIX,
+    MINIMUM_GIST_URL_PARTS,
+    PREVIEW_URL_TEMPLATE,
+    UPLOAD_TIMEOUT_SECONDS,
+)
+
+
+def _read_html(input_argument: str) -> str:
+    """Read HTML content from stdin (when input is '-') or a file path.
+
+    Reads the full stdin stream when input_argument is '-'. Callers piping
+    content through an external process should ensure bounded input.
+    """
+    if input_argument == "-":
+        return sys.stdin.read()
+    try:
+        return Path(input_argument).expanduser().resolve().read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise SystemExit(f"Cannot read {input_argument}: {error}")
+
+
+def _resolve_filename(input_argument: str, override: str | None) -> str:
+    """Pick the filename gh will use for the gist file."""
+    default_filename = GIST_DEFAULT_FILENAME
+    if override:
+        return Path(override).name
+    if input_argument != "-":
+        return Path(input_argument).name
+    return default_filename
+
+
+def _write_to_temp(html_text: str, filename: str, parent_directory: Path) -> Path:
+    """Write HTML to a temp file inside parent_directory with the given filename."""
+    target_path = parent_directory / filename
+    target_path.write_text(html_text, encoding="utf-8")
+    return target_path
+
+
+def _create_secret_gist(html_path: Path, description: str) -> str:
+    """Run `gh gist create` against html_path and return the gist URL."""
+    try:
+        completed = subprocess.run(
+            ["gh", "gist", "create", str(html_path), "--desc", description],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=UPLOAD_TIMEOUT_SECONDS,
+        )
+    except FileNotFoundError:
+        raise SystemExit(
+            "gh CLI not found. Install GitHub CLI (https://cli.github.com) and run `gh auth login`."
+        )
+    except subprocess.TimeoutExpired:
+        raise SystemExit(
+            f"gh gist create timed out after {UPLOAD_TIMEOUT_SECONDS}s. Check network and retry."
+        )
+    if completed.returncode != 0:
+        message_text = completed.stderr.strip() or completed.stdout.strip()
+        raise SystemExit(
+            f"gh gist create failed:\n{message_text}\nRun `gh auth login` and retry."
+        )
+    output_lines = completed.stdout.strip().splitlines()
+    if not output_lines:
+        raise SystemExit("gh gist create produced no output.")
+    last_line = output_lines[-1].strip()
+    if not last_line.startswith(GIST_HOST_PREFIX):
+        raise SystemExit(f"Unexpected gh gist create output: {last_line!r}")
+    return last_line
+
+
+def _compose_preview_url(gist_url: str, filename: str) -> str:
+    """Build the htmlpreview.github.io URL from the gist URL and the gist filename."""
+    minimum_parts = MINIMUM_GIST_URL_PARTS
+    preview_template = PREVIEW_URL_TEMPLATE
+    path_after_host = gist_url[len(GIST_HOST_PREFIX) :]
+    parts = path_after_host.split("/")
+    if len(parts) < minimum_parts:
+        raise SystemExit(f"Cannot parse gist URL: {gist_url!r}")
+    return preview_template.format(user=parts[0], gist_id=parts[1], filename=quote(filename, safe=""))
+
+
+def _open_in_browser(url: str) -> None:
+    """Open the URL in the default browser, deferring to OS-native behavior on Windows."""
+    if sys.platform.startswith("win"):
+        os.startfile(url)
+        return
+    webbrowser.open(url)
+
+
+def main() -> int:
+    """Entry point — read HTML, upload as secret gist, print URLs, open preview.
+
+    Returns:
+        Process exit code (0 on success).
+    """
+    parser = argparse.ArgumentParser(
+        description="Upload HTML as a secret gist; print gist + htmlpreview URLs."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to an .html file, or '-' for stdin.",
+    )
+    parser.add_argument(
+        "--filename",
+        default=None,
+        help="Filename inside the gist. Defaults to the input filename, or 'doc.html' for stdin.",
+    )
+    parser.add_argument(
+        "--description",
+        default="HTML artifact",
+        help="Gist description.",
+    )
+    parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Skip opening the preview URL in the default browser.",
+    )
+    arguments = parser.parse_args()
+
+    html_text = _read_html(arguments.input)
+    filename = _resolve_filename(arguments.input, arguments.filename)
+
+    with tempfile.TemporaryDirectory(prefix="gist-upload-") as temp_directory:
+        upload_path = _write_to_temp(html_text, filename, Path(temp_directory))
+        gist_url = _create_secret_gist(upload_path, arguments.description)
+        preview_url = _compose_preview_url(gist_url, filename)
+
+    print(f"Gist: {gist_url}", file=sys.stderr)
+    print(f"Preview: {preview_url}", file=sys.stderr)
+
+    if not arguments.no_open:
+        _open_in_browser(preview_url)
+        print("Opened preview in default browser.", file=sys.stderr)
+
+    print(preview_url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/doc-gist/scripts/test_gist_upload.py

@@ -0,0 +1,51 @@
+"""Tests for gist_upload.py pure functions — URL composition and filename resolution."""
+
+from pathlib import Path
+import sys
+
+_script_directory = str(Path(__file__).resolve().parent)
+if _script_directory not in sys.path:
+    sys.path.insert(0, _script_directory)
+
+from gist_upload import _compose_preview_url, _resolve_filename
+
+
+class TestResolveFilename:
+    def test_uses_override_when_provided(self):
+        assert (
+            _resolve_filename("report.html", "custom-name.html") == "custom-name.html"
+        )
+
+    def test_strips_directory_from_override(self):
+        assert (
+            _resolve_filename("report.html", "/some/path/override.html")
+            == "override.html"
+        )
+
+    def test_uses_input_filename_when_no_override(self):
+        assert _resolve_filename("report.html", None) == "report.html"
+
+    def test_uses_default_for_stdin_without_override(self):
+        assert _resolve_filename("-", None) == "doc.html"
+
+    def test_override_takes_precedence_over_stdin(self):
+        assert _resolve_filename("-", "writeup.html") == "writeup.html"
+
+
+class TestComposePreviewUrl:
+    def test_standard_gist_url(self):
+        result = _compose_preview_url(
+            "https://gist.github.com/user123/abc123def456",
+            "report.html",
+        )
+        assert result == (
+            "https://htmlpreview.github.io/"
+            "?https://gist.githubusercontent.com/user123/abc123def456/raw/report.html"
+        )
+
+    def test_filename_with_spaces_is_encoded(self):
+        result = _compose_preview_url(
+            "https://gist.github.com/user123/abc123def456",
+            "my report.html",
+        )
+        assert "my%20report.html" in result

package/skills/findbugs/SKILL.md

@@ -112,7 +112,73 @@ The XML prompt skeleton:
 </output_format>
 ```
 
-### Step 4: Surface findings, then clean up
+### Step 4: Post the audit review
+
+Every `/findbugs` invocation posts one audit review back to the PR. The
+unresolved-thread gate counts review threads, so a findbugs pass that
+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 precondition.** GitHub rejects both `APPROVE` and
+`REQUEST_CHANGES` reviews when the authenticated identity matches the
+PR author with HTTP 422; `post_audit_thread.py` retries and then exits 2.
+To run findbugs on a PR you authored, switch `gh auth` to an alternate
+reviewer identity (a separate GitHub account) BEFORE invoking the skill.
+Without this switch, exit 2 is a hard halt — there is no automated
+fallback path. The script does not auto-downgrade on the self-PR case.
+
+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.
+
+### Step 5: Surface findings, then clean up
 
 When the agent returns, report concisely:
 
@@ -148,7 +214,7 @@ Want me to run /fixbugs for the P0/P1 findings?
 
 ## Constraints
 
-- **Read-only.** The skill never edits code, never pushes, never commits.
+- **Read-only on code.** The skill never edits files, never pushes, never commits. One audit review per invocation gets posted back to the PR (Step 4) — that is the only side effect, and it is required so the unresolved-thread gate sees the audit pass.
 - **Foreground spawn.** The user is waiting for the result on this turn.
 - **PR-scoped, not session-scoped.** The audit covers the entire PR diff regardless of which files were edited in this conversation.
 - **Clean-room prompt.** The agent's prompt is self-contained — no references to chat history, no anchoring hints, no expected outcomes.

package/skills/monitor-open-prs/SKILL.md

@@ -2,24 +2,22 @@
 name: monitor-open-prs
 description: >-
   Discover every open pull request across the jl-cmd/* and JonEcho/*
-  owner scopes, spawn /bugteam on each in parallel with the Groq-backed
-  FIX implementer (BUGTEAM_FIX_IMPLEMENTER=groq-coder) and the bugbot
-  re-trigger flag (--bugbot-retrigger), wrap the session in `bws run`
-  to inject GROQ_API_KEY, and poll Cursor's bugbot replies after
-  convergence so any post-Groq findings loop back through /bugteam.
-  Triggers: '/monitor-open-prs', 'sweep the open PRs', 'groq-bugteam the backlog'.
+  owner scopes, spawn /bugteam on each in parallel with the bugbot
+  re-trigger flag (--bugbot-retrigger), and poll Cursor's bugbot replies
+  after convergence so any post-bugteam findings loop back through
+  /bugteam. Triggers: '/monitor-open-prs', 'sweep the open PRs',
+  'audit the open PR backlog'.
 ---
 
 # Monitor Open PRs
 
-**Core principle:** One sweep covers every open PR across both owner scopes. Claude discovers PRs live via `scripts/discover_open_prs.py` which shells out to `gh search prs --owner <owner> --state open --json ...`, dispatches `/bugteam` per PR with `BUGTEAM_FIX_IMPLEMENTER=groq-coder` and `--bugbot-retrigger`, then polls Cursor's bugbot replies until each PR is quiet for a full backoff cycle.
+**Core principle:** One sweep covers every open PR across both owner scopes. Claude discovers PRs live via `scripts/discover_open_prs.py` which shells out to `gh search prs --owner <owner> --state open --json ...`, dispatches `/bugteam --bugbot-retrigger` per PR, then polls Cursor's bugbot replies until each PR is quiet for a full backoff cycle.
 
 ## Contents
 
 - When this skill applies — refusal cases and trigger conditions
 - Discovery — `scripts/discover_open_prs.py` queries via `gh search prs` across both owner scopes
-- Wrapping — `bws run` for GROQ_API_KEY injection
-- Dispatch — `/bugteam --bugbot-retrigger <pr_numbers...>` with groq-coder + retrigger
+- Dispatch — `/bugteam --bugbot-retrigger <pr_numbers...>`
 - Post-convergence polling — bugbot replies and re-invocation
 - `scripts/discover_open_prs.py` — the discovery helper
 
@@ -29,37 +27,22 @@ description: >-
 
 Refusals — first match wins; respond with the quoted line exactly and stop:
 
-- **bws not on PATH.** `bws not installed. /monitor-open-prs injects GROQ_API_KEY via Bitwarden Secrets Manager.`
 - **GitHub API not accessible.** `get_me failed. /monitor-open-prs needs active GitHub MCP credentials.`
 - **Dirty tree on the caller's repo.** `Uncommitted changes detected. Stash, commit, or revert before /monitor-open-prs.`
-- **Required subagents missing.** Confirm `code-quality-agent`, `clean-coder`, and `groq-coder` exist. Else: `Required subagent type <name> not installed.`
+- **Required subagents missing.** Confirm `code-quality-agent` and `clean-coder` exist. Else: `Required subagent type <name> not installed.`
 
 ## Discovery
 
 Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to merge the live open-PR list across both scopes. The helper shells out to `gh search prs --owner <owner> --state open --json number,repository,url,headRefName,baseRefName` for each owner scope and flattens the result to a uniform dict shape with keys `number`, `owner`, `repo`, `head_ref`, `base_ref`, `url`. Empty scopes contribute empty lists; an entirely empty sweep returns `[]` and exits cleanly.
 
-## Secret Wrapping
-
-Every `/bugteam` dispatch runs inside `bws run` so `GROQ_API_KEY` is injected from Bitwarden Secrets Manager without touching the filesystem. The project and secret UUIDs are fixed for this skill:
-
-```bash
-bws run \
-  --project-id c69cedc5-aea1-4aa8-b350-b4300145d978 \
-  -- \
-  env BUGTEAM_FIX_IMPLEMENTER=groq-coder \
-  /bugteam --bugbot-retrigger <pr_numbers...>
-```
-
-The `bws run` subshell resolves the project's secrets and exports them for the wrapped command. The `GROQ_API_KEY` secret's UUID inside that project is `b7e99a7f-2ecc-42b3-99a5-b434010622f9`. GitHub auth is not sourced through `bws` — existing MCP `get_me` credentials carry the session.
-
 ## Dispatch
 
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>` under the `bws run` wrapper from §Secret Wrapping.
-3. The `BUGTEAM_FIX_IMPLEMENTER=groq-coder` env var routes the FIX role to the `groq-coder` subagent. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
-4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
+2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`.
+3. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
+4. Bugteam runs its own 20-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 
 **Fan-out (optional):** when the discovered list has more than one PR, the skill may spawn `/bugteam` dispatches in parallel by issuing multiple `Agent` calls in a single assistant message. Each dispatch operates in its own per-PR worktree (bugteam Step 1.1). Serialize when the caller sets an explicit `--serial` flag.
 
@@ -70,7 +53,7 @@ After a `/bugteam` invocation returns (converged, cap reached, stuck, or error),
 1. Baseline: capture `since_timestamp` as the PR's last commit timestamp.
 2. Every 60 seconds, call `pull_request_read(method="get", pullNumber=<pr_number>, owner=<owner>, repo=<repo>)` and filter the response's `comments` array for entries whose `.author.login` matches `"bugbot"` or `"cursor"` and `.createdAt` is after `<since_timestamp>`.
 3. Back off: 60s → 120s → 240s → 480s → 960s. If five successive polls return empty, exit polling for this PR.
-4. If bugbot posts a new finding in any poll, re-invoke `/bugteam <pr_number>` via the same `bws run` wrapper with the bugbot finding text seeded into the invocation's `bugs_to_fix` preamble. Reset the backoff.
+4. If bugbot posts a new finding in any poll, re-invoke `/bugteam <pr_number>` with the bugbot finding text seeded into the invocation's `bugs_to_fix` preamble. Reset the backoff.
 
 ### Polling Cost and Cadence
 
@@ -86,16 +69,14 @@ PRs discovered: <N>
   jl-cmd/*: <count>
   JonEcho/*: <count>
 PRs converged clean: <count>
-PRs hit 10-loop cap: <count>
+PRs hit 20-loop cap: <count>
 PRs stuck: <count>
 PRs errored: <count>
 Bugbot re-triggers fired: <count>
-Total Groq tokens consumed: <approx from /bugteam outcome summaries>
 ```
 
 ## Non-Negotiable Guardrails
 
-- Never source secrets outside `bws run` — no `.env` files, no shell history, no logs.
 - Never pass `--no-verify` or `--no-gpg-sign` to git in any dispatched bugteam run.
 - Never open a PR from this skill; only comment on existing ones.
 - Never merge or close PRs; the skill is read + audit + patch only.

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

@@ -16,12 +16,6 @@ def test_skill_has_frontmatter_name():
     assert "name: monitor-open-prs" in skill_text
 
 
-def test_skill_invokes_bugteam_with_groq_implementer():
-    skill_text = _read_skill_text()
-    assert "BUGTEAM_FIX_IMPLEMENTER" in skill_text
-    assert "groq-coder" in skill_text
-
-
 def test_skill_references_bugbot_retrigger_flag():
     skill_text = _read_skill_text()
     assert "--bugbot-retrigger" in skill_text
@@ -31,8 +25,3 @@ def test_skill_enumerates_both_owner_scopes():
     skill_text = _read_skill_text()
     assert "jl-cmd" in skill_text
     assert "JonEcho" in skill_text
-
-
-def test_skill_documents_bws_wrapping():
-    skill_text = _read_skill_text()
-    assert "bws run" in skill_text

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

@@ -0,0 +1,112 @@
+---
+name: pr-consistency-audit
+description: >-
+  Audits a PR for cross-file inconsistencies. Finds wrong argument names, missing required args, references to files or scripts that do not exist, stale feature remnants, docstring-vs-implementation mismatches, placeholder text, cross-file contradictions, parameter naming convention violations, and cross-platform bugs. Use when the user says "audit this PR", "find inconsistencies", "cross-reference docs against scripts", "check for stale references", "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.