takt 0.33.1 → 0.34.0

package/README.md

@@ -4,7 +4,7 @@
 
 **T**AKT **A**gent **K**oordination **T**opology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code.
 
-TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
+TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative workflow files.
 
 TAKT is built with TAKT itself (dogfooding).
 
@@ -14,7 +14,7 @@ TAKT is built with TAKT itself (dogfooding).
 
 **Practical** — A tool for daily development, not demos. Talk to AI to refine requirements, queue tasks, and run them. Worktree isolation on task execution, PR creation, and retry on failure.
 
-**Reproducible** — Execution paths are declared in YAML, keeping results consistent. Pieces are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR.
+**Reproducible** — Execution paths are declared in YAML, keeping results consistent. Workflows are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR.
 
 **Multi-agent** — Orchestrate multiple agents with different personas, permissions, and review criteria. Run parallel reviewers, route failures back to implementers, aggregate results with declarative rules. Prompts are managed as independent facets (persona, policy, knowledge, instruction) that compose freely across workflows ([Faceted Prompting](./docs/faceted-prompting.md)).
 
@@ -45,7 +45,7 @@ npm install -g takt
 ```
 $ takt
 
-Select piece:
+Select workflow:
   ❯ 🎼 default (current)
     📁 🚀 Quick Start/
     📁 🎨 Frontend/
@@ -67,7 +67,7 @@ What would you like to do?
     Continue conversation
 ```
 
-Choosing "Queue as task" saves the task to `.takt/tasks/`. Run `takt run` to execute — TAKT creates an isolated worktree, runs the piece (plan → implement → review → fix loop), and offers to create a PR when done.
+Choosing "Queue as task" saves the task to `.takt/tasks/`. Run `takt run` to execute — TAKT creates an isolated worktree, runs the workflow (plan → implement → review → fix loop), and offers to create a PR when done.
 
 ```bash
 # Execute queued tasks
@@ -81,7 +81,7 @@ takt add #12
 takt run
 ```
 
-> **"Execute now"** runs the piece directly in your current directory without worktree isolation. Useful for quick experiments, but note that changes go straight into your working tree.
+> **"Execute now"** runs the workflow directly in your current directory without worktree isolation. Useful for quick experiments, but note that changes go straight into your working tree.
 
 ### Manage results
 
@@ -92,16 +92,16 @@ takt list
 
 ## How It Works
 
-TAKT uses a music metaphor — the name itself comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. In TAKT, a **piece** is a workflow and a **movement** is a step within it, just as a musical piece is composed of movements.
+TAKT uses a music metaphor — the name itself comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. User-facing terminology uses **workflow** and **step**, while the internal canonical names remain **piece** and **movement** for backward compatibility.
 
-A piece defines a sequence of movements. Each movement specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
+A workflow is defined by a sequence of steps. Public YAML examples use `steps` and `initial_step`, while legacy `movements` and `initial_movement` are still accepted as compatibility aliases. Each step specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:
 
 ```yaml
 name: plan-implement-review
-initial_movement: plan
+initial_step: plan
 max_movements: 10
 
-movements:
+steps:
   - name: plan
     persona: planner
     edit: false
@@ -127,18 +127,22 @@ movements:
         next: implement    # ← fix loop
 ```
 
-Rules determine the next movement. `COMPLETE` ends the piece successfully, `ABORT` ends with failure. See the [Piece Guide](./docs/pieces.md) for the full schema, parallel movements, and rule condition types.
+Rules determine the next step. `COMPLETE` ends the workflow successfully, `ABORT` ends with failure. See the [Workflow Guide](./docs/pieces.md) for the full schema, parallel steps, and rule condition types.
 
-## Recommended Pieces
+Workflow files live in `workflows/` as the official directory name. TAKT still accepts legacy `pieces/` directories and `--piece` / legacy YAML keys as compatibility input, but normal docs and UI use `workflow` / `step`.
 
-| Piece | Use Case |
+When the same workflow name exists in multiple locations, TAKT resolves in this order: `.takt/workflows/` → `.takt/pieces/` → `~/.takt/workflows/` → `~/.takt/pieces/` → builtins.
+
+## Recommended Workflows
+
+| Workflow | Use Case |
 |-------|----------|
 | `default` | Standard development. Test-first with AI antipattern review and parallel review (architecture + supervisor). |
 | `frontend-mini` | Frontend-focused mini configuration. |
 | `backend-mini` | Backend-focused mini configuration. |
 | `dual-mini` | Frontend + backend mini configuration. |
 
