@bompus/house-rules 0.0.0-stage → 0.13.0

package/rules/modifiers/no-attribution.md

@@ -0,0 +1,16 @@
+---
+description: Commits, pull requests and comments carry no agent or tool credit lines unless the target repository asks for a disclosure.
+after: Writing
+---
+
+## No attribution
+
+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

@@ -0,0 +1,82 @@
+---
+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
+
+For work with two or more steps, create the task list up front, keep exactly
+one item in progress and mark each item done as it finishes. When no task tool
+is available, keep the list in short progress messages and say so once.
+
+Mirror the list to a plan file: the project's plans directory when it documents
+one, otherwise `plans/<topic>/plan.md` in your notes directory (§ Durable
+notes). At session start, read the relevant plans and every `blocked-on-user`
+plan whatever its owner, so unanswered decisions stay visible; that read is not
+the sweep below. Update the plan when you update the list, add findings as they
+turn up, and use the same item states in both. At each reconciliation event in
+§ Finishing work, update both records before choosing the next action. Point at
+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. 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 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.
+- When repeated attempts leave an item unresolved without new evidence, record
+  whether it is blocked, deferred or using an approach that is not working. For
+  an approach that is not working, change method within the authorized scope,
+  or propose a smaller deliverable or dropping the item; the user decides scope
+  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 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,
+`blocked-on-user` items and items whose owner has no live session in the host's
+session list or coordination roster, naming each owner. When you cannot tell
+whether an owner is live, or who owns an item, mention it as another session's
+context instead of offering it.

package/rules/modifiers/question-cards.md

@@ -0,0 +1,48 @@
+---
+description: Opt in to question cards beside complete text offers when the host supports them; availability and presentation can vary by host, provider and model.
+after: Offers
+---
+
+## Question cards
+
+This modifier opts in to cards beside text. Availability, invocation and
+presentation can vary by host, provider and model: a card may be unavailable,
+skipped or shown unexpectedly. Keep the complete text offer usable on its
+own; do not promise identical behavior across sessions. If the user chooses
+text only, disable this modifier and do not call question-card tools, even
+when they are exposed.
+
+Asking the user to choose between options is an offer, even when the user
+asked you to ask them, so it gets the full text offer on every host.
+
+When your host gives you a multiple-choice question tool (one that shows the
+user a question with selectable options), send every offer as a question card
+as well as text, unless the choice depends on content only the text carries:
+images, tables, code, links, or a comparison longer than a card option holds.
+Some hosts show the card before the text written ahead of it, so the user
+would answer without that content. Send those offers as text alone.
+
+1. Write the complete text offer first, with every part § Offers lists. A
+   one-line question, a line saying you will ask, or no text at all is not a
+   text offer. The card never replaces it, because some hosts cannot display
+   cards and some drop short text sent beside one.
+2. In the same reply, right after the text offer, call the tool. Do not end
+   the reply between the two.
+3. Ask one card question per offer question, in the same order. Give each
+   option the label it has in the text offer, code included when the offer
+   uses codes, with "(Recommended)" where the text offer has it: for example
+   `1A (Recommended) pylon` under coded offers, not `pylon`. Write each
+   option's description so it stands alone, saying what the option does and
+   what it costs or risks: on some hosts the card is all the user sees before
+   answering. Use multi-select when the options combine. Leave out an "Other"
+   option; hosts add their own free-text choice.
+4. Treat the card's answer as a typed reply naming the same options. On some
+   hosts the answer arrives as a new turn; it still answers the offer.
+
+When no such tool is available, send the text offer alone. Do not search for
+a substitute or call another tool in its place.
+
+When you answer a card that a delegated agent raised, key each answer by the
+question id in the request, because hosts use different ids. Then read the
+agent's result again: some hosts report the task finished while its card
+waits and deliver the real result only after the answer.

package/rules/modifiers/release-batching.md

@@ -0,0 +1,15 @@
+---
+description: Batch approved, compatible changes for releases and audit factual claims before releases or public announcements.
+after: Landing
+reference: ../references/release-batching.md
+---
+
+## Release batching
+
+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 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/scratch-on-disk.md

@@ -0,0 +1,15 @@
+---
+description: Task scratch lives on disk under the user data directory, never in RAM-backed /tmp.
+after: Durable notes
+---
+
+## Scratch files
+
+Keep task scratch on disk-backed storage, under `tmp/<topic>/` in your notes
+directory (§ Durable notes), even when a tool or harness defaults to `/tmp` or
+to a temp path it pre-approves. On many Linux systems
+`/tmp` is RAM-backed, so large files there compete with running programs for
+memory. Files that can approach 1 GB (databases, traces, downloads, extracted
+archives) never go there, whatever a tool's default says. Write in-progress
+receipts straight to their final location, and delete scratch when the task
+ends.

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

@@ -0,0 +1,19 @@
+---
+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 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/solo-operator.md

@@ -0,0 +1,13 @@
+---
+description: For repositories with one maintainer, the user's direction is the review; no review-gated steps.
+after: Landing
+---
+
+## Solo operator
+
+The user's repositories have no second reviewer: the user's explicit direction
+is the review. Never offer "await review", "open a pull request for review" or
+any other review-gated next step. Land each task through a pull request, so
+the pull request records why the default branch moved; skip it only for
+trivially mechanical changes, or when the user, directly or in the
+repository's own guidance, directs a direct push.

