@bompus/house-rules 0.11.0 → 0.14.0

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

package/rules/references/thread-visuals.md

@@ -0,0 +1,45 @@
+## Visuals in issues, discussions and comments
+
+Use an image, chart or diagram only to show a spatial interface state, compare
+before and after, show a trend across multiple measurements, or explain a flow
+with branches. Otherwise use text, a table or a short code block. Most comments
+are text. The exception is a qualified measured result. It lies outside its declared
+variation criterion and the outputs are identical. An
+issue, discussion or pull request that reports one opens with a headline chart
+of it, so a reader sees the benefit before reading the body. A result with
+one row that moved by less than 10% stays text and a table.
+Draw it with the `hr-writing-pr` skill's `scripts/benefit-chart.py` when that skill
+is installed, or with any charting tool. A comment that only adds data to an
+existing thread stays text and a table.
+
+Keep the exact numbers, steps or states in text beside the visual, and give the
+image alt text, so a reader who cannot see it loses nothing. Many readers of an
+issue or pull request are agents that cannot parse an image. Every value, label
+and caveat in the visual also appears as body text, such as a table, a list or a
+described state. The alt text says what the image shows, not only that it is a
+chart. Label a mockup as an
+illustration. Preview a chart or diagram design you have not used before with the
+user before posting it.
+
+The destination is usually public. Before posting, check the capture for private
+paths, private project or repository names, local usernames, tokens and other
+credentials, and follow any capture rule the repository or your host rules
+state, such as a required theme.
+
+Attach the file through the project host's supported route. On GitHub,
+`gh issue create`, `gh issue edit`, `gh issue comment` and `gh pr comment`
+accept `--attach '<file>#<alt text>'` in recent `gh` versions (check
+`gh <command> --help`). In a browser form (the route for an issue form), use
+the form's upload field when it renders. When it does not, add the file through
+a text field's attach control and replace the default alt text `Image` that the
+upload inserts. Do not commit the image to the repository or use a
+third-party image host.
+
+Where the CLI has no attach route (`gh discussion` has
+no `--attach` flag) or refuses the upload, such as for lack of write access to
+the repository, use a browser signed in to the user's GitHub account: the page's
+upload field takes the file where `--attach` does not. Hand the user the exact
+text and the file only when the host has no such browser or the upload fails
+there, and do not post another way.
+
+Posting to an external project still needs the user's direction.

package/setup.mjs

