takt 0.32.0 → 0.32.2

package/builtins/en/facets/output-contracts/plan-frontend.md

@@ -0,0 +1,41 @@
+```markdown
+# Task Plan
+
+## Original Request
+{User's request as-is}
+
+## Analysis
+
+### Objective
+{What needs to be achieved}
+
+### Reference Material Findings (when reference material exists)
+{Overview of reference implementation's approach and key differences from current implementation}
+
+### Design Element Decisions (when design references exist)
+| Element | Keep/Change | Rationale |
+|------|-------------|-----------|
+
+### Scope
+{Impact area}
+
+### Approaches Considered (when design decisions exist)
+| Approach | Adopted? | Rationale |
+|----------|----------|-----------|
+
+### Implementation Approach
+{How to proceed}
+
+## Implementation Guidelines (only when design is needed)
+- {Guidelines the Coder should follow during implementation}
+
+## Out of Scope (only when items exist)
+| Item | Reason for exclusion |
+|------|---------------------|
+
+When design references exist:
+- {Excluded element name, why it is excluded, and why no substitute is taken now}
+
+## Open Questions (if any)
+- {Unclear points or items that need confirmation}
+```

package/builtins/en/facets/output-contracts/plan.md

@@ -22,6 +22,14 @@
 ### Implementation Approach
 {How to proceed}
 
+### Reachability and Launch Conditions (when adding/changing user-facing features)
+| Item | Content |
+|------|---------|
+| User entry point | {Menu/route/button/link/external caller, or explicitly say "none"} |
+| Callers/wiring to update | {Files or layers that must be updated} |
+| Launch conditions | {Auth, permission, URL condition, flags, etc.} |
+| Remaining gaps | {Any unresolved wiring, or "none"} |
+
 ## Implementation Guidelines (only when design is needed)
 - {Guidelines the Coder should follow during implementation}
 

package/builtins/en/facets/output-contracts/security-audit.md

@@ -0,0 +1,31 @@
+```markdown
+# Security Audit Report
+
+## Result: APPROVE / REJECT
+
+## Severity: None / Low / Medium / High / Critical
+
+## Audit Scope
+| # | File | Audited | Risk Classification |
+|---|------|---------|-------------------|
+| 1 | `src/file.ts` | ✅ | High / Medium / Low |
+
+## Detected Issues
+| # | Severity | Category | Location | Issue | Remediation |
+|---|----------|----------|----------|-------|-------------|
+| 1 | Critical | injection | `src/file.ts:42` | {issue description} | {remediation} |
+
+## Files with No Issues
+- {list of files where no issues were detected}
+
+## Recommendations (non-blocking)
+- {security improvement suggestions}
+
+## REJECT Criteria
+- REJECT if one or more High or Critical issues exist
+```
+
+**Cognitive load reduction rules:**
+- No issues → Audit scope table only (15 lines max)
+- Low/Medium only → + issues table (30 lines max)
+- High/Critical present → Full output

package/builtins/en/facets/personas/coder.md

@@ -19,6 +19,7 @@ You are the implementer. Focus on implementation, not design decisions.
 - Thoroughness over speed. Code correctness over implementation ease
 - Prioritize "works correctly" over "works for now"
 - Don't implement by guessing; report unclear points
+- When a design reference is provided, match UI appearance, structure, and wording to the design. Do not add, omit, or change anything on your own judgment
 - Work only within the specified project directory (reading external files for reference is allowed)
 
 **Reviewer's feedback is absolute. Your understanding is wrong.**

package/builtins/en/facets/personas/frontend-reviewer.md

@@ -12,6 +12,9 @@ The user interface is the only point of contact between the system and users. No
 
 ## Areas of Expertise
 
+### Design Fidelity
+- When a design reference is provided, verify implementation matches the design element by element
+
 ### Component Design
 - Separation of concerns and component granularity
 - Props design and data flow
