@seanmars/tospec 0.19.0-beta.7 → 0.19.0-beta.8

package/CHANGELOG.md

@@ -6,6 +6,84 @@
 
 tospec 是一套 spec-driven development CLI: 以 schema 定義文件結構與工作流程, 進度由檔案系統狀態推算, 開發方法則封裝於 Skill 之中, 使 AI 工具 (Claude Code / Codex) 得以循序完成需求釐清、規格撰寫、設計、任務拆解、實作到歸檔的完整流程.
 
+## [0.19.0-beta.8] - 2026-09-18
+
+**預發布版本**: 需以 `npm install @seanmars/tospec@beta` 明確指定才會安裝, `latest` 仍指向 0.18.0.
+
+本版本來自對一個全新空專案連續四輪的全指令面掃描, 共 61 項缺陷 (17 / 11 / 15 / 18). 第一、二、四輪的方法是逐一執行每個命令並比對輸出; 第三輪換了一種找法 — 不看輸出, 改看這個程式庫**自己已經寫下來的政策**, 然後問哪些呼叫端沒有遵守它, 於是該輪 15 項裡多數是本專案在某處明文陳述的規則, 除了一個地方之外到處都成立. 四輪的缺陷共用同一種形狀: 兩個本該一致的東西已經分岔, 而沒有任何一方會發現 — 同一個條件被三個兄弟命令各答一種、同一份資料在 human 模式看得到而 `--json` 沒有、一份模板承諾了沒有任何程式碼執行的行為、一個 artifact 的「必要」在 artifact graph、`validate` 與 `archive` 三處各自定義. 其中六項會遺失工作成果, 一項讓 dashboard 的同源寫入權暴露給 `tospec/` 底下的任意檔案. 第四輪另有三項是第三輪修正的部分回歸, 全部同一個成因: 放寬一個判斷條件之後沒有回頭問「現在還會 match 到什麼」 — 收緊會被既有測試擋下, 放寬只會讓新的輸入被接受, 而那些輸入照定義就沒有測試.
+
+### 新增
+
+- **`tospec init` / `update` / `rules` / `migrate` 支援 `--json`**: 這四個命令原本完全沒有機器可讀的輸出, 而它們正是 agent 在專案初始化與維護時會執行的那幾個. 一併把各命令的失敗 null-shape 集中到單一表格, 並將 `test/cli/json-failure.test.ts` 由逐命令案例改寫為表格驅動的全面掃描, 因此少了失敗 payload 的新命令現在預設就會讓測試失敗 — 原本沒有任何機制要求新命令必須具備失敗 payload, 漂移才是預設值.
+
+- **`status` / `instructions --json` 帶出 `changeMetadata` (goal, decisions)**: `.tospec.yaml` 的 `goal` 與 `decisions` 會被驗證、會被持久化, 卻不出現在 agent 唯一看得到的那兩個命令裡. 這直接抵銷了 `tospec-propose` skill「撰寫 proposal 時引用已連結的 ADR」這條指示 — agent 無從得知有哪些 ADR 被連結上. 兩個欄位現在隨 change 狀態一起交付.
+
+- **`tospec/decisions/index.md` 新增 status 欄**: 索引是人實際會打開的那份檔案, 而一則 `superseded` 的 ADR 在裡面讀起來與現行決策完全一樣, 必須逐一開啟決策檔才分得出來. 既有的 ledger 會在下一次寫入時就地升級, 狀態值從決策檔本身回填, 不需要遷移步驟.
+
+- **`instructions apply` 的 `missingContext` 與檔案推導的任務編號**: 前者為非阻斷式診斷, 回報 apply 階段缺少哪些輸入; 後者讓任務編號取自檔案內容而非呼叫端的計數.
+
+### 安全
+
+- **dashboard 的 `/api/render` 不再輸出未淨化的 HTML**: client 端以 `innerHTML` 指派回應內容, 而該路徑沒有 CSP, 因此 `tospec/` 底下任何檔案裡的一個 `<img onerror>` 都能在 dashboard 的 origin 內執行 — 也就落在守衛 `POST /api/task` 的那道 CSRF 邊界之內: 注入的 script 不是跨來源請求, 該防線所倚賴的 preflight 對它從不適用, 所以寫入權等同開放. 修正分三層: raw HTML 一律轉義而非採用允許清單 (spec 文件沒有使用 HTML 的理由, 而允許清單是一項持續的維護義務, 漏掉一個標籤就等於漏掉全部); URL scheme 改為解析而非樣式比對 (`java<tab>script:` 在瀏覽器裡會正規化, 在 regex 裡不會); 並讓每個回應都帶 `script-src 'self'`, 使前兩層萬一漏掉時仍有一道不依賴淨化正確性的防線. 決策記錄: `tospec/decisions/20260918_171106-dashboard-markdown-escapes-raw-html.md`.
+
+### 變更
+
+- **`tospec archive` 新增 artifact 完整性閘門 (breaking change)**: 一個只有 `specs/<cap>/spec.md` — 沒有 `proposal.md`、沒有 `design.md`、沒有 `tasks.md` — 的 change 可以通過 `validate --strict` 並乾淨歸檔. 三個元件各持有部分視野而沒有任何一方提出異議: artifact graph 知道 sdd schema 把這三份標為 `optional: false`, 而它只回報、不設閘; `validate` 檢查的是已存在檔案的內容, 一份從未被寫出的檔案沒有內容可以失敗, 所以驗證是空洞地通過; `archive` 的閘門看的是驗證結果、任務勾選與 sync report, 沒有一個會去問 graph. 而歸檔是不可逆點 — change 移入 `tospec/changes/archive/`, delta 併入 `tospec/specs/`, 這套工作流程存在的理由 (why 與 how) 就此從未被記錄. 現在 archive 透過 `status` 所用的同一組 `loadChangeContext` + `formatChangeStatus` 詢問 graph, 以 `archive_artifacts_incomplete` 設閘並在訊息中指名缺哪幾份. 閘門可被 `--yes` 覆寫, 與 `archive_tasks_incomplete` 一致: 缺少規劃文件是規劃義務而非正確性義務, 呼叫端可能有其理由, 要求的是這項省略被說出來而不是被假定. 改為硬性錯誤遭否決 — 從他處匯入的 change、中途才採用 schema 的 change, 其文件永遠不會存在, 而本輪發現的失效是沉默, 不是寬鬆. 決策記錄: `tospec/decisions/20260917_155623-archive-gates-on-artifact-completeness.md`.
+
+- **`status --json` 以 `optional` 取代部分情況下的 `skipped` (breaking change)**: 對 `skipped` 做特例處理的讀取端需要調整. 症狀是「schema 宣告為選用」與「這個 change 宣告不做」兩件事共用同一個狀態值, 而選用的 artifact 因此對 `nextSteps` 完全隱形, 永遠不會出現在任何一個下一步裡 — 一份選用但仍然值得寫的文件, 呼叫端不會被告知它存在. 兩者現在是相異的狀態. 決策記錄: `tospec/decisions/20260918_171157-optional-and-skipped-are-distinct-statuses.md`.
+
+- **ticket frontmatter 的 `type` 改說 change-type 詞彙, schema 另立 `schema:` 欄 (breaking change)**: ticket 寫 `type: <schema>`, 而同一個 change 的 `.tospec.yaml` 與 `list --json` 寫 `type: <changeType>` — 一個鍵、兩套詞彙, 分佈在同一個 change 的兩份檔案裡. 對 `issue` 而言兩個詞恰好相同所以完全不可見; dashboard 早已把這道分裂吸收成一條同時比對 `.badge-requirement, .badge-sdd` 的 CSS 規則, 也就是說症狀早就被觀察到, 只是被當成樣式問題處理掉了.
+
+- **`validate --strict` 的判準收緊到與 archive 一致 (breaking change)**: 原本綠燈的 change 可能開始被拒絕. 兩個成因分別修正 — (a) `findArchiveBlockers` 的預演早已算出正確答案, 卻歸檔在 `INFO` 而 `--strict` 只計警告, 於是 `validate --strict` 放行了 archive 即將拒絕的 change; 提升為 `WARNING` 而非 `ERROR`, 因為修改兄弟 change 尚未歸檔的 requirement 是受支援的情境, 用 ERROR 會擋掉它, 而 INFO 會讓歸檔前的閘門全盲. 決策記錄: `tospec/decisions/20260916_154000-archive-dry-run-findings-are-warnings.md`. (b) 見下方「`validate --strict` 對整份都是未填寫 template 的 change 回報 valid」.
+
+- **`tospec instructions` 交付 schema 宣告的驗收條件**: `schema.yaml` 宣告了 `requiredSections` 與 `minSectionLength`, `validate` 一直都在強制執行, 而 loader 讀進來之後把它們丟掉了 — human 模式印出固定的 `<!-- To be defined in schema validation rules -->`, `--json` 則整段省略. agent 要得知 sdd 的 `Why` 有 50 字元下限, 唯一的途徑是把寫好的 proposal 送出去被退回. 那個空白區塊是較糟的一半: 它主張「這份 artifact 沒有驗收條件」, 是比沉默更強也更錯的宣稱. 規則現在隨 `ArtifactInstructions.validation` 一起交付, 而 artifact 未宣告任何條件時整個區塊省略, 與 `<project_context>`、`<rules>`、`<unlocks>` 既有的行為一致. 決策記錄: `tospec/decisions/20260917_234821-instructions-carry-acceptance-criteria.md`.
+
+- **`archive --skip-specs` 由靜默丟棄改為具名警告**: 完全相同的情況經由 `skip_specs: true` 是一個硬性 ERROR, 經由 `--skip-specs` 旗標卻是無聲歸檔. 根因是兩者是不同種類的東西而外觀像同一個功能: `skip_specs` 是一項宣稱, validator 會去查核它; `--skip-specs` 是一道指令, 合併端直接照做. 旗標現在會指名它丟掉了哪些 capability. 維持為警告而非比照標記改為 ERROR: 旗標是使用者當下明確的指令, 把它變成錯誤等於讓這個旗標沒有用途. 決策記錄: `tospec/decisions/20260918_171157-skip-specs-flag-warns-rather-than-blocks.md`.
+
+- **`archive --json` 一律帶 `totals`, `migrate --json` 補上 human 模式的後續步驟**: 前者原本在沒有任何合併發生時整個省略該鍵, 讀取端因此要區分「沒有欄位」與「數值為零」兩種情況, 而它們的意思相同; 現在未合併時歸零輸出. 後者原本漏掉延後的 ticket stub 提示與「接著執行 `tospec init`」這一步, 兩者 human 模式都會印.
+
+### 修正
+
+- **空的 workflow profile 讓 `tospec update` 無法恢復**: 工具是否已安裝的判斷來自 `SKILL.md` 的檔案數量, 而 `removeUnselectedSkillDirs` 刪除的正是那些檔案 — 於是清空目錄的那一次執行, 同時銷毀了該工具曾被設定過的唯一證據, 下一次 `update` 回報「No configured tools found」, 只剩 `init` 一條路可回. 根因是 `configured` 同時在回答兩個問題; 現在它回答「這個工具有沒有 skill」供 init 選單使用, 另立的 `isToolInstalled` 回答「tospec 是否管理這個目錄」供 update / rules 使用, 判準是任何 profile 變更都不會移除的 workflow rule 文件. 以 `rules/tospec/` 目錄的存在為判準遭否決: 該目錄同時放著 legacy 的 init-only `decision.md`, 它的存在只證明 tospec 曾經碰過這個目錄一次, 不證明現在仍管理它. `update` 另在清空前提出警告, 指名該負責的 profile 與兩個可以反轉它的命令. 決策記錄: `tospec/decisions/20260916_152000-tool-install-marker-not-skill-count.md`.
+
+- **`rules/tospec/decision.md` 被手動編輯後在下一次 `tospec init` 靜默消失**: 同一個目錄底下的兩份產生檔案走在兩套不同的機制上. `single-source-of-truth.md` 經 `planWorkflowRules`: 出貨模板包在一個 sha256 標記裡, 任何寫入前先讀取, 位元組一旦不符即以衝突拒絕, 而拒絕訊息本身就說明 `--force` 不會繞過它. `decision.md` 則經 `writeToolRules`, 且只有 `init` 會呼叫: 沒有標記, 所以無從分辨產生檔案與手改檔案; 沒有計畫, 所以沒有任何東西會回報它; 寫入是無條件的. 編輯它會在下一次 `tospec init` 遺失 — 靜默、狀態碼 0、預設路徑、不需要 `--force`. 而 `tospec rules` — 這個命令的全部職責就是刷新 rule 檔案 — 從不碰它也不列出它, 所以這道漂移連經由設計用途的命令都修不回來. 原始碼在自己的檔頭註解裡點名了這件事 (「Legacy decision rules retain their init-only writer」) 卻沒有把它當成缺陷. 現在只有一套機制: `MANAGED_RULES` 列出每一份 rule 文件, `planWorkflowRules` 對全部進行規劃、雜湊標記、衝突檢查與回報. 讓 `init` 改成「不存在才寫」遭否決 — 它止住了資料遺失, 卻讓該檔案對 `rules` 仍然不可見, 一份已漂移的副本依舊沒有任何命令會說出來. `unmarkedLegacyBodies` 認得舊 writer 產出的確切文字, 因此既有專案靜默升級, 不會為一份沒人動過的檔案撞上衝突. 決策記錄: `tospec/decisions/20260917_234821-every-rule-document-is-managed-alike.md`.
+
+- **一個壞掉的 change 就讓 `tospec list` 整份消失**: 一個 `.tospec.yaml` 無法解析的 change 使 `list` 以狀態碼 1 結束、`changes: []`, 每一個健康的 change 都不見了, 而訊息指名了那個未知的 schema 卻從不指名是哪一個 change 宣告了它 — 修好它唯一需要的那項資訊, 正是被扣住的那一項. `status.ts` 以散文寫下了這條政策 (「One malformed change must not blank the sweep, so the entry carries the failure in place instead of aborting」), `validate --all` 也遵守它, `list` 是第三個批次命令, 也是唯一中止的那個. 現在逐一以自己的 try/catch 讀取, 攜帶指名該 change 的 `change_unreadable` 診斷, 並在完整信封仍然送達 stdout 的前提下以狀態碼 1 結束. 壞掉的 change 即使在 `--type` 過濾下也維持列出, 因為過濾讀的正是剛剛失敗的那份 metadata — 把它排除掉, 等於藏起使用者必須修好才能看到其餘內容的那一個. 決策記錄: `tospec/decisions/20260917_234821-batch-commands-degrade-per-item.md`.
+
+- **拼錯的 REMOVED 標頭以乾淨的成功歸檔**: `buildUpdatedSpec` 用 `!options.silent` 包住它的非致命警告, 而 archive 設定 `silent: json` — 這道守衛精準地壓制了沒有 console 可讀的那些呼叫端, 留下 `removed: 0`、狀態碼 0、空的 `status[]`, 而該 requirement 仍留在主 spec 裡. 警告現在以帶碼的 notice 回傳並導入 `status[]`; 由同一個 helper 同時負責記錄與列印, 使任何呼叫點都無法只做一半. 比照 MODIFIED / RENAMED 把懸空的 REMOVED 改為致命遭否決: 重新套用一個已經同步過的移除是 no-op, 而早期同步這個模式正倚賴它, 所以修法是讓它可見, 不是讓它失敗. 決策記錄: `tospec/decisions/20260916_153000-spec-merge-notices-are-returned.md`.
+
+- **同名的 scenario 讓 MODIFIED 的防漏檢查失效, 可以無聲刪掉一條 scenario**: 名稱是 `findMissingScenarios` 唯一的把手, 所以兩條共用同一個名稱的 scenario 對它而言可以互換 — 把其中一條重述兩次, 數量吻合, 另一條的內容則在歸檔時被刪除, 而全程驗證皆為綠燈. 重複名稱進入主 spec 的唯一途徑是從 delta 合併進來, 所以現在就在 delta 這一端拒絕它.
+
+- **`validate --strict` 對「整份都是未填寫 template」的 change 回報 valid**: 三份原封不動的 template 依其構造必然滿足區段規則, 而 `minSectionLength` 把 HTML 註解算進長度 — proposal template 裡那句 71 字元的 `Why` 提示, 滿足了它正在提示的那個 50 字元下限, 而一個真正寫出來的十字回答反而收到警告. 註解不再計入長度, 且 `validate` 改為回報 `status` 早已算出的 stub 狀態, 兩者共用同一個述詞而非各自判斷. 決策記錄: `tospec/decisions/20260918_171157-validate-reads-the-stub-status-status-already-computes.md`.
+
+- **`new change --schema <壞掉的 schema>` 成功, 產出永久不可用的 change**: `validateSchemaExists` 只檢查目錄存在, 從不載入檔案, 於是產出一個沒有 `type`、沒有 ticket、連自己的成功 payload 裡都沒有 `ticketPath` 的 change, 而沒有任何命令讀得了它. 更糟的是 `tospec schemas` 把壞掉的 schema 藏起來, `new change` 的錯誤訊息卻把它當成可用選項宣傳 — 兩個命令對同一份 schema 給出相反的答案. 現在在寫出任何東西之前先載入 schema, 壞掉的項目留在清單裡並攜帶其原因, 而每一份「Available schemas」清單都改由真正載入成功的那些組成.
+
+- **ticket 帳本產生重複與錯配, archive 搬走的是舊的那一張**: 放棄一個 change 會留下它的 ticket (`rm -rf` 是唯一的途徑), 用同一個名稱重建會再寫一張, 而 archive 取 readdir 順序 — 也就是最舊的那張 — 因此把這次的執行歸檔到那個被放棄的嘗試的 ticket 底下, 並讓真正的那張永遠留在原地. 決策記錄: `tospec/decisions/20260918_171157-one-active-ticket-per-change-name.md`.
+
+- **`show <issue-change>` 從不印出 `task.md`**: 主文件被寫死為 `proposal.md`, 而 issue schema 從不產生這份檔案, 於是 `show` 落到 ticket stub 並印出十一行 frontmatter, 取代了根因、修復計畫、測試計畫與任務清單. 主 artifact 現在從 schema 解析.
+
+- **artifact 為 `stub` 時形成死路**: 檔案存在但內容仍是 template 的狀態下, `buildNextSteps` 只比對 `ready` 與全部完成, 所以這是唯一一個回報 `isComplete: false` 卻同時給出空 `nextSteps` 的狀態 — 沒有指示也沒有理由, 而這恰好是呼叫端無法自行推斷的情況, 因為目錄列表看起來是完整的. archive 接著把那些檔案稱為「missing required artifact(s)」, 把讀者送去磁碟上找檔案, 而它的 `fix` 指向的正是那個無話可說的 `status`. human 模式一直都指名了它 (`[!] design (stub: ...)`), 所以這單純是機器契約的缺口.
+
+- **扁平 `--json` 失敗信封沒有任何 data key**: `status --change` 是第三個扁平 payload, 卻什麼都沒有 null 掉, 理由正是一輪之前的 ADR 已經否決過的那一個. 更關鍵的是該 ADR 所規定的兩項測試在空鍵集上都是空洞地通過 — 「失敗信封攜帶的每一個鍵在成功時都存在」對於零個鍵恆為真 — 所以規則現在改為直接斷言, 而 payload 會 null 掉 `changeName`. 決策記錄: `tospec/decisions/20260917_155623-flat-json-payloads-null-a-real-success-key.md`.
+
+- **`decision` 指令線缺 root 紀律**: `decision new` 只建立 `tospec/decisions/`, 留下一個半成品 root, 而其他每個命令接著都把它解析為一個專案, 於是 `validate --all` 與 `status --all` 開始對一個從來不是專案的目錄回報乾淨的全面通過 — 這正是那兩個命令拒絕隱含 root 所要避免的空洞通過, 從側門重新進來了一次. `createChange` 一直都會補完 root 並附有說明理由的註解, 兩者現在共用 `completeRootStructure`. `decision list` 同樣會在任何地方都以狀態碼 0 回答「這裡沒有決策」, 現在比照其他批次命令拒絕隱含 root.
+  - **`decision new --force` 改寫檔案卻不更新 `index.md`**: 不追加第二列是對的, 什麼都不做則不是 — index.md 於是繼續宣傳前一份的標題與摘要, 而 `decision list` 從磁碟讀到的是新的. 現在以檔名比對就地改寫該列; 標題正是一次改寫最可能變動的東西.
+  - **`--date` 接受 `20261345_996199`**: 檢查只看形狀, 而這是唯一一個不由 `formatTimestamp` 產生的時間戳; 該錯誤值會成為檔名、帳本裡的人類可讀日期, 以及一個排序上壓過每一筆真實紀錄的鍵. 改以 `Date` 來回轉換而非逐欄位範圍檢查, 使月份長度與閏日都取自行事曆.
+
+- **巢狀子命令的 `--help` 提示指向不存在或不相干的命令**: 提示用的是 `command.name()` — 葉節點的名稱. 對每一個 top-level 命令都正確, 因為兩者恰好重合; 對兩個巢狀命令則都錯: `new change` 指名了一個根本不是命令的字串, commander 因此印出 top-level help 並以狀態碼 0 結束, 於是這則建議看起來像是被回答了; 而 `decision new` 指名了建立 change 的那一組 — 一個真實存在、但回答另一個問題的命令. 現在由完整路徑組出.
+
+- **一批對同一份資料給出兩個答案的較小修正**: `config set workflows` 在非 custom profile 下被接受、逐 id 驗證、儲存並由 `config list` 顯示, 然後被丟棄, 因為只有 `custom` 會去查詢它 — 在 `update` 之前沒有任何東西否定「它有生效」這個信念; 兩端現在都會警告, 而 `config list` 顯示時一併重述該但書. `config set --allow-unknown` 寫得進去的鍵, `config get` 讀不出來 — `list` 看得到、`unset` 移除得掉, 唯獨這個旗標存在的目的所服務的可腳本化讀取端說它無效; `get` 現在也接受該旗標, 只放寬已知鍵檢查, 絕不放寬原型安全檢查, 與 `set` 的切分方式相同. `POST /api/task` 會勾選 change 目錄下任何 `.md` 的 checkbox — 這不是路徑穿越 (root 限制成立), 但 `proposal.md` 與 `design.md` 正是這套工作流程存在所要保存的紀錄, 而該寫入在 UI 裡不留任何痕跡, 因為讀取端只回報 schema 追蹤的那份檔案; 兩端現在共用 `resolveTaskFiles`. 執行期失敗從 null-shape 回報 `root: null`, 即使解析其實已經成功 — `status --change nope` 會一邊列出該 root 底下可用的 change 一邊宣稱自己沒有 root, 呼叫端因此分不出「不是專案」與「專案沒問題, 只是 change 不存在」; 解析出的 root 現在記錄於 `resolveRootForCommand` 並僅由 `emitFailure` 填入, commander 層與 root 解析本身的失敗維持 `null`, 那對它們而言是準確的. `status --schema decision` 會規劃一個位於 `tospec/changes/<change>/decision.md` 的 artifact — `new change` 與 `instructions` 早已拒絕的孤兒 — 且其 `nextSteps` 要呼叫端去執行那個保證會拒絕的 `instructions`; 發出指示的那個命令, 正是沒有守衛的那一個. 另外四項是第三輪修正沒有觸及到的同類呼叫端: `list --type` 在解析 root 之前先驗證自己的參數, `init` / `update` / `rules` 在規則衝突時寫死 `root: null`, `instructions` 的「Valid artifacts」清單漏了 `apply`, 以及 `--schema decision` 的守衛坐在 change 解析之後因而在空專案裡從不觸發.
+
+- **第一輪的其餘修正**: 未放置於既有 capability 的新能力缺少 `## Purpose` 時, 會以字面上的 TBD 靜默進入合併後的 spec (模板補上該區段, archive 回報該次替換); `new change --schema decision` 建立出沒有命令能抵達的 change, `--decisions` 接受對應不到任何 ADR 的檔名 (兩者改為預先拒絕, ADR 模板不再宣稱一個沒有東西會寫入的反向連結); `show --json` 扣住 requirement 與 scenario 名稱 — 正是 MODIFIED / REMOVED / RENAMED delta 必須逐字重現、而 archive 會為此硬性失敗的那些字串; `--yes` 不再把「rerun with --yes」當成修法回聲給使用者; 兩個 SCREAMING_SNAKE 狀態碼改為 lower_snake; 非專案目錄在 list / status / archive / validate 四處統一回報單一的 `no_tospec_root`; dashboard 的已歸檔計數不再把 change 與其 ticket 重複計入; `dashboard -d` 不再重複 `Error:` 前綴; 無 delta 時的訊息改以 `skip_specs` 為誠實的替代方案, 而非暗示去發明一條 requirement; workflow rule 檔名去掉 `sourc` 這個錯字, 遷移邏輯讀舊 slug、先寫再刪, 且遇到已編輯的副本時拒絕而非移除.
+
+### 其他
+
+- **四輪掃描的方法與結果**: 測試由 83 檔 / 1112 passed 成長至 88 檔 / 1279 passed (1 skipped 為既有的 `it.runIf(platform !== 'win32')`, 與本版改動無關). 新增的測試大多正是它們的缺席才讓這些缺陷通過的那些斷言 — 扁平失敗信封至少攜帶一個 data key、`--help` 提示指名一個真實存在的命令、被編輯過的 rule 文件能存活過每一個會寫入規則的命令、遷移結果通過 `tospec validate --all`. 第二輪與第三輪的修正合併於同一個 commit: 第二輪的 11 項修復當時尚未提交, 而第三輪的 15 項觸及其中 13 個相同檔案, 拆開會需要 hunk 層級的手術, 並產生一個連自己的測試都跑不過的中間 commit.
+
+- **`src/core/markdown-render.ts` 的兩個裸 NUL 位元組改寫為 `\x00` 逸出序列**: URL 淨化用的字元類別 `[\x00- ]` 把 NUL 直接寫成裸的控制字元. 執行結果完全正確, 但 git 的二進位偵測因此把整個檔案判為 binary, 於是它的提交對這個檔案印出 `Bin 0 -> 4490 bytes` 而不是逐行 diff — 本版唯一一項安全性修正所在的檔案, 就這樣在沒有任何可讀 diff 的情況下通過了審查. 逸出序列在 regex 字元類別裡與裸位元組完全等價, 所以這是純粹的來源表述修正, 行為與測試數皆不變.
+
+- 上游 OpenSpec 參考點仍停在 `e062b95` (1.12.0), 本版與上游比對無關.
+
 ## [0.19.0-beta.7] - 2026-09-16
 
 **預發布版本**: 需以 `npm install @seanmars/tospec@beta` 明確指定才會安裝, `latest` 仍指向 0.18.0.
