session-orchestrator 5.1.0 → 5.2.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -230,6 +230,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 /** @type {typeof import('../scripts/lib/io.mjs').emitWarn} */ let emitWarn;
 /** @type {typeof import('../scripts/lib/io.mjs').writeJsonAtomicSync} */ let writeJsonAtomicSync;
 /** @type {typeof import('../scripts/lib/file-lock.mjs').withFileLock} */ let withFileLock;
+/** @type {typeof import('../scripts/lib/scope-echo.mjs').scopeDigest} */ let scopeDigest;
 let findScopeCollisions;
 
 const PLUGIN_ROOT = path.resolve(import.meta.dirname, '..');
@@ -287,6 +288,25 @@ const SHAPE_NONE = 'none';
 /** The per-dispatch observability record (#1092) — see § Observability. */
 const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
 
+/**
+ * The receive-side instruction line `renderScopeEchoInstruction()` renders and
+ * the coordinator appends immediately after the fenced block
+ * (`wave-loop-dispatch.md` § Pre-Dispatch: File-Scope Injection).
+ *
+ * Matching it HERE, in the same prompt, is what makes the agent-A-block-with-
+ * agent-B-line mix-up catchable without a single filesystem read: the block and
+ * the line must come from the same `$AGENT_FILESCOPE_JSON`, so their digests
+ * must agree (`digest_consistent`). The marker half stays case-sensitive for the
+ * same reason `scope-echo.mjs` keeps it so — a lowercase lookalike is not the
+ * line; the HEX half is read case-insensitively and normalised to lowercase.
+ * Non-global on purpose: a `g` regex carries `lastIndex` between calls.
+ */
+const ECHO_INSTRUCTION_RE =
+  /End your final report with the line:[ \t]*`{0,3}SCOPE-DIGEST:[ \t]*`{0,3}([0-9a-fA-F]{8})(?![0-9a-fA-F])/;
+
+/** Shape of a well-formed digest, used to reject anything a broken digest fn returns. */
+const DIGEST_RE = /^[0-9a-f]{8}$/;
+
 /**
  * Clamp for the one free-form string the event carries (`agent_id`, built from
  * the coordinator's own `description`). A dispatch description is a label, but
@@ -358,6 +378,14 @@ async function bootstrap() {
       io: { specifier: lib('io.mjs') },
       scopeGate: { specifier: lib('scope-gate.mjs') },
       fileLock: { specifier: lib('file-lock.mjs') },
+      // ONE normalization for the digest, shared with the receive side (#1092):
+      // `scope-echo.mjs` is pure (stdlib + `crypto-digest-utils.mjs`) and its
+      // `scopeDigest` is what `--verify` joins the two halves on. A second
+      // implementation here would let the halves disagree while both looked
+      // right — the class `guard-design.md` § "zero-import predicate module"
+      // names. Late-bound like every other repo module so a load failure
+      // banners instead of disarming the guard silently (#993).
+      scopeEcho: { specifier: lib('scope-echo.mjs') },
     },
     {
       hookName: HOOK_NAME,
@@ -370,6 +398,7 @@ async function bootstrap() {
   ({ readStdin, emitAllow, emitDeny, emitWarn, writeJsonAtomicSync } = modules.io);
   ({ findScopeCollisions } = modules.scopeGate);
   ({ withFileLock } = modules.fileLock);
+  ({ scopeDigest } = modules.scopeEcho);
 }
 
 // ---------------------------------------------------------------------------
@@ -407,8 +436,51 @@ const SCOPE_TERMS = 'DATEI[- ]SCOPE|FILE[- ]SCOPE|FILE SCOPE|DEIN SCOPE|SCOPE \\
  * hit in a region as one is the recorded failure of `parseEpicRef` (#1112).
  *
  * The real miss class is a different SHAPE, handled by {@link INLINE_SCOPE_DECL}.
+ *
+ * ## The marker vocabulary is CASE-SENSITIVE, and that is a measurement (#1092)
+ *
+ * Until 2026-09-16 both shapes carried the `i` flag, so the term `FILE SCOPE`
+ * also matched ordinary lowercase prose. The Learnings-Index header this repo
+ * injects into every agent prompt —
+ * `## Learnings Index (selected for your file scope) — …` — therefore matched
+ * the marker at column ~38 of a line-leading window, and the FIRST fenced block
+ * anywhere after it (a verification command, a report template) decided the
+ * class: no path survived, so the dispatch was recorded `unparseable`, i.e.
+ * matrix row 6 — "a declaration is present but the parser gave up".
+ *
+ * MEASURED in this session's own wave 1 (`.orchestrator/wave-dispatch-scopes.json`,
+ * waveKey `5de6560c-…|w1|Discovery`): `unparseable: 5, extracted: 0` for FIVE
+ * Discovery dispatches that carried no `FILE-SCOPE` block at all. Host-wide the
+ * same confusion accounts for the 52 historical `unparseable` records.
+ *
+ * Every DOCUMENTED marker is upper-case (`wave-loop-dispatch.md` § Pre-Dispatch:
+ * File-Scope Injection writes `FILE-SCOPE — exactly these:`), while every
+ * measured false positive is prose in sentence case — so dropping `i` separates
+ * them without narrowing the search window, which the § above showed recovers
+ * nothing.
+ *
+ * ## What dropping `i` costs, stated honestly (corrected 2026-09-16)
+ *
+ * The first cut of this note claimed the change "moves a CLASSIFICATION and
+ * never a decision", on the grounds that `marker-absent` and `unparseable` both
+ * resolve to ALLOW. That is only true for a declaration the parser would have
+ * given up on anyway. A MIXED-CASE declaration that WOULD have yielded paths
+ * (`File-Scope:` followed by a fenced path list) now matches nothing, so
+ * `extractScopeFromPrompt` returns `[]`, `findScopeCollisions` never runs, and
+ * the dispatch is ALLOWED unconditionally — a lost DENY capability for that
+ * spelling, i.e. a decision change, not a reclassification.
+ *
+ * It is safe today because every LIVE injector writes the upper-case canonical
+ * marker: `skills/wave-executor/references/wave-loop-dispatch.md`
+ * § Pre-Dispatch: File-Scope Injection documents `FILE-SCOPE — exactly these:`,
+ * and the repo-wide census (2026-09-16) finds the mixed-case spellings only in
+ * prose, never in an injected block. That is a property of the injectors, not of
+ * this regex, so it is PINNED rather than assumed:
+ * `tests/skills/wave-loop-scope-marker.test.mjs` asserts the documented marker
+ * line is upper-case and matches {@link SCOPE_MARKER}, so a future template edit
+ * to `File-Scope:` goes red instead of silently disarming the guard.
  */
