@michelj/context-guard 0.4.3 → 0.6.1

package/references/memory-definition.md

@@ -0,0 +1,120 @@
+# 记忆定义与撰写规范
+
+版本：v0.2
+
+读者：Coordinator。创建、修改、合并或清理项目与节点记忆前阅读本文。
+
+本文规定项目记忆和节点记忆写什么、怎样组织，以及 Coordinator 何时维护。文档随 Main Map 版本保存，使用现有 `edit_map` 和单文件读取接口；不新增权限体系。自动更新记忆仍未实现。
+
+## 记忆的定义
+
+记忆是供 Agent 接手项目时阅读的最新项目说明，不是完整对话、操作日志或任务记录的集合。项目记忆作为静态上下文，在用户第一次对话前由 Agent 阅读；节点记忆提供对应模块的细节，在处理该模块时按需读取。
+
+了解项目不是读完所有对话或文档，而是能够回答以下六方面的问题。
+
+- **目标**：项目为什么存在，要解决什么问题，做到什么程度才算成功，以及明确不解决哪些问题。
+- **用户**：谁会使用项目，在什么情况下使用，想完成什么事情，对使用方式有什么要求。
+- **能力**：项目目前能做什么，每项功能接收什么、产生什么结果，在什么条件下可用，有哪些限制。
+- **协作**：项目由哪些模块组成，各自负责什么，谁调用谁，信息如何传递，哪些事情必须配合完成。
+- **进展**：对照目标，哪些已经完成并验证，哪些尚未完成，当前卡在哪里。只保留最新状态，不记录操作过程。
+- **约束**：后续开发必须遵守哪些规则，哪些决定已经确认，为什么这样决定。尚未确定的讨论不能作为规则。
+
+## 文档位置与标题
+
+项目级和节点级都使用 Markdown。下面的位置指服务器上的逻辑记忆目录，不是要求在源码仓库中新增这些文件；服务器保存权威版本，本地只作为缓存或待同步草稿。项目根节点的 `memoryDocument` 投影为项目 `memory.md`，其他节点的同名字段投影到各节点目录的 `memory.md`。没有文档的节点不生成空文件。
+
+旧 `memories[]` 卡片不再是日常记忆编辑入口。工作台只提供按需打开的只读历史迁移预览，保留原文、附件引用和提案依据等元数据；用户可复制历史，人工整理到对应记忆文档并明确保存。预览不自动归类、追加正文、删除历史或生成完成事项记忆；保存仍使用现有版本校验事务，冲突时保留草稿。
+
+| 文档 | 逻辑位置 | 一级标题 |
+| --- | --- | --- |
+| 项目记忆 | 项目根目录 `memory.md` | `# 项目名称 · 项目记忆` |
+| 节点记忆 | 对应节点目录 `memory.md` | `# 节点名称 · 节点记忆` |
+
+项目记忆固定使用六个二级标题，名称和顺序不得更换：
+
+```markdown
+# 项目名称 · 项目记忆
+
+## 目标
+
+## 用户
+
+## 能力
+
+## 协作
+
+## 进展
+
+## 约束
+```
+
+节点记忆沿用相同的六个标题及顺序，只保留适用的部分，不用其他名称代替它们。适用但尚未明确的内容可以注明“尚未确认”，不能为了填满章节而编造。
+
+正文使用自然段或列表。目标、能力和规则适合逐点列出；职责和协作关系适合连贯说明。不要把每条记忆写成“编号／内容／依据／更新”的表单，不强制附加 P、R、E 或 001 等编号。
+
+来源、修改时间和历史版本由系统记录，不要求 Coordinator 在正文反复填写。需要向人展示日期时使用 `YYYYMMDD`。这不表示可以省略事实核实或修改追踪。
+
+## 项目与节点分别写什么
+
+| 部分 | 项目记忆 | 节点记忆 |
+| --- | --- | --- |
+| 目标 | 整个项目解决的问题、成功标准和不做的事情 | 本模块承担的目标、职责边界和不负责的事情 |
+| 用户 | 项目的使用者、主要场景和使用要求 | 使用本模块的人或调用它的其他模块，以及他们要完成的事情 |
+| 能力 | 主要能力概览和影响全局的限制 | 具体功能、输入输出、使用条件和局部限制 |
+| 协作 | 主要模块的分工与整体协作关系 | 与其他模块的依赖、调用和信息传递关系 |
+| 进展 | 整体完成情况、尚未完成的主要能力和关键阻塞 | 本模块已验证的结果、未完成部分和局部阻塞 |
+| 约束 | 全项目必须遵守的要求和已确认的取舍 | 本模块修改时必须保留的行为、兼容要求和局部规则 |
+
+项目记忆应让 Agent 先理解全貌，不展开所有模块细节。节点记忆应让 Agent 理解处理该模块所需的背景，不复制项目级规则，也不承诺代替阅读代码和接口文档。
+
+### 如何处理每个节点
+
+- 记忆跟随节点所代表的职责，不跟随某次任务或某个执行 Session。同一模块的多次开发更新同一份节点记忆。
+- 只影响某个节点的内容写在该节点；改变全局目标、整体协作或全局规则时，才更新项目记忆。
+- 有子节点时，父节点说明整体职责和子节点分工，具体行为留在对应子节点。只有会影响父级判断的变化才向上概括，不把子节点正文逐份复制上去。
+- 涉及多个模块时，各节点写自己的责任，项目级或共同父节点说明整体关系；引用实际存在的节点或文档，不为记忆另造一套模块分类。
+- 节点移动或改名后，Coordinator 检查记忆中的名称、关系与链接是否仍然正确。删除节点时，检查是否有仍有效的项目知识需要保留，不把全部旧记录搬到父节点。
+- 没有足够信息的节点不强行生成完整文档。已有任务记录、代码路径或一句节点名称，不足以证明模块能力已经实现。
+
+## Coordinator 的维护职责
+
+项目记忆和节点记忆统一由 Coordinator 整理与更新。人类可以直接编辑；Executor 和 Tester 提供实际结果及修改建议，不直接覆盖项目或节点的权威记忆。各 Agent 的工作记录不等于项目记忆。
+
+### 谁决定内容
+
+| 内容 | 决定与核实方式 |
+| --- | --- |
+| 目标、目标用户、用户需求、业务约束 | 由人类决定。Coordinator 只能根据明确确认更新，不能从随口建议或自己的推测中认定要求已变化 |
+| 已实现能力和技术限制 | Executor 回报实现，Tester 提供独立验证；Coordinator 对照相同实现版本更新，不能将方案直接写成现有能力 |
+| 模块职责与协作 | Coordinator 对照已批准方案和实际改动更新；超出方案的职责调整先向人类确认 |
+| 开发、测试进展与阻塞 | Executor 回报开发情况，Tester 回报测试情况，Coordinator 根据实际结果更新，不需要人类替 Agent 判断每项技术事实 |
+| 用户验收状态 | 由人类决定，Coordinator 记录结论；测试通过不能代替用户验收 |
+
+一段内容同时包含“人的要求”和“当前实现”时，要分开写。实现不符合要求，应在进展中说明差距，不能修改目标或约束来迁就实现。
+
+### 何时考虑更新
+
+| 流程时点 | Coordinator 要检查的内容 |
+| --- | --- |
+| 人类明确确认需求、规则或纠正记忆后 | 目标、用户、约束是否变化，是否需要修正现有说法 |
+| 方案审核通过后 | 是否需要记录已批准的决定或当前计划；尚未实施的方案不能写成已经存在的能力或协作关系 |
+| Executor 回报实现或阻塞后 | 开发进展、实际改动和待验证内容是否变化，哪些内容还需 Tester 核实 |
+| Tester 回报结果后 | 已验证的能力、技术限制和测试进展是否变化；验证结果是否对应 Executor 回报的实现版本 |
+| 人类验收后 | 更新验收结论；通过时整理最终说明，拒绝时保留未完成状态和待解决的问题 |
+| 节点结构变化或人类直接编辑记忆后 | 相关文档是否重复、过时或矛盾；不能用旧摘要覆盖人的新决定 |
+
+以上是检查时点，不是强制写入时点。没有新信息、没有错误、没有过时内容，就不修改。
+
+## 撰写与编辑要求
+
+1. **写能指导后续工作的内容。** 保留理解项目、作出决定或避免重复踩坑所需的信息，不因一段话能归入六类之一就全部保存。
+2. **写清楚，不凑字段。** 一句话能说明就写一句；需要交代条件、边界和原因时可以写一小段。有关联的内容连贯表达，不为缩短字数拆成看不懂的碎片。
+3. **先核实，再写成事实。** 区分用户要求、计划、实际实现、测试结果和验收结论。历史记录、Agent 自述或过时页面不能单独证明当前状态。
+4. **优先修改原文。** 同一事实有了变化，更新对应段落；重复内容合并，已经无效的说法从当前正文移除，历史由版本记录保留。
+5. **不要静默解决矛盾。** 来源冲突时先核实。涉及目标和业务规则的分歧交人类决定；技术事实回到代码和验证结果确认。核实前不能择一写成定论。
+6. **进展只讲当前结论。** 说明完成到哪、还有什么没完成、卡在哪里；不写每次命令、重启、重试或聊天过程。不用“刚刚”“昨天”等离开对话就不明确的说法。
+7. **不要把任务局部要求扩大成全局规则。** 只适用于某次任务的条件留在任务记录；确实影响后续模块工作的要求才进入节点记忆，影响整个项目的才进入项目记忆。
+8. **不保存无关和敏感内容。** 不把寒暄、原始日志、临时调试输出、个人琐事、密码或令牌写进记忆。详细测试证据和操作过程留在各自记录中。
+9. **遵守已有写入机制。** 编辑前读取权威版本，保存时使用现有版本校验和权限。遇到冲突保留草稿并重新核对，不覆盖其他修改；保存失败不能报告已更新。
+
+提交修改前，Coordinator 应确认：标题没有变、范围放对了、事实有根据、旧说法已处理、没有重复或流水账。版本、记录与发布仍遵循现有协议，本规范不新增接口。

