mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/memory/topic-types.ts

@@ -0,0 +1,142 @@
+// Topic-based memory schema (#1070). Each file groups related
+// bullets under a single topic. The frontmatter carries the type
+// and topic name; the body is markdown (H1 + optional H2 sections +
+// bullets). Coexists with #1029's atomic files during the
+// transition — PR-B retires the atomic format.
+
+import type { MemoryType } from "./types.js";
+
+export interface TopicMemoryFile {
+  type: MemoryType;
+  /** Filename without `.md`. Stable identifier; the index links to it. */
+  topic: string;
+  /** Raw markdown body — H1 heading + H2 subsections + bullets. */
+  body: string;
+  /** H2 headings extracted from the body, in source order, with
+   *  whitespace trimmed. The index renders these as the file's
+   *  "tags". Empty array when the file has no H2 yet (a young
+   *  topic with only bullets directly under H1). */
+  sections: string[];
+}
+
+// Pull H2 headings out of the body. Pure / regex-free / iterable so
+// a long body can't trip sonarjs. `##` followed by space OR tab is
+// accepted so a markdown file authored with mixed indentation
+// doesn't silently lose tags. `###` and deeper are NOT treated as
+// tags so the file can use them for further structure without
+// leaking into the index.
+export function extractH2Sections(body: string): string[] {
+  const sections: string[] = [];
+  for (const lineRaw of body.split("\n")) {
+    const line = stripCarriageReturn(lineRaw);
+    if (!isH2Line(line)) continue;
+    const heading = line.slice(2).trim();
+    if (heading.length > 0) sections.push(heading);
+  }
+  return sections;
+}
+
+function isH2Line(line: string): boolean {
+  if (!line.startsWith("##")) return false;
+  if (line.startsWith("###")) return false;
+  if (line.length === 2) return false;
+  const [, , next] = line;
+  return next === " " || next === "\t";
+}
+
+function stripCarriageReturn(line: string): string {
+  return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+
+// Maximum length of a topic slug (filename without `.md`). Both the
+// slugifier and the safety gate honour this cap, and downstream
+// callers that suffix a slug (e.g. collision resolution in
+// `topic-migrate`'s `pickUniqueSlug`) must trim the base so the
+// suffixed result still fits.
+export const MAX_TOPIC_SLUG_LENGTH = 60;
+
+// Windows refuses to create files with these basenames even with an
+// extension (`con.md` is blocked). Without this gate a clusterer
+// that returns "CON" would slugify to `con`, pass `isSafeTopicSlug`,
+// and then fail migration on Windows. Listed in lowercase since the
+// slugifier lowercases first.
+const WINDOWS_RESERVED_BASENAMES = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9",
+]);
+
+// Slugify a topic name for use as a filename. `<type>/<topic>.md`
+// must keep `topic` filesystem-safe and short. Collapses anything
+// non-alnum into a single `-`, lowercases, trims trailing
+// separators, caps at MAX_TOPIC_SLUG_LENGTH chars. Returns null when
+// the result is empty (caller decides whether to fall back to a
+// hash).
+export function slugifyTopicName(name: string): string | null {
+  const lower = name.toLowerCase();
+  const out: string[] = [];
+  let lastWasSep = true;
+  for (const char of lower) {
+    if ((char >= "a" && char <= "z") || (char >= "0" && char <= "9")) {
+      out.push(char);
+      lastWasSep = false;
+    } else if (!lastWasSep) {
+      out.push("-");
+      lastWasSep = true;
+    }
+  }
+  while (out.length > 0 && out[out.length - 1] === "-") out.pop();
+  const compact = out.slice(0, MAX_TOPIC_SLUG_LENGTH).join("");
+  if (compact.length === 0) return null;
+  const trimmed = trimTrailing(compact, "-");
+  if (WINDOWS_RESERVED_BASENAMES.has(trimmed)) return null;
+  return trimmed;
+}
+
+function trimTrailing(text: string, char: string): string {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === char) end -= 1;
+  return text.slice(0, end);
+}
+
+// Strict shape gate: lowercase alnum + `-` only, length 1–60, no
+// leading / trailing `-`, not the reserved index name. The
+// strictness is intentional: a clusterer's first attempt at a topic
+// slug is often a free-form phrase ("AI Research Papers!"), and we
+// want such inputs to fall through to `slugifyTopicName` rather
+// than land verbatim on the filesystem with spaces / punctuation
+// baked in. `isSafeMemorySlug` from #1029 was looser to allow
+// unicode body suffixes; here we force the slug format to be
+// filename-friendly so the topic doubles as the path component.
+export function isSafeTopicSlug(slug: string): boolean {
+  if (typeof slug !== "string") return false;
+  if (slug.length === 0) return false;
+  if (slug.length > MAX_TOPIC_SLUG_LENGTH) return false;
+  if (slug.startsWith("-") || slug.endsWith("-")) return false;
+  for (const char of slug) {
+    const ok = (char >= "a" && char <= "z") || (char >= "0" && char <= "9") || char === "-";
+    if (!ok) return false;
+  }
+  if (slug === "memory") return false;
+  if (WINDOWS_RESERVED_BASENAMES.has(slug)) return false;
+  return true;
+}

