@litfamily/litmuse 0.0.0-stage → 0.1.0

package/plugin/hooks/lib/hedge.mjs

@@ -0,0 +1,64 @@
+// Hedge-cluster check for project deliverables. A hedge is a word that softens a claim without changing it; one
+// functional qualifier is fine, a pile of them reads as templated model prose. Only hedges a write ADDS count.
+
+const EN_HEDGES = [
+  /\b(?:could|may|might)\s+(?:possibly|potentially|perhaps|arguably)\b/gi,
+  /\b(?:perhaps|possibly|potentially|arguably|presumably|seemingly|somewhat|relatively|generally|typically|probably|likely)\b/gi,
+  /\b(?:it seems|seems to|appears to|tends to|to some extent|in some cases|in many cases|to a certain degree)\b/gi,
+  /\b(?:could|might)\b/gi,
+];
+const KO_HEDGES = [
+  /것으로\s*(?:보인다|보입니다|보여요|추정됩니다|판단됩니다|생각됩니다)|(?:인|할|될)\s*듯\s*(?:하다|합니다|하며)|것\s*같(?:다|습니다|아요)/g,
+  /수도\s*있|수\s*있을\s*것|가능성이\s*있/g,
+  /다소|어느\s*정도|대체로|일반적으로|아마도?|어쩌면|비교적/g,
+];
+const SENTENCE_LIMIT = 2;
+const PARAGRAPH_LIMIT = 4;
+
+function paragraphs(text) {
+  let inFence = false;
+  const out = [];
+  let current = [];
+  for (const line of text.split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence || /^\s*>/.test(line)) continue;
+    if (!line.trim()) { if (current.length) out.push(current.join(' ')); current = []; continue; }
+    current.push(line);
+  }
+  if (current.length) out.push(current.join(' '));
+  return out;
+}
+
+const sentences = (p) => p.split(/(?<=[.!?。])\s+/).map((s) => s.trim()).filter(Boolean);
+
+// Counts hedge words in a sentence. The patterns overlap on purpose ("could possibly" is two hedges), so each
+// character span is claimed once: a longer match consumes the shorter ones inside it, except the phrase counts twice
+// when it joins a modal to an adverb.
+export function hedgeCount(sentence) {
+  let count = 0;
+  let rest = sentence;
+  for (const pattern of [...EN_HEDGES, ...KO_HEDGES]) {
+    const hits = rest.match(pattern);
+    if (!hits) continue;
+    count += hits.length + (pattern === EN_HEDGES[0] ? hits.length : 0);
+    rest = rest.replace(pattern, ' ');
+  }
+  return count;
+}
+
+// Returns {snippet, count} for the first paragraph the write turns into a hedge cluster, else null. Sentences already
+// in the file (or in the replaced text) belong to the writer and are not counted.
+export function addedHedgeCluster(newText, existingText = '') {
+  const existing = new Set(paragraphs(existingText).flatMap(sentences));
+  for (const p of paragraphs(newText)) {
+    const fresh = sentences(p).filter((s) => !existing.has(s));
+    const counts = fresh.map(hedgeCount);
+    const total = counts.reduce((a, b) => a + b, 0);
+    if (counts.some((c) => c >= SENTENCE_LIMIT) || total >= PARAGRAPH_LIMIT) {
+      return { snippet: fresh.join(' ').slice(0, 160), count: total };
+    }
+  }
+  return null;
+}
+
+export const HEDGE_MESSAGE = 'Keep the one qualifier that changes the claim and state the rest plainly; say what is known, then name the single open point once.';

