kandev/docs/specs/ui/requirements/comment-markdown.md

status, system, created, owners

status	system	created	owners
active	ui	2026-04-28	cfl

Comment Markdown Rendering Requirements

Overview

Task comments render as plain text with whitespace-pre-wrap. Agent responses routinely include markdown — code blocks, headers, bold text, lists — which renders as raw punctuation instead of formatted output.

Requirements

REQ-UI-COMMENT-MARKDOWN-001: Comment Markdown Rendering

Intent: Task comments render as plain text with whitespace-pre-wrap. Agent responses routinely include markdown — code blocks, headers, bold text, lists — which renders as raw punctuation instead of formatted output.

Acceptance criteria

• AC-UI-COMMENT-MARKDOWN-001.1: Comments render as rich GitHub-flavored markdown: headers, bold, italic, inline code, fenced code blocks, blockquotes, ordered and unordered lists, and tables.
• AC-UI-COMMENT-MARKDOWN-001.2: react-markdown with remark-gfm processes comment content. rehype-sanitize blocks raw HTML injection (already in dependencies). No dangerouslySetInnerHTML.
• AC-UI-COMMENT-MARKDOWN-001.3: Fenced code blocks display syntax highlighting and a one-click copy button.
• AC-UI-COMMENT-MARKDOWN-001.4: Bare URLs in comment text are auto-linked (handled by remark-gfm linkify).
• AC-UI-COMMENT-MARKDOWN-001.5: Markdown links to files in the active task workspace open the in-app file viewer; absolute workspace, worktree, and workspace-root-relative paths may include supported source-location suffixes without navigating the browser away from the task.
• AC-UI-COMMENT-MARKDOWN-001.6: Patterns matching [A-Z]+-\d+ (e.g., KAN-42, QA-7) are rendered as links to /office/tasks/<identifier>. The link uses the raw identifier as the URL segment; resolution to an internal task ID (if needed) is handled by the issue page.
• AC-UI-COMMENT-MARKDOWN-001.7: The comment list in TaskChat renders the available comments in transcript order.
• AC-UI-COMMENT-MARKDOWN-001.8: Scroll position is preserved when new comments arrive if the user has scrolled away from the bottom.
• AC-UI-COMMENT-MARKDOWN-001.9: When a task message links to an absolute file path beneath a repository checkout registered to that task, but the active session uses a different worktree path for the same repository, selecting the link opens the corresponding file from the active task workspace on desktop and phone. Kandev does not read or edit the registered source checkout.
• AC-UI-COMMENT-MARKDOWN-001.10: When an absolute host file path cannot be mapped to the active task workspace or to a registered repository represented by that workspace, selecting it does not navigate the current Kandev tab or issue a workspace file request.

Migrated source detail

Why

Task comments render as plain text with whitespace-pre-wrap. Agent responses routinely include markdown — code blocks, headers, bold text, lists — which renders as raw punctuation instead of formatted output.

What

• Comments render as rich GitHub-flavored markdown: headers, bold, italic, inline code, fenced code blocks, blockquotes, ordered and unordered lists, and tables.
• react-markdown with remark-gfm processes comment content. rehype-sanitize blocks raw HTML injection (already in dependencies). No dangerouslySetInnerHTML.
• Fenced code blocks display syntax highlighting and a one-click copy button.
• Bare URLs in comment text are auto-linked (handled by remark-gfm linkify).
• Markdown links to files in the active task workspace open the in-app file viewer; absolute workspace, worktree, and workspace-root-relative paths may include supported source-location suffixes without navigating the browser away from the task.
• Absolute paths beneath a task-linked repository's registered source checkout map by repository identity to the corresponding active worktree. The registered checkout itself is never read or edited.
• Patterns matching [A-Z]+-\d+ (e.g., KAN-42, QA-7) are rendered as links to /office/tasks/<identifier>. The link uses the raw identifier as the URL segment; resolution to an internal task ID (if needed) is handled by the issue page.
• The comment list in TaskChat renders the available comments in transcript order.
• Scroll position is preserved when new comments arrive if the user has scrolled away from the bottom.
• When the user is at (or near) the bottom, new comments auto-scroll into view.

Scenarios

• GIVEN a comment with **bold** and \code``, WHEN rendered, THEN bold text and inline code appear styled, not as raw characters.
• GIVEN a comment containing a fenced code block, WHEN rendered, THEN the block has syntax highlighting and a copy button that copies the block contents.
• GIVEN a comment containing the text see KAN-42 for context, WHEN rendered, THEN KAN-42 is a clickable link navigating to /office/tasks/KAN-42.
• GIVEN a comment containing https://example.com, WHEN rendered, THEN the URL is a clickable hyperlink.
• GIVEN a comment contains a markdown link to /root/.kandev/tasks/example/kandev/.github/workflows/build.yml:12, WHEN the user clicks it while the active worktree is /root/.kandev/tasks/example/kandev, THEN the in-app editor opens .github/workflows/build.yml instead of navigating to that absolute URL.
• GIVEN a task uses a worktree for a repository registered at /home/user/projects/example, WHEN a message links to /home/user/projects/example/ui/bundle.js:61, THEN Kandev opens the active worktree's ui/bundle.js in the desktop file tab or phone file viewer without navigating to a same-origin /home/user/projects/... URL.
• GIVEN a message links to an absolute host path that is neither in the active task workspace nor under a registered repository represented by that workspace, WHEN the user selects it, THEN Kandev leaves the task visible and does not request that path from the workspace file service.
• GIVEN the user has scrolled up to read earlier comments and a new comment arrives, WHEN the comment is appended, THEN the scroll position does not move.
• GIVEN the user is at the bottom of the thread and a new comment arrives, WHEN the comment is appended, THEN the viewport auto-scrolls to show the new comment.

Out of scope

• Editing or previewing markdown in the comment input box (input remains plain text).
• Server-side markdown storage or transformation — content is stored as raw text and rendered client-side only.
• Reading or editing a registered repository's source checkout; source-path links always resolve to the active task workspace copy.
• Resolving task identifier links to internal UUIDs before navigation (the issue page handles that).
• Emoji shortcode rendering (:+1: etc.) — remark-gemoji is present in dependencies but not required by this spec.
• Notifications or unread indicators for new comments.

Open questions

• Should the task-identifier regex be configurable (project key prefixes), or is a general [A-Z]+-\d+ pattern acceptable for all workspaces?
• Which syntax highlighting library to use — rehype-highlight (highlight.js) or rehype-pretty-code (shiki)? Shiki gives better theming but adds bundle weight.