@thebassclef/lite 1.5.1 → 1.7.0

package/README.md

@@ -35,7 +35,7 @@ See [`standards/os-support.md`](standards/os-support.md) for the full policy.
 
 ## Current release
 
-<!-- version-start -->1.5.1<!-- version-end -->
+<!-- version-start -->1.7.0<!-- version-end -->
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes.
 

package/dist/cli.cjs

@@ -38,7 +38,8 @@ const DEFAULTS$2 = {
   allowAnyDir: false,
   dir: void 0,
   yes: false,
-  json: false
+  json: false,
+  skipStatusline: false
 };
 let ArgvError$1 = class ArgvError extends Error {
   name = "ArgvError";
@@ -83,6 +84,11 @@ function parseInitArgs(argv) {
       i += 1;
       continue;
     }
+    if (token === "--skip-statusline") {
+      out.skipStatusline = true;
+      i += 1;
+      continue;
+    }
     if (token === "--dir") {
       const value = argv[i + 1];
       if (value === void 0 || value.startsWith("--")) {
@@ -802,6 +808,149 @@ function dirExists(p) {
     return false;
   }
 }
+const STATUSLINE_FIELD = {
+  type: "command",
+  command: "bash ~/.claude/bassclef-statusline.sh"
+};
+const DISPATCHER_REL = ["dist", "lite", "presence", "cli", "bassclef-statusline.dispatcher.sh"];
+const USER_DISPATCHER_REL = [".claude", "bassclef-statusline.sh"];
+const PROJECT_SETTINGS_REL = [".claude", "settings.json"];
+function installStatusline(opts) {
+  if (opts.skip) {
+    return {
+      dispatcher: skipped(node_path.join(opts.home, ...USER_DISPATCHER_REL)),
+      settings: skipped(node_path.join(opts.projectDir, ...PROJECT_SETTINGS_REL))
+    };
+  }
+  const dispatcherSource = node_path.join(opts.packageDir, ...DISPATCHER_REL);
+  if (!node_fs.existsSync(dispatcherSource)) {
+    throw new Error(
+      `bassclef init: cannot install statusline — bundled dispatcher missing at ${dispatcherSource}. Reinstall @thebassclef/lite or file a bug.`
+    );
+  }
+  const sourceBody = node_fs.readFileSync(dispatcherSource, "utf8");
+  const dispatcher = handleDispatcher(opts, dispatcherSource, sourceBody);
+  const settings = handleSettings(opts);
+  return { dispatcher, settings };
+}
+function handleDispatcher(opts, sourcePath, sourceBody) {
+  const target = node_path.join(opts.home, ...USER_DISPATCHER_REL);
+  if (opts.dryRun) {
+    return {
+      kind: "would-install",
+      path: target,
+      detail: `Dry-run: would copy ${sourcePath} → ${target} (0755).`
+    };
+  }
+  if (!node_fs.existsSync(target)) {
+    writeExec(target, sourceBody);
+    return { kind: "installed", path: target, detail: `Wrote ${target} (0755) from bundled dispatcher.` };
+  }
+  const st = node_fs.lstatSync(target);
+  if (st.isSymbolicLink()) {
+    if (!opts.force) {
+      return {
+        kind: "preserved",
+        path: target,
+        detail: `${target} is a symlink; refusing to follow. Pass --force to replace.`
+      };
+    }
+    node_fs.unlinkSync(target);
+    writeExec(target, sourceBody);
+    return { kind: "replaced", path: target, detail: `Replaced symlink at ${target} with bundled dispatcher.` };
+  }
+  const existing = node_fs.readFileSync(target, "utf8");
+  if (existing === sourceBody) {
+    return { kind: "unchanged", path: target, detail: `${target} already matches bundled dispatcher.` };
+  }
+  if (!opts.force) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} differs from bundled dispatcher. Pass --force to overwrite.`
+    };
+  }
+  writeExec(target, sourceBody);
+  return { kind: "replaced", path: target, detail: `Overwrote ${target} (--force) with bundled dispatcher.` };
+}
+function handleSettings(opts) {
+  const target = node_path.join(opts.projectDir, ...PROJECT_SETTINGS_REL);
+  if (opts.settingsPreserved) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} was preserved by init (--force not passed on existing file). Statusline field not merged. Re-run init with --force to overwrite.`
+    };
+  }
+  if (opts.dryRun) {
+    return {
+      kind: "would-install",
+      path: target,
+      detail: `Dry-run: would set statusLine in ${target}.`
+    };
+  }
+  const existing = readSettings(target);
+  const desired = STATUSLINE_FIELD;
+  const current = existing.statusLine;
+  if (current === void 0) {
+    const next2 = { ...existing, statusLine: desired };
+    writeSettings(target, next2);
+    return { kind: "installed", path: target, detail: `Wrote statusLine field to ${target}.` };
+  }
+  if (matchesDesired(current)) {
+    return { kind: "unchanged", path: target, detail: `${target} already carries the bassclef statusLine.` };
+  }
+  if (!opts.force) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} carries a different statusLine. Pass --force to overwrite.`
+    };
+  }
+  const next = { ...existing, statusLine: desired };
+  writeSettings(target, next);
+  return { kind: "replaced", path: target, detail: `Overwrote statusLine in ${target} (--force).` };
+}
+function skipped(path) {
+  return {
+    kind: "skipped",
+    path,
+    detail: "--skip-statusline set; no changes to statusline target."
+  };
+}
+function writeExec(target, body) {
+  node_fs.mkdirSync(node_path.dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  node_fs.writeFileSync(tmp, body, { mode: 493 });
+  node_fs.renameSync(tmp, target);
+  node_fs.chmodSync(target, 493);
+}
+function readSettings(target) {
+  if (!node_fs.existsSync(target)) return {};
+  const raw = node_fs.readFileSync(target, "utf8");
+  if (raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function writeSettings(target, next) {
+  node_fs.mkdirSync(node_path.dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  node_fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}
+`, { mode: 420 });
+  node_fs.renameSync(tmp, target);
+}
+function matchesDesired(current) {
+  if (!current || typeof current !== "object" || Array.isArray(current)) return false;
+  const c = current;
+  return c.type === STATUSLINE_FIELD.type && c.command === STATUSLINE_FIELD.command;
+}
 const FAMILIES = [
   "skills",
   "rules",
@@ -962,6 +1111,16 @@ function runInit(argv) {
       args.allowRoot,
       say
     );
+    const dryRunSettingsPreserved = !(args.force || upgradeApproved) && node_fs.existsSync(node_path.join(targetDir, ".claude", "settings.json"));
+    maybeEmitStatuslinePlan({
+      dryRun: true,
+      force: args.force || upgradeApproved,
+      skip: args.skipStatusline,
+      allowRoot: args.allowRoot,
+      targetDir,
+      say,
+      settingsPreserved: dryRunSettingsPreserved
+    });
     if (args.json) {
       const report = buildInitReport({
         entries: outcome.result?.wouldCopyEntries ?? [],
@@ -981,7 +1140,7 @@ function runInit(argv) {
     }
     return outcome.code;
   }
-  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json, say);
+  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json, args.skipStatusline, say);
 }
 function maybeEmitUpgradeAdvisory(targetDir, yes, json) {
   const prompt = json ? (t) => {
@@ -1204,7 +1363,7 @@ function runDryRun$1(plans, say) {
   }
   return 0;
 }
-function runReal$1(plans, force, verbose, targetDir, allowRoot, json, say) {
+function runReal$1(plans, force, verbose, targetDir, allowRoot, json, skipStatusline, say) {
   const results = [];
   let anyRefused = false;
   let anyError = false;
@@ -1307,6 +1466,20 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json, say) {
 `
     );
   }
+  const settingsRefused = (walker.result?.refused ?? []).some((r) => {
+    const p = typeof r === "string" ? r : r.path;
+    if (typeof p !== "string") return false;
+    return p === node_path.join(".claude", "settings.json") || p === ".claude/settings.json" || p.endsWith("/.claude/settings.json");
+  });
+  maybeEmitStatuslinePlan({
+    dryRun: false,
+    force,
+    skip: skipStatusline,
+    allowRoot,
+    targetDir,
+    say,
+    settingsPreserved: settingsRefused
+  });
   if (json) {
     renderJsonReport(report, (t) => {
       process.stdout.write(t);
@@ -1440,6 +1613,67 @@ function readDeclaredCommandLeaves(settingsPath) {
     return /* @__PURE__ */ new Set();
   }
 }
+function maybeEmitStatuslinePlan(opts) {
+  const packageDir = node_path.dirname(node_path.dirname(resolveBundleRoot(void 0)));
+  const dispatcherSource = node_path.join(
+    packageDir,
+    "dist",
+    "lite",
+    "presence",
+    "cli",
+    "bassclef-statusline.dispatcher.sh"
+  );
+  if (!node_fs.existsSync(dispatcherSource)) {
+    return;
+  }
+  let home;
+  try {
+    home = resolveHome({ allowRoot: opts.allowRoot });
+  } catch {
+    return;
+  }
+  let report;
+  try {
+    report = installStatusline({
+      home,
+      projectDir: opts.targetDir,
+      packageDir,
+      force: opts.force,
+      dryRun: opts.dryRun,
+      skip: opts.skip,
+      settingsPreserved: opts.settingsPreserved
+    });
+  } catch {
+    return;
+  }
+  const dv = report.dispatcher.kind;
+  const sv = report.settings.kind;
+  if (dv === "skipped" && sv === "skipped") {
+    opts.say(`bassclef init: statusline install skipped (--skip-statusline).
+`);
+    return;
+  }
+  if (opts.dryRun) {
+    opts.say(
+      `bassclef init: would install statusline dispatcher at ${report.dispatcher.path} and set statusLine in ${report.settings.path}.
+`
+    );
+    return;
+  }
+  const parts = [];
+  if (dv === "installed") parts.push(`wrote ${report.dispatcher.path}`);
+  else if (dv === "replaced") parts.push(`replaced ${report.dispatcher.path} (--force)`);
+  else if (dv === "preserved") parts.push(`preserved ${report.dispatcher.path} (pass --force to overwrite)`);
+  else if (dv === "unchanged") parts.push(`${report.dispatcher.path} already matches bundle`);
+  if (sv === "installed") parts.push(`set statusLine in ${report.settings.path}`);
+  else if (sv === "replaced") parts.push(`replaced statusLine in ${report.settings.path} (--force)`);
+  else if (sv === "preserved") parts.push(`preserved statusLine in ${report.settings.path} (pass --force to overwrite)`);
+  else if (sv === "unchanged") parts.push(`statusLine in ${report.settings.path} already matches`);
+  if (parts.length > 0) {
+    opts.say(`bassclef init: statusline — ${parts.join("; ")}.
+`);
+  }
+}
 const DEFAULTS$1 = {
   force: false,
   replaceEdits: false,

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { version } from "./index.js";
-import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, readFileSync, chmodSync, readdirSync, existsSync } from "node:fs";
+import { realpathSync, statSync, constants, lstatSync, mkdirSync, accessSync, unlinkSync, openSync, writeSync, closeSync, readlinkSync, readFileSync, chmodSync, readdirSync, existsSync, writeFileSync, renameSync } from "node:fs";
 import { isAbsolute, resolve, dirname, join, normalize, relative, basename as basename$1 } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -15,7 +15,8 @@ const DEFAULTS$2 = {
   allowAnyDir: false,
   dir: void 0,
   yes: false,
-  json: false
+  json: false,
+  skipStatusline: false
 };
 let ArgvError$1 = class ArgvError extends Error {
   name = "ArgvError";
@@ -60,6 +61,11 @@ function parseInitArgs(argv) {
       i += 1;
       continue;
     }
+    if (token === "--skip-statusline") {
+      out.skipStatusline = true;
+      i += 1;
+      continue;
+    }
     if (token === "--dir") {
       const value = argv[i + 1];
       if (value === void 0 || value.startsWith("--")) {
@@ -779,6 +785,149 @@ function dirExists(p) {
     return false;
   }
 }
+const STATUSLINE_FIELD = {
+  type: "command",
+  command: "bash ~/.claude/bassclef-statusline.sh"
+};
+const DISPATCHER_REL = ["dist", "lite", "presence", "cli", "bassclef-statusline.dispatcher.sh"];
+const USER_DISPATCHER_REL = [".claude", "bassclef-statusline.sh"];
+const PROJECT_SETTINGS_REL = [".claude", "settings.json"];
+function installStatusline(opts) {
+  if (opts.skip) {
+    return {
+      dispatcher: skipped(join(opts.home, ...USER_DISPATCHER_REL)),
+      settings: skipped(join(opts.projectDir, ...PROJECT_SETTINGS_REL))
+    };
+  }
+  const dispatcherSource = join(opts.packageDir, ...DISPATCHER_REL);
+  if (!existsSync(dispatcherSource)) {
+    throw new Error(
+      `bassclef init: cannot install statusline — bundled dispatcher missing at ${dispatcherSource}. Reinstall @thebassclef/lite or file a bug.`
+    );
+  }
+  const sourceBody = readFileSync(dispatcherSource, "utf8");
+  const dispatcher = handleDispatcher(opts, dispatcherSource, sourceBody);
+  const settings = handleSettings(opts);
+  return { dispatcher, settings };
+}
+function handleDispatcher(opts, sourcePath, sourceBody) {
+  const target = join(opts.home, ...USER_DISPATCHER_REL);
+  if (opts.dryRun) {
+    return {
+      kind: "would-install",
+      path: target,
+      detail: `Dry-run: would copy ${sourcePath} → ${target} (0755).`
+    };
+  }
+  if (!existsSync(target)) {
+    writeExec(target, sourceBody);
+    return { kind: "installed", path: target, detail: `Wrote ${target} (0755) from bundled dispatcher.` };
+  }
+  const st = lstatSync(target);
+  if (st.isSymbolicLink()) {
+    if (!opts.force) {
+      return {
+        kind: "preserved",
+        path: target,
+        detail: `${target} is a symlink; refusing to follow. Pass --force to replace.`
+      };
+    }
+    unlinkSync(target);
+    writeExec(target, sourceBody);
+    return { kind: "replaced", path: target, detail: `Replaced symlink at ${target} with bundled dispatcher.` };
+  }
+  const existing = readFileSync(target, "utf8");
+  if (existing === sourceBody) {
+    return { kind: "unchanged", path: target, detail: `${target} already matches bundled dispatcher.` };
+  }
+  if (!opts.force) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} differs from bundled dispatcher. Pass --force to overwrite.`
+    };
+  }
+  writeExec(target, sourceBody);
+  return { kind: "replaced", path: target, detail: `Overwrote ${target} (--force) with bundled dispatcher.` };
+}
+function handleSettings(opts) {
+  const target = join(opts.projectDir, ...PROJECT_SETTINGS_REL);
+  if (opts.settingsPreserved) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} was preserved by init (--force not passed on existing file). Statusline field not merged. Re-run init with --force to overwrite.`
+    };
+  }
+  if (opts.dryRun) {
+    return {
+      kind: "would-install",
+      path: target,
+      detail: `Dry-run: would set statusLine in ${target}.`
+    };
+  }
+  const existing = readSettings(target);
+  const desired = STATUSLINE_FIELD;
+  const current = existing.statusLine;
+  if (current === void 0) {
+    const next2 = { ...existing, statusLine: desired };
+    writeSettings(target, next2);
+    return { kind: "installed", path: target, detail: `Wrote statusLine field to ${target}.` };
+  }
+  if (matchesDesired(current)) {
+    return { kind: "unchanged", path: target, detail: `${target} already carries the bassclef statusLine.` };
+  }
+  if (!opts.force) {
+    return {
+      kind: "preserved",
+      path: target,
+      detail: `${target} carries a different statusLine. Pass --force to overwrite.`
+    };
+  }
+  const next = { ...existing, statusLine: desired };
+  writeSettings(target, next);
+  return { kind: "replaced", path: target, detail: `Overwrote statusLine in ${target} (--force).` };
+}
+function skipped(path) {
+  return {
+    kind: "skipped",
+    path,
+    detail: "--skip-statusline set; no changes to statusline target."
+  };
+}
+function writeExec(target, body) {
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, body, { mode: 493 });
+  renameSync(tmp, target);
+  chmodSync(target, 493);
+}
+function readSettings(target) {
+  if (!existsSync(target)) return {};
+  const raw = readFileSync(target, "utf8");
+  if (raw.trim() === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+function writeSettings(target, next) {
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}
+`, { mode: 420 });
+  renameSync(tmp, target);
+}
+function matchesDesired(current) {
+  if (!current || typeof current !== "object" || Array.isArray(current)) return false;
+  const c = current;
+  return c.type === STATUSLINE_FIELD.type && c.command === STATUSLINE_FIELD.command;
+}
 const FAMILIES = [
   "skills",
   "rules",
@@ -939,6 +1088,16 @@ function runInit(argv) {
       args.allowRoot,
       say
     );
+    const dryRunSettingsPreserved = !(args.force || upgradeApproved) && existsSync(join(targetDir, ".claude", "settings.json"));
+    maybeEmitStatuslinePlan({
+      dryRun: true,
+      force: args.force || upgradeApproved,
+      skip: args.skipStatusline,
+      allowRoot: args.allowRoot,
+      targetDir,
+      say,
+      settingsPreserved: dryRunSettingsPreserved
+    });
     if (args.json) {
       const report = buildInitReport({
         entries: outcome.result?.wouldCopyEntries ?? [],
@@ -958,7 +1117,7 @@ function runInit(argv) {
     }
     return outcome.code;
   }
-  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json, say);
+  return runReal$1(plans, args.force || upgradeApproved, args.verbose, targetDir, args.allowRoot, args.json, args.skipStatusline, say);
 }
 function maybeEmitUpgradeAdvisory(targetDir, yes, json) {
   const prompt = json ? (t) => {
@@ -1181,7 +1340,7 @@ function runDryRun$1(plans, say) {
   }
   return 0;
 }
-function runReal$1(plans, force, verbose, targetDir, allowRoot, json, say) {
+function runReal$1(plans, force, verbose, targetDir, allowRoot, json, skipStatusline, say) {
   const results = [];
   let anyRefused = false;
   let anyError = false;
@@ -1284,6 +1443,20 @@ function runReal$1(plans, force, verbose, targetDir, allowRoot, json, say) {
 `
     );
   }
+  const settingsRefused = (walker.result?.refused ?? []).some((r) => {
+    const p = typeof r === "string" ? r : r.path;
+    if (typeof p !== "string") return false;
+    return p === join(".claude", "settings.json") || p === ".claude/settings.json" || p.endsWith("/.claude/settings.json");
+  });
+  maybeEmitStatuslinePlan({
+    dryRun: false,
+    force,
+    skip: skipStatusline,
+    allowRoot,
+    targetDir,
+    say,
+    settingsPreserved: settingsRefused
+  });
   if (json) {
     renderJsonReport(report, (t) => {
       process.stdout.write(t);
@@ -1417,6 +1590,67 @@ function readDeclaredCommandLeaves(settingsPath) {
     return /* @__PURE__ */ new Set();
   }
 }
+function maybeEmitStatuslinePlan(opts) {
+  const packageDir = dirname(dirname(resolveBundleRoot(void 0)));
+  const dispatcherSource = join(
+    packageDir,
+    "dist",
+    "lite",
+    "presence",
+    "cli",
+    "bassclef-statusline.dispatcher.sh"
+  );
+  if (!existsSync(dispatcherSource)) {
+    return;
+  }
+  let home;
+  try {
+    home = resolveHome({ allowRoot: opts.allowRoot });
+  } catch {
+    return;
+  }
+  let report;
+  try {
+    report = installStatusline({
+      home,
+      projectDir: opts.targetDir,
+      packageDir,
+      force: opts.force,
+      dryRun: opts.dryRun,
+      skip: opts.skip,
+      settingsPreserved: opts.settingsPreserved
+    });
+  } catch {
+    return;
+  }
+  const dv = report.dispatcher.kind;
+  const sv = report.settings.kind;
+  if (dv === "skipped" && sv === "skipped") {
+    opts.say(`bassclef init: statusline install skipped (--skip-statusline).
+`);
+    return;
+  }
+  if (opts.dryRun) {
+    opts.say(
+      `bassclef init: would install statusline dispatcher at ${report.dispatcher.path} and set statusLine in ${report.settings.path}.
+`
+    );
+    return;
+  }
+  const parts = [];
+  if (dv === "installed") parts.push(`wrote ${report.dispatcher.path}`);
+  else if (dv === "replaced") parts.push(`replaced ${report.dispatcher.path} (--force)`);
+  else if (dv === "preserved") parts.push(`preserved ${report.dispatcher.path} (pass --force to overwrite)`);
+  else if (dv === "unchanged") parts.push(`${report.dispatcher.path} already matches bundle`);
+  if (sv === "installed") parts.push(`set statusLine in ${report.settings.path}`);
+  else if (sv === "replaced") parts.push(`replaced statusLine in ${report.settings.path} (--force)`);
+  else if (sv === "preserved") parts.push(`preserved statusLine in ${report.settings.path} (pass --force to overwrite)`);
+  else if (sv === "unchanged") parts.push(`statusLine in ${report.settings.path} already matches`);
+  if (parts.length > 0) {
+    opts.say(`bassclef init: statusline — ${parts.join("; ")}.
+`);
+  }
+}
 const DEFAULTS$1 = {
   force: false,
   replaceEdits: false,

package/dist/index.cjs

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = "1.5.1";
+const version = "1.7.0";
 exports.version = version;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export declare const version: "1.5.1";
+export declare const version: "1.7.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-const version = "1.5.1";
+const version = "1.7.0";
 export {
   version
 };

package/dist/lite/.claude/bassclef-orientation.md

@@ -66,6 +66,33 @@ JTBD → HTA → Entity Model → State Diagrams → Sequence Diagrams → /deco
 - **Don't conflate "propose" with "execute".** When operator says "propose," "options," "path forward" — wait for explicit go signal.
 - **Don't use bassclef-internal jargon** in operator-facing prose. Plain English at grade-10 reading level.
 - **Don't push to main without PR review** even on solo workflows.
+- **Don't run `git stash -u` on repos with gitignored substrate.** The `-u` flag moves untracked files to the stash. When your adopter repo gitignores `.claude/hooks/`, `.claude/skills/`, `.claude/rules/`, `.claude/agents/`, or `.claude/luminaries/`, `git stash -u` grabs the substrate files and Stop hooks fail with "No such file or directory" on every tool call. INSTEAD: use plain `git stash` unless you have vetted every untracked file first.
+
+## Substrate git posture
+
+Bassclef ships adopter `.gitignore` (per `presence/dist-templates/.gitignore`) with substrate tracked-by-default. Substrate paths under `.claude/hooks/`, `.claude/skills/`, `.claude/rules/`, `.claude/agents/`, `.claude/luminaries/` are NOT gitignored. Adopters commit substrate so `git stash -u` and similar verbs cannot grab it.
+
+**Opt-out recipe** — if you prefer substrate gitignored in your adopter repo:
+
+1. Add these lines to your `.gitignore`:
+
+   ```
+   .claude/hooks/
+   .claude/skills/
+   .claude/rules/
+   .claude/agents/
+   .claude/luminaries/
+   ```
+
+2. Untrack the files git already indexed:
+
+   ```
+   git rm --cached -r .claude/hooks .claude/skills .claude/rules .claude/agents .claude/luminaries
+   ```
+
+3. Commit the change.
+
+**Caveat.** `bassclef-sync` may re-add substrate files on the next session-start. If that happens, re-run the untrack step. Long-term cure lives with the sync script.
 
 ## Luminaries at design boundaries
 

package/dist/lite/.claude/hooks/session-reflection.d/70-recent-strategic-artifacts.sh

@@ -86,12 +86,14 @@ MSG="${MSG}  explicit operator statement (\"skip recent-artifacts this session\"
 MSG="${MSG}  Override: SKIP_RECENT_ARTIFACTS=1 <command> (logged)."
 
 # Emit via inherited blocked_banner (defined in session-reflection.sh)
+# Per standards/session-start-banner-discipline.md — this check is ADVISORY:
+# recent strategic artifacts are context worth reading; session may proceed.
 if type blocked_banner >/dev/null 2>&1; then
-  blocked_banner "$MSG"
+  blocked_banner "$MSG" advisory
 else
   # Defensive fallback if module is invoked outside the coordinator
   echo ""
-  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+  echo "⚠  ADVISORY"
   echo "$MSG"
   echo ""
 fi

package/dist/lite/.claude/hooks/session-reflection.d/80-hook-heartbeat-check.sh

@@ -104,10 +104,12 @@ done < <(jq -r '.critical_hooks[] | [.name, .max_age_seconds, .rationale] | @tsv
 if [ -n "$STALE_ENTRIES" ]; then
   NL=$'\n'
   MSG="hook liveness — stale hook(s) detected:$(echo -e "$STALE_ENTRIES")${NL}${NL}Cadence per standards/hook-cadence.json. Discipline per ADR-048 + .claude/rules/substrate-as-system.md.${NL}${NL}Resolve — run each named hook manually (check .claude/settings.json for its trigger event) OR file a substrate-defect ticket if the hook cannot be fired."
+  # Per standards/session-start-banner-discipline.md — stale hook is ADVISORY:
+  # session may proceed; operator informed to check hook trigger.
   if declare -f blocked_banner >/dev/null 2>&1; then
-    blocked_banner "$MSG"
+    blocked_banner "$MSG" advisory
   else
-    printf "BLOCKED: %b\n" "$MSG" >&2
+    printf "ADVISORY: %b\n" "$MSG" >&2
   fi
 fi