package/plugin/hooks/lib/motion.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, lstatSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PLUGIN_ROOT, sessionFile, toolName, toolInput, workspaceOf } from './common.mjs';
+
+// The lit-typographic-motion done gate. A motion turn ends when the skill's own done-check says the film or cover is
+// done, not when a command ran: PostToolUse records each `motion.mjs` run (subcommand, --out, --round and the
+// `exit N NAME` line when the tool output carries it) and each image `read_file` opened, and Stop runs
+// engine/node/done.mjs on the last output folder. A look round may list only images read_file really opened.
+export const MOTION_ROUTE = 'lit-typographic-motion';
+export const MOTION_MAX_HOLDS = 2;
+const BLOCKED_EXITS = new Set([10, 11, 12, 14, 15, 21, 22]);
+const SHELL = new Set(['bash', 'exec_command', 'shell']);
+const COMMAND = /\bmotion\.mjs["']?\s+(stage|make|cover-gate|cover|gate|sound|look|stills|sheet|video|perf)\b([^\n;&|]*)/;
+const IMAGE = /\.(png|jpe?g|webp|gif)$/i;
+const MAX_VIEWED = 2000;
+const DONE_MODULE = join(PLUGIN_ROOT, 'skills', MOTION_ROUTE, 'engine', 'node', 'done.mjs');
+
+const statePath = (payload) => sessionFile(payload)?.replace(/\.json$/, '.motion.json') ?? null;
+
+function isLink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export function readMotion(payload) {
+  const file = statePath(payload);
+  if (!file || !existsSync(file)) return null;
+  try {
+    const s = JSON.parse(readFileSync(file, 'utf8'));
+    return s && Array.isArray(s.runs) && Array.isArray(s.viewed) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeMotion(payload, state) {
+  const file = statePath(payload);
+  if (!file || isLink(file) || isLink(dirname(file))) return state;
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, file);
+  return state;
+}
+
+// Each motion prompt starts a fresh hold budget; the runs and the images opened earlier in the session stay.
+export function armMotionTurn(payload, now = Date.now()) {
+  const prev = readMotion(payload);
+  return writeMotion(payload, { runs: prev?.runs ?? [], viewed: prev?.viewed ?? [], holds: 0, notified: false, promptAt: now });
+}
+
+const unquote = (v) => v?.replace(/^["']|["']$/g, '');
+
+/** One `motion.mjs <mode> ...` command line as { mode, out, round, stillsOnly }, or null. */
+export function parseMotionCommand(command, cwd) {
+  const m = COMMAND.exec(String(command ?? ''));
+  if (!m) return null;
+  const tokens = [...m[2].matchAll(/"[^"]*"|'[^']*'|[^\s]+/g)].map((t) => unquote(t[0]));
+  const values = {};
+  const positional = [];
+  let stillsOnly = false;
+  for (let i = 0; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t === '--stills-only') stillsOnly = true;
+    else if (t.startsWith('--')) {
+      if (['--out', '--round', '--answers', '--blocked', '--window'].includes(t)) {
+        values[t] = tokens[i + 1];
+        i += 1;
+      }
+    } else if (!t.startsWith('>') && !t.startsWith('2>')) positional.push(t);
+  }
+  const abs = (p) => (p ? (isAbsolute(p) ? p : resolve(cwd, p)) : null);
+  const mode = m[1];
+  if (mode === 'gate') return { mode, out: abs(positional[0]), round: null, stillsOnly: false };
+  // cover-gate checks a file; it is no render, so it never becomes the folder the gate judges.
+  if (mode === 'cover-gate') return { mode, out: null, round: null, stillsOnly: false };
+  const round = values['--round'] === undefined ? null : Number(values['--round']);
+  // A window render is a diagnostic sheet; the full cover render is the one that counts.
+  if (values['--window'] !== undefined) return { mode: 'cover-window', out: null, round, stillsOnly: false };
+  return { mode, out: abs(values['--out']), round, stillsOnly };
+}
+
+/** The last `exit <code>` line the CLI printed, or null. */
+export function exitCodeOf(output) {
+  const hits = [...String(output ?? '').matchAll(/^exit (\d+)\b/gm)];
+  return hits.length ? Number(hits[hits.length - 1][1]) : null;
+}
+
+function toolText(payload) {
+  const r = payload.tool_response ?? payload.tool_output ?? payload.output ?? payload.result;
+  if (typeof r === 'string') return r;
+  if (!r || typeof r !== 'object') return '';
+  return [r.stdout, r.stderr, r.output, r.content, r.text].filter((p) => typeof p === 'string').join('\n');
+}
+
+/** PostToolUse while the motion route is active: remember renders and opened images. */
+export function recordMotionTool(payload, now = Date.now()) {
+  const tool = toolName(payload);
+  const input = toolInput(payload);
+  const cwd = workspaceOf(payload);
+  const state = readMotion(payload) ?? { runs: [], viewed: [], holds: 0, notified: false, promptAt: now };
+  if (SHELL.has(tool)) {
+    const parsed = parseMotionCommand(input.command ?? input.cmd ?? input.script, cwd);
+    if (!parsed) return null;
+    return writeMotion(payload, { ...state, runs: [...state.runs, { ...parsed, exitCode: exitCodeOf(toolText(payload)), at: now }].slice(-12) });
+  }
+  if (tool === 'read_file') {
+    const path = ['path', 'file_path', 'target_path', 'file'].map((k) => input[k]).find((v) => typeof v === 'string' && v);
+    if (!path || !IMAGE.test(path)) return null;
+    const abs = resolve(cwd, path);
+    if (state.viewed.includes(abs)) return state;
+    return writeMotion(payload, { ...state, viewed: [...state.viewed, abs].slice(-MAX_VIEWED) });
+  }
+  return null;
+}
+
+const notDone = (reasons) => `LitMuse lit-typographic-motion: the work is not done (${reasons.join('; ')}). Stop rendering now and say plainly in the reply that it is not done, why, and the command the user can run to finish it.`;
+
+/** Stop while the motion route is active: { action: 'allow' | 'block', why, reason? }. */
+export async function evaluateMotionStop(payload, now = Date.now()) {
+  const state = readMotion(payload);
+  if (!state) return { action: 'allow', why: 'no-motion-state' };
+  if (state.notified) return { action: 'allow', why: 'notified' };
+  const last = [...state.runs].reverse().find((r) => r.out) ?? null;
+  let verdict;
+  if (!last) verdict = { status: 'NOT_DONE', reasons: ['no render command ran under this route'], downgraded: [], openItems: [] };
+  else if (BLOCKED_EXITS.has(last.exitCode)) verdict = { status: 'BLOCKED', reasons: [`the render is BLOCKED (exit ${last.exitCode}); report the blocked state and its fix command`], downgraded: [], openItems: [] };
+  else {
+    const { evaluateDone } = await import(pathToFileURL(DONE_MODULE).href);
+    verdict = evaluateDone({ out: last.out, viewedFiles: new Set(state.viewed) });
+  }
+  if (verdict.status === 'DONE' || verdict.status === 'DONE_UNVIEWED') {
+    const say = [
+      ...(verdict.status === 'DONE_UNVIEWED' ? ['nobody looked at the frames (no image could be opened)'] : []),
+      ...(verdict.labels ?? []),
+      ...verdict.downgraded.map((d) => `downgraded: ${d}`),
+      ...verdict.openItems.map((o) => `open item: ${o}`),
+    ];
+    if (!say.length) return { action: 'allow', why: 'done' };
+    writeMotion(payload, { ...state, notified: true });
+    return { action: 'block', why: verdict.status, reason: `LitMuse lit-typographic-motion: the render is finished. The reply must say plainly: ${say.join('; ')}.` };
+  }
+  if (verdict.status === 'BLOCKED' || state.holds >= MOTION_MAX_HOLDS) {
+    writeMotion(payload, { ...state, notified: true });
+    return { action: 'block', why: 'not-done-notice', reason: notDone(verdict.reasons) };
+  }
+  writeMotion(payload, { ...state, holds: state.holds + 1, lastHoldAt: now });
+  const loop = verdict.mode === 'cover'
+    ? 'Finish the loop in references/cover.md: render the cover, open the sheet, the poster and the seam pair with read_file, record the look round, and render again when a gate misses TARGET or a look answer asks for it.'
+    : 'Finish the loop in references/look.md: render, open every listed still with read_file, record the look round, and render again when the gate or a look answer asks for it.';
+  return { action: 'block', why: 'not-done', reason: `LitMuse lit-typographic-motion${verdict.mode === 'cover' ? ' (cover mode)' : ''} is not done: ${verdict.reasons.join('; ')}. ${loop}` };
+}

package/plugin/hooks/lib/policy.mjs

@@ -0,0 +1,103 @@
+// What a lit-plan (planning) turn may do. Everything here is an allowlist: a tool, program or flag that is not
+// listed is refused, so new host tools, MCP tools and unfamiliar flags fail closed.
+
+// Tools that only read, or only manage children and sessions that are already limited.
+export const LIT_PLAN_READ_ONLY_TOOLS = [
+  'read_file', 'search', 'read_skill', 'web_search', 'web_fetch', 'read_memory', 'work_status', 'work_list',
+  'subagent_status', 'subagent_wait', 'subagent_read_result', 'subagent_cancel', 'request_user_input', 'get_goal',
+  'cron_list',
+];
+
+// Tools allowed with a check: file writers (plans/ and .litmuse/ only), shell (read-only commands only) and
+// child agents (read-only LitMuse agents only).
+export const FILE_TOOLS = new Set(['write_file', 'edit_file', 'apply_patch', 'delete_file']);
+export const SHELL_TOOLS = new Set(['bash', 'bash_input', 'exec_command', 'shell']);
+export const READ_ONLY_AGENTS = new Set([
+  'litmuse/lit-planner', 'litmuse/librarian-researcher', 'litmuse/lit-verifier', 'litmuse/quality-reviewer',
+  'litmuse/korean-style-analyzer', 'litmuse/korean-prose-editor', 'litmuse/meaning-preservation-auditor',
+  'litmuse/native-flow-reviewer', 'litmuse/polish-orchestrator',
+]);
+
+// Any of these characters makes a command compound, redirected, substituted or escaped: refused outright.
+const SHELL_META = /[;&|<>`$\\\n\r(){}]/;
+
+// Per-program flag allowlists. `flags` take no value; `valueFlags` take the next word; `prefixFlags` carry their
+// value after `=`; `numeric` allows `-<digits>`.
+const PROGRAMS = {
+  ls: { flags: /^-[laRh1FdtrSA]+$/ },
+  cat: { flags: /^-n$/ },
+  head: { flags: /^$/, valueFlags: ['-n', '-c'], numeric: true },
+  tail: { flags: /^$/, valueFlags: ['-n', '-c'], numeric: true },
+  wc: { flags: /^-[lwcm]+$/ },
+  rg: {
+    flags: /^(-[nilcwFSsv]+|--(files|hidden|no-heading|line-number|count|ignore-case|fixed-strings|word-regexp|files-with-matches|smart-case|case-sensitive|invert-match))$/,
+    valueFlags: ['-g', '--glob', '-t', '--type', '-A', '-B', '-C', '-m', '--max-count'],
+  },
+};
+const GIT = {
+  subcommands: new Set(['log', 'status', 'diff', 'show']),
+  flags: /^(--(oneline|stat|shortstat|numstat|summary|name-only|name-status|short|porcelain|cached|staged|patch|graph|decorate|all|no-color|abbrev-commit|branch)|-[sp])$/,
+  valueFlags: ['-n', '--max-count'],
+  prefixFlags: /^--(format|pretty|since|until|author|grep|max-count|stat)=[^\s]*$/,
+  numeric: true,
+};
+
+// Splits on spaces with plain single or double quotes; anything unusual returns null (refused).
+function words(command) {
+  const out = [];
+  let cur = '';
+  let quote = null;
+  let started = false;
+  for (const ch of command) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+    } else if (ch === ' ' || ch === '\t') {
+      if (started) out.push(cur);
+      cur = '';
+      started = false;
+    } else {
+      cur += ch;
+      started = true;
+    }
+  }
+  if (quote) return null;
+  if (started) out.push(cur);
+  return out;
+}
+
+function argsAllowed(args, spec) {
+  let positional = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (positional || !a.startsWith('-') || a === '-') continue;
+    if (a === '--') { positional = true; continue; }
+    if (spec.flags.test(a)) continue;
+    if (spec.numeric && /^-\d+$/.test(a)) continue;
+    if (spec.prefixFlags && spec.prefixFlags.test(a)) continue;
+    if (spec.valueFlags && spec.valueFlags.includes(a)) {
+      const v = args[i + 1];
+      if (v === undefined || v.startsWith('-')) return false;
+      i += 1;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+export function shellReadOnly(command) {
+  if (typeof command !== 'string' || !command.trim() || SHELL_META.test(command)) return false;
+  const argv = words(command.trim());
+  if (!argv || !argv.length) return false;
+  const [program, ...args] = argv;
+  if (program === 'git') {
+    const [sub, ...rest] = args;
+    return GIT.subcommands.has(sub) && argsAllowed(rest, GIT);
+  }
+  const spec = PROGRAMS[program];
+  return Boolean(spec) && argsAllowed(args, spec);
+}

package/plugin/hooks/lib/redact.mjs

@@ -0,0 +1,38 @@
+// Hooks may import only from plugin/hooks/lib, so the credential shapes of plugin/lib/secret-shapes.mjs are
+// repeated here for the handoff snapshot. Each hit is replaced in place; the snapshot never carries a credential.
+const SHAPES = [
+  /-----BEGIN (?:RSA |EC |DSA |ED25519 |OPENSSH |ENCRYPTED |SSH2 ENCRYPTED )?PRIVATE KEY-----/giu,
+  /-----BEGIN PGP PRIVATE KEY BLOCK-----/giu,
+  /(?<![A-Za-z0-9_])(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}(?![A-Za-z0-9_])/gu,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/gu,
+  /(?<![A-Za-z0-9_])npm_[A-Za-z0-9]{20,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Z0-9])(?:AKIA|ASIA)[A-Z0-9]{16}(?![A-Z0-9])/gu,
+  /(?<![A-Za-z0-9_])xox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9_-])/gu,
+  /(?<![A-Za-z0-9_])xapp-[A-Za-z0-9-]{20,}(?![A-Za-z0-9_-])/gu,
+  /(?<![A-Za-z0-9_])AIza[0-9A-Za-z_-]{20,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])hf_[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])whsec_[A-Za-z0-9]{24,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])(?:glpat|gldt|glrt)-[A-Za-z0-9_-]{8,}(?![A-Za-z0-9_])/gu,
+  /(?<![A-Za-z0-9_])eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+(?![A-Za-z0-9_])/gu,
+  /\bbearer\s+[A-Za-z0-9._~+/=-]{12,}/giu,
+  /(?<![A-Za-z0-9-])(?:proxy-)?authorization\s*:\s*[!#$%&'*+\-.^_`|~0-9A-Za-z]+\s+(?:[!#$%&'*+\-.^_`|~0-9A-Za-z]+\s*=\s*\S+|\S{12,})/giu,
+  /\b(?:password|passwd|secret|token|api[_-]?key|access[_-]?token)\s*[:=]\s*[^\s,;]+/giu,
+  /\b[A-Za-z][A-Za-z0-9]*(?:[_-][A-Za-z0-9]+)*[_-](?:token|secret|key)(?:[_-][A-Za-z0-9]+)*\s*[:=]\s*[^\s,;]+/giu,
+  /(?<![A-Za-z0-9_])_?auth(?:[_-]?token)?\s*[:=]\s*[^\s,;]{8,}/giu,
+  /(?<![A-Za-z0-9+.-])(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/[^/?#\s]+@/gu,
+];
+const CONTROL = /[\p{Cc}\p{Cf}]/gu;
+
+export function redact(value) {
+  let text = String(value ?? '').replace(CONTROL, ' ');
+  for (const re of SHAPES) text = text.replace(re, '[REDACTED]');
+  return text;
+}
+
+// One line of at most `max` characters, credentials removed first so a cut never leaves half of one.
+export function clip(value, max = 200) {
+  const text = redact(value).replace(/\s+/g, ' ').trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/plugin/hooks/lib/reentry.mjs

@@ -0,0 +1,38 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { sessionPath } from './common.mjs';
+
+// The route a `lit` prompt finds already active in this session. A damaged, journal-only or odd-shaped state counts
+// as nothing active, so the prompt gets the full activation and rewrites the state.
+export function liveRoute(state) {
+  if (!state || state.corrupt || state.fromJournal) return null;
+  return typeof state.route === 'string' && state.route && Number.isFinite(state.activatedAt) ? state.route : null;
+}
+
+// A plan whose Status header still waits for the user's okay is a draft, not work to resume.
+const UNAPPROVED = /^Status:\s*(awaiting approval|assumptions unconfirmed)/im;
+
+// Work a bare `lit` can pick up: an approved plan under plans/ that still has an open row and was already started
+// with start-work in some session of this workspace (the hooks journal every route change).
+export function resumablePlan(cwd) {
+  const journals = sessionPath(cwd, 'probe');
+  if (!journals) return null;
+  const dir = dirname(journals);
+  try {
+    const started = readdirSync(dir).some((f) => f.endsWith('.journal') && readFileSync(join(dir, f), 'utf8').includes('"route":"start-work"'));
+    if (!started) return null;
+  } catch {
+    return null;
+  }
+  const plans = join(cwd, 'plans');
+  if (!existsSync(plans)) return null;
+  let best = null;
+  for (const name of readdirSync(plans).filter((f) => f.endsWith('.md'))) {
+    const text = readFileSync(join(plans, name), 'utf8');
+    if (UNAPPROVED.test(text)) continue;
+    const row = /^- \[ \] (\d+|F\d+)\./m.exec(text);
+    const mtime = statSync(join(plans, name)).mtimeMs;
+    if (row && (!best || mtime > best.mtime)) best = { file: `plans/${name}`, row: row[1], mtime };
+  }
+  return best;
+}

package/plugin/hooks/lib/routes.mjs

@@ -0,0 +1,160 @@
+// Route table shared by the hooks (activation and session steering) and by the installer's
+// enrollment checks. Every shipped skill appears in SKILL_ROUTES exactly once.
+
+export const SKILL_ROUTES = [
+  { id: 'lit-loop', when: 'bare `lit`, or any multi-step task that needs criteria, tests and proof' },
+  { id: 'litgoal', when: 'create, check or close a goal that must outlive this session' },
+  { id: 'litwork', when: 'ship one change with proof: implement, fix, finish' },
+  { id: 'lit-plan', when: 'plan before code; writes plans/<slug>.md only' },
+  { id: 'lit-brainstorm', when: 'open ideation: diverge on options, then score a shortlist and hand off' },
+  { id: 'deep-interview', when: 'the request is vague or broad and needs questions first' },
+  { id: 'lit-crucible', when: 'pressure-test a brief for risks before planning' },
+  { id: 'start-work', when: 'execute an approved plan row by row' },
+  { id: 'lit-code', when: 'writing or changing code' },
+  { id: 'debugging', when: 'a bug, failing test or unexpected behavior' },
+  { id: 'refactor', when: 'restructure code while keeping behavior' },
+  { id: 'lit-commit', when: 'commits, staging, rebase, blame, bisect, history questions' },
+  { id: 'review-work', when: 'is this diff or branch correct, risky, safe to merge' },
+  { id: 'visual-qa', when: 'check a built interface in a browser at several widths' },
+  { id: 'comment-checker', when: 'audit code comments on a diff or files' },
+  { id: 'lit-burnoff', when: 'strip AI-generated bloat across a scope of files' },
+  { id: 'lit-burnoff-file', when: 'strip AI-generated residue from exactly one file' },
+  { id: 'litresearch', when: 'research across sources, prior art, landscape questions' },
+  { id: 'wikify', when: 'save or query findings in the task wiki under .litmuse/wiki' },
+  { id: 'lit-comprehend', when: 'explain agent-written work to a person' },
+  { id: 'lit-humanizer', when: 'polish Korean or English prose into the writer\'s voice' },
+  { id: 'lit-recap', when: 'where does the work stand (read-only)' },
+  { id: 'lit-handoff', when: 'before stopping or switching sessions' },
+  { id: 'lit-init', when: 'orient in an unfamiliar repository; leaves AGENTS.md' },
+  { id: 'frontend-ui-ux', when: 'build or restyle a user interface' },
+  { id: 'readme-studio', when: 'write or refresh a README from repo facts' },
+  { id: 'lit-docx', when: 'a Word document or DOCX/PDF to Markdown (needs Python)' },
+  { id: 'lit-pptx', when: 'a slide deck (needs Python)' },
+  { id: 'lit-scientific-visualization', when: 'a publication-ready figure from data' },
+  { id: 'lit-diagram-drawer', when: 'an architecture, workflow or timeline diagram' },
+  { id: 'lit-typographic-motion', when: 'make a short film, kinetic type or lyric video, or a seamless README cover loop' },
+  { id: 'autoresearch', when: 'a budgeted experiment loop against a metric' },
+  { id: 'structural-search', when: 'find or rewrite code by syntax shape (ast-grep)' },
+  { id: 'browser-drive', when: 'the answer only exists in a running web page' },
+  { id: 'lit-team', when: 'coordinate two or more child agents behind one durable team packet' },
+  { id: 'autoconference', when: 'a budgeted research conference: parallel researchers, review, synthesis' },
+  { id: 'rules', when: 'which rules, AGENTS.md and skills Muse loads, and in what order' },
+  { id: 'lsp', when: 'language diagnostics, definitions and references through checker CLIs' },
+  { id: 'lsp-setup', when: 'set up and verify a language checker for this project' },
+];
+
+// The word after a leading `lit` picks a route; anything else falls back to lit-loop.
+export const KEYWORD_ROUTES = {
+  loop: 'lit-loop',
+  plan: 'lit-plan',
+  work: 'litwork',
+  goal: 'litgoal',
+  research: 'litresearch',
+  review: 'review-work',
+  start: 'start-work',
+  recap: 'lit-recap',
+  status: 'lit-recap',
+  handoff: 'lit-handoff',
+  init: 'lit-init',
+  debug: 'debugging',
+  interview: 'deep-interview',
+  crucible: 'lit-crucible',
+  commit: 'lit-commit',
+  refactor: 'refactor',
+  burnoff: 'lit-burnoff',
+  'burnoff-file': 'lit-burnoff-file',
+  brainstorm: 'lit-brainstorm',
+  brainstorming: 'lit-brainstorm',
+  ideation: 'lit-brainstorm',
+  ideate: 'lit-brainstorm',
+  idea: 'lit-brainstorm',
+  ideas: 'lit-brainstorm',
+  team: 'lit-team',
+  conference: 'autoconference',
+  rules: 'rules',
+  lsp: 'lsp',
+  diagnostics: 'lsp',
+  'lsp-setup': 'lsp-setup',
+  motion: 'lit-typographic-motion',
+  film: 'lit-typographic-motion',
+  video: 'lit-typographic-motion',
+  '영상': 'lit-typographic-motion',
+  explain: 'lit-comprehend',
+  humanize: 'lit-humanizer',
+  korean: 'lit-humanizer',
+  '다듬어': 'lit-humanizer',
+  '윤문': 'lit-humanizer',
+};
+
+const SKILL_IDS = new Set(SKILL_ROUTES.map((r) => r.id));
+
+// `lit <task>` whose task asks to make a film goes to the motion skill: a film compound alone, or a bare video noun
+// with a making verb. Editing or captioning footage, a video inside a page or deck, a thumbnail, a script, UI motion
+// and video as a software feature stay where they were.
+const FILM_COMPOUND = /모션\s?그래픽|타이포\s?모션|키네틱\s?타이포|가사\s?영상|오프닝\s?타이틀|타이틀\s?시퀀스|motion[- ]graphics?\b|kinetic[- ]typ(?:e|ography)\b|lyric video|title sequence|opening titles?\b|(?:motion|readme)[- ]cover|cover loop|커버\s?루프|모션\s?커버/i;
+const VIDEO_NOUN = /영상|비디오|\bvideos?\b|\bclips?\b/i;
+const MAKE_VERB = /만들|제작|뽑아|렌더|\b(?:make|create|produce|render|build|animate)\b/i;
+const NOT_A_FILM = /자막|잘라|편집|썸네일|대본|요약|업로드|배경\s?영상|넣어|호버|안건|\b(?:trim|cut|captions?|subtitles?|embed|insert|thumbnail|script|summary|summari[sz]e|upload|background video|hover|motion tokens?|clip[- ]path|transcribe)\b/i;
+
+export function motionIntent(task) {
+  const text = String(task ?? '');
+  if (NOT_A_FILM.test(text)) return false;
+  return FILM_COMPOUND.test(text) || (VIDEO_NOUN.test(text) && MAKE_VERB.test(text));
+}
+
+// `lit new …` and `lit restart …` start over; `lit continue` and `lit resume` pick the work up where it stands.
+const RESTART_WORDS = new Set(['new', 'restart']);
+const CONTINUE_WORDS = new Set(['continue', 'resume']);
+const SEPARATORS = /^[\s:,.!?]+/;
+const firstWord = (s) => (/^([^\s:,.!?]+)/.exec(s)?.[1] ?? '').toLowerCase();
+
+// Activation is case-sensitive on purpose: `lit` or `LIT` activates, a sentence-initial "Lit" stays prose.
+// The result also says how the prompt re-enters: `bare` (no task text), `resume` (continue word) and `restart`.
+export function detectRoute(prompt) {
+  if (typeof prompt !== 'string') return null;
+  return detectLeading(prompt) ?? detectTrailing(prompt);
+}
+
+// A standalone `lit` or `LIT` as the last word of the prompt ("Hello! lit") activates lit-loop with the earlier text as
+// the task, as it does in the sibling products. Only a word of its own counts: a `lit` inside a word (literal, split),
+// after a path or URL character (lit-plan.md, /x/lit/y), in quotes, in a code span or fence, or followed by more text
+// does not.
+const TRAILING_LIT = /(?:^|\s)(?:lit|LIT)\s*$/;
+function detectTrailing(prompt) {
+  const withoutFences = prompt.replace(/```[\s\S]*?```/g, ' ');
+  if (withoutFences.includes('```')) return null;
+  const text = withoutFences.replace(/`[^`\n]*`/g, ' ');
+  if (!TRAILING_LIT.test(text)) return null;
+  return { route: 'lit-loop', keyword: null, bare: false, resume: false, restart: false, trailing: true };
+}
+
+function detectLeading(prompt) {
+  let text = prompt.trimStart();
+  if (text.startsWith('```')) return null;
+  // `/lit <route> <task>` arrives as typed in headless runs; the expanded /lit template starts with a marker line.
+  const slash = /^\/(?:litmuse:)?lit(?=$|\s)/.exec(text);
+  const marker = slash ? null : /^LitMuse route request:/.exec(text);
+  if (slash) text = `lit ${text.slice(slash[0].length).trimStart()}`;
+  else if (marker) text = `lit ${text.slice(marker[0].length).split('\n')[0].trim()}`;
+  const m = /^([A-Za-z][A-Za-z-]*)(?=$|[\s:,.!?])/.exec(text);
+  if (!m) return null;
+  const token = m[1];
+  const lower = token.toLowerCase();
+  if (token !== lower && token !== token.toUpperCase()) return null;
+  if (lower === 'lit') {
+    let rest = text.slice(token.length).replace(SEPARATORS, '');
+    let word = firstWord(rest);
+    const restart = RESTART_WORDS.has(word);
+    if (restart) {
+      rest = rest.slice(word.length).replace(SEPARATORS, '');
+      word = firstWord(rest);
+    }
+    const resume = !restart && CONTINUE_WORDS.has(word);
+    const bare = !restart && (word === '' || (resume && rest.slice(word.length).trim() === ''));
+    const route = KEYWORD_ROUTES[word];
+    if (!route && !bare && !resume && motionIntent(rest)) return { route: 'lit-typographic-motion', keyword: null, bare, resume, restart };
+    return { route: route ?? 'lit-loop', keyword: route ? word : null, bare, resume, restart };
+  }
+  if (lower.startsWith('lit') && SKILL_IDS.has(lower)) return { route: lower, keyword: null, bare: false, resume: false, restart: false };
+  return null;
+}