@michelj/context-guard 0.4.4 → 0.6.1

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
+```

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

@@ -0,0 +1,88 @@
+# Node / Module index 格式
+
+## 格式
+
+```md
+# <标题>
+
+<职责简介>
+
+## 关联模块与节点
+
+### Related
+
+#### [<关联标题>](<path>/index.md)
+<关联职责简介>
+
+### Sub
+
+#### [<下级标题>](<path>/index.md)
+<下级职责简介>
+
+## Bug
+
+### [<Bug ID> <标题>](bugs/<id>.md)
+<Bug 现象原文>
+
+Status: <Open|InProgress|Pending|Resolved|Unfixable>
+
+## Todo
+
+### [<Todo ID> <标题>](todos/<id>.md)
+<Todo 需求原文>
+
+Status: <Open|InProgress|Done>
+
+## Idea
+
+### [<Idea ID> <标题>](ideas/<id>.md)
+<Idea 正文原文>
+
+Status: <Proposed|Accepted>
+
+## 记忆
+
+[阅读记忆](memory.md)
+```
+
+没有内容时写 `NULL`。Related 只放相关节点，Sub 只放直接下级。Bug/Todo/Idea 区块全部由代码生成。`## 记忆` 仅在该节点有记忆文档时生成；项目根节点的链接指向项目根目录 `memory.md`。
+
+## 完整示例
+
+```md
+# Bug按钮
+
+提交当前节点的缺陷反馈。
+
+## 关联模块与节点
+
+### Related
+
+#### [侧边栏](../../侧边栏-module/index.md)
+提供模块导航与切换。
+
+### Sub
+
+NULL
+
+## Bug
+
+### [B002 连续点击产生重复反馈](bugs/B002.md)
+连续点击提交时生成重复记录。
+
+Status: Pending
+
+## Todo
+
+### [T002 补充反馈提交中的状态](todos/T002.md)
+提交期间显示进度并阻止重复提交。
+
+Status: InProgress
+
+## Idea
+
+### [I002 反馈时附带当前节点信息](ideas/I002.md)
+减少用户手工描述问题位置。
+
+Status: Proposed
+```

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

