takt 0.31.0 → 0.32.1

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/e2e-coverage-implement.md

@@ -0,0 +1,26 @@
+Implement missing E2E tests based on the test case list.
+
+**Important:** Refer to the test plan report: {report:01-e2e-coverage-plan.md}
+
+**Note:** If Previous Response exists, this is a resubmission.
+Check which test cases were flagged as unimplemented and implement them.
+
+**What to do:**
+1. Review the numbered test case list from the test plan
+2. Implement tests following existing E2E test patterns (file structure, helpers, fixtures, mock strategy)
+3. Implement ALL cases in the test case list (do not stop after implementing just a few)
+4. Run E2E tests and confirm all tests pass
+5. Confirm existing E2E tests are not broken
+
+**Implementation constraints:**
+- Do not modify the existing E2E test framework
+- Write one scenario per concern with clear expected results
+- Follow existing fixture/helper/mock patterns for cases with external dependencies
+
+**Required output (include headings)**
+## Implemented Test Cases
+- {Test case list number and corresponding test file/test name}
+## Unimplemented Test Cases (if any)
+- {Number and reason for not implementing}
+## Test Results
+- {Execution command and results}

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

@@ -0,0 +1,38 @@
+Comprehensively identify all user operation routes in the application and create a list of missing E2E test cases.
+
+**Note:** If Previous Response exists, this is a resubmission.
+Review and revise the list based on that feedback.
+
+**What to do:**
+
+1. **Understand the E2E test infrastructure**
+   - Review existing E2E test directory structure, test runner, helpers, fixtures, and mock strategy
+   - Identify the test execution commands
+
+2. **Identify user operation entry points** (read CODE, not just documentation)
+   - For CLI: extract command definitions, subcommands, and options from code
+   - For Web: extract routing definitions, page transitions, and API endpoints from code
+   - Trace each entry point's handler and processing flow, identifying branches and state transitions
+
+3. **Deep-dive into UX variations**
+   - For each entry point, enumerate all possible routes a user can take
+   - Option/flag combinations that create different branches (e.g., `--pipeline` on/off, `--auto-pr` on/off)
+   - State-dependent branches (first run vs existing data, config present vs absent)
+   - Not just happy paths — error handling and recovery routes when things fail midway
+   - Permission/role-based routes
+   - External dependency state branches (connection success vs failure, normal vs abnormal response)
+
+4. **Cross-reference with existing E2E tests**
+   - Analyze what existing tests cover on a per-file basis
+   - Identify which routes are already covered by existing tests
+   - List uncovered routes as "missing test cases"
+
+5. **Create the test case list**
+   - Assign a unique number to every test case (this is the ledger supervisor uses for verification)
+   - Assign priority to each case (user impact × untested risk)
+   - **Do NOT abbreviate.** Don't stop at 1-2 cases — enumerate ALL identified routes
+
+**Strictly prohibited:**
+- Reading only docs/README and guessing test cases → PROHIBITED. Read the code
+- Cutting the list short with "there might be more" → PROHIBITED. Enumerate all
+- Including cases already covered by existing tests → PROHIBITED. Only list verified gaps

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

@@ -0,0 +1,21 @@
+Cross-reference the test case list from the plan with implementation results, and verify all cases have been implemented.
+
+**Important:** Refer to the test plan report: {report:01-e2e-coverage-plan.md}
+
+**Verification procedure:**
+
+1. **Cross-reference with test case list (most important)**
+   - Check each numbered test case from the plan report one by one
+   - Identify the corresponding test file and test name for each case
+   - Read the test file to confirm the case is actually tested
+   - List any cases without a corresponding test as "unimplemented"
+   - REJECT if even one unimplemented case exists
+
+2. **Test quality verification**
+   - Does each test correctly verify the intent of the test case?
+   - Are assertions appropriate (not just existence checks, but value verification)?
+   - Does the mock/fixture usage follow existing patterns?
+
+3. **Test execution verification**
+   - Run E2E tests and confirm all tests pass
+   - Confirm existing tests are not broken

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

@@ -1,5 +1,9 @@
 Use reports in the Report Directory and fix the issues raised by the reviewer.
 
+**Fix principles:**
+- When a finding includes a "suggested fix", follow it rather than inventing your own workaround
+- Fix the target code directly. Do not deflect findings by adding tests or documentation instead
+
 **Report reference policy:**
 - Use the latest review reports in the Report Directory as primary evidence.
 - Past iteration reports are saved as `{filename}.{timestamp}` in the same directory (e.g., `architect-review.md.20260304T123456Z`). For each report, run Glob with a `{report-name}.*` pattern, read up to 2 files in descending timestamp order, and understand persists / reopened trends before starting fixes.

