docs: 规划 engineering-guard 事实提供方接入（EG-F01—08 全部待实施）

把 codegraph-plugin 接入 codeguard 工程守卫的规划入库。**本轮仅规划，
不含任何代码实现**——tasks.md 中 EG-F01—08 全部未勾选，fixture 与测试
模块为拟新增，文中已明确不声称其存在或执行。

内容：
- docs/engineering-guard-plan.md 规划入口与事实源索引
- openspec/changes/integrate-engineering-guard-facts/
  proposal / design / specs/engineering-fact-provider / tasks
- .openspec.yaml 声明 spec-driven schema（仓库历史 v1 schema 不被当前 CLI 识别）

范围约定：
- 本插件只提供接入说明与既有命令调度约束；事实转换器由 codeguard 工程内核
  持有，两仓不重复实现，不 vendor 上游 CLI。
- 缺索引、过期、未知解析语义、输出截断一律映射为 unknown；查询成功不等于
  架构合规。
- 保留仅 SessionStart、官方提示词原文、无索引静默与 fail-open；不新增阻断钩子。
- 索引创建/更新遵守用户授权，不自动重建用户索引。

与 v0.2.0 无冲突：该变更声明的「无索引静默」指 SessionStart 钩子（保持不变），
索引授权与 v0.2.0 的「提示后征得同意」一致。

Author: loong10k

docs/engineering-guard-plan.md

@@ -0,0 +1,20 @@
+# codegraph-plugin 工程守卫规划入口
+
+日期：2026-10-09。状态：规划已写入，新增能力尚未实施。职责：**源码事实与提供者能力**。
+
+## 本仓唯一规划事实源
+
+- [提案](../openspec/changes/integrate-engineering-guard-facts/proposal.md)：目标、兼容与范围。
+- [设计](../openspec/changes/integrate-engineering-guard-facts/design.md)：现有实现、改动位置、协议、风险、迁移与验证。
+- [实施任务](../openspec/changes/integrate-engineering-guard-facts/tasks.md)：EG-F01—08，全部待实施。
+- 规范要求位于同一 change 的 `specs/`，不会通过本入口另建任务或验收账本。
+
+## 联合规划定位
+
+完整体系由 codeguard 仓库 `docs/engineering-guard/README.md` 导航：包含六仓基线、统一内核、技术工具、协议、P0—P4、追溯和验收矩阵。共享协议的事实源是 `codeguard/openspec/changes/add-engineering-guard-core/`；本仓只定义自己拥有的集成行为。
+
+本地按“仓库名 + 仓内路径”读取；分发时使用固定版本 release manifest 和协议摘要，不要求安装者保有兄弟仓库。任何新 CLI、适配器、schema 或 fixture 都是计划产物，实际接口以实施后的协议发布为准。
+
+## 执行约束
+
+沿用本仓 AGENTS、现有规格/未完成任务和已有行为，保护用户未提交修改。先完成依赖任务，再进行行为测试 RED→最小实现→GREEN→受影响回归。真实宿主、原生工具、CI、服务端保护和平台分别验收。规划完成不触发安装、分支切换、发布或默认模式变化。

openspec/changes/integrate-engineering-guard-facts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-09

openspec/changes/integrate-engineering-guard-facts/design.md

