@seanmars/tospec 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@
 
 tospec 是一套 spec-driven development CLI: 以 schema 定義文件結構與工作流程, 進度由檔案系統狀態推算, 開發方法則封裝於 Skill 之中, 使 AI 工具 (Claude Code / Codex) 得以循序完成需求釐清、規格撰寫、設計、任務拆解、實作到歸檔的完整流程.
 
+## [0.23.0] - 2026-09-30
+
+本版本修正 code review 找到的**文件與 prompt 跟實際行為不一致**的地方: schema 交給 apply 的指示和預設 apply skill 對測試的要求互相矛盾, README 與 `docs/custom-schema.md` 列出的 artifact 狀態和原始碼不符, decision schema 註解寫的 ADR 檔名格式也和 CLI 實際寫出的不同.
+
+### 修正
+
+- **sdd / issue schema 的 `apply.instruction` 不再規定測試順序**: 使用預設 `tospec-apply` 時, agent 從 `tospec instructions apply` 拿到的 `instruction` 寫著 sdd 要 "Execute tasks.md with TDD", issue 要 "write a regression test that goes red first", skill 本身卻說測試是選配. 同一份 briefing 裡兩個指令互相矛盾. 根本原因是 `apply.instruction` 會原封不動交給兩個 apply 變體, 但 schema 在裡面規定了只屬於 `tospec-apply-with-tdd` 的做法. 0.22.0 只處理了 skill 這一側 (釐清 `tasks.md` 的測試步驟屬於 slice), 沒有處理 schema 這一側. 現在 schema 只說明要照 `tasks.md` 與 `task.md` 執行, 測試是否必須先 red 交給使用中的 apply skill 決定. 沒有採用為每個 schema 再做一份不含 TDD 的版本, 或放寬 TDD skill 的要求: 前者讓兩份 schema 的內容日後會分歧, 後者會拿掉使用者刻意選擇 TDD 變體時要的保證.
+
+### 其他
+
+- **README 與 `docs/custom-schema.md` 的 artifact 狀態更正為六種**: README 寫「文件狀態只有四種」, 但 `ArtifactStatusValue` 另外還有 `stub` (檔案存在但是空白或與 template 相同) 與 `optional`. README 把 `skipped` 解釋成「選配文件沒建」, 那其實是 `optional` 的意思; `skipped` 只會出現在 change 宣告 `skip_specs: true` 的情況. `docs/custom-schema.md` 的 `optional:` 欄位註解也寫成未建立時顯示 `skipped`. 兩者在 CLI 共用 `[~]` 標記, 很容易被當成同一件事.
+- **decision schema 註解的 ADR 檔名格式**: 註解寫 `<yyyy-MM-dd>-<topic>.md`, `tospec decision` 實際寫出的是 `<yyyyMMdd_HHmmss>-<topic>.md`.
+
 ## [0.22.0] - 2026-09-24
 
 本版本的主題是**減少 agent 每次 request 要讀的重複與過度強調的 prompt**. workflow 改為只以 Skill 提供, 不再同時產生內容會分歧的 `/tosx:<name>` slash command; 所有 skill 依 prompt audit 調整針對舊模型寫的全大寫強調與重複限制. audit 過程中也找出幾處 prompt 彼此矛盾或與 CLI 行為不符的地方, 一併修正.
@@ -471,6 +484,7 @@ Dashboard 進化為可背景常駐、多專案並存的服務, 並補上 TDD 導
 
 - 新增 `prepack` script 與 npm publish 的準備設定, 完備套件發行流程.
 
+[0.23.0]: https://github.com/seanmars/tospec/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/seanmars/tospec/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/seanmars/tospec/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/seanmars/tospec/compare/v0.18.0...v0.20.0

package/README.md

@@ -51,12 +51,14 @@ tospec archive add-dark-mode
 
 兩者都在 **apply** 階段實作, 最後由 **archive** 判斷要不要先 **sync** 再歸檔. apply 的完成標準是測試與 `tospec validate` 通過; 雙軸審查 (verify) 是 opt-in, 使用者開口才做.
 
-文件狀態只有四種:
+文件狀態有六種:
 
-- `done`: 檔案已存在
+- `done`: 檔案已存在且有內容
+- `stub`: 檔案存在但是空白或與 template 相同, 不算完成, 也不解鎖後續文件
 - `ready`: 前置文件都齊了, 這份還沒寫, 可以開始
 - `blocked`: 至少一份前置文件還沒建立
-- `skipped`: 選配文件沒建, 不擋流程
+- `optional`: 選配文件沒建, 不擋流程, 需要時再寫
+- `skipped`: change 以 `skip_specs: true` 宣告不需要 `specs`, 不擋流程
 
 ## Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanmars/tospec",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Spec-driven development CLI for structured requirements and issue workflows",
   "license": "MIT",
   "homepage": "https://www.npmjs.com/package/@seanmars/tospec",

package/schemas/decision/schema.yaml

@@ -3,7 +3,7 @@ version: 1
 description: Architecture Decision Record (ADR) workflow
 artifacts:
   # decision is created by the dedicated `tospec decision` command at
-  # tospec/decisions/<yyyy-MM-dd>-<topic>.md; it does not go through the change
+  # tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md; it does not go through the change
   # directory. This artifact only serves as the template and section-validation
   # data contract.
   - id: decision

package/schemas/issue/schema.yaml

@@ -44,7 +44,7 @@ apply:
   requires: [task]
   tracks: task.md
   instruction: |
-    Fix per task.md: first check whether a related test exists —
-    exists and fails → find out why it fails; exists and passes → check for missing
-    edge cases and add tests; none → write a regression test that goes red first.
-    Fix until everything is green, and verify it matches task.md.
+    Fix the root cause per task.md and confirm it with task.md's feedback loop,
+    keeping the existing suite green. Whether a new regression test is required,
+    and whether it must go red first, is set by the apply skill in use
+    (tospec-apply-with-tdd mandates it), not here. Verify the fix matches task.md.

package/schemas/sdd/schema.yaml

@@ -106,6 +106,7 @@ apply:
   requires: [tasks]
   tracks: tasks.md
   instruction: |
-    Execute tasks.md with TDD: each slice writes a failing test first (red), then
-    implements until it passes (green), testing only the seam design.md chose.
-    When done, verify behavior against the specs.
+    Execute tasks.md slice by slice, including the test tasks it lists; test only
+    the seam design.md chose. Whether each test must go red before its
+    implementation is set by the apply skill in use (tospec-apply-with-tdd
+    mandates it), not here. When done, verify behavior against the specs.