@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-code-review/references/evidence.md

@@ -0,0 +1,57 @@
+# Assess review evidence
+
+Apply this method to the pinned review scope, locally or in a read-only review.
+The repository owns required checks, gates and waivers; this method adds no
+permission to run commands, edit files or expand the review scope.
+
+## Read the scope and its evidence
+
+Start from the requested intent, diff, changed paths and verification evidence.
+Use an existing review packet when supplied; do not require a particular
+artifact path or release workflow. Read applicable repository guidance not
+already in context. Report missing scope or required evidence.
+
+Inspect changed regions first. When a supplied diff or shell is unavailable,
+locate those regions with available read-only search and file tools. Trace
+source, tests and consumers where needed to assess a concrete risk. Respect
+scope limits; name dependencies needing assessment outside them rather than
+asserting they are safe.
+
+Check behavior against requirements, invariants and testing standards. Treat a
+completion claim as a hypothesis to refute from the diff and evidence. For a
+bug fix, look for evidence that its regression test failed on the pre-fix code
+for the intended reason and passed after the fix. Missing evidence is a
+verification limit; whether it blocks follows the project's gate rules.
+
+## Account for weakened tests
+
+Before judging the change, list each existing test the diff deletes, skips,
+marks as expected to fail or weakens. Include narrowed assertions, widened
+tolerances and expected values rewritten to match new output. Require a stated
+reason tied to the changed requirement or supported test-audit evidence.
+An unexplained change is missing verification; classify it under the project's
+verification requirements rather than accepting the new output as its reason.
+
+When test auditing is in scope, use the installed `hr-test-audit` bundle's
+method and floor guard if available and command execution is authorized.
+The guard detects some weakening patterns; a clean result does not replace
+reading changed assertions. Report unavailable coverage without installing or
+running tools outside the selected scope.
+
+## Trace emitted results
+
+For input-to-output code such as resolvers, parsers or extractors, trace every
+path in scope to its emitted result before reporting performance or structure
+findings. Start from the nearest test fixture and construct the smallest input
+change that would emit a wrong result or drop a correct one. Report a confirmed
+counterexample with the fixture, changed input, expected and emitted results,
+and `path:line` for the steps. When no counterexample is found, record the paths
+and cases assessed; do not invent a failing result to fill the report.
+
+## Ground the result
+
+Do not repeat verified lint, type or format checks or invent release gates.
+Confirm each finding with its file and line, violated requirement and evidence.
+Distinguish confirmed defects from unresolved questions and omit speculative
+findings. Report missing evidence and unassessed requirements separately.
+A review pass does not establish that unrun checks passed.

package/skills/hr-code-review/references/impact.md

