setup-context-driven

设置 Context-Driven

使用公开的 roundfix baseline 命令系列。Roundfix 二进制文件是 Baseline Profiles、仓库检查、Decision Plans、Change Plans、确认、应用、恢复和 Baseline 验证的唯一运行时权威。本技能仅提供操作方法和解读说明，不具备独立的设置引擎或行为回退机制。

首次采用或恢复之前，请先阅读持久化操作契约： docs/user-guide/context-driven-development.md#adopt-or-update-the-context-driven-baseline。

边界

Baseline 负责声明的根区块、设置专用指南、首次采用时的根指令备份，以及 docs/agents/setup-context.json。它会保留受管理边界之外由仓库编写的字节。

Baseline 绝不会：

• 安装应用或 Agent 依赖项；
• 连接数据库或运行中的基础设施；
• 运行仓库格式化、构建、测试、lint、迁移或验证命令；
• 跟随不安全链接或修改嵌套指令载体；
• 根据实现证据推断仓库策略；
• 允许 ACP 提案授权修改；
• 组合配置文件，或加载用户范围或远程配置文件。

请将配置文件预期、仓库命令和建议视为不同的事实。配置文件预期是可移植的策略，并非实现证明。只有当结果显示 repositoryExecutable: true 且绑定了本地声明时，仓库命令才可执行。建议是供维护者运行的命令；Baseline 并未执行它。

解读组合后的指南

请按以下顺序阅读生成的根指令层级：通用指令、上下文和文档、Spec 工作流、已启用的自主工作、技术栈指南、范围指南，以及可选知识来源。范围更窄的指南可以为其关注事项增加约束，但不能削弱通用规范条款或已确认的项目决策。

Greenfield 组合仅生成 Baseline Profile 选定的指南和指针。它不会创建通用仓库指南；如果没有仓库专属规范规则，也不会留下残余载体。

如果 Greenfield 保留了需要分类的受管理源内容，Greenfield 会拒绝操作，并指出应选择 preservation.mode=preservation 作为处理方式。

对于更新或重新采用 Baseline，在批准保留台账之前，请先完整解读。每条现有规则都必须在一个有效的语义归属文档、一个已识别的类型化仓库文档或 docs/agents/specific-repository.md 中保留其精确源字节，或者逐条给出有理有据的拒绝理由或非治理分类。残余内容为空时会移除载体和根指针；非空且接受的残余内容只会保留其精确规则。

生成的 docs/agents/docs-layout.md 负责提供可复制的 ADR 和 Findings 契约。ADR 仅在状态为 accepted 时有效；没有生命周期 frontmatter 的旧版 ADR 仍然有效，除非正文将其标记为非活动。Findings 使用 pending、partial、deferred 和 done，以及终止状态 deprecated、superseded、closed 和 cancelled；保留原始观察结果，并以带日期的附录追加后续证据。请复制这些生成的模板；本技能不会渲染或替换它们。

刷新已接管的仓库

如果仓库具有兼容的 Setup Manifest，请使用非交互式托管刷新流程：

roundfix baseline update --repo . --format json

系统会呈现变更后的 Plan，且不会修改仓库内容，无需确认。若要批量扫描，请在同一条命令中批准计算得出的 Plan Digest：

roundfix baseline update --repo . --yes --format json

该命令会根据 Setup Manifest 推导当前的 Baseline Profile 和兼容决策。它不会询问已确定的问题，也不会调用语义分类。它只会修改 Baseline 管理的区域和 Repository Skill Set；管理边界之外的每个字节都保持不变。

对于先前审核过的 Plan Digest，请使用 --confirm-plan <digest>，而非 --yes。如果某项决策未包含在 manifest 中，命令会以 3 退出且不写入任何内容，除非维护者明确选择 --adopt-suggested。仅在需要跳过 Repository Skill Set 刷新时使用 --no-skills；仅当指定的是已声明的离线 Git checkout 或裸对象存储时，使用 --skills-source-dir <path>。