package/server/workspace/memory/types.ts

@@ -0,0 +1,83 @@
+// Typed memory schema (#1029). Each entry is a markdown file with a
+// YAML frontmatter envelope. The directory layout, filename
+// convention, and field set are documented in
+// `plans/done/feat-memory-storage-utilities.md`.
+//
+// `type` is the source of truth for an entry's classification —
+// filenames follow `<type>_<slug>.md` for ergonomics but the reader
+// must trust the frontmatter, never the filename.
+
+export const MEMORY_TYPES = ["preference", "interest", "fact", "reference"] as const;
+
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+
+export interface MemoryEntry {
+  /** One-line human-readable label. Becomes the link text in MEMORY.md. */
+  name: string;
+  /** Short blurb shown after the link in MEMORY.md and used as the
+   *  description hint when the agent decides whether to read the
+   *  full entry. */
+  description: string;
+  type: MemoryType;
+  /** Markdown body. The frontmatter envelope is stripped on parse and
+   *  re-applied on write. */
+  body: string;
+  /** Filename without extension. Stable identifier used by the index
+   *  link target. */
+  slug: string;
+}
+
+export function isMemoryType(value: unknown): value is MemoryType {
+  return typeof value === "string" && (MEMORY_TYPES as readonly string[]).includes(value);
+}
+
+// Bound the alphanumeric portion of a slug. Long bullets in the
+// legacy memory.md (e.g. paragraph-length recurring task descriptions)
+// would otherwise produce slugs > 200 chars and trip
+// `isSafeMemorySlug`'s upper bound, dropping the entry on disk. 80
+// chars keeps the filename readable in `ls` output, leaves headroom
+// under the safety cap, and is well under the 255-byte filename limit
+// every supported filesystem honors.
+const MAX_SLUG_BODY = 80;
+
+// Slugify a name into a filename-safe token. ASCII-only conversion of
+// [a-zA-Z0-9] segments; everything else collapses into a single `-`.
+// The result is truncated to MAX_SLUG_BODY and any trailing `-` from
+// the truncation is trimmed so the slug doesn't read like a partial
+// word. Non-ASCII (Japanese / 中文) input falls back to the type
+// prefix + short hash so two entries with all-non-ASCII names don't
+// collide on the empty string. Uses an explicit char loop instead of
+// regex so a deeply-recursive name can't trigger pathological
+// backtracking.
+export function slugifyMemoryName(name: string, type: MemoryType): string {
+  const ascii = compactAlnum(name.toLowerCase());
+  const bounded = trimTrailingSeparators(ascii.slice(0, MAX_SLUG_BODY));
+  if (bounded.length > 0) return `${type}_${bounded}`;
+  let hash = 0;
+  for (let index = 0; index < name.length; index += 1) {
+    hash = (hash * 31 + name.charCodeAt(index)) >>> 0;
+  }
+  return `${type}_${hash.toString(36)}`;
+}
+
+function trimTrailingSeparators(text: string): string {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === "-") end -= 1;
+  return text.slice(0, end);
+}
+
+function compactAlnum(text: string): string {
+  const out: string[] = [];
+  let lastWasSep = true;
+  for (const char of text) {
+    if ((char >= "a" && char <= "z") || (char >= "0" && char <= "9")) {
+      out.push(char);
+      lastWasSep = false;
+    } else if (!lastWasSep) {
+      out.push("-");
+      lastWasSep = true;
+    }
+  }
+  while (out.length > 0 && out[out.length - 1] === "-") out.pop();
+  return out.join("");
+}

