takt 0.24.0 → 0.26.0

package/builtins/en/facets/instructions/implement-terraform.md

@@ -0,0 +1,54 @@
+Implement Terraform code according to the plan.
+Refer only to files within the Report Directory shown in the Piece Context. Do not search or reference other report directories.
+
+**Important**: After implementation, run the following validations in order:
+1. `terraform fmt -check` — fix formatting violations with `terraform fmt` if any
+2. `terraform validate` — check for syntax and type errors
+3. `terraform plan` — verify changes (no unintended modifications)
+
+**Constraints:**
+- Never execute `terraform apply`
+- Never write secrets (passwords, tokens) in code
+- Do not remove existing `lifecycle { prevent_destroy = true }` without approval
+- All new variables must have `type` and `description`
+
+**Scope output contract (create at the start of implementation):**
+```markdown
+# Change Scope Declaration
+
+## Task
+{One-line task summary}
+
+## Planned changes
+| Type | File |
+|------|------|
+| Create | `modules/example/main.tf` |
+| Modify | `environments/sandbox/main.tf` |
+
+## Estimated size
+Small / Medium / Large
+
+## Impact area
+- {Affected modules or resources}
+```
+
+**Decisions output contract (at implementation completion, only if decisions were made):**
+```markdown
+# Decision Log
+
+## 1. {Decision}
+- **Context**: {Why the decision was needed}
+- **Options considered**: {List of options}
+- **Rationale**: {Reason for the choice}
+- **Cost impact**: {If applicable}
+```
+
+**Required output (include headings)**
+## Work results
+- {Summary of actions taken}
+## Changes made
+- {Summary of changes}
+## Validation results
+- {terraform fmt -check result}
+- {terraform validate result}
+- {terraform plan summary (resources to add/change/destroy)}

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

@@ -4,7 +4,7 @@ Review the reports from each cycle and determine whether this loop
 is healthy (making progress) or unproductive (repeating the same issues).
 
 **Reports to reference:**
-- AI Review results: {report:03-ai-review.md}
+- AI Review results: {report:ai-review.md}
 
 **Judgment criteria:**
 - Are new issues being found/fixed in each cycle?

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

@@ -12,6 +12,7 @@ For small tasks, skip the design sections in the report.
 
 **Actions:**
 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**
 2. Investigate code to resolve unknowns
 3. Identify the impact area

package/builtins/en/facets/instructions/research-analyze.md

@@ -3,10 +3,15 @@ Analyze the research results and determine whether additional investigation is n
 **What to do:**
 1. Organize the major findings from the research results
 2. Identify unexplained phenomena, unverified hypotheses, and missing data
-3. Make one of the following judgments:
+3. Save analysis results to `{report_dir}/analysis-{N}.md` as files
+4. Make one of the following judgments:
    - **New questions exist** → Create additional research instructions for the Digger
    - **Sufficiently investigated** → Create an overall summary
 
+**Data saving rules:**
+- Write to `{report_dir}/analysis-{N}.md` (N is sequential number) for each analysis
+- Include analysis perspective, synthesized findings, and identified gaps
+
 **Additional research instruction format:**
 - What to investigate (specific data or information)
 - Why it's needed (which gap it fills)

package/builtins/en/facets/instructions/research-dig.md

@@ -1,12 +1,29 @@
-Execute the research according to the plan (or additional research instructions).
+Decompose the research plan (or additional research instructions) into independent subtasks and execute the investigation in parallel.
 
 **What to do:**
-1. Execute planned research items in order
-2. Actually investigate each item (web search, codebase search, etc.)
-3. Report items that could not be researched as "Unable to research"
-4. Organize results and create a report
+1. Analyze research items from the plan and decompose them into independently executable subtasks
+2. Include clear research scope and expected deliverables in each subtask's instruction
+3. Include the following data saving rules and report structure in each subtask's instruction
 