-const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'im');
+export const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'm');
 
 /**
  * SHAPE 2 (lower precedence) — the measured miss class: a declaration written
@@ -436,7 +508,7 @@ const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'im');
  * one false extraction (`[".filter"]`) is a prose fragment, which is why the
  * fenced shape keeps precedence and this one runs only when that found nothing.
  */
-const INLINE_SCOPE_DECL = new RegExp(`(${SCOPE_TERMS})`, 'ig');
+const INLINE_SCOPE_DECL = new RegExp(`(${SCOPE_TERMS})`, 'g');
 const INLINE_DECL_OPERATOR = /^[^\n(:—–]{0,2}(\([^)\n]{0,80}\))?\s*(?:[—–][^\n:]{0,30})?\s*(:|—|–)/;
 
 /** Separators a coordinator uses between paths in an inline declaration. */
@@ -980,6 +1052,69 @@ export function bumpSignalCounter(ledger, waveKey, status) {
   return next;
 }
 
+/**
+ * The digest half of the per-dispatch record (#1092) — the field set that makes
+ * the SEND side joinable to the RECEIVE side.
+ *
+ * Four facts, all derived from the PROMPT alone, none of them a path:
+ *
+ *   `scope_digest`            — `scopeDigest()` over the paths extracted FROM THE
+ *                               PROMPT. This is the join key `scope-echo --verify`
+ *                               uses; `agent_id` cannot be one, because the two
+ *                               halves spell it differently (measured 2026-09-16:
+ *                               609 send-side vs 51 receive-side records, agent-id
+ *                               overlap ZERO — send writes
+ *                               `"i-3 #1353 … (session-orchestrator:code-implementer)"`,
+ *                               receive writes `"i-3"`).
+ *   `echo_instruction_present`— the coordinator appended the echo line at all.
+ *   `instructed_digest`       — the digest THAT LINE names.
+ *   `digest_consistent`       — the two agree. `false` is agent A's fenced block
+ *                               beside agent B's echo line, caught at dispatch
+ *                               time with no filesystem read.
+ *
+ * ABSENT IS NOT ZERO, in both directions (`docs/events-schema.md`):
+ * `scope_digest` is OMITTED for an empty scope — never the digest of the empty
+ * string, which is a real 8-hex value and would join marker-absent Discovery
+ * dispatches to each other. `instructed_digest` is omitted when no line was
+ * found, and `digest_consistent` unless BOTH are present.
+ *
+ * TOTAL by construction: every branch is wrapped, because this runs on the
+ * decision path of a deny-capable hook. A throwing digest function must cost the
+ * FIELD, never the verdict — same discipline as the awaited-and-caught emit.
+ *
+ * @param {string[]} files      paths extracted from the prompt
+ * @param {unknown} prompt      the dispatch prompt
+ * @param {((paths: string[]) => string)} [digestFn] injectable for tests; defaults
+ *   to the late-bound `scopeDigest` (undefined when `bootstrap()` has not run,
+ *   which this function treats exactly like a throwing one — the field is omitted)
+ * @returns {{scope_digest?: string, echo_instruction_present: boolean,
+ *            instructed_digest?: string, digest_consistent?: boolean}}
+ */
+export function scopeDigestFields(files, prompt, digestFn) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  try {
+    const fn = typeof digestFn === 'function' ? digestFn : scopeDigest;
+    if (typeof fn === 'function' && Array.isArray(files) && files.length > 0) {
+      const digest = fn(files);
+      if (typeof digest === 'string' && DIGEST_RE.test(digest)) out.scope_digest = digest;
+    }
+  } catch { /* a broken digest costs the field, never the decision */ }
+
+  let instructed = null;
+  try {
+    const match = typeof prompt === 'string' ? ECHO_INSTRUCTION_RE.exec(prompt) : null;
+    if (match !== null) instructed = match[1].toLowerCase();
+  } catch { instructed = null; }
+
+  out.echo_instruction_present = instructed !== null;
+  if (instructed !== null) out.instructed_digest = instructed;
+  if (typeof out.scope_digest === 'string' && instructed !== null) {
+    out.digest_consistent = out.scope_digest === instructed;
+  }
+  return /** @type {any} */ (out);
+}
+
 /**
  * @typedef {{action: 'allow'|'deny'|'warn', reason?: string, suggestion?: string,
  *            ledger?: object|null, note?: string, telemetry?: object}} Verdict
@@ -997,9 +1132,11 @@ export function bumpSignalCounter(ledger, waveKey, status) {
  * @param {Function} params.collide           `findScopeCollisions` (injected for testability)
  * @param {(entry: object) => boolean} [params.isFinished] liveness probe (§ Liveness)
  * @param {string} [params.nowIso]            dispatch timestamp recorded on the entry
+ * @param {(paths: string[]) => string} [params.digestFn] scope-digest function
+ *   (injected for testability; defaults to the late-bound `scopeDigest`)
  * @returns {Verdict}
  */
