long-goal

# Long Goal 把一个长期目标放在同一个 `Overall-goal/goal-N/` 中，从原始要求依次推进到规格、设计、任务、实施、验证和最终审查。持续执行到目标完成；不要用多个重复目录模拟审查轮次。 ## 核心约束 - 把 `input.md`、`spec.md`、`design.md`、`tasks.md`、`state.md`、`review.md` 作为唯一事实源，不在其他工作流维护重复计划或进度。 - 不调用 OpenSpec 技能、命令或聊天指令，不创建或更新 `openspec/` 工件。除非用户明确要求，现有 OpenSpec 内容只视为历史资料。 - 在规格、设计和任务门通过前，不修改实现代码。 - 在用户目标和安全边界内自主推进；仅在缺少必要权限、存在不可逆高风险操作或目标实质不明确时停止并说明阻塞。 - 保持改动小而可验证，不扩大范围，不覆盖原稿，不编造结果，不预写成功。 - 永不删除或覆盖已有 `goal-N/`。删除、公开、发送、覆盖或处理凭据仍须遵守上级安全规则。 ## 文件职责 每个目标只建立一个递增的 `goal-N/`： ```text Overall-goal/goal-N/ ├── input.md # 用户原始输入，逐字保存，之后只读 ├── spec.md # 目标、范围、非目标、约束、需求与验收标准 ├── design.md # 现状证据、方案、决策、兼容性、风险、验证与回滚 ├── tasks.md # 唯一任务清单及逐项验证记录 ├── state.md # 当前阶段、当前任务、最近验证、下一步和阻塞 └── review.md # 三轮审查、修复闭环和最终结论 ``` 遵守以下单一真相规则： - `input.md` 只保存原话，不解释。 - `spec.md` 只定义“必须实现什么”，为需求分配唯一 `REQ-NNN`。 - `design.md` 只定义“如何实现以及为何如此”。 - `tasks.md` 是唯一进度源；每项使用 `TASK-NNN [REQ-NNN]`，不得在 `state.md` 复制清单。 - `state.md` 只保存恢复执行所需的游标。 - `review.md` 只保存审查证据和结论，不取代任务状态。 ## 0. 定位项目与目标 1. 读取当前项目的 `AGENTS.md`、必要的子目录规范和已有 `README.md`；README 不存在时不要仅为本流程创建。 2. 检查 `Overall-goal/`： - 用户指定继续某个目标时，读取该目录。 - 用户要求继续且未指定编号时，仅在最新未完成目标与当前请求一致时恢复。 - 新目标创建下一个递增 `goal-N/`，不得复用或覆盖历史编号。 3. 恢复目标时，按 `input → spec → design → tasks → state → review` 顺序完整读取，再检查相关代码、差异和最新验证结果，从 `state.md` 的下一步继续。 4. 恢复旧版三文件目标时，先完成一次性迁移再继续： - 保留原 `input.md` 和 `plan.md`；把 `plan.md` 标记为只读历史，不再作为事实源。 - 从原始输入、旧计划、任务完成状态和仓库证据生成缺少的 `spec.md`、`design.md`、`state.md`、`review.md`。 - 将旧任务改为 `TASK-NNN [REQ-NNN]`，保留已完成标记和真实验证记录；不得把未验证任务迁移为完成。 - 在 `state.md` 记录迁移来源、当前实施位置和下一步。迁移后运行结构校验，不读取或调用 OpenSpec 补全内容。 ## 1. 初始化目标 先创建六个文件，再进行实现： - 在 `input.md` 逐字保存本次原始请求。 - 在 `state.md` 写入：`状态`、`当前阶段`、`当前任务`、`最近完成`、`最近验证`、`下一步`、`更新时间`、`阻塞原因`。 - 将状态设为 `active`，当前阶段设为 `specification`。 - 先填写其余文件的必要结构；未知内容明确标为待查证，不得猜测。 ## 2. 规格门 在 `spec.md` 依次写明： 1. `目标`：用户可观察的最终结果。 2. `范围` 与 `非目标`：允许和禁止改变的边界。 3. `约束`：兼容、安全、性能、数据、UI、迁移等硬条件。 4. `需求`：使用 `REQ-NNN`；每项描述可验证行为，必要时给出 Given/When/Then 场景、异常路径和边界条件。 5. `验收标准`：为每项需求声明检查方式，不以主观“看起来完成”作为证据。 检查目标、范围、场景和验收是否一致；未通过时只修订规格，不进入设计。 ## 3. 设计门 在 `design.md` 依次写明： 1. 现状与可核查证据。 2. 最小可行方案及关键数据流或调用关系。 3. 关键决策、备选方案和选择理由。 4. API、数据、配置、迁移、UI 和历史行为的兼容边界。 5. 风险、控制措施、测试策略和回滚方式。 逐项映射 `REQ-NNN`，避免无需求支撑的抽象、依赖或重构。设计不完整时不得编码。 ## 4. 任务门 在 `tasks.md` 建立有序清单： ```markdown - [ ] TASK-001 [REQ-001] 具体动作；验证：具体命令或可观察结果 ``` - 每个任务必须边界明确、可独立验证，并至少关联一个真实需求。 - 覆盖实现、测试、文档、回归和必要的视觉检查；不要创建纯形式任务。 - 每完成三个实现任务，插入一次范围、回归、安全和测试覆盖检查。 - 确保每个 `REQ-NNN` 至少被一个任务覆盖，然后运行 `scripts/validate_goal.py <goal-dir>`。 - 校验通过后，把 `state.md` 当前阶段改为 `implementation`，指向第一个未完成任务。 ## 5. 实施循环 每次只推进一个任务： 1. 重读该任务关联的需求、设计边界和目标文件。 2. 检查调用点、测试和兼容影响，实施最小改动。 3. 运行与风险相称的定向验证；失败时修复并重跑。 4. 只有验证证据成立后才勾选任务，并在 `tasks.md` 的“验证记录”写入命令、结果和关键证据。 5. 更新 `state.md` 的最近完成、最近验证和下一步，不复制任务列表。 实施中发现变化时，先更新对应事实源再继续：需求变化改 `spec.md`，方案变化改 `design.md`，新增工作改 `tasks.md`。不得让代码领先于规格，也不得用文档追认未经审查的范围扩张。 上下文压缩或执行中断后，重新执行第 0 节的恢复顺序；不要从头重复已验证工作。 ## 6. 集成验证 所有实现任务完成后： 1. 运行定向测试、相关全量测试、静态检查和构建。 2. 按项目规范完成安全、迁移、API、数据、UI、可访问性、响应式和回滚检查；只执行与本次变更相关的项目。 3. 逐项核对 `REQ-NNN → TASK-NNN → 验证证据`，确认无遗漏、无越界、无虚假完成。 4. 运行 `scripts/validate_goal.py <goal-dir>`，把真实结果写入 `tasks.md` 和 `state.md`。 验证失败时，将相关任务恢复为未完成并回到实施循环，不进入最终审查。 ## 7. 三轮审查 在同一个 `review.md` 中顺序完成三轮，不新建重复目标目录： 1. **需求与范围审查**：检查所有用户要求、非目标、边界场景和变更文件；修复遗漏或越界。 2. **工程与回归审查**：调用 `$grill-ai-review`，检查调用点、重复逻辑、复杂度、安全、测试强度、构建和回滚；修复真实问题并重验。 3. **用户结果审查**：从用户可观察结果复验完整流程，检查文档、错误路径、视觉与交互（适用时）以及剩余风险。 每轮记录 `状态：pass|fail`、问题、修复和验证证据。任一轮失败都回到相应事实源和实施循环；修复后重新完成受影响审查，禁止跳轮或预写 `pass`。 ## 8. 完成与持久化 所有实现和审查通过后，先填写最终状态，再执行完成门： - 所有任务已勾选，所有需求均有通过的验证证据。 - 三轮审查均为 `pass`，不存在未说明的阻塞或高风险残项。 - `state.md` 已写明最终验证、剩余风险和下一步，将状态改为 `complete`、当前阶段改为 `completed`。 - `review.md` 写入最终结论。 - `scripts/validate_goal.py <goal-dir> --final` 通过。 最终校验失败时，把状态恢复为 `active` 并回到对应阶段。校验通过后进入 README 记录，不得提前汇报完成。 ## 9. README 记录与结束 目标产生实现、修复或持久行为变化时，完成前必须规范更新项目根 `README.md`： 1. 只在唯一的 `# goal修复` 章节记录目标摘要；没有该章节时，在 README 末尾创建一次，不要散落到其他章节。 2. 按日期从旧到新排列；同一天按 `goal-N` 数字升序。新记录追加在该章节末尾；发现旧记录乱序时，仅移动完整记录块，不改写其内容。 3. 每个目标使用固定结构，内容必须来自已通过的任务和验证证据： ```markdown ## YYYY-MM-DD · goal-N · 简短标题 - 目标：一句话说明用户结果 - 关键变更：列出必要文件或行为，不粘贴大段代码和过程日志 - 验证：列出真实执行的关键命令及结果 - 残余风险：如实填写；没有则写“无已知残余风险” ``` 4. 不重复 `tasks.md`、`state.md` 或 `review.md` 的细节；仅当项目长期事实、入口或操作方式变化时，才对 README 其他对应章节做最小同步。 5. README 不存在但目标产生了上述项目变化时，创建最小 README 和 `# goal修复`；纯分析、只读调查或无项目事实变化时不编造记录，在 `review.md` 注明“不适用”及理由。 6. 写入后复核标题唯一、日期与 goal 顺序、内容真实性和无关章节未被污染；失败时把状态恢复为 `active` 并修复。 README 复核通过后进入安全清理，不得提前汇报完成。 ## 10. 安全清理与结束 1. 只清理本轮明确创建、可安全再生成且不属于交付物的临时测试脚本、测试夹具、缓存、临时截图和中间产物；正式回归测试、源代码、配置、数据、用户文件及 `goal-N/` 永久记录不得清理。 2. 删除前列出并核对准确的绝对路径，确认目标位于当前项目或本轮专用临时目录；禁止使用宽泛目录、未解析变量、危险通配符或跨范围递归删除。预存文件、用途不明文件或重大产物必须保留，除非用户明确授权删除。 3. 优先使用可恢复方式；遵守上级删除与审批规则。没有可清理内容时如实记录“无”，不要为了完成步骤而删除文件。 4. 在 `review.md` 记录实际清理清单，并在 `state.md` 记录清理后的验证结果。清理后检查交付物、工作区状态和关键入口，再运行 `scripts/validate_goal.py <goal-dir> --final`；失败时恢复为 `active` 并修复。 清理和复核通过后，保留完整 `goal-N/` 作为历史记录。最终向用户简明报告结果、关键变更、验证、清理内容、剩余风险和恢复位置；不要宣称未执行的检查成功。