package/server/workspace/news/reader.ts

@@ -83,8 +83,8 @@ export function extractDailyJsonIndex(markdown: string): NewsItem[] | null {
   if (!Array.isArray(shape.items)) return null;
   // Defensive filter: drop entries that don't carry the fields the
   // viewer relies on.
-  return shape.items.filter((item): item is NewsItem => {
-    return (
+  return shape.items.filter(
+    (item): item is NewsItem =>
       typeof item === "object" &&
       item !== null &&
       typeof item.id === "string" &&
@@ -92,9 +92,8 @@ export function extractDailyJsonIndex(markdown: string): NewsItem[] | null {
       typeof item.url === "string" &&
       typeof item.publishedAt === "string" &&
       typeof item.sourceSlug === "string" &&
-      Array.isArray(item.categories)
-    );
-  });
+      Array.isArray(item.categories),
+  );
 }
 
 // Build the list of YYYY-MM-DD strings for the last `days` days

package/server/workspace/paths.ts

@@ -24,6 +24,48 @@
 import { homedir } from "os";
 import path from "path";
 
+// Well-known individual files — imported from the shared
+// src/config/workspacePaths.ts (single source of truth for both
+// server and frontend). Re-exported so server callers keep the
+// same `import { WORKSPACE_FILES } from "./paths.js"` they use.
+import { WORKSPACE_FILES } from "../../src/config/workspacePaths.js";
+
+// Plugin-owned workspace dirs are auto-aggregated from every
+// plugin's META in `src/plugins/metas.ts`. Adding a new plugin =
+// register its META there; this file keeps the central
+// `WORKSPACE_DIRS.<key>` shape via spread so existing consumers
+// don't migrate. Plugin-specific literals never appear here.
+import {
+  BUILT_IN_PLUGIN_METAS,
+  defineHostAggregate,
+  type BuiltInPluginMetas,
+  type HostPluginCollision,
+  type IntraPluginCollision,
+} from "../../src/plugins/metas.js";
+
+// Merge every plugin's `workspaceDirs` into one record. The mapped
+// type below preserves each plugin's literal path strings (e.g.
+// `"data/accounting"`) so consumers like `WORKSPACE_DIRS.accounting`
+// keep their narrow types — without it, TypeScript widens to
+// `string` and downstream `WORKSPACE_PATHS.accounting` lookups break.
+//
+// Distributive conditional types collapse the per-plugin union into
+// an INTERSECTION so consumers see the merged shape rather than a
+// union (which TS won't let you index into safely once 2+ plugins
+// register).
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+// Plugins WITHOUT `workspaceDirs` must contribute an empty object
+// (`Record<never, never>`), NOT `Record<string, never>`. The latter
+// carries an index signature that, once intersected with a sibling
+// plugin's narrow contribution, drags `keyof` of the merged type
+// back to `string`. See server/workspace/workspace.ts: indexing
+// `WORKSPACE_PATHS[key]` over `EAGER_WORKSPACE_DIRS` requires
+// `WorkspaceDirKey` to stay a union of literals.
+type PluginWorkspaceDirsContribution<M> = M extends { readonly workspaceDirs: infer D } ? { readonly [K in keyof D]: D[K] } : Record<never, never>;
+
+type PluginWorkspaceDirsMap<T extends BuiltInPluginMetas> = UnionToIntersection<PluginWorkspaceDirsContribution<T[number]>>;
+
 // Workspace root. Hard-coded to `~/mulmoclaude` — there is no
 // WORKSPACE_PATH env override today; changing the location
 // requires a code edit or a symlink. Re-exported by
@@ -34,9 +76,20 @@ export const workspacePath = path.join(homedir(), "mulmoclaude");
 // Workspace-relative paths. Keys are the stable code-side identifiers
 // (e.g. `markdowns` — unchanged for call-site compatibility); values
 // are the on-disk paths, grouped per issue #284.
-export const WORKSPACE_DIRS = {
+const HOST_WORKSPACE_DIRS = {
   // conversations/
   chat: "conversations/chat",
+  // Typed memory entries (#1029). One markdown file per fact, indexed
+  // by `MEMORY.md` (= WORKSPACE_FILES.memoryIndex). Replaces the
+  // single-file `memory.md`; the legacy file is kept as
+  // `memory.md.backup` after migration.
+  memoryDir: "conversations/memory",
+  // Staging dir for the atomic→topic migration (#1070 PR-A). Cluster
+  // output lands here; the user reviews via `diff`, then `topic-swap`
+  // promotes it to `memoryDir`. The dir name is also matched verbatim
+  // by `topicStagingPath` and the swap-window detection in
+  // `topic-detect.ts`, so changes here ripple through both places.
+  memoryStaging: "conversations/memory.next",
   summaries: "conversations/summaries",
   // Tool-trace output for WebSearch (one .md per search, referenced
   // from chat JSONL `contentRef`). Lives alongside chat/ so search
@@ -44,11 +97,18 @@ export const WORKSPACE_DIRS = {
   searches: "conversations/searches",
   // data/
   wiki: "data/wiki",
-  todos: "data/todos",
+  // todos: removed (#1145) — todo data now lives under the plugin's
+  // own `files.data` scope at `data/plugins/%40mulmoclaude%2Ftodo-plugin/`.
   calendar: "data/calendar",
   contacts: "data/contacts",
   scheduler: "data/scheduler",
   sources: "data/sources",
+  translation: "data/translation",
+  // Pasted/dropped chat attachments — saved at upload time so the
+  // LLM can be handed a stable workspace path instead of inline
+  // base64. Conversion artefacts (e.g. PPTX → PDF) live alongside
+  // the original under the same YYYY/MM partition.
+  attachments: "data/attachments",
   transports: "data/transports",
   // artifacts/
   charts: "artifacts/charts",
@@ -71,6 +131,13 @@ export const WORKSPACE_DIRS = {
   configs: "config",
   roles: "config/roles",
   helps: "config/helps",
+  // Project-scope Claude Code skills root — both user-authored and
+  // launcher-managed presets live here. Path is hardcoded by Claude
+  // Code's slash-command resolver (it scans `<cwd>/.claude/skills/`
+  // alongside `~/.claude/skills/`); we centralise the literal here
+  // so server code references it through `WORKSPACE_PATHS.claudeSkills`
+  // instead of inlining the string.
+  claudeSkills: ".claude/skills",
   // Nested subdirs inside a top-level grouping. Kept here (rather
   // than module-local constants) when multiple modules need to
   // reference the same nested path — e.g. wiki/pages/ is used by
@@ -78,61 +145,72 @@ export const WORKSPACE_DIRS = {
   // prompt hint.
   wikiPages: "data/wiki/pages",
   wikiSources: "data/wiki/sources",
+  // Per-page edit-history snapshots (#763 PR 2). Hidden by leading
+  // dot so a curious user listing `data/wiki/` doesn't trip over a
+  // peer directory of historical content. Each `<slug>/` underneath
+  // holds N snapshot .md files newest-first.
+  wikiHistory: "data/wiki/.history",
   // Development — git-cloned repositories (#256).
   github: "github",
+  // Runtime-loaded plugins (#1043 C-2). The `plugins/` directory holds
+  // user-installed npm-published plugin tarballs; `.cache/<name>/<ver>/`
+  // is the extracted-on-boot mirror. Both live under the workspace root
+  // so the install / extract artefacts persist across npx invocations.
+  plugins: "plugins",
+  pluginCache: "plugins/.cache",
+  // Per-runtime-plugin storage roots (#1110). The platform creates
+  // `<root>/<sanitized-pkg-name>/` lazily on first write. data is the
+  // backup target; config holds per-machine UI state / defaults.
+  pluginsData: "data/plugins",
+  pluginsConfig: "config/plugins",
+  notifier: "data/notifier",
 } as const;
 
-// Well-known individual files — imported from the shared
-// src/config/workspacePaths.ts (single source of truth for both
-// server and frontend). Re-exported so server callers keep the
-// same `import { WORKSPACE_FILES } from "./paths.js"` they use.
-import { WORKSPACE_FILES } from "../../src/config/workspacePaths.js";
+// First-write-wins host+plugin aggregate (see `defineHostAggregate`):
+// host keys win on collision, second-claiming plugin wins are
+// dropped, both diagnostic lists are exposed for boot warnings.
+const WORKSPACE_DIRS_AGGREGATE = defineHostAggregate(BUILT_IN_PLUGIN_METAS, {
+  label: "WORKSPACE_DIRS",
+  hostRecord: HOST_WORKSPACE_DIRS,
+  // Reserve `WORKSPACE_FILES` keys too — those land in `WORKSPACE_PATHS`
+  // alongside dir paths and would silently overwrite a plugin's
+  // `workspaceDirs.<sameKey>` at the absolute-path step, leaving
+  // `WORKSPACE_DIRS` and `WORKSPACE_PATHS` disagreeing for that key
+  // (CR review #1125).
+  additionalReservedKeys: new Set(Object.keys(WORKSPACE_FILES)),
+  extract: (meta) => meta.workspaceDirs,
+  dimension: "workspaceDirs",
+});
+export const WORKSPACE_DIRS_HOST_COLLISIONS: readonly HostPluginCollision[] = WORKSPACE_DIRS_AGGREGATE.hostCollisions;
+export const WORKSPACE_DIRS_INTRA_COLLISIONS: readonly IntraPluginCollision[] = WORKSPACE_DIRS_AGGREGATE.intraCollisions;
+
+export const WORKSPACE_DIRS = WORKSPACE_DIRS_AGGREGATE.merged as unknown as typeof HOST_WORKSPACE_DIRS & PluginWorkspaceDirsMap<BuiltInPluginMetas>;
 export { WORKSPACE_FILES };
 
 // Absolute paths, built once at module load from `workspacePath`.
 // The `workspacePath` const is itself fixed (reads `homedir()`
 // at process start — no env override, see `server/workspace.ts`),
 // so freezing these paths is safe.
+//
+// Auto-derived from `WORKSPACE_DIRS` and `WORKSPACE_FILES`. Adding
+// a new dir or file to the upstream maps now flows into
+// `WORKSPACE_PATHS` automatically — no second hand-curated edit
+// required (CodeRabbit #1125 review: previously plugins adding
+// `workspaceDirs` keys still needed a manual `WORKSPACE_PATHS`
+// patch-up to be reachable in absolute form).
+const WORKSPACE_DIR_PATHS = Object.fromEntries(Object.entries(WORKSPACE_DIRS).map(([key, relativePath]) => [key, path.join(workspacePath, relativePath)])) as {
+  readonly [K in keyof typeof WORKSPACE_DIRS]: string;
+};
+
+const WORKSPACE_FILE_PATHS = Object.fromEntries(
+  Object.entries(WORKSPACE_FILES).map(([key, relativePath]) => [key, path.join(workspacePath, relativePath)]),
+) as {
+  readonly [K in keyof typeof WORKSPACE_FILES]: string;
+};
+
 export const WORKSPACE_PATHS = {
-  chat: path.join(workspacePath, WORKSPACE_DIRS.chat),
-  todos: path.join(workspacePath, WORKSPACE_DIRS.todos),
-  calendar: path.join(workspacePath, WORKSPACE_DIRS.calendar),
-  contacts: path.join(workspacePath, WORKSPACE_DIRS.contacts),
-  scheduler: path.join(workspacePath, WORKSPACE_DIRS.scheduler),
-  roles: path.join(workspacePath, WORKSPACE_DIRS.roles),
-  stories: path.join(workspacePath, WORKSPACE_DIRS.stories),
-  images: path.join(workspacePath, WORKSPACE_DIRS.images),
-  markdowns: path.join(workspacePath, WORKSPACE_DIRS.markdowns),
-  spreadsheets: path.join(workspacePath, WORKSPACE_DIRS.spreadsheets),
-  charts: path.join(workspacePath, WORKSPACE_DIRS.charts),
-  configs: path.join(workspacePath, WORKSPACE_DIRS.configs),
-  helps: path.join(workspacePath, WORKSPACE_DIRS.helps),
-  wiki: path.join(workspacePath, WORKSPACE_DIRS.wiki),
-  news: path.join(workspacePath, WORKSPACE_DIRS.news),
-  sources: path.join(workspacePath, WORKSPACE_DIRS.sources),
-  summaries: path.join(workspacePath, WORKSPACE_DIRS.summaries),
-  searches: path.join(workspacePath, WORKSPACE_DIRS.searches),
-  htmls: path.join(workspacePath, WORKSPACE_DIRS.htmls),
-  html: path.join(workspacePath, WORKSPACE_DIRS.html),
-  transports: path.join(workspacePath, WORKSPACE_DIRS.transports),
-  github: path.join(workspacePath, WORKSPACE_DIRS.github),
-  // nested subdirs
-  wikiPages: path.join(workspacePath, WORKSPACE_DIRS.wikiPages),
-  wikiSources: path.join(workspacePath, WORKSPACE_DIRS.wikiSources),
-  // files
-  memory: path.join(workspacePath, WORKSPACE_FILES.memory),
-  sessionToken: path.join(workspacePath, WORKSPACE_FILES.sessionToken),
-  wikiIndex: path.join(workspacePath, WORKSPACE_FILES.wikiIndex),
-  wikiLog: path.join(workspacePath, WORKSPACE_FILES.wikiLog),
-  wikiSchema: path.join(workspacePath, WORKSPACE_FILES.wikiSchema),
-  wikiSummary: path.join(workspacePath, WORKSPACE_FILES.wikiSummary),
-  summariesIndex: path.join(workspacePath, WORKSPACE_FILES.summariesIndex),
-  todosItems: path.join(workspacePath, WORKSPACE_FILES.todosItems),
-  todosColumns: path.join(workspacePath, WORKSPACE_FILES.todosColumns),
-  schedulerItems: path.join(workspacePath, WORKSPACE_FILES.schedulerItems),
-  schedulerUserTasks: path.join(workspacePath, WORKSPACE_FILES.schedulerUserTasks),
-  schedulerOverrides: path.join(workspacePath, WORKSPACE_FILES.schedulerOverrides),
-  newsReadState: path.join(workspacePath, WORKSPACE_FILES.newsReadState),
+  ...WORKSPACE_DIR_PATHS,
+  ...WORKSPACE_FILE_PATHS,
 } as const;
 
 export type WorkspaceDirKey = keyof typeof WORKSPACE_DIRS;
@@ -144,7 +222,6 @@ export type WorkspacePathKey = keyof typeof WORKSPACE_PATHS;
 // list is created lazily (first write) by its owning module.
 export const EAGER_WORKSPACE_DIRS: readonly WorkspaceDirKey[] = [
   "chat",
-  "todos",
   "calendar",
   "contacts",
   "scheduler",

package/server/workspace/roles.ts

@@ -1,16 +1,7 @@
 import path from "node:path";
 import { BUILTIN_ROLES, RoleSchema, type Role } from "../../src/config/roles.js";
-import { WORKSPACE_DIRS } from "./paths.js";
+import { WORKSPACE_DIRS, workspacePath } from "./paths.js";
 import { readdirUnderSync, readTextUnderSync } from "../utils/files/workspace-io.js";
-import { workspacePath } from "./paths.js";
-
-function withSwitchRole(role: Role): Role {
-  if (role.availablePlugins.includes("switchRole")) return role;
-  return {
-    ...role,
-    availablePlugins: [...role.availablePlugins, "switchRole"],
-  };
-}
 
 export function loadCustomRoles(): Role[] {
   return readdirUnderSync(workspacePath, WORKSPACE_DIRS.roles)
@@ -19,7 +10,7 @@ export function loadCustomRoles(): Role[] {
       try {
         const raw = readTextUnderSync(workspacePath, path.posix.join(WORKSPACE_DIRS.roles, fileName));
         if (!raw) return [];
-        return [withSwitchRole(RoleSchema.parse(JSON.parse(raw)))];
+        return [RoleSchema.parse(JSON.parse(raw))];
       } catch {
         return [];
       }

package/server/workspace/skills/parser.ts

@@ -6,6 +6,8 @@
 // pulling in a YAML parser we do line-by-line extraction.
 
 import { TIME_UNIT_MS, ONE_SECOND_MS } from "../../utils/time.js";
+import { LEADING_BLANK_LINES_PATTERN } from "../../utils/regex.js";
+import { parseFrontmatter } from "../../utils/markdown/frontmatter.js";
 import { SCHEDULE_TYPES } from "@receptron/task-scheduler";
 
 export interface SkillSchedule {
@@ -24,21 +26,6 @@ export interface ParsedSkill {
   roleId?: string;
 }
 
-// Match a YAML scalar value on a single line:
-//   description: Enable CI for a repository
-//   description: "Quoted with colons: inside"
-// Leading/trailing whitespace trimmed. Quoted values have their
-// outer quotes stripped but inner JSON-style escapes are NOT
-// reversed — SKILL.md descriptions in the wild are plain text.
-function parseScalar(raw: string): string {
-  const trimmed = raw.trim();
-  if (trimmed.length === 0) return "";
-  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
-
 /**
  * Parse schedule value from frontmatter.
  * Supported formats:
@@ -68,8 +55,8 @@ function parseScheduleValue(raw: string): SkillSchedule["parsed"] {
   // interval Ns / Nm / Nh — must be >= MIN_INTERVAL_MS
   const intervalMatch = trimmed.match(/^interval\s+(\d+)([smh])$/);
   if (intervalMatch) {
-    const value = Number(intervalMatch[1]);
-    const unit = intervalMatch[2];
+    const [, valueRaw, unit] = intervalMatch;
+    const value = Number(valueRaw);
     const unitMs = TIME_UNIT_MS[unit];
     if (!unitMs) return null;
     const intervalMs = value * unitMs;
@@ -80,6 +67,26 @@ function parseScheduleValue(raw: string): SkillSchedule["parsed"] {
   return null;
 }
 
+/** Type guard — coerce the parsed-meta value at `key` into a
+ *  string, mirroring the legacy `parseScalar` semantics so this
+ *  refactor stays behaviour-neutral (codex review iter-1 #908):
+ *
+ *    - key absent          → null  (legacy bailed out the same way)
+ *    - string value        → as-is, including the empty string
+ *    - `null` value (from a bare `description:` line that js-yaml
+ *      returns as `null`)  → empty string, matching parseScalar's
+ *      "" return for an empty raw value
+ *    - structured / number → null  (legacy didn't accept either —
+ *      parseScalar's input is always a string slice)
+ */
+function metaString(meta: Record<string, unknown>, key: string): string | null {
+  if (!(key in meta)) return null;
+  const value = meta[key];
+  if (typeof value === "string") return value;
+  if (value === null) return "";
+  return null;
+}
+
 /**
  * Parse a SKILL.md file. Returns null when:
  *  - the file has no frontmatter (no leading `---` fence)
@@ -87,50 +94,26 @@ function parseScheduleValue(raw: string): SkillSchedule["parsed"] {
  *  - there is no `description:` key
  *
  * An empty body is allowed (the skill may be just metadata for now).
+ *
+ * Built on the shared `parseFrontmatter` helper (#895 PR C) so the
+ * envelope / scalar / quote handling matches the rest of the
+ * codebase. Only `description`, `schedule`, and `roleId` are
+ * extracted — extra keys in a SKILL.md file are silently ignored.
  */
-// Extract key-value pairs from YAML frontmatter lines. Returns a
-// map of key → scalar value. Keeps parseSkillFrontmatter under the
-// cognitive-complexity threshold.
-function extractFrontmatterFields(lines: string[], startIdx: number, endIdx: number): Map<string, string> {
-  const fields = new Map<string, string>();
-  for (let i = startIdx; i < endIdx; i++) {
-    const line = lines[i];
-    const colonIdx = line.indexOf(":");
-    if (colonIdx === -1) continue;
-    const key = line.slice(0, colonIdx).trim();
-    const value = parseScalar(line.slice(colonIdx + 1));
-    fields.set(key, value);
-  }
-  return fields;
-}
-
 export function parseSkillFrontmatter(raw: string): ParsedSkill | null {
-  const lines = raw.split(/\r?\n/);
-  if (lines.length === 0 || lines[0].trim() !== "---") return null;
-
-  let closeIdx = -1;
-  for (let i = 1; i < lines.length; i++) {
-    if (lines[i].trim() === "---") {
-      closeIdx = i;
-      break;
-    }
-  }
-  if (closeIdx === -1) return null;
+  const parsed = parseFrontmatter(raw);
+  if (!parsed.hasHeader) return null;
 
-  const fields = extractFrontmatterFields(lines, 1, closeIdx);
-  const description = fields.get("description") ?? null;
+  const description = metaString(parsed.meta, "description");
   if (description === null) return null;
 
-  const scheduleRaw = fields.get("schedule") ?? null;
-  const roleId = fields.get("roleId") ?? null;
+  const scheduleRaw = metaString(parsed.meta, "schedule");
+  const roleId = metaString(parsed.meta, "roleId");
 
-  // Body starts after the closing fence. Trim leading blank lines so
-  // the UI doesn't render an awkward gap above the first heading.
-  const body = lines
-    .slice(closeIdx + 1)
-    .join("\n")
-    .replace(/^(?:\s*\n)+/, "")
-    .trimEnd();
+  // Trim leading blank lines so the UI doesn't render an awkward
+  // gap above the first heading. Pattern + ReDoS-safety rationale
+  // lives in `server/utils/regex.ts`.
+  const body = parsed.body.replace(LEADING_BLANK_LINES_PATTERN, "").trimEnd();
 
   const result: ParsedSkill = { description, body };
   if (scheduleRaw) {

package/server/workspace/skills/user-tasks.ts

@@ -10,11 +10,10 @@
 import { loadUserTasks as loadRaw, saveUserTasks } from "../../utils/files/user-tasks-io.js";
 import type { MissedRunPolicy } from "@receptron/task-scheduler";
 import { SCHEDULE_TYPES, MISSED_RUN_POLICIES } from "@receptron/task-scheduler";
-import type { TaskSchedule as LocalTaskSchedule } from "../../events/task-manager/index.js";
+import type { TaskSchedule as LocalTaskSchedule, ITaskManager } from "../../events/task-manager/index.js";
 import { DEFAULT_ROLE_ID } from "../../../src/config/roles.js";
 import { SESSION_ORIGINS, type SessionOrigin } from "../../../src/types/session.js";
 import { log } from "../../system/logger/index.js";
-import type { ITaskManager } from "../../events/task-manager/index.js";
 import { isRecord } from "../../utils/types.js";
 import { makeUuid } from "../../utils/id.js";