claude-dev-env 1.59.0 → 1.60.0

package/skills/_shared/pr-loop/scripts/test_preflight_worktree.py

@@ -0,0 +1,263 @@
+"""Tests for preflight_worktree against real git working trees."""
+
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_preflight() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "preflight_worktree.py"
+    spec = importlib.util.spec_from_file_location("preflight_worktree", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["preflight_worktree"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+preflight = _load_preflight()
+
+GIT_TIMEOUT = 30
+CLAUDE_REMOTE = "https://github.com/jl-cmd/claude-code-config.git"
+GIT_CEILING_DIRECTORIES = "GIT_CEILING_DIRECTORIES"
+
+
+@pytest.fixture(autouse=True)
+def _isolate_git_from_ancestor_repos(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(GIT_CEILING_DIRECTORIES, str(tmp_path))
+
+
+def _git(repo_dir: Path, *args: str) -> None:
+    subprocess.run(
+        ["git", "-C", str(repo_dir), *args],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT,
+    )
+
+
+def _init_repo(repo_dir: Path, origin_url: str | None) -> Path:
+    repo_dir.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["git", "init", "-q", str(repo_dir)],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_TIMEOUT,
+    )
+    if origin_url is not None:
+        _git(repo_dir, "remote", "add", "origin", origin_url)
+    return repo_dir
+
+
+@pytest.mark.parametrize(
+    ("remote_url", "expected_owner", "expected_repo"),
+    [
+        (
+            "https://github.com/jl-cmd/claude-code-config.git",
+            "jl-cmd",
+            "claude-code-config",
+        ),
+        (
+            "https://github.com/jl-cmd/claude-code-config",
+            "jl-cmd",
+            "claude-code-config",
+        ),
+        ("git@github.com:JonEcho/llm-settings.git", "jonecho", "llm-settings"),
+        (
+            "ssh://git@github.com/jl-cmd/Claude-Code-Config",
+            "jl-cmd",
+            "claude-code-config",
+        ),
+        ("https://github.com/jl-cmd/repo/", "jl-cmd", "repo"),
+    ],
+)
+def test_parse_repo_identity_accepts_every_github_remote_form(
+    remote_url: str, expected_owner: str, expected_repo: str
+) -> None:
+    identity = preflight.parse_repo_identity(remote_url)
+    assert identity is not None
+    assert identity.owner == expected_owner
+    assert identity.repo == expected_repo
+
+
+@pytest.mark.parametrize(
+    "remote_url",
+    ["https://gitlab.com/foo/bar.git", "", "not-a-url"],
+)
+def test_parse_repo_identity_rejects_non_github_remotes(remote_url: str) -> None:
+    assert preflight.parse_repo_identity(remote_url) is None
+
+
+def test_classify_same_repo_when_origin_matches_pr(tmp_path: Path) -> None:
+    repo_dir = _init_repo(tmp_path / "session", CLAUDE_REMOTE)
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    verdict = preflight.classify_environment(repo_dir, pr_identity)
+    assert verdict.outcome == preflight.OUTCOME_SAME_REPO
+    assert verdict.cwd_identity == pr_identity
+    assert verdict.has_healthy_worktree_machinery is True
+
+
+def test_classify_different_repo_when_origin_is_another_github_repo(
+    tmp_path: Path,
+) -> None:
+    repo_dir = _init_repo(
+        tmp_path / "session", "https://github.com/jonecho/llm-settings.git"
+    )
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    verdict = preflight.classify_environment(repo_dir, pr_identity)
+    assert verdict.outcome == preflight.OUTCOME_DIFFERENT_REPO
+    assert verdict.cwd_identity == preflight.RepoIdentity("jonecho", "llm-settings")
+
+
+def test_classify_different_repo_when_origin_is_non_github(tmp_path: Path) -> None:
+    repo_dir = _init_repo(tmp_path / "session", "https://gitlab.com/foo/bar.git")
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    verdict = preflight.classify_environment(repo_dir, pr_identity)
+    assert verdict.outcome == preflight.OUTCOME_DIFFERENT_REPO
+    assert verdict.cwd_identity is None
+
+
+def test_classify_re_rooted_when_origin_is_absent(tmp_path: Path) -> None:
+    repo_dir = _init_repo(tmp_path / "session", None)
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    verdict = preflight.classify_environment(repo_dir, pr_identity)
+    assert verdict.outcome == preflight.OUTCOME_RE_ROOTED
+
+
+def test_classify_re_rooted_when_directory_is_not_a_work_tree(
+    tmp_path: Path,
+) -> None:
+    plain_dir = tmp_path / "home"
+    plain_dir.mkdir()
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    verdict = preflight.classify_environment(plain_dir, pr_identity)
+    assert verdict.outcome == preflight.OUTCOME_RE_ROOTED
+    assert verdict.has_healthy_worktree_machinery is False
+
+
+@pytest.mark.parametrize(
+    ("outcome", "is_healthy", "mode", "expected_exit"),
+    [
+        ("same_repo", True, "strict", 0),
+        ("same_repo", True, "classify", 0),
+        ("same_repo", False, "strict", 1),
+        ("same_repo", False, "classify", 1),
+        ("different_repo", True, "strict", 1),
+        ("different_repo", True, "classify", 0),
+        ("re_rooted", False, "strict", 1),
+        ("re_rooted", False, "classify", 1),
+    ],
+)
+def test_decide_exit_code_matrix(
+    outcome: str, is_healthy: bool, mode: str, expected_exit: int
+) -> None:
+    verdict = preflight.PreflightVerdict(
+        outcome=outcome,
+        cwd_identity=None,
+        has_healthy_worktree_machinery=is_healthy,
+    )
+    assert preflight.decide_exit_code(verdict, mode) == expected_exit
+
+
+def test_build_report_lines_marks_outcome_and_routes_cross_repo() -> None:
+    verdict = preflight.PreflightVerdict(
+        outcome=preflight.OUTCOME_DIFFERENT_REPO,
+        cwd_identity=preflight.RepoIdentity("jonecho", "llm-settings"),
+        has_healthy_worktree_machinery=True,
+    )
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    classify_lines = preflight.build_report_lines(
+        verdict, "classify", Path("/tmp/x"), pr_identity
+    )
+    assert classify_lines[0] == "PREFLIGHT_OUTCOME=different_repo"
+    assert any("ROUTE" in line for line in classify_lines)
+    strict_lines = preflight.build_report_lines(
+        verdict, "strict", Path("/tmp/x"), pr_identity
+    )
+    assert any("ABORT" in line for line in strict_lines)
+
+
+def test_build_report_lines_aborts_on_broken_worktree_machinery() -> None:
+    verdict = preflight.PreflightVerdict(
+        outcome=preflight.OUTCOME_SAME_REPO,
+        cwd_identity=preflight.RepoIdentity("jl-cmd", "claude-code-config"),
+        has_healthy_worktree_machinery=False,
+    )
+    pr_identity = preflight.RepoIdentity("jl-cmd", "claude-code-config")
+    lines = preflight.build_report_lines(verdict, "strict", Path("/tmp/x"), pr_identity)
+    assert lines[0] == "PREFLIGHT_OUTCOME=same_repo"
+    assert any("git worktree prune" in line for line in lines)
+
+
+def test_main_strict_passes_in_matching_repo(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repo_dir = _init_repo(tmp_path / "session", CLAUDE_REMOTE)
+    monkeypatch.chdir(repo_dir)
+    exit_code = preflight.main(
+        ["--owner", "jl-cmd", "--repo", "claude-code-config", "--mode", "strict"]
+    )
+    captured = capsys.readouterr()
+    assert exit_code == preflight.EXIT_PREFLIGHT_OK
+    assert "PREFLIGHT_OUTCOME=same_repo" in captured.out
+
+
+def test_main_strict_aborts_when_session_rooted_in_other_repo(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repo_dir = _init_repo(
+        tmp_path / "session", "https://github.com/jonecho/llm-settings.git"
+    )
+    monkeypatch.chdir(repo_dir)
+    exit_code = preflight.main(
+        ["--owner", "jl-cmd", "--repo", "claude-code-config", "--mode", "strict"]
+    )
+    captured = capsys.readouterr()
+    assert exit_code == preflight.EXIT_PREFLIGHT_ABORT
+    assert "PREFLIGHT_OUTCOME=different_repo" in captured.out
+    assert "ABORT" in captured.out
+
+
+def test_main_classify_routes_cross_repo_without_abort(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repo_dir = _init_repo(
+        tmp_path / "session", "https://github.com/jonecho/llm-settings.git"
+    )
+    monkeypatch.chdir(repo_dir)
+    exit_code = preflight.main(
+        ["--owner", "jl-cmd", "--repo", "claude-code-config", "--mode", "classify"]
+    )
+    captured = capsys.readouterr()
+    assert exit_code == preflight.EXIT_PREFLIGHT_OK
+    assert "PREFLIGHT_OUTCOME=different_repo" in captured.out
+    assert "ROUTE" in captured.out
+
+
+def test_main_classify_aborts_when_re_rooted(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    plain_dir = tmp_path / "home"
+    plain_dir.mkdir()
+    monkeypatch.chdir(plain_dir)
+    exit_code = preflight.main(
+        ["--owner", "jl-cmd", "--repo", "claude-code-config", "--mode", "classify"]
+    )
+    captured = capsys.readouterr()
+    assert exit_code == preflight.EXIT_PREFLIGHT_ABORT
+    assert "PREFLIGHT_OUTCOME=re_rooted" in captured.out

package/skills/autoconverge/SKILL.md

@@ -43,7 +43,17 @@ PR's owner.
    ready, mark it draft first (`gh pr ready <n> --repo <o>/<r> --undo`) so the
    loop owns the ready transition.
 
-3. **Grant project permissions.**
+3. **Verify the worktree is the PR's repo (strict pre-flight).** Run
+   `python "$HOME/.claude/skills/_shared/pr-loop/scripts/preflight_worktree.py" --owner <owner> --repo <repo> --mode strict`.
+   It confirms the working directory is a checkout of the PR's own repo and
+   that `git worktree` machinery is healthy, so `EnterWorktree` can create and
+   enter the branch worktree. A non-zero exit prints a `PREFLIGHT_OUTCOME` line
+   and an `ABORT` line: report that line and stop. Autoconverge runs inside the
+   PR's own repo, so a working directory rooted in a different repo (for
+   example, `claude-code-config` while the PR lives in `llm-settings`) or in no
+   git checkout at all cannot continue.
+
+4. **Grant project permissions.**
    `python "$HOME/.claude/skills/bugteam/scripts/grant_project_claude_permissions.py"`
 
 ## Run the workflow
@@ -87,23 +97,44 @@ round records nothing resumable and replays dirty.
    here; this step builds the one-shot closing report and the seam (marker comment +
    gist URL) a future live-dashboard reuses.
 
-   a. **Resolve the journal path.** Glob
+   a. **Resolve a seed journal path.** Glob
       `~/.claude/projects/**/workflows/wf_<runId>.json` (where `runId` is the run id
-      the `Workflow` result returned) and take the match.
+      the `Workflow` result returned) and take the match. It seeds the merge, which
+      finds every other autoconverge journal for the same PR.
 
-   b. **Build the report.**
+   b. **Merge the PR's runs and build the summary prompt.**
+      ```
+      python "<skill>/workflow/aggregate_runs.py" \
+        --journal "<seed journal>" \
+        --pr <owner>/<repo>#<n> \
+        --work-dir "$CLAUDE_JOB_DIR/tmp/autoconverge-agg-<prNumber>" \
+        --out-prompt "$CLAUDE_JOB_DIR/tmp/autoconverge-summary-prompt-<prNumber>.txt" \
+        [--standards-note "<standardsNote>"] [--copilot-note "<copilotNote>"]
+      ```
+      It prints a JSON line with `combinedJournal`, `roundCount`, `finalSha`, and
+      `findingCount`. Pass `--standards-note`/`--copilot-note` only when the workflow
+      returned those notes.
+
+   c. **Write the summary.** Spawn a `convergence-summary` agent (a `general-purpose`
+      subagent) on the text of the prompt file from step b. The agent answers with the
+      `prProblem`/`prFix`/`problemScenes`/`fixScenes`/`verdictLine`/`issueClasses` JSON
+      object; write that object to
+      `$CLAUDE_JOB_DIR/tmp/autoconverge-summary-<prNumber>.json`.
+
+   d. **Build the report.**
       ```
       python "<skill>/workflow/render_report.py" \
-        --journal "<journal>" \
+        --journal "<combinedJournal>" \
+        --summary-file "<summary json>" \
         --out "$CLAUDE_JOB_DIR/tmp/autoconverge-report-<prNumber>.html" \
         --pr <owner>/<repo>#<n> \
         --final-sha <finalSha> \
-        --rounds <rounds> \
-        --repo <worktree>
+        --rounds <roundCount>
       ```
-      Capture the output path from stdout.
+      Use the `combinedJournal`, `finalSha`, and `roundCount` from step b. Capture the
+      output path from stdout.
 
-   c. **Publish as a secret gist** by reusing `doc-gist` (do not reimplement gist
+   e. **Publish as a secret gist** by reusing `doc-gist` (do not reimplement gist
       creation):
       ```
       python "$HOME/.claude/skills/doc-gist/scripts/gist_upload.py" \
@@ -114,17 +145,21 @@ round records nothing resumable and replays dirty.
       Capture the htmlpreview URL from stdout. The gist is secret by default; pass
       no public flag.
 
-   d. **Post one idempotent PR comment.** List the PR's issue comments; if one
+   f. **Post one idempotent PR comment.** List the PR's issue comments; if one
       carries the marker `<!-- autoconverge-report -->`, edit it in place, otherwise
       create a new one. The body begins with `<!-- autoconverge-report -->`, then
-      the htmlpreview link, headline counts (findings by severity, rounds, tests
-      added), and the full finding list as `file:line — P# — title` grouped by
-      severity. Honor the gh-body-file rule: write a BOM-free temp file and pass
-      `--body-file` to `gh issue comment`/`gh issue comment edit`, or use the
+      the htmlpreview link, then a plain-language summary that mirrors the report:
+      lead with the one-sentence `verdictLine`; then the plain Problem and Fix
+      sentences (`prProblem`, `prFix`); then the issue-class list — one bullet per
+      class as `plainName (×count, status)`. Place the raw finding list as
+      `file:line — P# — title` inside a collapsed
+      `<details><summary>Raw findings</summary>…</details>` block so the comment leads
+      with the human summary. Honor the gh-body-file rule: write a BOM-free temp file
+      and pass `--body-file` to `gh issue comment`/`gh issue comment edit`, or use the
       GitHub MCP `add_issue_comment` tool (body as a structured parameter, no
       `--body` flag).
 
-   e. **Open the report in Chrome.**
+   g. **Open the report in Chrome.**
       ```
       Start-Process chrome -ArgumentList '--new-window', '<report path>'
       ```
@@ -187,6 +222,8 @@ suite (`python -m pytest`) and keep scratch work in ephemeral temp dirs.
 
 - `SKILL.md` — this hub.
 - `workflow/converge.mjs` — the convergence workflow script.
-- `workflow/render_report.py` — builds the closing convergence insights HTML report.
-- `workflow/autoconverge_report_constants/` — named constants for the report builder.
+- `workflow/aggregate_runs.py` — merges every autoconverge journal for a PR into one journal and returns its deduped findings, fix summaries, round count, and final SHA.
+- `workflow/convergence_summary.py` — builds the convergence-summary agent prompt over a PR's merged findings.
+- `workflow/render_report.py` — builds the closing convergence insights HTML report, taking the summary from `--summary-file`.
+- `workflow/autoconverge_report_constants/` — named constants for the report builder and the summary prompt.
 - `reference/` — convergence definition, stop conditions, gotchas, closing report.

package/skills/autoconverge/reference/closing-report.md

@@ -4,35 +4,77 @@ When an autoconverge run converges (the workflow returns `converged: true`), the
 
 ## Data source
 
-The report reads two file types written by the workflow during the run:
+A PR's full convergence is the union of every autoconverge run it took. `aggregate_runs.py` finds all of them and merges them into one run tree the report reads:
 
-- **Run journal** — `~/.claude/projects/**/workflows/wf_<runId>.json` — the PR args, round log lines, `workflowProgress` array (one entry per agent step), and the final result.
-- **Agent transcripts** — `~/.claude/projects/**/subagents/workflows/<runId>/agent-<agentId>.jsonl` — one file per agent; each line is a JSON object; the renderer extracts the last `StructuredOutput` tool_use from each file.
+- **Run journals** — `~/.claude/projects/**/workflows/wf_<runId>.json` — each carries the PR args, round log lines, a `workflowProgress` array (one entry per agent step), and the run result. `aggregate_runs.py` picks every journal whose `args` owner/repo/prNumber match the PR and whose `workflowName` is `autoconverge`, orders them by timestamp, and concatenates their `workflowProgress` into one merged journal under the work directory.
+- **Agent transcripts** — `~/.claude/projects/**/subagents/workflows/<runId>/agent-<agentId>.jsonl` — one file per agent; each line is a JSON object. The merge copies every referenced transcript into the merged run tree, so the report reader extracts the last `StructuredOutput` tool_use from each exactly as it would for a single run.
 
-`converge.mjs` is not modified. The report is a pure reader of files the workflow already writes.
+The merged journal's round count is the number of `resolve-head` steps across every run, and its final SHA is the latest run's result SHA.
 
-## Building the report
+## Convergence summary
+
+The plain-language account of what the PR does and what the run caught is written at teardown, over the merged findings. `convergence_summary.py` builds the agent prompt from the deduped findings and the per-round fix summaries `aggregate_runs.py` returns; the teardown spawns a `convergence-summary` agent on that prompt; the agent's JSON answer is the summary. `render_report.py --summary-file <path>` reads that JSON and draws from it, so the summary needs no journal transcript of its own.
+
+The summary carries the structured visual data the report draws:
+
+- `prProblem` and `prFix` — one plain sentence each: the problem this PR solves and the change that solves it.
+- `problemScenes` and `fixScenes` — short cause→effect scenes. Each scene has a `trigger`, an optional `condition`, a `result`, and a one-line `caption`. A fix scene mirrors a problem scene with a good result.
+- `verdictLine` — one factual sentence: converged, the distinct issue-class count, all fixed or deferred.
+- `issueClasses` — one entry per distinct kind of problem, each with a `plainName`, a `count`, a `severity`, a `category`, a `status`, a plain `cause`, a `medium` (`terminal`, `code`, or `text`) that tells the report how to draw the before/after panels, and the literal `beforeLines` and `afterLines` shown in those panels. There is one class per kind, however many kinds there are — kinds are never folded together or dropped to hit a number.
+
+Python owns the counts, severity, and file:line; the summary agent owns the plain-language narrative. The report draws the same HTML each time it runs over the same merged journal and summary.
 
-```
-python "<skill>/workflow/render_report.py" \
-  --journal "<journal path>" \
-  --out "<output path>.html" \
-  --pr <owner>/<repo>#<n> \
-  --final-sha <sha> \
-  --rounds <N> \
-  --repo <worktree path>
-```
+## What the report draws
 
-The script reads the journal and transcripts, computes aggregated metrics (findings by severity, round, and theme; fix commits; tests added per round), and writes a self-contained HTML report. It prints the output path to stdout and exits 0 on success.
+The report body, in order:
+
+1. A title and a subtitle (owner/repo, component when it can be derived, finding count over round count, date).
+2. A **verdict banner** — a check circle, the `verdictLine`, and a Python-computed line giving the fix-commit count and the final short SHA.
+3. **What this PR does** — a problem card and a fix card. Each card draws its scenes as a trigger chip → optional condition → result, each with its caption. When a scene list is empty, the card falls back to drawing `prProblem` or `prFix` as a single caption line.
+4. **What was caught — and how it looked** — a lead line stating the bug-class count, the total finding count, the round count, and the fix-commit count, then one block per issue class: a name heading with a finding-count chip, a before panel and an after panel drawn in the style its `medium` names (a dark terminal window, a light code panel, or plain lines), and a cause line that states the plain cause plus a muted note with severity, category, count, and status. When both line lists are empty, the block drops to its heading and cause line.
+5. A footer (owner/repo, PR, findings, rounds, fix commits, generated date).
+
+A collapsed `<details>` raw-findings appendix (`file:line — P# — title`) closes the body and keeps the engineer grounding one click away.
+
+When the summary is absent, the report falls back to a minimal layout: the title, the subtitle, a plain run-stats note, and the collapsed raw-findings appendix.
+
+## Building the report
 
-All aggregation is deterministic: `generated_date` comes from the journal `timestamp`, not the system clock, so the same inputs always produce the same HTML.
+Three steps run at teardown, each a separate process:
+
+1. **Merge the runs and build the summary prompt.**
+   ```
+   python "<skill>/workflow/aggregate_runs.py" \
+     --journal "<seed journal path>" \
+     --pr <owner>/<repo>#<n> \
+     --work-dir "<work dir>" \
+     --out-prompt "<prompt path>.txt" \
+     [--standards-note "<note>"] [--copilot-note "<note>"]
+   ```
+   `--journal` is any one of the PR's journals — the seed that locates the rest. The script prints a JSON line carrying `combinedJournal`, `roundCount`, `finalSha`, and `findingCount`.
+
+2. **Write the summary.** Spawn a `convergence-summary` agent on the prompt file's text. Its JSON answer — the `prProblem`/`prFix`/`problemScenes`/`fixScenes`/`verdictLine`/`issueClasses` object — goes to a `.json` file.
+
+3. **Draw the report.**
+   ```
+   python "<skill>/workflow/render_report.py" \
+     --journal "<combinedJournal>" \
+     --summary-file "<summary json path>" \
+     --out "<output path>.html" \
+     --pr <owner>/<repo>#<n> \
+     --final-sha <finalSha> \
+     --rounds <roundCount>
+   ```
+   The script reads the merged journal and transcripts, counts findings by severity and fix commits, takes the summary from `--summary-file`, draws the visual report, and writes a self-contained HTML file. It prints the output path to stdout and exits 0 on success.
+
+Counting is deterministic: `generated_date` comes from the journal `timestamp`, not the system clock, so the same merged journal and summary always produce the same HTML.
 
 ## Publishing
 
 After rendering, the main session:
 
 1. **Uploads the HTML as a secret gist** using `doc-gist/scripts/gist_upload.py --no-open`. Captures the htmlpreview URL from stdout.
-2. **Posts one idempotent PR comment** marked with `<!-- autoconverge-report -->`. If a comment with that marker already exists on the PR, it is edited in place; otherwise a new comment is created. The comment body has the gist URL and a summary of findings by severity, rounds, and tests added, followed by the full finding list grouped by severity (`file:line — P# — title`). Write the body to a BOM-free temp file and pass `--body-file` to `gh issue comment` (never `--body`), or use the GitHub MCP `add_issue_comment` tool.
+2. **Posts one idempotent PR comment** marked with `<!-- autoconverge-report -->`. If a comment with that marker already exists on the PR, it is edited in place; otherwise a new comment is created. The body leads with the gist URL, then the one-sentence `verdictLine`, then the plain Problem and Fix sentences (`prProblem`, `prFix`), then the issue-class list — one bullet per class as `plainName (×count, status)` — and closes with the full finding list (`file:line — P# — title`) inside a collapsed `<details>` block. Write the body to a BOM-free temp file and pass `--body-file` to `gh issue comment` (never `--body`), or use the GitHub MCP `add_issue_comment` tool.
 3. **Opens the report** with `Start-Process chrome -ArgumentList '--new-window', '<report path>'`. A missing Chrome does not abort teardown.
 
 ## Live-dashboard seam