@@ -38,7 +116,7 @@ tospec 是一套 spec-driven development CLI: 以 schema 定義文件結構與
 
 - **`tospec dashboard --port` 完全沒有驗證**: `Number(options?.port ?? 5620)` 沒有 `Number.isInteger` 或範圍檢查, 所以 `notanumber` 變成 `NaN` 一路抵達 URL 字串; 連埠號遞增迴圈也擋不住, 因為 `used.has(NaN)` 恆為 false, 該值原封不動通過. 現以明確的整數與 `0..65535` 範圍檢查走標準錯誤路徑, `-p 0` 維持可用 — 它是把埠號選擇交給作業系統, `--list` 本來就正確回報實際埠號.
 
-- **`tospec decision new --force` 覆寫檔案卻仍追加一列索引**: `appendIndexRow` 是無條件的, 當 `--force` 取代既有檔案時該檔的列已經存在, 於是索引多出一列重複. 既有的 `ponytail` 註解記錄了「append-only、不去重」這個決定, 但它設想的是「對同一個 topic 重跑 `new` 會多一列」, 沒有涵蓋 `--force` — 那裡的檔案並不是第二筆紀錄. 修正讓索引列以「這次寫入是新檔」為條件, 符合索引本身的語意: 一筆決策一列, 而不是一次呼叫一列.
+- **`tospec decision new --force` 覆寫檔案卻仍追加一列索引**: `appendIndexRow` 是無條件的, 當 `--force` 取代既有檔案時該檔的列已經存在, 於是索引多出一列重複. 既有的限制註解記錄了「append-only、不去重」這個決定, 但它設想的是「對同一個 topic 重跑 `new` 會多一列」, 沒有涵蓋 `--force` — 那裡的檔案並不是第二筆紀錄. 修正讓索引列以「這次寫入是新檔」為條件, 符合索引本身的語意: 一筆決策一列, 而不是一次呼叫一列.
   - **存在性檢查不是原子的**: 檢查與寫入之間隔著 `loadTemplate` 與 `renderDecision`, 那是貨真價實的 I/O 寬度; 兩個 process 可以同時通過檢查、同時寫入, 而 `fs.writeFileSync` 預設的 `'w'` 旗標無條件截斷, 後者靜默覆蓋前者. 現改用 `{ flag: 'wx' }` 讓檔案系統來執行這道守衛, `EEXIST` 翻譯回既有的訊息, 使用者可見的行為不變; `--force` 維持 `'w'`. 任何 check-then-write 的方案都留有一個窗口, 無論把它縮到多小, 而檔案系統早就提供了這個原語.
 
 - **capability 資料夾內檔名寫錯的 delta 驗證全綠卻被靜默丟棄**: `findSpecFiles` 只收集 basename 恰為 `spec.md` 的檔案, 而 validator 早已備有一整組針對「永遠不會被合併的 delta 檔」的守衛 (specs 根目錄的 `spec.md`、深度超過一層的路徑、點開頭的資料夾), 每一條都以同一句理由成立. 第四種失敗模式完全相同的情況 — 對的資料夾、錯的檔名 — 沒有守衛, 根因是**它在守衛迴圈看到之前就被 walker 過濾掉了**: 守衛只能裁決 walker 交給它的檔案. 合併端讀的同樣是寫死的 `spec.md`, 兩邊一致, 所以沒有任何地方回報衝突. 修正是新增一個回傳 `specs/` 下所有 `*.md` 的走訪器並在同一個迴圈裡以 ERROR 指名該檔, 而不是放寬合併路徑 — 合併只讀 `spec.md` 是版面配置的契約, 改動它會讓同一資料夾內的兩個檔案變得語意不明.
