Codespec

Codespec 是一个面向实际项目开发的轻量阶段框架。默认 core 路径只解决四件事：

• 防需求漂移：用户意图必须落到 spec.md，并能追溯到来源或确认决策。
• 防范围蔓延：没有 REQ/ACC/DEC 支撑的设计、实现和测试不得进入变更。
• 防范围缩小：已有 REQ/ACC/VO 必须被设计、实现切片和验证证据覆盖。
• 防伪完成：只能按真实证据说明完成深度、未完成项和剩余风险。

阶段划分保持为 Requirement / Design / Implementation / Testing / Deployment。

核心链路

默认权威链路是：

source -> spec.md -> REQ/ACC/VO -> design_response/slice -> TC/RUN -> deployment evidence

关键规则：

• spec.md 是需求权威源，必须自足，不依赖长对话记忆。
• design.md 必须逐条回应 REQ/ACC/VO，不能只引用 ID。
• 每个 implementation slice 必须是垂直可验证行为，并写明 scope_guard。
• Requirement 阶段只要求 VO-* 验证义务；TC-* 测试计划在 Design -> Implementation 前补齐。
• Implementation / Testing / Deployment 阶段发现上游权威口径缺口时，先停下，经用户确认后 codespec reopen Requirement|Design --reason "<原因>"。

默认不使用的旧机制

core 路径不再默认使用：

• reviews/*.yaml gate evidence ledger
• markdown contracts/*.md freeze 流程
• authority-repairs/*.yaml
• semantic-handoff 强制账本

普通项目的接口与数据约束写在 design.md §5 或按需 design-appendices/*.md。真正跨服务、公开 API、SDK、事件协议或 DB migration 使用工程契约，例如 OpenAPI、protobuf、JSON Schema 或 migration 文件。

安装

在 workspace 根目录安装 runtime：

/root/codespec/scripts/install-workspace.sh /path/to/workspace

在项目仓库中初始化 dossier：

cd /path/to/workspace/project
../.codespec/scripts/init-dossier.sh

初始化会创建：

spec.md
design.md
testing.md
meta.yaml
AGENTS.md
CLAUDE.md
AI_INSTRUCTIONS.md
spec-appendices/
design-appendices/
scripts/

不会创建 reviews/、contracts/ 或 authority-repairs/。

常用命令

codespec readset
codespec gate-sequence start-design
codespec preflight start-design
codespec start-design
codespec start-implementation
codespec start-testing
codespec start-deployment
codespec deploy
codespec complete-change <version>
codespec reopen Design --reason "<reason>"
codespec reopen Requirement --reason "<reason>"
codespec doctor-boundaries

preflight 只运行 gate，不改变阶段。start-* 会运行 gate 并推进阶段。 doctor-boundaries 会把当前工作树按提交事实边界分类，帮助拆分 legacy cleanup、权威基线、阶段 metadata、实现和验证证据。

阶段推进标准

Requirement -> Design：

• spec.md 包含自足的意图、边界、来源、REQ/ACC/VO。
• 每个 REQ 有 ACC，每个 ACC 有 VO。
• ACC 可观察、可判定。
• out_of_scope 和 reopen triggers 能阻止未授权扩展。

Design -> Implementation：

• 每个 REQ/ACC/VO 有实质 design_response。
• testing.md 已补齐 TC-*。
• TC-* 已声明必要 evidence facets；进入 Implementation 后测试计划区冻结。
• 每个 slice 绑定 REQ/ACC/VO/TC，并包含 scope_guard。
• design.md §4 明确可修改和不可修改路径。

Implementation -> Testing：

• 实现改动都在 design.md §4 授权范围内。
• 每个核心改动能反向追溯到 slice 和需求。
• 相关 TC-* 至少有 branch-local RUN-* result: pass，或明确属于后续阶段验证。
• 不在 Implementation 中改写 TC-* 覆盖口径；发现缺口要 reopen Design。
• 未完成项和剩余风险显性说明。

Testing -> Deployment：

• 必测 TC-* 有 latest pass。
• latest pass RUN 满足 TC 的 required evidence facets。
• RUN-* 证据和本地 artifact 可复核。
• reopen_required: true 不允许继续推进。
• full-integration 不能替代 real provider、持久化或运行时边界证据。
• scripts/codespec-deploy 不能仍是初始化失败模板；它触达的 repo 面必须已在 design.md §4 授权，否则先 reopen Design，不在 Deployment 阶段临时扩 scope。

Deployment -> Completed：

• deployment.md 记录发布对象、环境、运行验证、回滚、监控和人工验收。
• 用户明确确认人工验收通过。
• 运行版本证明加载了本次部署。

Hooks

默认 hook 只保留低摩擦核心防护：

• pre-commit：metadata、phase capability、scope。
• pre-push：metadata、phase、scope、verification 等发布前基础检查。

pre-push 在 Implementation 及之后只对当前阶段区间运行 phase/scope 检查，避免一次性 push 多阶段提交时把早期 authority baseline 误判为后期修改。

完整阶段 gate 由 codespec preflight 或 codespec start-* 执行。 pre-commit 还会执行 commit-boundary，一个 commit 只能承载一个可独立审查的事实边界。 Design -> Implementation 前必须先提交干净的 Design baseline；start-implementation 不会在 dirty authority 工作树上写入实现基线。

迁移原则

从旧项目迁移时：

• 不把旧 reviews/、contracts/、authority-repairs/ 放回默认 readset。
• 有价值的 contract 内容改成 design-appendices/*.md 或真实工程契约。
• 保留业务语义：REQ/ACC/VO、out_of_scope、design_response、slice、TC/RUN。
• 后期权威口径变化一律走 reopen，不走补账式修复态。

验证框架

scripts/lint.sh
scripts/smoke.sh
scripts/audit-regressions.sh

lint.sh 是基础语法检查。smoke.sh 验证 core 默认路径。audit-regressions.sh 仅用于旧审计能力回归，不能影响 core 默认流程。