Merge pull request #353 from nrslib/release/v0.22.0

Release v0.22.0

.gitignore

@@ -1,4 +1,5 @@
 # Dependencies
+node_modules
 node_modules/
 
 # Build output

CHANGELOG.md

@@ -6,6 +6,39 @@ 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
+
+- **Repertoire package system** (`takt repertoire add/remove/list`): Import and manage external TAKT packages from GitHub — `takt repertoire add github:{owner}/{repo}@{ref}` downloads packages to `~/.takt/repertoire/` 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 repertoire 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) — repertoire package pieces automatically resolve their own facets first
+- **Repertoire category in piece selection**: Installed repertoire packages automatically appear as subcategories under a "repertoire" 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
+- **Repertoire package documentation**: Added comprehensive docs for the repertoire package system ([en](./docs/repertoire.md), [ja](./docs/repertoire.ja.md))
+
+### Changed
+
+- **BREAKING: "ensemble" renamed to "repertoire"**: All CLI commands, directories, config keys, and APIs renamed — `takt ensemble` → `takt repertoire`, `~/.takt/ensemble/` → `~/.takt/repertoire/`. Migration: rename your `~/.takt/ensemble/` directory to `~/.takt/repertoire/`
+- **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 repertoire scope via the resolver
+- `takt export-cc` now reads facets from the new `builtins/{lang}/facets/` directory structure
+- `confirm()` prompt now supports piped stdin (e.g., `echo "y" | takt repertoire add ...`)
+- 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 repertoire test suite: atomic-update, repertoire-paths, file-filter, github-ref-resolver, github-spec, list, lock-file, pack-summary, package-facet-resolution, remove-reference-check, remove, takt-repertoire-config, tar-parser, takt-repertoire-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
+- Added piece-selection-branches and repertoire e2e tests
+
 ## [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 repertoire add` | Install a repertoire 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.)