@@ -0,0 +1,103 @@
+# Change impact
+
+Loaded by `hr-code-review` for its Impact section.
+
+The diff shows what changed. This skill asks what else depends on the old
+behavior, and whether the change is safe for a reason someone has seen work.
+Follow project guidance for commands, test runners and domain safeguards.
+
+## Scope the change
+
+Read the whole diff and the code around each hunk. Write one or two sentences
+on what the change does, including behavior a reader of the diff could miss:
+a new default, a reordered side effect, a changed error type, a value that is
+now computed lazily or cached. If you cannot explain the change yet, read the
+code first (see `hr-explain-code`) before judging its impact.
+
+When the reason for old behavior affects the risk, inspect relevant history.
+Use a scoped `git log -p` or `git log -S<symbol>` where it can answer that
+question; a literal symbol search may miss renames or indirect behavior.
+
+## Look past the call sites
+
+List direct callers quickly; a compiler or a symbol search usually covers them,
+and they are rarely where the surprise is. Spend the effort on coupling that a
+symbol search does not see:
+
+- **Stored and serialized shapes.** Field names, enum values, JSON keys,
+  cache keys, database columns, file formats and anything written today and
+  read back after a deploy or by an older version.
+- **Other readers.** Another process, service, job, script or client that
+  consumes the output, the queue message, the log line or the API response.
+  Search for the literal strings, not only the symbol.
+- **Supported surfaces.** Other screens, entry points, clients, providers and
+  connection modes that reach the behavior. Check reverse operations and
+  state transitions too, such as enabling/disabling or connecting/disconnecting,
+  when the feature supports them. Use the project's actual supported cases;
+  do not invent surfaces or expand project-mandated verification to cover
+  unsupported cases. Keep the focused probe below when existing tests do not
+  exercise a load-bearing assumption.
+- **Timing.** Startup order, background workers, scheduled jobs, retries,
+  timeouts and shutdown. A change that is correct on the request path can
+  break a job that runs once a night.
+- **Configuration.** Environment variables, feature flags, defaults that
+  differ between environments, and code paths only one flag value reaches.
+- **Dependencies as pinned.** How the library behaves at the version in the
+  lockfile, including local patches the project applies, not the version in
+  current upstream docs. Check the effective installed source, patch files or
+  changelog when the change relies on a specific behavior.
+
+Each search is a finding. "No other reader of `order_status` found in this
+repository or its deploy config" is worth reporting; say where you looked.
+Never name a caller, consumer or API you have not seen at a real location.
+
+## Find the load-bearing assumption
+
+A change that looks risky usually rests on one or two facts: no
+consumer reads the old field, the flag is off in production, the migration
+runs before the new code. Name those assumptions explicitly. Then put most of
+the remaining effort into confirming or breaking them, rather than adding more
+hypothetical risks to a list.
+
+A risk that depends on an assumption you have already confirmed does not need
+its own entry. A risk nobody can check deserves a sentence on why it cannot be
+checked and who could.
+
+## Back each claim
+
+A claim can rest on your word alone, on a source location that shows it, on
+a failure path you walked step by step, or on real code that ran and gave the
+result. These are not equal, and the reader cannot tell them apart unless you
+say. Next to each important claim, state in a few words what backs it: "the
+only reader is `billing/export.py:88`", "traced: a missing key falls through
+to the default", "ran `test_legacy_payload`, passes".
+
+When feasible within the selected scope, reproduce the behavior in the
+running application for the strongest backing. Get the load-bearing assumption
+at least to something that ran. A careful trace is enough for lesser claims.
+A claim with nothing behind it is a gap; report it as one instead of dressing it up.
+
+Prefer evidence that already exists: run the tests that cover the changed code
+and read what they actually assert. When none exercise the assumption, write
+the smallest probe that does, such as a script that round-trips an old
+serialized record through the new code. Keep probes outside committed source,
+or delete them before reporting, and say in the report that you did.
+
+## Report
+
+Use these parts, in order:
+
+1. **What it does**: the change in plain terms, with the non-obvious behavior.
+2. **What it relies on**: each load-bearing assumption, its support, and
+   whether it held.
+3. **Risks**: for each real one, the location, how likely it is, what it costs
+   if it happens, and how to check it.
+4. **Ruled out**: concerns you examined and dismissed, with where you looked.
+   This keeps a reviewer from redoing the same search.
+5. **Before merging**: the specific check to run, with the command when there
+   is one, or "none needed" with the reason.
+
+Keep the list of risks short. Three real ones with locations beat fifteen
+possibilities. Before sharing publicly, follow the project's data-classification
+policy. Remove credentials, personal data, private project names and URLs,
+and local paths.

package/skills/hr-code-review/references/panel-adjudication.md

