@litfamily/litmuse 0.1.1 → 0.1.3

package/plugin/commands/lit.md

@@ -6,7 +6,7 @@ LitMuse route request: $ARGUMENTS
 
 Treat the line above as a LitMuse request; the prompt hook has already recorded its route.
 
-1. The first word picks the route: 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. Any other first word means lit-loop, except a task that asks to make a film (a film compound such as kinetic type, lyric video, title sequence, cover loop, 모션그래픽, 가사 영상, or a bare video noun with a making verb), which goes to lit-typographic-motion. Skills without a keyword (frontend-ui-ux, readme-studio, visual-qa, comment-checker, wikify, autoresearch, structural-search, browser-drive, lit-code) are reached through lit-loop or their own `/<skill>` command.
+1. The first word picks the route: 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, hijack → lit-hijack, hijacking → lit-hijack, 하이재킹 → lit-hijack, 하이잭 → lit-hijack, adhd → lit-adhd, rewind → lit-adhd, approve → start-work, deny → start-work, 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. Any other first word means lit-loop, except a task that asks to make a film (a film compound such as kinetic type, lyric video, title sequence, cover loop, 모션그래픽, 가사 영상, or a bare video noun with a making verb), which goes to lit-typographic-motion. Skills without a keyword (frontend-ui-ux, readme-studio, visual-qa, comment-checker, wikify, autoresearch, structural-search, browser-drive, lit-code) are reached through lit-loop or their own `/<skill>` command.
 2. Load that skill with read_skill using the id `plugin:litmuse:<route>` before any other tool, and follow it. When the hook context says the route is already active or resuming, skip steps 2 and 3: keep the criteria, plan and ledger you have.
 3. Your first output, before any tool call or other text, is the line `🔥 **LIT IGNITED · <route>** 🔥` on its own line, once. When the hook context says the route continues, the line is `🔥 **LIT CONTINUES · <route>** 🔥` instead.
 4. Report in reader mode: the result, any material risk, and the action the user must take.

package/plugin/hooks/lib/digest.mjs

@@ -10,7 +10,7 @@ const PLUGIN = join(LIB, '..', '..');
 
 // Files outside hooks/lib that a hook loads at run time: PostToolUse runs the lit-humanizer detector, and Stop runs the
 // lit-typographic-motion done-check with every engine module it imports.
-const MOTION_DONE = ['node/done.mjs', 'node/cover-assets.mjs', 'core/constants.mjs', 'node/chrome.mjs', 'node/cover-image.mjs', 'node/cover-treatment.mjs', 'node/treatment.mjs', 'node/sound.mjs', 'core/util.mjs', 'node/look.mjs', 'node/stills.mjs', 'node/analysis.mjs', 'core/flash.mjs', 'node/png.mjs'];
+const MOTION_DONE = ['node/done.mjs', 'node/cover-assets.mjs', 'core/constants.mjs', 'node/chrome.mjs', 'node/cover-image.mjs', 'node/cover-treatment.mjs', 'node/treatment.mjs', 'node/sound.mjs', 'node/house.mjs', 'node/styles.mjs', 'node/score.mjs', 'core/presets.mjs', 'core/util.mjs', 'node/look.mjs', 'node/stills.mjs', 'node/analysis.mjs', 'core/flash.mjs', 'node/png.mjs'];
 export const DIGEST_EXTRAS = ['skills/lit-humanizer/scripts/core.mjs', 'skills/lit-humanizer/rules.json', ...MOTION_DONE.map((f) => `skills/lit-typographic-motion/engine/${f}`)];
 
 const listed = (dir, ext) => readdirSync(dir).filter((f) => f.endsWith(ext)).sort().map((f) => join(dir, f));

package/plugin/hooks/lib/next-step.mjs