package/references/memory-filesystem-v2/Bug.en.md

@@ -0,0 +1,162 @@
+# Bug.md format
+
+## Status
+
+- `Open`: recorded, not started.
+- `InProgress`: the Executor and Tester workflow is not complete.
+- `Pending`: tests are complete and human acceptance is pending.
+- `Resolved`: human acceptance passed.
+- `Unfixable`: cannot be fixed; the workflow ends and the record stays. This is not deferral.
+
+**No deferred bugs.** Do not use `Deferred`. If the bug does not need a fix, **delete the Bug file** (it disappears from the index). Do not keep a `WontFix` parking status.
+
+Store images and other binaries separately; this Markdown file only holds a reference link.
+
+The migration generator projects leftover `deferred` values as `Unfixable` and omits leftover `wontfix` files. Neither becomes `Open`.
+
+Attribution attempts use only `Confirmed` and `Refuted`. A supported attribution starts as `Confirmed`. A later attempt changes it to `Refuted` and adds `RefutedBy` and the reason.
+
+## Template
+
+```md
+# <Bug ID> <Title>
+
+Reporter: <Human|Agent>
+Status: <Open|InProgress|Pending|Resolved|Unfixable>
+CurrentAttempt: <A1...An>
+
+## 1. Phenomenon
+
+<Original observable phenomenon>
+
+## 2. Later correction events
+
+- <Attempt / Human|Agent>: <Feedback or new evidence>
+
+## 3. Reproduction
+
+### A1
+<Reproduction steps for this attempt>
+
+## 4. Cause and code changes
+
+### Current valid conclusion
+<Causes and fixes that still hold>
+
+### A1
+Status: <Confirmed|Refuted>
+RefutedBy: <Attempt, only when Refuted>
+Reason: <Reason, only when Refuted>
+
+Cause: <Attribution made by that attempt>
+
+#### code index
+- `<code path>`
+  <Change summary>
+
+## 5. Tests
+
+- [A1](tests/<Bug ID>-A1.md): <one-line result>
+
+## 6. Repair Session index
+
+- [A1](traces/<Bug ID>-A1.md)
+```
+
+The Tests section does not record human acceptance. The Session section contains links only.
+
+## Four-attempt example
+
+```md
+# B002 Repeated clicks create duplicate feedback
+
+Reporter: Human
+Status: Pending
+CurrentAttempt: A4
+
+## 1. Phenomenon
+
+Clicking submit again before the first request finishes creates two identical feedback records.
+
+## 2. Later correction events
+
+- A1 / Human: rapid double-click still duplicates; acceptance failed because disabling the button misses the queued second event.
+- A2 / Human: retry after a weak-network timeout still duplicates; the synchronous lock covers one window only.
+- A3 / Agent B: two windows can submit the same draft; the request-key lookup does not prevent concurrent creation.
+- A4 / Tester B: concurrency, retry, and conflict regressions pass; awaiting human acceptance.
+
+## 3. Reproduction
+
+### A1
+Enter feedback and double-click Submit.
+
+### A2
+Delay the first request until timeout, then retry in the UI.
+
+### A3
+Let the server create the record, drop the response, and retry with the same request key.
+
+### A4
+Submit the same draft from two windows; retry with the same key and same content, then the same key and different content.
+
+## 4. Cause and code changes
+
+### Current valid conclusion
+A synchronous UI lock prevents single-window re-entry. An atomic server uniqueness constraint guarantees one record across windows and retries, while different content with the same key returns a conflict.
+
+### A1
+Status: Refuted
+RefutedBy: A2
+Reason: the second queued click occurs before the disabled state is committed.
+
+Cause: the submit button permits repeated clicks.
+
+#### code index
+- `src/ui/FeedbackForm.tsx`
+  Disable the button when submission starts.
+
+### A2
+Status: Confirmed
+
+Cause: there is a re-entry window before UI state updates.
+
+#### code index
+- `src/ui/submitFeedback.ts`
+  Add a synchronous lock at the submission boundary.
+
+### A3
+Status: Refuted
+RefutedBy: A4
+Reason: request-key lookup and insertion are not atomic.
+
+Cause: retry does not reuse an existing record; reusing the request key is sufficient.
+
+#### code index
+- `src/server/createFeedback.ts`
+  Look up the request key before creation.
+
+### A4
+Status: Confirmed
+
+Cause: concurrent requests can both pass the non-atomic lookup.
+
+#### code index
+- `src/storage/migrations/004_feedback_unique_key.sql`
+  Add a unique constraint over user and request key.
+- `src/server/createFeedback.ts`
+  Create atomically; return the existing record on an equivalent conflict and reject different content.
+
+## 5. Tests
+
+- [A1](tests/B002-A1.md): repeated clicks still reproduce the bug.
+- [A2](tests/B002-A2.md): one window passes; network retry fails.
+- [A3](tests/B002-A3.md): sequential retry passes; concurrency fails.
+- [A4](tests/B002-A4.md): concurrency, timeout retry, and conflict regressions pass.
+
+## 6. Repair Session index
+
+- [A1](traces/B002-A1.md)
+- [A2](traces/B002-A2.md)
+- [A3](traces/B002-A3.md)
+- [A4](traces/B002-A4.md)
+```

