takt 0.41.0 → 0.43.0

package/builtins/en/facets/policies/existing-system-respect.md

@@ -0,0 +1,73 @@
+# Existing System Respect Policy
+
+For released or operational systems, make only the minimum changes required by the request and avoid changing existing contracts unnecessarily.
+
+## Principles
+
+| Principle | Criteria |
+|-----------|----------|
+| Existing contracts first | Preserve contracts relied on by users, tests, and operations |
+| Minimum diff | Keep only changes required to satisfy the request |
+| Necessity over proximity | Do not use nearby code as a reason to change it |
+| Respect existing structure | Do not change file placement, type names, public APIs, or responsibility boundaries without explicit need |
+| Preserve comments | Do not delete comments that explain intent, constraints, or calculation rationale |
+| Tests are contracts | Do not treat behavior asserted by existing tests as incidental |
+| Separate improvements | Style or cleanup improvements must be directly required by the task |
+| Maintenance constraints first | Prefer preserving existing behavior and structure over general quality improvements |
+
+## Change Boundary
+
+| Criteria | Verdict |
+|----------|---------|
+| Change required to satisfy the request | OK |
+| Call-site update required to wire a necessary change | OK |
+| Local fix required to prevent side effects of a necessary change | OK |
+| Cleanup justified only because the file was touched | REJECT |
+| Moving files, renaming types, or changing public APIs without explicit need | REJECT |
+| Mixing framework-style improvements into the task | REJECT |
+| Including improvements that can be handled in another PR | REJECT |
+
+## Priority Against Other Policies
+
+In existing-system maintenance, apply general quality policies such as coding, frontend, design-fidelity, and testing only within the scope required by the request.
+
+| Conflict | Verdict |
+|----------|---------|
+| General quality criteria suggest an improvement, but the request does not require it | Do not change |
+| Existing structure is imperfect, but can satisfy this request | Preserve existing structure |
+| Satisfying a quality criterion requires changing an existing contract | Requires an explicit user request or plan-level rationale |
+| A minimal structural change is required for a bug fix | Make it with reason and impact scope documented |
+
+## Observable Contracts
+
+UI, accessibility, tests, logs, APIs, types, file placement, and comments can be contracts observed by users or developers.
+
+| Contract | Change condition |
+|----------|------------------|
+| UI copy, accessible names, role/state | Change only when directly required by the request |
+| Hook return values, Props type names, public function names | Change only when caller updates are required to satisfy the request |
+| Test expectations | Change only when the requested behavior changes |
+| Comments | Change only when correcting inaccurate comments or when code makes them truly obsolete |
+| File placement | Change only when the existing structure cannot satisfy the request |
+
+## Test Changes
+
+Tests should distinguish existing contracts from new requirements, not merely follow the implementation.
+
+| Pattern | Verdict |
+|---------|---------|
+| Add tests for new requirements | OK |
+| Add regression tests to preserve existing contracts | OK |
+| Merely weaken existing expectations to match implementation changes | REJECT |
+| Remove tested existing behavior to make tests pass | REJECT |
+| Delete tests because they obstruct the new implementation | REJECT |
+
+## Pre-Completion Check
+
+Before completion, classify the full diff as required changes, related changes, or unnecessary changes. Do not complete while unnecessary changes remain.
+
+| Classification | Criteria |
+|----------------|----------|
+| Required change | The request fails without it |
+| Related change | Needed to connect, verify, or keep a required change consistent |
+| Unnecessary change | Justified only by readability, style, cleanup, or future extensibility |

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

@@ -22,7 +22,9 @@
 
 | Pattern | Verdict |
 |---------|---------|
-| Abandoned TODO/FIXME | Warning |
+| TODO/FIXME without an issue number, external blocker, and removal condition | REJECT |
+| TODO/FIXME with issue number, external blocker, and removal condition | Warning |
+| Empty implementations, stubs, or commented-out old implementations left behind | REJECT |
 | @ts-ignore, @ts-expect-error without reason | Warning |
 | eslint-disable without reason | Warning |
 | Usage of deprecated APIs | Warning |

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

@@ -10,7 +10,7 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 | Eliminate ambiguity | Vague feedback like "clean this up a bit" is prohibited. Specify file, line, and proposed fix |
 | Fact-check | Verify against actual code before raising issues. Do not speculate |
 | Practical fixes | Propose implementable solutions, not theoretical ideals |
