用途
spec-coverage-map 用于生成一份可视化“规格说明到代码”覆盖映射图，展示哪些代码文件被哪些规格说明覆盖。它在实现阶段完成后或清理、文档阶段使用，帮助团队了解规格与实现之间的对应关系。
输出位置为 docs/spec-coverage-map.md，每次运行都会从头重新生成并覆盖已有文件。输出头部包含时间戳，路径使用相对于项目根目录的相对路径。
主要能力
- 发现规格说明：同时检查
.specify/memory/specifications和specs两个目录，合并结果并去重，统计规格数量。 - 提取文件引用：从每个规格中提取文件路径，支持反引号包裹路径、加粗路径（File: path/to/file.ext），以及 "Files"、"Implementation Status"、"Components Implemented"、"Technical Details" 章节中的路径，识别 .ts、.tsx、.js、.jsx、.py、.go、.tf、.yml 等扩展名。
- 文件分类：按后端、前端、基础设施、数据库、脚本、配置、测试等类别分组。
- 生成 ASCII 方框图：为每个规格生成方框图，展示其覆盖的文件，并标注状态和分类。
- 反向索引：生成文件到规格的对照表，标注覆盖数量与风险等级（1 个规格为 LOW，2-3 个为 MEDIUM，4+ 个为 HIGH）。
- 覆盖统计：按类别生成总文件数、已覆盖数、覆盖率表格，并生成热力图条形图。
- 缺口分析：列出未被任何规格覆盖的代码文件，按类别分组并给出建议。
- 共享文件评估：列出被 3+ 个规格引用的文件及风险等级；对高风险文件（4+ 规格）给出变更影响和测试建议。
使用方式
该技能通过命令运行，最终生成 docs/spec-coverage-map.md。其执行流程包括：发现规格 → 提取文件引用 → 校验（检查路径是否存在、统计规格数量是否匹配）→ 分类文件 → 生成 ASCII 方框图 → 创建反向索引 → 计算覆盖统计 → 识别缺口 → 高亮共享文件 → 组装输出。步骤 5-8 相互独立，可任意顺序生成，但都依赖步骤 1-4 建立的文件到规格映射。
运行时机：在 Gear 6（Implement）完成后或清理、文档阶段，生成覆盖图并报告摘要（总覆盖率、缺口数量、高风险共享文件）。解析规格时按排序顺序（001、002 等）处理以保证输出一致。
依赖与回退
该技能期望规格由 /stackshift.create-specs 或 /speckit.analyze 生成，并在上述章节中包含文件引用。若这些章节缺失，则回退为用正则提取反引号包裹的路径。跨技能引用包括 /stackshift.create-specs、/speckit.clarify、/speckit.analyze。
适用场景
- 需要快速了解哪些代码文件被规格覆盖、哪些没有。
- 在文档或清理阶段生成规格与代码的映射报告。
- 识别被多个规格引用的高风险共享文件。
- 发现没有文件引用的规格（标记 [NO FILE REFERENCES]）。
限制与错误处理
- 无规格：若两个目录中都未找到规格，则报错并停止，提示先运行 /stackshift.create-specs 生成规格。
- 单个规格无文件引用：在覆盖图中以空文件列表和 [NO FILE REFERENCES] 标记包含该规格，并在缺口分析中注明。
- 所有规格均无文件引用：报错并停止，列出可能原因（实现未开始、规格缺少 Files 或 Implementation Status 章节、使用旧格式等）。
- 覆盖率极低（< 50%）：提示覆盖率仅为 N%，建议运行 /speckit.analyze 校验对齐。
- 文件路径校验失败：在覆盖图中用 X 标记不存在的文件，并包含 "Stale References" 子章节列出规格中出现但代码库中不存在的路径。
- 若超过 50% 的规格没有文件引用，则报错并停止。反向索引中的唯一文件总数必须与方框图中的唯一文件总数一致。
- 引用文件中的示例数据不得复制，所有文件名和结构均从实际代码库推导。
成功标准
生成输出需包含：docs/spec-coverage-map.md 文件、每个发现规格的 ASCII 方框图、带风险等级的反向索引表、带热力图的分类覆盖统计、带建议的缺口分析、共享文件风险评估、整体覆盖率百分比。