仓库通过 verification.incremental 选择本地快速命令，该配置独立于完整的 verification.gate。仅包含单一 gate 的 Setup Manifest 会以 3 退出，指出缺失的增量决策，并且不写入任何内容。仓库在本地声明建议使用的 make verify-incremental 命令后，请使用 --adopt-suggested 重新运行 update；后续更新将使用已记录的决策，无需再带此标志。

人工采纳或更改配置文件

在交互式终端中运行：

roundfix baseline --repo . --format text

交互式工作流用于首次采纳、更改 Baseline Profile，或处理 Setup Manifest 未包含的决策。它会且仅会选择一个 Baseline Profile，并生成一份整合的 Change Plan，文件变更列在前面。使用兼容的 Setup Manifest 时，它会跳过已确定的决策和语义分类。在完整计划和 Plan Digest 显示之前，请勿授权变更。

决策和保留提示会标出一个可见的默认选项；按 Enter 即可确认。有效的已存储 Setup Manifest 值优先，即使 Profile Digest 已更改、需要再次采纳也是如此。否则，CLI 会使用其内置目录建议，包括用于后端工作的 codex gpt-6.1-sol high 和用于设计工作的 claude opus high。现有根目录指令默认采用 Preservation；指令清单为空时默认采用 Greenfield；如果存在可恢复的现有配置文件，则优先使用。分类、Plan approval 和应用变更仍需明确选择非空选项。

首次采纳时，请维护者选择一种指令模式：

• Greenfield 会备份安全的根目录载体，但不会导入其中的任何规则。
• Preservation 会备份安全的根目录载体，并要求对每个 Source Baseline Entry 审核并指定一项处理方式。

嵌套指令载体保持不变，且只会作为警告显示。不安全的根目录载体会阻止计划生成。如果无法使用或已放弃密封的 ACP 分类，请继续通过公共命令的结构化人工分类审核流程。切勿臆造 Source Baseline 标识、分类或目标位置。

Repository-Specific Normative Rules 只有一个规范载体：docs/agents/specific-repository.md。启用该选项只允许使用此目标位置，不会创建空白框架。Baseline 仅在规则已获批准且非空时，才会创建该文件及其受管理的根目录指针。它会按字节原样迁移 docs/agents/repository.md 或 docs/agents/repository-rules.md，移除已知的空旧框架，并阻止对内容不同的非空旧载体进行处理，要求人工协调。现有的 0.0.1 Decision Documents 若指向任一旧目标位置，会被规范化为规范路径。

对于受管理的刷新，请使用 roundfix baseline update；单独的 Profile Digest 变更不会强制重新访谈，只要配置文件和已存储的决策仍可解析即可。更改配置文件会生成新的完整交互式计划。如果维护者拒绝该计划，请使用命令的决策区域修订流程。每次接受的更正都必须生成新的 Plan Digest，并再次进行完整审核。

指令分类之前会先进行配置文件对齐。对于特定配置文件的阻碍项，交互式命令会提供 更改 Baseline Profile、经审核的 仓库自有 Profile 适配，或 拒绝且不写入。适配会列出每个模块和配置文件特定的能力移除，验证仓库自有 Profile ID，并重新审核内存中的草案；只有对齐就绪后才会继续。Profile 文件属于最终 Change Plan 的一部分，在 Plan Digest 获得批准之前不会写入。

通用必需能力不可移除或豁免。运行结果中指定的确切恢复预览，审核其 Plan Digest，确认同一份当前预览，然后重新运行配置文件对齐：

roundfix baseline skills restore --repo . --profile <built-in-id> --skill <skill-name> --format json
roundfix baseline skills restore --repo . --profile <built-in-id> --skill <skill-name> --confirm-plan <digest> --format json

项目决策与 Spec 约束

CLI 负责收集并呈现项目决策。本技能不会收集、推导、验证或呈现决策；它只解释公开结果，并通过 roundfix baseline 提交所有更正。

