loom-index-update

name	loom-index-update
description	Synchronize graph backend index, structured memory, and entry docs with code after verification passes. Use when: verified code changes need graph index sync, memory updates, or entry documentation refresh.
when_to_use	Sync graph backend, structured memory, and entry docs after verified code changes.
argument-hint	<spec_dir or sync scope>
user-invocable	true

图后端与记忆同步 Skill

触发条件

• 功能测试和 completion verification 通过后自动触发。
• 用户手动要求同步图后端、更新记忆或更新文档。

前置条件

1. 代码变更已完成。
2. loom-verification-before-completion 已通过，或用户明确要求只同步图后端/记忆。

执行流程

Step 1：检测变更范围

1. 运行 git diff --name-only HEAD 确认变更文件。
2. 按 references/update-checklist.md 判断是否需要同步图后端或结构化记忆。

Step 2：同步图后端

先读取 .loom/graph.config.json 确认当前图后端；配置不存在时默认 codegraph（向后兼容）。

loom index            # 同步当前图后端；后端不可用时跳过
loom index --check    # 检查图后端状态；后端不可用时跳过

图后端可用时，AI 通过 loom 暴露的固定 MCP 工具按需查询（不直接调用后端专属工具名）：

• loom_graph_status — 查询后端能力、新鲜度和可用性
• loom_graph_query — 统一图查询入口（capability：explore / definition / references / impact 等）
• loom_graph_sync — 同步或检查索引

当后端是 codegraph 时，loom_graph_* 内部委派给 codegraph_explore 等 MCP 工具；AI 不需要也不应该直接引用 codegraph_* 工具名。

图后端不可用（后端为 none、marker 不存在或 freshness=unavailable）时，在报告中注明“图后端不可用，图索引同步跳过”，不中断流水线。

降级规则：

• 后端不支持 impact 时，用 references、explore 或源码搜索降级，并报告“影响范围可能不完整”。
• 后端 freshness 不是 fresh 时，不得直接把其结论作为阻断判断依据，需用当前源码和 git diff 校验关键结论。
• 后端类型是 knowledge-base 时，不得用于精确调用链或 breaking change 影响范围判断。

Step 3：更新结构化 Memory

Memory 的单一真实来源是 .loom/memory/store.json。MEMORY.md 是 loom memory export 生成的只读视图，禁止手动编辑 MEMORY.md。

判断写入目标：

内容类型	写入方式
本次会话的关键结论（决策/踩坑/偏好/状态变更）	loom_add_memory 或 loom memory add --type <类型> --content "..."
技术选型、架构决定，需要保留背景和原因	type=adr，context 写背景和原因
实际遇到的坑，含根因和解决方式	type=踩坑，content 写“问题 + 根因 + 解决方式”
用户明确表达的工作习惯、风格偏好、禁止事项	type=偏好
技术栈或当前阶段变化	type=状态
本次会话有重要内容需要归档	loom memory archive --slug <slug> --file <session.md>

命令示例：

loom memory add --type 决策 --content "选择 codegraph 作为默认图后端"
loom memory export

会话归档规则：

• 触发条件：本次会话产生 2 条以上重要内容，或单条内容较长（>200 字）。
• 通过 loom memory archive --slug <feature-slug> --file <session.md> 写入归档。
• 需要提交导出视图时运行 loom memory export。

不写入的情况：

• 一般性代码变更（无决策、无踩坑、无偏好变化）→ 不更新 memory。
• 临时调试信息、过程性日志 → 不写入。

Step 4：必要时更新入口文件

只有引入新约定、新命令、入口程序变化或开发流程调整时，才更新入口文件。一般性代码变更不更新。

Step 5：输出报告

报告模板见：

• assets/report-graph-template.md（图后端可用，路径 A）
• assets/report-no-graph-template.md（图后端不可用，路径 B）

约束

• 只同步图后端和记忆文件，不修改业务代码。
• 图后端查询结果必须与实际代码一致；freshness 不是 fresh 时以源码为准。
• 新增表名、路由路径、方法签名必须与源码完全一致。
• 统一调 loom index；图后端不可用时跳过，不生成任何 Markdown 索引。

完成条件

同步完成后输出报告；图后端不可用时必须明确注明已跳过。