claude-dev-env 1.83.0 → 1.84.0

package/skills/qbug/SKILL.md

@@ -3,7 +3,7 @@ name: qbug
 description: >-
   Required baseline review for every new PR. Runs the /bugteam audit → fix →
   commit → push cycle via one clean-coder subagent (not a full team), looping
-  until convergence or stuck. Uses the same CODE_RULES gate, A–N category
+  until convergence or stuck. Uses the same CODE_RULES gate, A–P category
   rubric, and per-loop PR review shape as /bugteam — without TeamCreate,
   teammates, per-loop clean-room, or a loop cap. Invoke /bugteam instead for
   larger PRs that need per-loop bias isolation or a hard loop cap. Triggers:
@@ -21,8 +21,8 @@ Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE
 
 - Pre-flight script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/preflight.py`
 - Code-rules gate script: `${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/code_rules_gate.py`
-- Bug category rubric A–N: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
-- **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`bugteam/reference/audit-contract.md`](../bugteam/reference/audit-contract.md)
+- Bug category rubric A–P: [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md#audit-spawn-prompt-xml-bugfind-teammate)
+- **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`_shared/pr-loop/audit-contract.md`](../../_shared/pr-loop/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#audit-posting)
 
 ## When this skill applies
@@ -31,12 +31,15 @@ Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE
 
 Refusals — first match wins; respond with the quoted line exactly and stop:
 
-- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` contains the
-  token `bugteam` (comma-separated, case-insensitive, whitespace-tolerant):
-  `/qbug is disabled via CLAUDE_REVIEWS_DISABLED.` `/qbug` is the bugteam
+- **Disabled via environment.** When `CLAUDE_REVIEWS_DISABLED` carries the
+  token `bugteam`:
+  `/qbug is disabled via CLAUDE_REVIEWS_DISABLED.` Run the check via
+  `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugteam`
+  (exit 0 = disabled). `/qbug` is the bugteam
   baseline review and shares the `bugteam` token with `/bugteam`; the shared
   pre-flight script also exits 7 in this case so any caller invoking it
-  directly halts on the same signal.
+  directly halts on the same signal. The gate semantics live in the
+  `reviewer-gates` skill (`../reviewer-gates/SKILL.md`).
 - **No PR or upstream diff.** `No PR or upstream diff. /qbug needs a target.`
 - **Dirty tree.** `Uncommitted changes detected. Stash, commit, or revert before /qbug.`
 - **Missing subagent.** Before Step 2, confirm `clean-coder` exists. Else: `Required subagent type clean-coder not installed. /qbug needs clean-coder available.`
@@ -72,9 +75,7 @@ Pre-flight checks (in order):
 
 ## Step 1: Resolve PR scope (lead)
 
-1. Call `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` via the lead's available MCP tools (`N` comes from the parent skill's PR context, or fall back to `search_issues` MCP with the current branch name to recover the PR number). Extract `number`, `baseRefName`, `headRefName`, `url` from the response.
-2. Else `git merge-base HEAD origin/<default>` then `git diff <merge-base>...HEAD`
-3. Else refuse per § When this skill applies.
+Apply the `pr-scope-resolve` skill (`../pr-scope-resolve/SKILL.md`) with caller `qbug`. When no target exists, refuse per § When this skill applies with the sub-skill's canonical line.
 
 Capture: `owner/repo`, `baseRefName`, `headRefName`, PR `number`, `url`, `starting_sha = git rev-parse HEAD`.
 
