CSDD 安装包

把 CSDD 治理层（宪法、门禁、模板、文档）安装到已有仓库，并按清单可选安装第三方扩展。

整个包放在 .specify/packages/csdd/，通过 spec-kit 扩展机制分发。

安装到目标仓库

cd /path/to/your-repo

# 1. 目标仓库先初始化 spec-kit（已初始化则跳过）
#    claude 集成默认就是技能格式，不接受 --skills
uvx --from specify-cli==1.1.3 specify init --here \
  --integration claude --script sh --ignore-agent-tools --non-interactive
#    codex 集成需要：--integration codex --integration-options="--skills"

# 2. 安装本扩展（本地目录用 --dev）
uvx --from specify-cli==1.1.3 specify extension add /path/to/csdd/.specify/packages/csdd --dev

# 3. 预演，确认后执行
bash .specify/extensions/csdd/scripts/csdd-install.sh --target . --agent claude
bash .specify/extensions/csdd/scripts/csdd-install.sh --target . --agent claude --apply

装完在 agent 里有四个命令：/speckit.csdd.install、/speckit.csdd.verify、/speckit.csdd.extensions、/speckit.csdd.navigate。

一键部署

克隆本仓库后，对任意目标项目：

# 预演：不写文件，打印计划
bash scripts/csdd-bootstrap.sh --target /path/to/project --agent claude

# 执行；--with-extensions all 同时装清单里的第三方扩展（默认不装）
bash scripts/csdd-bootstrap.sh --target /path/to/project --agent claude --yes
bash scripts/csdd-bootstrap.sh --target /path/to/project --agent codex --yes --with-extensions brownkit,blueprint-index

只支持 claude、codex，其它集成未验证。目标项目需要有 README.md。退出码：0 成功 / 2 初始化失败 / 3 治理层有冲突 / 4 自检或扩展安装失败 / 5 安装成功但门禁自检因 .claude/ 下第三方技能文档的示例链接失败（见「已知限制」）。

第三方扩展优先用本仓库 cache/ 里的压缩包（哈希与清单一致才用，不联网）；缓存缺失或不符才联网下载，并再次核对整包哈希。

行为约定

情况	行为
目标不存在该文件	新增
内容相同	跳过
AGENTS.md / CONTRIBUTING.md 已存在且不同	追加带 CSDD:BEGIN 标记的区块，保留原内容
.specify/memory/constitution.md 是 spec-kit 默认占位模板	替换（识别 [PROJECT_NAME] 占位）
其它文件已存在且不同	报冲突并跳过，需显式 --force
有冲突且未加 --force	不写入任何文件，退出码 3
装完 bootstrap 失败	退出码 4，不假装成功

不做的事

• 不安装任何第三方扩展（用 /speckit.csdd.extensions，且默认全 skip）。
• 不生成 agent 技能（specify integration install 负责）。
• 不修改 quality-policy.json 的 checks（必须按项目技术栈人工填）。

维护本包

改了治理仓库根下的文件后，必须重新同步 payload，否则安装出去的是旧版本。本包位于治理仓库内的 .specify/packages/csdd 时，默认源仓库是上三级；本包被单独克隆（发布仓库）时，用 --repo 指向治理仓库根：

bash scripts/sync-payload.sh --repo /path/to/governance-repo
bash scripts/verify-package.sh --repo /path/to/governance-repo

第三方扩展的压缩包缓存在 cache/（见下），改了清单里的版本、来源或哈希后重新生成：

python3 scripts/cache_extensions.py

payload.manifest.txt 是唯一发布清单：增删文件改这里，不要手改 payload/。

verify-package.sh --target /repo 用来检查目标仓库是否被本地改过（一致 / 不一致 / 缺失）。

第三方扩展

清单在 extensions.manifest.json。硬规则：source 必须是 https 地址、sha256 必须是 64 位十六进制，缺任一项、整包哈希不符、extension.yml 与审计记录不符，都拒绝安装。装完用 specify extension list 确认真的登记了，否则退出码 4。

bash .specify/packages/csdd/scripts/csdd-extensions.sh --list
bash .specify/packages/csdd/scripts/csdd-extensions.sh --install spec-gates

清单里 7 个 spec-kit 扩展都已固定整包哈希。v-model 上游包超过 512 条目，脚本下载上游包、校验整包哈希后只解压 include 清单内的文件，并核对目录树哈希，属改造安装。整包哈希来自 GitHub 自动生成的标签压缩包，是否长期字节稳定未验证；发布前建议改指向自己仓库 release 里的压缩包。

安装不等于能力验证。

已知限制：

• blueprint-index 的 check 脚本在 bash 5.1 与 3.2 下语法检查失败（Ubuntu 22.04 默认 5.1.16，macOS 默认 3.2），bash 5.2.15 通过；上游 v0.3.0 与 main 相同，尚无修复。使用前请升级 bash。
• Claude 集成下，第三方扩展的技能文档（如 BrownKit 里的 a.md 示例链接）会被 quality_gate.py 的链接扫描当成坏链接，因为它只排除了 .agents/，没有排除 .claude/。Codex 集成不受影响。需要在你自己的门禁里排除 .claude/，并走你们的评审。