@seanmars/tospec 0.19.0-beta.0 → 0.19.0-beta.13

package/README.md

@@ -1,137 +1,132 @@
 # tospec
 
-> Spec-driven development CLI — 用 schema 定義文件與流程, 讓每個開發階段都能被檢查. 進度由檔案推算, 工作方法寫在 Skill 裡.
+> 用 schema 定義文件與流程的 spec-driven development CLI. 進度由檔案推算, 工作方法寫在 Skill 裡.
 
-tospec 把需求釐清, 規格, 設計, 任務, 實作到歸檔串成一套工作流程. Skill 協助 AI 工具 (Claude Code / Codex) 處理各階段, CLI 負責建立檔案, 檢查狀態與驗證規格格式. 它不另外維護狀態資料庫; `status` 會依 change 目錄裡有哪些檔案, 推算目前進度.
+寫需求時最常遇到的問題不是「不會寫」, 而是「寫到一半就跳去實作, 最後規格跟程式對不上」. tospec 把釐清需求, 寫規格, 設計, 拆任務, 實作, 歸檔串成一條線: Skill 帶著 AI 工具 (Claude Code / Codex) 走每一步, CLI 負責建檔, 看狀態, 驗證格式.
+
+它沒有狀態資料庫. `tospec status` 看 change 目錄裡有哪些檔案, 就知道走到哪一步; 檔案出現, 狀態就前進.
 
 ## 安裝
 
-需要 Node.js `>=22.22.0`.
+需要 Node.js 22.22.0 以上.
 
 ```bash
 npm install -g @seanmars/tospec
-```
-
-安裝後即可使用 `tospec` 指令:
-
-```bash
 tospec --help
-tospec --version
 ```
 
-也可以不安裝, 直接用 `npx`:
-
-```bash
-npx @seanmars/tospec --help
-```
+不想全域安裝也可以直接 `npx @seanmars/tospec --help`.
 
 ## 快速開始
 
 ```bash
-# 1. 在專案根目錄初始化, 並安裝 Claude Code 的 Skill
+# 初始化專案, 順便裝好 Claude Code 的 Skill
 tospec init --tools claude
 
-# 2. 建立一個新需求 change
+# 開一個新需求
 tospec new change add-dark-mode --schema sdd
 
-# 3. 查看目前各文件的狀態
+# 看這個 change 走到哪了
 tospec status --change add-dark-mode
 
-# 4. 驗證文件格式
+# 檢查文件格式
 tospec validate add-dark-mode
 
-# 5. 完成後歸檔, 把規格合併進主 specs
+# 做完了, 把規格合併進主 specs 並歸檔
 tospec archive add-dark-mode
 ```
 
-`--tools` 可填 `claude`, `codex`, `all` 或 `none`. 初始化後會建立 `tospec/` 目錄與 Skill; Claude Code 另外會產生 `/tosx:<name>` 快捷指令.
+`--tools` 可填 `claude`, `agents`, `all` 或 `none`. Skill 一律先寫進 `.agents/skills/` 這份 canonical 副本, 再複製到各工具目錄, 所以 `claude` 隱含 `agents`. Codex 直接讀 `.agents/`, 不會另外產生 `.codex/`. `none` 只建 `tospec/` 目錄, 不碰任何 agent 內容.
+
+`.claude/skills/` 是複本不是連結, 因為 junction 與 symlink 進 git 的記錄方式不同, 會讓追蹤內容取決於貢獻者的作業系統. 改了 `.agents/skills/` 之後要跑 `tospec update` 才會同步過去.
 
 ## 兩種工作流程
 
-建立 change 時用 `--schema` 選擇流程:
+開 change 時用 `--schema` 選:
 
 | schema | 用途 | 文件流程 |
 |--------|------|----------|
 | `sdd` | 開發新需求 | `proposal → specs / design → tasks` |
-| `issue` | 修正問題 | `task`(根因診斷) + 選配 `specs` |
+| `issue` | 修正問題 | `task` (根因診斷) + 選配 `specs` |
 
