@siddicky/oh-my-musecode 0.1.0

package/scripts/preflight.mjs

@@ -0,0 +1,121 @@
+/**
+ * Pure escalation-preflight logic, separated from the installer so the
+ * security-relevant branches are testable without an enterprise config document.
+ *
+ * Enterprise policy can only arrive from a system file or macOS managed
+ * preferences, neither of which a test can create. Keeping the parsing pure means
+ * the "refuse to install" path is covered by tests rather than by hope.
+ *
+ * Every probe is three-valued — yes / no / unknown. An earlier version collapsed
+ * unknown into "available" and "policy absent", so a crashed or missing `muse`
+ * made the installer report a *more* permissive posture than reality. A safety
+ * preflight must fail closed, so an indeterminate probe now blocks installation
+ * rather than being read as good news.
+ */
+
+/** @typedef {'yes' | 'no' | 'unknown'} Tri */
+
+/**
+ * @typedef {object} ProbeResult
+ * @property {number | null} status exit code, or null if the process never ran
+ * @property {string | null} signal terminating signal, if any
+ * @property {string} output combined stdout + stderr
+ * @property {boolean} ran whether the process actually started
+ */
+
+/**
+ * Classifies whether named permission profiles are usable.
+ *
+ * @param {ProbeResult | null} probe
+ * @returns {Tri}
+ */
+export function namedProfilesAvailable(probe) {
+  if (!probe || !probe.ran || probe.signal) return 'unknown';
+
+  // An explicit refusal is a definite "no" whatever the exit code.
+  if (
+    /profile does not exist|permission profiles? .*(is |are )?unavailable|no permission profile/i.test(
+      probe.output,
+    )
+  ) {
+    return 'no';
+  }
+
+  // Anything other than a clean exit tells us nothing about the capability.
+  if (probe.status !== 0) return 'unknown';
+
+  return 'yes';
+}
+
+/**
+ * Parses `muse config status` output.
+ *
+ * @param {ProbeResult | null} probe
+ * @returns {{ policyPresent: Tri, sandboxBypassForbidden: Tri }}
+ */
+export function parseConfigStatus(probe) {
+  if (!probe || !probe.ran || probe.signal || probe.status !== 0 || !probe.output.trim()) {
+    return { policyPresent: 'unknown', sandboxBypassForbidden: 'unknown' };
+  }
+
+  // A recognisable status document must actually mention the planes; anything
+  // else is output we do not understand and must not interpret.
+  if (!/plane=(defaults|policy)\b/.test(probe.output)) {
+    return { policyPresent: 'unknown', sandboxBypassForbidden: 'unknown' };
+  }
+
+  const policyPresent = probe.output
+    .split('\n')
+    .some((line) => /plane=policy\b/.test(line) && !/\bstate=absent\b/.test(line));
+
+  if (!policyPresent) return { policyPresent: 'no', sandboxBypassForbidden: 'no' };
+
+  return {
+    policyPresent: 'yes',
+    sandboxBypassForbidden: /forbid_sandbox_bypass/i.test(probe.output) ? 'yes' : 'no',
+  };
+}
+
+/**
+ * Combines both probes into the verdict the installer acts on.
+ *
+ * `blocked` is true when installation must not proceed: either policy definitely
+ * forbids the only escalation route, or the posture could not be determined at
+ * all. `blockReason` explains which.
+ *
+ * @param {{ profileProbe: ProbeResult | null, configProbe: ProbeResult | null }} probes
+ */
+export function escalationVerdict({ profileProbe, configProbe }) {
+  const namedProfiles = namedProfilesAvailable(profileProbe);
+  const { policyPresent, sandboxBypassForbidden } = parseConfigStatus(configProbe);
+
+  const describe = {
+    yes: 'AVAILABLE',
+    no: 'unavailable on this build (cannot scope the escalation)',
+    unknown: 'UNKNOWN — could not determine (probe failed)',
+  };
+
+  const detail = [`named permission profiles: ${describe[namedProfiles]}`];
+  if (policyPresent === 'unknown') {
+    detail.push('enterprise policy: UNKNOWN — could not read `muse config status`');
+  } else if (policyPresent === 'no') {
+    detail.push('enterprise policy: absent (no forbid_sandbox_bypass lock)');
+  } else {
+    detail.push(
+      `enterprise policy: present${sandboxBypassForbidden === 'yes' ? ' and forbids sandbox bypass' : ''}`,
+    );
+  }
+
+  let blocked = false;
+  let blockReason = null;
+
+  if (sandboxBypassForbidden === 'yes') {
+    blocked = true;
+    blockReason = 'policy-forbids-bypass';
+  } else if (policyPresent === 'unknown' || namedProfiles === 'unknown') {
+    blocked = true;
+    blockReason = 'posture-undetermined';
+  }
+
+  return { namedProfiles, policyPresent, sandboxBypassForbidden, detail, blocked, blockReason };
+}