package/references/memory-filesystem-v2/Bug.md

@@ -0,0 +1,162 @@
+# Bug.md 格式
+
+## 状态
+
+- `Open`：已记录，尚未开始处理。
+- `InProgress`：Executor 与 Tester 的处理流程尚未结束。
+- `Pending`：测试已完成，等待人类验收。
+- `Resolved`：人类验收通过。
+- `Unfixable`：修不好，流程结束，保留这条记录。不是延期，也不是「以后再做」。
+
+**没有延期。** 禁止 `Deferred`。不需要修 → **删除该 Bug 文件**（索引中消失），不要写成 `WontFix` 留着挂起。
+
+图片等二进制文件单独存储，只在本文挂引用链接。
+
+迁移生成器把历史 `deferred` 投影为 `Unfixable`，历史 `wontfix` 不生成文件。二者都不会变成 `Open`。
+
+归因轮次只使用 `Confirmed` 和 `Refuted`。新归因在本轮证据支持时写 `Confirmed`；后续轮次推翻后改为 `Refuted`，并补充 `RefutedBy` 和原因。
+
+## 格式
+
+```md
+# <Bug ID> <标题>
+
+Reporter: <Human|Agent>
+Status: <Open|InProgress|Pending|Resolved|Unfixable>
+CurrentAttempt: <A1...An>
+
+## 1. 现象
+
+<最初报告的现象，只描述可观察结果>
+
+## 2. 后续纠正事件
+
+- <A轮次 / Human|Agent>：<反馈或新证据>
+
+## 3. 复现
+
+### A1
+<该轮复现方法>
+
+## 4. 原因与代码改动
+
+### 当前有效结论
+<仍成立的原因与修复结论>
+
+### A1
+Status: <Confirmed|Refuted>
+RefutedBy: <A轮次，仅 Refuted 时出现>
+Reason: <推翻原因，仅 Refuted 时出现>
+
+原因：<该轮 Agent 当时的归因>
+
+#### code index
+- `<代码路径>`
+  <改动简介>
+
+## 5. 测试
+
+- [A1](tests/<Bug ID>-A1.md)：<一句结果>
+
+## 6. 修复 Session 索引
+
+- [A1](traces/<Bug ID>-A1.md)
+```
+
+测试区不记录人类验收。Session 区只放链接，不复制 Trace 内容。
+
+## 四轮复杂示例
+
+```md
+# B002 连续点击产生重复反馈
+
+Reporter: Human
+Status: Pending
+CurrentAttempt: A4
+
+## 1. 现象
+
+一次提交尚未结束时再次点击，会生成两条内容相同的反馈。
+
+## 2. 后续纠正事件
+
+- A1 / Human：快速双击仍重复，验收不通过；禁用按钮不能覆盖事件队列中的第二次提交。
+- A2 / Human：弱网超时后重试仍重复，验收不通过；同步锁只覆盖单个窗口。
+- A3 / Agent B：第二轮修复后，同一草稿在多个窗口同时提交仍重复，旧的请求键方案不能防并发创建。
+- A4 / Tester B：并发、重试和冲突回归通过，等待人类验收。
+
+## 3. 复现
+
+### A1
+填写反馈，连续双击提交按钮。
+
+### A2
+将首个请求延迟到超时，在界面重试。
+
+### A3
+服务端创建成功后丢弃响应，再用相同请求键重试。
+
+### A4
+两个窗口同时提交同一草稿；再以同键同内容和同键不同内容分别重试。
+
+## 4. 原因与代码改动
+
+### 当前有效结论
+单窗口同步锁阻止界面重入；服务端原子唯一约束保证跨窗口及网络重试只创建一条记录，同键不同内容明确冲突。
+
+### A1
+Status: Refuted
+RefutedBy: A2
+Reason: 事件队列中的第二次点击发生在按钮禁用生效前。
+
+原因：怀疑提交按钮允许重复点击。
+
+#### code index
+- `src/ui/FeedbackForm.tsx`
+  提交开始时禁用按钮。
+
+### A2
+Status: Confirmed
+
+原因：界面状态更新前存在重入窗口。
+
+#### code index
+- `src/ui/submitFeedback.ts`
+  在提交入口增加同步锁，结束时释放。
+
+### A3
+Status: Refuted
+RefutedBy: A4
+Reason: 请求键查重与插入不是原子操作，并发请求可同时通过检查。
+
+原因：超时重试未复用已创建反馈；复用请求键即可防止重复。
+
+#### code index
+- `src/server/createFeedback.ts`
+  创建前查询请求键并返回已有记录。
+
+### A4
+Status: Confirmed
+
+原因：查重与插入不原子，并发请求会同时通过检查。
+
+#### code index
+- `src/storage/migrations/004_feedback_unique_key.sql`
+  为用户与请求键建立组合唯一约束。
+- `src/server/createFeedback.ts`
+  原子创建；唯一键冲突时返回已有记录，同键不同内容返回冲突。
+
+## 5. 测试
+
+- [A1](tests/B002-A1.md)：连续点击仍可复现。
+- [A2](tests/B002-A2.md)：单窗口通过，弱网重试失败。
+- [A3](tests/B002-A3.md)：顺序重试通过，并发提交失败。
+- [A4](tests/B002-A4.md)：并发、超时重试和冲突回归通过。
+
+## 6. 修复 Session 索引
+
+- [A1](traces/B002-A1.md)
+- [A2](traces/B002-A2.md)
+- [A3](traces/B002-A3.md)
+- [A4](traces/B002-A4.md)
+```