@@ -1,11 +1,15 @@
 // Numbered selection flow. Only the existing revision-checked config writer saves.
 import { createInterface } from "node:readline";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs, stripVTControlCharacters } from "node:util";
 import { configurationPath, modifierList } from "./composition.mjs";
 import {
   changeSelection,
+  QUESTION_MODIFIERS,
+  QUESTION_PRESETS,
   configCommand,
   readConfiguration,
   selectionChanges,
@@ -19,7 +23,7 @@ const HELP = `Choose guidance with numbered prompts:
   house-rules setup [--config PATH] --json
 
 toggle N [N ...] or toggle NAME changes the listed choices.
-questions plain|coded|cards chooses the question format.
+questions default|plain|coded|cards chooses how questions are asked.
 search TEXT, clear search, show selected, show all, help N
 next, back, save (on Review), refresh (after a stale revision), cancel
 
@@ -34,6 +38,46 @@ const quote = (value) =>
     ? `'${value.replaceAll("'", "''")}'`
     : `'${value.replaceAll("'", "'\\''")}'`;
 
+// How this copy runs and how to apply a saved selection: the npm package has a
+// `house-rules` command, a checkout from the installer is updated by running the installer again.
+const entry = fileURLToPath(new URL("./compose.mjs", import.meta.url));
+const parts = entry.split(/[\\/]/).map((part) => part.toLowerCase());
+const packaged = parts.some(
+  (part, index) =>
+    part === "node_modules" && parts[index + 1] === "@bompus" && parts[index + 2] === "house-rules",
+);
+const cliCommand = () =>
+  packaged
+    ? "house-rules"
+    : `${process.platform === "win32" ? "& " : ""}${quote(process.execPath)} ${quote(entry)}`;
+
+const installerPath = () =>
+  join(dirname(entry), process.platform === "win32" ? "install.ps1" : "install.sh");
+// The installer composes <config dir>/house-rules.json only.
+const usesInstaller = (configPath) =>
+  !packaged && existsSync(installerPath()) && basename(configPath) === "house-rules.json";
+
+function recomposeCommand(configPath) {
+  const configDir = dirname(configPath);
+  const checkout = dirname(entry);
+  const windows = process.platform === "win32";
+  const installer = installerPath();
+  if (!usesInstaller(configPath))
+    return `${cliCommand()} --config ${quote(configPath)} --out ${quote(join(configDir, "rules.md"))}`;
+  // The installer reads these variables, so a copy or config outside the defaults must name them.
+  const home = homedir();
+  const data =
+    process.env.XDG_DATA_HOME ?? (windows ? process.env.LOCALAPPDATA : join(home, ".local/share"));
+  const config = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+  const env = [
+    ["HOUSE_RULES_DIR", checkout, join(data ?? "", "house-rules")],
+    ["HOUSE_RULES_CONFIG_DIR", configDir, join(config, "house-rules")],
+  ].filter(([, actual, normal]) => resolve(actual) !== resolve(normal));
+  return windows
+    ? `${env.map(([name, value]) => `$env:${name}=${quote(value)}; `).join("")}& ${quote(installer)}`
+    : `${env.map(([name, value]) => `${name}=${quote(value)} `).join("")}sh ${quote(installer)}`;
+}
+
 export async function setupCommand(argv) {
   let values;
   try {
@@ -100,6 +144,10 @@ export async function setupCommand(argv) {
       !projection.modifiers.includes("coded-offers")
     )
       projection.modifiers.push("coded-offers");
+    if (projection.modifiers.includes("model-default-questions"))
+      projection.modifiers = projection.modifiers.filter(
+        (name) => !["coded-offers", "question-cards"].includes(name),
+      );
     return selectionReport(projection, snapshot.path);
   };
   let baseline = catalog(); // Malformed layers, composition or legacy names still stop setup.
@@ -108,7 +156,7 @@ export async function setupCommand(argv) {
     const report = current.report ?? baseline;
     const unavailable = (snapshot.config.modifiers ?? []).filter((name) => !known.has(name));
     const modifiers = [
-      ...report.modifiers.filter((m) => !["coded-offers", "question-cards"].includes(m.name)),
+      ...report.modifiers.filter((m) => !QUESTION_MODIFIERS.includes(m.name)),
       ...unavailable.map((name) => ({
         name,
         enabled: true,
@@ -147,7 +195,7 @@ export async function setupCommand(argv) {
     console.log(command);
   };
   const show = () => {
-    print(`Choose guidance / ${["Modifiers", "Skills", "Review"][stage]}`);
+    print(`Choose guidance / ${["Optional rules", "Skills", "Review"][stage]}`);
     print(`Config: ${snapshot.path}`);
     const current = draft();
     if (current.error) print(`Selection needs repair: ${current.error.message}`);
@@ -172,7 +220,7 @@ export async function setupCommand(argv) {
         "Reproduce with the existing config command (POSIX shell on Unix, PowerShell on Windows):",
       );
       printCommand(
-        `house-rules config set --config ${quote(snapshot.path)} ${flags.join(" ")} --apply --expect ${quote(snapshot.revision)}`,
+        `${cliCommand()} config set --config ${quote(snapshot.path)} ${flags.join(" ")} --apply --expect ${quote(snapshot.revision)}`,
       );
       print("Review personal rule overrides. Setup does not interpret or edit their prose.");
       print(
@@ -181,18 +229,23 @@ export async function setupCommand(argv) {
       print("save / back / cancel");
       return;
     }
-    print("Core rules: always on. Modifiers are opt-in; skill selection follows your config.");
+    print("Core rules: always on. Optional rules are opt-in; skill selection follows your config.");
     if (stage === 1) {
       const skills = rows().filter((row) => row.kind === "skill");
       print(
         `${skills.filter((row) => row.enabled).length} of ${skills.length} available skills selected.`,
       );
     }
-    print(`Question format: ${questions ?? baseline.questions}. Use questions plain|coded|cards.`);
+    print(
+      `Question format: ${questions ?? baseline.questions}. Use questions default|plain|coded|cards.`,
+    );
+    const kind = stage === 0 ? "modifier" : "skill";
+    // With nothing selected yet, the selected-only view would be empty, so list every choice.
+    const nothingSelected = !rows().some((row) => row.kind === kind && row.enabled);
     const visible = rows().filter(
       (row) =>
-        row.kind === (stage === 0 ? "modifier" : "skill") &&
-        (!selectedOnly || row.enabled) &&
+        row.kind === kind &&
+        (!selectedOnly || nothingSelected || row.enabled) &&
         `${row.name} ${row.description}`.toLowerCase().includes(query.toLowerCase()),
     );
     for (const row of visible) {
@@ -203,7 +256,9 @@ export async function setupCommand(argv) {
     }
     if (!visible.length)
       print(`No matches for ${JSON.stringify(query)}. Use clear search or show all.`);
-    if (selectedOnly)
+    if (selectedOnly && nothingSelected)
+      print("Nothing is selected yet, so every choice is listed. Use toggle N to select.");
+    else if (selectedOnly)
       print("Showing current selections. Search for relevant additions or use show all.");
     if (baseline.unavailable.length)
       print(`Retained unavailable exclusions: ${baseline.unavailable.join(", ")}`);
@@ -268,8 +323,8 @@ export async function setupCommand(argv) {
           selectedOnly = false;
         } else if (command.startsWith("questions ")) {
           const preset = command.slice(10);
-          if (!["plain", "coded", "cards"].includes(preset))
-            throw new Error("Choose questions plain|coded|cards.");
+          if (!QUESTION_PRESETS.includes(preset))
+            throw new Error("Choose questions default|plain|coded|cards.");
           questions = preset;
         } else if (command.startsWith("toggle ") || command.startsWith("help ")) {
           const help = command.startsWith("help ");
@@ -306,6 +361,19 @@ export async function setupCommand(argv) {
             } else {
               const enabled = !(intent.get(`${row.kind}:${row.name}`)?.enabled ?? row.enabled);
               intent.set(`${row.kind}:${row.name}`, { kind: row.kind, name: row.name, enabled });
+              // A rule that expects a skill would otherwise warn on every compose.
+              for (const need of enabled ? (row.requires ?? "").split(",") : []) {
+                const skill = available.find((r) => r.kind === "skill" && r.name === need.trim());
+                // A skill listed in the same command keeps the toggle the user typed.
+                if (!skill || chosen.includes(skill)) continue;
+                if (intent.get(`skill:${skill.name}`)?.enabled ?? skill.enabled) continue;
+                intent.set(`skill:${skill.name}`, {
+                  kind: "skill",
+                  name: skill.name,
+                  enabled: true,
+                });
+                print(`Also selected the ${skill.name} skill, which ${row.name} expects.`);
+              }
             }
           }
         } else if (command === "refresh") {
@@ -353,11 +421,13 @@ export async function setupCommand(argv) {
           }
           print(`Selections saved: ${saved.path}`);
           print(
-            "Output was not regenerated and hosts were not connected by setup. Recompose with:",
-          );
-          printCommand(
-            `house-rules --config ${quote(saved.path)} --out ${quote(join(dirname(saved.path), "rules.md"))}`,
+            "Output was not regenerated and hosts were not connected by setup. To apply the selections, run:",
           );
+          printCommand(recomposeCommand(saved.path));
+          if (!usesInstaller(saved.path))
+            print(
+              "This rebuilds the rules only; add --skills-out with a new or empty directory to rebuild the skills too.",
+            );
           return;
         } else
           throw new Error(

package/skills/hr-agent-guidance-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-agent-guidance-audit
-description: Audit and simplify agent-facing rules, skills and linked documentation within the requested repository scope. Use for guidance cleanup, skill description accuracy, token/clarity audits, or contradictions and duplication across agent instructions.
+description: Audit and simplify agent-facing rules, skills and linked docs within the requested repository scope. Use for guidance cleanup, skill description accuracy, token/clarity audits, contradictions and duplication across instructions, or deciding which skills, docs and scripts to retire or merge.
 ---
 
 # Agent guidance audit
@@ -55,7 +55,12 @@ Verify effects before changing:
   for drift risk, not savings.
 
 When reviewing research records, staged lessons or guidance overrides, read
-[the record-maintenance method](references/records-and-lessons.md). For selected
+[the record-maintenance method](references/records-and-lessons.md). When
+deciding what to retire or merge, or triaging a usage report, read
+[the verdict method](references/retirement-verdicts.md). To shrink always-loaded
+guidance by measurement (size it, migrate, condense, test each rule with and
+without it, recommend opt-ins), follow
+[the pruning workflow](references/prune-workflow.md). For selected
 loading or behavior verification, locate the `hr-agent-guidance-refresh` bundle
 and read its `references/verification.md`; keep unavailable evidence unverified.
 
@@ -76,9 +81,9 @@ settles it or the resolution would loosen a prohibition or safety rule.
 ## Verify and report
 
 Check links, invocation metadata and affected installer behavior. Run required
-checks and verify installed bytes where restoration is in scope; do not claim
-runtime loading from file equality alone. Follow the repository's integration
-and cleanup boundary.
+checks and verify installed bytes where installing the files is in scope; do
+not claim runtime loading from file equality alone. Follow the repository's
+integration and cleanup boundary.
 
 Report what was removed or simplified, why it was safe, checks performed and
 remaining limits. Give each finding its `file:line`, quoted evidence, problem

package/skills/hr-agent-guidance-audit/references/prune-workflow.md

@@ -0,0 +1,72 @@
+# Pruning workflow for rules, skills and docs
+
+Use this when the goal is a smaller, clearer set of always-loaded guidance, not
+only a read-through. Each step produces a list you can act on; skip a step the
+request does not need.
+
+1. **Size it.** List every file the agent loads (composed rules, skill
+   descriptions, linked docs) with its byte count, largest first. The always-on
+   rules and the skill catalog are the costly part; a reference loaded on demand
+   is cheap. Record the totals so the end result can be compared.
+2. **Find what belongs elsewhere.** For each doc, script and agent definition
+   outside the portable rules repository, ask whether another project could use
+   it unchanged. Where the repository owns the file and the task covers the move,
+   move it into the shared repository and leave a pointer in the old place;
+   otherwise report it as a candidate without editing. Keep host mechanics,
+   personal choices and measurement data where they are.
+3. **Condense and clarify.** Cut repeated sentences, filler and wording tuned
+   for older models. Prefer positive wording ("do X") to prohibitions and plain
+   absolutes ("always", "never") where the rule really is absolute. Keep every
+   requirement a test or another file names. Measure each edit as
+   before/after bytes; if the total barely moves, say so rather than cutting
+   reasons.
+4. **Screen for unnecessary rules.** A rule earns its place only if the
+   model does worse without it. In the house-rules checkout,
+   `evals/end-of-reply/run.mjs --screen` runs each scenario twice, with the rules
+   and with the one rule named in the scenario's `without:` pattern removed:
+   - Write a scenario for the rule: `expect: reply`, a transcript where the rule
+     decides the outcome, and `requiredPattern` or `forbiddenPattern` for the
+     right and wrong reply. Add `without:` as a regular expression matching the
+     rule's exact text once. Add `allowRead: true` unless the scenario is about
+     the first call itself: a model that reads a file before answering is
+     otherwise graded on the read.
+   - Test the models you use, at the effort you use: Claude Opus 5.5 and
+     Sonnet 5.5, GPT-6.1 Sol, SWE-2 and Muse Spark 1.3 Contributor. Grok 4.7 is
+     optional: it took about three times as long as the others for the same
+     runs. One wrapper per agent is in `evals/end-of-reply/models/`; its README
+     section has the commands.
+   - Check for rule leaks first. Every one of these agents loads your own rules
+     by default, so probe each wrapper (the README gives the question) and
+     confirm none of your own rule files appear; a few known extras (Devin's own
+     global `AGENTS.md`, OpenCode's installed-skill list) are listed in the
+     README. A leak makes the "without" arm obey the rule anyway.
+   - Use `--runs 4` or more. This pass/fail screening is a deliberate exception
+     to the 3-runs-per-arm default for performance claims in `hr-benchmarking`,
+     because a count of passes needs more runs than a timing range does. Four
+     runs separate a rule only when the arms differ by 4 and 0; a smaller gap
+     needs 9 runs per arm before you act on it (8 of 9 against 3 of 9 gave
+     p = 0.05).
+   - Read the output: "rule helps" keeps the rule; "no difference" on all
+     models makes it a removal candidate; "fails with the rule" means fix the
+     scenario first, because it tests nothing. A scenario that fails in both
+     arms on most models (the pattern is too narrow, or the transcript lacks
+     what the rule needs) discriminates nothing; rewrite it and confirm that
+     it passes clearly more often with the rule than without before using its result.
+   - A harness that grades only the first reply penalizes models that read
+     before answering, whatever the rules say. Use `allowRead`, and compare a
+     model's failures with its replies before blaming the rule.
+   - A removal candidate is a recommendation, not a deletion. Confirm with
+     more runs, and offer the user the choice; moving the rule to an opt-in
+     modifier is the middle option.
+5. **Check against vendor guidance.** Read the current prompting guides of the
+   model vendors you target. Treat them as evidence: remove emphasis and steering
+   the guides now call unneeded only where the change keeps every domain
+   safeguard and explicit user choice, and keep what they recommend.
+6. **Recommend opt-ins.** A rule that matters only for some users or setups
+   belongs in a modifier that is off by default. List each candidate with who
+   needs it.
+7. **Land and adopt.** Run the full test suite and the end-of-reply eval with
+   the final composed rules, before and after, on each model. Land through the
+   repository's path, then adopt the new revision wherever it is pinned and
+   install the result. Report the size totals from step 1, the screening table,
+   and what you left alone.

package/skills/hr-agent-guidance-audit/references/records-and-lessons.md

@@ -46,7 +46,7 @@ or role owner; guidance points there. Distinguish explicit user preferences,
 temporary workarounds and model-performance choices. An adopted framework or
 runtime dependency needs the same record.
 
-Recheck affected overrides during upgrades, restoration, guidance audits or
+Recheck affected overrides during upgrades, reinstalls, guidance audits or
 model re-evaluation. Reopen model routing when aliases, effort levels, plan
 limits or observed quality/usage change. Compare current official documentation
 and effective runtime behavior. Record coverage; an installation drift check

package/skills/hr-agent-guidance-audit/references/retirement-verdicts.md

@@ -0,0 +1,49 @@
+# Retirement and merge verdicts
+
+Use this method when an audit asks which skills, guidance files, docs or
+scripts are still needed, or when a scheduled usage report lists candidates.
+
+## Inventory
+
+Cover skills, rule files, agent-facing docs, and the scripts, scheduled jobs
+and services that support them. A script counts as unused only when nothing
+outside its own tests and itself calls, schedules or documents it.
+
+Usage evidence is optional and only supporting. When session transcripts are
+available, count a use only when the skill or file was invoked or loaded for
+real work. Exclude sessions that only list, edit, audit or install it, and
+give anything added recently a grace period before low use counts against it.
+Low use alone never justifies retirement: rare skills can guard rare,
+expensive situations.
+
+## Verdicts
+
+Give each candidate exactly one verdict, with its evidence:
+
+- **Exact duplicate**: name the other copy and which one owns it.
+- **Near duplicate**: name the skill to merge into and list what the
+  retired side contributes that the survivor lacks. Carry those ideas over
+  in your own words, respecting the source's license.
+- **Covered by X**: quote the line or section of X that does the same job.
+  If you cannot quote it, the verdict is not "covered".
+- **Not applicable**: say to whom it does not apply and why.
+- **Keep**: name the concrete situation it serves.
+
+Verify every "covered by", provenance or history claim against the source
+before stating it. A plausible guess about why something exists is not
+evidence.
+
+## Shared source and local installs
+
+When the guidance ships to other people, give two verdicts: whether the
+shared source should keep it, and whether this installation should. Do not
+assume readers of shared guidance have the same optional tools, indexes or
+services as the auditing host. A skill made redundant here by a local tool
+can still be the only option for everyone else.
+
+## Report
+
+Group candidates by verdict. For merges, name the surviving skill, the
+carried-over ideas and the callers, tests and installer lists that must
+change. For retirements, name what replaces each item. Offer retirements and
+merges for the user's selection; do not delete on usage evidence alone.

package/skills/hr-agent-guidance-refresh/SKILL.md

@@ -1,68 +1,36 @@
 ---
 name: hr-agent-guidance-refresh
-description: "Check deployed agent components and reread changed guidance, skills and subagent definitions; verify configuration and tooling discovery. Use for reload requests, start/resume, or an update signal before affected work."
+description: "Reread the agent guidance a session loaded (instruction files, skills and subagent definitions) and report what changed since. Use for reload requests, session start or resume, or a signal that guidance was updated."
 ---
 
 # Agent guidance refresh
 
-Injected rules and skill catalogs can retain an earlier snapshot. Use the
-host's approved deployed target, not an upstream commit or pending source edit.
-This skill reads guidance and checks supported discovery; it does not authorize
+Injected rules and skill catalogs can retain an earlier snapshot. This skill
+rereads guidance and checks supported discovery; it does not authorize
 installation, configuration changes, model calls, new probes or provider restarts.
-A pushed-source notice remains pending until the affected component is deployed.
 
-1. At start/resume, or the next affected-action boundary after an update signal,
-   check the host's deployed revision or content fingerprints against this
-   session's last refresh record. Include the repository instruction root and
-   applicable shared rules, selected skills and their resources, subagent
-   definitions, configuration, supporting scripts and tooling. Scope this
-   inventory to components the session inherits or uses. Record effective
-   deployed identities through supported host discovery without exposing secrets.
-   If no record exists, read the applicable guidance and establish that baseline.
-   An unavailable target or approval record stays unverified; do not infer approval from a hash.
-2. Keep only the newest pending target per component. An unchanged identity
-   needs no repeated read or notice. Coalesce duplicate signals; a source revision
-   and its deployed target remain separate evidence. Routine updates wait for
-   the next affected action after the active operation ends. Keep idle and
-   offline sessions pending until resume; do not start a model turn for a notice.
-   Skip excluded skills and preserve explicit invocation policies, settings and repository safeguards.
-3. Finish an active operation before refreshing. When an evaluation fixes its
-   guidance or tools, record the target as held until that context is released.
-   Do not change its inputs. If an incompatible update prevents the next
-   affected operation, hold that operation for supported recovery instead of
-   using an incompatible context or forcing a restart.
-4. Read changed deployed instructions, affected skill resources and subagent
-   definitions through their local indexes and necessary references. Inspect
-   changed configuration through supported redacted summaries, never secret
-   values. Verify affected script or tool versions and the actual catalog,
-   configuration or callable interfaces the session would use next. Reading a
-   script does not run or deploy it. Recheck assumptions invalidated by changes.
-   Use supported context, catalog or tool refresh only when its capability and
-   authorization are established. A reread does not prove injected context,
-   effective subagent definitions, process configuration or tool discovery changed.
-   Record unsupported or failed paths. If a restart, reinstall or reload is needed,
-   report the component and required action as a blocker; do not perform it without
-   existing authorization.
-5. Record each component's source and deployed targets, affected paths, refresh
-   action and observed effective identity. Keep these results separate
-   from installed-byte checks, catalog discovery, delivery acknowledgements and
-   behavior tests. Mark components current only for the evidence obtained;
-   keep pending, held, unsupported and offline states explicit. Disconnected
-   sessions compare targets on resume. Update the pending target without
-   repeating its notice; report blockers when action is needed. Never treat an
-   acknowledgement as proof of loaded context.
+1. At start or resume, and at the next affected-action boundary after an update
+   signal, list what the session inherits or uses. That is the repository
+   instruction root, the rules, docs and skills it names with their resources,
+   any subagent definitions, and the configuration, supporting scripts and tools
+   it relies on. Compare them with this session's last refresh record. If no
+   record exists, read the applicable guidance and establish that baseline.
+2. Finish the active operation before refreshing. When an evaluation fixes its
+   guidance or tools, hold the update until that context is released and leave
+   its inputs unchanged.
+3. Reread changed instructions, affected skill resources and subagent definitions
+   through their indexes and the references they need. Inspect changed
+   configuration through redacted summaries, never secret values, and check the
+   versions or interfaces of the scripts and tools the session will use next.
+   Recheck assumptions the changes invalidate. A reread does not prove that
+   injected context, effective subagent definitions or tool discovery changed.
+   Use a context or catalog refresh only when the host supports it and you are
+   authorized. If a restart, reinstall or reload is needed, report the component
+   and the action as a blocker; do not perform it without existing authorization.
+4. Record what you reread, the identity you observed for each component and
+   what stays unverified. Report changed behavior or a blocker when it needs
+   attention; an unchanged check stays quiet.
 
 When guidance verification is selected, read
 [the verification method](references/verification.md) for evidence layers,
-answer-blind probes and scoped adoption checks.
-
-For an explicit source-update request, follow the owning checkout's adoption
-procedure and authorization before changing files. Upstream/source drift alone
-is not a newer deployed target. Report changed behavior or a blocker when it
-needs attention; an unchanged check stays quiet.
-
-When the host supplies Swarmail updates, follow the connected product
-instructions and `swarmail updates --help`. If those instructions are hidden
-or omit needed detail, locate the owning checkout's `docs/updates.md` at the
-installed or approved revision. Keep unsupported details unverified. Other
-hosts may supply a different qualified update signal.
+behavior checks that do not reveal the expected answer, and scoped adoption checks.

package/skills/hr-agent-guidance-refresh/references/verification.md

@@ -39,7 +39,7 @@ a probe pass.
 Follow the owning source's supported pin, generator and scoped installer when
 adoption is selected. Preserve account settings, exclusions, invocation policy,
 local patches and repository safeguards. Check destinations and repeat the
-scoped restoration to verify no further writes. Do not infer approval or
+scoped install to verify it writes nothing further. Do not infer approval or
 active-context loading from byte equality or an upstream commit.
 
 Record each layer's result separately. Unsupported refresh paths remain

package/skills/hr-audit-choices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-audit-choices
-description: "Audit the decisions an implementing agent made on the user's behalf, not its diff: trace the work into a choices ledger with a verdict per choice, changing no code. Use when the user asks which choices or assumptions went into implemented work, before landing delegated or AI-implemented work the user wants to review by decision, or when a fix works but may be shaped to one failing case."
+description: "Audit the decisions an implementing agent made for the user, not its diff: trace the work into a choices ledger with a verdict per choice, changing no code. Use when asked which choices or assumptions went into implemented work, before landing delegated or AI-implemented work the user wants reviewed by decision, or when a fix may be shaped to one failing case."
 ---
 
 # Audit choices