@seanmars/tospec 0.19.0-beta.3 → 0.19.0-beta.4

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/assets/rules/tospec/single-sourc-of-truth.md +17 -2
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,20 @@
6
6
 
7
7
  tospec 是一套 spec-driven development CLI: 以 schema 定義文件結構與工作流程, 進度由檔案系統狀態推算, 開發方法則封裝於 Skill 之中, 使 AI 工具 (Claude Code / Codex) 得以循序完成需求釐清、規格撰寫、設計、任務拆解、實作到歸檔的完整流程.
8
8
 
9
+ ## [0.19.0-beta.4] - 2026-09-10
10
+
11
+ **預發布版本**: 需以 `npm install @seanmars/tospec@beta` 明確指定才會安裝, `latest` 仍指向 0.18.0.
12
+
13
+ 本版本只改一份檔案的正文: 隨套件發布、載入到 agent 的 workflow 規則模板. 0.19.0-beta.3 已經把它縮減為正確的兩條原則, 這次要處理的不是它要求什麼, 而是它怎麼被讀 — 一份以權威身分載入 agent 的文字, 若只寫命令不寫理由, 它能約束的就只有它字面涵蓋到的情境.
14
+
15
+ ### 變更
16
+
17
+ - **workflow 規則模板改寫為結構化英文, 每條規則附上自己的失效機制**: 模板正文原本是兩條 bullet, 第一條英文、第二條中文, `IMPORTANT:` 夾在第一條的句子中間, 兩條都只給命令不給理由. 混語言與埋沒的強調只是表面症狀; 成因在於這份檔案的身分 — 它是被當成權威來源載入 agent 的那一份文字, 而沒有理由的命令在邊界情境無法自我防守: agent 讀得懂「除非必要」的字面意思, 卻推不出違反它會發生什麼, 於是「必要」的門檻實際上由當下的方便程度決定. 第一條還有一個更具體的問題: 「以程式碼為準」沒有指出方向, 而 tospec 自身就內建 `/tospec-sync` 這種把規格對齊程式碼的流程, 「文件與程式碼不一致」因此很容易被讀成「該修程式碼讓它符合文件」, 恰好是這條規則要禁止的那一半. 現改為兩個具名 section, 各自寫出規則、可執行的行為 (回報落差而非改程式碼去迎合文件; 斷言前先在程式碼中驗證) 與失效機制 (文件記錄的是撰寫當下的意圖, 會隨程式演進漂移; 歸檔目錄不隨程式更新), 並把優先序提到標題下方獨立一行, 明講它高於文件、註解、規劃產物與先前對話. 只把中文那條翻成英文的最小改法被否決: 那修掉了語言不一致, 卻原樣留下真正會失效的部分. 規則語意一字未變, `agent-workflow-rules` 規格要求的三件事 (程式碼優先、預設不讀兩個 archive 目錄、只保留原則而不複製各 skill 的程序) 全數保留, 因此本次沒有 delta spec. 既有產出檔的正文仍符合自身記錄的雜湊, 下次 `init` / `tospec rules` / `update` 會判定為正常升級而非衝突, 使用者無須手動處理.
18
+
19
+ ### 其他
20
+
21
+ - **本版未立為 change, 也未新增 ADR**: 變更落在 `agent-workflow-rules` 既有規格的框架之內, 是措辭與結構的改寫, 沒有推翻或新立任何取捨, 因此 `tospec/decisions/` 自 0.19.0-beta.3 的三份 ADR 之後沒有新增. 本專案自身的 `.claude` / `.codex` 規則檔已由 `tospec rules` 重新產生, 與 `assets/` 模板同步. 上游 OpenSpec 參考點仍停在 `e062b95` (1.12.0), 本版與上游比對無關. 測試 959 passed / 1 skipped (78 個檔案).
22
+
9
23
  ## [0.19.0-beta.3] - 2026-09-10
10
24
 
11
25
  **預發布版本**: 需以 `npm install @seanmars/tospec@beta` 明確指定才會安裝, `latest` 仍指向 0.18.0.
@@ -449,6 +463,7 @@ Dashboard 進化為可背景常駐、多專案並存的服務, 並補上 TDD 導
449
463
 
450
464
  - 新增 `prepack` script 與 npm publish 的準備設定, 完備套件發行流程.
451
465
 
466
+ [0.19.0-beta.4]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.3...v0.19.0-beta.4
452
467
  [0.19.0-beta.3]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.2...v0.19.0-beta.3
453
468
  [0.19.0-beta.2]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.1...v0.19.0-beta.2
454
469
  [0.19.0-beta.1]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.0...v0.19.0-beta.1
package/assets/rules/tospec/single-sourc-of-truth.md CHANGED
@@ -1,4 +1,19 @@
1
1
  # Single Source of Truth
2
2
 
3
- - IMPORTANT: Source code is the single source of truth. If any information elsewhere is inconsistent with source code, the content of source code should be considered correct.
4
- - 除非必要或者使用者明確要求, 否則不要讀取 `tospec/changes/archive`, `tospec/tickets/archive` 目錄下的文件, 因為這些文件可能是過時的, 並且不會自動更新.
3
+ **Priority: MUST. This rule outranks any conflicting statement you find in documentation, comments, planning artifacts, or earlier conversation.**
4
+
5
+ ## 1. Source code is authoritative
6
+
7
+ The source code in this repository is the only authoritative description of how the system actually behaves. Specifications, design documents, READMEs, changelogs, code comments, and prior summaries are secondary: each records intent at the moment it was written, and each drifts as the code moves on.
8
+
9
+ - When a document contradicts the code, **the code is correct**. Report the discrepancy; do not change the code to match the document unless the user explicitly asks for that.
10
+ - Before asserting how something works, verify it in the code. An answer sourced from a document alone is unverified.
11
+
12
+ ## 2. Archived documents are presumed stale
13
+
14
+ Do not read files under `tospec/changes/archive/` or `tospec/tickets/archive/` unless one of these holds:
15
+
16
+ - the task genuinely cannot be completed without them, or
17
+ - the user explicitly asks you to.
18
+
19
+ These directories store snapshots of finished work. Nothing updates them when the code changes, so treating them as current will make you describe behavior that no longer exists.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seanmars/tospec",
3
- "version": "0.19.0-beta.3",
3
+ "version": "0.19.0-beta.4",
4
4
  "description": "Spec-driven development CLI for structured requirements and issue workflows",
5
5
  "license": "MIT",
6
6
  "homepage": "https://www.npmjs.com/package/@seanmars/tospec",