Theme / v1.14.0

OpenSpec

規格驅動開發

基礎觀念

v1.13.x:供應鏈安全與可靠的 Archive

理解 v1.13.0 與 v1.13.1 的重點:在未審查的 repo 中安全執行、status 的 Next 提示、apply 對無 delta specs 的警告,以及 archive 對 bullet markers 與重複 section 的正確性修正。

概述

OpenSpec v1.13.0(2026-09-09)與 v1.13.1(2026-09-17,“Hardened CLI, safer archives”)把主軸放在兩件事:讓 OpenSpec 可以放心用在剛 clone 下來的第三方 repo(供應鏈安全),以及讓 archive / validation 的行為與你寫的內容一致(正確性)。

供應鏈安全:clone 別人的 repo 等於執行別人的設定

v1.13.1 修掉了三個攻擊面,全部都源自同一個前提:一個 OpenSpec 專案的設定檔也是程式碼的一部分。

三個修復的攻擊面

攻擊面 修復
config.yaml 注入 設定值不能再把 directive(指令)注入 agent instructions——惡意 repo 不能借 OpenSpec 的設定檔對你的 AI agent 下指令
精心構造的檔案掛起 openspec update 與 openspec archive 不再能被惡意構造的檔案 hang 住(阻斷服務)
.npmrc 重導更新檢查 repo 內的 .npmrc 不能再把 update check 導向攻擊者控制的伺服器

這是 spec 工具特有的風險:OpenSpec 產出的 instructions 會直接進入 agent 的 context,等於 repo 作者有了一個「對你的 agent 說話」的通道。v1.13.1 把這個通道關起來了。

v1.13.0:Apply 警告無 delta specs 的 change

openspec instructions apply 過去只要 tasks 存在就報告 ready——即使這個 change 完全沒有 spec deltas,而這正是 openspec validate 會拒絕的狀態。

現在它會在 text 與 --json 兩種輸出中警告,並指出兩條出路:

  1. 補寫 specs(正常路徑)
  2. 在 config 宣告 skip_specs: true(明確選擇不要 specs)

Archive 正確性(v1.13.0)

這部分是 v1.13.0 最重要的修正,因為它們是靜默失敗:看起來成功,實際上什麼都沒發生。

* 與 + 寫的 removal / rename 過去從未生效

CommonMark 允許 -、*、+ 三種 bullet marker,但舊版的 delta parser 只讀 -。

後果:用 * 或 + 寫的 ## REMOVED Requirements 或 RENAMED 區塊匹配不到任何東西——validate 通過、archive exit 0 回報成功,而 requirement 原封不動留在主 spec 裡。

重複的 ## ADDED Requirements section 過去只套用一份

一個檔案裡有兩個 ## ADDED Requirements section 時,舊版靜默保留其中一份,另一份的內容就此消失——而且 change 照樣被搬進 archive。

這不是刻意觸發才會遇到的邊角:在 delta 裡用 fenced code 範例記錄 OpenSpec 自己的語法,就會自然產生重複 header。

其他 archive 修正

  • fenced code 不再被改寫:requirement 裡記錄的範例(兩個以上連續空行)過去每次 archive 都被 blank-line tidying 重寫;現在 tidying 是 fence-aware 的。YAML、Python 與預期輸出 fixture 特別受惠。
  • 換行的 scenario bullets 可以 retire:retire_capabilities 過去拒絕任何 scenario bullet 換到第二行的 spec——在欄寬限制的 repo 裡幾乎是全部。

v1.13.1:status 的 Next 提示

openspec status 結尾現在會輸出一個 Next: 行,指出推進這個 change 的下一條確切指令。

恢復一個做到一半的 change,不再需要把整個工作流背起來。這是「工具主動告訴你下一步」的典型 UX 改進——脈絡在工作流裡,不在你的腦裡。

其他值得注意的改進(v1.13.1)

  • Profile-aware skills:產生的 skills 與 commands 只命名你 profile 有安裝的 workflow,並支援 “openspec propose” 這類自然語句匹配。
  • 專案檢查:工作流確認專案跑過 openspec init 才寫入,且不再以副作用建立 openspec/ 資料夾。
  • Artifact templates:產出的 proposal / spec / design / tasks 開頭加上頂層標題,markdownlint 不再每個檔案都報。
  • npm 安裝:套件不再宣告 install scripts,npm install -g @fission-ai/openspec 不再出現看起來像打包錯誤的 allow-scripts 警告。
  • Nix:flake 附 bash / zsh / fish completions。
  • openspec feedback:不再把整份報告塞進 issue 標題。

對既有使用者的影響

  • 用 * / + 寫 removal / rename 的 delta:過去實際上從未生效。升級後重新 archive 才會真正套用——記得檢查主 spec 是否還留著以為已移除的 requirements。
  • 自訂 profile:archive-without-sync 的組合會被拒絕,profile 定義需要兩者兼具。
  • CI 使用者:validation 更嚴格(無 body 的 scenario、delta section 外的 requirement、apply.requires 與 artifacts 的核對),預期可能多出一些新的錯誤回報。

後續修正:v1.13.2(2026-09-23)

1.13.x 系列在 v1.13.2 收尾:該版讓 /opsx:verify 回報實際檢查了什麼(跳過的檢查不再顯示為通過),並修掉 Windows 上 archive 會遺留 .openspec-archive.lock、遇到目錄改名被系統阻擋時中途 rollback 的問題——把「archive / verify 的行為要可信」這個主軸延伸到跨平台層面。

學習重點

  1. 「validate 通過 ≠ 套用成功」:bullet marker 案例的教訓是 parser 與 writer(applier)必須共享同一套文法。validate 讀得到的形式,archive 卻讀不到,中間的縫隙就是靜默資料丟失。
  2. Spec 工具的供應鏈攻擊面:任何「會把 repo 內容轉成 agent instructions」的工具,都繼承了 repo 作者的話語權。信任邊界要畫在「讀你的規格」與「對你的 agent下指令」之間。

來源:v1.13.0、v1.13.1、v1.13.2