clud-bug 0.5.12 → 0.5.14

package/README.md

@@ -3,9 +3,11 @@
 
 > **[cludbug.dev](https://cludbug.dev)** · live field journal.
 
-Clud Bug is a Claude PR-review naturalist for your GitHub repo. It pins **project-aware skills** auto-discovered from [skills.sh](https://skills.sh) and ships a baseline kit of review discipline so reviews stay focused on what matters: bugs, security, performance, and missing tests.
+Clud Bug is **skill-driven PR review** for your GitHub repo. Ship a brand-voice skill, get brand reviews. Ship a compliance skill, get PII checks on every diff. Each finding cites the skill that motivated it — the bot's authority comes from your specimens, not from generic advice.
 
-One command to install. The first PR you open afterwards gets a real review comment back — typically within two minutes.
+Four baseline skills ship by default — covering bug-finding, evidence-based review discipline, pattern conformity, and agent coordination. Add more from [skills.sh](https://skills.sh) or write your own — the bot loads them automatically.
+
+One command to install. The first PR you open afterwards gets a real review back — typically within two minutes.
 
 ## Quickstart
 

package/lib/skills.js

@@ -457,7 +457,20 @@ export function extractPerSkillLine(comment, skillName) {
 export function selectReviewHeader(comments, botLogin) {
   if (!Array.isArray(comments)) return null;
   if (typeof botLogin !== 'string' || !botLogin) return null;
-  for (const c of comments) {
+  // Sort newest-first by created_at. The composite passes the result of
+  // `gh api .../comments?sort=created&direction=desc` — but GitHub's
+  // REST issue-comments endpoint ignores `direction=desc` and returns
+  // ascending (oldest first) regardless. PR #64 caught this: the gate
+  // was selecting the OLDER "— critical findings" comment instead of
+  // the newer "— clean" follow-up, so fix-push reviews that resolved
+  // critical findings still failed the gate. Explicit sort here makes
+  // selection deterministic regardless of upstream API quirks.
+  const sorted = [...comments].sort((a, b) => {
+    const ta = a?.created_at ? Date.parse(a.created_at) : 0;
+    const tb = b?.created_at ? Date.parse(b.created_at) : 0;
+    return tb - ta; // newest first
+  });
+  for (const c of sorted) {
     if (!c || typeof c !== 'object') continue;
     const author = c.user?.login;
     const body = c.body;
@@ -496,7 +509,16 @@ export function extractFirstReviewHeaderLine(body) {
 export function selectReviewBody(comments, botLogin) {
   if (!Array.isArray(comments)) return null;
   if (typeof botLogin !== 'string' || !botLogin) return null;
-  for (const c of comments) {
+  // Same explicit newest-first sort as selectReviewHeader — gh api
+  // ignores direction=desc on issue-comments and returns ascending,
+  // so without this BB.3 was parsing per-skill outcomes from the
+  // OLDEST review comment, not the latest. See selectReviewHeader.
+  const sorted = [...comments].sort((a, b) => {
+    const ta = a?.created_at ? Date.parse(a.created_at) : 0;
+    const tb = b?.created_at ? Date.parse(b.created_at) : 0;
+    return tb - ta;
+  });
+  for (const c of sorted) {
     if (!c || typeof c !== 'object') continue;
     const author = c.user?.login;
     const body = c.body;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clud-bug",
-  "version": "0.5.12",
-  "description": "Claude PR review with project-aware skills. CLI installs a working GitHub Actions workflow and curates skills from skills.sh.",
+  "version": "0.5.14",
+  "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/thrillmot/clud-bug/issues",
   "type": "module",

package/templates/workflow-py.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v6
+# clud-bug-template-version: v8
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -125,7 +125,45 @@ jobs:
             never at the cost of clarity, evidence, or the critical-issues-only
             discipline. Don't perform the bit; let the precision speak.
 
-            When you finish, post your review as a single PR comment.
+            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):
@@ -198,30 +236,51 @@ jobs:
             critical-issues-only and pii-and-compliance lens at once), so
             bundling preserves that signal.
 
-            Post it via:
+            Post the summary via:
               gh pr comment "$PR_NUMBER" --body "<your review>"
 
-            If you previously reviewed this PR (you'll see prior claude[bot]
-            comments starting with "## 🐛 Clud Bug review"), resolve your
-            prior unresolved inline review threads where the flagged issue
-            is fixed in the current diff. List threads:
+            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.
+
+            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 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:
+            For each unresolved thread you (claude[bot]) authored where
+            the issue is now addressed by the head diff:
 
               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.
-            For line-specific issues, use the github_inline_comment MCP tool
-            with confirmed: true.
-            If there are no critical issues, post a one-line comment saying so.
+            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.
+
+            If there are no critical findings, you still post the summary
+            comment with the H2 header and "**This round:** 0 critical · …"
+            status line — strict mode + the status counters need the
+            comment to exist for every review pass.
 
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.12
+        uses: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.13
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow-ts.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v6
+# clud-bug-template-version: v8
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -126,7 +126,45 @@ jobs:
             never at the cost of clarity, evidence, or the critical-issues-only
             discipline. Don't perform the bit; let the precision speak.
 
-            When you finish, post your review as a single PR comment.
+            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):
@@ -199,30 +237,51 @@ jobs:
             critical-issues-only and pii-and-compliance lens at once), so
             bundling preserves that signal.
 
-            Post it via:
+            Post the summary via:
               gh pr comment "$PR_NUMBER" --body "<your review>"
 
-            If you previously reviewed this PR (you'll see prior claude[bot]
-            comments starting with "## 🐛 Clud Bug review"), resolve your
-            prior unresolved inline review threads where the flagged issue
-            is fixed in the current diff. List threads:
+            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.
+
+            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 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:
+            For each unresolved thread you (claude[bot]) authored where
+            the issue is now addressed by the head diff:
 
               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.
-            For line-specific issues, use the github_inline_comment MCP tool
-            with confirmed: true.
-            If there are no critical issues, post a one-line comment saying so.
+            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.
+
+            If there are no critical findings, you still post the summary
+            comment with the H2 header and "**This round:** 0 critical · …"
+            status line — strict mode + the status counters need the
+            comment to exist for every review pass.
 
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.12
+        uses: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.13
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v6
+# clud-bug-template-version: v8
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -148,7 +148,45 @@ jobs:
             never at the cost of clarity, evidence, or the critical-issues-only
             discipline. Don't perform the bit; let the precision speak.
 
-            When you finish, post your review as a single PR comment.
+            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):
@@ -221,26 +259,47 @@ jobs:
             critical-issues-only and pii-and-compliance lens at once), so
             bundling preserves that signal.
 
-            Post it via:
+            Post the summary via:
               gh pr comment "$PR_NUMBER" --body "<your review>"
 
-            If you previously reviewed this PR (you'll see prior claude[bot]
-            comments starting with "## 🐛 Clud Bug review"), resolve your
-            prior unresolved inline review threads where the flagged issue
-            is fixed in the current diff. List threads:
+            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.
+
+            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 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:
+            For each unresolved thread you (claude[bot]) authored where
+            the issue is now addressed by the head diff:
 
               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.
-            For line-specific issues, use the github_inline_comment MCP tool
-            with confirmed: true.
-            If there are no critical issues, post a one-line comment saying so.
+            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.
+
+            If there are no critical findings, you still post the summary
+            comment with the H2 header and "**This round:** 0 critical · …"
+            status line — strict mode + the status counters need the
+            comment to exist for every review pass.
 
       # Strict-mode gate. Fails the check when the BASE ref's manifest
       # has { "strictMode": true } AND the latest clud-bug review's first
@@ -257,6 +316,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: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.12
+        uses: thrillmot/clud-bug/.github/actions/strict-mode-gate@v0.5.13
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}