@@ -0,0 +1,58 @@
+# Adjudicate a panel
+
+Use this after a panel of models has answered the same brief and you must turn
+their replies into one result. It covers reading the replies, checking what they
+cite and reporting the choices. Resolving the seats comes first and is in
+[the panel plan contract](panel-plan.md).
+
+## Read the replies
+
+1. Extract each seat's text from its log. List what the seats agree on and where
+   they contradict each other.
+2. For every claim that carries weight, note whether each seat cites a receipt
+   that passes the check below. Two seats that cite the same line, or neither
+   citing anything, are unverified agreement, not corroboration.
+3. Run the citation gate on the logs:
+
+   ```sh
+   node <skill-directory>/scripts/check-receipts.mjs --repo <repo> <panel-log>...
+   ```
+
+   A citation written as `` `name` (path:line) `` passes only when the identifier
+   appears on the cited lines. A bare `path:line` passes when the file has that
+   line. A file named by basename or subpath must resolve to exactly one file in
+   the repository. Exit 1 means adjudicate those claims by hand; it does not mean
+   the panel failed. Exit 2 means no citations were found, a log could not be read or the
+   arguments were wrong; treat it as an unverified gate. Only exit 0 passes. A citation
+   to a file outside the repository fails.
+
+4. A person checks the remaining claims against the source. Record the base you
+   chose, what you took from other seats, what you rejected and which seats
+   dropped out. Keep the logs in the task's scratch directory, not in the repository.
+
+## Compare competing implementations
+
+When the brief asks seats to produce competing implementations and a cheap
+objective check (tests, a diff) exists, state the rubric before the run. The
+result may name a base and graft the others' best parts by hand, so the whole
+stays coherent. Name the premise the choice depends on and challenge it with one
+concrete case, including any hand edits made after the verdict. A graft that fails
+the case is recorded as unresolved, not named a winner.
+
+## Break a tie
+
+Give one seat both verdicts and your adjudication, and ask for residuals only,
+under the same read-only contract. Residuals are what the reference method misses,
+whether each surviving item is earned, and anything wrongly declined.
+
+## Open the report with a receipt
+
+Begin every panel report with this header so the choices can be audited without
+re-reading the thread:
+
+- **Seats:** each model, its family and its role (consensus, contrarian, tie-break).
+- **Settings per seat:** the effort or variant actually used and the one-line rule
+  that selected it (task mapping, seat rule or the user's explicit choice).
+- **Deviations:** any seat that did not run as briefed (fallback route, escalation,
+  dropout) and what replaced it.
+- **Adjudication basis:** the gate result, what was checked by hand and what remains inference.

package/skills/hr-code-review/references/panel-plan.md

@@ -0,0 +1,61 @@
+# Panel plan
+
+Use the bundled `../scripts/panel-plan.mjs` to see which seats stored panel
+preferences resolve to before any model runs. It reads files and prints a plan;
+it never launches a seat, discovers a provider, checks quota or changes a file.
+
+```sh
+node <skill-directory>/scripts/panel-plan.mjs --bindings bindings.json \
+  --author-family <family-of-the-running-session> [--config <house-rules.json>] \
+  [--task task.json] [--project project.json --approve-project <sha256-of-project.json>] \
+  [--approve-metered <alias>] [--json]
+```
+
+Exit 0 means a plan, 1 means named blockers, 2 means unreadable or invalid input.
+`--config` defaults to the house-rules configuration; its `panel` section is the
+user layer. Every input is a regular file, not a symlink.
+
+## Bindings
+
+A user-owned file maps each alias to its exact launch and provenance. Only the
+user's own file belongs here; credentials stay in the provider's authentication.
+
+```json
+{
+  "version": 1,
+  "aliases": {
+    "review-primary": {
+      "families": ["anthropic"],
+      "metered": false,
+      "launch": { "runner": "claude", "model": "<id>", "effort": "<level>" }
+    }
+  }
+}
+```
+
+`launch` is opaque to the resolver: the caller interprets and validates it. An
+omitted `families` means the family is unknown. An unknown family cannot satisfy
+`distinctFamilies` or `excludeAuthorFamily`, and an unknown author family
+cannot be excluded.
+
+## Resolution
+
+1. Layers apply in order user, project, task. A later layer replaces a role's
+   whole candidate list; its new roles append. Project preferences count only
+   with `--approve-project` equal to the file's SHA-256 revision; otherwise the
+   plan is blocked, not silently reduced to the user layer.
+2. Policy only tightens: the lowest `roundLimit`, `fallback: none`,
+   `meteredRoutes: included-only`, and either layer's `distinctFamilies` or
+   `excludeAuthorFamily`. A reduced panel needs the user layer to allow it and no
+   other layer to forbid it.
+3. A candidate is skipped, with a reason, when it has no binding, an unknown or
+   author family under strict policy, or a metered route (never allowed under
+   `included-only`; under `explicit-approval-required` only with
+   `--approve-metered <alias>`). With
+   `fallback: none` only the first candidate of each role is tried.
+4. A role with no eligible candidate blocks the plan, or is dropped when a
+   reduced panel is allowed. Distinct families are found by trying later
+   candidates; if no combination works the plan is blocked.
+
+The plan lists each seat, every skipped candidate and the round limit. It
+certifies configuration only, not availability, quota or effective effort.

package/skills/hr-code-review/references/panel-recommendations.json

@@ -0,0 +1,105 @@
+{
+  "version": 1,
+  "reviewed": "2026-10-14",
+  "entries": [
+    {
+      "id": "opus-5-5-bug-hunt",
+      "profiles": ["balanced"],
+      "task": "Find planted bugs: 105 across two repositories, count fixed",
+      "model": "claude-opus-5-5",
+      "harness": "Claude Code",
+      "route": "Anthropic first-party API",
+      "efforts": [
+        {
+          "effort": "medium",
+          "fixed": 30.3,
+          "listCostUsd": 15.68,
+          "wallMinutes": 17.0
+        },
+        {
+          "effort": "high",
+          "fixed": 31.7,
+          "listCostUsd": 22.25,
+          "wallMinutes": 23.9
+        },
+        {
+          "effort": "xhigh",
+          "fixed": 36.0,
+          "listCostUsd": 34.98,
+          "wallMinutes": 42.5
+        }
+      ],
+      "sourceUrl": "https://bughunt.productcompass.pm/data/benchmark.json",
+      "checked": "2026-10-14",
+      "samples": "3 runs per effort, non-superseded rows; each run covers both repositories",
+      "metric": "planted bugs fixed, mean of 3, out of 105",
+      "timeDefinition": "wall clock summed over both repositories; the board says these runs shared the machine with other work",
+      "costDefinition": "list-rate API price estimated from usage counts, summed over both repositories; not an invoice or subscription billing",
+      "limitations": "Counts planted bugs, not review quality on real changes; repeated attempts are not independent replications; runs used a 1M context window, and the board says its older Opus 5 rows are not comparable to these; the board also lists low and max rungs that this entry leaves out",
+      "rationale": "Medium used about 30% less cost and 29% less time than high for 1.4 fewer bugs; xhigh found more bugs at much higher cost and time. Medium supports a balanced starting point, not equivalence",
+      "status": "current"
+    },
+    {
+      "id": "sonnet-5-5-bug-hunt",
+      "profiles": ["balanced"],
+      "task": "Find planted bugs: 105 across two repositories, count fixed",
+      "model": "claude-sonnet-5-5",
+      "harness": "Claude Code",
+      "route": "Anthropic first-party API",
+      "efforts": [
+        {
+          "effort": "high",
+          "fixed": 34.3,
+          "listCostUsd": 19.85,
+          "wallMinutes": 27.9
+        },
+        {
+          "effort": "xhigh",
+          "fixed": 36.0,
+          "listCostUsd": 42.86,
+          "wallMinutes": 72.7
+        }
+      ],
+      "sourceUrl": "https://bughunt.productcompass.pm/data/benchmark.json",
+      "checked": "2026-10-14",
+      "samples": "3 runs per effort, non-superseded rows; each run covers both repositories",
+      "metric": "planted bugs fixed, mean of 3, out of 105",
+      "timeDefinition": "wall clock summed over both repositories; the board says the machine was idle for these runs, so the times do not compare with the Opus entry's",
+      "costDefinition": "list-rate API price estimated from usage counts, summed over both repositories; the board notes its harness priced this model on another model's table, so the dollar figure is less certain than the usage counts",
+      "limitations": "Same board limits as the Opus entry; its older Sonnet 5 rows are not comparable to these; the board also lists low, medium and max rungs that this entry leaves out",
+      "rationale": "At high and xhigh it found 34.3 and 36.0 planted bugs against Opus's 31.7 and 36.0, at similar cost ($19.85 and $42.86 against $22.25 and $34.98); the times are not comparable. Suggest it only where the user allows that model and effort",
+      "status": "current"
+    },
+    {
+      "id": "muse-wonder-full-bug-hunt",
+      "profiles": ["balanced"],
+      "task": "Find planted bugs: 105 across two repositories, count fixed",
+      "model": "muse-wonder-full-1.0",
+      "harness": "Muse Code (Meta's agent CLI)",
+      "route": "Meta API through a Muse Code subscription plan; no per-use price",
+      "efforts": [
+        {
+          "effort": "xhigh",
+          "fixed": 41.5,
+          "listCostUsd": "unknown",
+          "wallMinutes": 90.5
+        },
+        {
+          "effort": "max",
+          "fixed": 42,
+          "listCostUsd": "unknown",
+          "wallMinutes": 145.3
+        }
+      ],
+      "sourceUrl": "https://bughunt.productcompass.pm/data/benchmark.json",
+      "checked": "2026-10-14",
+      "samples": "2 runs per effort (xhigh 44 and 39, max 44 and 40); each run covers both repositories",
+      "metric": "planted bugs fixed, mean of 2, out of 105",
+      "timeDefinition": "active wall clock summed over both repositories; the board says its machine was shared with other work, and the second run of each effort was resumed in segments across two Muse Code versions, so only its active time is counted",
+      "costDefinition": "unknown: Meta publishes no price for this model, so no dollar figure is recorded",
+      "limitations": "Two runs per effort, and the board measures a median 1.7-point run-to-run move on three-run configurations, so the 0.5-point gap between xhigh and max is not a difference; the board lists no high or lower rung; the board's own note says max led on one repository and xhigh on the other; reachable only through a Muse Code subscription plan, so it fits a user who already has one; its usage draws on that plan's rolling windows, which the board does not measure",
+      "rationale": "xhigh fixed 41.5 planted bugs against Opus 5.5 xhigh's 36.0 and Sonnet 5.5 xhigh's 36.0, in a time the board says is loosely comparable at best, and max added nothing clear for 55 more minutes. Suggest it as an additional seat from a different model family where the user has a Muse Code plan and allows the effort; start at xhigh, and use max only on request",
+      "status": "current"
+    }
+  ]
+}

package/skills/hr-code-review/references/panel-recommendations.md

@@ -0,0 +1,46 @@
+# Panel recommendations
+
+Load this only during [panel setup](panel-setup.md) or when the user asks for
+recommendations. [`panel-recommendations.json`](panel-recommendations.json) holds
+the entries; this page says how to read them.
+
+The entries are dated suggestions for choosing seats, not measured guarantees,
+capability tiers or required seat counts. A model or effort here can be absent from
+a user's catalog, over their limit or excluded by them; the user's limits win.
+
+## Profiles
+
+| Profile    | Intended use                                  | Starting shape                                              |
+| ---------- | --------------------------------------------- | ----------------------------------------------------------- |
+| `quick`    | A bounded question with an objective verifier | Two eligible independent models, limited reply scope        |
+| `balanced` | A substantive review with explicit criteria   | Two models, with an explicitly permitted residual tie-break |
+| `deep`     | A broad or difficult review the user selected | A named larger panel, with receipt checks and adjudication  |
+
+The `quick` and `deep` profiles have no entry yet; current entries are tagged
+`balanced` only. The only recorded evidence here, the Bug Hunt board,
+measures single model-and-effort runs on a find-every-planted-bug task. It does not
+test a two-model panel with a limited reply scope, or a larger panel with receipt
+checks and adjudication, so tagging an entry `quick` or `deep` would extrapolate.
+For those profiles, suggest only the shape in the table and the user's own limits,
+and say that no recorded evidence backs a seat choice.
+
+## Reading an entry
+
+Each entry names the task the evidence measures, the exact model and effort, the
+harness and route, the source URL, the date it was checked, the number of runs, the
+quality metric and its definitions of time and cost, the limits of the evidence and
+why it is suggested. A value that was not recorded is the string `unknown`.
+
+- Compare entries only on the same board and conditions. A board's task time is not
+  a host's time to finish.
+- Public list prices are not a user's subscription billing.
+- A `status` other than `current` (`superseded`, `withdrawn`, `unverified`) stays
+  listed with its evidence and is not suggested.
+
+## Updating
+
+Check an entry again when a model, route, price or benchmark correction changes the
+choice, and when preparing a release. Only changed entries need new evidence. An
+update shows the old and suggested choices, the evidence date, the expected
+tradeoff and the uncertainty; the user confirms before any saved preference
+changes, and installing a newer catalog leaves saved profiles and bindings alone.

package/skills/hr-code-review/references/panel-setup.md

@@ -0,0 +1,54 @@
+# Panel setup
+
+Use this procedure on first use of a panel, or when the user asks to set one up,
+change it or see recommendations. It chooses and saves preferences only. It never
+launches a seat, probes a provider, buys anything or changes a provider setting.
+An explicit request that names every seat can run without setup; saving that
+choice afterwards is a separate opt-in.
+
+## First-use conversation
+
+1. Read the project's review gates and any seats, models or limits the user
+   already named. Find saved preferences and bindings. Do not import unrelated
+   settings.
+2. Use the host's read-only catalog or discovery interface to list routes. Record
+   the host, adapter version, observation time, provider instance and exact model
+   and effort options. Without one, ask the user which routes they have and label
+   the answers user-reported. Do not scan installed agent state.
+3. Show tooling, catalog and account access as separate evidence. An installed CLI
+   proves tooling, a catalog entry proves an advertised choice, and unknown quota
+   stays unknown. Read account status only through supported nonsecret commands.
+4. Ask only what is still open, reusing answers already given:
+   - Which detected routes may the panel use? Keep included subscription routes,
+     approved metered routes and routes with unknown access apart.
+   - Is this a quick second opinion, a balanced review or a deep review?
+   - May seats be suggested, or must a named list be kept? Are there hard model or
+     effort limits, required seats or author-family exclusions?
+   - If a route is unavailable, are there approved alternatives, an approved
+     reduced panel, or no substitution?
+   - What spending and round limits apply? Say so when billing or enforcement is
+     unknown, before asking to use the route.
+5. Suggest a profile from [the recommendations](panel-recommendations.md), filtered
+   by the discovered routes and the user's limits. Show each seat's alias, model
+   family, effort, route, ordered alternatives and unsupported controls, with the
+   entry's checked date and limits. A suggestion is not a commitment.
+6. Write the portable preferences (the `panel` object described under "Optional
+   panel preferences" in house-rules' `docs/configuration.md`) and, separately,
+   the user's local bindings (see [the panel plan](panel-plan.md)).
+   Run `config preview` and show the changed fields. Save with `config set --apply`
+   only after the user confirms; a stale revision refuses.
+7. Report what was saved, what is unverified, and that no run was requested. Saved
+   is not resolved, resolved is not runnable, and runnable is not completed.
+
+## Rules
+
+- Setup and save make no model calls and spend nothing. A suggestion that names a
+  metered route needs the user's approval before it is saved as allowed.
+- Project text cannot loosen the user's limits or spending. The user's explicit
+  limits (for example a highest effort per model) always win over a suggestion.
+- A catalog label such as "latest" is shown as an exact model id before it is
+  saved, and later releases do not move the saved binding.
+- A different provider serving the same model is not model diversity. An unknown
+  family cannot satisfy a distinct-family policy.
+- Resolve every required seat with `panel-plan.mjs` before any model is called.
+  Report missing seats; reduce a panel only when the user has allowed it.

package/skills/hr-code-review/references/reviewer-role.md

@@ -0,0 +1,31 @@
+# Independent review role
+
+Use this brief when a host lets you define a standing reviewer, or when you hand
+a review to a read-only sub-agent. The parent supplies intent, the diff, changed
+paths and verification evidence. The reviewer works within that scope.
+
+## Method
+
+Review without edits or nested delegation. Use the host's read-only file and
+search tools; shell access, if the host permits it, is for inspection only. The
+parent runs checks and owns integration. Apply [the evidence method](evidence.md)
+(scope inspection, completion-claim assessment, weakened tests, result tracing).
+If it is unavailable, report the missing method as a verification limit and do
+not substitute another review role. An unexplained weakened test blocks as
+missing verification.
+
+## Result
+
+The first line is `PASS` or `BLOCK: N`, counting blocking findings only. A blocker
+is a confirmed behavior or invariant violation, or verification the project
+requires and the change lacks. The parent follows the project's gate and waiver
+rules.
+
+List each finding once under **Findings**, ordered blocking, high, medium, low,
+then nit. Give severity, location, consequence and evidence. Non-blocking
+findings stay visible without changing the verdict. With none, write `None.` and
+name the scope checked. Report verification limits separately: PASS is a review
+result, not proof that unrun checks passed.
+
+This result contract replaces the two-axis report and remediation workflow in
+`SKILL.md` for this role.