@bompus/house-rules 0.11.0 → 0.13.0

package/rules/modifiers/low-quota-handoff.md

@@ -10,9 +10,10 @@ Check your remaining usage allowance at session start or resume, after a model
 switch and before substantial new work, using a reading the host shows or the
 user reports. When a fresh reading shows the current session's provider and
 model with less than 5% of its daily, weekly or monthly allowance left, use the
-`hr-handoff` skill to checkpoint the work. Another model being low, context size
-and token totals do not trigger it. When no reliable reading is available, say
-once that detection is unverified; never guess a low balance or poll for one.
+`hr-handoff` skill to checkpoint the work. Another model being low, context size,
+token totals and five-hour limits do not trigger it. When no reliable reading
+is available, say once that detection is unverified; never guess a low balance,
+poll for one, spend model turns on it or read credentials to get it.
 
 This handoff is a stop under § End of every reply: after saving it, end the
 reply with the handoff report and its recorded next action, which serve as the

package/rules/modifiers/model-default-questions.md

@@ -0,0 +1,33 @@
+---
+description: Leave how questions are asked to your host and model, with no text-only or question-card instruction.
+replaces: Offers
+---
+
+## Offers
+
+Ask for decisions the way your host and model normally ask questions. For each
+decision, explain what would change and why it matters to the user, then
+recommend an option. Put the option you recommend first marked "(Recommended)"
+and use § Finishing work to select displayed candidates. Add any other alternative
+only when the user raised it or leaving it out hides a real trade-off, and mark
+it "(Not Recommended)".
+
+A recommendation in prose without options is not an offer. When an option
+produces a change (code, a document, a pull request), say what it changes and which steps it includes,
+such as the pull request, review, landing and cleanup. Also say what it leaves
+for a later offer. Choosing it authorizes that scope, and asking about it
+authorizes nothing.
+
+An option that creates a rule, skill, document or script also names the owning
+repository, whether any project could use it unchanged, and what you searched.
+
+Recommend the option that finishes the work properly and holds up over time,
+not the one that is quickest to finish. When that work comes in dependent steps
+(land a change, then adopt it), show each step as its own option labeled
+"(Recommended, phase 1)", "(Recommended, phase 2)"; offer phase 2 after phase 1
+lands. Do not present a required step as an optional alternative, and mark an
+alternative that drops required work from the plan "(Not Recommended)".
+
+When three or more offers are open and unanswered, present no further offer.
+Load the `hr-what-next` skill and queue every new decision in its walk-through,
+one line each.

package/rules/modifiers/multi-agent.md

@@ -21,8 +21,12 @@ constraints. Put mechanically enforceable standards in tooling; reserve style
 and judgment for review. The user's direction is the judgment backstop when
 no second reviewer runs. An advisor model is not a second review.
 
-After review, fix findings and run relevant checks. A logic change permits a
-follow-up review but does not require one. Request it only for a named risk
+After review, treat each finding as a claim. Fix it when a reproduced failure
+(a test that fails before the fix, where one fits) or a cited requirement
+confirms it, with the smallest change that clears it; a reviewer's proposed
+remedy is a suggestion. Answer an unconfirmed finding with the reason. Run
+relevant checks. A logic change permits a follow-up review but does not
+require one. Request it only for a named risk
 local checks cannot resolve. Record its scope and round limit first; further
 fixes do not reset that limit. At the limit, get the user's direction before
 another model round. Required repository checks and review gates still apply.

package/rules/modifiers/no-attribution.md

@@ -1,5 +1,5 @@
 ---
-description: Commits, pull requests and comments carry no agent or tool credit lines.
+description: Commits, pull requests and comments carry no agent or tool credit lines unless the target repository asks for a disclosure.
 after: Writing
 ---
 
@@ -8,3 +8,9 @@ after: Writing
 Commits, pull requests, issues and comments carry no agent or tool credit: no
 "Generated with" lines, no `Co-Authored-By` agent trailers, no "Made with"
 footers. Where a host has a setting that turns attribution off, set it.
+
+When the target repository's contribution guidelines or pull request template
+ask for agent or model disclosure, give exactly what they ask for, where they
+ask for it, and nothing beyond it. If models are asked for, name each that did
+the work; one in a higher published tier of the same provider that reviewed or
+advised goes first (Opus reviewing Sonnet: Opus, Sonnet); else in work order.