@@ -0,0 +1,112 @@
+// The `go` half of the lit-adhd brief and of a saved lit-plan: the collector (or the Stop hook,
+// for a plan) writes this session's next-step record under `.litmuse/adhd/`, and a later
+// whole-prompt `go` reads it back and deletes it. The session
+// binding is the file name, so another session's record is never opened. A step older than 30
+// minutes is stale: the brief it came from no longer describes the work.
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { workspaceOf } from './common.mjs';
+import { resolveProjectStateRoot } from './workflow-stack.mjs';
+
+// The whole prompt, nothing more: `go`, `lit go`, `ㄱㄱ`, `고` or `진행`, with trailing punctuation.
+const GO_PROMPT = /^\s*(?:(?:lit\s+)?go|ㄱㄱ|고|진행)[\s.!?]*$/iu;
+export const isGoPrompt = (prompt) => typeof prompt === 'string' && prompt.length <= 64 && GO_PROMPT.test(prompt);
+
+export const NEXT_STEP_MAX_AGE_MS = 30 * 60_000;
+const KINDS = new Set(['resume-frame', 'approve-boundary', 'continue-work', 'start-plan', 'none']);
+
+const nextStepFile = (cwd, sessionId) => {
+  const id = String(sessionId ?? 'session').replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128) || 'session';
+  return join(resolveProjectStateRoot(cwd), '.litmuse', 'adhd', `next-${id}.json`);
+};
+
+const PLAN_NAME = /^plans\/[A-Za-z0-9._-]+\.md$/u;
+
+// `.litmuse` and `.litmuse/adhd` must be real folders (or not there yet): a linked one would carry
+// the record out of the project.
+const realDirs = (root, dir) => {
+  for (const part of [join(root, '.litmuse'), dir]) {
+    try {
+      if (!lstatSync(part).isDirectory()) return false;
+    } catch { /* absent: mkdir makes a real one */ }
+  }
+  mkdirSync(dir, { recursive: true });
+  return !lstatSync(join(root, '.litmuse')).isSymbolicLink() && !lstatSync(dir).isSymbolicLink();
+};
+
+/**
+ * The lit-plan half of `go`: once a planning turn has saved `plans/<slug>.md`, records it as this
+ * session's `start-plan` step, so a whole-prompt `go` within 30 minutes starts start-work on it.
+ * Plan names outside `plans/<slug>.md` and linked state folders write nothing. Never throws.
+ */
+export const putNextStep = (payload, plan, now = Date.now()) => {
+  const sessionId = typeof payload?.session_id === 'string' && payload.session_id ? payload.session_id : null;
+  if (!sessionId || typeof plan !== 'string' || !PLAN_NAME.test(plan) || /[\r\n]/u.test(plan)) return null;
+  try {
+    const cwd = workspaceOf(payload);
+    const path = nextStepFile(cwd, sessionId);
+    if (!realDirs(resolveProjectStateRoot(cwd), dirname(path))) return null;
+    const staging = `${path}.${process.pid}.tmp`;
+    try {
+      unlinkSync(staging);
+    } catch { /* no leftover */ }
+    const fd = openSync(staging, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      writeSync(fd, `${JSON.stringify({ kind: 'start-plan', target: { plan }, at: new Date(now).toISOString() })}\n`);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(staging, path);
+    return path;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Reads and deletes this session's next-step record. Returns `{kind, target}` when the record is
+ * whole and at most 30 minutes old, otherwise null; a stale or unreadable record is deleted all
+ * the same. Never throws.
+ */
+export const takeNextStep = (payload, now = Date.now()) => {
+  const sessionId = typeof payload?.session_id === 'string' && payload.session_id ? payload.session_id : null;
+  if (!sessionId) return null;
+  let cwd = null;
+  try {
+    cwd = workspaceOf(payload);
+  } catch {
+    return null;
+  }
+  if (!cwd) return null;
+  const path = nextStepFile(cwd, sessionId);
+  let text;
+  try {
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const stat = fstatSync(fd);
+      if (!stat.isFile() || stat.size > 16_384) return null;
+      text = readFileSync(fd, 'utf8');
+    } catch {
+      return null;
+    } finally {
+      try {
+        closeSync(fd);
+      } catch { /* already closed */ }
+    }
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(path);
+    } catch { /* nothing to consume */ }
+  }
+  try {
+    const record = JSON.parse(text);
+    const age = now - Date.parse(record.at);
+    if (!KINDS.has(record.kind) || !(age >= -60_000 && age <= NEXT_STEP_MAX_AGE_MS)) return null;
+    return { kind: record.kind, target: record.target && typeof record.target === 'object' ? record.target : null };
+  } catch {
+    return null;
+  }
+};

package/plugin/hooks/lib/routes.mjs

@@ -25,6 +25,8 @@ export const SKILL_ROUTES = [
   { 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-hijack', when: 'port published know-how into your own skill, clean-room' },
+  { id: 'lit-adhd', when: 'brief every recent session: asked, did, waiting, roadmap, one next step' },
   { 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' },
@@ -32,6 +34,7 @@ export const SKILL_ROUTES = [
   { 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-schematic', when: 'a P&ID, PFD, apparatus figure or isometric cutaway of real hardware' },
   { 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)' },
@@ -70,6 +73,14 @@ export const KEYWORD_ROUTES = {
   idea: 'lit-brainstorm',
   ideas: 'lit-brainstorm',
   team: 'lit-team',
+  hijack: 'lit-hijack',
+  hijacking: 'lit-hijack',
+  '하이재킹': 'lit-hijack',
+  '하이잭': 'lit-hijack',
+  adhd: 'lit-adhd',
+  rewind: 'lit-adhd',
+  approve: 'start-work',
+  deny: 'start-work',
   conference: 'autoconference',
   rules: 'rules',
   lsp: 'lsp',
@@ -102,6 +113,44 @@ export function motionIntent(task) {
   return FILM_COMPOUND.test(text) || (VIDEO_NOUN.test(text) && MAKE_VERB.test(text));
 }
 
+// Hardware wording (P&ID, PFD, cutaway, isometric, apparatus, and the Korean plant-drawing
+// words) routes a `lit` prompt to lit-schematic. Software-architecture wording keeps its
+// existing route: the guard below screens those prompts out.
+const SCHEMATIC_WORD = /P&ID|P&I\b|PFD|BFD|schematic|cutaway|isometric|apparatus|Piping and Instrumentation|모식|장치도|공정도|계장도|배관계장/i;
+const NOT_A_SCHEMATIC = /codebase|auth flow|boxes and arrows|software|entity-relationship|org chart|timeline|swimlane|sequence diagram/i;
+function schematicIntent(task) {
+  const t = String(task ?? '');
+  if (NOT_A_SCHEMATIC.test(t)) return false;
+  return SCHEMATIC_WORD.test(t);
+}
+
+// A deck asked for by slide wording routes a `lit` prompt to lit-pptx: a slide noun with a making
+// verb, or a slide count beside a slide noun ("덱 10장", "a 10-slide deck") with no verb at all.
+// Code documentation and photo retouching ("사진 10장 보정") stay where they were.
+const SLIDE_NOUN = /\b(?:slides?|slide\s?deck|deck|presentation|pptx?|powerpoint|keynote)\b|발표|슬라이드|피피티|파워포인트|(?<![가-힣])덱(?![가-힣])|(?<![가-힣])덱을|(?<![가-힣])덱으로/i;
+const MAKE_DECK = /\b(?:make|making|made|create|creating|write|writing|draft|drafting|prepare|preparing|build|building|generate|generating|produce|producing)\b|만들|만드|작성|써\s?줘|써\s?주|써서|써봐|쓰고|정리해|정리하|준비|초안|뽑아|짜\s?줘|구성해/i;
+const SLIDE_COUNT = /\d+\s?장|\b\d+[\s-]?slides?\b/i;
+const NOT_A_DECK = /readme|changelog|contributing|api\s?(?:문서|docs?\b|reference)|docstrings?|jsdoc|주석|\bdocs\/|\b(?:bug|test|coverage|error|crash|lint|issue|incident)\s+reports?\b|사진\s?\d+\s?장\s?보정|보정해|보정하/i;
+function deckIntent(task) {
+  const t = String(task ?? '');
+  if (NOT_A_DECK.test(t)) return false;
+  // A presentation asked for as a video is a film, not a deck.
+  if (motionIntent(t)) return false;
+  return SLIDE_NOUN.test(t) && (MAKE_DECK.test(t) || SLIDE_COUNT.test(t));
+}
+
+// An English request to build, redesign or review a page or site routes to the frontend skill: a making
+// verb beside an interface noun, a UI target named outright, or an artefacts review beside a page noun.
+const UI_NOUN = /\b(?:pages?|sites?|websites?|landing(?:\s?pages?)?|homepages?|portfolios?|dashboards?|forms?|checkouts?|onboardings?|wizards?|modals?|tooltips?|popovers?|navbars?|footers?|heros?|carousels?|galleries?|grids?|tables?|cards?|buttons?|inputs?|dropdowns?|tabs?|accordions?|themes?|layouts?|wireframes?|mockups?|prototypes?|redesigns?|uis?|ux|frontends?|front[-\s]?ends?|css|stylesheets?|responsive|accessibility|a11y|viewports?|breakpoints?|components?|design[-\s]?systems?|styleguides?|tokens?|interfaces?)\b/i;
+const UI_VERB = /\b(?:build|building|create|creating|make|makes|making|design|designing|redesign|redesigning|restyle|restyling|revamp|revamping|polish|polishing|harden|hardening|audit|auditing|review|reviewing|fix|fixing|improve|improving|modernize|modernizing|responsive)\b/i;
+const UI_TARGET = /^[^]*\b(?:page|site|website|landing|ui|ux|frontend|front-end|stylesheet|redesign|mockup|prototype|wireframe|theme|layout|component|design-system|styleguide)\b[^]*/i;
+function uiBuildIntent(task) {
+  const text = String(task ?? '');
+  if (!text.trim()) return false;
+  if (UI_VERB.test(text) && UI_NOUN.test(text)) return true;
+  return UI_TARGET.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']);
@@ -136,6 +185,12 @@ function detectLeading(prompt) {
   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()}`;
+  // A direct skill slash for the brief (`/lit-adhd`, `/litmuse:lit-rewind`) names the
+  // route the same way a bare `lit-adhd` prompt does; without this the hook records no
+  // route and the LIT card keeps its normal headline while the brief runs.
+  if (/^\/(?:litmuse:)?lit-(?:adhd|rewind)(?=$|\s)/.test(text)) {
+    return { route: 'lit-adhd', keyword: null, bare: false, resume: false, restart: false, trailing: false };
+  }
   const m = /^([A-Za-z][A-Za-z-]*)(?=$|[\s:,.!?])/.exec(text);
   if (!m) return null;
   const token = m[1];
@@ -152,9 +207,13 @@ function detectLeading(prompt) {
     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 && schematicIntent(rest)) return { route: 'lit-schematic', keyword: null, bare, resume, restart };
+    if (!route && !bare && !resume && deckIntent(rest)) return { route: 'lit-pptx', keyword: null, bare, resume, restart };
     if (!route && !bare && !resume && motionIntent(rest)) return { route: 'lit-typographic-motion', keyword: null, bare, resume, restart };
+    if (!route && !bare && !resume && uiBuildIntent(rest)) return { route: 'frontend-ui-ux', keyword: null, bare, resume, restart };
     return { route: route ?? 'lit-loop', keyword: route ? word : null, bare, resume, restart };
   }
+  if (lower === 'lit-rewind') return { route: 'lit-adhd', keyword: null, bare: false, resume: false, restart: false, trailing: false };
   if (lower.startsWith('lit') && SKILL_IDS.has(lower)) return { route: lower, keyword: null, bare: false, resume: false, restart: false };
   return null;
 }

package/plugin/hooks/lib/stage.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, lstatSync, renameSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, lstatSync, renameSync, realpathSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
@@ -66,8 +66,9 @@ export function readStage(file) {
   }
 }
 
-// mutate(record) returns the next record (or nothing to keep it). Never throws.
-export function updateStage(payload, mutate, env = process.env) {
+// mutate(record) returns the next record (or nothing to keep it). Never throws. `pointer: false` leaves
+// `latest.json` alone, for writes that say nothing about which session the user is driving.
+export function updateStage(payload, mutate, env = process.env, { pointer = true } = {}) {
   try {
     const cwd = workspaceOf(payload);
     const file = stageFile(cwd, payload.session_id, env);
@@ -83,9 +84,10 @@ export function updateStage(payload, mutate, env = process.env) {
     next.lanes = next.lanes.slice(-MAX_LANES);
     for (const k of ['route', 'keyword', 'plan', 'kind']) if (k in next) next[k] = clip(next[k]);
     if (!atomicWrite(file, next)) return false;
-    const pointer = readStage(latestFile(env)) ?? {};
-    pointer[next.workspace] = { session: payload.session_id, updated: now };
-    atomicWrite(latestFile(env), pointer);
+    if (!pointer) return true;
+    const latest = readStage(latestFile(env)) ?? {};
+    latest[next.workspace] = { session: payload.session_id, updated: now };
+    atomicWrite(latestFile(env), latest);
     return true;
   } catch {
     return false;
@@ -141,6 +143,51 @@ export function recordLaneStop(payload, env = process.env) {
   }, env);
 }
 
+// Liveness: each session's last hook event as one small record, `stage/liveness/<session>.json`, apart from the
+// stage record so a tool call never rewrites `latest.json`. PostToolUse and its failure twin say `alive`, Stop says
+// `idle`, SessionEnd says `ended`. The card reads these to sort other sessions into running, idle and gone. A
+// repeat of the same state inside 30 s writes nothing, so a busy session costs one write per half minute.
+export const LIVENESS_STATES = Object.freeze(['alive', 'idle', 'ended']);
+const LIVENESS_REPEAT_MS = 30_000;
+// A herdr pane id is short and plain (`w2B:p3`); anything else is dropped rather than stored.
+const PANE_ID = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,31}$/;
+
+export function livenessDir(env = process.env) {
+  return join(stageRoot(env), 'liveness');
+}
+
+export function readLiveness(env = process.env) {
+  try {
+    return readdirSync(livenessDir(env)).filter((n) => n.endsWith('.json')).map((n) => readStage(join(livenessDir(env), n))).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function markLiveness(payload, state, { env = process.env, now = Date.now() } = {}) {
+  try {
+    const id = safeId(payload?.session_id);
+    if (!id || !LIVENESS_STATES.includes(state)) return false;
+    const root = stageRoot(env);
+    const dir = livenessDir(env);
+    if (isLink(root) || !safeDir(dir)) return false;
+    const file = join(dir, `${id}.json`);
+    const prev = isLink(file) ? null : readStage(file);
+    if (prev && prev.state === state && now - Date.parse(prev.at) < LIVENESS_REPEAT_MS) return false;
+    const cwd = workspaceOf(payload);
+    const pane = typeof env.HERDR_PANE_ID === 'string' && PANE_ID.test(env.HERDR_PANE_ID) ? env.HERDR_PANE_ID : null;
+    return atomicWrite(file, { version: 1, session: id, state, at: new Date(now).toISOString(), cwd, workspace: workspaceHash(cwd), pane });
+  } catch {
+    return false;
+  }
+}
+
+// The plugin version this session's hooks and skills were loaded from, for the card's restart chip.
+export function recordLoadedVersion(payload, version, env = process.env) {
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+/.test(version)) return false;
+  return updateStage(payload, (rec) => ({ ...rec, loadedVersion: version }), env, { pointer: false });
+}
+
 export function recordSessionEnd(payload, env = process.env) {
   return updateStage(payload, (rec, now) => {
     rec.route = null;

package/plugin/hooks/lib/workflow-stack.mjs

@@ -0,0 +1,336 @@
+// The session's workflow stack, `.litmuse/workflow-stack/<session>.json`: where each running
+// discipline stands, so asking for something in the middle of a loop or a plan run pauses that
+// work instead of erasing it. The bottom frame is the spine (the main line of work); a discipline
+// started on top of it is a side frame. A successor in the main chain finishes the frame below it
+// instead of pausing it. Asking for a skill already in the stack resumes its frame with its stage
+// and count; `lit continue` on a side frame closes it and resumes the paused spine. Read-only
+// disciplines never touch the stack. `applyStackEvent` is pure; the store below writes one small
+// file per session, whole, and the status card reads it back through its own guarded read. Frames
+// keep skills, stages and counts only; never a prompt, a command or a path other than a
+// project-relative plan name.
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const MAX_FRAMES = 3;
+export const MAX_HISTORY = 20;
+export const MAX_STACK_BYTES = 64 * 1024;
+export const STACK_DROP_MS = 24 * 60 * 60 * 1000;
+export const READ_ONLY_DISCIPLINES = Object.freeze(['lit-recap', 'lit-comprehend', 'lit-handoff', 'lit-adhd', 'lit-rewind']);
+
+// Order in the main chain; a newcomer of a higher rank succeeds the frame below it.
+const CHAIN_RANK = Object.freeze({
+  'deep-interview': 0,
+  'lit-brainstorm': 0,
+  'lit-crucible': 1,
+  'lit-plan': 1,
+  'start-work': 2,
+  litwork: 2,
+  litgoal: 2,
+  autoresearch: 2,
+  'lit-loop': 2,
+  'review-work': 3,
+});
+const MAX_VERDICTS = 8;
+const PLAN_REF = /^plans\/[A-Za-z0-9_-][A-Za-z0-9._-]*\.md$/u;
+
+// Where each LitMuse discipline enters the map. Skills without an entry start as side frames.
+const DISCIPLINE_ENTRY = Object.freeze({
+  'deep-interview': { family: 'main', stage: 'interview' },
+  'lit-brainstorm': { family: 'main', stage: 'interview' },
+  'lit-crucible': { family: 'main', stage: 'plan' },
+  'lit-plan': { family: 'main', stage: 'plan' },
+  'start-work': { family: 'main', stage: 'work' },
+  litwork: { family: 'main', stage: 'work' },
+  litgoal: { family: 'main', stage: 'work' },
+  autoresearch: { family: 'main', stage: 'work' },
+  'lit-loop': { family: 'loop', stage: 'PIN' },
+  'review-work': { family: 'main', stage: 'review' },
+  litresearch: { family: 'research', stage: 'decompose' },
+});
+const WORKFLOW_FAMILIES = Object.freeze({
+  main: Object.freeze(['interview', 'plan', 'work', 'review', 'done']),
+  research: Object.freeze(['decompose', 'wave', 'expand', 'verify', 'synthesis']),
+  loop: Object.freeze(['PIN', 'RED', 'GREEN', 'VERIFY', 'REVIEW', 'RECORD']),
+});
+const STAGE_ALIASES = Object.freeze({ SURFACE: 'VERIFY', CLEAN: 'RECORD' });
+export const REVIEW_LANES = Object.freeze([
+  Object.freeze({ id: 'goal', words: Object.freeze(['goal', 'scope', 'diff']) }),
+  Object.freeze({ id: 'quality', words: Object.freeze(['quality', 'package', 'payload']) }),
+  Object.freeze({ id: 'security', words: Object.freeze(['security', 'provenance']) }),
+  Object.freeze({ id: 'qa', words: Object.freeze(['qa', 'tests', 'evidence']) }),
+  Object.freeze({ id: 'context', words: Object.freeze(['context', 'surface', 'docs', 'readiness']) }),
+]);
+const STAGE_UNITS = Object.freeze(['task', 'criterion', 'iteration', 'wave', 'round']);
+const VERDICT_STATES = Object.freeze(['pass', 'fail', 'pending', 'running']);
+
+export const normalizeStage = (family, stage) => {
+  const stages = WORKFLOW_FAMILIES[family];
+  if (!stages) return null;
+  const raw = String(stage ?? '').trim();
+  const named = family === 'loop' ? STAGE_ALIASES[raw.toUpperCase()] ?? raw.toUpperCase() : raw.toLowerCase();
+  return stages.includes(named) ? named : null;
+};
+
+export const emptyStack = (sessionId) => ({ version: 1, sessionId: typeof sessionId === 'string' && sessionId ? sessionId : null, frames: [], history: [] });
+
+const countOf = (value) => (Number.isInteger(value) && value >= 0 && value <= 9999 ? value : undefined);
+const planRef = (ref) => (ref && typeof ref.plan === 'string' && PLAN_REF.test(ref.plan) && !ref.plan.includes('..') ? { plan: ref.plan } : undefined);
+const isSuccessor = (skill, frame) => CHAIN_RANK[skill] !== undefined && CHAIN_RANK[frame.skill] !== undefined && CHAIN_RANK[skill] > CHAIN_RANK[frame.skill];
+
+const newFrame = (skill, ref, role, at) => {
+  const entry = DISCIPLINE_ENTRY[skill];
+  const frame = { skill, family: entry?.family ?? null, stage: entry?.stage ?? null, role, status: 'active', verdicts: {}, at };
+  const plan = planRef(ref);
+  if (plan) frame.ref = plan;
+  return frame;
+};
+
+// A saved plan, or a review whose five lanes have all reported: what comes next replaces it.
+const isFinished = (frame) => frame.done === true
+  || (frame.family === 'main' && frame.stage === 'review' && REVIEW_LANES.every(({ id }) => ['pass', 'fail'].includes(frame.verdicts?.[id])));
+
+const counts = (frame) => ({ stage: frame.stage, n: frame.n, total: frame.total });
+
+/**
+ * Applies one event to the stack and returns the next stack with the transitions it made
+ * (`started`, `paused`, `resumed`, `side.done`, `finished`, `dropped`), which the caller may log.
+ * Events: `start {skill, ref?, restart?}`, `continue`, `move {family, stage, n?, total?, unit?,
+ * done?, verdicts?, ref?, scope?}` (the hooks' observations) and `record {...same fields}`.
+ */
+export const applyStackEvent = (stack, event, now = new Date()) => {
+  const at = now.toISOString();
+  const transitions = [];
+  const note = (type, frame) => transitions.push({ type, skill: frame.skill, ...counts(frame) });
+  let frames = (Array.isArray(stack?.frames) ? stack.frames : [])
+    .filter((frame) => now.getTime() - Date.parse(frame.at) <= STACK_DROP_MS)
+    .map((frame) => ({ ...frame }));
+  const pause = (frame) => {
+    if (frame.status === 'paused') return;
+    frame.status = 'paused';
+    frame.pausedAt = at;
+    note('paused', frame);
+  };
+  const activate = (frame) => {
+    const wasPaused = frame.status === 'paused';
+    frame.status = 'active';
+    frame.at = at;
+    delete frame.pausedAt;
+    if (wasPaused) note('resumed', frame);
+  };
+  const closeAbove = (index, type) => {
+    for (const frame of frames.slice(index + 1).reverse()) note(type, frame);
+    frames = frames.slice(0, index + 1);
+  };
+  const push = (frame) => {
+    frames.push(frame);
+    note('started', frame);
+    while (frames.length > MAX_FRAMES) {
+      const side = frames.findIndex((candidate, index) => index < frames.length - 1 && candidate.role === 'side');
+      const [dropped] = frames.splice(side === -1 ? 0 : side, 1);
+      note('dropped', dropped);
+    }
+  };
+
+  const start = (skill, ref, restart) => {
+    if (READ_ONLY_DISCIPLINES.includes(skill)) return;
+    const hasFamily = Boolean(DISCIPLINE_ENTRY[skill]);
+    if (restart) {
+      closeAbove(-1, 'finished');
+      push(newFrame(skill, ref, hasFamily ? 'spine' : 'side', at));
+      return;
+    }
+    const existing = frames.findLastIndex((frame) => frame.skill === skill);
+    if (existing !== -1) {
+      const wanted = planRef(ref);
+      const kept = frames[existing].ref?.plan;
+      if (!isFinished(frames[existing]) && (!wanted || !kept || wanted.plan === kept)) {
+        closeAbove(existing, 'side.done');
+        activate(frames[existing]);
+        if (wanted) frames[existing].ref = wanted;
+        return;
+      }
+      const role = frames[existing].role;
+      closeAbove(existing - 1, 'finished');
+      if (frames.length) pause(frames.at(-1));
+      push(newFrame(skill, ref, role, at));
+      return;
+    }
+    let inherited = null;
+    let handed = null;
+    while (frames.length && isFinished(frames.at(-1))) {
+      const done = frames.pop();
+      note('finished', done);
+      inherited = done.role;
+      handed = handed ?? done.ref;
+    }
+    // Work that follows a plan in the main chain carries the plan's name on, so its count is the plan's.
+    const carried = (from) => ref ?? (CHAIN_RANK[skill] >= CHAIN_RANK['start-work'] ? from : undefined);
+    const top = frames.at(-1);
+    if (!top) {
+      push(newFrame(skill, carried(handed), hasFamily ? inherited ?? 'spine' : 'side', at));
+    } else if (!frames.some((frame) => frame.role === 'spine')) {
+      closeAbove(-1, 'finished');
+      push(newFrame(skill, ref, hasFamily ? 'spine' : 'side', at));
+    } else if (hasFamily && isSuccessor(skill, top)) {
+      frames.pop();
+      note(top.role === 'spine' ? 'finished' : 'side.done', top);
+      push(newFrame(skill, carried(top.ref ?? handed), top.role, at));
+    } else {
+      pause(top);
+      push(newFrame(skill, ref, 'side', at));
+    }
+  };
+
+  const update = (frame, fields) => {
+    const stage = normalizeStage(fields.family, fields.stage) ? String(fields.stage).trim() : null;
+    if (!stage) return;
+    const named = fields.family === 'loop' ? stage.toUpperCase() : stage.toLowerCase();
+    const sameStage = frame.family === fields.family && frame.stage === named;
+    frame.family = fields.family;
+    frame.stage = named;
+    for (const key of ['n', 'total']) {
+      const value = countOf(fields[key]);
+      if (value !== undefined) frame[key] = value;
+    }
+    if (STAGE_UNITS.includes(fields.unit)) frame.unit = fields.unit;
+    if (typeof fields.done === 'boolean') frame.done = fields.done;
+    const plan = planRef(fields.ref);
+    if (plan) frame.ref = plan;
+    const given = Object.entries(fields.verdicts ?? {}).filter(([name, state]) => /^[a-z][a-z0-9-]{0,23}$/u.test(name) && VERDICT_STATES.includes(state));
+    frame.verdicts = Object.fromEntries([...Object.entries(sameStage ? frame.verdicts ?? {} : {}), ...given].slice(-MAX_VERDICTS));
+    frame.at = at;
+  };
+
+  switch (event?.type) {
+    case 'start':
+      start(event.skill, event.ref, event.restart === true);
+      break;
+    case 'continue': {
+      const top = frames.at(-1);
+      const spine = frames.findLastIndex((frame) => frame.role === 'spine');
+      if (top?.role === 'side' && spine !== -1) {
+        closeAbove(spine, 'side.done');
+        activate(frames[spine]);
+      }
+      break;
+    }
+    case 'move': {
+      const target = event.scope === 'nearest'
+        ? frames.findLast((frame) => frame.family === event.family && frame.stage === event.stage)
+        : frames.at(-1);
+      if (target && target.family === event.family && (event.scope === 'nearest' || target.status === 'active')) update(target, event);
+      break;
+    }
+    case 'record':
+      if (frames.length) update(frames.at(-1), event);
+      else if (normalizeStage(event.family, event.stage)) {
+        const frame = { skill: null, family: event.family, stage: null, role: 'spine', status: 'active', verdicts: {}, at };
+        update(frame, event);
+        push(frame);
+      }
+      break;
+    default:
+      break;
+  }
+
+  if (frames.length && frames.at(-1).status !== 'active') activate(frames.at(-1));
+  const history = [...(Array.isArray(stack?.history) ? stack.history : []), ...transitions.map(({ type, skill }) => ({ event: type, skill, at }))].slice(-MAX_HISTORY);
+  return { stack: { version: 1, sessionId: stack?.sessionId ?? null, frames, history }, transitions };
+};
+
+// State placement: the outermost git root owns `.litmuse`, so a nested package shares its
+// parent's state; without git the workspace itself owns it. A linked worktree (its `.git` is a
+// file) is its own root: the climb stops there, so its state never lands in the main checkout.
+// Every reader and writer of `.litmuse` resolves through this one function.
+export const resolveProjectStateRoot = (startDir = process.cwd()) => {
+  const start = resolve(startDir);
+  let root = null;
+  let current = start;
+  for (;;) {
+    const git = join(current, '.git');
+    if (existsSync(git)) {
+      root = current;
+      try {
+        if (!lstatSync(git).isDirectory()) return root;
+      } catch { /* vanished between checks: keep climbing */ }
+    }
+    const parent = dirname(current);
+    if (parent === current) return root ?? start;
+    current = parent;
+  }
+};
+
+// The project a recorded cwd belongs to, for comparing records: links resolved first, so a session
+// that reached the project through a symlinked path (`/var` vs `/private/var`) is the same project.
+export const projectKey = (dir) => {
+  let real = resolve(dir);
+  try {
+    real = realpathSync(real);
+  } catch { /* gone or unreadable: compare as written */ }
+  return resolveProjectStateRoot(real);
+};
+
+const fileName = (sessionId) => `${String(sessionId ?? 'session').replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128) || 'session'}.json`;
+
+export const stackPath = (cwd, sessionId) => join(resolveProjectStateRoot(cwd), '.litmuse', 'workflow-stack', fileName(sessionId));
+
+const STATE_GITIGNORE = '# Created by LitMuse: local session state, not for commits.\n*\n';
+
+// Every component from the project root down must be a real directory: lstat sees only the
+// final component, so a `.litmuse` that is itself a link would otherwise smuggle writes elsewhere.
+const stateDirOk = (root, dir) => {
+  const rel = dirname(resolve(dir)).replace(resolve(root), '');
+  const parts = [resolve(root), ...rel.split('/').filter(Boolean).map((_, i, all) => join(resolve(root), ...all.slice(0, i + 1)))];
+  for (const part of parts) {
+    try {
+      // Missing components are fine: mkdir creates them as real directories below.
+      if (lstatSync(part).isSymbolicLink()) return false;
+    } catch { /* not there yet */ }
+  }
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    return false;
+  }
+  try {
+    return !lstatSync(dir).isSymbolicLink() && lstatSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/** Reads the session's stack; a link, a non-file, an oversized or malformed file reads as empty. */
+export const readStack = (cwd, sessionId) => {
+  const empty = emptyStack(sessionId);
+  let fd;
+  try {
+    const path = stackPath(cwd, sessionId);
+    if (!lstatSync(path).isFile()) return empty;
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const { size } = fstatSync(fd);
+    if (size > MAX_STACK_BYTES) return empty;
+    const buffer = Buffer.alloc(size);
+    readSync(fd, buffer, 0, size, 0);
+    const parsed = JSON.parse(buffer.toString('utf8'));
+    if (!parsed || !Array.isArray(parsed.frames) || parsed.frames.length > MAX_FRAMES) return empty;
+    return { ...empty, frames: parsed.frames, history: Array.isArray(parsed.history) ? parsed.history.slice(-MAX_HISTORY) : [] };
+  } catch {
+    return empty;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+};
+
+/** Writes the whole stack through a temporary file; a link at the destination is replaced, never followed. */
+export const writeStack = (cwd, sessionId, stack) => {
+  const root = resolveProjectStateRoot(cwd);
+  const path = stackPath(cwd, sessionId);
+  if (!stateDirOk(root, dirname(path))) return stack;
+  try {
+    writeFileSync(join(dirname(dirname(path)), '.gitignore'), STATE_GITIGNORE, { flag: 'wx' });
+  } catch { /* an existing ignore file stays as it is */ }
+  const staging = `${path}.${process.pid}.tmp`;
+  writeFileSync(staging, `${JSON.stringify(stack)}\n`, { flag: 'w' });
+  renameSync(staging, path);
+  return stack;
+};