package/builtins/en/facets/instructions/loop-monitor-ai-fix.md

@@ -7,6 +7,7 @@ is healthy (making progress) or unproductive (repeating the same issues).
 - AI Review results: {report:ai-review.md}
 
 **Judgment criteria:**
-- Are new issues being found/fixed in each cycle?
-- Are the same findings being repeated?
-- Are fixes actually being applied?
+- Are the same finding_ids persisting across multiple cycles?
+  - Same finding_id repeatedly persists → unproductive (stuck)
+  - Previous findings resolved and new findings appear as new → healthy (progressing)
+- Are fixes actually being applied to the code?

package/builtins/en/facets/instructions/loop-monitor-reviewers-fix.md

@@ -4,6 +4,8 @@ Review the latest review reports in the Report Directory and determine
 whether this loop is healthy (converging) or unproductive (diverging or oscillating).
 
 **Judgment criteria:**
-- Is the number of new / reopened findings decreasing each cycle?
-- Are the same family_tag findings not repeating (is persists not growing)?
+- Are the same finding_ids persisting across multiple cycles?
+  - Same finding_id repeatedly persists → unproductive (stuck)
+  - Previous findings resolved and new findings appear as new → healthy (converging)
 - Are fixes actually being applied to the code?
+- Is the number of new / reopened findings decreasing overall?

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

@@ -1,6 +1,7 @@
 Review the changes from a frontend development perspective.
 
 **Review criteria:**
+- Design fidelity (top priority when a design reference is provided)
 - Component design (separation of concerns, granularity)
 - State management (local vs. global decisions)
 - Performance (re-renders, memoization)
@@ -8,6 +9,12 @@ Review the changes from a frontend development perspective.
 - Data fetching patterns
 - TypeScript type safety
 
+**Design fidelity check (when a design reference exists):**
+1. Identify the design reference from the task order's referenced materials
+2. Compare design elements (layout, wording, colors, spacing) against implementation element by element
+3. For any discrepancy, check the decisions log to determine if it was intentional
+4. Report unintentional discrepancies as blocking issues
+
 **Note**: If this project does not include a frontend,
 proceed as no issues found.
 

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

@@ -0,0 +1,12 @@
+Understand the overall project structure and create a complete list of files to be audited for security.
+
+**What to do:**
+1. Identify the project's source code directories and list all files using Glob
+2. Understand the project's tech stack, frameworks, and major dependencies
+3. Classify each file's role briefly (API layer, domain layer, infrastructure layer, utilities, etc.)
+4. Identify files with high security risk (authentication, input handling, external communication, file operations, configuration, etc.)
+
+**Important:**
+- List ALL files without omission. Do not abbreviate
+- Include configuration files and test files
+- Even if the file count is large, list every single file

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

@@ -0,0 +1,22 @@
+Re-audit the files that were judged insufficient in the previous audit.
+
+**Important:** Review the supervisor's verification results and understand:
+- List of unaudited files
+- List of files flagged as insufficiently audited
+- Specific feedback
+
+**What to do:**
+1. **Read each flagged file in full using Read tool one by one**
+2. Review each file from a security perspective
+3. Report discovered issues with severity ratings
+
+**Strictly prohibited:**
+- Searching with Grep and only reviewing matching files → PROHIBITED
+- Reading only part of a file → PROHIBITED
+- Skipping a file because it "looks fine" → PROHIBITED
+
+**Required output (include headings):**
+## Re-audit Results
+- {Audit results for each file}
+## Detected Issues
+- {Issue details (severity, location, remediation)}

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

@@ -0,0 +1,20 @@
+Verify the completeness and quality of the security audit.
+
+**Important:** Refer to the plan report: {report:01-plan.md}
+
+**Verification procedure:**
+
+1. **Completeness verification (most important)**
+   - Cross-reference the file list from the plan report with files mentioned in the audit results
+   - List any files not mentioned in the audit results as "unaudited files"
+   - REJECT if even one unaudited file exists
+
+2. **Methodology verification**
+   - Check whether each file's audit result references specific code content
+   - If a file only says "no issues" without mentioning specific content checked, it may not have been actually Read → REJECT
+   - Check for signs that judgment was based solely on Grep keyword matching
+
+3. **Quality verification**
+   - Check whether severity classifications of detected issues are appropriate
+   - Read a few high-security-risk files yourself to verify no issues were missed
+   - Check whether there are too many false positives

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