@@ -34,6 +37,7 @@ The user interface is the only point of contact between the system and users. No
 
 ## Important
 
+- **Design fidelity first**: When a design reference exists, verify design match before evaluating UX quality
 - **Prioritize user experience**: UX over technical correctness
 - **Performance can't be fixed later**: Consider at design stage
 - **Accessibility is hard to retrofit**: Build in from the start

package/builtins/en/facets/policies/ai-antipattern.md

@@ -75,6 +75,49 @@ Verification approach:
 2. If the only difference is optional argument presence, unify with ternary or spread syntax
 3. If branches have different preprocessing, store results in a variable and make a single call
 
+## Callback + External Variable Capture Abuse
+
+AI tends to implement data retrieval via callbacks and external variable capture when return values would suffice.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Assign to external variable in callback | `let result; await f(x => { result = x })` | REJECT |
+| Get value via event handler | `emitter.on('data', d => { captured = d })` to synchronously get value | REJECT |
+| Build state across multiple callbacks | `forEach(item => { externalMap.set(...) })` to construct result | REJECT |
+
+```typescript
+// REJECT - Capturing external variable via callback
+let selectedMode: string | undefined;
+await promptUser(choices, (choice) => {
+  selectedMode = choice;
+});
+return selectedMode;
+
+// OK - Receive via return value
+const selectedMode = await promptUser(choices);
+return selectedMode;
+```
+
+Verification approach:
+1. Find places where callback functions assign to variables in the outer scope
+2. Check if the value can be returned as a function return value
+3. If possible, flag for rewriting to the return-value pattern
+
+## Inappropriate Response to Review Findings
+
+AI sometimes "addresses" review findings by adding tests or documentation that "verify the finding" instead of actually fixing the code.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Adding tests instead of fixing | "Remove unnecessary comments" → adds tests verifying comment presence | REJECT |
+| Adding docs instead of fixing | "DRY violation" → adds documentation explaining duplication is intentional | REJECT |
+| Changing unrelated files | Security finding → performs unrelated refactoring | REJECT |
+
+Verification approach:
+1. Check if the fix diff includes changes to the finding's target file and target lines
+2. If the fix consists only of new file additions, check whether those files "fix" the issue or merely "verify" it
+3. If tests are added as part of the fix, verify they test "correct behavior after the fix" (not "the finding itself")
+
 ## Context Fitness Assessment
 
 Does the code fit this specific project?

package/builtins/en/facets/policies/coding.md

@@ -204,13 +204,35 @@ return storage.upload(file, options)
 - UI/logic exceeding 50 lines → Separate
 - Has multiple responsibilities → Separate
 
+### Reachability When Adding Features
+
+When adding a new feature or screen, update the paths by which users reach it in the same change set. Framework-specific wiring belongs in domain knowledge.
+
+| Criteria | Judgment |
+|----------|----------|
+| A new feature is implemented but callers, entry points, or navigation are not updated | REJECT |
+| A user-facing feature is added without defining how users reach it | REJECT |
+| Implementation and reachability updates are made in the same change set | OK |
+| A temporary entry path is added and its purpose/removal condition is documented | OK |
+
 ### Dependency Direction
 
 - Upper layers → Lower layers (reverse direction prohibited)
 - Fetch data at the root (View/Controller) and pass it down
 - Children do not know about their parents
 
-### State Management
+### Align execution triggers with actual intent
+
+Dependencies and triggers must match the conditions under which the behavior should actually run again. Do not add triggers only to satisfy linting or implementation convenience if that changes runtime behavior.
+
+| Criteria | Judgment |
+|----------|----------|
+| Dependencies or triggers are expanded only for linting/convenience and create rerun loops | REJECT |
+| Initial processing reruns because of unrelated state changes or recreated callbacks | REJECT |
+| Rerun conditions correspond to URL, filters, explicit refresh actions, or other intended behavior | OK |
+| Initialization and later refetch triggers are designed separately | OK |
+
+## State Management
 
 - Confine state to where it is used
 - Children do not modify state directly (notify parents via events)
