@lovrozagar/grunt 0.9.4 → 0.9.5

package/.rulesync/reference/INDEX.md

@@ -10,7 +10,7 @@ Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp
 
 Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
 
-Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay.
+Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay. Extra `##` headings in shared reference docs (e.g. `law.md`) are kept. `grunt:*` package scripts that differ from a known grunt default stay; `grunt:test:e2e` is added only when a vitest e2e config exists. Check steps omitted from dest `scripts/pipeline.mjs` seed `.rulesync/grunt.pipeline.jsonc`. doctor/listen/speak call `scripts/lib/env.mjs` `loadEnv` when that file exists.
 
 # Skills
 

package/.rulesync/reference/law.md

@@ -8,4 +8,4 @@ Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp
 
 Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
 
-Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay.
+Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay. Extra `##` headings in shared reference docs (e.g. `law.md`) are kept. `grunt:*` package scripts that differ from a known grunt default stay; `grunt:test:e2e` is added only when a vitest e2e config exists. Check steps omitted from dest `scripts/pipeline.mjs` seed `.rulesync/grunt.pipeline.jsonc`. doctor/listen/speak call `scripts/lib/env.mjs` `loadEnv` when that file exists.

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- `grunt upgrade` keeps extra `##` sections in shared reference docs such as `law.md`, so consumer INDEX content survives the copy
+- Custom `grunt:*` package scripts that are not a known grunt default stay; `grunt:test:e2e` is added only when a vitest e2e config exists
+- Check steps a consumer omitted from `scripts/pipeline.mjs` seed `.rulesync/grunt.pipeline.jsonc` and are skipped; a failed `grunt:rulesync:check` lists every failing step and points at that overlay
+- doctor, listen, and speak call `scripts/lib/env.mjs` `loadEnv` when that file exists, so consumers do not need to patch those scripts
+- `scripts/session-map.mjs` no longer trips ESLint `no-regex-spaces`
+
 ## [0.9.1] - 2026-10-04
 
 ### Fixed

package/cli/init.mjs

@@ -15,7 +15,13 @@ import {
   snapshotGuardedRoots,
   remergeGuardedRoots,
   withGuardedCheckInteriors,
+  mergeReferenceMarkdown,
 } from "../scripts/guarded-md.mjs"