package/references/memory-filesystem-v2/Bug_Coordinater.md

@@ -0,0 +1,8 @@
+# Bug Coordinator
+
+Bug 模式下负责：
+
+- 创建 Bug，并在 `1. 现象` 记录人类或 Agent 报告的原始现象。
+- 明确 Reporter，启动 A1，并把执行任务交给 Executor。
+- 后续 Agent 或人类指出旧结论有误时，将事件追加到 `2. 后续纠正事件`。
+- 人类未验收时启动下一轮；Executor 与 Tester 完成后将整体状态推进到 `Pending` 等待人类验收。

package/references/memory-filesystem-v2/Bug_Executor.md

@@ -0,0 +1,8 @@
+# Bug Executor
+
+Bug 模式下负责当前轮次：
+
+- 复现 Bug，并把最短可重复步骤写入 `3. 复现` 的对应 A 轮次。
+- 在 `4. 原因与代码改动` 记录本轮归因、改动摘要和 `code index`。
+- 若本轮证据推翻旧归因，为旧轮次补充 `RefutedBy` 与推翻原因。
+- 保留同一现象下的所有根因，不因根因不同拆成另一个 Bug。

package/references/memory-filesystem-v2/Bug_Tester.md

@@ -0,0 +1,7 @@
+# Bug Tester
+
+Bug 模式下负责当前轮次：
+
+- 编写该轮测试记录，覆盖复现路径、修复验证和必要回归。
+- 将结果保存到测试文档；Bug.md 的 `5. 测试` 只登记对应 A 轮次的链接和一句结果。
+- 测试不通过时保留证据并交回下一轮，不代替人类验收。

