@bompus/house-rules 0.13.0 → 0.14.1

package/README.md

@@ -1,14 +1,22 @@
 <h1 align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.png">
-    <img src="docs/assets/banner-light.png" alt="house-rules" width="100%">
+    <img src="docs/assets/banner-light.png" alt="house-rules: Working rules and skills for AI coding agents" width="100%">
   </picture>
 </h1>
 
 <p align="center">
   <a href="https://github.com/bompus/house-rules/actions/workflows/check.yml"><img src="https://github.com/bompus/house-rules/actions/workflows/check.yml/badge.svg" alt="CI status"></a>
-  <a href="https://github.com/bompus/house-rules/releases/latest"><img src="https://img.shields.io/github/v/release/bompus/house-rules" alt="Latest release"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/bompus/house-rules" alt="MIT license"></a>
+  <a href="https://github.com/bompus/house-rules/releases/latest"><img src="https://badgen.net/github/release/bompus/house-rules" alt="Latest GitHub release"></a>
+  <a href="https://www.npmjs.com/package/@bompus/house-rules"><img src="https://badgen.net/npm/v/@bompus/house-rules" alt="Latest npm version"></a>
+  <a href="LICENSE"><img src="https://badgen.net/badge/license/MIT/blue" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="rules/core.md">Core rules</a>&nbsp;·
+  <a href="#modifiers">Opt-in modifiers</a>&nbsp;·
+  <a href="#writing-your-own-sections">Your own layer</a>&nbsp;·
+  <a href="examples/project/AGENTS.md">Each repo's AGENTS.md</a>
 </p>
 
 A practical starting point for ordinary development with AI coding agents.
@@ -291,7 +299,7 @@ changing the configuration.
 | `hr-ordering-tests`         | Enumerate event orderings through the real code to find race bugs.                                        |
 | `hr-plain-prose`            | Make text people read plain and specific.                                                                 |
 | `hr-progress-report`        | Report current task activity, milestone completion and remaining wall-clock time.                         |
-| `hr-pr-followup`            | Address conflicts, feedback and failing checks for a PR; honor landing authority; CodeRabbit review gate. |
+| `hr-pr-followup`            | Address conflicts, feedback and failing checks for a PR; landing authority; CodeRabbit and cubic gate.    |
 | `hr-read-reddit`            | Read Reddit feed output while supported; RSS support ends November 13, 2026. Partial web-search fallback. |
 | `hr-read-x-links`           | Read the full content of X posts.                                                                         |
 | `hr-research-shared-links`  | Research a shared link or repository in depth, compare it with your setup and rate each idea.             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bompus/house-rules",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Composable working rules and skills for AI coding agents",
   "homepage": "https://github.com/bompus/house-rules#readme",
   "license": "MIT",

package/rules/references/github-actions.md

@@ -8,6 +8,38 @@ Give jobs finite timeouts. Cancel an older pull-request run only when a newer
 run for the same pull request covers the same required checks; preserve required
 default-branch and release evidence.
 
+### Cancel superseded pull-request runs
+
+Key the `concurrency` group on the workflow and the pull request number, and
+cancel only for pull-request events:
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
+
+- Concurrency groups are shared by every workflow in the repository, so keep a
+  value unique to the workflow in the key. `github.workflow` is the workflow's
+  name, so it is unique only while workflow names are; otherwise use a fixed
+  prefix. Without a unique value, one workflow's run can cancel another's.
+- Keep the pull-request key stable across pushes: never a commit SHA or run ID
+  for a pull-request run, which differs on every push, so nothing is cancelled.
+  A workflow that runs only on pull requests can use `cancel-in-progress: true`.
+  A reusable workflow inherits the caller's `github.workflow`, so give caller and
+  callee different keys.
+- Cancellation needs a newer run in the same group. When a path filter means a
+  push starts no run, the older run finishes. Add a cleanup workflow only when
+  run history shows older runs finishing after pushes that started no
+  replacement; it must not check out pull-request code.
+- To skip checks on draft pull requests, add `github.event.pull_request.draft != true`
+  to each check job's `if`, including reusable-workflow callers and aggregate
+  jobs. A job guard stops a runner being allocated; a step guard does not. Add
+  `ready_for_review` and `converted_to_draft` to the `pull_request` types, so
+  checks start when review begins and a replacement run can cancel old work.
+  Use this only when the repository's policy says draft pull requests do not
+  need these checks.
+
 ### Choose the concurrency boundary
 
 Independent jobs can run on separate runners. A job's steps normally run in

package/rules/references/release-batching.md

@@ -15,6 +15,16 @@ or readiness condition in the task plan. Backlog items do not authorize
 implementation or landing. Do not hold a ready batch for unrelated, unapproved
 or indefinite work.
 
