feat: trace per-step knowledge delivery and evidence

doc/README.md

@@ -35,6 +35,7 @@
 | 文档 | 状态 |
 |---|---|
 | [`features/provider-registry.md`](features/provider-registry.md) | 已实现——五种后端的统一注册表 |
+| [`features/knowledge-use-trace.md`](features/knowledge-use-trace.md) | 知识检索、内容提供、规则检查与证据的逐步追踪 |
 | [`features/strict-review-deep-engine.md`](features/strict-review-deep-engine.md) | 已实现（默认开） |
 | [`features/review-recall.md`](features/review-recall.md) | 已实现（默认开）——v14/v15 召回攻坚 |
 | [`features/auto-run.md`](features/auto-run.md) | **draft，未实现**——GitHub 事件触发 |

doc/architecture/SPEC/README.md

@@ -68,7 +68,7 @@
 | 跨切 | `review/{diff_summary,triggers,reviewer}` `memory/{debug_memory,skills}` `run_trace` `notify` `metrics` |
 | 后端 | `providers/{registry,base,claude_code,codex,cursor,deepseek,zcode,audit,harness_llm}` `tool_bridge` |
 | MCP 面 | `thin_mcp_server` `mcp_server` `mcp_policy` `run_status` `knowledge_docs` `__main__` |
-| 共享服务 | `kb_service` `rfc_service`（包规范覆盖各自实现模块） |
+| 共享服务 | `kb_service` `rfc_service` `knowledge_trace`（包规范覆盖各自实现模块） |
 
 平凡的 `__init__.py` 再导出文件不单独出规范
 （`engine/steps/__init__` 例外，因为它定义了 `register_builtin_steps`）。

doc/architecture/SPEC/adapters/base.md

@@ -1,6 +1,6 @@
 # adapters/base.py —— 规范
 
-<!-- verified-against: 2026-09-28 -->
+<!-- verified-against: 2026-11-04 -->
 
 `LOC ~423 · 边缘（仓库知识） · refactor-status: ok`
 
@@ -64,3 +64,11 @@
 
 ## 2026-09-28 knowledge_lifecycle
 `knowledge_lifecycle` 加入 `HIGH_RISK_SECTIONS`：知识服务的开关与 `auto_merge` 切换只能经人工审阅修改。
+
+## 2026-11-04 逐文档 briefing 观测
+
+`render_briefing_docs(..., on_document=None)` 和 `RepoAdapter.briefing` 接受可选
+回调，报告实际经过 visible-text、frontmatter 去除、首尾空白去除和 briefing
+上限后保留的文档片段、相对文档 ID、源偏移与截断状态。零长度片段不代表
+模型获得正文；后续请求级裁剪仍由 agent runtime 核实。未传回调时渲染行为不变。
+回调不另读知识、不增加 briefing 预算，也不改变 manifest 写入门。

doc/architecture/SPEC/app/workflow_execution.md

@@ -1,6 +1,6 @@
 # app/workflow_execution.py — workflow execution boundary
 
-<!-- verified-against: 2026-10-29 -->
+<!-- verified-against: 2026-11-04 -->
 
 `WorkflowExecution` runs an already selected playbook with the caller's
 current LLM dependency. It rechecks the repository context before starting,
@@ -36,3 +36,12 @@ not belong in this module.
 `Copilot._execute` remains the compatibility entry point and records
 `last_run_dir`/`last_blocked_reason` from the returned result. Existing run
 state keys, traces, exit codes, and checkpoint behavior stay stable.
+
+Knowledge-use tracing is finalized in the same execution `finally` boundary,
+after restoring signal handlers. An existing session receives `complete` only
+when the executor returned `done` without shutdown; other exits receive
+`interrupted`. Finalization writes `KNOWLEDGE_TRACE.json` and
+`KNOWLEDGE_TRACE.md` through the agent-runtime owner. No session is created
+merely to finalize a workflow, and run finalizers, interruption handling and
+lock ownership retain their existing behavior. Required-mode trace failures
+propagate rather than allowing an audit-complete result.

