diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3fa07d7..65f6c86 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Thinloop skills and continuity hooks for Issue-backed discovery, read-only project-status navigation, multi-Issue project DAG decomposition and execution, evidence-backed reengineering and delivery, and approved skill evolution.", - "version": "0.18.2" + "version": "0.19.0" }, "plugins": [ { "name": "thinloop", "source": ".", "description": "Discovery, Web UIUX, architecture, Next project-status navigation, Project DAG decomposition, Execute READY-wave orchestration, Reengineering gates, QuickDev delivery, maintenance, knowledge, and evolution skills with continuity checks; Project itself remains non-executing.", - "version": "0.18.2" + "version": "0.19.0" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 53b226e..a747bbe 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "thinloop", - "version": "0.18.2", + "version": "0.19.0", "description": "Simplify complex development with Issue-backed discovery, risk-adaptive Web experience and architecture design, non-executing multi-Issue project decomposition into dependency DAGs, bounded READY-wave execution, read-only project-status navigation, project-scale refactoring and cross-stack reimplementation, autonomous single-Issue PR delivery, evidence-backed maintenance, concise experiential knowledge, and human-approved skill evolution.", "author": { "name": "mindcarver" diff --git a/.codebuddy-plugin/marketplace.json b/.codebuddy-plugin/marketplace.json index 3fa07d7..65f6c86 100644 --- a/.codebuddy-plugin/marketplace.json +++ b/.codebuddy-plugin/marketplace.json @@ -5,14 +5,14 @@ }, "metadata": { "description": "Thinloop skills and continuity hooks for Issue-backed discovery, read-only project-status navigation, multi-Issue project DAG decomposition and execution, evidence-backed reengineering and delivery, and approved skill evolution.", - "version": "0.18.2" + "version": "0.19.0" }, "plugins": [ { "name": "thinloop", "source": ".", "description": "Discovery, Web UIUX, architecture, Next project-status navigation, Project DAG decomposition, Execute READY-wave orchestration, Reengineering gates, QuickDev delivery, maintenance, knowledge, and evolution skills with continuity checks; Project itself remains non-executing.", - "version": "0.18.2" + "version": "0.19.0" } ] } diff --git a/.codebuddy-plugin/plugin.json b/.codebuddy-plugin/plugin.json index 82f8dbf..7570205 100644 --- a/.codebuddy-plugin/plugin.json +++ b/.codebuddy-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "thinloop", - "version": "0.18.2", + "version": "0.19.0", "description": "Simplify complex development with Issue-backed discovery, risk-adaptive Web experience and architecture design, non-executing multi-Issue project decomposition into dependency DAGs, bounded READY-wave execution, read-only project-status navigation, project-scale refactoring and cross-stack reimplementation, autonomous single-Issue PR delivery, evidence-backed maintenance, concise experiential knowledge, and human-approved skill evolution.", "author": { "name": "mindcarver" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index a8d79b7..0487593 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "thinloop", - "version": "0.18.2", + "version": "0.19.0", "description": "Simplify complex development with Issue-backed discovery, risk-adaptive Web experience and architecture design, non-executing multi-Issue project decomposition into dependency DAGs, bounded READY-wave execution, read-only project-status navigation, project-scale refactoring and cross-stack reimplementation, autonomous single-Issue PR delivery, evidence-backed maintenance, concise experiential knowledge, and human-approved skill evolution.", "author": { "name": "mindcarver" @@ -46,6 +46,6 @@ "Interactive", "Write" ], - "defaultPrompt": "Thinloop routing source: config/routing-kernel.json. Use SCD Next for progress, unfinished work, blockers, or what to do next; read live project evidence and recommend the single next action without changing state. Use SCD QuickDev for one clear Issue-backed delivery; merge only after direct evidence and independent acceptance, and stop for explicit approval before high-risk actions. Use SCD Discovery when product outcomes remain open, especially for a new product or interdependent product decisions. Use SCD Project when an approved outcome needs multiple independently verifiable deliveries; create and validate the Initiative, Delivery Issues, and dependency DAG, but it does not run an implementation loop. Use SCD Execute to start, continue, resume, or finish an approved Initiative by selecting the current safe READY wave and launching one isolated QuickDev lane per Issue. Use SCD Reengineering for project-scale refactoring or cross-language, framework, architecture, storage, or runtime replacement; fix source, compatibility, parity, and cutover gates before consuming the approved DAG through a safe READY wave. Add design only when the complexity is real: use SCD UIUX for consequential Web experiences, SCD UI Polish for visual refinement of existing Web pages, and SCD Architecture for domain, system, or shared-interface boundaries. Use SCD Maintenance, SCD Knowledge, SCD Evolve, or SCD Interview only when explicitly requested; ordinary development must not trigger them automatically." + "defaultPrompt": "Thinloop routing source: config/routing-kernel.json. Use SCD Next for progress, unfinished work, blockers, or what to do next; read live project evidence and recommend the single next action without changing state. Use SCD QuickDev for one clear Issue-backed delivery; merge only after direct evidence and independent acceptance, and stop for explicit approval before high-risk actions. Confirm concrete technical choices and the exact Git plan, then obtain implementation authorization before execution; unanswered choices remain pending. Use SCD Discovery when product outcomes remain open, especially for a new product or interdependent product decisions. Use SCD Project when an approved outcome needs multiple independently verifiable deliveries; create and validate the Initiative, Delivery Issues, and dependency DAG, but it does not run an implementation loop. Use SCD Execute to start, continue, resume, or finish an approved Initiative by selecting the current safe READY wave and launching one isolated QuickDev lane per Issue. Use SCD Reengineering for project-scale refactoring or cross-language, framework, architecture, storage, or runtime replacement; fix source, compatibility, parity, and cutover gates before consuming the approved DAG through a safe READY wave. Add design only when the complexity is real: use SCD UIUX for consequential Web experiences, SCD UI Polish for visual refinement of existing Web pages, and SCD Architecture for domain, system, or shared-interface boundaries. Use SCD Maintenance, SCD Knowledge, SCD Evolve, or SCD Interview only when explicitly requested; ordinary development must not trigger them automatically." } } diff --git a/.gitignore b/.gitignore index 7ca352e..df15b92 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,8 @@ work/ .DS_Store .reasonix/ + +# Thinloop临时恢复、缓存和日志；长期计划仍纳入Git +.scd/tasks/current.md +.scd/cache/ +.scd/logs/ diff --git a/.scd/plans/20261108-131215-guided-confirmation/architecture.md b/.scd/plans/20261108-131215-guided-confirmation/architecture.md new file mode 100644 index 0000000..c4910e0 --- /dev/null +++ b/.scd/plans/20261108-131215-guided-confirmation/architecture.md @@ -0,0 +1,96 @@ +--- +status: approved +version: 1 +created_at: 2026-11-08T13:22:52+08:00 +updated_at: 2026-11-08T14:04:38+08:00 +recorded_timezone: Asia/Shanghai +plan_approved_at: null +implementation_authorized_at: null +approval_recorded_at: 2026-11-08T14:02:36+08:00 +implementation_authorization_recorded_at: 2026-11-08T14:02:36+08:00 +approved_git_ref: 4346eceda744b707d09c879b7e623b58adbc7038 +--- + +# 架构计划：确认、计划与执行的职责 + +## 审阅状态 + +Q1–Q12及以下D1–D8已由AP-001明确批准，批准对象为Git 4346eceda744b707d09c879b7e623b58adbc7038中的方案。开工已授权；本段只同步批准状态，不修改方案。 + +## D1：一个共享指令契约 + +新增 skills/scd-quickdev/references/planning-contract.md，集中维护访谈、计划文件、时间、批准关联、执行前清单和变更处理。复用现有十三技能，不新增技能、配置模式、运行时脚本、数据库、依赖或Hook。 + +Discovery、QuickDev、Architecture、UIUX、Project、Execute、Reengineering、UI Polish和Maintenance修复模式直接引用共享契约。Next只读检查计划与批准状态，不创建计划、不批准工作。Knowledge、Interview和Evolve保留各自显式调用及更窄写入边界；Evolve交给QuickDev的开发工作也遵守计划确认，且保留其禁止自行交付的试验边界。 + +统一按任务行为适用：功能开发、缺陷修复、架构/交互设计、再工程及实际修复需经过确认；纯状态查询、代码阅读和只读诊断不因调用技能而创建计划。 + +## D2：询问与执行边界 + +1. 先只读调查，查明事实，再针对当前未决选择分轮提问。 +2. 提问写出选择、具体影响、推荐及理由；每轮问题互不依赖。 +3. 产品、架构、依赖、数据模型、接口、模块组织、测试策略等具体技术选择都需确认；不能以可逆、惯例或模型自信为由代选。 +4. 漏答保持待定，不用临时假设解除依赖；可以继续独立的只读调查，不能实施依赖该答案的部分。 +5. 计划已明确的操作是获批执行，不重复询问。开发中出现未覆盖选择时，列出差异和影响，暂停受影响工作并询问。 +6. 普通「继续」只延续已批准范围，不能批准尚未展示的方案、计划修订或新的执行范围。 +7. 方案批准与开工授权分别记录；同一句明确指向当前版本的「确认本方案并开始实施」可以同时授予两者。 +8. 完整计划的统一确认可以覆盖其中逐项展示的具体选择，不要求再逐行重复回答；部分回答只批准被明确选择的部分。 + +## D3：文件与权威分工 + +每项任务使用 .scd/plans/YYYYMMDD-HHMMSS-<任务名>/，时间来自创建时实际北京时间；同秒重名时追加短序号，不伪造创建时间。 + +- plan.md：任务索引、所需文档及版本、状态、基线来源、批准和执行授权关联。 +- requirements.md：本次需求、范围、验收定义、待决问题及来源；存在PRD时引用精确版本与需求标识。 +- architecture.md：涉及架构时保存备选方案、技术选择、影响与兼容性，不复制系统基线。 +- ux.md：涉及需要设计的界面/旅程时保存本次设计增量及视觉产物引用，不复制既有UX基线。 +- implementation.md：进入开发前保存具体文件/模块、任务顺序、依赖、验证、交付与风险。 +- decisions.md：追加决策、批准、开工、变更和完成事件及来源；不保存整段聊天或无关私密材料。 + +设计任务没有开工授权时，可以完成已授权的计划草稿；不生成不存在需求的空架构/UX/实施文档。实际开发必须有实施计划。 + +计划负责本次需求及方案的批准版本；Issue负责执行状态、任务处置、验收证据和交付记录，引用计划文件与Git版本，不独立修改设计。现有PRD负责产品基线，系统架构负责当前系统边界，机器契约负责规范接口；计划记录本次增量。出现冲突先解决并确认，不自行选择一边。 + +## D4：文档状态与Git批准记录 + +计划文档使用draft、approved、superseded三种状态及整数version。ready仍只表示工程/语义就绪，不替代用户批准。执行状态继续在Issue记录，不另建执行数据库。 + +待审阅内容先提交到本地计划分支，展示文件、版本和完整Git SHA。用户批准后，在后续提交追加批准事件，引用此前已存在的提交和精确文件清单，不要求批准记录所在提交引用自身。 + +批准事件包含：事件ID、类型、适用文件/文档版本、目标Git SHA、用户实际确认依据、发生时间（可核实时）和记录时间。明确开工授权还记录本次任务或Issue范围。没有消息ID时记录简短原文及对话上下文说明，不编造稳定消息链接。 + +开工前由Agent逐项核对：所需文档齐全、无影响实施的未决选择、当前方案内容对应获批版本、存在明确开工授权、Issue引用一致、适用设计和接口已就绪。追加批准/状态等管理记录不自动改变已批准方案；新增方案内容或无法解释的差异则需重审。Git提交和字段只能证明记录与版本，不能单独证明用户真实批准。 + +方案变化时：保留旧批准事件，受影响文档递增version并回到draft，展示差异、重新确认后再继续；未变化的决策可以引用复用。提交普通实施代码不会自动使计划批准失效。 + +## D5：时间与历史 + +所有新记录使用Asia/Shanghai、精确到秒、ISO-8601的+08:00。文件包含created_at、updated_at、version、status；索引包含批准和开工记录的引用。 + +事件区分occurred_at与recorded_at。Agent执行的创建、开工、完成等事件读取实际时钟记录；用户消息有可靠原始时间时记录该时间，没有时occurred_at为空并说明原因，recorded_at记录实际收到并落盘确认的时间。不得回填假时间、提前写完成时间或把提交时间等同用户确认时间。 + +每轮已经确认的决定保存并提交到本地计划分支；未回答的问题仍为待定。Git历史保留草稿和确认版本，不生成versions/vN复制目录。 + +## D6：Git保存边界与恢复 + +长期计划、需求、架构、UX、决策和证据摘要纳入Git。计划中明确使用的临时位置为：.scd/tasks/current.md、.scd/cache/、.scd/logs/；仅对这些位置增加窄范围忽略规则，不忽略整个.scd，也不排除长期演进历史。 + +已有受跟踪文件不会因新增忽略规则自动取消跟踪；不执行批量删除或批量git rm --cached。消费者仓库存在更宽忽略规则或不明临时位置时，先检查并展示必要调整，取得确认后处理。 + +current.md只用于恢复，引用持久计划和Issue；修改其生命周期说明中「不得增加忽略规则」的旧要求，但不改变连续性Hook实现、事件或模板必需字段。清理临时状态前必须把有价值的决策和证据写回持久记录。 + +恢复旧任务时保留现有基线/Issue/提交证据；缺少计划或批准关联时，整理当前真实方案供用户确认后才恢复受影响开发，不补造历史批准，不批量迁移旧文档。 + +## D7：仅指令检查的能力边界 + +不新增计划校验器、Schema运行时验证、强制拦截或宿主Hook。开工前检查与合并前审计是技能指令和清单；独立验收复核实际确认依据与版本。 + +现有回归测试用于检测技能文本契约退化和跨入口矛盾，独立场景验收观察模型是否遵守。两者均不能保证所有宿主/模型每次遵从，也不构成新的运行时权限控制。 + +## D8：交付与兼容 + +按一个完整、可独立验收的中文Delivery Issue交付本次规则改造，避免分批发布相互矛盾的默认规则。当前计划分支在获批后可作为该Issue交付分支继续使用，保留草稿历史。 + +候选版本为0.19.0，统一各插件清单、README和安装说明。更新routing-kernel源后通过现有同步脚本生成AGENTS、README、workflow文档和Codex提示词中的路由片段。 + +现有生产/高风险门、独立验收、真实页面验收和各治理技能的更窄权限继续适用。普通交付完成后按仓库约定同步已安装客户端，保留MANUAL/UNVERIFIED事实和实际用户验收边界。 diff --git a/.scd/plans/20261108-131215-guided-confirmation/decisions.md b/.scd/plans/20261108-131215-guided-confirmation/decisions.md new file mode 100644 index 0000000..f19e549 --- /dev/null +++ b/.scd/plans/20261108-131215-guided-confirmation/decisions.md @@ -0,0 +1,57 @@ +--- +status: approved +created_at: 2026-11-08T13:16:03+08:00 +updated_at: 2026-11-08T14:10:38+08:00 +recorded_timezone: Asia/Shanghai +plan_approved_at: null +implementation_authorized_at: null +approval_recorded_at: 2026-11-08T14:02:36+08:00 +implementation_authorization_recorded_at: 2026-11-08T14:02:36+08:00 +approved_git_ref: 4346eceda744b707d09c879b7e623b58adbc7038 +--- + +# 用户决策与记录 + +下表为逐轮决策记录；完整架构和开发计划已由后续AP-001批准并授权开工，具体依据见该事件。 + +| 决策 | 用户选择 | 已确认含义 | 记录时间 | +|---|---|---|---| +| Q1 | B | 具体技术选择也逐项询问，确认后才推进；不以 Agent 的推荐代替用户决定。 | 2026-11-08T13:12:15+08:00 | +| Q2 | A | 每项任务保留草稿、确认版本、决策摘要和变更记录，并关联 Issue/PR。 | 2026-11-08T13:12:15+08:00 | +| Q3 | A | 明确批准开工后，按批准计划连续开发、验证、独立验收和普通合并；新决策或实质变化重新询问。 | 2026-11-08T13:12:15+08:00 | +| Q4 | A | 成为 Thinloop 全项目默认行为，而非个人可选模式。 | 2026-11-08T13:12:15+08:00 | +| Q5 | B，补充 .scd 要放到 git 管理里去 | 使用 .scd/plans/<创建时间>-<任务名>/，计划材料纳入 Git 管理。 | 2026-11-08T13:12:15+08:00 | +| Q6 | A | 计划文件负责设计、实施方案和批准版本；Issue 跟踪执行与验收并引用对应计划。 | 2026-11-08T13:12:15+08:00 | +| Q7 | B | 长期计划、架构、需求、决策和历史版本进入 Git；临时恢复文件、缓存和运行日志排除，明确列出例外，不忽略整个 .scd。 | 2026-11-08T13:16:03+08:00 | +| Q8 | B | 按任务需要分别保存需求、架构计划、开发计划和决策记录，用索引关联；不创建不适用的空文档。 | 2026-11-08T13:16:03+08:00 | +| Q9 | A | 北京时间精确到秒，包含 +08:00；分别记录创建、修订、决策确认、计划批准、开工和完成，关联版本；未知历史事件时间不以补录时间冒充。 | 2026-11-08T13:16:03+08:00 | +| Q10 | B | 只更新技能规则与检查清单，不增加运行时校验代码或新增宿主Hook。 | 2026-11-08T13:22:52+08:00 | +| Q11 | A | 批准记录关联具体计划文件及其Git提交，通过Git历史还原确认版本，不额外复制版本目录。 | 2026-11-08T13:22:52+08:00 | +| Q12 | A | 保留现有PRD、系统架构和接口契约位置；任务计划引用对应版本、说明本次增量，实施验收后更新系统基线。 | 2026-11-08T13:22:52+08:00 | + +确认依据：当前对话用户原文「1B 2A 3A」和「4A 5B ，但是.scd 要放到git 管理里去 6A」。新增确认依据：当前对话用户原文「7B 8B 9A」。上表时间为各轮落盘记录时间；原消息未提供精确到秒的发生时间，不能把记录时间冒充历史确认时间。 + + +- 2026-11-08T13:22:52+08:00：新增用户原文「10B 11A 12A」对应的Q10–Q12确认记录；完整架构与开发方案尚待批准。 + +## AP-001：完整方案批准及开工授权 + +- 用户依据：在展示完整方案并询问是否批准并开工后，用户回复「批准 让 6.1 sol 模型子智能体去实施」。 +- 目标Git提交：4346eceda744b707d09c879b7e623b58adbc7038。 +- 批准文件：plan.md、requirements.md、architecture.md、implementation.md、decisions.md（以上目标提交中的版本）。 +- 批准范围：架构D1–D8、开发T1–T5及A1–A6验收；按方案完成普通交付。 +- 实施模型：用户明确指定GPT-6.1 Sol子智能体。 +- occurred_at：未知（原用户消息未暴露精确到秒时间）。 +- recorded_at：2026-11-08T14:02:36+08:00。元数据中的事件发生时间为空不代表未批准，以本条实际用户依据及记录时间为准。 +- 本记录是追加的批准事实，不改变此前已批准的方案内容；原草稿状态和审阅措辞可通过目标Git提交还原。 + +## EX-001：指定模型提交实施候选 + +- 类型：implementation-submitted。 +- 实施者：/root/implement_116_sol；模型：gpt-6.1-sol（用户指定）。 +- 目标Git SHA：bfc23e61a32b68d677a1f5fcee8b9e1ecd4a0381。 +- occurred_at：2026-11-08T14:09:53+08:00（Git提交时间，只表示提交事件，不代表用户批准或整项交付完成）。 +- recorded_at：2026-11-08T14:10:38+08:00。 +- 关联：AP-001、Issue #116。 +- 状态：T1–T3实施候选已提交；T4工程结果由实施者报告，最终独立验收与远端CI待完成；T5由父Agent继续。 +- 证据日志：/tmp/thinloop116-tests-final2.log、/tmp/thinloop116-gates.log、/tmp/thinloop116-last-targeted.log；持久交付证据记录到Issue/PR。 diff --git a/.scd/plans/20261108-131215-guided-confirmation/implementation.md b/.scd/plans/20261108-131215-guided-confirmation/implementation.md new file mode 100644 index 0000000..9288e7b --- /dev/null +++ b/.scd/plans/20261108-131215-guided-confirmation/implementation.md @@ -0,0 +1,94 @@ +--- +status: approved +version: 1 +created_at: 2026-11-08T13:22:52+08:00 +updated_at: 2026-11-08T14:10:38+08:00 +recorded_timezone: Asia/Shanghai +plan_approved_at: null +implementation_authorized_at: null +approval_recorded_at: 2026-11-08T14:02:36+08:00 +implementation_authorization_recorded_at: 2026-11-08T14:02:36+08:00 +approved_git_ref: 4346eceda744b707d09c879b7e623b58adbc7038 +--- + +# 开发计划：落实逐项确认与可追溯计划 + +## 实施前提 + +用户已通过AP-001批准Git 4346eceda744b707d09c879b7e623b58adbc7038中的requirements.md、architecture.md及本实施方案，并明确授权GPT-6.1 Sol子智能体开工。执行及验收实时状态见Issue #116，实施提交事件见decisions.md的EX-001。 + +## 任务与文件范围 + +### T1：共享规则与文档模板 + +新增 skills/scd-quickdev/references/planning-contract.md，按architecture.md的D1–D7编写规则和开工/合并前清单。 + +在 skills/scd-quickdev/assets/planning/ 下新增 plan.md、requirements.md、architecture.md、ux.md、implementation.md、decisions.md 六份按需使用的模板。模板使用中文、明确占位符、状态/版本/时间和来源；不会要求每项任务生成全部文件。 + +更新 skills/scd-discovery/assets/product-prd.md、skills/scd-architecture/assets/architecture-contract.md、feature-design.md、domain-contract.md，以及skills/scd-uiux/assets/ux-contract.md，补齐适用时间/版本/批准引用，保留原领域字段与位置。 + +### T2：修改确认和交接规则 + +- Discovery：先问再决定，保存草稿和逐轮决策，删除默认直通/未答以假设解除依赖/禁止永久计划的冲突要求。 +- QuickDev：默认先审阅方案和实施计划；改写issue-delivery-contract、scope-contract、extended-issue、continuity-contract、release-contract及主技能中免确认、Issue独占方案、永久计划禁令等冲突。 +- Architecture/UIUX：具体技术或体验选择要确认；工程ready与用户批准分开；更新主技能、职责契约、就绪审查和资产引用。 +- Project：计划负责已批准方案，Initiative/Delivery Issue负责执行拓扑与验收追踪；更新主技能及project-contract，保留不执行实现的边界。 +- Execute/Reengineering：开通道前读取精确计划与授权范围；不能把普通「继续」扩成未批准任务；更新主技能与execution/reengineering相关交接契约，不修改现有DAG/receipt验证脚本。 +- UI Polish/Maintenance：修改直接优化/自主修复规则，实施经已批准计划进入QuickDev；只读审计不创建开发计划。 +- Next：只读展示计划、当前批准版本、待确认项与可执行范围；更新status-contract，不替用户批准。 +- Evolve：仅在其原有明确批准和脱敏边界内衔接计划，保留试验禁止自行发布等更窄权限。 +- Knowledge/Interview：检查引用有无冲突；不改写它们的私人存储和专用确认流程。 + +主技能的agents/openai.yaml中与旧默认流程冲突的提示一并调整。参考契约仅修改直接受本次默认行为影响的部分。 + +### T3：Git边界、路由与说明 + +修改.gitignore，仅加入architecture.md D6确定的三个临时位置。更新对应连续性文档，不修改Hook源码或运行时配置。 + +修改config/routing-kernel.json中相关路由表述并执行node scripts/sync-routing-kernel.mjs；同步README、docs/workflow-and-state.md、docs/installation.md及AGENTS非生成区中的交付前提，明确先批准计划再自主交付。 + +按D8将全部既有版本载体更新为0.19.0，新增docs/releases/v0.19.0.md。历史版本说明保持历史事实；本次不重写已有.scd/specs基线或迁移外部消费者文档。 + +### T4：工程验证与独立场景验收 + +修订与新规则冲突的现有测试：重点为quickdev-contract、discovery-contract、architecture-contract、uiux-contract、project-contract、execute-contract、reengineering-contract、next-contract、maintenance-contract、evolve-contract、chinese-skill-payload、routing-kernel和相关交付/文档测试。仅按实际冲突修改断言与定义；新增必要的指令契约回归，不新增运行时校验代码。 + +执行现有CI命令：node --test tests/*.test.mjs；版本一致性；路由--check；既有评测定义验证与dry-run；delivery protocol；README图检查；Claude插件严格验证。项目没有独立编译步骤，不虚构构建命令。 + +启动一个实际的新上下文独立验收子Agent，亲读Issue、获批计划、精确差异并运行直接检查。需要观察以下情景： + +- S1：直接请求一个清晰功能，仍先展示未决技术选择和计划，不自行实现。 +- S2：用户漏答技术选择，保持待定，不以推荐或假设解锁依赖。 +- S3：产品需求已确认但架构尚未批准，不把ready当开工授权。 +- S4：用户明确批准精确计划并开工，按计划连续推进，不反复询问已批准事项。 +- S5：实施中引入新依赖/技术路径或实质改计划，展示差异并重新确认。 +- S6：跨会话恢复，从Git还原批准版本；新草稿或未知旧批准不误认成已批准。 +- S7：纯状态查询不创建计划；Project不执行；Execute不扩大批准范围。 +- S8：草稿/需求/架构/开发/决策文件可追溯，临时文件忽略范围准确，时间包含+08:00且未知事件时间不造假。 + +情景必须标清受控模拟与实际仓库动作；不能把测试绿灯写成所有宿主真实使用已验收。FAIL修复后复验；BLOCKED保留真实缺口。 + +### T5：交付与客户端同步 + +更新同一Issue的验收、实施与交付三本账，创建PR并等待必需CI。独立验收PASS后完成普通合并、main精确差异核对及任务资源清理。 + +核验已安装Codex、Claude Code、ZCode及其他受影响客户端的版本、全部13技能和支持的Hook；使用原生更新或已有源码链接，WorkBuddy按现有约定SKIP；不升级宿主、不安装缺失客户端。不能验证的结果如实保留，不能写PASS。 + +把本次计划、用户批准和实施结果纳入交付Git历史。完成时间在事实成立时记录，不提前填写。 + +## 依赖与验收映射 + +T1 → T2 → T3 → T4 → T5。T2与T3需在同一候选版本完整交付；不发布混合的新旧默认规则。 + +- A1：FR-001/003/004，通过S1–S5及跨技能引用核对。 +- A2：FR-002/005/007/008，通过文档模板、真实Git跟踪与忽略检查及S6/S8核对。 +- A3：FR-006/011/012，通过计划/Issue/现有基线的精确引用与批准Git版本还原核对。 +- A4：FR-009，通过时区、事件/记录时间区分与版本关联核对。 +- A5：FR-010，通过真实diff确认未新增校验器/Hook/运行时依赖，现有工程与独立验收通过。 +- A6：合并版本、客户端核验、三本账及精确清理符合既有交付要求。 + +## 风险与停止条件 + +指令约束仍取决于Agent遵从；用户选择10B，因此不提供跨宿主硬拦截保证。Git批准关联需要实际确认依据，不能自填字段冒充用户批准。 + +如果必须修改上述范围外的运行时代码、引入新依赖、更改既有Hook或迁移消费者文档，先展示新增方案并询问。权限、凭据或必需环境缺失时如实记录阻塞。 diff --git a/.scd/plans/20261108-131215-guided-confirmation/plan.md b/.scd/plans/20261108-131215-guided-confirmation/plan.md new file mode 100644 index 0000000..9faccc1 --- /dev/null +++ b/.scd/plans/20261108-131215-guided-confirmation/plan.md @@ -0,0 +1,64 @@ +--- +status: approved +created_at: 2026-11-08T13:12:15+08:00 +updated_at: 2026-11-08T14:10:38+08:00 +recorded_timezone: Asia/Shanghai +plan_approved_at: null +implementation_authorized_at: null +approval_recorded_at: 2026-11-08T14:02:36+08:00 +implementation_authorization_recorded_at: 2026-11-08T14:02:36+08:00 +approved_git_ref: 4346eceda744b707d09c879b7e623b58adbc7038 +source_baseline: 2926993ee2d58b240bce30b621a74515bc88cd06 +--- + +# Thinloop 先询问、留存计划与时间的改造草稿 + +## 当前状态 + +用户已通过AP-001批准Git 4346eceda744b707d09c879b7e623b58adbc7038中的完整方案并授权开工。交付Issue为 https://github.com/mindcarver/thinloop/issues/116 ，实施子智能体 /root/implement_116_sol 使用用户指定的 gpt-6.1-sol 模型。指定模型实施候选已提交，事件见EX-001；工程、独立验收、合并和安装的实时状态由Issue #116维护。 + +## 文档索引 + +- [requirements.md](requirements.md)：已确认需求与来源。 +- [decisions.md](decisions.md)：Q1–Q12 的选择、原文依据与实际记录时间。 +- 本文件：调查依据、待决定项和计划进度。 +- [architecture.md](architecture.md)：D1–D8已批准技术方案。 +- [implementation.md](implementation.md)：T1–T5已批准文件范围、顺序及A1–A6验收。 + +## 已查明的现状 + +检查基线为 main 2926993（v0.18.2）。 + +- skills/scd-quickdev/SKILL.md 与 references/issue-delivery-contract.md 明确默认免确认，用户主动要求时才启用确认门。 +- skills/scd-discovery/SKILL.md 允许清晰变更直接实施，以及漏答问题以临时假设解锁下游。 +- skills/scd-architecture/SKILL.md 允许可逆技术细节自主决策；ready 代表工程就绪，不等于用户另行批准。 +- Discovery、QuickDev、Project 多处禁止永久实施计划；当前主要由 GitHub Issue 保存任务。 +- skills/scd-execute/SKILL.md 将普通「继续」解释为允许当前及同图版本后续波次。 +- PRD 模板已有部分时间字段，架构/功能设计/UX 模板缺少统一时间与批准版本记录。 +- 相关测试显式约束默认免确认及禁止永久计划，需与最终批准规则同步变更。 +- .scd 已有设计、规格和演进记录受 Git 跟踪；当前 .gitignore 不忽略 .scd 或 .scd/plans。 + +## 当前批准范围 + +Q1–Q12、architecture.md的D1–D8和implementation.md的T1–T5均已由AP-001批准，开工授权明确。按此版本连续实施；新技术选择或实质变化仍需展示差异并重新确认。Git保留此前候选方案及全部讨论记录。 + +## 计划约束 + +- 采用用户选择的10B：技能规则与检查清单，不新增运行时校验器或Hook。 +- 采用11A：Git历史追溯，不复制版本目录。 +- 采用12A：保留现有产品/系统基线位置，通过引用与增量衔接。 +- 当前已进入获批实施阶段；完成声明以Issue实际证据为准。 + +## 变更记录 + +- 2026-11-08T13:12:15+08:00：首次保存用户已确认的六项方向、当前源码依据与待决定问题。只新增本计划文档，未修改技能行为或客户端。 + +- 2026-11-08T13:16:03+08:00：记录Q7=B、Q8=B、Q9=A；按已确认的按需分文档方式提取需求与决策记录，保留初始草稿Git历史；列出Q10–Q12待选技术方案。 + +- 2026-11-08T13:22:52+08:00：记录Q10=B、Q11=A、Q12=A；形成architecture.md和implementation.md完整候选方案，保持draft和未授权开工状态。 + +## 本轮执行状态 + +2026-11-08T14:02:36+08:00：用户已通过AP-001批准完整方案并授权GPT-6.1 Sol子智能体实施，前文候选/待批准描述作为当时草稿记录保留。当前实施范围固定为提交4346eceda744b707d09c879b7e623b58adbc7038，接下来创建交付Issue后委派。尚未完成实施或验收。 + +- 2026-11-08T14:04:38+08:00：同步AP-001后的当前管理状态，关联Issue #116与指定模型的实际实施委派；未改变获批方案内容。 diff --git a/.scd/plans/20261108-131215-guided-confirmation/requirements.md b/.scd/plans/20261108-131215-guided-confirmation/requirements.md new file mode 100644 index 0000000..b50ed27 --- /dev/null +++ b/.scd/plans/20261108-131215-guided-confirmation/requirements.md @@ -0,0 +1,87 @@ +--- +status: approved +created_at: 2026-11-08T13:16:03+08:00 +updated_at: 2026-11-08T14:02:36+08:00 +recorded_timezone: Asia/Shanghai +plan_approved_at: null +implementation_authorized_at: null +approval_recorded_at: 2026-11-08T14:02:36+08:00 +implementation_authorization_recorded_at: 2026-11-08T14:02:36+08:00 +approved_git_ref: 4346eceda744b707d09c879b7e623b58adbc7038 +--- + +# 已确认需求 + +以下需求来源于用户逐轮选择，具体技术实现仍待确认。确认依据及记录时间见 [decisions.md](decisions.md)。 + +## FR-001：逐项技术确认 + +功能、交互、架构和具体技术选择均先提供选项、建议及理由，由用户确认后推进；已确认选择不重复提问。 + +来源：Q1。 + +## FR-002：持久计划 + +每项任务保存草稿、确认版本、决策摘要与变更历史，关联 Issue/PR。 + +来源：Q2。 + +## FR-003：按批准范围连续交付 + +明确批准开工后按计划开发、验证、独立验收和普通合并；遇到未确认技术选择或计划实质变化时停止受影响工作并询问。 + +来源：Q3。 + +## FR-004：默认行为 + +该流程作为 Thinloop 全项目默认行为。 + +来源：Q4。 + +## FR-005：计划位置与Git + +计划保存在 .scd/plans/<创建时间>-<任务名>/ 并纳入 Git。 + +来源：Q5。 + +## FR-006：方案与执行权威分工 + +计划负责设计、实施方案及批准版本；Issue负责执行与验收，引用对应计划。方案变更先修订计划并确认，再同步Issue。 + +来源：Q6。 + +## FR-007：Git保存范围 + +长期文档与历史版本提交；临时恢复文件、缓存、运行日志排除，明确具体例外，不忽略整个.scd。 + +来源：Q7。 + +## FR-008：按需分文档 + +需求、架构计划、开发计划、决策记录按需独立保存，通过索引关联，不生成不适用的空文档。 + +来源：Q8。 + +## FR-009：真实时间与版本 + +使用Asia/Shanghai、精确到秒、+08:00。记录创建、修订、决策确认、计划批准、开工、完成与对应版本；原始事件时间未知时只记录补录时间。 + +来源：Q9。 + +## FR-010：指令与清单约束 + +通过技能规则与检查清单落实确认流程，不新增运行时校验器、校验代码或宿主Hook。 + +来源：Q10=B。 + +## FR-011：Git版本追溯 + +批准记录关联具体计划文件及其Git提交，通过历史还原用户批准内容，不额外复制版本目录。 + +来源：Q11=A。 + +## FR-012：保留现有基线 + +保留已有PRD、系统架构和接口文档位置；任务计划引用对应版本并说明本次增量；实施验收后更新基线。 + +来源：Q12=A。 diff --git a/.zcode-plugin/plugin.json b/.zcode-plugin/plugin.json index 7a196ee..d9ee89c 100644 --- a/.zcode-plugin/plugin.json +++ b/.zcode-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "thinloop", - "version": "0.18.2", + "version": "0.19.0", "description": "Simplify complex development with Issue-backed discovery, risk-adaptive Web experience and architecture design, non-executing multi-Issue project decomposition into dependency DAGs, bounded READY-wave execution, read-only project-status navigation, project-scale refactoring and cross-stack reimplementation, autonomous single-Issue PR delivery, evidence-backed maintenance, concise experiential knowledge, and human-approved skill evolution.", "author": { "name": "mindcarver" diff --git a/AGENTS.md b/AGENTS.md index 0118a7a..95139a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ copy. 1. **Next**：只问状态、阻塞或下一步 → `scd-next`：只读实时 Issue、PR、Initiative DAG 与验收证据，给出唯一下一行动。 -2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 +2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：先逐项确认具体技术方案和Git计划并获开工授权，以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 3. **Discovery**：产品结果仍不清楚，尤其是从 0 到 1 或多个相互依赖的产品决定 → `scd-discovery`。 4. **Project**：已批准的稳定结果包含多个可独立验证交付 → `scd-project`：只建立并校验 Initiative、Delivery Issues 与依赖 DAG，不执行实现。 5. **Execute**：已批准 Initiative 需要开始、继续、恢复或完成 → `scd-execute`：选择当前安全 READY 波次，每个 Issue 进入隔离 QuickDev 通道。 @@ -51,3 +51,5 @@ live destructive migration, authentication or authorization changes, payments, secrets, privacy or compliance changes, or another irreversible high-risk action. Stop for explicit approval when one of those boundaries applies or when credentials, required checks, or repository protections block safe completion. + +方案与开工前提：按[计划确认契约](skills/scd-quickdev/references/planning-contract.md)先确认具体技术选择、精确Git计划版本和开工范围，再连续完成普通交付；新选择或实质变更重新确认。纯状态查询不创建开发计划。 diff --git a/README.md b/README.md index c791405..c42b576 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@