+Before any decision to publish, check every package for commits past its latest
+release tag, and recommend a new release first when there are any. This covers
+public and private packages alike, and a republish of an existing tag, which
+ships the tagged content without the later commits. State how many commits are
+unreleased and what they change, and name the version the repository's scheme
+gives the combined changes. A package that has never been tagged has no
+baseline, so say that and treat the publish as its first release. The
+recommendation is not permission to tag, publish or announce, and it does not
+hold a ready batch for unrelated work.
+
 Before any release or public announcement, audit every public-facing
 material against the intended revision or artifact and current verified state:
 the README and package READMEs, comparisons, performance metrics, graphics and

package/rules/references/squash-landing.md

@@ -19,8 +19,8 @@ the review body too: findings outside the diff arrive there, not as threads.
 Let an enabled automatic review start; do not comment to request one. When none
 starts, check the integration's status instead of tagging the bot again. A bot's
 config file in the repository does not show that it is enabled, and an existing
-check on the head must report completion before you merge (for CodeRabbit, a
-successful status whose description starts with "Review completed").
+check on the head must report completion before you merge. A skipped or
+cancelled review is not a completed one.
 
 During integration, never switch, reset or remove the session's own checkout: no
 `checkout` or `switch` to another ref, no `reset` or branch force-move, and no

package/skills/hr-pr-followup/SKILL.md

@@ -55,8 +55,8 @@ Name the exact revision, failed or unfinished gates and unresolved decisions.
 Clean CI alone is not evidence that every review finding was handled.
 
 When the repository or user selects these GitHub helper policies, use
-[the CodeRabbit review gate and one-thread resolver](references/review-helpers.md).
-Its review-status checks cover CodeRabbit only; its thread check covers any
+[the CodeRabbit and cubic review gate and one-thread resolver](references/review-helpers.md).
+Its review-status checks cover CodeRabbit and cubic only; its thread check covers any
 reviewer and its review-body check any bot. It does not replace other required
 checks or the caller's judgment. The same reference describes the landing helper scripts (`merge-pr.sh`,
 `verify-landed.sh`, `check-landing.py`).

package/skills/hr-pr-followup/references/review-helpers.md

@@ -14,12 +14,26 @@ bun scripts/check-pr-review.ts 123 --repo OWNER/REPO
 
 The gate exits 0 when its selected feedback checks pass, 1 for open feedback,
 and 2 when coverage cannot be verified. It checks unresolved threads, pending