-export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso }) {
+export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn }) {
   const toolName = input?.tool_name;
   // Row 4: not our tool.
   if (toolName !== DISPATCH_TOOL) return { action: 'allow' };
@@ -1023,13 +1160,19 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   // agent id, never a path, never a byte of the prompt (issue #1092 acceptance
   // criterion 3). `wave` is omitted rather than zeroed when unknown.
   const wave = waveNumberOf(waveKey);
+  const digestFields = scopeDigestFields(files, toolInput.prompt, digestFn);
   const telemetryFor = (ledgerResult, collisionCount = 0) => ({
     ...(wave === null ? {} : { wave }),
     agent_id: id.slice(0, MAX_AGENT_ID_CHARS),
     declared_path_count: files.length,
     injected: files.length > 0,
+    // `marker_found` is NOT a second spelling of `injected`: a fenced block whose
+    // lines are prose is `marker_found: true, injected: false` (matrix row 6),
+    // which is the row-5-vs-row-6 split expressed as a boolean a query can group by.
+    marker_found: signal.status !== SIGNAL_MARKER_ABSENT,
     shape: signal.shape,
     signal: signal.status,
+    ...digestFields,
     ledger_result: ledgerResult,
     collision_count: collisionCount,
   });
@@ -1309,6 +1452,12 @@ async function main() {
 // symlinked plugin install) while `import.meta.url` is realpath-resolved by
 // node's default loader, so BOTH sides are realpath'd — the same comparison
 // `hooks/post-bash-write-verify.mjs` documents (#938 MED-2).
+//
+// NAMED CEILING (BV-004): kept inline rather than imported — hooks avoid
+// importing `scripts/lib` on the hot path, where every added module is paid on
+// every dispatch. The canonical predicate is `scripts/lib/is-main-module.mjs`;
+// revisit if this hook ever imports that tree for another reason, at which
+// point the copy costs more than the import saves.
 // ---------------------------------------------------------------------------
 function invokedAsScript() {
   const entry = process.argv[1];

package/hooks/skill-invocation-telemetry.mjs

@@ -37,6 +37,7 @@ import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
 import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
 import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
+import { isMainModule } from '../scripts/lib/is-main-module.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -209,7 +210,7 @@ async function main() {
 // Self-execution guard — run only when invoked directly (not when imported).
 // ---------------------------------------------------------------------------
 
-const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+const isMain =isMainModule(import.meta.url);
 if (isMain) {
   // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
   if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.1.0",
+  "version": "5.2.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/convergence-monitoring.md

@@ -0,0 +1,11 @@
+---
+description: "Monitor iterative improvement loops for convergence. Three signals — shrinking diff, pass-rate plateau, velocity — drive a Stop/Continue/Investigate decision at each inter-wave checkpoint. Distinct from /evolve (retrospective) and session-reviewer (wave output review): convergence-monitoring answers \"are we making progress?\" not \"was the last wave correct?\". Primary consumer: /autoresearch loops and wave-executor inter-wave checkpoints."
+---
+
+# /convergence-monitoring
+
+Use the Session Orchestrator skill definition at `skills/convergence-monitoring/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.

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-v1 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/npm-publish.md

@@ -0,0 +1,11 @@
+---
+description: "Use when publishing this package to npm — a version release (npm publish), verifying the registry/pi.dev listing, or diagnosing npm auth failures (E403 2FA/token errors). Token-based flow via NPM_TOKEN in .env.local with a temp userconfig, the leakage gate before every publish, post-publish verification and marker/badge upkeep. Trigger on \"publish to npm\", \"npm release\", \"E403 publish error\"."
+---
+
+# /npm-publish
+
+Use the Session Orchestrator skill definition at `skills/npm-publish/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.

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.

package/pi/prompts/plan.md

@@ -1,12 +1,12 @@
 ---
-description: Plan a new project, feature, or retrospective with structured requirement gathering
+description: "Use this skill when performing structured project planning and PRD generation with three modes: new (project kickoff with repo scaffolding), feature (compact feature PRD), retro (data-driven retrospective). All modes share a researched Q&A engine that dispatches parallel Explore agents before each question wave, presents options via AskUserQuestion with recommendations, and produces documents with prioritized issue creation."
 argument-hint: "[new|feature|retro]"
 ---
 
 # /plan
 
-Use the Session Orchestrator command definition at `commands/plan.md`.
+Use the Session Orchestrator skill definition at `skills/plan/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/portfolio.md

@@ -5,8 +5,8 @@ argument-hint: "[--dry-run] [--repo <name>]"
 
 # /portfolio
 
-Use the Session Orchestrator command definition at `commands/portfolio.md`.
+Use the Session Orchestrator skill definition at `skills/portfolio/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/reconcile.md

@@ -1,12 +1,12 @@
 ---
-description: Reconcile learnings into .claude/rules/ proposals — on-demand version of session-end Phase 3.6.8
+description: Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be generated from current session learnings. On-demand version of session-end Phase 3.6.8.
 argument-hint: "[--dry-run]"
 ---
 
 # /reconcile
 
-Use the Session Orchestrator command definition at `commands/reconcile.md`.
+Use the Session Orchestrator skill definition at `skills/reconcile/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/release.md

@@ -1,12 +1,12 @@
 ---
-description: Cut a release — the order the steps must run in, and the criteria that abort a release
+description: "Cut a release — the order the steps must run in, and the criteria that abort a release"
 argument-hint: "[X.Y.Z]"
 ---
 
 # /release
 
-Use the Session Orchestrator command definition at `commands/release.md`.
+Use the Session Orchestrator skill definition at `skills/release/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.