dsh-gate-agent 0.0.0-stage → 0.1.0

package/skills/gate-fix-bug/assets/worker-briefs/fix-bug-review.md

@@ -0,0 +1,23 @@
+# gate-fix-bug independent review worker
+
+```markdown
+你是 Gate 的独立 review worker。只评审 fix worker 的修复 diff，返回 findings，不修复。
+
+## 修复基线
+<fix 前 commit / 固定点、当前 diff 范围>
+
+## 选定失败与合同
+<原失败项、期望行为、验收/合同引用>
+
+## 修复报告
+<fix worker 的根因、改动、回归测试和验证结果>
+
+## 评审范围
+Standards / Spec 两轴；重点确认修复没有改变合同、没有扩大范围、没有削弱测试。
+
+## 输出
+返回 standards、spec 两组 findings，注明证据与严重度；不修改代码，不提交。
+```
+
+
+

package/skills/gate-fix-bug/assets/worker-briefs/gate-fix-bug.md

@@ -0,0 +1,33 @@
+# /gate-fix-bug — fix worker
+
+```markdown
+你是 Gate 的 fix-bug worker。使用 gate-fix-bug 完成这次已授权的实现缺陷修复；执行 Process 1-9，返回修复 receipt。独立 review 由主 agent 另派，不要自行完成 Step 10-12。
+
+## 选定失败
+<现象、复现步骤、最新结果>
+
+## 期望行为与合同
+<需求/验收/设计决定引用>
+
+## 证据/诊断
+<日志、失败测试、已有报告>
+
+## 修复范围
+<只修什么；明确不修什么>
+
+## 基线
+<commit、diff、相关文件>
+
+## 约束
+- 只修选定缺陷；不重构、不改产品行为、不加依赖、不做无关清理。
+- 先复现；回归测试应先失败，修复后通过。
+- 不通过削弱/删除有效测试让套件变绿。
+- 若发现是测试/合同/设计/环境问题，停止并报告属主。
+- 只执行 Process 1-9；不自行 review，不提交。
+
+## 验证
+<复现命令、相关测试、类型检查/构建>
+```
+
+
+

package/skills/gate-handoff/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: gate-handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+
+
+
+