+└── repertoire/             # Installed repertoire 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 |
+| [Repertoire Packages](./docs/repertoire.md) | Installing and sharing packages |
 | [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 |

builtins/en/facets/instructions/fix.md

@@ -2,12 +2,18 @@ Address the reviewer's feedback.
 Use reports in the Report Directory shown in the Piece Context and fix the issues raised by the reviewer.
 Use files in the Report Directory as primary evidence. If additional context is needed, you may consult Previous Response and conversation history as secondary sources (Previous Response may be unavailable). If information conflicts, prioritize reports in the Report Directory and actual file contents.
 
+**Important**: After fixing, run both build and tests.
+- Build verification is mandatory. Run the build (type check) and verify there are no type errors
+- Running tests is mandatory. After build succeeds, always run tests and verify results
+
 **Required output (include headings)**
 ## Work results
 - {Summary of actions taken}
 ## Changes made
 - {Summary of changes}
+## Build results
+- {Build execution results}
 ## Test results
-- {Command executed and results}
+- {Test command executed and results}
 ## Evidence
 - {List key points from files checked/searches/diffs/logs}

builtins/en/facets/instructions/implement.md

@@ -6,7 +6,9 @@ Use reports in the Report Directory as the primary source of truth. If additiona
 - Add unit tests for newly created classes and functions
 - Update relevant tests when modifying existing code
 - Test file placement: follow the project's conventions
-- Running tests is mandatory. After completing implementation, always run tests and verify results
+- Build verification is mandatory. After completing implementation, run the build (type check) and verify there are no type errors
+- Running tests is mandatory. After build succeeds, always run tests and verify results
+- When introducing new contract strings (file names, config key names, etc.), define them as constants in one place
 
 **Scope output contract (create at the start of implementation):**
 ```markdown
@@ -43,5 +45,7 @@ Small / Medium / Large
 - {Summary of actions taken}
 ## Changes made
 - {Summary of changes}
+## Build results
+- {Build execution results}
 ## Test results
-- {Command executed and results}
+- {Test command executed and results}

builtins/en/facets/instructions/review-arch.md

@@ -8,6 +8,7 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 - Test coverage
 - Dead code
 - Call chain verification
+- Scattered hardcoding of contract strings (file names, config key names)
 
 **Previous finding tracking (required):**
 - First, extract open findings from "Previous Response"

builtins/en/facets/policies/coding.md

@@ -284,6 +284,7 @@ function formatPercentage(value: number): string { ... }
 - **Direct mutation of objects/arrays** - Create new instances with spread operators
 - **console.log** - Do not leave in production code
 - **Hardcoded secrets**
+- **Scattered hardcoded contract strings** - File names and config key names must be defined as constants in one place. Scattered literals are prohibited
 - **Scattered try-catch** - Centralize error handling at the upper layer
 - **Unsolicited backward compatibility / legacy support** - Not needed unless explicitly instructed
 - **Internal implementation exported from public API** - Only export domain-level functions and types. Do not export infrastructure functions or internal classes

builtins/en/facets/policies/testing.md

@@ -10,6 +10,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | One test, one concept | Do not mix multiple concerns in a single test |
 | Test behavior | Test behavior, not implementation details |
 | Independence | Do not depend on other tests or execution order |
+| Type safety | Code must pass the build (type check) |
 | Reproducibility | Do not depend on time or randomness. Same result every run |
 
 ## Coverage Criteria
@@ -19,6 +20,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | New behavior | Test required. REJECT if missing |
 | Bug fix | Regression test required. REJECT if missing |
 | Behavior change | Test update required. REJECT if missing |
+| Build (type check) | Build must succeed. REJECT if it fails |
 | Edge cases / boundary values | Test recommended (Warning) |
 
 ## Test Priority

builtins/ja/facets/instructions/fix.md

@@ -2,12 +2,18 @@
 Piece Contextに示されたReport Directory内のレポートを確認し、レビュアーの指摘事項を修正してください。
 必要な根拠はReport Directory内のファイルを一次情報として取得してください。不足情報の補完が必要な場合に限り、Previous Responseや会話履歴を補助的に参照して構いません（Previous Responseは提供されない場合があります）。情報が競合する場合は、Report Directory内のレポートと実際のファイル内容を優先してください。
 
+**重要**: 修正後、ビルドとテストの両方を実行してください。
+- ビルド確認は必須。ビルド（型チェック）を実行し、型エラーがないことを確認
+- テスト実行は必須。ビルド成功後、必ずテストを実行して結果を確認
+
 **必須出力（見出しを含める）**
 ## 作業結果
 - {実施内容の要約}
 ## 変更内容
 - {変更内容の要約}
+## ビルド結果
+- {ビルド実行結果}
 ## テスト結果
-- {実行コマンドと結果}
+- {テスト実行コマンドと結果}
 ## 証拠
 - {確認したファイル/検索/差分/ログの要点を列挙}

builtins/ja/facets/instructions/implement.md

@@ -6,7 +6,9 @@ Report Directory内のレポートを一次情報として参照してくださ
 - 新規作成したクラス・関数には単体テストを追加
 - 既存コードを変更した場合は該当するテストを更新
 - テストファイルの配置: プロジェクトの規約に従う
-- テスト実行は必須。実装完了後、必ずテストを実行して結果を確認
+- ビルド確認は必須。実装完了後、ビルド（型チェック）を実行し、型エラーがないことを確認
+- テスト実行は必須。ビルド成功後、必ずテストを実行して結果を確認
+- ファイル名・設定キー名などの契約文字列を新規導入する場合は、定数として1箇所で定義すること
 
 **Scope出力契約（実装開始時に作成）:**
 ```markdown
@@ -43,5 +45,7 @@ Small / Medium / Large
 - {実施内容の要約}
 ## 変更内容
 - {変更内容の要約}
+## ビルド結果
+- {ビルド実行結果}
 ## テスト結果
-- {実行コマンドと結果}
+- {テスト実行コマンドと結果}

builtins/ja/facets/instructions/review-arch.md

@@ -8,6 +8,7 @@ AI特有の問題はレビューしないでください（ai_reviewムーブメ
 - テストカバレッジ
 - デッドコード
 - 呼び出しチェーン検証
+- 契約文字列（ファイル名・設定キー名）のハードコード散在
 
 **前回指摘の追跡（必須）:**
 - まず「Previous Response」から前回の open findings を抽出する