@@ -0,0 +1,49 @@
+## Context
+
+现有 `scripts/codegraph_lib/{host_targets,instructions_writer,prompt}.py` 负责索引存在检测、指令维护及官方提示词；本插件没有 `.codegraph/`，本轮未创建索引。现有 AGENTS 明确禁止修改上游 CLI、引入阻断 Hook 或自动 install。动机见 [proposal](proposal.md)，行为见 [spec](specs/engineering-fact-provider/spec.md)。
+
+## Goals / Non-Goals
+
+**Goals:** 将已有 CodeGraph 能力纳入工程守卫的事实层，准确披露索引、覆盖和版本；完成 P0 接入发现、P3 语义影响和 P4 基线演进的规划。
+
+**Non-Goals:** 不在本插件实现架构裁判、Rust 内核、第二套数据库或解析器；不修改官方提示词来塞入门禁命令。
+
+## Decisions
+
+1. 共享协议 owner：`codeguard/openspec/changes/add-engineering-guard-core/`，字段说明 `codeguard/docs/engineering-guard/protocol.md`。本插件维护提供者能力清单/调度说明/测试样例，真实 FactEnvelope 转换器在ArchGuard 的事实 adapters 中实现，避免双份逻辑。
+2. 先探测实际 CLI 版本及支持命令，不虚构 `codegraph export --json`。仅调用已确认的 status/files/query/符号查询能力；若当前版本没有稳定结构化输出，结果只作发现线索，确定性检查转用语言专用工具。未来上游增强另立上游任务，不纳入本仓偷偷实现。
+3. query 绑定实际仓库、源码清单摘要、索引身份与查询预算。区分语法边、解析符号边、启发式边；没有某条边不能在部分覆盖下证明依赖不存在。源码变更或 engine/index 不兼容使受影响事实 stale。
+4. 本次只读审查发现 codereview-plugin 索引为旧引擎且有待更新文件；此类状态应成为负向 fixture。图谱路径可用于定位，最终位置与关键关系仍结合当前源码验证。
+5. P0 文档和 fixture 不添加新的自动写操作；P3 才提供任务 changedSymbols/consumedApis/affectedTests 的能力映射。affectedTests 只能帮助排序，不允许删减契约指定回归。
+6. 框架反射、动态分派、代码生成、宏与跨语言桥接按 provider 能力记录 unknown/partial；人工 ADR 风险不从 AST 自动判定。P4 只对相同事实模型版本进行趋势比较，模型变更先建立可比性。
+
+```mermaid
+flowchart LR
+  C[已授权查询] --> U[现有 CodeGraph CLI]
+  U --> A[ArchGuard 事实适配器]
+  A --> V{身份与覆盖}
+  V -->|充分| F[有范围的结构事实]
+  V -->|过期或截断| X[unknown / stale]
+  F --> G[架构规则或语义审查]
+```
+
+## Implementation surfaces
+
+| 位置 | 计划修改 | 必保兼容 |
+|---|---|---|
+| `docs/engineering-guard-plan.md` | 接入、事实限制、授权、升级路径 | 不改变现有命令承诺 |
+| `tests/` 新增 provider 契约 fixture | 缺索引、旧版本、截断、位置漂移、动态边 | 测试不自动初始化用户仓库 |
+| `commands/`、`kimi-commands/` | 如需新增说明，按现有生成与双格式规则 | 不错误宣称格式对应某宿主 |
+| `scripts/codegraph_lib/prompt.py` | 原文 parity 验证 | 不改 CODEGRAPH_INSTRUCTIONS_BLOCK |
+
+实施验证：既有 `python3 -m unittest discover -s tests -t .`、README parity、命令覆盖及真实宿主 SessionStart；共享 adapter fixture 在 codeguard 单独验收。未安装宿主只标 unverified。
+
+## Risks / Trade-offs
+
+- [上游输出漂移] → capability probe + 固定支持矩阵；不解析含糊文本作强制事实。
+- [假称完整调用图] → 披露解析模式和预算，负向证明要求完整覆盖。
+- [提示词漂移] → 所有治理说明放独立文档，原文块保持字节一致。
+
+## Migration Plan
+
+先发布文档/能力契约，随后协调内核适配；独立运行完全兼容。升级/重建索引仍由既有授权决定。回滚不删除索引，不修改其他插件状态；旧提供者不能满足新必需事实时保持 incomplete。

openspec/changes/integrate-engineering-guard-facts/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+工程守卫需要可追溯的源码关系事实，但 CodeGraph 的查询成功、旧索引或截断输出都不能直接证明架构合规。插件需明确接入契约和能力边界，同时继续保持上游 CLI 的纯客户端定位。
+
+## What Changes
+
+- 规划 CodeGraph 提供者的能力清单、版本/索引/源码身份和不完整结果映射；实际事实转换器由 codeguard 的工程内核持有，本插件只提供接入说明和既有命令调度约束。
+- 保留仅 SessionStart、官方提示词原文、无索引静默和 fail-open；不增加阻断 Hook，不修改或 vendor 上游 CLI。
+- 缺索引、过期、未知解析语义、输出截断均保留 unknown；索引创建/更新遵守用户授权。
+- P3 接入符号影响与并行变更风险；P4 增加事实基线版本协商，仍不输出架构放行。
+
+## Capabilities
+
+### New Capabilities
+
+- `engineering-fact-provider`: 代码事实提供者的来源、能力、覆盖和兼容契约。
+
+### Modified Capabilities
+
+无。既有 session-start-prompt、commands-coverage 行为保持。
+
+## Impact
+
+插件文档、命令能力映射、协议 fixture 和宿主验收；不改变上游 codegraph。共同协议由 codeguard/add-engineering-guard-core 持有，转换器不在两个仓库重复实现。
+
+本轮仅规划；仓库历史 `openspec/v1` schema 不被当前 CLI 识别，新 change 显式使用可用的 spec-driven；未修改根 config 或旧 change。

openspec/changes/integrate-engineering-guard-facts/specs/engineering-fact-provider/spec.md