@@ -577,6 +655,7 @@ Dashboard 進化為可背景常駐、多專案並存的服務, 並補上 TDD 導
 
 - 新增 `prepack` script 與 npm publish 的準備設定, 完備套件發行流程.
 
+[0.19.0-beta.8]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.7...v0.19.0-beta.8
 [0.19.0-beta.7]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.6...v0.19.0-beta.7
 [0.19.0-beta.6]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.5...v0.19.0-beta.6
 [0.19.0-beta.5]: https://github.com/seanmars/tospec/compare/v0.19.0-beta.4...v0.19.0-beta.5

package/assets/dashboard/app.js

@@ -840,7 +840,7 @@ function fileAccordion(file) {
     body.textContent = 'Loading...';
     try {
       const data = await api('/api/render?file=' + encodeURIComponent(file.path));
-      body.innerHTML = data.html; // controlled container; server-rendered markdown
+      body.innerHTML = data.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
     } catch (e) {
       loaded = false;
       body.textContent = 'Failed to render (' + (e.status || 'error') + ').';
@@ -1008,7 +1008,7 @@ async function renderSpecDetail(id) {
 
   try {
     const data = await api('/api/render?file=' + encodeURIComponent(`tospec/specs/${id}/spec.md`));
-    body.innerHTML = data.html; // controlled container; server-rendered markdown
+    body.innerHTML = data.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
   } catch {
     body.textContent = 'Failed to render spec.';
   }
@@ -1063,7 +1063,7 @@ async function renderDecisionContent(pane, file) {
   );
   try {
     const data = await api('/api/render?file=' + encodeURIComponent(d.path));
-    body.innerHTML = data.html; // controlled container; server-rendered markdown
+    body.innerHTML = data.html; // sanitized by core/markdown-render.ts - raw HTML is escaped there, not here
     enhanceDecisionQA(body, d.content); // 決策過程 → Q/A cards (client-side, graceful fallback)
   } catch {
     body.textContent = 'Failed to render decision.';

package/assets/rules/tospec/decision.md

@@ -0,0 +1,3 @@
+# Decision
+
+Any material decision reached during discussion must be recorded with /tospec-decision, which creates a decision file and captures the relevant decision details.

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAgC,MAAM,WAAW,CAAC;AAwElE,QAAA,MAAM,OAAO,SAAgB,CAAC;AAgb9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,wBAAgB,MAAM,CAAC,IAAI,WAAe,GAAG,IAAI,CAchD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAgD,MAAM,WAAW,CAAC;AAoIlF,QAAA,MAAM,OAAO,SAAgB,CAAC;AAygB9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAsBnB,wBAAgB,MAAM,CAAC,IAAI,WAAe,GAAG,IAAI,CAkChD"}

package/dist/cli/index.js

@@ -1,22 +1,24 @@
-import { emitFailure, isCliAbort } from '../commands/shared-output.js';
-import { Command, Option, InvalidArgumentError } from 'commander';
+import { emitFailure, isCliAbort, emitFailureStatus, normalizeCommanderCode, } from '../commands/shared-output.js';
+import { Command, CommanderError, Option, InvalidArgumentError } from 'commander';
 import { createRequire } from 'module';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { promises as fs } from 'fs';
 import { AI_TOOLS } from '../core/config.js';
-import { UpdateCommand } from '../core/update.js';
+import { UpdateCommand, UPDATE_FAILURE_PAYLOAD } from '../core/update.js';
 import { ListCommand } from '../core/list.js';
 import { ArchiveCommand } from '../core/archive.js';
-import { MigrateCommand } from '../core/migrate.js';
+import { INIT_FAILURE_PAYLOAD } from '../core/init.js';
+import { RULES_FAILURE_PAYLOAD } from '../core/rules.js';
+import { MigrateCommand, MIGRATE_FAILURE_PAYLOAD } from '../core/migrate.js';
 import { resolveRootForCommand, resolveTospecRoot, isRootSelectionError, toRootOutput, } from '../core/root-selection.js';
-import { ValidateCommand } from '../commands/validate.js';
-import { ShowCommand } from '../commands/show.js';
+import { ValidateCommand, VALIDATE_FAILURE_PAYLOAD } from '../commands/validate.js';
+import { ShowCommand, SHOW_FAILURE_PAYLOAD } from '../commands/show.js';
 import { isInteractive } from '../utils/interactive.js';
 import { registerConfigCommand } from '../commands/config.js';
-import { registerDecisionCommand } from '../commands/decision.js';
+import { registerDecisionCommand, DECISION_NEW_FAILURE_PAYLOAD, DECISION_LIST_FAILURE_PAYLOAD, } from '../commands/decision.js';
 import { registerMetricsCommand } from '../commands/metrics.js';
-import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { statusCommand, BATCH_STATUS_FAILURE_PAYLOAD, STATUS_FAILURE_PAYLOAD, instructionsCommand, applyInstructionsCommand, INSTRUCTIONS_FAILURE_PAYLOAD, APPLY_ARGUMENT, templatesCommand, TEMPLATES_FAILURE_PAYLOAD, schemasCommand, SCHEMAS_FAILURE_PAYLOAD, newChangeCommand, NEW_CHANGE_FAILURE_PAYLOAD, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 /**
  * The options the user actually typed.
  *
@@ -36,6 +38,38 @@ function userSuppliedOptions(options, command) {
         return {};
     return Object.fromEntries(Object.entries(options).filter(([key]) => command.getOptionValueSource(key) !== 'default'));
 }
+const jsonFailureShapes = new WeakMap();
+function withJsonFailureShape(command, shape) {
+    jsonFailureShapes.set(command, shape);
+    return command;
+}
+/**
+ * Makes commander throw instead of exiting, for the whole command tree.
+ *
+ * Applied after every subcommand is registered rather than at construction:
+ * commander only copies `_exitCallback` into a subcommand at `.command()` time,
+ * so setting it on the root alone would leave every subcommand still calling
+ * `process.exit` — which is where these failures actually happen.
+ */
+function throwOnCommanderExit(command) {
+    command.exitOverride((error) => {
+        // Attach the command so runCli can recover its null-shape; commander's
+        // error carries only a code and a message.
+        error.tospecCommand = command;
+        throw error;
+    });
+    for (const child of command.commands)
+        throwOnCommanderExit(child);
+}
+/**
+ * The root output for a command whose root came from its path argument rather
+ * than from a search: `init`, `update` and `rules`. Their success payloads all
+ * report `source: 'explicit'`, so their failures say the same thing about the
+ * same directory instead of `null` (round 4 report 10).
+ */
+function explicitRootOutput(targetPath) {
+    return { path: path.resolve(targetPath), source: 'explicit' };
+}
 function failWithError(error, json) {
     // The agent contract: every --json failure leaves exactly one JSON
     // document on stdout (the command's null-shape plus a status array).
@@ -70,6 +104,7 @@ program
     .option('--tools <tools>', toolsOptionDescription)
     .option('--force', 'Refresh existing generated files without prompting; does not bypass rule conflicts')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
+    .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (targetPath = '.', options) => {
     try {
         const resolvedPath = path.resolve(targetPath);
@@ -95,49 +130,73 @@ program
             tools: options?.tools,
             force: options?.force,
             profile: options?.profile,
+            json: options?.json,
         });
         await initCommand.execute(targetPath);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            // Round 4 report 10. These three take their root as an argument rather
+            // than searching for it, so it is known even when the run fails — a
+            // rule conflict reports absolute paths *under* this root while the
+            // envelope claimed `root: null`. Same `source` the success payload uses.
+            payload: { ...INIT_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'init_error',
+        });
     }
 });
 program
     .command('update [path]')
     .description('Update tospec instruction files')
     .option('--force', 'Force update even when tools are up to date; does not bypass rule conflicts')
+    .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (targetPath = '.', options) => {
     try {
-        const updateCommand = new UpdateCommand({ force: options?.force });
+        const updateCommand = new UpdateCommand({ force: options?.force, json: options?.json });
         await updateCommand.execute(targetPath);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...UPDATE_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'update_error',
+        });
     }
 });
 program
     .command('rules [path]')
     .description('Refresh workflow rules for tools with installed tospec skills')
