SpecKit 工作区治理

要解决什么问题

在多 Skill 协作的 SpecKit 工作区里，正式契约、运行状态、产品页面、证据、临时文件和历史迭代很容易混在同一棵目录树里。历史版本若被塞进 archive/ 或藏在 feature 根目录，会丢失「版本号即索引」的交付语义；未登记的 evidence、重复的 Artifact-Key、以及冻结前仍存在的 Unknown 文件，也会让 Version 冻结与 Publish 无法可信地消费 manifest。

技能如何工作

本 Skill 只做跨 Skill 的目录治理，不编写业务 spec 或产品页面。它维护三层边界：feature 工作区、prototype/ 产品原型包、prototype/evidence/ 证据仓。

常用模式如下：

• audit：只读审计；默认输出 summary，完整 findings 写入 .specify/audit/。
• archive：仅移动已确认的临时文件到 .specify/archive/<run-id>/，并生成归档清单；不收纳历史版本，也不得把历史原型移入 archive。
• gate：Version 冻结前门禁；冻结前自动运行 audit_workspace.py --mode gate，Unknown 须人工处理。

Version 会先生成 .specify/cache/workspace-inventory.json，Archive、Audit 与门禁复用同一份 inventory，避免对同一批文件重复计算 SHA-256。版本路径审计会校验 Product-ID、Product-Version、Spec-Revision、Feature-ID 与 Artifact-Key（须唯一且符合 product/version/artifact）；出现 DUPLICATE_ARTIFACT_KEY、PRODUCT_VERSION_MISSING 等会阻断冻结或发布。content-routing-contract.md 与 scripts/validate_spec_scope.py 用于审计 spec.md 是否混入原型演示、夹具与证据细节，而不把展示或 Git 推送绑进冻结流程。

与其它 Skill 的默认衔接：Analyze / Clarify / Review 的一次性脚本写在 .specify/work/<skill>/<run-id>/ 并在完成后自清理；Prototype 须符合 prototype package contract，活动中的 preflight.json 与 current-prototype-run.json 在 run 未完成时不可清；Version 自动做 feature 级 audit 与 prototype gate；Publish 只消费 Frozen manifest 声明的文件。

适用边界与注意点

• 历史版本与历史原型是正式交付资产：同一产品版本下的迭代按版本号并列，由 INDEX.md、product-index.json、release.json 标识最新修订；archive 仅表示 .specify/archive/ 内可恢复的临时残留。
• 已知临时文件只允许移入 .specify/archive/<run-id>/，禁止未经确认递归删除；每个生产 Skill 只清理自己生成的临时文件。
• field-contract.json、field-coverage.json、schema-snapshot.json、prototype/field-render-map.json 为受管控正式资产，不得归为 Unknown。
• 手动使用本 Skill 主要用于老项目迁移、残留归档、Unknown 处理与工作区健康检查。