Release v0.22.0

CHANGELOG.md

@@ -6,6 +6,35 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.22.0] - 2026-02-22
+
+### Added
+
+- **Ensemble package system** (`takt ensemble add/remove/list`): Import and manage external TAKT packages from GitHub — `takt ensemble add github:{owner}/{repo}@{ref}` downloads packages to `~/.takt/ensemble/` with atomic installation, version compatibility checks, lock files, and package content summary before confirmation
+- **@scope references in piece YAML**: Facet references now support `@{owner}/{repo}/{facet-name}` syntax to reference facets from installed ensemble packages (e.g., `persona: @nrslib/takt-fullstack/expert-coder`)
+- **4-layer facet resolution**: Upgraded from 3-layer (project → user → builtin) to 4-layer (package-local → project → user → builtin) — ensemble package pieces automatically resolve their own facets first
+- **Ensemble category in piece selection**: Installed ensemble packages automatically appear as subcategories under an "ensemble" category in the piece selection UI
+- **Build gate in implement/fix instructions**: `implement` and `fix` builtin instructions now require build (type check) verification before test execution
+- **TAKT Pack specification** (`docs/takt-pack-spec.md`): Documentation for the TAKT package manifest format
+
+### Changed
+
+- **BREAKING: Facets directory restructured**: Facet directories moved under a `facets/` subdirectory at all levels — `builtins/{lang}/{facetType}/` → `builtins/{lang}/facets/{facetType}/`, `~/.takt/{facetType}/` → `~/.takt/facets/{facetType}/`, `.takt/{facetType}/` → `.takt/facets/{facetType}/`. Migration: move your custom facet files into the new `facets/` subdirectory
+- Contract string hardcoding prevention rule added to coding policy and architecture review instruction
+
+### Fixed
+
+- Override piece validation now includes ensemble scope via the resolver
+- Suppressed `poll_tick` debug log flooding during iteration input wait
+- Piece resolver `stat()` calls now catch errors gracefully instead of crashing on inaccessible entries
+
+### Internal
+
+- Comprehensive ensemble test suite: atomic-update, ensemble-paths, file-filter, github-ref-resolver, github-spec, list, lock-file, pack-summary, package-facet-resolution, remove-reference-check, remove, takt-pack-config, tar-parser, takt-pack-schema
+- Added `src/faceted-prompting/scope.ts` for @scope reference parsing, validation, and resolution
+- Added scope-ref tests for the faceted-prompting module
+- Added `inputWait.ts` for shared input-wait state to suppress worker pool log noise
+
 ## [0.21.0] - 2026-02-20
 
 ### Added

README.md

@@ -145,6 +145,7 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas
 | `takt #N` | Execute GitHub Issue as task |
 | `takt switch` | Switch active piece |
 | `takt eject` | Copy builtin pieces/personas for customization |
+| `takt ensemble add` | Install an ensemble package from GitHub |
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
 
@@ -212,10 +213,12 @@ See the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions.
 ~/.takt/                    # Global config
 ├── config.yaml             # Provider, model, language, etc.
 ├── pieces/                 # User piece definitions
-└── personas/               # User persona prompts
+├── facets/                 # User facets (personas, policies, knowledge, etc.)
+└── ensemble/               # Installed ensemble packages
 
 .takt/                      # Project-level
 ├── config.yaml             # Project config
+├── facets/                 # Project facets
 ├── tasks.yaml              # Pending tasks
 ├── tasks/                  # Task specifications
 └── runs/                   # Execution reports, logs, context
