feat: 加固 CodeGraph 查询新鲜度与过期标识

README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-> Current protocol version: `0.1.21` (in development); workflow version: `0.1.3`
+> Current protocol version: `0.1.22` (in development); workflow version: `0.1.3`
 
 Polaris is a repo-native engineering workflow for coding agent hosts. It stores requirements, plans, implementation results, independent reviews, validation evidence, and task state in Git, then uses deterministic gates to prevent requirement drift, stale evidence, and agents declaring their own work complete.
 
@@ -91,11 +91,13 @@ polaris code-intelligence add codegraph --repo .
 
 Run these commands from the target repository as appropriate. `codegraph init` creates the `.codegraph/` marker; without it Polaris uses source and Git directly and creates no stage record. Vendoring registers the project-scoped `polaris-codegraph` proxy in `.codex/config.toml` and `.mcp.json` without replacing unrelated settings. The host may require project trust or first-use approval; that approval remains the user's decision.
 
-Polaris stages call only `polaris_codegraph_explore`. The proxy checks status, may internally perform one bounded `codegraph sync` when requested and pending, runs one explore, rechecks status, and returns a freshness envelope before graph content. There is no separate stage status/sync MCP call. `CURRENT` means `NON_AUTHORITATIVE_CONTEXT`; `STALE` and `UNKNOWN` mean `NAVIGATION_ONLY` and require the named source/Git fallback; `UNAVAILABLE` means no graph. A current named file uses `READ_SOURCE`, a deleted file uses `INSPECT_GIT_DIFF`, and an index-wide or unsafe result uses `SEARCH_SOURCE`. Validation remains graph-free and relies on source, Git, builds, tests, static checks, and Human Checks.
+Polaris stages call only `polaris_codegraph_explore`. The proxy checks status and automatically runs at most one bounded incremental `codegraph sync` when pending changes exist, then runs one explore, rechecks status, and returns a freshness envelope before graph content. There is no separate stage status/sync MCP call. `CURRENT` means `NON_AUTHORITATIVE_CONTEXT`; `STALE` and `UNKNOWN`/`TREAT_AS_STALE` mean `NAVIGATION_ONLY` and require the exact source/Git fallback before a conclusion is used; `UNAVAILABLE` means no graph. A current named file uses `READ_SOURCE`, a deleted file uses `INSPECT_GIT_DIFF`, and an index-wide or unsafe result uses `SEARCH_SOURCE`. Validation remains graph-free and relies on source, Git, builds, tests, static checks, and Human Checks.
 
-The repository owner, not Polaris, owns CodeGraph installation, initialization, configuration, raw MCP registration, watcher, and daemon. Polaris never starts, configures, reconfigures, waits for, or manages them. Raw `codegraph_explore` or `codegraph explore` remains available out-of-band but cannot back `CURRENT` Polaris evidence. New records are v3 projections of the retained proxy bundle and completed fallbacks; v1/v2 are historical only. CodeGraph remains optional and never becomes a workflow gate.
+When status cannot be verified but the project has a safe repository identity, the proxy still calls `polaris_codegraph_explore` and returns `UNKNOWN`/`TREAT_AS_STALE`. The graph remains navigation-only: use the exact source/Git fallback before any conclusion.
 
