update faceted

CLAUDE.md

@@ -371,19 +371,30 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json
 
 **Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only step-specific instructions, not boilerplate.
 
-**Persona prompts contain only domain knowledge.** Persona prompt files (`builtins/{lang}/personas/*.md`) must contain only domain expertise and behavioral principles — never piece-specific procedures. Piece-specific details (which reports to read, step routing, specific templates with hardcoded step names) belong in the piece YAML's `instruction_template`. This keeps personas reusable across different pieces.
+**Faceted prompting: each facet has a dedicated file type.** TAKT assembles agent prompts from 4 facets. Each facet has a distinct role. When adding new rules or knowledge, place content in the correct facet.
 
-What belongs in persona prompts:
-- Role definition ("You are a ... specialist")
-- Domain expertise, review criteria, judgment standards
-- Do / Don't behavioral rules
-- Tool usage knowledge (general, not piece-specific)
+```
+builtins/{lang}/
+  personas/     — WHO: identity, expertise, behavioral habits
+  policies/     — HOW: judgment criteria, REJECT/APPROVE rules, prohibited patterns
+  knowledge/    — WHAT TO KNOW: domain patterns, anti-patterns, detailed reasoning with examples
+  instructions/ — WHAT TO DO NOW: step-specific procedures and checklists
+```
 
-What belongs in piece `instruction_template`:
-- Step-specific procedures ("Read these specific reports")
-- References to other steps or their outputs
-- Specific report file names or formats
-- Comment/output templates with hardcoded review type names
+| Deciding where to place content | Facet | Example |
+|--------------------------------|-------|---------|
+| Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" |
+| Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" |
+| Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section |
+| This-step-only procedure or checklist | Instruction | "レビュー観点: 構造・設計の妥当性..." |
+| Workflow structure, facet assignment | Piece YAML | `persona: coder`, `policy: coding`, `knowledge: architecture` |
+
+Key rules:
+- Persona files are reusable across pieces. Never include piece-specific procedures (report names, step references)
+- Policy REJECT lists are what reviewers enforce. If a criterion is not in the policy REJECT list, reviewers will not catch it — even if knowledge explains the reasoning
+- Knowledge provides the WHY behind policy criteria. Knowledge alone does not trigger enforcement
+- Instructions are bound to a single piece step. They reference procedures, not principles
+- Piece YAML `instruction_template` is for step-specific details (which reports to read, step routing, output templates)
 
 **Separation of concerns in piece engine:**
 - `PieceEngine` - Orchestration, state management, event emission

builtins/en/personas/coder.md

@@ -33,4 +33,5 @@ You are the implementer. Focus on implementation, not design decisions.
 - Making design decisions arbitrarily → Report and ask for guidance
 - Dismissing reviewer feedback → Prohibited
 - Adding backward compatibility or legacy support without being asked → Absolutely prohibited
+- Leaving replaced code/exports after refactoring → Prohibited (remove unless explicitly told to keep)
 - Layering workarounds that bypass safety mechanisms on top of a root cause fix → Prohibited

builtins/en/policies/coding.md

@@ -7,7 +7,7 @@ Prioritize correctness over speed, and code accuracy over ease of implementation
 | Principle | Criteria |
 |-----------|----------|
 | Simple > Easy | Prioritize readability over writability |
-| DRY | Extract after 3 repetitions |
+| DRY | Eliminate essential duplication |
 | Comments | Why only. Never write What/How |
 | Function size | One function, one responsibility. ~30 lines |
 | File size | ~300 lines as a guideline. Be flexible depending on the task |
@@ -245,23 +245,19 @@ Request → toInput() → UseCase/Service → Output → Response.from()
 
 ## Shared Code Decisions
 
-### Rule of Three
-
-- 1st occurrence: Write it inline
-- 2nd occurrence: Do not extract yet (observe)
-- 3rd occurrence: Consider extracting
+Eliminate duplication by default. When logic is essentially the same and should be unified, apply DRY. Do not decide mechanically by count.
 
 ### Should Be Shared
 
-- Same logic in 3+ places
+- Essentially identical logic duplicated
 - Same style/UI pattern
 - Same validation logic
 - Same formatting logic
 
 ### Should Not Be Shared
 