-| Boy Scout | If a changed file has problems, have them fixed within the task scope |
+| Boy Scout | Have problems fixed within the task scope when they are in changed code or in areas directly affecting correctness, contracts, or wiring of the change |
 
 ## Scope Determination
 
@@ -18,9 +18,10 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 |-----------|---------|--------|
 | Problem introduced by this change | Blocking | REJECT |
 | Code made unused by this change (arguments, imports, variables, functions) | Blocking | REJECT (change-induced problem) |
-| Existing problem in a changed file | Blocking | REJECT (Boy Scout rule) |
-| Structural problem in the changed module | Blocking | REJECT if within scope |
+| Existing problem in changed or directly related code | Blocking | REJECT (Boy Scout rule) |
+| Structural problem directly affecting correctness of the change | Blocking | REJECT if within scope |
 | Problem in an unchanged file | Non-blocking | Record only (informational) |
+| Existing problem that merely shares a changed file but does not directly affect correctness of the change | Non-blocking | Record only (informational) |
 | Refactoring that greatly exceeds task scope | Non-blocking | Note as a suggestion |
 
 ## Judgment Criteria
@@ -37,13 +38,15 @@ REJECT without exception if any of the following apply.
 - Unused code ("just in case" code)
 - Direct mutation of objects/arrays
 - Swallowed errors (empty catch blocks)
-- TODO comments (not tracked in an issue)
+- TODO/FIXME without an issue number, external blocker, and removal condition
 - Essentially identical logic duplicated (DRY violation)
 - Method proliferation doing the same thing (should be absorbed by configuration differences)
 - Specific implementation leaking into generic layers (imports and branching for specific implementations in generic layers)
 - Internal implementation exported from public API (infrastructure functions or internal classes exposed publicly)
 - Replaced code/exports surviving after refactoring
 - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
+- Missing caller, producer, or test data updates after a contract change
+- Sensitive data exposed in logs, error responses, or test output
 
 A DRY finding is not complete unless the proposed consolidation target is also sound. A consolidation proposal is invalid unless all of the following hold.
 
@@ -59,7 +62,7 @@ Not blocking, but improvement is recommended.
 - Tests coupled to implementation details
 - Overly complex functions/files
 - Unclear naming
-- Abandoned TODO/FIXME (those with issue numbers are acceptable)
+- TODO/FIXME with issue number, external blocker, and removal condition
 - `@ts-ignore` or `eslint-disable` without justification
 
 ### APPROVE
@@ -73,7 +76,7 @@ Always verify facts before raising an issue.
 | Do | Do Not |
 |----|--------|
 | Open the file and check actual code | Assume "it should be fixed already" |
-| Search for call sites and usages with grep | Raise issues based on memory |
+| Search for call sites and usages | Raise issues based on memory |
 | Cross-reference type definitions and schemas | Guess that code is dead |
 | Distinguish generated files (reports, etc.) from source | Review generated files as if they were source code |
 | Verify tool output is readable and uncorrupted | Raise issues based on garbled or abnormal output |
@@ -175,19 +178,20 @@ Leave it better than you found it.
 
 ### In Scope
 
-- Existing problems in changed files (unused code, poor naming, broken abstractions)
-- Structural problems in changed modules (mixed responsibilities, unnecessary dependencies)
+- Existing problems in changed code or in areas directly affecting correctness, contracts, or wiring of the change (unused code, poor naming, broken abstractions)
+- Structural problems directly affecting correctness of the change (mixed responsibilities, unnecessary dependencies)
 
 ### Out of Scope
 
 - Unchanged files (record existing issues only)
+- Existing problems that merely share a changed file but do not directly affect correctness, contracts, or wiring of the change
 - Refactoring that greatly exceeds task scope (note as a suggestion, non-blocking)
 
 ### Judgment
 
 | Situation | Verdict |
 |-----------|---------|
-| Changed file has an obvious problem | REJECT — have it fixed together |
+| Changed or directly related code has an obvious problem | REJECT — have it fixed together |
 | Redundant expression (a shorter equivalent exists) | REJECT |
 | Unnecessary branch/condition (unreachable or always the same result) | REJECT |
 | Fixable in seconds to minutes | REJECT (do not mark as "non-blocking") |