-Protocol `0.1.21` adds the project-scoped Polaris CodeGraph proxy, host adapter v3 registration, and auditable Code Intelligence record v3 while leaving Workflow at `0.1.3`. Record v1 and v2 are immutable historical evidence only; new evidence is projected from a retained proxy bundle into v3.
+The repository owner, not Polaris, owns CodeGraph installation, initialization, configuration, raw MCP registration, watcher, daemon, and every full `codegraph index` rebuild. Polaris never starts, configures, reconfigures, waits for, or manages them. Raw `codegraph_explore` or `codegraph explore` remains available out-of-band but cannot back `CURRENT` Polaris evidence. New records are v3 projections of the retained proxy bundle and completed fallbacks; v1/v2 are historical only. CodeGraph remains optional and never becomes a workflow gate.
+
+Protocol `0.1.22` keeps Workflow at `0.1.3` and adds an explicit version-only migration from `0.1.21` that neither inventories nor rewrites Code Intelligence record v3 evidence. Protocol `0.1.21` introduced the project-scoped Polaris CodeGraph proxy, host adapter v3 registration, and auditable record v3; record v1 and v2 remain immutable historical evidence only.
 
 ## v0.1 scope
 

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-> 当前协议版本：`0.1.21`（开发中）；Workflow 版本：`0.1.3`
+> 当前协议版本：`0.1.22`（开发中）；Workflow 版本：`0.1.3`
 
 Polaris 是运行在 Coding Agent 宿主上的仓库原生工程工作流。它把需求、计划、实现、独立审查、验证和任务状态保存在 Git 仓库中，并通过确定性门禁防止需求漂移、证据过期和 Agent 自行宣布完成。
 
@@ -91,11 +91,13 @@ polaris code-intelligence add codegraph --repo .
 
 `codegraph init` 创建 `.codegraph/` marker；没有 marker 时 Polaris 直接使用源码和 Git，不生成阶段 record。Vendoring 会在 `.codex/config.toml` 与 `.mcp.json` 中非破坏地注册项目级 `polaris-codegraph` 代理，并保留其他设置。宿主可能要求信任项目或首次使用确认；是否批准仍由用户决定。
 
-Polaris 阶段只调用 `polaris_codegraph_explore`。代理先检查 status，按请求且确有 pending 时至多执行一次有界 `codegraph sync`，再执行一次 explore、复查 status，并保证 freshness envelope 位于图内容之前；阶段没有独立的 status/sync MCP 调用。`CURRENT` 表示 `NON_AUTHORITATIVE_CONTEXT`；`STALE` 与 `UNKNOWN` 表示 `NAVIGATION_ONLY`，必须完成 envelope 指定的源码/Git 回退；`UNAVAILABLE` 表示没有图内容。当前具名文件使用 `READ_SOURCE`，已删除文件使用 `INSPECT_GIT_DIFF`，索引级或不安全结果使用 `SEARCH_SOURCE`。Validation 不调用 CodeGraph，仍以源码、Git、构建、测试、静态检查和 Human Check 为准。
+Polaris 阶段只调用 `polaris_codegraph_explore`。代理先检查 status，存在 pending changes 时自动且至多执行一次有界增量 `codegraph sync`，再执行一次 explore、复查 status，并保证 freshness envelope 位于图内容之前；阶段没有独立的 status/sync MCP 调用。`CURRENT` 表示 `NON_AUTHORITATIVE_CONTEXT`；`STALE` 与 `UNKNOWN`/`TREAT_AS_STALE` 表示 `NAVIGATION_ONLY`，在使用任何结论前必须完成 envelope 指定的精确源码/Git 回退；`UNAVAILABLE` 表示没有图内容。当前具名文件使用 `READ_SOURCE`，已删除文件使用 `INSPECT_GIT_DIFF`，索引级或不安全结果使用 `SEARCH_SOURCE`。Validation 不调用 CodeGraph，仍以源码、Git、构建、测试、静态检查和 Human Check 为准。
 
-CodeGraph 的安装、初始化、配置、raw MCP 注册、watcher 与 daemon 归仓库所有者，而不是 Polaris。Polaris 绝不启动、配置、重新配置、等待或管理这些能力。raw `codegraph_explore` 或 `codegraph explore` 仍可作为带外工具使用，但不能支持 Polaris 的 `CURRENT` 证据。新 record 必须由保留的代理 bundle 与已完成回退投影为 v3；v1/v2 仅供历史读取。CodeGraph 始终可选，永远不是 Workflow 门禁。
+当 status 无法验证但仓库身份安全时，代理仍执行 `polaris_codegraph_explore`，并返回 `UNKNOWN`/`TREAT_AS_STALE`。图只用于导航；在使用任何结论前，必须完成精确源码/Git 回退。
 