verification.incremental 指定快速本地检查；生成的指南会发布该检查。它是独立于 verification.gate 的必填项，后者指完整的仓库验证。

仅更改 HTTP 模式时，所有例外情况和源都会保留。

对于 Standard TypeScript Monorepo Profile，UUID 版本 7 是 identifier.strategy 的可见建议。人类必须明确选择保留该建议，或提供一条非空的仓库定义规则。当 Better Auth 仍为选定项时，auth.provider 会针对 /api/auth/* 提出 GET 和 POST，所有者为 Better Auth，并说明 Session、OAuth 重定向、回调及相关提供方协议的原因。人类必须保留或更改这项完整的类型化建议。/api/auth 是 Better Auth 的默认基础路径，不是 Baseline 规则：若仓库将 Better Auth 挂载在其他位置，则记录可选的 auth.base_path 决策；之后提供方和 HTTP 例外都涵盖该路径及其后的 /*。

自动化通过传递给 --decision-file 的严格 Decision Document 提供这两个结构化值。如果任一值尚未确定，规划将以 3 退出，在 roundfix/baseline-result/v1 中列出所有缺失的决策，不生成部分 Plan，也不写入任何内容。切勿将目录建议、仓库证据、设置批准或空答案视为授权。

每个新的 PRD 和 TechSpec 都必须包含 Project Constraints 表格行，涵盖：

• docs/agents/domain.md 中的标识符策略；
• docs/agents/backend.md 中的身份验证和 HTTP；
• docs/agents/spec-routing.md 中生效的 ADR 义务；以及
• docs/agents/agent-instructions.md 中的工具使用权限。

每一行都必须说明适用或不适用，并给出理由。在 Spec 明确记录维护者授权以及精确的、限定范围的仓库相对文件之前，受保护的工具使用工作仍须保持阻止状态。任务分配和通用实现请求都不构成此类授权。已完成和已归档的旧版 Spec 必须保持字节级不变。

用于首次采用或更改配置文件的非交互式规划

交互式根命令会拒绝重定向或不存在的终端输入。 自动化和 Agent 对已采用的仓库使用 baseline update。首次采用或更改配置文件时，使用：

roundfix baseline plan --repo . --profile <profile-id> --decision-file <decision-file> --format json

自动化可以传入等效的、经审核的严格草案：

roundfix baseline plan --repo . --profile-file <draft.json> --decision-file <decision-file> --format json

--profile-file 和 --profile 不能同时使用。CLI 会根据内嵌目录验证草案，在内存中解析草案，并将其规范仓库路径和精确字节纳入可移植 Plan。不要通过此技能写入、规范化、分类或渲染草案。

标量答案可以使用可重复的 --decision <id=value> 标志。结构化答案使用架构为 setup-context-driven/decisions/0.0.1 的可重复严格决策文档。

根据退出类别解读结果：

• 0：stdout 是一份完整的 roundfix/baseline-plan/v1 文档。
• 2：修复无效输入、架构、Git 状态或不安全的载体。
• 3：按 roundfix/baseline-result/v1 的 nextAction 操作；不存在部分 Plan。

为保留内容，仅使用根据公开的人为分类审核得出的当前严格决策文档。该文档必须恰好绑定当前源基线及每个源基线条目。仓库字节发生变化后，不要重用身份标识或摘要。

至少审核以下内容：

• repository、catalog 以及唯一解析出的 profile；
• 规范化后的 decisions；
• fileChanges 和完整的规范 managedEntries 台账；
• retention、warnings 和拟议的 setupManifest；
• 当 Plan 迁移历史记录时，审核 historyMoves 和 baseline.history.citation 警告；
• 每个精确的 preimage 和 postimage；
• planDigest。

Plan 可能包含仓库策略和精确生成的字节。请将其作为敏感审核工件存储和传输。

应用已批准的 Plan

请维护者批准当前精确的 planDigest。然后运行：

roundfix baseline apply --repo . --plan <plan-file> --confirm-plan <plan-digest> --format json

Apply 会严格解析所提供的 roundfix/baseline-plan/v1 文档，并且只应用其中的后映像。它绝不会重新计算或替换 Plan。

退出时：

• 0：应用和基线验证均已通过，或已验证精确的后映像。
• 1：检查执行、验证、恢复、输出或回滚失败。
• 2：更正无效输入、Plan 架构或不安全的仓库。
• 3：确认、前映像、目录、配置文件或 Git 血缘已不再是最新状态。生成并审核新的 Plan。
• 130：操作已取消。

仅当克隆稳定的 Git 血缘、对象格式、目录身份、配置文件和所有有界前映像均匹配时，可移植 Plan 才能应用于另一个克隆。

基线配置文件

通过公开 CLI 检查和验证配置文件：

roundfix baseline profile show <profile-id> --format json
roundfix baseline profile validate <profile-id> --format text

从一个内置配置文件创建一个仓库自有配置文件：

roundfix baseline profile init --id <repository-profile-id> --from <built-in-id>
roundfix baseline profile validate <repository-profile-id> --format text

仓库自有配置文件仅位于 .roundfix/baseline/profiles/<id>.json 下，只能组合内嵌目录条目 ID，并且必须与仓库一同进行版本控制。它们不能组合多个配置文件、加载用户级目录，也不能声明可执行内容或远程内容。

仓库 Skill Set 恢复

采用操作会报告缺失或发生偏移的外部技能，但绝不会将恢复作为副作用执行。预览明确请求的恢复操作：

roundfix baseline skills restore --repo . --profile <built-in-id> --skill <skill-name> --format json

非空预览会以 3 退出，并提供 Plan Digest，且不会写入任何内容。维护者批准该精确预览后，重新运行：

roundfix baseline skills restore --repo . --profile <built-in-id> --skill <skill-name> --confirm-plan <plan-digest> --format json

仅当 <path> 是已声明的离线 Git 检出目录或裸对象存储，且其中包含精确的不可变源提交时，才使用 --source-dir <path>。切勿用通用技能刷新来替代。

恢复后，再次生成相同的基线 Plan。恢复成功只能证明所选仓库 Skill Set 的字节，不代表仓库编写的策略。

规范资产同步

此操作仅供维护人员使用，绝不是常规采用流程的一部分：

roundfix baseline assets sync --source-dir <canonical-setups> --check --format json

仅当维护人员明确授权刷新由 Go 管理的规范设置快照时，才在不带 --check 的情况下运行。该命令会验证来源溯源信息和生成的目录，然后仅更改规范设置资产。

恢复

• 缺少决策或手动分类：按照 nextAction 操作，完成当前结构化输入，然后重新运行规划。
• 确认不匹配：审核后，从提供的计划中复制完整的当前 Plan Digest。
• 计划已过期：生成并批准替代计划；绝不要编辑或强制执行旧计划。
• 载体不安全：修复报告中指出的确切路径；绝不要通过临时变通方案跟随或替换该路径。
• 事务中断：重新运行相同的公开 apply 命令，以便 Roundfix 锁定并恢复其 Git 私有日志。绝不要删除恢复状态。
• 回滚未完成：停止写入，保留工作区和恢复状态，检查报告中的每个路径，恢复可信字节，然后生成新计划。

完成

仅凭规划不得声称采用或更新已完成。

1. 要求 apply 退出码为 0，并检查 verifiedPostimages。
2. 在 Baseline 之外运行报告中列出的每个格式化工具或 Verification 建议。
3. 在受管 Baseline 输出之外修复任何仓库故障。
4. 使用相同的当前 Profile 输入和决策生成新计划。
5. 要求没有文件更改，或以退出码 0 执行精确的幂等重新应用。

报告剩余警告、尚未运行的建议、已批准的 Plan Digest，以及最终的 Baseline 结果状态。