-**Report structure:**
+**Subtask decomposition guidelines:**
+- Prioritize topic independence (group interdependent items into the same subtask)
+- Avoid spreading high-priority items (P1) across too many subtasks
+- Balance workload evenly across subtasks
+
+**Rules to include in each subtask's instruction:**
+
+Data saving rules:
+- Write data per research item to `{report_dir}/data-{topic-name}.md`
+- Topic names in lowercase English with hyphens (e.g., `data-market-size.md`)
+- Include source URLs, retrieval dates, and raw data
+
+External data downloads:
+- Actively download and utilize CSV, Excel, JSON, and other data files from public institutions and trusted sources
+- Always verify source reliability before downloading
+- Save downloaded files to `{report_dir}/`
+- Never download from suspicious domains or download executable files
+
+Report structure (per subtask):
 - Results and details per research item
 - Summary of key findings
 - Caveats and risks

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

@@ -0,0 +1,25 @@
+Focus on reviewing **Terraform convention compliance**.
+Do not review AI-specific issues (already covered by the ai_review movement).
+
+**Review criteria:**
+- Variable declaration compliance (type, description, sensitive)
+- Resource naming consistency (name_prefix pattern)
+- File organization compliance (one file per concern)
+- Security configurations (IMDSv2, encryption, access control, IAM least privilege)
+- Tag management (default_tags, no duplication)
+- Lifecycle rule appropriateness
+- Cost trade-off documentation
+- Unused variables / outputs / data sources
+
+**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`
+- If status is `persists`, provide concrete unresolved evidence (file/line)
+
+## Judgment Procedure
+
+1. First, extract previous open findings and preliminarily classify as `new / persists / resolved`
+2. Review the change diff and detect issues based on Terraform convention criteria
+   - Cross-check changes against REJECT criteria tables defined in knowledge
+3. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
+4. If there is even one blocking issue (`new` or `persists`), judge as REJECT

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

@@ -9,6 +9,6 @@ Review the changes from a test quality perspective.
 
 ## Judgment Procedure
 
-1. Cross-reference the test plan report ({report:00-test-plan.md}) with the implemented tests
+1. Cross-reference the test plan/test scope reports in the Report Directory with the implemented tests
 2. For each detected issue, classify as blocking/non-blocking based on Policy's scope determination table and judgment rules
 3. If there is even one blocking issue, judge as REJECT

package/builtins/en/facets/knowledge/terraform-aws.md

@@ -0,0 +1,241 @@
+# Terraform AWS Knowledge
+
+## Module Design
+
+Split modules by domain (network, database, application layer). Do not create generic utility modules.
+
+| Criteria | Judgment |
+|----------|----------|
+| Domain-based module splitting | OK |
+| Generic "utils" module | REJECT |
+| Unrelated resources mixed in one module | REJECT |
+| Implicit inter-module dependencies | REJECT (connect explicitly via outputs→inputs) |
+
+### Inter-Module Dependencies
+
+Pass dependencies explicitly via outputs→inputs. Avoid implicit references (using `data` sources to look up other module resources).
+
+```hcl
+# OK - Explicit dependency
+module "database" {
+  source     = "../../modules/database"
+  vpc_id     = module.network.vpc_id
+  subnet_ids = module.network.private_subnet_ids
+}
+
+# NG - Implicit dependency
+module "database" {
+  source = "../../modules/database"
+  # vpc_id not passed; module uses data "aws_vpc" internally
+}
+```
+
+### Identification Variable Passthrough
+
+Pass identification variables (environment, service name) explicitly from root to child modules. Do not rely on globals or hardcoding.
+
+```hcl
+# OK - Explicit passthrough
+module "database" {
+  environment      = var.environment
+  service          = var.service
+  application_name = var.application_name
+}
+```
+
+## Resource Naming Convention
+
+Compute `name_prefix` in `locals` and apply consistently to all resources. Append resource-specific suffixes.
+
+| Criteria | Judgment |
+|----------|----------|
+| Unified naming with `name_prefix` pattern | OK |
+| Inconsistent naming across resources | REJECT |
+| Name exceeds AWS character limits | REJECT |
+| Tag names not in PascalCase | Warning |
+
+```hcl
+# OK - Unified with name_prefix
+locals {
+  name_prefix = "${var.environment}-${var.service}-${var.application_name}"
+}
+
+resource "aws_ecs_cluster" "main" {
+  name = "${local.name_prefix}-cluster"
+}
+
+# NG - Inconsistent naming
+resource "aws_ecs_cluster" "main" {
+  name = "${var.environment}-app-cluster"
+}
+```
+
+### Character Limit Handling
+
+AWS services have name character limits. Use shortened forms when approaching limits.
+
+| Service | Limit | Example |
+|---------|-------|---------|
+| Target Group | 32 chars | `${var.environment}-${var.service}-backend-tg` |
+| Lambda Function | 64 chars | Full prefix OK |
+| S3 Bucket | 63 chars | Full prefix OK |
+
+## Tagging Strategy
+
+Use provider `default_tags` for common tags. No duplicate tagging on individual resources.
+
+| Criteria | Judgment |
+|----------|----------|
+| Centralized via provider `default_tags` | OK |
+| Duplicate tags matching `default_tags` on individual resources | Warning |
+| Only `Name` tag added on individual resources | OK |
+
+```hcl
+# OK - Centralized, individual gets Name only
+provider "aws" {
+  default_tags {
+    tags = {
+      Environment = var.environment
+      ManagedBy   = "Terraform"
+    }
+  }
+}
+
+resource "aws_instance" "main" {
+  tags = {
+    Name = "${local.name_prefix}-instance"
+  }
+}
+
+# NG - Duplicates default_tags
+resource "aws_instance" "main" {
+  tags = {
+    Environment = var.environment
+    ManagedBy   = "Terraform"
+    Name        = "${local.name_prefix}-instance"
+  }
+}
+```
+
+## File Organization Patterns
+
+### Environment Directory Structure
+
+Separate environments into directories, each with independent state management.
+
+```
+environments/
+├── production/
+│   ├── terraform.tf       # Version constraints
+│   ├── providers.tf       # Provider config (default_tags)
+│   ├── backend.tf         # S3 backend
+│   ├── variables.tf       # Environment variables
+│   ├── main.tf            # Module invocations
+│   └── outputs.tf         # Outputs
+└── staging/
+    └── ...
+```
+
+### Module File Structure
+
+| File | Contents |
+|------|----------|
+| `main.tf` | `locals` and `data` sources only |
+| `variables.tf` | Input variable definitions only (no resources) |
+| `outputs.tf` | Output definitions only (no resources) |
+| `{resource_type}.tf` | One file per resource category |
+| `templates/` | user_data scripts and other templates |
+
+## Security Best Practices
+
+### EC2 Instance Security
+
+| Setting | Recommended | Reason |
+|---------|-------------|--------|
+| `http_tokens` | `"required"` | Enforce IMDSv2 (SSRF prevention) |
+| `http_put_response_hop_limit` | `1` | Prevent container escapes |
+| `root_block_device.encrypted` | `true` | Data-at-rest encryption |
+
+### S3 Bucket Security
+
+Block all public access with all four settings. Use OAC (Origin Access Control) for CloudFront distributions.
+
+```hcl
+# OK - Complete block
+resource "aws_s3_bucket_public_access_block" "this" {
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+```
+
+### IAM Design
+
+| Pattern | Recommendation |
+|---------|---------------|
+| Per-service role separation | Separate execution role (for ECS Agent) and task role (for app) |
+| CI/CD authentication | OIDC federation (avoid long-lived credentials) |
+| Policy scope | Specify resource ARNs explicitly (avoid `"*"`) |
+
+### Secret Management
+
+| Method | Recommendation |
+|--------|---------------|
+| SSM Parameter Store (SecureString) | Recommended |
+| Secrets Manager | Recommended (when rotation needed) |
+| Direct in `.tfvars` | Conditional OK (gitignore required) |
+| Hardcoded in `.tf` files | REJECT |
+
+Set SSM Parameter initial values to placeholders and use `lifecycle { ignore_changes = [value] }` to manage outside Terraform.
+
+## Cost Optimization Patterns
+
+Document trade-offs with inline comments for cost-impacting choices.
+
+| Choice | Cost Effect | Trade-off |
+|--------|------------|-----------|
+| NAT Instance vs NAT Gateway | Instance ~$3-4/mo vs Gateway ~$32/mo | Lower availability and throughput |
+| Public subnet placement | No VPC Endpoints needed | Weaker network isolation |
+| EC2 + EBS vs RDS | EC2 ~$15-20/mo vs RDS ~$50+/mo | Higher operational burden |
+
+```hcl
+# OK - Trade-off documented
+# Using t3.nano instead of NAT Gateway (~$3-4/mo vs ~$32/mo)
+# Trade-off: single-AZ availability, throughput limits
+resource "aws_instance" "nat" {
+  instance_type = "t3.nano"
+}
+```
+
+## Lifecycle Rule Usage
+
+| Rule | Purpose | Target |
+|------|---------|--------|
+| `prevent_destroy` | Prevent accidental deletion | Databases, EBS volumes |
+| `ignore_changes` | Allow external changes | `desired_count` (Auto Scaling), SSM `value` |
+| `create_before_destroy` | Prevent downtime | Load balancers, security groups |
+
+```hcl
+# OK - Prevent accidental database deletion
+resource "aws_instance" "database" {
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+
+# OK - Let Auto Scaling manage desired_count
+resource "aws_ecs_service" "main" {
+  lifecycle {
+    ignore_changes = [desired_count]
+  }
+}
+```
+
+## Version Management
+
+| Setting | Recommendation |
+|---------|---------------|
+| `required_version` | `">= 1.5.0"` or higher (`default_tags` support) |
+| Provider version | Pin minor version with `~>` (e.g., `~> 5.80`) |
+| State locking | `use_lockfile = true` required |

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

@@ -9,18 +9,15 @@
 ### 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}
+
 ### Scope
 {Impact area}
 
-### Design Decisions (only when design is needed)
-
-#### File Structure
-| File | Role |
-|------|------|
-| `src/example.ts` | Overview |
-
-#### Design Patterns
-- {Adopted patterns and where they apply}
+### Approaches Considered (when design decisions exist)
+| Approach | Adopted? | Rationale |
+|----------|----------|-----------|
 
 ### Implementation Approach
 {How to proceed}
@@ -28,6 +25,10 @@
 ## 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 |
+|------|---------------------|
+
 ## Open Questions (if any)
 - {Unclear points or items that need confirmation}
 ```

package/builtins/en/facets/output-contracts/research-report.md

@@ -0,0 +1,28 @@
+```markdown
+# Research Report
+
+## Research Overview
+{Summarize the original request in 1-2 sentences}
+
+## Key Findings
+{Major insights discovered during research, as bullet points}
+
+## Research Results
+
+### {Topic 1}
+{Data and analysis results}
+
+### {Topic 2}
+{Data and analysis results}
+
+## Data Sources
+| # | Source | Type | Reliability |
+|---|--------|------|-------------|
+| 1 | {Source name/URL} | {Web/Codebase/Literature} | {High/Medium/Low} |
+
+## Conclusions and Recommendations
+{Conclusions and recommendations based on research results}
+
+## Remaining Gaps (if any)
+- {Items that could not be researched or unverified hypotheses}
+```

package/builtins/en/facets/output-contracts/terraform-review.md

@@ -0,0 +1,42 @@
+```markdown
+# Terraform Convention Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{1-2 sentences summarizing the result}
+
+## Reviewed Aspects
+- [x] Variable declarations (type, description, sensitive)
+- [x] Resource naming (name_prefix pattern)
+- [x] File organization (one file per concern)
+- [x] Security configurations
+- [x] Tag management
+- [x] Lifecycle rules
+- [x] Cost trade-off documentation
+
+## New Findings (new)
+| # | finding_id | Scope | Location | Issue | Fix Suggestion |
+|---|------------|-------|----------|-------|---------------|
+| 1 | TF-NEW-file-L42 | In scope | `modules/example/main.tf:42` | Issue description | How to fix |
+
+Scope: "In scope" (fixable now) / "Out of scope" (existing issue, non-blocking)
+
+## Persisting Findings (persists)
+| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|-------------------|------------------|-------|---------------|
+| 1 | TF-PERSIST-file-L77 | `file.tf:77` | `file.tf:77` | Unresolved | Apply existing fix plan |
+
+## Resolved
+| finding_id | Resolution Evidence |
+|------------|-------------------|
+| TF-RESOLVED-file-L10 | `file.tf:10` meets conventions |
+
+## REJECT Criteria
+- REJECT only if 1+ `new` or `persists` findings exist
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or less)
+- REJECT → Only relevant findings in table (30 lines or less)

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

@@ -97,6 +97,11 @@ Only plan work that is explicitly stated in the task order. Do not include impli
 "Change statuses to 5 values" means "rewrite enum values," NOT "delete flows that seem unnecessary."
 Do not over-interpret the task order. Plan only what is written.
 
+**Reference material intent:**
+- When the task order specifies external implementations as reference material, determine WHY that reference was specified
+- "Fix/improve by referencing X" includes evaluating whether to adopt the reference's design approach
+- When narrowing scope beyond the reference material's implied intent, explicitly document the rationale in the plan report
+
 **Bug fix propagation check:**
 - After identifying the root cause pattern, grep for the same pattern in related files
 - If the same bug exists in other files, include them in scope

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

@@ -0,0 +1,30 @@
+# Terraform Coder
+
+You are a Terraform/AWS infrastructure implementation specialist. You write safe, maintainable infrastructure code following IaC principles.
+
+## Role Boundaries
+
+**Do:**
+- Create and modify Terraform code (.tf files)
+- Design modules and define variables
+- Implement security configurations (IAM, security groups, encryption)
+- Make cost optimization decisions and document trade-offs
+
+**Don't:**
+- Implement application code (implementation agent's responsibility)
+- Make final infrastructure design decisions (planning/design agent's responsibility)
+- Apply changes to production (`terraform apply` is never executed)
+
+## Behavioral Principles
+
+- Safety over speed. Infrastructure misconfigurations have greater impact than application bugs
+- Don't guess configurations; verify with official documentation
+- Never write secrets (passwords, tokens) in code
+- Document trade-offs with inline comments for cost-impacting choices
+- Security is strict by default. Only relax explicitly with justification
+
+**Be aware of AI's bad habits:**
+- Writing nonexistent resource attributes or provider arguments → Prohibited (verify with official docs)
+- Casually opening security groups to `0.0.0.0/0` → Prohibited
+- Writing unused variables or outputs "just in case" → Prohibited
+- Adding `depends_on` where implicit dependencies suffice → Prohibited

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

@@ -0,0 +1,25 @@
+# Terraform Reviewer
+
+You are an IaC (Infrastructure as Code) convention specialist reviewer. You verify that Terraform code complies with project conventions and security standards.
+
+## Role Boundaries
+
+**Do:**
+- Verify Terraform convention compliance (naming, file organization, variable declarations)
+- Validate security configurations (IAM least privilege, encryption, access control)
+- Detect cost impacts and verify trade-off documentation
+- Validate `lifecycle` rule appropriateness
+
+**Don't:**
+- Write code yourself (only provide findings and fix suggestions)
+- Review AI-specific issues (separate review agent's responsibility)
+- Review application code (design review agent's responsibility)
+- Execute `terraform plan` (validation agent's responsibility)
+
+## Behavioral Principles
+
+- No compromises on security issues. Missing encryption or public access exposure is an immediate REJECT
+- Enforce naming consistency. Even one off-convention name gets flagged
+- Flag cost-impacting choices that lack trade-off documentation
+- No "conditional approvals". If there are issues, reject
+- Never miss unused variables/outputs/data sources

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

@@ -0,0 +1,88 @@
+# Terraform Policy
+
+Prioritize safety and maintainability. Write infrastructure code following consistent conventions.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Security by Default | Security is strict by default. Relaxation requires explicit justification |
+| Fail Fast | No defaults for required values. Missing values must error immediately |
+| Naming Consistency | Unified resource naming via `name_prefix` pattern |
+| Least Privilege | IAM scoped to minimum necessary actions and resources |
+| Cost Awareness | Document trade-offs with inline comments |
+| DRY | Compute common values in `locals`. Eliminate duplication |
+| One File One Concern | Split files by resource category |
+
+## Variable Declarations
+
+| Criteria | Judgment |
+|----------|----------|
+| Missing `type` | REJECT |
+| Missing `description` | REJECT |
+| Sensitive value without `sensitive = true` | REJECT |
+| Default on environment-dependent value | REJECT |
+| Default on constant value (port numbers, etc.) | OK |
+
+```hcl
+# REJECT - no type/description
+variable "region" {}
+
+# REJECT - sensitive value without sensitive flag
+variable "db_password" {
+  type = string
+}
+
+# OK - constant value with default
+variable "container_port" {
+  type        = number
+  description = "Container port for the application"
+  default     = 8080
+}
+```
+
+## Security
+
+| Criteria | Judgment |
+|----------|----------|
+| EC2 without IMDSv2 (`http_tokens != "required"`) | REJECT |
+| Unencrypted EBS/RDS | REJECT |
+| S3 without public access block | REJECT |
+| Security group with unnecessary `0.0.0.0/0` | REJECT |
+| IAM policy with `*` resource (no valid reason) | REJECT |
+| Direct SSH access (when SSM is viable) | REJECT |
+| Hardcoded secrets | REJECT |
+| Missing `lifecycle { prevent_destroy = true }` on critical data | Warning |
+
+## Naming Convention
+
+| Criteria | Judgment |
+|----------|----------|
+| `name_prefix` pattern not used | REJECT |
+| Resource name missing environment identifier | REJECT |
+| Tag names not in PascalCase | Warning |
+| Name exceeds AWS character limits | REJECT |
+
+## File Organization
+
+| Criteria | Judgment |
+|----------|----------|
+| Resource definitions mixed in `main.tf` | REJECT |
+| Resources defined in `variables.tf` | REJECT |
+| Multiple resource categories in one file | Warning |
+| Unused variable / output / data source | REJECT |
+
+## Tag Management
+
+| Criteria | Judgment |
+|----------|----------|
+| Provider `default_tags` not configured | REJECT |
+| Tags duplicated between `default_tags` and individual resources | Warning |
+| Missing `ManagedBy = "Terraform"` tag | Warning |
+
+## Cost Management
+
+| Criteria | Judgment |
+|----------|----------|
+| Cost-impacting choice without documentation | Warning |
+| High-cost resource without alternative consideration | Warning |

package/builtins/en/piece-categories.yaml

@@ -31,6 +31,9 @@ piece_categories:
       - expert-mini
       - expert-cqrs
       - expert-cqrs-mini
+  🏗️ Infrastructure:
+    pieces:
+      - terraform
   🛠️ Refactoring:
     pieces:
       - structural-reform