session-orchestrator 5.1.0 → 5.2.0

package/pi/prompts/repo-audit.md

@@ -1,12 +1,11 @@
 ---
-description: Run a 9-category baseline compliance audit on the current repository
-argument-hint: ""
+description: "Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: \"/repo-audit\" assistant: \"Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar.\" <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9 categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>"
 ---
 
 # /repo-audit
 
-Use the Session Orchestrator command definition at `commands/repo-audit.md`.
+Use the Session Orchestrator skill definition at `skills/repo-audit/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/session.md

@@ -1,5 +1,5 @@
 ---
-description: Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)
+description: "Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)"
 argument-hint: "[housekeeping|feature|deep|ultradeep]"
 ---
 

package/pi/prompts/spinout.md

@@ -1,12 +1,12 @@
 ---
-description: Guided 5-step venture-spinout / sanitized-fork runbook (copy + fresh-init + SNAPSHOT-FREEZE) — interactive, not scripted
+description: "Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'."
 argument-hint: "[--type venture|snapshot] [--dry-run]"
 ---
 
 # /spinout
 
-Use the Session Orchestrator command definition at `commands/spinout.md`.
+Use the Session Orchestrator skill definition at `skills/spinout/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/sunset-review.md

@@ -1,12 +1,12 @@
 ---
-description: Identify unused / near-zero-use / stale skills, agents, and commands as Demote or Retire candidates (read-only; never deletes)
+description: "Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: \"/sunset-review\" assistant: \"Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision.\" <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>"
 argument-hint: "[--kind skill|agent|command] [--window-days N]"
 ---
 
 # /sunset-review
 
-Use the Session Orchestrator command definition at `commands/sunset-review.md`.
+Use the Session Orchestrator skill definition at `skills/sunset-review/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/templates-ack.md

@@ -1,5 +1,5 @@
 ---
-description: Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session
+description: "Acknowledge templates-first policy for the current session — bypasses the pre-bash-templates-first hook for the remainder of the session"
 argument-hint: "[optional-reason]"
 ---
 

package/pi/prompts/test.md

@@ -1,12 +1,12 @@
 ---
-description: Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues
+description: "Agentic end-to-end test orchestrator — drive web/macOS flows, evaluate UX rubric, reconcile issues"
 argument-hint: "[scope|profile-name] [--since <git-ref>] [--full]"
 ---
 
 # /test
 
-Use the Session Orchestrator command definition at `commands/test.md`.
+Use the Session Orchestrator skill definition at `skills/test/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/ux-grill.md

@@ -1,12 +1,12 @@
 ---
-description: Grill a running web app's UX — a deterministic mechanical pass (axe, target size, overflow, journeys) followed by a screenshot-grounded interrogation of the operator.
+description: "Use when a running web app's UX has to be audited reproducibly rather than by feel — a deterministic mechanical pass over routes and viewports (axe, target size, horizontal overflow, page title, scripted journeys) followed by a screenshot-grounded interrogation of the operator, journey by journey, with two persona lenses from the target repo's manifest. Triggered by \"grill the UX\", \"roast the dashboard\", \"UX-Audit\", \"/ux-grill\". Bootstraps its own manifest from a loopback URL on the first run, so it never requires a hand-written file to start."
 argument-hint: "[url | manifest-path]"
 ---
 
 # /ux-grill
 
-Use the Session Orchestrator command definition at `commands/ux-grill.md`.
+Use the Session Orchestrator skill definition at `skills/ux-grill/SKILL.md`.
 
 Arguments: $@
 
-Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/scripts/archive-closed-prds.mjs

@@ -41,7 +41,6 @@
 
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 
 import { findProjectRoot, resolveInstructionFile, warn } from './lib/common.mjs';
@@ -52,6 +51,7 @@ import { defaultGlabRepo } from './lib/vcs-repo-spec.mjs';
 import { readLock } from './lib/session-lock.mjs';
 import { resolveStateMdPath } from './lib/state-md/frontmatter-mutators.mjs';
 import { parseStateMd } from './lib/state-md/yaml-parser.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_PRD_DIR = 'docs/prd';
 const DEFAULT_VAULT_SUBDIR = '01-projects/session-orchestrator/prd';
