@loviusc/sa-spec 0.1.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loviusc/sa-spec",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Personal system analysis documentation workspace CLI",
   "publishConfig": {
     "access": "public",

package/readme.md

@@ -235,9 +235,10 @@ sa-spec init --full
 
 | 指令 | 用途 |
 |---|---|
-| `sa-spec init` | 建立最小文件骨架。 |
-| `sa-spec init --full` | 建立文件骨架與完整規則文件。 |
-| `sa-spec new --id REQ-001 --name login` | 建立需求資料夾與空白文件模板，包含 SRS、UML、OpenAPI、DB Schema、handoff 與 history。 |
+| `sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]` | 建立文件骨架與規則文件（支援 5 種語言，預設 `zh-TW`）。 |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | 建立需求資料夾與空白文件模板（未帶 `--id` 時啟用多人草稿模式，可選 `--branch` 自動建立並切換至 `feat/<name>` 分支）。 |
+| `sa-spec finalize --name login` | 將草稿需求定號歸檔為最新序號（自動計算最新號碼、重命名目錄、批次置換 `{{REQ_ID}}` 並重建索引）。 |
+| `sa-spec reindex` | 掃描 `project/REQ-*` 目錄，依序號重新生成乾淨無衝突的 `project/index.md`。 |
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
 | `sa-spec doctor` | 檢查必要檔案是否存在。 |
@@ -349,6 +350,89 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才會執行 `git push`。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
 
+## 多人協作解決方案（Git-Flow 與延遲綁定 ID）
+
+在單人開發時，循序流水號（`REQ-001`、`REQ-002`）簡單直覺；但在多人平行協作時，容易引發兩大痛點：
+1. **序號競爭撞車**：Alice 與 Bob 同時在各自的分支開發，雙方本機都取了 `REQ-003`，合併回主幹時發生目錄重名衝突。
+2. **中心化檔案衝突**：每次歸檔都要修改 `project/index.md`，導致頻繁的 Git merge conflict。
+
+`sa-spec v0.2.0` 引進 **「Feature Branch 隔離 + 延遲綁定序號（Late-Binding ID）」** 完整解決方案：
+
+```mermaid
+flowchart TD
+    A[開新需求: sa-spec new --name cart --branch] --> B[建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄]
+    B --> C[AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護]
+    C --> D{使用者確認通過<br/>執行 scc 或 finalize}
+    D --> E[查詢 master 最新序號 N]
+    E --> F[重命名為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 為正式號碼]
+    F --> G[sa-spec reindex: 動態重構 index.md]
+    G --> H[合併回 master: 零衝突、序號永遠連續！]
+```
+
+### 多人協作四步流程
+
+#### 1. 提出需求（草稿與分支隔離）
+開需求時**不搶序號**，直接以語意名稱建立分支與草稿目錄：
+
+```bash
+# 自動建立並切換至 feat/cart-checkout 分支，建立 project/cart-checkout/ 草稿目錄
+sa-spec new --name cart-checkout --branch
+```
+在 VS Code 側邊欄輸入：
+```text
+scp 購物車結帳需求
+```
+* **特點**：目錄名稱為 `project/cart-checkout/`，內部所有檔案皆使用 `{{REQ_ID}}` 佔位符。多人同時提出需求互不干擾、零衝突。即使需求中途放棄，直接刪除分支即可，絕不留下幽靈跳號。
+
+#### 2. 分析與衝突檢查（規格基線同步）
+在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
+
+#### 3. 確認歸檔與延遲定號（Late-Binding）
+當需求規格確認無誤，準備歸檔時：
+
+```bash
+# 自動向 master 查詢最新可用序號（例如 REQ-006）
+sa-spec finalize --name cart-checkout
+```
+* **自動化執行**：
+  1. 取得最新序號（例如目前最大是 `REQ-005`，自動取得 `REQ-006`）。
+  2. 使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`。
+  3. 自動掃描並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  4. 自動執行 `reindex` 重建需求總表。
+
+#### 4. 消除索引合併衝突（`sa-spec reindex`）
+`project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
+
+```bash
+sa-spec reindex
+```
+* 任何時候若有 PR 合併產生 index 衝突，只要執行 `sa-spec reindex`，即可依序號重新排序生成乾淨的總表，無需人工手動解 conflict。
+
+## 語言與國際化支援（i18n）
+
+`sa-spec` 支援 5 種主要語言的系統分析規格產出與規範手冊：
+
+| 語系代碼 | 語言名稱 | 內文與風格規範 | 專有名詞處理準則 |
+|---|---|---|---|
+| `zh-TW` | **繁體中文**（預設） | 台灣技術常用語（如：伺服器、支援、專案） | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `en` | **English** | 100% 標準技術英文，不可出現中/日/韓文字符 | 原生技術英文 |
+| `zh-CN` | **简体中文** | 大陸技術常用語（如：服务器、支持、项目） | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ja` | **日本語** | 日語技術文體（です/ます 或 である），外來詞尊重 Katakana 慣例 | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ko` | **한국어** | 韓語專業技術文體與規範敬語 | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+
+### 語言管理核心原則
+
+1. **初始化強制鎖定（Init-Time Lock）**：
+   * 語言由初始化階段決定，不可模稜兩可。
+   * **CLI 指令**：可直接指定語系參數，例如 `sa-spec init --lang en`。
+   * **AI 工作流**：在對話中輸入 `spec:init`（或 `sci`）時，若未指定語言，**AI 必須主動列出 5 種語言選單詢問使用者**，選定後寫入 `project/system-spec.md` 作為全專案唯一的真理之源（Single Source of Truth）。
+2. **全專案語言單一純粹（Single-Language Purity）**：
+   * 選定語言後，全專案的所有產出（`srs.md`、`openapi.yaml`、`db-schema.md`、`handoff.md`、`history.md` 與 `rules/`）必須 100% 統一使用該語言，禁止在同一專案內出現語言混雜。
+3. **專有名詞保留原生英文（Technical Terms Exception）**：
+   * 在非英語系模式（繁中、簡中、日文、韓文）下，業界公認標準之技術術語、協定、資料格式與元件名稱（例如：`REST API`、`Webhook`、`JWT`、`OAuth 2.0`、`Payload`、`Idempotency Key`、`Redis`、`UUID` 等），**一律強制維持原生英文**，嚴禁生硬直譯。
+4. **升級保護（Upgrade Inheritance）**：
+   * 執行 `sa-spec upgrade` 時，系統會**自動偵測並繼承現有專案語言**（讀取 `project/system-spec.md`），不會詢問或變更既有專案語言，確保升級零干擾。
+
 ## 完整範例：番茄時鐘
 
 以下示範從空資料夾開始，建立一個「番茄時鐘」需求。
@@ -597,6 +681,25 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.1
+- **5 國語言與國際化支援（i18n）**：
+  - **支援語系**：繁體中文 (`zh-TW`，台灣常用語)、英文 (`en`)、簡體中文 (`zh-CN`)、日文 (`ja`)、韓文 (`ko`)。
+  - **初始化強制鎖定**：`sa-spec init [--lang <lang>]` 或在 AI 對話中輸入 `spec:init`，未指定時主動彈出選單詢問使用者選擇，選定後寫入 `system-spec.md`。
+  - **專案語言單一純粹**：全專案規格產出 100% 統一該語言。
+  - **技術專有名詞保留原生英文**：非英語系模式下強制保留標準英文術語（如 REST API, Webhook, JWT），嚴禁生硬直譯。
+  - **升級保護**：`sa-spec upgrade` 自動偵測並繼承現有專案語言，不變更設定。
+
+### v0.2.0
+- **多人協作 Git-Flow 解決方案（延遲綁定序號與零衝突索引）**：
+  - **解決痛點**：多人平行開發時，傳統流水號（`REQ-001`）容易在各自分支撞車，且中心化的 `project/index.md` 容易造成 Git merge conflict。
+  - **延遲綁定序號（Late-Binding ID）**：開需求時不搶號，在 feature branch 上以語意名稱建立草稿需求（如 `project/cart`），內部使用 `{{REQ_ID}}` 佔位；只有在 `spec:commit` 最終歸檔時，才向 master/遠端確認最新可用序號並定號（如 `REQ-003`），自動批次置換佔位符，徹底避免幽靈跳號與序號競爭。
+  - **動態重建需求索引（`sa-spec reindex`）**：將 `project/index.md` 改為根據 `project/REQ-*` 目錄動態掃描並依序號排序生成，消除手動 append 造成的 Git 合併衝突。
+  - **CLI 指令升級**：
+    - `sa-spec new [--id REQ-001] --name login [--branch]`：支援草稿模式與自動切換 feature 分支。
+    - `sa-spec finalize --name login`：自動定號、重命名目錄、置換佔位符並重建索引。
+    - `sa-spec reindex`：一鍵掃描並重新排序生成乾淨的 `project/index.md`。
+  - **分析前防護**：`spec:analyze` 執行前確保取得 master/遠端最新規格，避免分支規格落後導致漏檢衝突。
+
 ### v0.1.3
 - **支援指令簡寫別名（同時保留完整指令）**：
   - `sci` ＝ `spec:init`

package/src/cli.js

@@ -17,6 +17,12 @@ function main() {
     case "new":
       createReqTemplate(args.slice(1));
       return;
+    case "finalize":
+      finalizeReq(args.slice(1));
+      return;
+    case "reindex":
+      reindexProject();
+      return;
     case "check":
       runCheck();
       return;
@@ -32,6 +38,11 @@ function main() {
     case "template":
       runTemplate(args.slice(1));
       return;
+    case "version":
+    case "--version":
+    case "-v":
+      showVersion();
+      return;
     case "help":
     case "--help":
     case "-h":
@@ -43,29 +54,54 @@ function main() {
   }
 }
 
+const SUPPORTED_LANGS = {
+  "zh-tw": { code: "zh-TW", name: "繁體中文", label: "繁體中文 (zh-TW)" },
+  "en": { code: "en", name: "English", label: "English (en)" },
+  "zh-cn": { code: "zh-CN", name: "简体中文", label: "简体中文 (zh-CN)" },
+  "ja": { code: "ja", name: "日本語", label: "日本語 (ja)" },
+  "ko": { code: "ko", name: "한국어", label: "한국어 (ko)" }
+};
+
 function initProject(args = []) {
   const includeRules = args.includes("--full");
+  const langArg = getOption(args, "--lang");
+  let langConfig = SUPPORTED_LANGS["zh-tw"];
+  if (langArg) {
+    const key = langArg.toLowerCase();
+    if (SUPPORTED_LANGS[key]) {
+      langConfig = SUPPORTED_LANGS[key];
+    } else {
+      console.log(`警告: 不支援的語言代碼 "${langArg}"，支援語系: zh-TW, en, zh-CN, ja, ko。已預設使用繁體中文。`);
+    }
+  }
+
+  const replacements = {
+    LANG_LABEL: langConfig.label,
+    LANG_CODE: langConfig.code
+  };
+
   const results = [
     ensureGitRepository(),
     ensureDir("skills"),
     ensureDir(path.join("skills", "system-analysis")),
     ensureDir("project"),
-    ensureFileFromTemplate("AGENTS.md", "AGENTS.md"),
-    ensureFileFromTemplate("readme.md", "readme.md"),
-    ensureFileFromTemplate(path.join("skills", "system-analysis", "SKILL.md"), path.join("skills", "system-analysis", "SKILL.md")),
-    ensureFileFromTemplate(path.join("project", "index.md"), path.join("project", "index.md")),
-    ensureFileFromTemplate(path.join("project", "system-spec.md"), path.join("project", "system-spec.md"))
+    ensureFileFromTemplate("AGENTS.md", "AGENTS.md", replacements),
+    ensureFileFromTemplate("readme.md", "readme.md", replacements),
+    ensureFileFromTemplate(path.join("skills", "system-analysis", "SKILL.md"), path.join("skills", "system-analysis", "SKILL.md"), replacements),
+    ensureFileFromTemplate(path.join("project", "index.md"), path.join("project", "index.md"), replacements),
+    ensureFileFromTemplate(path.join("project", "system-spec.md"), path.join("project", "system-spec.md"), replacements)
   ];
 
   if (includeRules) {
     results.push(ensureDir("rules"));
     for (const file of listFilesRecursive(path.join(templatesDir, "rules"))) {
       const relativePath = path.relative(templatesDir, file);
-      results.push(ensureFileFromTemplate(relativePath, relativePath));
+      results.push(ensureFileFromTemplate(relativePath, relativePath, replacements));
     }
   }
 
   printResultList("init", results);
+  console.log(`專案規格主要語言已設定為: ${langConfig.label}`);
 }
 
 function ensureGitRepository() {
@@ -215,12 +251,46 @@ function createReqTemplate(args, label = "new") {
   const id = getOption(args, "--id");
   const name = getOption(args, "--name");
 
-  if (!id || !name) {
-    fail("Usage: sa-spec template req --id REQ-001 --name login");
+  if (!name) {
+    fail("Usage: sa-spec new [--id REQ-001] --name login [--branch]");
     return;
   }
 
   const slug = slugify(name);
+
+  // 草稿模式（Git-Flow 多人協作）：未指定 id 時建立草稿目錄，以 {{REQ_ID}} 佔位
+  if (!id) {
+    if (args.includes("--branch")) {
+      const branchName = `feat/${slug}`;
+      const branchRes = spawnSync("git", ["checkout", "-b", branchName], { cwd, encoding: "utf8" });
+      if (branchRes.status === 0) {
+        console.log(`已建立並切換至分支: ${branchName}`);
+      } else {
+        console.log(`提示: 分支切換略過 (${(branchRes.stderr || "").trim() || "可能是已有同名分支或未在 git 目錄"})`);
+      }
+    }
+
+    const reqDir = path.join("project", slug);
+    const umlDir = path.join(reqDir, "uml");
+    const replacements = { REQ_ID: "{{REQ_ID}}", REQ_NAME: name };
+    const results = [
+      ensureDir(reqDir),
+      ensureDir(umlDir),
+      ensureFileFromTemplate(path.join("project", "req", "srs.md"), path.join(reqDir, "srs.md"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "uml", "main.puml"), path.join(umlDir, "main.puml"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "openapi.yaml"), path.join(reqDir, "openapi.yaml"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "db-schema.md"), path.join(reqDir, "db-schema.md"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "handoff.md"), path.join(reqDir, "handoff.md"), replacements),
+      ensureFileFromTemplate(path.join("project", "req", "history.md"), path.join(reqDir, "history.md"), replacements)
+    ];
+
+    printResultList(label, results);
+    console.log(`\n已建立草稿需求：${reqDir}（內部使用 {{REQ_ID}} 佔位符）`);
+    console.log(`分析確認後，可使用 sa-spec finalize --name ${slug} 定號歸檔。`);
+    return;
+  }
+
+  // 傳統模式：指定序號
   const reqDir = path.join("project", `${id}-${slug}`);
   const umlDir = path.join(reqDir, "uml");
   const replacements = { REQ_ID: id, REQ_NAME: name };
@@ -239,6 +309,166 @@ function createReqTemplate(args, label = "new") {
   printResultList(label, results);
 }
 
+function finalizeReq(args) {
+  const name = getOption(args, "--name") || getOption(args, "--draft") || args[0];
+  if (!name) {
+    fail("Usage: sa-spec finalize --name <name-or-slug>");
+    return;
+  }
+
+  const slug = slugify(name);
+  const projectDir = path.join(cwd, "project");
+  let draftRelDir = path.join("project", slug);
+  let draftAbsDir = path.join(cwd, draftRelDir);
+
+  if (!fs.existsSync(draftAbsDir)) {
+    const altRelDir = path.join("project", `draft-${slug}`);
+    if (fs.existsSync(path.join(cwd, altRelDir))) {
+      draftRelDir = altRelDir;
+      draftAbsDir = path.join(cwd, altRelDir);
+    } else {
+      fail(`找不到草稿需求目錄: ${draftRelDir}`);
+      return;
+    }
+  }
+
+  // 掃描既有最大 REQ 編號
+  let maxIdNum = 0;
+  if (fs.existsSync(projectDir)) {
+    const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith("REQ-")) {
+        const m = entry.name.match(/^REQ-(\d+)/i);
+        if (m) {
+          const num = parseInt(m[1], 10);
+          if (num > maxIdNum) {
+            maxIdNum = num;
+          }
+        }
+      }
+    }
+  }
+
+  const nextIdNum = maxIdNum + 1;
+  const nextId = `REQ-${String(nextIdNum).padStart(3, "0")}`;
+  const finalDirName = `${nextId}-${slug}`;
+  const finalRelDir = path.join("project", finalDirName);
+  const finalAbsDir = path.join(cwd, finalRelDir);
+
+  if (fs.existsSync(finalAbsDir)) {
+    fail(`目標目錄 ${finalRelDir} 已存在，請確認序號或目錄名稱。`);
+    return;
+  }
+
+  // 重命名目錄 (優先嘗試 git mv)
+  const gitMv = spawnSync("git", ["mv", draftRelDir, finalRelDir], { cwd, encoding: "utf8" });
+  if (gitMv.status === 0) {
+    console.log(`[Git] 已將目錄重命名為: ${finalRelDir}`);
+  } else {
+    fs.renameSync(draftAbsDir, finalAbsDir);
+    console.log(`已將目錄重命名為: ${finalRelDir}`);
+  }
+
+  // 替換目錄內檔案的 {{REQ_ID}} 佔位符
+  const files = listFilesRecursive(finalAbsDir);
+  for (const filePath of files) {
+    try {
+      const content = fs.readFileSync(filePath, "utf8");
+      if (content.includes("{{REQ_ID}}")) {
+        const updated = content.split("{{REQ_ID}}").join(nextId);
+        fs.writeFileSync(filePath, updated, "utf8");
+      }
+    } catch (_) {
+      // 略過無法以文字讀取之檔案
+    }
+  }
+
+  // 自動重新整理 index.md
+  reindexProject();
+
+  console.log(`\n 需求已成功定號歸檔為: ${nextId} (${finalDirName})`);
+  console.log(`建議接下來執行：`);
+  console.log(`  git add project/`);
+  console.log(`  git commit -m "docs(${nextId}): ${name} - 規格確認歸檔"`);
+}
+
+function reindexProject() {
+  const projectDir = path.join(cwd, "project");
+  const indexPath = path.join(projectDir, "index.md");
+  if (!fs.existsSync(projectDir)) {
+    fail("project/ directory not found.");
+    return;
+  }
+
+  // 讀取現有索引
+  const existingMap = new Map();
+  if (fs.existsSync(indexPath)) {
+    const existingRows = parseIndexRows(fs.readFileSync(indexPath, "utf8"));
+    for (const row of existingRows) {
+      existingMap.set(row.id, row);
+    }
+  }
+
+  const entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  const reqDirs = entries.filter((e) => e.isDirectory() && e.name.startsWith("REQ-"));
+
+  const rows = [];
+  for (const entry of reqDirs) {
+    const dirName = entry.name;
+    const match = dirName.match(/^(REQ-\d+)(?:-(.*))?$/i);
+    if (!match) continue;
+    const id = match[1].toUpperCase();
+    const fallbackTitle = match[2] || dirName;
+
+    const reqDirPath = path.join(projectDir, dirName);
+    const srsPath = path.join(reqDirPath, "srs.md");
+
+    let title = fallbackTitle;
+    let description = "待補充";
+    let status = "待確認";
+    let createdAt = formatLocalDateTime(new Date());
+    let updatedAt = createdAt;
+
+    if (existingMap.has(id)) {
+      const prev = existingMap.get(id);
+      title = prev.title || title;
+      description = prev.description || description;
+      status = prev.status || status;
+      createdAt = prev.createdAt || createdAt;
+      updatedAt = prev.updatedAt || updatedAt;
+    }
+
+    if (fs.existsSync(srsPath)) {
+      const srsContent = fs.readFileSync(srsPath, "utf8");
+      const titleMatch = srsContent.match(/^# 需求規格[：:]\s*(?:REQ-\d+\s*)?(.*)$/m);
+      if (titleMatch && titleMatch[1].trim()) {
+        title = titleMatch[1].trim();
+      }
+      const statusMatch = srsContent.match(/^-\s*狀態[：:]\s*(.+)$/m);
+      if (statusMatch && statusMatch[1].trim()) {
+        status = statusMatch[1].trim();
+      }
+    }
+
+    const numMatch = id.match(/\d+/);
+    const num = numMatch ? parseInt(numMatch[0], 10) : 0;
+
+    rows.push({ num, id, title, description, status, createdAt, updatedAt });
+  }
+
+  // 依數字循序排序
+  rows.sort((a, b) => a.num - b.num);
+
+  const header = `# 需求索引\n\n| 編號 | 標題 | 敘述 | 狀態 | 建立時間 | 更新時間 |\n|---|---|---|---|---|---|\n`;
+  const tableRows = rows
+    .map((r) => `| ${r.id} | ${r.title} | ${r.description} | ${r.status} | ${r.createdAt} | ${r.updatedAt} |`)
+    .join("\n");
+  const nextContent = rows.length > 0 ? `${header}${tableRows}\n` : `${header}\n`;
+
+  fs.writeFileSync(indexPath, nextContent, "utf8");
+  console.log(`sa-spec reindex: 已重新索引 ${rows.length} 個需求至 project/index.md`);
+}
+
 function ensureIndexRow(id, name) {
   const indexPath = path.join(cwd, "project", "index.md");
   if (!fs.existsSync(indexPath)) {
@@ -324,7 +554,10 @@ function parseIndexRows(content) {
     .map((parts) => ({
       id: parts[1],
       title: parts[2],
-      status: parts[4]
+      description: parts[3],
+      status: parts[4],
+      createdAt: parts[5],
+      updatedAt: parts[6]
     }));
 }
 
@@ -341,8 +574,33 @@ function slugify(value) {
     .replace(/^-+|-+$/g, "");
 }
 
+function detectProjectLanguage() {
+  const systemSpecPath = path.join(cwd, "project", "system-spec.md");
+  if (fs.existsSync(systemSpecPath)) {
+    const content = fs.readFileSync(systemSpecPath, "utf8");
+    const match = content.match(/^-\s*(?:主要語言|語言|Language)[：:]\s*(.+)$/im);
+    if (match) {
+      const val = match[1].trim();
+      for (const key of Object.keys(SUPPORTED_LANGS)) {
+        if (
+          val.toLowerCase().includes(key) ||
+          val.includes(SUPPORTED_LANGS[key].label) ||
+          val.includes(SUPPORTED_LANGS[key].name) ||
+          val.includes(SUPPORTED_LANGS[key].code)
+        ) {
+          return SUPPORTED_LANGS[key];
+        }
+      }
+      return { code: "custom", label: val };
+    }
+  }
+  return SUPPORTED_LANGS["zh-tw"];
+}
+
 function upgradeProject(args = []) {
   const dryRun = args.includes("--dry-run");
+  const langConfig = detectProjectLanguage();
+  console.log(`專案目前語言: ${langConfig.label}（依現有語言升級，不變更設定）`);
   const results = [];
 
   results.push(ensureDir("skills"));
@@ -476,13 +734,21 @@ function showHelp() {
   console.log(`sa-spec
 
 Usage:
-  sa-spec init [--full]
-  sa-spec new --id REQ-001 --name login
+  sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]
+  sa-spec new [--id REQ-001] --name login [--branch]
+  sa-spec finalize --name login
+  sa-spec reindex
   sa-spec check
   sa-spec upgrade [--dry-run]
+  sa-spec --version
 `);
 }
 
+function showVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
+  console.log(pkg.version);
+}
+
 function fail(message) {
   console.error(message);
   process.exitCode = 1;

package/templates/AGENTS.md

@@ -26,7 +26,12 @@
 
 # 重要限制
 
-- 使用繁體中文，並採用台灣常用語。
+- 語言與國際化規範（i18n）：
+  - 支援語系：繁體中文 (`zh-TW`，台灣常用語)、英文 (`en`)、簡體中文 (`zh-CN`)、日文 (`ja`)、韓文 (`ko`) 共 5 種語言。
+  - 初始化語言鎖定：執行 `spec:init` (或 `sci`) 時，若使用者未明確指定語言，AI 必須主動詢問使用者選擇上述 5 種語言之一，不得自行預設；選定後將主要語言寫入 `project/system-spec.md`。
+  - 全專案語言單一純粹：後續所有需求文件（`srs.md`、`uml/`、`openapi.yaml`、`db-schema.md`、`handoff.md`、`history.md`）必須 100% 統一使用該語言，不得在同一專案內混雜多種語言。
+  - 專有名詞保留原生英文：在中文、日文、韓文等非英語系模式下，業界公認標準之技術術語（如 REST API, Webhook, JWT, OAuth 2.0, Payload, Idempotency, Redis 等）強制保留原生英文，嚴禁生硬直譯。
+  - 升級保護：執行 `sa-spec upgrade` 時，自動偵測並繼承現有專案語言，不變更語言設定。
 - `spec:init` 必須檢查 Git 狀態：若 Git 未安裝，提醒使用者後續歸檔會使用版本管理但不可中斷初始化；若 Git 已安裝且目前目錄尚未初始化為 Git repository，則自動執行 `git init`；若已是 Git repository，僅回報狀態，不重複初始化。
 - `project/system-spec.md` 由 `sa-spec init` 建立；`spec:analyze` 只能讀取它做衝突檢查，並提出待確認的系統規格更新建議，不得寫入；`spec:commit` 才能依使用者確認後的內容更新 `project/system-spec.md`。
 - 不可自行幻想未確認的業務規則、角色、流程、資料或系統行為。
@@ -39,6 +44,7 @@
 - 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
 - `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
 - `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+- 多人協作與 Git-Flow 模式（延遲綁定序號）：支援多人平行開發。提出需求時可於 feature branch（如 `feat/<name>`）建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時向 master 確認最新可用序號並定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、重新生成 `project/index.md`，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
 - `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。

package/templates/project/system-spec.md

@@ -1,6 +1,7 @@
 # 系統概覽
 
 - 狀態：草稿
+- 主要語言：{{LANG_LABEL}}
 
 ## 這個系統要解決什麼
 待補充。

package/templates/readme.md

@@ -235,9 +235,10 @@ sa-spec init --full
 
 | 指令 | 用途 |
 |---|---|
-| `sa-spec init` | 建立最小文件骨架。 |
-| `sa-spec init --full` | 建立文件骨架與完整規則文件。 |
-| `sa-spec new --id REQ-001 --name login` | 建立需求資料夾與空白文件模板，包含 SRS、UML、OpenAPI、DB Schema、handoff 與 history。 |
+| `sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]` | 建立文件骨架與規則文件（支援 5 種語言，預設 `zh-TW`）。 |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | 建立需求資料夾與空白文件模板（未帶 `--id` 時啟用多人草稿模式，可選 `--branch` 自動建立並切換至 `feat/<name>` 分支）。 |
+| `sa-spec finalize --name login` | 將草稿需求定號歸檔為最新序號（自動計算最新號碼、重命名目錄、批次置換 `{{REQ_ID}}` 並重建索引）。 |
+| `sa-spec reindex` | 掃描 `project/REQ-*` 目錄，依序號重新生成乾淨無衝突的 `project/index.md`。 |
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
 | `sa-spec doctor` | 檢查必要檔案是否存在。 |
@@ -349,6 +350,89 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才會執行 `git push`。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
 
+## 多人協作解決方案（Git-Flow 與延遲綁定 ID）
+
+在單人開發時，循序流水號（`REQ-001`、`REQ-002`）簡單直覺；但在多人平行協作時，容易引發兩大痛點：
+1. **序號競爭撞車**：Alice 與 Bob 同時在各自的分支開發，雙方本機都取了 `REQ-003`，合併回主幹時發生目錄重名衝突。
+2. **中心化檔案衝突**：每次歸檔都要修改 `project/index.md`，導致頻繁的 Git merge conflict。
+
+`sa-spec v0.2.0` 引進 **「Feature Branch 隔離 + 延遲綁定序號（Late-Binding ID）」** 完整解決方案：
+
+```mermaid
+flowchart TD
+    A[開新需求: sa-spec new --name cart --branch] --> B[建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄]
+    B --> C[AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護]
+    C --> D{使用者確認通過<br/>執行 scc 或 finalize}
+    D --> E[查詢 master 最新序號 N]
+    E --> F[重命名為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 為正式號碼]
+    F --> G[sa-spec reindex: 動態重構 index.md]
+    G --> H[合併回 master: 零衝突、序號永遠連續！]
+```
+
+### 多人協作四步流程
+
+#### 1. 提出需求（草稿與分支隔離）
+開需求時**不搶序號**，直接以語意名稱建立分支與草稿目錄：
+
+```bash
+# 自動建立並切換至 feat/cart-checkout 分支，建立 project/cart-checkout/ 草稿目錄
+sa-spec new --name cart-checkout --branch
+```
+在 VS Code 側邊欄輸入：
+```text
+scp 購物車結帳需求
+```
+* **特點**：目錄名稱為 `project/cart-checkout/`，內部所有檔案皆使用 `{{REQ_ID}}` 佔位符。多人同時提出需求互不干擾、零衝突。即使需求中途放棄，直接刪除分支即可，絕不留下幽靈跳號。
+
+#### 2. 分析與衝突檢查（規格基線同步）
+在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
+
+#### 3. 確認歸檔與延遲定號（Late-Binding）
+當需求規格確認無誤，準備歸檔時：
+
+```bash
+# 自動向 master 查詢最新可用序號（例如 REQ-006）
+sa-spec finalize --name cart-checkout
+```
+* **自動化執行**：
+  1. 取得最新序號（例如目前最大是 `REQ-005`，自動取得 `REQ-006`）。
+  2. 使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`。
+  3. 自動掃描並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  4. 自動執行 `reindex` 重建需求總表。
+
+#### 4. 消除索引合併衝突（`sa-spec reindex`）
+`project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
+
+```bash
+sa-spec reindex
+```
+* 任何時候若有 PR 合併產生 index 衝突，只要執行 `sa-spec reindex`，即可依序號重新排序生成乾淨的總表，無需人工手動解 conflict。
+
+## 語言與國際化支援（i18n）
+
+`sa-spec` 支援 5 種主要語言的系統分析規格產出與規範手冊：
+
+| 語系代碼 | 語言名稱 | 內文與風格規範 | 專有名詞處理準則 |
+|---|---|---|---|
+| `zh-TW` | **繁體中文**（預設） | 台灣技術常用語（如：伺服器、支援、專案） | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `en` | **English** | 100% 標準技術英文，不可出現中/日/韓文字符 | 原生技術英文 |
+| `zh-CN` | **简体中文** | 大陸技術常用語（如：服务器、支持、项目） | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ja` | **日本語** | 日語技術文體（です/ます 或 である），外來詞尊重 Katakana 慣例 | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ko` | **한국어** | 韓語專業技術文體與規範敬語 | 強制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+
+### 語言管理核心原則
+
+1. **初始化強制鎖定（Init-Time Lock）**：
+   * 語言由初始化階段決定，不可模稜兩可。
+   * **CLI 指令**：可直接指定語系參數，例如 `sa-spec init --lang en`。
+   * **AI 工作流**：在對話中輸入 `spec:init`（或 `sci`）時，若未指定語言，**AI 必須主動列出 5 種語言選單詢問使用者**，選定後寫入 `project/system-spec.md` 作為全專案唯一的真理之源（Single Source of Truth）。
+2. **全專案語言單一純粹（Single-Language Purity）**：
+   * 選定語言後，全專案的所有產出（`srs.md`、`openapi.yaml`、`db-schema.md`、`handoff.md`、`history.md` 與 `rules/`）必須 100% 統一使用該語言，禁止在同一專案內出現語言混雜。
+3. **專有名詞保留原生英文（Technical Terms Exception）**：
+   * 在非英語系模式（繁中、簡中、日文、韓文）下，業界公認標準之技術術語、協定、資料格式與元件名稱（例如：`REST API`、`Webhook`、`JWT`、`OAuth 2.0`、`Payload`、`Idempotency Key`、`Redis`、`UUID` 等），**一律強制維持原生英文**，嚴禁生硬直譯。
+4. **升級保護（Upgrade Inheritance）**：
+   * 執行 `sa-spec upgrade` 時，系統會**自動偵測並繼承現有專案語言**（讀取 `project/system-spec.md`），不會詢問或變更既有專案語言，確保升級零干擾。
+
 ## 完整範例：番茄時鐘
 
 以下示範從空資料夾開始，建立一個「番茄時鐘」需求。
@@ -597,6 +681,25 @@ git push origin master
 
 ## 更新紀錄
 
+### v0.2.1
+- **5 國語言與國際化支援（i18n）**：
+  - **支援語系**：繁體中文 (`zh-TW`，台灣常用語)、英文 (`en`)、簡體中文 (`zh-CN`)、日文 (`ja`)、韓文 (`ko`)。
+  - **初始化強制鎖定**：`sa-spec init [--lang <lang>]` 或在 AI 對話中輸入 `spec:init`，未指定時主動彈出選單詢問使用者選擇，選定後寫入 `system-spec.md`。
+  - **專案語言單一純粹**：全專案規格產出 100% 統一該語言。
+  - **技術專有名詞保留原生英文**：非英語系模式下強制保留標準英文術語（如 REST API, Webhook, JWT），嚴禁生硬直譯。
+  - **升級保護**：`sa-spec upgrade` 自動偵測並繼承現有專案語言，不變更設定。
+
+### v0.2.0
+- **多人協作 Git-Flow 解決方案（延遲綁定序號與零衝突索引）**：
+  - **解決痛點**：多人平行開發時，傳統流水號（`REQ-001`）容易在各自分支撞車，且中心化的 `project/index.md` 容易造成 Git merge conflict。
+  - **延遲綁定序號（Late-Binding ID）**：開需求時不搶號，在 feature branch 上以語意名稱建立草稿需求（如 `project/cart`），內部使用 `{{REQ_ID}}` 佔位；只有在 `spec:commit` 最終歸檔時，才向 master/遠端確認最新可用序號並定號（如 `REQ-003`），自動批次置換佔位符，徹底避免幽靈跳號與序號競爭。
+  - **動態重建需求索引（`sa-spec reindex`）**：將 `project/index.md` 改為根據 `project/REQ-*` 目錄動態掃描並依序號排序生成，消除手動 append 造成的 Git 合併衝突。
+  - **CLI 指令升級**：
+    - `sa-spec new [--id REQ-001] --name login [--branch]`：支援草稿模式與自動切換 feature 分支。
+    - `sa-spec finalize --name login`：自動定號、重命名目錄、置換佔位符並重建索引。
+    - `sa-spec reindex`：一鍵掃描並重新排序生成乾淨的 `project/index.md`。
+  - **分析前防護**：`spec:analyze` 執行前確保取得 master/遠端最新規格，避免分支規格落後導致漏檢衝突。
+
 ### v0.1.3
 - **支援指令簡寫別名（同時保留完整指令）**：
   - `sci` ＝ `spec:init`

package/templates/skills/system-analysis/SKILL.md

@@ -27,7 +27,12 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 
 ## 硬性限制
 
-- 使用繁體中文，並採用台灣常用語。
+- 語言與國際化規範（i18n）：
+  - 支援語系：繁體中文 (`zh-TW`，台灣常用語)、英文 (`en`)、簡體中文 (`zh-CN`)、日文 (`ja`)、韓文 (`ko`) 共 5 種語言。
+  - 初始化語言鎖定：執行 `spec:init` (或 `sci`) 時，若使用者未明確指定語言，AI 必須主動詢問使用者選擇上述 5 種語言之一，不得自行預設；選定後將主要語言寫入 `project/system-spec.md`。
+  - 全專案語言單一純粹：後續所有需求文件（`srs.md`、`uml/`、`openapi.yaml`、`db-schema.md`、`handoff.md`、`history.md`）必須 100% 統一使用該語言，不得在同一專案內混雜多種語言。
+  - 專有名詞保留原生英文：在中文、日文、韓文等非英語系模式下，業界公認標準之技術術語（如 REST API, Webhook, JWT, OAuth 2.0, Payload, Idempotency, Redis 等）強制保留原生英文，嚴禁生硬直譯。
+  - 升級保護：執行 `sa-spec upgrade` 時，自動偵測並繼承現有專案語言，不變更語言設定。
 - `spec:init` 必須檢查 Git 狀態：
   - 若 Git 未安裝，提醒使用者後續歸檔會使用版本管理，但不可中斷初始化。
   - 若 Git 已安裝且目前目錄尚未初始化為 Git repository，則自動執行 `git init`。
@@ -43,6 +48,7 @@ description: 用 init、propose、analyze、commit 四段流程整理需求，
 - 交給 OpenSpec 或其他 AI 開發工具時，必須指定它先閱讀 `handoff.md`，並以 `handoff.md` 作為開發入口與限制摘要；其他規格文件作為詳細來源。
 - `spec:commit` 完成文件歸檔後，必須自動建立本機 Git commit；commit message 以需求編號與需求名稱為主，並加上簡短需求說明，格式為 `docs(REQ-001): 需求名稱 - 簡短需求說明`。
 - `spec:commit` 只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才可執行 `git push`；push 失敗時只回報認證或網路問題，不得回滾已完成的文件歸檔與本機 commit。
+- 多人協作與 Git-Flow 模式（延遲綁定序號）：支援多人平行開發。提出需求時可於 feature branch（如 `feat/<name>`）建立草稿目錄，內部使用 `{{REQ_ID}}` 佔位；執行 `spec:analyze` 前應先確保取得 master 最新規格以防漏檢衝突；執行 `spec:commit` 歸檔時向 master 確認最新可用序號並定號，自動將目錄定名為正式 `REQ-xxx`、替換內部佔位符、重新生成 `project/index.md`，避免多人合併時的序號競爭與索引衝突。
 - 文件未經使用者確認，不得標示為 `已審核`。
 - `uml/` 內的 UML 圖不限單一 UML 圖型；`spec:analyze` 必須依需求選擇最能說明流程、互動、狀態或資料關係的 UML 圖，例如活動圖、循序圖、使用案例圖、狀態圖或類別圖，不可為了固定格式硬產生活動圖。**嚴禁將多張圖混在同一個檔案中**，必須在需求資料夾下的 `uml/` 目錄拆分成獨立的 `.puml` 檔案（例如 `uml/main.puml`、`uml/sequence.puml`、`uml/state.puml`），且每個檔案只能包含一組 `@startuml` 與 `@enduml`，以避免 PlantUML 渲染或預覽失敗。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。