gsd-mempalace-capture

GSD > MEMPALACE CAPTURE

第 1 步——配置门控

使用 Read 工具直接读取 .planning/config.json，检查是否启用了 MemPalace 功能。

1. 使用 Read 工具读取 .planning/config.json。
2. 如果文件不存在，或缺少 config.mempalace，或 config.mempalace.enabled !== true，或 config.mempalace.capture_artifacts === false：显示禁用消息并停止。
3. 否则继续第 2 步。

禁用消息：

GSD > MEMPALACE CAPTURE

MemPalace capture is disabled (mempalace.enabled / mempalace.capture_artifacts).
Nothing was filed; the loop proceeds normally.

此步骤在 discuss:post / plan:post / verify:post 中设置为 onError: skip——捕获失败不会导致阶段失败。

第 2 步——确定目标

1. 产物。 从 <arguments> 块中获取产物。如果未提供，则根据循环节点推断：discuss:post → CONTEXT.md、plan:post → PLAN.md、verify:post → SUMMARY.md。
2. 房间。 将产物映射到房间：
   • CONTEXT.md → decisions
   • PLAN.md → planning
   • SUMMARY.md → milestones （已确认的问题→修复方案对会存入 problems——参见 execute:wave:post 中使用的 capture-problems 片段。）
3. 分区。 若 config.mempalace.wing 非空，则使用它；否则使用 config.project_code；再否则使用仓库目录名。
4. 模式 / 传输方式。 读取 config.mempalace.memory_mode。如果已注册 MemPalace MCP 服务且运行环境允许使用这些工具，则优先使用 MCP（mempalace_*）；否则使用 mempalace CLI（此技能的 Bash 允许工具涵盖该命令），如 mempalace-recall 所示。

第 3 步——原文归档（幂等）

发生任何错误或超时，都应停止并让阶段继续——捕获操作尽力而为。

1. 先去重。 交互模式：对产物的确定性抽屉 ID 调用 mempalace_check_duplicate。无头模式：依靠 mempalace mine 的内容哈希幂等性。

2. 添加抽屉（原文）。 将产物的确切文本连同来源信息（source_file、阶段 ID）归档到 wing: <wing> 的 room: <room> 中。交互模式：调用 mempalace_add_drawer。无头模式：见下文。

   mempalace mine 没有 --room 标志——只有 search 支持 --room（CLI 参考：https://mempalaceofficial.com/reference/cli.html）。房间分配由 detect_room() 完成：它会将文件夹路径中的片段与 mempalace.yaml 中的 rooms: 列表匹配（挖掘指南：https://mempalaceofficial.com/guide/mining.html——“房间会根据文件夹结构自动检测”；配置参考：https://mempalaceofficial.com/guide/configuration.html）。将产物放在以房间命名的文件夹下，以便 detect_room() 正确分配房间：

   STAGE=".planning/.mempalace-stage"
   # One-time: declare the GSD room taxonomy so detect_room() recognizes these folders
   mkdir -p "$STAGE"
   [ -f "$STAGE/mempalace.yaml" ] || cat > "$STAGE/mempalace.yaml" <<'YAML'
   # Each entry MUST be a dict with a `name` key (the miner's detect_room()
   # indexes room["name"] — a bare-string list crashes _mine_impl with
   # TypeError: string indices must be integers, not 'str'). Optional fields:
   # `description`, `keywords` (matched against folder-path segments).
   rooms:
     - name: decisions
     - name: planning
     - name: milestones
     - name: problems
     - name: general
   YAML
   # Suppress MemPalace cache artifacts written into the scanned tree
   [ -f "$STAGE/.gitignore" ] || echo "mempalace_embedder.json" > "$STAGE/.gitignore"
   # Stage under <room>/<phase-id>/<basename> — stable path so mine's content-hash
   # idempotency (file_already_mined keys on absolute source_file + mtime) deduplicates
   # instead of creating duplicate drawers on re-runs.
   ROOM_DIR="$STAGE/<room>/<phase-id>"
   mkdir -p "$ROOM_DIR"
   cp "<artifact-path>" "$ROOM_DIR/<basename>"
   # Mine with --wing only — no --room flag; detect_room() assigns from the folder path.
   # --daemon --background (#4700): MemPalace wraps every mine in a per-palace
   # lock; a concurrent writer would make a foreground mine exit 1
   # (MineAlreadyRunning) and this onError: skip step would silently drop the
   # capture. The background queue defers the job until the lock frees.
   mempalace mine "$STAGE" --wing <wing> --daemon --background
   

3. 镜像 KG 事实，除非 config.mempalace.mirror_kg === false（注册表默认值为 true——若缺少此键，则表示启用）：提取决策 / 交付事实，并使用 valid_from = 阶段日期调用 mempalace_kg_add 添加这些事实（例如，从 CONTEXT 提取 (<project>, decided, <decision>)；从 SUMMARY 提取 (<phase>, delivered, <capability>)）。在 augment 模式下，这些事实是 GSD 原生 .planning/graphs/ 的增量镜像。在 kg_backend / replace 模式下，palace KG 是权威事实库——GSD 仍会通过常规 graphify 生成 .planning/graphs/，因此即使 palace 无法访问，也不会丢失任何事实。

4. 重新运行阶段时，不得创建重复抽屉（使用确定性 ID + check_duplicate）。

步骤 4 -- 报告

打印一行摘要：Filed <artifact> → <wing>/<room> (<n> KG facts)、Capture queued — palace busy; MemPalace will file it when the lock frees（后台挖掘任务因另一位写入者而延后），或 MemPalace capture skipped — <reason>（#4700：跳过的捕获绝不会悄无声息）。

反模式

1. 切勿让任何 MemPalace 错误导致此步骤失败——捕获采用 onError: skip。
2. 切勿编写有损摘要——存储工件的原文（AAAK 压缩是独立且可选的索引）。
3. 切勿在此处清理或删除抽屉——清理（sync --apply）是 curator agent 在 ship:post 阶段的工作，且仅限于当前 wing。
4. 切勿跳过配置门槛或去重检查。