package/scripts/settings-install.mjs

@@ -0,0 +1,155 @@
+/**
+ * Delivery through muse settings, for builds where the plugins subsystem is off.
+ *
+ * muse 1.0.3-R2198.1 answers "plugins are not available in this build" to every
+ * `muse plugins` command, and a registered marketplace yields
+ * `{"skills":[],"diagnostics":[]}` — no discovery and no error. A plugin manifest
+ * alone therefore delivers nothing at all on this build.
+ *
+ * These routes were each verified to work instead:
+ *   - skills: `muse skills install --scope user` installs into $CONFIG_DIR/skills/
+ *   - hooks:  a `hooks` entry in $CONFIG_DIR/muse/settings.json genuinely fires
+ *             (a SessionStart hook configured this way ran and created .omm/)
+ *   - mcp:    an `mcpServers` entry in the same file is accepted
+ *
+ * The merge is deliberately conservative: it only touches keys it owns, so a
+ * hand-maintained settings.json survives installation intact.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * Identifies the entries this installer owns.
+ *
+ * Ownership is inferred from the command path rather than stamped with a marker
+ * field. An earlier version added `__owner` to each hook entry; muse rejected the
+ * unknown member and silently stopped loading the hook — no diagnostic, no error,
+ * the hook simply never fired. Settings documents only tolerate the members muse
+ * knows, so ownership has to be derived from what is already there.
+ */
+export const OWNER_TAG = 'oh-my-musecode';
+
+/**
+ * POSIX single-quote escaping for a path embedded in a shell command string.
+ *
+ * `JSON.stringify` is NOT shell quoting. Double quotes still permit command
+ * substitution, so a plugin root containing `$(...)` or backticks would execute
+ * when muse ran the hook — a checkout path is enough to get code execution.
+ * Single quotes suppress all expansion; the only character needing care is the
+ * single quote itself, closed and reopened around an escaped literal.
+ */
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+/** True when a hook command points at a script inside this plugin. */
+function commandBelongsTo(command, pluginRoot) {
+  return typeof command === 'string' && command.includes(join(pluginRoot, 'hooks'));
+}
+
+/** Builds the hook entries, rooted at an absolute plugin directory. */
+export function desiredHooks(pluginRoot) {
+  const hook = (script) => ({
+    type: 'command',
+    command: `node ${shellQuote(join(pluginRoot, 'hooks', script))}`,
+  });
+
+  return {
+    UserPromptSubmit: [{ hooks: [hook('user-prompt-submit.mjs')] }],
+    SessionStart: [{ hooks: [hook('session-start.mjs')] }],
+    Stop: [{ hooks: [hook('stop.mjs')] }],
+  };
+}
+
+/** Builds the MCP server entry. */
+export function desiredMcpServers(pluginRoot) {
+  return {
+    'omm-state': {
+      transport: 'stdio',
+      command: 'node',
+      args: [join(pluginRoot, 'dist', 'mcp', 'state-server.js')],
+    },
+  };
+}
+
+/** True when a settings hook group belongs to us. */
+function isOurs(group, pluginRoot) {
+  return (group?.hooks ?? []).some((h) => commandBelongsTo(h?.command, pluginRoot));
+}
+
+/**
+ * Merges our hooks and MCP server into an existing settings document without
+ * disturbing anything else.
+ *
+ * Idempotent by construction: our own previous entries are dropped before the
+ * current ones are appended, so repeated installs converge rather than stacking
+ * duplicate hooks.
+ */
+export function mergeSettings(existing, pluginRoot) {
+  const next = existing && typeof existing === 'object' ? structuredClone(existing) : {};
+  if (typeof next.schema_version !== 'number') next.schema_version = 1;
+
+  const hooks = { ...(next.hooks ?? {}) };
+  for (const [event, groups] of Object.entries(desiredHooks(pluginRoot))) {
+    const foreign = (hooks[event] ?? []).filter((group) => !isOurs(group, pluginRoot));
+    hooks[event] = [...foreign, ...groups];
+  }
+  next.hooks = hooks;
+
+  const servers = { ...(next.mcpServers ?? {}) };
+  for (const [id, server] of Object.entries(desiredMcpServers(pluginRoot))) {
+    const existingServer = servers[id];
+    // Merge and unmerge must agree on ownership. Unmerge only removes an
+    // omm-state entry pointing into this plugin, so merge must not silently
+    // replace one that does not — that would destroy an unrelated server that
+    // merely shares the id, and leave it unrecoverable.
+    if (existingServer && !(existingServer.args ?? []).join(' ').includes(pluginRoot)) {
+      throw new Error(
+        `settings already define an mcpServer named "${id}" that is not ours ` +
+          `(${JSON.stringify(existingServer.command ?? '')}). Refusing to overwrite it; ` +
+          `rename or remove it first.`,
+      );
+    }
+    servers[id] = server;
+  }
+  next.mcpServers = servers;
+
+  return next;
+}
+
+/** Removes every entry this installer owns. */
+export function unmergeSettings(existing, pluginRoot) {
+  const next = structuredClone(existing ?? {});
+
+  if (next.hooks) {
+    for (const event of Object.keys(next.hooks)) {
+      const remaining = (next.hooks[event] ?? []).filter((group) => !isOurs(group, pluginRoot));
+      if (remaining.length > 0) next.hooks[event] = remaining;
+      else delete next.hooks[event];
+    }
+    if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  }
+
+  if (next.mcpServers) {
+    for (const [id, server] of Object.entries(next.mcpServers)) {
+      const arg = (server?.args ?? []).join(' ');
+      if (id === 'omm-state' && arg.includes(pluginRoot)) delete next.mcpServers[id];
+    }
+    if (Object.keys(next.mcpServers).length === 0) delete next.mcpServers;
+  }
+
+  return next;
+}
+
+/** Reads a settings document, or null when absent. Throws on malformed JSON. */
+export function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return null;
+  return JSON.parse(readFileSync(settingsPath, 'utf8'));
+}
+
+/** Writes a settings document, creating the config directory if needed. */
+export function writeSettings(settingsPath, document) {
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(document, null, 2) + '\n', 'utf8');
+}