doc/architecture/SPEC/cli.md

@@ -1,6 +1,6 @@
 # cli/ —— 规范
 
-<!-- verified-against: 2026-10-30 -->
+<!-- verified-against: 2026-11-04 -->
 
 `LOC ~1420（6 个文件） · 接口 + 编排门面 · refactor-status: ok`
 
@@ -141,3 +141,12 @@ RFC 子命令原样转发与共享入口：`test_rfc_integration.py`；服务契
 保留原始 run，不自动重放已经完成的任务。托管安装的执行还在 worker 内持有
 跨进程 checkout/PR 锁，以覆盖不同 MCP 进程和 release；运行时固定与控制面契约见
 [upgrade.md](upgrade.md)。
+
+## 2026-11-04 知识使用追踪
+
+`infermatrix-copilot knowledge-trace …` 在通用 argparse、Copilot 和模型构造前
+分派到 `knowledge_trace.cli.main`。`show` 支持原始事件分页；`export` 读取全部
+事件页后输出 JSON 或 Markdown；`query --repo … --rule …` 返回有界事件摘要。
+`--root` 指定追踪运行目录；读取已有记录不受采集模式 `off` 限制。该入口不读取
+产品知识来补造历史记录，也不调用模型或发布结果。验证见
+`test/test_knowledge_trace_cli.py`。

doc/architecture/SPEC/engine/agent_runtime.md

@@ -1,6 +1,6 @@
 # engine/agent_runtime/ —— 规范
 
-<!-- verified-against: 2026-10-06 -->
+<!-- verified-against: 2026-11-04 -->
 
 `LOC ~1690（7 个文件） · 引擎（受治理的 agent 运行时） · refactor-status: ok`
 
@@ -119,3 +119,26 @@ cheap-seat 与按 pass 路由、MoA harness 成员、考古工具）。有两条
 ## 自进化接入（2026-10-04）
 
 影子 agent 使用严格只读 scope，知识检索与 repo map 受读根约束，拒绝知识写入工具。API 与 harness 调用均记录 trace/1；工作流的采集和配置指纹由执行器绑定，普通生产运行保持既有工具能力。
+
+## 2026-11-04 知识使用追踪
+
+`knowledge_trace.py` 是 Strict 到共享 `knowledge_trace/` 协议的唯一桥接：
+每次执行尝试建立一份会话，并行步骤和 MoA 成员保留完整的限定 step ID。
+`dispatch` 增加可选 `knowledge_assessments`，把规则、具体检查、证据和 finding
+关联；缺失声明保持未评估。每次模型调用的证据 ID 独立，重复 step 不覆盖旧证据。
+
+文档工具与 briefing 先记录检索，再排队候选内容；runner 在最终请求组装和
+裁剪后确认实际存在的片段，才记录 `model_request` 提供边界。自适应服务返回的
+`documents` 只作引用；`adaptive.packet_fragments` 仅解析实际 `model_content`
+中完整、哈希一致的 provider 围栏，不再读取源文档。保留 repo、source pins 和
+上下文会话元数据；continuation 或变换片段的源区间未知，预算截断明确保留。
+已授权的跨仓库自适应内容保持原执行行为，由单仓库追踪记录
+`context_cross_repository_unobserved` 缺口，不扩大追踪权限。累计预算、反馈回执、
+containment 与用户协议门继续由原知识上下文服务拥有。
+
+API 模式可以观测模型请求；harness 模式记录提供给外部 CLI 的 prompt 边界，
+外部 CLI 的原生读取和内部请求不能据此宣称已观测。skill/debug memory 保留
+检索身份并说明其缺少 curated-document 来源。`required` 采集失败阻止后续受控
+工作，`best_effort` 保持执行并标为 degraded；终结时写 JSON/Markdown 报告。
+验证见 `test/test_knowledge_trace_strict.py`、
+`test/test_knowledge_trace_adaptive_strict.py`。