@michelj/context-guard 0.4.3 → 0.6.1

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

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

@@ -0,0 +1,137 @@
+# Todo.md 格式
+
+## 状态
+
+- `Open`：已记录，尚未开始。
+- `InProgress`：Executor 与 Tester 的流程尚未结束。
+- `Done`：当前需求已经验收完成。
+
+方案轮次使用 `Confirmed` 和 `Refuted`。后续需求或证据推翻旧方案时，更新旧轮次并写明 `RefutedBy` 与原因。
+
+迁移兼容说明：当前生成器的 Todo A1 可能缺少 `Status`。这是尚未符合本格式的旧投影，不是第三种归因状态；修复生成器前不得自行补写或把缺失状态当成 `Confirmed`。
+
+## 格式
+
+```md
+# <Todo ID> <标题>
+
+Reporter: <Human|Agent>
+Status: <Open|InProgress|Done>
+CurrentAttempt: <A1...An>
+
+## 1. 需求
+
+<用户确认的目标>
+
+## 2. 后续调整事件
+
+- <A轮次 / Human|Agent>：<新增约束或范围变化>
+
+## 3. 验收标准
+
+### A1
+<该轮可执行验收标准>
+
+## 4. 方案与代码改动
+
+### 当前有效方案
+<仍成立的方案结论>
+
+### A1
+Status: <Confirmed|Refuted>
+RefutedBy: <A轮次，仅 Refuted 时出现>
+Reason: <推翻原因，仅 Refuted 时出现>
+
+方案：<该轮方案>
+
+#### code index
+- `<代码路径>`
+  <改动简介>
+
+## 5. 测试
+
+- [A1](tests/<Todo ID>-A1.md)：<一句结果>
+
+## 6. 实现 Session 索引
+
+- [A1](traces/<Todo ID>-A1.md)
+```
+
+## 三轮示例
+
+```md
+# T002 补充反馈提交中的状态
+
+Reporter: Human
+Status: InProgress
+CurrentAttempt: A3
+
+## 1. 需求
+
+反馈提交期间显示明确状态，并阻止同一提交重复执行。
+
+## 2. 后续调整事件
+
+- A1 / Human：按钮禁用后无法取消，要求保留取消操作。
+- A2 / Human：多个窗口仍会重复提交，范围扩展到跨窗口一致性。
+- A3 / Executor B：采用服务端请求键，补充同键不同内容的冲突规则。
+
+## 3. 验收标准
+
+### A1
+提交中显示进度；重复点击不产生第二个请求；用户可以取消。
+
+### A2
+两个窗口提交同一草稿时只创建一条记录。
+
+### A3
+同键同内容返回同一记录；同键不同内容返回冲突；取消后允许新请求。
+
+## 4. 方案与代码改动
+
+### 当前有效方案
+客户端状态机负责进度与取消，服务端请求键和唯一约束负责跨窗口幂等。
+
+### A1
+Status: Refuted
+RefutedBy: A2
+Reason: 仅禁用按钮不能满足取消和跨窗口一致性。
+
+方案：提交时禁用按钮并显示加载状态。
+
+#### code index
+- `src/ui/FeedbackForm.tsx`
+  增加提交中状态。
+
+### A2
+Status: Confirmed
+
+方案：使用可取消状态机管理单窗口提交。
+
+#### code index
+- `src/ui/feedbackSubmission.ts`
+  管理 idle、submitting、cancelling 状态。
+
+### A3
+Status: Confirmed
+
+方案：服务端以用户和请求键保证原子幂等。
+
+#### code index
+- `src/server/createFeedback.ts`
+  校验请求键并处理唯一键冲突。
+- `src/storage/migrations/004_feedback_unique_key.sql`
+  增加组合唯一约束。
+
+## 5. 测试
+
+- [A1](tests/T002-A1.md)：进度通过，取消失败。
+- [A2](tests/T002-A2.md)：单窗口通过，跨窗口失败。
+- [A3](tests/T002-A3.md)：状态、取消、跨窗口与冲突回归通过。
+
+## 6. 实现 Session 索引
+
+- [A1](traces/T002-A1.md)
+- [A2](traces/T002-A2.md)
+- [A3](traces/T002-A3.md)
+```

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

