@namewta/speculo 1.0.13 → 1.0.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/package.json +1 -1
- package/template/canonical/canonical-specdev-goal-plan.md +9 -5
- package/template/canonical/canonical-specdev-grill-with-docs.md +6 -4
- package/template/canonical/canonical-specdev-spec.md +8 -4
- package/template/canonical/canonical-specdev-tickets.md +20 -4
- package/template/commands/handoff.md +1 -1
- package/template/commands/status.md +1 -1
- package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +3 -3
- package/template/workflows/specdev/I-implement/references/implementation-procedure.md +1 -1
- package/template/workflows/specdev/I-init-setup/tracking-template.md +1 -1
- package/template/workflows/specdev/INDEX.md +1 -1
- package/template/workflows/specdev/README.md +4 -4
- package/template/workflows/specdev/T-tickets/ticket-template.md +1 -0
- package/template/workflows/specdev/T-triage/T-triage.md +80 -15
- package/template/workflows/specdev/T-triage/capture-protocol.md +89 -0
- package/template/workflows/specdev/T-triage/capture-template.md +42 -0
- package/template/workflows/specdev/T-triage/close-comment-template.md +42 -0
- package/template/workflows/specdev/T-triage/intake-protocol.md +8 -2
- package/template/workflows/specdev/T-triage/issue-body-template.md +34 -0
- package/template/workflows/specdev/T-triage/issue-record-template.md +27 -0
- package/template/workflows/specdev/T-triage/publish-protocol.md +92 -0
- package/template/workflows/specdev/T-triage/publish-template.md +49 -0
- package/template/workflows/specdev/T-triage/reconcile-protocol.md +3 -3
- package/template/workflows/specdev/T-triage/references/classification-map.md +54 -0
- package/template/workflows/specdev/T-triage/references/public-projection.md +89 -0
- package/template/workflows/specdev/T-triage/tools/capture-status.mjs +125 -0
- package/template/workflows/specdev/T-triage/tools/publish-status.mjs +148 -0
- package/template/workflows/specdev/T-triage/triage-template.md +12 -1
- package/template/workflows/specdev/common/README.md +2 -0
- package/template/workflows/specdev/common/rules/artifact-contract.md +6 -4
- package/template/workflows/specdev/common/rules/change-completion.md +1 -1
- package/template/workflows/specdev/common/rules/evidence-and-verification.md +2 -0
- package/template/workflows/specdev/common/rules/workflow-routing.md +3 -1
- package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +1 -0
- package/template/workflows/specdev/common/schemas/capture.schema.json +15 -0
- package/template/workflows/specdev/common/schemas/publish.schema.json +21 -0
- package/template/workflows/specdev/common/schemas/ticket.schema.json +11 -0
- package/template/workflows/specdev/common/schemas/triage.schema.json +3 -1
- package/template/workflows/specdev/common/tools/README.md +7 -0
- package/template/workflows/specdev/common/tools/validate-specdev.mjs +304 -6
package/README.md
CHANGED
|
@@ -73,12 +73,14 @@ After initialization, the target project gains the following AI agent-callable a
|
|
|
73
73
|
| Workflow | Work Entries | Description |
|
|
74
74
|
|---|---:|---|
|
|
75
75
|
| **learning** | 9 | Evidence-aware learning for projects, products, subjects, languages, and skills: complete 30–40 minute plain-language lessons, Socratic inquiry lessons, Goal-Plan compilation for later external /goal execution (teach a mine-unit of ≤15 lessons, then fan out miners), single-file homework review, optional retention review, and provenance-preserving topic synthesis |
|
|
76
|
-
| **specdev** | 14 | Local-first specification-driven development: archive, code review, diagnosis, grilling, implementation, setup, learning, goal planning, prototyping, architecture review, specs, tickets, triage, and wayfinding |
|
|
76
|
+
| **specdev** | 14 | Local-first specification-driven development: archive, code review, diagnosis, grilling, implementation, setup, learning, goal planning, prototyping, architecture review, specs, tickets, triage (intake / reconcile / publish / capture), and wayfinding |
|
|
77
77
|
| **ops** | 3 | Host inventory and project deployment: initialize, host manage, and APP/shared-service deploy with dual documentation |
|
|
78
78
|
| **person** | 2 | Persona-methodology and rigorous deliberation workflows (Mao Zedong Cognitive OS; Bidirectional Steelman Deliberation) |
|
|
79
79
|
|
|
80
80
|
Every workflow ships an `INDEX.md` as its auto-generated work catalog. Work entries follow `<Letter>-<work_name>/<Letter>-<work_name>.md` naming with progressive-disclosure sub-files, and resolve runtime paths via `<Path>{roots.xxx}/...</Path>` pointers in `workspace.json`.
|
|
81
81
|
|
|
82
|
+
SpecDev T-triage stays the only remote boundary. Use **intake** to freeze a source, **reconcile** to close that original source Issue after local completion, **publish** to project each completed Ticket as a classified GitHub Issue (local-origin work included), and **capture** to park a not-yet-Change note as a still-open GitHub Issue. GitHub is a projection, counter, and inbox — not the development source of truth. Run both reconcile and publish when an intake Change should also count its tickets. Capture does not create a Change.
|
|
83
|
+
|
|
82
84
|
## Documentation
|
|
83
85
|
|
|
84
86
|
- [AGENTS.md](./AGENTS.md) — AI agent handbook (authoritative)
|
package/package.json
CHANGED
|
@@ -450,20 +450,22 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
|
|
|
450
450
|
| 工件 | 具体位置 | 必须决定 | 不应决定 |
|
|
451
451
|
|---|---|---|---|
|
|
452
452
|
| 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
|
|
453
|
-
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work
|
|
453
|
+
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work、源 Issue reconcile 状态和 publish_action | 详细实现方案、开发进度或票级发布账本 |
|
|
454
|
+
| 发布账本 | `specdev/changes/{change}/publish.md` | 票级 GitHub 投影的编号、标签、marker、state 和发布计数 | Ticket 契约、Evidence 原文或源 Issue 关闭 |
|
|
455
|
+
| 捕获账本 | `specdev/capture.md` | 尚未成 Change 的记事项、GitHub inbox 编号、标签、marker 和 inbox 计数;缺失合法 | Change、Ticket、Evidence 或已完成票的发布投影 |
|
|
454
456
|
| 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
|
|
455
457
|
| 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
|
|
456
458
|
| 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
|
|
457
459
|
| Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
|
|
458
460
|
| Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
|
|
459
461
|
| Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
|
|
460
|
-
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket
|
|
462
|
+
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理或远程 Issue 编号 |
|
|
461
463
|
| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
|
|
462
464
|
| Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
|
|
463
465
|
| Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
|
|
464
466
|
| Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
|
|
465
467
|
| Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
|
|
466
|
-
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 |
|
|
468
|
+
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
|
|
467
469
|
| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实;索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
|
|
468
470
|
| 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
|
|
469
471
|
| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
|
|
@@ -493,7 +495,7 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
|
|
|
493
495
|
|
|
494
496
|
当前 change 决定与永久知识冲突时,必须在 LOG/ADR 中显式说明替代关系;它只约束当前 change,直到 A 决定是否提升并更新永久版本。
|
|
495
497
|
|
|
496
|
-
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。
|
|
498
|
+
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。GitHub 上由 publish 投影出的 Issue 不是开发权威;发布计数以 `specdev/changes/{change}/publish.md` 为准。GitHub 上由 capture 记下的 inbox Issue 也不是开发权威;inbox 计数以 `specdev/capture.md` 为准,缺失该文件视为空 inbox。
|
|
497
499
|
|
|
498
500
|
代码事实可以证明计划已过时,但不能静默改写用户目标或已接受契约。出现这种情况时,按 下方 `<deviation-control>` 标签 退回相应工件修订。
|
|
499
501
|
|
|
@@ -628,6 +630,8 @@ Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施
|
|
|
628
630
|
|
|
629
631
|
父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
|
|
630
632
|
|
|
633
|
+
Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成,不替代本文件的完整记录。
|
|
634
|
+
|
|
631
635
|
</evidence-and-verification>
|
|
632
636
|
|
|
633
637
|
<deviation-control>
|
|
@@ -713,7 +717,7 @@ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`
|
|
|
713
717
|
|
|
714
718
|
## 远程来源与归档
|
|
715
719
|
|
|
716
|
-
远程动作不参与本地完成判定。Triage 为 `pending-close`/`close-failed` 时先 reconcile;`closed`、`waived` 或 `not-applicable` 才允许 Archive
|
|
720
|
+
远程动作不参与本地完成判定。Triage `external_action` 为 `pending-close`/`close-failed` 时先 reconcile;`closed`、`waived` 或 `not-applicable` 才允许 Archive。Triage `publish_action` 为 `pending`/`publish-failed` 时先恢复或结束 publish;`not-requested`、`published` 或 `waived` 才允许 Archive。`not-requested` 是默认,未点过 publish 的 change 不被新模式绑架。归档后工件只读。
|
|
717
721
|
|
|
718
722
|
**完成标准**:完成声明可由本地工件、Git 与验证重建;只有一个 owner 命中;失败 candidate 不污染父分支。
|
|
719
723
|
|
|
@@ -251,20 +251,22 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
|
|
|
251
251
|
| 工件 | 具体位置 | 必须决定 | 不应决定 |
|
|
252
252
|
|---|---|---|---|
|
|
253
253
|
| 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
|
|
254
|
-
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work
|
|
254
|
+
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work、源 Issue reconcile 状态和 publish_action | 详细实现方案、开发进度或票级发布账本 |
|
|
255
|
+
| 发布账本 | `specdev/changes/{change}/publish.md` | 票级 GitHub 投影的编号、标签、marker、state 和发布计数 | Ticket 契约、Evidence 原文或源 Issue 关闭 |
|
|
256
|
+
| 捕获账本 | `specdev/capture.md` | 尚未成 Change 的记事项、GitHub inbox 编号、标签、marker 和 inbox 计数;缺失合法 | Change、Ticket、Evidence 或已完成票的发布投影 |
|
|
255
257
|
| 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
|
|
256
258
|
| 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
|
|
257
259
|
| 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
|
|
258
260
|
| Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
|
|
259
261
|
| Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
|
|
260
262
|
| Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
|
|
261
|
-
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket
|
|
263
|
+
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理或远程 Issue 编号 |
|
|
262
264
|
| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
|
|
263
265
|
| Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
|
|
264
266
|
| Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
|
|
265
267
|
| Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
|
|
266
268
|
| Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
|
|
267
|
-
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 |
|
|
269
|
+
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
|
|
268
270
|
| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实;索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
|
|
269
271
|
| 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
|
|
270
272
|
| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
|
|
@@ -294,7 +296,7 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
|
|
|
294
296
|
|
|
295
297
|
当前 change 决定与永久知识冲突时,必须在 LOG/ADR 中显式说明替代关系;它只约束当前 change,直到 A 决定是否提升并更新永久版本。
|
|
296
298
|
|
|
297
|
-
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。
|
|
299
|
+
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。GitHub 上由 publish 投影出的 Issue 不是开发权威;发布计数以 `specdev/changes/{change}/publish.md` 为准。GitHub 上由 capture 记下的 inbox Issue 也不是开发权威;inbox 计数以 `specdev/capture.md` 为准,缺失该文件视为空 inbox。
|
|
298
300
|
|
|
299
301
|
代码事实可以证明计划已过时,但不能静默改写用户目标或已接受契约。出现这种情况时,按 下方 `<deviation-control>` 标签 退回相应工件修订。
|
|
300
302
|
|
|
@@ -363,20 +363,22 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
|
|
|
363
363
|
| 工件 | 具体位置 | 必须决定 | 不应决定 |
|
|
364
364
|
|---|---|---|---|
|
|
365
365
|
| 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
|
|
366
|
-
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work
|
|
366
|
+
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work、源 Issue reconcile 状态和 publish_action | 详细实现方案、开发进度或票级发布账本 |
|
|
367
|
+
| 发布账本 | `specdev/changes/{change}/publish.md` | 票级 GitHub 投影的编号、标签、marker、state 和发布计数 | Ticket 契约、Evidence 原文或源 Issue 关闭 |
|
|
368
|
+
| 捕获账本 | `specdev/capture.md` | 尚未成 Change 的记事项、GitHub inbox 编号、标签、marker 和 inbox 计数;缺失合法 | Change、Ticket、Evidence 或已完成票的发布投影 |
|
|
367
369
|
| 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
|
|
368
370
|
| 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
|
|
369
371
|
| 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
|
|
370
372
|
| Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
|
|
371
373
|
| Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
|
|
372
374
|
| Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
|
|
373
|
-
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket
|
|
375
|
+
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理或远程 Issue 编号 |
|
|
374
376
|
| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
|
|
375
377
|
| Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
|
|
376
378
|
| Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
|
|
377
379
|
| Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
|
|
378
380
|
| Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
|
|
379
|
-
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 |
|
|
381
|
+
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
|
|
380
382
|
| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实;索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
|
|
381
383
|
| 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
|
|
382
384
|
| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
|
|
@@ -406,7 +408,7 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
|
|
|
406
408
|
|
|
407
409
|
当前 change 决定与永久知识冲突时,必须在 LOG/ADR 中显式说明替代关系;它只约束当前 change,直到 A 决定是否提升并更新永久版本。
|
|
408
410
|
|
|
409
|
-
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。
|
|
411
|
+
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。GitHub 上由 publish 投影出的 Issue 不是开发权威;发布计数以 `specdev/changes/{change}/publish.md` 为准。GitHub 上由 capture 记下的 inbox Issue 也不是开发权威;inbox 计数以 `specdev/capture.md` 为准,缺失该文件视为空 inbox。
|
|
410
412
|
|
|
411
413
|
代码事实可以证明计划已过时,但不能静默改写用户目标或已接受契约。出现这种情况时,按 下方 `<deviation-control>` 标签 退回相应工件修订。
|
|
412
414
|
|
|
@@ -557,6 +559,8 @@ Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施
|
|
|
557
559
|
|
|
558
560
|
父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
|
|
559
561
|
|
|
562
|
+
Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成,不替代本文件的完整记录。
|
|
563
|
+
|
|
560
564
|
</evidence-and-verification>
|
|
561
565
|
|
|
562
566
|
<deviation-control>
|
|
@@ -179,6 +179,7 @@ change: <YYYY-MM-DD-topic>
|
|
|
179
179
|
id: T-01
|
|
180
180
|
title: <标题>
|
|
181
181
|
status: draft
|
|
182
|
+
kind: bug
|
|
182
183
|
planning_depth: standard
|
|
183
184
|
planning_depth_reason: <触发该深度的事实>
|
|
184
185
|
ready: false
|
|
@@ -505,20 +506,22 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
|
|
|
505
506
|
| 工件 | 具体位置 | 必须决定 | 不应决定 |
|
|
506
507
|
|---|---|---|---|
|
|
507
508
|
| 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
|
|
508
|
-
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work
|
|
509
|
+
| 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work、源 Issue reconcile 状态和 publish_action | 详细实现方案、开发进度或票级发布账本 |
|
|
510
|
+
| 发布账本 | `specdev/changes/{change}/publish.md` | 票级 GitHub 投影的编号、标签、marker、state 和发布计数 | Ticket 契约、Evidence 原文或源 Issue 关闭 |
|
|
511
|
+
| 捕获账本 | `specdev/capture.md` | 尚未成 Change 的记事项、GitHub inbox 编号、标签、marker 和 inbox 计数;缺失合法 | Change、Ticket、Evidence 或已完成票的发布投影 |
|
|
509
512
|
| 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
|
|
510
513
|
| 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
|
|
511
514
|
| 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
|
|
512
515
|
| Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 本 change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
|
|
513
516
|
| Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
|
|
514
517
|
| Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
|
|
515
|
-
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket
|
|
518
|
+
| Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理或远程 Issue 编号 |
|
|
516
519
|
| Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
|
|
517
520
|
| Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
|
|
518
521
|
| Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
|
|
519
522
|
| Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
|
|
520
523
|
| Implementation Orchestration Evidence | `specdev/changes/{change}/evidence/implementation-orchestration.md` | 成员完成、组合 Ticket 顺序/锁、repository integration、整体验证、漂移和残余风险 | 新产品/架构决定或单 Ticket Evidence 替代品 |
|
|
521
|
-
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 |
|
|
524
|
+
| Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
|
|
522
525
|
| Change 学习图解 | `specdev/changes/{change}/learning/index.md` 与 `specdev/changes/{change}/learning/{number}_{topic}.md` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实;索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
|
|
523
526
|
| 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
|
|
524
527
|
| UI 设计包 | `specdev/changes/{change}/prototypes/{design-id}/design-system.md`、`specdev/changes/{change}/prototypes/{design-id}/comparison/` 与 `specdev/changes/{change}/prototypes/{design-id}/final/` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
|
|
@@ -548,7 +551,7 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
|
|
|
548
551
|
|
|
549
552
|
当前 change 决定与永久知识冲突时,必须在 LOG/ADR 中显式说明替代关系;它只约束当前 change,直到 A 决定是否提升并更新永久版本。
|
|
550
553
|
|
|
551
|
-
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。
|
|
554
|
+
`specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。GitHub 上由 publish 投影出的 Issue 不是开发权威;发布计数以 `specdev/changes/{change}/publish.md` 为准。GitHub 上由 capture 记下的 inbox Issue 也不是开发权威;inbox 计数以 `specdev/capture.md` 为准,缺失该文件视为空 inbox。
|
|
552
555
|
|
|
553
556
|
代码事实可以证明计划已过时,但不能静默改写用户目标或已接受契约。出现这种情况时,按 下方 `<deviation-control>` 标签 退回相应工件修订。
|
|
554
557
|
|
|
@@ -739,6 +742,8 @@ Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施
|
|
|
739
742
|
|
|
740
743
|
父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
|
|
741
744
|
|
|
745
|
+
Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成,不替代本文件的完整记录。
|
|
746
|
+
|
|
742
747
|
</evidence-and-verification>
|
|
743
748
|
|
|
744
749
|
<deviation-control>
|
|
@@ -1525,6 +1530,17 @@ implementation owner 只在来源 worktree 修改授权项目路径,运行 Tic
|
|
|
1525
1530
|
"cancelled"
|
|
1526
1531
|
]
|
|
1527
1532
|
},
|
|
1533
|
+
"kind": {
|
|
1534
|
+
"enum": [
|
|
1535
|
+
"bug",
|
|
1536
|
+
"feature",
|
|
1537
|
+
"refactor",
|
|
1538
|
+
"investigation",
|
|
1539
|
+
"operations",
|
|
1540
|
+
"documentation",
|
|
1541
|
+
"review"
|
|
1542
|
+
]
|
|
1543
|
+
},
|
|
1528
1544
|
"planning_depth": {
|
|
1529
1545
|
"enum": [
|
|
1530
1546
|
"lite",
|
|
@@ -35,7 +35,7 @@ disable-model-invocation: true
|
|
|
35
35
|
|
|
36
36
|
如果用户传入了参数,将其视为对下一个会话重点内容的描述,并据此定制文档。
|
|
37
37
|
|
|
38
|
-
交接范围包含 SpecDev change 时,引用该 change 的 `source.md`、`triage.md
|
|
38
|
+
交接范围包含 SpecDev change 时,引用该 change 的 `source.md`、`triage.md`、`publish.md`(若请求过)、`.status.json` 和当前 owning 工件,不复制正文。若 `external_action` 为 `pending-close` 或 `close-failed`,必须记录准确远程 locator、已完成步骤、授权状态和恢复入口 `T-triage`;不得把待关闭误报为本地未完成。若 `publish_action` 为 `pending` 或 `publish-failed`,必须记录账本路径、失败行和下一步,恢复入口仍是 T-triage publish。交接范围包含尚未成 Change 的 inbox 记事项时,引用 `<Path>{roots.state}/specdev/capture.md</Path>`(若存在)的失败行与恢复入口 T-triage capture,不创建 change。
|
|
39
39
|
|
|
40
40
|
## 路径引用规范
|
|
41
41
|
|
|
@@ -11,7 +11,7 @@ keywords: [status, 状态, active, blocked]
|
|
|
11
11
|
1. 读取 `<Path>{roots.state}/workspace.json</Path>`,解析 `<Path>{roots.config}</Path>`(不存在时以默认值静默降级),获取全部已安装 workflow/state 根。
|
|
12
12
|
2. 扫描 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>`,得到已安装 workflow ids。
|
|
13
13
|
3. 对每个 id 读取 `<Path>{roots.state}/{workflow}/status.json</Path>`,按该 workflow 自己的 schema 解释,不把 SpecDev 字段套到其他 workflow。Learning schema v2 的 active/archived entry 携带 stable `change_id`、kind、parent/root、current locator、current_work、Homework 和 retention projection;递归 Change 位于 `changes/**` 或 `archive/**`,位置历史读取 `<Path>{roots.state}/learning/locations.json</Path>`。SpecDev 继续使用 schema v5 根级 `changes/<change>`/`archive/YYYY-MM/<change>`;Ops schema v3 使用 hosts/projects/deployments/allocations/bindings/releases 资源表,运行记录在 hosts/{host_id}/runs/{run_id} 或 releases/{run_id};保留的非空 v2 只作为旧证据读取,不转换旧批准。不得按 change 名跨 workflow 合并。
|
|
14
|
-
4. 报告 active 数量、各 Change 的 `current_work`、去重后的 `works_run`、生命周期、parent/root、最近更新时间和停滞 Change(`.status.json` 超过 14 天未更新)。SpecDev 额外报告调查 claims 与 triage
|
|
14
|
+
4. 报告 active 数量、各 Change 的 `current_work`、去重后的 `works_run`、生命周期、parent/root、最近更新时间和停滞 Change(`.status.json` 超过 14 天未更新)。SpecDev 额外报告调查 claims、triage `external_action` / `publish_action`,以及 active+archive `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 汇总的 `published_issues`(含 `origin:local` / `origin:intake`)、`publish_skipped`、`publish_failed`;并报告 workspace `<Path>{roots.state}/specdev/capture.md</Path>` 的 `inbox_open` / `inbox_intaken` / `inbox_waived`(缺失视为空 inbox,不计入 `published_issues`)。数字以本地账本为准,不扫 GitHub 当权威。可用 `<Path>{roots.workflows}/specdev/T-triage/tools/publish-status.mjs</Path>` 与 `<Path>{roots.workflows}/specdev/T-triage/tools/capture-status.mjs</Path>`。Learning 额外报告 domain/topic、Lesson/Homework、immediate/retention 和 synthesis 状态;Ops 按主机和 APP/公共服务分别展示 deployment_id、observed_version、路径、最后部署时间、共享绑定、plan/approval/run 状态与双边 docs-receipt。docs_pending/unknown 必须列异常;普通状态报告不读取或输出 private 明文账本,不把 OPS 资源套入 active/archived Change 统计。
|
|
15
15
|
5. 报告 archived 数量和完整 scope/project/change locator;Learning 同时读取 `context/REVIEW.md` 汇总到期 Review、topic evidence status 和需要刷新内容。预期归档目录或 `.status.json` 缺失、active/archived 重叠、parent cycle、位置登记不一致、未知 schema、断开链接和 malformed 目录均列为异常,不自动修复。
|
|
16
16
|
6. 报告没有 workflow 资产的孤立状态根,以及缺少状态根的已安装 workflow;不自动修复。
|
|
17
17
|
7. 用户要求持久化时写入 `<Path>{roots.state}/commands/status/{date}-workspace-{topic}[-NN].md</Path>`,并在报告中列出本次扫描的 workflow 选择。
|
|
@@ -3,7 +3,7 @@ id: specdev/archive-and-consolidate
|
|
|
3
3
|
type: workflow-entry
|
|
4
4
|
workflow: specdev
|
|
5
5
|
name: 归档与沉淀
|
|
6
|
-
description:
|
|
6
|
+
description: 校验本地完成、源 Issue reconcile 门和票级 publish_action 门,复用全局归档能力移动 completed change 并提升当前知识,或从代码访谈形成可归档知识 change。
|
|
7
7
|
keywords: [归档, consolidation, ADR, context, research, knowledge, 代码库访谈]
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -31,7 +31,7 @@ A 是 SpecDev 的归档 wrapper:它拥有模式选择、SpecDev 完成门和
|
|
|
31
31
|
|
|
32
32
|
1. 读取全局/change 状态、Ticket、Map、Goal Plan、Evidence、ADR、CONTEXT、LOG、triage 和项目验证事实。
|
|
33
33
|
2. 加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`,确认 `change_status: completed`、完成 owner 已写入时间和证据、无 blocker/deviation;若该 change 是未完成父实现 change 的成员则停止,若其自身是父实现 change 则还需所有成员与 aggregate Evidence 完成。
|
|
34
|
-
3. 检查 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action`:`pending-close` 或 `close-failed` 返回 `<Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>`;只有 `closed | waived | not-applicable`
|
|
34
|
+
3. 检查 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 的 `external_action`:`pending-close` 或 `close-failed` 返回 `<Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>`;只有 `closed | waived | not-applicable` 继续。再检查 `publish_action`:`pending` 或 `publish-failed` 同样返回 T-triage publish;只有 `not-requested | published | waived`(缺省视为 `not-requested`)继续。
|
|
35
35
|
4. 调用 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 的 `archive-single + dry-run`,传入已解析 workflow/state/changes/archive/knowledge roots。展示完整移动、提升和清理计划。
|
|
36
36
|
5. 只有用户明确批准该计划后调用 `confirmed`。移动、知识写入和清理均使用计划内路径;计划后出现 drift 时停止。
|
|
37
37
|
6. 重读源、归档目标、全局索引、归档 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>` 和永久知识;运行 `--stage complete` 及包级校验,报告每个提升/跳过结论。
|
|
@@ -51,7 +51,7 @@ Dry-run 不修改文件。归档移动、知识 merge/rewrite/delete、Git 动
|
|
|
51
51
|
## 完成标准
|
|
52
52
|
|
|
53
53
|
- 模式与唯一 change 已确定;
|
|
54
|
-
-
|
|
54
|
+
- 本地完成、external reconcile 门和 publish_action 门通过;
|
|
55
55
|
- 机械归档与知识规则只有全局 skill 一个事实源;
|
|
56
56
|
- dry-run 与 confirmed 执行严格分离;
|
|
57
57
|
- 源不存在、目标完整、active/archived 无重叠、归档状态正确;
|
|
@@ -147,7 +147,7 @@ Lead 使用 `<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</P
|
|
|
147
147
|
|
|
148
148
|
Ticket 正常状态:`ready → in_progress → review → done`。`required` 的 `done` 要求 change worktree 已完成集成(`integrated` 或 `removed`)、父 HEAD=result SHA 且包含 source commit;`current` 的 `done` 要求 current workspace clean、direct-parent 验证通过且父 HEAD=result SHA。阻塞使用 `blocked`,契约偏差使用 `deviated`,无需改动使用 `cancelled`。Direct Spec 由当前 I-implement owner 按 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 关闭 change。
|
|
149
149
|
|
|
150
|
-
按存在和当前模式同步 Ticket、Tickets Map、Goal Plan、`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 和全局状态;Direct Spec 不创建缺失的 Ticket/Map/Goal Plan。最后一个计划内 Ticket 完成后,Goal Plan 的 Lead 按 change completion 关闭;无 Goal Plan 的当前 I owner 承担同一门禁。需要远程 reconcile 时返回 T-triage,否则进入 Archive。
|
|
150
|
+
按存在和当前模式同步 Ticket、Tickets Map、Goal Plan、`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 和全局状态;Direct Spec 不创建缺失的 Ticket/Map/Goal Plan。最后一个计划内 Ticket 完成后,Goal Plan 的 Lead 按 change completion 关闭;无 Goal Plan 的当前 I owner 承担同一门禁。需要远程 reconcile 或把已完成 Ticket 投影为 GitHub Issue 时返回 T-triage,否则进入 Archive。
|
|
151
151
|
|
|
152
152
|
当前 change 属于未完成父实现 change 时,单个组合 Ticket 完成、阻塞或触发 Lead 复盘,且子状态与 Evidence 已写入后,必须自动返回 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`,由父 Lead 重读全部成员并决定重新派发、返回上游或继续下一 frontier;不得要求用户逐个重新激活,不得直接归档子 change,也不得从本 Work 实现另一个成员。
|
|
153
153
|
|
|
@@ -10,4 +10,4 @@ SpecDev 只使用本地 Markdown/JSON 工件跟踪开发。远程 Issue、URL
|
|
|
10
10
|
- 工件状态应在同一次操作中同步,避免入口状态、Ticket 状态与 Map 状态漂移。
|
|
11
11
|
- 完成条件:全部必需 Ticket 为 `done` 或有批准的 `cancelled`,证据齐全,无未批准 deviation,change 级验证通过。
|
|
12
12
|
- 归档后的 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>` 默认只读;后续纠正通过新 change 和 supersedes 链完成。
|
|
13
|
-
- 可关闭的远程来源在本地完成后由 Triage reconcile;`closed`、显式 `waived` 或 `not-applicable`
|
|
13
|
+
- 可关闭的远程来源在本地完成后由 Triage reconcile;`closed`、显式 `waived` 或 `not-applicable` 后才归档。完成后若要把 Ticket 记到 GitHub,由 T-triage publish 写入 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`;`pending`/`publish-failed` 不可归档。尚未成 Change 的记事项由 T-triage capture 写入 `<Path>{roots.state}/specdev/capture.md</Path>`(缺失合法),Issue 保持 open,不创建 change。发布计数与 inbox 计数都以对应本地账本为准,标签词表见 T-triage classification-map。远程 Issue 仍不是开发权威。
|
|
@@ -3,7 +3,7 @@ id: specdev
|
|
|
3
3
|
type: workflow
|
|
4
4
|
workflow: specdev
|
|
5
5
|
name: SpecDev Workflow
|
|
6
|
-
description: 以本地工件为唯一开发权威,从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile
|
|
6
|
+
description: 以本地工件为唯一开发权威,从来源冻结、诊断、设计、原型、规格、Ticket、编排和审查推进到证据驱动实现、远程 reconcile 或票级发布投影、记事项捕获与知识归档。
|
|
7
7
|
keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototype, code-review, TDD, 证据]
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
## 工件链与权威
|
|
10
10
|
|
|
11
|
-
大需求 → W 的 Initiative 候选图 → 每个 change 自己的 G/Grill → S/Spec → T 的计划型 Ticket 与 tickets-map → P 的 Goal → I/实现与 Evidence → Goal 集成验收 → 按需学习/远程 reconcile
|
|
11
|
+
大需求 → W 的 Initiative 候选图 → 每个 change 自己的 G/Grill → S/Spec → T 的计划型 Ticket 与 tickets-map → P 的 Goal → I/实现与 Evidence → Goal 集成验收 → 按需学习/远程 reconcile 或 publish/归档。尚未成 Change 的记事项可先 T-triage capture 到 GitHub inbox,再逐条 intake。
|
|
12
12
|
|
|
13
13
|
已明确的小请求直接进入适用阶段;无需为了路由而创建 Triage。跨 change 实现由 P 统一管理。
|
|
14
14
|
|
|
@@ -47,14 +47,14 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
|
|
|
47
47
|
|
|
48
48
|
## 场景路由
|
|
49
49
|
|
|
50
|
-
不清晰的大需求选 W,单 change 的高影响决定选 G,Ready Spec 拆票选 T-tickets,一个或多个 Ready change 的 Goal 选 P-goal-plan
|
|
50
|
+
不清晰的大需求选 W,单 change 的高影响决定选 G,Ready Spec 拆票选 T-tickets,一个或多个 Ready change 的 Goal 选 P-goal-plan;来源冻结/远程回写/完成后记账/尚未成 Change 的记事项才选 T-triage。精确条件与全部出口见 `<Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>`。
|
|
51
51
|
|
|
52
52
|
## Work 条目
|
|
53
53
|
|
|
54
54
|
|
|
55
55
|
<!-- AUTO-INDEX-START -->
|
|
56
56
|
|
|
57
|
-
- **A-archive-and-consolidate** —
|
|
57
|
+
- **A-archive-and-consolidate** — 归档与沉淀:校验本地完成、源 Issue reconcile 门和票级 publish_action 门,复用全局归档能力移动 completed change 并提升当前知识,或从代码访谈形成可归档知识 change。
|
|
58
58
|
- **C-code-review** — 代码审查:将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点,执行隔离的标准轴与规范轴审查并持久化可恢复报告。
|
|
59
59
|
- **D-diagnose-bugs** — 诊断 Bug:先建立会在精确症状上变红的紧凑反馈回路,再通过最小化、排名假设和单变量探针确认根因,输出修复契约而不实施生产修复。
|
|
60
60
|
- **G-grill-with-docs** — Change 决策访谈:一个已界定 change 仍有产品、领域或架构决定待确认时进行可恢复访谈;跨 change 边界未清晰时先用 W。
|
|
@@ -66,7 +66,7 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
|
|
|
66
66
|
- **R-review-architecture** — 架构审查:从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险,以中文 Markdown 记录高置信候选,并对用户选择的一个方案运行设计树访谈。
|
|
67
67
|
- **S-spec** — 编写 Spec:综合已知事实、设计决定、诊断与代码现状,产出以外部行为和验收合同为权威的 Ready Spec。
|
|
68
68
|
- **T-tickets** — 编写计划型 Tickets:将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket,并绑定真实项目 Skill;不用于探索未知需求或执行代码。
|
|
69
|
-
- **T-triage** —
|
|
69
|
+
- **T-triage** — 请求分诊:需要冻结外部来源、审计摄入、对 completed change 回写来源 Issue、把已完成 Ticket 投影为带分类标签的 GitHub Issue,或把尚未成 Change 的记事项写成仍 open 的 GitHub Issue 时使用;已清晰的本地需求不必为了路由而经本入口。
|
|
70
70
|
- **W-wayfinder** — 探索大需求与 Change 边界:大需求的 change 边界或实施路线尚不可见时建立探索地图,并分别澄清各 change;已有清晰 Spec 时不触发。
|
|
71
71
|
|
|
72
72
|
<!-- AUTO-INDEX-END -->
|
|
@@ -3,15 +3,15 @@ id: specdev/triage
|
|
|
3
3
|
type: workflow-entry
|
|
4
4
|
workflow: specdev
|
|
5
5
|
name: 请求分诊
|
|
6
|
-
description:
|
|
7
|
-
keywords: [triage, 摄入, import, issue, reconcile, close, 风险, 路由]
|
|
6
|
+
description: 需要冻结外部来源、审计摄入、对 completed change 回写来源 Issue、把已完成 Ticket 投影为带分类标签的 GitHub Issue,或把尚未成 Change 的记事项写成仍 open 的 GitHub Issue 时使用;已清晰的本地需求不必为了路由而经本入口。
|
|
7
|
+
keywords: [triage, 摄入, import, issue, reconcile, publish, capture, close, 风险, 路由]
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# 请求分诊
|
|
11
11
|
|
|
12
12
|
> 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
|
|
13
13
|
|
|
14
|
-
Triage 是 SpecDev
|
|
14
|
+
Triage 是 SpecDev 唯一的远程摄入、关闭、发布投影与记事项捕获边界。开发期间,change 级 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`、Spec、Ticket、Map、Goal Plan、Evidence 和状态文件是开发唯一权威;workspace 级 `<Path>{roots.state}/specdev/capture.md</Path>` 是尚未成 Change 的 inbox 计数权威(缺失合法)。远程系统只保存原始请求、经确认后的完成通知、票级发布记录,以及仍 open 的记事项。GitHub 不是 tracker,也不是开发权威。
|
|
15
15
|
|
|
16
16
|
## 读取范围
|
|
17
17
|
|
|
@@ -19,28 +19,31 @@ Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间,`<Path>
|
|
|
19
19
|
2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
|
|
20
20
|
3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
普通本地请求直接进入适用 Work,不为了完成路由额外创建来源工件。用户明确要求来源审计时仍执行完整 intake;缺陷根因诊断仍交 D,不删除风险分诊与远程回写能力。
|
|
22
|
+
普通本地请求直接进入适用 Work,不为了完成路由额外创建来源工件。用户明确要求来源审计时仍执行完整 intake;缺陷根因诊断仍交 D,不删除风险分诊与远程回写能力。完成后要记账才选 publish。尚未成 Change、只想先在 GitHub 留一条仍 open 的记录时才选 capture。
|
|
24
23
|
|
|
25
24
|
## 模式
|
|
26
25
|
|
|
27
26
|
- **intake**:冻结输入、创建或恢复 change、分类并返回下一 Work。
|
|
28
|
-
- **reconcile**:本地 change 已完成后,确认远程完成摘要并关闭支持的 GitHub Issue;不重新分诊或修改开发契约。
|
|
27
|
+
- **reconcile**:本地 change 已完成后,确认远程完成摘要并关闭支持的 GitHub 来源 Issue;不重新分诊或修改开发契约。
|
|
28
|
+
- **publish**:本地 change 已完成后,把计划内 Ticket 投影为带分类标签的 GitHub Issue,用脱敏 Evidence 关闭它们,并留下 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 账本。标签必须包含 `specdev:published`。
|
|
29
|
+
- **capture**:尚未有 Change 时,把记事项写成仍 open 的 GitHub Issue,并留下 `<Path>{roots.state}/specdev/capture.md</Path>`。标签必须包含 `specdev:captured`。不创建 change,不写 change 级 triage 工件,`mode=capture` 不得出现在 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`。
|
|
29
30
|
|
|
30
31
|
## 共同启动
|
|
31
32
|
|
|
32
33
|
1. 解析 roots,按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和 change 状态。
|
|
33
|
-
2. Intake 可以创建 change;reconcile 必须选择一个已存在的 completed change
|
|
34
|
-
3.
|
|
35
|
-
4. 重读已有 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`,不覆盖已冻结的来源。
|
|
34
|
+
2. Intake 可以创建 change;reconcile 与 publish 必须选择一个已存在的 change。publish 的对象必须已 completed。capture 既不创建也不选择 change,不写 `current_work`,不加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`。
|
|
35
|
+
3. 仅 intake、reconcile 与 publish:若该 change 的 `current_work` 为 null,设置为 `specdev/triage`;指向其他 Work 时先恢复或完成显式 handoff。capture 跳过本步。
|
|
36
|
+
4. 重读已有 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`,不覆盖已冻结的来源。publish 在本地源缺失这些文件时可以按协议补建轻量快照,仍不得虚构 GitHub locator。capture 不读、不写这些文件。
|
|
37
|
+
|
|
38
|
+
`external_action` 只描述源 Issue。`publish_action` 只描述票级发布投影。capture 行 state 只描述 inbox 记录。三者互不覆盖。未授权时远程写入为零。
|
|
36
39
|
|
|
37
40
|
## Intake
|
|
38
41
|
|
|
39
42
|
输入为远程 Issue、URL、项目相对文件、用户粘贴内容或当前对话时,加载 `<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>`:
|
|
40
43
|
|
|
41
44
|
1. 按协议解析来源、查重、脱敏、冻结并计算内容 hash;使用 `<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>` 原子写入 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`。
|
|
42
|
-
2. 按需读取永久 ADR/CONTEXT、当前 change
|
|
43
|
-
3. 分类为 bug、feature、refactor、investigation、operations、documentation、review 或 mixed
|
|
45
|
+
2. 按需读取永久 ADR/CONTEXT、当前 change 工件和相关代码事实;缺失的可选输入静默跳过。相似的已归档拒绝或 ADR 只展示,不自动 wontfix,也不回写源 Issue 标签。
|
|
46
|
+
3. 分类为 bug、feature、refactor、investigation、operations、documentation、review 或 mixed。对照见 `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`。
|
|
44
47
|
4. 评估影响、紧急度、事故半径、安全、数据、迁移和人工批准;把未知项分为可发现事实、decision-needed 和低影响实现细节。
|
|
45
48
|
5. 使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`。
|
|
46
49
|
6. 运行阶段校验并返回最小正确路线:
|
|
@@ -59,15 +62,55 @@ Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间,`<Path>
|
|
|
59
62
|
本地 change 完成并需要关闭来源 Issue 时,加载:
|
|
60
63
|
|
|
61
64
|
- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`;
|
|
62
|
-
- `<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path
|
|
65
|
+
- `<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`;
|
|
66
|
+
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
63
67
|
|
|
64
68
|
按协议重验本地完成、生成最小外部摘要、展示准确目标和动作、取得本次明确授权,再调用 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>`。成功时把 `external_action` 更新为 `closed`;部分或完全失败为 `close-failed` 并保留可重试检查点;用户明确不关闭时为 `waived`。任何结果都不改写本地完成事实。
|
|
65
69
|
|
|
66
|
-
Reconcile 成功或 waived 后返回 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。不支持关闭的来源使用 `not-applicable`,无需虚构 provider。
|
|
70
|
+
Reconcile 成功或 waived 后返回 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。不支持关闭的来源使用 `not-applicable`,无需虚构 provider。若用户同时要求 publish,源 Issue 仍不是票 Issue。
|
|
71
|
+
|
|
72
|
+
## Publish
|
|
73
|
+
|
|
74
|
+
本地 change 完成、用户指定该 change 并要求把 Ticket 记到 GitHub 时,加载:
|
|
75
|
+
|
|
76
|
+
- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`;
|
|
77
|
+
- `<Path>{roots.workflows}/specdev/T-triage/publish-protocol.md</Path>`;
|
|
78
|
+
- `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`;
|
|
79
|
+
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
80
|
+
|
|
81
|
+
按协议走硬门、确认表、dry-run,再调用 github-npm-ops 的 `issue-search` / `issue-create` / `issue-comment-close`。账本写 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`。Issue 正文用 `<Path>{roots.workflows}/specdev/T-triage/issue-body-template.md</Path>`,关闭评论用 `<Path>{roots.workflows}/specdev/T-triage/close-comment-template.md</Path>`。
|
|
82
|
+
|
|
83
|
+
成功 `published`、用户放弃 `waived`,或从未请求的 `not-requested` 才允许归档。`pending` 与 `publish-failed` 挡住 Archive。下一站由用户指定:reconcile、A,或停止。
|
|
84
|
+
|
|
85
|
+
workspace 计数:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
node <Path>{roots.workflows}/specdev/T-triage/tools/publish-status.mjs</Path> \
|
|
89
|
+
--state-root <Path>{roots.state}/specdev</Path>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Capture
|
|
93
|
+
|
|
94
|
+
尚未成 Change、用户要求先把记事项写到 GitHub 时,加载:
|
|
95
|
+
|
|
96
|
+
- `<Path>{roots.workflows}/specdev/T-triage/capture-protocol.md</Path>`;
|
|
97
|
+
- `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`;
|
|
98
|
+
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
99
|
+
|
|
100
|
+
按协议走硬门、确认表、dry-run,再调用 github-npm-ops 的 `issue-search` / `issue-create`。不调用 `issue-comment-close`。账本写 `<Path>{roots.state}/specdev/capture.md</Path>`。Issue 正文用 `<Path>{roots.workflows}/specdev/T-triage/issue-record-template.md</Path>`。默认 1 条记录对应一次未来 intake / 一个未来 Change。攒多了再处理:批量 capture,然后逐条 intake 或先走 W;不把多条 locator 写入同一个 source。
|
|
101
|
+
|
|
102
|
+
成功留下仍 open 的 inbox Issue。intake 消费到同一 locator 时把对应行标为 `intaken`。用户放弃为 `waived`。capture 不挡 Archive,因为没有 change 可归档。
|
|
103
|
+
|
|
104
|
+
workspace inbox 计数:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
node <Path>{roots.workflows}/specdev/T-triage/tools/capture-status.mjs</Path> \
|
|
108
|
+
--state-root <Path>{roots.state}/specdev</Path>
|
|
109
|
+
```
|
|
67
110
|
|
|
68
111
|
## 状态与验证
|
|
69
112
|
|
|
70
|
-
运行:
|
|
113
|
+
intake、reconcile 或 publish 运行:
|
|
71
114
|
|
|
72
115
|
```bash
|
|
73
116
|
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
@@ -75,7 +118,16 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
|
75
118
|
<Path>{roots.state}/specdev/changes/{change}</Path>
|
|
76
119
|
```
|
|
77
120
|
|
|
78
|
-
|
|
121
|
+
capture 在账本存在时运行:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
125
|
+
--capture <Path>{roots.state}/specdev/capture.md</Path>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
缺失 `<Path>{roots.state}/specdev/capture.md</Path>` 合法,不要为了校验去创建它。
|
|
129
|
+
|
|
130
|
+
验证通过后,intake / reconcile / publish 原子重读 source、triage、publish(若请求过)和 change 状态;成功时将 `specdev/triage` 去重加入 `works_run` 并清空 `current_work`;可恢复失败保留 `current_work` 和具体 blocker。capture 不改任何 change 状态。
|
|
79
131
|
|
|
80
132
|
## 完成标准
|
|
81
133
|
|
|
@@ -85,11 +137,24 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
|
85
137
|
- 开发权威完全位于本地 state;
|
|
86
138
|
- 未授权时远程写入为零;
|
|
87
139
|
- Reconcile 可从失败检查点幂等恢复;
|
|
140
|
+
- Publish 可从 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 失败行幂等恢复,cancelled 默认 skip,本地源计入发布数;
|
|
141
|
+
- Capture 可从 `<Path>{roots.state}/specdev/capture.md</Path>` 失败行幂等恢复,Issue 保持 open,不创建 Change;
|
|
88
142
|
- 状态、验证结果和下一 Work 完整路径已返回。
|
|
89
143
|
|
|
90
144
|
## 子文件引用
|
|
91
145
|
|
|
92
146
|
- Intake:`<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>`
|
|
93
147
|
- Reconcile:`<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`
|
|
148
|
+
- Publish:`<Path>{roots.workflows}/specdev/T-triage/publish-protocol.md</Path>`
|
|
149
|
+
- Capture:`<Path>{roots.workflows}/specdev/T-triage/capture-protocol.md</Path>`
|
|
94
150
|
- Source 模板:`<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>`
|
|
95
151
|
- Triage 模板:`<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>`
|
|
152
|
+
- Publish 模板:`<Path>{roots.workflows}/specdev/T-triage/publish-template.md</Path>`
|
|
153
|
+
- Capture 模板:`<Path>{roots.workflows}/specdev/T-triage/capture-template.md</Path>`
|
|
154
|
+
- 分类映射:`<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`
|
|
155
|
+
- 公共投影:`<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`
|
|
156
|
+
- Issue 正文:`<Path>{roots.workflows}/specdev/T-triage/issue-body-template.md</Path>`
|
|
157
|
+
- 记事项正文:`<Path>{roots.workflows}/specdev/T-triage/issue-record-template.md</Path>`
|
|
158
|
+
- 关闭评论:`<Path>{roots.workflows}/specdev/T-triage/close-comment-template.md</Path>`
|
|
159
|
+
- 发布计数:`<Path>{roots.workflows}/specdev/T-triage/tools/publish-status.mjs</Path>`
|
|
160
|
+
- inbox 计数:`<Path>{roots.workflows}/specdev/T-triage/tools/capture-status.mjs</Path>`
|