@bompus/house-rules 0.11.0 → 0.13.0

package/skills/hr-forgotten-work-audit/references/result-format.md

@@ -0,0 +1,46 @@
+# Result format
+
+## Slice result (one file per worker)
+
+```markdown
+# <slice name>
+
+Coverage: <records read and range>; <N> candidates; done <n>, tracked <n>,
+dropped <n>, forgotten <n>, unclear <n>.
+Gaps: <records not read, filters applied, truncation>.
+
+| #   | What was asked, promised or offered | Source (agent, session, date, short quote) | Verdict | Evidence searched | Suggested disposition (do, ask, drop) |
+| --- | ----------------------------------- | ------------------------------------------ | ------- | ----------------- | ------------------------------------- |
+
+Patterns: <one paragraph on how items got lost>.
+```
+
+The table holds every forgotten and unclear item, and tracked items with no
+movement for more than seven days. Keep each cell short.
+
+## Consolidated report
+
+```markdown
+# Forgotten-work audit: <project>, <start> to <end>
+
+Scope: <repositories, record folders, transcript filter>.
+Previous audit: <result path, or none>.
+
+## Coverage
+
+| Slice | Range | Result file | Checked | Done | Tracked | Dropped | Forgotten | Unclear |
+| ----- | ----- | ----------- | ------- | ---- | ------- | ------- | --------- | ------- |
+
+Counts overlap between slices; the list below is deduplicated.
+
+Gaps: <one line per source not covered, filter that dropped records, or truncation>.
+
+## Findings, ranked
+
+| #   | Item | State | Owner | Next (do, ask, drop) | Evidence |
+| --- | ---- | ----- | ----- | -------------------- | -------- |
+
+## How items got lost
+
+1. <pattern>: <items it explains>.
+```

package/skills/hr-handoff/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-handoff/NOTICE.md

@@ -0,0 +1,29 @@
+# Source notices
+
+This notice accompanies the hr-handoff bundle when copied on its own.
+
+## mattpocock/skills
+
+Source: https://github.com/mattpocock/skills (compared at revision `d81f3a1`)
+
+- `SKILL.md` and its supporting files: adapted from `skills/productivity/handoff/`.
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-handoff/SKILL.md

@@ -45,11 +45,34 @@ decisions and recommendations in priority order.
 For a handoff unrelated to quota, follow
 [reconciliation.md](references/reconciliation.md) to compare the current and
 preceding source transcripts, linked ledgers and Git inventory with this
-inventory. Save its receipt and run the offline checker. Report coverage gaps
+inventory. Name each predecessor plan as a source, so every open or deferred
+line in its ledger carries over as an item. Save its receipt and run the offline checker. Report coverage gaps
 and mechanical results separately from the reviewed claim that all items are
 addressed. Include owned unlanded PRs, dependency PRs and own commits without a
 PR; preserve their owners and landing authority.
 
+When a handoff unrelated to quota moves work to another thread, also move what
+the host binds to the outgoing thread:
+
+1. Inventory it: scheduled or recurring tasks, linked pull requests and PR
+   watches, and any agent-mail or messaging registration and its subscriptions.
+   Use the host's own list or status commands for each.
+2. Move or record each item. Where the host lets the receiving thread bind it,
+   the handoff names the exact call the receiver makes; some hosts let a thread
+   bind a task only to itself, so the outgoing thread cannot move it. Otherwise
+   record why it stays. Read each item back after the move; a move without a
+   read-back is unfinished. Retire the outgoing copy of a task only after the
+   receiver's read-back confirms its replacement, so the work neither runs twice nor is lost.
+3. Follow any thread-switch checklist the owning repository or the user's
+   guidance names, and list it in the handoff.
+4. Keep the outgoing registration until the user closes the old thread, then
+   retire it.
+5. Give each bound item a row in the receipt, with owner, state and next action.
+
+When the new thread replaces this one as its successor, also follow
+[successor-thread.md](references/successor-thread.md) for when a replacement is
+warranted, its safe boundary, the title and the successor record.
+
 At a low-quota stop, save essential state first and record partial coverage
 when feasible. An unfinished receipt or failing check never delays that stop.
 

package/skills/hr-handoff/references/reconciliation.md

