The Plan pane could render an entire plan document as one giant H1 with
`##` markers showing inline (e.g. "…plan pack)## The goal, restatedYou
picked…") when a producer wrote the plan document body with its
paragraph/heading newlines collapsed onto a single line.
Two layers:
- Producer (source): the plan-authoring guidance modeled the body as a
single-line `"# Plan\n\n…"` template, inviting flattened bodies. Add
explicit formatting rules (each heading on its own line, blank line
between blocks, JSON-safe encoding) and a multi-section example.
Reinforce the same rule in the onboarding publish contract.
- Write-path guard (defense-in-depth): multilineTextSchema now runs
normalizeMidLineHeadings after escaped-break normalization. It inserts
a paragraph break before a mid-line ATX heading marker (`#{1,6} `) so a
malformed single-line body self-heals into headings/paragraphs. Scoped
to skip fenced code blocks and to leave inline `#` tokens (C#, F#,
#hashtags, #123) untouched.
Unit tests cover the guard (mid-line `##` break, C#/F#/hashtag/code-fence
exclusions, leading-heading no-op).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - The board and agent APIs accept multiline issue, approval,
interaction, and document text
> - Some callers accidentally send literal escaped newline sequences
like `\n` instead of JSON-decoded line breaks
> - That makes comments, descriptions, documents, and approval notes
render as flattened text instead of readable markdown
> - This pull request centralizes multiline text normalization in shared
validators
> - The benefit is newline-preserving API behavior across issue and
approval workflows without route-specific fixes
## What Changed
- Added a shared `multilineTextSchema` helper that normalizes escaped
`\n`, `\r\n`, and `\r` sequences to real line breaks.
- Applied the helper to issue descriptions, issue update comments, issue
comment bodies, suggested task descriptions, interaction summaries,
issue documents, approval comments, and approval decision notes.
- Added shared validator regressions for issue and approval multiline
inputs.
## Verification
- `pnpm exec vitest run --project @paperclipai/shared
packages/shared/src/validators/approval.test.ts
packages/shared/src/validators/issue.test.ts`
- `pnpm --filter @paperclipai/shared typecheck`
## Risks
- Low risk. This only changes text fields that are explicitly multiline
user/operator content.
- If a caller intentionally wanted literal backslash-n text in these
fields, it will now render as a real line break.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, GPT-5 coding agent, tool-enabled with
shell/GitHub/Paperclip API access. Context window was not reported by
the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
scotttong