@@ -116,7 +117,7 @@ Agent(
   subagent_type="code-quality-agent",
   model="haiku",
   description="qbug Haiku secondary audit for PR <number>",
-  prompt="<audit-only prompt: read the PR diff, apply A-N categories from <categories_file>, return structured findings. No FIX, no git add, no git commit, no git push.>",
+  prompt="<audit-only prompt: read the PR diff, apply A–P categories from <categories_file>, return structured findings. No FIX, no git add, no git commit, no git push.>",
   run_in_background=False
 )
 ```
@@ -187,11 +188,12 @@ The subagent receives this prompt and loops internally — the lead does not re-
 
        - Read the patch file.
        - Audit only added/modified lines. Read <categories_file> for the
-         A–N category definitions; investigate each category explicitly.
+         A–P category definitions; investigate each category explicitly.
        - Follow the shared audit contract at
-         bugteam/reference/audit-contract.md. Per category: produce
-         either a Shape A structured finding or a Shape B structured
-         proof-of-absence. Bare "verified clean" labels are REJECTED.
+         $HOME/.claude/_shared/pr-loop/audit-contract.md. Per category:
+         produce either a Shape A structured finding or a Shape B
+         structured proof-of-absence. Bare "verified clean" labels are
+         REJECTED.
        - Run the contract's adversarial second pass after the primary
          finding list.
        - The LEAD spawns the Haiku secondary auditor in parallel with
@@ -203,87 +205,20 @@ The subagent receives this prompt and loops internally — the lead does not re-
        <qbug_temp_dir>/loop-<loop_count>-audit.json per the contract's
        persistence schema.
 
-       Post ONE review per loop via `post_audit_thread.py`. 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 written to
-       `<qbug_temp_dir>/loop-<loop_count>-findings.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 surface in the loop's user-facing summary rather than
-       as inline anchored comments. The JSON root is a list of objects
-       shaped `{path, line, side, severity, description, fix_summary}`.
-       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 → write
-       `[]` and pass `--state CLEAN`; one or more anchored findings →
-       pass `--state DIRTY` with the full list.
-
-       **Self-PR auto-toggle.** GitHub rejects both `APPROVE` and
-       `REQUEST_CHANGES` reviews with HTTP 422 when the authenticated
-       identity matches the PR author ("Cannot approve/request changes
-       on your own pull request"). `post_audit_thread.py` detects this
-       case via `gh api user` + `gh api repos/<o>/<r>/pulls/<n>` and
-       auto-resolves an alternate gh account's token for the reviews
-       POST — the active `gh auth` account is not mutated; only the
-       bearer token sent on the request changes. After the POST the
-       active account is still whoever it was before, so no "swap back"
-       step is needed.
-
-       Configuration:
-
-       - `GH_TOKEN` / `GITHUB_TOKEN` env vars take precedence over the
-         toggle. Set them when you need to pin a specific reviewer
-         identity by token rather than by account login.
-       - `BUGTEAM_REVIEWER_ACCOUNT` env var names which authenticated
-         alternate to prefer when a toggle is needed (for example,
-         `BUGTEAM_REVIEWER_ACCOUNT=jl-cmd`). The env var name is shared
-         across every skill that invokes `post_audit_thread.py`. When
-         unset, the script falls back to the first alternate account
-         `gh auth status` reports.
-       - The named alternate must be logged in (`gh auth login -h
-         github.com -u <login>`) before the audit skill runs. The
-         script exits 1 with a pointing-at-`gh auth login` message
-         when self-PR is detected and no usable alternate is
-         authenticated.
-
-       ```
-       python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/post_audit_thread.py" \
-         --skill qbug \
-         --owner <owner> \
-         --repo <repo> \
-         --pr-number <pr_number> \
-         --commit <head_sha> \
-         --state <CLEAN|DIRTY> \
-         --findings-json <qbug_temp_dir>/loop-<loop_count>-findings.json
-       ```
-
-       The script POSTs a single review with `event=APPROVE` on CLEAN
-       (the request event; GitHub stores it as `state=APPROVED`; empty
-       `comments[]`, body documents "no findings") or
-       `event=REQUEST_CHANGES` on DIRTY (one inline anchored comment per
-       finding; each becomes its own resolvable thread on the PR). It
-       handles retries internally (1s / 4s / 16s backoff across four
-       attempts). Exit 0 emits the new review's `html_url` to stdout;
-       extract the numeric review id from the URL's
-       `#pullrequestreview-<id>` suffix (the trailing URL fragment of
-       `html_url`, the part after `#`). Then harvest child-comment URLs **and PR review
-       thread node ids** via
-       `pull_request_read(method="get_review_comments",
-       owner=<owner>, repo=<repo>, pullNumber=<pr_number>)` filtered to
-       that review id. The same response carries each
-       comment's PR review thread node id (e.g. `PRRT_kwDOxxx`) — match
-       children to findings in the order they appear in the findings
-       JSON. Each `loop_comment_index[finding_id]` entry must carry
-       `finding_comment_id` (numeric, used by
+       Post ONE review per loop. Read
+       $HOME/.claude/skills/post-audit-findings/SKILL.md and apply it
+       with `--skill qbug`. That skill owns the findings-JSON mapping,
+       the anchored-only serialization, the CLEAN/DIRTY decision, the
+       self-PR reviewer toggle, and the exit codes. qbug-specific
+       persistence: write the anchored findings JSON to
+       `<qbug_temp_dir>/loop-<loop_count>-findings.json` and pass that
+       path as `--findings-json`. Unanchored findings surface in the
+       loop's user-facing summary rather than as inline anchored
+       comments.
+
+       On exit 0, harvest ids per that skill's "Harvest ids for the fix
+       loop" section: each `loop_comment_index[finding_id]` entry must
+       carry `finding_comment_id` (numeric, used by
        `add_reply_to_pull_request_comment`), `finding_comment_url`, and
        `thread_node_id` (`PRRT_kwDOxxx`, used by `resolve_thread`) so
        the FIX step can reply against the comment and resolve the
@@ -313,7 +248,7 @@ The subagent receives this prompt and loops internally — the lead does not re-
        for every modified file.
 
        Post-fix self-audit: follow the contract's post-fix self-audit
-       sequence at bugteam/reference/audit-contract.md. Paranoid mode
+       sequence at $HOME/.claude/_shared/pr-loop/audit-contract.md. Paranoid mode
        (Haiku secondary in parallel), internal iteration cap = 3, exit
        "stuck: post-fix audit not converging" after 3 rounds with fresh
        findings. Only when gate_findings empty AND post_fix_findings
@@ -330,55 +265,22 @@ The subagent receives this prompt and loops internally — the lead does not re-
        Write <qbug_temp_dir>/loop-<loop_count>-diagnostics.json per the
        contract's diagnostics schema (all eight keys required).
 
-       For each finding, atomically (a) post the fix reply and
-       (b) call `resolve_thread`. The two calls form one logical action
-       per thread — do not yield to the lead between them, and do not
-       batch all replies before any resolves.
-
-       (a) Reply via
-       `add_reply_to_pull_request_comment(commentId=<loop_comment_index[finding_id].finding_comment_id>,
-       body=<reply_body>, owner=<owner>, repo=<repo>,
-       pullNumber=<pr_number>)`. The reply body uses the unified template
-       at [`../../_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md).
-       Skeleton (identical across all paths):
-
-       ```
-       **Claude finished @<reviewer>'s task** —— <status_line>
-
-       ---
-       ### <action_heading> ✅
-
-       <1–2 paragraph plain-language explanation>
-
-       **`<file>:<line>`:**
-       - <bullet describing change or rationale>
-       - <bullet describing change or rationale>
-
-       <closing paragraph>
-       ```
-
-       Per-path `<status_line>` / `<action_heading>`:
-       - `status=fixed`: `Fixed in <short_sha>` (first 7 chars) /
-         finding-specific action verb (e.g.,
-         `Replaced Any with concrete type`).
-       - `status=could_not_address`: `Could not address this loop` /
-         one-line reason text.
-       - `status=hook_blocked`: `Hook blocked the fix commit` /
-         one-line hook summary.
-
+       For each finding, read
+       $HOME/.claude/skills/pr-fix-protocol/SKILL.md and apply its
+       reply-and-resolve unit: atomically (a) post the fix reply via
+       `add_reply_to_pull_request_comment` against
+       `loop_comment_index[finding_id].finding_comment_id`, using the
+       body template at
+       $HOME/.claude/_shared/pr-loop/audit-reply-template.md, then
+       (b) call `pull_request_review_write(method="resolve_thread",
+       threadId=<loop_comment_index[finding_id].thread_node_id>)` for
+       the same thread. Per-path `<status_line>`:
+       - `status=fixed`: `Fixed in <short_sha>` (first 7 chars).
+       - `status=could_not_address`: `Could not address this loop`.
+       - `status=hook_blocked`: `Hook blocked the fix commit`.
        Body text is passed directly as string parameters — no temp
        files, no jq, no shell pipes.
 
-       (b) Immediately call
-       `pull_request_review_write(method="resolve_thread",
-       threadId=<loop_comment_index[finding_id].thread_node_id>,
-       owner=<owner>, repo=<repo>, pullNumber=<pr_number>)` for the
-       same thread (this is the PR review thread node ID —
-       `PRRT_kwDOxxx` — distinct from the numeric comment ID; the
-       AUDIT step captures it at audit time when calling
-       `get_review_comments` and stores it on each
-       `loop_comment_index` entry alongside `finding_comment_id`).
-
        Update state: last_action="fixed". Append
        `<N> fix: <short_sha> — <fixed>/<could_not_address>/<hook_blocked>`
        to audit_log.
@@ -443,7 +345,7 @@ Delete the resolved `<qbug_temp_dir>` tree and any `.qbug-*.md` temp files in th
 - **No loop cap.** Cycle runs until `converged`, `stuck`, or `error`. User can interrupt.
 - **Code rules gate before every AUDIT.** Same `validate_content` logic as /bugteam.
 - **One commit per FIX action.** Linear branch, fast-forward push only.
-- **Categories A–N.** Same rubric as [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md).
+- **Categories A–P.** Same rubric as [`bugteam/PROMPTS.md`](../bugteam/PROMPTS.md).
 - **One review per loop.** Anchored findings as `comments[]`; unanchored findings surface in the calling skill's user-facing output (chat reply to the user) rather than in the PR review body.
 - **PR description rewrite on every exit**, same as /bugteam Step 4.5.
 - **Temp file cleanup on every exit path.**

package/skills/qbug/test_qbug_skill_audit_schema.py

@@ -1,6 +1,6 @@
 """Tests verifying the shared audit contract and qbug's reference to it.
 
-The contract lives in bugteam/reference/audit-contract.md and is the single
+The contract lives in _shared/pr-loop/audit-contract.md and is the single
 source of truth for finding schema, proof-of-absence shape, adversarial pass,
 Haiku secondary, and de-dup/merge rules. qbug/SKILL.md must reference it.
 """
@@ -12,7 +12,7 @@ from pathlib import Path
 
 SKILL_FILE_PATH = Path(__file__).parent / "SKILL.md"
 CONTRACT_FILE_PATH = (
-    Path(__file__).parent.parent / "bugteam" / "reference" / "audit-contract.md"
+    Path(__file__).parents[2] / "_shared" / "pr-loop" / "audit-contract.md"
 )
 CATEGORY_E_RUBRIC_FILE_PATH = (
     Path(__file__).parent.parent.parent

package/skills/qbug/test_qbug_skill_post_fix_audit.py

@@ -76,7 +76,7 @@ def test_should_require_loop_n_diagnostics_json() -> None:
 
 def test_contract_should_require_all_eight_source_keys_in_diagnostics() -> None:
     contract_path = (
-        Path(__file__).parent.parent / "bugteam" / "reference" / "audit-contract.md"
+        Path(__file__).parents[2] / "_shared" / "pr-loop" / "audit-contract.md"
     )
     contract_text = contract_path.read_text(encoding="utf-8")
     required_keys = [

package/skills/reviewer-gates/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: reviewer-gates
+description: >-
+  Runs the availability gates a PR-loop orchestrator checks before engaging an
+  external reviewer: the CLAUDE_REVIEWS_DISABLED opt-out parse (bugbot,
+  bugteam, and copilot tokens via reviews_disabled.py), the once-per-run
+  Copilot premium-quota pre-check (copilot_quota.py with copilot_down
+  semantics), and the Cursor Bugbot trigger/acknowledge/CI-detect flow
+  (check_bugbot_ci.py with the literal `bugbot run` comment). Invoked by
+  PR-loop orchestrators — pr-converge, autoconverge, bugteam, qbug, findbugs,
+  copilot-review, monitor-open-prs — at run start and at each reviewer
+  engagement point. Not a general code-review skill; it decides whether a
+  reviewer runs, never what the reviewer finds.
+---
+
+# Reviewer Gates
+
+**Core principle:** one place decides whether an external reviewer is engaged. A caller never hand-parses `CLAUDE_REVIEWS_DISABLED`, never re-queries Copilot quota mid-run, and never invents a Bugbot trigger phrase.
+
+## How callers invoke this
+
+- **Skill-capable contexts** (a lead session with the `Skill` tool): `Skill({skill: "reviewer-gates", args: "--skill <caller> <gate> [gate parameters]"})`.
+- **Fallback** (a subagent or teammate without the `Skill` tool): the caller's spawn prompt says "Read `~/.claude/skills/reviewer-gates/SKILL.md` and apply the `<gate>` section with the parameters below."
+
+Every invocation carries the caller's identity (`--skill <caller>`, e.g. `pr-converge`, `qbug`). The refusal line in Gate 1 and every logged decision names the caller, so a multi-skill session's transcript shows which loop each gate served.
+
+## Gate 1: Reviewer opt-out (`CLAUDE_REVIEWS_DISABLED`)
+
+The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token list (case-insensitive, whitespace-tolerant). Three tokens exist:
+
+| Token | Disables |
+|---|---|
+| `bugteam` | The whole bug-audit family: `/bugteam`, `/qbug`, `/findbugs`, and audit dispatch in `/monitor-open-prs` |
+| `bugbot` | Cursor Bugbot triggering and polling |
+| `copilot` | GitHub Copilot review requests and polling |
+
+Run the shared parser — never an inline shell parse:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer <bugbot|bugteam|copilot>
+```
+
+- **Exit 0** — the named reviewer is opted out. A skill whose whole run depends on that reviewer responds with its refusal line and stops. The template: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
+- **Exit 1** — the reviewer is available; continue.
+
+## Gate 2: Copilot quota pre-check (once per run)
+
+At run start — before any Copilot request, poll, or agent spawn — run:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/copilot_quota.py"
+```
+
+It resolves the configured GitHub account, reads the remaining Copilot premium-request quota via `gh api copilot_internal/user`, and prints one line. Log that line.
+
+- **Exit 0** — Copilot has quota. Leave `copilot_down` false (or pass `copilotDisabled: false` to a workflow).
+- **Any non-zero exit** — skip Copilot for the whole run: the account is out of quota, the quota API or account access is down, or no account is set. Set `copilot_down = true` (or `copilotDisabled: true`). The no-account line names the exact `.env` path and key to set; the account comes from the `COPILOT_QUOTA_ACCOUNT` environment variable or a git-ignored `.env` file.
+
+Run the pre-check once per run, not per tick or per round. Every later tick reads the stored flag. While `copilot_down` is true:
+
+- Skip every Copilot fetch, request, poll, and agent spawn outright.
+- Export `CLAUDE_REVIEWS_DISABLED="copilot"` in the shell of any convergence check (`check_convergence.py`), so the check bypasses its Copilot review gate and pending-requested-reviews gate and the run still marks ready on the remaining signals.
+
+`reviewer_availability.py` (same directory) is the single entry point when a caller wants one command answering "may reviewer X be engaged?" — it composes the opt-out parse and, for Copilot, the quota check: exit 0 to engage, non-zero to skip.
+
+## Gate 3: Bugbot trigger, acknowledge, and CI-detect
+
+Cursor Bugbot signals through CI check runs, not always through a posted review. The decision tree runs against `<current_head>` with `check_bugbot_ci.py` (installed at `$HOME/.claude/skills/pr-converge/scripts/check_bugbot_ci.py`; `--help` documents every mode):
+
+1. **Silent-pass pre-check (always first).**
+   `python "$HOME/.claude/skills/pr-converge/scripts/check_bugbot_ci.py" --check-clean --owner <O> --repo <R> --sha <current_head>`
+   - Exit 0 — Bugbot CI completed with a `success`/`neutral` conclusion and posted no review: a silent pass. Record `bugbot_clean_at = <current_head>` and stop; do not trigger.
+   - Exit 1 (not a silent pass) or exit 2 (gh CLI error, silent pass not confirmable) — continue.
+2. **Already-queued check.**
+   `... check_bugbot_ci.py --check-active --owner <O> --repo <R> --sha <current_head>`
+   - Exit 0 — Bugbot is already queued on this commit. Skip posting; wait for completion (callers schedule their own wakeup).
+   - Exit 1 — continue.
+3. **Trigger.** Post exactly `bugbot run` as an issue comment (`add_issue_comment`) — no `@cursor[bot]` mention, no other text. `bugbot run` is empirically the only re-trigger Cursor Bugbot recognizes; every other phrasing silently no-ops. Wait 8 seconds with an in-turn Monitor delay, never a foreground `sleep` (blocked in headless runs).
+4. **Acknowledge check.**
+   `... check_bugbot_ci.py --owner <O> --repo <R> --sha <current_head>`
+   - Exit 0 — a check run is present: record `bugbot_acknowledged_at = <now, ISO 8601>`; the caller polls on its own cadence.
+   - Exit non-zero — Bugbot is down: set `bugbot_down = true` and route past the Bugbot phase; the run continues on its remaining signals.
+
+The silent-pass pre-check runs first so a bot that already finished cleanly is never re-prompted — Bugbot refuses to re-run on an evaluated commit, and without the pre-check the acknowledge step would falsely mark `bugbot_down = true`.
+
+**Flag reset rule:** `bugbot_down` resets to false whenever `<current_head>` changes — a new HEAD invalidates the old down-detection. `copilot_down` never resets mid-run; it holds until the run ends.
+
+## Gotchas
+
+- **`bugbot run` is load-bearing text.** Alternative phrasings (`@cursor run`, `cursor review`, `bugbot please`) return no error and do nothing.
+- **A skipped gate is a decision, not an omission.** When `copilot_down` or `bugbot_down` short-circuits a phase, record the flag and the exit line that set it — a convergence report that cannot show why a reviewer was skipped is incomplete.
+- **The opt-out gate re-runs at every reviewer entry point;** the quota pre-check runs once per run. Confusing the two either re-spends quota-API calls per tick or misses a mid-run opt-out.
+
+## Folder map
+
+- `SKILL.md` — this file; the skill ships no scripts of its own. Gate scripts live in `_shared/pr-loop/scripts/` (`reviews_disabled.py`, `copilot_quota.py`, `reviewer_availability.py`) and `pr-converge/scripts/` (`check_bugbot_ci.py`).

package/skills/session-log/CLAUDE.md

@@ -1,12 +1,12 @@
 # session-log
 
-Logs a session report as a gallery-shaped HTML file in the Obsidian vault, auto-publishes it as a secret gist, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
+Logs a session report as a self-contained HTML page in the Obsidian vault, publishes it with the `Artifact` tool, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
 
 **Trigger:** `/session-log`, "journal this session", "log this work", "session report", "save session", "capture session", "document what we did".
 
 ## Purpose
 
-Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, decision extraction, and folder hygiene; it delegates HTML authorship to `doc-gist`.
+Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, HTML composition and publishing, decision extraction, and folder hygiene.
 
 ## Key files
 
@@ -18,14 +18,14 @@ Produces a self-contained HTML session report shaped to the session's character
 
 1. **Backend detection** — headless vault (`ob --version` + `OBSIDIAN_VAULT_PATH`) then local vault (`~/.claude/vault/`). Session number from `[N]. *.html` and `[N]. *.md` files in the project folder.
 2. **Session metadata** — project name, session number, session ID from `CLAUDE_CODE_SESSION_ID`, date, title.
-3. **HTML via doc-gist shape principles** — gallery-anchored design (e.g., `17-pr-writeup.html` for feature builds, `12-incident-report.html` for incidents). `<!-- @publish-as-gist -->` marker triggers auto-publish hook on Write/Edit.
-4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line. The URL from the final Edit is canonical.
+3. **Compose and publish via the Artifact tool** — loads the `artifact-design` skill first, designs the shape for the session's character (e.g., a PR-writeup shape for feature builds, a timeline shape for incidents), writes the HTML, then publishes it with the `Artifact` tool using the fixed favicon `📓`.
+4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line, then redeploy via `Artifact` on the same `file_path` so the URL stays the same.
 5. **Decision extraction** — scans conversation for unrecorded decisions; prompts user via `AskUserQuestion` before invoking `/remember`.
-6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues.
+6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues and redeploys via `Artifact`.
 
 ## Conventions
 
-- The `<!-- @publish-as-gist -->` marker must appear exactly as shown; each Edit re-fires the hook and produces a new gist ID.
-- Session reports use HTML; `.md` paths are blocked by `md_to_html_blocker` for session paths.
+- Session reports use HTML — the Artifact tool publishes HTML or Markdown, and HTML gives the report designer more visual structure.
 - `write_existing_file_blocker` rejects Write on existing paths — use Edit for all vault-context updates.
+- The `Artifact` tool redeploys to the same URL on repeat calls with the same `file_path` within the current run — edits made in steps 3 and 5 to the session created this run never mint a new URL.
 - Final step copies `/rename [Project] - [Primary Outcome]` to the clipboard via `pwsh Set-Clipboard`.

package/skills/session-log/SKILL.md

@@ -1,44 +1,30 @@
 ---
 name: session-log
 description: >-
-  Log a session report by handing the HTML authorship to doc-gist (which designs fresh per session and auto-publishes via the `<!-- @publish-as-gist -->` marker hook), then track vault context, extract unrecorded decisions, tidy the project's session folder, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
+  Log a session report by composing a self-contained HTML page and publishing it with the Artifact tool, then track vault context, extract unrecorded decisions, tidy the project's session folder, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
 ---
 
 # Session Log
 
 ## Overview
 
-The HTML artifact is doc-gist's job end-to-end. Session-log owns everything around it: where the file lives in the vault, what number it gets, the frontmatter metadata contract, post-write vault tracking, decision extraction, project-folder hygiene, and the closing `/rename` hand-off.
+Session-log composes the HTML report and publishes it directly with the `Artifact` tool. The skill owns the whole flow: where the file lives in the vault, what number it gets, the frontmatter metadata contract, HTML composition and publishing, post-write vault tracking, decision extraction, project-folder hygiene, and the closing `/rename` hand-off.
 
 **Announce at start:** "I'm logging this session."
 
-## Why this skill delegates HTML to doc-gist
+## Why this report is designed fresh per session
 
-Sessions come in many shapes — convergence loops, feature builds, research dives, incidents, refactors, decisions. A single h2-emoji-list template forces every session into the same form regardless of fit, and the artifact reads as a process log rather than a substance log. Doc-gist's principle: *"design fresh per request, drawing on a gallery of 20 HTML shape patterns."* Each session report gets the shape that fits the session.
-
-The gallery lives at `~/.claude/skills/doc-gist/references/examples/`. Patterns that usually fit session reports:
-
-| Session character | Gallery shape to study |
-|---|---|
-| Feature build / PR ships | `17-pr-writeup.html` |
-| Incident, debugging arc, convergence loop | `12-incident-report.html` |
-| Status update / weekly progress | `11-status-report.html` |
-| Implementation plan or decision record | `16-implementation-plan.html` |
-| Exploration of multiple approaches | `01-exploration-code-approaches.html` |
-| Code-explainer with module map | `04-code-understanding.html` |
-
-The session designer reads the matching gallery file, then designs the report in that shape. **Adapt, do not copy.**
+Sessions come in many shapes — convergence loops, feature builds, research dives, incidents, refactors, decisions. A single h2-emoji-list template forces every session into the same form regardless of fit, and the artifact reads as a process log rather than a substance log. Load the `artifact-design` skill before composing any page content — it calibrates the design investment and shape to the session's character: a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough.
 
 ## Gotchas
 
-- **Doc-gist's auto-publish hook fires on Write/Edit of any HTML containing `<!-- @publish-as-gist -->`.** Session-log composes the HTML with the marker so auto-publish runs by default — sessions are intended for sharing with collaborators. The hook prints the gist + preview URLs to tool output; capture both.
-- **`gh` must be authenticated.** Auto-publish runs `gh gist create`. If `gh` is unauthenticated, `gh gist create` writes its error message; `gist_upload.py` surfaces it from stderr when present and falls back to stdout when stderr is empty (so the error always appears somewhere in the tool result). The hook exits 0 (does not block the Write). Look at the full tool result, then surface the error to the user; the local vault HTML is still the canonical artifact, so the remaining steps still run.
-- **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. The `md_to_html_blocker` PreToolUse hook blocks `.md` writes unless the path is exempt — exemptions include any path containing `/.claude/` and README/CHANGELOG files at repo root. Session reports use HTML, which the hook ignores entirely.
+- **Load the `artifact-design` skill before writing page content.** The `Artifact` tool needs this step first — it is not optional polish.
+- **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
+- **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
+- **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
 - **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/no-historical-clutter.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
 - **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
-- **Each Write/Edit of the marked HTML creates a fresh gist with a new ID.** `gist_upload.py` calls `gh gist create` with no lookup of any prior gist. Step 3 performs two Edits and Step 5's tidy may Edit the current session a third time — each Edit produces a different gist URL than its predecessor. Quote the URLs from the FINAL publish (the most recent auto-publish run for the session being created — the second Step-3 Edit when Step 5 does not touch the current session, or the Step 5 Edit when it does) to the user; never embed a URL inside the HTML that a later Edit then re-publishes.
 - **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
-- **Auto-published gists carry the default `gist_upload.py` description (`HTML artifact`), not a session-specific title.** The auto-publish hook invokes `gist_upload.py` with only `--input` and `--no-open` — it has no session-title context to pass as `--description`. Browsing or sharing gists, operators see "HTML artifact" rather than `Session [N] — [Title] — session-log — [Project]`. Workaround: after the canonical Edit completes, edit the existing gist's description in place with `gh gist edit <gist-id> --desc "Session [N] — [Title] — session-log — [Project]"` (this updates the existing gist's metadata; no new gist ID is created) if a meaningful title matters for that share. The HTML frontmatter inside the file remains the authoritative session metadata regardless of the gist's external description.
 
 ## Backend Detection (run before Step 1)
 
@@ -87,27 +73,25 @@ tags: [session, [project-tag], [topic-tags]]
 
 Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `session_id`, write the value read from `CLAUDE_CODE_SESSION_ID` in step 1 (or `unknown` when the variable is unset); for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits `vault_context_retrieved` to `true` if any of the three vault MCP tools fired this session.
 
-## Step 2: Compose the HTML via doc-gist's shape principles
+## Step 2: Compose and Publish the HTML via the Artifact Tool
 
-Design the artifact for **this session's character**, drawing on the doc-gist gallery patterns listed above. The report must answer for a cold reader, from the H2 headers alone, three questions: *what shipped*, *why it matters*, *what impact it had*. Process narration (commit-by-commit walks, agent gotchas, retry counts) belongs at the end, not in the opening sections.
+Load the `artifact-design` skill before writing any content. Design the artifact for **this session's character** — a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough. The report must answer for a cold reader, from the section headers alone, three questions: *what shipped*, *why it matters*, *what impact it had*. Process narration (commit-by-commit walks, agent gotchas, retry counts) belongs at the end, not in the opening sections.
 
-**Required somewhere in the HTML (commonly in `<head>`):** the auto-publish marker.
+**Required as the first content line:** the frontmatter HTML comment from step 1.
 
-```html
-<!-- @publish-as-gist -->
-```
+**Required somewhere in the content:** a `<title>` element naming the session — it names the browser tab and the artifact gallery entry.
 
-The marker triggers the PostToolUse hook after Write or Edit — the hook scans the entire HTML for the literal sentinel string and uploads the file to a secret gist, then prints the gist + preview URLs to your tool output. The marker must be the literal comment text exactly; whitespace inside breaks it.
+**Required as the first content section (after the frontmatter comment):** an opening "What this session shipped" paragraph + bullets — written so a reader with zero prior context understands the outcome. For continuation sessions (where the substantive work landed in a prior session), recap the parent session's outcome briefly so the report stands alone.
 
-**Required at the top of `<body>`:** the frontmatter HTML comment from step 1.
+**Required: self-contained, responsive, theme-aware HTML.** Inline all CSS in a `<style>` block and all JS inline; embed any images as data URIs — the `Artifact` tool's content security policy blocks external CDN scripts, stylesheets, fonts, and network requests. Use relative units so the layout holds at any width, and support both light and dark via `prefers-color-scheme` (or `:root[data-theme]` overrides).
 
-**Required as the first content section:** an opening "What this session shipped" paragraph + bullets — written so a reader with zero prior context understands the outcome. For continuation sessions (where the substantive work landed in a prior session), recap the parent session's outcome briefly so the report stands alone.
+**No document wrapper tags.** The `Artifact` tool wraps the file content in a `<!doctype html>…<head>…</head><body>` skeleton at publish time — write the `<title>`, `<style>`, and body markup directly, with no `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags of your own.
 
-**Required: self-contained HTML.** Embed all styles in a `<style>` block inside `<head>` (inline `style="..."` attributes are also fine if preferred); no `./relative/paths` to local assets. Doc-gist's transport sends a single HTML file with no neighbors, so any relative-path reference (CSS, JS, images) cannot resolve and the asset will be missing from the preview. Absolute external URLs (CDN-hosted assets, image hotlinks) work but add an external dependency the report should not need — design the report to stand alone with no external dependencies.
+Beyond those requirements, design the shape that fits the session — the `artifact-design` skill's guidance covers typography, palette, and layout choices.
 
-Beyond those four requirements, design the shape that fits. A convergence loop session reads naturally as an incident timeline (`12-incident-report.html`); a feature build reads as a PR writeup (`17-pr-writeup.html`); a research session reads as a feature explainer (`14-research-feature-explainer.html`). Read the matching gallery entry for typography, palette, spatial idioms — adapt, do not copy.
+**Write the file** via the Write tool to the vault path. Create the project directory via `mkdir -p` if it does not exist.
 
-**Write the file** via the Write tool to the vault path. Create the project directory via `mkdir -p` if it does not exist. The auto-publish hook fires after the Write completes and prints a gist + preview URL pair to tool output (the bare preview URL on stdout; both labeled `Gist: <url>` and `Preview: <url>` lines on stderr — both streams appear in the agent's tool-result). Step 3 performs **two Edit calls** and each one re-fires the hook with a fresh URL pair — only the URL pair from the second (final) Step-3 Edit is canonical for the just-created session (the step-2 pair and the first step-3 pair are orphaned the moment the next Edit lands). Always quote the URL pair from the **most recent auto-publish run for the session being created**. Note: Step 5's tidy audits every `.html` file in the project folder including the just-created session, so if Step 5's frontmatter auto-fix touches the current session, the Step 5 republish URL pair becomes the new canonical pair for that session (re-quote it to the user with a "Session republished — new preview: <url>" line). The second Step-3 Edit's URL pair stays canonical only when Step 5 does not touch the current session.
+**Publish the file** by calling the `Artifact` tool with `file_path` set to the vault path just written, `favicon` set to the fixed session-log favicon `📓` — this favicon stays the same across every session-log report so the series reads as one consistent collection; never swap it per session — and `description` set to a one-sentence subtitle summarizing the session. Capture the returned URL: it is the canonical URL for this session report, and it stays the same across every later `Artifact` call on this same `file_path` within the current run (steps 3 and 5 redeploy to it rather than minting a new one).
 
 **If the Write fails**, output the HTML content in the conversation so the user can copy it manually. Before emitting the HTML to chat, resolve the `vault_context_retrieved` placeholder to `true` or `false` based on the same vault-MCP-tool scan that Step 3 would have run, and include the matching vault-context `<li>` line (Retrieved or Not retrieved) so the emitted HTML is a valid copy-paste artifact with complete frontmatter. Skip Step 3 and continue at step 4.
 
@@ -121,10 +105,10 @@ Review the conversation history for any use of these vault MCP tools (look only
 - `mcp__obsidian__read_note`
 - `mcp__obsidian__read_multiple_notes`
 
-Edit the vault HTML via two Edit calls (each Edit re-fires the auto-publish hook and creates a fresh gist; **the URL pair from the second/final Edit is canonical** — the first Edit's URLs are orphaned the moment the second Edit lands):
+Edit the vault HTML via two Edit calls:
 
 1. Set the frontmatter `vault_context_retrieved` field to `true` when any of the three tools fired this session, `false` otherwise.
-2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block before `</body>`:
+2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block at the end of the content:
 
 ```html
 <h2>Notes</h2>
@@ -137,7 +121,7 @@ Edit the vault HTML via two Edit calls (each Edit re-fires the auto-publish hook
 
 If the report already has a notes / references section, use Edit to insert one matching child element at the end of that section. The element shape mirrors whatever the section already uses: an extra `<li>` before the closing `</ul>` for a list, an extra `<dt>Vault context</dt><dd>…</dd>` pair before the closing `</dl>` for a description list, an extra `<p><strong>Vault context:</strong> …</p>` before the section's closing tag for a paragraph-based section. Pick the form that matches the surrounding markup.
 
-The gist URL stays out of the HTML body on purpose: each Edit re-fires the auto-publish hook and produces a brand-new gist ID, so any URL embedded in the file becomes stale the instant the next Edit lands. The canonical gist + preview URL is the pair from **the most recent auto-publish run that touched the current session report** — typically the second (final) Step-3 Edit, but the Step 5 Edit takes over as canonical when Step 5's frontmatter auto-fix edits the current session (re-quote the Step 5 pair with a "Session [N] republished — new preview: <url>" line per the Step 2 guidance at line 107). Quote whichever pair is most recent when announcing the report.
+After both Edits land, call the `Artifact` tool again with the same `file_path` and the same `favicon` used in step 2 to redeploy the updated content. This updates the URL captured in step 2 in place; no new URL is minted.
 
 ## Step 4: Decision Extraction
 
@@ -160,7 +144,7 @@ Scope: the current project's session folder only.
    - Missing frontmatter fields that can be inferred (e.g., `blocked: false` when status is `completed`; `vault_context_retrieved: false` when the field is absent, since the field defaults to false in pre-existing sessions)
    - `type` field set to a wrong value (correct to `session-report`)
 
-   Each Edit on a marked HTML file re-fires doc-gist's auto-publish hook and produces a fresh gist + preview URL pair in the agent's tool output (the bare preview URL on stdout; both labeled `Gist: <url>` and `Preview: <url>` lines on stderr) — the prior gist URL becomes orphaned. Surface a `Session [N] republished — new preview: <url>` line per Edit so the user can update any prior shares.
+   When the Edit touches the session report created in this run, call `Artifact` again with the same `file_path` and `favicon` from step 2 to redeploy — the URL captured in step 2 stays unchanged. When the Edit touches an older session report published in a prior run, call `Artifact` on that `file_path` with no `url` argument, since this skill keeps no record of that file's earlier URL — this publishes the older report at a new URL. Surface a `Session [N] republished at a new URL: <url>` line so the user can update any prior shares.
 4. **Report issues that need user input:**
    - Files with wrong naming convention (propose new name)
    - Stale statuses (propose update to `completed` or ask)
@@ -190,14 +174,13 @@ The primary outcome comes from the session title resolved in step 1.
 
 - [ ] Backend detected and announced
 - [ ] Session number resolved from `[N]. *.html` and `[N]. *.md` files (both parsed to preserve sequence across the format migration)
-- [ ] HTML composed via doc-gist's shape principles (gallery-anchored)
-- [ ] `<!-- @publish-as-gist -->` marker present somewhere in the HTML
-- [ ] Frontmatter HTML comment present at top of `<body>`
+- [ ] `artifact-design` skill loaded before composing page content
+- [ ] HTML composed for this session's character (no document wrapper tags; self-contained, responsive, theme-aware)
+- [ ] Frontmatter HTML comment present as the first content line
 - [ ] `session_id` frontmatter field set from `CLAUDE_CODE_SESSION_ID` (the authoring agent's own session), or `unknown` when the variable is unset
 - [ ] Opening section answers "what shipped / why / impact" for a cold reader
-- [ ] Self-contained HTML (no relative-path asset refs; avoid external dependencies)
-- [ ] Auto-publish URLs captured from step 2 and step 3 (or HTML emitted to chat when step 2 Write failed)
-- [ ] Vault-context line appended via Edit (step 3); URL pair from the most recent auto-publish run for the current session quoted to the user (typically the final Step-3 Edit, but the Step 5 republish takes over when Step 5 edits the current session)
+- [ ] Published via the `Artifact` tool with the fixed favicon `📓`; URL captured (or HTML emitted to chat when step 2 Write failed)
+- [ ] Vault-context line appended via Edit (step 3); `Artifact` redeployed on the same URL
 - [ ] Decision extraction surfaced any unrecorded items
 - [ ] Session tidy reported anomalies or stayed silent
 - [ ] `/rename` command copied to clipboard via `pwsh Set-Clipboard`