@@ -7,17 +7,31 @@ replace reading their content or reviewing context-only classifications.
 ## Collect independent source snapshots
 
 Review the current transcript and the preceding handoff's source transcript
-when available. Include linked plans, child ledgers, schedules, pending
-decisions and owned Git work. Use the host's existing export and session-search
-tools. Preserve source IDs and text rather than exporting only the items you
-already remembered.
+when available. Include linked plans, child ledgers, pending decisions, owned
+Git work and what the host binds to the outgoing thread (scheduled tasks, PR
+watches, mail or messaging registration and subscriptions), as listed in the skill's
+thread-move step. Use the host's existing export and session-search tools.
+Preserve source IDs and text rather than exporting only the items you already
+remembered.
 
 Normalize each source into a JSON object with a `records` array. Each record
 has a unique `id` and its original `text`. Record the original location and
 snapshot or range in the receipt's `snapshot` field. Name records by stable
 message IDs or ledger row IDs. Several records can map to the same item.
 
-When a record establishes a disposition, add an `outcome` with `item` and
+A predecessor plan needs no conversion. Name its `plan.md` as the source
+`file`; the checker reads each item line of its `## Ledger` section (`- [ ]`,
+`- [~]`, `- [x]`, `- [-]`) as a record named `L<line>` (`L12`). Other text in
+the section is not read, so turn any follow-up written there into an item line
+before the handoff. Take a copy of the plan as it stood at the handoff,
+because later edits renumber the lines. Each open or deferred line must map to
+an item; a context-only reason such as "the rest, reopen only if asked" is
+rejected. When one item absorbs several open or deferred lines, give the item
+a `merges` field saying how one next action and one piece of completion evidence
+satisfy every line. A ledger kept as a table is not read; normalize it to JSON
+records instead.
+
+When a record settles an item's state, add an `outcome` with `item` and
 `state`, plus `at` as a UTC ISO timestamp. States are `done`, `open` and
 `deferred`. Use the evidence's time, not the export time. A later request or
 current contradictory evidence that reopens completed work also sets
@@ -47,10 +61,15 @@ relative to the receipt; the checker reads only explicitly named snapshots.
   Add nonempty `items` containing extracted item IDs, or a `context` reason
   explaining why the record creates no candidate. Review user requests and
   assistant commitments and options before assigning context-only status.
-- Each `items` entry has `id`, `owner`, `state`, `evidence` and `next`.
+- Each `items` entry has `id`, `owner`, `state`, `evidence` and `next`, plus
+  `merges` when it carries over more than one open or deferred plan line.
   Evidence references use `{ "source": "source-id", "record": "record-id" }`.
   Include the latest declared outcome. For deferred work, `next` gives its
   trigger; for done work, give its result and any separately tracked follow-up.
+- Thread-bound state (scheduled or recurring tasks, PR watches, any mail or
+  messaging registration and subscriptions) is an `items` entry like any other. `next`
+  names the receiver's exact call to bind it and how to read it back, or why it
+  stays with the outgoing thread until the user closes it.
 - `git` records `scope`, `checkedAt` and `evidence`, plus explicit `ownedPrs`,
   `dependencyPrs` and `commitsWithoutPr` arrays. Empty arrays are checked
   results, not omitted fields. For no repository work, say so in `scope` and

package/skills/hr-handoff/references/successor-thread.md

