takt 0.49.0 → 0.51.0

package/builtins/en/facets/personas/merge-readiness-reviewer.md

@@ -0,0 +1,28 @@
+# Merge Readiness Reviewer
+
+You are the final gate reviewer who decides whether the converged change is quality-ready to enter a codebase that must be maintained going forward. Without limiting yourself to one specialty, inspect the accumulated diff, surrounding code, and execution evidence for cross-cutting misses, maintainability risks, and merge blockers.
+
+## Role Boundaries
+
+**Do:**
+- Judge whether the change is quality-ready for a maintainable codebase based on actual code and diffs
+- Detect unmet requests, broken existing behavior, missing tests, out-of-scope changes, maintainability degradation, and obvious risks
+- Check cross-cutting coverage for changed contracts, identifiers, config, outputs, entry points, and persisted/displayed/executed paths
+- Report only blocking issues with concrete evidence
+
+**Don't:**
+- Write code yourself
+- Deep-review architecture direction; that is the Architecture Reviewer's job
+- Deep-review security vulnerabilities; that is the Security Reviewer's job
+- Deep-review test design; that is the Testing Reviewer's job
+- Deep-review code style or implementation craft; that is the Coding Reviewer's job
+
+## Behavioral Principles
+
+- Keep the final question as: "Is this change quality-ready for a codebase we must keep maintaining?"
+- Re-check the accumulated diff even when specialist reviews have passed
+- Trace changed names, contracts, and entry points across same-kind usages
+- Do not miss states that future maintainers cannot safely trace, modify, or verify
+- Do not mark an item verified unless you actually searched or inspected it
+- Judge `resolved` against the original finding's expected result and acceptance criteria
+- Report only issues that should block the merge, not preferences or general advice

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

@@ -22,7 +22,7 @@ you verify "**was the right thing built (Validation)**".
 ## Behavioral Principles
 
 - Re-check requirements yourself. Do not adopt the decomposition from earlier reviews without verification
-- Treat `pure-review` as supporting material, not as the final answer
+- Treat `merge-readiness-review` as supporting material, not as the final answer
 - Mark missing execution evidence as unverified instead of assuming success
 - Treat contradictions between report text and execution evidence as first-class findings
 - Distinguish `false_positive` from `overreach`; a technically invalid finding and a scope-exceeding finding are not the same

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

@@ -135,6 +135,24 @@ Verification approach:
 3. If tests are added as part of the fix, verify they test "correct behavior after the fix" (not "the finding itself")
 4. For mid-PR specification changes, verify the tests cover the new behavior in the layer that owns it, not only the absence of the old specification
 
+## Superficial Fixes Through Test Doubles
+
+AI sometimes makes tests pass by loosening test doubles or ignoring arguments the production code uses instead of fixing the production contract. A passing test is evidence only when it exercised the same semantic contract as production.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| A test double omits constraints or overrides always applied by the production helper | Permissions, capabilities, limits, or missing-value semantics differ from production | REJECT |
+| A mock ignores input that production uses for branching | Accepts `options` or `context` but never verifies them | REJECT |
+| A dependency with side-effect contracts is replaced by a return-only stub | Session updates, cache invalidation, or event emission are unobserved | REJECT |
+| The test only verifies that something was called, not the arguments or side effects | The test passes even when constraints are not propagated | REJECT |
+| The test double reproduces the observable production contract and assertions inspect arguments and side effects | Key options, missing values, and failure-state transitions are verified | OK |
+
+Verification approach:
+1. Inspect the replaced production function, builder, or adapter for return shape, missing values, side effects, and override propagation
+2. Check whether the test double collapses branch-relevant inputs into fixed values
+3. When the fix concerns state transitions or permission propagation, verify call arguments and side effects in addition to final state
+4. Check that test names and completion reports do not overclaim behavior the test double cannot prove
+
 ## Context Fitness Assessment
 
 Does the code fit this specific project?
@@ -214,6 +232,7 @@ AI often changes existing contracts under the banner of "improvement", "standard
 | New contract required by new functionality | OK |
 | Missing information is added while preserving the existing contract | OK |
 | Reason, impact scope, and migration path for the contract change are explicit | OK |
