@seanmars/tospec 0.9.0 → 0.11.0

package/schemas/decision/templates/decision.md

@@ -1,37 +1,37 @@
-# [決策主題]
+# [decision topic]
 
-## 狀態
+## Status
 
 - proposed
-- 日期:[yyyyMMdd_HHmmss]
+- Date: [yyyyMMdd_HHmmss]
 
-<!-- 狀態: proposed(已提出) / accepted(已採用) / superseded(已被取代, 需註明取代者) -->
+<!-- Status: proposed / accepted / superseded (name the successor when superseded) -->
 
-## 背景
-<!-- 為什麼要做這個決策: 現況、限制與需求目標 -->
+## Context
+<!-- Why this decision is needed: current state, constraints, and requirement goals -->
 
-## 決策
-<!-- 選了什麼方案; canonical 術語; 為什麼這樣選而非其他方案 -->
+## Decision
+<!-- What was chosen; the canonical terms; why this over the other options -->
 
-## 影響
-<!-- 受影響的模組 / API / 文件 / 測試 -->
+## Impact
+<!-- Affected modules / APIs / docs / tests -->
 
-## 替代方案
-<!-- 評估過哪些方案, 各自優缺點與結論 -->
+## Alternatives
+<!-- Options evaluated, their trade-offs, and the conclusion -->
 
-## 後續工作
-<!-- 分階段的後續實作項目 -->
+## Follow-up
+<!-- Follow-up implementation items, phased if useful -->
 
-## 關聯變更
-<!-- 選配: 實作此決策的 change (由 tospec new change --decisions 反向連結); 列出 change 名稱, 歸檔後可補歸檔路徑; 尚無實作可省略 -->
+## Related Changes
+<!-- Optional: changes that implement this decision (back-linked by tospec new change --decisions); list change names, add archive paths once archived; omit if none yet -->
 
-## 決策過程
-<!-- 選配: 關鍵問答紀錄; 每組以 **Q:** 開頭, 下一段為回答; 摘要即可, 不貼逐字稿; 無互動討論可省略 -->
+## Decision Process
+<!-- Optional: the key Q&A that shaped this decision; each pair starts with **Q:**, answer in the next paragraph; summarize, don't paste a transcript; omit if there was no interactive discussion -->
 
-**Q:** [問題]
+**Q:** [question]
 
-[回答]
+[answer]
 
-**Q:** [問題]
+**Q:** [question]
 
-[回答]
+[answer]

package/schemas/issue/schema.yaml

@@ -2,18 +2,20 @@ name: issue
 version: 1
 description: Diagnosis and repair workflow for issues
 artifacts:
-  # ticket 是 CLI 管理的全域索引 (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
-  # 不是 graph artifact: 由 `tospec new change` 自動產生於 change 目錄之外, 故不列於此。
+  # ticket is a CLI-managed global index (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
+  # not a graph artifact: `tospec new change` auto-generates it outside the change
+  # directory, so it is not listed here.
   - id: task
     generates: task.md
     description: Root-cause diagnosis and repair plan
     template: task.md
     requires: []
     instruction: |
-      診斷並撰寫 issue task: 先建立 tight feedback loop (一個指令能讓
-      這個 bug 變 red), 列 3-5 個可否證的假設並排序, 逐一驗證後寫下根因。
-      內容: 根因分析、修正方案、測試計畫 (既有測試為何沒抓到 / 缺哪些
-      edge case)、任務 checkbox 清單。
+      Diagnose and write the issue task: first build a tight feedback loop (one
+      command that turns this bug red), list 3-5 falsifiable hypotheses and rank
+      them, verify each, then write down the root cause. Contents: root-cause
+      analysis, fix plan, test plan (why existing tests missed it / which edge
+      cases are missing), and a task checkbox list.
     validation:
       requiredSections: [Feedback Loop, Root Cause, Fix Plan, Test Plan, Tasks]
   - id: specs
@@ -23,12 +25,14 @@ artifacts:
     requires: []
     optional: true
     instruction: |
-      僅當修正會改變對外行為時撰寫 delta specs (文法同 sdd)。
-      若 bug 源於 spec 本身錯誤, 用 MODIFIED 修正該 Requirement。
+      Write delta specs only when the fix changes externally observable behavior
+      (same grammar as sdd). If the bug stems from a wrong spec, fix that
+      Requirement with MODIFIED.
 apply:
   requires: [task]
   tracks: task.md
   instruction: |
