@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-better-typography/variable-fonts-and-opentype.md

@@ -0,0 +1,105 @@
+# Variable fonts and OpenType
+
+What a font file can do beyond drawing letters and how to reach those abilities from CSS.
+
+## Static vs variable
+
+- **Static font:** one weight and one style per file. Regular, medium and bold is three files.
+- **Variable font:** a whole range in one file. Any value in it works, such as `font-weight: 589`.
+
+A variable font is not automatically better. At one or two weights, static files can be smaller. At several weights, optical sizes, or custom axes, a variable font usually wins.
+
+## Load intended weights and styles
+
+Use a weight or style the active family does not provide and the browser may synthesize it, so load the faces the design uses. `none` disables weight, style, small-cap, superscript and subscript synthesis together and can erase distinctions when the real face is unavailable. Verify the whole fallback stack and every emphasis state before setting it.
+
+```css
+.brand-wordmark {
+  /* Safe only after this isolated treatment is verified */
+  font-synthesis: none;
+}
+```
+
+For body and interface text, keep synthesis enabled unless a verified font setup supplies every requested form. If only one mode is unwanted, use the specific longhand (`font-synthesis-weight`, `font-synthesis-style` and related properties) instead of the blanket shorthand.
+
+## Axes
+
+Variable-font controls, each with a four-letter tag. A font supports only the axes its designer included.
+
+| Axis         | Tag                       | Controls                                       |
+| ------------ | ------------------------- | ---------------------------------------------- |
+| Weight       | `wght`                    | Stroke thickness (like `font-weight`)          |
+| Optical size | `opsz`                    | Details and spacing tuned for the display size |
+| Width        | `wdth`                    | Glyph width                                    |
+| Slant        | `slnt`                    | Slant angle                                    |
+| Custom       | e.g. `GRAD` (Roboto Flex) | Whatever the designer built                    |
+
+Inter's variable file exposes only `wght` and `opsz`.
+
+Optical sizes predate variable fonts, and many families still ship them as separate files. Heldane Text is sturdier and more spaced for reading sizes, Heldane Display finer for large ones.
+
+## Properties over axis tags
+
+When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders, where `font-variation-settings` silently does nothing. Save raw tags for custom axes with no property of their own:
+
+```css
+/* Good: common axes use the properties */
+.heading {
+  font-weight: 650;
+  font-optical-sizing: auto;
+}
+
+/* Good: custom axis with no property of its own */
+.heading-grade {
+  font-variation-settings: "GRAD" 80;
+}
+
+/* Bad: weight via raw tag breaks on fallback fonts */
+.heading {
+  font-variation-settings: "wght" 650;
+}
+```
+
+## OpenType features
+
+OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, work the same on static and variable fonts. A font ships only the features its designer included.
+
+| Tag           | Feature                                         |
+| ------------- | ----------------------------------------------- |
+| `tnum`        | Tabular numbers: every digit the same width     |
+| `zero`        | Slashed zero: `0` distinct from `O`             |
+| `liga`        | Ligatures: joins pairs like "fi" into one shape |
+| `ss01`–`ss20` | Stylistic sets (numbered slots)                 |
+| `cv01`–`cv99` | Character variants (numbered slots)             |
+
+Same rule as axes. Prefer the `font-variant-*` properties and reserve `font-feature-settings` for tags with no property:
+
+```css
+/* Good: common features use the properties */
+.price {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Good: slashed zero via the property too */
+.id {
+  font-variant-numeric: slashed-zero;
+}
+
+/* Good: niche feature with no property of its own */
+.logo {
+  font-feature-settings: "ss01" 1;
+}
+```
+
+Tabular numbers matter for changing values. Without them each digit has a different width and the layout shifts as values update.
+
+## Small caps, superscripts, subscripts
+
+- **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
+- **Superscripts** sit above the normal line, the 2 in x², and **subscripts** below it, as in H₂O. Enable proper glyphs with `font-variant-position`.
+
+Both require the font to include the glyphs.
+
+## Stylistic sets and character variants
+
+`ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.

package/skills/hr-better-typography/wrapping-and-punctuation.md

@@ -0,0 +1,57 @@
+# Wrapping and punctuation
+
+Where lines start, where they end, where they break and which characters they use.
+
+## Measure (line length)
+
+Long lines make it harder for the eye to find the start of the next. For long-form text, aim for 60–75 characters per line.
+
+Any unit works. `65ch` measures characters directly, one `ch` being the width of the `0` in the current font, and a pixel or rem cap is just as good. At a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) and `max-w-2xl` (`672px`) both fit. What matters is that a cap exists and the line length sits in range. Recheck it if the body font size changes.
+
+## Alignment
+
+`text-align` controls where each line starts and ends. `justify` stretches spaces until both edges line up, which works in specific editorial layouts and nowhere else in an interface.
+
+## Wrapping
+
+| Property                    | Use                                                                |
+| --------------------------- | ------------------------------------------------------------------ |
+| `text-wrap: balance`        | Distributes text evenly across multiple lines                      |
+| `text-wrap: pretty`         | Avoids leaving a single short word on the final line               |
+| `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
+| `white-space: nowrap`       | Keeps labels and badges on one line where a break looks broken     |
+
+Use `balance` on headings and `pretty` on descriptions. Skip both in long-form text, because browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
+
+## Truncation
+
+- Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
+- Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
+- Middle: CSS has no middle ellipsis. Split the string in markup, an end-truncating head and a fixed tail such as the extension or last few characters, or shorten it in script with the full value in `title`. Use it where items differ at the end (`Q3-report…v12-final.pdf`).
+- None: numbers, amounts, dates and anything the user compares get the room they need.
+
+Truncation hides content. Where the missing text matters, make the full value available in a tooltip or an expanded view.
+
+## Case
+
+`text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so a redesign never means rewriting copy.
+
+## Smart punctuation
+
+Keyboard characters are not always the best characters:
+
+| Instead of               | Use                                                                    |
+| ------------------------ | ---------------------------------------------------------------------- |
+| Straight quotes `"..."`  | Curly quotes that curve around the text (keep straight quotes in code) |
+| Hyphen in ranges         | En dash: `2010–2020`                                                   |
+| Two hyphens for an aside | Em dash character                                                      |
+| Three periods `...`      | The single ellipsis character `…`                                      |
+| Regular space in `16 px` | ` ` so the value never breaks apart                               |
+| Uncontrolled word breaks | `­` to mark where a word may break                                 |
+
+## Internationalization
+
+Two refinements for mixed-direction text:
+
+- **Long paragraphs align by their own language.** A one- or two-line snippet follows the surrounding UI's direction. A paragraph of three or more lines aligns to its own script instead, so an English paragraph stays start-aligned LTR even inside an RTL interface. `text-align: start` with the correct `lang`/`dir` on the paragraph element handles this.
+- **Never reverse digits.** Numbers keep their order in every direction, so a phone number or "541" reads identically in RTL. Browsers handle this through the Unicode bidi algorithm. Never fight it with manual reordering, and wrap mixed number and text values in `<bdi>` where adjacent RTL text disturbs them.

package/skills/hr-better-writing/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+Copyright (c) 2026 Emil Kowalski
+
+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-better-writing/NOTICE.md

@@ -0,0 +1,46 @@
+# Source notices
+
+This notice accompanies the hr-better-writing bundle when copied on its own.
+
+## jakubkrehel/skills
+
+Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
+
+- `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
+  `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
+  including their supporting references and discovery metadata.
+
+Copyright (c) 2026 Jakub Krehel
+
+## emilkowalski/skills
+
+Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
+
+- `skills/hr-better-layout/`, `skills/hr-better-typography/` and `skills/hr-better-writing/`:
+  clipping, truncation and plural-form guidance adapted from `skills/break-ui/SKILL.md`.
+
+Copyright (c) 2026 Emil Kowalski
+
+## house-rules and MIT permission notice
+
+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-better-writing/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: hr-better-writing
+description: "Interface copy rules: button and link labels, error messages, empty states, placeholders, toggles and consistent terminology. Use when writing or reviewing text users see in a web UI; commit messages, PRs, docs and replies belong to hr-plain-prose."
+license: MIT
+metadata:
+  upstream: https://github.com/jakubkrehel/skills
+  upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
+  upstream_path: skills/better-writing/
+  local_patches: "Use-when description; name-validation example; plural check at 0, 1 and many (from emilkowalski/skills break-ui)"
+  house_rules_patches: "Portable provenance and review verdict"
+  break_ui_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/break-ui/SKILL.md
+---
+
+# Interface writing
+
+Clear and brief beats clever; consistent beats varied. The best error message is the interaction redesigned so the error cannot happen.
+
+How copy renders (capitalization via `text-transform`, truncation, smart punctuation) belongs to `hr-better-typography`. Error markup and announcements (`aria-invalid`, live regions) belong to `hr-better-accessibility`. Room for translated strings belongs to `hr-better-layout`.
+
+## Recon the existing voice
+
+Before writing or reviewing, read the copy nearby. Note the product's terminology, its localization conventions and any voice or content style guide.
+
+A deliberate brand voice is not a defect. Raise a departure from plain language only when it creates inconsistency, ambiguity, translation risk, or a tone the stakes don't support.
+
+## One voice, flexible tone
+
+The product has one voice and its existing copy establishes it. A local edit does not get to invent a new one. Keep terms consistent: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
+
+| Context                           | Tone                          |
+| --------------------------------- | ----------------------------- |
+| Success, onboarding, empty states | Warm, can be light            |
+| Routine actions, settings         | Neutral, minimal              |
+| Errors, destructive confirmations | Calm, plain, zero playfulness |
+| Data loss, security               | Serious, explicit             |
+
+## Address the reader directly
+
+In instructional copy, write "you", not "the user". In errors, "we" invites ambiguity and reads as deflection, so prefer "Unable to load content" over "We're having trouble loading this content". In success, onboarding and empty-state copy, an established first-person voice can stay if it reads clearly.
+
+Use possessives sparingly: "Favorites" beats "Your Favorites". Hold one perspective throughout a flow.
+
+## Plain words over clever ones
+
+Choose words a tired reader gets on the first pass, and delete every word that does no work. No idioms, no colloquialisms, no humor that won't translate.
+
+Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible.
+
+Never assemble a sentence from fragments around a variable (`"You have " + n + " new messages"`), because word order changes per language. Use a full templated string with proper pluralization: the i18n library's plural forms or `Intl.PluralRules`, checked at 0, 1 and many so "1 members" never ships.
+
+## Verb-first buttons
+
+A button label starts with a verb naming the action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or a bare "Yes" and "No" on a consequential action.
+
+A confirmation button repeats the consequence, so the dialog is answerable without reading the body. "Delete this project?" offers `Delete project` and `Cancel`.
+
+## Consistent flow vocabulary
+
+A multi-step flow uses one vocabulary throughout: "Get started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms makes users wonder whether the buttons do different things.
+
+## Links describe their destination
+
+Link text has to make sense out of context, because screen-reader users navigate by a list of the page's links. Write "Read the billing docs". "Click here" fails this and the device-verb rule at once.
+
+A bare "Learn more" breaks down as soon as two appear on one page. Suffix each one: "Learn more about exports".
+
+## One capitalization policy
+
+Pick title case or sentence case per element type, then apply it to every instance of that type. Sentence case is the safer default. It is calmer, has no per-word rules to remember and localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
+
+## Settings describe the ON state
+
+Label a toggle for what happens when it is on. "Send read receipts" lets users infer the off state; the negative ("Don't send read receipts") turns the toggle into a double negative.
+
+Link straight to a referenced setting rather than describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
+
+## Errors say how to fix, next to where it broke
+
+An error is an instruction, and it belongs beside the field that failed:
+
+| Bad                         | Good                                                 |
+| --------------------------- | ---------------------------------------------------- |
+| That password is too short  | Choose a password with at least 8 characters         |
+| Invalid date                | Enter a date as DD/MM/YYYY                           |
+| Oops! Something went wrong. | Unable to save. Check your connection and try again. |
+
+No blame, no "oops", no exclamation marks. Phrase hints positively ("Use digits only", not "Don't use letters or symbols") and show them before the mistake, not after. When the same error keeps firing, redesign the interaction instead of rewording it.
+
+## Empty states point forward
+
+An empty state says what this place is, how to fill it and offers one clear next action:
+
+```html
+<!-- Bad: a shrug -->
+<p>No results.</p>
+
+<!-- Good: orientation plus a next step -->
+<p class="font-medium">No projects yet</p>
+<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
+<button class="mt-4">Create a project</button>
+```
+
+A search or filter empty state names the query and offers an exit: "No results for 'quarterly'. Clear filters". Never park persistent information in an empty state. It disappears the moment content exists.
+
+## Placeholders are examples, not labels
+
+A placeholder shows the expected format: `name@example.com`, `DD/MM/YYYY`. It vanishes on input, so it is never the only label. Every field keeps a visible one.
+
+## Reporting
+
+**Severity.** `HIGH` misleads the user or hides how to recover from an error. `MEDIUM` breaks voice, terminology, or capitalization consistency. `LOW` is isolated wording polish.
+
+**Verification.** Source alone is enough here. Check every label against the action it invokes, every error for a stated fix and terminology against the copy around it. No browser check is required.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| -------- | -------- | ------ | ----- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+Report `Block` when any `HIGH` remains. With partial coverage and no `HIGH`, report the coverage gap without a verdict. With complete coverage and no `HIGH`, report `Approve`, leaving lower-severity findings in the table as work to do. With nothing to report, state "No actionable writing findings" and report verification.

package/skills/hr-better-writing/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Better Writing"
+  short_description: "UX writing, interface copy and microcopy"

package/skills/hr-code-review/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-code-review/NOTICE.md

@@ -0,0 +1,26 @@
+# Source notices
+
+Source: https://github.com/no-human-ai/no_human (compared at revision `9b50bf6`)
+
+The evidence method's test-weakening assessment and refutation of completion
+claims are informed by this source. The method is independently written.
+
+Copyright (c) 2026 Eyal Golan
+
+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-code-review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: hr-code-review
+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.
+
+- **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. 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
+
+Use the scope stated by the user or established in the task:
+
+- **Working-tree changes:** use `git diff HEAD` for tracked changes and `git ls-files --others --exclude-standard` to identify untracked files to inspect.
+- **Committed branch comparison:** resolve the base and use `git diff <base>...HEAD`.
+- **Since an exact commit or tag:** use `git diff <revision> HEAD`; include working-tree changes only when requested, using `git diff <revision>` and inspecting in-scope untracked files.
+- **Merge-base comparison including local changes:** resolve `git merge-base <base> HEAD`, compare the working tree with that revision, and inspect in-scope untracked files.
+
+Record the resolved base, comparison command, and whether staged, unstaged, and untracked files are included. Validate supplied refs before dispatching reviewers. Ask only when scope remains ambiguous. Report an empty scope only after checking every included category. Record the commit list when reviewing committed changes.
+
+### 2. Identify the spec source
+
+Look for the originating spec in this order:
+
+1. A path the user passed as an argument.
+2. The linked issue or pull request, or an approved plan or specification in the repository.
+3. The user's request as recorded in the session.
+4. If nothing is found, report "Spec conformance not assessed: no source found" and complete the review supported by available evidence. Ask for a source only when its absence prevents the judgment the user requested; continue independent review while awaiting it. Do not infer requirements from the implementation itself.
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+When the diff adds or changes what an API returns (a handler, serializer, DTO,
+response schema or webhook payload), load `hr-api-exposure-check` and give its
+Two answers per field test to the Standards reviewer, or apply it in a local
+review. If that skill is missing or excluded, report the limit on response-field
+assessment and use the available project standards. Do not claim the skill was
+applied or install it without authorization.
+
+Use the design heuristics below when relevant to the changed code. They are prompts to investigate maintenance problems, not a checklist that must produce findings or automatic refactoring prescriptions.
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation. Like any standard here, skip anything tooling already enforces.
+
+Recommend a transformation only when inspected evidence shows a concrete current
+maintenance problem and the remedy reduces it without weakening required behavior.
+State the consequence and any equivalence assumptions; otherwise omit the finding.
+
+- **Naming:** does ambiguity cause a concrete misunderstanding at a call site?
+- **Duplication and repeated branches:** must these sites evolve together, or do they express independent policies? Extraction or polymorphism must earn its coupling and indirection.
+- **Grouped data and domain primitives:** are invalid combinations or repeated invariant checks causing problems that a type would actually prevent?
+- **Module boundaries and data access:** does current coupling force scattered edits, expose internals or mix unrelated responsibilities? Moving code must improve the boundary rather than merely rearrange it.
+- **Delegation and inheritance:** does a wrapper or interface provide a useful contract, isolation or adaptation? One caller or implementation is not itself a defect.
+- **Speculative flexibility:** does configuration or abstraction serve a current requirement? Remove unsupported complexity only after checking its consumers and behavior.
+
+### 4. Review each axis
+
+Use the same pinned scope for both axes, whether reviewing locally or delegating.
+Read [the evidence-assessment method](references/evidence.md) and include it in
+each delegated brief. It covers completion claims, weakened tests, emitted
+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.** 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,
+one reviewer per group. Do not assign this work to a reviewer focused on
+structure or maintainability.
+
+**Standards sub-agent prompt** should include:
+
+- The full diff command and commit list.
+- The applicable standards sources and relevant design heuristics, including their evidence requirement.
+- The brief: "Report documented-standard violations with citations, and design findings only when inspected code shows a concrete current maintenance problem. For each finding give the location, consequence and proportionate remedy that preserves required behavior. Distinguish hard violations from heuristic judgments; repository standards override heuristics. Do not prescribe abstraction from a pattern alone. Skip tooling-enforced issues. Keep findings concise, with enough evidence to assess them."
+
+**Spec sub-agent prompt** should include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report missing or partial requirements, behavior outside the requested scope, and incorrectly implemented requirements. Cite the requirement and code location for each finding. Keep findings concise, with enough evidence to assess their consequence. Where the spec is silent, what a reasonable user of this software would expect is still a requirement; grade it by its effect on that user. Before your verdict, list under `Declined to judge` every behavior you considered and set aside as out of scope, one line each with the reason, or write `none`."
+
+Ground findings in inspected code and cite their locations and applicable
+standards or requirements. Report concrete consequences; smells alone do not
+justify a new abstraction. Mark missing evidence and unassessed requirements
+explicitly rather than claiming a pass.
+
+### 5. Aggregate
+
+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.
+
+Tag each finding with one actionability label, independent of the confidence tag:
+
+- `blocking` must be fixed before merge.
+- `important` should be fixed and may block, depending on context.
+- `nit` is a minor style or preference issue.
+- `suggestion` is an optional improvement worth considering.
+- `learning` is an educational note that needs no action.
+- `praise` marks good work; report it so review is not only defects.
+
+Within each axis, order findings by actionability (`blocking` first, in the list order above), then by confidence (HIGH first).
+
+Grade actionability by the finding's effect on users, not by whether the spec
+mentions the trigger or by the implementer's stated rationale. Rule on each
+line of the Spec reviewer's `Declined to judge` list: promote it to a finding
+or confirm it out of scope, and show both in the report.
+
+### 6. Remediation options
+
+When a finding has more than one viable remedy, or the remedy you would
+recommend differs from the ideal fix, present them as an offer in the house rules' § Offers format
+for the user to choose from. Give each option a rough relative effort and its
+tradeoffs, mark the recommendation, and separately name the right fix, meaning
+the remedy that best serves the codebase absent current constraints. When the
+recommendation is not the right fix, say why: scope, risk, blast radius or
+existing debt. Skip this step for findings with a single obvious remedy; do not
+produce an options list per nit.
+
+When the user rejects, narrows or edits a finding or remedy, record the reason
+in the task's plan or notes. Record why it was wrong or
+unwanted, not merely that it was declined. For each accepted finding, record
+the verifying command or one-line reason with it, so a later session can
+re-check the fix without re-deriving the finding.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing is a **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions is a **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

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

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Code Review"
+  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.