@bompus/house-rules 0.11.0 → 0.14.0

package/skills/hr-benchmarking/references/tools.md

@@ -10,7 +10,7 @@ relying on flags or interpreting output.
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Whole CLI commands                 | [Hyperfine](https://github.com/sharkdp/hyperfine): repeated runs with wall time, CPU time and peak memory, warmup/preparation and JSON output.         | Works across Linux, macOS and Windows. Declare warm/cold conditions. Since 2.0 commands run without a shell unless `-S` or `--shell` is given; 1.x needs `-N` for that. Peak memory and `--metrics` hardware counters are measured on Linux and macOS only; on Windows use another tool for memory. Check `schema_version` before reading exported JSON; 2.0 changed its layout. |
 | JavaScript operations              | [Tinybench](https://github.com/tinylibs/tinybench), directly or through the project's benchmark runner: warmup and task latency/throughput statistics. | The unit is a task invocation. For 1,000-operation batches, batch p99 divided by 1,000 is the p99 of batch-average costs, not mean operation cost or individual-operation p99.                                                                                                                                                                                                   |
-| HTTP load, including JS/TS servers | [oha](https://github.com/hatoo/oha): a native load generator with concurrency/rate controls, latency distributions and JSON output.                    | Declare protocol, connections, rate, deadlines, keepalive and error handling. Check generator CPU/network limits. Latency correction requires rate limiting with `-q`.                                                                                                                                                                                                           |
+| HTTP load, including JS/TS servers | [oha](https://github.com/hatoo/oha): a native load generator with concurrency/rate controls, latency distributions and JSON output.                    | Declare protocol, connections, rate, deadlines, keepalive and error handling. Check generator CPU/network limits. For fixed-rate load, `--latency-correction` corrects coordinated omission; it is ignored unless `-q` is set.                                                                                                                                                   |
 | Command CPU and memory             | [GNU time](https://www.gnu.org/software/time/manual/time.html), commonly `/usr/bin/time -v`: wall time, CPU and maximum RSS.                           | GNU options differ from shell `time` and BSD/macOS tools. RSS is a lifetime high-water mark for the observed process; it does not isolate retained cache memory.                                                                                                                                                                                                                 |
 | Host or process contention         | Linux [mpstat/pidstat](https://github.com/sysstat/sysstat): processor utilization and process CPU, memory and I/O observations.                        | Sampling can miss short bursts; some counters need kernel support. These explain interference, not application latency.                                                                                                                                                                                                                                                          |
 
@@ -44,14 +44,13 @@ during the interval, attributed to that parent. It shows which process ran
 commands too short-lived to appear in a snapshot, not the commands themselves,
 and can include CPU the children used before the interval started.
 
-Each interval reports `cpuBusyCores` per logical CPU for pinned runs (see
-[fenced-core arm](#fenced-core-arm)). Busy CPU excludes idle, iowait and steal
-time. A CPU brought online or offline during the interval reports `null`; the
-fenced-core gate rejects that interval.
+Each interval reports `cpuBusyCores` per logical CPU. Busy CPU excludes idle,
+iowait and steal time. A CPU brought online or offline during the interval
+reports `null`.
 The collector uses its own `/proc/self/status` `VmHWM` for peak RSS;
 `ru_maxrss` can retain a launcher's inherited high-water mark.
-It records observer CPU and scan duration. Include those costs in the declared
-measurement budget; no negligible-impact claim follows from successful collection.
+It records observer CPU and scan duration. Report those costs beside the results; no
+negligible-impact claim follows from successful collection.
 
 On Windows, `scripts/process-attribution.ps1` accepts mandatory `OutputPath`
 and `StopPath` arguments. It saves process PID, start time, name and cumulative
@@ -60,10 +59,10 @@ before computing deltas. It stops when the stop file exists or after 120 samples
 choose a fresh stop path. Use the host's approved PowerShell invocation without
 changing execution policy.
 
-Neither collector stops jobs, takes a lock or grants admission. Boundary samples
+Neither collector stops jobs or changes any setting. Boundary samples
 miss processes that start and exit between them; unreadable processes are counted
 as missing. CPU contributors explain observed activity, not whether it changed
-application latency. Keep host/resource gates and owner coordination separate.
+application latency.
 
 ## Scheduling controls
 
@@ -72,53 +71,16 @@ establish isolation. Check support for the actual kernel, controller and I/O
 path. Record effective values and unavailable controls for every arm; requesting
 a setting does not prove it took effect.
 
-| Control                                                                          | Effect and limit                                                                                                                                                                                                             |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Nice level](https://man7.org/linux/man-pages/man2/nice.2.html)                  | Lower numeric values raise fair CPU scheduling priority. Permissions and autogroup policy affect the result. This does not reserve a core.                                                                                   |
-| CPU affinity (`taskset`)                                                         | Restricts available CPUs and can affect worker counts and parallelism. It does not reserve exclusive cores. Use it for a declared CPU configuration or a [fenced-core arm](#fenced-core-arm), not automatic noise reduction. |
-| [CPU and I/O cgroup weights](https://docs.kernel.org/admin-guide/cgroup-v2.html) | Adjust relative shares among active sibling groups. Parent limits and controller/device support still apply; a higher weight is not a capacity guarantee.                                                                    |
-| [Process I/O priority](https://man7.org/linux/man-pages/man2/ioprio_set.2.html)  | Depends on the supporting I/O scheduler and path. Process-specific priority does not cover asynchronous writes.                                                                                                              |
-| [Memory protection](https://docs.kernel.org/admin-guide/cgroup-v2.html)          | `memory.low` and `memory.min` protect against reclaim, not memory-bandwidth competition. Excessive hard protection can cause OOM. Memory caps remain limits, not reservations.                                               |
-
-### Fenced-core arm
-
-On a shared host where brief bursts from other sessions keep failing host-wide
-admission, a fenced-core arm keeps other work off chosen CPUs for a finite phase. It is a
-declared sensitivity arm that needs the user's authorization, because it changes
-other sessions' CPU placement:
-
-1. Choose the benchmark CPUs as whole physical cores (include SMT siblings) and pin
-   every arm, its browser or runtime and its children to them.
-2. Move every other thread you are permitted to change off the benchmark CPUs.
-   Record each thread's identity (PID, thread ID, birth ticks) and original
-   affinity. Stop and signal nothing. A thread that sets its own affinity, or
-   is created with an explicit mask, can stay eligible on the benchmark CPUs;
-   the gate still counts its CPU.
-3. Gate on foreign CPU on the benchmark CPUs: their busy time (`cpuBusyCores`)
-   minus the interval CPU of the benchmark's own live processes (`busyCores`).
-   Do not subtract `reapedChildCores`: it can include CPU used before the
-   interval, so it would understate foreign load. Process CPU is not per-CPU,
-   so the subtraction holds only while the whole tree stays on the benchmark
-   CPUs: check every thread's effective affinity at the start and end of each
-   batch, and reject the batch if any ran elsewhere. Boundary checks miss a
-   thread that widens and restores its affinity within the batch; when the
-   workload can change its own affinity, confine the tree with a cpuset it
-   cannot widen. In the same census, record every other permitted thread
-   still eligible on the benchmark CPUs as unfenced. Report host-wide load as
-   context.
-4. At the phase boundary, restore recorded threads after checking their birth
-   ticks. Threads started during the window inherited the fence; give them the
-   CPU set they would otherwise have inherited, usually all CPUs. A still-fenced
-   thread can start another while you restore, so repeat the census until a
-   full pass finds no permitted thread left fenced; threads started after their
-   creator is restored inherit the restored set. Do not freeze processes to stop
-   thread creation. Run this cleanup even when the phase fails.
-
-Report results as constrained to the pinned setting with the effective
-affinities. Processes you cannot change (other users, system services) stay
-unfenced; record them. In a virtual machine, guest affinity does not reserve
-host cores; host activity, shared cache, memory bandwidth and power limits
-still apply.
+| Control                                                                          | Effect and limit                                                                                                                                                                    |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Nice level](https://man7.org/linux/man-pages/man2/nice.2.html)                  | Lower numeric values raise fair CPU scheduling priority. Permissions and autogroup policy affect the result. This does not reserve a core.                                          |
+| CPU affinity (`taskset`)                                                         | Restricts available CPUs and can affect worker counts and parallelism. It does not reserve exclusive cores. Use it for a declared CPU configuration, not automatic noise reduction. |
+| [CPU and I/O cgroup weights](https://docs.kernel.org/admin-guide/cgroup-v2.html) | Adjust relative shares among active sibling groups. Parent limits and controller/device support still apply; a higher weight is not a capacity guarantee.                           |
+| [Process I/O priority](https://man7.org/linux/man-pages/man2/ioprio_set.2.html)  | Depends on the supporting I/O scheduler and path. Process-specific priority does not cover asynchronous writes.                                                                     |
+| [Memory protection](https://docs.kernel.org/admin-guide/cgroup-v2.html)          | `memory.low` and `memory.min` protect against reclaim, not memory-bandwidth competition. Excessive hard protection can cause OOM. Memory caps remain limits, not reservations.      |
+
+In a virtual machine, guest affinity does not reserve host cores; host
+activity, shared cache, memory bandwidth and power limits still apply.
 
 Avoid realtime [CPU](https://man7.org/linux/man-pages/man7/sched.7.html) or
 [I/O](https://man7.org/linux/man-pages/man1/ionice.1.html) classes for generic
@@ -137,6 +99,49 @@ Use a separate diagnostic run; instrumentation changes the work it observes.
 | Which system calls fail or wait?            | Linux [strace](https://github.com/strace/strace/blob/master/doc/strace.1.in): syscall results, errors and ordering.                                                                                                                                   | Interception changes execution; summaries are not ordinary throughput. Traces may contain sensitive paths or payloads.                    |
 | Which native allocations churn?             | Linux [heaptrack](https://github.com/KDE/heaptrack): allocation counts, temporary allocations and allocation stacks.                                                                                                                                  | Symbols improve attribution. Pool allocators need annotations; native allocation traces do not identify individual GC-managed JS objects. |
 
+### Native and JavaScript CPU profiles
+
+Keep native symbols in the diagnostic build. For a Rust release build, use
+`CARGO_PROFILE_RELEASE_DEBUG=line-tables-only CARGO_PROFILE_RELEASE_STRIP=none`.
+For Node JIT frames under `perf`, add `--perf-basic-prof`. A runtime CPU profile
+may attribute a native addon's work to its JavaScript caller; use native samples
+to see inside that call. Node `--cpu-prof` writes separate files for worker threads;
+retain them alongside the main-thread profile.
+
+If `perf report` stalls while expanding a large binary's inline frames, try
+`perf report --stdio --no-inline`. This omits inline-call expansion, so record
+that limit when attributing samples.
+
+### Viewing profiles
+
+[speedscope](https://github.com/jlfwong/speedscope) opens profiles locally as
+interactive flame graphs, including Node CPU profiles and Linux `perf` captures.
+It has been used to inspect JavaScript and native stacks across worker threads.
+To import a `perf` capture, write `perf script > profile.perf` without a custom
+`-F` field list; a partially recognized format can display one stack without an
+import error. Check that the expected threads and stacks appear.
+
+The npm CLI opens the default browser with `speedscope <profile>`. When using a
+controlled browser, serve its packaged `dist/release/` directory and the profile
+over loopback HTTP, then open `index.html#profileURL=<URL-encoded-profile-url>`.
+Use `encodeURIComponent(profileUrl)` for the value so query parameters remain
+part of the profile URL. Choose a free port and keep private captures on the
+local host. Follow the host's browser rules.
+
+### Allocation and waiting-time limits
+
+`heaptrack` unwinds a stack on each native allocation. Start with a small input:
+millions of allocations can make instrumentation dominate runtime. Treat that
+runtime as diagnostic overhead, and verify improvements with uninstrumented runs.
+
+On-CPU profiles omit time spent off CPU. Use a separate
+[bpftrace](https://bpftrace.org/docs) scheduler trace when a thread's wall time
+greatly exceeds its CPU time. Track the target and its descendants, and aggregate
+time between switch-out and switch-in. Off-CPU time includes both blocked time
+and time runnable threads wait for a CPU; sums across threads can exceed wall time.
+Kernel tracepoints, PID namespaces and privileges affect attribution, so verify
+the target's identity and that probes attached before starting it.
+
 Node `--heap-prof` samples allocation activity. Bun's documentation describes
 a full V8-format heap snapshot at exit, not the same sampled allocation history;
 its accepted interval flag does not add allocation sampling. Record which kind
@@ -147,7 +152,7 @@ For a concrete crash, hang or event-tracing question, use the available
 [system tracing tool](https://bpftrace.org/docs). They are optional diagnostic
 tools, not benchmark prerequisites; platform and permissions affect availability.
 
-For TypeScript compiler versus application timing, read [the language reference](javascript.md).
+For TypeScript compiler versus application timing, and for Bun-versus-Node pitfalls, read [the language reference](javascript.md).
 
 ## Correctness and audit evidence
 

package/skills/hr-better-accessibility/SKILL.md

@@ -7,7 +7,7 @@ metadata:
   upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
   upstream_path: skills/better-accessibility/
   local_patches: "Use-when description; reduced-motion kill switch spares spinners; 320px reflow keeps the 2D-content exception; carousel pan-y, touch-callout and real-hardware check (from emilkowalski/skills mobile-native)"
-  house_rules_patches: "Portable provenance and review verdict"
+  house_rules_patches: "Portable provenance and review verdict; unique SVG title and desc ids"
   mobile_native_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/mobile-native/SKILL.md
 ---
 

package/skills/hr-better-accessibility/screen-readers.md

@@ -84,6 +84,7 @@ A missing `alt` is worse than an empty one, because screen readers fall back to
 
 - Decorative SVG: `aria-hidden="true"` and `focusable="false"`, the latter for legacy Edge and IE tabbing. No title needed.
 - Meaningful inline SVG: `role="img"` plus `aria-label="…"`, or a `<title>` as the first child referenced by `aria-labelledby`.
+- Give each `<title>` and `<desc>` an `id` that is unique on the page, such as `chart-revenue-title`. Two inline SVGs that share a bare `id="title"` both resolve to the first one. Keep `<title>` to a short name and make `<desc>` one sentence about what the figure shows, not how it is drawn.
 - Simple cases: `<img src="icon.svg" alt="…">` is the most reliable delivery.
 
 ```tsx

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

@@ -1,6 +1,6 @@
 ---
 name: hr-code-review
-description: Review a branch, PR, working-tree changes or changes since a revision for repository standards and spec conformance. Use only when the user requests a change review. Do not use for simplification-only or strictest maintainability audits.
+description: Review a branch, PR, working-tree changes or changes since a revision for repository standards, spec conformance and what the change can break beyond its diff. Use when asked for a change review, what a change might break before merging, or to set up or change a review panel or for panel recommendations. Not for simplification-only or strictest maintainability audits.
 ---
 
 Two-axis review of the changes the user requested: working-tree changes, a committed branch, or changes since a named revision.
@@ -8,10 +8,22 @@ Two-axis review of the changes the user requested: working-tree changes, a commi
 - **Standards**: does the code conform to this repo's documented coding standards?
 - **Spec**: does the code implement the originating issue / spec?
 
-Keep both axes distinct. Review small scopes locally; use separate read-only
+Keep both axes distinct. Add an **Impact** section when the user asks what the
+change might break, or when the diff changes something read outside its own
+lines: a stored or serialized shape, output another process consumes, timing,
+configuration, or reliance on pinned dependency behavior. Follow
+[the change-impact method](references/impact.md) for it. Review small scopes locally; use separate read-only
 subagents when the scope benefits from independent review and the host permits
 it. Missing spec material limits the Spec assessment, not all useful review.
 
+When a selected review uses an ACP stdio agent, read [the bundled client contract](references/acp-client.md) before launching it. Host orchestration and authorization still determine the route.
+
+When a panel uses stored preferences, read [the panel plan contract](references/panel-plan.md) to resolve the seats before launching any of them.
+
+When a panel has answered and you must combine its replies, read [the panel adjudication procedure](references/panel-adjudication.md); it includes a citation gate.
+
+When the user asks to set up or change a panel, for panel recommendations, or to use a panel for the first time without naming every seat, read [the panel setup procedure](references/panel-setup.md); it loads [the recommendations](references/panel-recommendations.md) when needed.
+
 ## Process
 
 ### 1. Pin the review scope
@@ -70,7 +82,7 @@ results and verification limits.
 When delegating and both sources are available, the reviews may run in parallel.
 If a source arrives later or scope changes, update only the affected assessment.
 
-**Hosts.** Both sub-agents are read-only. Use the current host's native agent mechanism and follow the repository's model-selection rules. A sub-agent never runs the model that wrote the code; when the author is its vendor's strongest model, use another vendor's model where one is available, through the host or that vendor's command-line agent run read-only with the same brief. When no other model is available, use a fresh context and say in the report that the reviewer shares the author's model.
+**Hosts.** A standing reviewer or a read-only sub-agent given one review uses [the independent review role](references/reviewer-role.md) and its PASS/BLOCK result. Both sub-agents are read-only. Use the current host's native agent mechanism and follow the repository's model-selection rules. A sub-agent never runs the model that wrote the code; when the author is its vendor's strongest model, use another vendor's model where one is available, through the host or that vendor's command-line agent run read-only with the same brief. When no other model is available, use a fresh context and say in the report that the reviewer shares the author's model.
 
 **Correctness of input-to-output code** goes in the Spec brief, using the
 evidence method above. Split a large scope into groups of about three files,
@@ -100,6 +112,10 @@ Present Standards and Spec separately. Verify delegated findings, remove
 unsupported or duplicate claims, and prioritize within each axis. Preserve the
 distinction between documented violations and heuristic suggestions.
 
+Report Impact after the two axes: what the change relies on, its real risks and
+what was ruled out, as the change-impact method describes. It never reranks
+Standards or Spec findings.
+
 Report a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes; the separation exists to prevent that reranking.
 
 Tag each surviving finding HIGH (corroborated by a second source or a directly cited requirement), MEDIUM (single inspected source), or LOW (inferred; name the check that would confirm it). Nothing is dropped on confidence alone: the operator adjudicates.

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

@@ -1,3 +1,3 @@
 interface:
   display_name: "HR: Code Review"
-  short_description: "Review a diff on standards and spec"
+  short_description: "Review a diff on standards, spec and impact"

package/skills/hr-code-review/references/acp-client.md

@@ -0,0 +1,43 @@
+# ACP review client
+
+Use the bundled `../scripts/acp-panel-client.mjs` when the selected review needs
+an ACP v1 agent over stdio. This helper does not choose a provider, model,
+effort or review scope. It does not select a route based on whether it uses the usage
+allowance. Launch it only within the user's authorization.
+
+```sh
+node <skill-directory>/scripts/acp-panel-client.mjs \
+  '["<agent-command>","<stdio-argument>"]' brief.md answer.txt <review-root> \
+  --model <advertised-model-id> --effort <advertised-effort-value> \
+  --verdict 'VERDICT:' --max-turns 2 --idle-min 5 --timeout-min 60
+```
+
+Node 22+ and Bun can run the same file. Arguments after the output path are
+optional. The default is one turn, no required verdict, five minutes of idle
+silence counted from launch and a sixty-minute hard deadline. The hard deadline has a one-minute
+minimum. The caller supplies its environment and temporary-storage policy.
+
+The client advertises confined file reads, disables writes and terminal
+execution, and rejects all permission requests. Physical file targets must stay
+inside the canonical review root. Put Git/GitHub evidence in the brief when the
+agent cannot obtain it through its own approved route. Missing or mismatched
+model/effort confirmations stop before the first prompt. Codex must advertise
+and confirm `read-only` mode; any other advertised mode is also set to read-only.
+
+These controls govern client-provided ACP capabilities. They do not sandbox an
+agent's own tools, prevent dishonest setting reports, or eliminate filesystem
+races during concurrent replacement. The caller must qualify the provider's
+own read-only route. Git status comparison detects some workspace changes; it
+does not detect ignored-file writes or prove that no writes occurred.
+
+The output contains collected agent text. Exit codes are:
+
+- 0: satisfied verdict condition
+- 1: setup/protocol failure
+- 2: missing arguments
+- 3: incomplete verdict
+- 4: changed Git status (the answer file is written after this comparison)
+- 124: deadline, even when the agent honors the cancel
+
+A permission-cancelled turn may continue within `--max-turns`. A matching marker
+is a completion signal, not proof that the review is accurate.

package/skills/{hr-change-impact/SKILL.md → hr-code-review/references/impact.md}

@@ -1,11 +1,7 @@
----
-name: hr-change-impact
-description: "Check what a change can break beyond the lines it edits, and back the claim that it is safe with something that ran. Use when the user asks what a change might break, wants its impact checked before merging, or distrusts a small diff."
-disable-model-invocation: true
----
-
 # 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.
@@ -105,9 +101,3 @@ 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.
-
-## Related skills
-
-- `hr-explain-code` when you need to understand the code before judging a change.
-- `hr-code-review` for standards, style and spec conformance of the same diff.
-- `hr-diagnosing-bugs` once something is actually broken.

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.