@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-tdd/mocking.md

@@ -0,0 +1,39 @@
+# When to mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes; prefer a test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Reuse production interfaces**
+
+Prefer existing operation-specific APIs when they serve production callers. Otherwise mock the transport boundary; request routing in a fake is acceptable. Do not add wrappers solely to simplify mocks. Assert observable results rather than calls to repo-owned helpers.

package/skills/hr-tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and bad tests
+
+## Good tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- Assertions establish one observable behavior; use several when the contract needs them
+
+## Bad tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = { process: jest.fn() };
+  await checkout(cart, mockPayment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting internal collaborator calls/counts/order instead of observable behavior. External-boundary count or order contracts are valid assertions.
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Bypassing the tested public interface to inspect private implementation state. Observable storage, wire, and DOM outcomes remain valid; prefer fake state over call logs when state expresses the contract.
+
+```typescript
+// BAD: Checks private storage when storage is not the public contract
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

package/skills/hr-test-audit/LICENSE

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

package/skills/hr-test-audit/NOTICE.md

@@ -0,0 +1,67 @@
+# Source notices
+
+This notice accompanies the hr-test-audit bundle when copied on its own.
+Each source below is published under the MIT License. The licence text at the
+end applies to each of them, with the copyright line shown for that source.
+
+## obra/superpowers
+
+Source: https://github.com/obra/superpowers (compared at revision `8ca22db`)
+
+- `SKILL.md`: cites `writing-good-tests.md`.
+
+Copyright (c) 2025 Jesse Vincent
+
+## addyosmani/agent-skills
+
+Source: https://github.com/addyosmani/agent-skills (compared at revision `9d0c60d`)
+
+- `scripts/floor-guard.ts`: adapted from constraint-driven-development.
+
+Copyright (c) 2025 Addy Osmani
+
+## openclaw/openclaw
+
+Source: https://github.com/openclaw/openclaw (linked at revision `65f1e4d`, compared at `1fda703`)
+
+- `SKILL.md`: the authoring gate, junk patterns, retention bar and evidence
+  fields are adapted from `.agents/skills/test-audit/`.
+
+Copyright (c) 2026 OpenClaw Foundation
+
+## no-human-ai/no_human
+
+Source: https://github.com/no-human-ai/no_human (compared at revision `9b50bf6`)
+
+- `SKILL.md`: the rule that weakening a test counts as removing it is adapted
+  from its tamper guard.
+
+Copyright (c) 2026 Eyal Golan
+
+## omkamal/pypict-claude-skill
+
+Source: https://github.com/omkamal/pypict-claude-skill (compared at revision `fbda212`)
+
+- `SKILL.md`: the pairwise-coverage guidance is adapted from this skill.
+
+Copyright (c) 2025 pypict-claude-skill contributors
+
+## MIT License text
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,146 @@
+---
+name: hr-test-audit
+description: Gate new or changed tests on the value they add, and sweep an existing suite for low-value, implementation-coupled or duplicate tests to delete. Use when adding or reviewing tests, or when asked to prune, audit or clean up a test suite.
+---
+
+# Test audit
+
+Two modes share one value bar: a test earns its upkeep by protecting observable
+behavior, a credible regression, or an independent contract. **Authoring mode**
+gates each new or changed test before it lands. **Audit mode** finds existing
+tests that fail the bar and removes them in small, evidenced batches. For the
+red-green loop itself, use a TDD skill where one is installed; this skill decides which tests are worth
+keeping.
+
+## Authoring gate
+
+Before adding a test, answer all four. A missing answer means don't add it yet.
+
+1. What observable behavior, invariant or contract does it protect?
+2. What credible regression makes it fail? Name the production change that
+   turns it red: a wrong constant or argument, a wrong branch, a missing side
+   effect, an empty or default return, or a missing check for empty, nil,
+   unauthorized or malformed input. If none would, it is a change detector or
+   cannot fail.
+3. Why doesn't existing coverage already catch that? Each contract has one
+   owning test at its strongest boundary. Another layer needs its own risk the
+   owner cannot reach. Prefer a new case in an existing table or fixture over a
+   near-duplicate test.
+4. Does it need a production seam (export, flag, wrapper, injection hook) that
+   no production caller uses? Then test at the real boundary instead.
+
+When a unit must be tested in isolation, write down the ways it can fail before
+writing the code, and test those failures. A test written after the code tends
+to restate the code.
+
+A bug regression test must fail on the pre-fix code for the intended reason,
+then pass after the fix. One that never demonstrably failed proves the mock, not
+the fix. One regression at the owning boundary covers the bug; don't replay it
+at every layer it crosses. For a sequence `hr-ordering-tests` found, that
+regression is the named test beside its enumeration.
+
+Changing an existing test so it checks less counts as removing it: deleting or
+skipping it, loosening an assertion, or rewriting an expected value to match new
+output. It needs the audit-mode evidence from step 2, not only these answers.
+To catch these moves in a diff, run
+`bun <this skill's directory>/scripts/floor-guard.ts [--base <ref>]` from
+the repository. It reports new suppression comments, added skips or
+`.only`, deleted test files and assertions removed from surviving tests, and
+exits 0 clean, 1 with findings, 2 when it could not run. Each finding still
+needs a reason; a 2 is never a pass.
+
+For retry and concurrency failures, exercise the implementation at the boundary
+where order matters. Cover the credible lost-response, interrupted-write or
+restart sequence with controlled barriers and assert durable state or externally
+visible behavior. Do not replace that coverage with a separate model of the code.
+Code that merges events from more than one actor also needs an enumeration test
+from `hr-ordering-tests`, and a change that adds a kind of event adds it to that
+test's event list.
+
+When behavior depends on three or more independent settings, cover every pair
+of their values rather than every combination: list each setting's value
+classes and edge values, drop combinations the code rejects, and build the
+smallest table where each pair appears at least once (Microsoft PICT generates
+one). Most interaction bugs need only two settings to line up. Add an explicit
+case for each combination of three or more settings already known to interact,
+such as one behind a past bug or a documented constraint.
+
+Then check the test against the junk patterns below. A match fails the gate
+unless the retention bar names the contract it independently guards.
+
+## Junk patterns
+
+Authoring rejects new tests that match; audits hunt for existing ones that do.
+
+- no assertion, or an assertion that cannot fail
+- expected values produced by the code under test, or copied from it
+  (fixtures, inventories, export lists, snapshots taken from current output)
+- exact source, import or string greps standing in for behavior
+- private helpers or call shapes tested again where a real boundary already
+  covers them
+- the same contract asserted several times, or one shared helper re-tested in
+  every caller
+- tests that exist only to keep test-only exports, globals or wrappers alive,
+  and production code whose only callers are tests
+- mocks that implement the asserted behavior, or one mock standing in for
+  different APIs
+- negative tests that pass for an unrelated reason (a different guard rejects
+  the input, or the production path never reaches the check)
+- names or fixtures that promise more than the test exercises
+- tests that break under a behavior-preserving refactor
+
+## Retention bar
+
+Keep a test that independently enforces a public API, protocol, config,
+migration, storage, security, platform, default or release contract. Also keep
+call-order tests when order is observable, regressions with a credible failure
+mode, and a source check when it is the cheapest guard that fails on a
+user-facing change and survives a rename. Slow or static is not a reason to
+delete. A kept test that fails on the unchanged baseline may be a real bug:
+reproduce and fix it rather than deleting the test.
+
+## Audit mode
+
+1. **Discover, read-only.** Read the repository's testing guidance first. For a
+   large suite, split discovery by area and run the slices in parallel if the
+   host allows. Prefer a few high-confidence candidates over a long speculative
+   list. Before judging one, read the whole test, the production code it covers,
+   that code's callers, and any overlapping tests.
+2. **Record evidence per candidate** before editing: test name and location;
+   the failure it can actually detect; non-test callers of what it covers; the
+   stronger test that remains, or why none is needed; why it exists (history);
+   what production or test-support code its removal frees; the focused
+   validation command. A missing field means the candidate is not ready.
+3. **Edit one coherent batch.** Remove the tests along with the test-only
+   exports, wrappers and dead paths they kept alive; don't leave aliases. Move a
+   retained regression to its owning boundary. Don't add replacement tests that
+   restate the implementation, and don't count uncertain deletions as progress.
+4. **Validate.** Run the owning and sibling tests, then the repository's
+   required checks. Where a removed test grepped source or a plan, run the
+   script or dry run that owns the real contract instead.
+5. **Report**: categories removed, kept false positives and why, checks run,
+   and production versus test lines changed (`git diff --numstat`). Land one
+   batch at a time through the repository's normal flow, then rerun discovery on
+   the updated base for the next batch.
+
+## Sources
+
+Original synthesis, adapting:
+
+- OpenClaw's
+  [`test-audit`](https://github.com/openclaw/openclaw/blob/65f1e4d2279eecd6e40d55d82027d5c97b4b272b/.agents/skills/test-audit/SKILL.md):
+  the authoring gate, junk patterns, retention bar and evidence fields.
+- [Ansh Nanda via Ray Fernando](https://x.com/RayFernando1337/status/2102927565778522610):
+  the failure-list-first rule. Their "E2E tests only" rule is not adopted.
+- no_human's [tamper guard](https://github.com/no-human-ai/no_human): weakening
+  a test counts as removing it.
+- addyosmani/agent-skills'
+  [floor guard](https://github.com/addyosmani/agent-skills/blob/main/skills/constraint-driven-development/references/floor-guard.md)
+  (MIT): the diff checker.
+- obra/superpowers `writing-good-tests.md`: the mutation check behind
+  authoring-gate question 2.
+- omkamal's [pypict skill](https://github.com/omkamal/pypict-claude-skill):
+  pairwise coverage.
+
+For recorded proof that a UI change works, see michaelshimeles'
+[`evidence-driven-testing`](https://github.com/michaelshimeles/skills/tree/main/evidence-driven-testing).

package/skills/hr-test-audit/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Test audit"
+  short_description: "Gate new tests and prune low-value ones"

package/skills/hr-test-audit/scripts/floor-guard.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+// Flag changes that make tests or checkers easier to pass: new suppression
+// comments, added skips or `.only`, deleted test files, and assertions removed
+// from test files that still exist. Diff-scoped: merge base to working tree,
+// untracked files included. Tightening is silent; only loosening is reported.
+//   bun floor-guard.ts [--base <ref>]   (default: origin/HEAD, then origin/main)
+// Exit 0 clean, 1 findings, 2 the guard could not run. Never read 2 as clean.
+// Adapted from addyosmani/agent-skills constraint-driven-development
+// references/floor-guard.md (MIT).
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+
+export type Finding = { rule: string; file: string; text: string };
+
+const SUPPRESSIONS =
+  /@ts-ignore|@ts-nocheck|@ts-expect-error|eslint-disable|oxlint-disable|biome-ignore|#\s*noqa|#\s*type:\s*ignore|istanbul ignore|c8 ignore|nosemgrep|gitleaks:allow|Stryker disable/;
+const SKIPS =
+  /\.(skip|todo|only)\s*\(|\b(xit|xdescribe|xtest)\s*\(|@pytest\.mark\.(skip|xfail)|\bt\.Skip\(/;
+const ASSERTION = /\b(expect|assert\w*|should)\b/;
+
+export function isTestFile(path: string): boolean {
+  return /\.(test|spec)\.[^/]+$|_test\.[^/]+$|(^|\/)test_[^/]+$|(^|\/)(tests?|__tests__)\//.test(
+    path,
+  );
+}
+
+// Reads a unified diff (`--unified=0` is enough) and returns the loosening moves.
+export function scanDiff(diff: string): Finding[] {
+  const added: { file: string; text: string }[] = [];
+  const removed: { file: string; text: string }[] = [];
+  const deleted = new Set<string>();
+  const strip = (p: string) => p.replace(/^[ab]\//, "");
+  let file = "";
+  let oldFile = "";
+  // File headers appear only between `diff --git` and the first `@@`; inside a hunk,
+  // an added line such as `++ x` is content, not a header.
+  let inHunk = false;
+  for (const line of diff.split("\n")) {
+    if (line.startsWith("diff ")) {
+      inHunk = false;
+    } else if (line.startsWith("@@")) {
+      inHunk = true;
+    } else if (!inHunk && line.startsWith("--- ")) {
+      oldFile = strip(line.slice(4));
+    } else if (!inHunk && line.startsWith("+++ ")) {
+      const newFile = strip(line.slice(4));
+      file = newFile === "/dev/null" ? oldFile : newFile;
+      if (newFile === "/dev/null") {
+        deleted.add(oldFile);
+      }
+    } else if (line.startsWith("+")) {
+      added.push({ file, text: line.slice(1) });
+    } else if (line.startsWith("-")) {
+      removed.push({ file, text: line.slice(1) });
+    }
+  }
+
+  const findings: Finding[] = [];
+  const flag = (rule: string, f: string, text: string) =>
+    findings.push({ rule, file: f, text: text.trim().slice(0, 120) });
+  for (const { file: f, text } of added) {
+    if (SUPPRESSIONS.test(text)) {
+      flag("silenced-checker", f, text);
+    }
+    if (isTestFile(f) && SKIPS.test(text)) {
+      flag("test-skipped", f, text);
+    }
+  }
+  for (const f of deleted) {
+    if (isTestFile(f)) {
+      flag("test-deleted", f, "file deleted");
+    }
+  }
+  // An assertion line that reappears in the same file was moved, not removed.
+  const kept = new Set(added.map((a) => `${a.file}\0${a.text.trim()}`));
+  for (const { file: f, text } of removed) {
+    if (!isTestFile(f) || deleted.has(f) || !ASSERTION.test(text)) {
+      continue;
+    }
+    if (!kept.has(`${f}\0${text.trim()}`)) {
+      flag("assertion-removed", f, text);
+    }
+  }
+  return findings;
+}
+
+function git(args: string[], okStatuses = [0]): string | null {
+  const r = spawnSync("git", args, { encoding: "utf8" });
+  return r.status !== null && okStatuses.includes(r.status) ? r.stdout : null;
+}
+
+function main(): number {
+  const bail = (msg: string) => (console.error(`floor-guard: ${msg}`), 2);
+  let base: string | undefined;
+  try {
+    base = parseArgs({ options: { base: { type: "string" } } }).values.base;
+  } catch (error) {
+    return bail(error instanceof Error ? error.message : String(error));
+  }
+  const bases = base ? [base] : ["origin/HEAD", "origin/main"];
+  let mergeBase: string | undefined;
+  for (const b of bases) {
+    mergeBase = git(["merge-base", b, "HEAD"])?.trim();
+    if (mergeBase) {
+      break;
+    }
+  }
+  if (!mergeBase) {
+    return bail(`no merge base against ${bases.join(" or ")}`);
+  }
+  const tracked = git(["diff", "--unified=0", mergeBase, "--"]);
+  const untracked = git(["ls-files", "--others", "--exclude-standard"]);
+  if (tracked === null || untracked === null) {
+    return bail("could not read the diff");
+  }
+  let diff = tracked;
+  for (const f of untracked.split("\n").filter(Boolean)) {
+    // --no-index exits 1 when the sides differ, which is the normal case here.
+    const d = git(["diff", "--no-index", "--unified=0", "/dev/null", f], [0, 1]);
+    if (d === null) {
+      return bail(`could not diff untracked file ${f}`);
+    }
+    diff += `\n${d}`;
+  }
+  const findings = scanDiff(diff);
+  for (const f of findings) {
+    console.log(`${f.rule}\t${f.file}\t${f.text}`);
+  }
+  if (findings.length === 0) {
+    console.log("floor-guard: clean");
+  }
+  return findings.length ? 1 : 0;
+}
+
+if (import.meta.main) {
+  process.exit(main());
+}

package/skills/hr-usage-report/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: hr-usage-report
+description: Measure where Claude Code, Codex and OpenCode usage went by provider, model and role, and chart model comparisons as HTML. Use for quota or cost questions and to show a model or role recommendation visually.
+---
+
+# Usage report
+
+Answer quota and model-role questions from measured usage and published
+evidence, then show the result as charts and tables. Run the scripts from this
+skill's directory with Bun.
+
+## 1. Measure where usage went
+
+```bash
+bun scripts/usage-by-model.ts --days 7 [--providers claude,codex,opencode] [--claude-projects <dir,dir>] [--prices <api.json>] [--json]
+```
+
+It reads Claude Code transcripts (`projects` under `~/.claude` and under every
+other `~/.claude_*` or `~/.claude-*` configuration directory, so sessions run
+with a separate `CLAUDE_CONFIG_DIR` count; `--claude-projects` replaces that
+list), Codex rollouts
+(`~/.codex/sessions`) and the OpenCode database, all read-only and local. It
+prices each request at [models.dev](https://models.dev) list rates, including
+long-context tiers, and splits usage by provider, model and role: main session,
+subagent, advisor. Without `--prices` it downloads `https://models.dev/api.json`;
+that request carries no local data. Use `--since <ISO>` for a fixed start.
+
+Read the output beside the provider's live quota readings:
+
+- **Shares, not dollars.** List price stands in for subscription quota; no
+  provider publishes the conversion. Say so in the report.
+- **Cache reads.** When cache reads dominate a row's cost, context length, not
+  the model's output, drives usage. Compare the main-request context median
+  with the session-start median: the gap is conversation growth; the start is
+  fixed overhead (system prompt, rules, tool schemas).
+- **Advisor rows.** Each advisor call re-reads the whole transcript uncached at
+  the advisor's rates; a few calls can outweigh many main turns.
+- **Cross-provider work.** The same table shows what the author's sessions and
+  another vendor's reviewer each cost.
+- **Unpriced models.** The summary lists models models.dev has no price for;
+  report them rather than dropping them.
+
+## 2. Pick evidence by question
+
+| Question                              | Evidence                                                             | Read                                                                |
+| ------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Quality per dollar for implementation | Agentic coding boards that publish effort, harness and cost per task | Score against cost at every effort; cost per solved task            |
+| Review and bug finding                | Bug-finding boards with run counts per row                           | The effort curve; treat single runs as noisy                        |
+| Raw speed                             | Output tokens per second                                             | Generation speed only                                               |
+| Task speed                            | Boards that time whole tasks                                         | Time to finish; a model that generates faster can still take longer |
+| Fit for your own work                 | A known-answer trial on your own tasks (`hr-benchmarking`)           | Correctness and model time per task shape                           |
+
+Compare models at the same effort and harness, or say they differ. A vendor
+table that sets one model's top effort against another's lower effort is not a
+matched comparison. Keep token speed and task time in separate charts; never
+infer one from the other.
+
+## 3. Render the report
+
+Write a data file, then:
+
+```bash
+bun scripts/render-report.ts <data.json> <out.html>
+```
+
+The page is self-contained, follows the host's theme variables when it is
+embedded, and falls back to a dark surface. `assets/example-report.json` uses
+every section type.
+
+The data file declares `series` once, so each model keeps one color across
+every chart in the report: up to three colored series with slots 0 to 2, and at
+most one `"reference": true` series drawn dashed and neutral. The renderer
+rejects a fourth colored series because no fourth hue passes the color-vision
+check on the dark surface against the other three. Compare more models in a
+second report file.
+
+Section types:
+
+- `curve`: points with `x`, `y`, `label`, `tip` per series; `xLog`, domains,
+  ticks and axis affixes. Use for score against cost across efforts.
+- `ladder`: `categories` (usually efforts) and `values` per series, `null` for a
+  missing row, optional `notes` such as run counts.
+- `bars`: `rows` of `label`, `key`, `value`, optional `display` and `tip`.
+- `pair`: two sections side by side, such as token speed beside task time.
+- `table`: `columns` and `rows`; a cell may be `{ "text", "verdict": "yes" | "maybe" | "no" }`;
+  `numeric` lists right-aligned column indexes.
+
+End with one verdict table per model or role: role, key evidence with numbers,
+verdict. Name the evidence date in the title, and apply any model or effort
+limits the user has set before recommending a configuration.

package/skills/hr-usage-report/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Usage report"