-CodeRabbit review, skipped review statuses and a missing check when the head
-contains `.coderabbit.yaml`. It also checks bot review bodies with outside-diff,
-nitpick or duplicate findings. A completed CodeRabbit CheckRun must conclude SUCCESS;
-failed, cancelled, skipped or missing conclusions block the gate. A CodeRabbit status also requires SUCCESS
-and a description starting with "Review completed". It does not
-check every CI result or authorize landing.
+CodeRabbit or cubic review, skipped review statuses and a missing check when
+the head contains `.coderabbit.yaml`. It also checks bot review bodies with
+outside-diff, nitpick or duplicate findings. A completed CodeRabbit CheckRun
+must conclude SUCCESS; failed, cancelled, skipped or missing conclusions block
+the gate. A CodeRabbit status also requires SUCCESS and a description starting
+with "Review completed"; that is how the gate tests the general squash rule that an
+existing review check must report completion. It does not check every CI result or
+authorize landing.
+
+The check named exactly "cubic · AI code reviewer" on the head commit is held to the
+same rule: while it runs, the gate refuses, and a completed one must conclude
+SUCCESS. A NEUTRAL or skipped conclusion means cubic did not review the head
+("Incremental review could not start", "Automatic AI review not started after
+branch rewrite", "AI review line limit reached"), so the gate refuses it too.
+That pull request stays blocked until someone comments `@cubic review` or the
+limit clears, and the refusal says so. A head commit with no cubic check is not blocked,
+because cubic's `cubic.yaml` is optional and its absence does not show that cubic is
+expected. `--wait` does not wait for a cubic check that has not posted yet.
+In a repository that uses cubic, confirm right after a push that its check has appeared
+before landing.
 
 If a review is missing or incomplete, inspect the integration and the repository's
 review policy. The helper does not determine automatic-review enablement or
@@ -42,7 +56,7 @@ judges whether the explanation answers the findings.
 Connections are paginated. Partial responses, malformed fields, repeated
 cursors and head changes fail closed. A final head read does not make review
 feedback an atomic snapshot. `--wait --timeout 30` polls only while CodeRabbit
-runs, or briefly while its expected check has not appeared.
+or cubic runs, or briefly while CodeRabbit's expected check has not appeared.
 
 ## Resolve one review thread
 

package/skills/hr-pr-followup/scripts/check-pr-review.ts

@@ -1,16 +1,22 @@
 #!/usr/bin/env bun
 // Refuses to land a pull request while review feedback is open: an unresolved review thread, a
-// review bot (CodeRabbit) whose check is still running, or a bot review whose body carries findings
+// review bot (CodeRabbit or cubic) whose check is still running, or a bot review whose body carries findings
 // GitHub cannot show as threads ("Outside diff range comments", "Nitpick comments", "Duplicate comments") with no human
 // explicit acknowledgement for that review and the current head. Run only when the repository
 // selects this gate. It also refuses when CodeRabbit's status on the
 // head commit says anything but "Review completed": CodeRabbit marks a skipped review (for example
 // on a non-default base) as success with "Review skipped: …". When the head commit has
-// `.coderabbit.yaml` but no CodeRabbit check, it refuses too. Missing or incomplete reviews
+// `.coderabbit.yaml` but no CodeRabbit check, it refuses too. A cubic check ("cubic · AI code
+// reviewer") on the head commit must also complete with SUCCESS: a running one refuses, and so does
+// any other conclusion, NEUTRAL and skipped included, because NEUTRAL means cubic did not review the
+// head ("Incremental review could not start", "AI review line limit reached"). That PR stays blocked
+// until someone comments `@cubic review` or the limit clears. A head commit with no cubic check is
+// not blocked, since cubic's `cubic.yaml` is optional and its absence does not show that cubic
+// is expected, and --wait does not wait for one to appear. Missing or incomplete reviews
 // require inspection of the review integration and the repository's selected review policy.
 //   bun scripts/check-pr-review.ts <pr> [--repo <owner>/<name>] [--wait [--timeout <minutes>]]
 // Exit 1 while feedback is open, 2 when gh fails. Without --repo, gh resolves the repository from
-// the current checkout. --wait polls every 30 s while CodeRabbit's review is still running, and for
+// the current checkout. --wait polls every 30 s while CodeRabbit's or cubic's review is still running, and for
 // up to 3 minutes while the head commit has no CodeRabbit check yet (CodeRabbit posts it a little
 // after a push), then reports as usual; after --timeout minutes (default 30) it reports what is
 // still open.
@@ -30,13 +36,17 @@
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 
-const REVIEW_BOTS = /coderabbit/i;
+const CODERABBIT = /coderabbit/i;
+const CUBIC = /^cubic · AI code reviewer$/i;
+const isReviewBot = (name: string) => CODERABBIT.test(name) || CUBIC.test(name);
 const REVIEW_BOT_CONFIG = ".coderabbit.yaml";
 const BODY_FINDINGS = /Outside diff range comments|Nitpick comments|Duplicate comments/;
 const REVIEWED = /^Review completed/;
 const FOLLOW_UP = "check the review integration and repository review policy";
 const RUNNING = "review still running: ";
 const NO_CHECK = "no CodeRabbit check on the head commit";
+// A neutral cubic result means it did not review the head; a person has to ask again.
+const CUBIC_RETRY = "comment `@cubic review` or wait for its limit to clear";
 const POLL_MS = 30_000;
 const NO_CHECK_GRACE_MS = 180_000;
 
@@ -364,25 +374,26 @@ export function openFeedback(pr: ReviewState): string[] {
   const head = pr.commits.nodes[0]?.commit;
   const contexts = head?.statusCheckRollup?.contexts.nodes ?? [];
   const hasConfig = head?.tree.entries.some((e) => e.name === REVIEW_BOT_CONFIG) ?? false;
-  if (hasConfig && !contexts.some((ctx) => REVIEW_BOTS.test(ctx.context ?? ctx.name ?? ""))) {
+  if (hasConfig && !contexts.some((ctx) => CODERABBIT.test(ctx.context ?? ctx.name ?? ""))) {
     open.push(`${NO_CHECK}: ${FOLLOW_UP}`);
   }
   for (const ctx of contexts) {
     const name = ctx.context ?? ctx.name ?? "";
     const running =
       ctx.state === "PENDING" || (ctx.status !== undefined && ctx.status !== "COMPLETED");
-    if (!REVIEW_BOTS.test(name)) {
+    if (!isReviewBot(name)) {
       continue;
     }
     if (running) {
       open.push(`${RUNNING}${name}`);
     } else if (ctx.name !== undefined && ctx.conclusion !== "SUCCESS") {
+      const retry = CUBIC.test(name) ? `; ${CUBIC_RETRY}` : "";
       open.push(
-        `${name} review concluded ${ctx.conclusion ?? "(missing conclusion)"}: ${FOLLOW_UP}`,
+        `${name} review concluded ${ctx.conclusion ?? "(missing conclusion)"}: ${FOLLOW_UP}${retry}`,
       );
     } else if (
       ctx.context !== undefined &&
-      (ctx.state !== "SUCCESS" || !REVIEWED.test(ctx.description ?? ""))
+      (ctx.state !== "SUCCESS" || (CODERABBIT.test(name) && !REVIEWED.test(ctx.description ?? "")))
     ) {
       open.push(
         `${name} did not review the head commit ("${ctx.description ?? ""}"): ${FOLLOW_UP}`,