+import {
+  COMMANDS as PIPELINE_COMMANDS,
+  PIPELINE_CONFIG_REL,
+  inferPipelineSkip,
+} from "../scripts/pipeline.mjs"
 import {
   PACKAGE_MANAGERS,
   UNKNOWN_PACKAGE_MANAGER,
@@ -41,6 +47,8 @@ export {
   remergeGuardedRoots,
   healGuardedRootFile,
   withGuardedCheckInteriors,
+  extraH2Sections,
+  mergeReferenceMarkdown,
 } from "../scripts/guarded-md.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
@@ -147,6 +155,23 @@ export const LAUNCH_SCRIPTS = {
   gemini: "gemini --yolo",
   grok: "grok --yolo",
 }
+/** Exact prior grunt defaults. A dest script equal to one of these migrates to the current value. */
+export const HISTORICAL_SCRIPT_DEFAULTS = {
+  antigravity: ["antigravity"],
+  claude: ["claude"],
+  codex: ["codex"],
+  gemini: ["gemini"],
+  grok: ["grok"],
+}
+export const E2E_VITEST_CONFIGS = [
+  "vitest.e2e.config.ts",
+  "vitest.e2e.config.mts",
+  "vitest.e2e.config.js",
+  "vitest.e2e.config.mjs",
+  "vitest.e2e.config.cjs",
+]
+export const REFERENCE_REL = ".rulesync/reference"
+export { PIPELINE_CONFIG_REL }
 const OWNED_HOOK_FILES = [
   "scrub-spawn-prompt.mjs",
   "gate-fat-tools.mjs",
@@ -333,11 +358,61 @@ function extraOwnedSuffix(cur, newSrc) {
   return null
 }
 
-function mergeScriptValue(newSrc, cur) {
+function mergeScriptValue(newSrc, cur, historical = []) {
   if (cur.startsWith(newSrc)) return cur
   const suffix = extraOwnedSuffix(cur, newSrc)
   if (suffix != null) return newSrc + suffix
-  return newSrc
+  if (historical.includes(cur)) return newSrc
+  if (looksGruntOwnedPrefix(cur)) return newSrc
+  return cur
+}
+
+function historicalFor(key) {
+  return HISTORICAL_SCRIPT_DEFAULTS[key] || []
+}
+
+function hasE2eConfig(dest) {
+  return E2E_VITEST_CONFIGS.some((name) => fs.existsSync(path.join(dest, name)))
+}
+
+export function snapshotReferenceDocs(dest) {
+  const dir = path.join(dest, REFERENCE_REL)
+  const snap = {}
+  if (!fs.existsSync(dir)) return snap
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".md") || GENERATED_MAP_FILES.has(name)) continue
+    const abs = path.join(dir, name)
+    if (!fs.statSync(abs).isFile()) continue
+    snap[name] = fs.readFileSync(abs, "utf8")
+  }
+  return snap
+}
+
+export function remergeReferenceDocs(dest, snap, pkgRoot) {
+  const pkgDir = path.join(pkgRoot, REFERENCE_REL)
+  const destDir = path.join(dest, REFERENCE_REL)
+  for (const [name, existing] of Object.entries(snap)) {
+    const pkgFile = path.join(pkgDir, name)
+    if (!fs.existsSync(pkgFile)) continue
+    const incoming = fs.readFileSync(pkgFile, "utf8")
+    fs.mkdirSync(destDir, { recursive: true })
+    fs.writeFileSync(path.join(destDir, name), mergeReferenceMarkdown(existing, incoming))
+  }
+}
+
+export function seedPipelineConfig(dest, destPipelineSrc) {
+  if (!destPipelineSrc || !/export const COMMANDS/.test(destPipelineSrc)) return false
+  const abs = path.join(dest, PIPELINE_CONFIG_REL)
+  if (fs.existsSync(abs)) return false
+  const overlay = {}
+  for (const mode of Object.keys(PIPELINE_COMMANDS)) {
+    const skip = inferPipelineSkip(destPipelineSrc, mode)
+    if (skip.length) overlay[mode] = { skip }
+  }
+  if (!Object.keys(overlay).length) return false
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  fs.writeFileSync(abs, `${JSON.stringify(overlay, null, 2)}\n`)
+  return true
 }
 
 function rewritePackageManagerRunRefs(scripts, srcKeys) {
@@ -394,17 +469,19 @@ export function mergePackageJson(dest, pkgRoot) {
   const srcKeys = []
   for (const [k, v] of Object.entries(srcPkg.scripts || {})) {
     if (k === "test" || k.endsWith(":raw") || k in LAUNCH_SCRIPTS) continue
-    srcKeys.push(k)
     const destKey = toGruntScriptName(k)
     const current = destPkg.scripts[destKey]
     const legacy = destPkg.scripts[k]
+    if (k === "test:e2e" && current == null && legacy == null && !hasE2eConfig(dest)) continue
+    srcKeys.push(k)
+    const historical = historicalFor(k)
     const ownedLegacy =
       legacy != null &&
       (legacy.startsWith(v) || extraOwnedSuffix(legacy, v) != null || looksGruntOwnedPrefix(legacy))
     if (current != null) {
-      destPkg.scripts[destKey] = mergeScriptValue(v, current)
+      destPkg.scripts[destKey] = mergeScriptValue(v, current, historical)
     } else if (ownedLegacy) {
-      destPkg.scripts[destKey] = mergeScriptValue(v, legacy)
+      destPkg.scripts[destKey] = mergeScriptValue(v, legacy, historical)
     } else {
       destPkg.scripts[destKey] = v
     }
@@ -419,7 +496,7 @@ export function mergePackageJson(dest, pkgRoot) {
   for (const [k, v] of Object.entries(LAUNCH_SCRIPTS)) {
     const destKey = toGruntScriptName(k)
     const current = destPkg.scripts[destKey]
-    destPkg.scripts[destKey] = current != null ? mergeScriptValue(v, current) : v
+    destPkg.scripts[destKey] = current != null ? mergeScriptValue(v, current, historicalFor(k)) : v
     const staleKey = `grunt:yolo:${k}`
     if (destPkg.scripts[staleKey] === v) delete destPkg.scripts[staleKey]
   }
@@ -507,6 +584,13 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
       }
     }
 
+    const refSnap = self ? {} : snapshotReferenceDocs(dest)
+    let destPipelineSrc = ""
+    if (!self) {
+      const destPipeline = path.join(dest, "scripts", "pipeline.mjs")
+      if (fs.existsSync(destPipeline)) destPipelineSrc = fs.readFileSync(destPipeline, "utf8")
+    }
+
     for (const dir of COPY_DIRS) {
       const src = path.join(pkgRoot, dir)
       const d = path.join(dest, dir)
@@ -540,6 +624,8 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
     mergeGitignore(dest)
 
     if (!self) {
+      remergeReferenceDocs(dest, refSnap, pkgRoot)
+      seedPipelineConfig(dest, destPipelineSrc)
       mergePackageJson(dest, pkgRoot)
       copyRootIfMissing(dest, pkgRoot)
       emitDestMaps(dest)

package/cli/init.test.ts

@@ -37,6 +37,14 @@ import {
   RETIRED_PATHS,
   RESERVED_SKILLS,
   LAUNCH_SCRIPTS,
+  HISTORICAL_SCRIPT_DEFAULTS,
+  E2E_VITEST_CONFIGS,
+  extraH2Sections,
+  mergeReferenceMarkdown,
+  snapshotReferenceDocs,
+  remergeReferenceDocs,
+  seedPipelineConfig,
+  PIPELINE_CONFIG_REL,
   mergeClaudeSettings,
   mergeGitignore,
   mergeGuardedContent,
@@ -55,6 +63,7 @@ import {
 } from "./init.mjs";
 import { UNKNOWN_PACKAGE_MANAGER } from "../scripts/package-manager.mjs";
 import { runGuardedRoots } from "../scripts/guarded-roots.mjs";
+import { COMMANDS as PIPELINE_COMMANDS } from "../scripts/pipeline.mjs";
 
 const tmpDirs: string[] = [];
 afterEach(() => {
@@ -1714,6 +1723,158 @@ describe("mergePackageJson", () => {
       expect(pkg.scripts[k]).toBe(v);
     }
   });
+
+  it("keeps customized grunt launchers that are not a known default", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-keep-custom-launch-");
+    const wrapped = {
+      "grunt:antigravity": "node scripts/with-env.mjs agy --dangerously-skip-permissions",
+      "grunt:claude": "node scripts/with-env.mjs claude --dangerously-skip-permissions",
+      "grunt:codex": "node scripts/with-env.mjs codex --dangerously-bypass-approvals-and-sandbox",
+      "grunt:gemini": "node scripts/with-env.mjs gemini --yolo",
+      "grunt:grok": "node scripts/with-env.mjs grok --yolo",
+    };
+    fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ scripts: wrapped }));
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:antigravity"]).toBe(wrapped["grunt:antigravity"]);
+    expect(out.scripts["grunt:claude"]).toBe(wrapped["grunt:claude"]);
+    expect(out.scripts["grunt:codex"]).toBe(wrapped["grunt:codex"]);
+    expect(out.scripts["grunt:gemini"]).toBe(wrapped["grunt:gemini"]);
+    expect(out.scripts["grunt:grok"]).toBe(wrapped["grunt:grok"]);
+  });
+
+  it("migrates a historical bare launcher to the current default", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-hist-launch-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { "grunt:antigravity": "antigravity" } }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:antigravity"]).toBe(LAUNCH_SCRIPTS.antigravity);
+    expect(HISTORICAL_SCRIPT_DEFAULTS.antigravity).toContain("antigravity");
+  });
+
+  it("does not add grunt:test:e2e when dest has no e2e vitest config", () => {
+    const dest = tmp("pj-noe2e-");
+    fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ name: "app", scripts: {} }));
+    mergePackageJson(dest, PKG_ROOT);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:test:e2e"]).toBeUndefined();
+    expect(out.scripts["grunt:rulesync:check"]).toBe("node ./scripts/guarded-roots.mjs check");
+  });
+
+  it("adds grunt:test:e2e when dest has a vitest e2e config", () => {
+    const dest = tmp("pj-e2e-");
+    fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ name: "app", scripts: {} }));
+    fs.writeFileSync(path.join(dest, E2E_VITEST_CONFIGS[0]), "export default {}\n");
+    mergePackageJson(dest, PKG_ROOT);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:test:e2e"]).toBe("vitest run -c vitest.e2e.config.ts");
+  });
+
+  it("keeps an existing grunt:test:e2e even without an e2e config", () => {
+    const dest = tmp("pj-e2e-keep-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { "grunt:test:e2e": "node scripts/e2e.mjs" } }),
+    );
+    mergePackageJson(dest, PKG_ROOT);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["grunt:test:e2e"]).toBe("node scripts/e2e.mjs");
+  });
+});
+
+describe("reference markdown merge", () => {
+  it("extraH2Sections keeps titles incoming does not have, including CRLF", () => {
+    const existing = "# Law\r\n\r\n## Skills naming\r\n\r\nstock\r\n\r\n## Autorun\r\n\r\ngo-live\r\n";
+    const incoming = "# Law\n\n## Skills naming\n\nstock plus su\n";
+    expect(extraH2Sections(existing, incoming)).toBe("## Autorun\n\ngo-live");
+    expect(extraH2Sections("# Law\n\nno headings\n", incoming)).toBe("");
+    expect(extraH2Sections("## \nempty title\n## Autorun\nkeep\n", incoming)).toBe("## Autorun\nkeep");
+  });
+
+  it("mergeReferenceMarkdown appends extras and normalizes a trailing newline", () => {
+    const incoming = "# Law\n\n## Skills naming\n\nstock";
+    expect(mergeReferenceMarkdown("", incoming)).toBe("# Law\n\n## Skills naming\n\nstock\n");
+    expect(mergeReferenceMarkdown("# Law\n\n## Skills naming\n\nstock\n\n## Autorun\n\nX\n", incoming)).toBe(
+      "# Law\n\n## Skills naming\n\nstock\n\n## Autorun\n\nX\n",
+    );
+  });
+
+  it("snapshotReferenceDocs skips generated maps, non-md, and directories", () => {
+    const dest = tmp("ref-snap-");
+    expect(snapshotReferenceDocs(dest)).toEqual({});
+    const dir = path.join(dest, ".rulesync", "reference");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "law.md"), "# Law\n");
+    fs.writeFileSync(path.join(dir, "INDEX.md"), "generated\n");
+    fs.writeFileSync(path.join(dir, "notes.txt"), "nope\n");
+    fs.mkdirSync(path.join(dir, "nested.md"));
+    expect(snapshotReferenceDocs(dest)).toEqual({ "law.md": "# Law\n" });
+  });
+
+  it("remergeReferenceDocs writes extras for packaged refs and leaves consumer-only files", () => {
+    const pkgRoot = stubPkgRoot();
+    const pkgRef = path.join(pkgRoot, ".rulesync", "reference");
+    fs.mkdirSync(pkgRef, { recursive: true });
+    fs.writeFileSync(path.join(pkgRef, "law.md"), "# Law\n\n## Skills naming\n\nstock\n");
+    const dest = tmp("ref-remerge-");
+    const destRef = path.join(dest, ".rulesync", "reference");
+    fs.mkdirSync(destRef, { recursive: true });
+    fs.writeFileSync(
+      path.join(destRef, "law.md"),
+      "# Law\n\n## Skills naming\n\nold\n\n## Autorun\n\nkeep\n",
+    );
+    fs.writeFileSync(path.join(destRef, "stripe.md"), "# Stripe\n");
+    remergeReferenceDocs(
+      dest,
+      {
+        "law.md": fs.readFileSync(path.join(destRef, "law.md"), "utf8"),
+        "stripe.md": "# Stripe\n",
+      },
+      pkgRoot,
+    );
+    expect(fs.readFileSync(path.join(destRef, "law.md"), "utf8")).toBe(
+      "# Law\n\n## Skills naming\n\nstock\n\n## Autorun\n\nkeep\n",
+    );
+    expect(fs.readFileSync(path.join(destRef, "stripe.md"), "utf8")).toBe("# Stripe\n");
+  });
+});
+
+describe("pipeline seed", () => {
+  it("writes skip overlay from dest pipeline and does not overwrite an existing file", () => {
+    const dest = tmp("pipe-seed-");
+    const skipped = PIPELINE_COMMANDS.check[1];
+    const src = `export const COMMANDS = {
+  check: [
+    ${PIPELINE_COMMANDS.check.filter((c) => c !== skipped).map((c) => JSON.stringify(c)).join(",\n    ")}
+  ],
+};
+`;
+    expect(seedPipelineConfig(dest, src)).toBe(true);
+    const cfg = path.join(dest, PIPELINE_CONFIG_REL);
+    expect(JSON.parse(fs.readFileSync(cfg, "utf8"))).toEqual({ check: { skip: [skipped] } });
+    fs.writeFileSync(cfg, '{"check":{"skip":["keep"]}}\n');
+    expect(seedPipelineConfig(dest, src)).toBe(false);
+    expect(JSON.parse(fs.readFileSync(cfg, "utf8"))).toEqual({ check: { skip: ["keep"] } });
+  });
+
+  it("skips seed when dest is not a COMMANDS module or matches stock", () => {
+    const dest = tmp("pipe-seed-skip-");
+    expect(seedPipelineConfig(dest, "")).toBe(false);
+    expect(seedPipelineConfig(dest, "console.log(1)\n")).toBe(false);
+    const stock = `export const COMMANDS = {
+  generate: [${PIPELINE_COMMANDS.generate.map((c) => JSON.stringify(c)).join(", ")}],
+  check: [${PIPELINE_COMMANDS.check.map((c) => JSON.stringify(c)).join(", ")}],
+  watch: [${PIPELINE_COMMANDS.watch.map((c) => JSON.stringify(c)).join(", ")}],
+};
+`;
+    expect(seedPipelineConfig(dest, stock)).toBe(false);
+    expect(fs.existsSync(path.join(dest, PIPELINE_CONFIG_REL))).toBe(false);
+  });
 });
 
 describe("init", () => {
@@ -2220,6 +2381,43 @@ describe("init", () => {
     ).toThrow("emit-maps failed");
   });
 
+  it("keeps extra ## sections in dest law.md and INDEX", () => {
+    const dest = tmp("grunt-law-extra-");
+    fs.mkdirSync(path.join(dest, ".rulesync", "reference"), { recursive: true });
+    const pkgLaw = fs.readFileSync(path.join(PKG_ROOT, ".rulesync", "reference", "law.md"), "utf8");
+    fs.writeFileSync(
+      path.join(dest, ".rulesync", "reference", "law.md"),
+      `${pkgLaw.trimEnd()}\n\n## Autorun\n\npush → go-live/\n`,
+    );
+    init(dest, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" });
+    const law = fs.readFileSync(path.join(dest, ".rulesync", "reference", "law.md"), "utf8");
+    expect(law).toMatch(/## Skills naming/);
+    expect(law).toMatch(/## Autorun/);
+    expect(law).toMatch(/push → go-live\//);
+    const index = fs.readFileSync(path.join(dest, ".rulesync", "reference", "INDEX.md"), "utf8");
+    expect(index).toMatch(/## Autorun/);
+    expect(index).toMatch(/push → go-live\//);
+  });
+
+  it("seeds grunt.pipeline.jsonc from dest pipeline omissions during init", () => {
+    const dest = tmp("grunt-pipe-init-");
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    const skipped = PIPELINE_COMMANDS.check.find((c) => c.includes("subagents"));
+    const src = `export const COMMANDS = {
+  check: [
+    ${PIPELINE_COMMANDS.check.filter((c) => c !== skipped).map((c) => JSON.stringify(c)).join(",\n    ")}
+  ],
+};
+`;
+    fs.writeFileSync(path.join(dest, "scripts", "pipeline.mjs"), src);
+    init(dest, { execFileSync: vi.fn(), skipGlobals: true, packageManager: "npm" });
+    const cfg = JSON.parse(fs.readFileSync(path.join(dest, PIPELINE_CONFIG_REL), "utf8"));
+    expect(cfg.check.skip).toEqual([skipped]);
+    expect(fs.readFileSync(path.join(dest, "scripts", "pipeline.mjs"), "utf8")).toContain(
+      "subagents --check",
+    );
+  });
+
   it("does not stamp package INDEX over dest; re-emits union", () => {
     const dest = tmp("grunt-index-keep-");
     fs.mkdirSync(path.join(dest, ".rulesync", "reference"), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",

package/scripts/doctor.mjs

@@ -444,7 +444,17 @@ export function runDoctor({
   return { code: missingRequired.length || missingMaps.length ? 1 : 0, stdout, stderr: "" };
 }
 
-function main() {
+/** Load dest `scripts/lib/env.mjs` `loadEnv` when that file exists next to this script. */
+export async function loadOptionalConsumerEnv(baseHref = import.meta.url) {
+  const file = fileURLToPath(new URL("./lib/env.mjs", baseHref));
+  if (!fs.existsSync(file)) return false;
+  const { loadEnv } = await import(pathToFileURL(file).href);
+  if (typeof loadEnv === "function") loadEnv();
+  return true;
+}
+
+async function main() {
+  await loadOptionalConsumerEnv();
   const r = runDoctor();
   if (r.stdout) process.stdout.write(r.stdout);
   if (r.stderr) process.stderr.write(r.stderr);
@@ -454,5 +464,8 @@ function main() {
 const thisFile = fileURLToPath(import.meta.url);
 const invoked = process.argv[1] ? path.resolve(process.argv[1]) : "";
 if (invoked === thisFile || import.meta.url === pathToFileURL(invoked).href) {
-  main();
+  main().catch((err) => {
+    process.stderr.write((err && err.message ? err.message : String(err)) + "\n");
+    process.exit(1);
+  });
 }

package/scripts/guarded-md.mjs

@@ -111,6 +111,34 @@ export function mergeGuardedContent(existingText, gruntBody) {
   return composeGuardedMarkdown(gruntBody, user, nl);
 }
 
+/** `##` blocks in `existing` whose titles are not in `incoming`. */
+export function extraH2Sections(existing, incoming) {
+  const incomingTitles = new Set(
+    [...String(incoming ?? "").matchAll(/^## (.+)$/gm)].map((m) => m[1].trim()),
+  );
+  const text = String(existing ?? "").replace(/\r\n/g, "\n");
+  const matches = [...text.matchAll(/^## /gm)];
+  if (!matches.length) return "";
+  const chunks = [];
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : text.length;
+    const block = text.slice(start, end).replace(/(?:\n)+$/, "");
+    const title = block.match(/^## (.+)$/m)?.[1].trim();
+    if (title && !incomingTitles.has(title)) chunks.push(block);
+  }
+  return chunks.join("\n\n");
+}
+
+/** Grunt body plus consumer-only `##` sections. No sentinels (INDEX inlines law.md). */
+export function mergeReferenceMarkdown(existing, incoming) {
+  const src = String(incoming ?? "");
+  const extras = extraH2Sections(existing ?? "", src);
+  const base = src.replace(/(?:\r?\n)+$/, "");
+  if (!extras.trim()) return `${base}\n`;
+  return `${base}\n\n${extras.replace(/(?:\n)+$/, "")}\n`;
+}
+
 export function writeMergedGuardedFile(destPath, gruntBody) {
   if (!fs.existsSync(destPath)) {
     fs.writeFileSync(destPath, mergeGuardedContent("", gruntBody));

package/scripts/listen.mjs

@@ -5,7 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { whichBin } from "./doctor.mjs";
+import { loadOptionalConsumerEnv, whichBin } from "./doctor.mjs";
 
 export const DEFAULT_MODEL = "whisper-1";
 export const DEFAULT_GGML = "ggml-base.en.bin";
@@ -576,6 +576,7 @@ function waitPidExit(pid, killFn, timeoutMs = 8000) {
 
 export async function main(argv = process.argv.slice(2), opts = {}) {
   const { _, flags } = parseArgv(argv);
+  if (!opts.env) await loadOptionalConsumerEnv();
   const env = opts.env || process.env;
   const home = opts.home || str(env.HOME || env.USERPROFILE, os.homedir());
   const cwd = str(flags.cwd || opts.cwd, process.cwd());

package/scripts/pipeline.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 /** Inner generate/check/watch chain. Called by guarded-roots; not a public npm script. */
 import { execSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { stripJsonc } from "./jsonc.mjs";
+
+export const PIPELINE_CONFIG_REL = ".rulesync/grunt.pipeline.jsonc";
 
 export const COMMANDS = {
   generate: [
@@ -41,12 +45,90 @@ export function envWithLocalBin(cwd, env = process.env) {
   return merged;
 }
 
-export function runPipeline(mode, { cwd = process.cwd(), exec = execSync } = {}) {
-  const cmds = COMMANDS[mode];
+function asStringList(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string" && x) : [];
+}
+
+export function quotedCommandsInBlock(src, key) {
+  const m = String(src ?? "").match(new RegExp(`${key}:\\s*\\[([\\s\\S]*?)\\]`, "m"));
+  if (!m) return [];
+  const out = [];
+  for (const line of m[1].split(/\r?\n/)) {
+    const code = line.replace(/\/\/.*$/, "").trim();
+    if (!code) continue;
+    for (const x of code.matchAll(/"((?:\\.|[^"\\])*)"/g)) {
+      out.push(x[1].replace(/\\"/g, '"'));
+    }
+  }
+  return out;
+}
+
+export function inferPipelineSkip(src, mode) {
+  const stock = COMMANDS[mode];
+  if (!stock || !src || !new RegExp(`${mode}:\\s*\\[`).test(src)) return [];
+  const active = new Set(quotedCommandsInBlock(src, mode));
+  return stock.filter((c) => !active.has(c));
+}
+
+export function loadPipelineOverlay(cwd, mode, warn = (m) => process.stderr.write(`${m}\n`)) {
+  const abs = path.join(cwd, PIPELINE_CONFIG_REL);
+  if (!fs.existsSync(abs)) return { skip: [], extra: [] };
+  let raw;
+  try {
+    raw = JSON.parse(stripJsonc(fs.readFileSync(abs, "utf8")));
+  } catch (err) {
+    warn(`pipeline: ignoring ${PIPELINE_CONFIG_REL}: ${err.message}`);
+    return { skip: [], extra: [] };
+  }
+  const section = raw && typeof raw === "object" && !Array.isArray(raw) ? raw[mode] : null;
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    return { skip: [], extra: [] };
+  }
+  return { skip: asStringList(section.skip), extra: asStringList(section.extra) };
+}
+
+export function resolvePipelineCommands(mode, cwd, warn) {
+  const stock = COMMANDS[mode];
+  if (!stock) return null;
+  const { skip, extra } = loadPipelineOverlay(cwd, mode, warn);
+  const skipSet = new Set(skip);
+  return [...stock.filter((c) => !skipSet.has(c)), ...extra];
+}
+
+export function formatCheckFailures(failures) {
+  const n = failures.length;
+  const lines = [`pipeline check failed (${n} step${n === 1 ? "" : "s"}):`];
+  for (const { cmd, err } of failures) {
+    lines.push(`- ${cmd}`);
+    const msg = err && err.message ? err.message : String(err);
+    for (const line of msg.split(/\r?\n/)) {
+      if (line) lines.push(`  ${line}`);
+    }
+  }
+  lines.push(
+    "If a consumer post-step rewrites this output (hooks-union, codex-sync), add the stock command to check.skip in .rulesync/grunt.pipeline.jsonc",
+  );
+  return lines.join("\n");
+}
+
+export function runPipeline(mode, { cwd = process.cwd(), exec = execSync, warn } = {}) {
+  const cmds = resolvePipelineCommands(mode, cwd, warn);
   if (!cmds) {
     throw new Error("usage: pipeline.mjs generate|check|watch");
   }
   const env = envWithLocalBin(cwd);
+  if (mode === "check") {
+    const failures = [];
+    for (const cmd of cmds) {
+      try {
+        exec(cmd, { cwd, stdio: "inherit", shell: true, env });
+      } catch (err) {
+        failures.push({ cmd, err });
+      }
+    }
+    if (failures.length) throw new Error(formatCheckFailures(failures));
+    return;
+  }
   for (const cmd of cmds) {
     exec(cmd, { cwd, stdio: "inherit", shell: true, env });
   }

package/scripts/session-map.mjs

@@ -63,7 +63,7 @@ function main() {
       JSON.stringify({
         hookSpecificOutput: {
           hookEventName: "SessionStart",
-          additionalContext: `${header(/  …$/m.test(out.text) ? out.depth : null)}\n${out.text}`,
+          additionalContext: `${header(/ {2}…$/m.test(out.text) ? out.depth : null)}\n${out.text}`,
         },
       }),
     );

package/scripts/speak.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { loadOptionalConsumerEnv } from "./doctor.mjs";
 
 export const DEFAULT_ELEVEN_VOICE = "JBFqnCBsd6RMkjVDRZzb";
 export const DEFAULT_ELEVEN_MODEL = "eleven_multilingual_v2";
@@ -246,6 +247,7 @@ export async function say({
 
 export async function main(argv = process.argv.slice(2), opts = {}) {
   const { _, flags } = parseArgv(argv);
+  if (!opts.env) await loadOptionalConsumerEnv();
   const env = opts.env || process.env;
   const home = opts.home || os.homedir();
   const cwd = opts.cwd || process.cwd();