session-orchestrator 5.1.0 → 5.3.0

package/hooks/wave-scope-commit-guard.mjs

@@ -41,63 +41,7 @@ import { join } from 'node:path';
 // consumer repo or a test tmp-dir.
 import { pathMatchesPattern, findScopeFile } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
-
-const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-// #801: resolve wave-scope.json via the same precedence every other reader
-// uses (.pi/.cursor/.codex/.claude — scope-gate.mjs findScopeFile). The prior
-// hardcoded `.orchestrator/wave-scope.json` path was DEAD — the coordinator
-// writes wave-scope.json to the state dir (.claude/ on Claude Code; see
-// skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
-// returns null when no scope file exists at any precedence dir, preserving
-// the "no active wave → exit 0" semantics below.
-const scopePath = findScopeFile(repoRoot);
-const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
-
-// ---------------------------------------------------------------------------
-// Sub-mode B — allowedPaths check
-// ---------------------------------------------------------------------------
-
-const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
-const stagedFiles = stagedOutput.split('\n').filter(Boolean);
-
-if (scopePath) {
-  let scope;
-  try {
-    scope = JSON.parse(readFileSync(scopePath, 'utf8'));
-  } catch (err) {
-    process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
-    process.exit(1);
-  }
-
-  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
-  if (allowedPaths.length > 0) {
-    const violations = stagedFiles.filter(
-      (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
-    );
-
-    if (violations.length > 0) {
-      process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
-      for (const v of violations) process.stderr.write(`  - ${v}\n`);
-      process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
-      process.stderr.write('To proceed:\n');
-      process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
-      process.stderr.write('  2) git commit                    # retry\n');
-      process.exit(1);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Sub-mode C — cross-agent staging-fence reconciliation (issue #552)
-// ---------------------------------------------------------------------------
-//
-// Skip entirely when no fence dir exists OR no staged files. The fence dir
-// only appears when a wave-agent invoked `git add` while SO_WAVE_AGENT=1.
-// Manual / coordinator commits never write a fence file, so this branch
-// short-circuits to exit 0 for them (AC5 safe-default).
-if (!existsSync(fenceDir) || stagedFiles.length === 0) {
-  process.exit(0);
-}
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // Resolve the "current" agent id from SO_WAVE_AGENT_ID (when set by the
 // caller) or fall back to a PID-derived marker. The fence files themselves
@@ -105,11 +49,20 @@ if (!existsSync(fenceDir) || stagedFiles.length === 0) {
 // fence entries (we cross-check against SIBLINGS, not ourselves).
 const ownAgentId = process.env.SO_WAVE_AGENT_ID ?? null;
 
+/**
+ * Recorded by the writer when a staging command stages a set no path operand
+ * names (`git add -A`, `git add .`, `git add -u`). Overlaps everything.
+ * Mirrors ALL_PATHS_MARKER in hooks/pre-bash-staging-fence.mjs.
+ */
+const ALL_PATHS_MARKER = '*';
+
 /**
  * Build a regex that finds a staged path inside a `git add` command string.
  * Word-boundary on both sides so `src/foo.ts` does not match `src/foo.ts.bak`.
  * The path is escaped so glob metacharacters (`*`, `?`) and shell metas
  * cannot be reinterpreted.
+ *
+ * LEGACY PATH ONLY since #1404 — see the fallback branch in findOverlaps.
  */
 function pathRegex(p) {
   const escaped = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -117,8 +70,56 @@ function pathRegex(p) {
 }
 
 /**
- * Walk a single sibling fence file and return the staged paths whose path
- * pattern matches any of our staged files.
+ * Normalise a path token so reader and writer compare the same spelling.
+ *
+ * DELIBERATE DUPLICATE of the identically-named function in
+ * hooks/pre-bash-staging-fence.mjs: this guard is a husky pre-commit hook
+ * outside the Claude-Code hook import set, and the two sides must agree byte
+ * for byte. Change one, change both.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeStagedPath(raw) {
+  let p = String(raw).trim();
+  while (p.startsWith('./')) p = p.slice(2);
+  p = p.replace(/\/{2,}/g, '/');
+  while (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+  return p;
+}
+
+/**
+ * Does a path a sibling recorded overlap one of OUR staged files? Both sides
+ * arrive already normalised. A DIRECTORY entry overlaps every file beneath it
+ * (`src` overlaps `src/foo.ts`); the marker overlaps everything.
+ *
+ * @param {string} fencePath
+ * @param {string} ourPath
+ * @returns {boolean}
+ */
+function pathsOverlap(fencePath, ourPath) {
+  if (fencePath === ALL_PATHS_MARKER) return true;
+  if (fencePath === ourPath) return true;
+  return ourPath.startsWith(`${fencePath}/`);
+}
+
+/**
+ * Walk a single sibling fence file and return the staged paths a sibling
+ * agent also recorded an intent to stage.
+ *
+ * Two entry shapes are accepted:
+ *  - #1404 shape `{ paths, command_hash, timestamp }` — path LISTS compared
+ *    against our staged set.
+ *  - LEGACY shape `{ command, timestamp }` — a fence file written by a
+ *    pre-#1404 hook version. Live sessions on this host may hold such files
+ *    RIGHT NOW, and dropping them would read as "no overlap" — silently
+ *    weaker than before the change. So the old raw-command regex still runs
+ *    for an entry that has `command` and no `paths`.
+ *    NAMED CEILING (BV-004): this fallback exists only to span the sessions
+ *    running across the upgrade. REVISIT TRIGGER — remove it one minor
+ *    release after 5.3.0 (i.e. in 5.4.0), by which point no process started
+ *    before the upgrade can still be writing fence files. The command text it
+ *    reads is never PRINTED (issue #1404) — only the fact of the match is.
  */
 function findOverlaps(fenceJsonPath, ourStaged) {
   let body;
@@ -131,61 +132,157 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   if (!Array.isArray(body.staged_paths)) return [];
   if (ownAgentId && body.agent_id === ownAgentId) return []; // skip self
 
+  const siblingAgent = body.agent_id ?? '<unknown>';
   const matches = [];
   for (const entry of body.staged_paths) {
+    if (Array.isArray(entry?.paths)) {
+      const hash = typeof entry.command_hash === 'string' ? entry.command_hash : '<no-hash>';
+      for (const raw of entry.paths) {
+        if (typeof raw !== 'string') continue;
+        const fencePath = normalizeStagedPath(raw);
+        for (const ours of ourStaged) {
+          if (pathsOverlap(fencePath, normalizeStagedPath(ours))) {
+            matches.push({ ourPath: ours, siblingAgent, fencePath, hash });
+          }
+        }
+      }
+      continue;
+    }
+
     const cmd = entry?.command;
     if (typeof cmd !== 'string') continue;
     for (const ours of ourStaged) {
       if (pathRegex(ours).test(cmd)) {
-        matches.push({ ourPath: ours, siblingAgent: body.agent_id ?? '<unknown>', cmd });
+        matches.push({
+          ourPath: ours,
+          siblingAgent,
+          fencePath: '<legacy entry, pre-#1404>',
+          hash: '<legacy entry, pre-#1404>',
+        });
       }
     }
   }
   return matches;
 }
 
-let overlaps = [];
-
-try {
-  await withStagingFenceLock(
-    repoRoot,
-    async () => {
-      let entries;
-      try {
-        entries = readdirSync(fenceDir);
-      } catch {
-        return;
-      }
-      for (const name of entries) {
-        if (!name.endsWith('.json')) continue;
-        if (name.startsWith('.')) continue; // skip .commit.lock, tmp files
-        const overlapsFromFile = findOverlaps(join(fenceDir, name), stagedFiles);
-        overlaps = overlaps.concat(overlapsFromFile);
+/**
+ * Both sub-modes, in the order the pre-commit hook needs them. Every statement
+ * here used to sit at module top level, which meant a bare `import()` of this
+ * file ran `git rev-parse` / `git diff --cached` and could exit the IMPORTING
+ * process with 1 (#1393). Moved into a function so the entry guard below can
+ * gate it; the logic and its exit codes are unchanged.
+ */
+async function main() {
+  const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+  // #801: resolve wave-scope.json via the same precedence every other reader
+  // uses (.pi/.cursor/.codex/.claude — scope-gate.mjs findScopeFile). The prior
+  // hardcoded `.orchestrator/wave-scope.json` path was DEAD — the coordinator
+  // writes wave-scope.json to the state dir (.claude/ on Claude Code; see
+  // skills/wave-executor/wave-loop.md), so this guard never fired. findScopeFile
+  // returns null when no scope file exists at any precedence dir, preserving
+  // the "no active wave → exit 0" semantics below.
+  const scopePath = findScopeFile(repoRoot);
+  const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
+
+  // -------------------------------------------------------------------------
+  // Sub-mode B — allowedPaths check
+  // -------------------------------------------------------------------------
+
+  const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+  const stagedFiles = stagedOutput.split('\n').filter(Boolean);
+
+  if (scopePath) {
+    let scope;
+    try {
+      scope = JSON.parse(readFileSync(scopePath, 'utf8'));
+    } catch (err) {
+      process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
+      process.exit(1);
+    }
+
+    const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+    if (allowedPaths.length > 0) {
+      const violations = stagedFiles.filter(
+        (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
+      );
+
+      if (violations.length > 0) {
+        process.stderr.write('✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:\n');
+        for (const v of violations) process.stderr.write(`  - ${v}\n`);
+        process.stderr.write('\nThese files were likely added by lint-staged eslint --fix / prettier --write.\n');
+        process.stderr.write('To proceed:\n');
+        process.stderr.write('  1) git restore --staged <path>   # for each foreign path\n');
+        process.stderr.write('  2) git commit                    # retry\n');
+        process.exit(1);
       }
-    },
-    { timeoutMs: 5000 },
-  );
-} catch (err) {
-  // Lock acquisition failed — emit a warning but do NOT block the commit.
-  // The race-detection layer is opportunistic; a lock-acquire timeout is
-  // strictly less severe than blocking a legitimate commit on flaky FS.
-  process.stderr.write(
-    `⚠ wave-scope-commit-guard: staging-fence lock failed — ${err?.message ?? err}\n`,
-  );
-  process.exit(0);
-}
+    }
+  }
 
-if (overlaps.length > 0) {
-  process.stderr.write('✗ wave-scope-commit-guard: staging-fence: cross-agent overlap detected:\n');
-  for (const o of overlaps) {
-    process.stderr.write(`  - ${o.ourPath} (also staged by sibling agent ${o.siblingAgent})\n`);
+  // -------------------------------------------------------------------------
+  // Sub-mode C — cross-agent staging-fence reconciliation (issue #552)
+  // -------------------------------------------------------------------------
+  //
+  // Skip entirely when no fence dir exists OR no staged files. The fence dir
+  // only appears when a wave-agent invoked `git add` while SO_WAVE_AGENT=1.
+  // Manual / coordinator commits never write a fence file, so this branch
+  // short-circuits to exit 0 for them (AC5 safe-default).
+  if (!existsSync(fenceDir) || stagedFiles.length === 0) {
+    process.exit(0);
   }
-  process.stderr.write('\nAnother wave-agent recorded a `git add` for one or more of your staged paths.\n');
-  process.stderr.write('To proceed:\n');
-  process.stderr.write('  1) Coordinate with the sibling agent OR\n');
-  process.stderr.write('  2) git restore --staged <path>   # for each conflicting path, then retry\n');
-  process.stderr.write('  3) git commit --no-verify        # bypass (PSA-001/PSA-003 risk — operator opt-out)\n');
-  process.exit(1);
+
+  let overlaps = [];
+
+  try {
+    await withStagingFenceLock(
+      repoRoot,
+      async () => {
+        let entries;
+        try {
+          entries = readdirSync(fenceDir);
+        } catch {
+          return;
+        }
+        for (const name of entries) {
+          if (!name.endsWith('.json')) continue;
+          if (name.startsWith('.')) continue; // skip .commit.lock, tmp files
+          const overlapsFromFile = findOverlaps(join(fenceDir, name), stagedFiles);
+          overlaps = overlaps.concat(overlapsFromFile);
+        }
+      },
+      { timeoutMs: 5000 },
+    );
+  } catch (err) {
+    // Lock acquisition failed — emit a warning but do NOT block the commit.
+    // The race-detection layer is opportunistic; a lock-acquire timeout is
+    // strictly less severe than blocking a legitimate commit on flaky FS.
+    process.stderr.write(
+      `⚠ wave-scope-commit-guard: staging-fence lock failed — ${err?.message ?? err}\n`,
+    );
+    process.exit(0);
+  }
+
+  if (overlaps.length > 0) {
+    process.stderr.write('✗ wave-scope-commit-guard: staging-fence: cross-agent overlap detected:\n');
+    for (const o of overlaps) {
+      process.stderr.write(
+        `  - ${o.ourPath} (sibling agent ${o.siblingAgent} recorded ${o.fencePath}, command ${o.hash})\n`,
+      );
+    }
+    process.stderr.write('\nAnother wave-agent recorded a `git add` for one or more of your staged paths.\n');
+    process.stderr.write('To proceed:\n');
+    process.stderr.write('  1) Coordinate with the sibling agent OR\n');
+    process.stderr.write('  2) git restore --staged <path>   # for each conflicting path, then retry\n');
+    process.stderr.write('  3) git commit --no-verify        # bypass (PSA-001/PSA-003 risk — operator opt-out)\n');
+    process.exit(1);
+  }
+
+  process.exit(0);
 }
 
-process.exit(0);
+// Entry guard (#1393): run only as the node script `.husky/pre-commit` execs —
+// a bare `import()` must run no git command and must not exit the importing
+// process. No shouldRunHook gate here: this file is NOT registered in
+// hooks/hooks.json, so the profile-gate never governed it.
+if (isMainModule(import.meta.url)) {
+  await main();
+}

package/monitors/monitors.json

@@ -2,7 +2,7 @@
   {
     "name": "ecosystem-health",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/ecosystem-health.mjs --watch",
-    "description": "Ecosystem repo health watcher (CI status, branch drift, stale baselines across vault-registered projects). Emits one NDJSON line per detected state change. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
+    "description": "Local state-file watcher: every 900 s it stats and reads ONE file, .orchestrator/metrics/ecosystem-health.jsonl under the plugin root, and emits one NDJSON line per change (appeared / disappeared / changed). No network, no CI or branch probing, no repo enumeration, no Session Config read. Nothing writes that file yet (0 writers, measured 2026-09-18), so every run emits `no-state-yet` and idles until SIGTERM — ceiling and revisit trigger at DEFAULT_INTERVAL_S in scripts/lib/ecosystem-health.mjs. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
     "when": "on-skill-invoke:session-start"
   },
   {

package/output-styles/wave-summary.md

@@ -32,7 +32,7 @@ Only include if the plan changed:
 
 - One table row per agent — no nested details
 - Status is exactly one of: `done`, `partial`, `failed`
-- File lists use short relative paths (e.g., `hooks/on-stop.sh`)
+- File lists use short relative paths (e.g., `hooks/on-stop.mjs`)
 - Quality gates are pass/fail — no ambiguity
 - Adaptations only when deviating from plan — omit if on track
 - Keep under 20 lines total

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -57,6 +57,7 @@
     "test": "node scripts/check-package-manager.mjs && vitest --run",
     "test:coverage": "node scripts/check-package-manager.mjs && vitest --run --coverage",
     "test:watch": "node scripts/check-package-manager.mjs && vitest",
+    "test:pack": "node scripts/check-package-manager.mjs && SO_PACK_TEST=1 vitest --run tests/scripts/pack-install-lifecycle.test.mjs",
     "quality-gate": "node scripts/run-quality-gate.mjs --variant full-gate",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/pi/prompts/autopilot.md

@@ -1,12 +1,12 @@
 ---
-description: Autonomous session-orchestration loop with kill-switches (Phase C-1.b — all 10 kill-switches shipped)
+description: "Use this skill when running an autonomous session-orchestration loop. Chains session-start → session-plan → wave-executor → session-end for N iterations with all 10 kill-switches (SPIRAL, FAILED wave, carryover > 50%, max-hours, max-sessions, resource-overload, token-budget, stall-timeout, sub-threshold confidence, user-abort). Reads Mode-Selector output (Phase B) to decide auto-execute vs. fallback. Writes one autopilot.jsonl record per loop run. Phase C scaffold (issue #277); implementation lives in scripts/lib/autopilot.mjs (Phase C-1 follow-up)."
 argument-hint: "[--headless] [--verbose] [--max-sessions=N] [--max-hours=H] [--confidence-threshold=0.X] [--dry-run]"
 ---
 
 # /autopilot
 
-Use the Session Orchestrator command definition at `commands/autopilot.md`.
+Use the Session Orchestrator skill definition at `skills/autopilot/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/bootstrap.md

@@ -1,12 +1,12 @@
 ---
-description: Scaffold the minimum repo structure required by session-orchestrator
+description: "Use this skill when scaffolding the minimum repository structure required by session-orchestrator. Invoked automatically by the Bootstrap Gate when CLAUDE.md, Session Config, or bootstrap.lock is missing. Also available as /bootstrap for manual invocation. Three intensity tiers: fast (demos/spikes), standard (MVPs), deep (production/team)."
 argument-hint: "[--upgrade <tier>]"
 ---
 
 # /bootstrap
 
-Use the Session Orchestrator command definition at `commands/bootstrap.md`.
+Use the Session Orchestrator skill definition at `skills/bootstrap/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/brainstorm.md

@@ -1,12 +1,12 @@
 ---
-description: Run a lightweight Socratic design dialogue (3-5 AUQ rounds) and write a spec markdown file before any implementation work. Use BEFORE /plan feature when scope/UX is ambiguous.
+description: "Use when you have a feature idea but the scope or UX is still ambiguous — runs a lightweight Socratic design dialogue (3-5 AUQ rounds) and writes a spec markdown file. Use BEFORE /plan feature when product intent needs validation; skip to /plan feature when scope is already clear. HARD-GATE prevents any code work until the design is user-approved."
 argument-hint: "[topic-or-feature-slug]"
 ---
 
 # /brainstorm
 
-Use the Session Orchestrator command definition at `commands/brainstorm.md`.
+Use the Session Orchestrator skill definition at `skills/brainstorm/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/close.md

@@ -4,8 +4,8 @@ description: End session with verification, commits, and documentation
 
 # /close
 
-Use the Session Orchestrator command definition at `commands/close.md`.
+Use the Session Orchestrator skill definition at `skills/close/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/debug.md

@@ -1,12 +1,12 @@
 ---
-description: Run a 4-phase systematic debugging investigation before proposing any fix. Iron Law — NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference.
+description: "Use when encountering any bug, test failure, build break, or unexpected behavior — runs a 4-phase systematic debugging process before proposing any fix. Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Produces a `.orchestrator/debug/` artifact the fixer agent must reference."
 argument-hint: "[bug-description-or-issue-ref]"
 ---
 
 # /debug
 
-Use the Session Orchestrator command definition at `commands/debug.md`.
+Use the Session Orchestrator skill definition at `skills/debug/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/discovery.md

@@ -1,12 +1,12 @@
 ---
-description: Systematic quality discovery and issue detection
+description: "Use this skill when running systematic quality discovery and issue detection. Runs modular probes adapted to the project's tech stack, presents findings interactively for user triage, and creates VCS issues for confirmed problems. Invoked standalone via /discovery or embedded in session-end."
 argument-hint: "[all|code|infra|ui|arch|session|audit|vault|feature] [--since <git-ref>] [--full]"
 ---
 
 # /discovery
 
-Use the Session Orchestrator command definition at `commands/discovery.md`.
+Use the Session Orchestrator skill definition at `skills/discovery/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/dispatcher.md

@@ -1,12 +1,12 @@
 ---
-description: Pick the next-best repo to work on across the portfolio — rank free repos, recommend one, claim its lease atomically, and route to the entry command
+description: "Use when you want the orchestrator to pick the next repo to work on across your whole portfolio — it enumerates candidate repos below the confinement root, resolves free/busy from each repo's session.lock lease, ranks the FREE ones by backlog priority × staleness × readiness, recommends the single most worthwhile one via AskUserQuestion, atomically claims it, and routes you to the chosen entry command. Triggers: \"what should I work on next\", \"dispatch me to a repo\", \"pick the next project\", \"run /dispatcher\". <example>Context: operator finished a session and wants the next-best repo across the portfolio. user: \"/dispatcher\" assistant: \"Ranked 18 free repos — top recommendation: Pencil-Designs (score 4.50, 90d stale). Confirm via the picker, I'll claim its lease atomically, then route you to /session deep.\"</example>"
 argument-hint: "[--dry-run] [--repo <name>]"
 ---
 
 # /dispatcher
 
-Use the Session Orchestrator command definition at `commands/dispatcher.md`.
+Use the Session Orchestrator skill definition at `skills/dispatcher/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/eli5.md

@@ -1,12 +1,12 @@
 ---
-description: Say the last answer again in plain words — same facts, in the order the operator needs them. Optional topic argument.
+description: "Explain a topic like I'm a 5 year old — restate my last output, or a named topic, in plain words without dropping a single fact. Use when the user types /eli5 [topic], or says an answer was too technical, too long, or unclear about what he now has to do."
 argument-hint: "[topic]"
 ---
 
 # /eli5
 
-Use the Session Orchestrator command definition at `commands/eli5.md`.
+Use the Session Orchestrator skill definition at `skills/eli5/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/eval.md

@@ -1,12 +1,12 @@
 ---
-description: Run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed session against the pre-registered rubric-v1 dimensions
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 
 # /eval
 
-Use the Session Orchestrator command definition at `commands/eval.md`.
+Use the Session Orchestrator skill definition at `skills/eval/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/evolve.md

@@ -1,12 +1,12 @@
 ---
-description: Extract session patterns into reusable learnings
+description: "Use this skill when extracting session patterns into reusable learnings. Three modes: analyze (extract from session history), review (edit/manage existing learnings), list (display active learnings). Manages .orchestrator/metrics/learnings.jsonl."
 argument-hint: "[analyze|review|list|dialectic [--apply]]"
 ---
 
 # /evolve
 
-Use the Session Orchestrator command definition at `commands/evolve.md`.
+Use the Session Orchestrator skill definition at `skills/evolve/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/go.md

@@ -5,8 +5,8 @@ argument-hint: "[optional instructions]"
 
 # /go
 
-Use the Session Orchestrator command definition at `commands/go.md`.
+Use the Session Orchestrator skill definition at `skills/go/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/grill.md

@@ -1,12 +1,12 @@
 ---
-description: Stress-test a plan, design, or PRD before any build — relentless one-question-at-a-time interrogation that hunts contradictions against the code and challenges assumptions. Composable; no HARD-GATE.
+description: "Use when the user wants a plan, design, or PRD stress-tested before any build — relentlessly interrogates one decision at a time, grounds every question in the codebase, hunts contradictions against the domain language and the code, and challenges the load-bearing assumptions. Triggered by \"grill me\", \"stress-test this plan\", \"poke holes in my design\". Composable — run standalone or as an adversarial pass before /plan feature."
 argument-hint: "[file-path-or-topic]"
 ---
 
 # /grill
 
-Use the Session Orchestrator command definition at `commands/grill.md`.
+Use the Session Orchestrator skill definition at `skills/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/pi/prompts/harness-audit.md

@@ -1,12 +1,11 @@
 ---
 description: Run the harness audit and report the rubric score for this repository
-argument-hint: ""
 ---
 
 # /harness-audit
 
-Use the Session Orchestrator command definition at `commands/harness-audit.md`.
+Use the Session Orchestrator skill definition at `skills/harness-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/memory-cleanup.md

@@ -1,12 +1,12 @@
 ---
-description: Manual memory consolidation — review, consolidate, and prune memory files (Dream-equivalent)
+description: "Use this skill when performing manual memory consolidation (Dream-equivalent). Reviews, consolidates, and prunes memory files under ~/.claude/projects/*/memory/. Run after major refactors, every 5+ sessions, or when memory quality degrades (broken links, stale references, contradictions, MEMORY.md > 200 lines). Invoke with /memory-cleanup."
 argument-hint: "[--dry-run | --apply-pending]"
 ---
 
 # /memory-cleanup
 
-Use the Session Orchestrator command definition at `commands/memory-cleanup.md`.
+Use the Session Orchestrator skill definition at `skills/memory-cleanup/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/persona-panel.md

@@ -1,12 +1,12 @@
 ---
-description: Run a parallel multi-persona domain-expert review panel against a file, directory, or output range
+description: "Use this skill when you need multi-persona parallel content review — domain experts, buyer personas, compliance reviewers, or custom catalog entries reviewing a target file or output. Dispatches N persona agents in parallel, consolidates verdicts via a configurable mode (voting-quorum, hard-gate-threshold, or coordinator-summary), and writes a timestamped sidecar to .orchestrator/persona-panel/. Invoked via /persona-panel <target-path>."
 argument-hint: "<target> [--personas <names,...>] [--mode <voting|hard-gate|summary>] [--threshold <M-of-N|all|any>] [--grounding <off|re-derive>] [--dry-run]"
 ---
 
 # /persona-panel
 
-Use the Session Orchestrator command definition at `commands/persona-panel.md`.
+Use the Session Orchestrator skill definition at `skills/persona-panel/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.