@bompus/house-rules 0.11.0 → 0.13.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement through the repository's private reporting form: on the [Security tab](https://github.com/bompus/house-rules/security), choose **Report a vulnerability** and say the report is about conduct. Only the maintainer can read it. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/README.md

@@ -16,7 +16,7 @@ Fresh installs select eight skills for setup, review, diagnosis, explanation,
 planning, tests, writing and remaining work. Modifiers start off. Add guidance
 when a task needs it, and let each repository supply its own safeguards.
 
-<p align="center"><img src="docs/assets/overview.png" alt="The four layers composed into one rules file: core, opt-in modifiers, your layer and each repository's AGENTS.md. The eval figures in this illustration come from an early internal run and are not a current result." width="100%"></p>
+<p align="center"><img src="docs/assets/overview.png" alt="The four layers: core, opt-in modifiers and your own layer are composed into one rules file, and each repository's AGENTS.md adds to it. Beside them, what a fresh install selects: core rules on, modifiers off, eight skills." width="100%"></p>
 
 If you are an AI agent reading this for your user, the prompt under
 [Evaluate it with your agent](#evaluate-it-with-your-agent) is the evaluation
@@ -28,10 +28,10 @@ don't install or copy anything on your own.
 1. **Core** (`rules/core.md`): the base every setup gets. Its first section is
    the end-of-reply check, so an agent that reads only the top of the file
    still knows when to keep working and when to stop and ask.
-2. **Modifiers** (`rules/modifiers/`): opt-in preferences, such as coded
+2. **Optional rules**, called modifiers in the files (`rules/modifiers/`): opt-in preferences, such as coded
    option lists or squash-only landing. Each one replaces a core section or
    adds a section after one.
-3. **Your layer** (by default `~/.config/house-rules/`): `house-rules.json`
+3. **Your own rules**, called your layer in the files (by default `~/.config/house-rules/`): `house-rules.json`
    names the modifiers you enable, `rules/` holds your own sections, and
    `skills/` holds your own skills. A skill there replaces the house-rules
    skill of the same name. The config's other keys are optional: `layers`
@@ -95,8 +95,9 @@ Updates preserve your existing config. An explicit `skills.include` list keeps
 later shipped additions off until selected. Browse the full catalog only when
 you want more choices.
 
-On a later run it keeps the previous skills directory under a dated name
-instead of deleting it. It never edits an agent host's files. The comment at
+On a later run, if the composed skills changed, it keeps the previous skills
+directory under a dated name instead of deleting it; if they match, it says so
+and keeps nothing extra. It never edits an agent host's files. The comment at
 the top of `install.sh` lists the environment variables that change its paths
 or runtime; `install.ps1` takes the same variables. Some skill scripts need Bun
 even when Node.js composes the rules.
@@ -105,14 +106,16 @@ Then connect the composed file to your agent. Claude Code reads
 `@~/.config/house-rules/rules.md` on its own line in `~/.claude/CLAUDE.md`;
 other hosts take a copy in their user-level rules file, with the
 `house-rules-references/` directory placed beside it. Written rules link to the
-procedures in that directory; stdout and configuration previews keep them
-inline. See [reference output](docs/configuration.md#reference-output). To change modifiers or
+procedures in that directory, which hold detail; an agent may act without opening
+one, so each guard stays written in the rules themselves. Stdout and configuration
+previews keep the procedures inline. See [reference output](docs/configuration.md#reference-output). To change modifiers or
 skills, change to the checkout directory and run `node compose.mjs setup`,
 or `bun compose.mjs setup` when Node.js is unavailable. Review the numbered
-choices and use `save` to change only the configuration. Then run the
-installer again.
+choices and use `save` to change only the configuration. Setup then prints the
+command that applies the selection: the installer for a checkout, or
+`house-rules --config` for the npm package.
 The [configuration CLI guide](docs/configuration.md) covers status, previews,
-question preferences and safe writes. The
+question preferences, optional panel preferences and safe writes. The
 `hr-house-rules-setup` skill preserves selections, offers relevant additions and connects
 hosts, and asks before it touches a host file.
 
@@ -161,13 +164,6 @@ and reconcile existing notice files before replacing them. A full
 skill, keep its entire directory, including any `NOTICE.md` and `LICENSE`.
 Personal layers must also carry notices required by their own sources.
 
-The `hr-navigation-retro` skill finds navigation failures in selected tool-call
-transcripts, then proposes fixes verified against current source. Any agent with
-file and shell access can run it. Supported inputs include Claude Code, Codex,
-OpenCode exports, Cursor CLI streams and ACP v1 recordings from other agents.
-See its [input limits](skills/hr-navigation-retro/references/inputs.md).
-It is explicit-only, requires Python 3.11+ and keeps reports local.
-
 ## Upgrading skill names
 
 All shipped skill names use `hr-`. Before updating an older installation,
@@ -191,9 +187,6 @@ repository's AGENTS.md or equivalent). Tell me:
 2. Which ones duplicate or conflict with what I already have.
 3. Whether to adopt it whole (compose.mjs plus my own layer) or copy single
    sections into my existing rules. Taking individual ideas is fine.
-If I run several agent sessions on one machine at once, also look at
-Swarmail (https://github.com/bompus/swarmail); house-rules has an opt-in
-modifier for it.
 Read only: don't install, compose or edit anything until I choose. When I
 adopt a section or idea, record its source in distributed notices, such as
 "Adapted from house-rules (https://github.com/bompus/house-rules)". Keep required
@@ -221,41 +214,58 @@ Use pnpm for JavaScript projects unless the repository uses another manager.
 
 The operations are `replaces:`, `after:`, `before:` and `removes:`; a
 `removes:` file has no body. A file without frontmatter is added at the end.
-Frontmatter may also hold `description:` and `requires:` (a comma-separated
-list of skills the section relies on); any other key is an error. Files apply
+Frontmatter may also hold `description:`, `requires:` (a comma-separated
+list of skills the section relies on; the core rules and any modifier that relies
+on skills declare them, and composing warns when one is not in the composed
+set) and `reference:` (a procedure file the section links to; see
+[reference output](docs/configuration.md#reference-output)); any other key is an error. Files apply
 in name order, after the modifiers.
 
 ## Modifiers
 
-| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Modifier&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | What it does                                                                                                                                                                                                                   |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `coded-offers`                                                                                                                                           | Offers use numbered questions and coded options (`1A`, `1B`) so one short reply answers every decision.                                                                                                                        |
-| `effort-estimates`                                                                                                                                       | Options that differ in cost, or work that waits on CI, a build or a deploy, carry a wall-clock estimate based on comparable finished work. Estimates from workers, docs or other models are converted the same way or dropped. |
-| `land-when-done`                                                                                                                                         | Authorized repository work is not finished until it is in the remote default branch.                                                                                                                                           |
-| `low-quota-handoff`                                                                                                                                      | When the current model's usage allowance runs low, write a handoff before work stops.                                                                                                                                          |
-| `multi-agent`                                                                                                                                            | Work is split across delegated workers and several agent hosts; worker reports, review standards and cleanup checks account for all of them.                                                                                   |
-| `no-attribution`                                                                                                                                         | Commits, pull requests and comments carry no agent or tool credit lines.                                                                                                                                                       |
-| `plan-files`                                                                                                                                             | Multi-step work keeps a visible task list mirrored to a plan file with a ledger of every item's outcome.                                                                                                                       |
-| `question-cards`                                                                                                                                         | Opt in to question cards beside complete text offers when the host supports them; availability and presentation can vary by host, provider and model.                                                                          |
-| `release-batching`                                                                                                                                       | Batch approved, compatible changes for releases and audit factual claims before releases or public announcements.                                                                                                              |
-| `scratch-on-disk`                                                                                                                                        | Task scratch lives on disk under the user data directory, never in RAM-backed `/tmp`.                                                                                                                                          |
-| `shared-host-load`                                                                                                                                       | Coordinate shared local work within host-defined resource budgets; isolate measurements and release reservations during remote waits.                                                                                          |
-| `solo-operator`                                                                                                                                          | For repositories with one maintainer, the user's direction is the review; no review-gated steps.                                                                                                                               |
-| `squash-landing`                                                                                                                                         | Pull requests land by squash merge after review-bot findings are handled, and the session's checkout moves off the landed branch.                                                                                              |
-| `swarmail`                                                                                                                                               | Locate Swarmail-owned instructions and tool contracts for local session coordination.                                                                                                                                          |
-
-Questions use text by default, with plain options or `coded-offers`. Text-only
-setups do not call question-card tools merely because a host exposes them.
-Enable `question-cards` only when you want cards too. Cards can be unavailable,
-skipped or shown unexpectedly across hosts, providers and models; the text
-offer remains usable on its own. `hr-house-rules-setup` asks which format you
-want and explains these limits before changing the configuration.
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Modifier&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | What it does                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backlog-outline`                                                                                                                                        | A backlog report adds a Markdown outline of every open item grouped by what it waits on; nothing is rendered, so it reads the same on every host.                                                                                                                     |
+| `backlog-visual`                                                                                                                                         | A backlog report adds one dark panel of every open item grouped by what it waits on, with a table for waiting items and one row per decision; hosts without a render tool get the same outline in Markdown.                                                           |
+| `coded-offers`                                                                                                                                           | Offers use numbered questions and coded options (`1A`, `1B`) so one short reply answers every decision.                                                                                                                                                               |
+| `cross-session-relay`                                                                                                                                    | Relayed work between sessions keeps its source and authorized scope, and an authorized push that changes inherited guidance or tooling is announced to the affected sessions.                                                                                         |
+| `effort-estimates`                                                                                                                                       | Options that differ in cost, or work that waits on CI, a build or a deploy, carry a wall-clock estimate based on comparable finished work. Estimates from workers, docs or other models are converted the same way or dropped.                                        |
+| `land-when-done`                                                                                                                                         | Authorized repository work is not finished until it is in the remote default branch.                                                                                                                                                                                  |
+| `low-quota-handoff`                                                                                                                                      | When the current model's usage allowance runs low, write a handoff before work stops.                                                                                                                                                                                 |
+| `model-default-questions`                                                                                                                                | Leave how questions are asked to your host and model, with no text-only or question-card instruction.                                                                                                                                                                 |
+| `multi-agent`                                                                                                                                            | Work is split across delegated workers and several agent hosts; worker reports, review standards and cleanup checks account for all of them.                                                                                                                          |
+| `no-attribution`                                                                                                                                         | Commits, pull requests and comments carry no agent or tool credit lines unless the target repository asks for a disclosure.                                                                                                                                           |
+| `periodic-updates`                                                                                                                                       | A job expected to run longer than about 10 minutes posts a short status update every 5 minutes by default, with progress, an ETA with its basis or "unmeasured", and findings so far, until the job ends; a watcher event that changes nothing gets at most one line. |
+| `plan-files`                                                                                                                                             | Multi-step work keeps a visible task list mirrored to a plan file with a ledger of every item's outcome.                                                                                                                                                              |
+| `question-cards`                                                                                                                                         | Opt in to question cards beside complete text offers when the host supports them; availability and presentation can vary by host, provider and model.                                                                                                                 |
+| `release-batching`                                                                                                                                       | Batch approved, compatible changes for releases and audit factual claims before releases or public announcements.                                                                                                                                                     |
+| `scratch-on-disk`                                                                                                                                        | Task scratch lives on disk under the user data directory, never in RAM-backed `/tmp`.                                                                                                                                                                                 |
+| `shared-host-load`                                                                                                                                       | On a shared machine, follow its resource budgets; without one, get operator direction before parallel workers or whole-repository commands, and use memory controls.                                                                                                  |
+| `solo-operator`                                                                                                                                          | For repositories with one maintainer, the user's direction is the review; no review-gated steps.                                                                                                                                                                      |
+| `squash-landing`                                                                                                                                         | Pull requests land by squash merge after review-bot findings are handled, and the session's checkout moves off the landed branch.                                                                                                                                     |
+| `upstream-contributions`                                                                                                                                 | A measured optimization, fix or defect found in a third-party project is offered for submission to that project through its own contribution route.                                                                                                                   |
+| `web-image-formats`                                                                                                                                      | Prefer WebP for web raster images when it saves bytes at acceptable quality, with format exceptions and delivered-file checks.                                                                                                                                        |
+
+Questions use text only by default. Setup asks how you want questions asked:
+
+- **Model default**: house-rules gives no instruction, so your model and host ask
+  their usual way (`model-default-questions`).
+- **Text only**: plain text options, with or without short reply codes such as
+  `1A` (`coded-offers`). No question tools are called, even when the host
+  exposes them.
+- **Clickable choices when available**: complete text options plus a
+  question card (`question-cards`). Cards can be unavailable, skipped or shown
+  unexpectedly across hosts, providers and models; the text offer remains usable
+  on its own.
+
+`hr-house-rules-setup` asks which you want and explains these limits before
+changing the configuration.
 
 ## Skills
 
 | Skill                       | Use it to                                                                                                 |
 | --------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `hr-agent-guidance-audit`   | Audit a repository's agent guidance for stale, duplicated or conflicting rules.                           |
+| `hr-agent-guidance-audit`   | Audit agent guidance for stale or conflicting rules, and decide what to retire or merge.                  |
 | `hr-agent-guidance-refresh` | Re-read guidance that changed since the session started.                                                  |
 | `hr-api-exposure-check`     | Keep API responses to the fields a consumer reads and the caller may see.                                 |
 | `hr-audit-choices`          | List and check the decisions made while implementing a task.                                              |
@@ -265,50 +275,71 @@ want and explains these limits before changing the configuration.
 | `hr-better-layout`          | Build and review grouping, alignment, spacing, responsive layout and clipping.                            |
 | `hr-better-typography`      | Style and review type scales, wrapping, spacing, truncation and font loading.                             |
 | `hr-better-writing`         | Write and review interface labels, errors, empty states and product terminology.                          |
-| `hr-change-impact`          | Check what a change can break beyond its diff before merging.                                             |
-| `hr-code-review`            | Review a diff against the repository's standards and the originating request.                             |
-| `hr-design-exploration`     | Compare four visual directions and refine the selected two toward one final design.                       |
+| `hr-code-review`            | Review a diff against standards and the request, and check what it can break beyond its lines.            |
+| `hr-design-exploration`     | Compare visual directions, or variants of one component, and refine toward one design.                    |
 | `hr-diagnosing-bugs`        | Work a hard bug or regression to a confirmed cause.                                                       |
 | `hr-explain-code`           | Trace how existing code works, read-only, before changing it.                                             |
 | `hr-extract-shared-steps`   | Move operations repeated across workflows into shared functions.                                          |
+| `hr-forgotten-work-audit`   | Audit past sessions, plans and handoffs for promised work that dropped off every list.                    |
 | `hr-handoff`                | Write a handoff a fresh session can resume from.                                                          |
 | `hr-house-rules-setup`      | Choose modifiers, create your layer and connect your hosts.                                               |
 | `hr-issue-tracker-setup`    | Configure project tracker, domain-term and ADR conventions; explicit-only.                                |
 | `hr-lean-plan`              | Write or tighten an implementation plan with the fewest moving parts.                                     |
-| `hr-maintainability-review` | Review a diff or entire codebase strictly for structure and maintainability.                              |
+| `hr-maintainability-review` | Review a diff or entire codebase strictly for structure, over-engineering and leftover scaffolding.       |
 | `hr-manual-qa`              | Give reproducible human checks after reporting agent verification results.                                |
 | `hr-navigation-retro`       | Audit navigation failures in selected transcripts and propose verified findability fixes; explicit-only.  |
 | `hr-ordering-tests`         | Enumerate event orderings through the real code to find race bugs.                                        |
 | `hr-plain-prose`            | Make text people read plain and specific.                                                                 |
 | `hr-progress-report`        | Report current task activity, milestone completion and remaining wall-clock time.                         |
-| `hr-pr-followup`            | Address conflicts, feedback and failing checks for a requested PR; honor existing landing authority.      |
+| `hr-pr-followup`            | Address conflicts, feedback and failing checks for a PR; honor landing authority; CodeRabbit review gate. |
 | `hr-read-reddit`            | Read Reddit feed output while supported; RSS support ends November 13, 2026. Partial web-search fallback. |
 | `hr-read-x-links`           | Read the full content of X posts.                                                                         |
+| `hr-research-shared-links`  | Research a shared link or repository in depth, compare it with your setup and rate each idea.             |
 | `hr-split-to-prs`           | Divide work into coherent PRs while preserving recovery points and verifying each slice.                  |
+| `hr-sqlite`                 | Check settings, locking, queries and copies in SQLite code against measured findings.                     |
 | `hr-stock-ui-audit`         | Find and triage template-default styling in frontend code.                                                |
 | `hr-tdd`                    | Implement requested test-first work through one red-green slice at a time; simplify during review.        |
 | `hr-test-audit`             | Decide which new tests are worth keeping and which old ones to prune.                                     |
+| `hr-usage-report`           | Measure where agent usage went by provider, model and role, and chart model comparisons.                  |
 | `hr-what-next`              | Reconcile remaining session work and recommend priorities when asked what comes next.                     |
 | `hr-writing-for-agents`     | Write skills, rules and other documents agents read.                                                      |
 | `hr-writing-pr`             | Write a pull request title and body from the final diff.                                                  |
 
+The `hr-navigation-retro` skill finds navigation failures in selected tool-call
+transcripts, then proposes fixes verified against current source. Any agent with
+file and shell access can run it. Supported inputs include Claude Code, Codex,
+OpenCode exports, Cursor CLI streams and ACP v1 recordings from other agents.
+See its [input limits](skills/hr-navigation-retro/references/inputs.md).
+It is explicit-only, requires Python 3.11+ and keeps reports local.
+
 ## Checking the rules against your models
 
-`evals/end-of-reply/` runs short scenarios through any model CLI and grades
+`evals/end-of-reply/` (in the GitHub repository, not the npm package) runs short scenarios through any model CLI. It grades
 whether the agent keeps working or ends with an offer at the right time,
-including when it reads only the first 80 lines. In a 2026-10-04 run of the
-three original scenarios against v0.5.7 on seven models, the rules passed 62 of
-63 replies, against 26 for a one-sentence instruction and 21 with no rules; its
-README has the breakdown and limits.
+including when it reads only the first 80 lines. A 2026-10-11 replay covered
+its 18 scenarios, two runs each, on Claude Code 2.1.296 only, at revision
+`efd4d7b`; `rules/core.md` has changed since. The rules scored
+22 of 36 replies with Opus 5.5 and 27 of 36 with Sonnet 5.5. A one-sentence
+instruction scored 18 and 16, and no rules scored 17 and 16. The gains cluster
+in follow-ups, parked findings, stacked offers and spin-offs, where the
+controls scored 0. Two runs per scenario is a small sample, so read the counts,
+not a percentage. No other agent was measured. The eval's README has the
+breakdown and limits.
 
 ## Development
 
 ```bash
-node --test test/*.test.mjs   # composer and eval grader (or: bun test test/)
-bun test skills/    # skill scripts
-npx oxlint . && npx oxfmt --check .
+node --test test/*.test.mjs   # composer and eval grader
+bun test test/                # the same under Bun
+bun test skills/              # skill scripts
+npm run check:package -- --bun   # npm tarball: packs, installs, runs the CLI
+npx --yes oxlint@1.85.0 . && npx --yes oxfmt@0.70.0 --check .
 ```
 
+These versions match the pins in `.github/workflows/check.yml`; an unpinned `npx`
+fetches the latest release, whose formatting can differ from CI's. Change both
+together.
+
 Oxfmt checks authored Markdown, HTML, JSON, JSONC, YAML, TOML and CSS as well
 as JavaScript and TypeScript. Test fixtures stay excluded because scanner
 tests depend on their exact text and line numbers. Package fields and
@@ -319,7 +350,7 @@ Set `HOUSE_RULES_TEST_TMP` to an existing directory to choose their scratch root
 otherwise they use the operating system temporary directory. Choose a disk-backed
 location when the system temporary directory is RAM-backed.
 
-CI runs the same checks on every push and pull request. See
+CI runs these checks on every pull request and on pushes to `main`, and also runs the tests and the tarball check on Windows. See
 [CONTRIBUTING.md](CONTRIBUTING.md) before opening one.
 
 The local-reference gate runs in `test/guidance-links.test.mjs`. Audit another

package/compose.mjs

@@ -51,7 +51,13 @@ function main(argv) {
     return;
   }
   const configPath = configurationPath(values.config);
-  const config = JSON.parse(readFileSync(configPath, "utf8").replace(/^\uFEFF/, ""));
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+    throw new Error(`${configPath} is not valid JSON (${error.message}); fix it or move it aside`);
+  }
   const { out, "skills-out": skillsOut, "references-out": explicitReferences } = values;
   if (explicitReferences && !out) throw new Error("--references-out requires --out");
   const referencesOut = out
@@ -102,7 +108,7 @@ function main(argv) {
     for (const f of NOTICES) cpSync(join(BASE, f), join(skillsOut, f));
   }
   console.error(
-    `composed ${fragments.length} fragment(s), ${rules.split("\n").length} lines${skillsOut ? `, ${skills.size} skill(s)` : ""}`,
+    `composed ${rules.split("\n").length} lines of rules from ${fragments.length} optional or personal rule file(s)${skillsOut ? ` and ${skills.size} skill(s)` : ""}`,
   );
 }
 

package/composition.mjs

@@ -14,6 +14,10 @@ const KEYS = [...OPS, "description", "requires", "reference"];
 // Windows line endings and a byte-order mark would otherwise hide frontmatter and headings.
 const normalize = (text) => text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
 
+// A YAML value may be wrapped in one pair of matching quotes; the text inside is the value.
+const unquote = (value) =>
+  value.length > 1 && /^(["']).*\1$/.test(value) ? value.slice(1, -1) : value;
+
 // Minimal frontmatter: `key: value` lines between `---` fences.
 export function parseFragment(rawText, source) {
   const text = normalize(rawText);
@@ -22,7 +26,7 @@ export function parseFragment(rawText, source) {
   if (m) {
     for (const line of m[1].split("\n")) {
       const i = line.indexOf(":");
-      if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+      if (i > 0) meta[line.slice(0, i).trim()] = unquote(line.slice(i + 1).trim());
     }
   }
   return { meta, body: (m ? text.slice(m[0].length) : text).trim(), source };
@@ -182,7 +186,10 @@ const layersOf = (config) => config.layers ?? ["."];
 function loadRawFragments(config, configDir) {
   const fragments = (config.modifiers ?? []).map((name) => {
     const path = join(BASE, "rules/modifiers", `${name}.md`);
-    if (!existsSync(path)) throw new Error(`unknown modifier "${name}" (see --list)`);
+    if (!existsSync(path))
+      throw new Error(
+        `unknown modifier "${name}"; remove it from "modifiers" in the configuration file ("node compose.mjs --list" in the checkout, or "house-rules --list", shows the available names)`,
+      );
     return { ...parseFragment(readFileSync(path, "utf8"), `modifier ${name}`), path, root: BASE };
   });
   for (const layer of layersOf(config)) {
@@ -340,7 +347,8 @@ export function composeConfiguration(config, configDir, { referencesDirectory }
   const references = new Map([...candidates].map(([name, value]) => [name, value.text]));
   const skills = skillSources(config, configDir);
   const warnings = [];
-  for (const f of fragments) {
+  const core = parseFragment(readFileSync(join(BASE, "rules/core.md"), "utf8"), "rules/core.md");
+  for (const f of [core, ...fragments]) {
     for (const need of (f.meta.requires ?? "")
       .split(",")
       .map((s) => s.trim())

package/config-view.mjs

@@ -74,13 +74,16 @@ export function renderHelp() {
     "  Selection",
     "    --enable-modifier <name>    --disable-modifier <name>",
     "    --enable-skill <name>       --disable-skill <name>",
-    "    --questions plain|coded|cards",
+    "    --questions default|plain|coded|cards",
+    "    --panel-file <json>        Replace portable panel preferences (preview/set)",
+    "    --expect-panel <revision>  Require reviewed panel input when applying",
     "",
     "  Output",
     "    --config <path>   --json   --rules (preview only)",
     "",
     "  Repeat toggle flags to change several selections together.",
     "  Saving config does not regenerate output or connect agent hosts.",
+    "  Panel preferences do not discover providers, enable a skill or run models.",
     "",
   ].join("\n");
 }
@@ -124,12 +127,24 @@ export function renderConfig(report) {
       }
       if (!removed.length && !added.length) detail("Selection order changed.");
     }
+    if (report.panel) {
+      section(report.panel.changed ? "Panel section replacement" : "Panel section unchanged");
+      detail(`Panel input revision  ${report.panel.revision}`);
+      detail("Before");
+      for (const line of JSON.stringify(report.panel.before, null, 2).split("\n")) detail(line);
+      detail("After");
+      for (const line of JSON.stringify(report.panel.after, null, 2).split("\n")) detail(line);
+      detail(
+        `Preferences ${report.applied ? "configured" : "proposed"} only. Route access, effort and permissions are unverified.`,
+      );
+    }
     lines.push("");
     if (!report.applied) {
+      const panelGuard = report.panel ? ` --expect-panel ${report.panel.revision}` : "";
       detail(
         report.command === "set"
-          ? `To save, repeat with --apply --expect ${report.revision}`
-          : `To save, run config set with the same selection flags plus --apply --expect ${report.revision}`,
+          ? `To save, repeat with --apply --expect ${report.revision}${panelGuard}`
+          : `To save, run config set with the same selection flags plus --apply --expect ${report.revision}${panelGuard}`,
       );
       detail("Review personal rule overrides below before choosing a question format.");
     } else