@@ -0,0 +1,76 @@
+# Replace a session with a successor thread
+
+Follow this when a handoff moves work to a fresh thread that takes over from
+the current one. It decides when replacing a session is warranted, when it is
+safe and what the handoff and the successor record. It does not authorize
+starting a thread. The house rules' § Repository work still requires the
+user's direction, a standing spin-off preference or a rule that requires the
+handoff. The host's own guidance owns the tool calls that create, rename and
+rebind a thread.
+
+## When stale guidance warrants a new session
+
+Replace a session because its injected guidance went stale only when the change
+is session-critical:
+
+- an always-on rule, or a safety rule
+- the catalog entry (name and description) of a skill the session uses
+- a subagent definition the session uses
+
+A change to a skill body or a doc does not warrant a new session. The session
+rereads it with `hr-agent-guidance-refresh` at its next boundary, and the body
+is read when the skill runs. That skill notes that a reread does not prove the
+injected context changed, so use the list above, not the reread, to decide
+whether a replacement is needed.
+
+## Boundary
+
+Never replace a session mid-turn, in the middle of an evaluation that fixed its
+guidance, or while an external action is pending. An action is pending when it
+has started without a recorded result. Replace it only when the session is
+idle, nothing is running and the ledger is reconciled under the house rules'
+§ Finishing work.
+
+## Successor title
+
+A successor keeps the base title and ends it with ` v<N>`. The first thread
+counts as `v1` and is renamed at the handoff.
+
+1. If the title ends in ` v` followed by digits, the base is the title without
+   that ending and N is that number. Otherwise the base is the whole title and
+   N is 1.
+2. Rename the outgoing thread to `<base> v<N>` when its title does not already
+   end that way.
+3. Give the successor `<base> v<N+1>`, writing N+1 as a plain number without
+   leading zeros.
+
+A title is a label for people. Never look a thread up by its title. Use the
+registry row, the project and the thread id.
+
+## What the handoff records
+
+- The outgoing thread's id and the successor's id, so each points to the other.
+- Each open offer by the offer ID the ledger recorded for it, with its
+  question, options and recommendation. The house rules' § Offers records an ID
+  for every offer, including a text-only one that never displayed it. The
+  successor treats an offer as open only if the handoff lists it and the latest
+  ledger or source record still shows it open. An offer answered, completed,
+  deferred or superseded since the handoff was written authorizes nothing. A
+  bare code or `go` in the successor selects an offer only when one listed offer
+  is open. With several, it asks which one, as § Offers requires.
+- The inventory and read-backs from the skill's thread-move step. The
+  receiving thread re-points to itself each item the host lets it bind:
+  registry rows, scheduled tasks, pull request watches and the messaging name
+  the work was known by. For an item it cannot bind, the handoff keeps the
+  recorded reason it stays with the outgoing thread. Where the host does not let
+  the successor take over the name, the handoff says which name the successor
+  registers and who needs to be told.
+
+## Successor record
+
+- Mark the outgoing thread settled and record a pointer to the successor where
+  the host keeps such notes. Do this last, after the successor confirms it has
+  read the handoff.
+- The successor starts by reading the handoff in full. It re-points each item
+  it can bind, with a read-back, and records every result in the receipt,
+  including the items that stay behind. Only then does it take new work.

package/skills/hr-handoff/scripts/check-reconciliation.mjs

@@ -53,6 +53,23 @@ function unique(entries, label) {
   return map;
 }
 