-    依 task.md 修正: 先確認是否已有相關測試 —
-    有且失敗 → 找出為何失敗; 有且通過 → 檢查 edge case 缺漏, 補測試;
-    沒有 → 先寫會 red 的回歸測試。修到全綠, 並驗證符合 task.md 規範。
+    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.

package/schemas/issue/templates/spec.md

@@ -1,13 +1,13 @@
 ## ADDED Requirements
 
-### Requirement: [名稱]
-[系統 SHALL/MUST ... 的行為描述 — 關鍵字必須在內文, 不能只在標題]
+### Requirement: [name]
+[Behavior the system SHALL/MUST ... — the keyword must appear in the body, not only in the heading]
 
-#### Scenario: [情境名稱]
-- **WHEN** [條件]
-- **THEN** [結果]
-- **AND** [附加結果]
+#### Scenario: [scenario name]
+- **WHEN** [condition]
+- **THEN** [outcome]
+- **AND** [additional outcome]
 
-<!-- 亦可使用 MODIFIED、REMOVED、RENAMED Requirements。
-MODIFIED 必須包含完整更新後的 requirement 區塊。
-REMOVED 必須包含 Reason 與 Migration；RENAMED 使用 FROM/TO 配對。 -->
+<!-- MODIFIED, REMOVED, and RENAMED Requirements may also be used.
+MODIFIED must contain the full updated requirement block.
+REMOVED must include Reason and Migration; RENAMED uses a FROM/TO pair. -->

package/schemas/issue/templates/task.md

@@ -1,21 +1,21 @@
-# Task: [issue 名稱]
+# Task: [issue name]
 
 ## Feedback Loop
-[能讓這個 bug 變 red 的單一指令]
+[The single command that turns this bug red]
 
 ## Root Cause
-[驗證過的根因 — 不是猜測; 附驗證方式]
+[The verified root cause — not a guess; include how it was verified]
 
 ## Fix Plan
-[修正方案與理由; 為什麼修這裡是根因修法而非症狀修法]
+[The fix and its rationale; why fixing here is a root-cause fix rather than a symptom fix]
 
 ## Test Plan
-- 既有測試為何沒抓到: [分析]
-- 需補的測試 / edge cases: [清單]
+- Why existing tests didn't catch it: [analysis]
+- Tests / edge cases to add: [list]
 
 ## Tasks
-### 1. 修正
-- [ ] 1.1 撰寫回歸測試 (red)
-- [ ] 1.2 實作修正至測試通過 (green)
-- [ ] 1.3 補 edge case 測試: [...]
-- [ ] 1.4 跑完整測試套件確認無回歸
+### 1. Fix
+- [ ] 1.1 Write a regression test (red)
+- [ ] 1.2 Implement the fix until the test passes (green)
+- [ ] 1.3 Add edge-case tests: [...]
+- [ ] 1.4 Run the full test suite to confirm no regressions

package/schemas/issue/templates/ticket.md

@@ -1,2 +1,2 @@
 ## Summary
-[一句話描述這個 issue 的現象 — 詳細根因/重現/修法見 task.md]
+[One sentence describing the symptom of this issue — detailed root cause / repro / fix live in task.md]

package/schemas/sdd/schema.yaml

@@ -2,17 +2,19 @@ name: sdd
 version: 1
 description: Spec-driven development workflow for new requirements
 artifacts:
-  # ticket 是 CLI 管理的全域索引 (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
-  # 不是 graph artifact: 由 `tospec new change` 自動產生於 change 目錄之外, 故不列於此。
+  # ticket is a CLI-managed global index (tospec/tickets/<yyyyMMdd_HHmmss>-<name>.md),
+  # not a graph artifact: `tospec new change` auto-generates it outside the change
+  # directory, so it is not listed here.
   - id: proposal
     generates: proposal.md
     description: Main proposal — why, what changes, capabilities, impact
     template: proposal.md
     requires: []
     instruction: |
-      承載主要細節: Why (動機, 為什麼現在做)、What Changes (具體新增/修改/移除)、
-      Capabilities (New/Modified capability 與對應 specs)、Impact (受影響的程式/API/相依/系統)。
-      這是 specs 與 design 展開的依據; 禁止寫入檔案路徑與程式碼片段 (會過時)。
+      Carry the main detail: Why (motivation, why now), What Changes (concrete
+      add/modify/remove), Capabilities (New/Modified capabilities and their specs),
+      Impact (affected code/APIs/dependencies/systems). This is what specs and
+      design expand from; never write file paths or code snippets (they go stale).
     validation:
       requiredSections: [Why, What Changes, Impact]
       minSectionLength:
@@ -23,19 +25,34 @@ artifacts:
     template: spec.md
     requires: [proposal]
     instruction: |
-      依 proposal 撰寫 delta specs。每個 capability 一個檔案。
-      文法: ## ADDED|MODIFIED|REMOVED|RENAMED Requirements /
-      ### Requirement: <名稱> (內文必須含 SHALL 或 MUST) /
-      #### Scenario: <名稱> (四個 #, WHEN/THEN/AND bullet)。
-      MODIFIED 必須貼上完整更新後的 requirement 區塊。
+      Write delta specs from the proposal. One file per capability.
+      Grammar: ## ADDED|MODIFIED|REMOVED|RENAMED Requirements /
+      ### Requirement: <name> (the body must contain SHALL or MUST) /
+      #### Scenario: <name> (four #, WHEN/THEN/AND bullets).
+      MODIFIED must paste the full updated requirement block.
+      A new capability's delta must open with ## Purpose (one sentence on why this
+      capability exists); archive carries it into the newly created main spec. Do
+      not add Purpose to an existing capability's delta (edit the main spec's
+      Purpose directly instead).
   - id: design
     generates: design.md
     description: Technical design and testing seams
     template: design.md
     requires: [proposal]
     instruction: |
-      技術設計: Context、Goals/Non-Goals、Decisions、測試 seam 的選定
-      (優先沿用既有 seam, 越高層越好, 數量越少越好)、Risks、Open Questions。
+      Technical design: Context, Goals/Non-Goals, Decisions, the chosen testing
+      seam (reuse an existing seam, the highest layer possible, as few as possible),
+      Migration Plan, Risks, Open Questions.
+      Decisions: one sub-block per decision, numbered `### D{index}: <title>`
+      (D1, D2, ...). Each opens with a short summary of what was decided, then adds
+      **Why** / **Trade-off** / **Alternative (rejected)** bullets as the decision
+      warrants — not every decision needs all three.
+      Migration Plan: only when the change alters existing data, config, or behavior;
+      otherwise write "No migration needed."
+      proposal covers why and what, design covers how: reference proposal.md, don't
+      restate it. Context holds only the current state and constraints the approach
+      needs (motivation lives in proposal.md - Why); Goals/Non-Goals add design-level
+      boundaries only, not a restatement of the proposal's scope.
     validation:
       requiredSections: [Context, Decisions, Testing Seams]
   - id: tasks
@@ -44,12 +61,14 @@ artifacts:
     template: tasks.md
     requires: [specs, design]
     instruction: |
-      把 specs + design 切成 tracer-bullet 垂直切片任務。
-      每個任務群組 = 一條窄而完整的路徑 (可獨立驗證)。
-      每個實作任務前面都要有對應的「先寫測試」任務 (TDD red 先行)。
+      Cut specs + design into tracer-bullet vertical slices.
+      Each task group = one narrow, complete path (independently verifiable).
+      Every implementation task is preceded by its own "write the test first" task
+      (TDD red before green).
 apply:
   requires: [tasks]
   tracks: tasks.md
   instruction: |
-    依 tasks.md 以 TDD 執行: 每個切片先寫失敗測試 (red), 再實作到通過 (green),
-    只測 design.md 選定的 seam。完成後對照 specs 驗證行為一致。
+    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.

package/schemas/sdd/templates/design.md

@@ -1,14 +1,34 @@
-# Design: [change 名稱]
+# Design: [change name]
 
 ## Context
