superpowers-mcp 6.3.9 → 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.9-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)** サーバーにパッケージ化した使用説明書です。
@@ -179,7 +179,24 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 最近の更新
 
-### v6.3.9（最新）
+### 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()` に置換。
@@ -221,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.9-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)** 서버로 패키징한 사용 지침을 요약한 것입니다.
@@ -177,7 +177,24 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 최근 업데이트
 
-### v6.3.9 (최신)
+### 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()`으로 대체.
@@ -219,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.9-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.
@@ -178,7 +178,24 @@ To help you choose the right skill, we have structured all 14 skills across the
 
 ## 🆕 Recent Updates
 
-### v6.3.9 (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()`.
@@ -220,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.9-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)** 伺服器之相關資訊與使用說明。
@@ -177,7 +177,24 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ## 🆕 最近更新
 
-### v6.3.9 (最新版)
+### 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()`。
@@ -219,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)。*
 
 ---