-兩者都在 **apply** 階段實作, 最後由 **archive** 判斷是否需要先 **sync** 再歸檔. apply 以完整測試與 `tospec validate` 通過為完成標準; **verify (雙軸審查) 是 opt-in**, 只有使用者主動要求時才執行, apply 不會自己跑, 也不會主動詢問.
+兩者都在 **apply** 階段實作, 最後由 **archive** 判斷要不要先 **sync** 再歸檔. apply 的完成標準是測試與 `tospec validate` 通過; 雙軸審查 (verify) 是 opt-in, 使用者開口才做.
 
-文件狀態的判斷方式:
+文件狀態只有四種:
 
-- `done` — 對應檔案已存在
-- `ready` — 前置文件都已建立, 這份還沒有, 可以開始
-- `blocked` — 至少一個前置文件還沒建立
-- `skipped` — 選配文件未建立, 不阻擋流程
+- `done`: 檔案已存在
+- `ready`: 前置文件都齊了, 這份還沒寫, 可以開始
+- `blocked`: 至少一份前置文件還沒建立
+- `skipped`: 選配文件沒建, 不擋流程
 
-## Skill 工作流程
+## Skill
 
-工作方法寫在 Skill 裡, CLI 只負責檔案與驗證. `tospec init` 會安裝 10 個 workflow Skill:
+`tospec init` 會裝 10 個 workflow Skill, Claude Code 另外會有對應的 `/tosx:<name>` 快捷指令.
 
 | Skill | 作用 |
 |-------|------|
-| `tospec-explore` | 以訪談收斂還很模糊的需求或問題 |
-| `tospec-grill` | 對任何產出 (計畫/決策/設計) 做四象限壓力測試 |
-| `tospec-propose` | 把已討論清楚的需求整理成完整 sdd change |
-| `tospec-issue` | 診斷 bug 至根因, 產出 issue change |
-| `tospec-decision` | 記錄架構決策為永久 ADR |
+| `tospec-explore` | 用訪談收斂還很模糊的需求或問題 |
+| `tospec-grill` | 對計畫, 決策, 設計做壓力測試 |
+| `tospec-propose` | 把討論清楚的需求整理成完整的 sdd change |
+| `tospec-issue` | 診斷 bug 到根因, 產出 issue change |
+| `tospec-decision` | 把架構決策記成永久 ADR |
 | `tospec-update` | 修訂 change 的規劃文件並保持一致 |
-| `tospec-apply` | 逐項實作任務 (不強制寫測試); verify 需使用者主動要求 |
+| `tospec-apply` | 逐項實作任務 |
 | `tospec-apply-with-tdd` | 同上, 但強制先寫測試 (red → green) |
 | `tospec-sync` | 以程式碼為準核對規格, 產出 sync-report |
-| `tospec-archive` | 判斷是否需要 sync, 然後歸檔完成的 change |
+| `tospec-archive` | 判斷要不要 sync, 然後歸檔 |
 
-典型流程: `explore` (想清楚) → `propose` (寫成 change) → `apply` (實作) → `sync` (需要時核對規格) → `archive` (歸檔). 修 bug 則從 `issue` 開始, 走同樣的 apply → archive 收尾.
+典型流程: `explore` 想清楚, `propose` 寫成 change, `apply` 實作, 需要時 `sync` 核對規格, 最後 `archive`. 修 bug 從 `issue` 開始, 一樣走 apply → archive 收尾.
 
 ## CLI 指令
 
-多數指令支援 `--json`, 方便 AI 工具讀取結果.
+多數指令支援 `--json`, 給 AI 工具讀. 封包格式與 exit code 見 [Agent 契約](./docs/agent-contract.md).
 
 ### 專案管理
 
