claude-code-session-manager 0.65.0 → 0.66.0

package/src/main/agentLibrary.cjs

@@ -34,6 +34,25 @@ function parseTools(raw) {
 /** Filename-safe persona name: lowercase, hyphenated, matches the `.md` files on disk. */
 const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
 
+/** Sentinel `projects:` entry meaning "this agent's Action button shows in every project". */
+const ALL_PROJECTS = '*';
+
+/**
+ * Frontmatter values are single-line (see lib/prdFrontmatter.cjs) but an
+ * Action's opening instruction is genuinely multi-line prose (the builder
+ * action is `/builder\n\n<instruction>`). Encode newlines as a literal `\n`
+ * two-char sequence on the way out, decode on the way in — one place, so the
+ * round-trip is structural rather than something each caller remembers.
+ */
+function encodeLine(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/\r?\n/g, '\\n');
+}
+
+function decodeLine(s) {
+  if (!s) return '';
+  return String(s).replace(/\\([\\n])/g, (_m, c) => (c === 'n' ? '\n' : '\\'));
+}
+
 /**
  * Serializes a persona's frontmatter + body back to `.md` file text.
  * `tags` is a Claude-Code-agnostic extension of the frontmatter (Claude Code
@@ -41,14 +60,25 @@ const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
  * this persona is associated with, so Agent Library and Tag Library can each
  * assign/remove the relationship from either side. Stored the same
  * comma-list way as `tools` for one parser to cover both.
+ *
+ * `projects` / `action` / `actionLabel` are the same kind of extension, for
+ * the Sessions workspace's per-project **Action buttons**: `projects` is the
+ * list of project cwds (or the `*` sentinel = every project) whose Sessions
+ * toolbar shows a one-click button for this agent, `action` is the opening
+ * instruction that button sends into the new session, and `actionLabel`
+ * overrides the button's caption (defaults to the persona name). Claude Code
+ * ignores all three; only this app reads them.
  */