+| Fixing display, accessibility, or test contract breakage newly caused by the requested change | OK. This is change-induced reconciliation, not scope creep |
 
 Verification approach:
 1. Inspect changed strings, attributes, event names, return values, error messages, and log formats in the diff

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

@@ -303,6 +303,17 @@ interface Channel {
 }
 ```
 
+### Explicit Dependencies
+
+Pass dependencies in a form whose role and type are visible. Do not reject function-typed parameters categorically; judge whether they hide a stable business role or external dependency behind an anonymous callback.
+
+| Pattern | Verdict |
+|---------|---------|
+| A business rule or external lookup relayed through multiple layers as an anonymous callback | REJECT. Give the role a name and promote it to a port, validator, service, or equivalent boundary |
+| A function type defined as a named business role or port | OK. Its meaning and substitution boundary are visible |
+| A function passed for local enrichment or conversion at a layer boundary | OK. The responsibility stays within the boundary and is not relayed onward |
+| A block that scopes a lock, transaction, or resource | OK. It is a control structure, not dependency smuggling |
+
 ### Leaky Abstraction
 
 If a specific implementation appears in a generic layer, the abstraction is leaking. The generic layer should only know interfaces; branching should be absorbed by implementations.
@@ -329,6 +340,8 @@ A name expresses the code's actual role and effect, not its implementation mecha
 | Side effects or call frequency are unreadable | Cannot tell from the name whether it initializes, retrieves, or updates | REJECT |
 | Cannot distinguish it from nearby APIs | Same name as the wrapped or delegated API, hiding which layer owns the responsibility | REJECT |
 | Named after role/effect | The provided value, state change, or responsibility is clear from the name | OK |
+| Path/origin suffix with no distinct counterpart path in existence | FromRequest / ViaApi on the only existing path | REJECT. Drop the suffix; when the counterpart path disappears, the name follows |
+| Naming convention differs for only some of a set of same-kind operations | createXxxFromRequest / updateXxxFromRequest / deleteXxx | REJECT. Make them consistent |
 
 ```typescript
 // REJECT - Name reads as if it causes a side effect every time, but it is a memoized accessor
@@ -362,6 +375,7 @@ Criteria:
 - Has its own state → Separate
 - UI/logic exceeding 50 lines → Separate
 - Has multiple responsibilities → Separate
+- Has an independent reason to change, responsibility, or reuse boundary → Separate. Whether small supporting types may share a file depends on language conventions and file cohesion
 
 ### Reachability When Adding Features
 
@@ -459,8 +473,7 @@ async function createUser(data) {
 }
 
 // ✅ Centralized handling at the upper layer
-// Catch collectively at the Controller/Handler layer
-// Or handle via @ControllerAdvice / ErrorBoundary
+// Handle collectively at the boundary exception translation layer
 async function createUser(data) {
   return await userService.create(data)  // Let exceptions propagate up
 }
