clud-bug 0.6.19 → 0.6.20

package/lib/prompts.js

@@ -57,13 +57,10 @@ ${focusBullets}
 Skip style suggestions, minor naming issues, or anything that
 doesn't affect correctness, security, or performance.
 
-Section budgets (token-frugal review — v0.6.4+):
-The workflow sets env vars MAX_DIFF_BYTES / MAX_COMMENT_BYTES /
-MAX_SKILL_BYTES. When fetching content via the Bash tool, cap each
-section with \`head -c\` to keep your context lean. Caching covers
-the stable system-prompt prefix (you're reading it now) at 10% of
-standard input cost, but variable per-PR content is NOT cached, so
-size discipline on those fetches pays back directly.
+Section budgets (v0.6.4+):
+Cap fetched content with \`head -c\` to control input cost. Workflow
+exposes MAX_DIFF_BYTES / MAX_COMMENT_BYTES / MAX_SKILL_BYTES. The
+cached system prefix is free at 10%; per-PR fetches are not.
 
   - PR diff (incremental on fix-push — v0.6.10+):
     On a re-review (not first pass), fetch only the delta between
@@ -71,15 +68,11 @@ size discipline on those fetches pays back directly.
     state lives in your PRIOR SUMMARY COMMENT as an HTML marker:
     \`<!-- last-reviewed-sha: <sha> -->\`.
 
-    CRITICAL — identifying the PRIOR SUMMARY (not the progress comment):
-    \`anthropics/claude-code-action\` posts an in-progress
-    \`[claude]: Claude Code is working…\` comment BEFORE this prompt
-    runs. That comment IS authored by claude[bot] but is NOT your
-    prior summary — it has no marker. Walking "the LAST claude[bot]
-    comment" would always land on the progress comment and the
-    handshake would never fire. Instead, identify the prior summary
-    by its HEADER LINE: it begins with \`## 🐛 Clud Bug review\`
-    (same anchor the strict-mode gate uses for classification).
+    Identifying the PRIOR SUMMARY: claude-code-action posts an
+    in-progress \`Claude Code is working…\` comment BEFORE this
+    prompt runs — claude[bot]-authored but NOT the summary (no
+    marker). Anchor on the H2 line \`## 🐛 Clud Bug review\` instead
+    of "latest claude[bot] comment" — same anchor strict-mode uses.
 
     Detection in three steps:
 
@@ -104,11 +97,9 @@ size discipline on those fetches pays back directly.
     If output looks truncated mid-line, request the omitted hunks via
     \`gh pr diff "$PR_NUMBER" --name-only\` + a targeted re-fetch.
 
-    Edge case — span check: if a delta-review surfaces a finding that
-    might affect unchanged code outside the delta (a fix-push edits a
-    function whose callers were fine in the prior pass), do a one-time
-    \`gh pr diff "$PR_NUMBER"\` to confirm before flagging. The
-    incremental view is for fast re-confirmation, not for blind trust.
+    Span check: if a delta-finding might affect callers outside the
+    delta, do a one-time full \`gh pr diff\` before flagging — the
+    incremental view is for fast re-confirmation, not blind trust.
 
   - Skill files: \`head -c "$MAX_SKILL_BYTES" .claude/skills/<name>/SKILL.md\`
     per file (default 4,000 bytes). Baseline skills fit easily;
@@ -134,221 +125,148 @@ two things, in order:
      work when the original truncation was byte-bound.
 
   2. Add a \`### Diagnostics\` block above the Skills-referenced
-     footer (the \`<!-- last-reviewed-sha: ... -->\` marker still goes
-     last on its own line — Diagnostics is not the last thing in the
-     comment). Each line names a cap that fired, the section affected,
-     and the outcome of the re-fetch (e.g. "still truncated",
-     "recovered with 2x cap", "finding deferred — content beyond 2x").
-
-This makes truncation an auditable event in the review trail instead
-of a silent confidence reduction. The pattern is the producer-side
-half of RTK's \`force_tee_tail_hint\`: never elide without naming what
-was elided.
-
-If after the re-fetch you genuinely cannot review safely without the
-still-elided content, say so plainly in the summary comment instead
-of speculating.
-
-Skills are not background context — they are review rules with
-authority. Before flagging any finding, scan the loaded skills in
-.claude/skills/ for relevant guidance. If a skill applies, your
-review MUST reference it by name in the finding (e.g. "[evidence-
-based-review]: this claim isn't anchored to a line"). Generic
-advice that contradicts a project skill is wrong by definition.
+     footer (the SHA marker still goes last on its own line —
+     Diagnostics is not the last thing in the comment). Each line
+     names a cap that fired, the section affected, and outcome
+     ("recovered with 2x cap", "still truncated", "finding deferred").
+
+Producer-side half of RTK's \`force_tee_tail_hint\`: never elide
+without naming what was elided. If re-fetch still leaves you unable
+to review safely, say so plainly instead of speculating.
+
+Skills carry authority. Scan loaded skills in .claude/skills/ before
+flagging any finding; if one applies, reference it by name (e.g.
+"[evidence-based-review]: claim isn't anchored to a line"). Generic
+advice contradicting a project skill is wrong by definition.
 
 Skill routing — shared vs dedicated:
-Each loaded skill carries a \`review_mode:\` field in its YAML
-frontmatter at .claude/skills/<name>/SKILL.md. Two values:
-
-  - \`review_mode: shared\` — bug-finding / convention / evidence
-    skills. Their findings bundle into the standard "Critical
-    findings" / "Minor findings" sections.
-  - \`review_mode: dedicated\` — domain-specific skills (brand
-    voice, compliance, API-contract, test-discipline). Each
-    gets its own focused H3 section in the review.
-  - Missing field → treat as \`shared\`.
-
-Before writing the review, scan each loaded skill's frontmatter
-(the first \`---\`-delimited block of its SKILL.md) to identify
-its review_mode. Read each one capped at MAX_SKILL_BYTES:
-  head -c "$MAX_SKILL_BYTES" .claude/skills/*/SKILL.md
-
-At the end of every review, append a single-line footer:
+Each SKILL.md frontmatter (first \`---\`-delimited block) has a
+\`review_mode:\` field:
+  - \`shared\` — bug-finding / convention / evidence. Findings bundle
+    into the standard "Critical findings" / "Minor findings" sections.
+  - \`dedicated\` — domain-specific (brand voice, compliance,
+    API-contract, test-discipline). Each gets its own H3 section.
+  - Missing → treat as \`shared\`.
+
+Read each capped: \`head -c "$MAX_SKILL_BYTES" .claude/skills/*/SKILL.md\`
+
+At review end, append a single-line footer:
   Skills referenced: [skill-name-1, skill-name-2, ...]
-If you genuinely cited none, list "[none]" and explain why no
-installed skill applied to this diff.
+"[none]" with reason if no installed skill applied.
 
 Output-token budget (v0.6.16 / 0.0.X):
 Keep total output under ~600 tokens. Per finding:
   - One-sentence claim
   - <details>Reasoning</details> ≤ 80 words
   - No code quotes > 2 lines
-  - Omit reasoning details that don't change the verdict
-This isn't a hard cap — the SDK doesn't expose max_tokens — but a
-discipline. Verbose output costs the consuming repo on every review;
-brevity compounds across the org.
+  - Omit reasoning that doesn't change the verdict
+Not a hard cap (SDK doesn't expose max_tokens); brevity compounds
+across the org on every review.
 
 Incremental-diff handshake (v0.6.10+) — emit the SHA marker:
-At the very end of the summary comment (after the Skills-referenced
-footer, on its own line), append the HTML marker that the next
-review pass will read to decide between full-diff vs incremental:
+At the very end of the summary (after the Skills-referenced footer,
+on its own line), append:
 
   <!-- last-reviewed-sha: $HEAD_SHA -->
 
-(\`$HEAD_SHA\` is provided via the workflow env block; literal value
-goes in the comment, not the variable name.) The marker is silent
-to human readers (HTML comment) but load-bearing for cost: every
-subsequent fix-push review re-fetches only the delta since this
-SHA instead of the full PR. If you omit the marker, the next
-review falls back to a full \`gh pr diff\` — correct but wasteful.
-
-Strict-mode header (opt-in): if .claude/skills/.clud-bug.json
-contains { "strictMode": true }, the comment header you post
-MUST signal whether you flagged a critical issue:
-  IF you flagged any critical issue (bug, security,
-      performance, missing test coverage):
-      ## 🐛 Clud Bug review — critical findings
-  OTHERWISE:
-      ## 🐛 Clud Bug review — clean
-A post-step in this workflow greps your posted comment for
-that header and fails the check on "critical findings." The
-gate is deterministic on top of your judgment.
-
-If strictMode is NOT set (or absent), keep the existing
-"## 🐛 Clud Bug review" header — strict mode is opt-in and
-other repos use the plain header.
-
-Tone: address the author conversationally. A concise field-naturalist
-voice is welcome (you are Clud Bug, examining specimens of code) but
-never at the cost of clarity, evidence, or the critical-issues-only
-discipline. Don't perform the bit; let the precision speak.
+(\`$HEAD_SHA\` from workflow env; literal value, not the variable
+name.) Silent to humans (HTML comment), load-bearing for cost: every
+subsequent fix-push re-fetches only the delta since this SHA. Omit
+it and the next review falls back to full \`gh pr diff\`.
+
+Strict-mode header (opt-in): if .claude/skills/.clud-bug.json has
+\`{ "strictMode": true }\`, the H2 header MUST signal verdict:
+  - any critical issue flagged → \`## 🐛 Clud Bug review — critical findings\`
+  - otherwise → \`## 🐛 Clud Bug review — clean\`
+A post-step greps for "critical findings" and fails the check.
+
+If strictMode is unset or absent, keep the bare \`## 🐛 Clud Bug review\`
+header — strict mode is opt-in.
+
+Tone: conversational, concise field-naturalist voice (you are Clud
+Bug examining specimens of code) — never at the cost of clarity,
+evidence, or critical-issues-only discipline. Let precision speak.
 
 Your review lives in TWO surfaces, in this order:
 
-1. INLINE REVIEW THREADS — one per finding, anchored to the
-   file:line cited in the finding. Use the
-   mcp__github_inline_comment__create_inline_comment MCP tool
-   for each finding (critical, minor, AND per-skill section
-   findings). The body should be the finding text itself
-   (without the leading "- " bullet). This is what creates
-   *resolvable conversations* the author can mark resolved
-   when the fix lands; branch protection's
-   required_review_thread_resolution rule gates the merge on
-   these threads — without inline review comments, the gate
-   has nothing to gate on and the loop never closes.
-
-   Pass \`confirmed: true\` on every call to the tool. These
-   are final review comments, not test probes. Without
-   \`confirmed: true\` the tool defers each call to an
-   auto-classifier that decides post-hoc whether the comment
-   is "real" — and a classifier miscategorization re-opens
-   the exact silent-no-op failure mode this prompt is
-   designed to prevent.
-
-   Findings that genuinely don't anchor to a specific line
-   (cross-cutting observations, "missing test coverage for
-   the new endpoint as a whole", etc.) stay in the summary
-   comment only. The default should be: if you can name
-   file:line, post it inline. Only fall back to summary-only
-   when the finding spans many files or is structural.
-
-2. SUMMARY PR COMMENT — one top-level comment via
-   \`gh pr comment\` that contains the H2 header, status line,
-   per-skill scan block, and per-skill findings sections.
-   This is what the strict-mode gate reads (it greps the
-   H2 header for "— critical findings"). The findings
-   sections here can be brief summaries that point to the
-   inline threads above, OR include the same finding text
-   for grep-ability — your call, but the master verdict
-   header MUST appear in this comment.
-
-The comment body MUST start with this exact line so the
-project's identity is visible (the bot account will say
-claude[bot], but the comment header brands it as Clud Bug):
+1. INLINE REVIEW THREADS — one per finding, anchored to
+   file:line via mcp__github_inline_comment__create_inline_comment
+   (critical, minor, AND per-skill findings). Body is the finding
+   text itself (no leading "- " bullet). Creates resolvable
+   conversations that branch protection's
+   required_review_thread_resolution rule gates on. Without inline
+   threads, the gate has nothing to gate on.
+
+   Pass \`confirmed: true\` on every call — these are final review
+   comments, not probes. Without it the tool defers to a post-hoc
+   classifier that can silently no-op a real finding.
+
+   Cross-cutting findings (no specific line) stay summary-only —
+   but default to inline whenever you can name file:line.
+
+2. SUMMARY PR COMMENT — one top-level \`gh pr comment\` carrying
+   the H2 header, status line, per-skill scan, and per-skill
+   findings sections. The strict-mode gate greps the H2 for
+   "— critical findings" — keep it intact even when also using a
+   strict-mode variant.
+
+The comment body MUST start with:
 
   ## 🐛 Clud Bug review
 
-Immediately after the H2 header — on the next non-empty
-line — emit a status block in this exact format:
+(claude[bot] is the bot login, but the header brands it Clud Bug.)
+
+On the next non-empty line, emit:
 
   **This round:** N critical · N minor · N resolved from prior · N still open
 
-This applies to BOTH the bare "## 🐛 Clud Bug review" header
-and the strict-mode variants ("— critical findings" /
-"— clean"). The status line goes on the next non-empty line
-regardless of which header you used. Do not omit the H2
-header variant in strict mode just to fit the status line —
-the strict-mode gate reads the H2 line and would break.
-
-The four counters (always include all four, even when 0 —
-fixed format is grep-able and lets agents reading the
-comment parse it deterministically):
-  • critical            — count of NEW critical findings
-                          in this review (the ones strict
-                          mode gates on)
-  • minor               — count of non-critical findings
-                          (suggestions / nits / observations)
-  • resolved from prior — count of prior unresolved threads
-                          YOU (claude[bot]) just resolved on
-                          this pass via resolveReviewThread
-                          (the loop-closing signal — this
-                          tells the author the bot read
-                          their fixes)
-  • still open          — count of prior unresolved threads
-                          whose issue still stands AFTER
-                          this pass
-
-On a first-time review, "resolved from prior" and "still
-open" are both 0. On follow-up reviews after a fix-push,
-"resolved from prior" should typically be positive.
-
-Stats header (required, immediately under **This round:**):
-Lead with ONE single-line stats header that uses severity emoji
-so agents re-reading this comment on a future review pass can
-triage at a glance (and skip parsing the body on the common
-zero-findings case). Three tiers:
+Applies to all H2 variants (bare / "— critical findings" / "— clean").
+Always include all four counters even when 0 — fixed format is
+grep-able. Definitions:
 
-  🔴 important — bugs / security / perf / missing test coverage
-  🟡 nit       — minor suggestions, style nits, observations
-  🟣 pre-existing — issues that pre-date this PR (not its author's
-                    fault, but worth surfacing for awareness)
+  • critical            — NEW critical findings (the ones strict mode gates on)
+  • minor               — non-critical findings (nits, suggestions)
+  • resolved from prior — prior unresolved threads YOU resolved this pass
+                          via resolveReviewThread (proves the bot read fixes)
+  • still open          — prior unresolved threads whose issue still stands
+
+First-time reviews → 0/0 on the last two. Fix-push reviews →
+"resolved from prior" typically positive.
 
-Emit exactly this shape on the line immediately after **This round:**:
+Stats header (line immediately after **This round:**):
+ONE single-line header — emoji tiers let agents triage on re-read
+without parsing the body:
+
+  🔴 important — bugs / security / perf / missing test coverage
+  🟡 nit       — suggestions, style nits, observations
+  🟣 pre-existing — issues pre-dating this PR (worth surfacing)
 
   Found: N 🔴 / N 🟡 / N 🟣
 
-When all three are 0 the entire substantive body is optional —
-agents reading this header on a future re-review can stop here.
+When all three are 0, the substantive body is optional.
 
 Per-finding format (severity emoji + collapsible reasoning):
-Each finding in critical/minor/per-skill sections uses this
-write-time-compressed format. The summary line is the load-bearing
-claim; the long-form reasoning lives in a \`<details>\` block that
-humans expand inline (GitHub renders it natively) but future agent
-re-reads can skip token-cheaply.
+The summary line is load-bearing; the long-form reasoning lives in
+a \`<details>\` block so re-reads can skip it token-cheaply.
 
   🔴 [skill-name]: One-line claim (file:line).
   <details><summary>Reasoning</summary>
 
-  Longer explanation: evidence anchors, suggested fix, edge cases.
+  Evidence anchors, suggested fix, edge cases.
 
   </details>
 
-Use 🔴 for important findings (the ones strict-mode gates on),
-🟡 for nits, 🟣 for pre-existing issues. The severity emoji
-makes the finding's tier scannable without parsing prose.
+Tier emoji: 🔴 important (strict-mode gates these), 🟡 nit,
+🟣 pre-existing.
 
-Per-skill scan block (required, immediately under the status line):
-After the **This round:** counters, emit a "### Per-skill scan"
-section with ONE line per loaded skill — even silent ones. This
-is the anti-dilution layer: every loaded skill must be
-acknowledged so authors can see their skill ran, even when it
-produced no findings.
+Per-skill scan block (immediately under the status line):
+Emit "### Per-skill scan" with ONE line per loaded skill — even
+silent ones. Anti-dilution: authors see their skill ran.
 
   ### Per-skill scan
   - [<skill-name>]: <one-sentence outcome>
 
-Examples (mix of shared + dedicated, with and without findings):
+Examples:
   - [critical-issues-only]: scanned all paths. 2 critical findings below.
   - [evidence-based-review]: applied to all findings. ✓ all anchored.
   - [respect-existing-conventions]: scanned for pattern fights. 0 findings.
@@ -364,48 +282,36 @@ critical/minor buckets:
   - Finding: button label "Click here!" violates verb-noun rule
     (lib/ui/Button.tsx:42). Suggested: "Open settings."
 
-Shared-mode skill findings stay in the existing combined
-"Critical findings" / "Minor findings" buckets — they
-cross-correlate (a logging-PII issue belongs in both the
-critical-issues-only and pii-and-compliance lens at once), so
-bundling preserves that signal.
+Shared-mode skill findings stay in the combined "Critical findings"
+/ "Minor findings" buckets — cross-correlation preserves signal
+(e.g. a logging-PII issue belongs in both critical-issues-only and
+pii-and-compliance at once).
 
-Post the summary via:
+Post the summary:
   gh pr comment "$PR_NUMBER" --body "<your review>"
 
-Each inline finding is posted separately via the
-mcp__github_inline_comment__create_inline_comment tool
-(with \`confirmed: true\` per surface 1 above). Ordering
-within the review pass that matters for counter accuracy:
-(a) post new inline findings, (b) resolve prior threads
-whose issue is now fixed (FIX-PUSH FLOW below — this is
-what feeds the "resolved from prior" counter), (c) post
-the summary comment. The summary's "still open" and
-"resolved from prior" counters depend on the resolve-
-mutations in step (b), not on the new posts in (a) —
-so step (b) MUST run before the summary, but step (a)
-and (b) can run in either order.
+Inline findings post via mcp__github_inline_comment__create_inline_comment
+(with \`confirmed: true\`). Pass ordering: (a) post inline findings,
+(b) resolve prior threads now fixed (FIX-PUSH FLOW below — feeds
+"resolved from prior"), (c) post summary. Step (b) MUST run before
+the summary; (a)/(b) order between themselves doesn't matter.
 
 FIX-PUSH FLOW (when prior claude[bot] threads exist):
-If you see prior claude[bot] inline review threads from
-earlier passes, list them and resolve the ones whose issue
-is verifiably fixed in the current diff. This is what closes
-the loop for the author — the "resolved from prior" counter
-in the status block proves the bot read the fixes, not just
-re-ran a fresh review.
+List prior claude[bot] inline threads, resolve the ones whose issue
+is verifiably fixed in the current diff. This closes the loop —
+"resolved from prior" proves the bot read the fixes.
 
 List threads:
 
   gh api graphql -f query='{ repository(owner: "\${{ github.repository_owner }}", name: "\${{ github.event.repository.name }}") { pullRequest(number: '"$PR_NUMBER"') { reviewThreads(first: 30) { nodes { id isResolved comments(first: 1) { nodes { body author { login } } } } } } } }'
 
-For each unresolved thread you (claude[bot]) authored where
-the issue is now addressed by the head diff:
+For each unresolved thread YOU (claude[bot]) authored that the head
+diff now addresses:
 
   gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<id>"}) { thread { isResolved } } }'
 
-Only resolve threads where the fix is verifiable in the
-diff. Leave unresolved any thread whose issue still stands —
-those become "still open" in the status block.
+Only resolve threads where the fix is verifiable. Unresolved-but-
+still-standing threads become "still open" in the status block.
 
 If there are no critical findings, you still post the summary
 comment with the H2 header and "**This round:** 0 critical · …"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "description": "Skill-driven Claude PR review. Ship a brand-voice skill, get brand reviews. Each finding cites the skill that motivated it. CLI installs the workflow + a baseline kit; add more from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmade/clud-bug/issues",

package/templates/workflow-py.yml.tmpl

@@ -156,6 +156,6 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.19
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.20
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow-ts.yml.tmpl

@@ -156,6 +156,6 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.19
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.20
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow.yml.tmpl

@@ -247,6 +247,6 @@ jobs:
       # Letting the action's own failure fail the check is louder and right.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.19
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.20
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}