@bompus/house-rules 0.11.0 → 0.13.0

package/config.mjs

@@ -27,6 +27,7 @@ import {
   splitSections,
 } from "./composition.mjs";
 import { renderConfig, renderHelp } from "./config-view.mjs";
+import { changePanelPreferences } from "./skills/hr-code-review/scripts/panel-preferences.mjs";
 
 const COMMANDS = ["catalog", "status", "validate", "preview", "set"];
 const TOGGLES = ["enable-modifier", "disable-modifier", "enable-skill", "disable-skill"];
@@ -41,6 +42,10 @@ function stringList(value, key) {
   if (new Set(value).size !== value.length) throw new Error(`${key} contains duplicates`);
 }
 
+export const QUESTION_PRESETS = ["default", "plain", "coded", "cards"];
+export const QUESTION_MODIFIERS = ["model-default-questions", "coded-offers", "question-cards"];
+const BACKLOG_VIEWS = ["backlog-visual", "backlog-outline"];
+
 function validateStructure(config) {
   if (!object(config)) throw new Error("configuration must be a JSON object");
   for (const key of ["modifiers", "layers"]) stringList(config[key], key);
@@ -54,12 +59,26 @@ function validateSelection(config) {
   validateStructure(config);
   const known = new Set(modifierList().map((m) => m.name));
   for (const name of config.modifiers ?? []) {
-    if (!known.has(name)) throw new Error(`unknown modifier "${name}" (see config catalog)`);
+    if (!known.has(name))
+      throw new Error(
+        `unknown modifier "${name}" (see config catalog); preview its removal with config set --disable-modifier <name>, then save it with config set --disable-modifier <name> --apply --expect <revision>`,
+      );
   }
+  if (BACKLOG_VIEWS.every((name) => config.modifiers?.includes(name)))
+    throw new Error(
+      `${BACKLOG_VIEWS.join(" and ")} cannot be combined; enable one, or neither for the table alone`,
+    );
   if (config.modifiers?.includes("question-cards") && !config.modifiers.includes("coded-offers"))
     throw new Error(
       "question-cards requires coded-offers; use --questions cards or disable question-cards",
     );
+  if (
+    config.modifiers?.includes("model-default-questions") &&
+    config.modifiers.some((name) => ["coded-offers", "question-cards"].includes(name))
+  )
+    throw new Error(
+      "model-default-questions cannot combine with coded-offers or question-cards; use --questions",
+    );
 }
 
 export function readConfiguration(path) {
@@ -77,7 +96,7 @@ export function readConfiguration(path) {
   try {
     if (text !== null) config = JSON.parse(text.replace(/^\uFEFF/, ""));
   } catch {
-    throw new Error("invalid JSON in configuration");
+    throw new Error(`invalid JSON in ${path}`);
   }
   validateStructure(config);
   return { path, text, revision: revisionOf(text), config };
@@ -127,11 +146,13 @@ export function selectionReport(config, path) {
     unavailable,
     layers: (config.layers ?? ["."]).map((layer) => resolve(dirname(path), layer)),
     fragments: result.fragments.map((f) => ({ source: f.source, ...f.meta })),
-    questions: selected.has("question-cards")
-      ? "cards"
-      : selected.has("coded-offers")
-        ? "coded"
-        : "plain",
+    questions: selected.has("model-default-questions")
+      ? "default"
+      : selected.has("question-cards")
+        ? "cards"
+        : selected.has("coded-offers")
+          ? "coded"
+          : "plain",
     warnings: result.warnings,
     composedRules: result.rules,
     hostLoading: "unverified",
@@ -165,7 +186,7 @@ export function changeSelection(config, options, path) {
       if (
         kind === "modifier" &&
         options.questions !== undefined &&
-        ["coded-offers", "question-cards"].includes(name)
+        QUESTION_MODIFIERS.includes(name)
       )
         throw new Error("use --questions or explicit question modifiers, not both");
     }
@@ -182,12 +203,15 @@ export function changeSelection(config, options, path) {
     }
   }
   if (options.questions !== undefined) {
-    if (!["plain", "coded", "cards"].includes(options.questions))
-      throw new Error("--questions must be plain, coded or cards");
-    if (options.questions === "plain") modifiers.delete("coded-offers");
+    if (!QUESTION_PRESETS.includes(options.questions))
+      throw new Error("--questions must be default, plain, coded or cards");
+    if (options.questions === "plain" || options.questions === "default")
+      modifiers.delete("coded-offers");
     else modifiers.add("coded-offers");
     if (options.questions === "cards") modifiers.add("question-cards");
     else modifiers.delete("question-cards");
+    if (options.questions === "default") modifiers.add("model-default-questions");
+    else modifiers.delete("model-default-questions");
   }
   if (JSON.stringify([...modifiers]) !== JSON.stringify(next.modifiers ?? []))
     next.modifiers = [...modifiers];
@@ -284,12 +308,16 @@ export function configCommand(argv) {
       questions: { type: "string" },
       apply: { type: "boolean" },
       expect: { type: "string" },
+      "panel-file": { type: "string" },
+      "expect-panel": { type: "string" },
       ...Object.fromEntries(TOGGLES.map((key) => [key, { type: "string", multiple: true }])),
     },
   });
   if (values.help) return console.log(renderHelp());
   const changing = Boolean(
-    values.questions !== undefined || TOGGLES.some((key) => values[key]?.length),
+    values.questions !== undefined ||
+    values["panel-file"] !== undefined ||
+    TOGGLES.some((key) => values[key]?.length),
   );
   if (
     (changing || values.apply || values.expect !== undefined) &&
@@ -298,10 +326,31 @@ export function configCommand(argv) {
     throw new Error("selection flags belong to config set or preview");
   if (values.apply && command !== "set") throw new Error("--apply belongs to config set");
   if (values.expect !== undefined && !values.apply) throw new Error("--expect requires --apply");
+  if (values["expect-panel"] !== undefined && (!values.apply || values["panel-file"] === undefined))
+    throw new Error("--expect-panel requires --apply and --panel-file");
   if (values.rules && values.json) throw new Error("choose --rules or --json, not both");
   if (values.rules && command !== "preview") throw new Error("--rules belongs to config preview");
+  if (values.rules && values["panel-file"] !== undefined)
+    throw new Error("--panel-file requires a change report; omit --rules");
   const snapshot = readConfiguration(configurationPath(values.config));
-  const next = changing ? changeSelection(snapshot.config, values, snapshot.path) : snapshot.config;
+  let next = changing ? changeSelection(snapshot.config, values, snapshot.path) : snapshot.config;
+  let panelRevision;
+  if (values["panel-file"] !== undefined) {
+    const path = resolve(values["panel-file"]);
+    if (!lstatSync(path).isFile())
+      throw new Error("panel input must be a regular file, not a symlink or directory");
+    const text = readFileSync(path, "utf8");
+    panelRevision = revisionOf(text);
+    if (values.apply && values["expect-panel"] !== panelRevision)
+      throw new Error("panel input changed or --expect-panel missing; preview again");
+    let preferences;
+    try {
+      preferences = JSON.parse(text.replace(/^\uFEFF/, ""));
+    } catch {
+      throw new Error("invalid JSON in panel input");
+    }
+    next = changePanelPreferences(next, preferences);
+  }
   const report = selectionReport(next, snapshot.path);
   const changes = selectionChanges(snapshot.config, next);
   const applied = values.apply ? writeConfiguration(snapshot, next, values.expect) : null;
@@ -312,6 +361,18 @@ export function configCommand(argv) {
     revision: applied?.revision ?? snapshot.revision,
     changes,
     applied,
+    ...(values["panel-file"] === undefined
+      ? {}
+      : {
+          panel: {
+            state: values.apply ? "configured" : "proposed",
+            revision: panelRevision,
+            before: snapshot.config.panel ?? null,
+            after: next.panel,
+            changed: JSON.stringify(snapshot.config.panel) !== JSON.stringify(next.panel),
+            readiness: "unverified",
+          },
+        }),
     ...report,
   };
   if (values.rules) return process.stdout.write(report.composedRules);

package/docs/configuration.md

@@ -19,7 +19,7 @@ or `toggle NAME`, with several choices separated by spaces. `search TEXT`,
 Excluding a skill name excludes its personal override as well as the shipped
 copy. Exclusions without a current source remain in the configuration.
 
-Use `questions plain|coded|cards` for question preferences; these modifiers
+Use `questions default|plain|coded|cards` for question preferences; these modifiers
 are handled together rather than as individual toggles. `next` moves from
 modifiers to skills, then review. `back` keeps the draft. Only `save` on review
 writes configuration. Before a save attempt, `cancel`, end of input or Ctrl-C
@@ -86,7 +86,7 @@ validation proves what a running agent has loaded.
 
 ```bash
 node compose.mjs config set --config <config-path> \
-  --enable-modifier swarmail --disable-skill hr-read-reddit --questions coded
+  --enable-modifier shared-host-load --disable-skill hr-read-reddit --questions coded
 ```
 
 `set` previews by default. It shows the selection changes, composition summary,
@@ -102,11 +102,17 @@ not add a shipped name. Disabling adds an exclusion, retaining the include list,
 unrelated exclusions and custom settings. Configs without an include list keep
 their existing selection behavior.
 
-| Question preset     | Enabled offer modifiers             |
-| ------------------- | ----------------------------------- |
-| `--questions plain` | Neither offer modifier              |
-| `--questions coded` | `coded-offers`                      |
-| `--questions cards` | `coded-offers` and `question-cards` |
+| Question preset       | What you get                      | Enabled offer modifiers             |
+| --------------------- | --------------------------------- | ----------------------------------- |
+| `--questions default` | Model default                     | `model-default-questions`           |
+| `--questions plain`   | Text only                         | Neither offer modifier              |
+| `--questions coded`   | Text only, with short reply codes | `coded-offers`                      |
+| `--questions cards`   | Clickable choices when available  | `coded-offers` and `question-cards` |
+
+`default` adds no instruction about how to ask: the model and host ask
+questions their usual way, which on some hosts means clickable choices and on
+others plain text. Core rules, without a preset, keep text only. `default`
+cannot combine with `coded-offers` or `question-cards`.
 
 Question presets preserve other modifiers. Choose a preset or explicit offer
 modifier toggles, rather than combining both in one command. Cards still depend
@@ -125,6 +131,75 @@ contradictory flags, malformed config and composition errors stop the command
 before it writes configuration. Older skill names need the
 [skill name upgrade](skill-names.md) before composition.
 
+## Optional panel preferences
+
+Use `--panel-file <json>` with `config preview` or `config set` to replace only
+the configuration's `panel` section. The input contains the complete preferences
+object, without a surrounding `panel` key. It must be a regular JSON file.
+
+```json
+{
+  "version": 1,
+  "profile": "balanced",
+  "roles": [
+    { "id": "correctness", "candidates": ["review-primary", "review-alternative"] },
+    { "id": "contrarian", "candidates": ["challenge-primary"] }
+  ],
+  "policy": {
+    "fallback": "approved-only",
+    "roundLimit": 1,
+    "meteredRoutes": "explicit-approval-required",
+    "distinctFamilies": true,
+    "excludeAuthorFamily": true,
+    "allowReducedPanel": false
+  }
+}
+```
+
+```bash
+node compose.mjs config preview --config <config-path> --panel-file <panel-json>
+node compose.mjs config set --config <config-path> --panel-file <panel-json> \
+  --apply --expect <reviewed-config-revision> --expect-panel <reviewed-input-revision>
+```
+
+Preview shows the entire previous and proposed panel section, including ordered
+alternatives. Explicit apply replaces that section; it does not merge role lists.
+Normal selection flags can accompany a panel replacement, with both changes
+covered by the same revision guard. `--rules` cannot accompany `--panel-file`
+because rule output would hide the panel replacement preview.
+Panel input has its own SHA-256 revision. Apply requires `--expect-panel` from
+the preview as well as the config revision, so an edited input file cannot
+silently replace reviewed preferences. A changed input requires another preview.
+
+Version 1 requires `version`, a non-empty ordered `roles` array and `policy`.
+Each role has a unique `id` and a non-empty ordered `candidates` array without
+duplicates. Role IDs and candidate aliases start with a lowercase letter, use
+only lowercase letters, digits and hyphens, and contain at most 64 characters.
+Aliases refer to future local bindings; they are not provider/model identifiers.
+The optional `profile` is `quick`, `balanced` or `deep`. It records a preference,
+not a measured performance tier or a seat-count default.
+
+Policy requires `fallback` (`none` or `approved-only`), a positive safe-integer
+`roundLimit`, and `meteredRoutes` (`included-only` or
+`explicit-approval-required`). Optional `distinctFamilies`, `excludeAuthorFamily`
+and `allowReducedPanel` are booleans. An omitted policy option is unspecified,
+not permission to bypass a host or project limit. Unknown fields and unsupported
+versions fail an explicit panel operation before configuration writes.
+
+The preview reports `proposed`; an explicit save reports `configured`.
+Both report readiness as `unverified`. This feature stores preferences only.
+It does not discover or resolve providers, verify quota or effective effort,
+enforce policy at runtime, enable a skill, change subscriptions or invoke models.
+Exact routes and effort choices belong to local bindings, outside this portable
+schema; the `hr-code-review` skill's `panel-plan.mjs` resolves preferences and
+bindings into seats without calling a model ([contract](../skills/hr-code-review/references/panel-plan.md)). To choose or change seats with the agent, ask it to set up or change your review panel; the skill's [setup procedure](../skills/hr-code-review/references/panel-setup.md) suggests seats from dated recommendations and saves nothing until you confirm. Saving preferences does not authorize spending or waive review gates.
+
+Ordinary setup, composition and selection operations preserve existing `panel`
+data without adopting or validating it, including older unrelated uses of that
+key. Before replacing such data, review the full preview. Other selections and
+custom keys are retained. Credentials and provider configuration do not belong
+in the panel input. Input validation checks structure, not secret detection.
+
 ## Write safeguards
 
 Saving requires the revision reported by status or preview. A stale revision
@@ -144,8 +219,9 @@ another writer's lock automatically.
 ## Compose and connect
 
 Saving changes only configuration. Recompose with the existing composer or run
-the installer again. The installer retains previous composed skill directories;
-manual `--skills-out` still requires an empty or absent directory.
+the installer again. When the composed skills changed, the installer keeps the
+previous composed skills directory under a dated name; when they match, it keeps
+nothing extra. Manual `--skills-out` still requires an empty or absent directory.
 
 ```bash
 node compose.mjs --config <config-path> --out <rules-path> \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bompus/house-rules",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Composable working rules and skills for AI coding agents",
   "homepage": "https://github.com/bompus/house-rules#readme",
   "license": "MIT",
@@ -23,10 +23,12 @@
     "!skills/*/test/",
     "!**/__pycache__/",
     "docs/",
+    "!docs/npm-release.md",
     "examples/",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md",
-    "CONTRIBUTING.md"
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
   ],
   "type": "module",
   "publishConfig": {