Function appendIssueComment

src/workspaces/issues/mutate.ts:178–208

(
  wsDir: string,
  id: string,
  author: string,
  text: string,
)

 * Returns the re-validated record, or `not_found` when the file is absent.
 */
export async function appendIssueComment(
  wsDir: string,
  id: string,
  author: string,
  text: string,
): Promise<MutateResult> {
  if (!ID_RE.test(id)) return { ok: false, reason: 'not_found' }
  const raw = await readWorkspaceFile(wsDir, relFor(id))
  if (raw === null) return { ok: false, reason: 'not_found' }

  const split = splitFrontmatter(raw)
  if (!split) return { ok: false, reason: 'invalid', error: 'missing YAML frontmatter' }
  // Validate the existing file so we don't grow a comment onto a broken issue.
  const current = parseIssueContent(id, raw)
  if (!current.ok) return { ok: false, reason: 'invalid', error: current.error }

  const stamp = new Date().toISOString()
  const block = `**${author}** · ${stamp}\n\n${text.trim()}`

  const body = split.body
  const hasSection = /^##\s+Comments\s*$/m.test(body)
  const base = hasSection ? body : `${body}${body ? '\n\n' : ''}${COMMENTS_HEADING}`
  const newBody = `${base}\n\n${block}`

  // Preserve the frontmatter raw (no re-serialize) — a comment is body-only.
  const content = `---\n${split.frontmatter}\n---\n\n${newBody}\n`
  const reparsed = parseIssueContent(id, content)
  if (!reparsed.ok) return { ok: false, reason: 'invalid', error: reparsed.error }
  await writeWorkspaceFile(wsDir, relFor(id), content)
  return { ok: true, issue: reparsed.issue }
}

/**
 * Create a new issue file. Derives a kebab slug from `title` when `id` is