@@ -0,0 +1,60 @@
+# Memory Filesystem v2.1
+
+读者：产品角色 Agent（格式与阅读面）；仓库开发 Agent（生成器与迁移缺口）。
+
+**版本：`fs-v2.1`（当前设计版本；底层事务格式仍为 v2）**
+从何而来：已评审的 Cloud Main / Session 记忆文件结构。
+
+确认：现行存储法只认这一版。下一版必须另开版本号。入口见 [当前设计版本](../design-current.md)。
+未升格设计草案不是本版本，不得当存储法。
+
+这是 Cloud Main 与 Session 记忆的已评审目标文件结构。启用 filesystem v2 的服务器提供按版本读取单份 Markdown 的显式 API，Agent 可通过 `context-guard memory file` 读取获授权的文档；这不是本地私有 `content/` 磁盘路径。未启用该投影的项目不能使用此入口，旧记录仍只作兼容传输。Agent 打开模块时默认读哪套目录（FIND.md / snapshot 与本投影如何切换）尚未拍板，不得在本文里选边。
+
+## 目录
+
+```text
+filesystem-v2/
+|-- FORMAT
+|-- runtime-state.json                 # 事务兼容状态，不是 Agent 阅读入口
+`-- content/
+    |-- storage.json
+    |-- main/
+    |   |-- map.json                   # 代码导航表
+    |   |-- memory.md                  # 项目记忆；有内容时生成
+    |   |-- nodes/
+    |   |   `-- <name>-module|node/
+    |   |       |-- index.md
+    |   |       |-- memory.md          # 节点记忆；有内容时生成
+    |   |       |-- bugs/<id>.md
+    |   |       |-- todos/<id>.md
+    |   |       `-- ideas/<id>.md
+    |   |-- manifest.json
+    |   `-- migration-report.json
+    `-- sessions/<session-hash>/        # 与 Main 同构，彼此隔离
+```
+
+节点的 Bug、Todo、Idea 索引直接生成在该节点的 `index.md` 中，不再创建 `bugs-index.json`、`tasks-index.json` 或 Idea JSON 索引。
+项目和节点的记忆正文存于 Main Map 对应节点的 `memoryDocument`，随版本写入并投影为上述 `memory.md`。只有人和 Coordinator 能修改；Executor、Tester 可按已有单文件读取权限查看。项目记忆是 Coordinator 首轮静态上下文，进入节点时只加载最近的相关节点记忆，历史条目仍按需读。文档格式见 [记忆定义](../memory-definition.md)。
+
+## 文档
+
+- [Node / Module index](Node_Module_Index.md) · [English](Node_Module_Index.en.md)
+- [Bug](Bug.md) · [English](Bug.en.md)
+- [Todo](Todo.md) · [English](Todo.en.md)
+- [Idea](Idea.md) · [English](Idea.en.md)
+- Bug 模式：[Coordinator](Bug_Coordinater.md) · [Executor](Bug_Executor.md) · [Tester](Bug_Tester.md)
+- Todo 模式：[Coordinator](Todo_Coordinater.md) · [Executor](Todo_Executor.md) · [Tester](Todo_Tester.md)
+
+## 代码生成职责
+
+目标实现由代码生成目录名、文档 ID、整体状态、`CurrentAttempt`、A1/A2 轮次编号、Related/Sub、节点 `index.md` 中的 Bug/Todo/Idea 条目、测试链接、Session 链接、`map.json`、`manifest.json` 和迁移报告。
+
+Todo/Bug 的显式 `attempts` 依附工作项保存在版本化 Map 事务快照中；数组顺序生成 A1…An、`CurrentAttempt`、反证关系、测试和 Session 链接。每轮包含 `status`（`Confirmed|Refuted`）；`Refuted` 必须指向更晚轮次并写明原因。可选字段为 `event`/`eventSource`、Bug 的 `reproduction`/`cause`/`resolution`、Todo 的 `acceptance`/`solution`，以及 `codeIndex`、`test`、`sessionIds`。生成的 Markdown 是投影，不是手工持久化入口；重建时从事务快照恢复。
+
+旧 Todo 若没有方案证据，迁移投影仍保留未判定的 A1 并在报告标记 `TODO_ATTEMPT_UNCLASSIFIED`；不能擅自判为 `Confirmed`。该旧项需要后续审核补齐显式 Attempt，完成前不得把它称为完全符合模板。
+
+生成器完整复制对应 Bug 现象、Todo 需求或 Idea 正文的首段，不由 Agent 重写，也不按字符数截断。详细内容仍以链接文档为准。
+
+## 兼容边界
+
+`legacy-records/` 和 `runtime-state.json` 仅用于迁移、事务兼容与回滚。普通 Agent 上下文、接口分析和项目导航不得读取它们。需要核对历史迁移时必须显式说明兼容目的。

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

@@ -0,0 +1,137 @@
+# Todo.md format
+
+## Status
+
+- `Open`: recorded, not started.
+- `InProgress`: the Executor and Tester workflow is not complete.
+- `Done`: the current requirement has passed acceptance.
+
+Solution attempts use `Confirmed` and `Refuted`. When later requirements or evidence invalidate an earlier solution, update that attempt with `RefutedBy` and the reason.
+
+Migration compatibility: Todo A1 generated by the current runtime may omit `Status`. That legacy projection does not yet conform to this format and does not introduce a third attribution status. Do not synthesize the field or treat its absence as `Confirmed` before the generator is fixed.
+
+## Template
+
+```md
+# <Todo ID> <Title>
+
+Reporter: <Human|Agent>
+Status: <Open|InProgress|Done>
+CurrentAttempt: <A1...An>
+
+## 1. Requirement
+
+<Confirmed user goal>
+
+## 2. Later adjustment events
+
+- <Attempt / Human|Agent>: <New constraint or scope change>
+
+## 3. Acceptance criteria
+
+### A1
+<Executable acceptance criteria for this attempt>
+
+## 4. Solution and code changes
+
+### Current valid solution
+<Solution conclusions that still hold>
+
+### A1
+Status: <Confirmed|Refuted>
+RefutedBy: <Attempt, only when Refuted>
+Reason: <Reason, only when Refuted>
+
+Solution: <Solution proposed in this attempt>
+
+#### code index
+- `<code path>`
+  <Change summary>
+
+## 5. Tests
+
+- [A1](tests/<Todo ID>-A1.md): <one-line result>
+
+## 6. Implementation Session index
+
+- [A1](traces/<Todo ID>-A1.md)
+```
+
+## Three-attempt example
+
+```md
+# T002 Show feedback submission state
+
+Reporter: Human
+Status: InProgress
+CurrentAttempt: A3
+
+## 1. Requirement
+
+Show an explicit state during feedback submission and prevent duplicate execution.
+
+## 2. Later adjustment events
+
+- A1 / Human: disabling the button removes cancellation; cancellation must remain available.
+- A2 / Human: multiple windows still duplicate submissions; scope expands to cross-window consistency.
+- A3 / Executor B: use a server request key and define conflicts for different content using the same key.
+
+## 3. Acceptance criteria
+
+### A1
+Show progress, prevent a second request, and allow cancellation.
+
+### A2
+Two windows submitting the same draft create one record.
+
+### A3
+Same key and content return one record; different content returns a conflict; a new request is allowed after cancellation.
+
+## 4. Solution and code changes
+
+### Current valid solution
+A client state machine provides progress and cancellation. A server request key and uniqueness constraint provide cross-window idempotency.
+
+### A1
+Status: Refuted
+RefutedBy: A2
+Reason: disabling one button cannot provide cancellation or cross-window consistency.
+
+Solution: disable the button and show loading during submission.
+
+#### code index
+- `src/ui/FeedbackForm.tsx`
+  Add the submitting state.
+
+### A2
+Status: Confirmed
+
+Solution: use a cancellable state machine for one-window submission.
+
+#### code index
+- `src/ui/feedbackSubmission.ts`
+  Manage idle, submitting, and cancelling states.
+
+### A3
+Status: Confirmed
+
+Solution: enforce atomic idempotency by user and request key on the server.
+
+#### code index
+- `src/server/createFeedback.ts`
+  Validate the request key and handle uniqueness conflicts.
+- `src/storage/migrations/004_feedback_unique_key.sql`
+  Add the composite uniqueness constraint.
+
+## 5. Tests
+
+- [A1](tests/T002-A1.md): progress passes; cancellation fails.
+- [A2](tests/T002-A2.md): one window passes; multiple windows fail.
+- [A3](tests/T002-A3.md): state, cancellation, cross-window, and conflict regressions pass.
+
+## 6. Implementation Session index
+
+- [A1](traces/T002-A1.md)
+- [A2](traces/T002-A2.md)
+- [A3](traces/T002-A3.md)
+```