@bompus/house-rules 0.0.0-stage → 0.13.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,188 @@
+# Third-party notices
+
+Some files in this repository copy or adapt work published under the MIT
+License. Each source's copyright notice and the licence text follow.
+`CODE_OF_CONDUCT.md` is the Contributor Covenant, under CC BY 4.0, noted at
+the end.
+
+## Cursor workflow ideas
+
+Source: https://cursor.com/docs/skills
+
+- `skills/hr-split-to-prs/`: independently written workflow informed by the
+  purpose of Cursor's built-in `split-to-prs` skill.
+- `skills/hr-pr-followup/`: independently written workflow informed by the
+  purpose of Cursor's built-in `autopilot` skill.
+
+These bundles distribute no Cursor instruction text. Their MIT licence applies
+to newly written house-rules material, not to the Cursor skills.
+
+## mattpocock/skills
+
+Source: https://github.com/mattpocock/skills (compared at revision `d81f3a1`)
+
+- `skills/hr-writing-for-agents/`: adapted from `skills/productivity/writing-for-agents/`.
+- `skills/hr-code-review/`: adapted from `skills/engineering/code-review/`.
+- `skills/hr-handoff/`: adapted from `skills/productivity/handoff/`.
+- `skills/hr-diagnosing-bugs/`: written for this repository after
+  `skills/engineering/diagnosing-bugs/`, which it shares a purpose with.
+
+- `skills/hr-tdd/`: adapted from `skills/engineering/tdd/` at revision
+  `f3fc5632f401156837ee3872f14fe33ccf1024ea`. The bundle carries its MIT notice.
+
+Copyright (c) 2026 Matt Pocock
+
+## obra/superpowers
+
+Source: https://github.com/obra/superpowers (compared at revision `8ca22db`)
+
+- `skills/hr-writing-for-agents/SKILL.md`: the instruction-form table is adapted
+  from `writing-skills`. Its wording tests found that a recipe beat a prohibition
+  for shape failures.
+- `skills/hr-test-audit/SKILL.md`: cites `writing-good-tests.md`.
+
+Copyright (c) 2025 Jesse Vincent
+
+## addyosmani/agent-skills
+
+Source: https://github.com/addyosmani/agent-skills (compared at revision `9d0c60d`)
+
+- `skills/hr-test-audit/scripts/floor-guard.ts`: adapted from
+  constraint-driven-development.
+
+Copyright (c) 2025 Addy Osmani
+
+## openclaw/openclaw
+
+Source: https://github.com/openclaw/openclaw (linked at revision `65f1e4d`, compared at `1fda703`)
+
+- `skills/hr-test-audit/SKILL.md`: the authoring gate, junk patterns, retention
+  bar and evidence fields are adapted from `.agents/skills/test-audit/`.
+
+Copyright (c) 2026 OpenClaw Foundation
+
+## no-human-ai/no_human
+
+Source: https://github.com/no-human-ai/no_human (compared at revision `9b50bf6`)
+
+- `skills/hr-test-audit/SKILL.md`: the rule that weakening a test counts as
+  removing it is adapted from its tamper guard.
+- `skills/hr-code-review/references/evidence.md`: test-weakening assessment and
+  refuting completion claims are informed by its verification approach.
+
+Copyright (c) 2026 Eyal Golan
+
+## omkamal/pypict-claude-skill
+
+Source: https://github.com/omkamal/pypict-claude-skill (compared at revision `fbda212`)
+
+- `skills/hr-test-audit/SKILL.md`: the pairwise-coverage guidance is adapted from
+  this skill.
+
+Copyright (c) 2025 pypict-claude-skill contributors
+
+## sickn33/antigravity-awesome-skills
+
+Source: https://github.com/sickn33/antigravity-awesome-skills (compared at revision `7bb0ab4`)
+
+- `skills/hr-writing-pr/SKILL.md`: selected ideas from
+  `skills/git-pr-workflows-pr-enhance/`. Selected ideas also come from
+  [Luke Parker's writing-pr post](https://x.com/LukeParkerDev/status/2096769160021979571).
+
+Copyright (c) 2026 Antigravity User
+
+## cursor/plugins (pstack)
+
+Source: https://github.com/cursor/plugins (compared at revision `e43c7ee`)
+
+- `rules/core.md`: the § Implementation economy bullet on scripting changes
+  that span more than three places is adapted from
+  `pstack/skills/principle-build-the-lever/`.
+- `skills/hr-diagnosing-bugs/SKILL.md`: § Question the premise is adapted from
+  `pstack/skills/principle-attack-the-premise/`.
+- `skills/hr-benchmarking/SKILL.md`: the validity checks are adapted from
+  `pstack/skills/benchmark-checklist/`.
+
+Copyright (c) 2026 Lauren Tan
+
+## 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-accessibility/` and `skills/hr-better-layout/`: mobile behavior and
+  viewport guidance adapted from `skills/mobile-native/SKILL.md`.
+- `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
+
+## humanlayer/skills
+
+Source: https://github.com/humanlayer/skills (compared at revision `bba9d13ab34f0a87f1cc33df4dd196372393ddfc`)
+
+- `skills/hr-explain-code/SKILL.md` and `skills/hr-writing-pr/SKILL.md`: compact
+  visual explanation and focused structural-diff guidance adapted from
+  `plugins/show-me/skills/show-me/SKILL.md`.
+
+Copyright (c) 2026 HumanLayer
+
+## Jeanno/jeanno-skills (ideas)
+
+Source: https://github.com/Jeanno/jeanno-skills (compared at revision `db4e8fd66197ece38d622ca8b527dbe821843df2`)
+
+- `skills/hr-manual-qa/SKILL.md`: independently written instructions informed by
+  the reproducible-checklist idea in `skills/qa-checklist/SKILL.md`.
+- `rules/core.md`: independently written correction handling informed by the
+  dependent-work sweep in `skills/realign/SKILL.md`.
+
+No source text from this repository is copied here.
+
+## ayghri/i-have-adhd (ideas)
+
+Source: https://github.com/ayghri/i-have-adhd (compared at revision `723af7d9afaf43eb871dbcce6129e2bf80de90d5`)
+
+- `rules/core.md`: independently written guidance informed by the small visible
+  list idea in `skills/i-have-adhd/SKILL.md`.
+- `skills/hr-plain-prose/SKILL.md`: independently written reply check informed
+  by the first-and-last-line check in that skill.
+
+No source text from this repository is copied here.
+
+## MIT License text
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributor Covenant
+
+Source: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+
+- `CODE_OF_CONDUCT.md`: version 2.1, with this repository's reporting method
+  filled in. Licensed under
+  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); its own
+  Attribution section credits the source.

package/compose.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Composes rules and skills into explicit output paths; config commands manage selections.
+//   node compose.mjs --config <path> [--out <file>] [--skills-out <dir>]
+//   node compose.mjs config help
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { composeConfiguration, configurationPath, modifierList } from "./composition.mjs";
+import { configCommand } from "./config.mjs";
+import { setupCommand } from "./setup.mjs";
+import { checkOutputPath, planReferenceOutput, writeReferenceOutput } from "./rule-references.mjs";
+export {
+  compose,
+  composeConfiguration,
+  configurationPath,
+  loadFragments,
+  modifierList,
+  parseFragment,
+  skillSources,
+  splitSections,
+} from "./composition.mjs";
+const BASE = dirname(fileURLToPath(import.meta.url));
+const NOTICES = ["LICENSE", "THIRD_PARTY_NOTICES.md"];
+
+function main(argv) {
+  if (argv[0] === "setup") return setupCommand(argv.slice(1));
+  if (argv[0] === "config") {
+    return configCommand(argv.slice(1));
+  }
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      config: { type: "string" },
+      out: { type: "string" },
+      "skills-out": { type: "string" },
+      "references-out": { type: "string" },
+      list: { type: "boolean" },
+    },
+  });
+  if (values.list) {
+    for (const m of modifierList()) console.log(`${m.name}: ${m.description ?? ""}`);
+    return;
+  }
+  const configPath = configurationPath(values.config);
+  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
+    ? resolve(explicitReferences ?? join(dirname(resolve(out)), "house-rules-references"))
+    : null;
+  const { fragments, rules, skills, warnings, references } = composeConfiguration(
+    config,
+    dirname(configPath),
+    referencesOut
+      ? { referencesDirectory: relative(dirname(resolve(out)), referencesOut) || "." }
+      : {},
+  );
+  for (const warning of warnings) console.error(`warning: ${warning}`);
+  const paths = [
+    out && { path: resolve(out), directory: false },
+    skillsOut && { path: resolve(skillsOut), directory: true },
+    referencesOut && { path: referencesOut, directory: true },
+  ].filter(Boolean);
+  for (const { path, directory } of paths) checkOutputPath(path, directory);
+  for (const a of paths)
+    for (const b of paths) {
+      if (a === b) continue;
+      const rel = relative(a.path, b.path);
+      if (
+        !rel ||
+        (rel !== ".." &&
+          !rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+          !isAbsolute(rel))
+      )
+        throw new Error("Output paths must not overlap");
+    }
+  // Composition errors and a non-empty --skills-out stop the run before anything is written.
+  if (skillsOut && existsSync(skillsOut) && readdirSync(skillsOut).length)
+    throw new Error(`--skills-out ${skillsOut} must be empty or absent`);
+  const referenceWrites = references.size ? planReferenceOutput(referencesOut, references) : [];
+  writeReferenceOutput(referenceWrites);
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true });
+    writeFileSync(out, rules);
+  } else process.stdout.write(rules);
+  if (skillsOut) {
+    // Skill tests stay in the source checkout; hosts get only what the skill uses.
+    for (const [name, from] of skills)
+      cpSync(from, join(skillsOut, name), {
+        recursive: true,
+        filter: (src) => src !== join(from, "test"),
+      });
+    for (const f of NOTICES) cpSync(join(BASE, f), join(skillsOut, f));
+  }
+  console.error(
+    `composed ${rules.split("\n").length} lines of rules from ${fragments.length} optional or personal rule file(s)${skillsOut ? ` and ${skills.size} skill(s)` : ""}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  try {
+    await main(process.argv.slice(2));
+  } catch (e) {
+    console.error(`house-rules: ${e.message}`);
+    process.exit(e.exitCode ?? 1);
+  }
+}