package/skills/gate-implement/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gate-implement
+description: Gate 实现方法：主 agent 读取后提炼任务并派发；subagent worker 不加载技能。
+user-invocable: false
+---
+
+## Main agent use
+
+主 agent 在派发前自行读取本方法，给 subagent worker 一份自包含任务：已接受的范围、约束、验收检查和实现规则。subagent worker 不应加载本技能或其他 gate 方法文件。
+
+任务模板：本技能 `assets/worker-briefs/gate-enter-implement.md`。
+
+## 实现
+
+## 1. 入口条件
+
+实现已接受工作项（proposed Agent Note）的选定范围。编码前读取其范围、验收条件与引用的设计章节。
+
+实现前检查范围、验收条件、必需决定、批准证据、未解决 blocker，以及该范围的执行授权。复用有效证据，不重复确认。把已确认的范围和决定同步给各自属主；未解决的重要决定按项目的讨论、授权和 gate 规则返回 discuss。仅记录状态或位置不构成就绪或授权。
+
+## 2. 按需拆分
+
+通过 Implementation Gate 后，只在确实需要拆分时创建 implementation ticket。ticket 的存在不是进入实现的前提。
+
+工作适合一个连贯执行单元时直接实现。
+
+工作过大、存在有意义的独立切片或依赖时，读取 [tickets.md](./tickets.md) 。
+
+不要为了枚举编码步骤而创建 ticket。
+
+## 3. 执行
+
+按工作项的范围、验收条件、引用要求、已接受设计和架构决定实现。
+
+使用既有架构、约定、接口和领域语言，除非权威设计明确改变。
+
+如果实现暴露出未解决的产品、领域、架构、接口、兼容性或其他合同决定，停止受影响实现，并向主 agent 返回 receipt 和该决定。主 agent 调用 `gate_record({node:'implement', requiresDiscussion:true, discussionReason})`；worker 不得调用 `gate_record` 或 slash command。决定未解决前先讨论，不做新的 planning/implement 授权，也不继续受影响代码。
+
+### 实现期测试
+
+按改动需要编写或更新测试。测试优先能改善反馈或明确行为时使用；采用时加载 `gate-tdd` 技能并遵循其流程。
+
+工作时运行聚焦测试和相关静态检查。
+
+### 实现 findings
+
+gate 可能返回实质 findings。按属主处理：
+
+| Finding | 路由 |
+| --- | --- |
+| 当前实现缺失或违反已同意合同 | 在当前实现中修复 |
+| 同一已同意工作需要额外执行单元 | 增加或更新 implementation ticket |
+| 产品或技术合同必须改变或从未解决 | 停止受影响工作，把决定 blocker 返回主 agent；主 agent 调 `gate_record` 带 `requiresDiscussion:true`；新 planning 需要授权 |
+| 与已同意工作无关 | 不自动扩大范围 |
+
+没有“顺手修一下”的无关工作路径。
+
+对属于本实现的 findings，在当前实现中修复，重跑受影响测试和静态检查，并在下一次 receipt 报告每项处置。没有证据不要标记已解决。
+
+## 4. Receipt 与交接
+
+实现完成的条件：
+
+- 授权范围已实现
+- 必需 ticket 已完成
+- 相关实现期检查通过
+- 实质 findings 已解决或明确报告为 blocked
+- 改动已准备好进入 `gate-verify`
+
+返回 receipt，包含：
+
+- 改动文件与覆盖范围
+- 运行的测试和静态检查及结果
+- 每项 finding 的处置
+- 剩余风险、blocker 或需要决定的点
+
+不要执行 `gate-verify`、不要把工作项标完成、不要推进 gate。verify 节点和最终完成由 gate 负责。
+
+
+
+
+

package/skills/gate-implement/assets/worker-briefs/gate-enter-implement.md

@@ -0,0 +1,24 @@
+# /gate-enter-implement — implement worker
+
+```markdown
+你是 Gate 的 implement worker。按已确认方案实施；不 review，不 verify，不推进 gate。
+
+## 工作项
+<task / 用户简述>
+
+## 合同与范围
+<验收条件、设计约束、本次要做 / 明确不做>
+
+## 基线
+<固定点、相关文件、已有改动>
+
+## 实施要求
+- 按现有架构和测试策略做最小完整实现。
+- 不扩大范围，不引入无关依赖，不修改产品合同。
+- 需要时补测试；记录实际运行的命令和结果。
+
+## 交付
+返回：改动文件、测试/命令结果、偏差、遗留风险。
+```
+
+

package/skills/gate-implement/tickets.md

