takt 0.28.1 → 0.30.0

package/README.md

@@ -22,13 +22,15 @@ TAKT is built with TAKT itself (dogfooding).
 
 Choose one:
 
-- **Provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed
+- **Provider CLIs**: [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed
 - **Direct API**: Anthropic / OpenAI / OpenCode API Key (no CLI required)
 
 Optional:
 
 - [GitHub CLI](https://cli.github.com/) (`gh`) — for `takt #N` (GitHub Issue tasks)
 
+> **OAuth and API key usage:** Whether OAuth or API key access is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.
+
 ## Quick Start
 
 ### Install
@@ -140,7 +142,6 @@ See the [Builtin Catalog](./docs/builtin-catalog.md) for all pieces and personas
 | `takt run` | Execute all pending tasks |
 | `takt list` | Manage task branches (merge, retry, instruct, delete) |
 | `takt #N` | Execute GitHub Issue as task |
-| `takt switch` | Switch active piece |
 | `takt eject` | Copy builtin pieces/facets for customization |
 | `takt repertoire add` | Install a repertoire package from GitHub |
 

package/builtins/en/config.yaml

@@ -4,22 +4,15 @@
 # =====================================
 # General settings (piece-independent)
 # =====================================
+# Note: this template contains global-only settings for ~/.takt/config.yaml.
 language: en        # UI language: en | ja
-log_level: info     # Log level: debug | info | warn | error
-provider: claude    # Default provider: claude | codex | opencode | mock
-# model: sonnet     # Optional model name passed to provider
 
 # Execution control
 # worktree_dir: ~/takt-worktrees   # Base directory for shared clone execution
-# auto_pr: false                   # Auto-create PR after worktree execution
-branch_name_strategy: ai      # Branch strategy: romaji | ai
-concurrency: 2                  # Concurrent task execution for takt run (1-10)
-# task_poll_interval_ms: 500       # Polling interval in ms during takt run (100-5000)
 # prevent_sleep: false             # Prevent macOS idle sleep while running
+# auto_fetch: false                # Fetch before clone to keep shared clones up-to-date
 
 # Output / notifications
-# minimal_output: false            # Minimized output for CI logs
-# verbose: false                   # Verbose output mode
 # notification_sound: true         # Master switch for sounds
 # notification_sound_events:       # Per-event sound toggle (unset means true)
 #   iteration_limit: true
@@ -27,74 +20,28 @@ concurrency: 2                  # Concurrent task execution for takt run (1-10)
 #   piece_abort: true
 #   run_complete: true
 #   run_abort: true
-# observability:
-#   provider_events: false         # Persist provider stream events
-# analytics:
-#   enabled: true                  # Enable analytics metrics collection
-#   events_path: ~/.takt/analytics/events  # Analytics event directory
-#   retention_days: 30             # Analytics event retention (days)
+# verbose: false                   # Shortcut: enable trace/debug and set logging.level=debug
+# logging:
+#   level: info                    # Log level for console and file output
+#   trace: true                    # Generate human-readable execution trace report (trace.md)
+#   debug: false                   # Enable debug.log + prompts.jsonl
+#   provider_events: false          # Persist provider stream events
 
 # Credentials (environment variables take priority)
 # anthropic_api_key: "sk-ant-..." # Claude API key
 # openai_api_key: "sk-..."         # Codex/OpenAI API key
+# gemini_api_key: "..."            # Gemini API key
+# google_api_key: "..."            # Google API key
+# groq_api_key: "..."              # Groq API key
+# openrouter_api_key: "..."        # OpenRouter API key
 # opencode_api_key: "..."          # OpenCode API key
 # codex_cli_path: "/absolute/path/to/codex"  # Absolute path to Codex CLI
 
-# Pipeline
-# pipeline:
-#   default_branch_prefix: "takt/"             # Prefix for pipeline-created branches
-#   commit_message_template: "feat: {title} (#{issue})"  # Commit template
-#   pr_body_template: |                          # PR body template
-#     ## Summary
-#     {issue_body}
-#     Closes #{issue}
-
 # Misc
 # bookmarks_file: ~/.takt/preferences/bookmarks.yaml  # Bookmark file location
 
-# =====================================
-# Piece-related settings (global defaults)
-# =====================================
-# 1) Route provider/model per persona
-# persona_providers:
-#   coder:
-#     provider: codex    # Run coder persona on Codex
-#     model: o3-mini     # Use o3-mini model (optional)
-#   reviewer:
-#     provider: claude   # Run reviewer persona on Claude
-
-# 2) Provider options
-#    Priority (for piece-capable keys such as provider/model/provider_options):
-#    global < piece < project < env
-# provider_options:
-#   codex:
-#     network_access: true      # Allow network access for Codex
-#   opencode:
-#     network_access: true      # Allow network access for OpenCode
-#   claude:
-#     sandbox:
-#       allow_unsandboxed_commands: false   # true allows unsandboxed execution for listed commands
-#       excluded_commands:
-#         - "npm publish"                  # Commands excluded from sandbox
-
-# 3) Movement permission policy
-# provider_profiles:
-#   codex:
-#     default_permission_mode: full         # Base permission: readonly | edit | full
-#     movement_permission_overrides:
-#       ai_review: readonly                 # Per-movement override
-#   claude:
-#     default_permission_mode: edit
-
-# 4) Runtime preparation before execution (recommended: enabled)
-runtime:
-  prepare:
-    - gradle      # Prepare Gradle cache/env under .runtime
-    - node        # Prepare npm cache/env under .runtime
-
-# 5) Piece list / categories
+# Piece list / categories
 # enable_builtin_pieces: true                             # Enable built-in pieces from builtins/{lang}/pieces
 # disabled_builtins:
 #   - magi                                                # Built-in piece names to disable
 # piece_categories_file: ~/.takt/preferences/piece-categories.yaml  # Category definition file
-# interactive_preview_movements: 3                        # Preview movement count in interactive mode (0-10)

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

@@ -1,10 +1,16 @@
-Address the reviewer's feedback.
-Use reports in the Report Directory shown in the Piece Context and fix the issues raised by the reviewer.
-Use files in the Report Directory as primary evidence. If additional context is needed, you may consult Previous Response and conversation history as secondary sources (Previous Response may be unavailable). If information conflicts, prioritize reports in the Report Directory and actual file contents.
+Use reports in the Report Directory and fix the issues raised by the reviewer.
 
-**Important**: After fixing, run both build and tests.
-- Build verification is mandatory. Run the build (type check) and verify there are no type errors
-- Running tests is mandatory. After build succeeds, always run tests and verify results
+**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.
+
+**Completion criteria (all must be satisfied):**
+- All findings in this iteration (new / reopened) have been fixed
+- Potential occurrences of the same `family_tag` have been fixed simultaneously (no partial fixes that cause recurrence)
+- At least one regression test per `family_tag` has been added (mandatory for config-contract and boundary-check findings)
+- Findings with the same `family_tag` from multiple reviewers have been merged and addressed as one fix
+
+**Important**: After fixing, run the build (type check) and tests.
 
 **Required output (include headings)**
 ## Work results
@@ -15,5 +21,11 @@ Use files in the Report Directory as primary evidence. If additional context is
 - {Build execution results}
 ## Test results
 - {Test command executed and results}
+## Convergence gate
+| Metric | Count |
+|--------|-------|
+| new (fixed in this iteration) | {N} |
+| reopened (recurrence fixed) | {N} |
+| persists (carried over, not addressed this iteration) | {N} |
 ## Evidence
 - {List key points from files checked/searches/diffs/logs}

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

@@ -0,0 +1,9 @@
+The reviewers → fix loop has repeated {cycle_count} times.
+
+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 fixes actually being applied to the code?

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

@@ -3,6 +3,8 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 
 **Review criteria:**
 - Structural and design validity
+- Modularization (high cohesion, low coupling, no circular dependencies)
+- Functionalization (single responsibility per function, operation discoverability, consistent abstraction level)
 - Code quality
 - Appropriateness of change scope
 - Test coverage
@@ -10,6 +12,12 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 - Call chain verification
 - Scattered hardcoding of contract strings (file names, config key names)
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

package/builtins/en/facets/instructions/review-cqrs-es.md

@@ -11,6 +11,12 @@ AI-specific issue review is not needed (already covered by the ai_review movemen
 **Note**: If this project does not use the CQRS+ES pattern,
 review from a general domain design perspective instead.
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the CQRS and Event Sourcing criteria above

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

@@ -11,6 +11,12 @@ Review the changes from a frontend development perspective.
 **Note**: If this project does not include a frontend,
 proceed as no issues found.
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the frontend development criteria above

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

@@ -7,6 +7,12 @@ Review the changes from a quality assurance perspective.
 - Logging and monitoring
 - Maintainability
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

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

@@ -6,6 +6,12 @@ Review the changes from a requirements fulfillment perspective.
 - Whether changes outside the scope (scope creep) have crept in
 - Whether there are any partial or missing implementations
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

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

@@ -4,6 +4,12 @@ Review the changes from a security perspective. Check for the following vulnerab
 - Data exposure risks
 - Cryptographic weaknesses
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Review the change diff and detect issues based on the security criteria above

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

@@ -11,6 +11,12 @@ Do not review AI-specific issues (already covered by the ai_review movement).
 - Cost trade-off documentation
 - Unused variables / outputs / data sources
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 **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`

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

@@ -7,6 +7,12 @@ Review the changes from a test quality perspective.
 - Completeness (unnecessary tests, missing cases)
 - Appropriateness of mocks and fixtures
 
+
+**Design decisions reference:**
+Review {report:coder-decisions.md} to understand the recorded design decisions.
+- Do not flag intentionally documented decisions as FP
+- However, also evaluate whether the design decisions themselves are sound, and flag any problems
+
 ## Judgment Procedure
 
 1. Cross-reference the test plan/test scope reports in the Report Directory with the implemented tests

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

@@ -15,22 +15,27 @@
 | Scope | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Category | Location | Issue | Fix Suggestion |
-|---|------------|----------|----------|-------|----------------|
-| 1 | AI-NEW-src-file-L23 | Hallucinated API | `src/file.ts:23` | Non-existent method | Replace with existing API |
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | AI-NEW-src-file-L23 | hallucination | Hallucinated API | `src/file.ts:23` | Non-existent method | Replace with existing API |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
-| 1 | AI-PERSIST-src-file-L42 | `src/file.ts:42` | `src/file.ts:42` | Still unresolved | Apply prior fix plan |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | AI-PERSIST-src-file-L42 | hallucination | `src/file.ts:42` | `src/file.ts:42` | Still unresolved | Apply prior fix plan |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | AI-RESOLVED-src-file-L10 | `src/file.ts:10` no longer contains the issue |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | AI-REOPENED-src-file-L55 | hallucination | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

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

@@ -15,24 +15,29 @@
 - [x] Call chain verification
 
 ## Current Iteration Findings (new)
-| # | finding_id | Scope | Location | Issue | Fix Suggestion |
-|---|------------|-------|----------|-------|----------------|
-| 1 | ARCH-NEW-src-file-L42 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
+|---|------------|------------|-------|----------|-------|----------------|
+| 1 | ARCH-NEW-src-file-L42 | design-violation | In-scope | `src/file.ts:42` | Issue description | Fix approach |
 
 Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
-| 1 | ARCH-PERSIST-src-file-L77 | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | ARCH-PERSIST-src-file-L77 | design-violation | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | ARCH-RESOLVED-src-file-L10 | `src/file.ts:10` now satisfies the rule |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | ARCH-REOPENED-src-file-L55 | design-violation | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

package/builtins/en/facets/output-contracts/cqrs-es-review.md

@@ -15,13 +15,33 @@
 | Projections | ✅ | - |
 | Eventual consistency | ✅ | - |
 
-## Issues (if REJECT)
-| # | Scope | Location | Issue | Fix Suggestion |
-|---|-------|----------|-------|----------------|
-| 1 | In-scope | `src/file.ts:42` | Issue description | Fix approach |
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
+|---|------------|------------|-------|----------|-------|----------------|
+| 1 | CQRS-NEW-src-file-L42 | cqrs-violation | In-scope | `src/file.ts:42` | Issue description | Fix approach |
 
 Scope: "In-scope" (fixable in this change) / "Out-of-scope" (existing issue, non-blocking)
 
-## Existing Issues (reference, non-blocking)
-- {Record of existing issues unrelated to the current change}
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | CQRS-PERSIST-src-file-L77 | cqrs-violation | `src/file.ts:77` | `src/file.ts:77` | Still unresolved | Apply prior fix plan |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| CQRS-RESOLVED-src-file-L10 | `src/file.ts:10` now satisfies the rule |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | CQRS-REOPENED-src-file-L55 | cqrs-violation | `Previously fixed at src/file.ts:10` | `Recurred at src/file.ts:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
 ```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

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

@@ -15,8 +15,31 @@
 | Accessibility | ✅ | - |
 | Type safety | ✅ | - |
 
-## Issues (if REJECT)
-| # | Location | Issue | Fix Suggestion |
-|---|----------|-------|----------------|
-| 1 | `src/file.tsx:42` | Issue description | Fix approach |
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|-------|----------------|
+| 1 | FE-NEW-src-file-L42 | component-design | `src/file.tsx:42` | Issue description | Fix approach |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | FE-PERSIST-src-file-L77 | component-design | `src/file.tsx:77` | `src/file.tsx:77` | Still unresolved | Apply prior fix plan |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| FE-RESOLVED-src-file-L10 | `src/file.tsx:10` now satisfies the rule |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | FE-REOPENED-src-file-L55 | component-design | `Previously fixed at src/file.tsx:10` | `Recurred at src/file.tsx:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
 ```
+
+**Cognitive load reduction rules:**
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)

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

@@ -16,21 +16,26 @@
 | Maintainability | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Category | Location | Issue | Fix Suggestion |
-|---|------------|----------|----------|-------|----------------|
-| 1 | QA-NEW-src-test-L42 | Testing | `src/test.ts:42` | Missing negative test | Add failure-path test |
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | QA-NEW-src-test-L42 | test-coverage | Testing | `src/test.ts:42` | Missing negative test | Add failure-path test |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
-| 1 | QA-PERSIST-src-test-L77 | `src/test.ts:77` | `src/test.ts:77` | Still flaky | Stabilize assertion & setup |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | QA-PERSIST-src-test-L77 | test-coverage | `src/test.ts:77` | `src/test.ts:77` | Still flaky | Stabilize assertion & setup |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | QA-RESOLVED-src-test-L10 | `src/test.ts:10` now covers error path |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | QA-REOPENED-src-test-L55 | test-coverage | `Previously fixed at src/test.ts:10` | `Recurred at src/test.ts:55` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```

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

@@ -20,22 +20,27 @@
 | 1 | {change not in requirements} | `src/file.ts` | Justified/Unnecessary |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Category | Location | Issue | Fix Suggestion |
-|---|------------|----------|----------|-------|----------------|
-| 1 | REQ-NEW-src-file-L42 | Unimplemented | `src/file.ts:42` | Issue description | Fix suggestion |
+| # | finding_id | family_tag | Category | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|----------------|
+| 1 | REQ-NEW-src-file-L42 | req-gap | Unimplemented | `src/file.ts:42` | Issue description | Fix suggestion |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
-| 1 | REQ-PERSIST-src-file-L77 | `file:line` | `file:line` | Unresolved | Fix suggestion |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | REQ-PERSIST-src-file-L77 | req-gap | `file:line` | `file:line` | Unresolved | Fix suggestion |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | REQ-RESOLVED-src-file-L10 | `file:line` now satisfies the requirement |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | REQ-REOPENED-src-file-L55 | req-gap | `Previously fixed at file:line` | `Recurred at file:line` | Issue description | Fix approach |
+
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

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

@@ -14,25 +14,30 @@
 | Dependencies | ✅ | - |
 
 ## Current Iteration Findings (new)
-| # | finding_id | Severity | Type | Location | Issue | Fix Suggestion |
-|---|------------|----------|------|----------|-------|----------------|
-| 1 | SEC-NEW-src-db-L42 | High | SQLi | `src/db.ts:42` | Raw query string | Use parameterized queries |
+| # | finding_id | family_tag | Severity | Type | Location | Issue | Fix Suggestion |
+|---|------------|------------|----------|------|----------|-------|----------------|
+| 1 | SEC-NEW-src-db-L42 | injection-risk | High | SQLi | `src/db.ts:42` | Raw query string | Use parameterized queries |
 
 ## Carry-over Findings (persists)
-| # | finding_id | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
-|---|------------|-------------------|------------------|-------|----------------|
-| 1 | SEC-PERSIST-src-auth-L18 | `src/auth.ts:18` | `src/auth.ts:18` | Weak validation persists | Harden validation |
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | SEC-PERSIST-src-auth-L18 | injection-risk | `src/auth.ts:18` | `src/auth.ts:18` | Weak validation persists | Harden validation |
 
 ## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
 |------------|---------------------|
 | SEC-RESOLVED-src-db-L10 | `src/db.ts:10` now uses bound parameters |
 
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | SEC-REOPENED-src-auth-L55 | injection-risk | `Previously fixed at src/auth.ts:20` | `Recurred at src/auth.ts:55` | Issue description | Fix approach |
+
 ## Warnings (non-blocking)
 - {Security recommendations}
 
 ## Rejection Gate
-- REJECT is valid only when at least one finding exists in `new` or `persists`
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - Findings without `finding_id` are invalid
 ```
 

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

@@ -4,39 +4,44 @@
 ## Result: APPROVE / REJECT
 
 ## Summary
-{1-2 sentences summarizing the result}
+{Summarize the result in 1-2 sentences}
 
 ## 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] File structure (one concern per file)
+- [x] Security settings
 - [x] Tag management
-- [x] Lifecycle rules
+- [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 |
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Scope | Location | Issue | Fix Suggestion |
+|---|------------|------------|-------|----------|-------|----------------|
+| 1 | TF-NEW-file-L42 | tf-convention | In-scope | `modules/example/main.tf:42` | Issue description | Fix approach |
 
-Scope: "In scope" (fixable now) / "Out of scope" (existing issue, non-blocking)
+Scope: "In-scope" (fixable in this change) / "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 |
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | TF-PERSIST-file-L77 | tf-convention | `file.tf:77` | `file.tf:77` | Still unresolved | Apply prior fix plan |
 
-## Resolved
+## Resolved Findings (resolved)
 | finding_id | Resolution Evidence |
-|------------|-------------------|
-| TF-RESOLVED-file-L10 | `file.tf:10` meets conventions |
+|------------|---------------------|
+| TF-RESOLVED-file-L10 | `file.tf:10` now satisfies the convention |
 
-## REJECT Criteria
-- REJECT only if 1+ `new` or `persists` findings exist
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | TF-REOPENED-file-L55 | tf-convention | `Previously fixed at file.tf:10` | `Recurred at file.tf:55` | Issue description | Fix approach |
+
+## Rejection Gate
+- REJECT is valid only when at least one finding exists in `new`, `persists`, or `reopened`
 - 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)
+- APPROVE → Summary only (5 lines or fewer)
+- REJECT → Include only relevant finding rows (30 lines or fewer)