package/composition.mjs

@@ -0,0 +1,361 @@
+// Composition and source discovery shared by output generation and configuration management.
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BASE = dirname(fileURLToPath(import.meta.url));
+const PROTECTED = "End of every reply";
+// The protected section points at § Offers, so Offers may be replaced but not removed.
+const REQUIRED = [PROTECTED, "Offers"];
+const OPS = ["replaces", "after", "before", "removes"];
+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);
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+  const meta = {};
+  if (m) {
+    for (const line of m[1].split("\n")) {
+      const i = line.indexOf(":");
+      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 };
+}
+
+// Splits on level-2 headings outside fenced code blocks; level-3 and deeper stay inside their section.
+export function splitSections(rawText) {
+  const parts = [[]];
+  let fence = null;
+  for (const line of normalize(rawText).split("\n")) {
+    const f = /^(`{3,}|~{3,})/.exec(line);
+    if (f && (!fence || f[1][0] === fence[0])) fence = fence ? null : f[1];
+    if (!fence && line.startsWith("## ")) parts.push([]);
+    parts.at(-1).push(line);
+  }
+  const preamble = parts.shift().join("\n").trim();
+  const sections = parts.map((lines) => ({
+    heading: lines[0].slice(3).trim(),
+    text: lines.join("\n").trim(),
+  }));
+  return { preamble, sections };
+}
+
+function composeParts(coreText, fragments, referencesDirectory, candidates) {
+  const core = parseFragment(coreText, "core");
+  if ("reference" in core.meta && "references" in core.meta)
+    throw new Error("core: use reference or references, not both");
+  const paths =
+    "references" in core.meta
+      ? core.meta.references.split(",").map((path) => path.trim())
+      : "reference" in core.meta
+        ? [core.meta.reference]
+        : [];
+  if (paths.some((path) => !path) || new Set(paths).size !== paths.length)
+    throw new Error("core: references must contain distinct non-empty paths");
+  const outputs = new Map();
+  if (paths.length) {
+    core.path = join(BASE, "rules/core.md");
+    core.root = BASE;
+    for (const path of paths) {
+      const output = renderReference(core, referencesDirectory, true, path);
+      if (outputs.has(output.heading))
+        throw new Error(`core: duplicate reference section "${output.heading}"`);
+      outputs.set(output.heading, output);
+    }
+    coreText = core.body;
+  }
+  const { preamble, sections } = splitSections(coreText);
+  if (referencesDirectory !== undefined)
+    for (const section of sections) section.referenceOutput = outputs.get(section.heading);
+  const find = (heading, f) => {
+    const i = sections.findIndex((s) => s.heading === heading);
+    if (i < 0) throw new Error(`${f.source}: no section "${heading}" to target`);
+    return i;
+  };
+  for (const f of fragments) {
+    const unknown = Object.keys(f.meta).filter((k) => !KEYS.includes(k));
+    if (unknown.length)
+      throw new Error(
+        `${f.source}: unknown frontmatter key "${unknown[0]}" (use ${KEYS.join(", ")})`,
+      );
+    const ops = OPS.filter((k) => k in f.meta);
+    if (ops.length > 1) throw new Error(`${f.source}: use one of ${OPS.join(", ")}`);
+    const op = ops[0];
+    const target = op && f.meta[op];
+    if (op && !target) throw new Error(`${f.source}: ${op}: needs a section heading`);
+    if (target === PROTECTED && op !== "after")
+      throw new Error(
+        `${f.source}: "${PROTECTED}" stays first and can only be added to with after:`,
+      );
+    if (op === "removes") {
+      if (REQUIRED.includes(target))
+        throw new Error(`${f.source}: "${target}" can be replaced, not removed`);
+      if (f.body) throw new Error(`${f.source}: a removes: fragment has no body`);
+      sections.splice(find(target, f), 1);
+      continue;
+    }
+    const { preamble: stray, sections: added } = splitSections(f.body);
+    for (const section of added) section.referenceOutput = f.referenceOutput;
+    if (!added.length || stray)
+      throw new Error(`${f.source}: body must start with a "## " heading`);
+    if (op === "replaces") {
+      // A replacement keeps the `after:` tag of the section it replaces, so later `after:` fragments still queue behind it.
+      const i = find(target, f);
+      sections.splice(i, 1, ...added.map((s) => ({ ...s, after: sections[i].after })));
+    } else if (op === "before") sections.splice(find(target, f), 0, ...added);
+    else if (op === "after") {
+      // Earlier `after:` fragments for the same target stay first, in configured order.
+      let i = find(target, f) + 1;
+      while (sections[i]?.after === target) i++;
+      sections.splice(i, 0, ...added.map((s) => ({ ...s, after: target })));
+    } else sections.push(...added);
+  }
+  const seen = new Set();
+  for (const s of sections) {
+    if (seen.has(s.heading))
+      throw new Error(`duplicate section "${s.heading}"; use replaces: to override it`);
+    seen.add(s.heading);
+    if (s.referenceOutput) {
+      const resource = s.referenceOutput;
+      const previous = candidates.get(resource.name);
+      if (previous && previous.text !== resource.text)
+        throw new Error(`conflicting reference "${resource.name}"`);
+      candidates.set(resource.name, resource);
+    }
+  }
+  if (sections[0]?.heading !== PROTECTED)
+    throw new Error(`"${PROTECTED}" must stay the first section`);
+  for (const h of REQUIRED)
+    if (!seen.has(h))
+      throw new Error(`a "${h}" section is required; a replacement must keep that heading`);
+  return [preamble, ...sections.map((s) => s.text)].filter(Boolean).join("\n\n") + "\n";
+}
+
+export function compose(coreText, fragments) {
+  const inline = fragments.map((fragment) => {
+    if (!("reference" in fragment.meta) || !fragment.body.includes(`](${fragment.meta.reference})`))
+      return fragment;
+    const f = { ...fragment };
+    if (!f.path) {
+      const name =
+        typeof f.source === "string" ? f.source.replace(/^modifier /, "").replace(/\.md$/, "") : "";
+      const path = join(BASE, "rules/modifiers", `${name}.md`);
+      if (
+        !/^[a-z0-9-]+$/.test(name) ||
+        !existsSync(path) ||
+        parseFragment(readFileSync(path, "utf8"), name).body !== f.body
+      )
+        throw new Error(`${f.source}: use loadFragments to establish the reference source layer`);
+      f.path = path;
+      f.root = BASE;
+    }
+    renderReference(f, undefined);
+    return f;
+  });
+  return composeParts(coreText, inline, undefined, new Map());
+}
+
+const mdFiles = (dir) =>
+  existsSync(dir)
+    ? readdirSync(dir)
+        .filter((f) => f.endsWith(".md"))
+        .sort()
+    : [];
+
+export function modifierList() {
+  const dir = join(BASE, "rules/modifiers");
+  return mdFiles(dir).map((f) => ({
+    name: f.slice(0, -3),
+    ...parseFragment(readFileSync(join(dir, f), "utf8"), f).meta,
+  }));
+}
+
+// The directory holding house-rules.json is the user's layer unless the config lists others.
+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}"; 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)) {
+    const dir = join(resolve(configDir, layer), "rules");
+    for (const f of mdFiles(dir))
+      fragments.push({
+        ...parseFragment(readFileSync(join(dir, f), "utf8"), join(dir, f)),
+        path: join(dir, f),
+        root: resolve(configDir, layer),
+      });
+  }
+  return fragments;
+}
+
+// Later layers' skills shadow base skills of the same name.
+export function skillSources(config, configDir) {
+  const base = join(BASE, "skills");
+  const shipped = new Set(
+    readdirSync(base).filter((name) => existsSync(join(base, name, "SKILL.md"))),
+  );
+  const legacyNames = new Map(
+    [...shipped].filter((name) => name.startsWith("hr-")).map((name) => [name.slice(3), name]),
+  );
+  const exclude = new Set(config.skills?.exclude ?? []);
+  const independent = new Set(config.skills?.independent ?? []);
+  const included = config.skills?.include;
+  if (included !== undefined) {
+    if (
+      !Array.isArray(included) ||
+      included.some((name) => typeof name !== "string" || !name.trim())
+    )
+      throw new Error("skills.include must be an array of non-empty strings");
+    if (new Set(included).size !== included.length)
+      throw new Error("skills.include contains duplicates");
+    for (const name of included) {
+      if (!shipped.has(name))
+        throw new Error(`unknown shipped skill "${name}" in skills.include (see config catalog)`);
+    }
+  }
+  for (const name of exclude) {
+    if (legacyNames.has(name) && !independent.has(name))
+      throw new Error(
+        `legacy skill name "${name}" in skills.exclude; replace it with "${legacyNames.get(name)}"`,
+      );
+  }
+  const sources = new Map();
+  for (const root of [
+    base,
+    ...layersOf(config).map((l) => join(resolve(configDir, l), "skills")),
+  ]) {
+    if (!existsSync(root)) continue;
+    for (const name of readdirSync(root)) {
+      if (!existsSync(join(root, name, "SKILL.md"))) continue;
+      if (legacyNames.has(name) && !independent.has(name))
+        throw new Error(
+          `legacy skill name "${name}" in a personal layer; rename its directory and frontmatter name to "${legacyNames.get(name)}", or list "${name}" in skills.independent to keep it as an independent skill`,
+        );
+      if (root !== base && legacyNames.get(name.slice(3)) === name) {
+        const declaredName = parseFragment(readFileSync(join(root, name, "SKILL.md"), "utf8"), name)
+          .meta.name?.replace(/\s+#.*$/, "")
+          .replace(/^(['"])(.*)\1$/, "$2");
+        if (legacyNames.has(declaredName))
+          throw new Error(
+            `legacy skill name "${declaredName}" in frontmatter; set name to "${name}" to match its renamed override directory`,
+          );
+      }
+      if (
+        !exclude.has(name) &&
+        (root !== base || included === undefined || included.includes(name))
+      )
+        sources.set(name, join(root, name));
+    }
+  }
+  return sources;
+}
+
+export function configurationPath(path) {
+  return resolve(
+    path ??
+      join(
+        process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
+        "house-rules/house-rules.json",
+      ),
+  );
+}
+
+function renderReference(f, referencesDirectory, core = false, reference = f.meta.reference) {
+  const invalidReference = `${f.source}: reference must be a regular file within its source layer`;
+  const path = resolve(dirname(f.path), reference);
+  if (!reference || !existsSync(path) || !lstatSync(path).isFile())
+    throw new Error(invalidReference);
+  const inside = relative(realpathSync(f.root), realpathSync(path));
+  if (inside.startsWith("..") || isAbsolute(inside)) throw new Error(invalidReference);
+  const name = basename(path);
+  if (!/^[a-z0-9][a-z0-9-]*\.md$/.test(name))
+    throw new Error(`${f.source}: invalid reference filename`);
+  const text = readFileSync(path, "utf8");
+  const original = splitSections(text);
+  const parts = splitSections(f.body);
+  const section = core
+    ? parts.sections.find((s) => s.heading === original.sections[0]?.heading)
+    : null;
+  const short = core ? splitSections(section?.text ?? "") : parts;
+  if (
+    original.preamble ||
+    short.preamble ||
+    original.sections.length !== 1 ||
+    short.sections.length !== 1 ||
+    original.sections[0].heading !== short.sections[0].heading
+  )
+    throw new Error(`${f.source}: reference must contain the same single section heading`);
+  const sourceLink = `](${reference})`;
+  if (!(core ? section.text : f.body).includes(sourceLink))
+    throw new Error(`${f.source}: reference link missing from body`);
+  if (referencesDirectory === undefined) {
+    f.body = core ? f.body.replace(section.text, text.trim()) : text.trim();
+  } else {
+    const href = encodeURI(
+      `${referencesDirectory.replace(/\\/g, "/").replace(/\/$/, "")}/${name}`,
+    ).replace(/[()#?]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+    f.body = f.body.replaceAll(sourceLink, `](${href})`);
+    if (!core) f.referenceOutput = { name, text, heading: original.sections[0].heading };
+  }
+  return { name, text, heading: original.sections[0].heading };
+}
+
+function referenceFragments(config, configDir, referencesDirectory) {
+  if (
+    referencesDirectory !== undefined &&
+    (typeof referencesDirectory !== "string" || !referencesDirectory.trim())
+  )
+    throw new Error("referencesDirectory must be a non-empty string");
+  const fragments = loadRawFragments(config, configDir);
+  const candidates = new Map();
+  for (const f of fragments) {
+    if (!("reference" in f.meta)) continue;
+    renderReference(f, referencesDirectory);
+  }
+  return { fragments, candidates };
+}
+
+// Existing low-level callers receive complete inline procedure bodies too.
+export function loadFragments(config, configDir) {
+  return referenceFragments(config, configDir).fragments;
+}
+
+export function composeConfiguration(config, configDir, { referencesDirectory } = {}) {
+  const { fragments, candidates } = referenceFragments(config, configDir, referencesDirectory);
+  const rules = composeParts(
+    readFileSync(join(BASE, "rules/core.md"), "utf8"),
+    fragments,
+    referencesDirectory,
+    candidates,
+  );
+  const references = new Map([...candidates].map(([name, value]) => [name, value.text]));
+  const skills = skillSources(config, configDir);
+  const warnings = [];
+  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())
+      .filter(Boolean)) {
+      if (!skills.has(need))
+        warnings.push(`${f.source} expects the "${need}" skill, which is not in the composed set`);
+    }
+  }
+  return { fragments, rules, skills, warnings, references };
+}