-function serializePersona({ name, description, tools, model, color, tags, title, body }) {
+function serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body }) {
   const lines = ['---', `name: ${name}`];
   if (description) lines.push(`description: ${description}`);
   if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
   if (model && model !== 'inherit') lines.push(`model: ${model}`);
   if (color) lines.push(`color: ${color}`);
   if (tags && tags.length) lines.push(`tags: ${tags.join(', ')}`);
+  if (projects && projects.length) lines.push(`projects: ${projects.join(', ')}`);
+  if (action) lines.push(`action: ${encodeLine(action)}`);
+  if (actionLabel) lines.push(`actionLabel: ${encodeLine(actionLabel)}`);
   if (title) lines.push(`title: ${title}`);
   lines.push('---', '');
   return lines.join('\n') + (body || '').trim() + '\n';
@@ -67,6 +97,9 @@ async function savePersona({
   model,
   color,
   tags,
+  projects,
+  action,
+  actionLabel,
   title,
   body,
   globalDir = path.join(os.homedir(), '.claude', 'agents'),
@@ -77,7 +110,7 @@ async function savePersona({
     throw new Error('agent name must be lowercase, hyphenated (e.g. "my-agent")');
   }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  const text = serializePersona({ name, description, tools, model, color, tags, title, body });
+  const text = serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
@@ -203,6 +236,9 @@ async function listPersonas({
       model: fm.model || null,
       color: fm.color || null,
       tags: parseTools(fm.tags),
+      projects: parseTools(fm.projects),
+      action: decodeLine(fm.action) || null,
+      actionLabel: decodeLine(fm.actionLabel) || null,
       title: fm.title || null,
       path: real,
       body: body.trim(),
@@ -220,5 +256,7 @@ module.exports = {
   savePersona,
   deletePersona,
   removeOverride,
+  serializePersona,
   PERSONA_NAME_RE,
+  ALL_PROJECTS,
 };

package/src/main/index.cjs

@@ -26,6 +26,7 @@ const voiceWizard = require('./voiceWizard.cjs');
 const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
+const prdAdminRoutes = require('./lib/prdAdminRoutes.cjs');
 const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
@@ -37,6 +38,7 @@ const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
+prdAdminRoutes.registerAdminRoute(adminHttp, scheduler.remote);
 chatRunner.registerAdminRoute(adminHttp);
 const supervisor = require('./supervisor.cjs');
 const watchers = require('./watchers.cjs');

package/src/main/ipcSchemas.cjs

@@ -327,6 +327,62 @@ const scheduleRetagPrd = z.object({
   items: z.array(scheduleRetagItem).min(1).max(500),
 });
 
+// ──────────────────────────────────────────── Admin API — PRD lifecycle (PRD 1024)
+//
+// GET routes parse their input from URLSearchParams (all values arrive as
+// strings), so numeric/array fields aren't accepted here — only slug/cwd/
+// epicId/status, matching what a query string can actually carry.
+const adminListPrdsQuery = z.object({
+  cwd: z.string().min(1).max(4096).optional(),
+  epicId: z.string().min(1).max(200).optional(),
+  status: z.string().min(1).max(40).optional(),
+});
+
+const adminGetPrdQuery = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
+});
+
+// Partial frontmatter patch for update-prd — same recognized-key set as
+// prdFrontmatter.cjs's parsePrdFile/serializePrdFile round-trip pair. Every
+// field optional; the route refuses an empty patch+no-body request via the
+// top-level .refine below.
+const adminPrdFrontmatterPatch = z.object({
+  title: z.string().min(1).max(200).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  cwd: z.string().min(1).max(4096).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  estimateMinutes: z.number().int().min(1).max(100000).optional(),
+  parallelGroup: z.number().int().min(0).max(999999).optional(),
+  sourcePromptId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  sourceTabId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  // 'discussion' deliberately excluded: matches prdFrontmatter.cjs's
+  // parsePrdFile, which never parses that value for a PRD's tag key (a
+  // discussion-tagged Epic never reaches PRD authoring).
+  tag: z.enum(['feature', 'bug', 'build']).optional(),
+  // Provenance stamp (PRD-authoring lockdown). Free-text rather than an enum
+  // — 'scheduler-api' (create-time) and 'legacy-adopted' (migration/manual
+  // adopt) are the two values this codebase writes today, but the field
+  // itself is descriptive, not a closed set.
+  createdVia: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+  issuedAt: z.string().min(1).max(64).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
+});
+
+const adminUpdatePrd = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+  cwd: z.string().min(1).max(4096).optional(),
+  frontmatter: adminPrdFrontmatterPatch.optional(),
+  body: z.string().refine(
+    (s) => Buffer.byteLength(s, 'utf8') <= PRD_WRITE_MAX_BYTES,
+    `body must be ≤ ${PRD_WRITE_MAX_BYTES} bytes`,
+  ).optional(),
+}).refine(
+  (it) => (it.frontmatter && Object.keys(it.frontmatter).length > 0) || it.body !== undefined,
+  'at least one of frontmatter or body is required',
+);
+
+const adminCancelJob = z.object({
+  slug: z.string().regex(SCHEDULE_SLUG_RE),
+});
+
 // ──────────────────────────────────────────── Projects
 const ENCODED_SLUG_RE = /^[A-Za-z0-9._-]+$/;
 
@@ -812,6 +868,10 @@ module.exports = {
     schedulerCreatePrd,
     scheduleArchivePrd,
     scheduleRetagPrd,
+    adminListPrdsQuery,
+    adminGetPrdQuery,
+    adminUpdatePrd,
+    adminCancelJob,
     setConfigSchema,
     setSessionSlotsSchema,
     shellOpen,

package/src/main/lib/localAdminHttp.cjs

@@ -151,17 +151,24 @@ function createAdminHttp() {
       sendJson(res, 401, { ok: false, error: 'unauthorized' });
       return;
     }
-    if (req.method === 'GET' && req.url === HEALTH_PATH) {
+    // Route lookup is keyed by pathname only — req.url carries the raw query
+    // string too, which would otherwise never match a registered route (every
+    // route before PRD 1024 was query-free, so this was a latent gap, not a
+    // behavior change for them). `query` is handed to the route handler as a
+    // third argument (URLSearchParams) for routes that need it (e.g. GET
+    // /admin/scheduler/prds?cwd=&epicId=&status=).
+    const urlObj = new URL(req.url, 'http://127.0.0.1');
+    if (req.method === 'GET' && urlObj.pathname === HEALTH_PATH) {
       sendJson(res, 200, { ok: true });
       return;
     }
     try {
-      const handler = routes.get(`${req.method} ${req.url}`);
+      const handler = routes.get(`${req.method} ${urlObj.pathname}`);
       if (!handler) {
         sendJson(res, 404, { ok: false, error: 'not found' });
         return;
       }
-      await handler(req, res);
+      await handler(req, res, urlObj.searchParams);
     } catch (e) {
       sendJson(res, 500, { ok: false, error: e?.message ?? 'internal error' });
     }

package/src/main/lib/prdAdminRoutes.cjs

@@ -0,0 +1,175 @@
+/**
+ * prdAdminRoutes.cjs — admin HTTP routes closing the PRD-lifecycle capability
+ * gap (PRD 1024, step 1 of locking the PRD entity behind the scheduler
+ * service boundary — see that PRD's Goal). Before this file, the admin API
+ * exposed only create-prd/jobs/reset-job/send-prompt: there was no way to
+ * READ, LIST, EDIT, ARCHIVE, or CANCEL a PRD/job over HTTP, which is exactly
+ * why direct filesystem access to session-manager-operations/scheduler/ was
+ * still sanctioned. This file plumbs those operations to HTTP; it adds no
+ * enforcement/denial of direct access — that's the dependent PRD's job (see
+ * this PRD's "Out of scope").
+ *
+ * Every route here reuses an existing verified implementation rather than
+ * reimplementing it:
+ *   - list/get/update/cancel delegate to scheduler.cjs's `remote` object
+ *     (job-status-aware; remote already owns the PRD-dir search + symlink
+ *     defense patterns these need)
+ *   - archive/retag delegate to queueOps.cjs's archiveMany/retagMany
+ *     directly (job-status-agnostic bulk file ops; already used by the
+ *     renderer's schedule:archive-prd/schedule:retag-prd IPC handlers)
+ *
+ * Registered against the same injected localAdminHttp.cjs transport as
+ * scheduler.cjs's registerAdminRoutes and prdCreate.cjs's registerAdminRoute
+ * (see index.cjs) — auth, loopback-only binding, and the bearer-token
+ * lifecycle are all the transport's job, not this file's.
+ */
+'use strict';
+
+const { schemas } = require('../ipcSchemas.cjs');
+const { readBody, sendJson } = require('./localAdminHttp.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
+const queueOps = require('../queueOps.cjs');
+
+function parseJsonBody(raw) {
+  try {
+    return { ok: true, value: raw ? JSON.parse(raw) : {} };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * registerAdminRoute(adminHttp, remote) — `remote` is scheduler.cjs's
+ * `remote` object, injected (not required directly) so this file stays
+ * testable without booting Electron, matching prdCreate.cjs's and
+ * scheduler.cjs's own registerAdminRoute(s) pattern.
+ */
+function registerAdminRoute(adminHttp, remote) {
+  adminHttp.registerRoute('GET', '/admin/scheduler/prds', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminListPrdsQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    const prds = await remote.listPrds(input);
+    sendJson(res, 200, { ok: true, prds });
+  });
+
+  adminHttp.registerRoute('GET', '/admin/scheduler/prd', async (req, res, query) => {
+    let input;
+    try {
+      input = schemas.adminGetPrdQuery.parse(Object.fromEntries(query ?? []));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid query', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.getPrdParsed(input.slug, input.cwd);
+    if (!result.ok) {
+      sendJson(res, 404, result);
+      return;
+    }
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/update-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminUpdatePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.updatePrd(input);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : /status is/i.test(result.error ?? '') ? 409 : 400;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_prd_update', { route: '/admin/scheduler/update-prd', slug: input.slug, cwd: input.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/archive-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleArchivePrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.archiveMany(input.slugs);
+    // Audit only the slugs that actually archived — archiveMany's `results`
+    // array carries the real per-slug outcome; logging every requested slug
+    // regardless of whether it succeeded would misrepresent a partial-failure
+    // batch as a clean one in audit-log.jsonl.
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_archive', { route: '/admin/scheduler/archive-prd', slug: r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/cancel-job', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminCancelJob.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await remote.cancelJob(input.slug);
+    if (!result.ok) {
+      const status = /not found/i.test(result.error ?? '') ? 404 : 409;
+      sendJson(res, status, result);
+      return;
+    }
+    appendAuditEvent('admin_job_cancel', { route: '/admin/scheduler/cancel-job', slug: input.slug, cwd: result.cwd ?? null });
+    sendJson(res, 200, result);
+  });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/retag-prd', async (req, res) => {
+    const raw = await readBody(req);
+    const parsedBody = parseJsonBody(raw);
+    if (!parsedBody.ok) {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.scheduleRetagPrd.parse(parsedBody.value);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const result = await queueOps.retagMany(input.items);
+    // Audit only the items that actually retagged (see the archive-prd route
+    // above for why this must read result.results rather than the request).
+    for (const r of result.results ?? []) {
+      if (!r.ok) continue;
+      appendAuditEvent('admin_prd_retag', { route: '/admin/scheduler/retag-prd', slug: r.newSlug ?? r.slug, cwd: null });
+    }
+    sendJson(res, result.ok ? 200 : 500, result);
+  });
+}
+
+module.exports = { registerAdminRoute };

package/src/main/lib/prdCreate.cjs

@@ -57,6 +57,15 @@ function buildPrdBody(input) {
   // filename prefix is the single source of truth for grouping; adding a
   // second one here would let the two drift out of sync.
   const fmLines = ['---', `title: ${title}`, `cwd: ${cwd}`, `estimateMinutes: ${estimateMinutes}`];
+  // Provenance stamp (PRD-authoring lockdown): every PRD written through this
+  // function — the sole in-process implementation behind both the admin
+  // HTTP create-prd route and the renderer's chat:create-prd IPC handler —
+  // carries proof it was authored via the API, not a bare Write/Edit tool
+  // call. scheduler.cjs's reconcile() refuses to run a discovered PRD with no
+  // `createdVia` (quarantines it instead); this line is why every
+  // API-created PRD is exempt. Stamped here, not left to a caller, so the
+  // guarantee can't be forgotten by a future route.
+  fmLines.push('createdVia: scheduler-api', `issuedAt: ${new Date().toISOString()}`);
   // Optional, additive: traces this PRD back to the PromptTicket (PRD 748)
   // that was classified 'develop' and spawned it (PRD 749).
   if (sourcePromptId) fmLines.push(`sourcePromptId: ${sourcePromptId}`);
@@ -204,7 +213,24 @@ async function createPrd(input, remote) {
     sourceTabId: input.sourceTabId ?? null,
   });
 
-  return { ok: true, nn, filename: `${filenameSlug}.md` };
+  // No `status` field here, and never one named 'queued' — that string was
+  // handed straight to callers as if it were a real ScheduleJob status, and
+  // is exactly how the 1021/1022 incident's invalid `"status": "queued"`
+  // rows got onto disk (this route's own response was the most likely
+  // source). A PRD is a queue row's SOURCE, not the row itself: writePrd
+  // only ever joins an Epic and writes the .md file — the queue row is
+  // created separately, by the next reconcile() pass. `enqueued: false` is
+  // true by construction (this function never touches queue.json), so no
+  // caller can copy a fake job status out of this response again.
+  return {
+    ok: true,
+    nn,
+    filename: `${filenameSlug}.md`,
+    prdPath: writeResult.path ?? null,
+    epicId: writeResult.epicId ?? null,
+    enqueued: false,
+    note: 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
+  };
 }
 
 /**
@@ -240,7 +266,16 @@ function registerAdminRoute(adminHttp, remote) {
       return;
     }
 
-    sendJson(res, 200, { nn: result.nn, filename: result.filename, status: 'queued' });
+    // Mirror createPrd()'s own honest shape verbatim — never re-add a
+    // 'status' field here. See createPrd's return above for why.
+    sendJson(res, 200, {
+      nn: result.nn,
+      filename: result.filename,
+      prdPath: result.prdPath ?? null,
+      epicId: result.epicId ?? null,
+      enqueued: false,
+      note: result.note,
+    });
   });
 }
 

package/src/main/lib/prdFrontmatter.cjs

@@ -48,4 +48,182 @@ function splitFrontmatter(raw) {
   };
 }
 
-module.exports = { splitFrontmatter };
+/**
+ * parsePrdFile / serializePrdFile — CJS port of
+ * src/renderer/lib/prdFrontmatter.ts's round-trip parse+serialize pair, so
+ * main-process callers (the admin update-prd route, PRD 1024) get the same
+ * "unrecognized keys round-trip verbatim via `extras`, recognized keys emit
+ * in a stable order, unchanged values re-emit their original line verbatim"
+ * guarantee the renderer's PRD editor already relies on — an edit through
+ * either surface never reorders or drops a key it didn't touch. Recognized
+ * key set intentionally mirrors the TS module exactly (title, cwd,
+ * estimateMinutes, parallelGroup, sourcePromptId, sourceTabId, tag,
+ * createdVia, issuedAt); every other frontmatter key (e.g. dependsOn)
+ * round-trips via `extras`, same as the renderer's editor today.
+ *
+ * `createdVia`/`issuedAt` (PRD provenance-lockdown) are recognized here so
+ * the update-prd route (the only sanctioned way to stamp a PRD's provenance
+ * after creation — see prdCreate.cjs's buildPrdBody for the create-time
+ * stamp) round-trips them like any other known key rather than shunting them
+ * into `extras`.
+ */
+
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'createdVia', 'issuedAt'];
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+function indentOf(line) {
+  let n = 0;
+  for (const ch of line) {
+    if (ch === ' ') n++;
+    else if (ch === '\t') n += 2;
+    else break;
+  }
+  return n;
+}
+
+function parseScalar(raw) {
+  const v = raw.trim();
+  if (v === '' || v === '~' || v === 'null') return null;
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+$/.test(v)) return Number(v);
+  if (/^-?\d+\.\d+$/.test(v)) return Number(v);
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+function applyKey(fm, key, after) {
+  const v = parseScalar(after);
+  if (v === null) return;
+  switch (key) {
+    case 'estimateMinutes':
+      fm.estimateMinutes = typeof v === 'number' ? v : Number(v);
+      return;
+    case 'parallelGroup':
+      fm.parallelGroup = typeof v === 'number' ? v : Number(v);
+      return;
+    case 'title':
+      fm.title = String(v);
+      return;
+    case 'cwd':
+      fm.cwd = String(v);
+      return;
+    case 'sourcePromptId':
+      fm.sourcePromptId = String(v);
+      return;
+    case 'sourceTabId':
+      fm.sourceTabId = String(v);
+      return;
+    case 'tag':
+      // Matches the TS source's applyKey exactly: a 'discussion'-tagged
+      // ticket never reaches PRD authoring, so that value is never parsed
+      // here even if present in a hand-edited file — see this file's header
+      // comment.
+      if (v === 'feature' || v === 'bug' || v === 'build') fm.tag = v;
+      return;
+    case 'createdVia':
+      fm.createdVia = String(v);
+      return;
+    case 'issuedAt':
+      fm.issuedAt = String(v);
+      return;
+  }
+}
+
+/** Parse a full PRD file into { frontmatter, body }, same shape as the TS module. */
+function parsePrdFile(text) {
+  const m = text.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: text };
+  const fmText = m[1];
+  const body = m[2] ?? '';
+
+  const lines = fmText.split(/\r?\n/);
+  const fm = {};
+  const extras = {};
+
+  for (let i = 0; i < lines.length;) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith('#')) { i++; continue; }
+    const ind = indentOf(line);
+    if (ind !== 0) { i++; continue; }
+    const colon = line.indexOf(':');
+    if (colon < 0) { i++; continue; }
+    const key = line.slice(0, colon).trim();
+    const after = line.slice(colon + 1);
+    let j = i + 1;
+    const band = [line];
+    while (j < lines.length) {
+      const nxt = lines[j];
+      if (nxt.trim() === '' || nxt.trimStart().startsWith('#')) { band.push(nxt); j++; continue; }
+      if (indentOf(nxt) === 0 && nxt.indexOf(':') >= 0) break;
+      band.push(nxt);
+      j++;
+    }
+
+    if (RECOGNIZED_KEYS.has(key)) {
+      applyKey(fm, key, after);
+      const parsed = parseScalar(after);
+      if (parsed !== null && (typeof parsed === 'string' || typeof parsed === 'number')) {
+        if (!fm._raw) fm._raw = {};
+        fm._raw[key] = { line, parsed };
+      }
+    } else {
+      extras[key] = { lines: band };
+    }
+    i = j;
+  }
+
+  if (Object.keys(extras).length) fm.extras = extras;
+  return { frontmatter: fm, body };
+}
+
+function serializeScalar(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  const s = String(v);
+  const needsQuote =
+    s === '' ||
+    /^(true|false|null|~)$/.test(s) ||
+    /^-?\d+(\.\d+)?$/.test(s) ||
+    /^\s|\s$/.test(s) ||
+    s.startsWith("'") ||
+    s.startsWith('"') ||
+    s.includes('\n');
+  if (!needsQuote) return s;
+  if (s.includes("'")) return `"${s.replace(/"/g, '\\"')}"`;
+  return `'${s}'`;
+}
+
+/** Serialize { frontmatter, body } back to a full file. Byte-identical round-trip when unchanged. */
+function serializePrdFile(fm, body) {
+  const out = [];
+  for (const key of EMIT_ORDER) {
+    const v = fm[key];
+    if (v === undefined || v === null || v === '') continue;
+    const cached = fm._raw?.[key];
+    if (cached && cached.parsed === v) {
+      out.push(cached.line);
+      continue;
+    }
+    if (typeof v === 'number') {
+      out.push(`${key}: ${v}`);
+      continue;
+    }
+    out.push(`${key}: ${serializeScalar(v)}`);
+  }
+  if (fm.extras) {
+    for (const k of Object.keys(fm.extras)) {
+      const band = fm.extras[k];
+      if (!band || !band.lines.length) continue;
+      out.push(band.lines.join('\n'));
+    }
+  }
+
+  const fmText = out.join('\n');
+  return `---\n${fmText}\n---\n${body}`;
+}
+
+module.exports = { splitFrontmatter, parsePrdFile, serializePrdFile, RECOGNIZED_KEYS };