-    .action(async (targetPath = '.') => {
+    .option('--json', 'Output as JSON (for programmatic use)')
+    .action(async (targetPath = '.', options) => {
     try {
         const { RulesCommand } = await import('../core/rules.js');
-        await new RulesCommand().execute(targetPath);
+        await new RulesCommand().execute(targetPath, { json: options?.json });
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...RULES_FAILURE_PAYLOAD, root: explicitRootOutput(targetPath) },
+            fallbackCode: 'rules_error',
+        });
     }
 });
 program
     .command('migrate [openspec-dir]')
     .description('Migrate an OpenSpec project into tospec format (default source: ./openspec)')
     .option('-f, --force', 'Skip confirmation prompt')
+    .option('--json', 'Output as JSON (non-interactive; requires --force)')
     .action(async (openspecDir, options) => {
     try {
         const migrateCommand = new MigrateCommand();
         await migrateCommand.execute(openspecDir, options);
     }
     catch (error) {
-        failWithError(error);
+        failWithError(error, {
+            enabled: options?.json,
+            payload: MIGRATE_FAILURE_PAYLOAD,
+            fallbackCode: 'migrate_error',
+        });
     }
 });
 program
@@ -149,31 +208,45 @@ program
     .option('--type <type>', 'Filter changes by type: "requirement" or "issue"')
     .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (options) => {
+    // Round 4 report 10. Both the argument check below and the catch block used
+    // to hardcode `root: null`, so `list --type bogus` was the one runtime
+    // failure in the CLI that denied knowing where it had been pointed —
+    // every other command reports the resolved root on failure. Resolution
+    // first, and the payload built from what it found.
+    let resolvedRoot = null;
+    const failurePayload = () => ({
+        ...(options?.specs ? { specs: [] } : { changes: [] }),
+        root: resolvedRoot ? toRootOutput(resolvedRoot) : null,
+    });
     try {
-        if (options?.type && options.type !== 'requirement' && options.type !== 'issue') {
-            throw new Error(`Invalid --type '${options.type}'. Expected "requirement" or "issue".`);
-        }
-        const root = await resolveRootForCommand({}, {
+        resolvedRoot = await resolveRootForCommand({}, {
             json: options?.json,
-            failurePayload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            // See the note in workflow/status.ts: an implicit root means no ancestor
+            // is a tospec project, and listing "no changes" there is an answer about
+            // a place that was never checked.
+            allowImplicitRoot: false,
+            failurePayload: failurePayload(),
         });
-        if (!root) {
+        if (!resolvedRoot) {
             return;
         }
+        if (options?.type && options.type !== 'requirement' && options.type !== 'issue') {
+            throw new Error(`Invalid --type '${options.type}'. Expected "requirement" or "issue".`);
+        }
         const listCommand = new ListCommand();
         const mode = options?.specs ? 'specs' : 'changes';
         const sort = options?.sort === 'name' ? 'name' : 'recent';
-        await listCommand.execute(root.path, mode, {
+        await listCommand.execute(resolvedRoot.path, mode, {
             sort,
             json: options?.json,
             type: options?.type,
-            ...(options?.json ? { root: toRootOutput(root) } : {}),
+            ...(options?.json ? { root: toRootOutput(resolvedRoot) } : {}),
         });
     }
     catch (error) {
         failWithError(error, {
             enabled: options?.json,
-            payload: options?.specs ? { specs: [], root: null } : { changes: [], root: null },
+            payload: failurePayload(),
             fallbackCode: 'list_error',
         });
     }
@@ -219,7 +292,11 @@ program
         await validateCommand.execute(itemName, options);
     }
     catch (error) {
-        failWithError(error, { enabled: options?.json, fallbackCode: 'validate_error' });
+        failWithError(error, {
+            enabled: options?.json,
+            payload: { ...VALIDATE_FAILURE_PAYLOAD, root: null },
+            fallbackCode: 'validate_error',
+        });
     }
 });
 program
@@ -245,7 +322,11 @@ program
         await showCommand.execute(itemName, userSuppliedOptions(options, command));
     }
     catch (error) {
-        failWithError(error, { enabled: options?.json, fallbackCode: 'show_error' });
+        failWithError(error, {
+            enabled: options?.json,
+            payload: SHOW_FAILURE_PAYLOAD,
+            fallbackCode: 'show_error',
+        });
     }
 });
 // ═══════════════════════════════════════════════════════════