-协议 `0.1.21` 新增项目级 Polaris CodeGraph 代理、Host Adapter v3 注册和可审计的 Code Intelligence record v3，Workflow 仍为 `0.1.3`。record v1/v2 仅作为不可变历史证据读取；新证据必须由保留的代理 bundle 投影为 v3。
+CodeGraph 的安装、初始化、配置、raw MCP 注册、watcher、daemon 与每次全量 `codegraph index` 重建都归仓库所有者，而不是 Polaris；全量重建始终由用户主动执行。Polaris 绝不启动、配置、重新配置、等待或管理这些能力。raw `codegraph_explore` 或 `codegraph explore` 仍可作为带外工具使用，但不能支持 Polaris 的 `CURRENT` 证据。新 record 必须由保留的代理 bundle 与已完成回退投影为 v3；v1/v2 仅供历史读取。CodeGraph 始终可选，永远不是 Workflow 门禁。
+
+协议 `0.1.22` 保持 Workflow `0.1.3`，并新增从 `0.1.21` 出发的显式纯版本迁移；该迁移不清点也不重写 Code Intelligence record v3 证据。协议 `0.1.21` 引入项目级 Polaris CodeGraph 代理、Host Adapter v3 注册和可审计的 record v3；record v1/v2 仍仅作为不可变历史证据读取。
 
 ## v0.1 边界
 

VERSION

@@ -1 +1 @@
-0.1.21
+0.1.22

docs/USAGE.md

@@ -2,7 +2,7 @@
 
 本文面向希望在受支持 Coding Agent 宿主中使用 Polaris 管理软件工程任务的项目成员。当前内置 Codex 与 Claude Code 适配器；本文从首次接入讲到日常提出需求、独立 Implementation、进度查询、Review、验证、恢复与升级。
 
-> 当前协议版本：v0.1.21；Workflow 版本：v0.1.3。Polaris v0.1 是仓库原生的 Skills、宿主 worker 定义与 Python 脚本集合，并提供一个只分发到这些脚本的 `polaris` CLI；不提供后台服务或图形界面。
+> 当前协议版本：v0.1.22；Workflow 版本：v0.1.3。Polaris v0.1 是仓库原生的 Skills、宿主 worker 定义与 Python 脚本集合，并提供一个只分发到这些脚本的 `polaris` CLI；不提供后台服务或图形界面。
 
 ## 1. 先理解 Polaris 保存什么
 