@@ -0,0 +1,7 @@
+# Todo Coordinator
+
+Todo 模式下负责：
+
+- 在 `1. 需求` 记录用户确认的目标。
+- 将后续范围或目标变化追加到 `2. 后续调整事件`，并启动新的 A 轮次。
+- 协调 Executor 与 Tester 完成当前轮次，并维护整体流程状态。

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

@@ -0,0 +1,7 @@
+# Todo Executor
+
+Todo 模式下负责当前轮次：
+
+- 根据需求和验收标准执行任务，包括代码修改、实现、修复。
+- 在 `4. 方案与代码改动` 记录方案、改动摘要和 `code index`。
+- 后续方案推翻旧方案时，为旧轮次补充 `RefutedBy` 与原因。

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

@@ -0,0 +1,7 @@
+# Todo Tester
+
+Todo 模式下负责当前轮次：
+
+- 在 `3. 验收标准` 完善可执行的验收条件。
+- 编写并执行该轮测试记录。
+- Todo.md 的 `5. 测试` 只登记对应 A 轮次的测试链接和一句结果。

package/references/named-workbench.md

@@ -0,0 +1,124 @@
+# Project-named local workbench
+
+`context-guard workbench --root /path/to/project` now prints an HTTP URL such as
+`http://my-project.localhost:1355/prototype/workbench.html`. SessionStart uses the
+same entry. No global Portless install, DNS edit, certificate, administrator
+permission, or additional npm runtime dependency is needed.
+
+The name is derived from the Map's project name and normalized to lowercase DNS
+letters, digits and hyphens (`Context_Guard` becomes `context-guard`). Non-ASCII
+only names use a stable `project-<id>` fallback. Set a readable explicit name with:
+
+```sh
+context-guard workbench --root /path/to/project --name my-project
+```
+
+Different projects cannot take over the same registered name, even when a backend
+is stopped. Choose another name; this command never kills the other project.
+Runtime routes are private local state, not project memory or files to commit.
+
+## Multiple sessions and worktrees
+
+Linked Git worktrees share one project service. Bindings are keyed by the real
+Session ID, never by branch: two Sessions on one branch remain independent. Once
+a project workbench has been established, a new unbound Session automatically
+reuses the unique matching registered workbench. Human confirmation is required
+only for the project's first workbench, an ambiguous/mismatched candidate, or an
+explicit move of an already-bound Session to another worktree.
+The legacy service-target command remains available:
+
+```sh
+context-guard workbench bind --root /path/to/second-worktree --project-root /path/to/map-worktree
+```
+
+The two paths must have the same local Git common directory. Unrelated clones,
+same-name folders and different repositories are not silently joined. Binding
+chains are rejected. Stop any service in the second worktree first, after saving
+its drafts. The target Map must already exist; this command does not create one.
+If the second worktree has its own Map, binding fails unless `--keep-local` is
+explicitly provided. That flag preserves its files unchanged; it does not merge
+or delete data, and does not authorize a Session binding.
+
+The target selects only the service. Python lifecycle records stay in the source
+worktree; the service keeps Maps isolated by Session/worktree identity. Existing
+records are not migrated to the target. First-use or ambiguous hooks ask for
+confirmation and do not guess a service or open a browser. A unique established
+project binding is reused automatically. All Sessions remains the read-only published
+main baseline, never the target worktree's unmerged Map. See `server-memory.md`
+for the private-memory deployment and publication boundary.
+
+The named entry and project identity are shared in the Git common directory. A
+user-private global registry at `~/.context-guard/named-workbench/projects.json`
+also records every established local project, its known worktree roots and its
+canonical URL. It lives outside the replaceable Skill directory, so reinstalling
+or upgrading the Skill does not erase bindings or create a second workbench.
+Restarting the backend from another linked worktree retains the project's URL.
+Inspect every known project without starting or stopping a service with
+`context-guard workbench --list --root /path/to/current/project`. The command
+does not equate historical registration with liveness: it probes the backend
+and named route, includes route-only legacy instances, deduplicates the same
+physical instance across linked worktrees, and returns separate
+`registeredCount`, `runningCount`, `readyCount`, `stoppedCount`, and
+`attentionCount` values. Project entries expose readable names, canonical URLs
+and states (`ready`, `direct-only`, `legacy`, `duplicate`, `route-stale`,
+`route-mismatch`, `stopped`, or `unknown`) without user-facing Session, Git or
+backend instance identifiers. `unknown` means a recorded owner process is still
+alive but did not answer the bounded health probe; it must not be treated as
+stopped or replaced automatically.
+
+When opening is requested, it is claimed atomically by the backend: live workbench pages
+suppress another open, and parallel first starts share a five-second opening
+window. A failed browser launch can therefore delay a retry for five seconds.
+An explicit CLI command still prints the URL for manual opening. Headless/CI and
+resume/compact hooks do not open a browser. SessionStart validates the binding and
+injects the URL without automatically opening another page.
+
+## Process lifecycle and compatibility
+
+One loopback-only HTTP proxy is shared across projects, independent of each
+backend. Closing one project does not close the proxy or other projects. The
+proxy does no directory polling, certificate work, LAN exposure or tunnelling.
+SSE is streamed; WebSockets are intentionally unsupported.
+
+Default proxy port is 1355. If another application (including full Portless) owns
+it, the proxy chooses a free port among the next 20 and returns that actual URL;
+it never takes over the existing listener. The chosen URL still has a port. A
+proxy/backend crash is recovered on the next `workbench`/SessionStart invocation;
+there is no always-polling supervisor. Run the command again after an unexpected
+exit. A still-live but unhealthy owner fails visibly instead of being killed.
+
+Each forwarded request checks the backend's instance identity before sending
+capabilities. Host, Origin and the forwarding capability are checked; agent
+grants and cross-project token isolation remain in force. These are local
+single-user safeguards, not protection against another process running with
+full access to the same user's files.
+
+A recognized older backend or named proxy is upgraded in place on the next bound
+lifecycle or `workbench` command. The proxy preserves its route store and must
+acknowledge an authenticated stop before replacement. The old backend must first
+acknowledge its synchronization fence and release the project lock; otherwise the
+command returns `UPGRADE_PENDING` and does not start a replacement. Unknown legacy
+runtimes and duplicate owners still require explicit diagnosis/migration. Browser
+recovery storage remains on the stable project origin, so a normal compatible
+upgrade does not change its storage boundary.
+
+- `CONTEXT_GUARD_NAMED_WORKBENCH=0` or `--direct`: old direct loopback URL.
+- `CONTEXT_GUARD_NAMED_STATE_DIR`: isolated private proxy state directory (default
+  `~/.context-guard/named-workbench`). Never share this directory across OS users.
+- `CONTEXT_GUARD_NAMED_PORT`: preferred proxy port, default 1355.
+
+## Attribution and tests
+
+The reduced route store derives from Portless 0.15.6 under Apache-2.0. See
+`THIRD_PARTY_NOTICES.md` and `licenses/Portless-Apache-2.0.txt`; both are included
+in the npm package and installed Skill. The proxy/adapter are separate Context
+Guard implementations, not a vendored full Portless CLI.
+
+`tests/named-workbench.test.mjs` is part of `npm test`: authorization, Origin/Host,
+read/write, five sessions/SSE streams, opening claims, name collision, backend
+identity/port reuse, proxy restart, multi-project isolation, corrupt route state,
+concurrent process startup, isolated test registries, persistent global registry,
+recognized backend/proxy runtime upgrade, legacy route repair, explicit Git
+worktree binding and the real Python SessionStart handler. This does not prove
+delivery by every desktop host, OS or browser.
+Outstanding coverage is tracked in `CI_todo.md`.

package/references/plan-review.md

@@ -0,0 +1,12 @@
+# 计划审核
+
+Executor 把 Plan 交给 Coordinator 时适用。Executor 提交前按同一四项自检。
+
+只检查以下四项，全部成立才可通过：
+
+1. 范围与已确认需求一致
+2. 节点与 Ask user 的挂载一致
+3. 含有可检查的验收条件
+4. 未越出授权节点
+
+任一项不成立则退回，并指出不成立的项。你通过 Plan 后对方才可开发。你通过 Plan 不等于用户已验收。不得伪造审核回执。