@@ -198,15 +202,24 @@ Do not tolerate problems just because existing code does the same. If existing c
 
 ## Judgment Rules
 
-- All issues detected in changed files are blocking (REJECT targets), even if the code existed before the change
-- Only issues in files NOT targeted by the change may be classified as "existing problems" or "non-blocking"
-- "The code itself existed before" is not a valid reason for non-blocking. As long as it is in a changed file, the Boy Scout rule applies
+- Issues detected in changed code or in areas directly affecting correctness, contracts, or wiring of the change are blocking (REJECT targets), even if the code existed before the change
+- Only issues not directly related to the change may be classified as "existing problems" or "non-blocking"
+- "The code itself existed before" is not a valid reason for non-blocking when the issue is in changed or directly related code
 - If even one issue exists, REJECT. "APPROVE with warnings" or "APPROVE with suggestions" is prohibited
 
 ## Basic Review Procedure
 
 Common procedure that every reviewer must follow. Do not duplicate this in individual instructions.
 
+### Diff Baseline (Anchor to the Base)
+
+The review target is the entire cumulative diff from the task's starting point (the base), not just the changes from the most recent iteration.
+
+- In the fix ↔ review loop, recompute the diff from the base every time and evaluate the whole. Do not move the baseline to the latest fix
+- The base is the merge-base with the integration branch, or the starting point recorded in `plan` / `order`. Do not treat only the "changes" section of `Previous Response` as the diff
+- Unrequested changes introduced in earlier iterations (unrelated comment deletions, renames, reformatting, contract changes, weakened tests) remain in the cumulative diff even when they no longer appear in the latest fix report. Reconcile against them every time
+- Track finding states (new / persists / resolved) on a fixed baseline. Do not narrow the diff scope and conclude "it is no longer in the diff"
+
 ### Referring to Primary Sources
 
 - Use `order.md`, `plan.md`, and the actual code as primary sources

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

@@ -12,6 +12,7 @@ Every behavior change requires a corresponding test, and every bug fix requires
 | Independence | Do not depend on other tests or execution order |
 | Type safety | Code must pass the build (type check) |
 | Reproducibility | Do not depend on time or randomness. Same result every run |
+| Do not freeze non-executable assets | Do not make prose or section structure that does not define runtime behavior a CI failure condition |
 
 ## Coverage Criteria
 
@@ -33,6 +34,23 @@ Every behavior change requires a corresponding test, and every bug fix requires
 
 **Note:** When a design reference is provided, UI appearance verification is elevated to medium priority. Refer to the Design Fidelity Policy.
 