-| 指令 | 作用 |
-|------|------|
-| `tospec init [path]` | 初始化專案, 建立 `tospec/` 與 Skill. 選項: `--tools <claude\|codex\|all\|none>`, `--force`, `--profile <name>` |
-| `tospec update [path]` | 重新產生已設定的 Skill, 修復連結或複製檔案. 選項: `--force` |
-| `tospec migrate [openspec-dir]` | 把 OpenSpec 專案轉成 tospec 格式 (預設讀 `./openspec`). 選項: `-f, --force` |
-| `tospec config <sub>` | 全域設定. 子命令: `path`, `list`, `get <key>`, `set <key> <value>`, `unset <key>`, `reset`, `edit`, `profile [preset]` (調整要安裝的 Skill) |
-
-### 建立與查詢
+| 指令 | 作用 | 選項 |
+|------|------|------|
+| `tospec init [path]` | 初始化專案, 建立 `tospec/`, Skill 與 workflow 規則 | `--tools`, `--force`, `--profile <name>`, `--json` |
+| `tospec update [path]` | 重新產生 Skill 並同步到各工具目錄 | `--force`, `--json` |
+| `tospec rules [path]` | 只刷新 workflow 規則檔, 不動 Skill 與設定 | `--json` |
+| `tospec migrate [openspec-dir]` | 把 OpenSpec 專案轉成 tospec 格式 (預設讀 `./openspec`) | `-f, --force`, `--json` |
+| `tospec config <sub>` | 全域設定: `path`, `list`, `get`, `set`, `unset`, `reset`, `edit`, `profile [preset]` | 各子命令多支援 `--json` |
 
-| 指令 | 作用 |
-|------|------|
-| `tospec new change <name>` | 建立 change 目錄與 ticket 索引檔. 選項: `--schema <sdd\|issue>`, `--description <text>`, `--goal <text>`, `--decisions <files>`, `--json` |
-| `tospec list` | 列出進行中的 change (預設). 選項: `--specs`, `--changes`, `--sort <recent\|name>`, `--type <requirement\|issue>`, `--json` |
-| `tospec show [item-name]` | 顯示 change 或 spec 內容. 選項: `--type <change\|spec>`, `--deltas-only`, `--requirements`, `--no-scenarios`, `-r, --requirement <id>`, `--no-interactive`, `--json` |
-| `tospec status` | 依檔案與 schema 顯示各文件狀態. 選項: `--change <id>`, `--schema <name>`, `--json` |
-| `tospec decision new <topic>` | 建立 ADR (`tospec/decisions/<yyyyMMdd_HHmmss>-<topic>.md`) 與索引列. 選項: `--title <text>`, `--summary <text>`, `--date <yyyyMMdd_HHmmss>`, `--status <proposed\|accepted\|superseded>`, `--force`, `--json` |
-| `tospec decision list` | 以索引表列出 ADR. 選項: `--status <proposed\|accepted\|superseded>`, `--sort <date\|name>`, `--json` |
-| `tospec skill-metrics` | 開啟本機網頁, 以圖表呈現每個 Skill 的耗時. 選項: `--no-open` |
+workflow 規則檔 (`.agents/rules/tospec/single-source-of-truth.md` 與 `.claude/` 下的複本) 由套件產生, 內含版本標記與內容雜湊. 一旦偵測到手改, `init` / `update` / `rules` 都會在寫入任何檔案前整次失敗, `--force` 也不例外. 想保留修改, 先備份再刪掉該檔重跑.
 
-`tospec skill-metrics` 會在 loopback 上啟動一台伺服器, 印出網址、開啟瀏覽器, 並停在前景直到 Ctrl+C. 連接埠固定從 **26693** 開始; 若已被占用則自動往上遞增直到找到可用的, 所以再開一個也不會失敗. 網頁是唯一的輸出形式, 沒有表格也沒有 `--json`; `--no-open` 只印網址而不開瀏覽器, 供沒有瀏覽器的環境使用.
+### 建立與查詢
 