package/rules/modifiers/periodic-updates.md

@@ -0,0 +1,25 @@
+---
+description: A job expected to run longer than about 10 minutes posts a short status update every 5 minutes by default, with progress, an ETA with its basis or "unmeasured", and findings so far, until the job ends; a watcher event that changes nothing gets at most one line.
+after: Reporting
+---
+
+## Periodic status updates
+
+A job expected to run longer than about 10 minutes gets a status update on its
+own schedule, without the user asking. So does a job that has run that long with
+no estimate. This covers a build, test suite, benchmark, CI run, long search or
+similar. The default interval is 5 minutes. That figure is a default, not a
+measured value; use the interval the user names instead.
+
+Each update is one short line, not a report, posted even when nothing has
+changed. It gives completed/total or a percent (the current step when the job
+reports no total), the ETA with its basis or the word "unmeasured", and a
+one-line summary of findings so far. A milestone, failure, stall or change in
+the forecast goes in full instead.
+
+Where the host can run a background watcher or timer, arm it to post the
+updates and to report in full only a milestone, failure, stall, forecast change
+or the run's completion. A watcher event that changes nothing gets at most one
+line. Otherwise post at the first natural checkpoint after each interval has
+passed, when a step finishes or a tool call returns. Stop the updates when the
+job ends; the final report replaces them.

package/rules/modifiers/plan-files.md

@@ -1,6 +1,7 @@
 ---
 description: Multi-step work keeps a visible task list mirrored to a plan file with a ledger of every item's outcome.
 after: Durable notes
+requires: hr-handoff, hr-what-next
 ---
 
 ## Task tracking
@@ -19,15 +20,24 @@ turn up, and use the same item states in both. At each reconciliation event in
 the plan or handoff that owns an item instead of copying it; a handoff points
 at its plan.
 
+When you rebuild a ledger or inventory from an earlier one, carry
+each open or deferred line over as an item, marked done with its outcome
+when it has closed. Several lines may share one item only when the same next
+action and completion evidence satisfy every line. A summary row such as "the
+rest, reopen only if asked" loses them. The `hr-handoff` skill's `scripts/check-reconciliation.mjs` checks that
+every such line maps to an item when the earlier plan is named as a source; it
+does not judge the outcome.
+
 - Head the plan with `Owner:` (session name, or `none` for a shared backlog)
   and `Status:` (`active`, `paused`, `blocked-on-user`, `completed`); update both
-  when they change.
+  when they change. Add `Purpose:` with the session's purpose in one sentence
+  (§ Session purpose).
 - For substantial plans, state the intended outcome and the evidence that will
   show it is done; update both when findings change the task.
 - When new work arrives mid-task, add it as pending before switching; never
   drop an in-progress item silently.
 - Keep the whole ledger in the plan: deferred items, follow-ups and incidental