package/scripts/verify-manifest.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * Validates the plugin manifests against muse's native plugin contract.
+ *
+ * muse ships the authoritative contract with its bundled `create-plugin` skill
+ * (`.../skills/create-plugin/references/native-plugin-contract.md`). We cannot run
+ * `muse plugins validate` because the whole plugins subsystem answers "plugins are
+ * not available in this build" on 1.0.3-R2198.1 — so this script enforces the
+ * documented contract locally instead, and is the closest thing to a validator the
+ * build allows.
+ *
+ * The `agents` check matters most: the validator rejects that capability family,
+ * and a manifest declaring it loads while its definitions stay permanently
+ * inactive. Failing the build is better than shipping a roster that silently
+ * never activates.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const ACCEPTED_CAPABILITIES = new Set([
+  'skills',
+  'commands',
+  'hooks',
+  'mcpServers',
+  'reminders',
+]);
+
+// Rejected outright by muse's validator.
+const REJECTED_CAPABILITIES = new Set(['tools', 'agents', 'outputStyles', 'settings', 'apps']);
+
+const HOOK_EVENTS = new Set([
+  'PreToolUse',
+  'PostToolUse',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+  'SubagentStop',
+  'PreCompact',
+  'Notification',
+]);
+
+// Portable capability/plugin id grammar from the contract.
+const ID_GRAMMAR = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+const RESERVED_BASENAMES = new Set([
+  'con', 'prn', 'aux', 'nul',
+  ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+  ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+
+const problems = [];
+
+function readJson(relPath, { required }) {
+  const abs = join(ROOT, relPath);
+  if (!existsSync(abs)) {
+    if (required) problems.push(`${relPath}: missing`);
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(abs, 'utf8'));
+  } catch (err) {
+    problems.push(`${relPath}: ${err.message}`);
+    return null;
+  }
+}
+
+/** Contract: relative UTF-8 paths, `/` separators, no traversal, no absolute paths. */
+function checkRelativePath(label, value) {
+  if (typeof value !== 'string' || value === '') {
+    problems.push(`${label}: path must be a non-empty string`);
+    return;
+  }
+  if (value.startsWith('/')) problems.push(`${label}: absolute paths are rejected (${value})`);
+  if (value.includes('\\')) problems.push(`${label}: backslashes are rejected (${value})`);
+  if (value.split('/').includes('..')) problems.push(`${label}: parent traversal is rejected (${value})`);
+  if (!existsSync(join(ROOT, value))) problems.push(`${label}: referenced file does not exist (${value})`);
+}
+
+function checkId(label, id) {
+  if (typeof id !== 'string' || !ID_GRAMMAR.test(id)) {
+    problems.push(`${label}: id "${id}" does not match the portable id grammar`);
+    return;
+  }
+  if (RESERVED_BASENAMES.has(id.split('.')[0].toLowerCase())) {
+    problems.push(`${label}: id "${id}" case-folds to a reserved device name`);
+  }
+}
+
+// ------------------------------------------------- native manifest (authoritative)
+
+const native = readJson('.muse-plugin/plugin.json', { required: true });
+
+if (native) {
+  if (native.schemaVersion !== 1) problems.push('plugin.json: schemaVersion must be 1');
+  if (!native.name) problems.push('plugin.json: missing `name`');
+  else checkId('plugin.json name', native.name);
+  if (native.name === 'loop' || native.name === 'muse-core') {
+    problems.push(`plugin.json: plugin id "${native.name}" is reserved by the product bundle`);
+  }
+  if (!native.version) problems.push('plugin.json: missing `version`');
+  if (!native.description) problems.push('plugin.json: missing `description`');
+  if (native.compat?.source !== 'native') problems.push('plugin.json: compat.source must be "native"');
+  if (native.compat?.manifestDir !== '.muse-plugin') {
+    problems.push('plugin.json: compat.manifestDir must be ".muse-plugin"');
+  }
+
+  const caps = native.capabilities;
+  if (!caps || typeof caps !== 'object' || Array.isArray(caps)) {
+    problems.push('plugin.json: `capabilities` must be an object');
+  } else {
+    for (const key of Object.keys(caps)) {
+      if (REJECTED_CAPABILITIES.has(key)) {
+        problems.push(
+          `plugin.json: capability \`${key}\` is rejected by muse's validator and must not be declared` +
+            (key === 'agents'
+              ? ' — personas are rendered into subagent prompts instead (see src/personas.ts)'
+              : ''),
+        );
+      } else if (!ACCEPTED_CAPABILITIES.has(key)) {
+        problems.push(`plugin.json: unknown capability \`${key}\``);
+      } else if (!Array.isArray(caps[key])) {
+        problems.push(`plugin.json: capability \`${key}\` must be an array`);
+      }
+    }
+
+    for (const skill of caps.skills ?? []) {
+      checkId('plugin.json skill', skill.id);
+      checkRelativePath(`plugin.json skill ${skill.id}`, skill.path);
+      if (!skill.path?.endsWith('SKILL.md')) {
+        problems.push(`plugin.json skill ${skill.id}: path must target a SKILL.md`);
+      }
+    }
+
+    for (const command of caps.commands ?? []) {
+      checkId('plugin.json command', command.id);
+      checkRelativePath(`plugin.json command ${command.id}`, command.path);
+    }
+
+    const hookSources = new Map();
+    for (const hook of caps.hooks ?? []) {
+      checkId('plugin.json hook', hook.id);
+      if (!HOOK_EVENTS.has(hook.event)) {
+        problems.push(`plugin.json hook ${hook.id}: unsupported event "${hook.event}"`);
+      }
+      if (!Array.isArray(hook.command) || hook.command.length === 0) {
+        problems.push(`plugin.json hook ${hook.id}: command must be a structured argv array`);
+        continue;
+      }
+      // Any argv element naming a relative source file must exist beneath the root.
+      for (const arg of hook.command.slice(1)) {
+        if (typeof arg === 'string' && arg.includes('/')) {
+          checkRelativePath(`plugin.json hook ${hook.id}`, arg);
+          // Contract: two hook ids may not share a source path.
+          if (hookSources.has(arg)) {
+            problems.push(
+              `plugin.json hook ${hook.id}: shares source ${arg} with ${hookSources.get(arg)}`,
+            );
+          }
+          hookSources.set(arg, hook.id);
+        }
+      }
+    }
+
+    for (const server of caps.mcpServers ?? []) {
+      checkId('plugin.json mcpServer', server.id);
+      if (server.transport && server.transport !== 'stdio' && !server.url) {
+        problems.push(`plugin.json mcpServer ${server.id}: non-stdio transport requires a url`);
+      }
+      if (!Array.isArray(server.command) || server.command.length === 0) {
+        problems.push(`plugin.json mcpServer ${server.id}: command must be a structured argv array`);
+      }
+    }
+  }
+}
+
+// ------------------------------------------- Claude-family manifest (compatibility)
+
+// Kept so the same tree can be consumed by Claude-family hosts. It is NOT the
+// delivery mechanism for muse; it must simply not contradict the native manifest.
+const marketplace = readJson('.claude-plugin/marketplace.json', { required: false });
+if (marketplace) {
+  if (!Array.isArray(marketplace.plugins) || marketplace.plugins.length === 0) {
+    problems.push('marketplace.json: `plugins` must be a non-empty array');
+  } else {
+    for (const [i, plugin] of marketplace.plugins.entries()) {
+      if (!plugin.source) problems.push(`marketplace.json: plugins[${i}] is missing \`source\``);
+      if (!plugin.name) problems.push(`marketplace.json: plugins[${i}] is missing \`name\``);
+    }
+  }
+}
+
+const claude = readJson('.claude-plugin/plugin.json', { required: false });
+if (claude?.capabilities) {
+  for (const key of Object.keys(claude.capabilities)) {
+    if (REJECTED_CAPABILITIES.has(key)) {
+      problems.push(`.claude-plugin/plugin.json: capability \`${key}\` is rejected by muse`);
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error('Manifest verification FAILED:\n');
+  for (const problem of problems) console.error(`  - ${problem}`);
+  process.exit(1);
+}
+
+console.log('Manifest verification passed: native contract satisfied, no rejected capabilities.');

package/scripts/verify-skills.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Validates every skill in the corpus against the installed `muse` binary.
+ *
+ * This is the only trustworthy oracle for frontmatter conformance. `valid: true`
+ * on its own is not enough: muse tolerates unknown frontmatter keys by recording
+ * them in `compatibility.unknown_fields` and ignoring them at runtime. A skill
+ * carrying `triggers:` or `pipeline:` therefore validates "successfully" while
+ * behaving as if those fields were never written — so an empty unknown_fields
+ * array is part of the pass condition, not a nicety.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS_DIR = join(ROOT, 'skills');
+
+const skills = readdirSync(SKILLS_DIR, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(SKILLS_DIR, entry.name, 'SKILL.md')))
+  .map((entry) => entry.name)
+  .sort();
+
+if (skills.length === 0) {
+  console.error('verify-skills: no skills found under skills/');
+  process.exit(1);
+}
+
+let failures = 0;
+
+for (const name of skills) {
+  const result = spawnSync('muse', ['skills', 'validate', join(SKILLS_DIR, name), '--json'], {
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    console.error(`  ${name}: could not run muse (${result.error.message})`);
+    failures++;
+    continue;
+  }
+
+  let report;
+  try {
+    report = JSON.parse(result.stdout);
+  } catch {
+    console.error(`  ${name}: muse did not return parseable JSON`);
+    failures++;
+    continue;
+  }
+
+  const unknown = report.compatibility?.unknown_fields ?? [];
+  const unsupported = (report.diagnostics ?? []).filter(
+    (d) => d.code === 'unsupported-skill-field',
+  );
+
+  const problems = [];
+  if (!report.valid) problems.push('valid=false');
+  if (unknown.length > 0) problems.push(`inert frontmatter keys: ${unknown.join(', ')}`);
+  if (unsupported.length > 0) {
+    problems.push(`unsupported fields: ${unsupported.map((d) => d.message).join('; ')}`);
+  }
+
+  if (problems.length > 0) {
+    console.error(`  ${name}: FAIL — ${problems.join(' | ')}`);
+    failures++;
+  } else {
+    console.log(`  ${name}: ok`);
+  }
+}
+
+if (failures > 0) {
+  console.error(`\nverify-skills: ${failures} of ${skills.length} skills failed.`);
+  process.exit(1);
+}
+
+console.log(`\nverify-skills: all ${skills.length} skills valid with no inert frontmatter.`);

package/skills/cancel/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: cancel
+description: End any active pipeline stage (deep-interview, deep-dive, trace, ralplan, ralph, team) and clean up .omm/ state left running or in progress. Use ONLY when the user explicitly asks to cancel, stop, or abandon current work, or invokes /cancel. Do NOT use to pause and resume later (leave in-progress state alone if the user just wants a break), and do not use it to undo already-committed code changes — this skill stops orchestration state, it does not revert files.
+---
+
+# Cancel
+
+Stop whatever pipeline stage is active and leave `.omm/` state in a clean,
+honest, resumable-or-discardable condition. Explicit invocation only — like
+every skill here, nothing auto-cancels on your behalf; the user has to ask.
+
+## Scope
+
+This skill ends orchestration state. It does not:
+
+- Revert code changes already made to the working tree. If the user also
+  wants that, they need to say so separately (`git` operations are a
+  distinct, more destructive action and should never be inferred from a
+  bare "cancel").
+- Kill a task the user actually wants paused rather than abandoned. If the
+  request is genuinely "pause, I'll come back to this," leave the state
+  files as they are — this skill is for "stop, and I mean stop," not for a
+  checkpoint.
+
+If it is unclear which the user means, ask before deleting anything —
+cleanup here is one-directional.
+
+## What "active" means
+
+Check for state that implies an in-flight stage:
+
+- `.omm/specs/*.md` with no terminal approval marker (an interview left
+  mid-round or a spec left unapproved).
+- `.omm/state/trace-*.md` for a trace that never converged.
+- `.omm/state/prd.json` with any story `status` other than `"done"` or
+  `"blocked"`.
+- Any `subagent_spawn` children still running from a `team` or `ralph` run
+  in this session — check with `subagent_status` across tracked ids.
+
+## Steps
+
+1. **Cancel live subagents first.** For every tracked subagent id from an
+   active `team` or `ralph` run that is still running, call
+   `subagent_cancel` and wait for terminal cancellation
+   (`subagent_wait`/`subagent_status`) before touching files — do not leave
+   a subagent writing into a worktree you are about to declare abandoned.
+2. **Mark state, don't just delete it.** For each in-flight artifact found
+   above, decide with the user (or from their instruction) whether to:
+   - **Discard**: delete the file/entry. Only do this for state the user
+     explicitly wants gone.
+   - **Archive**: move it under `.omm/logs/cancelled/<timestamp>-<name>` so
+     the evidence of what was attempted survives even though the run did
+     not complete. Prefer this default over silent deletion — an
+     abandoned run is still useful history.
+3. **Leave completed work alone.** Stories already `"done"` in `prd.json`,
+   approved specs, and merged `team` results are not part of what gets
+   cleaned up — cancel affects the active/pending state, not history that
+   already succeeded.
+4. **Report exactly what changed.** List every file archived or deleted and
+   every subagent cancelled. Do not report "cancelled" if some tracked
+   subagent could not be confirmed terminal — say so and flag it instead of
+   claiming a clean stop.
+
+## Worktrees
+
+If a `team` or `ralph` run left worktrees under muse's worktree area from
+`worktree_isolation`, note their existence in the report so the user can
+decide whether to keep or discard them — this skill does not assume
+authority to delete a worktree that might contain unmerged, wanted work.
+
+## Handoff
+
+Cancel is terminal by design — it does not chain into anything. After
+reporting, stop. If the user wants to restart the same effort, they invoke
+the relevant skill again explicitly; cancel does not offer to do that for
+them.