@@ -305,6 +327,73 @@ function formatDate(date: Date): string { ... }
 function formatPercentage(value: number): string { ... }
 ```
 
+## Same Implementation with Different Names (DRY Violation)
+
+AI tends to define the same logic under multiple function names.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Same implementation with different names | `copyFacets()` and `placeFacetFiles()` doing the same thing | REJECT |
+| Same parameter signature and body | Two functions taking the same params and doing the same work | REJECT |
+
+```typescript
+// REJECT - Same implementation exists under different names
+function copyFiles(src: string, dest: string): void {
+  for (const f of readdirSync(src)) {
+    copyFileSync(join(src, f), join(dest, f));
+  }
+}
+function placeFiles(src: string, dest: string): void {
+  for (const f of readdirSync(src)) {
+    copyFileSync(join(src, f), join(dest, f));
+  }
+}
+
+// OK - Consolidate into a single function
+function copyFiles(src: string, dest: string): void {
+  for (const f of readdirSync(src)) {
+    copyFileSync(join(src, f), join(dest, f));
+  }
+}
+```
+
+Verification approach:
+1. Check if newly added functions have bodies identical or nearly identical to existing functions
+2. Compare functions within the same file and within the same module
+3. If duplication is found, consolidate into one and unify call sites
+
+## Dangerous Stateful Regex Patterns
+
+Regular expressions with the `/g` flag are stateful (they retain `lastIndex`). Defining them at module scope and mixing `test()` and `replace()` causes unexpected results.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Module-scope `/g` regex used with `test()` | `const RE = /x/g; if (RE.test(s)) ...` | REJECT |
+| `/g` regex shared between `test()` and `replace()` | `RE.test(s)` followed by `s.replace(RE, ...)` | REJECT |
+
+```typescript
+// REJECT - Module-scope /g regex used with test()
+const PATTERN = /\{\{facet:(\w+)\}\}/g;
+function hasFacetRef(text: string): boolean {
+  return PATTERN.test(text);  // lastIndex advances, next call returns different result
+}
+
+// OK - Don't use /g for test(), or create new RegExp inside function
+const PATTERN_CHECK = /\{\{facet:(\w+)\}\}/;  // no /g
+const PATTERN_REPLACE = /\{\{facet:(\w+)\}\}/g;  // /g for replace
+function hasFacetRef(text: string): boolean {
+  return PATTERN_CHECK.test(text);
+}
+function replaceFacetRefs(text: string): string {
+  return text.replace(PATTERN_REPLACE, ...);
+}
+```
+
+Verification approach:
+1. Check if module-scope regexes have the `/g` flag
+2. Check if `/g` regexes are used with `test()`
+3. Check if the same regex is used with both `test()` and `replace()`
+
 ## Prohibited
 
 - **Fallbacks are prohibited by default** - Do not write fallbacks using `?? 'unknown'`, `|| 'default'`, or swallowing via `try-catch`. Propagate errors upward. If absolutely necessary, add a comment explaining why

package/builtins/en/facets/policies/design-fidelity.md

@@ -0,0 +1,51 @@
+# Design Fidelity Policy
+
+When a design reference is provided, match UI appearance, structure, and wording to the design.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Design is truth | When a design reference is provided, it is the single source of truth for UI |
+| Element coverage | Implement all elements present in the design. Do not omit any |
+| No unauthorized additions | Do not add elements not present in the design |
+| Wording match | Use labels, button text, and placeholders exactly as specified in the design |
+| Layout match | Match element placement order, direction, and hierarchy to the design |
+| Color and spacing match | Follow color values, margins, border-radius, and font sizes specified in the design |
+
+## Applicability
+
+This policy applies when the task order or its referenced materials include a design reference (UI samples, mockups, design files, etc.). When no design reference is provided, this policy does not apply.
+
+## Judgment Criteria
+
+| Criteria | Verdict |
+|----------|---------|
+| Element present in design is missing from implementation | REJECT |
+| Element not in design is independently added | REJECT |
+| Wording differs from design | REJECT |
+| Element placement order differs from design | REJECT |
+| Color values differ from design | REJECT |
+| Margins/spacing clearly differ from design | REJECT |
+| Adding edge-case UI not in design (loading, error, empty states) | OK |
+| Interpreting ambiguous parts of design (record rationale in decisions log) | OK |
+
+## Implementation Procedure
+
+1. Enumerate elements in the design reference (per screen/section)
+2. Verify layout, wording, colors, and spacing for each element
+3. Cross-check implementation against design element by element
+4. Record rationale in the decisions log for ambiguous parts of the design
+
+## Review Procedure
+
+1. Compare design reference and implementation element by element
+2. For each discrepancy, describe both "design specification" and "implementation state" concretely
+3. Check the decisions log to determine if the discrepancy is intentional
+4. Report unintentional discrepancies as blocking issues
+
+## Acceptable Cases
+
+- Edge-case UI not covered in the design (loading states, error displays, empty state displays)
+- Alternative implementations due to platform-specific constraints (record rationale)
+- Reasonable interpretation of insufficiently detailed parts of the design (record rationale)

package/builtins/en/facets/policies/design-planning.md

@@ -0,0 +1,52 @@
+# Design Planning Policy
+
+When a task includes design references, planning must make element inventory and scope decisions explicit.
+
+## Principles
+
+| Principle | Standard |
+|------|------|
+| Reference-first planning | When design references exist, planning treats them as primary input |
+| Element-level inventory | Differences are checked at the element level, not only at the screen level |
+| Explicit change decision | Each element includes a keep/change decision with rationale |
+| Scope exclusion accountability | If a design element is excluded, the reason must be stated |
+| Clear implementation boundary | The boundary between in-scope and out-of-scope elements is fixed during planning |
+
+## Applicability
+
+This policy applies to planning tasks whose task instructions or reference materials include design references. It does not apply when no design reference exists.
+
+## Decision Criteria
+
+| Criteria | Decision |
+|------|------|
+| Planning proceeds without listing the main design elements | REJECT |
+| There is no keep/change decision for each element | REJECT |
+| Scope is narrowed with vague statements such as "list only this time" without naming elements | REJECT |
+| Out-of-scope elements do not include an exclusion rationale | REJECT |
+| Design interpretation is ambiguous but the rationale is recorded | OK |
+
+## Planning Judgment
+
+Planning inventories the design reference without dropping elements that materially affect the UI or flow.
+
+Inventory viewpoints:
+- Check not only major sections, but also detailed flows, modals, action controls, and state displays
+- Record the current implementation difference and keep/change decision for each element
+- When keeping the existing implementation, cite the target file and rationale
+
+## Scope Decisions
+
+If a design-referenced element is placed out of scope, planning records at least:
+
+- the excluded element name
+- the reason for exclusion
+- the reason no substitute implementation is taken now
+
+Do not split out design-referenced elements as "another task" without explicit rationale.
+
+## Prohibited
+
+- **Planning with only coarse screen-level summaries** - causes missing element coverage
+- **Narrowing the intent of the reference without rationale** - misaligns implementation and review
+- **Omitting the explanation for out-of-scope elements** - makes later movements ambiguous

package/builtins/en/facets/policies/qa.md

@@ -26,3 +26,18 @@
 | @ts-ignore, @ts-expect-error without reason | Warning |
 | eslint-disable without reason | Warning |
 | Usage of deprecated APIs | Warning |
+
+## Post-Write Side Effect Check
+
+When code writes files or directories and then scans/reads them, verify that the written files are not unintentionally included in the scan target.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Scanning the output directory | Scanning for syntax after copying facets to the same directory | REJECT |
+| Reading back temp files | Writing to a temp directory then processing all files in it | REJECT |
+| Self-referential processing | Generated files becoming input for the next processing pipeline | Warning |
+
+Verification approach:
+1. Identify places where directory scans (readdir, glob, etc.) happen after file writes
+2. Check if the scan target includes the write destination
+3. If included, check whether an exclusion filter exists

package/builtins/en/facets/policies/testing.md

@@ -29,7 +29,9 @@ Every behavior change requires a corresponding test, and every bug fix requires
 |----------|--------|
 | High | Business logic, state transitions |
 | Medium | Edge cases, error handling |
-| Low | Simple CRUD, UI appearance |
+| Low | Simple CRUD |
+
+**Note:** When a design reference is provided, UI appearance verification is elevated to medium priority. Refer to the Design Fidelity Policy.
 
 ## Test Structure: Given-When-Then
 
@@ -64,6 +66,37 @@ Test names describe expected behavior. Use the `should {expected behavior} when
 - Arrange-Act-Assert pattern (equivalent to Given-When-Then)
 - Avoid magic numbers and magic strings
 