@@ -247,6 +250,7 @@ await engine.run();
 | [Agent Guide](./docs/agents.md) | Custom agent configuration |
 | [Builtin Catalog](./docs/builtin-catalog.md) | All builtin pieces and personas |
 | [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology |
+| [TAKT Pack Spec](./docs/takt-pack-spec.md) | Ensemble package format |
 | [Task Management](./docs/task-management.md) | Task queuing, execution, isolation |
 | [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode |
 | [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history |

docs/CHANGELOG.ja.md

@@ -6,6 +6,35 @@
 
 フォーマットは [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) に基づいています。
 
+## [0.22.0] - 2026-02-22
+
+### Added
+
+- **Ensemble パッケージシステム** (`takt ensemble add/remove/list`): GitHub から外部 TAKT パッケージをインポート・管理 — `takt ensemble add github:{owner}/{repo}@{ref}` でパッケージを `~/.takt/ensemble/` にダウンロード。アトミックなインストール、バージョン互換チェック、ロックファイル生成、確認前のパッケージ内容サマリ表示に対応
+- **@scope 参照**: piece YAML のファセット参照で `@{owner}/{repo}/{facet-name}` 構文をサポート — インストール済み ensemble パッケージのファセットを直接参照可能（例: `persona: @nrslib/takt-fullstack/expert-coder`）
+- **4層ファセット解決**: 3層（project → user → builtin）から4層（package-local → project → user → builtin）に拡張 — ensemble パッケージのピースは自パッケージ内のファセットを最優先で解決
+- **ピース選択に ensemble カテゴリ追加**: インストール済みの ensemble パッケージがピース選択 UI の「ensemble」カテゴリにサブカテゴリとして自動表示
+- **implement/fix インストラクションにビルドゲート追加**: `implement` と `fix` のビルトインインストラクションでテスト実行前にビルド（型チェック）の実行を必須化
+- **TAKT Pack 仕様** (`docs/takt-pack-spec.md`): TAKT パッケージマニフェストのフォーマット仕様ドキュメント
+
+### Changed
+
+- **BREAKING: ファセットディレクトリ構造の変更**: 全レイヤーでファセットディレクトリが `facets/` サブディレクトリ配下に移動 — `builtins/{lang}/{facetType}/` → `builtins/{lang}/facets/{facetType}/`、`~/.takt/{facetType}/` → `~/.takt/facets/{facetType}/`、`.takt/{facetType}/` → `.takt/facets/{facetType}/`。マイグレーション: カスタムファセットファイルを新しい `facets/` サブディレクトリに移動してください
+- 契約文字列のハードコード散在防止ルールをコーディングポリシーとアーキテクチャレビューインストラクションに追加
+
+### Fixed
+
+- オーバーライドピースの検証が ensemble スコープを含むリゾルバー経由で実行されるよう修正
+- イテレーション入力待ち中の `poll_tick` デバッグログ連続出力を抑制
+- ピースリゾルバーの `stat()` 呼び出しでアクセス不能エントリ時にクラッシュせずエラーハンドリング
+
+### Internal
+
+- Ensemble テストスイート: atomic-update, ensemble-paths, file-filter, github-ref-resolver, github-spec, list, lock-file, pack-summary, package-facet-resolution, remove-reference-check, remove, takt-pack-config, tar-parser, takt-pack-schema
+- `src/faceted-prompting/scope.ts` を追加（@scope 参照のパース・バリデーション・解決）
+- faceted-prompting モジュールの scope-ref テストを追加
+- `inputWait.ts` を追加（ワーカープールのログノイズ抑制のための入力待ち状態共有）
+
 ## [0.21.0] - 2026-02-20
 
 ### Added

docs/README.ja.md

@@ -156,6 +156,7 @@ movements:
 | `takt #N` | GitHub Issue をタスクとして実行します |
 | `takt switch` | 使う piece を切り替えます |
 | `takt eject` | ビルトインの piece/persona をコピーしてカスタマイズできます |
+| `takt ensemble add` | GitHub から ensemble パッケージをインストールします |
 
 全コマンド・オプションは [CLI Reference](./cli-reference.ja.md) を参照してください。
 
@@ -223,10 +224,12 @@ takt --pipeline --task "バグを修正して" --auto-pr
 ~/.takt/                    # グローバル設定
 ├── config.yaml             # プロバイダー、モデル、言語など
 ├── pieces/                 # ユーザー定義の piece
-└── personas/               # ユーザー定義の persona
+├── facets/                 # ユーザー定義のファセット（personas, policies, knowledge など）
+└── ensemble/               # インストール済み ensemble パッケージ
 
 .takt/                      # プロジェクトレベル
 ├── config.yaml             # プロジェクト設定
+├── facets/                 # プロジェクトのファセット
 ├── tasks.yaml              # 積まれたタスク
 ├── tasks/                  # タスクの仕様書
 └── runs/                   # 実行レポート、ログ、コンテキスト
@@ -258,6 +261,7 @@ await engine.run();
 | [Agent Guide](./agents.md) | カスタムエージェントの設定 |
 | [Builtin Catalog](./builtin-catalog.ja.md) | ビルトイン piece・persona の一覧 |
 | [Faceted Prompting](./faceted-prompting.ja.md) | プロンプト設計の方法論 |
+| [TAKT Pack Spec](./takt-pack-spec.md) | Ensemble パッケージのフォーマット仕様 |
 | [Task Management](./task-management.ja.md) | タスクの追加・実行・隔離 |
 | [CI/CD Integration](./ci-cd.ja.md) | GitHub Actions・パイプラインモード |
 | [Changelog](../CHANGELOG.md) ([日本語](./CHANGELOG.ja.md)) | バージョン履歴 |

docs/cli-reference.ja.md

@@ -300,6 +300,26 @@ takt metrics review
 takt metrics review --since 7d
 ```
 
+### takt ensemble
+
+Ensemble パッケージ（GitHub 上の外部 TAKT パッケージ）を管理します。
+
+```bash
+# GitHub からパッケージをインストール
+takt ensemble add github:{owner}/{repo}@{ref}
+
+# デフォルトブランチからインストール
+takt ensemble add github:{owner}/{repo}
+
+# インストール済みパッケージを一覧表示
+takt ensemble list
+
+# パッケージを削除
+takt ensemble remove @{owner}/{repo}
+```
+
+インストールされたパッケージは `~/.takt/ensemble/` に保存され、ピース選択やファセット解決で利用可能になります。
+
 ### takt purge
 
 古いアナリティクスイベントファイルを削除します。

docs/cli-reference.md

@@ -300,6 +300,26 @@ takt metrics review
 takt metrics review --since 7d
 ```
 
+### takt ensemble
+
+Manage ensemble packages (external TAKT packages from GitHub).
+
+```bash
+# Install a package from GitHub
+takt ensemble add github:{owner}/{repo}@{ref}
+
+# Install from default branch
+takt ensemble add github:{owner}/{repo}
+
+# List installed packages
+takt ensemble list
+
+# Remove a package
+takt ensemble remove @{owner}/{repo}
+```
+
+Installed packages are stored in `~/.takt/ensemble/` and their pieces/facets become available in piece selection and facet resolution.
+
 ### takt purge
 
 Purge old analytics event files.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "takt",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "takt",
-      "version": "0.21.0",
+      "version": "0.22.0",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.2.47",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "takt",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "TAKT: TAKT Agent Koordination Topology - AI Agent Piece Orchestration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",