session-orchestrator 5.1.0 → 5.3.0

package/scripts/generate-cursor-adapter.mjs

@@ -7,6 +7,18 @@
  * `skills/`; these wrappers keep one maintained body while giving Cursor a
  * native entry per command/skill (same pattern as `generate-pi-prompts.mjs`).
  *
+ * `.cursor/commands/` is generated from the UNION of two sources: every
+ * `commands/*.md`, plus every skill whose frontmatter carries an explicit
+ * `user-invocable: true`. The second source exists because the operator-facing
+ * slash-command marker moved INTO the skill frontmatter when the command bodies
+ * were folded into their same-named `skills/<name>/SKILL.md`. A name present in
+ * both sources is a generator ERROR, not a precedence question — two documents
+ * claiming one public `/name` is a merge that did not finish.
+ *
+ * `disable-model-invocation` is propagated from the SOURCE frontmatter and is
+ * NOT derived from `user-invocable` — see {@link disablesModelInvocation} for
+ * the two grounds and the measurement behind them.
+ *
  * Usage:
  *   node scripts/generate-cursor-adapter.mjs
  *   node scripts/generate-cursor-adapter.mjs --check
@@ -15,6 +27,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
@@ -26,17 +39,22 @@ const CURSOR_SKILLS_DIR = path.join(ROOT, '.cursor', 'skills');
 const CHECK_ONLY = process.argv.includes('--check');
 const DESCRIPTION_MAX = 1024;
 