-頁面共五張圖: 各 Skill 的總投入時間 (實色為 engaged, 凹陷部分為 idle, 整根長度即 span)、典型的單次時長 (engaged 與 span 的中位數)、每次執行的分佈 (每一次 run 都是一個點)、每日投入時間, 以及執行時間軸. 總量與中位數刻意分成兩張: 一個 Skill 可能總量第一但每次都很短, 那是次數多而不是每次慢.
+| 指令 | 作用 | 選項 |
+|------|------|------|
+| `tospec new change <name>` | 建立 change 目錄與 ticket | `--schema <sdd\|issue>`, `--description`, `--goal`, `--decisions <files>`, `--json` |
+| `tospec list` | 列出進行中的 change | `--specs`, `--changes`, `--sort <recent\|name>`, `--type <requirement\|issue>`, `--json` |
+| `tospec show [item-name]` | 顯示 change 或 spec | `--type <change\|spec>`, `--diff`, `--requirements`, `--no-scenarios`, `-r <id>`, `--no-interactive`, `--json` |
+| `tospec status` | 顯示各文件狀態 | `--change <id>`, `--all`, `--schema <name>`, `--json` |
+| `tospec decision new <topic>` | 建立 ADR 與索引列 | `--title`, `--summary`, `--date`, `--status`, `--force`, `--json` |
+| `tospec decision list` | 列出 ADR | `--status`, `--sort <date\|name>`, `--reindex`, `--json` |
+| `tospec skill-metrics` | 開本機網頁看每個 Skill 的耗時 | `--no-open` |
 
-時間範圍、idle gap、split gap 都可在頁面上調整並即時重算, 選擇會記在瀏覽器中; 「只看 tospec workflow」單純隱藏列, 不重新計算. 右上角可切換主題與語言 (English / 正體中文), 兩者同樣會被記住. 終端機輸出維持英文, 與其他指令一致.
+`show --diff` 會把 change 裡每個 requirement 對照主 specs 顯示差異, 包括 REMOVED 會刪掉的那段.
 
-資料同時來自 Claude Code 與 Codex 兩種工具的紀錄, 一律唯讀且不寫入任何檔案. Claude Code 讀取 transcript 的 `attributionSkill` 欄位 (只存在於較新的 session, 舊紀錄無法回溯統計); Codex 的 session 沒有對應欄位, 因此改用推論 — 只要偵測到某個 Skill 的 `SKILL.md` 被讀取, 就視為該 Skill 開始執行. 由於 Codex 的歸屬是推論而非直接紀錄, 兩者精準度不同, 頁面上一律分開呈現、絕不合併成同一個數字, Codex 的數字並附上這項說明. 每一列的標籤結尾都會標上來源工具 (Claude/Codex), 兩者皆標而非只標其中一方, 以免另一方被讀成預設值. 頁面在統計為空時, 會分別指出兩種工具各自屬於哪一種情況.
+`skill-metrics` 讀 Claude Code 與 Codex 的 session 紀錄, 只讀不寫. Claude Code 是直接讀 transcript 的歸屬欄位 (舊 session 沒有, 統計不到); Codex 沒有對應欄位, 改用「讀了哪個 `SKILL.md`」推論. 兩者精準度不同, 頁面上分開呈現, 不合併.
 
 ### 驗證與歸檔
 
-| 指令 | 作用 |
-|------|------|
-| `tospec validate [item-name]` | 檢查必要段落與 delta spec 格式. 選項: `--all`, `--changes`, `--specs`, `--type <change\|spec>`, `--strict`, `--concurrency <n>`, `--no-interactive`, `--json` |
-| `tospec archive [change-name]` | 重新驗證, 合併 delta specs 到主 specs, 再把 change 移到 archive. 選項: `-y, --yes`, `--skip-specs`, `--no-validate`, `--require-sync`, `--json` |
+| 指令 | 作用 | 選項 |
+|------|------|------|
+| `tospec validate [item-name]` | 檢查必要段落與 delta spec 格式 | `--all`, `--changes`, `--specs`, `--type`, `--strict`, `--concurrency <n>`, `--no-interactive`, `--json` |
+| `tospec archive [change-name]` | 重新驗證, 合併 delta specs, 把 change 移到 archive | `-y`, `--skip-specs`, `--no-validate`, `--require-sync`, `--json` |
 
-delta spec 的位置固定為 `specs/<capability>/spec.md`, **恰好一層**: 更深的巢狀目錄不會被合併, 驗證會直接報錯. 完全沒有行為變更的 change (工具, CI, 純文件) 在 `.tospec.yaml` 設 `skip_specs: true` 宣告即可, 不要為了通過驗證捏造 requirement.
+delta spec 固定放在 `specs/<capability>/spec.md`, 恰好一層, 更深的目錄不會被合併. 完全沒有行為變更的 change (工具, CI, 純文件) 在 `.tospec.yaml` 設 `skip_specs: true` 就好, 不要為了過驗證捏造 requirement.
+
+requirement 內文慣例上要有 SHALL 或 MUST, 缺了是 WARNING; `--strict` 才會把它當錯誤.
 
 ### 給 AI 工具的指令
 