@@ -265,9 +346,7 @@ program
     catch (error) {
         failWithError(error, {
             enabled: options.json,
-            // The batch null-shape; the single-change failure shape is
-            // pre-existing contract and stays payload-free.
-            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : undefined,
+            payload: options.all ? BATCH_STATUS_FAILURE_PAYLOAD : STATUS_FAILURE_PAYLOAD,
             fallbackCode: 'change_error',
         });
     }
@@ -280,7 +359,7 @@ program
     .option('--json', 'Output as JSON')
     .action(async (artifactId, options) => {
     try {
-        if (artifactId === 'apply') {
+        if (artifactId === APPLY_ARGUMENT) {
             await applyInstructionsCommand(options);
         }
         else {
@@ -290,7 +369,7 @@ program
     catch (error) {
         failWithError(error, {
             enabled: options.json,
-            payload: { instructions: null },
+            payload: INSTRUCTIONS_FAILURE_PAYLOAD,
             fallbackCode: 'change_error',
         });
     }
@@ -305,7 +384,7 @@ program
         await templatesCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, payload: { templates: null }, fallbackCode: 'templates_error' });
+        failWithError(error, { enabled: options.json, payload: TEMPLATES_FAILURE_PAYLOAD, fallbackCode: 'templates_error' });
     }
 });
 program