package/references/memory-filesystem-v2/Idea.en.md

@@ -0,0 +1,36 @@
+# Idea.md format
+
+Only the Coordinator reads and writes Idea documents. Whether an Idea becomes a Todo is decided by the user and Coordinator in conversation and is not recorded in Idea.md.
+
+## Template
+
+```md
+# <Idea ID> <Title>
+
+Status: <Proposed|Accepted>
+
+## 1. Idea
+
+<Idea text>
+
+## 2. Discussion and conclusion
+
+- <Time or round>: <Discussion conclusion>
+```
+
+## Example
+
+```md
+# I002 Include the current node with feedback
+
+Status: Proposed
+
+## 1. Idea
+
+When feedback is created from a node, include its ID and title automatically so the user does not need to describe the location manually.
+
+## 2. Discussion and conclusion
+
+- C1: retain the stable node ID; use the title for display only so renaming does not break the relationship.
+- C2: implementation has not been decided, so this remains an Idea.
+```

package/references/memory-filesystem-v2/Idea.md

@@ -0,0 +1,36 @@
+# Idea.md 格式
+
+Idea 只由 Coordinator 读写。是否转成 Todo 由用户与 Coordinator 在对话中决定，不记录在 Idea.md。
+
+## 格式
+
+```md
+# <Idea ID> <标题>
+
+Status: <Proposed|Accepted>
+
+## 1. 想法
+
+<想法正文>
+
+## 2. 讨论与结论
+
+- <时间或轮次>：<讨论结论>
+```
+
+## 示例
+
+```md
+# I002 反馈时附带当前节点信息
+
+Status: Proposed
+
+## 1. 想法
+
+用户从节点内创建反馈时，自动附带当前节点 ID 和标题，减少手工描述问题位置。
+
+## 2. 讨论与结论
+
+- C1：保留原始节点 ID；标题只用于显示，避免重命名后失去关联。
+- C2：尚未决定是否实施，继续作为 Idea 保留。
+```

