diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index b281c5734..8cac6db7c 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -2,6 +2,14 @@
 
 > 策划历史条目边界：旧策划 V1/V2 已全部退役，当前入口仅使用 Design Agent。下文带日期的旧 Planning V2、Fast GDD、`plan.submit_gdd`、旧 IPC/模块记录仅用于追溯，不能作为恢复旧代码、身份门禁或专属测试的依据；共享问题需在现役调用上核查。现行合同见[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。
 
+## 2026-09-24 模型输出的围栏会粘在正文行里：聊天 Markdown 必须先归一化再解析
+
+- **现象**：AGC 对话里代码块解析错位——引言行被当成代码渲染（`…实现细节（game.js）：```js`），或者代码块收不住、把后面的正文一起吞进去（`… return centerOn(projection); }````）。文本本身「看起来没问题」，容易被当成渲染器坏了。
+- **原因**：CommonMark 只认**整行**的围栏（最多 3 个空格缩进）。模型经常把 ``` 直接粘在上一行末尾，那个 ``` 退化成行内文本：开场围栏不成立（后面的正文被当成代码）、收场围栏不生效（代码块不闭合，吞掉剩余内容）。`ChatMarkdownMessage` 原先只做空行压缩，没有这一步归一化。
+- **处理（现行口径）**：`normalizeMarkdownFences` 在解析前把「围栏前是非空白字符、围栏到行尾只剩语言标识（可空）」的行拆成两行。判据刻意收窄：整行 / 缩进围栏、行内代码（单个反引号）、代码里出现的 ``` （`const s = "```";`）以及引用块 / 列表项开头的合法围栏（`> ```js`、`- ```js`）都不动——后两者拆开只会把围栏从引用块 / 列表项里挪出来。归一化对 `preserveBlankLines`（文件预览）同样生效。
+- **同时**：块级 `pre` 与块内 `code` 都要给 `whitespace-pre-wrap` + `break-words`（两处各写过 `white-space`，只改一处不换行），否则窄面板里长行会把消息拉宽、顶出横向滚动条。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/ChatMarkdownMessage.test.tsx`（去掉归一化或换行类名即红）；真实 Chromium 夹具里长代码行 `horizontalOverflow: false`、粘住的开场 / 收场围栏都渲染成正确结构。
+
 ## 2026-09-24 对话过程卡的读秒退回 1 秒一跳：刷新粒度必须与显示精度同格
 
 - **现象**：AGC DirectProject 对话区底部那条「陶泥儿正在处理 / 已耗时 12.4秒」的状态条，小数位一秒才动一格，看着像读数卡住；同一屏里工具卡片的耗时与资源生成侧栏的读秒都在正常走 0.1 秒，只有这一处不动。