+/** Memo for {@link skillFlags} — skill name → parsed frontmatter + both markers. */
+const SKILL_FLAGS = new Map();
+
 function isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
 
 function commandFiles() {
+  if (!existsSync(COMMANDS_DIR)) return [];
   return readdirSync(COMMANDS_DIR)
     .filter((name) => name.endsWith('.md'))
     .sort();
 }
 
 function skillDirs() {
+  if (!existsSync(SKILLS_DIR)) return [];
   return readdirSync(SKILLS_DIR)
     .filter((name) => isDir(path.join(SKILLS_DIR, name)) && existsSync(path.join(SKILLS_DIR, name, 'SKILL.md')))
     .sort();
@@ -44,15 +62,30 @@ function skillDirs() {
 
 /**
  * Parse YAML-ish frontmatter including `>` / `|` folded scalars.
+ *
+ * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
+ * two probes below miss the block entirely: the file parsed as "no
+ * frontmatter", so every flag in it (`user-invocable`,
+ * `disable-model-invocation`) silently disappeared and the skill was demoted
+ * out of `.cursor/commands/` with no diagnostic anywhere. Both are normalised
+ * away first — the same treatment `parseAgentFrontmatter`
+ * (`scripts/lib/agent-frontmatter.mjs`) gives them.
+ *
+ * NOT replaced by the shared `parseSkillFrontmatter`: that one returns the
+ * `__BLOCK_SCALAR__` sentinel for a `description: >`, which is the form every
+ * merged skill actually uses — routing through it would emit the sentinel as
+ * the wrapper description.
+ *
  * @param {string} content
  * @returns {Record<string, string>}
  */
 function parseFrontmatter(content) {
-  if (!content.startsWith('---\n')) return {};
-  const end = content.indexOf('\n---\n', 4);
+  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
   if (end === -1) return {};
 
-  const lines = content.slice(4, end).split('\n');
+  const lines = text.slice(4, end).split('\n');
   const fields = {};
   let i = 0;
   while (i < lines.length) {
@@ -158,13 +191,155 @@ Cursor has no Skill tool. When the command says to invoke a skill, Read \`skills
 `;
 }
 
-function isUserInvocable(value) {
-  return value === 'true' || value === true;
+/**
+ * Skills that declare themselves operator-facing slash commands.
+ *
+ * The predicate is `isUserInvocableValue` from `scripts/lib/user-invocable-skills.mjs`
+ * — the ONE normaliser for this marker, shared with the Pi and Codex generators
+ * and with every counter. The private copy this replaced read only a
+ * whitespace-trimmed bare `true`, so `True` and `true # note` were demoted HERE
+ * while the shared counter listed them as commands; the SKILL.md path is passed
+ * so a demotion WARN names the file.
+ *
+ * @returns {string[]} skill names, sorted
+ */
+function userInvocableSkills() {
+  return skillDirs().filter((name) => skillFlags(name).userInvocable);
+}
+
+/**
+ * Both boolean markers of ONE skill, parsed and judged exactly once.
+ *
+ * Memoised because the predicate is not side-effect free: a truthy-lookalike
+ * value (`yes`, `on`, `1`) emits a stderr WARN, so reading the same key from
+ * three call sites emitted the same warning three times — measured 2026-09-18
+ * on a two-skill fixture: 3 WARN lines for 2 defects. One skill, one reading,
+ * one diagnostic.
+ *
+ * @param {string} skillName
+ * @returns {{file: string, fields: Record<string, string>, userInvocable: boolean,
+ *   sourceDisablesModel: boolean, disablesModel: boolean}}
+ */
+function skillFlags(skillName) {
+  const cached = SKILL_FLAGS.get(skillName);
+  if (cached) return cached;
+  const file = path.join(SKILLS_DIR, skillName, 'SKILL.md');
+  const fields = parseFrontmatter(readFileSync(file, 'utf8'));
+  const userInvocable = isUserInvocableValue(fields['user-invocable'], file, 'user-invocable');
+  const sourceDisablesModel = isUserInvocableValue(
+    fields['disable-model-invocation'], file, 'disable-model-invocation',
+  );
+  const flags = {
+    file,
+    fields,
+    userInvocable,
+    sourceDisablesModel,
+    // See {@link disablesModelInvocation} for the two OR-ed grounds.
+    disablesModel: sourceDisablesModel || !userInvocable,
+  };
+  SKILL_FLAGS.set(skillName, flags);
+  return flags;
+}
+
+/**
+ * A `.cursor/commands/<name>.md` wrapper for a skill that IS the slash command
+ * (`user-invocable: true`). Same contract as {@link renderCommand}, pointing at
+ * the skill body instead of a command file.
+ *
+ * @param {string} skillName
+ * @returns {string}
+ */
+function renderSkillCommand(skillName) {
+  const { fields, sourceDisablesModel } = skillFlags(skillName);
+  const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
+  // Same GH#54 rule as renderCommand: `argument-hint` ALWAYS goes through
+  // yamlQuote(), because its canonical authored form (`[mode] [--flag]`) is a
+  // YAML flow sequence when emitted bare.
+  // The command wrapper carries the SOURCE value only — never the library-skill
+  // ground of {@link disablesModelInvocation}, which cannot apply here: this
+  // surface exists BECAUSE the skill is `user-invocable: true`. Propagated so an
+  // operator-only command stays operator-only on whichever of the two surfaces
+  // Cursor reads the policy from (same mapping the Codex adapter makes onto
+  // `policy.allow_implicit_invocation`, `scripts/generate-codex-skills.mjs`).
+  const frontmatter = [
+    '---',
+    frontmatterLine('description', yamlQuote(description)),
+    frontmatterLine('argument-hint', yamlQuote(fields['argument-hint'])),
+    sourceDisablesModel ? 'disable-model-invocation: true' : null,
+    '---',
+  ].filter(Boolean).join('\n');
+
+  return `${frontmatter}
+
+# /${skillName}
+
+Use the Session Orchestrator skill definition at \`skills/${skillName}/SKILL.md\`.
+
+Arguments: $ARGUMENTS
+
+Read that skill file and follow it exactly. When it references \`$ARGUMENTS\`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+
+Cursor has no Skill tool. When the skill says to invoke another skill, Read \`skills/<skill-name>/SKILL.md\` and follow it. Supporting files (\`soul.md\`, phase docs) live in that same \`skills/<skill-name>/\` directory.
+`;
+}
+
+/**
+ * Emit `disable-model-invocation: true` into a Cursor wrapper?
+ *
+ * TWO independent grounds, OR-ed — the flag is a restriction, so the rule is
+ * fail-closed:
+ *   1. the SOURCE skill declares it (the single truth for operator-only skills).
+ *      That flag is an INDEPENDENT axis from `user-invocable`, not its inverse:
+ *      six skills carry BOTH (measured 2026-09-17: bootstrap, brainstorm, close,
+ *      go, plan, release), and deriving the wrapper's flag from `user-invocable`
+ *      alone emitted NO flag for exactly those six — letting a Cursor model
+ *      auto-invoke `/close`, `/go` and `/release`;
+ *   2. the skill is not `user-invocable`, i.e. a library skill whose Cursor
+ *      wrapper is reached by an explicit Read from a command body, never by a
+ *      model's own dispatch. This ground predates the #1 fix and is kept
+ *      deliberately: dropping it would REMOVE the flag from 24 of 50 wrappers
+ *      (measured 2026-09-17) on no Cursor-side evidence, which is the one
+ *      direction a guard fix must never move.
+ *
+ * NAMED CEILING on ground 2 (BV-004). Whether Cursor reads
+ * `disable-model-invocation` at all is UNVERIFIED as of 2026-09-18: the key is
+ * documented here for Claude Code and Codex only, and `rg
+ * "disable-model-invocation" docs .claude .cursor/rules` returns zero Cursor
+ * citations. Ground 2 therefore stamps 24 wrappers on the ASSUMPTION that
+ * Cursor honours it — kept because stamping a restriction a reader ignores
+ * costs nothing, while dropping it would loosen 24 wrappers if the reader does
+ * honour it. REVISIT TRIGGER: Cursor documents the key (or a measured Cursor
+ * run shows it ignored) — then decide ground 2 on that evidence instead.
+ * Pinned by `tests/scripts/generate-cursor-adapter.test.mjs` ("stamps
+ * disable-model-invocation on ground 2 alone").
+ *
+ * Truth table — both readings normalised by `isUserInvocableValue`, so every
+ * form a YAML parser reads as `true` (`True`, `"true"`, `true # note`) counts
+ * as `true` on BOTH axes. Ground 2 made that load-bearing rather than cosmetic:
+ * while this file kept a private bare-`true` predicate, a `True`-marked
+ * user-invocable skill read as NOT user-invocable HERE and got the restriction
+ * STAMPED, while the shared counter listed it as a command:
+ *
+ *   | source flag | user-invocable | emitted |
+ *   |-------------|----------------|---------|
+ *   | true        | true           | yes (1) |
+ *   | true        | false/absent   | yes (1+2) |
+ *   | false/absent| true           | no      |
+ *   | false/absent| false/absent   | yes (2) |
+ *
+ * Both readings come from {@link skillFlags} (`sourceDisablesModel ||
+ * !userInvocable`), which parses each SKILL.md once — so a truthy-lookalike
+ * value warns once per key per skill instead of once per call site.
+ *
+ * @param {string} skillName
+ * @returns {boolean}
+ */
+function disablesModelInvocation(skillName) {
+  return skillFlags(skillName).disablesModel;
 }
 
 function renderSkill(skillName) {
-  const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
-  const fields = parseFrontmatter(readFileSync(skillPath, 'utf8'));
+  const { fields } = skillFlags(skillName);
   const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
   // Same rule as renderCommand: no frontmatter value is emitted raw. `name` is
   // a directory basename today, so it is plain-safe in practice — routing it
@@ -174,7 +349,7 @@ function renderSkill(skillName) {
     `name: ${yamlQuote(skillName)}`,
     `description: ${yamlQuote(description)}`,
   ];
-  if (!isUserInvocable(fields['user-invocable'])) {
+  if (disablesModelInvocation(skillName)) {
     lines.push('disable-model-invocation: true');
   }
   lines.push('---');
@@ -191,12 +366,37 @@ Cursor has no Skill tool. Treat "invoke the ${skillName} skill" as: Read \`skill
 `;
 }
 
+/**
+ * The expected `.cursor/commands/` set: every `commands/*.md` PLUS every skill
+ * marked `user-invocable: true`.
+ *
+ * @returns {Map<string, string>} file name → content, sorted by file name
+ * @throws {Error} when one public name is claimed by both sources
+ */
 function expectedCommands() {
   const commands = new Map();
   for (const commandFile of commandFiles()) {
     commands.set(commandFile, renderCommand(commandFile));
   }
-  return commands;
+
+  const collisions = [];
+  for (const skillName of userInvocableSkills()) {
+    const fileName = `${skillName}.md`;
+    if (commands.has(fileName)) {
+      collisions.push(skillName);
+      continue;
+    }
+    commands.set(fileName, renderSkillCommand(skillName));
+  }
+  if (collisions.length > 0) {
+    throw new Error(
+      `${collisions.length} public name(s) claimed by BOTH commands/ and a user-invocable skill: ${collisions.join(', ')}. `
+      + 'Exactly one document may own a slash command — delete the commands/<name>.md whose body was folded into skills/<name>/SKILL.md, '
+      + 'or drop `user-invocable: true` from the skill.',
+    );
+  }
+
+  return new Map([...commands].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
 }
 
 function expectedSkills() {
@@ -284,7 +484,16 @@ function writeAll(expectedCmds, expectedSkillsMap) {
   process.stdout.write(`cursor adapter: wrote ${expectedCmds.size} command(s), ${expectedSkillsMap.size} skill(s)\n`);
 }
 
-const expectedCmds = expectedCommands();
-const expectedSkillsMap = expectedSkills();
+let expectedCmds;
+let expectedSkillsMap;
+try {
+  expectedCmds = expectedCommands();
+  expectedSkillsMap = expectedSkills();
+} catch (error) {
+  // Loud and diagnosable: a source conflict must never degrade into a partial
+  // write or a stack trace read as "some node thing went wrong".
+  process.stderr.write(`FAIL: ${error.message}\n`);
+  process.exit(1);
+}
 if (CHECK_ONLY) checkAll(expectedCmds, expectedSkillsMap);
 else writeAll(expectedCmds, expectedSkillsMap);

package/scripts/generate-hook-import-set.mjs

@@ -24,10 +24,10 @@
  * write is NEVER performed on a usage error.
  */
 
-import { readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 /** The four hook manifests whose entry files seed the crawl. */
 export const HOOK_MANIFESTS = [
@@ -263,30 +263,15 @@ export function main(argv) {
   return 0;
 }
 
-/**
- * True when this module was launched as the process entry script.
- *
- * A string compare of `import.meta.url` against `file://${process.argv[1]}` is
- * fragile in exactly the invocations CI and husky use: any symlinked or
- * realpath-differing path (measured: `/tmp` → `/private/tmp` on macOS) makes
- * the compare false, so the whole CLI body becomes a silent no-op that still
- * exits 0 — a fail-OPEN drift gate. A space or `#` in the path breaks the
- * hand-built URL the same way. Same shape as `hooks/post-bash-write-verify.mjs`.
- *
- * @returns {boolean}
- */
-function invokedAsScript() {
-  const entry = process.argv[1];
-  if (!entry) return false;
-  const self = fileURLToPath(import.meta.url);
-  try {
-    return realpathSync(entry) === realpathSync(self);
-  } catch {
-    // argv[1] unresolvable (deleted/renamed mid-run) — best-effort raw compare.
-    return entry === self;
-  }
-}
-
-if (invokedAsScript()) {
+// Entry guard via the canonical predicate (`scripts/lib/is-main-module.mjs`).
+// A string compare of `import.meta.url` against `file://${process.argv[1]}` is
+// fragile in exactly the invocations CI and husky use: any symlinked or
+// realpath-differing path (measured: `/tmp` → `/private/tmp` on macOS) makes the
+// compare false, so the whole CLI body becomes a silent no-op that still exits 0
+// — a fail-OPEN drift gate. This script is a plain CLI, not a hook, so it may
+// import from `scripts/lib/` (the hooks that still inline the same predicate do
+// so to keep `scripts/lib` off their hot path — see the ceiling comment in
+// `hooks/post-bash-write-verify.mjs`).
+if (isMainModule(import.meta.url)) {
   process.exit(main(process.argv));
 }

package/scripts/generate-pi-prompts.mjs

@@ -6,56 +6,162 @@
  * cross-harness `$ARGUMENTS` placeholder. The generated wrapper keeps one
  * maintained command source while giving Pi a native prompt entry per command.
  *
+ * `pi/prompts/` is generated from the UNION of two sources: every
+ * `commands/*.md`, plus every skill whose frontmatter carries an explicit
+ * `user-invocable: true`. The second source exists because the operator-facing
+ * slash-command marker moved INTO the skill frontmatter when the command bodies
+ * were folded into their same-named `skills/<name>/SKILL.md`. A name present in
+ * both sources is a generator ERROR, not a precedence question — two documents
+ * claiming one public `/name` is a merge that did not finish.
+ *
  * Usage:
  *   node scripts/generate-pi-prompts.mjs
  *   node scripts/generate-pi-prompts.mjs --check
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
 const ROOT = path.dirname(SCRIPT_DIR);
 const COMMANDS_DIR = path.join(ROOT, 'commands');
+const SKILLS_DIR = path.join(ROOT, 'skills');
 const PROMPTS_DIR = path.join(ROOT, 'pi', 'prompts');
 const CHECK_ONLY = process.argv.includes('--check');
+const DESCRIPTION_MAX = 1024;
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
 
 function commandFiles() {
+  if (!existsSync(COMMANDS_DIR)) return [];
   return readdirSync(COMMANDS_DIR)
     .filter((name) => name.endsWith('.md'))
     .sort();
 }
 
+function skillDirs() {
+  if (!existsSync(SKILLS_DIR)) return [];
+  return readdirSync(SKILLS_DIR)
+    .filter((name) => isDir(path.join(SKILLS_DIR, name)) && existsSync(path.join(SKILLS_DIR, name, 'SKILL.md')))
+    .sort();
+}
+
+/**
+ * Parse YAML-ish frontmatter including `>` / `|` folded scalars, returning
+ * DECODED values (surrounding quotes stripped). Skill descriptions are folded
+ * scalars in practice, which the previous line-at-a-time parser read as the
+ * literal `>`. Mirrors `generate-cursor-adapter.mjs`.
+ *
+ * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
+ * two probes below miss the block entirely: the file parsed as "no
+ * frontmatter", so `user-invocable` silently disappeared and the skill was
+ * demoted out of `pi/prompts/` with no diagnostic anywhere. Both are normalised
+ * away first — the same treatment `parseAgentFrontmatter`
+ * (`scripts/lib/agent-frontmatter.mjs`) gives them.
+ *
+ * @param {string} content
+ * @returns {Record<string, string>}
+ */
 function parseFrontmatter(content) {
-  if (!content.startsWith('---\n')) return {};
-  const end = content.indexOf('\n---\n', 4);
+  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---\n', 4);
   if (end === -1) return {};
 
+  const lines = text.slice(4, end).split('\n');
   const fields = {};
-  const block = content.slice(4, end).split('\n');
-  for (const line of block) {
-    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!match) continue;
-    fields[match[1]] = match[2];
+  let i = 0;
+  while (i < lines.length) {
+    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      i += 1;
+      continue;
+    }
+    const key = match[1];
+    const raw = match[2];
+    if (raw === '>' || raw === '| ' || raw === '|' || raw === '>-' || raw === '|-') {
+      const folded = [];
+      i += 1;
+      while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i] === '')) {
+        folded.push(lines[i].replace(/^\s+/, ''));
+        i += 1;
+      }
+      const joiner = raw.startsWith('|') ? '\n' : ' ';
+      fields[key] = folded.filter(Boolean).join(joiner).trim();
+      continue;
+    }
+    fields[key] = raw.replace(/^["']|["']$/g, '');
+    i += 1;
   }
   return fields;
 }
 
+/** @see generate-cursor-adapter.mjs — same allow-list, same reasoning. */
+const YAML_SCALAR_LOOKALIKE = /^(?:true|false|yes|no|on|off|null|nan|[-+]?\.?inf|~)$/i;
+const YAML_PLAIN_SAFE = /^[A-Za-z0-9_][A-Za-z0-9 _.,()/-]*$/;
+
+/**
+ * Render a frontmatter VALUE as YAML. `argument-hint`'s canonical authored form
+ * (`[mode] [--flag]`) is a YAML flow SEQUENCE when emitted bare — GH#54, which
+ * made Copilot CLI >= 1.0.65 silently drop the file.
+ *
+ * @param {unknown} value
+ * @returns {string|null} the YAML scalar, or `null` when there is nothing to emit
+ */
+function yamlQuote(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const text = String(value);
+  if (text.trim() === '') return null;
+  if (text !== text.trim()) return JSON.stringify(text);
+  if (!YAML_PLAIN_SAFE.test(text)) return JSON.stringify(text);
+  if (YAML_SCALAR_LOOKALIKE.test(text)) return JSON.stringify(text);
+  if (/^\d/.test(text)) return JSON.stringify(text);
+  return text;
+}
+
 function frontmatterLine(key, value) {
-  if (value === undefined || value === '') return null;
+  if (value === undefined || value === '' || value === null) return null;
   return `${key}: ${value}`;
 }
 
+function clampDescription(text) {
+  const collapsed = String(text || '').replace(/\s+/g, ' ').trim();
+  if (collapsed.length <= DESCRIPTION_MAX) return collapsed;
+  return collapsed.slice(0, DESCRIPTION_MAX - 1).trimEnd() + '…';
+}
+
+/**
+ * Skills that declare themselves operator-facing slash commands.
+ *
+ * The predicate is `isUserInvocableValue` from `scripts/lib/user-invocable-skills.mjs`
+ * — the ONE normaliser for this marker, shared with the Cursor and Codex
+ * generators and with every counter. A local copy here is how the quoted-value
+ * disagreement arose (`"true"`: wrapper generated on two adapters, counted by
+ * neither counter, crash on the third).
+ *
+ * @returns {string[]} skill names, sorted
+ */
+function userInvocableSkills() {
+  return skillDirs().filter((name) => {
+    const file = path.join(SKILLS_DIR, name, 'SKILL.md');
+    const fields = parseFrontmatter(readFileSync(file, 'utf8'));
+    return isUserInvocableValue(fields['user-invocable'], file);
+  });
+}
+
 function renderPrompt(commandFile) {
   const commandPath = path.join(COMMANDS_DIR, commandFile);
   const commandName = commandFile.replace(/\.md$/, '');
   const fields = parseFrontmatter(readFileSync(commandPath, 'utf8'));
   const frontmatter = [
     '---',
-    frontmatterLine('description', fields.description),
-    frontmatterLine('argument-hint', fields['argument-hint']),
+    frontmatterLine('description', yamlQuote(clampDescription(fields.description))),
+    frontmatterLine('argument-hint', yamlQuote(fields['argument-hint'])),
     '---',
   ].filter(Boolean).join('\n');
 
@@ -71,12 +177,68 @@ Read that command file and follow it exactly. When it references \`$ARGUMENTS\`,
 `;
 }
 
+/**
+ * A `pi/prompts/<name>.md` wrapper for a skill that IS the slash command
+ * (`user-invocable: true`). Same contract as {@link renderPrompt}, pointing at
+ * the skill body instead of a command file.
+ *
+ * @param {string} skillName
+ * @returns {string}
+ */
+function renderSkillPrompt(skillName) {
+  const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
+  const fields = parseFrontmatter(readFileSync(skillPath, 'utf8'));
+  const description = clampDescription(fields.description || `Session Orchestrator skill: ${skillName}`);
+  const frontmatter = [
+    '---',
+    frontmatterLine('description', yamlQuote(description)),
+    frontmatterLine('argument-hint', yamlQuote(fields['argument-hint'])),
+    '---',
+  ].filter(Boolean).join('\n');
+
+  return `${frontmatter}
+
+# /${skillName}
+
+Use the Session Orchestrator skill definition at \`skills/${skillName}/SKILL.md\`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references \`$ARGUMENTS\`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+`;
+}
+
+/**
+ * The expected `pi/prompts/` set: every `commands/*.md` PLUS every skill marked
+ * `user-invocable: true`.
+ *
+ * @returns {Map<string, string>} file name -> content, sorted by file name
+ * @throws {Error} when one public name is claimed by both sources
+ */
 function expectedPrompts() {
   const prompts = new Map();
   for (const commandFile of commandFiles()) {
     prompts.set(commandFile, renderPrompt(commandFile));
   }
-  return prompts;
+
+  const collisions = [];
+  for (const skillName of userInvocableSkills()) {
+    const fileName = `${skillName}.md`;
+    if (prompts.has(fileName)) {
+      collisions.push(skillName);
+      continue;
+    }
+    prompts.set(fileName, renderSkillPrompt(skillName));
+  }
+  if (collisions.length > 0) {
+    throw new Error(
+      `${collisions.length} public name(s) claimed by BOTH commands/ and a user-invocable skill: ${collisions.join(', ')}. `
+      + 'Exactly one document may own a slash command — delete the commands/<name>.md whose body was folded into skills/<name>/SKILL.md, '
+      + 'or drop `user-invocable: true` from the skill.',
+    );
+  }
+
+  return new Map([...prompts].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
 }
 
 function checkPrompts(expected) {
@@ -122,6 +284,14 @@ function writePrompts(expected) {
   console.log(`pi prompts: wrote ${expected.size} file(s)`);
 }
 
-const expected = expectedPrompts();
+let expected;
+try {
+  expected = expectedPrompts();
+} catch (error) {
+  // Loud and diagnosable: a source conflict must never degrade into a partial
+  // write or a stack trace read as "some node thing went wrong".
+  console.error(`FAIL: ${error.message}`);
+  process.exit(1);
+}
 if (CHECK_ONLY) checkPrompts(expected);
 else writePrompts(expected);

package/scripts/github-protection-audit.mjs

@@ -34,8 +34,8 @@
 
 import { execFile as _execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { pathToFileURL } from 'node:url';
 import { resolveRepoSpec as _resolveRepoSpec, resolveRepoHost as _resolveRepoHost } from './lib/vcs-repo-spec.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const execFileAsync = promisify(_execFile);
 
@@ -347,8 +347,7 @@ export async function auditGithubBranchProtection(opts = {}, deps = {}) {
 }
 
 // CLI entry — only when run directly, not when imported (e.g. by tests).
-const isMain =
-  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   auditGithubBranchProtection({ repoRoot: process.cwd() }).then((result) => {