superpowers-mcp 6.3.8 → 6.3.10

package/README.ja.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![バージョン](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![バージョン](https://img.shields.io/badge/version-6.3.10-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 このドキュメントは、Superpowers スキルライブラリと自律型ワークフローを、独立した高パフォーマンスかつ安全な **Model Context Protocol (MCP)** サーバーにパッケージ化した使用説明書です。
@@ -43,6 +43,8 @@
 > [!NOTE]
 > **任意のディレクトリから実行可能**: 本リポジトリを事前にクローンしたり、特定のフォルダに移動したりする必要はありません。ターミナルの**任意の場所**から以下のコマンドを直接実行できます。インストーラーがユーザーホームディレクトリ（`~`）を基準にグローバル設定ファイルを自動検出し、すべてのワークスペースで即座に有効化します。
 
+デスクトップ向け設定：[LM Studio、Roo Code、ChatWise、Cherry Studio](docs/desktop-setup.md)。新しい CLI オプションは npm 未公開です。公開まではガイドのローカルコマンドを使用してください。
+
 > [!TIP]
 > **透明性と環境保護の原則**: Superpowers は、選択されていない他のエディタを勝手にスキャンしたり一括変更したりすることは決してありません。使用する AI ツールに合わせて専用コマンドを実行するだけで、**アトミック書き込み技術**により設定を安全に統合します（クラッシュ時破損ゼロ、**デフォルトで `.bak` ファイル等のゴミを残さない完全クリーン仕様**、既存の他 MCP サーバーには影響なし）。
 
@@ -52,6 +54,8 @@
 
 | Harness / クライアント | 対応 OS | ワンクリック設定コマンド | 設定ファイルの場所 |
 | :--- | :--- | :--- | :--- |
+| **LM Studio** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target lmstudio` | `~/.lmstudio/mcp.json` |
+| **Roo Code (VS Code Desktop)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target roo` | `.../rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
 | **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
 | **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
 | **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
@@ -175,7 +179,39 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 最近の更新
 
-### v6.3.8（最新）
+### v6.3.10（最新）
+
+- **ユニバーサルセットアップエンジンのキー名衝突解消とユーザー設定の無損失保持**：
+  - 既存の `servers`、`mcp`、`mcpServers` を自動探索し、異なる AI Client 間で競合する重複設定ブロックが作成されるのを防止。
+  - 再インストール時にもユーザー独自の `env`、`cwd`、`disabled`、`alwaysAllow` 等のフィールドを安全にマージし無損失で保持。
+  - `disabled: true` と `enabled: true` が矛盾して併存する不正状態を確実に排除。
+  - コマンドライン引数を厳格に検証し、未定義の位置引数を拒絶（終了コード 1）。唐突なプロセス終了を `process.exitCode` に統一し、パイプラインでの非同期 I/O 切り捨てを防止。
+- **コアスキルエンジンの単一 Stat スナップショット検証と世代シールド**：
+  - キャッシュ検証に単一 `fs.stat` スナップショット比較（`dev`, `ino`, `size`, `mtimeMs`）を採用。シンボリックリンクやファイルが差し替えられた場合は即座にキャッシュを無効化（全ディレクトリ走査不要）。
+  - `clearCache()` で単調増加の `scanEpoch` を進め `loadingEpoch` をリセットすることで、非同期遅延スキャンによるキャッシュリセット後の上書き汚染を防止。
+  - オープン済み記述子の Inode 検証（`readFileNoFollow`）により TOCTOU 記述子差し替えを排除。
+- **MCP Prompt テンプレートの堅牢性と重複展開排除**：
+  - テンプレートファイルが空または存在しない場合、構造化 `stderr` 診断を出力し標準 `McpError(ErrorCode.InternalError)` をスロー。
+  - `appliedInterpolations` により置換済みプレースホルダーを追跡し、多重の引数末尾追加を防止。
+- **包括的セキュリティ監査と回帰テスト基盤**：
+  - 全テストスイート **292 件の自動化アサーション**（Node.js: 163、Bash: 35、PowerShell: 94）が 100% 合格、脆弱性ゼロ・機密漏洩ゼロを確認。
+
+### v6.3.9
+
+- **完全な ReDoS 防御（CodeQL Alert #4 の解決）**：
+  - YAML 解析（`updateYamlConfig`）の多項式バックトラック正規表現を明確なプレフィックス一致とネイティブ `String.prototype.trim()` に置換。
+  - `extractInlineComment` 線形スキャナー（$O(N)$）を導入し、長大な空白入力時のバックトラックを防止。GitHub CodeQL Alert #4（`js/polynomial-redos`）の解決を遠隔解析で確認。
+  - `tests/setup_test.js` に 60,000 文字の空白パディングストレステストを追加し、線形時間（<1ms）での処理を保証。
+- **クライアント対応の拡張（17 種類の AI Agent クライアントをサポート）**：
+  - **LM Studio**（`lmstudio`、`~/.lmstudio/mcp.json`）および VS Code Desktop 版 **Roo Code**（`roo`、`rooveterinaryinc.roo-cline/settings/mcp_settings.json`）のターゲットを追加。
+  - YAML パーサーを強化し、`mcp_servers:` および `superpowers:` 宣言のインラインコメントやファイルヘッダーコメントを保持。
+- **デスクトップ向け設定エクスポートと終了コードの整合性**：
+  - `setup --print-config`（`--bun` 対応）を追加し、ChatWise や Cherry Studio などのデスクトップクライアントへ無変更でインポート可能な JSON を出力。
+  - `src/server.ts` の setup 委任において `process.exitCode` を保持し、非ゼロ終了コードの握りつぶしを防止。
+- **デスクトップセットアップガイド**：
+  - LM Studio、Roo Code、ChatWise、Cherry Studio の設定手順を解説した [`docs/desktop-setup.md`](docs/desktop-setup.md) を追加。
+
+### v6.3.8
 
 - **実行可能な対話型ワークフローランチャー**：
   - `feature-pipeline` と `structured-debug` は、ステージごとに明示的な `read_skill` 呼び出しを示し、必要なユーザー承認ゲートを保持し、実行が MCP サーバー内ではなくクライアント Agent 側で行われることを明記します。
@@ -202,47 +238,6 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 - **全自動回帰テストの基盤**：
   - テストスイートを **274 の全自動アサーション**（Node.js: 145、Bash: 35、PowerShell: 94）に拡張し、100% の合格率を維持。
 
-### v6.3.7
-
-- **上流同期 — バッチ 1〜3（obra/superpowers）**：
-  - **スキルの自動ルーティング**：`systematic-debugging` と `test-driven-development` の description にトリガーフレーズ（`"tdd"`、`"systematic debug"` など）と相互クロスルートを追加し、MCP クライアントでのスキル選択精度を向上。
-  - **テストコマンドがない場合のエビデンス律**：`verification-before-completion` に「When There Is No Test Command」を追加。レポート、調査、監査、書簡では成果物を再度開き、証明できる事項を証明し、未完了項目を明示。主張できるのは「完全」であり「正しい」ではない。
-  - **ブレインストーミングの意図ゲート**：「Establish Shared Understanding」（意図の探索 → 理解の書き戻し → 設計への引き継ぎ）を新設し、HARD-GATE をパスごとの前提条件を列挙する形に書き直し。一度の承認を残り工程の省略許可と見なすことを禁止。
-  - **プランニング・ハンドオフ・レビュー**：brainstorming の仕様セルフレビューを 0.0–9.9 の評価 + burden ledger + 単一の有界改善パス + 読み取り専用の再評価に昇格。失敗時は初稿へ復元する安全則付き。
-  - **保存済みプランのレビューと文脈的ハンドオフ**：`writing-plans` は実行前に人間が保存プランをレビューすることを必須化。実行方法が未指定の場合は、固定の既定値ではなくこのプラン固有の推奨を提示。
-  - **プランのチェックボックス簿記**：`executing-plans` と `subagent-driven-development` が完了メッセージと同時にプランファイルの手順をチェック。
-  - **リモート安全境界**：`using-git-worktrees` は共有 ref から分岐する際に `--no-track` を必須化し、`git branch -vv` による追跡確認（初回 commit 前に `--unset-upstream`）を求める。`executing-plans` は commit をローカルに留め、共有ブランチの書き換えを禁止。implementer はタスク中の push 要求を BLOCKED として controller に報告する。
-  - **Discoveries 台帳**：SDD の進捗台帳に `## Discoveries` セクションを追加し、タスク横断の知見が compaction を越えて次のディスパッチのインターフェース条項に引き継がれる。
-  - **保留所見のエクスポート**：プランワークスペース削除前に、`Ruling:`／`minor (deferred)`／`parked` 行を PR の「Deferred items」チェックリスト、またはコミット済み `docs/superpowers/follow-ups/<plan>.md` へ退避する。
-  - **Greenfield SDD スクリプト**：リポジトリ未作成時は `sdd-workspace` がカレントディレクトリへフォールバック（`.ps1` も同様）。`review-package` は非リポジトリ環境で実行可能なエラーを返す。
-  - **TDD 特性化ガード**：振る舞いを保つリファクタリング向けの 5 ステップ手順（変異→失敗確認→VCS 復元→グリーン維持）。境界とミューテーション検査の各節から参照。
-- **上流コンテンツ同期 — バッチ 4**：brainstorm の起動スクリプトは `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST` からホスト既定値を取得（`--host`/`--url-host` が優先）。`writing-skills` にコンテンツ移動時のリンク再解決手順を追加し、SDD レビュアは完全なレポートを `…/task-N-review.md` に書いて 15 行未満の要約のみを返すようになり、MCP 側に `review_file` 引数（指定パスが正規化後にレポート／brief ファイルと一致する場合は導出した `-review.md` に置換）と、`[FIX_BASE_SHA]` を実際に展開する `fix_base_sha` 別名を追加。
-- **上流ドリフトレポート**：`npm run drift` がコミット済みベースラインと `obra/superpowers` を比較し、採用済みファイルの変更・ローカルに無い取り込み・fork 独自追加を一覧表示。`npm run drift:record -- --ignore <skill>` でレビュー済み同期後に更新し、書き込み前に途中で切れた API tree を拒否。
-- **MCP サーフェス網羅テスト**：ディスク上の各スキルは自身のコンテンツを返す MCP リソースとして公開され、プロンプト一覧は 4 つの README と完全一致すること。
-- **MCP 説明文の忠実性**：上流のエスケープ引用形式を非引用の YAML plain scalar に適応し、`SkillsManager` が MCP 経由で余分なバックスラッシュを出力しないようにした。
-- **回帰ガード**：`tests/upstream_sync_test.js` をバッチ 1〜4 を覆う 22 個のラベル付きチェックに拡張。全スイート合格（npm 8 スイート 139 チェック、PowerShell 90 アサーション、SDD 16 + ホスト既定 11 + render-graph 8 の bash アサーション）。
-- **リリース準備の強化**：Bash／PowerShell の brainstorm host テストは background モードを明示的に強制し、264 アサーションの全マトリクスが `CODEX_CI=1` でも完了。`package-lock.json` を v6.3.7 と Node `>=18` に同期し、npm repository と CLI `bin` メタデータを正規化。`npm publish --dry-run` とパッケージのインストール smoke test で検証済み。
-
-### v6.3.6
-
-- **極限のパフォーマンス最適化（2倍〜8.1倍の高速化）**：
-  - **スキルの並行インデックスと事前キャッシュ**：`SkillsManager.listSkills` を非同期並行ディレクトリ走査（`Promise.all`）とルートパス事前解決キャッシュにアップグレードし、コールドスタート時のインデックス遅延を 4.79ms から 2.35ms に短縮（**2.04倍の高速化**）。
-  - **超高速インメモリ Canonical キャッシュ**：`readSkillContent` において物理実パスをキーとする Canonical キャッシュとエイリアスマッピングを導入し、同一スキルの再読み込み時間を 0.013ms から 1.6µs に短縮（**8.1倍の高速化**）。
-  - **Frontmatter スライシングと ReDoS 防御**：`parseFrontmatter` においてファイル全体の一括正規表現走査を 64 KB のプレフィックスバッファ切り出しに置き換え、大規模ファイルでの GC 停止と二次関数的 ReDoS リスクを根絶。
-  - **JSON パース高速パス**：`stripJsonComments` (`src/setup-runner.ts`) にネイティブ JSON 試行を導入し、コメントのない設定ファイルの読み込み時間を 0.55µs に短縮（**5.1倍の高速化**）。
-  - **マルチターゲット並行ビルド**：`esbuild.js` で 4 つの独立アーティファクトを `Promise.all` で並行コンパイルし、ビルド時間を ~50ms に短縮（**~42% 高速化**）。
-- **デュアル Subagent 深度コードレビューと包括的欠陥修正 (FIX ALL)**：
-  - **Partial-Read バッファ切り捨て防御**：`SkillsManager.readFileNoFollow` に累積読み込みループ（`while (totalRead < fileSize)`）を実装し、高負荷 I/O や仮想ファイルシステムでの暗黙の Markdown 切り捨てを防止。
-  - **Scan Epoch 並行競合シールド**：`listSkills` に単調増加の `scanEpoch` カウンタを導入し、非同期の古いスキャンが最新のキャッシュ状態を上書きするレースコンディションを解消。
-  - **Canonical キャッシュ整合性の保証**：実物理パス（`realFilePath`）をマスターキーとし、`canonicalPathMap` でエイリアスを追跡することで、強制リロード時のシンボリックリンクキャッシュ乖離（Cache Drift）を根絶。
-  - **システムディレクトリブラックリストの拡張**：`getSafeSkillsPath` に macOS 固有の `/private/etc` および `/private/var` を追加し、特権ディレクトリへのパスエスケープを防止。
-  - **設定書き込み時のシンボリックリンク先検証**：`safeWriteConfig` で `fs.lstat` と実パス解決を実施し、機密システム領域へのシンボリックリンク書き込みを拒絕。
-  - **厳格な TypeScript と Rule 7 ゼロ欠陥準拠**：未使用のデッドコード（`exists`）を完全削除し、`--noUnusedLocals --noUnusedParameters` に合格。型なし・空の catch ブロックをすべて排除。
-- **自動化テストスイートの拡張と回帰検証**：
-  - 85 件のコアユニット/結合テストと 174 件の回帰アサーションが 100% 合格（`setup_test.js` は 33 件すべて合格）。[`SECURITY.md`](SECURITY.md)、[`tests/code_review_report.md`](tests/code_review_report.md)、[`tests/performance_optimization_report.md`](tests/performance_optimization_report.md) を整備。
-- **多言語ドキュメントの同期**：
-  - 4 言語すべての README（[`README.md`](README.md)、[`README.zh-TW.md`](README.zh-TW.md)、[`README.ja.md`](README.ja.md)、[`README.ko.md`](README.ko.md)）でサポート環境一覧、パフォーマンス指標、ワンクリックコマンド表を同期。
-
 👉 *これまでの詳細なリリース履歴については、完全な [CHANGELOG.md](CHANGELOG.md) を参照してください。*
 
 ---

package/README.ko.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.10-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 이 문서는 Superpowers 스킬 라이브러리와 자율 에이전트 워크플로우를 독립적이고 고성능이며 안전한 **Model Context Protocol (MCP)** 서버로 패키징한 사용 지침을 요약한 것입니다.
@@ -43,6 +43,8 @@
 > [!NOTE]
 > **모든 디렉터리에서 바로 실행 가능**: 이 저장소를 복제(clone)하거나 특정 폴더로 이동할 필요가 없습니다. 터미널의 **어느 위치에서나** 바로 아래 명령어를 실행할 수 있습니다. 설치 도구가 사용자 홈 디렉터리(`~`)를 기준으로 전역 설정 파일을 자동 탐지하여 모든 작업 공간에서 즉시 활성화합니다.
 
+데스크톱 빠른 설정: [LM Studio, Roo Code, ChatWise, Cherry Studio](docs/desktop-setup.md). 새 CLI 옵션은 아직 npm에 배포되지 않았습니다. 배포 전에는 가이드의 로컬 명령을 사용하세요.
+
 > [!TIP]
 > **투명성 및 환경 보호 원칙**: Superpowers MCP는 악성코드처럼 선택되지 않은 다른 에디터를 임의로 스캔하거나 일괄 수정하지 않습니다. 사용 중인 AI 클라이언트 전용 명령어를 실행하기만 하면, **원자적 쓰기(Atomic Swap) 기술**을 통해 설정을 안전하게 병합합니다 (충돌 시 손상 제로, **기본적으로 불필요한 `.bak` 쓰레기 파일을 남기지 않는 클린 사양**, 기존 다른 MCP 서버 무영향).
 
@@ -52,6 +54,8 @@
 
 | Harness / 클라이언트 | 지원 OS | 원클릭 설정 명령어 | 기본 설정 파일 경로 |
 | :--- | :--- | :--- | :--- |
+| **LM Studio** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target lmstudio` | `~/.lmstudio/mcp.json` |
+| **Roo Code (VS Code Desktop)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target roo` | `.../rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
 | **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
 | **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
 | **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
@@ -173,7 +177,39 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 최근 업데이트
 
-### v6.3.8 (최신)
+### v6.3.10 (최신)
+
+- **유니버설 글로벌 설정 엔진 키 충돌 해소 및 사용자 설정 무손실 보존**:
+  - 기존의 `servers`, `mcp`, `mcpServers`를 자동 감지하여 서로 다른 AI Client 환경에서 중복되거나 모순되는 설정 블록이 생성되는 것을 방지.
+  - 재설치 시에도 사용자가 직접 구성한 `env`, `cwd`, `disabled`, `alwaysAllow` 등의 필드를 안전하게 병합하고 무손실 보존.
+  - `disabled: true`와 `enabled: true`가 동시에 공존하는 모순 상태를 원천 차단.
+  - 명령행 인수를 엄격하게 검증하여 예기치 않은 위치 인수를 거부(종료 코드 1). 프로세스 종료를 `process.exitCode`로 표준화하여 Unix 파이프라인에서 비동기 I/O 잘림 방지.
+- **핵심 스킬 엔진 단일 Stat 스냅샷 검증 및 세대 격리**:
+  - 단일 `fs.stat` 스냅샷 비교(`dev`, `ino`, `size`, `mtimeMs`)를 도입하여 심볼릭 링크나 파일이 교체된 경우 전체 디렉터리 재탐색 없이 즉시 캐시를 무효화.
+  - `clearCache()`에서 단조 증가하는 `scanEpoch`를 전진시키고 `loadingEpoch`를 리셋하여 지연된 비동기 스캔이 캐시 리셋 후 최신 상태를 오염시키는 것을 방지.
+  - 열려 있는 디스크립터의 Inode 검증(`readFileNoFollow`)을 통해 TOCTOU 디스크립터 교체 경쟁 조건 제거.
+- **MCP Prompt 템플릿 견고성 및 중복 인수 추가 방어**:
+  - 템플릿 파일이 비어 있거나 누락된 경우 구조화된 `stderr` 진단을 출력하고 표준 `McpError(ErrorCode.InternalError)`를 발생시킴.
+  - `appliedInterpolations`를 통해 치환된 템플릿 플레이스홀더를 추적하여 불필요한 레거시 인수 중복 추가 방지.
+- **포괄적인 보안 감사 및 자동화 회귀 테스트 기준선**:
+  - 전체 스위트 **292개 자동 어서션**(Node.js: 163, Bash: 35, PowerShell: 94) 100% 통과, 취약점 0건, 기밀 유출 0건 확인.
+
+### v6.3.9
+
+- **영구적인 ReDoS 방어 (CodeQL Alert #4 해결)**:
+  - YAML 파싱(`updateYamlConfig`)의 다항식 역추적 정규식을 모호하지 않은 접두사 일치와 네이티브 `String.prototype.trim()`으로 대체.
+  - `extractInlineComment` 선형 스캐너($O(N)$)를 도입하여 긴 공백 입력 시의 역추적을 차단. GitHub CodeQL Alert #4(`js/polynomial-redos`) 공식 해결 확인.
+  - `tests/setup_test.js`에 60,000자 공백 패딩 스트레스 테스트를 추가하여 선형 처리 시간(<1ms) 보장.
+- **클라이언트 에코시스템 확장 (17개 AI Agent 클라이언트 지원)**:
+  - **LM Studio**(`lmstudio`, `~/.lmstudio/mcp.json`) 및 VS Code Desktop용 **Roo Code**(`roo`, `rooveterinaryinc.roo-cline/settings/mcp_settings.json`) 설정 타깃 추가.
+  - YAML 파서 강화로 `mcp_servers:` 및 `superpowers:` 선언의 인라인 주석 및 헤더 주석 보존.
+- **데스크톱용 안전한 설정 내보내기 및 종료 코드 무결성**:
+  - `setup --print-config`(`--bun` 지원) 옵션을 추가하여 ChatWise, Cherry Studio 등 데스크톱 클라이언트에서 부작용 없이 임포트할 수 있는 JSON 출력.
+  - `src/server.ts`의 setup 위임 처리에서 `process.exitCode`를 보존하여 비정상 종료 코드가 0으로 덮어씌워지지 않도록 수정.
+- **데스크톱 설정 가이드**:
+  - LM Studio, Roo Code, ChatWise, Cherry Studio의 상세 설정 지침을 담은 [`docs/desktop-setup.md`](docs/desktop-setup.md) 추가.
+
+### v6.3.8
 
 - **실행 가능한 대화형 워크플로 런처**:
   - `feature-pipeline`과 `structured-debug`는 단계별 명시적 `read_skill` 호출을 제공하고, 필수 사용자 승인 게이트를 유지하며, MCP 서버 내부가 아닌 클라이언트 Agent가 실행한다는 점을 명확히 밝힙니다.
@@ -200,47 +236,6 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 - **전체 자동 회귀 테스트 기준선**:
   - 테스트 스위트를 **274개 자동 어서션**(Node.js: 145, Bash: 35, PowerShell: 94)으로 확장하고 100% 통과율 유지.
 
-### v6.3.7
-
-- **업스트림 동기화 — 배치 1~3 (obra/superpowers)**:
-  - **스킬 자동 라우팅**: `systematic-debugging`과 `test-driven-development` 설명에 트리거 문구(`"tdd"`, `"systematic debug"` 등)와 상호 크로스 라우트를 추가하여 MCP 클라이언트의 스킬 선택 정확도를 향상.
-  - **테스트 명령이 없을 때의 증거 규율**: `verification-before-completion`에 "When There Is No Test Command" 섹션 추가. 보고서, 연구, 감사, 서신 작업은 산출물을 다시 열어 증명 가능한 것을 증명하고 미완료 항목을 명시해야 하며, "완전함"만 주장할 수 있고 "정확함"은 주장할 수 없음.
-  - **브레인스토밍 의도 게이트**: "Establish Shared Understanding"(의도 탐색 → 이해 되쓰기 → 설계 반영) 신설 및 HARD-GATE를 경로별 전제 조건 목록으로 재작성. 한 번의 승인을 나머지 단계 생략 허가로 해석하는 것을 금지.
-  - **플래닝 핸드오프 리뷰**: brainstorming의 스펙 셀프 리뷰를 0.0–9.9 평가 + burden ledger + 단일 유계 개선 패스 + 읽기 전용 재평가로 승격. 실패 시 초안을 복원하는 안전 규칙 포함.
-  - **저장된 계획 검토 및 상황별 핸드오프**: `writing-plans`는 실행 전에 사람이 저장된 계획을 검토하도록 요구하며, 실행 방식이 지정되지 않은 경우 고정 기본값 대신 이 계획에 맞는 추천을 제시.
-  - **계획 체크박스 기록**: `executing-plans`와 `subagent-driven-development`가 완료 메시지와 동시에 계획 파일의 단계를 체크.
-  - **원격 안전 경계**: `using-git-worktrees`는 공유 ref에서 분기할 때 `--no-track`을 필수로 요구하고 `git branch -vv` 추적 점검(첫 커밋 전 `--unset-upstream`)을 수행한다. `executing-plans`는 커밋을 로컬로 유지하고 공유 브랜치 재작성을 금지하며, implementer는 작업 중 push 요구를 BLOCKED로 컨트롤러에 보고한다.
-  - **Discoveries 원장**: SDD 진행 원장에 `## Discoveries` 섹션을 추가하여 태스크 간 발견이 compaction을 넘어 다음 디스패치의 인터페이스 조항으로 이어진다.
-  - **보류 발견 내보내기**: 플랜 워크스페이스 삭제 전에 `Ruling:`／`minor (deferred)`／`parked` 줄을 PR의 "Deferred items" 체크리스트 또는 커밋된 `docs/superpowers/follow-ups/<plan>.md`로 내보낸다.
-  - **Greenfield SDD 스크립트**: 리포지토리가 아직 없으면 `sdd-workspace`가 현재 디렉터리로 폴백하고(`.ps1` 동일), `review-package`는 비리포지토리 환경에서 실행 가능한 오류를 반환한다.
-  - **TDD 특성화 가드**: 동작 보존 리팩터링을 위한 5단계 절차(변이 → 실패 확인 → VCS 복원 → 그린 유지)를 추가하고 경계·변이 점검 섹션에서 상호 참조한다.
-- **업스트림 콘텐츠 동기화 — 배치 4**: brainstorm 시작 스크립트가 `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST`에서 호스트 기본값을 가져오고(`--host`/`--url-host` 우선), `writing-skills`에 콘텐츠 이동 시 링크 재해석 절차를 추가했으며, SDD 리뷰어가 전체 보고서를 `…/task-N-review.md`에 쓰고 15줄 미만 요약만 반환합니다 — MCP에 `review_file` 인자(요청 경로가 정규화 후 보고서나 brief 파일과 일치하면 파생된 `-review.md`로 대체)와 `[FIX_BASE_SHA]`를 실제로 치환하는 `fix_base_sha` 별칭을 추가.
-- **업스트림 드리프트 리포트**: `npm run drift`가 커밋된 베이스라인과 `obra/superpowers`를 비교해 채택된 파일 변경, 로컬에 없는 가져오기, 포크 전용 추가를 나열합니다. `npm run drift:record -- --ignore <skill>`로 검토된 동기화 후 갱신하며, 쓰기 전에 잘린 API tree를 거부합니다.
-- **MCP 표면 커버리지 테스트**: 디스크의 모든 스킬은 자신의 콘텐츠를 제공하는 MCP 리소스로 노출되어야 하며, 프롬프트 목록은 4개 README와 정확히 일치해야 합니다.
-- **MCP 설명 정합성**: 업스트림의 이스케이프 따옴표 형식을 인용 없는 YAML plain scalar로 적응하여 `SkillsManager`가 MCP로 리터럴 백슬래시를 내보내지 않도록 함.
-- **회귀 가드**: `tests/upstream_sync_test.js`를 배치 1~4를 포괄하는 22개 라벨 체크로 확장. 전체 스위트 통과(npm 8개 스위트 139개 체크, PowerShell 90개 어서션, SDD 16 + 호스트 기본 11 + render-graph 8개 bash 어서션).
-- **릴리스 준비 강화**: Bash와 PowerShell brainstorm host 테스트가 background 모드를 명시적으로 강제하여 전체 264개 검증이 `CODEX_CI=1`에서도 완료됩니다. `package-lock.json`을 v6.3.7 및 Node `>=18`과 동기화하고 npm repository와 CLI `bin` 메타데이터를 정규화했으며, `npm publish --dry-run`과 패키지 설치 smoke test로 검증했습니다.
-
-### v6.3.6
-
-- **극한의 성능 최적화 (2배~8.1배 가속)**:
-  - **스킬 병렬 인덱싱 및 사전 캐싱**: `SkillsManager.listSkills`를 비동기 병렬 디렉토리 탐색(`Promise.all`)과 루트 경로 사전 확인 캐싱으로 업그레이드하여 콜드 스타트 인덱싱 지연 시간을 4.79ms에서 2.35ms로 단축(**2.04배 속도 향상**).
-  - **초고속 인메모리 Canonical 캐시**: `readSkillContent`에 물리 실제 경로 기반 Canonical 캐시 및 별칭 매핑을 도입하여 동일 스킬의 반복 읽기 시간을 0.013ms에서 1.6µs로 단축(**8.1배 속도 향상**).
-  - **Frontmatter 슬라이싱 및 ReDoS 방어**: `parseFrontmatter`에서 전체 파일 정규식 스캔을 64 KB 접두사 버퍼 슬라이싱으로 대체하여 대용량 파일에서의 GC 일시 중단 및 2차 ReDoS 위험을 원천 차단.
-  - **JSON 파싱 초고속 직통 경로**: `stripJsonComments` (`src/setup-runner.ts`)에 네이티브 JSON 파싱 시도를 도입하여 주석 없는 설정 파일 읽기 속도를 0.55µs로 단축(**5.1배 속도 향상**).
-  - **멀티 타깃 병렬 번들러**: `esbuild.js`에서 4개 독립 결과물을 `Promise.all`로 병렬 빌드하여 빌드 시간을 ~50ms로 단축(**~42% 속도 향상**).
-- **듀얼 Subagent 심층 코드 리뷰 및 결함 전면 보강 (FIX ALL)**:
-  - **Partial-Read 버퍼 잘림 방어**: `SkillsManager.readFileNoFollow`에 누적 읽기 루프(`while (totalRead < fileSize)`)를 구현하여 높은 디스크 I/O 또는 가상 파일 시스템 환경에서의 무음 Markdown 잘림 방지.
-  - **Scan Epoch 동시성 경쟁 쉴드**: `listSkills`에 단조 증가 `scanEpoch` 카운터를 도입하여 비동기 백그라운드 스캔이 최신 캐시 상태를 덮어쓰는 경쟁 조건 제거.
-  - **Canonical 캐시 정합성 보장**: 물리 실제 경로(`realFilePath`)를 마스터 키로 사용하고 `canonicalPathMap`으로 별칭을 추적하여 강제 리로드 시 심볼릭 링크 캐시 드리프트(Cache Drift) 완벽 해결.
-  - **시스템 디렉토리 블랙리스트 확장**: `getSafeSkillsPath`에 macOS 고유의 `/private/etc` 및 `/private/var`를 추가하여 특권 디렉토리 경로 탈출 공격 방지.
-  - **설정 파일 쓰기 시 심볼릭 링크 대상 검증**: `safeWriteConfig`에서 `fs.lstat` 및 실제 경로 해석을 수행하여 민감한 시스템 영역을 가리키는 심볼릭 링크 쓰기 차단.
-  - **엄격한 TypeScript 및 Rule 7 무결점 준수**: 미사용 사장 코드(`exists`)를 완전히 제거하여 `--noUnusedLocals --noUnusedParameters` 통과, 모든 타입 미지정/빈 catch 블록 제거.
-- **자동화 회귀 테스트 스위트 확장 및 검증**:
-  - 85개 핵심 단위/통합 테스트 및 174개 회귀 어서션 100% 통과(`setup_test.js` 33개 테스트 전체 통과). [`SECURITY.md`](SECURITY.md), [`tests/code_review_report.md`](tests/code_review_report.md), 그리고 [`tests/performance_optimization_report.md`](tests/performance_optimization_report.md) 정비.
-- **다국어 문서 동기화**:
-  - 모든 언어의 README([`README.md`](README.md), [`README.zh-TW.md`](README.zh-TW.md), [`README.ja.md`](README.ja.md), [`README.ko.md`](README.ko.md))에서 지원 환경 목록, 성능 지표, 원클릭 명령 표 동기화.
-
 👉 *이전 버전의 전체 릴리스 내역은 [CHANGELOG.md](CHANGELOG.md)를 참조하세요.*
 
 ---

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.10-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 This document summarizes the information and usage instructions for packaging the Superpowers skills and autonomous workflow system into an independent, high-performance, and secure **Model Context Protocol (MCP)** server.
@@ -43,6 +43,8 @@ To get up and running with Superpowers instantly without intrusive background mo
 > [!NOTE]
 > **Run From Any Directory**: You do NOT need to clone this repository or navigate to a specific folder. You can execute these commands directly from **any directory** in your terminal. The installer automatically targets global configuration files rooted in your user home directory (`~`), instantly enabling Superpowers across all your workspaces.
 
+Desktop quick setup: [LM Studio, Roo Code, ChatWise and Cherry Studio](docs/desktop-setup.md). New CLI options below are unreleased; use the local commands in the guide until the next npm release.
+
 > [!TIP]
 > **Transparency & Zero-Pollution Principle**: Superpowers will NEVER silently scan or bulk-modify unselected editors like adware. You explicitly choose the client you use, ensuring 100% transparent and safe modification via **atomic write swap** (zero crash risk, **zero disk pollution by default** without dumping `.bak` files, zero impact on your existing MCP servers).
 
@@ -52,6 +54,8 @@ Select your client and run the corresponding command in your terminal:
 
 | Harness / Client | Supported OS | One-Click Setup Command | Global Config Location |
 | :--- | :--- | :--- | :--- |
+| **LM Studio** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target lmstudio` | `~/.lmstudio/mcp.json` |
+| **Roo Code (VS Code Desktop)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target roo` | `.../rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
 | **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
 | **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
 | **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
@@ -174,7 +178,39 @@ To help you choose the right skill, we have structured all 14 skills across the
 
 ## 🆕 Recent Updates
 
-### v6.3.8 (Latest)
+### v6.3.10 (Latest)
+
+- **Universal Setup Key Conflict Resolution & Lossless Field Preservation**:
+  - Automatically discovers existing declarations across recognized server keys (`servers`, `mcp`, `mcpServers`), preventing duplicate conflicting configurations.
+  - Safely merges and preserves user-authored configuration fields (`env`, `cwd`, `disabled`, `alwaysAllow`, `args`) on re-installation.
+  - Eliminates contradictory states between opposing flags (`disabled: true` vs `enabled: true`).
+  - Rejects unknown flags and unexpected positional CLI arguments with exit code 1; standardizes on `process.exitCode` for non-truncating output over Unix pipes.
+- **Skills Core Engine Fast-Path Cache Stat Verification & Scan Epoch Shielding**:
+  - Implements fast-path single-stat verification (`dev`, `ino`, `size`, `mtimeMs`) on cached skill paths, immediately invalidating stale cache if symlinks redirect without rescanning the whole tree.
+  - Advancing monotonic `scanEpoch` and resetting `loadingEpoch` on `clearCache()` prevents pending async directory scans from repopulating flushed caches.
+  - Authoritative open file descriptor verification (`readFileNoFollow`) prevents TOCTOU descriptor swaps.
+- **MCP Prompt Template Robustness & Deduplication**:
+  - Halts with `McpError(ErrorCode.InternalError)` and structured stderr diagnostic when prompt template files are missing or empty.
+  - Tracks applied template substitutions via `appliedInterpolations`, preventing redundant argument appending.
+- **Comprehensive Security Audit & Automated Regression Floor**:
+  - 100% verified across **292 automated test assertions** (Node.js 163, Bash 35, PowerShell 94), 0 vulnerabilities, 0 hardcoded secrets.
+
+### v6.3.9
+
+- **Permanent ReDoS Defense (CodeQL Alert #4 Resolved)**:
+  - Replaced ambiguous regex backtracking in YAML parsing (`updateYamlConfig`) with unambiguous prefix key matching and native `String.prototype.trim()`.
+  - Added `extractInlineComment` linear scan ($O(N)$), preventing polynomial backtracking on inputs padded with long whitespace runs. Formally closed CodeQL Alert #4 (`js/polynomial-redos`).
+  - Added regression test suite in `tests/setup_test.js` validating linear processing (<1ms) against 60,000 whitespace characters.
+- **Client Setup Expansion (17 Supported AI Agent Clients)**:
+  - Added setup targets for **LM Studio** (`lmstudio`, `~/.lmstudio/mcp.json`) and **Roo Code** in VS Code Desktop (`roo`, `rooveterinaryinc.roo-cline/settings/mcp_settings.json`) across macOS, Windows, and Linux.
+  - Enhanced YAML configuration parser to preserve inline comments on `mcp_servers:` and `superpowers:`.
+- **Desktop Import Tooling & Delegation Exit Code Integrity**:
+  - Added `setup --print-config` (optional `--bun`) to output clean MCP JSON for desktop client import (ChatWise, Cherry Studio, etc.) without writing files.
+  - Hardened `src/server.ts` setup delegation to preserve `process.exitCode` from CLI commands.
+- **Desktop Setup Guide**:
+  - Added comprehensive [`docs/desktop-setup.md`](docs/desktop-setup.md) covering LM Studio, Roo Code, ChatWise, and Cherry Studio setup.
+
+### v6.3.8
 
 - **Actionable Interactive Workflow Launchers**:
   - `feature-pipeline` and `structured-debug` now emit explicit stage-by-stage `read_skill` calls, preserve required user approval gates, and clearly state that execution happens through the client agent rather than inside the MCP server.
@@ -201,47 +237,6 @@ To help you choose the right skill, we have structured all 14 skills across the
 - **Automated Regression Verification Floor**:
   - Expanded test suite to **274 automated test assertions** across Node.js (145), Bash (35), and PowerShell (94) with a 100% pass rate.
 
-### v6.3.7
-
-- **Upstream Sync — Batches 1–3 (obra/superpowers)**:
-  - **Automatic Skill Routing**: `systematic-debugging` and `test-driven-development` descriptions now name their typed trigger phrases (`"tdd"`, `"systematic debug"`, …) and cross-route to the sibling skill, improving skill selection inside MCP clients.
-  - **Evidence Without a Test Command**: `verification-before-completion` gains the "When There Is No Test Command" section — for reports, research, audits, and correspondence, re-open the artifact, prove what can be proven, and account for every part of the request while claiming *complete*, never *right*.
-  - **Brainstorming Intent Gates**: new "Establish Shared Understanding" step (discover intent, write back your understanding, carry it into the design) plus a rewritten HARD-GATE that lists each path's prerequisites and refuses to treat one approval as permission to skip the rest.
-  - **Planning-Handoff Review**: brainstorming's spec self-review becomes a scored handoff review (0.0–9.9 readiness, burden ledger, one bounded improvement pass, read-only reassessment) with a fail-safe restore rule.
-  - **Saved-Plan Review & Contextual Handoff**: `writing-plans` now requires the human to review the saved plan before execution and, when no method was supplied, a plan-specific execution recommendation instead of a hardcoded default.
-  - **Plan Checkbox Bookkeeping**: `executing-plans` and `subagent-driven-development` tick the plan file's steps in the same message as the completion bookkeeping.
-  - **Remote-Safety Boundary**: `using-git-worktrees` requires `--no-track` plus a `git branch -vv` tracking check (`--unset-upstream` before the first commit); `executing-plans` keeps commits local and forbids rewriting shared branches; implementers report any mid-task push demand as BLOCKED instead of pushing.
-  - **Discoveries Ledger**: SDD's progress ledger gains a `## Discoveries` section so cross-task findings survive compaction and feed the next dispatch's interface clauses.
-  - **Deferred Findings Export**: before a plan workspace is deleted, `Ruling:` / `minor (deferred)` / `parked` lines are exported to a PR "Deferred items" checklist or a committed `docs/superpowers/follow-ups/<plan>.md`.
-  - **Greenfield SDD Scripts**: `sdd-workspace` falls back to the current directory before a repo exists (matching `.ps1` behavior), while `review-package` refuses actionably outside a repo.
-  - **TDD Characterization Guard**: a five-step procedure for behavior-preserving refactors — mutate, verify failure, restore via VCS, stay green — referenced from the boundary and mutation-check sections.
-- **Upstream Content Sync — Batch 4**: the brainstorm start script takes its hosts from `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST` (`--host`/`--url-host` still win), `writing-skills` gained moved-content link re-resolution, and SDD reviewers now write their full report to `…/task-N-review.md` and return under 15 lines — exposed over MCP as the new `review_file` argument (replaced by the derived `-review.md` sibling when the requested path normalises to the report or brief file), plus the `fix_base_sha` alias that finally feeds `[FIX_BASE_SHA]`.
-- **Upstream Drift Report**: `npm run drift` compares the committed upstream baseline against `obra/superpowers` and lists adopted files that moved, imports missing locally, and fork-only additions; `npm run drift:record -- --ignore <skill>` refreshes it after a reviewed sync and refuses truncated API trees before writing.
-- **MCP Surface Coverage Test**: every skill on disk must be an exposed MCP resource serving its own content, and the prompt inventory must match all four READMEs exactly.
-- **MCP Description Fidelity**: upstream's escaped-quote descriptions were adapted to unquoted YAML plain scalars so the `SkillsManager` parser never emits literal backslashes over MCP.
-- **Regression Guards**: `tests/upstream_sync_test.js` now carries 22 labeled checks covering Batches 1–4; full suite green (139 npm checkmarks across 8 suites, 90 PowerShell assertions, 16 SDD + 11 host-default + 8 render-graph bash assertions).
-- **Release-Readiness Hardening**: Bash and PowerShell brainstorm host tests explicitly force background mode, so the full 264-assertion matrix also completes under `CODEX_CI=1`; `package-lock.json` now matches v6.3.7 and Node `>=18`; npm repository and CLI `bin` metadata are normalized and verified through `npm publish --dry-run` plus a packed-install smoke test.
-
-### v6.3.6
-
-- **Extreme Performance Optimization (2x~8.1x Speedup)**:
-  - **Parallel Skill Discovery**: Upgraded `SkillsManager.listSkills` to concurrent asynchronous directory traversal (`Promise.all`) combined with pre-resolved root path caching, cutting cold-start skill indexing latency from 4.79ms to 2.35ms (**2.04x speedup**).
-  - **High-Velocity In-Memory Canonical Caching**: Introduced canonical realpath-keyed caching with aliasing for `readSkillContent`, dropping repeated skill reads from 0.013ms to 1.6µs (**8.1x speedup**).
-  - **Frontmatter Slicing & ReDoS Defense**: Replaced full-document regular expression scans in `parseFrontmatter` with targeted 64 KB prefix buffer slices, eliminating GC pauses and quadratic ReDoS risks on large skill files.
-  - **JSON Parsing Fast-Path**: Implemented native JSON trial in `stripJsonComments` (`src/setup-runner.ts`), accelerating non-commented JSON configuration reads to 0.55µs (**5.1x speedup**).
-  - **Parallel Multi-Target Bundler**: Replaced sequential builds in `esbuild.js` with `Promise.all` across 4 build targets, reducing build time to ~50ms (**~42% speedup**).
-- **Dual-Subagent Code Review & Comprehensive Quality Hardening (FIX ALL)**:
-  - **Partial-Read Buffer Truncation Defense**: Implemented an accumulator loop (`while (totalRead < fileSize)`) in `SkillsManager.readFileNoFollow`, ensuring full buffer delivery under high disk concurrency and slow storage systems.
-  - **Scan Epoch Concurrency Shield**: Added a monotonic `scanEpoch` counter in `listSkills` to prevent out-of-order asynchronous reloads from clobbering updated skill catalogs.
-  - **Canonical Path Cache Invalidation**: Unified cache indexing on physical canonical paths (`realFilePath`) and linked aliases in `canonicalPathMap`, completely eliminating symlink cache drift during force reloads.
-  - **System Blacklist Expansion**: Added macOS `/private/etc` and `/private/var` into `getSafeSkillsPath`, guarding against privilege directory pointer attacks.
-  - **Symlink Target Defense in Configuration Writes**: `safeWriteConfig` verifies `fs.lstat` and realpaths before writes, blocking symlinks pointing to sensitive system locations.
-  - **Strict TypeScript & Rule 7 Zero-Defect Compliance**: Cleaned up unused dead code (`exists`), enforced clean compilation under `--noUnusedLocals --noUnusedParameters`, and eliminated all unhandled or untyped empty catch blocks.
-- **Automated Regression Suite Expansion**:
-  - All 85 core unit/integration tests and 174 regression assertions passing at 100% across all suites (`edge_cases_test.js`, `run_test.js`, `brainstorm_server_test.js`, `prompts_compositions_test.js`, and `setup_test.js` with 33 passed tests). Refreshed [`SECURITY.md`](SECURITY.md), [`tests/code_review_report.md`](tests/code_review_report.md), and [`tests/performance_optimization_report.md`](tests/performance_optimization_report.md).
-- **Multilingual Documentation Alignment**:
-  - Synchronized supported harness directories, performance metrics, and one-click commands across all 4 localized READMEs ([`README.md`](README.md), [`README.zh-TW.md`](README.zh-TW.md), [`README.ja.md`](README.ja.md), [`README.ko.md`](README.ko.md)).
-
 👉 *For the complete release history, see [CHANGELOG.md](CHANGELOG.md).*
 
 ---

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![版本](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.10-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 **Model Context Protocol (MCP)** 伺服器之相關資訊與使用說明。
@@ -43,6 +43,8 @@
 > [!NOTE]
 > **可在系統任何目錄下直接執行**：您不需要預先切換到特定專案目錄，也無須 clone 本儲存庫。在終端機的**任意目錄**皆可直接執行以下指令！安裝程式會自動鎖定您系統中的全域設定檔（以使用者家目錄為基準），一次設定、全域與所有專案皆可自動生效。
 
+桌面版快速安裝：[LM Studio、Roo Code、ChatWise 與 Cherry Studio](docs/desktop-setup.md)。以下新增的 CLI 選項尚未發布至 npm；發布前請使用指南中的本機指令。
+
 > [!TIP]
 > **透明與零污染保護原則**：Superpowers 絕不會像惡意軟體般擅自全域掃描或批量改寫您未指定的其他編輯器。您使用哪一款 AI 工具，就執行該工具的專屬一鍵指令，完全透明、可控且安全無損（採用**原子寫入技術**，保證斷電不壞檔，且**預設零磁碟垃圾殘留**，不隨意產生 `.bak`，亦絕不影響原有其他 MCP 伺服器）。
 
@@ -52,6 +54,8 @@
 
 | Harness / 客戶端 | 支援 OS | 專屬一鍵設定指令 | 全域設定檔路徑 |
 | :--- | :--- | :--- | :--- |
+| **LM Studio** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target lmstudio` | `~/.lmstudio/mcp.json` |
+| **Roo Code (VS Code Desktop)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target roo` | `.../rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
 | **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
 | **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
 | **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
@@ -173,7 +177,39 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 最近更新
 
-### v6.3.8 (最新版)
+### v6.3.10 (最新版)
+
+- **全域安裝引擎鍵名衝突化解與使用者設定無損保留**：
+  - 自動探索既有的 `servers`、`mcp`、`mcpServers`，防止在不同 AI Client 環境中重複建立互相矛盾的設定區塊。
+  - 重新執行安裝時自動合併並無損保留使用者自訂的 `env`、`cwd`、`disabled`、`alwaysAllow` 等欄位。
+  - 徹底消除 `disabled: true` 與 `enabled: true` 同時並存的矛盾無效狀態。
+  - 嚴格校驗命令列引數，拒絕未預期的位置參數（結束碼 1）；全面以 `process.exitCode` 取代突兀退出，確保非同步串流完整沖刷。
+- **核心技能引擎單次 Stat 快照校驗與世代隔離**：
+  - 引入單次 `fs.stat` 快照校驗 (`dev`, `ino`, `size`, `mtimeMs`)，若符號連結或實體檔案遭置換立即失效快取，無需重新遍歷整個目錄。
+  - `clearCache()` 採用單調遞增的 `scanEpoch` 並重設 `loadingEpoch`，杜絕慢速異步掃描在快取重設後的髒覆寫。
+  - 權威描述元 Inode 校驗 (`readFileNoFollow`) 消除 TOCTOU 描述元置換競態。
+- **MCP Prompt 模板健壯性與去重機制**：
+  - 遇到空白或遺失模板時主動輸出結構化 `stderr` 並拋出標準 `McpError(ErrorCode.InternalError)`。
+  - 以 `appliedInterpolations` 追蹤已替換標記，防止多餘參數重複追加。
+- **全方位安全審計與回歸測試底線**：
+  - 全套件 **292 項自動化測試斷言**（Node.js: 163 項、Bash: 35 項、PowerShell: 94 項）100% 通過，0 漏洞、0 敏感資訊外洩。
+
+### v6.3.9
+
+- **永久 ReDoS 防禦（CodeQL Alert #4 關閉）**：
+  - 將 YAML 解析（`updateYamlConfig`）中的多項式回溯正則改為單一無歧義前綴匹配與原生 `String.prototype.trim()`。
+  - 引入 `extractInlineComment` 線性掃描器（$O(N)$），徹底杜絕長空白填充下的多項式回溯；GitHub CodeQL Alert #4 (`js/polynomial-redos`) 經遠端靜態分析確認正式關閉。
+  - 於 `tests/setup_test.js` 增加 60,000 字元極限空白填充壓力測試，確保線性執行耗時（<1ms）。
+- **目標客戶端生態系擴充（支援 17 款 AI Agent 客戶端）**：
+  - 新增 **LM Studio**（`lmstudio`，指向 `~/.lmstudio/mcp.json`）與 VS Code 桌面版 **Roo Code**（`roo`，指向 `rooveterinaryinc.roo-cline/settings/mcp_settings.json`）跨平台安裝目標。
+  - 增強 YAML 解析器，在更新與移除流程中完美保留 `mcp_servers:` 與 `superpowers:` 宣告的行內註解與檔案標頭註解。
+- **桌面端安全匯入工具與退出碼完整性**：
+  - 提供 `setup --print-config`（支援 `--bun`）輸出純淨 MCP JSON 設定，方便 ChatWise、Cherry Studio 等桌面客戶端無副作用匯入。
+  - 修正 `src/server.ts` setup 命令轉發機制，完整繼承 CLI 返回之 `process.exitCode`。
+- **桌面整合指南**：
+  - 新增完整文件 [`docs/desktop-setup.md`](docs/desktop-setup.md)，涵蓋 LM Studio、Roo Code、ChatWise 與 Cherry Studio 步驟指引。
+
+### v6.3.8
 
 - **可執行的互動式工作流啟動器**：
   - `feature-pipeline` 與 `structured-debug` 會逐階段給出明確的 `read_skill` 呼叫，保留必要的使用者核准關卡，並清楚說明流程由客戶端 Agent 執行，不是 MCP 伺服器內部自動執行。
@@ -200,47 +236,6 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 - **全自動化回歸測試底線**：
   - 擴展測試套件至 **274 項自動化斷言全數通過**（Node.js: 145 項、Bash: 35 項、PowerShell: 94 項），維持 100% 通過率。
 
-### v6.3.7
-
-- **上游同步 — 第 1–3 批（obra/superpowers）**：
-  - **技能自動路由**：`systematic-debugging` 與 `test-driven-development` 的 description 新增觸發詞（`"tdd"`、`"systematic debug"` 等）與兄弟技能交叉導引，提升 MCP 客戶端的技能選擇準確度。
-  - **無測試指令的證據律**：`verification-before-completion` 新增「When There Is No Test Command」章節：報告、研究、稽核與書信類工作必須重新開啟成品、逐項證明並誠實列出未完成項，只能宣稱「完整」而非「正確」。
-  - **Brainstorming 意圖閘門**：新增「Establish Shared Understanding」（探索意圖 → 回寫理解 → 帶入設計），並重寫 HARD-GATE 明列各路徑前置條件，禁止把單次核准當成跳過後續階段的許可。
-  - **規劃交接審查（Planning-Handoff Review）**：brainstorming 的規格自我審查升級為 0.0–9.9 評分 + burden ledger + 單次有界改進 + 唯讀複評，並具備失敗時還原初稿的保底規則。
-  - **已存計畫審閱與情境化交接**：`writing-plans` 要求人類先審閱存檔計畫才可執行；未指定執行方式時必須給出針對本計畫的推薦，而非固定預設。
-  - **計畫勾選簿記**：`executing-plans` 與 `subagent-driven-development` 在完成訊息中同步勾選計畫檔步驟。
-  - **遠端安全邊界**：`using-git-worktrees` 要求從共享 ref 開分支時必須加 `--no-track`，並以 `git branch -vv` 檢查追蹤狀態（首次 commit 前先 `--unset-upstream`）；`executing-plans` 要求 commit 保持本地、禁止改寫共享分支；implementer 遇到任何 push 需求一律回報 BLOCKED，不得自行推送。
-  - **Discoveries 帳本**：SDD 進度帳本新增 `## Discoveries` 區段，跨任務發現可穿越 compaction，並成為下一次派工介面條款的來源。
-  - **延後發現匯出**：刪除計畫工作區前，`Ruling:`／`minor (deferred)`／`parked` 行必須匯出到 PR 的「Deferred items」清單，或提交至 `docs/superpowers/follow-ups/<plan>.md`。
-  - **Greenfield SDD Scripts**：repo 尚未建立時 `sdd-workspace` 退回當前目錄（`.ps1` 同步支援），`review-package` 則在非 repo 環境下給出可行動的錯誤。
-  - **TDD 特徵化守門**：行為保持型重構的五步程序（先變異、確認失敗、由 VCS 還原、維持綠燈），並從邊界與變異檢查章節交叉引用。
-- **上游內容同步 — 第 4 批**：brainstorm 啟動腳本改由 `BRAINSTORM_HOST`/`BRAINSTORM_URL_HOST` 決定 host（`--host`/`--url-host` 仍優先）、`writing-skills` 新增搬移內容時的連結重解指引，SDD 審查者改為把完整報告寫入 `…/task-N-review.md` 並只回傳少於 15 行摘要 — MCP 端新增 `review_file` 參數（若要求的路徑正規化後等於報告或 brief 檔，改用推導出的 `-review.md`），以及讓 `[FIX_BASE_SHA]` 真正被代入的 `fix_base_sha` 別名。
-- **上游 drift 報告**：`npm run drift` 以已提交的上游基線比對 `obra/superpowers`，列出已採納檔案的變動、本地缺漏的引進檔案與 fork 專屬新增；`npm run drift:record -- --ignore <skill>` 於審閱同步後更新基線，且會在寫入前拒絕遭截斷的 API tree。
-- **MCP 表面覆蓋率測試**：磁碟上的每個 skill 都必須是對外曝露、且讀出內容屬於該 skill 的 MCP resource，prompt 清單必須與 4 個 README 完全一致。
-- **MCP 描述保真**：上游的跳脫引號格式改為未加引號的 YAML plain scalar，確保 `SkillsManager` 經 MCP 輸出時不會出現多餘反斜線。
-- **回歸防護**：`tests/upstream_sync_test.js` 增至 22 項標記檢查（涵蓋第 1–4 批）；全測試套件通過（8 個 npm 套件共 139 項檢查、PowerShell 90 項斷言、SDD 16 + host 預設 11 + render-graph 8 項 bash 斷言）。
-- **發佈前強化**：Bash 與 PowerShell 的 brainstorm host 測試明確強制 background 模式，讓完整 264 項驗證在 `CODEX_CI=1` 下也能正常結束；`package-lock.json` 已同步至 v6.3.7 與 Node `>=18`；npm repository 與 CLI `bin` metadata 已正規化，並經 `npm publish --dry-run` 與打包安裝 smoke test 驗證。
-
-### v6.3.6
-
-- **極致效能躍升優化 (2x~8.1x 加速)**：
-  - **並行技能索引與快取前置**：`SkillsManager.listSkills` 升級為非同步並行目錄遍歷 (`Promise.all`) 搭配根目錄預解析快取，冷啟動技能索引延遲由 4.79ms 銳減至 2.35ms（**2.04x 速度提升**）。
-  - **極速記憶體 Canonical 快取**：針對 `readSkillContent` 引入以實體真實路徑為鍵的 Canonical 快取與別名映射機制，二次技能讀取由 0.013ms 驟降至 1.6µs（**8.1x 速度提升**）。
-  - **Frontmatter 切片與 ReDoS 防護**：`parseFrontmatter` 改以 64 KB 前綴緩衝區局部切片取代全檔正則匹配，徹底消除大檔案 GC 停頓與二次方 ReDoS 風險。
-  - **JSON 解析高速直通路徑**：在 `stripJsonComments` (`src/setup-runner.ts`) 引入原生 JSON 嘗試，無註解設定檔讀取速度提升至 0.55µs（**5.1x 速度提升**）。
-  - **並行多目標打包編譯**：`esbuild.js` 採用 `Promise.all` 並行編譯 4 大產物，全專案打包時間降至 ~50ms（**~42% 速度提升**）。
-- **雙子 Subagent 深度 Code Review 與全面缺陷加固 (FIX ALL)**：
-  - **Partial-Read 緩衝區截斷防禦**：`SkillsManager.readFileNoFollow` 實作累加式讀取迴圈（`while (totalRead < fileSize)`），杜絕高併發磁碟 I/O 或虛擬檔案系統下的無聲截斷。
-  - **Scan Epoch 並發版本防護**：`listSkills` 引入遞增的 `scanEpoch` 代數計數器，防止背景慢速掃描覆寫較新的快取狀態。
-  - **Canonical 快取一致性保證**：以實體真實路徑 (`realFilePath`) 為核心鍵值並透過 `canonicalPathMap` 維護別名映射，徹底消除符號連結別名的快取漂移 (Cache Drift)。
-  - **系統黑名單防禦擴展**：`getSafeSkillsPath` 補齊 macOS `/private/etc` 與 `/private/var`，杜絕攻擊者透過環境變數逃逸至敏感系統目錄。
-  - **設定檔寫入符號連結逃逸防禦**：`safeWriteConfig` 在寫入前透過 `fs.lstat` 與真實路徑解析，嚴格拒絕指向敏感系統路徑的符號連結偽造寫入。
-  - **嚴格 TypeScript 與 Rule 7 零瑕疵合規**：徹底清理廢棄死代碼（`exists` 私有方法），全面通過 `--noUnusedLocals --noUnusedParameters`，並消除全專案所有無型別/空白 catch 區塊。
-- **自動化測試套件擴充與基準回歸**：
-  - 全套件 85 項核心單元/端到端測試與 174 項回歸斷言 100% 通過（包含 `setup_test.js` 33 項測試全部通過），並產出 [`SECURITY.md`](SECURITY.md)、[`tests/code_review_report.md`](tests/code_review_report.md) 與 [`tests/performance_optimization_report.md`](tests/performance_optimization_report.md)。
-- **多語系文檔全面對齊**：
-  - 4 語系 README（[`README.md`](README.md)、[`README.zh-TW.md`](README.zh-TW.md)、[`README.ja.md`](README.ja.md)、[`README.ko.md`](README.ko.md)）同步支援環境清單、效能指標與一鍵指令表格。
-
 👉 *更多歷史版本更新紀錄，請參閱完整的 [CHANGELOG.md](CHANGELOG.md)。*
 
 ---

package/docs/desktop-setup.md

@@ -0,0 +1,86 @@
+# Desktop quick setup / 桌面版快速安裝
+
+The new `lmstudio`, `roo` and `--print-config` options are unreleased. Until the next npm release, run from a checkout:
+
+```bash
+npm ci
+npm run build
+node out/setup.js --target lmstudio
+# Or choose Roo Code in VS Code Desktop:
+node out/setup.js --target roo
+# Or print JSON to import into a desktop app:
+node out/setup.js --print-config
+```
+
+目前新增選項尚未發布至 npm。發布前請使用上方本機指令；設定中的 MCP 伺服器仍透過 npm 啟動已發布版本。
+
+Install Node.js with npm first and restart the desktop app after saving its configuration. If a GUI cannot find `npx`, use its absolute executable path in the app's MCP configuration (`command -v npx` on macOS/Linux; `where.exe npx` on Windows). This installs the Superpowers MCP connection, not the desktop application. Tool execution also depends on the model and the client's available capabilities.
+
+## File-based desktop setup
+
+After the next npm release:
+
+```bash
+npx -y superpowers-mcp setup --target lmstudio
+npx -y superpowers-mcp setup --target roo
+```
+
+Run only the command for the client you want. Both targets support `--dry-run`, `--backup`, `--bun` and `--remove`. `lm-studio` aliases `lmstudio`; `roo-code` and `roocode` alias `roo`.
+
+| Client | Configuration location |
+| --- | --- |
+| LM Studio, all three OSes | User home + `.lmstudio/mcp.json` |
+| Roo Code, macOS | `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
+| Roo Code, Windows | `%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
+| Roo Code, Linux | `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` |
+
+Roo setup targets the standard VS Code Desktop profile. For Insiders, portable builds, remote VS Code or a custom storage location, open Roo's **Edit Global MCP** configuration and merge the JSON below into its existing `mcpServers` object.
+
+LM Studio: open **Program → Install → Edit mcp.json** to inspect the configuration, then enable the integration for your chat. Select a model that supports tool use.
+
+## ChatWise and Cherry Studio
+
+Copy this complete JSON, or generate it with `node out/setup.js --print-config` (`--bun` selects `bunx`). After release, the equivalent command is `npx -y superpowers-mcp setup --print-config`.
+
+```json
+{
+  "mcpServers": {
+    "superpowers": {
+      "command": "npx",
+      "args": ["-y", "superpowers-mcp"]
+    }
+  }
+}
+```
+
+### ChatWise
+
+[Add Superpowers to ChatWise / 一鍵加入 ChatWise](https://chatwise.app/mcp-add?json=eyJtY3BTZXJ2ZXJzIjp7InN1cGVycG93ZXJzIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15Iiwic3VwZXJwb3dlcnMtbWNwIl19fX0%3D)
+
+ChatWise must already be installed. Alternatively, copy the JSON, open **Settings → Tools → + → Import JSON from Clipboard**, then enable tools for the chat. Use the MCP Tools chat workflow: ChatWise's current Agent preview documents MCP as disabled in that mode.
+
+先安裝 ChatWise，再點上方連結；也可以在 Tools 設定從剪貼簿匯入 JSON，並在對話開啟工具。請使用支援 MCP Tools 的對話模式，目前 Agent 預覽模式不支援 MCP。
+
+### Cherry Studio
+
+Open **Settings → MCP → MCP Servers → Add → Import from JSON**, paste the JSON, save and enable the server. If using manual creation, choose **stdio**, name `superpowers`, command `npx`, and two separate arguments: `-y` and `superpowers-mcp`. Then open **Work → Agent menu → Edit → MCP** and enable this server for the intended Agent.
+
+在「設定 → MCP → MCP 伺服器 → 新增」匯入 JSON，儲存並啟動後，到「工作 → Agent 選單 → 編輯 → MCP」綁定。只加入伺服器、未綁定 Agent 時，Agent 不會取得工具。
+
+## Verify the connection
+
+Ask the assistant: **Use `list_skills` to list the Superpowers skills, then use `read_skill` to read `brainstorming`.** Confirm that actual tool results appear. Prompts and resources vary by client; the tool-based path is the common verification route.
+
+Hermes users can now keep inline comments such as `mcp_servers: # configured servers`; setup also recognizes `superpowers: # my agent` during update and removal.
+
+## References
+
+- [LM Studio MCP configuration and paths](https://lmstudio.ai/blog/lmstudio-v0.3.17)
+- [LM Studio MCP usage](https://lmstudio.ai/docs/app/mcp)
+- [Roo Code MCP configuration](https://roocodeinc.github.io/Roo-Code/features/mcp/using-mcp-in-roo/)
+- [Roo Code storage and configuration migration](https://github.com/RooCodeInc/Roo-Code/issues/8520)
+- [ChatWise JSON import and install links](https://docs.chatwise.app/tools)
+- [ChatWise Agent preview limitations](https://docs.chatwise.app/agent)
+- [Cherry Studio MCP setup and Agent binding](https://docs.cherryai.com.cn/advanced-basic/extensions/mcp)
+
+Paths and import formats were checked against these sources on 2026-09-13. Automated checks exercise configuration generation, preservation and removal; desktop GUI connections have not been tested on physical Windows/Linux installations.