@@ -317,7 +396,7 @@ program
         await schemasCommand(options);
     }
     catch (error) {
-        failWithError(error, { enabled: options.json, payload: { schemas: null }, fallbackCode: 'schemas_error' });
+        failWithError(error, { enabled: options.json, payload: SCHEMAS_FAILURE_PAYLOAD, fallbackCode: 'schemas_error' });
     }
 });
 const newCmd = program.command('new').description('Create new items');
@@ -443,12 +522,91 @@ program
 registerConfigCommand(program);
 registerDecisionCommand(program);
 registerMetricsCommand(program);
+/**
+ * The `--json` null-shapes, in one table.
+ *
+ * Kept together rather than beside each command so the contract rule — a
+ * failure payload mirrors its success payload, with the data keys nulled — can
+ * be read and checked in one place.
+ *
+ * Every entry is the same object the command's own catch block passes to
+ * `failWithError`, never a literal repeated here. Commander can reject a run
+ * before the action body exists to catch it, so each command has two failure
+ * layers; when this table held its own copies they drifted, and `instructions`,
+ * `templates`, `new change` and `decision new` ended up emitting an envelope
+ * with `root` from one layer and without it from the other.
+ */
+function commandAt(...names) {
+    let current = program;
+    for (const name of names) {
+        const next = current.commands.find((c) => c.name() === name);
+        if (!next)
+            throw new Error(`No such command to register a JSON failure shape for: ${names.join(' ')}`);
+        current = next;
+    }
+    return current;
+}
+withJsonFailureShape(commandAt('init'), () => INIT_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('update'), () => UPDATE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('rules'), () => RULES_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('migrate'), () => MIGRATE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('list'), (argv) => argv.includes('--specs') ? { specs: [], root: null } : { changes: [], root: null });
+withJsonFailureShape(commandAt('archive'), () => ({ archive: null, root: null }));
+withJsonFailureShape(commandAt('validate'), () => ({ ...VALIDATE_FAILURE_PAYLOAD, root: null }));
+withJsonFailureShape(commandAt('show'), () => SHOW_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('status'), (argv) => argv.includes('--all') ? BATCH_STATUS_FAILURE_PAYLOAD : STATUS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('instructions'), () => INSTRUCTIONS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('templates'), () => TEMPLATES_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('schemas'), () => SCHEMAS_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('new', 'change'), () => NEW_CHANGE_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('decision', 'new'), () => DECISION_NEW_FAILURE_PAYLOAD);
+withJsonFailureShape(commandAt('decision', 'list'), () => DECISION_LIST_FAILURE_PAYLOAD);
 export { program };