-See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas.
+See the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and personas.
 
 ## Key Commands
 
@@ -148,7 +152,7 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas
 | `takt run` | Execute all pending tasks |
 | `takt list` | Manage task branches (merge, retry, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
-| `takt eject` | Copy builtin pieces/facets for customization |
+| `takt eject` | Copy builtin workflows/facets for customization |
 | `takt repertoire add` | Install a repertoire package from GitHub |
 
 See the [CLI Reference](./docs/cli-reference.md) for all commands and options.
@@ -177,10 +181,10 @@ See the [Configuration Guide](./docs/configuration.md) for all options, provider
 
 ## Customization
 
-### Custom pieces
+### Custom workflows
 
 ```bash
-takt eject default    # Copy builtin to ~/.takt/pieces/ and edit
+takt eject default    # Copy builtin workflow to ~/.takt/workflows/ and edit
 ```
 
 ### Custom personas
@@ -192,9 +196,9 @@ Create a Markdown file in `~/.takt/personas/`:
 You are a code reviewer specialized in security.
 ```
 
-Reference it in your piece: `persona: my-reviewer`
+Reference it in your workflow: `persona: my-reviewer`
 
-See the [Piece Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details.
+See the [Workflow Guide](./docs/pieces.md) and [Agent Guide](./docs/agents.md) for details.
 
 ## CI/CD
 
@@ -220,25 +224,28 @@ 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
+├── workflows/              # User workflow definitions
 ├── facets/                 # User facets (personas, policies, knowledge, etc.)
 └── repertoire/             # Installed repertoire packages
 
 .takt/                      # Project-level
 ├── config.yaml             # Project config
+├── workflows/              # Project workflow overrides
 ├── facets/                 # Project facets
 ├── tasks.yaml              # Pending tasks
 ├── tasks/                  # Task specifications
 └── runs/                   # Execution reports, logs, context
 ```
 
+Legacy `pieces/` directories are still read for compatibility, but `workflows/` is the canonical name in current docs and CLI output.
+
 ## API Usage
 
 ```typescript
 import { PieceEngine, loadPiece } from 'takt';
 
 const config = loadPiece('default');
-if (!config) throw new Error('Piece not found');
+if (!config) throw new Error('Workflow not found');
 
 const engine = new PieceEngine(config, process.cwd(), 'My task');
 engine.on('movement:complete', (movement, response) => {
@@ -254,9 +261,9 @@ await engine.run();
 |----------|-------------|
 | [CLI Reference](./docs/cli-reference.md) | All commands and options |
 | [Configuration](./docs/configuration.md) | Global and project settings |
-| [Piece Guide](./docs/pieces.md) | Creating and customizing pieces |
+| [Workflow Guide](./docs/pieces.md) | Creating and customizing workflows |
 | [Agent Guide](./docs/agents.md) | Custom agent configuration |
-| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin pieces and personas |
+| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin workflows 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 |

package/builtins/en/config.yaml

@@ -34,8 +34,8 @@ language: en        # UI language: en | ja
 # notification_sound: true         # Master switch for sounds
 # notification_sound_events:       # Per-event sound toggle (unset means true)
 #   iteration_limit: true
-#   piece_complete: true
-#   piece_abort: true
+#   workflow_complete: true
+#   workflow_abort: true
 #   run_complete: true
 #   run_abort: true
 # logging:
@@ -82,12 +82,12 @@ language: en        # UI language: en | ja
 # runtime:
 #   prepare: [node, gradle, ./custom-script.sh]
 
-# Piece-level overrides
-# piece_overrides:
+# Workflow-level overrides
+# workflow_overrides:
 #   quality_gates:
 #     - "All tests pass"
 #   quality_gates_edit_only: true
-#   movements:
+#   steps:
 #     review:
 #       quality_gates:
 #         - "No security vulnerabilities"
@@ -116,8 +116,8 @@ language: en        # UI language: en | ja
 # Misc
 # bookmarks_file: ~/.takt/preferences/bookmarks.yaml  # Bookmark file location
 
-# Piece list / categories
-# enable_builtin_pieces: true                             # Enable built-in pieces from builtins/{lang}/pieces
+# Workflow list / categories
+# enable_builtin_workflows: true                          # Enable built-in workflows from builtins/{lang}/workflows
 # disabled_builtins:
 #   - magi                                                # Built-in piece names to disable
-# piece_categories_file: ~/.takt/preferences/piece-categories.yaml  # Category definition file
+# workflow_categories_file: ~/.takt/preferences/workflow-categories.yaml  # Category definition file

package/builtins/en/facets/instructions/architecture-audit-plan.md

@@ -0,0 +1,13 @@
+Audit the project architecture before making changes.
+
+**What to do:**
+1. Enumerate the main modules, layers, boundaries, and public entry points using Read, Glob, and Grep
+2. Identify the dependency directions, shared abstractions, and major call chains
+3. Build an audit scope that covers all modules relevant to structure, ownership, and wiring
+4. Highlight modules with higher architectural risk (boundary leaks, giant files, scattered logic, coupling hotspots)
+5. Prepare an audit order that reviews the highest-risk modules first
+
+**Important:**
+- Start from full module and boundary enumeration, not from a few suspicious files
+- Focus on structure and wiring, not style-only comments
+- If the architecture cannot be inferred from code alone, state the missing evidence explicitly

package/builtins/en/facets/instructions/architecture-audit-review.md

@@ -0,0 +1,15 @@
+Re-audit the modules or boundaries that were judged insufficient in the previous architecture audit.
+
+**Important:** Refer to these reports:
+- Plan report: {report:01-architecture-audit-plan.md}
+- Audit report: {report:02-architecture-audit.md}
+
+**What to do:**
+1. Read the flagged modules, boundaries, and call chains in full
+2. Re-check the structural claims and identify what was previously skipped or weakly evidenced
+3. Update the audit result with concrete file evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Strictly prohibited:**
+- Modifying production code
+- Claiming a boundary or dependency direction is valid without file evidence
+- Skipping a flagged module because it "looks standard"

package/builtins/en/facets/instructions/architecture-audit-supervise.md

@@ -0,0 +1,14 @@
+Verify the completeness and quality of the architecture audit itself.
+
+**Important:** Refer to these reports:
+- Plan report: {report:01-architecture-audit-plan.md}
+- Audit report: {report:02-architecture-audit.md}
+
+**Verification procedure:**
+1. Cross-check the module inventory from the plan against the audited modules in the audit report
+2. Reject if important modules or boundaries remain unaudited
+3. Reject if key dependency directions, wiring paths, ownership boundaries, or call chains from the plan are missing from the audit result without an explicit reason
+4. Verify the audit report includes concrete structural evidence, not just design opinions
+5. Verify the report includes the enumeration commands used and that they are sufficient to support the claimed scope
+6. Sample-read a few high-risk modules yourself to confirm the structural claims are credible
+7. Require re-audit if findings or suggested issue titles are too vague to file directly

package/builtins/en/facets/instructions/architecture-audit-team-leader.md

@@ -0,0 +1,22 @@
+Decompose the architecture audit, assign modules to each part, and execute in parallel.
+
+**Important:** Refer to the plan report: {report:01-architecture-audit-plan.md}
+
+**What to do:**
+1. Review the module inventory and architectural risk areas from the plan report
+2. Split the audit into 3 groups by module or boundary
+3. Assign exclusive ownership to each part so every relevant module is audited once
+
+**Each part's instruction MUST include:**
+- Assigned module and file list
+- The boundaries and call chains to verify
+- Required audit procedure:
+  1. Read the assigned files in full
+  2. Trace dependency direction, entry points, and shared abstractions
+  3. Record structural findings with concrete file evidence
+- Completion criteria: every assigned module has been audited and all findings are reported with evidence
+
+**Constraints:**
+- Each part is read-only
+- Do not audit files outside the assignment
+- Prefer evidence from code structure and call chains over style-only comments

package/builtins/en/facets/instructions/dual-team-leader-implement.md

@@ -10,6 +10,8 @@ Analyze the implementation task and, if decomposition is appropriate, split into
    - If few files are involved, or the task is a rename/refactoring, implement in a single part
 
 2. If decomposing: prioritize splitting along frontend and backend boundaries
+   - **If design references exist and backend changes are not explicitly required, do not decompose.** Visual structure, copy, spacing, and styling are tightly coupled, and splitting them increases design drift risk
+   - **If design references exist, keep all UI components of the same screen in the same part.** Do not split headers, filters, cards, banners, and modals of one screen across different parts
    - Splitting between frontend (UI, components, styles) and backend (API, logic, data layer) is the most natural decomposition axis
    - When API contracts (request/response types) are defined, parallel implementation works well
    - When API contracts are undecided, implement backend first in one part and defer frontend
@@ -24,9 +26,13 @@ Analyze the implementation task and, if decomposition is appropriate, split into
      - **Reference-only files** (read-only, modification prohibited)
      - **Implementation task** (what and how to implement)
      - **Completion criteria** (implementation of responsible files is complete)
+   - When design references exist, each part instruction must also include:
+     - **Design references** (which files are the primary source of truth)
+     - **Elements to verify** (layout, copy, color, spacing, and navigation flow)
    - If tests are already written, instruct parts to implement so existing tests pass
-   - Do not include build checks (all parts complete first, then build is verified together)
+   - Refer to Quality Gates and plan any required verification as a dedicated single verification part
+   - Do not make parallel implementation parts run duplicate full-build or full-test checks
 
 **Constraints:**
-- Parts do not run tests (handled by subsequent movements)
+- If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete
 - Do not modify files outside your responsibility (causes conflicts)

package/builtins/en/facets/instructions/e2e-audit-plan.md

@@ -0,0 +1,13 @@
+Audit the target for E2E coverage before making changes.
+
+**What to do:**
+1. Enumerate all user entry points, major routes, task flows, and failure paths from the codebase
+2. Read the existing E2E tests and map which flows and scenarios are already covered
+3. Build a complete list of auditable user flows and scenario variants
+4. Identify missing E2E scenarios and prioritize them by user impact and regression risk
+5. Prepare an implementation order that covers the highest-risk missing scenarios first
+
+**Important:**
+- Start from complete route and flow enumeration, not from a few obvious pages
+- Include unhappy paths, permission differences, and recovery paths when relevant
+- If a flow cannot be audited from local code and tests alone, state the missing evidence explicitly

package/builtins/en/facets/instructions/e2e-audit-review.md

@@ -0,0 +1,16 @@
+Re-audit the routes or scenarios that were judged insufficient in the previous E2E audit.
+
+**Important:** Review the supervisor's verification results and understand:
+- Unaudited flows or scenarios
+- Coverage claims lacking evidence
+- Specific feedback on issue quality or scope
+
+**What to do:**
+1. Read the flagged route-related code and corresponding E2E tests in full
+2. Re-check the coverage claims for the flagged scenarios and identify what was previously skipped or weakly evidenced
+3. Update the audit result in issue-ready form with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Strictly prohibited:**
+- Modifying E2E tests or production code
+- Claiming a scenario is covered without citing the actual test evidence
+- Skipping a flagged route because it "looks fine"

package/builtins/en/facets/instructions/e2e-audit-supervise.md

@@ -0,0 +1,11 @@
+Verify the completeness and quality of the E2E audit itself.
+
+**Important:** Refer to the audit plan report: {report:01-e2e-audit-plan.md}
+
+**Verification procedure:**
+1. Cross-check the full route and flow inventory in the plan against the audited scenarios in the audit report
+2. Reject if any important entry point, user flow, unhappy path, permission variant, or recovery path from the plan is missing from the audit result without an explicit reason
+3. Verify the audit report includes concrete evidence for covered and missing scenarios, not just high-level claims
+4. Verify the report includes the enumeration commands used and that they are sufficient to support the claimed scope
+5. Sample-read a few high-risk routes and corresponding tests yourself to validate the coverage claims
+6. Require re-audit if issue titles, priorities, or recommended actions are too vague to be filed directly

package/builtins/en/facets/instructions/e2e-audit-team-leader.md

@@ -0,0 +1,22 @@
+Decompose the E2E audit, assign flows to each part, and execute in parallel.
+
+**Important:** Refer to the plan report: {report:01-e2e-audit-plan.md}
+
+**What to do:**
+1. Review the user flow list, existing scenarios, and risk areas from the plan report
+2. Split the audit into 3 groups by feature area or route cluster
+3. Assign exclusive ownership so every audited flow is reviewed once
+
+**Each part's instruction MUST include:**
+- Assigned routes, entry points, and corresponding E2E files
+- The happy paths, failure paths, and permission variants to verify
+- Required audit procedure:
+  1. Read the relevant code for the assigned flows
+  2. Read the corresponding E2E tests in full
+  3. Record covered and missing scenarios with concrete evidence
+- Completion criteria: every assigned flow has been audited and findings are reported in issue-ready form
+
+**Constraints:**
+- Each part is read-only
+- Do not modify E2E tests or production code
+- Do not audit routes outside the assignment

package/builtins/en/facets/instructions/plan.md

@@ -14,6 +14,9 @@ For small tasks, skip the design sections in the report.
 1. Understand the task requirements
    - **When reference material points to an external implementation, determine whether it is a "bug fix clue" or a "design approach to adopt". If narrowing scope beyond the reference material's intent, include the rationale in the plan report**
    - **For each requirement, determine "change needed / not needed". If "not needed", cite the relevant code (file:line) as evidence. Claiming "already correct" without evidence is prohibited**
+   - **Limit requirements to explicit requirements and implicit requirements that follow directly from them. Do not turn general best practices or future extensions into requirements**
+   - **When decomposing requirements, split only as far as needed to make them independently verifiable. Do not jump from decomposition into new requirements**
+   - **When adding an implicit requirement, state which explicit requirement it is derived from in the plan report**
 2. Investigate code to resolve unknowns
 3. Identify the impact area
 4. Determine file structure and design patterns (if needed)

package/builtins/en/facets/instructions/review-requirements.md

@@ -14,14 +14,19 @@ Review {report:coder-decisions.md} to understand the recorded design decisions.
 
 **Previous finding tracking (required):**
 - First, extract open findings from "Previous Response"
-- Assign `finding_id` to each finding and classify current status as `new / persists / resolved`
+- Assign `finding_id` to each finding and classify current status as `new / persists / resolved / reopened`
 - If status is `persists`, provide concrete unresolved evidence (file/line)
 
 ## Judgment Procedure
 
-1. Extract requirements one by one from the review target report and task
-2. For each requirement, identify the implementing code (file:line)
-3. Confirm that the code satisfies the requirement
-4. Check for any changes not covered by the requirements
-5. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
-6. If there is even one blocking issue (`new` or `persists`), judge as REJECT
+1. Read `order.md`, the task body, `plan.md`, and `coder-decisions.md`, then extract the requirements one by one
+2. If a sentence contains multiple conditions or paths, split it into the smallest independently verifiable units
+   - Do not keep `A/B`, `global/project`, `JSON/leaf`, `allow/deny`, or `read/write` in a single row
+3. For each requirement, identify the implementing code (file:line)
+4. Classify each requirement as `satisfied / unmet / unverified`
+   - Do not mark a row `satisfied` without concrete code evidence
+   - Do not mark a row `satisfied` when only part of the cases is covered
+5. List out-of-scope changes and judge whether they are justified or unnecessary
+6. Reclassify prior findings into `new / persists / resolved / reopened`
+7. For each detected issue, classify it as blocking/non-blocking based on the Policy's scope table and judgment rules
+8. If there is even one blocking issue in `new`, `persists`, or `reopened`, judge as REJECT

package/builtins/en/facets/instructions/supervise.md

@@ -10,7 +10,7 @@ Verify existing evidence for tests, builds, and functional checks, then perform
    - Read `order.md` and extract required behavior and prohibitions
    - Read `plan.md` and confirm intended approach and scope
    - Read `coder-decisions.md` and confirm why the implementation moved in that direction
-   - Do not treat prior review conclusions as authoritative unless they align with all three and the code
+   - Do not treat prior review conclusions or requirements-review conclusions as authoritative unless they align with all three and the code
 3. Whether each task spec requirement has been achieved
    - Extract requirements one by one from the task spec
    - If a single sentence contains multiple conditions or paths, split it into the smallest independently verifiable units
@@ -31,7 +31,7 @@ Verify existing evidence for tests, builds, and functional checks, then perform
 5. Handling tests, builds, and functional checks
    - Do not assume this movement will rerun commands
    - Use only evidence available in this run, such as execution logs, reports, or CI results
-   - If evidence is missing, mark the item as unverified
+   - If evidence is missing, mark the item as unverified rather than successful
    - If report text conflicts with execution evidence, call out the inconsistency explicitly
 
 **Report verification:** Read all reports in the Report Directory and
@@ -54,6 +54,7 @@ Extract requirements from the task spec and verify each one individually against
 
 - If any ❌ exists, REJECT is mandatory
 - ✅ without evidence is invalid (must verify against actual code)
+- Do not mark a row as ✅ when only part of the cases is verified
 - Do not rely on plan report's judgment; independently verify each requirement
 
 ## Re-evaluation of Prior Findings
@@ -63,6 +64,7 @@ Extract requirements from the task spec and verify each one individually against
 
 - If final judgment differs from prior review conclusions, explain why with evidence
 - If marking `false_positive` or `overreach`, state whether it conflicts with the task objective, the plan, or both
+- If overturning a requirements-review conclusion, explain why with concrete evidence
 
 ## Verification Summary
 | Item | Status | Verification method |

package/builtins/en/facets/instructions/team-leader-implement.md

@@ -22,8 +22,9 @@ Analyze the implementation task and, if decomposition is appropriate, split into
      - **Implementation task** (what and how to implement)
      - **Completion criteria** (implementation of responsible files is complete)
    - If tests are already written, instruct parts to implement so existing tests pass
-   - Do not include build checks (all parts complete first, then build is verified together)
+   - Refer to Quality Gates and plan any required verification as a dedicated single verification part
+   - Do not make parallel implementation parts run duplicate full-build or full-test checks
 
 **Constraints:**
-- Parts do not run tests (handled by subsequent movements)
+- If tests or build verification are needed, run them as a dedicated single verification part after dependent implementation parts are complete
 - Do not modify files outside your responsibility (causes conflicts)

package/builtins/en/facets/instructions/unit-audit-plan.md

@@ -0,0 +1,13 @@
+Audit the target for unit test coverage before making changes.
+
+**What to do:**
+1. Enumerate the target production files, exported APIs, internal branches, error paths, boundary checks, and state transitions using Read, Glob, and Grep
+2. Read existing unit tests and map which behaviors are already covered
+3. Build a complete inventory of auditable behaviors for each target file
+4. Identify missing unit tests and prioritize them by regression risk
+5. Prepare an implementation order that covers the highest-risk gaps first
+
+**Important:**
+- Start from complete enumeration, not from a few obvious gaps
+- Do not stop after identifying a handful of missing tests
+- If the scope is unclear, state exactly which files or behaviors need clarification

package/builtins/en/facets/instructions/unit-audit-review.md

@@ -0,0 +1,16 @@
+Re-audit the files or behaviors that were judged insufficient in the previous unit audit.
+
+**Important:** Review the supervisor's verification results and understand:
+- Unaudited files or behaviors
+- Coverage claims lacking evidence
+- Specific feedback on issue quality or scope
+
+**What to do:**
+1. Read the flagged production files and corresponding tests in full
+2. Re-check the coverage claims for the flagged behaviors and identify what was previously skipped or weakly evidenced
+3. Update the audit result in issue-ready form with concrete evidence, explicit scope coverage, and missing-item reasons where applicable
+
+**Strictly prohibited:**
+- Modifying tests or production code
+- Claiming a behavior is covered without citing the actual test evidence
+- Skipping a flagged file or behavior because it "looks fine"

package/builtins/en/facets/instructions/unit-audit-supervise.md

@@ -0,0 +1,11 @@
+Verify the completeness and quality of the unit test audit itself.
+
+**Important:** Refer to the audit plan report: {report:01-unit-audit-plan.md}
+
+**Verification procedure:**
+1. Cross-check the full target inventory in the plan against the audited files and behaviors in the audit report
+2. Reject if any production file, exported API, branch, error path, boundary check, or state transition from the plan is missing from the audit result without an explicit reason
+3. Verify the audit report includes concrete evidence for both covered and missing behaviors, not just conclusions
+4. Verify the report includes the enumeration commands used and that they are sufficient to support the claimed scope
+5. Sample-read a few target production files and corresponding tests yourself to confirm the coverage claims are credible
+6. Require re-audit if issue titles, priorities, or recommended actions are too vague to be filed directly

package/builtins/en/facets/instructions/unit-audit-team-leader.md

@@ -0,0 +1,22 @@
+Decompose the unit audit, assign files to each part, and execute in parallel.
+
+**Important:** Refer to the plan report: {report:01-unit-audit-plan.md}
+
+**What to do:**
+1. Review the production file list, existing tests, and audited behavior inventory from the plan report
+2. Split the audit into 3 groups by module or test area
+3. Assign exclusive ownership so every target file and behavior is audited once
+
+**Each part's instruction MUST include:**
+- Assigned production files and corresponding test files
+- The behaviors, branches, error paths, and boundary checks to verify
+- Required audit procedure:
+  1. Read every assigned production file in full
+  2. Read the corresponding unit tests in full
+  3. Record covered and missing behaviors with concrete file evidence
+- Completion criteria: every assigned target has been audited and findings are reported in issue-ready form
+
+**Constraints:**
+- Each part is read-only
+- Do not modify tests or production code
+- Do not audit files outside the assignment

package/builtins/en/facets/knowledge/architecture.md

@@ -104,6 +104,99 @@ Prohibited patterns:
 - Error handling centralized (no try-catch scattered everywhere)
 - Business logic not leaking into Controller/View
 
+## Resolve at the Boundary
+
+Values such as config, options, providers, permissions, and paths should be resolved at the boundary before entering the core flow. Main processing should assume values are already resolved and should not keep asking config sources.
+
+| Criteria | Judgment |
+|----------|----------|
+| Create a resolved object such as `ExecutionContext` or `ResolvedOptions` at the entry point | OK |
+| Orchestration layers handle only resolved values | OK |
+| Lower layers reload global/project/env and resolve the same value again | REJECT |
+| Separate resolution functions exist for display and execution | REJECT |
+| Unresolved options are passed deep and later fixed with `??` | REJECT |
+
+```typescript
+// REJECT - Execution layer knows config sources directly
+async function executePiece(options) {
+  const engine = new PieceEngine({
+    provider: options.provider ?? globalConfig.provider,
+  });
+}
+
+class AgentRunner {
+  run(step, options) {
+    const provider = options.provider ?? resolveProviderFromConfig();
+    return getProvider(provider).call();
+  }
+}
+
+// OK - Resolve at the boundary, use resolved values internally
+async function executePiece(options) {
+  const context = resolveExecutionContext(options);
+  const engine = new PieceEngine(context);
+}
+
+class AgentRunner {
+  run(step, options) {
+    return getProvider(options.resolvedProvider).call();
+  }
+}
+```
+
+### Tell, Don't Ask
+
+Do not make lower layers inspect config sources and decide for themselves. Upper layers should tell them what to use by passing resolved values. Separate value selection from execution.
+
+| Pattern | Judgment |
+|---------|----------|
+| Upper layer passes a value such as `resolvedProvider` | OK |
+| Lower layer inspects `options` and resolves on its own | REJECT |
+| Execution object exposes only `run()` after `setup(config)` | OK |
+| Runtime branches call `getGlobalConfig()` during execution | REJECT |
+
+### Anti-Corruption Layer
+
+Precedence resolution and external config formats belong in a dedicated boundary layer. Pass only normalized internal values into the core model.
+
+| Pattern | Judgment |
+|---------|----------|
+| Encapsulate YAML/env/CLI differences in a resolver/adapter | OK |
+| Domain layer directly handles env var names or config key strings | REJECT |
+| Conversion from external form to internal form is centralized in one place | OK |
+| Same normalization logic is copied in multiple places | REJECT |
+
+### Phase Separation
+
+Separate input, interpretation, execution, and output into distinct stages. Iterative processing should, as much as possible, receive already interpreted input in bulk and then repeat only execution.
+
+| Criteria | Judgment |
+|----------|----------|
+| Convert raw input into a `Resolved*` type at the boundary before entering the core flow | OK |
+| Loop body handles only execution on resolved data | OK |
+| Config/env/options are interpreted inside every iteration | REJECT |
+| Each iteration packs `input -> interpret -> execute -> output` into one function | REJECT |
+| Even when optimization requires incremental handling, interpretation is isolated in a dedicated method | OK |
+
+```typescript
+// REJECT - Each iteration also interprets input
+for (const item of items) {
+  const resolved = resolveItem(item, rawOptions, config);
+  const result = execute(resolved);
+  output(result);
+}
+
+// OK - Interpret first, iterations only execute
+const resolvedItems = items.map((item) => resolveItem(item, rawOptions, config));
+
+for (const item of resolvedItems) {
+  const result = execute(item);
+  output(result);
+}
+```
+
+Even when interpretation must happen incrementally, keep `nextRawInput()`, `resolveInput()`, and `executeResolved()` as separate responsibilities. Performance constraints may compress phases, but must not mix responsibilities.
+
 ## Code Quality Detection
 
 **Explanatory Comment (What/How) Detection Criteria:**