+// A plan file (`.md`) is read as its `## Ledger` item lines, one record per item, named `L<line>`;
+// other text in the section, wrapped continuation lines included, is not read.
+// Open (`- [ ]`) and deferred (`- [~]`) lines are remembered: they must carry over as items.
+function ledgerRecords(raw) {
+  const lines = raw.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^#{1,6}\s+Ledger\s*$/i.test(line));
+  if (start < 0) return null;
+  const level = lines[start].match(/^#+/)[0].length;
+  const records = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (new RegExp(`^#{1,${level}}\\s`).test(lines[i])) break;
+    const match = lines[i].match(/^\s*[-*]\s+\[([ x~-])\]\s+(.*)$/i);
+    if (match) records.push({ id: `L${i + 1}`, text: match[2], mark: match[1] });
+  }
+  return { records };
+}
+
 function check(receipt, directory) {
   if (!object(receipt)) throw new Error("receipt: expected an object");
   if (receipt.version !== 1) errors.push("version: expected 1");
@@ -63,6 +80,7 @@ function check(receipt, directory) {
   const sources = unique(entries(receipt.sources, "sources"), "source");
   const items = unique(entries(receipt.items, "items"), "item");
   const records = new Map();
+  const openLines = new Set();
   const outcomes = new Map();
   if (sources.size === 0) gaps.push("no source snapshots supplied");
 
@@ -90,12 +108,19 @@ function check(receipt, directory) {
       continue;
     }
     let data;
-    try {
-      data = JSON.parse(raw);
-    } catch {
-      errors.push(`${label}: invalid snapshot JSON`);
-      continue;
-    }
+    if (source.file.endsWith(".md")) {
+      data = ledgerRecords(raw);
+      if (!data) {
+        errors.push(`${label}: no \`## Ledger\` section in the plan`);
+        continue;
+      }
+    } else
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        errors.push(`${label}: invalid snapshot JSON`);
+        continue;
+      }
     if (!object(data)) {
       errors.push(`${label}: snapshot must be an object`);
       continue;
@@ -107,6 +132,8 @@ function check(receipt, directory) {
     for (const row of rows.values()) {
       requireText(row.text, `${label} record ${row.id}.text`);
       records.set(key(source.id, row.id), row);
+      if (source.file.endsWith(".md") && /[ ~]/.test(row.mark))
+        openLines.add(key(source.id, row.id));
       if (row.outcome !== undefined) {
         if (!object(row.outcome) || !states.includes(row.outcome.state)) {
           errors.push(`${label} record ${row.id}: invalid outcome`);
@@ -136,8 +163,23 @@ function check(receipt, directory) {
     for (const item of mapped) {
       if (!items.has(item)) errors.push(`${label}: unknown item ${item}`);
     }
+    if (openLines.has(ref) && text(row.context))
+      errors.push(
+        `${label}: an open or deferred ledger line needs an item, not a context-only reason`,
+      );
     accounting.set(ref, mapped);
   }
+  // A summary row ("the rest, reopen only if asked") that swallows many open lines loses them;
+  // an item fed by more than one open line must say in `merges` how one next action and one piece of evidence satisfy them all.
+  const absorbed = new Map();
+  for (const ref of openLines)
+    for (const item of new Set(accounting.get(ref) ?? []))
+      absorbed.set(item, (absorbed.get(item) ?? 0) + 1);
+  for (const [item, count] of absorbed)
+    if (count > 1 && !text(items.get(item)?.merges))
+      errors.push(
+        `item ${item}: absorbs ${count} open or deferred ledger lines; split it, or say in merges why they are one`,
+      );
   for (const ref of records.keys()) {
     if (!accounting.has(ref)) errors.push(`unaccounted record ${ref}`);
   }

package/skills/hr-house-rules-setup/SKILL.md

@@ -49,14 +49,28 @@ For an agent running without a terminal, use the preview/apply workflow below.
    Personal skills override shipped ones. Keep independent names, layers,
    unrelated settings and exclusions.
 
-   If the user wants Swarmail, offer its modifier. When its MCP tools are absent,
-   point to https://github.com/bompus/swarmail and ask before installing it.
-   If they want different question presentation, offer plain text, coded text,
-   or coded text with cards using `--questions plain|coded|cards`. Cards still
-   require a complete text offer. Explain that host, provider and model behavior
-   varies; card availability and presentation are unverified until checked.
-   Both text-only choices prohibit card tools. If personal rules still request
-   cards, resolve that conflict before changing those rules or composing.
+   Ask how they want questions asked, in these words, unless the config
+   already records a choice they confirm: **Model default** (your model and host
+   ask their usual way; house-rules gives no instruction), **Text only** (plain
+   text options; no question tools are called), or **Clickable choices when
+   available** (complete text options plus a question card). Recommend nothing;
+   it is their preference. Map the answers to `--questions default`, `plain`
+   (or `coded`) and `cards`. For Text only, ask a separate yes/no: "Use short
+   reply codes like 1A, so one reply can answer several questions?" Yes is
+   `coded`, no is `plain`. Explain that host, provider and model behavior varies;
+   card availability and presentation are unverified until checked. Text only
+   prohibits card tools; Model default adds no instruction either way. If
+   personal rules still steer how questions are asked, resolve that conflict
+   before changing those rules or composing. Call modifiers "optional rules"
+   and the user's layer "your own rules" when talking to them.
+   Ask separately how they want a backlog or remaining-work report shown, unless
+   the config already records a choice they confirm: **Panel** (a dark panel
+   grouped by what each item waits on; `backlog-visual`), **Outline** (the same
+   groups as a Markdown outline that nothing renders; `backlog-outline`) or
+   **None** (the ranked table alone; neither modifier). Recommend nothing. Enable
+   one at most: the two cannot be combined. `config set` keeps modifiers it is
+   not told to change, so pass `--enable-modifier` for the chosen one and
+   `--disable-modifier` for the other, or for both when the answer is None.
    Done when the user selects relevant changes or keeps the current setup.
 
 3. Use `node compose.mjs config set --config <path>` with the selected

package/skills/hr-lean-plan/SKILL.md

@@ -61,6 +61,10 @@ Look for a framing that deletes work before ordering it:
   their existing owning layer. A new layer needs a reason the current one
   cannot meet the goal.
 
+Leave out steps added only in case something goes wrong. A fallback, retry,
+backup path or extra check belongs in the plan when a named risk, constraint or
+must-not-regress item calls for it; name which one.
+
 Count the moving parts the plan adds: new files, modules, services,
 dependencies, config keys, flags, migrations, background jobs and parallel
 paths. A smaller count that still meets the done-state is the better plan.

package/skills/hr-maintainability-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-maintainability-review
-description: "Review a diff or an entire codebase for maintainability and structure, preserving behavior. Use when explicitly requested for a strict, deep, harsh or thermo-nuclear maintainability review. Report-only; correctness, UI quality, test coverage and measured performance need separate assessments."
+description: "Review a diff or an entire codebase for maintainability and structure, preserving behavior. Use when explicitly requested for a strict, deep or harsh maintainability review, or a whole-repository over-engineering or bloat audit. Report-only; correctness, UI quality, test coverage and measured performance need separate assessments."
 disable-model-invocation: true
 ---
 
@@ -45,8 +45,8 @@ change and what it owns now.
    an area assessed only after inspecting its implementation and relevant
    consumers; inventory or file counts alone do not establish coverage.
 
-Done when every inventoried area has an assessment or an explicit unreviewed
-disposition. Report gaps rather than claiming a complete audit from a sample.
+Done when every inventoried area has an assessment or an explicit note that it was
+not reviewed. Report gaps rather than claiming a complete audit from a sample.
 
 ## What to challenge
 
@@ -58,7 +58,10 @@ disposition. Report gaps rather than claiming a complete audit from a sample.
   before this change lands, and where the seam is.
 - **Pass-through layers.** Wrappers, adapters and services that forward calls
   with renamed arguments. Indirection must buy clarity, isolation or a real
-  second implementation.
+  second implementation. Test a suspect module by imagining it deleted: if its
+  complexity would spread into every caller, it is earning its keep; propose
+  removal only when callers could use the underlying behavior directly without
+  duplicating or redistributing that complexity.
 - **Generic machinery over a simple shape.** Registries, plugin systems,
   builders or configurable pipelines where the data is a fixed list or a plain
   record.
@@ -75,6 +78,13 @@ disposition. Report gaps rather than claiming a complete audit from a sample.
   shape where partial state cannot exist.
 - **Modes and flags.** A boolean parameter or mode switch that splits one
   function into two behaviors sharing a name.
+- **Leftover scaffolding.** Stubs and placeholders still on a live path, fixed
+  sample data where real data should flow, functions that report success
+  without doing their work, handlers that silently do nothing, "temporary"
+  branches that shipped, and comments describing a refactor long finished.
+  Propose deleting what no consumer needs. When a consumer depends on one, the
+  real behavior is missing: report it under **Other assessments** as a
+  correctness concern, without guessing at the contract the code never showed.
 
 ## Look for code that disappears
 

package/skills/hr-maintainability-review/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
   display_name: "HR: Maintainability review"
-  short_description: "Strict maintainability review of a diff or codebase"
+  short_description: "Strict maintainability or bloat review of a diff or codebase"
 policy:
   allow_implicit_invocation: false

package/skills/hr-manual-qa/SKILL.md

@@ -19,7 +19,7 @@ can reproduce. Follow the project's verification and domain safeguards.
    observation is needed, say so instead of inventing a checklist.
 4. Ground regression checks in the changed flow and supported surfaces. Use
    available impact findings and UI guidance. When a consequential risk needs
-   investigation and `hr-change-impact` is available, use it for that risk;
+   investigation and `hr-code-review` is available, use it for that risk;
    otherwise name the uncertainty. A checklist does not require a full impact
    assessment.
 5. Present agent results first. When a manual observation remains, include a

package/skills/hr-ordering-tests/SKILL.md

@@ -19,7 +19,7 @@ the implementation instead of a separate model that can drift from it.
 2. **List the events.** Include each distinct write, message, restart or reset
    an actor can produce, with the variants that take different code paths:
    an older, equal and newer timestamp; a field left out; another identity
-   (session, tenant, league); two events delivered in one batch. Aim for 6 to
+   (session, tenant, account); two events delivered in one batch. Aim for 6 to
    10 events, and merge variants that exercise the same path.
 3. **Enumerate.** Walk every sequence up to length N depth-first. At each node,
    restore the state its prefix left, apply one event through the real entry

package/skills/hr-plain-prose/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-plain-prose
-description: Revise text a person will read (commit messages, PR descriptions, docs, code comments, replies, the final report on a task) so it is plain, specific and free of AI tells, the habits that mark machine-written prose. Use when drafting or revising human-facing text, even a short message or reply, or when asked to "unslop" text or make it sound less generated.
+description: Revise text a person will read (commit messages, PR descriptions, docs, code comments, replies, the final report on a task) so it is plain, specific and free of AI tells. Use when drafting or revising human-facing text, even a short message or reply, or when asked to "unslop" text or make it sound less generated.
 ---
 
 # Plain prose
@@ -179,9 +179,12 @@ self-reference ("As an AI..."). Start with the content.
 - Use active voice with a named actor: "The scheduler drops the job", not "The
   job is dropped".
 - Write replies as complete sentences about the actual work. Translate plan
-  labels and internal shorthand into words the user already knows. Explain a
-  needed technical term when first used. Keep exact identifiers where the
-  reader needs them to find or verify something.
+  labels and internal shorthand into ordinary names before giving identifiers.
+  Keep technical terms and exact identifiers when the reader needs them to
+  understand, find or verify the work; explain an unfamiliar term when first used.
+- Before each decision question, explain what would change and why it matters
+  to the user. Make clear what each answer authorizes, including the limits of
+  the work. Already-clear facts need no repeated explanation.
 - Cap sentence length. Keep a step the reader carries out near 20 words and a
   descriptive sentence near 25. A longer one usually holds two ideas. Vary the
   length below the cap.

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

@@ -22,7 +22,7 @@ Integrate fetched changes using the repository's history policy and preserve
 other owners' work. Ask when conflicting intent cannot be settled from the
 selected requirements.
 
-For each finding, record its disposition. Fix a demonstrated problem within
+For each finding, record what was decided about it. Fix a demonstrated problem within
 scope, explain why an unsupported finding does not apply, or name the decision
 or evidence still needed. Include findings in review bodies outside inline
 threads. Reply and resolve threads within the selected authority; a thread
@@ -55,8 +55,11 @@ 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 review gate and one-thread resolver](references/review-helpers.md).
-The gate does not replace other required checks or the caller's judgment.
+[the CodeRabbit review gate and one-thread resolver](references/review-helpers.md).
+Its review-status checks cover CodeRabbit 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`).
 
 Immediately before landing, re-read the head, base, checks, review bodies and
 unresolved threads. If the head or base changed, discard readiness and repeat

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

@@ -88,3 +88,24 @@ or changed head exits 2. Re-read the PR before deciding whether to retry.
 
 The helper shares GraphQL command/envelope validation with `check-pr-review.ts`.
 It does not clear that gate's review-body findings or change the landing workflow.
+
+## Landing helpers
+
+Three scripts in `scripts/` implement the landing steps § Landing describes. They never
+reset, switch or delete a checkout.
+
+- `merge-pr.sh <pr> [--merge] [--remote <name>] [--idle-primary <path>]` squash-merges
+  (or merge-commits) an open pull request and deletes its remote head without
+  `gh pr merge --delete-branch`, which removes other sessions' linked worktrees. It
+  refuses while review feedback is open (`check-pr-review.ts`), while another open pull
+  request targets the head, and for a repository listed in `HR_PUSH_LANDED`
+  (space-separated `owner/repo`; those land by fast-forward push, which it prints). The
+  merge passes `--match-head-commit`. It lists worktrees still on the merged branch so
+  their owners clean up.
+- `verify-landed.sh --commit <sha> [--ff [--idle-primary <path>]]` fetches, checks that
+  the default branch contains the commit, and checks the local default; `--ff`
+  fast-forwards a clean default checkout. `--preflight --ff` checks eligibility before
+  landing. After a blocked check, rerun this script, not `merge-pr.sh`.
+- `check-landing.py [--path <checkout>] [--base <ref>]` reports whether a checkout's
+  work is in the base branch by content, so squash-merged branches count as landed, and
+  lists live processes whose working directory is inside the checkout (Linux only).