@@ -219,13 +219,15 @@ Python CLI 无法直接查看 Codex 或 Claude Code 当前会话中的 MCP 工
 }
 ```
 
-CodeGraph watcher 与连接时 reconciliation 是常规实时更新机制。Polaris 阶段只调用 `polaris_codegraph_explore`：代理在同一有界窗口内检查 status，按调用参数且确有 pending 时至多运行一次 `codegraph sync`，执行一次 explore，再复查 status。阶段没有独立的 status/sync MCP 工具，也不会等待 watcher、轮询、重试、启动 daemon 或改写用户的 raw MCP 配置。Documentation Sync 仅在 supported source 变化时执行一次查询，使用 `sync_if_needed: true`，并把 query 限制到 changed source paths 与 documented symbols。
+CodeGraph watcher 与连接时 reconciliation 是常规实时更新机制。Polaris 阶段只调用 `polaris_codegraph_explore`：代理在同一有界窗口内检查 status，存在 pending changes 时自动且至多运行一次增量 `codegraph sync`，执行一次 explore，再复查 status。阶段没有独立的 status/sync MCP 工具，也不会等待 watcher、轮询、重试、启动 daemon 或改写用户的 raw MCP 配置。Documentation Sync 仅在 supported source 变化时执行一次查询，把 query 限制到 changed source paths 与 documented symbols；automatic incremental sync 仅由代理负责。
 
-代理结果的第一个内容块总是 freshness envelope。`CURRENT / NON_AUTHORITATIVE_CONTEXT` 表示图可作为非权威上下文；`STALE / NAVIGATION_ONLY` 表示已知失效；`UNKNOWN / NAVIGATION_ONLY` 表示无法证明新鲜度；`UNAVAILABLE / NO_GRAPH` 表示没有图输出。任何状态都不宣称与 Git commit 严格一致，`UNKNOWN` 绝不能当作 current。raw `codegraph_explore` 或 `codegraph explore` 仍可由用户带外调用，但不能支持 Polaris 的 `CURRENT` 证据。
+当 status 无法验证但仓库身份安全时，代理仍执行 `polaris_codegraph_explore`，并返回 `UNKNOWN`/`TREAT_AS_STALE`。图只用于导航；在使用任何结论前，必须完成精确源码/Git fallback。
 
-`STALE` 或 `UNKNOWN` 必须先完成 envelope 指定的源码/Git fallback。当前具名普通文件直接读取并记录 `READ_SOURCE` 与当前 SHA-256；安全但已删除的路径检查注册 subject 的 Git diff，记录 `INSPECT_GIT_DIFF`、null observed SHA-256 与 base/head/diff hashes；不安全路径或索引级失效执行 `SEARCH_SOURCE`，记录有限、受限的当前文件路径与 SHA-256。图不能扩大冻结 scope、替代源码或决定 Review verdict，Validation 完全不调用 CodeGraph。
+代理结果的第一个内容块总是 freshness envelope。`CURRENT / NON_AUTHORITATIVE_CONTEXT` 表示图可作为非权威上下文；`STALE / NAVIGATION_ONLY` 表示已知失效；`UNKNOWN / TREAT_AS_STALE / NAVIGATION_ONLY` 表示无法证明新鲜度；`UNAVAILABLE / NO_GRAPH` 表示没有图输出。任何状态都不宣称与 Git commit 严格一致，`UNKNOWN` 必须按 `TREAT_AS_STALE` 处理，绝不能当作 current。raw `codegraph_explore` 或 `codegraph explore` 仍可由用户带外调用，但不能支持 Polaris 的 `CURRENT` 证据。
 
-每次代理调用都会把精确响应和 bundle 留在 ignored 的 `runtime/code-intelligence/`。完成 fallback 后，Agent 写只含 summary、已确认 symbols 和 source_fallbacks 的 annotations JSON，再运行 `record_code_intelligence.py <task-id> --repo . --bundle <bundle-path> --annotations <annotations-path>` 投影不可变 v3 record。不得手写 record；没有代理调用就省略 record。v1/v2 record 仅作为不可变历史证据读取。
+`STALE` 或 `UNKNOWN`/`TREAT_AS_STALE` 必须先完成 envelope 指定的精确源码/Git fallback。当前具名普通文件直接读取并记录 `READ_SOURCE` 与当前 SHA-256；安全但已删除的路径检查注册 subject 的 Git diff，记录 `INSPECT_GIT_DIFF`、null observed SHA-256 与 base/head/diff hashes；不安全路径或索引级失效执行 `SEARCH_SOURCE`，记录有限、受限的当前文件路径与 SHA-256。图不能扩大冻结 scope、替代源码或决定 Review verdict，Validation 完全不调用 CodeGraph。
+
+每次代理调用都会把精确响应和 bundle 留在 ignored 的 `runtime/code-intelligence/`。完成 fallback 后，Agent 写只含 summary、已确认 symbols 和 source_fallbacks 的 annotations JSON，再运行 `record_code_intelligence.py <task-id> --repo . --bundle <bundle-path> --annotations <annotations-path>` 投影不可变 v3 record。不得手写 record；没有代理调用就省略 record。全量 `codegraph index` 始终由用户主动执行，v1/v2 record 仅作为不可变历史证据读取。
 
 ## 4. Polaris 仓库自举
 
@@ -611,8 +613,9 @@ polaris migrate --repo .
 2. 注册步骤同时绑定源/目标 `polaris_version` 与 `workflow_version`。Migration protocol v2 支持仅更新版本，也支持显式替换冻结 workflow 并映射任务状态。
 3. `0.1.19 → 0.1.20` 使用 `replace_version_and_workflow` 与 `append_mapped_workflow_event`：冻结 workflow 更新到 `0.1.3`，旧 `IMPLEMENTED` / `DOCS_SYNCED` 映射到 `IMPLEMENTING`，旧 `REVIEWED` 映射到 `VALIDATING`；旧 R0/R1 `VERIFIED` 也映射回 `VALIDATING`，以便通过 `PASS_AND_CLOSE` 重新提交关闭产物，R2 `VERIFIED` 保持不变。迁移事件记录源/目标状态及旧版本；旧 `events.jsonl` 行不可修改。
 4. `0.1.20 → 0.1.21` 只替换协议版本，Workflow 保持 `0.1.3`。迁移会校验并清点 canonical v1/v2 Code Intelligence 历史记录的路径与 SHA-256，保持原字节不变；中断恢复前会重算清单，任何变化都会拒绝继续。v1/v2 此后仅可作为历史证据读取。
-5. `.polaris/migrations/MIG-<from>-to-<to>.json` 先写为 `IN_PROGRESS`，全部投影更新后改为 `COMPLETED`。迁移锁会记录迁移/任务身份、主机名和 PID；若进程在中间终止，同一主机重新执行命令会接管已死亡的同迁移锁、验证并复用已经追加的事件，不会重复迁移。活跃进程、其他迁移或来源不明的锁不会被自动删除。
-6. 迁移完成后脚本自动运行项目校验；`validate_project.py` 会拒绝未完成记录、缺失/伪造的任务迁移事件或版本不一致。
+5. `0.1.21 → 0.1.22` 只替换协议版本，Workflow 保持 `0.1.3`。迁移记录中的 `retired_code_intelligence_records` 固定为空列表，不重新清点或重写任何 record v3 历史证据。
+6. `.polaris/migrations/MIG-<from>-to-<to>.json` 先写为 `IN_PROGRESS`，全部投影更新后改为 `COMPLETED`。迁移锁会记录迁移/任务身份、主机名和 PID；若进程在中间终止，同一主机重新执行命令会接管已死亡的同迁移锁、验证并复用已经追加的事件，不会重复迁移。活跃进程、其他迁移或来源不明的锁不会被自动删除。
+7. 迁移完成后脚本自动运行项目校验；`validate_project.py` 会拒绝未完成记录、缺失/伪造的任务迁移事件或版本不一致。
 
 没有注册路径时不要手改版本号。应先取得包含所需相邻步骤的 Polaris 版本，逐级完成并分别提交；任何失败都先保留 `.polaris/migrations/` 和事件现场，修复原因后重跑同一迁移命令。
 
@@ -638,6 +641,8 @@ v0.1.20 / Workflow v0.1.3 删除没有独立治理边界的中间状态和事件
 
 v0.1.21 新增项目级 Polaris CodeGraph MCP 代理、Host Adapter v3 注册与 Code Intelligence record v3；Workflow 仍为 v0.1.3，CodeGraph 仍为可选且不参与门禁。v1/v2 record 仅作为不可变历史证据读取。
 
+v0.1.22 新增 `0.1.21 → 0.1.22` 显式相邻迁移；Workflow 仍为 v0.1.3。该迁移不重新清点或重写 record v3，迁移记录中的 retirement inventory 固定为空。
+
 ## 13. 失败探索与卡点
 
 如果一个技术方向被证据否定，不要让结论只留在聊天中。记录任务内探索：