package/references/memory-filesystem-v2/Node_Module_Index.en.md

@@ -0,0 +1,88 @@
+# Node / Module index format
+
+## Template
+
+```md
+# <Title>
+
+<Responsibility summary>
+
+## Related modules and nodes
+
+### Related
+
+#### [<Related title>](<path>/index.md)
+<Related responsibility summary>
+
+### Sub
+
+#### [<Child title>](<path>/index.md)
+<Child responsibility summary>
+
+## Bug
+
+### [<Bug ID> <Title>](bugs/<id>.md)
+<Copied bug phenomenon>
+
+Status: <Open|InProgress|Pending|Resolved|Unfixable>
+
+## Todo
+
+### [<Todo ID> <Title>](todos/<id>.md)
+<Copied requirement>
+
+Status: <Open|InProgress|Done>
+
+## Idea
+
+### [<Idea ID> <Title>](ideas/<id>.md)
+<Copied idea text>
+
+Status: <Proposed|Accepted>
+
+## Memory
+
+[Read memory](memory.md)
+```
+
+Use `NULL` when a section is empty. Related contains related nodes; Sub contains direct children. Bug, Todo, and Idea entries are generated by code. The Memory section appears only when that node has a memory document; the root node links to project-level `memory.md`.
+
+## Complete example
+
+```md
+# Bug button
+
+Submits defect feedback for the current node.
+
+## Related modules and nodes
+
+### Related
+
+#### [Sidebar](../../Sidebar-module/index.md)
+Provides module navigation and switching.
+
+### Sub
+
+NULL
+
+## Bug
+
+### [B002 Repeated clicks create duplicate feedback](bugs/B002.md)
+Repeated submission clicks create duplicate records.
+
+Status: Pending
+
+## Todo
+
+### [T002 Show feedback submission state](todos/T002.md)
+Show progress and prevent repeated submission while a request is active.
+
+Status: InProgress
+
+## Idea
+
+### [I002 Include the current node with feedback](ideas/I002.md)
+Reduce the location details the user must enter manually.
+
+Status: Proposed
+```