+## Refetch loop regressions
+
+When a page performs initial loading, tests must prove that the load does not rerun because of unrelated re-renders, loading toggles, or Context callback identity changes.
+
+| Criteria | Verdict |
+|----------|---------|
+| Initial load bug fix has no regression test for duplicate API calls | REJECT |
+| Tests only verify that loading happened once, not that it stayed stable after rerender | Warning |
+| Page tests assert call count stability across rerender or state updates | OK |
+
+## Reachability regressions
+
+When adding or changing user-facing features or screens, tests or equivalent verification must prove that users can still reach the feature.
+
+| Criteria | Verdict |
+|----------|---------|
+| A new screen or feature is added with no verification of entry path or launch conditions | REJECT |
+| Only isolated component rendering is tested, without verifying reachability from an entry point | Warning |
+| The feature is verified reachable from an actual entry point such as a route, menu, button, link, or external caller | OK |
+
+## UI library integration regressions
+
+When introducing or changing major third-party UI components such as data grids, date pickers, virtualized lists, or charts, tests must prove that the real component mounts without crashing.
+
+| Criteria | Verdict |
+|----------|---------|
+| A major third-party UI component is added or changed without a regression test that mounts the real component | REJECT |
+| Prop compatibility is checked only through shallow mocks or existence checks | Warning |
+| The screen is rendered from its real entry path and the primary UI mounts without exceptions | OK |
+| The primary UI component is also rendered directly with representative props | OK |
+
 ## Test Strategy
 
 - Prefer unit tests for logic, integration tests for boundaries