@@ -635,7 +635,7 @@ export function main({
 // CLI guard — prevents process.exit during test-time imports
 // ---------------------------------------------------------------------------
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   try {
     const { code } = main();
     process.exit(code ?? 0);

package/scripts/auq-audit.mjs

@@ -76,6 +76,7 @@ import {
 } from './lib/auq/schema.mjs';
 import { corpusKindOf, parseRepo } from './lib/auq/parse.mjs';
 import { writeStdoutLineSync } from './lib/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT_DEFAULT = path.resolve(HERE, '..');
@@ -818,8 +819,6 @@ function pkgVersion() {
   }
 }
 
-const invokedDirectly =
-  process.argv[1] !== undefined &&
-  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+const invokedDirectly =isMainModule(import.meta.url);
 
 if (invokedDirectly) main();

package/scripts/backfill-abandoned-sessions.mjs

@@ -39,11 +39,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { fileURLToPath } from 'node:url';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
 import { emitEvent } from './lib/events.mjs';
 import { getProjectDir } from './lib/platform.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { isLockLive, readLock } from './lib/session-lock.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
 
 const LOCK_ACQUIRED = 'orchestrator.session.lock.acquired';
 const SESSION_STARTED = 'orchestrator.session.started';
@@ -101,6 +103,24 @@ function readJsonl(filePath) {
  * session.started UUID, each bridged to its semantic id via lock.acquired
  * where one exists. Preserves first-seen order.
  *
+ * THIS VERY PROCESS is excluded (#1376). The shared core's own
+ * `skipped-own-live-lock` branch used to carry that job alone, but it is now
+ * defeasible: `ownSessionIsEnding` lets the SessionEnd hook record its own
+ * session, so the CLI must not depend on a branch whose meaning the caller
+ * chooses. The exclusion needs THREE conjuncts, and dropping any one of them
+ * breaks it in a different direction:
+ *   1. the candidate names the lock (by either id, including the #863 (d)
+ *      lock shape that stores the semantic id in `session_id`),
+ *   2. the lock is LIVE — a stale lock names a session nobody is running, and
+ *      reconstructing it is exactly this CLI's job, and
+ *   3. a PROCESS-LOCAL id (hook payload / harness env, never the repo-global
+ *      lock — see `readProcessLocalSessionIds`) matches the lock, which is
+ *      what distinguishes THIS process from a PEER's running session in the
+ *      same working copy. Without it the repo-global lock would vouch for
+ *      itself and a peer's live session would read as "me".
+ * A peer's live session is NOT excluded here and does not need to be: the core
+ * still rejects it through the untouched own/foreign live-lock guards.
+ *
  * @param {{ repoRoot: string }} args
  * @returns {Array<{ sessionId: string, semanticSessionId: string|null }>}
  */
@@ -124,17 +144,51 @@ export function planSessions({ repoRoot }) {
   }
   const semanticByUuid = new Map([...semanticFromEnded, ...semanticFromLock]);
 
+  const runningIds = readRunningSessionIds(repoRoot);
+
   const seen = new Set();
   const plan = [];
   for (const ev of events) {
     if (ev.event !== SESSION_STARTED || typeof ev.session_id !== 'string') continue;
     if (seen.has(ev.session_id)) continue;
     seen.add(ev.session_id);
-    plan.push({ sessionId: ev.session_id, semanticSessionId: semanticByUuid.get(ev.session_id) ?? null });
+    const semanticSessionId = semanticByUuid.get(ev.session_id) ?? null;
+    if (runningIds.has(ev.session_id)
+      || (semanticSessionId !== null && runningIds.has(semanticSessionId))) continue;
+    plan.push({ sessionId: ev.session_id, semanticSessionId });
   }
   return plan;
 }
 
+/**
+ * The id(s) naming the session THIS process is, when that session holds the
+ * live lock — else the empty set (#1376). Never throws: an unreadable lock,
+ * an absent one, or an env without any process-local id all degrade to "no
+ * exclusion", which is the pre-#1376 behaviour.
+ *
+ * @param {string} repoRoot
+ * @returns {Set<string>}
+ */
+function readRunningSessionIds(repoRoot) {
+  const ids = new Set();
+  try {
+    const lock = readLock({ repoRoot });
+    if (!lock || !isLockLive(lock)) return ids;
+    const lockIds = [lock.session_id, lock.semantic_session_id]
+      .filter((id) => typeof id === 'string' && id.length > 0);
+    const processLocal = new Set(readProcessLocalSessionIds());
+    // Conjunct 3 — only a PROCESS-LOCAL witness may promote the repo-global
+    // lock to "this is me". Membership is tested against the lock's ids, not
+    // the other way round, so an env var that happens to name some other
+    // session never widens the exclusion.
+    if (!lockIds.some((id) => processLocal.has(id))) return ids;
+    for (const id of lockIds) ids.add(id);
+  } catch {
+    /* readLock is no-throw by contract; the contract is not ours to trust */
+  }
+  return ids;
+}
+
 /**
  * Cheap pre-filter (#926): the set of session ids ALREADY present in
  * sessions.jsonl.
@@ -527,7 +581,7 @@ async function main() {
   process.exit(0);
 }
 
-const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const isDirectRun = isMainModule(import.meta.url);
 if (isDirectRun) {
   main().catch((err) => {
     process.stderr.write(`backfill-abandoned-sessions: unexpected error: ${err?.stack ?? err}\n`);

package/scripts/backfill-evidence-digest.mjs

@@ -50,6 +50,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 
 import { computeEvidenceDigest } from './lib/reconcile/renderer.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 /** ISO-8601 instant — mirrors the renderer's `EVIDENCE_RECORDED_AT_RE`. */
 const EVIDENCE_RECORDED_AT_RE = /^\d{4}-\d{2}-\d{2}T[0-9:.]+(?:Z|[+-]\d{2}:\d{2})$/;
@@ -373,4 +374,4 @@ function main(argv) {
   process.exit(unsealable === 0 ? 0 : 1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main(process.argv.slice(2));
+if (isMainModule(import.meta.url)) main(process.argv.slice(2));

package/scripts/backfill-learnings-from-vault.mjs

@@ -64,7 +64,6 @@
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, resolve, dirname, basename, relative } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
@@ -72,6 +71,7 @@ import { subjectToSlug, parseFrontmatter } from './lib/vault-mirror/utils.mjs';
 import { kebab } from './lib/learnings/kebab.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { appendLearning, isBackupOf } from './lib/learnings/io.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const DEFAULT_RULES_DIR = '.claude/rules';
 const DEFAULT_STORE = '.orchestrator/metrics/learnings.jsonl';
@@ -962,7 +962,7 @@ export async function main(argv = [], deps = {}) {
 }
 
 /* c8 ignore start — CLI entrypoint */
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+if (isMainModule(import.meta.url)) {
   main(process.argv.slice(2))
     .then(({ code }) => process.exit(code))
     .catch((err) => {

package/scripts/check-package-manager.mjs

@@ -67,6 +67,7 @@ import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 const SELF_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -388,8 +389,7 @@ function parseArgs(argv) {
 }
 
 // CLI entry — only when run directly, not when imported (e.g. by tests).
-const isMain =
-  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+const isMain =isMainModule(import.meta.url);
 
 if (isMain) {
   const { opts, unknown } = parseArgs(process.argv.slice(2));

package/scripts/ci/assert-vitest-green.mjs

@@ -50,6 +50,7 @@
 //   the existing bare message and the exit-code contract is unchanged.
 
 import { readFileSync } from 'node:fs';
+import { isMainModule } from '../lib/is-main-module.mjs';
 
 const DEFAULT_MIN_TESTS = 5000;
 
@@ -232,7 +233,7 @@ function parseArgs(argv) {
 }
 
 // CLI entry — only when run directly, not when imported by tests.
-const isMain = import.meta.url === `file://${process.argv[1]}`;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const { path, minTests, logPath } = parseArgs(process.argv.slice(2));
   if (!path) {

package/scripts/emit-session.mjs

@@ -26,7 +26,6 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { appendJsonl } from './lib/common.mjs';
 import {
   MEMORY_CLEANUP_EVENT,
@@ -42,6 +41,7 @@ import {
   clampTimestampsMonotonic,
   aliasLegacyEndedAt,
 } from './lib/session-schema.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 export { serializeSessionLineChecked };
 
@@ -277,8 +277,7 @@ async function main() {
 // not when imported as a module (e.g. by tests that exercise the exported
 // serializeSessionLineChecked seam — #662). Without this guard, importing the
 // module would block on stdin / exit the test process.
-const _isDirectRun =
-  process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const _isDirectRun =isMainModule(import.meta.url);
 
 if (_isDirectRun) {
   main().catch((err) => {

package/scripts/export-hw-learnings.mjs

@@ -63,6 +63,7 @@ import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.mjs';
 import { emitEvent, sessionAttribution } from './lib/events.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // Vault-relative default write target (Epic #774 — docs Public-Split removed
 // the prior in-repo generated telemetry doc in favor of the private Meta-Vault).
@@ -724,7 +725,7 @@ export async function exportHwLearnings(opts) {
 }
 
 // Run as CLI when invoked directly
-const isMain = import.meta.url === `file://${process.argv[1]}`;
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   const opts = parseArgs(process.argv.slice(2));
 

package/scripts/express-path.mjs

@@ -281,7 +281,7 @@ async function main() {
 
   // The banner the coordinator echoes into the transcript — `/go` and
   // session-plan's Express Path Short-Circuit both key off this EXACT line
-  // (`commands/go.md` § Express Path Detection), so it is written verbatim,
+  // (`skills/go/SKILL.md` § Express Path Detection), so it is written verbatim,
   // without the `express-path:` diagnostic prefix. Still stderr: stdout belongs
   // to the verdict.
   if (verdict.activated) {

package/scripts/gc-stale-worktrees.mjs

@@ -26,6 +26,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { validateWorkspacePath } from './lib/worktree/lifecycle.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -658,7 +659,7 @@ EXIT CODES
 // CLI guard — prevents process.exit during test-time imports (#368)
 // ---------------------------------------------------------------------------
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((err) => {
     process.stderr.write(`gc-stale-worktrees: unexpected error: ${err?.stack ?? err}\n`);
     process.exit(2);

package/scripts/generate-codex-skills.mjs

@@ -9,6 +9,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 import { toPortableFrontmatter } from './generate-agents-skills.mjs';
+import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
 
 const OUTPUT = '.codex-plugin/skills';
 const MARKER = 'Generated by scripts/generate-codex-skills.mjs; do not edit.';
@@ -26,8 +27,19 @@ function validateFrontmatter(fm, name, path) {
   if (typeof fm.description !== 'string' || !fm.description.trim() || fm.description.trim().length > 1024) {
     fail('description must be a non-empty string of at most 1024 characters');
   }
-  for (const key of ['disable-model-invocation', 'user-invocable']) {
-    if (Object.hasOwn(fm, key) && typeof fm[key] !== 'boolean') fail(`${key} must be a boolean`);
+  if (Object.hasOwn(fm, 'disable-model-invocation') && typeof fm['disable-model-invocation'] !== 'boolean') {
+    fail('disable-model-invocation must be a boolean');
+  }
+  // `user-invocable` is deliberately NOT a hard fail on a non-boolean: a quoted
+  // or cased value (`"true"`, `True`) used to crash this generator while the
+  // Cursor and Pi generators emitted a wrapper for it and the counters ignored
+  // it — four readings of one key. `isUserInvocableValue` is now the single
+  // normaliser; a value it cannot read as `true` demotes the skill (with its own
+  // WARN for the truthy-looking cases) instead of stopping the build.
+  if (Object.hasOwn(fm, 'user-invocable')
+    && typeof fm['user-invocable'] !== 'boolean'
+    && typeof fm['user-invocable'] !== 'string') {
+    fail('user-invocable must be a boolean (or the string form `"true"`/`"false"`)');
   }
   for (const key of ['argument-hint', 'license', 'compatibility']) {
     if (Object.hasOwn(fm, key) && typeof fm[key] !== 'string') fail(`${key} must be a string`);
@@ -42,6 +54,19 @@ function validateFrontmatter(fm, name, path) {
   }
 }
 
+/**
+ * The repo-wide marker for "operator-facing slash command" — delegated to
+ * `isUserInvocableValue`, the ONE normaliser, so this generator, the Cursor and
+ * Pi generators and the counters cannot disagree about a quoted or cased value.
+ *
+ * @param {Record<string, unknown>} fm
+ * @param {string} [path] named in the shared WARN when a truthy-looking value is demoted
+ * @returns {boolean}
+ */
+function isUserInvocable(fm, path) {
+  return isUserInvocableValue(fm?.['user-invocable'], path);
+}
+
 /** Existing native policy is meaningful; Claude's user-invocable flag is not a substitute. */
 function readNativePolicy(root, name) {
   const path = `skills/${name}/agents/openai.yaml`;
@@ -80,7 +105,14 @@ function readSources(root) {
       try { fm = yaml.load(match[1], { schema: yaml.CORE_SCHEMA }); }
       catch (error) { throw new Error(`${path}: invalid YAML: ${error.message}`, { cause: error }); }
       validateFrontmatter(fm, name, path);
-      sources.push({ name, path, command, fm, policy: command ? fm['disable-model-invocation'] !== true : readNativePolicy(root, name) });
+      // Policy precedence for a skill: a native `agents/openai.yaml` wins; else
+      // an explicitly user-invocable skill (a slash command that used to be a
+      // `commands/*.md` file) derives it from `disable-model-invocation` exactly
+      // as command sources do; a library skill emits no policy.
+      const policy = command
+        ? fm['disable-model-invocation'] !== true
+        : (readNativePolicy(root, name) ?? (isUserInvocable(fm, path) ? fm['disable-model-invocation'] !== true : undefined));
+      sources.push({ name, path, command, fm, policy });
     }
   }
   return sources;
@@ -128,9 +160,21 @@ function renderSkill(source, warnings) {
     '',
     'Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.',
   ];
-  if (source.command) lines.push(
+  // `$ARGUMENTS` semantics belong to every OPERATOR-FACING document — a
+  // `commands/*.md`, and equally a skill that declares `user-invocable: true`
+  // and references `$ARGUMENTS` in its own body. Gating them on `source.command`
+  // alone silently dropped the argument-handling contract from every command
+  // body that was folded into its same-named skill.
+  if (source.command || isUserInvocable(source.fm)) lines.push(
     '',
     '`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. When the workflow needs a command, pass its arguments through structured tool parameters or safely quoted individual arguments.',
+  );
+  // The redispatch warning is only TRUE for a command source: it exists because
+  // a same-named command and internal skill are two distinct documents. A
+  // user-invocable SKILL is already the canonical document, so telling it not to
+  // redispatch "the public command adapter" would describe a file that does not
+  // exist.
+  if (source.command) lines.push(
     '',
     'Read the full command before invoking an internal skill. An instruction to invoke a skill (including `session-orchestrator:<name>` or the `Skill` tool) means read and follow the canonical `skills/<name>/SKILL.md` beneath the plugin root. Do not redispatch the public command adapter: a same-named command and internal skill are distinct documents, and redispatch would recurse.',
   );