-- Similar but subtly different (forced generalization adds complexity)
-- Used in only 1-2 places
+- Duplication across different domains (e.g., customer validation and admin validation are separate concerns)
+- Superficially similar code with different reasons to change
 - Based on "might need it in the future" predictions
 
 ```typescript
@@ -289,4 +285,6 @@ function formatPercentage(value: number): string { ... }
 - **Hardcoded secrets**
 - **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
+- **Replaced code surviving after refactoring** - Remove replaced code and exports. Do not keep unless explicitly told to
 - **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed

builtins/en/policies/review.md

@@ -38,9 +38,11 @@ REJECT without exception if any of the following apply.
 - Direct mutation of objects/arrays
 - Swallowed errors (empty catch blocks)
 - TODO comments (not tracked in an issue)
-- Duplicated code in 3+ places (DRY violation)
+- Essentially identical logic duplicated (DRY violation)
 - Method proliferation doing the same thing (should be absorbed by configuration differences)
 - Specific implementation leaking into generic layers (imports and branching for specific implementations in generic layers)
+- Internal implementation exported from public API (infrastructure functions or internal classes exposed publicly)
+- Replaced code/exports surviving after refactoring
 - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
 
 ### Warning

builtins/ja/personas/coder.md

@@ -33,4 +33,5 @@
 - 設計判断を勝手にする → 報告して判断を仰ぐ
 - レビュワーの指摘を軽視する → 禁止
 - 後方互換・Legacy 対応を勝手に追加する → 絶対禁止
+- リファクタリングで置き換えたコード・エクスポートを残す → 禁止（明示的に残すよう指示されない限り削除する）
 - 根本原因を修正した上で安全機構を迂回するワークアラウンドを重ねる → 禁止

builtins/ja/policies/coding.md

@@ -7,7 +7,7 @@
 | 原則 | 基準 |
 |------|------|
 | Simple > Easy | 書きやすさより読みやすさを優先 |
-| DRY | 3回重複したら抽出 |
+| DRY | 本質的な重複は排除する |
 | コメント | Why のみ。What/How は書かない |
 | 関数サイズ | 1関数1責務。30行目安 |
 | ファイルサイズ | 目安として300行。タスクに応じて柔軟に |
@@ -245,23 +245,19 @@ Request → toInput() → UseCase/Service → Output → Response.from()
 
 ## 共通化の判断
 
-### 3回ルール
-
-- 1回目: そのまま書く
-- 2回目: まだ共通化しない（様子見）
-- 3回目: 共通化を検討
+基本的に重複は排除する。本質的に同じロジックであり、まとめるべきと判断したら DRY にする。回数で機械的に判断しない。
 
 ### 共通化すべきもの
 
-- 同じ処理が3箇所以上
+- 本質的に同じロジックの重複
 - 同じスタイル/UIパターン
 - 同じバリデーションロジック
 - 同じフォーマット処理
 
 ### 共通化すべきでないもの
 
-- 似ているが微妙に違うもの（無理に汎用化すると複雑化）
-- 1-2箇所しか使わないもの
+- ドメインが異なる重複（例: 顧客用バリデーションと管理者用バリデーションは別物）
+- 表面的に似ているが変更理由が異なるコード
 - 「将来使うかも」という予測に基づくもの
 
 ```typescript
@@ -289,4 +285,6 @@ function formatPercentage(value: number): string { ... }
 - **機密情報のハードコーディング**
 - **各所でのtry-catch** - エラーは上位層で一元処理
 - **後方互換・Legacy対応の自発的追加** - 明示的な指示がない限り不要
+- **内部実装のパブリック API エクスポート** - 公開するのはドメイン操作の関数・型のみ。インフラ層の関数や内部クラスをエクスポートしない
+- **リファクタリング後の旧コード残存** - 置き換えたコード・エクスポートは削除する。明示的に残すよう指示されない限り残さない
 - **安全機構を迂回するワークアラウンド** - 根本修正が正しいなら追加の迂回は不要

builtins/ja/policies/review.md

@@ -38,9 +38,11 @@
 - オブジェクト/配列の直接変更
 - エラーの握りつぶし（空の catch）
 - TODO コメント（Issue化されていないもの）
-- 3箇所以上の重複コード（DRY違反）
+- 本質的に同じロジックの重複（DRY違反）
 - 同じことをするメソッドの増殖（構成の違いで吸収すべき）
 - 特定実装の汎用層への漏洩（汎用層に特定実装のインポート・分岐がある）
+- 内部実装のパブリック API エクスポート（インフラ層の関数・内部クラスが公開されている）
+- リファクタリングで置き換えられた旧コード・旧エクスポートの残存
 - 関連フィールドのクロスバリデーション欠如（意味的に結合した設定値の不変条件が未検証）
 
 ### Warning（警告）