@@ -0,0 +1,114 @@
+# Implementation Tickets
+
+After entering implementation, decompose authorized work only when it cannot be executed coherently as one unit. Tickets are created by implementation as needed, not prerequisites for its initial gate.
+
+Tickets are execution units, not additional design documents.
+
+Do not use decomposition to reopen decisions already settled upstream.
+
+## Storage
+
+Follow the project's documentation hierarchy for work-item ownership and its tracker configuration for operations. Existing work stays with its owner unless explicitly migrated; location-rule changes alone do not create replacement tickets.
+
+Use the project's existing work-tracking mechanism.
+
+Tickets may be:
+
+- issues in an issue tracker
+- local Markdown files
+- another project-defined execution artifact
+
+Reference the parent work item (proposed Agent Note) by its path, using the project's native relationship mechanism when available.
+
+## Tracer bullets
+
+Prefer tracer-bullet vertical slices.
+
+Each ticket should:
+
+- deliver a narrow but complete behavior or coherent change
+- cut through the layers required for that behavior
+- be independently verifiable where practical
+- fit within one fresh execution context
+- leave the system in a coherent state
+- declare genuine blocking dependencies
+
+Prefer one behavior through the necessary layers over one architectural layer across many behaviors.
+
+## Blocking edges
+
+Declare only dependencies that genuinely prevent a ticket from starting.
+
+Tickets with no unresolved blockers form the executable frontier.
+
+Do not create artificial sequencing where work can proceed independently.
+
+Independent frontier tickets may execute in parallel when safe and supported.
+
+Re-evaluate the executable frontier as tickets complete.
+
+## Wide refactors
+
+Do not force broad mechanical changes into artificial vertical slices.
+
+When necessary, prefer:
+
+1. **Expand** — introduce the new form alongside the old.
+2. **Migrate** — move consumers in coherent batches.
+3. **Contract** — remove the old form after migration.
+
+Represent genuine dependency edges explicitly.
+
+## Ticket contents
+
+Keep each ticket concise.
+
+Include:
+
+### Objective
+
+The behavior or coherent change the ticket delivers.
+
+### Acceptance criteria
+
+Observable or verifiable conditions for completion.
+
+### Blocked by
+
+Only genuine blocking work.
+
+Use the project's native dependency mechanism when one exists.
+
+## Inheritance
+
+Tickets inherit scope, requirements, design and applicable execution authorization from their identified parent work item and referenced artifacts.
+
+This may include:
+
+- work item
+- PRD
+- work item contract
+- Agent Note
+- RFC
+- ADRs
+- project constraints
+
+Reference those sources rather than duplicating them.
+
+Avoid detailed implementation recipes or decisions the implementer can safely make itself.
+
+## Execution
+
+Work the executable frontier.
+
+Before starting a ticket, check its inherited scope, acceptance conditions and blocking dependencies. Reuse the parent's valid authorization for that scope without repeating the full planning gate. A new material decision returns affected work to the project's Planning stage; decomposition cannot supply a missing upstream decision.
+
+Complete each ticket to a coherent, tested, and verifiable state before advancing dependent work.
+
+Update and close completed tickets according to the configured tracker workflow.
+
+Commit completed ticket work when the repository workflow expects ticket-level commits.
+
+Continue until all tickets required by the authorized scope are complete. Ticket completion does not replace the gate's review and verify nodes; return the completed scope and evidence to the gate.
+
+

