@bompus/house-rules 0.0.0-stage → 0.13.0

package/docs/configuration.md

@@ -0,0 +1,269 @@
+# Configure house rules
+
+Use `node compose.mjs config help` to see the commands. Bun supports the same
+interface. The CLI manages the existing `house-rules.json`; it keeps personal
+layers, independent skill names and unrelated settings.
+
+## Guided selection
+
+Run `node compose.mjs setup --config <config-path>` in a terminal. Bun supports
+the same command. The numbered flow uses ordinary line input; `--plain` selects
+the same flow. Both input and output must be terminals. Redirected input or
+output prints scripting instructions and exits 2 without saving. Use
+`setup --json` for the existing read-only `config status --json` report.
+
+Modifiers and skills have stable row numbers while searching. Use `toggle N`
+or `toggle NAME`, with several choices separated by spaces. `search TEXT`,
+`clear search`, `show selected` and `show all` change visibility only.
+`help N` shows the full description, source and invocation policy.
+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 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
+leaves it unchanged.
+A new config with no selection changes is not created.
+
+Review includes personal rule origins and an equivalent `config set` command.
+The command uses POSIX quoting on Unix and PowerShell quoting on Windows.
+Personal prose can override the selected preferences; setup does not interpret
+or edit it. Existing composition errors still block saving. Unknown stored
+modifiers can be removed, and a question preset can repair its prerequisite.
+Malformed configuration, legacy skill names and invalid layers require repair
+outside setup.
+
+If another writer changes configuration before save, setup preserves the
+draft intent and refuses the stale write. Use `refresh` to compare that intent
+with the fresh configuration, then explicitly save again. It never saves a
+fresh comparison automatically. Saving preserves custom keys and their meaning;
+the writer formats JSON, so existing whitespace is not preserved.
+
+If verification fails after saving, configuration may already have changed.
+Inspect `config status` or use `refresh` before another save. Cancelling ends
+the session without undoing an earlier save attempt.
+
+Setup saves selections only. Recompose output separately, then connect the
+chosen hosts. It does not install, update, repair or remove managed output.
+
+## Browse and inspect
+
+```bash
+node compose.mjs config catalog --config <config-path>
+node compose.mjs config status --config <config-path>
+node compose.mjs config validate --config <config-path>
+```
+
+`setup` initially shows current selections. Search for relevant additions or
+use `show all` to browse the complete catalog. Review and saving do not require
+a catalog-wide decision.
+
+`catalog` shows modifiers, skills and rule sections. `status` shows enabled
+selections and effective personal sources. Both use aligned tables, with color
+in a terminal and stacked rows on narrow screens. `NO_COLOR` disables color.
+Use `--json` for structured output without terminal styling.
+
+A missing config is treated as an empty selection without creating files.
+Modifiers are opt-in. Fresh installers copy the sample config with eight skills
+and no modifiers. A missing config or an existing config without `skills.include`
+keeps the full shipped set. The default config path is the same as the composer
+uses. Pass `--config` to choose another.
+
+`skills.include` is an optional list of shipped skill names. An empty list selects
+no shipped skills; later shipped additions stay off unless listed. Unknown names,
+malformed lists and duplicates are errors. Personal layer skills still load and
+override shipped skills, even when the shipped name is absent from the list.
+`skills.exclude` takes precedence across every layer. Existing independent names,
+layers and custom settings retain their behavior. The catalog remains complete
+so you can discover additions without enabling them.
+
+Status distinguishes configured question preferences from effective rule
+sources. Personal rules can override those preferences. Neither status nor
+validation proves what a running agent has loaded.
+
+## Preview and save
+
+```bash
+node compose.mjs config set --config <config-path> \
+  --enable-modifier shared-host-load --disable-skill hr-read-reddit --questions coded
+```
+
+`set` previews by default. It shows the selection changes, composition summary,
+personal rule overrides and current revision. Repeat the exact command with
+`--apply --expect <revision>` to save the reviewed change. Read the new revision
+from the result before another write.
+
+Toggle flags can repeat. Enable or disable modifiers with `--enable-modifier`
+and `--disable-modifier`; skills use `--enable-skill` and `--disable-skill`.
+Enabling a skill removes its exclusion. When `skills.include` exists, enabling
+a shipped skill also adds it to that list. Enabling a personal-only skill does
+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       | 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
+on the agent host, provider and model. Review any personal Offers override
+before saving; the CLI does not rewrite personal prose.
+
+To repair invalid modifier selections, preview changes that produce a valid
+selection. `--questions` can repair the offer dependency; `--disable-modifier`
+can remove an unknown modifier already stored in the config. Malformed config
+structure, unknown enables and unknown disables absent from the config remain
+errors.
+
+`preview` accepts the same selection flags without saving. Add `--rules` to
+print the composed rules, or `--json` for the full report. Unknown choices,
+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
+fails without overwriting a newer config. Cooperating CLI writers share an
+exclusive `<config-path>.lock` file; a competing writer fails immediately.
+The CLI writes a sibling temporary file, then replaces the config atomically.
+Repeated requests leave an unchanged config's bytes and modification time alone.
+A missing config is created only by explicit apply.
+
+Manual editors do not share the lock. Avoid editing the config while a CLI
+write runs. The CLI checks again before replacement, but cannot exclude a
+manual write racing that final replacement. It refuses symlink config files.
+If an interrupted writer leaves a lock, inspect its recorded process ID and
+confirm that writer has ended before removing the lock. The CLI never removes
+another writer's lock automatically.
+
+## Compose and connect
+
+Saving changes only configuration. Recompose with the existing composer or run
+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> \
+  --skills-out <new-skills-directory>
+```
+
+Connecting or copying that output to agent hosts remains a separate setup
+step. Use `hr-house-rules-setup` for the guided workflow. Custom rule prose
+still belongs in layer fragments; the protected completion sections stay
+required.
+
+## Reference output
+
+`--out rules.md` writes selected procedure references to a sibling
+`house-rules-references/` directory. Keep that directory beside the rules file
+when copying it to a host. References do not depend on `skills.include` or
+`skills.exclude`. Core Landing and Reporting always contribute their references; enabled modifiers
+contribute theirs. Reporting is also bundled with `hr-what-next` for standalone
+skill use. Excluding that skill does not remove the core reference. A personal replacement suppresses the resource it replaces.
+
+The `multi-agent` modifier exports its complete agent-work procedure when enabled,
+including review follow-ups and cleanup qualification. It remains independent
+of selected skills; enabling reference output does not enable the modifier.
+
+Use `--references-out <directory>` with `--out` to choose another destination;
+links are rendered relative to the rules file. Keep both locations available.
+Stdout and ordinary composition/configuration API calls retain full inline
+procedures, so existing preview and copy-only workflows need no bundle.
+
+A hash manifest permits repeat exports and updates to previously generated
+files. Modified, missing or unrecognized files in that directory stop generation
+before output writes. Reconcile them explicitly; generation never removes old
+procedure files or unrelated files. Output directories must not overlap.
+
+Core rule frontmatter may name one `reference` or a comma-separated `references`
+list relative to `rules/core.md`. Use only one form; list paths and section headings
+must be distinct and non-empty. Each target must be a regular file within the
+source layer, with one level-2 heading matching the core section holding its
+mandatory link. Default composition expands that section;
+linked output retains its safety boundaries and reading trigger. Modifier
+references use the same validation and output inventory.
+
+For low-level `compose(coreText, fragments)`, use `loadFragments` for personal
+layers so reference paths retain their source ownership. Directly parsed shipped
+modifiers are recognized only when their label and body match the shipped file.

package/docs/skill-names.md

@@ -0,0 +1,50 @@
+# Upgrading skill names
+
+Every skill shipped by house-rules uses the `hr-` prefix. For example,
+`handoff` becomes `hr-handoff`. Rule headings, modifier names and the
+`house-rules` command stay the same. Skills from other sources keep their names.
+
+## Before updating
+
+1. In `house-rules.json`, replace each shipped skill name in `skills.exclude`
+   with its `hr-` name.
+2. For each personal override of a shipped skill, rename its directory and
+   its frontmatter `name:` to the matching `hr-` name.
+3. Update your skill invocations, rules, links and host settings to use the
+   new names.
+
+Composition refuses unresolved old exclusion names, ambiguous old personal
+folders and legacy frontmatter names in prefixed overrides before writing output. The error names the replacement. Fix the
+config or layer, then compose again. The installer keeps the previous composed
+skills until composition succeeds.
+
+A personal override named `hr-handoff` replaces the shipped `hr-handoff`.
+If your generic `handoff` is a separate skill you intend to keep alongside it,
+record that decision in your config:
+
+```json
+{
+  "skills": {
+    "independent": ["handoff"],
+    "exclude": ["hr-read-reddit"]
+  }
+}
+```
+
+`skills.independent` lets the listed personal skills keep names that match old
+house-rules names. It does not create an alias or replace the prefixed skill.
+`skills.exclude` uses the new names for shipped skills. An old name listed in
+`skills.independent` refers to the independent personal skill and can be excluded
+without excluding its prefixed counterpart. Unrelated personal
+names need no entry in `skills.independent`.
+
+## Connect hosts after composing
+
+If a host reads the whole composed directory, point it at the new composed set.
+If it has individual skill links or copied folders, replace its old house-rules
+entries with the matching prefixed entries. Preserve unrelated skills.
+Restart or reload the host and check that it discovers the new names.
+
+The composer and installer do not edit host files or remove old host entries.
+Do not keep both the old and new house-rules copies active. Historical skill
+invocations need the new names; there are no compatibility aliases.

package/examples/person/house-rules.json

@@ -0,0 +1,15 @@
+{
+  "modifiers": [],
+  "skills": {
+    "include": [
+      "hr-house-rules-setup",
+      "hr-code-review",
+      "hr-diagnosing-bugs",
+      "hr-explain-code",
+      "hr-lean-plan",
+      "hr-test-audit",
+      "hr-plain-prose",
+      "hr-what-next"
+    ]
+  }
+}

package/examples/person/rules/10-tooling.md

@@ -0,0 +1,8 @@
+---
+after: Implementation economy
+---
+
+## My tooling
+
+Use `pnpm` for JavaScript projects unless the repository already uses another
+package manager. Run the project's own lint and test scripts before committing.

package/examples/person/rules/20-reporting.md

@@ -0,0 +1,9 @@
+---
+replaces: Reporting
+---
+
+## Reporting
+
+Lead with the result in one sentence, then a short list of what changed, what
+was checked and what is left. Keep reports under 15 lines unless asked for
+detail.

package/examples/project/AGENTS.md

@@ -0,0 +1,18 @@
+# Example project
+
+## Session
+
+Before your first reply in a session, read § End of every reply and § Offers in
+your user-level house rules in full. They apply here unchanged; this file only
+adds to them and never removes the offer.
+
+## Landing
+
+This repository lands by direct push to `main` after `npm test` passes; that
+is the landing path § Landing asks the repository to name. Never force-push
+`main`.
+
+## Commands
+
+- Install: `npm ci`
+- Test: `npm test`

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@bompus/house-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.0",
+  "description": "Composable working rules and skills for AI coding agents",
+  "homepage": "https://github.com/bompus/house-rules#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bompus/house-rules.git"
+  },
+  "bin": {
+    "house-rules": "compose.mjs"
+  },
+  "files": [
+    "compose.mjs",
+    "composition.mjs",
+    "rule-references.mjs",
+    "config.mjs",
+    "config-view.mjs",
+    "setup.mjs",
+    "rules/",
+    "skills/",
+    "!skills/*/test/",
+    "!**/__pycache__/",
+    "docs/",
+    "!docs/npm-release.md",
+    "examples/",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "check:package": "node scripts/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/rule-references.mjs

@@ -0,0 +1,91 @@
+// Plan reference writes before changing output; retain owned older files, never delete them.
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+const safeName = (name) => /^[a-z0-9][a-z0-9-]*\.md$/.test(name);
+
+export function checkOutputPath(path, directory = false) {
+  path = resolve(path);
+  for (let current = path; ; current = dirname(current)) {
+    let stat;
+    try {
+      stat = lstatSync(current);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (stat) {
+      if (
+        stat.isSymbolicLink() ||
+        (current === path && !directory ? !stat.isFile() : !stat.isDirectory())
+      )
+        throw new Error(`Unsafe output path: ${current}`);
+    }
+    if (dirname(current) === current) break;
+  }
+}
+
+export function planReferenceOutput(directory, references) {
+  checkOutputPath(directory, true);
+  const manifestPath = join(directory, "manifest.json");
+  let files = {};
+  if (existsSync(directory) && readdirSync(directory).length) {
+    if (!existsSync(manifestPath) || !lstatSync(manifestPath).isFile())
+      throw new Error(`Unmanaged reference directory: ${directory}`);
+    const content = readFileSync(manifestPath, "utf8");
+    let manifest;
+    try {
+      manifest = JSON.parse(content);
+    } catch {
+      throw new Error(`Invalid reference manifest: ${manifestPath}; reconcile it first`);
+    }
+    if (
+      manifest?.format !== 1 ||
+      !manifest.files ||
+      typeof manifest.files !== "object" ||
+      Array.isArray(manifest.files)
+    )
+      throw new Error(`Invalid reference manifest: ${manifestPath}`);
+    files = manifest.files;
+    for (const [name, sha] of Object.entries(files)) {
+      if (!safeName(name) || typeof sha !== "string" || !/^[a-f0-9]{64}$/.test(sha))
+        throw new Error(`Invalid reference manifest: ${manifestPath}`);
+      const path = join(directory, name);
+      if (!existsSync(path) || !lstatSync(path).isFile() || hash(readFileSync(path)) !== sha)
+        throw new Error(`Modified or missing reference; reconcile it first: ${path}`);
+    }
+    for (const name of readdirSync(directory)) {
+      const path = join(directory, name);
+      if (
+        lstatSync(path).isSymbolicLink() ||
+        (name !== "manifest.json" && !Object.hasOwn(files, name))
+      )
+        throw new Error(`Unrecognized reference file; reconcile it first: ${path}`);
+    }
+  }
+  const writes = [];
+  for (const [name, text] of references) {
+    if (!safeName(name) || typeof text !== "string") throw new Error("Invalid reference output");
+    if (files[name] !== hash(text)) writes.push({ path: join(directory, name), text });
+    files[name] = hash(text);
+  }
+  const text = JSON.stringify({ format: 1, files }, null, 2) + "\n";
+  if (!existsSync(manifestPath) || readFileSync(manifestPath, "utf8") !== text)
+    writes.push({ path: manifestPath, text });
+  return writes;
+}
+
+export function writeReferenceOutput(writes) {
+  for (const { path, text } of writes) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  }
+}