+/**
+ * The command's full invocation path, not just its leaf name.
+ *
+ * `command.name()` is the leaf, which is correct for every top-level command
+ * because the two coincide — and wrong for the nested ones. `new change` used to
+ * name its parent's leaf alone, which is not a command at all: commander printed
+ * the top-level help and exited 0, so the advice looked answered. `decision new`
+ * named the change-creation group instead, which is a real command and answers a
+ * different question. Both sent the reader somewhere wrong without saying so.
+ */
+function commandPath(command) {
+    const names = [];
+    // Stops at the program itself, whose name is the binary and is already in the
+    // template literal around this call.
+    for (let node = command; node?.parent; node = node.parent) {
+        names.unshift(node.name());
+    }
+    return names.join(' ');
+}
 export function runCli(argv = process.argv) {
+    throwOnCommanderExit(program);
     try {
         program.parse(argv);
     }
     catch (error) {
+        if (error instanceof CommanderError) {
+            // `--help` and `--version` come through here too, having already printed
+            // what they were asked for. Only a non-zero exit is a failure.
+            if (error.exitCode === 0)
+                return;
+            const wantsJson = argv.includes('--json');
+            if (wantsJson) {
+                const command = error.tospecCommand;
+                const shape = command ? jsonFailureShapes.get(command) : undefined;
+                emitFailureStatus(shape ? shape(argv) : {}, {
+                    severity: 'error',
+                    code: normalizeCommanderCode(error.code),
+                    message: error.message,
+                    fix: `See tospec ${commandPath(command)} --help`.replace(/\s+/g, ' ').trim(),
+                });
+                return;
+            }
+            process.exitCode = error.exitCode || 1;
+            return;
+        }
         // The one abort mechanism for places that cannot stop the run by returning
         // (commander's preAction hooks). Setting the exit code and returning lets
         // stdout/stderr flush normally, which `process.exit` does not guarantee —