package/skills/gate-plan-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gate-plan-review
+description: 由主 agent 读取并提炼后派发的只读 Plan Review 方法；保留 Standards/Spec/Architecture 三轴，只报告发现。
+user-invocable: false
+---
+
+## 主 agent 使用
+
+主 agent 在派发前自行读取本方法，把工作项、Note、固定点和评审规则交给一个或多个 review worker；worker 数量由主 agent 按规模决定。worker 不应加载本技能或其他 gate 方法文件。worker prompt 只包含这些计划内容；不要附带项目环境验证（`package.json`、Node 版本、git 状态、文件存在性、初始化 smoke 结果）。
+
+任务模板：本技能 `assets/worker-briefs/plan-review.md`；派发前读取并填写。
+
+## 计划评审
+
+评审被评审的工作项、范围、产品合同与 Agent Note；不修改规划，不替 planning 做决定。只评审计划内容，不评审项目环境、初始化结果、文件存在性或运行版本。
+
+确定被评审的 Proposal 或既有工作项、选定范围、产品合同与 Agent Note。工作项拥有本次产品行为和验收；跨工作项合同同样由工作项或 Note 承接。评审整个规划集合，并把结果报告给同一工作项。
+
+## 三条评审线
+
+- **Standards**：是否符合现有权威决定、领域语言和项目约束；
+- **Spec**：产品范围与验收是否明确，设计是否完整承接且没有遗漏、越界或暗中改写；
+- **Architecture**：职责、依赖、接口、数据流和系统关系是否一致。
+
+只报告实质问题和真实取舍。
+
+## 产品合同检查
+
+- 范围与非目标是否明确；
+- 正常、边界和失败行为是否足够清楚；
+- 标准、协议、安全策略、兼容边界和运维不变量是否写到能直接实现并验收的程度；
+- 验收条件是否可观察、可判定；
+- 产品决定是否仍需要实施者猜测；
+- Proposal 是否重复 Design 的技术细节，或 Design 是否改写、扩大 Proposal 的验收；
+- Proposal 是否用决策史代替可验收的产品行为；
+- 备选与理由是否留在 Design / Alternatives，而不是混入 Proposal；
+- 批准证据是否留在工作项节；
+- 技术探索是否还留有会改变范围的重要未知问题。
+
+## 技术设计检查
+
+- 是否能从工作项追溯到适用的产品要求；
+- 是否覆盖适用的产品行为和约束；
+- 是否把产品假设当成技术决定；
+- 是否存在尚未解决的重要技术选择；
+- 是否具备足够清楚的验证切入点；
+- 多份设计的边界是否完整且不互相矛盾；
+- Design / Alternatives 是否承载长期设计、真实备选与理由；批准证据是否留在工作项节。
+
+## 报告归属
+
+评审结果报告为通过、需要修订或拒绝。需要外部批准的决定，在取得批准前不得视为已接受。
+
+本 worker 只报告，不修改规划，不决定修正方案。按属主报告：
+
+- 产品范围、行为与验收问题报告给工作项；
+- 本次规划的技术设计问题报告给 Agent Note；引用输入的问题按项目配置反馈其属主；
+- 状态、评审与批准证据报告给工作项；
+- 领域术语问题报告给 技能`gate-domain-modeling` 的属主，技术决定报告给相关 Agent Note。
+
+由 planning worker 决定并执行修正；本 worker 不更新工作项、Note 或就绪状态。
+
+仅当提议为架构决定单独建档时，使用 技能`adr`  的准入条件检查反悔成本与真实权衡。其他 Agent Note 按项目部署后的 README 判断是否有长期设计价值。纯行为规则归产品合同；普通实现细节不因“重要”就自动生成 Note。
+
+设计仍依赖临时产品假设时保持非权威。修订产品合同后，检查所有承接同一产品合同的设计，不只修改最先暴露问题的那一份。
+
+## 评审标准
+
+规划集合满足以下条件时报告通过：
+
+- Standards、Spec 与 Architecture 没有未解决的实质问题；
+- 工作项产品合同已经稳定；
+- 每项适用验收条件都有设计承接，或明确说明无需技术设计；
+- 实施所需设计已按项目约定接受或批准；
+- 设计与适用产品合同之间没有遗漏、越界或冲突；
+- 所需决定已解决并写回权威工件；
+- 需要持久保存的决定已按约定记录；
+- 实施不需要发明重要产品行为或架构。
+
+评审通过只报告结论，不自动构成批准或执行授权，也不由本 worker 更新工作项或就绪状态。
+
+没有通过时，报告未解决问题及其属主；由 planning worker 修正，gate 再安排复审。普通实现细节可以保持开放。
+
+
+
+
+

package/skills/gate-plan-review/assets/worker-briefs/plan-review.md

@@ -0,0 +1,19 @@
+# Plan / Proposal Review worker
+
+```markdown
+你是 Gate 的只读 Plan Review worker。只评审计划、提案或 Note，不修改、不写代码。
+
+## 评审对象
+<工作项 / 提案 / Note 路径、固定点>
+
+## 合同
+<需求、验收条件、适用设计决定>
+
+## 评审三轴
+Standards / Spec / Architecture。每轴只报 findings，注明证据与严重度。
+
+## 输出
+返回 standards、spec、architecture 三组 findings；不要合并三轴，不要修复。
+```
+
+

