takt 0.31.0 → 0.32.0

package/README.md

@@ -12,7 +12,7 @@ TAKT is built with TAKT itself (dogfooding).
 
 **Batteries included** — Architecture, security, and AI antipattern review criteria are built in. Ship code that meets a quality bar from day one.
 
-**Practical** — A tool for daily development, not demos. Talk to AI to refine requirements, queue tasks, and run them. Automatic worktree isolation, PR creation, and retry on failure.
+**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.
 
@@ -39,7 +39,7 @@ Optional:
 npm install -g takt
 ```
 
-### Talk to AI, then execute
+### Talk to AI and queue tasks
 
 ```
 $ takt
@@ -55,21 +55,24 @@ Select piece:
 [AI clarifies requirements and organizes the task]
 
 > /go
-```
 
-TAKT creates an isolated worktree, runs the piece (plan → implement → review → fix loop), and offers to create a PR when done.
+Proposed task:
+  ...
 
-### Queue tasks, then batch execute
+What would you like to do?
+    Execute now
+    Create GitHub Issue
+  ❯ Queue as task          # ← normal flow
+    Continue conversation
+```
 
-Use `takt` to queue multiple tasks, then execute them all at once:
+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.
 
 ```bash
-# Queue tasks through conversation
-takt
-> Refactor the auth module
-> /go          # queues the task
+# Execute queued tasks
+takt run
 
-# Or queue from GitHub Issues
+# You can also queue from GitHub Issues
 takt add #6
 takt add #12
 
@@ -77,6 +80,8 @@ 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.
+
 ### Manage results
 
 ```bash

package/builtins/en/facets/instructions/write-tests-first.md

@@ -12,14 +12,13 @@ Refer only to files within the Report Directory shown in the Piece Context. Do n
    - Does a new status/state merge into an existing workflow?
    - Does a new option propagate through a call chain to the endpoint?
    - If any apply, create integration tests
-5. Run the build (type check) to verify test code has no syntax errors
 
 **Test writing guidelines:**
 - Follow the project's existing test patterns (naming conventions, directory structure, helpers)
 - Write tests in Given-When-Then structure
 - One concept per test. Do not mix multiple concerns in a single test
 - Cover happy path, error cases, boundary values, and edge cases
