superpowers-mcp 6.3.7 → 6.3.8

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.7-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![バージョン](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 このドキュメントは、Superpowers スキルライブラリと自律型ワークフローを、独立した高パフォーマンスかつ安全な **Model Context Protocol (MCP)** サーバーにパッケージ化した使用説明書です。
@@ -23,11 +23,11 @@
 | :--- | :--- | :--- |
 | **Tools** | `list_skills`, `read_skill` | 14 種類の Superpowers スキルをオンデマンドで検索・読み込み。 |
 | **Prompts** | 9 個のネイティブ Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
-| **Resources** | 14 個の Direct URI | `skill://superpowers/<skill-name>` (MCP 規格に準拠した直接アクセス) |
+| **Resources** | 14 個の Skill URI + 1 ガイド | `skill://superpowers/<skill-name>` と `guide://superpowers/skill-compositions` |
 
 ### AI エージェントとの対話（基本操作）
 
-インストールまたは設定が完了すると、AI エージェントが自動的に `Superpowers Skills` および `Prompts` を認識して呼び出せるようになります。
+インストールまたは設定後、MCP クライアントは Superpowers の tools、prompts、resources を検出できます。MCP prompt はユーザーが選択して起動し、その後エージェントが指示に従って `read_skill` を呼び出します。
 
 **基本的な対話例：**
 - **エンジニアリング規律の初期化**：「`session-start` プロンプトを適用して」（Superpowers のルールとコンテキストを注入）
@@ -125,24 +125,24 @@
 
 ## 🔄 スキル構成 & ワークフローパイプライン (Skill Compositions & Pipelines)
 
-複数ステップの複雑なタスクを実行する際は、以下の**ワンクリック・エンドツーエンドパイプライン**を使用してください（詳細ガイド：[`docs/skill-compositions.ja.md`](docs/skill-compositions.ja.md)）：
+複数ステップの複雑なタスクには、以下の**対話型ワークフローランチャー**を使用してください。設計、計画レビュー、ブランチ完了時にはユーザーの判断を待つため、サーバー側の無人自動化ではありません（詳細：[`docs/skill-compositions.ja.md`](docs/skill-compositions.ja.md)）。
 
 ### 1. エンドツーエンド新機能開発パイプライン (Feature Development Pipeline)
 ```
 brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **ワンクリック指示：**「`feature-pipeline` を適用して、[機能名] の開発を進めてください」
+- **起動方法：**MCP Prompts メニューから `feature-pipeline` を選択し、必須の `feature_name` と任意の `requirements` を入力します。
 - **特徴：** 要件明確化 (Spec) ➔ 計画分解 (Plan) ➔ Worktree 分離 ➔ 独立サブエージェント＋TDD 実装 ➔ フルテスト検証 ➔ 敵対的コードレビュー ➔ ブランチ完了。
 
 ### 2. 構造化トラブルシューティングパイプライン (Structured Troubleshooting Pipeline)
 ```
 systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **ワンクリック指示：**「`structured-debug` を適用して、次のエラーを調査・修正してください：[エラーログ]」
+- **起動方法：**MCP Prompts メニューから `structured-debug` を選択し、問題または失敗テストを入力します。
 - **特徴：** 根本原因の仮説分解 ➔ Worktree 隔離並行調査 ➔ 複数エージェント検証 ➔ 失敗テスト作成・修正 ➔ 完全な回帰検証 ➔ レビュー指摘解決 ➔ ブランチ完了。
 
 ### 3. 動的ワークフローガイド (Dynamic Workflow Guide)
-- **ワンクリック指示：**「`skill-composition` を適用して、現在の状況 [リファクタリング/移行/レガシーコード保護] の手順を提示してください」
+- **起動方法：**`skill-composition` を選択してリファクタリング、移行、レガシーコード向けの推奨手順を取得します。これらには現在、専用ランチャー prompt はありません。
 - **特徴：** 大規模リファクタリング、レガシーシステムの安全網構築、オンボーディングに最適なパイプラインを動的に提案：
   - **大規模リファクタリング＆移行 (Pipeline 3)：** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
   - **レガシーコード安全網 (Pipeline 4)：** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
@@ -173,21 +173,36 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 
 ---
 
-## 🔧 アップストリームへの追従
-
-この fork は上流 [`obra/superpowers`](https://github.com/obra/superpowers) のスキル内容をレビュー済みバッチで取り込みます。最後の同期時点の上流 blob SHA は [`tests/upstream-sync-baseline.json`](tests/upstream-sync-baseline.json) に記録されています。
-
-```bash
-npm run drift                    # ベースラインと上流を比較し、変更点を一覧表示
-npm run drift:record             # レビュー済み同期の後にベースラインを更新
-node scripts/upstream-drift.js   # オフライン：ベースライン整合性 + ローカル網羅率
-```
-
-レポートは、上流で変更されたファイル、上流の追加・削除、追跡対象だがローカルに無いファイル、fork 独自の追加を分けて表示します。意図的に採用しない上流スキルは drift ではなく「判断待ち」として報告され、`npm run drift:record -- --ignore <skill>` で記録します。取り込み済みの上流ファイルが削除されたり、スキルの上流系譜が失われると `npm test` が失敗します。GitHub tree が途中で切れた場合、レポートモードは結果を部分的と明示して `--fail-on-drift` を抑止し、record モードは書き込み自体を拒否して最後の完全なベースラインを保護します。
-
 ## 🆕 最近の更新
 
-### v6.3.7（最新）
+### v6.3.8（最新）
+
+- **実行可能な対話型ワークフローランチャー**：
+  - `feature-pipeline` と `structured-debug` は、ステージごとに明示的な `read_skill` 呼び出しを示し、必要なユーザー承認ゲートを保持し、実行が MCP サーバー内ではなくクライアント Agent 側で行われることを明記します。
+  - マルチ Agent 対応 Host では Subagent を使い、非対応 Host では利用できない機能を称することなくインラインまたは逐次実行にフォールバックします。
+  - `read_skill` はスキル名単体と、文書化された `superpowers:` プレフィックスの両方を受け付けます。
+  - Skill Compositions ガイドを npm パッケージに含め、`guide://superpowers/skill-compositions` からも参照できます。
+- **ユニバーサルセットアップエンジンの並行安全性・Inode 防御・シンボリックリンク脱出防止**：
+  - **Allowed Roots 境界隔離**：設定の書き込み先を明示的な許可ルート（`homeDir`、`appData`、`localAppData`）内に限定し、親ディレクトリシンボリックリンク経由の脱出攻撃を遮断。
+  - **楽観的並行競合検知**：アトミックな `fs.renameSync` の直前にディスク内容と `expectedContent` を照合し、マルチプロセス競合による新しい設定の上書きを防止。
+  - **ディレクトリ Inode & Dev TOCTOU 防御**：一時ファイル書き込み前後でディレクトリのデバイス ID と inode を検証し、ディレクトリ差し替え攻撃を無効化。
+  - **Fail-Closed 厳格構文検証**：JSON のルートまたはサーバー項目が Plain Object でない場合は即座に拒絶し、プロトタイプ汚染を防止。
+- **コアスキルエンジンの確定性ソートと動的キャッシュ再検証**：
+  - **確定性ディレクトリ走査と衝突防止**：ディレクトリをアルファベット順に確定ソートし、競合キーを即座に検知して重複を安全にスキップ。
+  - **自動キャッシュ再検証 (`CACHE_REVALIDATE_MS = 1000`)**：ディスクの変更を 1 秒以内に自動検知・同期し、サーバー再起動なしで編集を反映。
+  - **大文字小文字フォールディングと正規パス防御**：`src/server.ts` が darwin/win32 で大文字小文字フォールディングと `fs.realpathSync` を実行し、システム保護ディレクトリを確実に遮断。
+- **RFC 6455 WebSocket プロトコル強化と弾力性ログ圧縮**：
+  - `CONTINUATION` (0x00) 分割メッセージの再構築を完全サポートし、制御フレームの分割禁止（`opcode >= 0x8 && !fin`）と非標準 RSV 拡張の排除を徹底。
+  - 末尾弾力性ログ圧縮：イベントログが 1 MB 上限に達した際、改行区切りの直近レコードを保持したままローテーションし、履歴の全損を回避。
+  - 秘密ファイル記述子を `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW` で安全にオープン。
+- **Shell および PowerShell スクリプトのコマンドインジェクション防御**：
+  - `find-polluter.sh` および `find-polluter.ps1`：配列展開引数受け渡し (`"${TEST_COMMAND[@]}"`、`& $testCommand @testCommandArgs`) と空白セーフな読み込みループにより、シェルインジェクションを根絶。
+  - `sdd-workspace`：`cd` 実行前に `CDPATH=''` をリセットし、環境変数によるディレクトリハイジャックを防止。
+  - `sdd-workspace.ps1`：BOM なし UTF-8 (`[System.Text.UTF8Encoding]::new($false)`) でプランマーカーを保存し、Unicode パスの完全性を保護。
+- **全自動回帰テストの基盤**：
+  - テストスイートを **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 クライアントでのスキル選択精度を向上。

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.7-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 이 문서는 Superpowers 스킬 라이브러리와 자율 에이전트 워크플로우를 독립적이고 고성능이며 안전한 **Model Context Protocol (MCP)** 서버로 패키징한 사용 지침을 요약한 것입니다.
@@ -23,11 +23,11 @@
 | :--- | :--- | :--- |
 | **Tools** | `list_skills`, `read_skill` | 14개의 Superpowers 스킬을 온디맨드로 검색, 로드 및 확인합니다. |
 | **Prompts** | 9개의 네이티브 Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
-| **Resources** | 14개의 Direct Skill URIs | `skill://superpowers/<skill-name>` (MCP 표준 기반 직접 접근) |
+| **Resources** | 14개 Skill URI + 1개 가이드 | `skill://superpowers/<skill-name>` 및 `guide://superpowers/skill-compositions` |
 
 ### AI 에이전트와 대화하기 (기본 사용법)
 
-설치 또는 구성이 완료되면 AI 에이전트가 `Superpowers Skills` 및 `Prompts`를 자동으로 인식하고 호출할 수 있습니다.
+설치 또는 구성 후 MCP 클라이언트는 Superpowers tools, prompts, resources를 탐색할 수 있습니다. MCP prompt는 사용자가 선택하여 시작하며, 이후 에이전트가 지침에 따라 `read_skill`을 호출합니다.
 
 **기본 대화 예시:**
 - **엔지니어링 규율 초기화**: "`session-start` 프롬프트 적용해줘" (Superpowers 규칙 및 환경 주입)
@@ -125,24 +125,24 @@
 
 ## 🔄 스킬 조합 및 워크플로우 파이프라인 (Skill Compositions & Pipelines)
 
-여러 단계의 복잡한 엔지니어링 작업을 수행할 때는 아래의 **원클릭 엔드투엔드 파이프라인**을 사용하세요(상세 가이드: [`docs/skill-compositions.ko.md`](docs/skill-compositions.ko.md)):
+여러 단계의 복잡한 작업에는 아래 **대화형 워크플로 런처**를 사용하세요. 설계, 계획 검토, 브랜치 마무리 단계에서 사용자 결정을 기다리므로 서버 측 무인 자동화가 아닙니다(상세: [`docs/skill-compositions.ko.md`](docs/skill-compositions.ko.md)).
 
 ### 1. 엔드투엔드 새 기능 개발 파이프라인 (Feature Development Pipeline)
 ```
 brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **원클릭 명령어:** "`feature-pipeline`을 적용하여 [기능 이름] 개발을 진행해줘"
+- **시작 방법:** MCP Prompts 메뉴에서 `feature-pipeline`을 선택하고 필수 `feature_name`과 선택적 `requirements`를 입력합니다.
 - **특징:** 요구사항 확인 (Spec) ➔ 작업 분해 (Plan) ➔ Worktree 격리 ➔ 독립 서브에이전트 + TDD 구현 ➔ 전체 테스트 검증 ➔ 대립 코드 리뷰 ➔ 브랜치 마무리.
 
 ### 2. 구조화된 문제 해결 파이프라인 (Structured Troubleshooting Pipeline)
 ```
 systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **원클릭 명령어:** "`structured-debug`를 적용하여 다음 오류를 분석하고 수정해줘: [오류 로그]"
+- **시작 방법:** MCP Prompts 메뉴에서 `structured-debug`를 선택하고 문제 또는 실패 테스트를 입력합니다.
 - **특징:** 근본 원인 가설 분해 ➔ Worktree 격리 병렬 조사 ➔ 다중 에이전트 검증 ➔ 실패 테스트 작성 및 수정 ➔ 완전한 회귀 검증 ➔ 리뷰 지적 해결 ➔ 브랜치 마무리.
 
 ### 3. 동적 워크플로우 가이드 (Dynamic Workflow Guide)
-- **원클릭 명령어:** "`skill-composition`을 적용하여 현재 상황 [리팩토링/마이그레이션/레거시 코드 보호]에 맞는 절차를 안내해줘"
+- **시작 방법:** `skill-composition`을 선택해 리팩터링, 마이그레이션, 레거시 코드용 권장 흐름을 확인합니다. 현재 이 시나리오에는 전용 런처 prompt가 없습니다.
 - **특징:** 대규모 리팩토링, 레거시 시스템 안전망 구축, 온보딩에 맞는 최적의 파이프라인을 동적으로 추천:
   - **대규모 리팩토링 및 마이그레이션 (Pipeline 3):** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
   - **레거시 코드베이스 안전망 (Pipeline 4):** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
@@ -171,23 +171,36 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 | 13 | **🤖 고급 에이전트 제어** | **`using-superpowers`** | **기본 규율 및 스킬 로드**：작업 전 적절한 스킬을 탐색하고 적용하도록 안내하는 Superpowers 기본 규율. | 세션 시작 시 자동으로 로드되어 AI의 행동 규범을 설정. |
 | 14 | **🤖 고급 에이전트 제어** | **`writing-skills`** | **스킬 작성 및 관리**：새로운 Superpowers 스킬을 생성, 테스트 및 패키징하는 표준 가이드. | 팀 전용 새 스킬을 작성하거나 기존 스킬을 확장할 때. |
 
----
-
-## 🔧 업스트림 따라잡기
-
-이 포크는 업스트림 [`obra/superpowers`](https://github.com/obra/superpowers) 의 스킬 콘텐츠를 검토된 배치로 가져옵니다. 마지막 동기화 시점의 업스트림 blob SHA는 [`tests/upstream-sync-baseline.json`](tests/upstream-sync-baseline.json) 에 기록됩니다.
-
-```bash
-npm run drift                    # 베이스라인과 업스트림을 비교해 변경 목록 출력
-npm run drift:record             # 검토된 동기화 후 베이스라인 갱신
-node scripts/upstream-drift.js   # 오프라인: 베이스라인 무결성 + 로컬 커버리지
-```
-
-보고서는 업스트림 변경, 업스트림 추가/삭제, 추적 대상이지만 로컬에 없는 파일, 포크 전용 추가를 구분해 보여줍니다. 의도적으로 채택하지 않는 업스트림 스킬은 drift가 아니라 결정 사항으로 보고되며, `npm run drift:record -- --ignore <skill>`로 기록합니다. 가져온 업스트림 파일이 삭제되거나 스킬의 업스트림 계보가 끊기면 `npm test`가 실패합니다. GitHub tree 응답이 잘린 경우 보고 모드는 결과를 부분적이라고 표시하고 `--fail-on-drift`를 억제하며, record 모드는 쓰기 자체를 거부하여 마지막 완전한 베이스라인을 보호합니다.
-
 ## 🆕 최근 업데이트
 
-### v6.3.7 (최신)
+### v6.3.8 (최신)
+
+- **실행 가능한 대화형 워크플로 런처**:
+  - `feature-pipeline`과 `structured-debug`는 단계별 명시적 `read_skill` 호출을 제공하고, 필수 사용자 승인 게이트를 유지하며, MCP 서버 내부가 아닌 클라이언트 Agent가 실행한다는 점을 명확히 밝힙니다.
+  - 멀티 Agent를 지원하는 Host에서는 Subagent를 사용하고, 그 외에는 없는 기능을 사용했다고 표현하지 않고 인라인 또는 순차 실행으로 폴백합니다.
+  - `read_skill`은 스킬 이름 단독 형식과 문서화된 `superpowers:` 접두사 형식을 모두 지원합니다.
+  - Skill Compositions 가이드가 npm 패키지에 포함되며 `guide://superpowers/skill-compositions`에서도 읽을 수 있습니다.
+- **유니버설 글로벌 설정 엔진 동시성 안전, Inode 방어 및 심볼릭 링크 탈출 격리**:
+  - **Allowed Roots 경계 격리**: 설정 파일 대상을 사용자가 명시한 허용 루트(`homeDir`, `appData`, `localAppData`) 내부로 제한하여 상위 디렉터리 심볼릭 링크 탈출 공격 차단.
+  - **낙관적 동시성 충돌 감지**: 원자적 `fs.renameSync` 직전에 디스크 내용과 `expectedContent`를 대조하여 다중 프로세스 경쟁으로 인한 최신 설정 덮어쓰기 방지.
+  - **디렉터리 Inode & Dev TOCTOU 방어**: 임시 파일 작성 전후로 디렉터리의 디바이스 ID와 inode를 검증하여 디렉터리 교체 공격 차단.
+  - **Fail-Closed 엄격 구문 분석**: JSON 루트 또는 서버 필드가 Plain Object가 아닐 경우 즉시 거부하여 프로토타입 오염 방지.
+- **핵심 스킬 엔진 결정론적 정렬 및 동적 캐시 재검증**:
+  - **결정론적 디렉터리 색인 및 충돌 방어**: 디렉터리를 알파벳순으로 정렬하고 충돌 키를 즉시 감지하여 안전하게 중복 건너뛰기.
+  - **자동 캐시 재검증 (`CACHE_REVALIDATE_MS = 1000`)**: 디스크 변경 사항을 1초 내에 자동 감지하여 서버 재시작 없이 편집 내용 반영.
+  - **대소문자 폴딩 및 정규 경로 방어**: `src/server.ts`가 darwin/win32에서 대소문자 폴딩과 `fs.realpathSync`를 수행하여 시스템 보호 디렉터리 접근 원천 차단.
+- **RFC 6455 WebSocket 프로토콜 강화 및 복원력 있는 로그 압축**:
+  - `CONTINUATION` (0x00) 분할 메시지 재조합 완전 지원, 제어 프레임 분할 금지(`opcode >= 0x8 && !fin`) 및 비표준 RSV 확장 엄격 차단.
+  - 후미 탄력적 로그 압축: 이벤트 로그가 1 MB 한도에 도달하면 개행 정렬된 최근 레코드를 보존하여 전체 손실 방지.
+  - 비공개 파일 디스크립터를 `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW`로 안전하게 열기.
+- **Shell 및 PowerShell 스크립트 명령 주입 방어**:
+  - `find-polluter.sh` 및 `find-polluter.ps1`: 배열 전개 인자 전달 (`"${TEST_COMMAND[@]}"`, `& $testCommand @testCommandArgs`)과 공백 안전 읽기 루프로 셸 주입 원천 차단.
+  - `sdd-workspace`: `cd` 실행 전 `CDPATH=''`를 재설정하여 환경 변수를 통한 디렉터리 탈취 차단.
+  - `sdd-workspace.ps1`: BOM 없는 UTF-8(`[System.Text.UTF8Encoding]::new($false)`)로 플랜 마커를 저장하여 Unicode 경로 정합성 유지.
+- **전체 자동 회귀 테스트 기준선**:
+  - 테스트 스위트를 **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 클라이언트의 스킬 선택 정확도를 향상.

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.7-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.8-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.
@@ -23,11 +23,11 @@ This document summarizes the information and usage instructions for packaging th
 | :--- | :--- | :--- |
 | **Tools** | `list_skills`, `read_skill` | Discover, search, and load full skill instructions and checklists on demand. |
 | **Prompts** | 9 Native Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
-| **Resources** | 14 Direct Skill URIs | `skill://superpowers/<skill-name>` (Standard direct URI access) |
+| **Resources** | 14 Skill URIs + 1 Guide | `skill://superpowers/<skill-name>` plus `guide://superpowers/skill-compositions` |
 
 ### Chatting with the AI Agent (Basic Usage)
 
-Once installed or configured, your AI Agent will automatically discover and invoke `Superpowers Skills` and `Prompts`.
+Once installed or configured, your MCP client can discover the Superpowers tools, prompts, and resources. MCP prompts are user-invoked; select one from your client's MCP Prompts menu. Skill loading then depends on the agent following the selected prompt and calling `read_skill`.
 
 **Basic Interaction Examples:**
 - **Initialize Engineering Discipline:** "Apply `session-start` prompt" (Injects Superpowers rules & context)
@@ -125,24 +125,25 @@ This is the easiest way as it handles path resolution automatically.
 
 ## 🔄 Skill Compositions & Workflow Pipelines
 
-For complex, multi-step engineering tasks, use these **one-click end-to-end pipelines** where the AI guides you step-by-step (see detailed guide: [`docs/skill-compositions.md`](docs/skill-compositions.md)):
+For complex engineering tasks, use these **interactive workflow launchers**. They start an agent-guided process and pause at design, plan-review, and branch-finishing decisions; they do not execute server-side or run unattended. See the published [`Skill Compositions Guide`](docs/skill-compositions.md), also available as the MCP resource `guide://superpowers/skill-compositions`.
 
 ### 1. New Feature Development Pipeline
 ```
 brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **One-Click Command:** "Please apply `feature-pipeline` to build [Feature Name]"
-- **Workflow:** Clarifies requirements (Spec) ➔ Decomposes plan ➔ Isolates worktree ➔ Implements via fresh subagents & TDD ➔ Runs full test suite ➔ Conducts code review ➔ Finishes branch.
+- **Start it:** Select `feature-pipeline` from your client's MCP Prompts menu and provide `feature_name` plus optional `requirements`.
+- **Workflow:** Clarifies requirements (Spec) ➔ waits for design approval ➔ creates a reviewable plan ➔ waits for plan approval ➔ isolates a worktree ➔ implements with SDD or the inline fallback and TDD ➔ verifies ➔ reviews ➔ asks how to finish the branch.
+- **Fallback:** If the host has no multi-agent tools, the workflow uses `executing-plans` instead of claiming to dispatch subagents.
 
 ### 2. Structured Troubleshooting Pipeline
 ```
 systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **One-Click Command:** "Please apply `structured-debug` to investigate this error: [Paste Trace / Logs]"
+- **Start it:** Select `structured-debug` from your client's MCP Prompts menu and provide the issue or failing tests.
 - **Workflow:** Hypothesizes root causes ➔ Isolates worktrees for parallel agents ➔ Authors failing reproduction tests ➔ Applies targeted fix ➔ Confirms zero regressions ➔ Reviews fix ➔ Finishes branch.
 
 ### 3. Dynamic Workflow Guide
-- **One-Click Command:** "Please apply `skill-composition` for [Refactoring / Migration / Legacy Codebase]"
+- **Start it:** Select `skill-composition` to get a recommended workflow for refactoring, migration, or a legacy codebase. These scenarios do not currently have dedicated launcher prompts.
 - **Workflow:** Dynamically recommends the optimal multi-skill composition for large refactors, migration safety nets, or onboarding:
   - **Large Refactoring & Migration:** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
   - **Legacy Codebase Safety Net:** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
@@ -171,23 +172,36 @@ To help you choose the right skill, we have structured all 14 skills across the
 | 13 | **🤖 Advanced Agents** | **`using-superpowers`** | **Superpowers Foundation & Discipline**: Establishes mandatory skill discovery, loading discipline, and priority rules. | Automatically loaded at session start to enforce software engineering standards. |
 | 14 | **🤖 Advanced Agents** | **`writing-skills`** | **Skill Authoring & Maintenance**: Guides the creation, testing, and packaging of new Superpowers skills. | When creating custom skills or enhancing existing skill instructions. |
 
----
-
-## 🔧 Keeping Up with Upstream
-
-This fork imports the upstream [`obra/superpowers`](https://github.com/obra/superpowers) skill content through reviewed batches. The upstream blob SHAs captured at the last sync live in [`tests/upstream-sync-baseline.json`](tests/upstream-sync-baseline.json).
-
-```bash
-npm run drift                    # compare the baseline against upstream and list what moved
-npm run drift:record             # refresh the baseline after a reviewed sync
-node scripts/upstream-drift.js   # offline: baseline integrity + local coverage
-```
-
-The report separates files that changed upstream, upstream additions and removals, tracked files missing from this fork, and fork-only additions. An upstream skill this fork deliberately does not adopt is reported as a decision rather than drift, and is recorded with `npm run drift:record -- --ignore <skill>`. `npm test` fails when an imported upstream file is deleted or when a shipped skill loses its upstream lineage. Report mode marks a truncated GitHub tree as partial and suppresses `--fail-on-drift`; record mode refuses that response entirely so an incomplete listing cannot overwrite the last complete baseline.
-
 ## 🆕 Recent Updates
 
-### v6.3.7 (Latest)
+### v6.3.8 (Latest)
+
+- **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.
+  - Hosts with multi-agent support can use subagent execution; other hosts fall back to inline or sequential execution without claiming unavailable capabilities.
+  - `read_skill` accepts both bare skill names and the documented `superpowers:` prefix.
+  - The composition guide is included in the npm package and available through `guide://superpowers/skill-compositions`.
+- **Universal Global Setup Concurrency & Symlink Breakout Defense**:
+  - **Allowed Roots Boundary Containment**: Enforces destination restriction to explicit allowed user roots (`homeDir`, `appData`, `localAppData`), blocking parent-directory symlink breakout attacks.
+  - **Optimistic Concurrency Conflict Defense**: Compares file content against `expectedContent` immediately prior to atomic `fs.renameSync`, preventing race conditions from silently overwriting newer configurations.
+  - **Directory Inode & Device TOCTOU Verification**: Re-checks parent directory canonical path, device ID (`dev`), and inode (`ino`) before and after temporary file creation, blocking directory swap attacks.
+  - **Fail-Closed Validation**: Rejects non-object JSON roots or server fields and duplicate YAML keys.
+- **Skills Core Engine Collision Defense & Dynamic Cache Revalidation**:
+  - **Deterministic Directory Cataloging**: Catalogs directories in deterministic alphabetical order and detects alias/name collisions in `newSkillMap`, emitting diagnostic warnings and skipping duplicates.
+  - **Automatic Cache Revalidation (`CACHE_REVALIDATE_MS = 1000`)**: Detects disk modifications within 1 second without requiring MCP server restarts.
+  - **Canonical Path Blacklisting**: Platform case-folding and `fs.realpathSync` validation to prevent symlink bypass of system directories (`/private/etc`, `/private/var`, `C:\Windows`).
+- **RFC 6455 WebSocket Protocol & Resilient Stream Hardening**:
+  - Support for fragmented text messages (`CONTINUATION` opcode `0x00`) with payload size tracking and RFC 6455 control frame constraints (`opcode >= 0x8 && !fin` rejected).
+  - Resilient tail event log compaction: Preserves recent newline-delimited event records when approaching the 1 MB file cap rather than dropping all historical events.
+  - Event log append mode hardened with `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW`.
+- **Shell & PowerShell Script Hardening**:
+  - `find-polluter.sh` & `find-polluter.ps1`: Caller-supplied test command with safe array expansion (`"${TEST_COMMAND[@]}"`, `& $testCommand @testCommandArgs`) and space-safe while loop, preventing shell command injection.
+  - `sdd-workspace`: Sanitizes `CDPATH=''` before all `cd` operations, neutralizing directory redirection attacks.
+  - `sdd-workspace.ps1`: Lossless Unicode plan marker persistence using UTF-8 without BOM (`[System.Text.UTF8Encoding]::new($false)`).
+- **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.

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.7-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.8-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 **Model Context Protocol (MCP)** 伺服器之相關資訊與使用說明。
@@ -23,11 +23,11 @@
 | :--- | :--- | :--- |
 | **Tools (工具)** | `list_skills`, `read_skill` | 依需求隨時探索、搜尋並載入技能完整內容與操作規範。 |
 | **Prompts (提示詞)** | 9 個原生 Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
-| **Resources (資源)** | 14 項技能 Direct URI | `skill://superpowers/<skill-name>`（支援 MCP 協議標準資源直讀） |
+| **Resources (資源)** | 14 項技能 URI + 1 項指南 | `skill://superpowers/<skill-name>`，以及 `guide://superpowers/skill-compositions` |
 
 ### 與 AI Agent 對話（基礎操作）
 
-安裝或配置完成後，您的 AI Agent 將能夠自動識別並調用 `Superpowers Skills` 與 `Prompts`。
+安裝或配置完成後，MCP 客戶端即可發現 Superpowers 的 tools、prompts 與 resources。MCP prompt 必須由使用者選取；之後是否載入技能，取決於 Agent 是否遵循 prompt 並呼叫 `read_skill`。
 
 **基礎互動範例：**
 - **初始化工程規範**：「套用 `session-start` prompt」（注入 Superpowers 技能體系與工程紀律）
@@ -125,24 +125,24 @@
 
 ## 🔄 技能編排與工作流流水線 (Skill Compositions & Pipelines)
 
-當執行多步驟的複雜任務時，請直接使用以下**一鍵端到端工作流**，AI 會自動按標準工程步驟引導（詳見完整指南：[`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md)）：
+當執行多步驟的複雜任務時，請使用以下**互動式工作流啟動器**。它會啟動 Agent 引導的流程，並在設計、計畫審閱與分支收尾時等待使用者決定；它不是伺服器端無人值守自動化。詳見 [`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md)。
 
 ### 1. 端到端新功能開發管線 (Feature Development Pipeline)
 ```
 brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **一鍵指令：**「請套用 `feature-pipeline`，幫我開發 [新功能名稱]」
+- **啟動方式：**從客戶端的 MCP Prompts 選單選取 `feature-pipeline`，提供必要的 `feature_name` 與選填的 `requirements`。
 - **流程特色：** 需求確認 (Spec) ➔ 任務拆解 (Plan) ➔ Worktree 隔離 ➔ 獨立 Subagent + TDD 實作 ➔ 全套測試驗證 ➔ 專家代碼審查 ➔ 分支收尾。
 
 ### 2. 結構化多點除錯管線 (Structured Troubleshooting Pipeline)
 ```
 systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
 ```
-- **一鍵指令：**「請套用 `structured-debug`，幫我排查這個報錯：[貼上錯誤訊息]」
+- **啟動方式：**從 MCP Prompts 選單選取 `structured-debug`，提供錯誤描述或失敗測試。
 - **流程特色：** 根因分析拆解假說 ➔ Worktree 隔離平行排查 ➔ 多 Agent 驗證 ➔ 編寫失敗測試並修復 ➔ 全套迴歸驗證 ➔ 審查結果解決 ➔ 分支合併收尾。
 
 ### 3. 動態技能導引 (Dynamic Workflow Guide)
-- **一鍵指令：**「請套用 `skill-composition`，我目前的情境是 [重構/遷移/接手舊專案]」
+- **啟動方式：**選取 `skill-composition` 取得重構、遷移或舊系統的流程建議；這些情境目前沒有各自獨立的啟動 prompt。
 - **流程特色：** 針對大型重構、舊代碼防護網建立或團隊新人上手，動態推薦最佳步驟：
   - **大型重構與遷移 (Pipeline 3)：** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
   - **舊專案工程防護網 (Pipeline 4)：** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
@@ -171,23 +171,36 @@ systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔
 | 13 | **🤖 進階調度** | **`using-superpowers`** | **Superpowers 基礎紀律**：MCP 入口技能，引導 Agent 在任何任務前主動搜尋並載入對應技能規範。 | 開啟對話時自動載入，規範 AI 的行為準則。 |
 | 14 | **🤖 進階調度** | **`writing-skills`** | **技能撰寫與維護**：規範如何為團隊建立、測試與封裝新的 Superpowers 技能。 | 需要擴充專屬新技能或更新既有技能時。 |
 
----
-
-## 🔧 與上游保持同步
-
-本 fork 以逐批審閱的方式引進上游 [`obra/superpowers`](https://github.com/obra/superpowers) 的技能內容；最後同步時的上游 blob SHA 記錄在 [`tests/upstream-sync-baseline.json`](tests/upstream-sync-baseline.json)。
-
-```bash
-npm run drift                    # 對比基線與上游，列出已變動項目
-npm run drift:record             # 審閱同步完成後更新基線
-node scripts/upstream-drift.js   # 離線：基線完整性 + 本地覆蓋率
-```
-
-報告會分別列出：上游變更、上游新增、上游移除、基線追蹤但本地缺漏的檔案，以及 fork 專屬新增。刻意不採用的上游技能會列為「待決策」而非 drift，並可用 `npm run drift:record -- --ignore <skill>` 記錄。當已引進的上游檔案被刪除、或某技能失去上游系譜時，`npm test` 會失敗。若 GitHub tree 回應遭截斷，報告模式會標示結果不完整並停用 `--fail-on-drift`；record 模式則直接拒絕寫入，避免不完整清單覆蓋最後一份完整基線。
-
 ## 🆕 最近更新
 
-### v6.3.7 (最新版)
+### v6.3.8 (最新版)
+
+- **可執行的互動式工作流啟動器**：
+  - `feature-pipeline` 與 `structured-debug` 會逐階段給出明確的 `read_skill` 呼叫，保留必要的使用者核准關卡，並清楚說明流程由客戶端 Agent 執行，不是 MCP 伺服器內部自動執行。
+  - 支援多 Agent 的 Host 可使用 Subagent；其他 Host 會退回會話內或序列執行，不會聲稱使用不存在的能力。
+  - `read_skill` 同時接受純技能名稱與文件所載的 `superpowers:` 前綴。
+  - Skill Compositions 指南已納入 npm 套件，並可透過 `guide://superpowers/skill-compositions` 讀取。
+- **全域安裝引擎並行安全、Inode 防禦與符號連結跳脫隔離**：
+  - **Allowed Roots 邊界隔離**：強制限制目的地路徑必須在使用者允許目錄（`homeDir`、`appData`、`localAppData`），杜絕父層符號連結跳脫攻擊。
+  - **樂觀並行衝突檢測**：在原子 `fs.renameSync` 前比對磁碟檔案與 `expectedContent`，防止多行程競態覆寫較新的設定檔。
+  - **目錄 Inode & Dev TOCTOU 防禦**：比對暫存檔案目錄之真實裝置與 inode 識別碼，防止目錄置換攻擊。
+  - **Fail-Closed 嚴格解析防護**：JSON 根目錄或伺服器欄位非 Plain Object 時即刻拒絕，阻斷原型污染與畸形設定。
+- **核心技能引擎確定性排序與動態快取驗證**：
+  - **目錄確定性排序與別名衝突防禦**：目錄按字母確定性排序並即時阻擋衝突鍵名，杜絕隨機覆寫與快取錯位。
+  - **自動快取驗證 (`CACHE_REVALIDATE_MS = 1000`)**：磁碟變更在 1 秒內自動同步，無需重啟 MCP 伺服器即可反映檔案編輯。
+  - **大小寫折疊與真實路徑防禦**：`src/server.ts` 在 darwin/win32 進行大小寫折疊與 `fs.realpathSync` 驗證，徹底攔截系統保護目錄（`/private/etc`、`/private/var`、`C:\Windows`）。
+- **RFC 6455 WebSocket 協議加固與日誌彈性壓縮**：
+  - 完整支援 `CONTINUATION` (0x00) 分段訊息重組，並嚴格驗證控制幀不得分段 (`opcode >= 0x8 && !fin`)，阻絕非標準 RSV 擴展。
+  - 尾部彈性日誌壓縮：日誌達 1 MB 上限時保留最新換行對齊記錄，避免整檔抹除遺失事件上下文。
+  - 私有檔案描述元以 `O_RDWR | O_APPEND | O_CREAT | O_NOFOLLOW` 安全開啟。
+- **Shell 與 PowerShell 腳本指令注入防禦**：
+  - `find-polluter.sh` 與 `find-polluter.ps1`：指令參數陣列化展開 (`"${TEST_COMMAND[@]}"`、`& $testCommand @testCommandArgs`) 搭配含空白檔名安全讀取迴圈，杜絕 Shell 注入。
+  - `sdd-workspace`：執行 `cd` 前重設 `CDPATH=''`，阻絕環境變數目錄劫持。
+  - `sdd-workspace.ps1`：以 UTF-8 without BOM (`[System.Text.UTF8Encoding]::new($false)`) 寫入計畫標記，確保無損 Unicode 路徑往返。
+- **全自動化回歸測試底線**：
+  - 擴展測試套件至 **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 客戶端的技能選擇準確度。

package/docs/maintainers/upstream-sync.md

@@ -0,0 +1,42 @@
+# Upstream Synchronization
+
+This guide is for maintainers who review and import skill content from [`obra/superpowers`](https://github.com/obra/superpowers).
+
+The upstream blob SHAs captured at the last sync are stored in [`tests/upstream-sync-baseline.json`](../../tests/upstream-sync-baseline.json).
+
+## Commands
+
+```bash
+npm run drift                    # compare the baseline against upstream and list what moved
+npm run drift:record             # refresh the baseline after a reviewed sync
+node scripts/upstream-drift.js   # offline: baseline integrity + local coverage
+```
+
+The drift report separates:
+
+- files changed upstream;
+- upstream additions and removals;
+- tracked files missing from this fork; and
+- fork-only additions.
+
+An upstream skill that this fork deliberately does not adopt is reported as a decision rather than drift. Record that decision after review with:
+
+```bash
+npm run drift:record -- --ignore <skill>
+```
+
+## Synchronization Workflow
+
+1. Run `npm run drift` to identify upstream changes.
+2. Review the changes and import only the content appropriate for this fork.
+3. Run the test suite with `npm test`.
+4. After the reviewed sync is complete, run `npm run drift:record` to update the baseline.
+5. Commit the imported changes and updated baseline together.
+
+Do not refresh the baseline before reviewing and importing the changes. Doing so would mark unseen upstream changes as handled.
+
+## Safety Checks
+
+`npm test` fails when an imported upstream file is deleted or when a shipped skill loses its upstream lineage.
+
+Report mode marks a truncated GitHub tree as partial and suppresses `--fail-on-drift`. Record mode refuses a truncated response entirely so an incomplete listing cannot overwrite the last complete baseline.