package/skills/gate-planning/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gate-planning
+description: Gate 规划方法：主 agent 读取后提炼任务并派发；worker 不加载技能。
+user-invocable: false
+---
+
+## 必读资源
+
+写设计节（`## Design`、`### 设计` 或自由设计节）前必须读取 `proposal.md` 和 `rfc.md`；rfc 的检查项必须进入 worker prompt，不能以“as needed”跳过。mechanical 或不写设计节的工作项不强制读 rfc。
+
+## 主 agent 使用
+
+主 agent 在派发前自行读取本方法，给 worker 一份自包含任务：具体工作项、约束和规划规则。worker 不应加载本技能或其他 gate 方法文件。worker prompt 只给计划内容；不要附带项目环境验证（`package.json`、Node 版本、git 状态、文件存在性、初始化 smoke 结果）。
+
+任务模板：本技能 `assets/worker-briefs/gate-enter-plan.md`；派发前读取并填写。
+
+# 规划
+
+## 项目绑定
+
+- 本次工作项就是 proposed Agent Note；
+- 产品行为、范围、验收由工作项拥有；
+- 工作项内容按 [proposal.md](./proposal.md) ；技术设计按 [rfc.md](./rfc.md)（写设计节前必读）；
+- 技术设计与长期决定写入 Agent Note；
+- 模板使用内置 `gate-write-agent-notes` 的 `templates/proposed.md`；不新增或复制模板；
+- Note 的位置、格式、生命周期遵循内置 `gate-write-agent-notes`；不得在 planning 内另建生命周期或状态；
+- Plan Review 由 gate 的 `gate-plan-review` worker 执行；planning 接收主代理转交的 findings，负责决定与修正。
+
+## 0. 先检索与判定归属
+
+- 加载内置 `gate-write-agent-notes`，按 §3 用 `grep`/`glob`/`read` 检索入口注释、分类树、关键词和模块 README，不依赖 shell。
+- 按 §4 判定：既有决定未变时就地同步 `implemented/` Note；新想法写 `proposed/`；class 只能是六类封闭集。
+- 把检索证据写入 `noteSearch`，把归属与 class 写入 `notePaths` / `noteDecision`，随 `gate_record({node:'plan'})` 提交。
+
+把当前对话与项目上下文整理成最少但足够的规划工件，使工作具备实施条件。先确定各项事实的项目属主，再按需让产品合同与技术探索往返收敛；不为填满文档类型而创建工件。
+
+## 1. 确定工作项
+
+本次工作项由 proposed Agent Note 承接。按 [proposal.md](./proposal.md)  写清 why、范围与非目标、产品行为与验收、决定与未决问题、评审与批准证据。
+
+复用合适的既有 Note；需要新 Note 时加载内置技能 `gate-write-agent-notes` 创建 proposed Note，不另建独立 Proposal 文件，也不要求 Issue tracker。
+
+在 gate 环境中，Note 的落盘使用 `gate_note_write`：新建写 `proposed/<class>/...`，原地同步既有 implemented Note 写 `implemented/<class>/...`；通用 `write`/`edit`/shell 在 planning 被限制。
+
+工作项与设计在同一份 Note 分节；工作项不复制 Design 正文，Design 不改写工作项验收。
+
+## 2. 收敛产品合同与技术设计
+
+### 产品合同
+
+产品行为、范围与验收由本次工作项写全；跨工作项持续生效的合同由工作项拥有，并在同一 Note 中分节，不复制成第二套合同。
+
+### 探索性设计
+
+当技术可行性会实质影响产品范围时，读取技术设计检查项[rfc.md](./rfc.md) ，在 proposed Note 中形成探索草案。只要写设计节，就必须先读 rfc.md；规模小不构成跳过理由。
+
+探索草案必须区分产品事实与临时假设，把影响产品范围的结论反馈给工作项，不得作为实施依据。
+
+产品合同与探索草案可以往返修改，直到范围与验收不再依赖未解决的技术可行性问题。
+
+### 技术设计定稿
+
+需要解决重要技术决定时，使用 技术设计检查项（[rfc.md](./rfc.md) ），把已确定的产品合同转成 Agent Note 中的技术设计；一份产品合同可以由多个边界明确的 Note 分别承接。只要写设计节，就必须先读 rfc.md。
+
+设计定稿遵循 技术设计规则（[rfc.md](./rfc.md) ） 的合同稳定性与评审条件。Note 的 proposed/implemented 表示交付生命周期，不代替评审和批准证据。
+
+使用项目既有领域语言和适用架构约束。领域术语与模型变化使用 `gate-domain-modeling`；需要为架构决定单独建档时，使用 `adr` 的准入条件判断，在相关 Agent Note 中记录决定。
+
+### 决定权限
+
+在已同意的产品合同、既有架构和项目约束内，自主解决普通技术选择。
+
+涉及未解决的产品、业务、兼容性、成本、风险、架构方向或其他价值判断时，交由用户决定，除非用户已经明确委托决定权。
+
+## 3. Review findings
+
+Plan Review is owned by the gate's `gate-plan-review` worker; do not run it here.
+
+主代理转交 findings 后，逐条决定其属主并在对应工件修正：产品范围与验收回到工作项，本次规划的技术设计回到 Agent Note，工作状态与批准证据回到工作项。引用输入的问题按项目配置反馈其属主，并报告受影响范围。不得自行宣称整体通过。
+
+## 4. 完成与交接
+
+Planning 完成需要同时满足：
+
+- 产品范围和验收条件已经稳定；
+- 实施所需设计已按项目约定接受或批准；
+- 设计完整承接工作项产品合同；
+- 所需决定已解决；
+- 主代理报告 Plan Review 无未解决发现（不由本 worker 自行宣称）。
+
+若用户只要求规划，交付规划结果与评审证据后结束。端到端任务把 receipt 交回 gate；执行授权由 gate 单独核对，不在本 worker 内推进。
+
+
+
+
+