-| 指令 | 作用 |
-|------|------|
-| `tospec instructions [artifact]` | 回傳建立文件或套用任務的完整指引 (artifact 填 `apply` 時回傳實作指引). 選項: `--change <id>`, `--schema <name>`, `--json` |
-| `tospec schemas` | 列出可用的工作流程 schema 與其文件. 選項: `--json` |
-| `tospec templates` | 顯示指定 schema 中各文件範本的實際路徑. 選項: `--schema <name>`, `--json` |
+| 指令 | 作用 | 選項 |
+|------|------|------|
+| `tospec instructions [artifact]` | 回傳建立文件的完整指引; `artifact` 填 `apply` 回傳實作指引 | `--change <id>`, `--schema <name>`, `--json` |
+| `tospec schemas` | 列出可用的 schema 與其文件 | `--json` |
+| `tospec templates` | 顯示 schema 中各文件範本的路徑 | `--schema <name>`, `--json` |
 
 ### Dashboard
 
@@ -139,16 +134,15 @@ delta spec 的位置固定為 `specs/<capability>/spec.md`, **恰好一層**:
 tospec dashboard [path]
 ```
 
-啟動本機唯讀 web dashboard, 檢視 change 與 specs 進度. 選項: `-p, --port <n>` (預設 5620), `--host <addr>` (預設 127.0.0.1), `-o, --open` (啟動後開啟瀏覽器), `-d, --detach` (背景執行), `--stop` (停止本專案的 dashboard), `-l, --list` (列出所有執行中的 dashboard), `--allow-remote` (允許綁定非 loopback 位址, 會對外網開放).
-
-## 文件
+本機 web dashboard, 看 change 與 specs 進度. 唯一的寫入是勾 task checkbox, 已歸檔或 sync 通過的 change 不能勾.
 
-- [Agent 契約](./docs/agent-contract.md) —— `--json` 的成功/失敗封包與 exit code
-- [自訂 schema](./docs/custom-schema.md) —— `schema.yaml` 欄位, 解析順序, 佈局限制
+選項: `-p, --port <n>` (預設 5620), `--host <addr>` (預設 127.0.0.1), `-o, --open`, `-d, --detach`, `--stop`, `-l, --list`, `--allow-remote` (綁非 loopback 位址, 會對外網開放).
 
-## 更新日誌
+## 文件
 
-各版本的變更與其根因說明: [CHANGELOG.md](./CHANGELOG.md)
+- [Agent 契約](./docs/agent-contract.md): `--json` 的成功/失敗封包與 exit code
+- [自訂 schema](./docs/custom-schema.md): `schema.yaml` 欄位, 解析順序, 佈局限制
+- [CHANGELOG](./CHANGELOG.md): 各版本的變更與根因說明
 
 ## 授權
 

package/assets/dashboard/app.js

@@ -587,6 +587,10 @@ function updateHealthStrip(staleDays) {
   if (parseErrors) {
     items.push(healthItem(`${parseErrors} ticket parse error(s)`, 'tickets-panel'));
   }
+  const unreadable = overview.changes.filter((c) => c.unreadable).length;
+  if (unreadable) {
+    items.push(healthItem(`${unreadable} change(s) with unreadable metadata`, 'changes-panel'));
+  }
   if (activity && activity.available && activity.specDrift) {
     items.push(el('span', { class: 'health-item', text: 'spec drift: code moved, tospec/ did not (7d)' }));
   }
@@ -614,6 +618,13 @@ function changeRow(c, staleDays, changed) {
     row.classList.add('row-ready');
     row.append(el('span', { class: 'badge badge-ready', text: 'ready' }));
   }
+  if (c.unreadable) {
+    // Ahead of every other badge: the counts beside it were all computed from
+    // metadata that would not parse, so they are zeros, not measurements.
+    const badge = el('span', { class: 'badge badge-unreadable', text: 'unreadable' });
+    badge.title = c.unreadable;
+    row.append(badge);
+  }
   if (c.artifactSummary.blocked > 0) {
     row.append(el('span', { class: 'badge badge-blocked-warn', text: 'blocked' }));
   }
@@ -840,7 +851,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 +1019,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 +1074,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/dashboard/style.css

@@ -671,6 +671,13 @@ a.row:hover {
   color: var(--error);
 }
 
+/* A change whose .tospec.yaml would not parse: every count beside it is a zero
+   rather than a measurement, so it is marked as an error, not a progress state. */
+.badge-unreadable {
+  background: var(--error-bg);
+  color: var(--error);
+}
+
 /* -- artifact blocks & status -- */
 .blocks {
   display: inline-flex;

package/assets/metrics/app.js

@@ -52,6 +52,7 @@ const STRINGS = {
     'control.theme': 'Theme',
     'control.language': 'Language',
     'control.refresh': '↻ Refresh',
+    'control.capturedAt': 'Data captured at {time} — Refresh to re-read',
     'range.30': 'Last 30 days',
     'range.90': 'Last 90 days',
     'range.365': 'Last year',
@@ -118,6 +119,7 @@ const STRINGS = {
     'control.theme': '主題',
     'control.language': '語言',
     'control.refresh': '↻ 重新讀取',
+    'control.capturedAt': '資料擷取於 {time}, 按重新讀取以更新',
     'range.30': '最近 30 天',
     'range.90': '最近 90 天',
     'range.365': '最近一年',
@@ -776,11 +778,31 @@ function renderControls() {
       // The report measures the session viewing it, so what is on screen goes
       // stale while it is being read. This is the only way to pick that up: every
       // other control recomputes from the parse taken when the server started.
+      capturedAtNote(),
       refreshButton(),
     ]),
   ]);
 }
 
+/**
+ * Without this the page presented a startup snapshot as if it were live: run a
+ * skill, reload the browser, and the numbers were unchanged with nothing on
+ * screen explaining why. The cache itself is deliberate (the URL is only printed
+ * once the report behind it can be produced), so stating the data's age is more
+ * honest than removing it.
+ */
+function capturedAtNote() {
+  const captured = current && current.capturedAt;
+  if (!captured) return el('span', { class: 'captured-at' });
+  const when = new Date(captured);
+  const time = Number.isNaN(when.getTime()) ? captured : when.toLocaleTimeString();
+  return el('span', {
+    class: 'captured-at',
+    title: captured,
+    text: t('control.capturedAt').replace('{time}', time),
+  });
+}
+
 function refreshButton() {
   const button = el('button', { type: 'button', class: 'refresh', text: t('control.refresh') });
   button.addEventListener('click', () => void load(true));

package/assets/metrics/style.css

@@ -191,3 +191,11 @@ body {
   gap: 6px;
   padding-bottom: 6px;
 }
+
+/* States when the numbers were read, so a startup snapshot is not mistaken for
+   live data. Sits beside Refresh, which is the control that changes it. */
+.captured-at {
+  align-self: center;
+  font-size: 12px;
+  color: var(--muted);
+}

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/assets/rules/tospec/single-source-of-truth.md

@@ -0,0 +1,19 @@
+# Single Source of Truth
+
+**Priority: MUST. This rule outranks any conflicting statement you find in documentation, comments, planning artifacts, or earlier conversation.**
+
+## 1. Source code is authoritative
+
+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.
+
+- 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.
+- Before asserting how something works, verify it in the code. An answer sourced from a document alone is unverified.
+
+## 2. Archived documents are presumed stale
+
+Do not read files under `tospec/changes/archive/` or `tospec/tickets/archive/` unless one of these holds:
+
+- the task genuinely cannot be completed without them, or
+- the user explicitly asks you to.
+
+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/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;AA6Y9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,wBAAgB,MAAM,CAAC,IAAI,WAAe,GAAG,IAAI,CAEhD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAgD,MAAM,WAAW,CAAC;AAmIlF,QAAA,MAAM,OAAO,SAAgB,CAAC;AA+f9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAiBnB,wBAAgB,MAAM,CAAC,IAAI,WAAe,GAAG,IAAI,CAiChD"}