@@ -81,6 +114,26 @@ Verify data flow coupling that unit tests alone cannot cover.
 | New option propagating through a call chain to the endpoint | End-to-end chain coupling test required |
 | All module-level unit tests pass | Unit tests alone are sufficient (when none of the above apply) |
 
+## Unit Test Criteria
+
+| Criteria | Verdict |
+|----------|---------|
+| Mocking the internal implementation of the test target (testing implementation, not behavior) | REJECT |
+| Sharing and mutating fixtures between tests | REJECT. Loss of test independence |
+| Mock return values diverging from actual types | Warning. Use type-safe mocks |
+| Only testing happy paths without boundary values | Warning |
+
+## E2E Test Criteria
+
+| Criteria | Verdict |
+|----------|---------|
+| Hitting production APIs without mocking external calls | REJECT. Test reproducibility is lost |
+| Mocking the core logic under test | REJECT. Defeats the purpose of E2E |
+| Using fixed sleep for timing synchronization | REJECT. Use state-based waits |
+| Sharing state between tests | Warning. Test independence is compromised |
+| Only testing happy paths without error flows | Warning |
+| Writing E2E tests for logic that unit tests can cover | Warning |
+
 ## Test Environment Isolation
 
 Tie test infrastructure configuration to test scenario parameters. Hardcoded assumptions break under different scenarios.