package/skills/gate-planning/assets/worker-briefs/gate-enter-plan.md

@@ -0,0 +1,24 @@
+# /gate-enter-plan — planning worker
+
+```markdown
+你是 Gate 的 planning worker。完成规划并写 Note；不写代码，不实现。
+
+## 需求/约束
+<用户简述、已确认约束、范围>
+
+## 项目上下文
+<相关代码、文档、历史 Note 的关键事实；不要附环境 smoke>
+
+## Design 检查项
+<按 gate-planning/rfc.md 的适用检查点填写；worker 不加载技能，root 必须转交>
+
+## Note 要求
+- 先按 §3 检索历史，再按 §4 判定归属与 class。
+- 新建时用 gate_note_write 写 proposed Note；原地同步 implemented Note 时写 implemented/<class>/...。
+- 内容包含 problem / proposal / design / alternatives / acceptance / risks。
+
+## 交付
+返回：Note 路径、class、lifecycle、noteDecision、检索结论、主要设计取舍、未决问题。
+```
+
+

package/skills/gate-planning/proposal.md

@@ -0,0 +1,51 @@
+# Proposal
+
+工作项与技术设计由同一份 proposed Agent Note 承接；工作项负责为什么要改、本次范围、产品行为与验收、评审与批准证据及就绪状态；技术设计写在同一 Note 的 Design 节，不另设设计属主。
+
+## 配置与存放
+
+- 唯一载体：`proposed/<class>/YYYY-MM-DD-topic.md`；
+- 不创建独立 Proposal 文件；
+- 模板使用 `<skills-root>/write-agent-notes/templates/proposed.md`；
+- 路径、分类、格式与生命周期由 `write-agent-notes` Skill 管。
+
+## 内容
+
+同一份 Note 中，工作项部分必须包含：
+
+```text
+## Problem
+why、背景、约束
+
+## Proposal
+### 范围与非目标
+### 产品行为与验收
+### 决定与未决问题
+### 评审与批准证据
+
+## Design
+技术设计、边界、关键决定
+
+## Alternatives considered
+真实备选、最强理由、为什么不选
+
+## Acceptance criteria
+可观察、可判定的验收
+
+## Risks
+风险与未决问题
+```
+
+- `## Proposal` 的子项是内容要求，不是新增模板；
+- `## Design` 是自由节，由 `rfc.md` 检查；
+- `## Alternatives considered`、`## Acceptance criteria`、`## Risks` 保持 Agent Note 模板结构；
+- 工作项内容与设计写在同一份 Note，不复制到第二份文件。
+
+## 状态更新
+
+- Plan Review 结果、批准与就绪状态记录在 Note 的工作项部分；
+- 评审通过、批准、执行授权是三件事；
+- 只有规划内容通过、所需批准齐备且没有阻塞时，才标记为就绪；
+- proposed → implemented 由 `write-agent-notes` 在实现与验证完成后处理，planning 不提前转换。
+
+