@@ -0,0 +1,27 @@
+Decompose the security audit task, assign files to each part, and execute in parallel.
+
+**Important:** Refer to the plan report: {report:01-plan.md}
+
+**What to do:**
+
+1. Review the file list from the plan report and understand all files to be audited
+2. Split files into 3 groups by module/layer
+   - Distribute high-security-risk files (authentication, input handling, external communication, etc.) evenly across groups
+   - Keep related files (within the same module) in the same group when possible
+3. Assign exclusive file ownership to each part
+
+**Each part's instruction MUST include:**
+- **Assigned file list** (all file paths to review via Read)
+- **Audit procedure:**
+  1. **Read each assigned file in full using Read tool one by one** (do NOT abbreviate with Grep or partial reads)
+  2. Review each file from a security perspective
+  3. Report discovered issues with severity ratings
+- **Strictly prohibited:**
+  - Searching with Grep and only reviewing matching files → PROHIBITED. Read ALL files
+  - Reading only part of a file → PROHIBITED. Read the entire file
+  - Skipping a file because it "looks fine" → PROHIBITED. Review every file
+- **Completion criteria:** All assigned files have been Read in full, and audit results are reported for each file
+
+**Constraints:**
+- Each part is read-only. Do not modify code
+- Do not audit files outside your assignment (to prevent overlap)

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/e2e-testing.md

@@ -0,0 +1,89 @@
+# E2E Testing Knowledge
+
+## E2E Test Scope
+
+E2E tests verify the entire user operation flow. Their scope differs from unit and integration tests.
+
+| Test Type | Scope | Verification Target |
+|-----------|-------|-------------------|
+| Unit | Function/Class | Logic correctness |
+| Integration | Inter-module coupling | Data flow correctness |
+| E2E | Entire user operation flow | Behavior as seen by the user |
+
+| Criteria | Judgment |
+|----------|----------|
+| Writing E2E tests for logic that unit tests can cover | Warning. Consider moving to unit tests |
+| Verifying user operation flows | E2E test is appropriate |
+| Scenarios spanning multiple commands/pages | E2E test is appropriate |
+| Error message display verification | E2E test is appropriate |
+
+## UX Route Identification
+
+E2E test completeness depends on thorough UX route identification. Identify entry points from code, not documentation.
+
+### Entry Point Identification
+
+| Application Type | How to Find Entry Points |
+|-----------------|-------------------------|
+| CLI | Extract command definitions, subcommand registrations, option/flag definitions from code |
+| Web | Extract routing definitions, page component lists from code |
+| API | Extract endpoint definitions, router registrations from code |
+
+### Branch Patterns
+
+Exhaustively enumerate routes branching from each entry point.
+
+| Branch Pattern | Example |
+|---------------|---------|
+| Option/flag combinations | `--verbose` on/off, `--format json` vs `--format table` |
+| State-dependent branches | First run vs existing data, config present vs absent |
+| Permission/role | Admin vs regular user, authenticated vs unauthenticated |
+| External dependency state | Connection success vs timeout, normal vs error response |
+| Error recovery | Retry on midway failure, rollback |
+| Input variations | Valid input, invalid input, empty input, boundary values |
+
+
+## Mock Boundary Design
+
+In E2E tests, deciding "how far to run real code and where to start mocking" is critical.
+
+### Mock Design Principles
+
+- Run the application code under test as-is
+- Insert mocks at external service boundaries
+- Follow existing fixture/helper mock patterns
+- Check existing mock infrastructure before introducing new mechanisms
+
+## Flaky Test Prevention
+
+E2E tests are prone to non-deterministic failures.
+
+| Cause | Mitigation |
+|-------|-----------|
+| Timing dependency | Use explicit wait conditions (state-based waits, not fixed sleeps) |
+| Port conflicts | Assign random ports per test |
+| Filesystem residue | Create temp directories per test, cleanup on teardown |
+| Process leaks | Set timeouts and force-kill |
+| Environment dependency | Explicitly set up prerequisites for test execution |
+| Execution order dependency | Initialize state so each test runs independently |
+
+```typescript
+// NG - fixed sleep for timing
+await sleep(3000)
+expect(result).toBeDefined()
+
+// OK - condition-based wait
+await waitFor(() => expect(result).toBeDefined(), { timeout: 5000 })
+```
+
+## Test Case Management
+
+Manage test cases as a list to guarantee E2E test completeness.
+
+| Principle | Description |
+|-----------|-------------|
+| Numbered list | Assign a unique number to each test case and track implementation status |
+| Classify by entry point | Group by command/page/endpoint |
+| Prioritize | Determine priority by user impact × untested risk |
+| Cross-reference with existing tests | Check existing test coverage before adding new tests |
+

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