-  findings with a one-line disposition (`user-flagged`, `deferred-by`,
+  findings with a one-line reason (`user-flagged`, `deferred-by`,
   `blocked-by`, `low priority`), and closed items with their outcome (landed
   commit, won't do and why, moved elsewhere) and start and end times. Note the
   start time when you pick an item up.
@@ -38,9 +48,31 @@ at its plan.
   changes and drops. Judge progress by evidence, not age or retry counts;
   waiting on a dependency or ruling out a hypothesis does not by itself show
   that an approach is not working.
+- Keep the ledger as a `## Ledger` section of item lines a script can read:
+  `- [ ] text` is open, `- [~] text … trigger: <what reopens it>` deferred,
+  `- [x] text … evidence: <result>` done and `- [-] text … by: <who dropped it>`
+  dropped (`by: user, not selected` for an option the user passed over). Name
+  each scratch directory, checkout and branch you own in an item. Write each
+  follow-up as an item, not as a sentence elsewhere in the plan.
+- An item that waits on another thread (an upstream issue or pull request, a
+  maintainer, another session) carries `recheck: YYYY-MM-DD`, because a
+  trigger such as "maintainer replies" does not fire by itself. A question you
+  send to another thread is an open item that names where the reply will
+  arrive and carries a `recheck:` date. On that date, look at the thread,
+  record what you found, and set a new date or close the item.
+- Before claiming that nothing remains or the session can close, and before
+  archiving a plan, run the `hr-what-next` skill's
+  `scripts/check-open-work.mjs <plan>`, adding `--checkout <path>` for each
+  checkout you touched and `--repo <owner/repo>` when items name pull requests
+  or issues by number alone, and quote its result. Open or deferred items, and owned
+  resources no open item names, mean work remains. Check each item it lists as
+  possibly finished or due for a re-check, and update its line.
 - Before archiving a completed plan, save its completed status, completion
   time and evidence. Apply § Finishing work before marking the whole session
-  completed. Then move the plan to `plans/archive/<topic>-<date>/` beside it.
+  completed. Then archive with the same script's `--archive` flag; it moves the
+  plan to `plans/archive/<topic>-<date>/` beside it only when the status is
+  completed and nothing is open. A plan whose status is `active`, `paused` or
+  `blocked-on-user` stays where the session-start read finds it.
 
 Sweep other sessions' plans and handoffs only when the user asks, such as
 "what's waiting on me?", and only for the current project. Offer unowned items,

package/rules/modifiers/release-batching.md

@@ -9,5 +9,7 @@ reference: ../references/release-batching.md
 Landing does not authorize publishing. Follow the repository's release requirements.
 Before preparing or publishing a release or public announcement, read
 [the release procedure](../references/release-batching.md), including its factual
-accuracy audit. Do not publish with unresolved accuracy blockers or expand scope
-to new benchmarks.
+accuracy audit and changelog audit. Run the accuracy audit on every public
+repository's version bump and the changelog audit on every version bump, before
+the first publish step, and land their corrections first. Do not publish with
+unresolved accuracy blockers or expand scope to new benchmarks.

package/rules/modifiers/shared-host-load.md

@@ -1,48 +1,19 @@
 ---
-description: Coordinate shared local work within host-defined resource budgets; isolate measurements and release reservations during remote waits.
+description: On a shared machine, follow its resource budgets; without one, get operator direction before parallel workers or whole-repository commands, and use memory controls.
 after: Coordination and isolation
 ---
 
 ## Shared machine load
 
-When local work shares a host, follow its declared CPU, memory and I/O budgets
-and admission procedure. Before resource-intensive builds, tests or tools,
-check current load and running jobs. Choose concurrency and memory controls
-within that budget, accounting for interactive use of the machine.
-
-Classify each local phase and its actual commands, hooks and children. A phase
-is resource-intensive when its expected CPU, memory or I/O demand exceeds the
-host's concurrent-work budget.
-
-Before calling demand unknown, inspect the command, its applicable hooks,
-wrappers and children. When inspection establishes bounded demand within existing
-host limits and the active measurement's light-work allowance, proceed without
-fresh benchmark-owner permission, a collector or a measurement receipt.
-Inspection is sufficient qualification; missing resource samples alone is not
-a blocker. Use the host's admission procedure when inspection cannot establish
-that the complete invocation fits the host's budget and any active measurement's
-light-work allowance. Admit the complete invocation when its children
-need admission, and retain required hooks. This resource permission does not
-lift checkout ownership, shared-write serialization, named input freezes or
-explicit operation-specific user restrictions. A retained benchmark lock alone
-does not suspend permitted light work.
-
-Without a budget or qualification procedure, get
-operator direction before launching parallel local workers or commands that
-build, test, index or process an entire repository or dataset. Bounded reads
-and edits may continue. Coordinate competing phases without blocking whole
-sessions.
-
-Use an exclusive slot when the host policy requires one or a local performance
-measurement needs isolation. Remote inference, light CLI/API work and remote
-waits need no exclusive slot. A memory cap, an agent/model comparison or
-recording elapsed time alone does not make a phase heavy. Record timing
-conditions and concurrent local work for shared or remote evaluations.
-
-Other sessions may continue light reads, edits and remote requests within the
-reservation's budget. Preserve measured files, runtimes, dependencies and
-services. During isolated local performance measurements, the measuring session
-only monitors. Release reservations while waiting on remote work or review.
-
-Constrain work that risks exhausting memory using the host's supported controls.
-Check host evidence of memory pressure before retrying with a larger budget.
+When local work shares a host, follow its declared resource budgets. A phase is
+resource-intensive when its expected CPU, memory or I/O demand exceeds the
+host's budget for concurrent work. Before such a phase, check current load and
+running jobs. Without a budget, get operator direction before launching
+parallel local workers or commands that build, test, index or process an
+entire repository or dataset; bounded reads and edits may continue.
+
+Work risks exhausting memory when its expected or last measured peak leaves
+little headroom in the memory available to it, or when its peak is unknown and
+its input is large. Constrain such work using the host's supported controls.
+Retry with a larger budget only when host evidence shows memory pressure caused
+the failure; without that evidence, find the cause before raising the budget.

package/rules/modifiers/squash-landing.md

@@ -18,5 +18,5 @@ conditions in § Landing. After the merge, fetch first; move off a landed branch
 only when its content is in the base and the tree is clean. When the base is
 checked out elsewhere, detach at the fetched base. Never merge, reset or stash
 to move the checkout. Leave app-managed checkouts for the app to retire.
-If the tree is dirty or ownership is uncertain, stand down and record its owner.
+If the tree is dirty or ownership is uncertain, stop and record its owner.
 Update the task record and follow § Cleanup after each landing.

package/rules/modifiers/upstream-contributions.md

@@ -0,0 +1,45 @@
+---
+description: A measured optimization, fix or defect found in a third-party project is offered for submission to that project through its own contribution route.
+after: Repository work
+requires: hr-benchmarking, hr-writing-pr
+---
+
+## Upstream contributions
+
+When work on a third-party project produces a finding that is worth a
+maintainer's time, offer to submit it to that project rather than leaving it in
+a local branch or a note. It qualifies when you reproduced or measured the
+effect and it matches a kind of change the project's contribution guide or open
+issues invite, such as performance fixes or a reported defect.
+
+1. Offer the submission under § Offers as soon as the evidence is complete.
+   Name the channel and the scope.
+2. Pick the channel from the project's contribution guide: a comment on an
+   existing matching issue, a new issue, a discussion for proposals, or a pull
+   request. A behavior change, or a project that asks for prior approval, starts
+   with a comment or discussion, not a pull request. Count the underlying
+   problems and split the submission when the guide asks for one per request.
+3. Meet § Repository work first: the search for existing reports, the review of
+   the diff, the relevant checks, and the project's template and disclosure ask.
+4. Show the user the exact text and channel once before posting. Posting is
+   public and cannot be undone; this rule makes submitting the expected next
+   step, not a waiver of that look. Only a user instruction naming the kind of
+   submission and the projects, such as "post issue comments on project X
+   without asking", removes it.
+5. Title a performance discussion or issue with its headline result and the
+   workload it holds for, such as "saving a file takes 1.1 s with 500
+   open tabs, 0.17 s with the fix". Use a figure only when it clears the
+   `hr-benchmarking` bar (outside the declared variation criterion,
+   repetitions stated) and keep the caveats in the body. Title a defect by what
+   the person sees, not by the code involved, and add how often only when the
+   evidence supports a rate. Open the body with the same headline. A qualified
+   measured result also gets a chart of it (`hr-writing-pr`). A pull request keeps
+   the project's title convention; its opening body sentence carries the figure
+   (`hr-writing-pr`).
+6. When a later measurement or review changes the headline, edit the title and
+   opening lines of your own submission to match, and say in a comment what
+   changed. A submission that buries its benefit under background gets rewritten,
+   not left.
+
+A finding outside the session's purpose stays parked under § Session purpose
+until the user opens it.

package/rules/modifiers/web-image-formats.md

@@ -0,0 +1,35 @@
+---
+description: Prefer WebP for web raster images when it saves bytes at acceptable quality, with format exceptions and delivered-file checks.
+after: Writing
+---
+
+## Web image formats
+
+When creating, importing or replacing raster images a web project controls,
+prefer WebP when its target browsers and publishing pipeline support it.
+Compare files at the required dimensions and acceptable visual quality; use
+WebP when it reduces bytes while preserving required detail, transparency and
+animation. Convert existing assets only within the selected task's scope.
+
+WebP supports lossy and lossless compression and transparency, with broad
+browser support. Smaller files reduce data transfer and can shorten image
+downloads. Page rendering also depends on discovery, layout and rendering
+work; measure page timing separately before claiming a speed gain.
+
+Keep SVG for suitable vector artwork. Use PNG or lossless WebP when exact
+pixels or sharp text require it. Choose another supported format, including
+AVIF, when a size/quality comparison or required consumer favors it. Preserve
+fallbacks that supported clients or integrations require. Keep externally
+hosted images in their provider's permitted delivery format; this preference
+does not authorize downloading, transcoding or rehosting them.
+
+Preserve editing sources when needed, attribution, alt text, intended crop,
+dimensions and responsive sources. Compare the actual derivatives delivered
+by the publishing system, whose encoder settings may differ from a local
+preview. Verify image responses, MIME types and appearance at the relevant
+viewports. A WebP filename alone establishes neither correct encoding nor
+smaller delivery. Format and quality selection require judgment; this
+preference has no automatic enforcement check.
+
+References: [WebP overview](https://developers.google.com/speed/webp) and
+[MDN image formats](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Image_types).

package/rules/references/backlog-view.md

@@ -0,0 +1,154 @@
+## Backlog view
+
+Whenever any item remains in a backlog, remaining-work or walk-through report,
+show one panel of every open item beside the table, not only when the user asks
+to see the backlog. Group the items by what each waits on and order the groups
+bottom-up, so the items that can move sit last, next to the offer:
+
+1. **Waiting on others or a date**, with its count and "not work to start yet".
+   A table with Trigger, Item and Owner columns, in date order with undated
+   events last. A long path or list goes on a second line under its item.
+   Never start these items or offer them.
+2. **Needs your decision**, with its count. One bordered row per question: a Q
+   badge carrying the offer's question number, the item, a muted second line
+   with its status and owner, and answer chips on the right: the question's own
+   option codes when the offer uses codes (`1A`, `1B`), otherwise yes, no and
+   defer. The chips repeat the offer's choices; they are not controls and are
+   never a second set of reply labels. Mark the group being
+   asked "group N of M, this reply" in the header, tinted, with an accent rail
+   beside its rows. Put that group last, with its highest-ranked question last
+   within it.
+3. **Actionable now**, with its count. Keep the group when it is empty: write
+   "Nothing." and the reason.
+
+The panel has a fixed dark background (`#12151c`) with text `#e6e8ee` and muted
+text `#98a1b5` (7.0:1 on the panel). Triggers are `#8fb4ff`; the current group
+and Q badges use `#ffd479`, with dark text on the badge. Group names, counts,
+Q numbers and the words "this reply" carry the meaning, not color alone. Below
+about 520 px wide it becomes one column: hide the column headings and stack
+trigger, item and owner. Render it with the host's own preview or rendering
+tool, and check it at desktop and phone widths when the tool allows. Build it
+from this skeleton, with the report's own items:
+
+```html
+<div class="w">
+  <section>
+    <h4>1. Waiting on others or a date · 2 <small>not work to start yet</small></h4>
+    <div class="cols"><span>Trigger</span><span>Item</span><span>Owner</span></div>
+    <div class="r">
+      <span class="d">Oct 14</span><span>Vendor replies to the support ticket</span
+      ><span class="mu">vendor</span>
+    </div>
+  </section>
+  <section class="cur">
+    <h4>2. Needs your decision · 1 <small>group 1 of 1, this reply</small></h4>
+    <div class="dq">
+      <span class="q">Q1</span>
+      <span class="t">Drop the unused cache layer?<span class="m">parked · web app</span></span>
+      <span class="a"><span>yes</span><span>no</span><span>defer</span></span>
+    </div>
+  </section>
+  <section>
+    <h4>3. Actionable now · 0</h4>
+    <div class="none">Nothing. Every other open item waits on a date or someone else.</div>
+  </section>
+</div>
+<style>
+  .w {
+    background: #12151c;
+    color: #e6e8ee;
+    border-radius: 10px;
+    padding: 16px;
+    font:
+      13px/1.45 system-ui,
+      sans-serif;
+  }
+  .w section {
+    margin: 0 0 14px;
+  }
+  .w section:last-child {
+    margin: 0;
+  }
+  .w h4 {
+    margin: 0 0 6px;
+    padding: 5px 10px;
+    background: #181c27;
+    border-radius: 6px;
+    color: #c9d1e3;
+    display: flex;
+    justify-content: space-between;
+  }
+  .w small,
+  .mu,
+  .m {
+    color: #98a1b5;
+    font-weight: 400;
+  }
+  .cols,
+  .r {
+    display: grid;
+    grid-template-columns: 132px 1fr 168px;
+    gap: 10px;
+    padding: 6px 10px;
+    border-bottom: 1px solid #1c2130;
+  }
+  .cols {
+    color: #98a1b5;
+    font-size: 12px;
+  }
+  .d {
+    color: #8fb4ff;
+  }
+  .none {
+    padding: 6px 10px;
+    color: #98a1b5;
+  }
+  .cur h4 {
+    background: #2a2410;
+    color: #ffd479;
+    box-shadow: inset 3px 0 0 #ffd479;
+  }
+  .dq {
+    display: grid;
+    grid-template-columns: 34px 1fr auto;
+    gap: 8px;
+    border: 1px solid #ffd479;
+    border-radius: 8px;
+    padding: 7px 10px;
+    margin: 8px 0;
+  }
+  .q {
+    background: #ffd479;
+    color: #12151c;
+    border-radius: 4px;
+    font-weight: 700;
+    text-align: center;
+    align-self: start;
+  }
+  .m {
+    display: block;
+    font-size: 12px;
+  }
+  .a span {
+    border: 1px solid #2a3040;
+    border-radius: 5px;
+    padding: 0 7px;
+    margin-left: 4px;
+  }
+  @media (max-width: 520px) {
+    .cols {
+      display: none;
+    }
+    .r {
+      grid-template-columns: 1fr;
+    }
+  }
+</style>
+```
+
+Where the host has no render tool, give the same groups as a Markdown outline:
+numbered group headings with counts, one bullet per item with its trigger in
+bold first and its owner last, Q labels in bold with the item and its status,
+"Nothing." and the reason for an empty actionable group, and "▶ group N of M,
+this reply" on the group being asked. The offer keeps its own format; the view
+adds no offer.

package/rules/references/landing.md

@@ -7,26 +7,24 @@ then, a task finishes committed on its branch with landing offered. Choosing an
 offer option that includes landing, or replying with the accept line when the
 recommended option includes it, is that direction.
 
-At task completion, unlanded commits or uncommitted task changes get one landing
-option, never a bare done or a commit alone; only an explicit user deferral leaves
-them out, recorded with the branch, the commits and the reason. Write it as
-`Land PR #<n>` or `Commit and land <change>`. Landing is the whole sequence in
-this section and § Cleanup; do not list its steps in the option. Name only
-what departs from that sequence, such as a direct merge or a step held for the
-user. Choosing the option authorizes the whole landing, merge included. Land through the path the
-repository requires (pull request or direct push), and never bypass required
-checks. Landing is done when a fresh fetch shows the default branch contains
-the change.
+At task completion, unlanded or uncommitted task changes get one landing option, `Land PR #<n>` or `Commit and land <change>`, never a bare done; only an explicit user deferral (recorded with branch, commits and reason) leaves it out. The option covers this section and § Cleanup, merge included; name only departures from that. Land through the repository's required path without bypassing checks. Landing is done when a fresh fetch shows the change in the default branch.
+
+Leave alone a checkout another
+session or job uses, or whose use you cannot tell. Never merge, reset, stash or
+switch it to make it match the default.
 
 After integration:
 
 - Fetch, then bring the local default branch current. When it is clean,
   strictly behind and not checked out elsewhere, fast-forward it. When another
   worktree has it checked out and you know no session or running job is using
-  that worktree (your own main checkout, for example), run `git pull --ff-only`
-  there; unrelated uncommitted files may stay. When you cannot tell, treat it
-  as in use. Confirm the local and fetched remote heads match.
-- If the default branch is diverged, on another branch, in use, or the pull
+  that worktree (your own main checkout, for example), run
+  `git merge --ff-only <sha>` there with the remote head you just fetched and
+  verified; unrelated uncommitted files may stay. Avoid `git pull` there: a
+  fetch by another process can rewrite the shared `FETCH_HEAD` mid-pull and
+  fail it with "Cannot fast-forward to multiple branches". When you cannot
+  tell, treat it as in use. Confirm the local and fetched remote heads match.
+- If the default branch is diverged, on another branch, in use, or the merge
   refuses because local edits would be overwritten, leave it and report its
   path and the blocker. Never merge, reset, stash or switch branches to make it
   match, and never update other sessions' worktrees or separate clones.
@@ -37,3 +35,5 @@ After integration:
 - When the change landed by squash, verify the pull request's recorded squash
   commit is in the fetched default branch and the intended changes landed; the
   original feature commits need not be ancestors.
+
+Before the first publish step of a version bump (tag, publish, release, announcement), review unreleased changelog entries and public materials (READMEs, charts, graphics with alt text, listing text, announcement) and fix what is stale first; an urgent release may limit only the materials to what it affects.

package/rules/references/multi-agent.md

@@ -20,8 +20,12 @@ never in prose for either. When no second reviewer runs, the user's direction
 is the only judgment backstop; say so instead of assuming review happened.
 Asking an advisor model is not a second review.
 
-After a model review, fix its findings and run the relevant checks. A fix
-that changes code logic permits a follow-up review; it does not require one.
+After a model review, treat each finding as a claim. Fix it when a reproduced
+failure (a test that fails before the fix, where one fits) or a cited
+requirement confirms it, with the smallest change that clears it; a reviewer's
+proposed remedy is a suggestion. Answer an unconfirmed finding with the reason.
+Run the relevant checks. A fix that changes code logic permits a follow-up
+review; it does not require one.
 Code logic includes control flow, data handling, interfaces, queries and values
 a program reads. Request a follow-up only for a named remaining risk that
 local checks cannot resolve. Batch known fixes first, then focus the review on

package/rules/references/release-batching.md

@@ -15,17 +15,40 @@ 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 release or public announcement, audit the README, comparisons,
-performance metrics, relevant documentation, announcement plans and drafts,
-and release notes against the intended revision or artifact and current
-verified state. Record which materials were checked and the evidence for
+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
+visuals (banners, charts, diagrams, screenshots and demo recordings, with their
+alt text), relevant documentation, registry and marketplace listing text,
+announcement plans and drafts, release notes and the release announcement.
+
+Check each for old version numbers, figures and behavior. Regenerate or replace
+a visual that shows them; where that is not possible, remove it or label the
+version it shows. Record which materials were checked and the evidence for
 claims in the task plan. Correct, add, remove or update content to resolve
 outdated instructions, omissions, contradictions and unsupported claims.
+
 Distinguish released, deployed and planned behavior; give performance claims
 measurement conditions and evidence, and label unverified results. Preserve
 historical results with their tested versions instead of presenting them as
 current measurements.
 
+Run the audit on every version bump, before the first publish step: the tag,
+the registry or package publish, the GitHub release or any announcement. Land
+each correction first. Landing the corrections is part of the audit; one made
+after publishing means the audit did not finish. This applies to every public
+repository, including ones created later.
+
+Audit the pending changelog entries at the same point on every version bump,
+public or private, and land the corrected changelog first. Check each entry
+against the code that will ship: names, commands, counts and figures are
+verified, not copied, and no transient number stays. Keep entries plain and no
+longer than their reader needs. Merge entries that describe iterations of one
+concern into one entry that states the final behavior; how a change evolved
+stays in git. Keep whole any entry a user must act on (a breaking change, an
+upgrade or a repair step); never merge it away. An urgent release does not narrow
+this audit.
+
 Recheck affected claims when the candidate or supporting evidence changes.
 Before publishing, resolve unsupported or contradictory claims by correcting,
 qualifying or removing them; record any remaining accuracy blocker. Do not

package/rules/references/squash-landing.md

@@ -16,10 +16,16 @@ When a review bot reviews pull requests, merge only after its check finishes
 and each finding is fixed or answered with a reason, threads resolved. Read
 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").
+
 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
 `worktree remove` on it. Updating the default branch it has checked out
-(`merge --squash`, `merge --ff-only`, or `pull --ff-only` after a remote merge)
+(`merge --squash`, or `merge --ff-only` to the fetched remote head after a remote merge)
 under the fast-forward conditions in § Landing is expected; report other paths
 to their owners.
 
@@ -33,9 +39,9 @@ Fetch first, then:
   has the base checked out, detach at the fetched base (`git switch --detach
 <remote>/<base>`) and create or switch to a branch before any further
   commits.
-- When an app manages the checkout, leave it: the app retires it, and the
-  report does not mention it.
-- When the tree is dirty or ownership is in doubt, stand down: record the
+- When an app manages the checkout, leave it for the app to retire. Report it;
+  it is not a blocker.
+- When the tree is dirty or ownership is in doubt, stop: record the
   merged commit, the checkout path and the owner wherever you track the task.
 
 After each landing, update the task list and any active handoff with the