package/skills/gate-planning/rfc.md

@@ -0,0 +1,73 @@
+# 技术设计
+
+本文件提供技术设计的检查项，供 Planning 在 proposed Agent Note 中探索和定稿设计。Note 的位置与格式遵循项目配置。
+
+设计可以早于产品合同定稿开始，但只有适用的工作项合同或工作项合同 稳定后，才能被接受并成为实施依据。
+
+## 位置与生命周期
+
+遵循项目 Agent Notes README 的生命周期。proposed/implemented/rejected 反映交付结果，不代表批准。
+
+设计在获得项目要求的评审与批准前保持非权威；被替代时保留与替代设计的关系。已交付 Note 的决定被推翻时，由新 Note 记录新决定，旧 Note 不改写成相反结论。
+
+## 输入与承接关系
+
+评审时应能从工作项确认：
+
+- 承接的工作项产品要求，或工作项合同 的修订及适用章节；
+- 本设计负责的技术范围以及与同一产品合同下其他设计的边界。
+
+一份产品合同可以拆给多份设计承接。设计不复制产品范围与验收正文；工作项建立要求与设计之间的链接。
+
+## 探索草案
+
+以下技术事实会影响产品范围时，可以先写探索草案：
+
+- 上游能力和可用性；
+- 成本、性能或资源上限；
+- 兼容性与迁移可行性；
+- 安全、可靠性或运维硬约束；
+- 不同技术路线导致的产品体验差异。
+
+探索草案必须区分已经确定的产品事实、临时假设和待决定问题。它输出可行性结论及其对产品范围的影响，把产品选择交回产品合同属主，不得自行定下产品行为。
+
+探索草案不能作为实施依据。
+
+## 技术设计
+
+按需要解决会实质约束实现的内容：
+
+- 系统边界与职责；
+- 接口、协议、Schema 与持久化；
+- 生命周期和失败行为；
+- 兼容与迁移；
+- 重要的安全、可靠性、性能或资源约束；
+- 有意义的验证切入点。
+
+普通实现细节留给实现阶段，不为完整感规定目录、类型或步骤。
+
+设计不得扩大、缩小或改写适用产品合同。设计中发现产品缺口时，暂停相关部分的接受，先修订工作项或工作项合同，再检查同一合同下其他设计是否受影响。
+
+## 技术决定
+
+在已同意的产品合同、既有架构和项目约束内，自主解决普通技术选择。重要备选存在真实取舍时，给出推荐与足够的评审理由。
+
+需要产品、业务、兼容性、成本、风险、持久架构方向或其他价值判断时，交给相应决定权限，不把问题伪装成纯技术选择。
+
+接受的决定形成或改变领域语言时，使用 `gate-domain-modeling` SKILL 维护领域资料。需要为架构决定单独建档时，使用 `adr` SKILL 的准入条件判断；决定属于本设计时在同一 Note 中维护，可独立判断的新决定按项目 Note 规则记录。
+
+## 定稿与评审条件
+
+技术设计可以进入 Plan Review，需要满足：
+
+- 适用的工作项产品合同或工作项合同 已经稳定；
+- 承接的工作项要求，或工作项合同 的修订与章节明确；
+- 方案足够解决重要技术决定；
+- 重要备选有推荐；
+- 需要外部权限的决定已明确；
+- 验证切入点足够清楚；
+- 实施不需要重新发现重要产品或技术决定。
+
+准备好评审不等于已经接受或批准。
+
+