用途
CocoTrace 用于在软件生命周期产物之间建立并查询“需求到实现”的可追溯性。它维护一条有向依赖图：bloom.md → discuss.md → spec.md → plan.md → build-output → eval-results。通过 SHA-256 内容哈希检测真实变更，而非依赖 git 操作导致的时间戳漂移；任何节点变更后，过期状态会沿依赖链向下游传播。
主要能力
- $trace build：执行 cocotrace/trace-check 契约（确定性、不使用 LLM、Tier 2 异步），读取 lifecycle/trace.json，显示各产物的状态（current/stale/missing）与 SHA-256 摘要表，并创建 git 提交：chore(cocotrace): update artifact traceability graph。输出形如“[N] current, [M] stale, [P] missing”。对未变更内容重复运行会生成逐位相同的 trace.json。
- $trace gaps：读取 trace.json 与 spec.md，提取 spec.md 中所有 ## 标题作为需求章节，检查 lifecycle/build/ 中对应的实现文件，报告孤立需求（spec.md 中无构建产物）、未覆盖代码（build/ 中无可追溯需求）以及覆盖率。若 spec.md 没有 ## 章节标题，则输出提示并优雅退出。
- $trace show <artifact>：从指定产物向后追溯上游节点、向前追溯下游节点，以 ASCII 依赖链显示，并标注“YOU ARE HERE”。
- $trace blast <object>：计算指定 Snowflake 对象（表、视图、列或 Cortex 模型标识符）的影响范围，即 CocoPod 中所有依赖该对象的 Cortex 函数。读取 snowflake-deps.json（由 $trace sync 维护的函数→对象依赖反向索引），返回每个受影响函数的依赖类型（read/write/structural）、到 CocoBloom 承诺与 CocoSpec 结果陈述的下游可追溯链，以及其 CocoContract 证据相对于对象当前状态是否过期。
- $trace check --before-change "<change description>"：变更前影响评估门，不阻止变更。对变更描述所隐含的对象运行影响范围计算，生成人类可读的影响摘要，并通过 CocoAudit 将门事件记录到 lifecycle/audit.md，证明变更前已评估影响范围。输出与 $trace blast 相同的影响范围表，并附变更描述与审计确认行。
- $trace health：计算当前依赖图的 Snowflake 资产健康等级。运行 invoke cocotrace/health-grader --input .cocoplus/trace/snowflake-assets.json。等级为 A-F，综合死资产百分比、循环依赖、耦合、安全发现、层级违规和变更热点。死资产包括零调用 UDF、未被查询的视图和过期表；层级违规包括 BI 直接消费暂存对象、应用代码更新原始源、从开发环境访问生产资产。若 cocoplus.toml 中 [trace].show_grade = false，则隐藏字母等级但仍显示底层指标。
- $trace compare <before.json> <after.json>：运行 invoke cocotrace/health-grader --compare <before.json> <after.json>，以 before/after 差值显示热力收据行，例如：blast radius 23 -> 18 v / health B+ -> A- ^。
使用方式
通过 $trace 系列命令操作。SessionStart 会追加一个 cocotrace/trace-check 请求（Tier 2 异步、非阻塞）；若有产物过期，会显示非阻塞提示，例如“⚠️ CocoTrace: discuss.md changed since spec.md was last traced. Run $trace build to update the traceability graph.”。trace.json 会记录本次追踪运行的 git 分支与提交元数据，并提交到 git 供团队查看。报告（如 trace-gaps.md 或影响范围摘要）可通过共享导出器导出：invoke reporting/report-export --source <trace-report.md> --format <markdown|html|pdf> --out-dir .cocoplus/trace/exports；PDF 请求会报告渲染器可用性，Markdown 与 HTML 为本地确定性导出。
适用场景
适用于需要维护需求与实现之间可追溯性的 Snowflake 数据与 Cortex 项目，尤其是需要评估变更影响范围、检测过期产物、分析可追溯性缺口和评估资产健康度的团队。
限制
cocotrace/trace-check 是确定性的，不使用 LLM 或推理；SHA-256 基于文件内容而非元数据；过期状态按 walk_order 传播，上游变更则下游始终过期；SessionStart 提示为非阻塞，绝不阻止会话启动。