-- Write tests that are expected to pass after implementation is complete
+- Write tests that are expected to pass after implementation is complete (build errors and test failures are expected at this stage)
 
 **Scope output contract (create at the start):**
 ```markdown
@@ -55,5 +54,3 @@ Small / Medium / Large
 - {Summary of actions taken}
 ## Changes made
 - {List of test files created}
-## Build results
-- {Build execution results}

package/builtins/en/facets/knowledge/cqrs-es.md

@@ -408,6 +408,56 @@ Checklist:
 | Query side tests don't create data via Command | Recommended |
 | Integration tests consider Axon async processing | Required |
 
+## Master Data and CRUD
+
+Not everything in a CQRS+ES system needs event sourcing. Master data (reference data) with simple characteristics is better implemented as plain CRUD — it's simpler and easier to maintain.
+
+However, don't mechanically decide "it's master data, so CRUD". The more criteria below that apply, the more CRUD is suitable. Conversely, if even one requirement calls for CQRS+ES, consider adopting it.
+
+**Criteria for determining CRUD is sufficient:**
+
+| Aspect | Leans CRUD | Leans CQRS+ES |
+|--------|-----------|---------------|
+| Business requirements | Just "manage X" with no special mentions | Specific business rules or constraints |
+| Logic evolution | Simple reference/update, no foreseeable complexity | State transitions or lifecycle may grow complex |
+| Change history / audit | No need to track "who changed what when" | Change history or audit trail required |
+| Domain events | Changes don't affect other aggregates or processes | Changes trigger downstream processes |
+| Consistency scope | Self-contained, no cross-aggregate consistency needed | Must maintain consistency with other aggregates |
+| Point-in-time queries | No "what was the state at time T" queries | Point-in-time queries required |
+
+**Typical CRUD candidates:**
+- Code masters such as prefecture/country codes
+- Classification masters such as categories and tags
+- Configuration values, constant tables
+
+**Cases where CQRS+ES is justified:**
+- Product master, but price change history tracking is needed
+- Organization master, but changes trigger permission recalculation
+- Business partner master, but has credit assessment state transitions
+
+```kotlin
+// CRUD is sufficient: Simple category master
+@Entity
+data class Category(
+    @Id val categoryId: String,
+    val name: String,
+    val displayOrder: Int
+)
+
+// CQRS+ES is appropriate: Product with price change history tracking
+data class Product(
+    val productId: String,
+    val currentPrice: Money
+) {
+    fun changePrice(newPrice: Money, reason: String): PriceChangedEvent {
+        require(newPrice.amount > BigDecimal.ZERO) { "Price must be positive" }
+        return PriceChangedEvent(productId, currentPrice, newPrice, reason)
+    }
+}
+```
+
+Even when implementing with CRUD, other aggregates in the CQRS+ES system reference CRUD entities by ID. The principle that CRUD entities don't directly access aggregate internal state still applies.
+
 ## Infrastructure Layer
 
 Check:

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

@@ -98,6 +98,56 @@ app.get('/user/:id', authorize('read:user'), (req, res) => {
 - Missing type checks → REJECT
 - No size limits set → REJECT
 
+## Logging & Masking
+
+Prevent sensitive information from leaking into logs and responses.
+
+**Never log:**
+- Passwords, tokens, API keys
+- Credit card numbers, personal identification numbers
+- Session IDs, authentication header values
+- Personal information (email, phone) unless necessary for debugging
+
+**Masking patterns:**
+
+```typescript
+// NG - Password exposed in logs
+logger.info('User login attempt', { email, password })
+
+// OK - Exclude sensitive fields
+logger.info('User login attempt', { email })
+```
+
+```kotlin
+// NG - Logging entire request object
+logger.info("Request: {}", request)
+
+// OK - Log only safe fields
+logger.info("Request: userId={}, action={}", request.userId, request.action)
+```
+
+**Structured logging field filtering:**
+
+When passing objects to log output, ensure `toString()` or JSON serialization does not include sensitive fields.
+
+```kotlin
+// NG - data class toString() includes password
+data class UserCredentials(val email: String, val password: String)
+
+// OK - Override toString() to mask sensitive fields
+data class UserCredentials(val email: String, val password: String) {
+    override fun toString(): String = "UserCredentials(email=$email, password=***)"
+}
+```
+
+| Criteria | Verdict |
+|----------|---------|
+| Log output contains passwords, tokens, or API keys | REJECT |
+| Error responses contain stack traces or internal paths | REJECT |
+| data class toString() exposes sensitive fields | REJECT |
+| Sensitive info can be output regardless of log level | REJECT |
+| Debug logs contain PII but disabled in production | Warning. Risk of misconfiguration |
+
 ## Cryptography
 
 - Use of weak crypto algorithms → REJECT

package/builtins/en/facets/knowledge/task-decomposition.md

@@ -2,15 +2,17 @@
 
 ## Decomposition Feasibility
 
-Before splitting a task into multiple parts, assess whether decomposition is appropriate. When decomposition is unsuitable, implementing in a single part is more efficient.
+Before splitting a task into multiple parts, assess whether decomposition is appropriate. Conditions that prohibit decomposition and REJECT criteria are defined in the Task Decomposition Policy. This section explains the underlying reasoning.
 
-| Criteria | Judgment |
-|----------|----------|
-| Changed files clearly separate into layers | Decompose |
-| Shared types/IDs span multiple parts | Single part |
-| Broad rename/refactoring | Single part |
-| Fewer than 5 files to change | Single part |
-| Same file needs editing by multiple parts | Single part |
+### Decision Criteria Table (Rationale)
+
+| Perspective | Detection Pattern | Recommended Judgment | Rationale (Why) |
+|-------------|-------------------|----------------------|-----------------|
+| Shared contracts (ID/type) | A new ID/type is defined in one part and referenced by another | Do not decompose (single part) | Producer/consumer mismatches in type, naming, and handoff are common |
+| Event chains | Both emitter and receiver must be changed together | Do not decompose (single part) | Bidirectional assumptions drift and cause runtime inconsistencies |
+| Interface changes | Existing signature change + multiple call-site updates required | Do not decompose (single part) | Missed call-site updates easily lead to build/runtime failures |
+| File ownership overlap | Same file assigned to multiple parts | Do not decompose (restructure plan) | Overwrites/conflicts create repeated REJECT in review cycles |
+| Layer independence | API/Domain/Infra boundaries are clear and dependencies are one-way | Decomposition allowed | Clear boundaries reduce coupling across parts |
 
 ### Detecting Cross-Cutting Concerns
 
@@ -20,17 +22,9 @@ When any of the following apply, independent parts cannot maintain consistency.
 - Both the event emitter and event receiver need changes
 - An existing interface signature changes, requiring updates to all call sites
 
-## File Exclusivity Principle
-
-When decomposing into multiple parts, each part's file ownership must be completely exclusive.
-
-| Criteria | Judgment |
-|----------|----------|
-| Same file edited by multiple parts | REJECT (causes conflicts) |
-| Type definition and consumer in different parts | Consolidate into the type definition part |
-| Test file and implementation file in different parts | Consolidate into the same part |
+## Grouping Priority
 
-### Grouping Priority
+When decomposition is appropriate, use the following criteria to group files.
 
 1. **By dependency direction** — keep dependency source and target in the same part
 2. **By layer** — domain layer / infrastructure layer / API layer

package/builtins/en/facets/policies/task-decomposition.md

@@ -0,0 +1,53 @@
+# Task Decomposition Policy
+
+Ensure decomposition quality for parallel parts.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Explicit decomposition judgment | Evaluate the knowledge base criteria table before decomposing; state the judgment explicitly |
+| File exclusivity | Each file is owned by exactly one part. No exceptions |
+| Dependency direction | If parts have dependencies, merge them into a single part |
+| Tests with implementation | Test files and corresponding implementation files belong to the same part |
+| Quality gates aggregate | Build/test execution belongs in a part that aggregates all other parts' results |
+
+## File Exclusivity
+
+When multiple parts edit the same file, sub-agents overwrite each other's changes.
+
+| Criteria | Judgment |
+|----------|----------|
+| Same file appears in multiple parts' assignments | REJECT |
+| Type definition file and consumer file in different parts | REJECT (merge into the type definition part) |
+| Assigned files described as "touch as needed on failure" or similar vague expressions | REJECT (determine files upfront) |
+| Test file and implementation file in different parts | REJECT |
+| Wildcard assignments (`src/**/*`) overlapping with another part's scope | REJECT |
+
+## Conditions That Prohibit Decomposition
+
+When any of the following apply, implement in a single part. Do not decompose.
+
+| Criteria | Judgment |
+|----------|----------|
+| Broad rename or refactor | Single part |
+| Shared types or IDs cross multiple parts | Single part |
+| Fewer than 5 files to change | Single part |
+| Existing interface signature change + updating all call sites | Single part |
+
+## Quality Gate Parts
+
+Parts responsible for build/test execution follow different rules from implementation parts.
+
+| Criteria | Judgment |
+|----------|----------|
+| Quality gate part includes implementation part files in its assignment | REJECT |
+| Quality gate split into multiple parts | REJECT (merge into one) |
+| Quality gate part's fix scope is "anything" | REJECT (specify target files upfront) |
+
+## Prohibited
+
+- **Skipping decomposition judgment** - decomposing without evaluating the knowledge criteria table
+- **Assigning the same file to multiple parts** - including via wildcard assignments
+- **Separating dependent changes** - putting type definitions and consumers, or event emitters and receivers, in different parts
+- **Parts with undefined file assignments** - vague assignments like "fix as needed" or "modify if required"

package/builtins/en/piece-categories.yaml

@@ -33,18 +33,20 @@ piece_categories:
       - terraform
   🔍 Review:
     pieces:
-      - review
-      - review-fix
-      - frontend-review
-      - frontend-review-fix
-      - backend-review
-      - backend-review-fix
-      - dual-review
-      - dual-review-fix
-      - dual-cqrs-review
-      - dual-cqrs-review-fix
-      - backend-cqrs-review
-      - backend-cqrs-review-fix
+      - review-default
+      - review-fix-default
+      - review-frontend
+      - review-fix-frontend
+      - review-backend
+      - review-fix-backend
+      - review-dual
+      - review-fix-dual
+      - review-dual-cqrs
+      - review-fix-dual-cqrs
+      - review-backend-cqrs
+      - review-fix-backend-cqrs
+      - review-takt-default
+      - review-fix-takt-default
   🧪 Testing:
     pieces:
       - unit-test
@@ -52,7 +54,8 @@ piece_categories:
   🎵 TAKT Development:
     pieces:
       - takt-default
-      - takt-default-review-fix
+      - review-takt-default
+      - review-fix-takt-default
   Others:
     pieces:
       - research

package/builtins/en/pieces/backend-cqrs-mini.yaml

@@ -15,7 +15,7 @@ loop_monitors:
     threshold: 3
     judge:
       persona: supervisor
-      instruction_template: loop-monitor-reviewers-fix
+      instruction: loop-monitor-reviewers-fix
       rules:
         - condition: converging (findings decreasing, fixes applied)
           next: fix_both

package/builtins/en/pieces/backend-cqrs.yaml

@@ -1,5 +1,5 @@
 name: backend-cqrs
-description: CQRS+ES, Security, QA Expert Review
+description: CQRS+ES development piece with test-first, AI review, 2-stage reviews, fix loops, and supervision
 piece_config:
   provider_options:
     codex:
@@ -10,15 +10,27 @@ max_movements: 30
 initial_movement: plan
 loop_monitors:
   - cycle:
-      - reviewers
+      - ai_review
+      - ai_fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction: loop-monitor-ai-fix
+      rules:
+        - condition: Healthy (making progress)
+          next: ai_review
+        - condition: Unproductive (no improvement)
+          next: reviewers_1
+  - cycle:
+      - reviewers_1
       - fix
     threshold: 3
     judge:
       persona: supervisor
-      instruction_template: loop-monitor-reviewers-fix
+      instruction: loop-monitor-reviewers-fix
       rules:
         - condition: converging (findings decreasing, fixes applied)
-          next: reviewers
+          next: reviewers_1
         - condition: unproductive (same findings repeating)
           next: supervise
 movements:
@@ -41,13 +53,53 @@ movements:
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
-        next: implement
+        next: write_tests
       - condition: Requirements are unclear and planning cannot proceed
         next: ABORT
     output_contracts:
       report:
         - name: plan.md
           format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - backend
+      - cqrs-es
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Test creation is complete
+        next: implement
+      - condition: Skipping test creation as target is not yet implemented
+        next: implement
+      - condition: Cannot proceed with test creation
+        next: plan
+      - condition: User input required for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-scope.md
+          format: coder-scope
+        - name: test-decisions.md
+          format: coder-decisions
   - name: implement
     edit: true
     persona: coder
@@ -106,7 +158,7 @@ movements:
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
-        next: reviewers
+        next: reviewers_1
       - condition: AI-specific issues detected
         next: ai_fix
     output_contracts:
@@ -159,9 +211,9 @@ movements:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
       - condition: ai_fix's judgment is valid (no fix needed)
-        next: reviewers
+        next: reviewers_1
     instruction: arbitrate
-  - name: reviewers
+  - name: reviewers_1
     parallel:
       - name: cqrs-es-review
         edit: false
@@ -186,6 +238,35 @@ movements:
           report:
             - name: cqrs-es-review.md
               format: cqrs-es-review
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+    rules:
+      - condition: all("approved")
+        next: reviewers_2
+      - condition: any("needs_fix")
+        next: fix
+  - name: reviewers_2
+    parallel:
       - name: security-review
         edit: false
         persona: security-reviewer
@@ -260,7 +341,7 @@ movements:
     pass_previous_response: false
     rules:
       - condition: Fix complete
-        next: reviewers
+        next: reviewers_1
       - condition: Cannot proceed, insufficient info
         next: plan
     instruction: fix

package/builtins/en/pieces/backend-mini.yaml

@@ -15,7 +15,7 @@ loop_monitors:
     threshold: 3
     judge:
       persona: supervisor
-      instruction_template: loop-monitor-reviewers-fix
+      instruction: loop-monitor-reviewers-fix
       rules:
         - condition: converging (findings decreasing, fixes applied)
           next: fix_both

package/builtins/en/pieces/backend.yaml

@@ -1,5 +1,5 @@
 name: backend
-description: Backend, Security, QA Expert Review
+description: Backend development piece with test-first, AI review, 2-stage reviews, fix loops, and supervision
 piece_config:
   provider_options:
     codex:
@@ -10,15 +10,27 @@ max_movements: 30
 initial_movement: plan
 loop_monitors:
   - cycle:
-      - reviewers
+      - ai_review
+      - ai_fix
+    threshold: 3
+    judge:
+      persona: supervisor
+      instruction: loop-monitor-ai-fix
+      rules:
+        - condition: Healthy (making progress)
+          next: ai_review
+        - condition: Unproductive (no improvement)
+          next: reviewers_1
+  - cycle:
+      - reviewers_1
       - fix
     threshold: 3
     judge:
       persona: supervisor
-      instruction_template: loop-monitor-reviewers-fix
+      instruction: loop-monitor-reviewers-fix
       rules:
         - condition: converging (findings decreasing, fixes applied)
-          next: reviewers
+          next: reviewers_1
         - condition: unproductive (same findings repeating)
           next: supervise
 movements:
@@ -40,13 +52,52 @@ movements:
     instruction: plan
     rules:
       - condition: Task analysis and planning is complete
-        next: implement
+        next: write_tests
       - condition: Requirements are unclear and planning cannot proceed
         next: ABORT
     output_contracts:
       report:
         - name: plan.md
           format: plan
+  - name: write_tests
+    edit: true
+    persona: coder
+    policy:
+      - coding
+      - testing
+    knowledge:
+      - backend
+      - architecture
+    provider_options:
+      claude:
+        allowed_tools:
+          - Read
+          - Glob
+          - Grep
+          - Edit
+          - Write
+          - Bash
+          - WebSearch
+          - WebFetch
+    required_permission_mode: edit
+    instruction: write-tests-first
+    rules:
+      - condition: Test creation is complete
+        next: implement
+      - condition: Skipping test creation as target is not yet implemented
+        next: implement
+      - condition: Cannot proceed with test creation
+        next: plan
+      - condition: User input required for clarification
+        next: write_tests
+        requires_user_input: true
+        interactive_only: true
+    output_contracts:
+      report:
+        - name: test-scope.md
+          format: coder-scope
+        - name: test-decisions.md
+          format: coder-decisions
   - name: implement
     edit: true
     persona: coder
@@ -104,7 +155,7 @@ movements:
     instruction: ai-review
     rules:
       - condition: No AI-specific issues found
-        next: reviewers
+        next: reviewers_1
       - condition: AI-specific issues detected
         next: ai_fix
     output_contracts:
@@ -156,9 +207,9 @@ movements:
       - condition: ai_review's findings are valid (fix required)
         next: ai_fix
       - condition: ai_fix's judgment is valid (no fix needed)
-        next: reviewers
+        next: reviewers_1
     instruction: arbitrate
-  - name: reviewers
+  - name: reviewers_1
     parallel:
       - name: arch-review
         edit: false
@@ -183,6 +234,35 @@ movements:
           report:
             - name: architect-review.md
               format: architecture-review
+      - name: testing-review
+        edit: false
+        persona: testing-reviewer
+        policy:
+          - review
+          - testing
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - WebSearch
+              - WebFetch
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        instruction: review-test
+        output_contracts:
+          report:
+            - name: testing-review.md
+              format: testing-review
+    rules:
+      - condition: all("approved")
+        next: reviewers_2
+      - condition: any("needs_fix")
+        next: fix
+  - name: reviewers_2
+    parallel:
       - name: security-review
         edit: false
         persona: security-reviewer
@@ -256,7 +336,7 @@ movements:
     pass_previous_response: false
     rules:
       - condition: Fix complete
-        next: reviewers
+        next: reviewers_1
       - condition: Cannot proceed, insufficient info
         next: plan
     instruction: fix

package/builtins/en/pieces/compound-eye.yaml

@@ -108,7 +108,7 @@ movements:
     rules:
       - condition: synthesis complete
         next: COMPLETE
-    instruction_template: |
+    instruction: |
       Two models (Claude / Codex) independently answered the same instruction.
       Synthesize their responses.