+## Non-Executable Asset Tests
+
+Tests that freeze prose, headings, or structure in non-executable assets such as explanations, guides, README files, or Markdown documentation are prohibited by default.
+These assets change often during wording improvements and reorganization, so making prose diffs fail CI creates high maintenance cost.
+
+| Criteria | Verdict |
+|----------|---------|
+| Exact prose, heading, or section-structure assertions for non-executable assets | REJECT |
+| Scanning all non-executable assets only to enforce wording or terminology | REJECT |
+| Tests that require explanatory files that may be deleted or consolidated | REJECT |
+| Adding tests for docs-only changes when no executable contract exists | REJECT |
+| Validating executable or machine-processed contracts such as CLI examples, config examples, or generated artifacts | OK |
+| Contract tests for schemas, configuration, code, generators, or runtime behavior | OK |
+| Not adding tests for docs-only changes that have no executable contract | OK |
+
+Verify non-executable asset changes with review, Markdown lint, link checks, or sample command execution when needed.
+
 ## Test Structure: Given-When-Then
 
 ```typescript
@@ -57,6 +75,18 @@ test('should return NotFound error when user does not exist', async () => {
 | Clarity | Failure cause is obvious | Failure cause is unclear |
 | Focus | One test, one concept | Multiple concerns mixed |
 
+## Test Data and Fixtures
+
+Test data should explicitly generate the minimum facts needed by each test. Mutating shared fixtures or using mocks that drift from real contracts reduces test reliability.
+
+| Criteria | Verdict |
+|----------|---------|
+| Shared fixtures are mutated and reused across tests | REJECT |
+| Mocks, fixtures, or factories return shapes that differ from real types or API contracts | REJECT |
+| Each test hand-writes a huge full-field fixture | Warning. Consider a factory |
+| Factories provide defaults and each test overrides only relevant fields | OK |
+| Contract changes update fixtures, mocks, and snapshots in the same change | OK |
+
 ### Naming
 
 Test names describe expected behavior. Use the `should {expected behavior} when {condition}` pattern.
@@ -125,8 +155,11 @@ Verify data flow coupling that unit tests alone cannot cover.
 
 ## E2E Test Criteria
 
+Design E2E tests from the entry points users actually use. Use code-level entry points such as routes, commands, endpoints, navigation, buttons, or external callbacks, not documentation assumptions alone.
+
 | Criteria | Verdict |
 |----------|---------|
+| E2E tests are written for imagined flows without checking real entry points | REJECT |
 | 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 |

package/builtins/en/workflow-categories.yaml

@@ -19,6 +19,7 @@ workflow_categories:
     workflows:
       - frontend
       - frontend-mini
+      - frontend-maintenance
   ⚙️ Backend:
     workflows:
       - backend

package/builtins/en/workflows/auto-improvement-loop.yaml

@@ -117,7 +117,11 @@ steps:
       - type: enqueue_task
         mode: new
         workflow: takt-default
-        base_branch: improve
+        base_branch:
+          name: improve
+          create_if_missing:
+            from: main
+            push: true
         task: "{structured:plan_from_issue.task_markdown}"
         issue: "{structured:plan_from_issue.issue}"
         worktree:
@@ -187,7 +191,11 @@ steps:
       - type: enqueue_task
         mode: new
         workflow: takt-default
-        base_branch: improve
+        base_branch:
+          name: improve
+          create_if_missing:
+            from: main
+            push: true
         task: "{structured:plan_fresh_improvement.task_markdown}"
         issue: "{structured:plan_fresh_improvement.issue}"
         worktree:
@@ -255,7 +263,11 @@ steps:
         mode: from_pr
         pr: "{context:route_context.selected_pr.number}"
         workflow: takt-default
-        base_branch: improve
+        base_branch:
+          name: improve
+          create_if_missing:
+            from: main
+            push: true
         task: "{structured:plan_from_existing_pr.task_markdown}"
     rules:
       - when: effect.enqueue_from_pr.enqueue_task.success == true
@@ -296,7 +308,11 @@ steps:
         mode: from_pr
         pr: "{context:route_context.selected_pr.number}"
         workflow: takt-default
-        base_branch: improve
+        base_branch:
+          name: improve
+          create_if_missing:
+            from: main
+            push: true
         task: |
           Resolve the conflicts raised while syncing the PR with its base branch.
           Target PR: {context:route_context.selected_pr.number}

package/builtins/en/workflows/default-peer-review.yaml

@@ -1,5 +1,5 @@
 name: default-peer-review
-description: default series Phase 2. Parallel reviewers (arch + ai-antipattern-2nd + supervise) ⇄ fix loop.
+description: default series Phase 2. Parallel reviewers (arch + ai-antipattern-2nd + coding-review + supervise) ⇄ fix loop.
 subworkflow:
   callable: true
   visibility: internal
@@ -72,6 +72,28 @@ steps:
           report:
             - name: ai-antipattern-review.md
               format: ai-antipattern-review
+      - name: coding-review
+        edit: false
+        persona: coding-reviewer
+        policy: review
+        pass_previous_response: false
+        provider_options:
+          claude:
+            allowed_tools:
+              - Read
+              - Glob
+              - Grep
+              - Bash
+              - WebSearch
+              - WebFetch
+        instruction: review-coding
+        rules:
+          - condition: approved
+          - condition: needs_fix
+        output_contracts:
+          report:
+            - name: coding-review.md
+              format: coding-review
       - name: supervise
         edit: false
         persona: supervisor
@@ -97,9 +119,9 @@ steps:
               format: summary
               use_judge: false
     rules:
-      - condition: all("approved", "No AI-specific issues", "All checks passed")
+      - condition: all("approved", "No AI-specific issues", "approved", "All checks passed")
         next: COMPLETE
-      - condition: any("needs_fix", "AI-specific issues found", "Requirements unmet, tests failing, build errors")
+      - condition: any("needs_fix", "AI-specific issues found", "needs_fix", "Requirements unmet, tests failing, build errors")
         next: fix
   - name: fix
     edit: true