package/rules/modifiers/squash-landing.md

@@ -0,0 +1,22 @@
+---
+description: Pull requests land by squash merge after review-bot findings are handled, and the session's checkout moves off the landed branch.
+after: Landing
+reference: ../references/squash-landing.md
+---
+
+## Squash landing
+
+Prefer squash merges unless the repository requires another strategy or the user
+picks one. Before integration, handling review feedback, or moving off a landed
+branch, read [the squash procedure](../references/squash-landing.md).
+When a review bot reviews pull requests, merge only after it finishes; fix or
+answer all findings, resolve threads, and read the full review body.
+
+During integration, never switch, reset, force-move or remove the session's
+checkout. Default-branch updates must meet the fast-forward and ownership
+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, 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/github-actions.md

@@ -0,0 +1,45 @@
+## GitHub Actions
+
+Inspect the current workflows, run logs and effective repository policies before
+changing CI. Distinguish runner startup or action-policy failures from test
+failures, timeouts and missing credentials. Preserve checks and assertions;
+qualify timeout changes with the actual failing operation and comparable runs.
+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.
+
+### Choose the concurrency boundary
+
+Independent jobs can run on separate runners. A job's steps normally run in
+sequence, but GitHub also supports native parallel steps. Confirm current
+[workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsparallel)
+before using it; older model knowledge may omit this capability.
+
+- A `parallel` group starts its steps together and waits for the group.
+- `background: true` starts a step without waiting. Use its `id` with `wait` or
+  `cancel`, or use `wait-all` to wait for every active background step, as the
+  dependency and failure policy requires.
+- Parallel steps share a runner, workspace and resource budget. Inspect writes,
+  caches, outputs and prerequisites before overlapping commands. Install shared
+  dependencies first. Do not infer a speedup without measurements.
+- Workflow `concurrency` controls overlapping runs; it does not parallelize steps.
+
+Keep failure propagation and required evidence intact. More parallelism can
+increase contention or duplicate work. Prefer the smallest independent group
+that addresses a measured or operational need.
+
+### Forks and notifications
+
+Establish whether a fork is maintained independently or only hosts contributions
+upstream. Honor that purpose before enabling workflows, publishing or changing
+automation settings. Inspect repository Actions permissions separately from
+workflow triggers and notification subscriptions.
+
+Disabling repository Actions stops ordinary workflows, but enabled Dependabot
+can still run on Actions. Check dependency-update automation separately when
+investigating continuing runs. Keep security alerts and notification preferences
+distinct from update automation; do not silence unrelated failures.
+
+Sources: [parallel-step announcement](https://github.blog/changelog/2026-06-25-actions-steps-can-now-be-run-in-parallel/),
+[Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository),
+[Dependabot on Actions](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-on-actions).

package/rules/references/landing.md

@@ -0,0 +1,39 @@
+## Landing
+
+A branch or worktree is an intermediate step. Land a change (merge or push it
+into the remote default branch) only when the user has directed it, for this
+task or as a standing rule in their rules or the repository's guidance. Until
+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 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 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.
+- Delete the merged remote branch when it is this task's own branch
+  (`git push origin --delete <branch>` when the merge did not); § Cleanup
+  covers branches others may rely on. Before merging a pull request that another open pull
+  request targets, retarget that one to the default branch first.
+- 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

@@ -0,0 +1,51 @@
+## Working with other agents
+
+A worker's report that leaves items open without naming a blocker is a
+checkpoint, not completion: send it back naming them, and after two or three
+continuations review the work yourself. A worker with a background command or
+subagent still running is not done. Take its elapsed time from the host's
+durations or timestamps, not from its report. When wall-clock time matters,
+give a budget and restate the elapsed time in each follow-up, or say that an
+earlier correct result beats a later one; budgets are advisory, hard timeouts
+are not. Reuse workers for related follow-ups, do independent work while they
+run instead of polling, and keep workers from delegating further unless asked.
+
+Split standards by where they are enforced. Give implementers the task, file
+boundaries, public APIs and load-bearing architectural constraints, even ones
+no tool can check. Keep style and judgment calls for the review pass, where the
+reviewer reads the applicable guidance itself; a convention that does not fit
+one line with a yes/no test is taste and reviewer-only. What a formatter,
+linter, type check or automated gate can enforce belongs in tooling for both,
+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, 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
+changed logic and unresolved findings. Never restart a whole-change review
+solely because a fix changed logic.
+
+Before a follow-up, record its scope and round limit in the plan. A further
+logic fix does not reset that limit. When the limit is reached, report any
+remaining blocker and get the user's direction before another model round.
+Fixes that touch only docs, comments, changelog text or tests ship on local
+checks. The pull request body names the findings fixed and says when no
+further round ran. Required repository checks and review gates still apply.
+
+Before cleaning up a branch, directory or worktree by hand or on a schedule,
+check that no session of any installed agent host uses it: session records and
+workspace or branch associations as well as processes, including idle, paused,
+disconnected and resumable sessions. Resolve equivalent paths and check
+sessions in child directories before removing a parent. Recheck right before
+deleting; scheduled cleanup skips what it could not verify. When you finish,
+offer an app-managed session's branch to its owner for deletion, unless the
+session is still on it. Before creating a task worktree, check the
+repository's worktree list and report unexplained leftovers; `git worktree
+prune --dry-run` shows stale registrations.