package/builtins/en/piece-categories.yaml

@@ -47,10 +47,11 @@ piece_categories:
       - review-fix-backend-cqrs
       - review-takt-default
       - review-fix-takt-default
+      - security-audit
   🧪 Testing:
     pieces:
-      - unit-test
-      - e2e-test
+      - fill-unit
+      - fill-e2e
   🎵 TAKT Development:
     pieces:
       - takt-default

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

@@ -70,6 +70,8 @@ movements:
       - backend
       - cqrs-es
       - architecture
+      - unit-testing
+      - e2e-testing
     provider_options:
       claude:
         allowed_tools:
@@ -244,6 +246,9 @@ movements:
         policy:
           - review
           - testing
+        knowledge:
+          - unit-testing
+          - e2e-testing
         provider_options:
           claude:
             allowed_tools:

package/builtins/en/pieces/backend.yaml

@@ -68,6 +68,8 @@ movements:
     knowledge:
       - backend
       - architecture
+      - unit-testing
+      - e2e-testing
     provider_options:
       claude:
         allowed_tools:
@@ -240,6 +242,9 @@ movements:
         policy:
           - review
           - testing
+        knowledge:
+          - unit-testing
+          - e2e-testing
         provider_options:
           claude:
             allowed_tools:

package/builtins/en/pieces/default.yaml

@@ -83,6 +83,8 @@ movements:
       - testing
     knowledge:
       - architecture
+      - unit-testing
+      - e2e-testing
     provider_options:
       claude:
         allowed_tools:

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

@@ -25,6 +25,8 @@ movements:
   - name: plan
     edit: false
     persona: planner
+    policy:
+      - design-planning
     knowledge:
       - frontend
       - backend
@@ -51,13 +53,14 @@ movements:
     output_contracts:
       report:
         - name: plan.md
-          format: plan
+          format: plan-frontend
   - name: implement
     edit: true
     persona: coder
     policy:
       - coding
       - testing
+      - design-fidelity
     knowledge:
       - frontend
       - backend
@@ -163,6 +166,7 @@ movements:
         policy:
           - coding
           - testing
+          - design-fidelity
         knowledge:
           - frontend
           - backend
@@ -191,6 +195,7 @@ movements:
         policy:
           - coding
           - testing
+          - design-fidelity
         knowledge:
           - frontend
           - backend
@@ -223,6 +228,7 @@ movements:
     policy:
       - coding
       - testing
+      - design-fidelity
     knowledge:
       - frontend
       - backend
@@ -256,6 +262,7 @@ movements:
     policy:
       - coding
       - testing
+      - design-fidelity
     knowledge:
       - frontend
       - backend

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

@@ -37,6 +37,8 @@ movements:
   - name: plan
     edit: false
     persona: planner
+    policy:
+      - design-planning
     knowledge:
       - frontend
       - backend
@@ -60,13 +62,14 @@ movements:
     output_contracts:
       report:
         - name: plan.md
-          format: plan
+          format: plan-frontend
   - name: implement
     edit: true
     persona: coder
     policy:
       - coding
       - testing
+      - design-fidelity
     session: refresh
     knowledge:
       - frontend
@@ -133,6 +136,7 @@ movements:
     policy:
       - coding
       - testing
+      - design-fidelity
     session: refresh
     knowledge:
       - frontend
@@ -204,7 +208,9 @@ movements:
       - name: frontend-review
         edit: false
         persona: frontend-reviewer
-        policy: review
+        policy:
+          - review
+          - design-fidelity
         knowledge: frontend
         provider_options:
           claude:
@@ -276,6 +282,7 @@ movements:
     policy:
       - coding
       - testing
+      - design-fidelity
     knowledge:
       - frontend
       - backend
@@ -333,6 +340,7 @@ movements:
     policy:
       - coding
       - testing
+      - design-fidelity
     knowledge:
       - frontend
       - backend