+[Current state and constraints that shape the approach; see proposal.md - Why for motivation, don't restate it]
 
 ## Goals / Non-Goals
 
+**Goals:**
+[What this design aims to achieve]
+
+**Non-Goals:**
+[What is explicitly out of scope — design-level boundaries only, don't restate the proposal's scope]
+
 ## Decisions
-[每個決策: 選了什麼 / 考慮過什麼 / 為什麼]
+<!-- One sub-block per decision, numbered D1, D2, ... Each opens with a short summary of what was
+     decided, then adds **Why** / **Trade-off** / **Alternative (rejected)** bullets as the
+     decision warrants (not every decision needs all three). Inline a trimmed code/type/schema
+     snippet only when it pins the decision more precisely than prose. -->
+
+### D1: [short title stating the decision]
+[Summary: what was chosen and what it does.]
+
+- **Why**: [rationale]
+- **Trade-off**: [cost accepted — only if there is one]
+- **Alternative (rejected)**: [option considered and why it lost — when a real one existed]
 
 ## Testing Seams
-[測試切入點: 沿用哪個既有 seam, 或新增哪個; 為什麼是這一層]
+[The seam(s) tospec-apply will test at: reuse an existing seam over a new one, the highest layer that still catches the behavior, as few as possible (ideally one); say why this layer]
+
+## Migration Plan
+[Only when the change alters existing data, config, or behavior: migration steps, backward-compat handling, rollout order. Otherwise: "No migration needed."]
 
 ## Risks / Trade-offs
 

package/schemas/sdd/templates/proposal.md

@@ -1,15 +1,15 @@
 ## Why
-<!-- 動機: 解決什麼問題, 為什麼現在做 (>= 50 字) -->
+<!-- Motivation: what problem does this solve, why now (>= 50 chars) -->
 
 ## What Changes
-<!-- 具體變更: 新增 / 修改 / 移除 了什麼 -->
+<!-- Concrete changes: what is added / modified / removed -->
 
 ## Capabilities
 ### New Capabilities
-- `<name>`: <描述> (對應 specs/<name>/spec.md)
+- `<name>`: <description> (maps to specs/<name>/spec.md)
 
 ### Modified Capabilities
-- `<existing-name>`: <改變的 requirement>
+- `<existing-name>`: <the requirement that changes>
 
 ## Impact
-<!-- 受影響的程式 / API / 相依 / 系統 -->
+<!-- Affected code / APIs / dependencies / systems -->

package/schemas/sdd/templates/spec.md

@@ -1,13 +1,13 @@
 ## ADDED Requirements
 
-### Requirement: [名稱]
-[系統 SHALL/MUST ... 的行為描述 — 關鍵字必須在內文, 不能只在標題]
+### Requirement: [name]
+[Behavior the system SHALL/MUST ... — the keyword must appear in the body, not only in the heading]
 
-#### Scenario: [情境名稱]
-- **WHEN** [條件]
-- **THEN** [結果]
-- **AND** [附加結果]
+#### Scenario: [scenario name]
+- **WHEN** [condition]
+- **THEN** [outcome]
+- **AND** [additional outcome]
 
-<!-- 亦可使用 MODIFIED、REMOVED、RENAMED Requirements。
-MODIFIED 必須包含完整更新後的 requirement 區塊。
-REMOVED 必須包含 Reason 與 Migration；RENAMED 使用 FROM/TO 配對。 -->
+<!-- MODIFIED, REMOVED, and RENAMED Requirements may also be used.
+MODIFIED must contain the full updated requirement block.
+REMOVED must include Reason and Migration; RENAMED uses a FROM/TO pair. -->

package/schemas/sdd/templates/tasks.md

@@ -1,11 +1,11 @@
-# Tasks: [change 名稱]
+# Tasks: [change name]
 
-## 1. [切片名稱 — 一條垂直路徑]
-- [ ] 1.1 撰寫失敗測試: [對應的 Scenario 名稱]
-- [ ] 1.2 實作至測試通過
-- [ ] 1.3 對照 spec 驗證行為
+## 1. [slice name — one vertical path]
+- [ ] 1.1 Write a failing test: [corresponding Scenario name]
+- [ ] 1.2 Implement until the test passes
+- [ ] 1.3 Verify behavior against the spec
 
-## 2. [下一個切片]
-- [ ] 2.1 撰寫失敗測試
-- [ ] 2.2 實作至測試通過
-- [ ] 2.3 對照 spec 驗證行為
+## 2. [next slice]
+- [ ] 2.1 Write a failing test
+- [ ] 2.2 Implement until the test passes
+- [ ] 2.3 Verify behavior against the spec

package/schemas/sdd/templates/ticket.md

@@ -1,2 +1,2 @@
 ## Summary
-[一句話描述這個 change 要做什麼 — 詳細 why/what/capabilities/impact 見 proposal.md]
+[One sentence describing what this change does — detailed why/what/capabilities/impact live in proposal.md]