@michelj/context-guard 0.4.4 → 0.6.1

package/references/agent-handoff.md

@@ -0,0 +1,40 @@
+# Agent 交接
+
+Coordinator 向 Executor、Tester 发送任务时适用。Executor 接收时按同一四项核对。
+
+## 准备与派发
+
+新 TODO/Bug 调用 `prepare_task` 后等待 brief 审批，不用 `ask_user` 再发批准或派发选项。人批准 brief 后后台为任务自动创建执行 Session 和工作树，就绪后派发；不为新任务调用 `dispatch_task`。这就是 Coordinator 创建执行 Session 的正常能力，但不能把“挂载”或“准备成功”说成已经派发。
+
+`conversationId` 与 `executionSessionId` 是两类身份，禁止混用。`main`、`legacy`、`session:*`、`item-*` 是对话标识，不能作执行 ID。新任务身份取自 `list_tasks`；旧任务执行 ID 必须逐字复制自本轮 `list_sessions` 返回值。
+
+执行 ID 为空表示尚未创建或绑定，不能调用 `read_task`。核对条目的 `taskId`、`itemId`、`nodeId`、`kind` 及审批状态，需要准备需求时沿用这些身份。`legacy-dispatch-review` 先核对原任务，不能当新任务重派。不向用户展示内部执行 ID，也不要求用户选 Session 或处理内部权限错误。
+
+## 交接内容
+
+一次交接必须写明：
+
+1. 任务说明（用户已确认的那一版，不得改字）
+2. 挂载节点
+3. Main 版本
+4. 验收条件
+
+不得使用含糊指令，例如「适当处理」「参考相关模块」。不得在交接中授予额外节点权限，不得把 Session 草稿当作 Main。
+
+对方可读取总体 context，执行过程中不得改写 Main。不得对人说话。Executor 先提交代码和 handoff，Coordinator 再交给 Tester；测试和人工验收前不归档或结束计划。人工验收后才归档并结束计划。
+
+## Executor 接收核对
+
+所有命令使用宿主提供的当前 worktree；`mainVersion` 是记忆版本，不是 Git SHA。先核对现有代码与任务要求的差距，已满足的部分记录事实和证据，需要补验证时将缺失检查纳入 Plan，不重复实现已经完成的功能。
+
+执行前通过 `plan-status` 读取 `pending_signals`。对应已挂载 Cloud 任务的信号用 `resolve-signal --kind task` 分类，不另建同义 TODO/Bug；独立新需求按其内容记录。Hook 因未分类信号拒绝写入时，先完成分类，再继续原操作，不换工具绕过。
+
+## 中断与返工
+
+未完成任务出现 interrupted 事件后，系统自动发起恢复，保留原 Session、Plan、节点和证据。已有恢复控制时等待匹配的 resumed 回执，不重复发送或绕过 Plan 审核。需要补充指导时使用 `guide_task`，不要把仍在执行的任务当中断任务恢复。
+
+CI 失败或人类验收拒绝都回到原任务、原执行环境。验收拒绝由系统自动推进返工，先核对权威状态，不误报为执行端未认领。
+
+## 收工
+
+人工验收通过后，Coordinator 先读取 `read_task.completionPolicy`，用 `guide_task` 通知原 Executor 归档、结束计划。正式任务提交 PR，核验合并和 Session 发布回执后调用 `complete_task`；服务端指定的 `experiment-only` 任务保留同一提交的测试与人审证据，按返回的回执调用 `complete_task`，不创建 PR、不发布 Main。两者都须等宿主 `closed` 回报才算关闭。不要让人直接联系执行端。

package/references/claude-runtime.md