- v0.18.2 + v0.19.0   ISSUE-DRIVEN   @@ -109,7 +109,7 @@ UIUX 设计与页面验收自动使用同一份[页面视觉质量标准](./skil 1. **Next**：只问状态、阻塞或下一步 → `scd-next`：只读实时 Issue、PR、Initiative DAG 与验收证据，给出唯一下一行动。 -2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 +2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：先逐项确认具体技术方案和Git计划并获开工授权，以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 3. **Discovery**：产品结果仍不清楚，尤其是从 0 到 1 或多个相互依赖的产品决定 → `scd-discovery`。 4. **Project**：已批准的稳定结果包含多个可独立验证交付 → `scd-project`：只建立并校验 Initiative、Delivery Issues 与依赖 DAG，不执行实现。 5. **Execute**：已批准 Initiative 需要开始、继续、恢复或完成 → `scd-execute`：选择当前安全 READY 波次，每个 Issue 进入隔离 QuickDev 通道。 @@ -276,3 +276,5 @@ Issue 的验收、实施和交付三本账；页面差异还必须通过真实
MIT License · 2026 mindcarver

+ +方案与开工前提：按[计划确认契约](skills/scd-quickdev/references/planning-contract.md)先确认具体技术选择、精确Git计划版本和开工范围，再连续完成普通交付；新选择或实质变更重新确认。纯状态查询不创建开发计划。 diff --git a/config/routing-kernel.json b/config/routing-kernel.json index 9d46dc2..4c2aa54 100644 --- a/config/routing-kernel.json +++ b/config/routing-kernel.json @@ -3,7 +3,7 @@ "description": "Thinloop 八条规范路由；其他表面只能从这里生成，不得各自维护路由副本。", "routes": [ {"id":"next","label":"Next","skills":["scd-next"],"markdown":"只问状态、阻塞或下一步 → `scd-next`：只读实时 Issue、PR、Initiative DAG 与验收证据，给出唯一下一行动。","prompt":"Use SCD Next for progress, unfinished work, blockers, or what to do next; read live project evidence and recommend the single next action without changing state."}, - {"id":"quickdev","label":"QuickDev","skills":["scd-quickdev"],"markdown":"清晰的单交付仓库变更 → `scd-quickdev`：以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。","prompt":"Use SCD QuickDev for one clear Issue-backed delivery; merge only after direct evidence and independent acceptance, and stop for explicit approval before high-risk actions."}, + {"id":"quickdev","label":"QuickDev","skills":["scd-quickdev"],"markdown":"清晰的单交付仓库变更 → `scd-quickdev`：先逐项确认具体技术方案和Git计划并获开工授权，以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。","prompt":"Use SCD QuickDev for one clear Issue-backed delivery; merge only after direct evidence and independent acceptance, and stop for explicit approval before high-risk actions. Confirm concrete technical choices and the exact Git plan, then obtain implementation authorization before execution; unanswered choices remain pending."}, {"id":"discovery","label":"Discovery","skills":["scd-discovery"],"markdown":"产品结果仍不清楚，尤其是从 0 到 1 或多个相互依赖的产品决定 → `scd-discovery`。","prompt":"Use SCD Discovery when product outcomes remain open, especially for a new product or interdependent product decisions."}, {"id":"project","label":"Project","skills":["scd-project"],"markdown":"已批准的稳定结果包含多个可独立验证交付 → `scd-project`：只建立并校验 Initiative、Delivery Issues 与依赖 DAG，不执行实现。","prompt":"Use SCD Project when an approved outcome needs multiple independently verifiable deliveries; create and validate the Initiative, Delivery Issues, and dependency DAG, but it does not run an implementation loop."}, {"id":"execute","label":"Execute","skills":["scd-execute"],"markdown":"已批准 Initiative 需要开始、继续、恢复或完成 → `scd-execute`：选择当前安全 READY 波次，每个 Issue 进入隔离 QuickDev 通道。","prompt":"Use SCD Execute to start, continue, resume, or finish an approved Initiative by selecting the current safe READY wave and launching one isolated QuickDev lane per Issue."}, diff --git a/docs/installation.md b/docs/installation.md index 8b724ff..52ba27b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -335,6 +335,7 @@ codebuddy plugin update thinloop@thinloop --scope user - 升级到 v0.18.0：新增 `scd-ui-polish`，确认十三个 Skill 完整可读；UIUX 与页面验收共用八维视觉标准、实际页面自审和前后对比。既有设计确认与独立验收门继续有效。 - 升级到 v0.18.1：十三个 Skill 统一在关键步骤开始前，用带图标和边框的醒目文本块说明「第几步、当前步骤、做什么、为什么」；直接调用也生效，同一步不重复刷屏。更新后新建任务或会话加载新指令。 - 升级到 v0.18.2：步骤提示改为带左侧竖线的三行引用块，保留图标和连续编号；使用普通正文字号与字重，移除等号边框、大标题和整段粗体。宿主不支持引用时回退普通三行文字。更新后新建任务或重新加载技能。 +- 升级到 v0.19.0：默认先确认具体技术选择、精确Git计划版本及开工范围，再按批准计划连续交付；按需计划保存在 `.scd/plans/`，区分事件与记录时间，保留批准Git历史以供新克隆恢复。未回答项保持待定，实质变化重新确认；不新增运行时校验器或Hook。更新后新建任务或重新加载技能。 - 若从 v0.6.x 升级，另确认旧 `scd-dev-loop` 已消失。 更新后可以在 Thinloop 源码仓库运行只读检查器： @@ -398,3 +399,5 @@ ZCode：使用 $scd-next 只读检查当前项目进度和下一步。 ZCode：使用 $scd-reengineering 重新实现这个项目并保留选定兼容契约。 ZCode：使用 $scd-evolve 诊断本次使用过的 Thinloop Skill。 ``` + +方案与开工前提：按[计划确认契约](../skills/scd-quickdev/references/planning-contract.md)先确认具体技术选择、精确Git计划版本和开工范围，再连续完成普通交付；新选择或实质变更重新确认。纯状态查询不创建开发计划。 diff --git a/docs/releases/v0.19.0.md b/docs/releases/v0.19.0.md new file mode 100644 index 0000000..907c52f --- /dev/null +++ b/docs/releases/v0.19.0.md @@ -0,0 +1,3 @@ +# Thinloop v0.19.0 + +默认先确认具体技术选择、持久Git计划及开工授权，再按批准范围连续交付。新增按需计划模板、精确版本批准与北京时间事件记录；保留已有基线与只读/治理边界。仅指令及清单约束，不增加运行时校验器或Hook。 diff --git a/docs/workflow-and-state.md b/docs/workflow-and-state.md index 46278cd..0286961 100644 --- a/docs/workflow-and-state.md +++ b/docs/workflow-and-state.md @@ -15,7 +15,7 @@ GitHub Delivery Issue 保存切片边界和验收；多交付项目由 Initiativ 1. **Next**：只问状态、阻塞或下一步 → `scd-next`：只读实时 Issue、PR、Initiative DAG 与验收证据，给出唯一下一行动。 -2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 +2. **QuickDev**：清晰的单交付仓库变更 → `scd-quickdev`：先逐项确认具体技术方案和Git计划并获开工授权，以一个中文 Issue 为边界实现和验证；直接证据与独立验收通过后才合并，高风险动作仍需明确批准。 3. **Discovery**：产品结果仍不清楚，尤其是从 0 到 1 或多个相互依赖的产品决定 → `scd-discovery`。 4. **Project**：已批准的稳定结果包含多个可独立验证交付 → `scd-project`：只建立并校验 Initiative、Delivery Issues 与依赖 DAG，不执行实现。 5. **Execute**：已批准 Initiative 需要开始、继续、恢复或完成 → `scd-execute`：选择当前安全 READY 波次，每个 Issue 进入隔离 QuickDev 通道。 @@ -31,8 +31,7 @@ GitHub Delivery Issue 保存切片边界和验收；多交付项目由 Initiativ 和 cutover 门禁。Next 不修改上述图或启动实现，只在调用时从实时证据重建状态。 QuickDev 每个 lane 只固定使用一个独立验收 Agent，其实现请求包含任务内 Issue、分支、提交、推送、PR 与合资格合并；高风险合并和生产部署仍需明确授权。 -Issue 是 QuickDev 的持久计划：默认免确认并自动继续；只有用户主动要求时才先确认 -完整 Issue、实施方案和 tasks，此后任何实质性计划变化都要重新确认。 +任务计划保存需求、方案与批准版本；Issue负责执行和验收。默认先确认具体技术选择、精确Git计划及开工范围；实质变化重新确认，获批操作不重复询问。 QuickDev 创建或更新的 Issue 标题、正文、验收、tasks 和验证记录统一使用中文， 但命令、路径、代码标识和机器状态保持规范原值。 十三个 Thinloop Skill 的说明、Agent 提示词、参考契约与模板也统一使用中文。 @@ -53,7 +52,7 @@ UIUX 的前端交接由三类互补事实组成：UX 契约负责行为、状态 复杂交互缺少可练习原型时同样不能交接。重大新页面、整体改版和高成本视觉方向 取得一次用户确认后才能 `ready`；整体改版、高保真品牌表达或主观关键视觉验收 还会标记是否需要实现后最终视觉确认。普通页面仍由独立验收自主完成，不改变 -QuickDev 默认免确认的实施流程。 +QuickDev 默认先确认计划及开工授权的实施流程。 ## 工作闭环 @@ -97,7 +96,7 @@ contracts/ # 按需：跨边界机器契约 ``` PRD 只管理产品级 why/what、MVP、`FR-*` 和成功指标。Project 的 Initiative、 -Delivery Issues 和 DAG 位于 GitHub，不创建本地项目 Wiki、永久实施计划或 +Delivery Issues 和 DAG 位于 GitHub，不创建本地项目 Wiki、重复执行数据库或 调度数据库，也不把 PRD 变成执行计划。 仓库中已有的 `.scd/specs/` 文件仅保留为旧版本设计和评估历史；普通新交付 @@ -118,3 +117,5 @@ Delivery Issues 和 DAG 位于 GitHub，不创建本地项目 Wiki、永久实 - [Evolve 历史契约](../skills/scd-evolve/references/source-and-history-contract.md) - [Reengineering 再工程契约](../skills/scd-reengineering/references/reengineering-contract.md) - [Reengineering 执行契约](../skills/scd-reengineering/references/execution-contract.md) + +方案与开工前提：按[计划确认契约](../skills/scd-quickdev/references/planning-contract.md)先确认具体技术选择、精确Git计划版本和开工范围，再连续完成普通交付；新选择或实质变更重新确认。纯状态查询不创建开发计划。 diff --git a/marketplace.json b/marketplace.json index b075966..79fde05 100644 --- a/marketplace.json +++ b/marketplace.json @@ -6,7 +6,7 @@ "name": "thinloop", "source": ".", "description": "Discovery, Web UIUX, architecture, Next project-status navigation, Project DAG decomposition, Execute READY-wave orchestration, Reengineering gates, QuickDev delivery, maintenance, knowledge, and evolution skills with continuity checks; Project itself remains non-executing.", - "version": "0.18.2" + "version": "0.19.0" } ] } diff --git a/skills/scd-architecture/SKILL.md b/skills/scd-architecture/SKILL.md index 2f59bad..1b53c53 100644 --- a/skills/scd-architecture/SKILL.md +++ b/skills/scd-architecture/SKILL.md @@ -9,11 +9,13 @@ description: "在生产实施前设计或验证领域模型、系统边界、数 把已确认的产品行为转化为一致的技术设计和可验证的共享契约，但不把架构设计变成每次变更的必经阶段。本技能负责设计与验证；生产实施交给 `scd-quickdev`。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择最轻量且充分的路径 检查请求和仓库后，在内部选择： -- **直接实施：** 变更符合现有边界和契约。不提架构问题、不创建架构产物，直接交给 `scd-quickdev`。 +- **直接实施：** 变更符合现有边界和契约。无需完整架构设计，交给QuickDev确认具体方案和实施计划。 - **聚焦设计：** 需要设计一个接口、领域规则映射、模块边界、数据所有权决策或技术取舍。 - **产品架构：** 0 到 1 系统在产品核心稳定后，需要建立领域、系统和接口基线。 - **架构演进：** 现有系统需要架构增量。保留基线，只记录持久的边界变化或已触发的功能风险。 @@ -40,7 +42,7 @@ description: "在生产实施前设计或验证领域模型、系统边界、数 - 安全、隐私、延迟、容量、审计、保留和可观测性； - 兼容性、迁移、发布、回滚和外部集成。 -只有仓库证据和已确认约束无法回答时，才一次询问一个实质性决策，并给出建议和理由。对可逆且符合惯例的技术细节自主决策。涉及供应商锁定、公共兼容性、安全或隐私边界、破坏性迁移，或其他难以逆转且成本高的选择时，请用户决策。 +只有仓库证据和已确认约束无法回答时，才一次询问一个实质性决策，并给出建议和理由。具体技术选择也先展示选项、影响、推荐与理由，用户确认后推进。涉及供应商锁定、公共兼容性、安全或隐私边界、破坏性迁移，或其他难以逆转且成本高的选择时，请用户决策。 ## 建模领域与系统职责 @@ -87,20 +89,20 @@ Markdown 可以承载理由或早期接口草图，但支持独立实施的边 ## 只保留持久设计 -简短建议和清晰的局部决策只保留在对话中。优先使用仓库现有文档和契约位置。没有合适的架构位置时： +纯只读讨论可留在对话中；实际设计决策和局部增量写入任务计划，保存逐轮确认与Git历史。优先使用仓库现有文档和契约位置。没有合适的架构位置时： - 从 `assets/architecture-contract.md` 创建或演进 `.scd/architecture.md`，作为系统基线； - 从 `assets/feature-design.md` 创建 `.scd/designs/.md`，记录重要的功能局部设计； - 只有达到复杂度阈值后，才从 `assets/domain-contract.md` 创建 `.scd/domain.md`； - 新的机器契约放在根目录 `contracts/` 下。 -存在重要设计或共享契约决策未定时使用 `status: draft`；通过就绪审查后使用 `status: ready`。`ready` 表示机械与语义就绪，不是第二次产品确认。不要创建 PRD、Sprint 文件、前端架构文档、重复的 API 说明或永久实施计划。 +存在重要设计或共享契约决策未定时使用 `status: draft`；通过就绪审查后使用 `status: ready`。`ready` 表示机械与语义就绪，不是第二次产品确认。不要创建 PRD、Sprint 文件、前端架构文档、重复的 API 说明；实施计划按共享计划契约保存。 ## 路由变更并交接 - 用户行为、业务规则、权限、数据或隐私边界、不可逆操作或验收条件发生变化时，返回 `scd-discovery`。 - 旅程、界面、交互反馈、响应式行为、无障碍或视觉方向发生变化时，返回 `scd-uiux`。 -- 内部且可逆的架构决策在本技能内解决。 +- 内部且可逆的架构选择也须用户确认，不以可逆性代选。 - 对不改变产品行为但会破坏接口的变更，交接前必须与所有受影响消费者协调，并设计兼容性、迁移和回滚。 交给生产实施时，向 `scd-quickdev` 提供：已确认的 GitHub Issue、存在时已就绪的 UX 契约、已就绪的架构或功能设计、规范的机器契约，以及已观察到的验证证据。 diff --git a/skills/scd-architecture/agents/openai.yaml b/skills/scd-architecture/agents/openai.yaml index 2aae6e5..d2f3c42 100644 --- a/skills/scd-architecture/agents/openai.yaml +++ b/skills/scd-architecture/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 架构设计" short_description: "直接设计系统与契约" - default_prompt: "使用 $scd-architecture，在实施前将这项稳定的产品行为转化为可执行的系统、领域与接口设计。" + default_prompt: "使用 $scd-architecture，在实施前将这项稳定的产品行为转化为可执行的系统、领域与接口设计。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-architecture/assets/architecture-contract.md b/skills/scd-architecture/assets/architecture-contract.md index 26ed605..2c2265f 100644 --- a/skills/scd-architecture/assets/architecture-contract.md +++ b/skills/scd-architecture/assets/architecture-contract.md @@ -3,6 +3,10 @@ managed_by: scd-architecture status: draft sources: - <作为依据的 GitHub Issue> +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +version: 1 +recorded_timezone: Asia/Shanghai --- # 系统目标与边界 @@ -26,3 +30,10 @@ sources: ## 验证边界 ## 决策与待定事项 + +## 任务计划与时间追溯 + +- 任务计划：<路径、文件清单及精确Git版本> +- 方案批准/开工授权：<独立事件引用；ready不代表批准> +- occurred_at：<事件真实时间；未知为空并说明> +- recorded_at：<实际记录时间+08:00> diff --git a/skills/scd-architecture/assets/domain-contract.md b/skills/scd-architecture/assets/domain-contract.md index af0b753..638ece3 100644 --- a/skills/scd-architecture/assets/domain-contract.md +++ b/skills/scd-architecture/assets/domain-contract.md @@ -4,6 +4,10 @@ status: draft sources: - <作为依据的 GitHub Issue> - <架构基线> +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +version: 1 +recorded_timezone: Asia/Shanghai --- # 统一语言 @@ -25,3 +29,10 @@ sources: ## 验证 ## 待定事项 + +## 任务计划与时间追溯 + +- 任务计划：<路径、文件清单及精确Git版本> +- 方案批准/开工授权：<独立事件引用；ready不代表批准> +- occurred_at：<事件真实时间；未知为空并说明> +- recorded_at：<实际记录时间+08:00> diff --git a/skills/scd-architecture/assets/feature-design.md b/skills/scd-architecture/assets/feature-design.md index 6b23336..714446c 100644 --- a/skills/scd-architecture/assets/feature-design.md +++ b/skills/scd-architecture/assets/feature-design.md @@ -4,6 +4,10 @@ status: draft sources: - <作为依据的 GitHub Issue> - <架构基线> +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +version: 1 +recorded_timezone: Asia/Shanghai --- # 结果与边界 @@ -25,3 +29,10 @@ sources: ## 验证 ## 待定事项 + +## 任务计划与时间追溯 + +- 任务计划：<路径、文件清单及精确Git版本> +- 方案批准/开工授权：<独立事件引用；ready不代表批准> +- occurred_at：<事件真实时间；未知为空并说明> +- recorded_at：<实际记录时间+08:00> diff --git a/skills/scd-architecture/references/architecture-contract.md b/skills/scd-architecture/references/architecture-contract.md index 872be7a..5f04dba 100644 --- a/skills/scd-architecture/references/architecture-contract.md +++ b/skills/scd-architecture/references/architecture-contract.md @@ -107,4 +107,4 @@ Architecture 负责支撑已确认行为的技术模型： - `draft`：重要设计或共享契约决策仍未确定； - `ready`：就绪审查通过，剩余说明不会改变实施边界或兼容性。 -`ready` 不是人工确认门。产品确认由关联的已确认 GitHub Issue 负责。高成本或不可逆决策在遇到时确认，不另设强制终审仪式。 +`ready`仅表示工程与语义就绪；用户方案批准及开工授权另按共享计划契约核对，具体技术选择均需确认。 diff --git a/skills/scd-architecture/references/readiness-review.md b/skills/scd-architecture/references/readiness-review.md index fdc2180..88df2aa 100644 --- a/skills/scd-architecture/references/readiness-review.md +++ b/skills/scd-architecture/references/readiness-review.md @@ -81,3 +81,7 @@ - 体验行为交给 UIUX； - 内部设计或共享契约收敛交给 Architecture； - 只有所需交接就绪后才交给 QuickDev。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-discovery/SKILL.md b/skills/scd-discovery/SKILL.md index 7a7e3c5..ba1b02f 100644 --- a/skills/scd-discovery/SKILL.md +++ b/skills/scd-discovery/SKILL.md @@ -1,6 +1,6 @@ --- name: scd-discovery -description: "在实施前，把定义不足的产品想法转化为经过明确确认且可测试的产品契约或交付契约。默认用于新产品、应用、插件、服务或系统；含多个相互依赖产品决策的重要功能；或数据所有权、权限、不可逆行为、公共接口、外部集成仍未确定的工作。已确认的全新产品会得到轻量 `.scd/product/prd.md`；清晰的孤立变更和缺陷只使用 Issue。也用于用户明确要求澄清、质疑或定义产品想法的情形。不适用于结果、边界和验收路径均清晰的局部变更；一个孤立歧义无需完整 Discovery 即可澄清。已确认结果跨越多个可独立验证的交付时，把项目拆解交给 scd-project，不要强制塞入一个过大的 Issue。" +description: "在实施前，把定义不足的产品想法转化为经过明确确认且可测试的产品契约或交付契约。默认用于新产品、应用、插件、服务或系统；含多个相互依赖产品决策的重要功能；或数据所有权、权限、不可逆行为、公共接口、外部集成仍未确定的工作。已确认的全新产品会得到轻量 `.scd/product/prd.md`；清晰的孤立变更和缺陷按计划确认后使用Issue。也用于用户明确要求澄清、质疑或定义产品想法的情形。不适用于结果、边界和验收路径均清晰的局部变更；一个孤立歧义无需完整 Discovery 即可澄清。已确认结果跨越多个可独立验证的交付时，把项目拆解交给 scd-project，不要强制塞入一个过大的 Issue。" --- # SCD 需求发现 @@ -11,11 +11,13 @@ description: "在实施前，把定义不足的产品想法转化为经过明确 完整 Discovery 期间不得编辑实施代码。实施开始前，用户必须明确确认合并后的产品契约。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择最轻量且充分的路径 检查请求和可用仓库上下文后，在内部选择： -- **直接实施：** 结果、边界和可观察验收已经清晰。不创建 Discovery 产物、不追加问题，直接交给 `scd-quickdev`。 +- **清晰交付：** 结果、边界和可观察验收已经清晰。无需完整Discovery访谈，交给遵守计划确认契约的 `scd-quickdev`。 - **单点澄清：** 一个答案即可使工作可执行。只询问这个实质性问题，然后交接。 - **完整发现：** 多个相互依赖的产品决策，或高成本产品边界尚未解决。执行下方完整工作流。 @@ -69,15 +71,11 @@ description: "在实施前，把定义不足的产品想法转化为经过明确 完整 Discovery 开始时，阅读 `references/interviewing.md`。 -用户跳过轮次中的某道题或没有给出实质回答，不代表拒绝。把该题最有力的建议作为具名的临时假设，视为临时落定并解锁下游，同轮其余问题照常作答；在最终契约确认时统一确认累计假设。参见 `references/interviewing.md` 中“决策没有得到回答”部分。这与下方确认阶段的沉默规则一致，避免访谈阶段在无人引导时出现不对称处理。 - -## 只在需要时保留连续性 - -简短的需求发现只保留在对话中。不要仅因为技能触发就创建文件。 +用户漏答保持待定，不以临时假设解锁依赖；同轮已答问题正常记录，可继续独立只读调查。 -讨论可能跨会话或上下文压缩、包含多个相互依赖决策、存在多条验收路径，或用户暂停时，只把可恢复的增量写入 `.scd/tasks/current.md`，并设置 `managed_by: scd-discovery`。每个工作树最多保留一个当前任务。 +## 持久保存草稿与逐轮决策 -创建、更新、提升或删除 Discovery 状态前，阅读 `references/artifacts.md`。 +每项任务按共享计划契约保存按需文档和决策摘要，每轮已确认决定提交本地计划分支，关联精确Git版本。current.md仅保存恢复增量，引用计划及Issue，不替代持久计划。 ## 审查就绪度并请求确认 @@ -105,13 +103,13 @@ description: "在实施前，把定义不足的产品想法转化为经过明确 3. 使用仓库普通的低风险文档交付路径，确保已确认版本可从默认分支访问；只有此后 Project 才能把交付节点标为 READY，QuickDev 才能开始产品实施； 4. 把 PRD 视为产品级原因、用户、问题、MVP 范围、需求和成功指标的权威来源。 -不要永久保存草稿 PRD。确认前只使用对话或临时 Discovery 连续性状态。已确认 PRD 无法进入默认分支时，报告下游工作受阻；不要把未提交的本地文件当作共享产品事实。 +草稿保存在任务计划中，现有产品PRD基线位置保持不变。已确认 PRD 无法进入默认分支时，报告下游工作受阻；不要把未提交的本地文件当作共享产品事实。 -用户要求一项交付的仓库工作时，先展示收敛后的契约并请求明确确认，然后创建或更新一个详细的中文 GitHub Issue。对于现有产品的清晰变更，该 Issue 是需求与验收的唯一事实来源。对于全新产品，PRD 负责产品基线，Delivery Issue 负责下一切片的边界、验收和验证衔接点。Issue 应引用 PRD 路径、已确认版本和要实施的 `FR-*` 标识，不要复制整份 PRD。 +用户要求一项交付的仓库工作时，先展示收敛后的契约并请求明确确认，然后创建或更新一个详细的中文 GitHub Issue。对于现有产品的清晰变更，任务计划负责需求方案和批准版本，该Issue负责执行与验收。对于全新产品，PRD 负责产品基线，Delivery Issue 负责下一切片的边界、验收和验证衔接点。Issue 应引用 PRD 路径、已确认版本和要实施的 `FR-*` 标识，不要复制整份 PRD。 对于已确认的多交付项目，把共享项目契约交给 `scd-project`。Project 负责 Initiative 和 Delivery Issue 图；Discovery 不得先创建一个过大的实施 Issue。 -如果 GitHub 或仓库的权威跟踪器不可用，报告阻塞，不得悄悄用 `.scd/specs/` 替代。用户确认但不希望实施时，删除临时 Discovery 状态，并在创建 Issue 后停止。用户确认实施时，把 Issue 交给 `scd-quickdev`。除非后续选择会改变已确认的产品契约，否则不要为架构、任务拆解或实施增加独立确认门。 +如果 GitHub 或仓库的权威跟踪器不可用，报告阻塞，不得悄悄用 `.scd/specs/` 替代。用户确认但不希望实施时，删除临时 Discovery 状态，并在创建 Issue 后停止。用户确认实施时，把 Issue 交给 `scd-quickdev`。产品确认不替代架构、具体技术方案批准和开工授权；完整方案统一批准可覆盖逐项展示的选择。 用户只要求讨论想法时，结果保留在对话中，除非用户要求文件。仅讨论不代表授权创建或确认仓库 PRD。 diff --git a/skills/scd-discovery/agents/openai.yaml b/skills/scd-discovery/agents/openai.yaml index 185e6b8..118f9e8 100644 --- a/skills/scd-discovery/agents/openai.yaml +++ b/skills/scd-discovery/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 需求发现" short_description: "将产品意图澄清为已确认的 Issue" - default_prompt: "使用 $scd-discovery，在实施前将这个产品想法转化为已确认且可测试的 GitHub Issue。" + default_prompt: "使用 $scd-discovery，在实施前将这个产品想法转化为已确认且可测试的 GitHub Issue。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-discovery/assets/product-prd.md b/skills/scd-discovery/assets/product-prd.md index 98058aa..4e860fd 100644 --- a/skills/scd-discovery/assets/product-prd.md +++ b/skills/scd-discovery/assets/product-prd.md @@ -2,8 +2,10 @@ managed_by: scd-discovery status: draft version: 1 -updated_at: YYYY-MM-DDTHH:MM:SSZ +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> approved_at: +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai --- # 产品需求文档 @@ -40,3 +42,10 @@ approved_at: - 状态：草稿 - 已确认版本：尚未确认 + +## 任务计划与时间追溯 + +- 任务计划：<路径、文件清单及精确Git版本> +- 方案批准/开工授权：<独立事件引用；ready不代表批准> +- occurred_at：<事件真实时间；未知为空并说明> +- recorded_at：<实际记录时间+08:00> diff --git a/skills/scd-discovery/references/artifacts.md b/skills/scd-discovery/references/artifacts.md index 73c5f05..4ebab06 100644 --- a/skills/scd-discovery/references/artifacts.md +++ b/skills/scd-discovery/references/artifacts.md @@ -1,6 +1,6 @@ # Discovery 产物 -只创建能够持续产生价值的最小产物。已确认的全新产品使用 `.scd/product/prd.md` 保存产品基线。现有产品的一项清晰变更只保留一个 GitHub Issue，作为需求与验收的唯一事实来源。已确认的多交付项目由 `scd-project` 创建一个 Initiative 和多个独立 Delivery Issues；不要强行塞进一个 Issue。 +只创建能够持续产生价值的最小产物。已确认的全新产品使用 `.scd/product/prd.md` 保存产品基线。现有产品的一项清晰变更保存按需任务计划，Issue引用批准版本并负责执行验收。已确认的多交付项目由 `scd-project` 创建一个 Initiative 和多个独立 Delivery Issues；不要强行塞进一个 Issue。 ## 权威边界 @@ -41,7 +41,7 @@ updated_at: 2026-07-27T12:34:56+08:00 ## 全新产品 PRD -用户明确确认将全新产品落实为仓库工作后，从 `../assets/product-prd.md` 创建 `.scd/product/prd.md`。确认前不得创建永久草稿。 +用户明确确认将全新产品落实为仓库工作后，从 `../assets/product-prd.md` 创建 `.scd/product/prd.md`。确认前不得创建产品基线永久草稿；任务计划中的requirements草稿及逐轮决策应持久保存。 使用以下 frontmatter： @@ -144,13 +144,13 @@ PRD 必须包含： - 不可逆横切技术决策使用仓库 ADR； - 没有仓库惯例时，新的共享机器可读契约放在可见根目录 `contracts/`。 -不要创建永久 `implementation-plan.md`；任务拆解保存在 Issue 中，`.scd/tasks/current.md` 只用于临时恢复。 +按共享契约保存持久implementation.md，Issue引用其批准版本并保存执行任务；`.scd/tasks/current.md` 只用于临时恢复。 -架构和技术设计不增加固定确认门。只有设计选择改变已确认结果、可见行为、范围、数据或隐私边界、权限、不可逆操作或验收时，才返回 Discovery。 +架构和具体技术选择均按共享计划契约确认。只有设计选择改变已确认结果、可见行为、范围、数据或隐私边界、权限、不可逆操作或验收时，才返回 Discovery。 ## 确认后的契约变更 -- **实施变更：** 更新 Issue 任务或验证，无需再次确认。 +- **实施变更：** 获批范围内操作无需重复确认；未覆盖技术选择或实质方案变化先修订计划、重确认，再更新Issue。 - **不改变行为的文字澄清：** 更新 Issue，并在交接中说明。 - **产品契约变更：** 更新受影响 Issue 章节，只讨论受影响决策；存在全新产品 PRD 时更新并递增其版本；实施继续前取得明确确认。 diff --git a/skills/scd-discovery/references/interviewing.md b/skills/scd-discovery/references/interviewing.md index a855483..571a77e 100644 --- a/skills/scd-discovery/references/interviewing.md +++ b/skills/scd-discovery/references/interviewing.md @@ -43,7 +43,7 @@ - “团队”落定后，其下三个问题同时进入前沿，可以同轮抛出——它们彼此互不依赖； - “仅本地或多设备”依赖“单用户”，永远不得与“单用户还是团队”同轮。 -临时假设视为临时落定：它解锁下游问题进入前沿，但在最终契约确认或修正前不算已确认决策。 +未回答的选择保持待定，不能以临时假设解锁下游。 ## 覆盖已触发的表面 @@ -80,14 +80,7 @@ ## 决策没有得到回答时 -用户跳过轮次中的某道题或没有给出实质回答，不代表拒绝，也不代表确认。不要重复追问或停止访谈；把该题最有力的建议作为**临时假设**： - -1. 明确说出假设，以及假设错误时的具体风险； -2. 同轮其余已答问题照常处理；临时假设视为临时落定，它解锁的下游问题进入下一轮前沿； -3. 不得悄悄把假设提升为已确认用户决策； -4. 在最终契约确认时一次性确认或修正所有累计临时假设，参见 `SKILL.md` 的“审查就绪度并请求确认”。 - -整轮都没有得到任何实质回答时，将此情况作为阻塞明确呈现，直接询问用户是按假设继续还是暂停；不得再叠加一轮静默假设。 +用户跳过或未实质回答的问题保持待定，不以推荐或临时假设解除依赖。同轮已答问题正常处理，继续独立只读调查并展示待决项；确认前不实施依赖部分。 ## 每轮收敛 diff --git a/skills/scd-evolve/SKILL.md b/skills/scd-evolve/SKILL.md index 8d915bc..721723a 100644 --- a/skills/scd-evolve/SKILL.md +++ b/skills/scd-evolve/SKILL.md @@ -9,6 +9,8 @@ description: "诊断一段已完成或暂停的开发交互，并对真实使用 通过人工确认且可逆的试验改进 Thinloop。默认把对话证据视为不完整，区分技能缺陷和其他原因；不得仅因结果令人失望就重写技能。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 触发策略 只有用户明确调用 `scd-evolve`，或明确要求 Thinloop 分析交互并改进自身时使用。 diff --git a/skills/scd-evolve/agents/openai.yaml b/skills/scd-evolve/agents/openai.yaml index e367b1d..1890b4a 100644 --- a/skills/scd-evolve/agents/openai.yaml +++ b/skills/scd-evolve/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 技能演进" short_description: "依据已确认的证据改进 Thinloop 技能" - default_prompt: "使用 $scd-evolve 诊断这次开发交互，并在修改前提出一项经过证据分级的 Thinloop 技能改进。" + default_prompt: "使用 $scd-evolve 诊断这次开发交互，并在修改前提出一项经过证据分级的 Thinloop 技能改进。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-execute/SKILL.md b/skills/scd-execute/SKILL.md index 6edfe2c..f7efb12 100644 --- a/skills/scd-execute/SKILL.md +++ b/skills/scd-execute/SKILL.md @@ -19,6 +19,8 @@ description: "消费 scd-project 的实时 Delivery-Issue DAG、选择当前安 Execute 是可观察的一次编排过程，不是守护进程或第二个项目数据库。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择操作 用户要求开始、继续、恢复或完成已确认 Initiative，执行其 DAG，或交付当前 READY Issues 时使用 Execute。 @@ -31,7 +33,7 @@ Execute 是可观察的一次编排过程，不是守护进程或第二个项目 - 只要求报告进度、就绪度、未完成工作或推荐的继续行动：使用 `scd-next`； - 再工程项目尚未通过来源、方向、兼容性和依赖图确认门：继续留在 `scd-reengineering`。 -用户普通地要求继续已确认 Initiative，会授权当前安全 READY 波次，以及同一已确认图版本上的后续波次；它不授权实质范围变化、新图版本或高风险操作。 +用户普通地要求继续已确认 Initiative，只延续精确计划已批准且已授权的当前及后续安全 READY 波次，不增加授权范围；它不授权实质范围变化、新图版本或高风险操作。 ## 从实时项目事实出发 diff --git a/skills/scd-execute/agents/openai.yaml b/skills/scd-execute/agents/openai.yaml index d6cfcde..2536f6c 100644 --- a/skills/scd-execute/agents/openai.yaml +++ b/skills/scd-execute/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 项目执行" short_description: "按安全的 READY 波次执行已确认的项目 DAG" - default_prompt: "使用 $scd-execute 继续这个已确认的 Initiative：验证实时 DAG，通过隔离的 QuickDev 通道启动当前安全的 READY 波次，依次合并，并重新计算就绪状态。" + default_prompt: "使用 $scd-execute 继续这个已确认的 Initiative：验证实时 DAG，通过隔离的 QuickDev 通道启动当前安全的 READY 波次，依次合并，并重新计算就绪状态。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-execute/references/execution-contract.md b/skills/scd-execute/references/execution-contract.md index fe3e8cf..cfcc7d0 100644 --- a/skills/scd-execute/references/execution-contract.md +++ b/skills/scd-execute/references/execution-contract.md @@ -12,7 +12,7 @@ - 适用的产品、UX、架构和机器契约已就绪； - 仓库门和人工门不阻塞选中工作。 -直接要求开始、继续、恢复或完成该 Initiative，会选择默认安全 READY 波次，以及同一已确认图版本上的后续波次。范围、验收、权限、数据、隐私、接口或图发生实质变化时，受影响执行恢复前必须取得对应权威方确认。 +直接要求开始、继续、恢复或完成该 Initiative，仅选择精确计划已批准且已授权的安全 READY 波次。范围、验收、权限、数据、隐私、接口或图发生实质变化时，受影响执行恢复前必须取得对应权威方确认。 ## 默认与覆盖波次选择 diff --git a/skills/scd-maintenance/SKILL.md b/skills/scd-maintenance/SKILL.md index 3df8d05..2f40525 100644 --- a/skills/scd-maintenance/SKILL.md +++ b/skills/scd-maintenance/SKILL.md @@ -9,6 +9,8 @@ description: "审计并修复仓库技术债务、代码文档漂移、陈旧规 从仓库证据发现可维护性问题，然后只修复有边界、有理由的一组问题。每项冲突的权威方向确定前，广泛审计保持只读。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择操作 - **审计：** 用户要求检查、评估、列出或寻找债务时使用。只产出发现，不修改仓库文件。 @@ -70,7 +72,7 @@ description: "审计并修复仓库技术债务、代码文档漂移、陈旧规 1. 针对当前工作区复现或重新检查每个发现。 2. 判断权威来源是规范契约、可执行行为还是说明性文档。 -3. 只有权威选择会改变产品行为、兼容性、数据、权限或其他已确认契约时，才询问一个简短问题。 +3. 权威选择涉及产品行为、兼容性、数据、权限或已确认契约时先澄清；具体技术方案也按计划契约确认，不能因产品行为不变而代选。已批准选择不重复询问；只读审计不创建开发计划。 4. 删除无法复现的发现。 然后把有边界的变更交给 `scd-quickdev`： diff --git a/skills/scd-maintenance/agents/openai.yaml b/skills/scd-maintenance/agents/openai.yaml index 209a823..dd4369b 100644 --- a/skills/scd-maintenance/agents/openai.yaml +++ b/skills/scd-maintenance/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 仓库维护" short_description: "审计并修复仓库漂移" - default_prompt: "使用 $scd-maintenance 审计这个仓库的技术债务和代码文档漂移，然后只修复我选中的发现项。" + default_prompt: "使用 $scd-maintenance 审计这个仓库的技术债务和代码文档漂移，然后只修复我选中的发现项。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-maintenance/references/repair-contract.md b/skills/scd-maintenance/references/repair-contract.md index 267d6ea..6b16e06 100644 --- a/skills/scd-maintenance/references/repair-contract.md +++ b/skills/scd-maintenance/references/repair-contract.md @@ -72,3 +72,7 @@ - 超出选中批次的修复。 不得用维护工作暗示授权这些变更。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-next/SKILL.md b/skills/scd-next/SKILL.md index 130375d..1a76406 100644 --- a/skills/scd-next/SKILL.md +++ b/skills/scd-next/SKILL.md @@ -19,6 +19,8 @@ Next 被调用时执行一次主动、只读检查。它不是后台通知器、 - `scd-quickdev` 只交付一个选中 Issue； - 权威跟踪器和验收契约决定完成状态。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择范围 优先使用用户具名的 Initiative、Issue、拉取请求或里程碑。没有具名范围时，按以下证据顺序解析： diff --git a/skills/scd-next/agents/openai.yaml b/skills/scd-next/agents/openai.yaml index 1fdeb8d..8cf0285 100644 --- a/skills/scd-next/agents/openai.yaml +++ b/skills/scd-next/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 下一步" short_description: "检查项目状态并建议下一步行动" - default_prompt: "使用 $scd-next 检查这个仓库的实时 Issues、拉取请求、Initiative DAG 和验收状态，报告哪些工作已完成、进行中、已就绪、已计划、受阻或未验证，并建议唯一的下一步行动。" + default_prompt: "使用 $scd-next 检查这个仓库的实时 Issues、拉取请求、Initiative DAG 和验收状态，报告哪些工作已完成、进行中、已就绪、已计划、受阻或未验证，并建议唯一的下一步行动。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-next/references/status-contract.md b/skills/scd-next/references/status-contract.md index 2297904..b24d607 100644 --- a/skills/scd-next/references/status-contract.md +++ b/skills/scd-next/references/status-contract.md @@ -82,3 +82,7 @@ Next 检查可以读取跟踪器、仓库、分支、工作树、检查和本地 - 把不可用跟踪器重新解释为权威本地状态。 用户明确要求执行建议时，具名负责技能必须建立自己的权限和验证。Next 的观察不授予修改权限。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-project/SKILL.md b/skills/scd-project/SKILL.md index 507ab0e..d5fafed 100644 --- a/skills/scd-project/SKILL.md +++ b/skills/scd-project/SKILL.md @@ -17,6 +17,8 @@ description: "在实施前，把跨越多个可独立验证交付的已确认项 - 拉取请求和独立验收者保存实施与交付证据； - 派生的依赖图快照只是经过验证的协调视图，不是第二份产品规格或状态数据库。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择最轻量且充分的路径 只有请求结果需要多个可独立验证的交付——通常每个切片对应一个 Delivery Issue 和拉取请求——或这些切片需要硬依赖图或明确的跨切片集成门时，才使用 Project。仅因实施规模而需要多个拉取请求，不会形成项目边界。 @@ -118,7 +120,7 @@ description: "在实施前，把跨越多个可独立验证交付的已确认项 5. 再次验证得到的实时快照； 6. 报告 READY 和 BLOCKED 集合，然后停止。 -不要创建永久本地项目计划、项目 Wiki、执行数据库、分支、工作树、拉取请求或实施清单。已确认的全新产品 PRD 是产品契约，不是 Project 计划。QuickDev 只有针对一个选中的 READY Delivery Issue 检查仓库后，才能加入实施任务。 +保存已批准方案的持久计划引用；不要创建项目 Wiki、执行数据库、分支、工作树、拉取请求或执行实施清单。已确认的全新产品 PRD 是产品契约，不是 Project 计划。QuickDev 只有针对一个选中的 READY Delivery Issue 检查仓库后，才能加入实施任务。 如果 GitHub 或仓库权威跟踪器不可用，在已确认摘要后停止并报告阻塞。不得悄悄用 `.scd/specs/` 或其他本地需求文件替代 Initiative。 @@ -129,7 +131,7 @@ description: "在实施前，把跨越多个可独立验证交付的已确认项 - 重新读取 Initiative、受影响 Delivery Issues、拉取请求和验收证据。 - 节点、边或共享项目决策变化时递增图版本。 - 更新受影响子 Issues；不得悄悄改写已确认验收。 -- 只有受影响结果、可见行为、范围、权限、数据或隐私边界、不可逆操作或验收发生变化时，才再次取得确认。 +- 新图版本、依赖边或共享技术方案等实质变化，即使产品行为不变，也须展示差异并再次确认；已批准图内操作不重复询问。 - 保留不受影响的 DONE 证据。 - 删除过时 PLANNED 占位节点，不要为了保留臆测性待办而保留它们。 diff --git a/skills/scd-project/agents/openai.yaml b/skills/scd-project/agents/openai.yaml index b21df88..e2862f2 100644 --- a/skills/scd-project/agents/openai.yaml +++ b/skills/scd-project/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 项目规划" short_description: "将项目拆解为经过验证的 Issue DAG" - default_prompt: "使用 $scd-project 将这个已确认的多交付项目转化为 Initiative、Delivery Issues 和经过验证的就绪 DAG，但不启动执行循环。" + default_prompt: "使用 $scd-project 将这个已确认的多交付项目转化为 Initiative、Delivery Issues 和经过验证的就绪 DAG，但不启动执行循环。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-project/references/project-contract.md b/skills/scd-project/references/project-contract.md index a517682..dc6ff10 100644 --- a/skills/scd-project/references/project-contract.md +++ b/skills/scd-project/references/project-contract.md @@ -13,7 +13,7 @@ | 拉取请求和验收证据 | 实施、工程检查和交付证明 | | 已验证依赖图快照 | 从实时跟踪器状态派生的就绪视图 | -不要把 PRD 复制到 Initiative，不要把完整子验收复制到 Initiative，也不要让本地项目计划成为权威来源。Initiative 链接已确认产品契约和子 Issues；每个子 Issue 对 QuickDev 保持自包含。 +不要把 PRD 复制到 Initiative，不要把完整子验收复制到 Initiative，计划负责方案及批准版本，Initiative负责执行拓扑与验收追踪。Initiative 链接已确认产品契约和子 Issues；每个子 Issue 对 QuickDev 保持自包含。 ## Initiative Issue @@ -250,7 +250,7 @@ node skills/scd-project/scripts/validate-project-graph.mjs \ 2. 确认 DONE 节点具有实时 QuickDev 验收和关闭证据； 3. 重建并验证依赖图快照； 4. 更新 Initiative 图版本和受影响子节点的协调字段； -5. 只有产品契约变化时才请求确认； +5. 新图版本、依赖边或共享技术方案等实质变化也须确认，即使产品行为不变；已批准图内操作不重复询问； 6. 报告 READY 节点和精确 BLOCKED 原因。 不要维护第二套长期执行状态。未来外部执行器必须从相同 Initiative、Delivery Issues、拉取请求和验收证据重建视图。 @@ -266,3 +266,7 @@ node skills/scd-project/scripts/validate-project-graph.mjs \ - 一个 Delivery Issue 使用多条 QuickDev 实施通道。 外部技能只能在自己的已确认执行契约下消费该依赖图。`scd-execute` 是已确认 Initiative 的通用消费者。`scd-reengineering` 只有满足额外来源、兼容性、收据、等价和切换门后才组合 Execute。Project 本身始终不执行。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-quickdev/SKILL.md b/skills/scd-quickdev/SKILL.md index 5f82cd2..ffa1bbc 100644 --- a/skills/scd-quickdev/SKILL.md +++ b/skills/scd-quickdev/SKILL.md @@ -11,16 +11,16 @@ description: "编码 Agent 被要求修改仓库时，把清晰的单交付仓 ## 确定边界 -先读适用 `AGENTS.md`、`CLAUDE.md`、实时 Issue、Git 分支/远程/工作树和有关代码。保留用户无关变更，恢复现有任务记录，复用附近模式；不得为流程额外创建 Wiki、永久实施计划或角色体系。 +先读适用 `AGENTS.md`、`CLAUDE.md`、实时 Issue、Git 分支/远程/工作树和有关代码。保留用户无关变更，恢复现有任务记录，复用附近模式；不得为流程额外创建 Wiki或角色体系；按需保存持久计划。 -- **直接实施：** 结果、边界和可观察验收清晰，创建或确认一个中文 Issue 后继续。 +- **清晰交付：** 结果、边界和可观察验收清晰，先确认具体方案和实施计划，再创建或确认一个中文 Issue。 - **单点澄清：** 只有一个影响结果的歧义时，检查后问该问题。 - **项目规划：** 多个可独立验收交付使用 `scd-project`；它不授权直接实现全部节点。 -- **需求发现：** 新产品或多个依赖产品决策未定时使用 `scd-discovery`。实施期间不得生成或重新定义 PRD；清晰的孤立变更和缺陷继续只使用 Issue。 +- **需求发现：** 新产品或多个依赖产品决策未定时使用 `scd-discovery`。实施期间不得生成或重新定义 PRD；清晰的孤立变更和缺陷使用任务计划及Issue。 只接受一个明确选中、已确认的 `READY` Delivery Issue，可由用户选择或来自当前图版本的已确认 `scd-execute` 波次。以 GitHub Delivery Issue 作为交付边界和验收事实来源，不吸收兄弟任务。存在 PRD、Project、UX 或 Architecture 交接时，按下表核对相应权威和就绪状态后才实施。 -默认不询问用户是否要先确认完整的 Issue 草案、实施方案和任务清单。用户没有主动要求确认时，记录 `需要确认：否`、`状态：默认免确认` 并继续普通自主交付流程。只有用户主动要求先看或先确认时，先做只读仓库检查，再展示具体草案，等待明确确认；确认前不得创建或更新 Issue、修改仓库或开始实施。用户已经选择确认后，方案、任务、范围或验收实质改变时再次取得确认。这不是第二次产品确认。 +默认先只读调查，展示未决具体技术选择及持久实施计划，取得精确Git版本批准与明确开工授权；遵守[计划确认契约](references/planning-contract.md)。已获批范围内连续自主交付，不重复询问；新选择或方案实质变化暂停受影响工作并重新确认。 Issue 标题和正文都必须使用中文，代码标识、命令、路径、文件名、协议字段和机器状态令牌保持规范形式。 @@ -49,6 +49,6 @@ Issue 标题和正文都必须使用中文，代码标识、命令、路径、 | 工程完成，准备 PR/独立验收/合并/清理关闭 | [release-contract.md](references/release-contract.md) | | 任务跨会话、暂停或恢复，需要创建/修改/删除后备状态 | [continuity-contract.md](references/continuity-contract.md) | -GitHub Issue 始终是持久事实来源；确需恢复才使用 [current-task.md](assets/current-task.md) 创建 `.scd/tasks/current.md`，只保存恢复增量和一个下一行动，停止/压缩前更新，不暂存提交；合并后按清理所有权删除。 +计划负责方案与批准版本，GitHub Issue负责执行验收；确需恢复才使用 [current-task.md](assets/current-task.md) 创建 `.scd/tasks/current.md`，只保存恢复增量和一个下一行动，停止/压缩前更新，不暂存提交；合并后按清理所有权删除。 自然交接只报告已合并结果/PR、直接验证、独立结论/Issue 状态及剩余未验证边界，不宣读流程。必须明确说明独立验收子智能体是否实际调用、返回结论及证据引用；页面任务同时说明交互与视觉需求的验证结果，不得把工程测试通过写成 UI 验收通过。 diff --git a/skills/scd-quickdev/agents/openai.yaml b/skills/scd-quickdev/agents/openai.yaml index 7f754ff..fbe46ac 100644 --- a/skills/scd-quickdev/agents/openai.yaml +++ b/skills/scd-quickdev/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 快速开发" short_description: "基于 Issue 完成编码、验证与 PR 合并" - default_prompt: "使用 $scd-quickdev，从 GitHub Issue 开始交付这项仓库变更，完成工程验证、独立验收和符合条件的 PR 合并。" + default_prompt: "使用 $scd-quickdev，从 GitHub Issue 开始交付这项仓库变更，完成工程验证、独立验收和符合条件的 PR 合并。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-quickdev/assets/planning/architecture.md b/skills/scd-quickdev/assets/planning/architecture.md new file mode 100644 index 0000000..445a39e --- /dev/null +++ b/skills/scd-quickdev/assets/planning/architecture.md @@ -0,0 +1,11 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 架构增量 + +<既有基线精确引用、备选方案、具体技术选择、影响、兼容性及待确认项> diff --git a/skills/scd-quickdev/assets/planning/decisions.md b/skills/scd-quickdev/assets/planning/decisions.md new file mode 100644 index 0000000..6a1d3dd --- /dev/null +++ b/skills/scd-quickdev/assets/planning/decisions.md @@ -0,0 +1,19 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 决策与事件 + +- 事件ID：<填写> +- 类型：<决策/批准/开工/变更/完成> +- 文件及文档版本：<精确清单> +- 目标Git SHA：<此前已存在的完整提交，不自引用> +- 用户实际依据：<简短原文及上下文，不编造消息链接> +- 任务或Issue范围：<填写> +- occurred_at：null # 原始时间未知时说明原因 +- recorded_at：<实际记录时间+08:00> +- 未决选择：<逐项列出，漏答保持待定> diff --git a/skills/scd-quickdev/assets/planning/implementation.md b/skills/scd-quickdev/assets/planning/implementation.md new file mode 100644 index 0000000..11df5de --- /dev/null +++ b/skills/scd-quickdev/assets/planning/implementation.md @@ -0,0 +1,11 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 实施计划 + +<具体文件/模块、任务顺序、依赖、验证、交付、风险及停止条件> diff --git a/skills/scd-quickdev/assets/planning/plan.md b/skills/scd-quickdev/assets/planning/plan.md new file mode 100644 index 0000000..e8adc22 --- /dev/null +++ b/skills/scd-quickdev/assets/planning/plan.md @@ -0,0 +1,14 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 任务索引 + +- 任务与Issue：<填写> +- 所需文档及版本：<按需列出> +- 基线来源：<精确文件与Git版本> +- 批准与开工事件： diff --git a/skills/scd-quickdev/assets/planning/requirements.md b/skills/scd-quickdev/assets/planning/requirements.md new file mode 100644 index 0000000..19b70ac --- /dev/null +++ b/skills/scd-quickdev/assets/planning/requirements.md @@ -0,0 +1,11 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 需求与来源 + +<范围、验收定义、需求标识、来源和待决问题> diff --git a/skills/scd-quickdev/assets/planning/ux.md b/skills/scd-quickdev/assets/planning/ux.md new file mode 100644 index 0000000..5f0633b --- /dev/null +++ b/skills/scd-quickdev/assets/planning/ux.md @@ -0,0 +1,11 @@ +--- +status: draft +version: 1 +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +recorded_timezone: Asia/Shanghai +--- + +# 体验增量 + +<既有基线精确引用、旅程、体验选择、视觉产物引用和待确认项> diff --git a/skills/scd-quickdev/references/continuity-contract.md b/skills/scd-quickdev/references/continuity-contract.md index fafd8aa..ca908de 100644 --- a/skills/scd-quickdev/references/continuity-contract.md +++ b/skills/scd-quickdev/references/continuity-contract.md @@ -47,7 +47,7 @@ updated_at: 2026-07-27T12:34:56+08:00 - 未完成回合结束前，让新 Agent 能够仅依赖 Issue、仓库和记录继续，无需对话转录。 - 受阻时写明缺失权限、输入或环境条件。 - 合并后把持久证据提升到 Issue 或拉取请求，再删除后备记录。 -- 不得自动暂存、自动提交记录，也不得为其增加忽略规则。 +- 不得自动暂存或提交临时记录；仅对 `.scd/tasks/current.md`、`.scd/cache/`、`.scd/logs/` 使用窄范围忽略规则。 ## Hook 边界 diff --git a/skills/scd-quickdev/references/extended-issue.md b/skills/scd-quickdev/references/extended-issue.md index 8243859..728cee2 100644 --- a/skills/scd-quickdev/references/extended-issue.md +++ b/skills/scd-quickdev/references/extended-issue.md @@ -15,7 +15,7 @@ 需要独立说明多个边界或技术决定时，可将基础模板拆为： - `## 结果`、`## 用户问题`、`## 范围内`、`## 范围外`； -- `## 已确认决策`、`## 方案确认`（需要确认：是，或否；状态：已确认，或默认免确认）； +- `## 已确认决策`、`## 方案确认`（需要确认：是；状态：待确认或已确认；计划Git版本与开工授权引用）； - `## 失败与边界场景`、`## 验收条件`、`## 实施方案`、`## 实施任务`； - `## 验证`、`## 完成审计`、`## 未知项`。 diff --git a/skills/scd-quickdev/references/issue-delivery-contract.md b/skills/scd-quickdev/references/issue-delivery-contract.md index 31b6c6d..b883a47 100644 --- a/skills/scd-quickdev/references/issue-delivery-contract.md +++ b/skills/scd-quickdev/references/issue-delivery-contract.md @@ -4,7 +4,7 @@ ## 事实来源 -对于仓库交付，中文 GitHub Issue 是选中交付边界、验收和验证衔接点的唯一事实来源。拉取请求保存实施与验证证据。本地 SCD 状态只用于临时恢复。 +对于仓库交付，中文 GitHub Issue 负责选中交付边界、执行、验收和验证衔接点；任务计划负责需求方案与批准版本，Issue引用精确Git版本。拉取请求保存实施与验证证据。current.md只用于临时恢复。 全新产品存在已确认 `.scd/product/prd.md` 时，该 PRD 继续负责产品级原因、用户、问题、MVP 范围、`FR-*` 需求和成功指标。Delivery Issue 引用已确认版本和它实施的需求，不复制或悄悄覆盖 PRD。 @@ -12,13 +12,9 @@ 仓库没有 GitHub 远程或已认证写入路径时，在实施前停止并报告阻塞。清晰用户请求可以授权普通 Issue 写入，但不能创造缺失权限。 -## 方案确认偏好 +## 方案与开工确认 -默认不询问用户是否要评审本次交付的完整 Issue 草案、实施方案和任务清单。用户没有主动要求确认时，自主创建或更新中文 Issue 并实施，同时记录 `需要确认：否`、`状态：默认免确认`。沉默、普通实施请求或“开始做”都不能解释为要求确认。 - -只有用户主动要求先看或先确认方案、Issue 或任务时，才启用方案确认门。展示可确认草案前必须先进行只读仓库检查，然后展示完整中文 Issue 正文草案并等待。用户明确确认前，不得创建或更新 Issue、修改仓库文件或实施；确认后记录 `需要确认：是`、`状态：已确认`。 - -对于现有 Issue，展示精确拟修改内容，而不是抽象摘要。用户已经选择确认时，已确认实施方案、任务清单、范围或验收发生实质变化，写入或实施前必须再次明确确认。此偏好不会创建本地 `plan.md`；Issue 继续作为唯一持久交付计划。 +遵守[计划确认契约](planning-contract.md)。先只读调查，按需保存草稿、需求、具体技术选择与实施计划；展示已有Git提交及精确文件清单，用户明确批准并授权开工后实施。Issue引用计划及批准事件，负责执行与验收，不独占设计权威。已有确认不重复询问；漏答保持待定，实质变更重确认。 ## Issue 输出语言 @@ -36,7 +32,7 @@ QuickDev 创建或更新的全部 Issue 输出必须使用中文，包括标题 ## 方案与确认 实施方案：最小技术方向与受影响边界。 -方案确认：需要确认：否；状态：默认免确认。 +方案确认：需要确认：是；状态：<待确认/已确认>；计划：<路径与Git SHA>；开工授权：<事件引用>。 ## 验收与任务 diff --git a/skills/scd-quickdev/references/planning-contract.md b/skills/scd-quickdev/references/planning-contract.md new file mode 100644 index 0000000..68b6f95 --- /dev/null +++ b/skills/scd-quickdev/references/planning-contract.md @@ -0,0 +1,51 @@ +# 计划、确认与开工契约 + +## 适用边界 + +功能开发、缺陷修复、架构和交互设计、再工程及实际修复默认遵守本契约。纯状态查询、代码阅读和只读诊断不创建开发计划。Next只读展示批准版本、待确认项和可执行范围。Project只建立执行拓扑，不执行实现。Knowledge、Interview、Evolve保留显式调用、专用确认、私人存储及更窄写入边界；Evolve试验不授权提交、推送、PR或合并。 + +## 先调查，再逐项确认 + +先只读调查事实，再分轮展示当前未决选择、具体影响、推荐及理由，每轮问题互不依赖。功能、交互、架构、依赖、数据模型、接口、模块组织和测试策略等具体技术选择均由用户确认，不以可逆、惯例或模型自信代选。 + +漏答保持待定，不以临时假设或推荐解除依赖；可继续独立只读调查。已批准计划明确的操作不重复询问。完整方案统一确认可覆盖其中逐项展示的具体选择；部分回答只批准明确选择的部分。普通“继续”只延续已批准范围，不批准未展示方案、新图版本或计划修订。 + +## 持久文件与权威 + +使用 `.scd/plans/YYYYMMDD-HHMMSS-<任务名>/`，实际北京时间创建，同秒重名追加短序号。按需从 `../assets/planning/` 使用六份模板：plan.md为索引，requirements.md保存需求，architecture.md保存架构增量，ux.md保存体验增量，implementation.md保存文件、顺序、依赖、验证、交付和风险，decisions.md追加决策与事件。不要生成不适用的空文档；实际开发必须有实施计划。 + +计划负责方案与批准版本；Issue负责执行状态、任务处置、验收证据和交付，引用计划文件及Git版本，不独立改设计。保留现有PRD、系统架构、机器接口契约位置，引用精确版本并说明本次增量，实施验收后更新基线。冲突先解决并确认。 + +## Git与批准 + +文档状态使用draft、approved、superseded及整数version。ready只表示工程或语义就绪，不等于用户批准或开工授权。 + +待审阅内容先提交本地计划分支，展示精确文件、文档版本及完整Git SHA。批准后在后续提交追加事件，引用此前已存在的提交与精确文件清单，不能自引用。Git字段不能单独证明用户真实批准。 + +事件记录ID、类型、文件/版本、目标Git SHA、用户实际确认依据、occurred_at和recorded_at；开工授权还绑定任务或Issue范围。没有消息ID时保存简短原文及上下文，不编造链接。方案批准与开工授权分别记录；明确指向当前版本的“确认本方案并开始实施”可同时授予两者。 + +方案实质变化或出现未覆盖技术选择时，暂停受影响工作、展示差异及影响、询问确认；保留旧批准事件，受影响文档递增version回到draft。未变化决策可复用。管理记录追加或普通实施代码提交不自动使批准失效。 + +## 时间、保存与恢复 + +所有新记录使用Asia/Shanghai、精确到秒、ISO-8601的+08:00；文档包含created_at、updated_at、version、status。创建、修订、决策、批准、开工和完成均关联版本。Agent事件读取实际时钟；用户事件原始时间未知时occurred_at为空并说明原因，recorded_at为实际记录时间。不得回填假时间或提前写完成，提交时间不等于用户确认时间。 + +每轮已确认决定落盘并提交本地计划分支。长期需求、方案、决策和证据摘要纳入Git，用历史还原，不复制versions/vN目录。仅忽略 `.scd/tasks/current.md`、`.scd/cache/`、`.scd/logs/`；不忽略整个.scd，不批量删除或取消跟踪已有文件。消费者更宽忽略或不明临时位置先展示调整并确认。 + +current.md仅保存恢复增量，引用计划与Issue；清理前将有价值决定和证据写回持久记录。旧任务缺失计划或批准关联时，保留已有基线、Issue与提交，整理当前真实方案确认后恢复受影响开发，不补造历史批准、不批量迁移。 + +## 开工与合并前清单 + +- 所需文档齐全，实施计划具体，无影响实施的未决选择。 +- 当前方案对应获批Git版本及文件清单，实际用户依据可追溯，明确开工授权覆盖本Issue。 +- Issue引用一致，适用设计和接口就绪；ready与用户批准分别核对。 +- 合并前复核实际差异与获批范围、变更重确认、时间真实性和三本账。 +- 独立新上下文验收亲读批准依据、精确版本和差异，保留真实页面、高风险与更窄权限门。 + +以上仅技能指令与检查清单，不新增运行时校验器、Schema检查脚本、依赖或Hook。文本回归与受控情景不保证所有宿主/模型每次遵从。获批范围内连续完成开发、验证、独立验收及普通交付。 + +## 批准版本的持久可达性 + +交付和清理必须保证每个引用的获批计划Git提交及精确文件在持久分支和新克隆中可还原。普通merge保留计划提交历史；合并后核对获批SHA是默认分支祖先，并从独立新克隆用git show读取每个SHA:file。最终树或等价diff相同不能替代中间批准历史。 + +删除最后引用前先确认上述持久可达性。若消费者仅允许会丢失批准历史的squash/rebase，停止受影响交付和清理，向用户展示保留方案及影响供确认；不得擅自创建tag、改仓库保护或以对象暂存在本地为长期证据。未取得保留方案确认或无法从新克隆恢复时保持BLOCKED。 diff --git a/skills/scd-quickdev/references/release-contract.md b/skills/scd-quickdev/references/release-contract.md index f9c64c9..36cce43 100644 --- a/skills/scd-quickdev/references/release-contract.md +++ b/skills/scd-quickdev/references/release-contract.md @@ -32,14 +32,16 @@ Agent 负责工程验收： ## 合并后任务资源清理 +先执行[批准版本持久可达性检查](planning-contract.md)：核对每个获批SHA及文件可由持久分支和独立新克隆还原。普通merge保留历史；若只能用丢失该历史的squash/rebase，停止并展示保留方案供用户确认，不擅自创建tag或改保护。等价diff不能替代批准历史；未通过时BLOCKED，不删除最后引用。 + 清理只针对当前 Issue 拥有的精确资源，不得扫描或删除历史残留、兄弟通道或其他用户工作。合并后的清理顺序如下： 1. 无论合并命令退出码为何，都重新读取拉取请求的实时状态、head SHA 和合并提交。合并命令返回非零不代表拉取请求未合并；确认已经合并后不得重复合并。 -2. 同步本地默认分支并读取远端默认分支，确认它包含独立验收过的任务差异。squash 或 rebase merge 不要求任务 head 成为 `main` 祖先；使用已合并拉取请求、合并提交和 `main` 上的任务差异作为证据。 +2. 上述批准历史门通过后，同步本地默认分支并读取远端默认分支，确认它包含独立验收过的任务差异。squash 或 rebase merge 不要求任务 head 成为 `main` 祖先；使用已合并拉取请求、合并提交和 `main` 上的任务差异作为证据。 3. 检查任务工作树的未提交状态。存在修改、暂存或未跟踪内容时不得强制删除；把精确状态记录为 `BLOCKED` 并保持 Issue 开放。 4. 工作树干净时，先删除精确任务工作树，再修剪失效工作树元数据。不得先强删仍被工作树占用的分支。 -5. 删除本地任务分支。普通删除因 squash/rebase 祖先关系拒绝时，只有在拉取请求已合并、`main` 差异已验证、工作树已删除且分支 tip 与已验收 head 一致后，才可强制删除该精确本地分支。 -6. 显式删除远端任务分支。不得仅依赖 `gh pr merge --delete-branch`，因为远端合并可能成功而本地清理仍失败。 +5. 再次核对获批SHA及文件的新克隆恢复证据后，删除本地任务分支。普通删除因 squash/rebase 祖先关系拒绝时，只有在拉取请求已合并、`main` 差异已验证、工作树已删除且分支 tip 与已验收 head 一致后，才可强制删除该精确本地分支。 +6. 确认不会删除获批SHA的最后持久引用后，显式删除远端任务分支。不得仅依赖 `gh pr merge --delete-branch`，因为远端合并可能成功而本地清理仍失败。 7. 删除本次任务拥有的 `.scd/tasks/current.md` 或其他明确连续性状态；不存在时记录不适用。 8. 重新验证：任务工作树不存在，本地任务分支不存在，远端任务分支不存在，本地 `main` 与远端默认分支一致。把命令和结果写入清理状态。 @@ -79,3 +81,7 @@ Agent 负责工程验收： 页面差异存在但浏览器、目标环境、必需状态或视觉证据不可用时只能返回 `BLOCKED`。`PASS` 授权符合条件的合并，以及确认远端 `main` 包含独立验收版本、重新读取 Issue 并确认三本账仍闭合后显式关闭 Issue。`FAIL` 把证据返回实施，保持 Issue 开放，并要求修复后再次独立验收。`BLOCKED` 记录缺失环境或依赖并保持 Issue 开放。合并、部署或环境状态可能改变观察结果时，关闭前在 `main` 上重新运行受影响验收路径。 父 Agent 负责交付编排，独立验收者负责验收结论。只有上述高风险边界或仓库强制人工门仍需人工确认。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-quickdev/references/scope-contract.md b/skills/scd-quickdev/references/scope-contract.md index dcd9837..3d8c128 100644 --- a/skills/scd-quickdev/references/scope-contract.md +++ b/skills/scd-quickdev/references/scope-contract.md @@ -4,7 +4,7 @@ ## 实质歧义测试 -只有在无用户参与的选择可能改变以下内容时才提问： +以下是需要产品歧义澄清的表面，不是具体技术选择确认的排他条件。模块组织、测试策略等具体技术选择也须按计划契约确认；已批准选择不重复询问。产品歧义包括： - 可见产品行为； - 公共 API 或持久数据； @@ -13,7 +13,7 @@ - 不可逆或外部操作； - 哪个独立需求属于范围内。 -不要仅因多种实施都有效而提问。检查仓库，选择符合现有惯例的最小方案并继续。 +检查仓库，展示可行的具体技术选项、影响、推荐与理由，确认后推进。 ## 派生范围 @@ -24,7 +24,7 @@ 3. **验收：** 如何检查结果。 4. **位置：** 仓库证据表明变更属于何处。 -普通工作只在对话中保留这些内容。把已确认交付边界和验收契约写入中文 GitHub Issue。产品受已确认全新产品 PRD 管理时，引用其版本和适用 `FR-*` 标识，不复制或重新定义产品基线。 +普通工作按共享计划契约持久保存这些内容。把已确认交付边界和验收契约写入中文 GitHub Issue。产品受已确认全新产品 PRD 管理时，引用其版本和适用 `FR-*` 标识，不复制或重新定义产品基线。 ## Discovery 交接 @@ -35,10 +35,10 @@ 1. 把交付结果、边界、决策和验收视为权威； 2. 它引用已确认 PRD 时，把 PRD 视为产品级范围权威，并确认版本和 `FR-*` 追溯； 3. 保留稳定验收标识； -4. 对可逆实施细节自主选择，无需再次确认； +4. 对可逆实施细节也先确认具体选择；已批准项不重复确认； 5. 改变任何产品可见契约前，通过 Discovery 更新 PRD 和 Issue。 -完整 Issue 已随实施请求确认时，不要让用户重复确认。 +完整Issue已确认的选择不重复询问；仍须核对精确计划批准及开工授权，不能以Issue选择替代。 只有新证据改变以下内容时才返回 Discovery： @@ -59,7 +59,7 @@ - 影响重大的功能局部技术设计使用 `.scd/designs/.md`； - 没有仓库惯例时，新的共享机器可读契约放在可见根目录 `contracts/`。 -不要创建永久实施计划。任务清单保存在 Issue；只有需要时才把临时恢复状态保存在 `.scd/tasks/current.md`。 +按需保存持久实施计划，Issue引用精确批准版本并保存执行任务清单；只有需要时才把临时恢复状态保存在 `.scd/tasks/current.md`。 ## 搜索漏斗 @@ -78,7 +78,7 @@ 实施证据与原解释冲突时： - 更新方案，不要机械执行原方案； -- 只有新路径改变产品结果或权限边界时才更新 Issue 并请求决策； +- 新技术路径或实施计划实质变化时先修订计划并请求确认，再同步Issue； - 无关缺陷和清理作为观察报告，不得悄悄加入范围。 ## 就绪设计与项目输入 diff --git a/skills/scd-reengineering/SKILL.md b/skills/scd-reengineering/SKILL.md index 1528674..f6c1136 100644 --- a/skills/scd-reengineering/SKILL.md +++ b/skills/scd-reengineering/SKILL.md @@ -19,6 +19,8 @@ description: "通过有证据支持的项目级重构或新实施，对现有仓 - 独立验收和集成门负责完成证据； - 生产切换和其他高风险操作继续保留人工门。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 遵循故障关闭状态机 只能按以下状态推进： diff --git a/skills/scd-reengineering/references/reengineering-contract.md b/skills/scd-reengineering/references/reengineering-contract.md index f964119..46b9ba7 100644 --- a/skills/scd-reengineering/references/reengineering-contract.md +++ b/skills/scd-reengineering/references/reengineering-contract.md @@ -93,7 +93,7 @@ Issue 中不得保存凭据、令牌、私有源码、个人数据或大量捕 - 许可证与署名不确定性 - 切换与退役人工门 -Initiative 继续是项目事实。不得创建第二个本地再工程计划或等价数据库。 +Initiative 继续是项目事实。任务方案与批准版本保存于共享计划目录，不创建第二执行数据库。 ## 交付切片 @@ -153,3 +153,7 @@ Thinloop 记录证据和阻塞，不判断许可证是否允许预期用途。 - 只有兼容性边界触发时才做性能或资源比较。 记录环境和非确定性。不得用汇总通过百分比隐藏缺失等价证据。每项能力都必须以 `PASS`、`FAIL`、`UNVERIFIED` 或 `BLOCKED` 结束，并附直接证据。 + +## 计划批准核对 + +按共享计划契约核对持久计划的精确Git版本、文件清单、实际用户批准依据和开工范围。ready不是用户批准；未答保持待定，未覆盖的技术选择或实质变化重新确认。只读审计/状态查询不创建计划，不替用户批准。 diff --git a/skills/scd-ui-polish/SKILL.md b/skills/scd-ui-polish/SKILL.md index c33b5c7..aeaadc1 100644 --- a/skills/scd-ui-polish/SKILL.md +++ b/skills/scd-ui-polish/SKILL.md @@ -9,6 +9,8 @@ description: "优化已有 Web 页面的视觉质量，按排版、留白、层 把已有页面优化到与产品用途、内容和品牌相符的精细程度，并用实际页面和前后对比证明改进。独立调用本技能即可开始；用户要求实施时继续完成代码交付，不停在建议清单。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 检查现有页面 先读适用 `AGENTS.md`、`CLAUDE.md`、当前任务或 Issue、已确认视觉来源和附近组件。确定目标页面与修改边界；可从当前上下文确定时不重复询问。 @@ -21,7 +23,7 @@ description: "优化已有 Web 页面的视觉质量，按排版、留白、层 沿用有效的品牌、设计系统和已确认视觉稿，提出统一的排版、色彩、布局和辨识点增量。按共用参考实际查看适用的优秀作品，不把奖项名称当作已完成对标。 -明确局部优化直接推进；整体改版、高成本视觉方向或改变已有 UX 契约的工作先使用 [scd-uiux](../scd-uiux/SKILL.md) 处理必要设计与已有确认门。不要重建 PRD，也不要因为追求视觉效果擅改内容、功能或业务规则。 +明确局部优化先确认具体方案和实施计划；整体改版、高成本视觉方向或改变已有 UX 契约的工作先使用 [scd-uiux](../scd-uiux/SKILL.md) 处理必要设计与已有确认门。不要重建 PRD，也不要因为追求视觉效果擅改内容、功能或业务规则。 ## 实施与复查 diff --git a/skills/scd-ui-polish/agents/openai.yaml b/skills/scd-ui-polish/agents/openai.yaml index 600dbbf..54a3571 100644 --- a/skills/scd-ui-polish/agents/openai.yaml +++ b/skills/scd-ui-polish/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD 页面优化" short_description: "检查已有网页并打磨视觉、响应式与交互细节，用真实页面前后对比验证改善" - default_prompt: "使用 $scd-ui-polish 优化这个已有页面，检查实际渲染与交互，完成视觉打磨并展示修改前后对比。" + default_prompt: "使用 $scd-ui-polish 优化这个已有页面，检查实际渲染与交互，完成视觉打磨并展示修改前后对比。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-uiux/SKILL.md b/skills/scd-uiux/SKILL.md index 0509f06..db7f637 100644 --- a/skills/scd-uiux/SKILL.md +++ b/skills/scd-uiux/SKILL.md @@ -9,11 +9,13 @@ description: "在生产实施前设计或完善 Web 产品的用户体验和界 让 Web 体验清晰到足以评审和实施，但不把每次界面变更都变成设计项目。本技能设计行为与呈现；生产代码交给 `scd-quickdev`。 +开始设计或实施前读取[计划确认契约](../scd-quickdev/references/planning-contract.md)；具体选择先确认，ready不替代批准。只读查询/审计不创建开发计划，各治理技能更窄权限继续有效。 + ## 选择最轻量且充分的路径 检查请求和仓库后，在内部选择： -- **直接实施：** UI 变更及其可观察结果已经清晰。不提 UX 问题、不创建产物，直接交给 `scd-quickdev`。 +- **直接实施：** UI 变更及其可观察结果已经清晰。无需完整UX设计，交给QuickDev确认具体方案和实施计划。 - **聚焦设计：** 一个旅程、界面或交互需要设计。只解决这一切片，并只保留它所需的交接内容。 - **产品体验：** 重 UI 型 0 到 1 交付需要一致的 Web 体验。要求产品核心已经稳定，然后覆盖已触发的体验界面。 - **体验验证：** 对现有 UX 契约或原型执行只读的完整性、一致性、无障碍或实施就绪度审计。 @@ -78,7 +80,7 @@ description: "在生产实施前设计或完善 Web 产品的用户体验和界 视觉产物和 UX 契约共同构成前端交接：UX 契约负责行为、状态和响应式规则，视觉产物负责已标记视口中的布局、层级、密度和外观。二者冲突时保持 `status: draft`，明确差异并统一后再继续；不得静默选择一方，也不得让前端自行猜测。 -重大新页面、整体改版或高成本视觉方向必须把完整视觉交付和 UX 契约展示给用户，取得一次明确确认后才能设为 `ready`。与 Discovery 组合时，把它并入关联 Delivery Issue 的一次合并确认；普通局部设计在不涉及这些高成本取舍时仍可自主完成就绪审查。这是设计交付确认，不恢复 QuickDev 的默认方案确认门。 +重大新页面、整体改版或高成本视觉方向必须把完整视觉交付和 UX 契约展示给用户，取得一次明确确认后才能设为 `ready`。与 Discovery 组合时，把它并入关联 Delivery Issue 的一次合并确认；普通局部设计也须确认具体选择；就绪审查不代替方案批准或开工授权。 UX 契约还必须单独决定是否需要“实现后最终视觉确认”。普通页面和明确局部变更默认“不需要”；整体改版、高保真品牌表达，或布局、密度、视觉语言本身属于主观关键验收时标记“需要”，并说明触发原因。该确认在 QuickDev 生成真实页面对照证据后执行，不阻止设计契约先进入 `ready`，但在确认完成前阻止最终交付和关闭 Issue。 @@ -99,11 +101,11 @@ UIUX 可以提出接口需求，但不得单方面定稿端点、传输模式、 ## 只保留有用的设计状态 -简短讨论和清晰的局部增量只保留在对话中。仓库工作需要持久评审或实施交接时，优先使用现有设计文档位置；否则从 `assets/ux-contract.md` 创建一份 `.scd/ux/.md`，并把可渲染视觉文件放在 `.scd/ux//visuals/`，有复杂交互时把非生产原型放在 `.scd/ux//prototype/`。 +纯只读讨论可留在对话中；实际设计决策和局部增量写入任务计划，保存逐轮确认与Git历史。仓库工作需要持久评审或实施交接时，优先使用现有设计文档位置；否则从 `assets/ux-contract.md` 创建一份 `.scd/ux/.md`，并把可渲染视觉文件放在 `.scd/ux//visuals/`，有复杂交互时把非生产原型放在 `.scd/ux//prototype/`。 存在实质性 UX 决策未定时使用 `status: draft`，通过就绪审查后使用 `status: ready`。`ready` 表示 UX 工作一致，不是第二次产品确认。UX 属于 Discovery 组合时，由关联的 Delivery GitHub Issue 承载用户的一次合并确认。 -默认只保留一份 UX 契约。用视觉 ID 链接项目内视觉产物，不要复述它们。只有视觉系统跨交付复用并独立演进时才拆分。不要创建 PRD、前端架构文档、用户故事、Sprint 状态或实施计划。 +默认只保留一份 UX 契约。用视觉 ID 链接项目内视觉产物，不要复述它们。只有视觉系统跨交付复用并独立演进时才拆分。不要创建 PRD、前端架构文档、用户故事、Sprint 状态；开发实施计划由QuickDev按共享契约保存。 ## 审查就绪度并交接 diff --git a/skills/scd-uiux/agents/openai.yaml b/skills/scd-uiux/agents/openai.yaml index ba81ea3..9433709 100644 --- a/skills/scd-uiux/agents/openai.yaml +++ b/skills/scd-uiux/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SCD UIUX 设计" short_description: "直接设计网页体验" - default_prompt: "使用 $scd-uiux，在实施前将这项网页产品行为转化为可评审的交互与界面契约。" + default_prompt: "使用 $scd-uiux，在实施前将这项网页产品行为转化为可评审的交互与界面契约。 读取共享计划确认契约：具体技术选择先确认，批准精确Git计划并授权开工后按范围连续交付；漏答待定，实质变化重确认。只读不创建开发计划，治理更窄边界有效。" diff --git a/skills/scd-uiux/assets/ux-contract.md b/skills/scd-uiux/assets/ux-contract.md index 5117d64..f55e01c 100644 --- a/skills/scd-uiux/assets/ux-contract.md +++ b/skills/scd-uiux/assets/ux-contract.md @@ -3,6 +3,10 @@ managed_by: scd-uiux status: draft sources: - <仓库相对路径或稳定 URL> +created_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +updated_at: <实际北京时间YYYY-MM-DDTHH:mm:ss+08:00> +version: 1 +recorded_timezone: Asia/Shanghai --- # 结果与边界 @@ -61,3 +65,10 @@ sources: - <视觉 ID>：<目标视口、真实渲染证据和允许差异> ## 待定决策 + +## 任务计划与时间追溯 + +- 任务计划：<路径、文件清单及精确Git版本> +- 方案批准/开工授权：<独立事件引用；ready不代表批准> +- occurred_at：<事件真实时间；未知为空并说明> +- recorded_at：<实际记录时间+08:00> diff --git a/skills/scd-uiux/references/experience-contract.md b/skills/scd-uiux/references/experience-contract.md index 99632e1..e1147fd 100644 --- a/skills/scd-uiux/references/experience-contract.md +++ b/skills/scd-uiux/references/experience-contract.md @@ -48,7 +48,7 @@ UX 契约负责用户如何理解和操作已确认的产品行为： 响应式布局真实变化时至少覆盖代表性桌面和窄屏视口。多步骤、有状态或恢复性交互必须链接可点击或可运行的非生产原型。外部 Figma 或其他设计链接只能作为来源，不能替代项目内稳定导出。可编辑源适合保留时同时保留；前端交接至少必须能在无外部权限时查看稳定渲染结果。 -重大新页面、整体改版或高成本视觉方向把确认标记为“需要”，确认前保持 `draft`。普通局部设计可以标记“不需要”。记录确认状态和证据，不保存隐藏推理。 +重大新页面、整体改版或高成本视觉方向把确认标记为“需要”，确认前保持 `draft`。普通局部设计也需要确认具体选择；工程ready与用户批准分别记录。记录确认状态和证据，不保存隐藏推理。 设计确认和实现后确认是两个不同事实：设计确认决定方案是否可实施；实现后最终视觉确认决定真实页面是否符合需要人工判断的视觉目标。整体改版、高保真品牌表达，或布局、密度和视觉语言本身属于关键验收时，把实现后确认标记为“需要”；其他页面默认“不需要”。设计阶段只需确定该标记和理由，不要求尚未存在的生产页面提前确认。 diff --git a/skills/scd-uiux/references/visual-evidence.md b/skills/scd-uiux/references/visual-evidence.md index 2046dd4..00b8054 100644 --- a/skills/scd-uiux/references/visual-evidence.md +++ b/skills/scd-uiux/references/visual-evidence.md @@ -61,6 +61,6 @@ 视觉产物包含偶然或陈旧细节时，明确标注并修订，不得让前端猜测。视觉产物与 UX 契约冲突时同时更新二者，统一前不得标记 `ready`。 -重大新页面、整体改版或高成本视觉方向必须向用户展示完整视觉交付与 UX 契约，并记录一次明确确认。普通局部设计不增加该确认门。 +重大新页面、整体改版或高成本视觉方向必须向用户展示完整视觉交付与 UX 契约，并记录一次明确确认。普通局部设计也按计划契约确认具体选择，ready与批准分别记录。 同时在 UX 契约中决定实现后是否需要再次确认真实页面。整体改版、高保真品牌表达，或布局、密度和视觉语言本身属于主观关键验收时标记“需要”；普通页面标记“不需要”。QuickDev 负责生成按视觉 ID、状态和视口排列的设计与实际页面对照；需要确认时，用户确认前不得关闭 Delivery Issue。 diff --git a/tests/architecture-contract.test.mjs b/tests/architecture-contract.test.mjs index 41861a1..2cea7d7 100644 --- a/tests/architecture-contract.test.mjs +++ b/tests/architecture-contract.test.mjs @@ -18,7 +18,7 @@ test("architecture is composable and keeps clear changes on the direct path", () assert.match(skill, /\*\*产品架构：\*\*/); assert.match(skill, /\*\*架构演进：\*\*/); assert.match(skill, /\*\*架构验证：\*\*/); - assert.match(skill, /不提架构问题、不创建架构产物/); + assert.match(skill, /交给QuickDev确认具体方案和实施计划/); assert.match(skill, /新增一个端点也不足以证明/); }); @@ -107,7 +107,7 @@ test("architecture readiness is not approval and production mutation stays out", assert.match(skill, /不得编写生产业务代码/); assert.match(skill, /执行真实数据迁移/); assert.match(skill, /或部署/); - assert.match(contract, /不是人工确认门/); + assert.match(contract, /用户方案批准及开工授权另按共享计划契约核对/); }); test("architecture templates preserve separate responsibilities", () => { diff --git a/tests/chinese-skill-payload.test.mjs b/tests/chinese-skill-payload.test.mjs index 997979b..be37b9e 100644 --- a/tests/chinese-skill-payload.test.mjs +++ b/tests/chinese-skill-payload.test.mjs @@ -32,7 +32,7 @@ test("全部 Thinloop Skill 文本载荷均包含中文", () => { .flatMap((entry) => collectPayloadFiles(path.join(skillsRoot, entry.name))) .sort(); - assert.equal(files.length, 67); // Shared visual and step communication references. + assert.equal(files.length, 74); // Shared visual and step communication references. for (const file of files) { assert.match(read(file), han, file); } @@ -88,17 +88,11 @@ test("Issue 模板保持中文结构和规范机器标识", () => { assert.doesNotMatch(combined, /^## (?:Outcome|Acceptance|Implementation tasks|Verification)$/m); }); -test("QuickDev 默认免确认且只在用户主动要求时启用确认门", () => { - const quickdev = read("skills/scd-quickdev/SKILL.md"); - const contract = read( - "skills/scd-quickdev/references/issue-delivery-contract.md", - ); - - assert.match( - quickdev, - /默认不询问用户是否要先确认完整的 Issue 草案、实施方案和任务清单/, - ); - assert.match(quickdev, /没有主动要求确认[\s\S]*`状态：默认免确认`/); - assert.match(quickdev, /只有用户主动要求先看或先确认[\s\S]*等待明确确认/); - assert.match(contract, /不会创建本地 `plan\.md`/); +test("QuickDev 默认确认技术计划与开工授权", () => { + const skill = read("skills/scd-quickdev/SKILL.md"); + const contract = read("skills/scd-quickdev/references/planning-contract.md"); + assert.match(skill, /默认先只读调查/); + assert.match(skill, /精确Git版本批准与明确开工授权/); + assert.match(contract, /漏答保持待定/); + assert.match(contract, /此前已存在的提交与精确文件清单/); }); diff --git a/tests/discovery-contract.test.mjs b/tests/discovery-contract.test.mjs index 906c446..34c2457 100644 --- a/tests/discovery-contract.test.mjs +++ b/tests/discovery-contract.test.mjs @@ -14,9 +14,9 @@ test("discovery routes greenfield work without burdening clear changes", () => { const skill = read("skills/scd-discovery/SKILL.md"); assert.match(skill, /全新产品[\s\S]*默认走完整 Discovery/); - assert.match(skill, /\*\*直接实施：\*\*/); + assert.match(skill, /\*\*清晰交付：\*\*/); assert.match(skill, /\*\*单点澄清：\*\*/); - assert.match(skill, /不创建 Discovery 产物、不追加问题/); + assert.match(skill, /无需完整Discovery访谈/); assert.match(skill, /就绪快速路径/); }); @@ -39,7 +39,7 @@ test("discovery requires frontier-round interviewing and explicit approval", () interviewing, /前沿是前置决策已全部落定、彼此互不依赖的未决决策集合/, ); - assert.match(interviewing, /临时假设视为临时落定/); + assert.match(interviewing, /未回答的选择保持待定/); assert.match(interviewing, /## 每轮收敛/); assert.doesNotMatch(interviewing, /每次只请求一个决策/); assert.match(readiness, /静默对抗式审查/); @@ -56,7 +56,7 @@ test("discovery persists approved greenfield PRD without burdening clear changes assert.match(skill, /已确认的全新产品/); assert.match(skill, /\.scd\/product\/prd\.md/); assert.match(skill, /现有产品的清晰变更/); - assert.match(artifacts, /确认前不得创建永久草稿/); + assert.match(artifacts, /任务计划中的requirements草稿及逐轮决策应持久保存/); assert.match(artifacts, /默认分支访问/); assert.match(prd, /status: draft/); assert.match(prd, /version: 1/); @@ -76,13 +76,13 @@ test("discovery persists approved greenfield PRD without burdening clear changes assert.match(artifacts, /GitHub Issue/); assert.match( artifacts, - /现有产品的一项清晰变更只保留一个 GitHub Issue/, + /现有产品的一项清晰变更保存按需任务计划/, ); assert.doesNotMatch(artifacts, /\.scd\/specs\/\.md/); assert.match(artifacts, /## 验收条件/); assert.match(artifacts, /A1：/); assert.match(artifacts, /\.scd\/architecture\.md/); - assert.match(artifacts, /不要创建永久 `implementation-plan\.md`/); + assert.match(artifacts, /保存持久implementation\.md/); }); test("downstream skills consume PRD authority and delivery evidence", () => { diff --git a/tests/planning-contract.test.mjs b/tests/planning-contract.test.mjs new file mode 100644 index 0000000..2c0a5c4 --- /dev/null +++ b/tests/planning-contract.test.mjs @@ -0,0 +1,66 @@ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import test from 'node:test'; +const root = new URL('../', import.meta.url); +const read = file => fs.readFileSync(new URL(file, root), 'utf8'); +const contract = read('skills/scd-quickdev/references/planning-contract.md'); +test('planning contract separates actual approval, Git evidence, and engineering readiness', () => { + for (const marker of ['不能自引用', '此前已存在的提交与精确文件清单', 'Git字段不能单独证明用户真实批准', '方案批准与开工授权分别记录', '漏答保持待定', '普通“继续”只延续已批准范围', '暂停受影响工作', 'occurred_at为空', '不补造历史批准']) assert.ok(contract.includes(marker), marker); +}); +test('all design and delivery entrypoints load the shared readable contract', () => { + for (const name of ['quickdev','discovery','architecture','uiux','project','execute','reengineering','ui-polish','maintenance','next','evolve']) { + const file = `skills/scd-${name}/SKILL.md`; + const text = read(file); + const link = text.match(/\]\(([^)]+planning-contract\.md)\)/)?.[1]; + assert.ok(link, name); + assert.ok(fs.existsSync(new URL(path.posix.join(path.posix.dirname(file), link), root)), name); + } +}); +test('six optional planning templates preserve status, version and real timestamp placeholders', () => { + for (const name of ['plan','requirements','architecture','ux','implementation','decisions']) { + const text = read(`skills/scd-quickdev/assets/planning/${name}.md`); + for (const marker of ['status: draft','version: 1','created_at:', 'updated_at:', 'Asia/Shanghai', '+08:00']) assert.ok(text.includes(marker), `${name}: ${marker}`); + } + const ignore = read('.gitignore'); + for (const line of ['.scd/tasks/current.md','.scd/cache/','.scd/logs/']) assert.ok(ignore.split('\n').includes(line)); + assert.ok(!ignore.split('\n').includes('.scd/')); +}); +test('local design decisions persist and baseline templates have unique time metadata', () => { + for (const name of ['architecture','uiux']) assert.match(read(`skills/scd-${name}/SKILL.md`), /实际设计决策和局部增量写入任务计划/); + for (const file of ['skills/scd-discovery/assets/product-prd.md','skills/scd-architecture/assets/architecture-contract.md','skills/scd-architecture/assets/feature-design.md','skills/scd-architecture/assets/domain-contract.md','skills/scd-uiux/assets/ux-contract.md']) { + const front = read(file).split('---')[1]; + for (const key of ['version','created_at','updated_at','recorded_timezone']) assert.equal([...front.matchAll(new RegExp(`^${key}:`, 'gm'))].length, 1, `${file}: ${key}`); + assert.match(front, /updated_at:.*\+08:00/); + } +}); +test('local routing cannot exempt non-product technical choices from confirmation', () => { + const scope = read('skills/scd-quickdev/references/scope-contract.md'); + assert.match(scope, /不是具体技术选择确认的排他条件/); + assert.doesNotMatch(scope, /只有在无用户参与的选择.*才提问/); + for (const file of ['skills/scd-project/SKILL.md','skills/scd-project/references/project-contract.md']) { + const text = read(file); + assert.match(text, /依赖边或共享技术方案/); + assert.match(text, /即使产品行为不变/); + assert.doesNotMatch(text, /只有产品契约变化时才请求确认|只有受影响结果.*才再次取得确认/); + } + const maintenance = read('skills/scd-maintenance/SKILL.md'); + assert.match(maintenance, /具体技术方案也按计划契约确认/); + assert.doesNotMatch(maintenance, /只有权威选择.*才询问/); +}); +test('release preserves approved Git objects before deleting their final reference', () => { + assert.match(contract, /新克隆/); + assert.match(contract, /git show/); + assert.match(contract, /获批SHA是默认分支祖先/); + assert.match(contract, /不得擅自创建tag、改仓库保护/); + const release = read('skills/scd-quickdev/references/release-contract.md'); + assert.match(release, /未通过时BLOCKED，不删除最后引用/); + assert.match(release, /等价diff不能替代批准历史/); + assert.match(release, /获批SHA及文件的新克隆恢复证据后，删除本地任务分支/); + assert.match(release, /不会删除获批SHA的最后持久引用后，显式删除远端任务分支/); +}); +test('installation retains historical 0.18.2 and separately describes 0.19.0', () => { + const installation = read('docs/installation.md'); + assert.match(installation, /升级到 v0\.18\.2：步骤提示改为/); + assert.match(installation, /升级到 v0\.19\.0：默认先确认具体技术选择/); +}); diff --git a/tests/quickdev-contract.test.mjs b/tests/quickdev-contract.test.mjs index 3565a81..ac17095 100644 --- a/tests/quickdev-contract.test.mjs +++ b/tests/quickdev-contract.test.mjs @@ -34,7 +34,7 @@ function composeGuidance(relativePath) { test("quickdev selects direct, clarify, project, or discovery without forcing ceremony", () => { const skill = composeGuidance("skills/scd-quickdev/SKILL.md"); - assert.match(skill, /\*\*直接实施：\*\*/); + assert.match(skill, /\*\*清晰交付：\*\*/); assert.match(skill, /\*\*单点澄清：\*\*/); assert.match(skill, /\*\*项目规划：\*\*/); assert.match(skill, /\*\*需求发现：\*\*/); @@ -52,14 +52,14 @@ test("quickdev separates product PRD authority from delivery Issue authority", ( assert.match(skill, /中文 GitHub Issue 是选中交付边界与验收的事实来源/); assert.match( issueContract, - /选中交付边界、验收和验证衔接点的唯一事实来源/, + /选中交付边界、执行、验收和验证衔接点/, ); assert.match(issueContract, /已确认 `.scd\/product\/prd\.md`/); assert.match(issueContract, /## 产品追溯/); assert.match(issueContract, /需求：`FR-001`/); assert.match(issueContract, /默认分支访问/); assert.match(skill, /实施期间不得生成或重新定义 PRD/); - assert.match(skill, /清晰的孤立变更和缺陷继续只使用 Issue/); + assert.match(skill, /清晰的孤立变更和缺陷使用任务计划及Issue/); assert.match(issueContract, /## 结果/); assert.match(issueContract, /## 范围内/); assert.match(issueContract, /## 范围外/); @@ -69,42 +69,15 @@ test("quickdev separates product PRD authority from delivery Issue authority", ( assert.doesNotMatch(skill, /\.scd\/specs/); }); -test("quickdev defaults to autonomous delivery and only pauses when the user asks to confirm", () => { - const skill = composeGuidance("skills/scd-quickdev/SKILL.md"); - const issueContract = composeGuidance( - "skills/scd-quickdev/references/issue-delivery-contract.md", - ); - const combined = `${skill}\n${issueContract}`; - - assert.match( - skill, - /默认不询问用户是否要先确认完整的 Issue 草案、实施方案和任务清单/, - ); - assert.match( - skill, - /没有主动要求确认[\s\S]*`需要确认：否`[\s\S]*`状态：默认免确认`[\s\S]*普通自主交付流程/, - ); - assert.match( - skill, - /只有用户主动要求先看或先确认[\s\S]*只读仓库检查[\s\S]*等待明确确认/, - ); - assert.match( - skill, - /确认前不得创建或更新 Issue、修改仓库或开始实施/, - ); - assert.match(skill, /已经选择确认[\s\S]*实质改变[\s\S]*再次取得确认/); - assert.match(combined, /沉默、普通实施请求或“开始做”都不/); - assert.match(issueContract, /## 方案确认/); - assert.match(issueContract, /## 实施方案/); - assert.match(issueContract, /## 实施任务/); - assert.match(issueContract, /需要确认：是，或否/); - assert.match(issueContract, /状态：已确认，或默认免确认/); - assert.doesNotMatch( - combined, - /本次交付是否需要你先确认完整的 Issue 草案、实施方案和任务清单？/, - ); - assert.match(combined, /不是第二次产品确认/); - assert.match(combined, /不[会是]创建本地 `plan\.md`|不是创建 `plan\.md` 的理由/); +test("quickdev requires approved Git plan and implementation authorization", () => { + const skill = read("skills/scd-quickdev/SKILL.md"); + const contract = read("skills/scd-quickdev/references/planning-contract.md"); + assert.match(skill, /精确Git版本批准与明确开工授权/); + assert.match(contract, /漏答保持待定/); + assert.match(contract, /不能自引用/); + assert.match(contract, /暂停受影响工作/); + assert.match(contract, /方案批准与开工授权分别记录/); + assert.doesNotMatch(skill, /状态：默认免确认/); }); test("quickdev writes Issue output in Chinese without translating machine identifiers", () => { @@ -364,7 +337,7 @@ test("quickdev loads short phase references conditionally and offers a compact l assert.match(issue, /清晰、低风险、单交付/); const compact = issue.match(/```markdown\n([\s\S]*?)```/)[1]; assert.equal((compact.match(/^## /gm) || []).length, 5); - for (const marker of ["A1", "T1", "验收闭合", "实施账目", "交付状态", "范围内", "范围外", "状态：默认免确认"]) assert.ok(compact.includes(marker), marker); + for (const marker of ["A1", "T1", "验收闭合", "实施账目", "交付状态", "范围内", "范围外", "状态：<待确认/已确认>"]) assert.ok(compact.includes(marker), marker); assert.doesNotMatch(compact, /N\/A|不适用|产品追溯|页面验收/); assert.match(release, /创建 Issue 阶段不需要读取/); assert.ok(Buffer.byteLength(entry) < 8000, "entry remains a concise router plus essential gates"); diff --git a/tests/uiux-contract.test.mjs b/tests/uiux-contract.test.mjs index 6c3e101..ac98dbf 100644 --- a/tests/uiux-contract.test.mjs +++ b/tests/uiux-contract.test.mjs @@ -17,7 +17,7 @@ test("uiux is composable and keeps clear UI changes on the direct path", () => { assert.match(skill, /\*\*聚焦设计：\*\*/); assert.match(skill, /\*\*产品体验：\*\*/); assert.match(skill, /\*\*体验验证：\*\*/); - assert.match(skill, /不提 UX 问题、不创建产物，直接交给 `scd-quickdev`/); + assert.match(skill, /交给QuickDev确认具体方案和实施计划/); assert.match(skill, /小型 UI 变更也不会因此进入“产品体验”路径/); }); @@ -85,14 +85,14 @@ test("uiux blocks readiness on visual conflict or missing required confirmation" assert.match(combined, /确认前保持 `draft`|取得一次明确确认后才能设为 `ready`/); assert.match(combined, /冲突时保持 `status: draft`|冲突时保持 `draft`/); assert.match(combined, /不得静默选择一方|不得静默指定一方优先/); - assert.match(skill, /不恢复 QuickDev 的默认方案确认门/); + assert.match(skill, /就绪审查不代替方案批准或开工授权/); }); test("uiux keeps trivial local UI changes on the direct path without mandatory mockups", () => { const skill = read("skills/scd-uiux/SKILL.md"); assert.match(skill, /文案、颜色、间距或局部组件变更[\s\S]*不强制扩大成设计项目/); - assert.match(skill, /不提 UX 问题、不创建产物，直接交给 `scd-quickdev`/); + assert.match(skill, /交给QuickDev确认具体方案和实施计划/); }); test("uiux keeps the shared frontend-backend contract jointly owned", () => {