@@ -0,0 +1,45 @@
+## Purpose
+
+为 Partme Guard 提供 engineering-fact-provider 的可观察行为契约，统一已批准约束、当前候选和独立验证证据的关联，并明确未知、失败、兼容模式与越权情况下不得伪造工程通过的边界。
+
+## ADDED Requirements
+
+### Requirement: EG-CGP-001 Client boundary
+
+插件 SHALL 保持现有命令客户端和 SessionStart 提示定位；不改上游 CLI、不增加阻断 Hook、不在本插件重复实现工程策略或图谱引擎。
+
+#### Scenario: EG-CGP-001 contract behavior
+- **WHEN** 未安装统一工程内核或会话 Hook 异常
+- **THEN** 保留原静默/fail-open 行为，不阻断宿主启动
+
+### Requirement: EG-CGP-002 Fact identity
+
+集成契约 SHALL 为图谱事实提供 CLI/索引版本、查询范围、源码摘要、位置、解析类型和覆盖限制；领域事实适配由 ArchGuard 实现，GuardCore 仅定义通用 envelope。
+
+#### Scenario: EG-CGP-002 contract behavior
+- **WHEN** 已有索引与候选文件不同或引擎版本不兼容
+- **THEN** 标记 stale/unknown，不能作为完整架构负向证明
+
+### Requirement: EG-CGP-003 Explicit indexing
+
+插件 MUST 遵守索引创建、重建与配置的显式授权；只读接入检测不自动 init/sync/install。
+
+#### Scenario: EG-CGP-003 contract behavior
+- **WHEN** 发现没有索引
+- **THEN** 报告缺失；可用的其他确定性检查继续，缺图谱义务保持未知
+
+### Requirement: EG-CGP-004 Bounded capabilities
+
+集成 SHALL 区分稳定结构化输出与自然语言发现输出；截断、动态分派未解析及不支持语法明确披露。
+
+#### Scenario: EG-CGP-004 contract behavior
+- **WHEN** 查询只返回部分调用关系
+- **THEN** 结果不得声明无其他依赖或已完整发现冲突
+
+### Requirement: EG-CGP-005 Lifecycle compatibility
+
+插件 SHALL 保持官方提示词原文、命令目录归属、用户文档原子维护和既有独立运行；分发与宿主验收分别留证。
+
+#### Scenario: EG-CGP-005 contract behavior
+- **WHEN** 新增治理说明后启动会话
+- **THEN** additionalContext 仍来自原文块，不混入自造门禁指令

openspec/changes/integrate-engineering-guard-facts/tasks.md

@@ -0,0 +1,25 @@
+# 工程守卫实施任务
+
+状态：全部待实施。本轮仅完成规划；下面的 fixture/测试模块为拟新增，不声称已经存在或执行。只在实现、目标 RED→GREEN、受影响回归及所需真实环境证据齐备后勾选。
+
+依赖前缀：K=codeguard 内核，F=codegraph-plugin，H=codeguard-plugin，R=codereview-plugin，G=gitflow-plugin，W=flowguard-plugin。跨仓依赖通过任务 ID 引用，完成状态只在所属仓账本维护。所有实现先复核当前 HEAD 与用户修改；目标路径见 [design](design.md)。
+
+## 1. P0 提供者契约与兼容
+
+- [ ] 1.1 **EG-F01** 核对上游 CLI 能力与当前 SessionStart/原文块/命令覆盖，先加独立运行兼容反例；不创建用户索引。 依赖：EG-K01。规格：EG-CGP-001, EG-CGP-005。
+- [ ] 1.2 **EG-F02** 编制版本/索引/源码身份与授权映射 fixture；缺索引、旧索引和查询时变化必须 unknown；转换器归 core。 依赖：EG-F01。规格：EG-CGP-002, EG-CGP-003。
+- [ ] 1.3 **EG-F03** 为已支持 CLI 输出提供完整/截断/坏报告 fixture 与 capability 清单；没有机器协议时明确 advisory，不虚构命令。 依赖：EG-F02。规格：EG-CGP-004。
+
+## 2. P2 宿主与事实分发
+
+- [ ] 2.1 **EG-F04** 执行 unittest、README parity、命令覆盖及实际宿主 SessionStart；插件文档与官方原文块分离，分别记录宿主限制。 依赖：EG-F03。规格：EG-CGP-005。
+
+## 3. P3 符号与影响契约
+
+- [ ] 3.1 **EG-F05** 为符号/调用/API/受影响测试定义查询能力与解析类型测试集，包含宏/反射/跨语言 unknown，供 core EG-K21 使用。 依赖：EG-F03。规格：EG-CGP-002, EG-CGP-004。
+- [ ] 3.2 **EG-F06** 共同验收不同文件 API 影响样例与源码位置漂移；不据 affectedTests 删减必需回归。 依赖：EG-F05, EG-K21。规格：EG-CGP-004。
+
+## 4. P4 基线与发行
+
+- [ ] 4.1 **EG-F07** 定义不同上游版本与事实模型的可比性、升级/回滚和许可来源；不自动重建用户索引。 依赖：EG-F06。规格：EG-CGP-002, EG-CGP-005。
+- [ ] 4.2 **EG-F08** 完成不可变版本、manifest/市场同步和安装回执；索引可用、宿主接线和治理生效分别验收。 依赖：EG-F04, EG-F07。规格：EG-CGP-001, EG-CGP-005。