@@ -0,0 +1,120 @@
+# Managed Claude CLI receiver
+
+Claude uses `CLAUDE_CONFIG_DIR` for settings and installed Skills. The installer
+honors that variable first and retains `CLAUDE_HOME` as a legacy fallback. Keep
+executor and CI profiles and real Session IDs separate; use one shared project
+backend and device heartbeat service, not a timer in every Hook.
+
+## Cloud-created Executor Sessions
+
+The operator may opt an existing Executor receiver into creation with
+`allowSessionCreation:true` in its private runtime configuration. Cloud must also
+list that receiver's Session ID in the project's `coordinator.sessionTemplates`;
+both opt-ins are required. This does not enable permission bypass or install
+anything into Codex's configuration.
+
+The human uses **Coordinator → 新建执行会话**, selects the configured template and
+supplies a name. Cloud persists the request and generated UUID; the existing
+device heartbeat transports it. The backend creates an independent Git worktree
+from the registered Main ref and a private Claude profile containing only the
+template's installed Skill and reviewed settings. It does not copy old chats.
+Only the native startup binding changes the request to `registered`; that state
+is not proof of task execution or current online status. Failed preparation is
+reported through the same heartbeat, with durable retry until acknowledgment.
+
+Created Executors use the template's existing independent CI receiver. The
+receiver stays serial; each handoff and CI capability still names the actual
+Executor Session and exact SHA. Cloud verifies the persisted creation relation
+and current device/worktree binding. Removing Cloud's template opt-in revokes this
+inherited delegation. No task is assigned merely by creating a Session.
+
+## Configure an existing receiver
+
+After the real Claude Session has emitted its native startup Hook and bound to
+the project, the local operator can configure its receiver:
+
+```sh
+context-guard workbench claude --root <worktree> --session <uuid> --input <private-runtime.json>
+```
+
+The private input contains absolute `command`, `root`, `configDir` and
+`environmentFile` paths, optional command-prefix `args`, plus `name`, `model` and
+`role` (`executor` or `ci`). `resumeExisting:true` is required when the native
+Session already has a persisted conversation. `systemPromptFile` points to the
+installed role prompt. The role field identifies the local runner; it does not
+issue a Cloud CI or Coordinator capability.
+
+For CI, also configure `executorSessionId` and an exact `ciCommands` allowlist
+(for example `npm test` and `npm run build`). The CI worktree must differ from
+the Executor worktree. Cloud's private project Coordinator configuration must
+declare `ciReceivers[ciSessionId] = {executorSessionId, worktreeId}`. A body field
+or local role label cannot grant that authority. The backend reuses device login
+and the existing persistent transport; it does not start another heartbeat.
+
+On `ci.request`, the receiver checks out the handed-off SHA only in the clean CI
+worktree. `map ci context` returns the logical Executor Session, task, exact SHA,
+immutable reference versions and allowed commands. `map ci exchange --input -`
+accepts normal protocol JSON; the backend supplies that logical Session rather
+than changing the native CI Session identity. Allowed operations are
+`object.read`, evidence-only `object.put` with refs prefixed `ci:<ciSessionId>:`,
+and `ci.result` for this task and SHA. A changed HEAD or dirty worktree prevents
+a CI result. CI Hooks allow only the configured test commands without a Plan;
+business-source writes and development Plans remain forbidden.
+
+## Reviewed Executor tasks
+
+`map task plan --input <file>` accepts `{operationId,content:{paths,steps}}`.
+It records an immutable Plan at the actual HEAD and requests Coordinator review.
+Keep the operation ID after an uncertain reply; use a new ID for a revised Plan.
+Approval names the exact task, Plan version and source SHA. Read `map execution`
+and pass its `taskId`, `planRef` and `planVersion` to the usual `plan-start` input.
+
+After committing the delivered code, `map task handoff --input <file>` accepts
+`{operationId,ciTodo:{items:[...]},unitTests:[...],experiences:[...]}`. Test evidence
+must describe actual runs; experiences may be empty if nothing reusable was
+learned. The command refuses a dirty worktree, persists immutable objects and
+reports their references with the exact commit SHA. It does not assert CI success,
+human acceptance or a merge. Keep the local Plan active through handoff. The
+handoff precedes Tester and human acceptance; archive and run `plan-finish` only
+after human review. The Coordinator consumes the existing protocol
+journal to receive brief decisions, Plan submissions and CI results; model
+failures remain paused until an explicit retry.
+
+`environmentFile` is private JSON containing only the required `ANTHROPIC_*`
+provider fields and optional `CLAUDE_CODE_SUBAGENT_MODEL` and
+`CLAUDE_CODE_ATTRIBUTION_HEADER`. Keep credentials out of runtime arguments,
+prompts, logs and Map data. `permissionMode:"bypassPermissions"` is accepted only
+with `isolated:true`; the operator must actually provide an isolated execution
+environment. This flag does not install or create a sandbox.
+
+Cloud remains responsible for task ordering. The local receiver permits one
+native turn per Session; a busy receiver leaves the next notification pending
+in the existing inbox. Accepted invocations have durable identities. A local
+backend restart can recover a lost acknowledgement from the receiver's saved
+intent without launching the same prompt again. Native workers outlive backend
+restarts; they do not own another heartbeat service.
+
+`timeoutMs` limits silence; `maxTurnMs` limits the total native turn (30 minutes
+by default). Either limit preserves an interrupted delivery for recovery in the
+same Session rather than treating elapsed time as task completion.
+
+The Claude installer includes failure, permission, pre/post-compaction and
+SessionEnd hooks in addition to start/tool/stop events. Non-decision events only
+record state; they do not restart model generation. See the native
+[Claude Hook contract](https://code.claude.com/docs/en/hooks). Signal IDs are read
+from `plan-status.pending_signals`, never inferred from lifecycle event IDs.
+
+An interrupted or uncertain native turn remains visible and is not automatically
+re-executed. Do not delete its saved intent to retry. Controlled recovery and CI
+delegation must be verified before claiming full lifecycle support. Native turn
+completion is not a successful task, human acceptance, GitHub merge, or archive.
+
+For an explicitly requested continuation of an interrupted turn, the local operator
+may run `workbench claude --recover --root <worktree> --session <uuid> --input
+<private-json>`. Input is `{operationId,deliveryId,message}`: identify the exact
+interrupted delivery and describe what to continue. Both previous processes must
+have exited; a live or uncertain process is never killed by recovery. The original
+record remains unchanged, and a new durable continuation resumes the same native
+Session. Reuse the same operation ID and content after an uncertain response.
+Existing task, Plan and CI permissions still apply; this is not an approval or
+permission to repeat completed work. No background recovery loop is added.

package/references/cloud-sync-interface.md

@@ -0,0 +1,66 @@
+# Cloud Session synchronization
+
+Read this reference for a Cloud-connected project or a preserved synchronization
+conflict. Memory authority and publication remain defined in `server-memory.md`.
+
+## One connection, isolated Sessions
+
+Use `context-guard workbench connect --url <origin> --root <project> --session
+<actual-session-id> --wait` for browser authorization. Once connected, ordinary
+`workbench --root <project> --session <actual-session-id>` reuses the project
+connection. The workbench owns the background connection; never start a separate
+project-wide Map daemon or point a Session at Main to bypass publication.
+
+Local edits enter a durable outbox. Cloud changes are read through events with
+heartbeat recovery. Receipts, queues and cursors remain isolated per Session:
+
+```text
+<project-shared-dir>/session-memory/<session-hash>/remote-sync/
+  state.json
+  server-base.json
+  outbox.json
+  conflict.json
+```
+
+These are private data, not repository files. The workbench preserves uncertain
+requests and retries their original operation IDs. Independent edits can merge;
+overlapping edits preserve base, local and remote documents for review.
+
+## Commands and confirmation
+
+```bash
+context-guard sync status --root <project> --session <actual-session-id>
+context-guard sync ensure --root <project> --session <actual-session-id>
+context-guard sync prepare --root <project> --session <actual-session-id>
+context-guard sync checkpoint --root <project> --session <actual-session-id>
+context-guard sync finish --root <project> --session <actual-session-id>
+```
+
+`status` reads saved Session synchronization state without printing credentials;
+it is not a fresh server receipt. `ensure` reuses the workbench. `prepare`, `pull`
+and `checkpoint` use the current memory read/reconciliation path. `finish` uploads
+the Session through the durable memory path and returns `confirmed: true` only
+with a server snapshot version. None of these commands publishes Main or records
+human acceptance. Lifecycle `plan-finish` still enforces archive and review gates.
+
+The retired project-wide development windows are not supported. Plan scope stays
+in the lifecycle plan; `sync track`, `sync connect` and `sync serve` must not start
+the old transport. Use `workbench connect` for authentication.
+
+## Upgrades and conflicts
+
+Old `.codex/context/private/cloud-sync/` data and shared `cloud-sync/` configuration
+are inspected read-only. Unconfirmed work, a changed draft, unreadable state or a
+conflict returns `UPGRADE_REQUIRED` with reason `legacy-sync-state-pending`.
+Preserve and reconcile those records; do not delete them or infer that an old
+project Map belongs to a particular Session. A configuration-only remnant does
+not block an already connected current client. If it is the only connection,
+`legacy-sync-reconnect` requests current browser authorization.
+
+Network failure leaves current queues on disk. Reconnect retries with backoff;
+conflicts require explicit reconciliation. Do not manufacture a new request ID,
+erase private state or report success merely because a connection is alive.
+
+The private Session service uses authorized `/v1/projects/:project/sessions/`
+reads, changes/events and map writes. Session generations and server authorization
+remain enforced. Credentials never belong in Maps, logs or generated HTML.

package/references/design-current.md

@@ -0,0 +1,14 @@
+# 当前设计版本
+
+读者：产品角色 Agent 与仓库开发 Agent。
+
+**当前版本：`fs-v2.2`**
+
+现行存储与工作项文件格式仍是 [Memory Filesystem v2.1](memory-filesystem-v2/README.md)。v2.2 增加 Session 发布完成证明：可信审核路径显式确认 `sessionId`、`generation`、`sessionVersion`、`sourceCommit` 后才可进入既有 Git/任务发布门禁。上传、心跳和初始 HEAD 在 Main 上均不代表完成；后续修改使证明失效。底层 v2 事务格式与现有单文件接口不变。Agent 默认只认这一份。下次改设计必须再开新版本，不能在同一份「现行」上悄悄换意思。旧版不留在 main。
+
+未升格设计草案不是当前版本，也不是已升格的法。没升版之前，实现和 Skill 都不得拿它们当存储、权限或发布协议。
+
+尚未拍板、本文不选边：
+
+- Agent 打开模块时读哪套目录（FIND.md / snapshot 与 v2 Markdown 投影如何切换）
+- 安装包里链到仓库 `docs/` 打不开怎么办

package/references/map-mount.md

@@ -0,0 +1,41 @@
+# 挂载 Map
+
+读者：产品角色 Agent。意图清楚后打开本文，学会怎么调用。第一次挂载或忘记时通读。用户说挂错了时再打开。
+
+Executor 写入自己的 Session Map，不是 Main。非人写 Main 结构只有 Coordinator：通过 `edit_map` / `mapWrite` 创建、改名、更新、移动或删除节点，也可删除指定节点上的 TODO/Bug，并以 `coordinator` 身份审计；可以先草稿，进 Main 再过门禁。版本校验、幂等回执和根节点保护由服务端强制执行，不能借此修改权限或记忆。不要把白名单 developer 客户端当成现行例外。命令细节以 [workbench-interface.md](workbench-interface.md) 为准。
+
+## 挂到哪
+
+节点定位由 Coordinator 完成，方式见 [读取 Map](map-read.md)。按需求读取已发布 Main 的导航、候选节点职责与 owns，推荐现有节点并用一句话解释依据；不要要求用户描述节点名称、ID 或代码路径。
+
+需求不清楚时，只问缺失的业务信息。例如“测试实验”应问想验证什么功能，而不是问挂到哪里。存在多个候选时比较职责后给出推荐，只就影响选择的业务差异提问。没有匹配节点时说明已查范围并提出新节点建议。Coordinator 可先建草稿节点，进 Main 仍走门禁；Executor 仍按提案交人类在 Coordinator 会话里确认，不编造节点或自行批准。
+
+## 需求
+
+需求摘要写清“要改变什么、在哪里可见、如何验收”。用户要求部署、发布、启动服务或提供访问地址时，保留实际交付目标；只问真正缺少的环境信息，不得用源码路径或 CI 通过替代部署结果。只有用户明确要求只读检查时才采用只读任务。
+
+推荐节点使用 Main 中的完整节点标题，通过 `show_nodes` 或 `ask_user.nodeIds` 提供可跳转引用。推荐不等于批准或派单。
+
+Cloud 用户确认节点和事项类型后，调用 `mount_conversation` 把 Coordinator 挂到该节点，不写入 Main。执行 Session 仍须等该事项的 brief 获批后创建。用户找回旧话题时先用 `list_conversations` 定位，有歧义再澄清，不重新创建同一事项。
+
+使用本次 Prompt 的 signal，不要编造。
+
+```sh
+context-guard record-todo --root "<project>" --session "<session-id>" \
+  --signal "<signal-id>" --node <id> --title "<title>" --description "<acceptance>"
+```
+
+## Bug
+
+```sh
+context-guard record-bad-case --root "<project>" --session "<session-id>" \
+  --signal "<signal-id>" --node <id> --title "<title>" --phenomenon "<what-failed>"
+```
+
+## 新节点
+
+Executor 需要新职责时用 `map apply` 提交 create，带上 `owns` 与 `proposalEvidence`，由 Coordinator 会话里的人确认。Coordinator 使用注入目录中的稳定父节点 ID、记录所属 `nodeId` 与当前 Main 版本调用 `edit_map`；可以先草稿，进 Main 再过门禁。页面收到提交事件后负责渲染节点和动效。两者都不能直接改 `map.json`，冲突后先重读权威 Main，再按原操作身份核对回执。
+
+## 挂错了
+
+用户说挂错了：重新读取相关节点，自行检查职责与 owns，给出修订建议和依据，不要求用户找出正确节点。只有需求范围仍有歧义时才问业务问题。改完把挂载与摘要再交给用户审核；需要新节点时仍走提案，不得自己确认。

package/references/map-read.md

@@ -0,0 +1,50 @@
+# 读取 Map
+
+第一次使用时通读本文，学会怎么调用。以后直接读已发布 Main。需要或忘记时再打开本文。
+
+Map 是整个项目的记忆。命令细节以 [workbench-interface.md](workbench-interface.md) 为准。
+
+## 读哪一张图
+
+Ask user 与路由只读**已发布 Main**。Session 草稿不是项目事实，不得用来判断意图或挂载节点。
+
+没有已发布 Main 时如实说明，不得用未发布图顶替。项目选用服务器记忆时，权威来源见 [server-memory.md](server-memory.md)。
+
+## 怎么读
+
+先读足以定位职责的导航（节点标题与职责），再读目标节点上的记忆、Idea、Todo、Bug。按需读取，不要把整张 Map 贴进对话。不要 Grep 整个 `.codex/context/`。当活动接口已经暴露 Filesystem v2 投影时，从目标 `index.md` 跟随 Markdown 链接；链接就是跳转。Agent 打开模块时先读哪套目录（FIND.md / snapshot 与 v2）尚未拍板，不得在本文选边。
+
+已知节点时，从该节点读起。未知节点时，沿 Map 的模块与职责定位，不得猜测一个不存在的节点。专用检索是可选加速，不是必经步骤。
+
+事项当前所在节点只是检索起点，不自动等于最终执行节点。Coordinator 应根据需求读取候选节点的职责与 owns 后推荐挂载位置，不把查图工作交给用户。
+
+指定节点时，只取该节点及其直接相关记录，不自动展开子树，不读取邻接节点的未授权内容。
+
+## 命令
+
+本地会话首次承担 Coordinator 时，用 `context-guard workbench --root <project> --session <actual-session-id> --role coordinator` 显式记录上下文身份；该标记只控制上下文投递，不授予 Main 写权。
+
+本地：
+
+```sh
+context-guard map read --root "<project>" --session "<session-id>" --node <id>
+context-guard map changes --root "<project>" --session "<session-id>" --cursor "<last-cursor>"
+```
+
+`map read` 返回该时刻的权威内容与 `version`。缺少 cursor 表示读取当前状态，不是「没有变化」。错误码与页面草稿门禁见 [workbench-interface.md](workbench-interface.md)。
+
+Cloud 读取已发布 Main 使用 `workbench.read`，`scope=main`。省略 version 时取当前已发布版本，随后分页与路由必须固定该版本。见 [接口契约](https://github.com/Michel-Johnson/Context-Guard-Cloud/blob/main/docs/interface.md)。
+
+## 版本
+
+Cloud 每轮提供 Main 节点目录；事项对话还提供节点祖先链和分级记忆。目录用于定位，旧对话不能代替 `read_task` 等权威读取；Main 版本变化后使用新目录。
+
+记下本次读取的 Main 版本。后续挂载、交接与审计划都使用这一版，不得改口成「最新」。指定的历史版本不可用时失败，不得偷偷换成另一版。
+
+## 页面导航
+
+`read_map` 会同步聚焦被读取的节点，但不修改 Map。逐层读取时按实际层级调用，不用文字声称已完成页面操作。
+
+用户明确要求打开、进入、跳转或定位已确定的节点时，直接调用 `open_node`，不改成推荐按钮。只有同名或多个候选不能唯一定位时，才用 `ask_user.nodeIds` 澄清。
+
+用户要求演示、展示或游览 Map 时，选 2～4 个有代表性的现有节点调用 `tour_nodes`；完成后简述展示内容，不要求用户逐个点击。演示不授予修改权限。

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