@@ -471,8 +484,20 @@ async function createUser(data) {
 | Layer | Responsibility |
 |-------|---------------|
 | Domain/Service layer | Throw exceptions on business rule violations |
-| Controller/Handler layer | Catch exceptions and convert to responses |
-| Global handler | Handle common exceptions (NotFound, auth errors, etc.) |
+| Application layer | Do not swallow exceptions; only handle explicit compensation or retry |
+| Adapter boundary | Translate exceptions to protocol-specific responses or presentation |
+| Global handler | Handle only cross-cutting exceptions such as authentication, validation, and common error shapes |
+
+### HTTP Exception Translation
+
+HTTP adapters / controllers / handlers must not translate exceptions into HTTP representation endpoint by endpoint. Translate exceptions into HTTP status codes, response bodies, and headers at an exception translation layer on the HTTP adapter boundary.
+
+| Criteria | Judgment |
+|----------|----------|
+| Each endpoint maps exceptions to HTTP representation through the same try-catch or wrapper | REJECT. Move it to an exception translation layer at the HTTP adapter boundary |
+| API-specific exception mapping is added to a global handler shared by all APIs | REJECT. Keep it inside the target API boundary |
+| Only truly cross-cutting mappings such as authentication, validation, and common error shapes are handled by a global handler | OK |
+| HTTP representation mapping lives in the application or domain layer | REJECT. Keep it at the HTTP adapter boundary |
 
 ## Conversion Placement
 
@@ -539,6 +564,8 @@ AI tends to define the same logic under multiple function names.
 |---------|---------|---------|
 | 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 |
+| Public method only forwards to a private method with the identical signature and has no distinct public contract, registration, decorator, authorization, instrumentation, or side effect | Internal alias delegates 1:1 to the implementation | REJECT. Promote the delegate and merge |
+| A 1:1 delegating public method is a stable API or an entry point for framework registration, decorators, authorization, or instrumentation | Public boundary delegates implementation while preserving an external contract | OK. Keep the boundary and make its role explicit |
 
 ```typescript
 // REJECT - Same implementation exists under different names

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

@@ -13,10 +13,12 @@ Define the shared judgment criteria and behavioral principles for all reviewers.
 | State consistency | For side effects and state changes, verify that success, failure, and interruption paths have no missing, duplicated, or inconsistent effects |
 | Contract coverage | Verify new contracts across normal entries, derived conditions, validation, evaluation, output, and re-injection paths |
 | Contract consistency | Verify that contracts carried by consolidation or abstraction are applied to existing equivalent branches by the same standard |
+| Semantic contract | For meaningful fields such as IDs, source, trace, and issue/PR numbers, verify not only the storage shape but also the meaning interpreted downstream |
 | External contract verification | Verify semantic contracts of external services, SDKs, and generated artifacts from primary evidence or actual types |
 | Specification completeness | When changing a user-facing contract, verify that implementation, tests, and documentation describe the same lookup order, override rules, special syntax, and failure conditions |
 | Requirement anchoring | Do not reinterpret required task items as optional, out of scope, or different requirements for implementation convenience |
 | Resolution judgment | Judge `resolved` against the original finding acceptance criteria and original task requirements, not merely against the presence of a fix |
+| Concern handling | Any concern recognized in the prose must either become a finding or be explicitly classified with evidence as non-finding |
 | Behavior evidence | Verify what behavior the tests or logs prove, not merely that they exist |
 | 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 |
 
@@ -27,6 +29,7 @@ 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 changed or directly related code | Blocking | REJECT (Boy Scout rule) |
+| Existing ambiguous or incorrect contract exposed through a new public entry, adapter, or tool | Blocking | REJECT (existing behavior is not an exemption) |
 | 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) |
@@ -55,12 +58,15 @@ REJECT without exception if any of the following apply.
 - Replaced code/exports surviving after refactoring
 - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified)
 - Missing caller, producer, consumer, validator, test data, or derived-entry updates after a contract change
+- Meaningful fields such as IDs, source, trace, or issue/PR numbers are added, forwarded, or persisted while only the storage shape is checked, without verifying downstream interpretation or confusion with existing fields
 - User-facing contract changes for configuration, CLI, or file formats where documentation or examples omit priority, first-match/merge behavior, inline overrides, scoped/special references, or failure conditions
 - Existing branches with the same contract remain on the old implementation after adding or changing a shared helper, normalizer, builder, or adapter
+- A new public entry, adapter, or tool republishes an existing ambiguous or incorrect contract as an external contract
 - Fields, attributes, outputs, settings, or identifiers requested by the task are treated as optional, unset, out of scope, or missing for some entry point or execution mode without explicit evidence
 - Operation-specific error types, statuses, return values, or idempotency of an external service, SDK, or generated artifact are not verified, and another operation's contract or mock success is used instead
 - Missing, duplicated, or incorrectly ordered effects in side-effect or state-change paths
 - Sensitive data exposed in logs, error responses, or test output
+- Review prose recognizes a contract mismatch, side effect, boundary value, or unverified risk but does not turn it into a finding and does not classify it as a non-finding with evidence
 
 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.
 
@@ -116,11 +122,17 @@ If tool output is unreadable, re-read using a reliable method before making any
 | Output contains garbled text or encoding anomalies | Recognize the corruption, then re-read using an alternative method (open the file directly, specify line numbers for the target section) before judging |
 | Search command did not find the target code | Read the specific lines of the file directly to confirm absence before raising an issue. Search failure does not equal code absence |
 | Re-raising a prior finding without re-checking actual code | Must read current code before marking as persists. Do not re-raise from memory of the prior review |
+| A verification task did not actually run the target work due to caching, skipping, or missing configuration | Do not count it as passing evidence. Record what was actually executed separately from what remains unverified |
 
 ## Writing Specific Feedback
 
 Every issue raised must include the following.
 
+When the same kind of problem appears in multiple locations, report one representative finding and list the other locations inline as `also: src/store.ts:L232, src/projection.ts:L243`. Do not spend rows enumerating the same kind of issue; use the remaining attention to hunt different kinds of problems. Do not merge, however, in these cases:
+
+- Findings already tracked under separate `finding_id`s (do not break the tracking unit)
+- When a Finding Contract is in use (report every observed problem as an individual raw finding; deduplication is the responsibility of the findings-manager and the ledger)
+
 - **Which file and line number**
 - **What the problem is**
 - **How to fix it**
@@ -257,6 +269,8 @@ Do not tolerate problems just because existing code does the same. If existing c
 - 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
+- "Same as existing behavior" is not an approval reason when a new public entry, adapter, or tool exposes that contract
+- When a concern mentioned in prose is not made a finding, classify it as `false_positive` / `overreach` / `out_of_scope` / `no_issue_after_verification` and provide evidence
 - If even one issue exists, REJECT. "APPROVE with warnings" or "APPROVE with suggestions" is prohibited
 
 ## Basic Review Procedure
@@ -269,7 +283,7 @@ The review target is the entire cumulative diff from the task's starting point (
 
 - 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
+- Unrequested changes introduced in earlier iterations (unrelated comment deletions, renames, reformatting, contract changes, weakened tests, environment-dependent tool-generated diffs — version stamps, re-serialization, order-only rewrites) remain in the cumulative diff even when they no longer appear in the latest fix report. Reconcile against them every time and confirm their causal link to the request
 - 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
@@ -292,6 +306,7 @@ When the diff adds or changes a contract such as a config value, state, conditio
 - Verify that definition, production, normalization, validation, evaluation, persistence, output, and event emission all apply the same contract
 - Check derived paths as well as the normal entry: derived conditions, aggregate conditions, parent/child workflows, loop decisions, early exits, and exception paths
 - When persisted data or externally supplied data is re-injected into JSON, Markdown, logs, events, or later instructions, include escaping, boundary handling, and failure behavior in the contract
+- Verify that values normalized or validated at a boundary propagate as the same normalized value through persistence, execution, external calls, and event emission. Treat reuse of pre-normalized values in later stages as a contract inconsistency
 - Search for existing returns, throws, catches, early returns, branches, and call sites with the same responsibility
 - If an existing branch does not satisfy the new contract, treat it as related code even if the code itself predates the change
 - If tests cover only the new path and do not verify existing equivalent branches or derived entries, treat it as a coverage gap
@@ -305,6 +320,7 @@ When a change involves side effects or state changes such as external calls, con
 - Trace entry, normal completion, early return, exception, retry, interruption, and cleanup paths
 - Verify that anything acquired, started, registered, or applied is handled exactly as required on the corresponding paths
 - Verify that the same side effect is not executed more than once, and that required effects are not skipped on failure paths
+- Verify that no new side effect, such as an external notification, confirmation request, tool call, or persistence write, is started after interruption, cancellation, timeout, or any other condition has made continuation invalid
 - For changes that affect shared state or downstream execution, verify that partial failure does not leave state that breaks the next run
 - If these checks have not been performed, do not treat the behavior as functionally verified
 

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

@@ -91,6 +91,8 @@ test('should return NotFound error when user does not exist', async () => {
 | Reproducibility | Same result every time | Depends on time or randomness |
 | Clarity | Failure cause is obvious | Failure cause is unclear |
 | Focus | One test, one concept | Multiple concerns mixed |
+| UI element identification | Identify targets by user-observable contracts such as role plus exact accessible name | Broad partial matches, first match, or display position used to identify the target |
+| Collision cases | Verify targets remain distinguishable even with valid data sharing the same display string | Deliberately making all fixture display values unique, hiding the possibility of collisions |
 
 ## Testing Side Effects and State Transitions
 
@@ -165,9 +167,9 @@ Test data should explicitly generate the minimum facts needed by each test. Muta
 | Factories provide defaults and each test overrides only relevant fields | OK |
 | Contract changes update fixtures, mocks, and snapshots in the same change | OK |
 
-## External Contract Mocks
+## Contract Mocks and Test Doubles
 
-When mocking an external SDK, external API, generated client, or CLI, align mocked exception types, statuses, return values, missing values, partial successes, and idempotency with the real contract. Type compatibility alone does not verify the semantic contract.
+When mocking an external SDK, external API, generated client, or CLI, align mocked exception types, statuses, return values, missing values, partial successes, and idempotency with the real contract. When using test doubles for internal builders, runners, or adapters, also match production semantics for permissions, capabilities, overrides, missing values, and side effects. Type compatibility alone does not verify the semantic contract.
 
 | Criteria | Verdict |
 |----------|---------|
@@ -175,6 +177,7 @@ When mocking an external SDK, external API, generated client, or CLI, align mock
 | The mock throws the exception or return value expected by the implementation, and test success is used as proof of the external contract | REJECT |
 | Error types or response shapes from a different operation in the same service are reused | REJECT |
 | The mock is type-safe but operation-specific semantic contracts, such as existing-resource behavior, partial success, or missing detection, are not verified | REJECT |
+| Internal test double drops constraints, overrides, or side effects that production always passes | REJECT |
 | When real integration is stubbed, the report separates what the mock verifies from the unverified real-integration scope | OK |
 
 ### Naming
@@ -232,6 +235,7 @@ Verify data flow coupling that unit tests alone cannot cover.
 | Data flow crossing 3+ modules | Integration test required |
 | New status/state merging into an existing workflow | Integration test for the full transition flow required |
 | New option propagating through a call chain to the endpoint | End-to-end chain coupling test required |
+| Handler, middleware, or translator selection and precedence is decided by runtime configuration | Integration test with production-like configuration required. A limited (slice) configuration only proves the behavior of what it includes |
 | All module-level unit tests pass | Unit tests alone are sufficient (when none of the above apply) |
 
 ## Unit Test Criteria

package/builtins/en/workflow-categories.yaml

@@ -4,6 +4,7 @@ workflow_categories:
       - default
       - default-mini
       - default-high
+      - cli
       - frontend
       - backend
       - dual
@@ -20,6 +21,7 @@ workflow_categories:
       - frontend
       - frontend-mini
       - frontend-maintenance
+      - frontend-for-local-llm
   ⚙️ Backend:
     workflows:
       - backend
@@ -27,12 +29,15 @@ workflow_categories:
       - backend-maintenance
       - backend-cqrs
       - backend-cqrs-mini
+      - backend-for-local-llm
+      - backend-cqrs-for-local-llm
   🔧 Dual:
     workflows:
       - dual
       - dual-mini
       - dual-cqrs
       - dual-cqrs-mini
+      - dual-for-local-llm
   🏗️ Infrastructure:
     workflows:
       - terraform
@@ -62,12 +67,19 @@ workflow_categories:
   🎵 TAKT Development:
     workflows:
       - takt-default
-      - takt-default-with-fc
       - takt-default-refresh-all
       - takt-default-refresh-fast
       - auto-improvement-loop
       - review-takt-default
       - review-fix-takt-default
+      - takt-default-for-local-llm
+  🖥️ Local LLM:
+    workflows:
+      - takt-default-for-local-llm
+      - frontend-for-local-llm
+      - backend-for-local-llm
+      - backend-cqrs-for-local-llm
+      - dual-for-local-llm
   Others:
     workflows:
       - research

package/builtins/en/workflows/audit-architecture-backend.yaml

@@ -66,6 +66,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture-dual.yaml

@@ -68,6 +68,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture-frontend.yaml

@@ -68,6 +68,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge:

package/builtins/en/workflows/audit-architecture.yaml

@@ -62,6 +62,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     policy: review
     knowledge: architecture

package/builtins/en/workflows/audit-e2e.yaml

@@ -75,6 +75,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     edit: false
     persona: supervisor
     policy: review

package/builtins/en/workflows/audit-security.yaml

@@ -58,6 +58,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     persona: supervisor
     knowledge: security
     instruction: audit-security-supervise

package/builtins/en/workflows/audit-unit.yaml

@@ -77,6 +77,7 @@ steps:
   - name: supervise
     tags:
       - review
+      - supervise
     edit: false
     persona: supervisor
     policy: review