@clipboard-health/ai-rules 2.29.10 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.29.10",
+  "version": "2.31.0",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/skills/cb-babysit/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: cb-babysit
+description: Watch a PR through CI and review feedback. Auto-fix high-confidence failures and address review comments. Use when the user says 'babysit <PR>' or 'respond to PR comments'.
+argument-hint: "[pr-number-or-url]"
+---
+
+## Setup
+
+The user invokes this skill with an optional PR number or URL. Parse in this order and stop at the first match:
+
+1. **Full PR URL**: if the user's text contains `https?://github\.com/[^/\s]+/[^/\s]+/pull/\d+`, capture the URL.
+2. **Explicit PR token**: match `(?:PR|pr|pull request)\s*#?(\d+)` or a bare `#(\d+)` in the user's text.
+3. **Bare numeric argument**: only when the complete text is a positive integer without surrounding prose.
+4. **None of the above**: operate on the PR for the current branch.
+
+Resolve bundled "./scripts" paths relative to SKILL.md.
+
+## Sentinels
+
+The skill uses two sentinels with visible footer lines.
+
+**Addressed sentinel**: `<sub>🤖 <code>cb-babysit:addressed v1 core@3.12.0</code></sub>`. Appended on its own line at the end of every reply the skill posts so re-runs know which threads and review-body comments are already handled. Dedupe also recognizes the legacy `babysit-pr:addressed v1` prefix from before this skill was renamed.
+
+**Follow-up sentinel**: `<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>`. Attached to replies that defer an out-of-scope comment as a tracked follow-up. The sentinel is additive: the post-reply scripts still append the `addressed` sentinel at the end.
+
+**Sentinel recency rules.** The script emits a per-thread `activityState` with three values. Step 6a owns the handling rules for each state.
+
+- **`active`**: no sentinel yet, OR at least one human commented after the last sentinel.
+- **`uncertain`**: a sentinel exists AND one or more bot comments appeared after it. The thread carries a `postSentinelBotComments` array listing EVERY such comment.
+- **`addressed`**: the sentinel is the newest relevant activity on the thread.
+
+Automated review bodies and top-level Conversation-tab comments each carry a stable `fingerprint` (sha256 of the normalized body); prior sentinel bodies embed them, and steps 4 and 7 do the dedupe.
+
+## Workflow
+
+### 1. Preflight
+
+```bash
+git status --short
+```
+
+If non-empty, classify the dirty files against the target PR's changed paths (`gh pr diff --name-only`):
+
+- Any dirty file overlaps the PR's surface, or you cannot confidently classify → stop and report. The skill never starts where it might sweep up related in-progress work.
+- All dirty files are clearly unrelated (disjoint paths, pre-existing edits) → stash exactly those files by name with a labeled stash (`git stash push -m "cb-babysit: pre-existing unrelated work (auto-restored)" -- <paths>`), proceed, and `git stash pop` as the final step of the pass, including on early exits. Report the stash/restore in the summary.
+
+If a PR number or URL was parsed from inputs, check out that PR now:
+
+```bash
+gh pr checkout <pr-number-or-url>
+```
+
+If the command fails, stop and report.
+
+### 2. Locate the PR
+
+```bash
+gh pr view --json number,url,headRefName,statusCheckRollup,mergeable,mergeStateStatus 2>/dev/null
+```
+
+If no PR exists for the current branch, stop and report.
+
+#### Resolve merge conflicts, if any
+
+If `mergeable == "CONFLICTING"` (or `mergeStateStatus == "DIRTY"`), merge the base into the PR branch locally:
+
+```bash
+BASE=$(gh pr view --json baseRefName --jq .baseRefName)
+git fetch origin "$BASE"
+git merge --no-edit "origin/$BASE"
+```
+
+Resolve directly only for lockfile/generated regenerations, additive non-overlapping edits, or trivial textual conflicts in PR-touched files. `git merge --abort` for anything semantic, ambiguous, or outside the PR's intentional surface, and skip to step 10 to exit **stuck** with a diagnosis. After a clean resolution, commit the merge and `git push origin HEAD`.
+
+### 3. Wait for CI
+
+Wrap the watch call with a timeout so a hung check doesn't wedge the turn:
+
+```bash
+rc=0
+if command -v gtimeout >/dev/null 2>&1; then
+  gtimeout 600 gh pr checks --watch || rc=$?
+elif command -v timeout >/dev/null 2>&1; then
+  timeout 600 gh pr checks --watch || rc=$?
+else
+  gh pr checks --watch || rc=$?
+fi
+case $rc in 0|1|8|124) ;; *) exit $rc;; esac
+```
+
+Exit codes 0 (pass), 1 (fail), 8 (pending), and 124 (timeout) are expected and handled next. Other codes (auth errors, etc.) re-raise.
+
+### 4. Fetch review data
+
+```bash
+bash scripts/unresolvedPrComments.sh
+```
+
+The output JSON has:
+
+- `threads`: every unresolved review thread, with `threadId`, `replyToCommentDatabaseId`, `comments[]`, `lastBabysitSentinelAt`, `lastHumanCommentAt`, `lastBotCommentAt`, `postSentinelBotComments[]`, `postSentinelHumanComments[]`, and `activityState` (`"active"` / `"uncertain"` / `"addressed"`).
+- `activeThreads`: threads where `activityState != "addressed"`; these need attention this pass (active AND uncertain).
+- `uncertainThreads`: just the uncertain subset. For each, read EVERY entry in `postSentinelBotComments` before deciding.
+- `reviewBodyComments`: every review from a known automated reviewer (CodeRabbit, Mendral, Dependabot, etc.), with the raw body and a stable per-review `fingerprint`. The agent reads each body directly to extract findings.
+- `issueComments`: every top-level Conversation-tab comment, each with `isBabysitSentinel`, `isKnownBot`, and a per-comment `fingerprint`.
+- `activeIssueComments`: the subset of `issueComments` that are NOT cb-babysit sentinels, NOT from a known bot, and whose `fingerprint` is NOT already listed in any prior cb-babysit summary. These are the human Conversation-tab comments still needing a reply.
+- `priorBabysitSentinels`: prior cb-babysit summary comments posted as PR issue-comments. The script does the dedupe lookup for `activeIssueComments` automatically; the agent uses this array for `reviewBodyComments` dedupe.
+- `truncated`: array naming any GraphQL connection that hit GitHub's 100-item cap (`reviewThreads`, `thread-comments`, `reviews`, `issueComments`). Non-empty means some comments may not be in this JSON; surface this in the final summary.
+- `totalActiveThreads`, `totalUncertainThreads`, `totalActiveIssueComments`, `totalReviewBodyComments`, `totalUnresolvedComments` for quick checks.
+
+### Scope
+
+This PR's review-feedback scope is strict by default. Steps 6a (threads), 6b (top-level conversation comments), and 7 (automated review bodies) classify each comment as in-scope or out-of-scope using this rule before choosing a verdict. Step 5 (CI) uses the broader CI-scope rule in that step, not this one. CI can legitimately fail on unchanged lines because the PR changed a contract or dependency path.
+
+Build the changed-line set from `gh pr diff` once per pass. Count changed diff lines on both sides: added lines in the new version, removed lines in the old version, and modified code represented by adjacent remove/add pairs. Do not count diff context lines. A reviewer comment or automated review-body comment is **in scope** when its anchor falls on a changed diff line on either side of the hunk. Deleted-line comments like "why remove this?" or "please add this back" are in scope by definition. For a range like `12-14`, any overlap with a changed diff line is in scope.
+
+When matching review comments to hunks, use the anchor line provided by `unresolvedPrComments.sh`; it may be the current `line` or the script's fallback to `originalLine`. Compare that anchor against both new-side added ranges and old-side removed ranges.
+
+Comments on unchanged/context lines, touched files outside changed lines, or untouched files are **out of scope by default**.
+
+Narrow escape hatch: treat an unchanged/context-line comment as in scope only when there is an explicit external signal that this PR caused or requires the issue. Acceptable signals:
+
+- The reviewer explicitly ties the concern to this PR's change.
+- The comment points to an unchanged line directly used by a changed diff line, and you can name the changed `file:line` that creates the coupling.
+- CI, test, or typecheck output proves the PR changed the contract or behavior for the symbol, API, or execution path named by the comment.
+
+If you cannot name one of those signals, classify the comment as out of scope. Do not use broad judgment phrases like "related", "nearby", "maintainability", or "review confidence" to widen scope.
+
+Default posture: focus on in-scope feedback. For out-of-scope feedback, apply the fix **only** if it meets the out-of-scope bar below. Otherwise defer with a follow-up reply.
+
+**Out-of-scope fix bar** (apply the fix even though it's out of scope):
+
+- Security vulnerability, data loss, or crash in the PR's execution path.
+- Obvious correctness bug (wrong output, broken invariant) confirmed by reading the referenced code.
+- One-line or trivial change that obviously cannot regress anything (typo, missing null check matching surrounding style, etc.).
+
+**All other out-of-scope fix requests → Defer**: post a Defer reply tagged with the follow-up sentinel (see step 9). Do not expand the PR. Defer is specifically for "this is a real but out-of-scope ask we are choosing not to act on here."
+
+### 5. Handle CI failures
+
+Run `bash scripts/fetchFailedLogs.sh` to stream failed output for every failing check on the PR. The first line is either:
+
+- `# cb-babysit: no failing checks` → skip to step 6a.
+- `# cb-babysit: failing checks` → followed by one delimited block per failing job or external check:
+  - `# --- run=<id> job=<id> ---` blocks carry the job's `--log-failed` output (GitHub Actions).
+  - `# --- external check: <name> (<url>) ---` blocks carry no logs, the check isn't a GitHub Actions run (e.g., Nx Cloud, semgrep, CodeRabbit). Treat these like "External checks with no inspectable logs" in the diagnosis-only list below: stop and report, don't guess a fix.
+
+Read the logs and diagnose: **build/type errors first** (they cause cascading test failures), then lint/format, then tests.
+
+**Apply a fix directly** only when the cause is high-confidence and inside the PR's changed surface:
+
+- Compile/type errors in files the PR touched.
+- Deterministic lint/format violations.
+- Tests that the PR broke by renaming/removing symbols they reference.
+- Missing test updates for intentional behavior changes.
+
+**Stop and report a diagnosis** (do not guess a fix) for:
+
+- Flaky/intermittent failures.
+- Infrastructure or provider outages.
+- Permission/auth/missing-secret failures.
+- Unrelated failures (touching code this PR didn't modify).
+- Ambiguous test intent.
+- External checks with no inspectable logs.
+
+Scope check for CI: scope is the PR's changed files plus failures directly caused by those changes in the PR's execution path. Use `gh pr diff --name-only` as the first signal. Allow fixes outside changed files only when the logs and code make causality clear (e.g., the PR renamed a symbol that a sibling test references). CI failures outside that surface are out of scope. Report the diagnosis, don't apply speculative fixes. CI fixes are never Deferred as follow-ups: CI needs to pass on this PR.
+
+### 6a. Assess active review threads
+
+For every thread in `activeThreads` (this includes both `"active"` and `"uncertain"`):
+
+- Group comments by file; read each file once (not per comment).
+- If the referenced file no longer exists, record "comment may be outdated" and classify as **Already fixed**.
+- If `activityState == "uncertain"`, read EVERY entry in `postSentinelBotComments` (not just the newest):
+  - If EVERY entry is a non-actionable acknowledgement (e.g., `"Thanks, resolved"`, `"LGTM"`, `"Learnings added"`) → mark the thread **Skip-reply** (the existing sentinel already covers the thread; posting again would be noise). Do not classify it Agree/Disagree/Already-fixed. Record this in the final summary so the skip is visible.
+  - If ANY entry carries new actionable content (new nit, new finding, corrected diagnosis) → treat the thread as new feedback and proceed below. Note in the final summary that an uncertain thread was reactivated, citing the specific comment.
+  - If you cannot confidently classify every entry → default to treating it as new feedback.
+- Each remaining thread (i.e., NOT marked Skip-reply) gets a scope classification first. Use the Scope subsection to label it in-scope or out-of-scope. For comments on deleted lines, record that the anchor is on the removed side of the diff. For any unchanged/context-line comment classified in scope via the narrow escape hatch, record the external signal and the changed `file:line` when applicable.
+- Then pick one verdict; each of these (except Skip-reply) will get a reply posted in step 9:
+  - **In-scope** threads use the original three verdicts:
+    - **Agree**: the comment identifies a real issue. Apply the fix. Record the thread ID and a one-line what-changed.
+    - **Disagree**: the current code is acceptable. Record a short reasoning.
+    - **Already fixed**: a prior commit addresses the concern. Record a pointer (commit SHA, file:line).
+  - **Out-of-scope** threads apply the out-of-scope fix bar from the Scope subsection:
+    - Meets the bar → **Agree** (apply the fix, and note in the reply that it was fixed despite being out of scope because it met the bar).
+    - Does not meet the bar → **Defer** (new verdict). Record a one-line rationale and, if relevant, a pointer to where the concern lives.
+    - Disagree and Already-fixed can still apply to out-of-scope comments (e.g., reviewer asks for a refactor that's already landed on main, or misreads the code).
+
+### 6b. Assess top-level Conversation-tab comments
+
+For every entry in `activeIssueComments`, humans commenting on the PR Conversation tab without anchoring to a file/line:
+
+- Apply the **Scope** subsection's rules. A top-level comment is in scope when the reviewer explicitly ties it to a changed file/line, behavior the PR introduced, or a contract the PR altered. Otherwise out of scope by default.
+- Pick a verdict the same way as a thread: Agree / Disagree / Already fixed (in-scope), or Agree-meets-bar / Defer (out-of-scope). Apply fixes for Agree verdicts.
+- Replies are NOT posted as individual top-level comments. That would clutter the conversation. Instead, every issue-comment verdict goes into the **same step-9 PR-level summary** as the review-body findings, under its own `## Conversation-tab comments` heading. Per-comment fingerprints join the fenced fingerprint block so future runs dedupe.
+- If `activeIssueComments` is empty AND `reviewBodyComments` is empty (or all dedupe), skip the PR-level summary comment entirely in step 9.
+
+### 7. Assess automated review bodies
+
+For every entry in `reviewBodyComments`:
+
+- Dedupe first: if its `fingerprint` already appears in any `priorBabysitSentinels[].body`, skip; already covered.
+- Otherwise, READ THE BODY IN FULL. Automated reviewers (CodeRabbit, Mendral, etc.) pack findings into nested `<details>/<blockquote>` HTML with file paths, line ranges, and titles inline. Identify each individual finding the body contains.
+- For each finding, **classify scope** (in / out) using the Scope subsection. For ranges like `12-14`, any overlap with changed diff lines on either side of the hunk is in scope; no overlap is out of scope unless one of the explicit escape-hatch signals applies.
+- Pick a verdict per finding:
+  - In-scope → Agree / Disagree / Already fixed (as with threads). If Agree, apply the fix.
+  - Out-of-scope → apply the out-of-scope fix bar. Meets the bar → Agree and apply the fix, noting in the summary that it was fixed despite being out of scope. Does not meet the bar → **Defer**. A Deferred finding does not get its own top-level comment; it goes into the summary under the **Deferred (out of scope)** heading (see step 9).
+
+The whole-body `fingerprint` (not per-finding) goes in the fenced fingerprint block at the end of the summary. If the review body later changes (new findings, edits), the fingerprint changes and the next pass will post the summary again. It's slightly noisier but never silently drops a new finding.
+
+If `reviewBodyComments` is empty (or all entries dedupe), skip ONLY the review-body section of the summary in step 9. Still post thread replies for every non-Skip-reply thread from step 6a and handle issue comments per step 6b.
+
+### 8. Commit and push (if any edits)
+
+If steps 5, 6, or 7 modified any files, decide:
+
+- **Which files are yours this pass.** The worktree may contain unrelated in-progress work. Only stage files this pass touched. If in doubt, run `git diff --name-only` and pick from that list deliberately.
+- **A focused commit message.** Prefer something like `cb-babysit: <one-line what-changed>`; the project's commitlint expects conventional-commit form, so a `fix(core): ...` or `docs(core): ...` prefix is usually right.
+
+Then run:
+
+```bash
+bash scripts/commitAndPush.sh "<message>" <file1> [<file2> ...]
+```
+
+The script enforces explicit staging (never `git add -A`), never skips hooks, and prints:
+
+```text
+sha=<commit-sha>
+url=https://github.com/<owner>/<repo>/commit/<sha>
+```
+
+Capture the `url=` line for the reply templates in step 9.
+
+### 9. Post replies
+
+For every thread assessed in step 6a that was NOT marked **Skip-reply** (i.e., one of Agree / Disagree / Already fixed / Defer):
+
+```bash
+bash scripts/postSentinelReply.sh "$THREAD_ID" "$BODY"
+```
+
+Skip-reply threads are left alone as the existing sentinel already covers them.
+
+Body templates (the script appends the `addressed` sentinel if missing):
+
+- **Agree**: `Addressed in <commit-url>. <one-line what-changed>.`
+- **Disagree**: `Leaving current behavior. <reasoning>.`
+- **Already fixed**: `Already handled by <commit-url-or-file:line>. <brief pointer>.`
+- **Defer**: `Out of scope for this PR; this looks like follow-up work rather than something introduced or required by this change. <one-line rationale or pointer if useful>.\n\n<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>`
+
+For Defer replies, include the follow-up sentinel on its own line as shown. The script will append the `addressed` sentinel after it on its own line, so the final body ends with the follow-up sentinel followed by a blank line followed by the `addressed` sentinel. `grep cb-babysit:followup` finds the deferral and `grep cb-babysit:addressed` still marks the thread handled for dedupe.
+
+The script uses the `addPullRequestReviewThreadReply` GraphQL mutation. It does NOT resolve the thread.
+
+If any automated review bodies were assessed in step 7 OR any active issue comments were assessed in step 6b, post ONE top-level PR comment summarizing all of them:
+
+```bash
+bash scripts/postSentinelPrComment.sh "$PR_NUMBER" "$BODY"
+```
+
+The PR-level summary should:
+
+- Group by source. Use `## Review-body findings` for step-7 work and `## Conversation-tab comments` for step-6b work. Omit a section if its list is empty.
+- Inside each section, group verdicts under **Agree / Disagree / Already fixed / Deferred (out of scope)** subheadings. Omit a subheading if its list is empty.
+- Under **Deferred (out of scope)**, list each deferred item as a bullet, followed on its own line by `<sub>🤖 <code>cb-babysit:followup v1 core@3.12.0</code></sub>` so grep catches them individually.
+- Include the commit URL for fixes.
+- End with a fenced fingerprint block listing every current fingerprint (addressed and deferred) one per line. Include both `reviewBodyComments[].fingerprint` (whole-body, one per automated review) and `activeIssueComments[].fingerprint` (per Conversation-tab comment). Future runs dedupe by matching these against `priorBabysitSentinels`.
+
+### 10. Summarize
+
+Report:
+
+- Commits made (with URLs).
+- Merge conflict status if relevant (resolved or aborted with reason).
+- CI checks fixed / still failing / skipped-with-diagnosis.
+- Review threads replied to, grouped by verdict (including any Defer count: "X threads deferred as follow-ups").
+- Conversation-tab comments addressed, grouped by verdict (e.g. "Z conversation comments deferred as follow-ups").
+- Review-body findings summarized (or skipped because already covered), including the Deferred count: "Y review-body findings deferred as follow-ups".
+- Threads left active because of bot-acknowledgement uncertainty (flag by thread URL).
+- If `truncated` is non-empty: explicitly call out which connection hit GitHub's 100-item GraphQL cap (e.g. "`truncated: ['thread-comments']`, at least one review thread has more than 100 comments; this pass may have missed the tail. Investigate before relying on it for completeness.").
+- The stop condition triggered for this pass (clean / progressing / stuck).
+
+When the report mentions any deferrals, include a one-liner the user can run later to enumerate them, e.g.:
+
+```bash
+gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){pullRequest(number:$n){reviewThreads(first:100){nodes{comments(first:50){nodes{body url}}}}comments(first:100){nodes{body url}}}}}' -F o=<owner> -F r=<repo> -F n=<pr> | grep -B1 cb-babysit:followup
+```
+
+Do not rely only on `gh pr view --json comments,reviews`. That view can miss inline review-thread replies, which is where most Defer replies live.
+
+## Loop control
+
+After the single pass completes, pick exactly one outcome:
+
+- **Exit clean**: all CI checks passed AND every thread in `activeThreads` was either marked Skip-reply during step 6a's inspection or has already received a fresh sentinel reply in this pass (Agree / Disagree / Already-fixed / **Defer** all count. A Defer reply is a sentinel reply), AND every entry in `activeIssueComments` is covered by this pass's PR-level summary, AND every current review-body fingerprint is covered by an existing sentinel comment (deferred review-body and conversation-comment fingerprints count; they're in the summary's fenced block). Do not use raw `totalActiveThreads` / `totalActiveIssueComments` from the script output. They're pre-inspection and will stay non-zero for Skip-reply or post-summary cases. A PR with Deferred items is still clean from babysit's perspective: the skill has done what it can without widening scope. Report success and stop.
+- **Exit progressing**: pass made commits, posted new replies, or both, and the PR is not yet clean (CI is still pending, a new CI run was triggered by this pass's commits, or more work remains). There is real work still in flight that another run would pick up. Report what was done and what is pending, and tell the user to re-run `/cb-babysit` once CI settles, or to wrap the call with `/loop <cadence> /cb-babysit` (or a shell `while true; do ...; done`) for automatic re-runs.
+- **Exit stuck**: pass made no commits and posted no new replies, and the PR is still not clean. Nothing actionable happened this pass. Use this whenever progress is blocked on something outside the skill's scope, including:
+  - Merge conflict in step 2 that exceeded the high-confidence resolution bar.
+  - CI still running (`gh pr checks --watch` timed out with pending checks).
+  - CI failing with a diagnosis-only verdict from Step 5 (flaky / infra / auth / external check / ambiguous / out-of-scope failure).
+  - Only Skip-reply threads remained AND CI was already red or pending.
+
+  Report the specific blocker (pending vs. diagnosed-failure, with the diagnosis text) and tell the user to investigate or re-run once state may have changed.
+
+This skill never waits or repeats internally.

package/skills/{babysit-pr → cb-babysit}/scripts/_sentinel.sh

@@ -4,12 +4,13 @@
 #
 # SENTINEL is the literal emitted on new replies: a visible footer (robot mark +
 # token in `<code>`, wrapped in `<sub>`). SENTINEL_PREFIX is the wrapper-free
-# substring used for matching/dedupe, so it matches both this footer and legacy
-# `<!-- babysit-pr:addressed v1 ... -->` sentinels. The `core@X.Y.Z` suffix is
-# substituted at build time by embedPluginVersion.mts.
+# substring used for matching/dedupe. LEGACY_SENTINEL_PREFIX keeps old
+# `babysit-pr:addressed v1` comments from being reprocessed after the rename.
+# The `core@X.Y.Z` suffix is substituted at build time by embedPluginVersion.mts.
 
-SENTINEL_PREFIX='babysit-pr:addressed v1 '
-SENTINEL='<sub>🤖 <code>babysit-pr:addressed v1 core@3.10.1</code></sub>'
+SENTINEL_PREFIX='cb-babysit:addressed v1 '
+LEGACY_SENTINEL_PREFIX='babysit-pr:addressed v1 '
+SENTINEL='<sub>🤖 <code>cb-babysit:addressed v1 core@3.12.0</code></sub>'
 
 # Bot author allowlist (JSON array literal). Used by unresolvedPrComments.sh
 # as a fallback when GraphQL's `author.__typename == "Bot"` misses a GitHub
@@ -18,11 +19,11 @@ SENTINEL='<sub>🤖 <code>babysit-pr:addressed v1 core@3.10.1</code></sub>'
 BOTS_JSON='["coderabbitai","coderabbitai[bot]","mendral-app","mendral-app[bot]","dependabot","dependabot[bot]","github-actions","github-actions[bot]","github-advanced-security","github-advanced-security[bot]","renovate","renovate[bot]","renovate-bot","pre-commit-ci","pre-commit-ci[bot]","codecov","codecov[bot]","sonarcloud","sonarcloud[bot]"]'
 
 # Echo $1 with SENTINEL appended on its own trailing paragraph, unless the
-# body already contains any version of the sentinel (matched via SENTINEL_PREFIX).
+# body already contains any version of the sentinel.
 ensure_sentinel() {
   local body="$1"
   case "$body" in
-    *"$SENTINEL_PREFIX"*) printf '%s' "$body" ;;
+    *"$SENTINEL_PREFIX"* | *"$LEGACY_SENTINEL_PREFIX"*) printf '%s' "$body" ;;
     *) printf '%s\n\n%s' "$body" "$SENTINEL" ;;
   esac
 }

package/skills/{babysit-pr → cb-babysit}/scripts/fetchFailedLogs.sh

@@ -5,9 +5,9 @@
 #   pr-number: optional; defaults to the PR on the current branch.
 #
 # Output (plain text on stdout). First line is either:
-#   # babysit-pr: no failing checks
+#   # cb-babysit: no failing checks
 # or:
-#   # babysit-pr: failing checks
+#   # cb-babysit: failing checks
 # followed by one delimited block per failing job:
 #   # --- run=<id> job=<id> ---
 #   <log body>
@@ -16,10 +16,9 @@
 # first line). Exit 1 on infrastructure errors (gh missing, not authed, no PR).
 # Exit 2 on usage errors.
 #
-# Filter uses `bucket == "fail"` (gh CLI's normalized lowercase field) instead
-# of `.conclusion` because the two gh APIs disagree on case —
-# `gh pr view --json statusCheckRollup` returns UPPER (GraphQL enum),
-# `gh run view --json jobs` returns lower (REST). `bucket` sidesteps it.
+# Failing-check detection normalizes `bucket`, `.conclusion`, and `.state`
+# because gh's PR GraphQL and Actions REST payloads expose different fields and
+# casing, and some status contexts have a null `bucket`.
 #
 # Requires: gh, jq.
 
@@ -74,7 +73,7 @@ FAILING_RAW="$(printf '%s' "$ROLLUP" \
     ')"
 
 if [ -z "$FAILING_RAW" ]; then
-  echo "# babysit-pr: no failing checks"
+  echo "# cb-babysit: no failing checks"
   exit 0
 fi
 
@@ -98,7 +97,7 @@ $FAILING_RAW
 EOF
 RUN_IDS="$(printf '%s\n' $RUN_IDS | sort -u | tr '\n' ' ')"
 
-echo "# babysit-pr: failing checks"
+echo "# cb-babysit: failing checks"
 
 for RUN_ID in $RUN_IDS; do
   for JOB_ID in $(gh run view "$RUN_ID" --json jobs \

package/skills/{babysit-pr → cb-babysit}/scripts/postSentinelPrComment.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # postSentinelPrComment.sh — Post a top-level PR comment (used for nitpick summaries).
-# Appends the babysit-pr sentinel if missing.
+# Appends the cb-babysit sentinel if missing.
 #
 # Usage: bash postSentinelPrComment.sh <pr-number> <body>
 #

package/skills/{babysit-pr → cb-babysit}/scripts/postSentinelReply.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # postSentinelReply.sh — Post a threaded reply to a PR review thread.
-# The body MUST end with the babysit-pr sentinel; this script enforces that.
+# The body MUST end with the cb-babysit sentinel; this script enforces that.
 # Does NOT resolve the thread — that stays with the human.
 #
 # Usage: bash postSentinelReply.sh <thread-id> <body>

package/skills/{babysit-pr → cb-babysit}/scripts/unresolvedPrComments.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# unresolvedPrComments.sh — Fetch review data for babysit-pr.
+# unresolvedPrComments.sh — Fetch review data for cb-babysit.
 #
 # Returns one JSON document with:
 #   - threads / activeThreads / uncertainThreads — review threads with
@@ -10,10 +10,10 @@
 #   - issueComments — every top-level PR conversation comment, tagged with
 #     isBabysitSentinel and isKnownBot flags.
 #   - activeIssueComments — non-sentinel, non-bot issue comments whose
-#     per-comment fingerprint is NOT already listed in any prior babysit-pr
+#     per-comment fingerprint is NOT already listed in any prior cb-babysit
 #     summary. These are the human Conversation-tab comments needing a reply.
 #   - priorBabysitSentinels — issue comments whose body contains the
-#     babysit-pr sentinel prefix. Used for review-body + issue-comment dedupe.
+#     cb-babysit sentinel prefix. Used for review-body + issue-comment dedupe.
 #   - truncated — array naming any GraphQL connection that hit GitHub's
 #     100-item cap (reviewThreads, thread-comments, reviews, issueComments).
 #     Agent must surface this in the final summary.
@@ -258,9 +258,9 @@ main() {
   #   - postSentinelHumanComments: ARRAY of every human comment after the sentinel
   #   - activityState: "active" / "uncertain" / "addressed"
   local threads_json
-  threads_json="$(printf '%s' "$response" | jq --arg sentinel_prefix "$SENTINEL_PREFIX" --argjson bots "$BOTS_JSON" '
+  threads_json="$(printf '%s' "$response" | jq --arg sentinel_prefix "$SENTINEL_PREFIX" --arg legacy_sentinel_prefix "$LEGACY_SENTINEL_PREFIX" --argjson bots "$BOTS_JSON" '
     def is_bot: ((.author.__typename // "") == "Bot") or ((.author.login // "") | IN($bots[]));
-    def is_sentinel: ((.body // "") | contains($sentinel_prefix));
+    def is_sentinel: ((.body // "") | contains($sentinel_prefix) or contains($legacy_sentinel_prefix));
     [
       .data.repository.pullRequest.reviewThreads.nodes[]
       | select(.isResolved == false)
@@ -416,8 +416,8 @@ main() {
 
   # All issue comments (top-level Conversation-tab comments).
   local raw_issue_comments
-  raw_issue_comments="$(printf '%s' "$response" | jq --arg sentinel_prefix "$SENTINEL_PREFIX" --argjson bots "$BOTS_JSON" '
-    def is_sentinel_body: ((.body // "") | contains($sentinel_prefix));
+  raw_issue_comments="$(printf '%s' "$response" | jq --arg sentinel_prefix "$SENTINEL_PREFIX" --arg legacy_sentinel_prefix "$LEGACY_SENTINEL_PREFIX" --argjson bots "$BOTS_JSON" '
+    def is_sentinel_body: ((.body // "") | contains($sentinel_prefix) or contains($legacy_sentinel_prefix));
     def is_bot_author: ((.author.__typename // "") == "Bot") or ((.author.login // "") | IN($bots[]));
     [
       .data.repository.pullRequest.comments.nodes[]
@@ -443,12 +443,12 @@ main() {
 
   # Concatenate prior sentinel bodies into one blob — used as a haystack for
   # fingerprint dedupe (both review-body and issue-comment fingerprints land
-  # in the fenced block at the end of a babysit-pr summary).
+  # in the fenced block at the end of a cb-babysit summary).
   local prior_sentinel_blob
   prior_sentinel_blob="$(printf '%s' "$prior_sentinels" | jq -r '[.[].body] | join("\n")')"
 
   # activeIssueComments: non-sentinel, non-bot comments whose fingerprint is
-  # NOT already listed in any prior babysit-pr summary.
+  # NOT already listed in any prior cb-babysit summary.
   local active_issue_comments
   active_issue_comments="$(printf '%s' "$issue_comments" | jq --arg blob "$prior_sentinel_blob" '
     [.[]

package/skills/cb-ship/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: cb-ship
+description: Ship changes. Simplify the diff, commit, push, and open or update a PR. Use when the user says 'ship it', 'commit and push', or wants a PR created or updated.
+argument-hint: "[--draft]"
+---
+
+## Setup
+
+- If `gh auth status` fails, stop and tell the user.
+- If `git rev-parse --verify origin/HEAD` fails, `origin/HEAD` is unset. Stop and tell the user to run `git remote set-head origin -a`.
+- If `git status --short`, `git log --oneline origin/HEAD..HEAD`, and `gh pr view --json url --jq .url 2>/dev/null` are all empty, stop and reply "nothing to ship."
+
+Resolve bundled "./references" paths relative to SKILL.md.
+
+## Workflow
+
+1. Create a new branch if on the default branch (e.g., `feat/add-user-validation`, `fix/null-check-in-parser`).
+2. Use ./references/simplify.md on the full PR diff: `git diff $(git merge-base HEAD origin/HEAD)..HEAD` and any uncommitted changes.
+3. Inspect `git status --short`, identify intended files, ask if ambiguous, then git add them. If uncommitted changes, create a conventional commit with `git commit --no-gpg-sign`.
+4. Push changes to origin.
+5. Create or update the PR using ./references/pr-template.md:
+   a. If the host exposes a session ID (e.g., CODEX_THREAD_ID, CLAUDE_CODE_SESSION_ID), include the resume command in the PR body in backticks: ``Agent session: `codex resume <id>` `` or ``Agent session: `claude --resume <id>` ``. Preserve existing `Agent session:` lines, append only.
+   b. If a PR exists, update the title and body if the new changes aren't reflected.
+   c. Otherwise, create one with `gh pr create`; make it a draft if the user passed `--draft`.
+6. Output:
+
+   ```plaintext
+   - Directory: [Absolute path]
+   - Branch: [Branch name]
+   - Session: [Resume command from 5a] (omit if none)
+   - PR: [Complete url] (e.g., `https://github.com/clipboardhealth/core-utils/pull/123`)
+   ```

package/skills/cb-ship/references/pr-template.md

@@ -0,0 +1,21 @@
+## Title
+
+Conventional commit type and description with no scope, followed by the issue tracker ID in parentheses if you can derive it from the branch name or session context (e.g., `feat: add resume command (STAFF-123)`).
+
+## Body
+
+```md
+## Summary
+
+Concisely explain the user intent from session history and the meaningful behavior/system change.
+
+## Validation
+
+- List proof of validation: commands, screenshots, telemetry, Loom, or `Not run: <reason>`.
+
+## Notes
+
+Optional, don't fabricate: ticket links, rollout plan, residual risk, or specific areas for reviewers to focus.
+
+<sub>🤖 <code>cb-ship:created v1 core@3.12.0</code></sub>
+```

package/skills/cb-ship/references/simplify.md

@@ -0,0 +1,50 @@
+# Simplify
+
+If the host supports it, launch three review agents concurrently, passing each the full diff. Otherwise, perform the reviews inline.
+
+## Agents
+
+### 1: Code reuse review
+
+Review each change:
+
+1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase. Common locations are utility directories, shared modules, library monorepos `cbh-core` and `core-utils`, and files adjacent to the changed ones.
+2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.
+3. **Flag any inline logic that could use an existing utility.** Hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.
+
+### 2: Code quality review
+
+Review each change for hacky patterns:
+
+1. **Redundant state** that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls.
+2. **Parameter sprawl**: Adding new parameters to a function instead of generalizing or restructuring existing ones.
+3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction. Exempt intentional, structurally-parallel repetition that aids readability — test arrange/act/assert blocks are the common case.
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries.
+5. **Premature abstraction (YAGNI)**: an interface, wrapper, or config object introduced for a single caller — inline it until a second caller justifies it.
+6. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase.
+7. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value. Check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior.
+8. **Nested conditionals**: ternary chains (`a ? x : b ? y : ...`), nested if/else, or nested switch 3+ levels deep. Flatten with early returns, guard clauses, a lookup table, or an if/else-if cascade.
+9. **Unnecessary comments**: Delete comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller. Keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds).
+10. **Defensive code on trusted inputs**: null/empty/type guards on inputs already guaranteed upstream (a validated DTO, the type system, a controller that already checked), optional chaining where the types guarantee presence, fallbacks that mask bugs (`?? ''`, `|| []`, `?? 0` on values that should never be absent), and try/catch that only logs and rethrows or guards an impossible state. Leave guards at genuine trust boundaries (raw request bodies, webhook payloads, third-party responses) and any error handling around real I/O, network, parsing, or payments — removing those changes behavior.
+11. **Type escapes**: `as any`, `: any`, `as unknown as X`, gratuitous non-null `!`, `@ts-ignore`/`@ts-expect-error` added to dodge a type error — replace with the real type when it is determinable from the call site, the imported type, or the shape in use; if it is not, leave it and flag it rather than deleting it (breaks the build) or swapping in a TODO (more clutter).
+12. **Dead & leftover code**: unreachable branches and stray debug statements (`console.log`/print-style output) — delete outright rather than commenting out; keep intentional logging that goes through the repo's logger. Unused exports/symbols with no remaining references are already covered by `.rules/common/typeScript.md`'s Dead Code Cleanup rule.
+
+### 3: Efficiency review
+
+Review each change for:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns.
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel.
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths.
+4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally. Add a change-detection guard so downstream consumers aren't notified when nothing changed. If a wrapper function takes an updater/reducer callback, verify it honors same-reference returns (or whatever the "no change" signal is), otherwise callers' early-return no-ops are silently defeated.
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern); operate directly and handle the error.
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks.
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one.
+
+## Fix issues
+
+Once all three reviews are complete, aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on.
+
+## Validate fixes
+
+Find validation commands in, e.g., `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, or pre-commit/pre-push hooks and fix any failures.

package/skills/cb-work/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: cb-work
+description: Implement a plan file or direct request end-to-end, validate, and ship via cb-ship. Use when the user says 'implement the plan' or clearly wants a change implemented and shipped.
+argument-hint: "[--draft] [plan path or implementation request]"
+---
+
+## Setup
+
+- **Path-like input** (absolute or relative): Resolve the path. If it doesn't resolve to a readable file, stop and tell the user. Do not reinterpret a missing path as a direct request.
+- **Natural-language request**: Treat as the implementation task.
+- **No argument**: Ask for either a plan path or the implementation request.
+
+## Prepare
+
+Unless instructed otherwise:
+
+- Create and `cd` into a git worktree based on a freshly fetched `origin/HEAD` using the host's worktree mechanism if it has one; use a descriptive branch name (e.g., `feat/add-user-validation`, `fix/null-check-in-parser`).
+- Install dependencies according to repo docs and detected lock files, e.g., `npm ci`.
+
+## Implement
+
+The plan or request is the source of truth for scope:
+
+- Make exactly the changes requested, no extra refactors or cleanup.
+- On any drift from the plan (e.g. referenced files or utilities missing, an assumption invalid, a constraint missed) stop and report. Do not silently rewrite the approach.
+- Do not modify the plan file itself unless asked.
+
+Run the relevant checks after each meaningful unit of work, not only at the end.
+
+## Validate
+
+If the plan names specific checks, use those; skip clearly slow or CI-only suites. Otherwise find validation commands in, e.g., `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, or pre-commit/pre-push hooks.
+
+Done when every check passes or the user has explicitly accepted a failure.
+
+## Hand off
+
+Invoke the `cb-ship` skill, passing `--draft` if it was passed to this skill. Relay `cb-ship`'s reply to the user.